AppModule

App Modules are used to extend the functionality of the CargoX platform. They define the structure, behavior, and UI components for specific application features.

Structure

App Modules are defined using YAML files. The YAML structure typically includes the following main sections:

module: # Module definition and metadata
components: # UI components and layouts
configurations: # System and integration configurations
entities: # Data structure definitions
permissions: # Access control settings
routes: # Application routing
defaultData: # Default data to be loaded into the module

Module Definition

The module section defines basic information about the AppModule:

module:
  appModuleId: "00000000-0000-0000-0000-000000000000" # UUID of the module
  name: "ExampleModule" # Internal name of the module
  displayName: # Localized display names
    en-US: "Example Module"
    fr-FR: "Module d'exemple"
  description: # Localized descriptions
    en-US: "This is an example module"
    fr-FR: "Ceci est un module d'exemple"
  application: "TMS" # The application this module belongs to (e.g., TMS, WMS)

Key attributes:

• appModuleId: Unique identifier for the module
• name: Internal name of the module
• displayName: Localized display names
• description: Localized descriptions
• application: The application this module belongs to (e.g., TMS, WMS)

Components

Components define the UI elements and their behavior. They can range from simple fields to complex layouts with nested elements.

Example of a simple component:

components:
  - name: "ExampleModule/SimpleForm"
    displayName:
      en-US: "Simple Form"
    # ai_chat:
    #   common_questions:
    #     - question: "What is the name of the module?"
    #     - question: "What is the description of the module?"
    #   context:
    #     - graphql:
    #         query: "query { exampleField }"
    #       template:
    #         - "{{ exampleField }}"
    #       knowledge:
    #         - tag: ["customs"]
    #   tools:
    #     - name: "UpdateConsignee"
    #       instructions: "Update the consignee with the given ID. required fields are name, address, city, state, zip, country, phone, email, and website."
    #       workflow: "UpdateConsigneeWorkflow"
    #       actions:
    #         - name: "consigneeId"
    #           description: "The ID of the consignee to update"
    #           type: "string"
    layout:
      component: "form"
      props:
        cols: 2
      children:
        - component: "field"
          props:
            name: "exampleField"
            label:
              en-US: "Example Field"
            type: "text"

Components can include more complex structures with tabs, data grids, and dynamic behaviors:

components:
  - name: "ExampleModule/ComplexComponent"
    layout:
      component: "layout"
      children:
        - component: "tabs"
          children:
            - component: "tab"
              props:
                label:
                  en-US: "Details"
              children:
                - component: "dataGrid"
                  props:
                    entity: "ExampleEntity"
                    allowFilters: true
        - component: "button"
          props:
            label:
              en-US: "Save"
            onClick:
              - mutation:
                  command: "saveExampleMutation"

Routes

Routes define the navigation structure of the application:

routes:
  - name: "ExampleModule/List"
    path: "example-module"
    component: "ExampleModule/ListComponent"
    props:
      title:
        en-US: "Example List"
    children:
      - name: "ExampleModule/Details"
        path: ":id"
        component: "ExampleModule/DetailsComponent"

Key attributes:

• name: Name of the route (unique within the system)
• path: URL path for the route (unique within the system)
• component: Component to render for the route
• props: Properties to pass to the component
  • title: Title of the route (localized)
• children: Nested routes (optional)

Entities

Entities define the data structures used in the module:

entities:
  - name: "ExampleEntity"
    displayName:
      en-US: "Example Entity"
    fields:
      - name: "field1"
        displayName:
          en-US: "Field 1"
        fieldType: "text"
      - name: "field2"
        displayName:
          en-US: "Field 2"
        fieldType: "number"
        isCustomField: false # Define as Custom field

Key attributes:

• name: Name of the entity (unique within the system)
• displayName: Localized display names
• fields: List of fields in the entity
  • name: Name of the field (unique within the entity)
  • displayName: Localized display names
  • fieldType: Type of the field (e.g., text, number, date)
  • isCustomField: Define as Custom field
  • props: Component properties

Configurations

Configurations define the system and integration organization configurations used in the module:

configurations:
  - configName: "system.measurementUnits" # Name of the configuration
    displayName:
      en-US: "Measurement Units"
    description:
      en-US: "Measurement Units"
    component: "Configurations/MeasurementUnits" # Component to edit the configuration
    defaultValue: # Default value of the configuration
      dimFactor: 139
      vKgFactor: 5000
      vLbFactor: 139
      lengthUnit: "In"

Key attributes:

• configName: Name of the configuration (unique within the system)
• displayName: Localized display names
• description: Localized descriptions
• component: Component name to edit the configuration
• defaultValue: Default value of the configuration (optional)

Permissions

Permissions define access control for various module features:

permissions:
  - name: "ExampleModule/Read"
    displayName:
      en-US: "Read Example Module"
    roles:
      - "Administrator"
  - name: "ExampleModule/Edit"
    displayName:
      en-US: "Edit Example Module"
    roles:
      - "Administrator"
      - "Editor"

Key attributes:

• name: Name of the permission (unique within the system)
• displayName: Localized display names
• roles: List of roles that can access the permission

Key Features

1. Localization: Supports multiple languages for display names and descriptions.
2. Dynamic Behavior: Includes support for queries, mutations, and conditional logic.
3. Flexible Layouts: Allows for complex UI structures with nested components.
4. Data Integration: Links UI components with backend entities and operations.
5. Access Control: Integrates permission management directly into the module definition.

Default Data

Default data is used to populate the module with data when it is loaded. It is defined in the defaultData section.

defaultData:
  - entity: "Currency"
    overwrite: true
    keys:
      - code
    data:
      - code: "USD"
        name: "US Dollar"
        symbol: "$"
  - entity: "PaymentTerm"
    keys:
      - name
    data:
      - name: "Net 30"
        description: "Payment due within 30 days"
        netDueDays: 30
        discountPercentage: 0
        discountDueDays: 0
      - name: "2/10 Net 30"
        description: "2% discount if paid within 10 days, otherwise due within 30 days"
        netDueDays: 30
        discountPercentage: 2
        discountDueDays: 10

Key attributes:

• entity: Name of the entity to populate
• keys: List of keys to identify the data (unique within the entity)
• data: List of data objects to populate the entity with
• overwrite: Overwrite existing data, default is false. If true, conflicts with existing data will be overwritten.

If a conflict is detected, the default data will not be loaded unless overwrite is set to true. Keys are used to identify duplicate records in the database.