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 modulename
: Internal name of the moduledisplayName
: Localized display namesdescription
: Localized descriptionsapplication
: 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 routeprops
: Properties to pass to the componenttitle
: 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 namesfields
: List of fields in the entityname
: Name of the field (unique within the entity)displayName
: Localized display namesfieldType
: Type of the field (e.g., text, number, date)isCustomField
: Define as Custom fieldprops
: 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 namesdescription
: Localized descriptionscomponent
: Component name to edit the configurationdefaultValue
: 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 namesroles
: List of roles that can access the permission
Key Features
- Localization: Supports multiple languages for display names and descriptions.
- Dynamic Behavior: Includes support for queries, mutations, and conditional logic.
- Flexible Layouts: Allows for complex UI structures with nested components.
- Data Integration: Links UI components with backend entities and operations.
- 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 populatekeys
: List of keys to identify the data (unique within the entity)data
: List of data objects to populate the entity withoverwrite
: 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.