App Manifest

Overview

CXTMS Apps extend the functionality of the CXTMS platform by allowing developers to add custom features and integrations. This guide provides step-by-step instructions on how to build and deploy a CXTMS App using a Git repository.

Steps to Deploy an App

1. Create a Git Repository: Set up a dedicated Git repository for your app. Each app should have its own repository.

2. Organize App Structure: Structure your app repository with the following core elements:

   • app.yaml file for the app manifest
   • icon.png file for the app icon (optional)
   • README.md file for app information
   • modules directory for all app modules
   • workflows directory for all app workflows

3. Define App Manifest: Create the app.yaml file in the root of your repository.

4. Create README: Add a comprehensive README.md file to your repository root.

5. Develop Modules: Create and organize your app's modules within the modules directory.

Define App Manifest

The app.yaml file defines the app's manifest and should be placed in the root of your repository. Here's an example for an app named my-app:

name: "@cargox/my-app" # Name of the app (should be unique)
description: "My App provides tools for managing custom orders efficiently."
author: "CargoX" # Your name or organization
version: "1.0.0" # Semver versioning
repository: "https://github.com/my-org/my-app.git"
icon: "icon.png" # Optional

Key Attributes:

• name: The name of the app.
• description: A brief description of the app.
• author: The author of the app.
• version: The version of the app.
• repository: The URL of the app's repository.
• icon: The path to the app's icon file.

Managing Installed App Manifests

When an organization installs app manifests, each entry pins a source repository and branch, and can opt into automatic updates.

App Manifest Reference Fields

Field	Type	Required	Description
repository	string	Yes	Full HTTPS URL of the app's Git repository
repositoryBranch	string	Yes	Branch to install from (e.g., main, develop)
isAutoUpdateEnabled	boolean	No	When true, the platform automatically pulls the latest commit from the branch on each sync cycle. Defaults to false.

Example Configuration

appManifests:
  - repository: "https://github.com/cargoxplorer/cx-app-core"
    repositoryBranch: "develop"
    isAutoUpdateEnabled: true
  - repository: "https://github.com/cargoxplorer/cx-app-ups"
    repositoryBranch: "develop"
    isAutoUpdateEnabled: true
  - repository: "https://github.com/cargoxplorer/cx-app-fedex-v2"
    repositoryBranch: "develop"
    isAutoUpdateEnabled: true

Auto-Update Behavior

When isAutoUpdateEnabled is true, the platform syncs the app on every manifest update cycle, pulling the latest commit from the configured branch. This is recommended for staging and QA environments to keep apps current with active development. For production, set this to false and deploy from pinned tags or release branches.

Available First-Party Apps

The following apps are maintained by the CXTMS team and can be included in white-label configurations:

App	Repository	Description
cx-app-core	cargoxplorer/cx-app-core	Core platform modules shared across all organization types
cx-app-ups	cargoxplorer/cx-app-ups	UPS carrier integration — rate quotes, label generation, and tracking
cx-app-fedex-v2	cargoxplorer/cx-app-fedex-v2	FedEx v2 carrier integration — rate quotes, label generation, and tracking

README File

The README.md file should provide detailed information about the app, its features, and how to use it. Here's an example:

# My App

My App is a comprehensive solution for managing custom orders. It allows users to create, view, and track custom orders seamlessly within the CargoX platform.

## Features

- Create new custom orders with a user-friendly form.
- List and search through existing custom orders.
- Receive notifications for order updates.

## Setup Instructions

[Include setup and installation instructions here]

## Usage Guide

[Provide a brief guide on how to use the app]

App Module Files

App modules define both the UI components and workflows of your app. Place all module files in the modules directory within your repository. Organize modules into subdirectories as needed.

Example Structure:

modules/
└── name-module.yaml
└── name-2-module.yaml
└── name-3-module.yaml
└── ...

Workflow Files

Workflow files define the automated processes that are part of the app. Place all workflow files in the workflows directory within your app repository.

Repository Structure

Here's an example of the complete repository structure for a single app:

my-app-repository/
├── app.yaml
├── README.md
└── modules/
    └── name-module.yaml
    └── name-2-module.yaml
    └── name-3-module.yaml
    └── ...
└── workflows/
    └── workflow-id-1.yaml
    └── workflow-id-2.yaml
    └── workflow-id-3.yaml
    └── ...