Permissions

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

This page covers UI permissions, which decide what the web and mobile clients render. The server checks separate names on API calls: see UI and API Names and API Permissions.

Introduction

Permissions are a crucial part of the security model in CXTMS. 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 of a UI permission usually follows the format ModuleName/EntityName/Action

For example:

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

Common actions include:

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

These are conventions for UI names: the client compares the whole name and gives the parts no meaning. API names have a fixed format and action list, and use none of Edit, Export or Import. An import needs Create and Update.

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

UI and API Names

A module declares both kinds of name in the same permissions: block, and they do different things:

	UI names	API names
Format	Free-form: System/Contacts/Update, TMS/Shipment/Create	API/<Entity>[/<Subtype>]/<Action>, always singular: API/Contact/Store/Update
Checked by	The web and mobile clients, on components, routes and hasPermission	The server, on API calls
Matching	Exact name, case-sensitive	Case-insensitive, and wildcards grant

A UI name does not grant an API name, so a role needs both to use a button and the mutation behind it. See API Permissions.

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.