Developer Getting Started

Introduction

CargoXplorer is a low-code TMS platform where most customization is done without changing the platform source code. As a developer, you typically extend and modify the system using:

• 🧩 App Modules: UI screens, dialogs, routing, permissions, localization, client-side behavior (actions), and configuration surfaces.
• 🔄 Workflows: server-side automation, orchestration, validation gates (before-save), notifications, and integrations (webhooks, GraphQL tasks, utility tasks).

This page is a practical “developer onramp” that explains:

• What to change first (App Modules + Workflows)
• What requires platform source changes (new external libraries/frameworks, new primitives)
• How to structure your app repository and YAML

What you can implement with App Modules (typical)

• UI screens and navigation
  • New menu items, list/detail pages, dialogs, dashboards
  • Custom routes and nested routes
• User interactions and UI behavior
  • Buttons and action sequences (navigate, query, mutation, workflow execution)
  • Conditional rendering, validation, and form behavior
• Security and user experience
  • Permissions, role access to actions and routes
  • Localization of labels, titles, and help text
• Configuration and data surfaces
  • Organization-level configuration pages
  • Default/reference data shipped with the module

Quick start procedure (repository-first)

1. Create a Git repository for your app (one app per repo).
2. Add app.yaml at the repository root (name, version, repository URL, etc.).
3. Create modules/ and workflows/ folders to separate UI from automation.
4. Add your first App Module in modules/:
   • Define module: metadata
   • Add a minimal components: entry (screen) and routes: entry (navigation)
   • Add permissions: to control access
5. Add your first Workflow in workflows/:
   • Define workflow: metadata
   • Add at least one activities: block with one step
6. Commit and push changes so the platform can consume the updated YAML.
7. Deploy/sync the app into your CargoXplorer environment using your organization’s standard app delivery process.
8. Iterate safely:
   • Small commits
   • One feature per module/workflow change where possible
   • Use fileName and meaningful naming for traceability

🔗 End-to-end reference for steps and structure: Building Apps

Who this guide is for

This guide targets technical developers who:

• Can read/write YAML
• Understand basic TMS concepts (entities, events, triggers, validations, integrations)
• Are comfortable with Git and repository-based delivery

Development model (what goes where)

Goal	Best mechanism	Why
Add/modify screens, dialogs, lists, forms, widgets	🧩 App Modules	UI is declarative; changes are isolated and reviewable
Add button behaviors, validations, navigation, data fetch	🧩 App Module Actions	Actions provide consistent patterns for UI-driven behavior
Add business processes (approval flows, automation, orchestration)	🔄 Workflows	Centralized, event-driven, testable execution
Integrate external systems (REST endpoints, webhook-driven flows)	🔄 Workflows (+ UI actions if needed)	Workflows can run async, handle retries/logging/auditing
Add new component types, new workflow task types, or new runtime capabilities	🛠️ Platform source changes	Requires new framework-level building blocks

When source modification is required

Most work should stay in App Modules and Workflows. You usually need platform source changes when you must introduce new primitives, for example:

• External libraries/frameworks support
  • Adding a brand-new UI framework component not supported by the existing component catalog
  • Adding a new charting/mapping SDK integration that requires compiled/bundled frontend code
• New integration runtime capabilities
  • Adding a new workflow task type (e.g., a specialized connector) that is not available as a built-in task
• Core behavior changes
  • Modifying backend validation rules that must apply system-wide and cannot be expressed as a workflow “Before” trigger

If you’re unsure, start with App Modules + Workflows and only escalate to source changes when you hit a hard limitation.

YAML Structure

CargoXplorer apps are delivered as a Git repository that contains an app manifest plus YAML files for modules and workflows.

Recommended repository layout

my-app-repository/
├── app.yaml
├── README.md
├── icon.png                      # optional
├── modules/
│   ├── my-feature-module.yaml
│   └── ...
└── workflows/
    ├── my-workflow.yaml
    └── ...

🔗 For the canonical structure, see: Building Apps

App manifest (app.yaml) structure

app.yaml describes the app package metadata (name, version, repository, etc.).

name: "@cargox/my-app"
description: "My app extends CargoXplorer with custom screens and automation."
author: "My Company"
version: "1.0.0"
repository: "https://github.com/my-org/my-app.git"
icon: "icon.png" # optional

App Module YAML structure (high-level)

App Modules are defined in YAML files under modules/. The typical top-level sections are:

module:
components:
configurations:
entities:
permissions:
routes:
defaultData:

🔗 Deep dives:

• 🔗 App Modules overview
• 🔗 Components catalog
• 🔗 Routing
• 🔗 Permissions
• 🔗 Variables (UI expressions)
• 🔗 Actions reference

Workflow YAML structure (high-level)

Workflow YAML files live under workflows/. A common structure looks like:

workflow:
inputs:
outputs:
variables:
triggers:
schedules:
activities:
events:

🔗 Deep dives:

• 🔗 Workflows overview
• 🔗 Workflow YAML (manifest)
• 🔗 Triggers
• 🔗 Workflow variables
• 🔗 Workflow tasks
• 🔗 Webhook workflows

Attribute Description

This section summarizes the most-used attributes you will touch when building apps. It does not replace the full reference pages; instead it helps you quickly pick the right file/section.

App manifest (app.yaml)

Attribute	Type	Required	Description
name	string	Yes	Unique app package name (recommended: scoped name like @cargox/...)
description	string	Yes	Human-readable description of the app
author	string	Yes	Organization or individual maintaining the app
version	string	Yes	App version (SemVer recommended)
repository	string	Yes	Git repository URL used to source the app
icon	string	No	Relative file path to an icon (e.g., icon.png)

