@cxtms/cx-schema 1.9.67 → 1.9.242

package/skills/cxtms-workflow-builder/ref-flow.md

@@ -42,7 +42,9 @@ aggregations: [...]                         # Optional
 Specifies which entity's lifecycle this flow manages.
 
 ### Valid Entity Names
-Order, Commodity, AccountingTransaction, Workflow, OrganizationConfig, Contact, AppModule, Attachment, OrderCommodity, TrackingEvent, JobOrder
+Order, Commodity, AccountingTransaction, Workflow, OrganizationConfig, Contact, AppModule, Attachment, OrderCommodity, TrackingEvent, JobOrder, OrderMove, DispatchRoute
+
+`OrderMove` and `DispatchRoute` flows resolve target statuses by name within the current organization. A transition updates `OrderMoveStatusId` or `DispatchRouteStatusId`; assigning the current status is a no-op.
 
 ### Entity Types (required for specific entities)
 
@@ -162,10 +164,13 @@ states:
         priority: 1
 ```
 
+For Order-triggered auto-transitions, `order.orderStatusName` is available in the lightweight trigger payload and is loaded before trigger mapping when the navigation property was not already present.
+
 **Cross-entity resolution:**
 | Triggering Entity | Flow Entity | Resolution |
 |-------------------|-------------|------------|
 | Order | Commodity | Via `OrderCommodities` join table |
+| Commodity | Order | Via `OrderCommodities` join table; evaluates each distinct related order, then applies the Flow's Order subtype filter |
 
 ### From States
 - Single state: `from: Draft`

package/skills/cxtms-workflow-builder/ref-query.md

@@ -30,6 +30,19 @@ Executes internal GraphQL queries against the CX backend. The query runs via Med
 
 The query result is a dictionary. The `mapping` path extracts from the result. Output stored at `ActivityName.GetOrder.order`.
 
+GraphQL `filter` and `orderBy` strings support custom-value join expressions, including terminal, contact-address, and vessel references registered by the backend:
+
+```graphql
+orders(
+  organizationId: $organizationId
+  orderBy: "customValues.deliveryLocationId->contactAddress.name"
+  filter: "customValues.returnLocationId->contactAddress.name:Chicago*"
+  filter: "customValues.vesselId->vessel.name:Ever*"
+) { items { orderId orderNumber } }
+```
+
+Supported join aliases include `contact`, `order`, `modeOfTransportation`, `country`, `terminal`, and `contactAddress`.
+
 **Notes**:
 - `organizationId` is always available as a system variable
 - Variables support template expressions: `"{{ int organizationId }}"`
@@ -77,12 +90,14 @@ If validation fails and `continueOnError` is false (default), execution stops an
 ## Workflow/Execute
 
 Executes a child workflow. Can run sync (wait for result) or async (fire and forget).
+Pass `executionId` when the call represents a retryable business operation; it is treated as an idempotency key, so duplicate attempts return the original result instead of re-running the child workflow.
 
 ```yaml
 - task: "Workflow/Execute@1"
   name: RunChild
   inputs:
     workflowId: "<uuid>"
+    executionId: "{{ inputs.operationId? }}"
     workflowInputs:
       orderId: "{{ inputs.orderId }}"
       customerId: "{{ Data.GetOrder.order.customer.contactId }}"
