@cxtms/cx-schema 1.9.24 → 1.9.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cxtms/cx-schema",
-  "version": "1.9.24",
+  "version": "1.9.25",
   "description": "Schema validation package for CXTMS YAML modules",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/schemas/workflows/tasks/order-tracking-event.json

@@ -74,6 +74,17 @@
           "type": ["boolean", "string"],
           "description": "Skip if same EventDefinitionId already on order"
         },
+        "autoLinkToCommodities": {
+          "type": ["boolean", "string"],
+          "description": "Per-task override for the tms.trackingEvents.autoLinkToCommodities org config. When true, links the tracking event to all first-level commodities; when false, skips auto-linking. Ignored when commodityIds is supplied."
+        },
+        "commodityIds": {
+          "type": ["array", "string"],
+          "description": "Explicit list of commodity IDs to link the tracking event to. When provided (non-empty), overrides auto-link entirely and links only these commodities. IDs not belonging to the order are silently dropped.",
+          "items": {
+            "type": ["integer", "string"]
+          }
+        },
         "eventDefinitionValues?": {
           "type": "object",
           "description": "Values for creating a new EventDefinition if not found by name",

package/schemas/workflows/tasks/tracking-event.json

@@ -1,12 +1,13 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "TrackingEvent Tasks",
-  "description": "Tracking event import operations",
+  "description": "Tracking event create and import operations",
   "type": "object",
   "properties": {
     "task": {
       "type": "string",
       "enum": [
+        "TrackingEvent/Create@1",
         "TrackingEvent/Import@1"
       ],
       "description": "Task type identifier"
@@ -36,11 +37,64 @@
     },
     "inputs": {
       "type": "object",
-      "description": "TrackingEvent/Import inputs",
+      "description": "TrackingEvent/Create inputs (organizationId, eventDefinitionId or eventDefinitionName, orderId/commodityId/commodityIds, description, location, includeInTracking, sendEmail, eventDate, customValues, skipIfExists, eventDefinitionValues) OR TrackingEvent/Import inputs",
       "properties": {
+        "organizationId": {
+          "type": ["integer", "string"],
+          "description": "Organization ID (required for TrackingEvent/Create@1)"
+        },
         "orderId": {
+          "type": ["integer", "string"],
+          "description": "Target order ID. Required for TrackingEvent/Import@1; for TrackingEvent/Create@1 at least one of orderId, commodityId, or commodityIds must be provided."
+        },
+        "commodityId": {
+          "type": ["integer", "string"],
+          "description": "(TrackingEvent/Create@1) Single commodity to link. Can be combined with orderId and/or commodityIds."
+        },
+        "commodityIds": {
+          "type": ["array", "string"],
+          "description": "(TrackingEvent/Create@1) List of commodities to link. Can be combined with orderId and/or commodityId.",
+          "items": {
+            "type": ["integer", "string"]
+          }
+        },
+        "eventDefinitionId": {
+          "type": ["integer", "string"],
+          "description": "(TrackingEvent/Create@1) ID of an existing event definition. Required if eventDefinitionName is not provided."
+        },
+        "eventDefinitionName": {
+          "type": "string",
+          "description": "(TrackingEvent/Create@1) Name of the event definition. Required if eventDefinitionId is not provided. Auto-creates a new definition when combined with eventDefinitionValues."
+        },
+        "eventDate": {
+          "type": "string",
+          "description": "(TrackingEvent/Create@1) Event date (converted to UTC; defaults to current UTC time)"
+        },
+        "includeInTracking": {
+          "type": ["boolean", "string"],
+          "description": "(TrackingEvent/Create@1) Include in public tracking display"
+        },
+        "sendEmail": {
+          "type": ["boolean", "string"],
+          "description": "(TrackingEvent/Create@1) Send email notification"
+        },
+        "location": {
+          "type": "string",
+          "description": "(TrackingEvent/Create@1) Event location (overrides EventDefinition default)"
+        },
+        "description": {
           "type": "string",
-          "description": "Target order ID (required)"
+          "description": "(TrackingEvent/Create@1) Event description (overrides EventDefinition default). NOTE: When specified at inputs level (not step root), this is the tracking-event description."
+        },
+        "customValues": {
+          "type": "object",
+          "description": "(TrackingEvent/Create@1) Free-form custom values stored on the event",
+          "additionalProperties": true
+        },
+        "eventDefinitionValues": {
+          "type": "object",
+          "description": "(TrackingEvent/Create@1) Values for creating a new EventDefinition when none matches the given name",
+          "additionalProperties": true
         },
         "events": {
           "type": ["array", "string"],
@@ -94,7 +148,7 @@
         },
         "skipIfExists": {
           "type": ["boolean", "string"],
-          "description": "Skip event if duplicate found via matchByFields. Default: true"
+          "description": "(TrackingEvent/Import@1) Skip event if duplicate found via matchByFields. Default: true. (TrackingEvent/Create@1) Skip if an event with the same event definition already exists on the target order or commodity."
         },
         "createEventDefinitions": {
           "type": ["boolean", "string"],

package/skills/cxtms-developer/ref-entity-order-sub.md

@@ -77,6 +77,12 @@ Milestone/tracking event on an order or commodity.
 |-------|------|
 | `eventDefinition` | `EventDefinition` |
 
+### GraphQL Computed
+
+| Field | Returns | Notes |
+|-------|---------|-------|
+| `businessDays(path: String!)` | `int?` | Business days from the date at `path` to today, using the org's business calendar. `path` is a dot-separated property path on the tracking event (e.g. `"eventDate"`, `"customValues.scheduledAt"`). Returns `null` if path doesn't resolve or value isn't a parseable date. |
+
 ---
 
 ## EventDefinition

package/skills/cxtms-developer/ref-entity-order.md

@@ -109,6 +109,7 @@ These are virtual fields that filter `orderEntities` by type:
 | `getChargesByChargeType(chargeType)` | `[Charge]` | Charges filtered by type |
 | `getOrderSummary(weightUnit, volumeUnit, dimensionsUnit)` | `OrderSummary` | |
 | `lastTrackingEvent(eventDefinitionName)` | `TrackingEvent` | Most recent |
+| `businessDays(path: String!)` | `int?` | Business days from the date at `path` to today, using the org's business calendar. `path` is a dot-separated property path on the order (e.g. `"customValues.leg.pickup.scheduledAt"`). Returns `null` if path doesn't resolve or value isn't a parseable date. |
 | `attachmentsSummary` | `OrderAttachmentSummaryGqlDto` | `.totalCount` (int), `.hasAny` (bool) — batched DataLoader, backed by DB view |
 | `notesSummary` | `OrderNoteSummaryGqlDto` | `.totalCount` (int), `.hasAny` (bool) — batched DataLoader, backed by DB view |
 | `notesCount(threadFilter)` | `int` | |

package/skills/cxtms-module-builder/ref-components-display.md

@@ -227,6 +227,7 @@ Colored chip/badge with dot indicator.
 | `label` | `string` | Badge text (template-parsed) |
 | `colorKey` | `string` | Color lookup key (template-parsed; defaults to lowercased label) |
 | `options.colors` | `Record<string, {label, bgcolor, dot}>` | Color map (must include `default`) |
+| `onClick` | `Action[]` | Actions to dispatch when the badge is clicked. Makes the badge interactive (pointer cursor). |
 
 ```yaml
 component: badge
@@ -238,6 +239,22 @@ props:
       active: { label: "Active", bgcolor: "#e8f5e9", dot: "#4caf50" }
       inactive: { label: "Inactive", bgcolor: "#fce4ec", dot: "#f44336" }
       default: { label: "Unknown", bgcolor: "#f5f5f5", dot: "#9e9e9e" }
+
+# Badge with click action
+component: badge
+name: priorityBadge
+props:
+  label: "{{ order.priority }}"
+  colorKey: "{{ order.priority }}"
+  options:
+    colors:
+      high: { label: "High", bgcolor: "#fce4ec", dot: "#f44336" }
+      normal: { label: "Normal", bgcolor: "#e8f5e9", dot: "#4caf50" }
+      default: { label: "Unknown", bgcolor: "#f5f5f5", dot: "#9e9e9e" }
+  onClick:
+    - navigate:
+        route: order-detail
+        params: { id: "{{ order.id }}" }
 ```
 
 ---

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

@@ -197,11 +197,11 @@ Input priority: `stream` > `fileUrl` > `postalCodes`. Task catches exceptions an
 | `OrderCharge/Create` | Create order charge |
 | `OrderDocument/Create` | Create order document |
 | `OrderDocument/Send` | Send order document |
-| `OrderTrackingEvent/Create` | Create a single tracking event on an order |
+| `OrderTrackingEvent/Create` | Create a single tracking event on an order. Auto-links to first-level commodities by default; override per task via `autoLinkToCommodities` or target specific commodities via `commodityIds`. |
 | `OrderEntity/ChangeCustomValue` | Change custom field value |
 
 ```yaml
-# Create a single tracking event
+# Create a single tracking event (auto-links to first-level commodities by default)
 - task: "OrderTrackingEvent/Create@1"
   name: AddPickupEvent
   inputs:
@@ -219,6 +219,32 @@ Input priority: `stream` > `fileUrl` > `postalCodes`. Task catches exceptions an
       carrierEventCode: "PU"
 ```
 
+**Auto-link to commodities.** When the event is added to an order, it is also linked to every first-level commodity (commodities where `ContainerCommodityId` is null). This behavior is governed by the org config `tms.trackingEvents.autoLinkToCommodities` (default `true`) and can be overridden per task:
+
+```yaml
+# Force-enable auto-link even if the org config disables it
+- task: "OrderTrackingEvent/Create@1"
+  inputs:
+    orderId: "{{ order.orderId }}"
+    organizationId: "{{ organizationId }}"
+    eventDefinitionName: "Arrived"
+    autoLinkToCommodities: true
+
+# Link to specific commodities only (bypasses auto-link entirely)
+- task: "OrderTrackingEvent/Create@1"
+  inputs:
+    orderId: "{{ order.orderId }}"
+    organizationId: "{{ organizationId }}"
+    eventDefinitionName: "Partial Delivery"
+    commodityIds: [101, 102, 103]
+```
+
+| Precedence | Source | Behavior |
+|---|---|---|
+| 1 (highest) | `commodityIds` input | Link exactly those IDs. IDs not on the order are silently dropped. `autoLinkToCommodities` is ignored. |
+| 2 | `autoLinkToCommodities` input | `true` → link all first-level commodities; `false` → link none. Overrides org config. |
+| 3 (default) | `tms.trackingEvents.autoLinkToCommodities` org config | Default `true` → link first-level commodities. |
+
 ## Inventory
 
 | Task | Description |
@@ -235,8 +261,27 @@ Input priority: `stream` > `fileUrl` > `postalCodes`. Task catches exceptions an
 | `Country/Create`, `Country/Update`, `Country/Delete` | Country CRUD |
 | `Cities/Import` | Import cities |
 | `Rate/Update` | Update rate |
+| `TrackingEvent/Create` | Create a single tracking event and link to an order, a commodity, or multiple commodities |
 | `TrackingEvent/Import` | Batch import tracking events into an order |
 
+```yaml
+# Create a single tracking event linked to a commodity (or a list of commodities)
+- task: "TrackingEvent/Create@1"
+  name: CreateCommodityEvent
+  inputs:
+    organizationId: "{{ organizationId }}"
+    eventDefinitionName: "Scanned"
+    commodityIds: [101, 102]   # or commodityId for a single commodity
+    orderId: "{{ order.orderId }}"   # optional; triggers auto-link to first-level commodities
+    eventDate: "{{ utcNow() }}"
+    location: "{{ scan.location }}"
+    includeInTracking: true
+    sendEmail: false
+    skipIfExists: true
+```
+
+Use [`OrderTrackingEvent/Create@1`](#order-sub-entities) when you want per-task overrides of the commodity auto-link behavior (`autoLinkToCommodities`, `commodityIds`). `TrackingEvent/Create@1` only honors the org-wide `tms.trackingEvents.autoLinkToCommodities` default for the auto-link step.
+
 ```yaml
 # Batch import tracking events
 - task: "TrackingEvent/Import@1"

package/skills/cxtms-workflow-builder/ref-expressions-ncalc.md

@@ -4,7 +4,7 @@
 - NCalc expression syntax `[variable]` (in conditions and expression directives)
 - Operators (comparison, logical, arithmetic, ternary, membership)
 - Iterator variables (`[each.*]` and `[item.*]`)
-- Collection functions (any, all, count, sum, first, last, distinct, select, zip, groupBy, join, etc.)
+- Collection functions (any, all, count, sum, first, last, distinct, select, zip, groupBy, join, sort, etc.)
 - String functions (isNullOrEmpty, length, lower, upper, replace, format, base64, coalesce, etc.)
 - Date functions (now, parseDate, addDays, formatDate, dateFromUnix, etc.)
 - Math functions (Abs, Ceiling, Floor, Round, Min, Max, etc.)
@@ -44,7 +44,7 @@ conditions:
 
 Functions use two iterator variable names:
 - **`[each.*]`** -- used by: `any`, `all`, `sum`, `select`, `join` (3-arg), and projections over `zip(...)` output
-- **`[item.*]`** -- used by: `first`, `last`, `groupBy`
+- **`[item.*]`** -- used by: `first`, `last`, `groupBy`, `sort`
 
 ### Collection Functions
 
@@ -68,6 +68,9 @@ Functions use two iterator variable names:
 | `zip([a], [b])` | Pair elements from two or more lists into `[{item1, item2}, ...]`. Custom keys: `zip([a], [b], 'name', 'code')`. Variadic: accepts N lists. Truncates to shortest list. Returns empty list if any input is empty/null. Falls back to `item1`, `item2`, ... when custom key count does not match list count |
 | `split([str], ' ')` | Split string by first character of separator. Returns `List<string>` |
 | `elementAt([items], 0)` | Get element at index (zero-based) from list |
+| `sort([items])` | Sort items ascending by their natural value |
+| `sort([items], [item.expr])` | Sort ascending by projected property using `[item.*]` accessor |
+| `sort([items], [item.expr], 'asc'\|'desc')` | Sort with explicit direction. `orderBy` is an alias for `sort` |
 
 ### String Functions
 

package/skills/cxtms-workflow-builder/ref-expressions-template.md

@@ -181,7 +181,7 @@ Used in `collection:` (foreach), `mapping:` (outputs), and variable resolution.
 | `list[*].dictKey` | Wildcard traversal into Dictionary/JObject keys | `items[*].customValues.chapter_en` |
 | `list[**]` | Recursive flatten (all depths) | `containerCommodities[**]` |
 | `list[-1]` | Depth filter (leaves only) | `tree[**][-1]` |
-| `list[condition]` | Filter by condition | `items[status=Active]` |
+| `list[condition]` | Filter by condition. LHS supports dotted nested paths | `items[status=Active]`, `activity[status.type=D]` |
 | `dict['key']` | Dictionary key access | `customValues['myField']` |
 | `list[*].{f1 f2}` | Field selector (projection) | `items[*].{name description}` |
 | `list[*].{alias:source}` | Field selector with alias | `items[*].{id:commodityId}` |