🔗 Full guide: Building Apps

App module definition (module:)

Attribute	Type	Required	Description
appModuleId	string (UUID)	Yes	Unique ID of the module
name	string	Yes	Internal module name (used in identifiers)
displayName	object	No	Localized display names (e.g., en-US)
description	object	No	Localized descriptions
application	string	Yes	Target application area (e.g., TMS)
fileName	string	No	Repo-relative path for UI linking (defaults to modules/{name}-module.yaml)

🔗 Full reference: App Modules

Workflow definition (workflow:)

Attribute	Type	Required	Description
workflowId	string (UUID)	Yes	Unique workflow identifier
name	string	Yes	Workflow display name
description	string	No	What the workflow does
isActive	boolean	No	Enable/disable the workflow (default true)
workflowType	string	No	Workflow type (e.g., Webhook for webhook workflows)
executionMode	string	No	Sync or Async (default Async)
logLevel	string	No	Logging level (use Debug during development)
enableTransaction	boolean	No	Execute within a transaction (default true)
runAs	string	No	User context (default is current user; use system when appropriate)
fileName	string	No	Repo-relative path for UI linking (defaults to workflows/{id}.yaml)

🔗 Full reference: Workflow YAML

Examples

This example shows a minimal end-to-end flow:

• A module adds a screen with a button
• The button triggers a workflow
• The workflow performs server-side work (example uses an Action Event for visibility/auditing)

Example 1: Minimal app manifest

app.yaml:

name: "@cargox/dev-getting-started-example"
description: "Example app: UI button triggers a workflow."
author: "CargoXplorer Docs"
version: "0.1.0"
repository: "https://github.com/example/dev-getting-started-example.git"

Example 2: Minimal module (screen + button)

modules/dev-getting-started-module.yaml:

module:
  appModuleId: "2c4f77c5-5a57-4c1f-9f55-1a5e1c2a0f11"
  name: "DevGettingStarted"
  application: "TMS"
  displayName:
    en-US: "Dev Getting Started"
  fileName: "modules/dev-getting-started-module.yaml"

permissions:
  - name: "DevGettingStarted/Run"
    displayName:
      en-US: "Run Dev Getting Started Workflow"
    roles:
      - "Administrator"

components:
  - name: "DevGettingStarted/Screen"
    displayName:
      en-US: "Dev Getting Started Screen"
    layout:
      component: "layout"
      children:
        - component: "text"
          props:
            value:
              en-US: "This screen is provided by an App Module."
        - component: "button"
          permission: "DevGettingStarted/Run"
          props:
            label:
              en-US: "Run workflow"
            options:
              variant: "primary"
              size: "md"
            onClick:
              - workflow:
                  workflowId: "6ee9fd9f-0fa1-4f1d-b5cd-09f75c79b9c4"
                  inputs:
                    source: "ui-button"

routes:
  - name: "DevGettingStarted/Home"
    path: "dev-getting-started"
    component: "DevGettingStarted/Screen"
    props:
      title:
        en-US: "Developer Getting Started"

🔗 References used in this example:

• 🔗 Button component
• 🔗 Actions reference (workflow action)
• 🔗 Routing

Example 3: Minimal workflow (creates an Action Event)

workflows/dev-getting-started-workflow.yaml:

workflow:
  workflowId: "6ee9fd9f-0fa1-4f1d-b5cd-09f75c79b9c4"
  name: "Dev / Getting Started / Example"
  description: "Example workflow triggered from an App Module button."
  isActive: true
  executionMode: "Async"
  logLevel: "Info"
  fileName: "workflows/dev-getting-started-workflow.yaml"

inputs:
  - name: "source"
    type: "text"
    props:
      required: true
      displayName:
        en-US: "Trigger Source"

activities:
  - name: "record"
    description: "Create an action event for traceability."
    steps:
      - task: "ActionEvent/Create@1"
        name: "createEvent"
        inputs:
          action:
            eventName: "dev.gettingStarted.run"
            eventData:
              source: "{{ source }}"
              workflowId: "{{ workflow.workflowId }}"
              workflowName: "{{ workflow.name }}"

🔗 References used in this example:

• 🔗 Workflow YAML
• 🔗 Workflow variables
• 🔗 ActionEvent entity

Best Practices

• Start with the platform extension points

  • Use 🧩 App Modules for UI, routing, permissions, and client-side actions.
  • Use 🔄 Workflows for server-side business logic, validations, and integrations.

• Keep repositories organized

  • Put all module YAML under modules/ and all workflows under workflows/.
  • Use meaningful file names and set fileName so the UI can link to your repo paths.

• Prefer declarative composition over source changes

  • If you can implement something with existing components/actions/tasks, do that first.
  • Escalate to platform code changes only when you need a new primitive.

• Design for observability

  • During development, use workflow.logLevel: "Debug" selectively.
  • Emit Action Events for important integration points and failures.

• Use “Before” triggers carefully

  • “Before” entity triggers are synchronous and can block persistence on error.
  • Use them for validation/gates; use “After” for notifications and downstream integrations.
  • 🔗 Triggers

• Be explicit with permissions

  • Add module permissions for screens/actions and assign them to roles.
  • Keep permission names consistent and predictable.

Related Topics

• 🔗 Platform Overview
• 🔗 Building Apps
• 🔗 App Modules
• 🔗 App Module Components
• 🔗 Actions
• 🔗 Workflows Overview
• 🔗 Workflow YAML
• 🔗 Workflow Variables
• 🔗 Workflow Tasks
• 🔗 GraphQL API Overview
• 🔗 API Credentials
• 🔗 Security