Publish & Deploy

This lesson walks through the complete deploy-and-publish workflow step by step. You will learn how to push individual modules and workflows to the server, publish an entire feature in one shot, remove artifacts you no longer need, handle validation errors, and release a finished feature back to git.

---

Prerequisites

Before any server commands will work, make sure you are authenticated and have an active organization context. If you have not done this yet, complete the CLI Setup topic first.

bash
1# Verify your current context (server, org, app)
2npx cxtms orgs use
3
4# If no org is active, select one
5npx cxtms orgs select

For automation scripts or CI/CD pipelines, add your PAT token and server URL to .env:

1CXTMS_AUTH=pat_xxxxx...
2CXTMS_SERVER=https://tms-v3-dev.usatrt.com

When CXTMS_AUTH is set the CLI skips the interactive OAuth flow entirely.

---

Step 1: Deploy a Single Module

Use appmodule deploy to push one module file to the server. This creates the module if it does not exist, or updates it if it does.

bash
1npx cxtms appmodule deploy features/billing/modules/billing-module.yaml --org 5

Expected output:

1Deploying module: features/billing/modules/billing-module.yaml
2  ✔ BillingModule deployed (id: 3f8a2c1d-...)

The --org flag is the numeric organization ID. Always pass it explicitly in scripts to avoid the interactive org picker blocking execution.

When to use this: During active development, deploy individual modules frequently as you iterate on the YAML. There is no need to publish everything just to test one screen.

---

Step 2: Deploy a Single Workflow

Use workflow deploy to push one workflow file to the server.

bash
1npx cxtms workflow deploy features/billing/workflows/invoice-generation.yaml --org 5

Expected output:

1Deploying workflow: features/billing/workflows/invoice-generation.yaml
2  ✔ InvoiceGeneration deployed (id: 7b4d9e2a-...)

Deploying updates the server's copy of the workflow without affecting any currently running executions of the previous version. New executions will use the updated version immediately.

---

Step 3: Validate Before You Deploy

The CLI validates YAML against the schema before deploying. You can also run validation locally without touching the server:

bash
1# Validate a single module
2npx cxtms features/billing/modules/billing-module.yaml
3
4# Validate a single workflow
5npx cxtms features/billing/workflows/invoice-generation.yaml

This catches schema errors early. Fix all validation errors before deploying — the server will reject invalid YAML with the same errors, but validation is faster locally.

---

Step 4: Publish All — Entire Project

When you want to push every module and workflow in the project to the server at once, use publish without arguments:

bash
1npx cxtms publish --org 5

This command:

1. Discovers all *-module.yaml files under modules/ and features/*/modules/
2. Discovers all *.yaml workflow files under workflows/ and features/*/workflows/
3. Validates each file against its schema
4. Deploys each valid file to the server
5. Reports any files that failed validation (they are skipped, not aborted)

Expected output:

1Publishing project to org 5...
2  ✔ BillingModule
3  ✔ ShippingModule
4  ✔ InvoiceGeneration
5  ✔ ShipmentTracking
6  ⚠ features/shipping/workflows/broken-workflow.yaml — validation failed (skipped)
7Published 4 of 5 artifacts.

A validation failure on one file does not stop the rest from deploying. Review the error output, fix the affected file, and re-run publish or deploy it individually.

---

Step 5: Publish a Single Feature

To deploy only the modules and workflows for one feature, pass --feature:

bash
1npx cxtms publish --feature billing --org 5

This is equivalent to running appmodule deploy and workflow deploy on every file under features/billing/ — but in a single command.

You can also pass the feature name as a positional argument:

bash
1npx cxtms publish billing --org 5

When to use this: During feature development, publish the feature after a batch of related changes. This is faster than publishing the entire project and avoids touching unrelated modules and workflows.

---

Step 6: Undeploy a Module

To remove a module from the server, use appmodule undeploy with the module's UUID. You can find the UUID in the YAML file under appModuleId.

bash
1# Get the module ID from the YAML
2grep "appModuleId" features/billing/modules/old-module.yaml
3# appModuleId: 3f8a2c1d-e7b4-4a12-9c3d-1f2e8a4b6c0d
4
5npx cxtms appmodule undeploy 3f8a2c1d-e7b4-4a12-9c3d-1f2e8a4b6c0d --org 5

Expected output:

  ✔ Module 3f8a2c1d-... undeployed

Undeploying removes the module's UI screens and routes from the server. Users who had those screens open will see an error until they navigate away. Plan module removals accordingly.

---

Step 7: Undeploy a Workflow

Use workflow undeploy with the workflow's UUID. Find the UUID under workflowId in the YAML.

bash
1grep "workflowId" features/billing/workflows/old-workflow.yaml
2# workflowId: 7b4d9e2a-c3f1-4d89-b5e2-6a8c9d0e1f2b
3
4npx cxtms workflow undeploy 7b4d9e2a-c3f1-4d89-b5e2-6a8c9d0e1f2b --org 5

Expected output:

  ✔ Workflow 7b4d9e2a-... undeployed

Undeploying a workflow prevents new executions. Any execution currently in progress completes normally.

---

Step 8: Handle Validation Errors

If publish reports validation failures, read the error output carefully. Common causes:

Missing required field:

1features/billing/modules/billing-module.yaml
2  Error: module.application is required

Open the file and add the missing field. The application field must be "CargoXplorer".

Unknown component type:

1features/billing/modules/billing-module.yaml
2  Error: component 'customGrid' is not a valid component type

Check the component name against the schema. Common typo: dataGrid not datagrid.

Invalid template expression:

1features/billing/workflows/invoice-generation.yaml
2  Error: activity 'Main', step 'GetInvoice': inputs.orderId — invalid expression syntax

Template expressions use {{ }}. Check for unclosed braces or unsupported syntax.

Run npx cxtms <file.yaml> on the failing file alone to get the full error context without the noise of other files.

---

Step 9: Release to Git

Once you are satisfied with the feature on the dev server, release the server-side YAML back to git:

bash
1npx cxtms app release -m "Add billing feature: invoice and payment modules" --org 5

This creates a PR from a publish/... branch into your target branch. The PR contains the final YAML state of all modules and workflows that have unpublished changes.

To release only specific files:

bash
1npx cxtms app release -m "Fix billing module layout" \
2  features/billing/modules/billing-module.yaml \
3  --org 5

To release everything regardless of whether it has been changed:

bash
1npx cxtms app release -m "Full project republish" --force --org 5

Do not run app release automatically. Release deliberately when a feature is complete and ready for review.

---

Deployment Order Reference

Here is a summary of when to use each command:

---

CI/CD Integration

For automated pipelines, combine PAT token auth with publish:

yaml
1# GitHub Actions example
2- name: Publish to dev server
3  run: npx cxtms publish --org ${{ vars.CX_ORG_ID }}
4  env:
5    CXTMS_AUTH: ${{ secrets.CXTMS_PAT }}
6    CXTMS_SERVER: ${{ vars.CXTMS_SERVER }}

With CXTMS_AUTH set, the CLI skips the OAuth browser flow and authenticates directly with the PAT. The --org flag prevents any interactive prompts.

---

Summary

In this lesson you:

• Deployed individual modules with appmodule deploy and workflows with workflow deploy
• Published an entire project or a single feature with publish
• Removed artifacts from the server with appmodule undeploy and workflow undeploy
• Handled validation errors by reading the CLI output and fixing the affected YAML files
• Released server-side changes back to git with app release -m "<message>"

In the next topic, you will scaffold your first module and deploy it as part of a complete feature.