Skip to main content

Permissions

Permissions in CargoXplorer define access control for various application features. They are used to restrict or allow user access to specific functionalities based on roles.

Introduction​

Permissions are a crucial part of the security model in CargoXplorer. They determine what actions users can perform within the system based on their assigned roles.

When to Use Permissions​

  • When setting up new user roles
  • When adding new features that require restricted access
  • When modifying existing access controls
  • When auditing system security

Structure​

Permissions are typically defined in the permissions section of an AppModule YAML file. Here's a basic structure:

permissions:
  - name: "ModuleName/EntityName/Action"
    displayName:
      en-US: "Human-readable permission name"
    description:
      en-US: "Detailed description of the permission"
    roles:
      - "RoleName1"
      - "RoleName2"

Key Components​

Permission Name​

The name field follows a specific format: ModuleName/EntityName/Action

For example:

  • System/Jobs/Read
  • TMS/ParcelShipment/Create

Common actions include:

  • Create
  • Read
  • Edit
  • Delete
  • Export
  • Import

Display Name and Description​

These fields provide human-readable information about the permission:

displayName:
  en-US: "Read Jobs"
description:
  en-US: "Allows user to view job details"

Roles​

The roles field lists which user roles are granted this permission:

roles:
  - Administrator
  - Manager

Use Cases​

Basic CRUD Permissions​

permissions:
  - name: "TMS/Shipment/Create"
    displayName:
      en-US: "Create Shipments"
    roles:
      - "ShippingAgent"
      - "Manager"
  - name: "TMS/Shipment/Read"
    displayName:
      en-US: "View Shipments"
    roles:
      - "ShippingAgent"
      - "Manager"
      - "Customer"
  - name: "TMS/Shipment/Update"
    displayName:
      en-US: "Edit Shipments"
    roles:
      - "ShippingAgent"
      - "Manager"
  - name: "TMS/Shipment/Delete"
    displayName:
      en-US: "Delete Shipments"
    roles:
      - "Manager"

Feature-specific Permissions​

permissions:
  - name: "TMS/Reports/ExportFinancial"
    displayName:
      en-US: "Export Financial Reports"
    description:
      en-US: "Allows exporting of sensitive financial data"
    roles:
      - "FinanceManager"
      - "Auditor"

Applying Permissions to Components​

Permissions can be applied directly to UI components to control visibility or functionality:

components:
  - name: "TMS/ShipmentDetails"
    layout:
      component: "button"
      props:
        label:
          en-US: "Edit Shipment"
        permission: "TMS/Shipment/Update"
        options:
          disabled: "{{ !hasPermission 'TMS/Shipment/Update' }}"

Best Practices​

  1. Use descriptive names for permissions that clearly indicate their purpose.
  2. Keep permissions granular to allow for fine-tuned access control.
  3. Regularly audit and review permissions to ensure they align with current security requirements.
  4. Use role-based permissions to simplify user management.
  5. Document the purpose and scope of each permission for easier maintenance.