Getting Started

This guide walks you through creating your first CXTMS app — a UI screen with a button that triggers a server-side workflow.

Prerequisites: You can read/write YAML, are comfortable with Git, and have access to a CXTMS environment.

1. Create Your App Repository

Each app lives in its own Git repository with this structure:

my-app/
├── app.yaml              # App manifest
├── modules/
│   └── my-module.yaml    # UI definitions
└── workflows/
    └── my-workflow.yaml  # Server-side automation

Start with the manifest. Create app.yaml at the repository root:

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

For full manifest options, see Building Apps.

2. Add an App Module

Create modules/dev-getting-started-module.yaml. This defines a screen with a button that triggers a workflow:

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"

What this does:

• module: — registers the module with a unique ID and name
• permissions: — restricts the button to Administrators
• components: — defines a screen with a text block and a button. The button's onClick triggers a workflow by ID.
• routes: — maps the screen to the URL path /dev-getting-started

3. Add a Workflow

Create workflows/dev-getting-started-workflow.yaml. This workflow receives an input and creates an Action Event for traceability:

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 }}"

What this does:

• workflow: — identifies the workflow (the workflowId matches what the button references)
• inputs: — declares a required source parameter passed from the button
• activities: — runs one step: creates an Action Event with the trigger source and workflow metadata

4. Deploy

Commit and push your changes. Deploy the app into your CXTMS environment using your organization's standard app delivery process. Navigate to /dev-getting-started to see the screen and test the button.

What's Next

Goal	Go to
Understand the platform architecture	Platform Overview
Learn the full app repository structure	Building Apps
Build more UI screens and forms	App Modules → Components
Create workflows and automations	Workflows → Tasks
Query data programmatically	GraphQL API