@@ -91,6 +106,7 @@ Executes a child workflow. Can run sync (wait for result) or async (fire and for
 The child workflow's outputs are available as step outputs: `ActivityName.RunChild.outputName`.
 
 **Circular call detection**: The executor maintains a call stack and throws if a workflow calls itself recursively.
+**Idempotency**: Reuse an `executionId` only for retries of the same workflow operation. A reused ID for another workflow or organization is rejected.
 
 ## Workflow/Create, Workflow/Update, Workflow/Delete
 

package/skills/cxtms-workflow-builder/ref-utilities.md

@@ -155,6 +155,9 @@ Performs HTTP requests to external APIs.
   inputs:
     url: "{{ apiBaseUrl }}/api/v1/orders"
     method: POST
+    params:
+      status: "active"
+      limit: 10
     contentType: "application/json"
     headers:
       - name: "Authorization"
@@ -166,6 +169,8 @@ Performs HTTP requests to external APIs.
       mapping: "response?.body?"
 ```
 
+**`params`** (optional): Dictionary of URL query parameters. Keys and values are automatically URL-encoded and appended to the URL. Use when the query string comes from workflow variables rather than being hardcoded in the URL.
+
 **Response structure**: The task returns a `Dictionary<string, object>` (case-insensitive) with key `response`. The response contains `StatusCode`, `Headers`, and `Body` (PascalCase in C#, but access is case-insensitive). Use `response?.body?` to get the parsed body. You can drill deeper: `response?.body?.output?`, `response?.body?.items?[0]?`.
 
 **Case sensitivity**: Variable paths go through `Dictionary<string, object>(StringComparer.OrdinalIgnoreCase)` — so `body` and `Body` both work. Convention: use lowercase `body`.
@@ -297,11 +302,19 @@ Exports data to file format.
   inputs:
     data: "{{ Data?.GetOrders?.result?.items? }}"
     format: "csv"
+    headers: ["orderNumber", "firstTrackingNumber"]
+    columnMappings:
+      orderNumber: "Order #"
+      firstTrackingNumber: "First Tracking #"
+    exportTemplates:
+      firstTrackingNumber: "shipments?[0]?.trackingNumber?"
   outputs:
     - name: file
       mapping: "file?"
 ```
 
+**Computed export columns:** `exportTemplates` is an optional map of output header name → NCalc expression. Expressions are evaluated against each original row before the export record is written. Use null-safe paths for nested/collection data, e.g. `oceanShipments?[0]?.trackingNumber?`. `columnMappings` controls display labels; `exportTemplates` controls values.
+
 ## Import@1
 
 Imports data from file content or URL. Supports `file://` URLs for local files (e.g. from UnzipFile output).
@@ -317,6 +330,23 @@ Imports data from file content or URL. Supports `file://` URLs for local files (
       mapping: "data?"
 ```
 
+Use `columnMappings` when inbound CSV/XLSX headers do not match the internal field paths. Keys are the field paths workflows should consume; values are the headers present in the file.
+
+```yaml
+- task: "Utilities/Import@1"
+  name: ImportMappedData
+  inputs:
+    fileUrl: "{{ inputs.fileUrl }}"
+    format: "csv"
+    columnMappings:
+      contact.name: "Customer Name"
+      contact.emailAddress: "Email"
+      customValues.externalId: "External ID"
+  outputs:
+    - name: data
+      mapping: "data?"
+```
+
 ```yaml
 # Import from local file (e.g. extracted from ZIP)
 - task: "Utilities/Import@1"
@@ -363,7 +393,7 @@ Groups a collection of dictionaries by one or more fields. Produces `{ key, valu
 
 ## Import Tasks
 
-Import tasks handle bulk data ingestion. All support `file://` URLs for chaining with UnzipFile.
+Import tasks handle bulk data ingestion. All support `file://` URLs for chaining with UnzipFile. Dictionary-based imports skip empty cell values instead of overwriting existing data with blanks. Accounting Account, Accounting Item, Currency, Payment Term, and Sales Tax imports match by primary key first when an ID is present, then by configured key fields; matched rows are skipped unless `updateIfExists` is true.
 
 ### Order/Import@1
 
@@ -379,7 +409,7 @@ Imports postal/ZIP codes. Inputs: `organizationId`, `fileUrl`/`stream`/`postalCo
 
 ### TrackingEvent/Import@1
 
-Imports tracking events for an order. Inputs: `orderId`, `events`, `matchByFields` (default: `["eventDefinitionName", "eventDate"]`), `skipIfExists`, `createEventDefinitions`. Auto-links commodities via `CommodityId`.
+Imports tracking events for exactly one order, dispatch route, or dispatch route stop. Inputs: one of `orderId` / `dispatchRouteId` / `dispatchRouteStopId`, `events`, `matchByFields` (default: `["eventDefinitionName", "eventDate"]`), `skipIfExists`, `createEventDefinitions`. Order targets can auto-link commodities; route and stop targets do not.
 
 ```yaml
 # Full ZIP-to-import pipeline

package/templates/workflow-public-api.yaml

@@ -48,6 +48,7 @@ outputs:
       type: object
       description: "Order details"
       schema:
+        type: object
         properties:
           orderId:
             type: integer