@cxtms/cx-schema 1.9.67 → 1.9.241

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

@@ -6,6 +6,7 @@
 - Dashboard component
 - DashboardWidget component
 - Widget component
+- Map component
 - Timeline component
 - TimelineGrid component
 - OAuth2 component
@@ -103,6 +104,55 @@ props:
 
 ---
 
+## map
+
+Inline Google Maps component for plotting explicit markers or dispatch route/template stops.
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `google` | `google` | Map provider; only Google Maps is supported |
+| `height` | `number` | `520` | Map viewport height in pixels |
+| `center` | `{lat,lng}` | auto | Optional fixed center; numbers or numeric strings |
+| `zoom` | `number` | auto | Initial zoom; single marker defaults to 14 |
+| `markers` | `array` | - | Explicit markers; takes precedence over `stops` |
+| `stops` | `array` | - | Dispatch route/template stops converted from `stopContact.shipping` |
+| `fitBounds` | `boolean` | `true` | Fit viewport to valid markers when no fixed center is supplied |
+| `showUnmappedNote` | `boolean` | `true` | Show a caption for unplotted markers/stops |
+| `showInfoWindow` | `boolean` | `true` | Show marker label/address/stop type in a Google info window |
+| `onMarkerClick` | `action[]` | - | Fired with clicked marker as `result` |
+
+`markers` should include `id`, `label`, `lat`, `lng`, and optionally `number`, `address`, `stopType`. Invalid coordinates and `0,0` are treated as unmapped.
+
+```yaml
+component: map
+name: dispatchRouteMap
+props:
+  height: 560
+  stops: "{{ dispatchRoute.stops }}"
+  fitBounds: true
+  onMarkerClick:
+    - setStore:
+        selectedStopId: "{{ result.id }}"
+```
+
+```yaml
+component: map
+name: terminalMap
+props:
+  height: 420
+  center: { lat: 33.749, lng: -84.388 }
+  zoom: 8
+  markers:
+    - id: atl
+      label: Atlanta Terminal
+      lat: 33.749
+      lng: -84.388
+      address: "Atlanta, GA"
+```
+
+---
+
 ## notes
 
 Rich-text notes/comments component with TipTap editor, message threading, and pagination.
@@ -177,17 +227,17 @@ CSS Grid-based dashboard with draggable/resizable widgets.
 | `options.gridGap` | `number` | `16` | Gap between cells (px) |
 | `options.allowEdit` | `boolean` | `false` | Enable edit mode (drag/resize/add/remove) |
 | `options.showGridLines` | `boolean` | `true` | Grid background in edit mode |
-| `options.autoSave` | `boolean` | `false` | Auto-save layout |
+| `options.autoSave` | `boolean` | `false` | Auto-save layout to UserSettings (`tms:dashboards:{name}:layout`) |
 | `options.title` | `string` | — | Dashboard title |
 | `options.height` | `string` | — | Container height |
 
-**Children:** `dashboard-widget` components only.
+**Children:** `dashboard-widget` components only. Saved layouts merge sparse YAML-widget overrides, removed-widget markers, and user-added widget entries back onto YAML defaults.
 
 ---
 
 ## dashboard-widget
 
-Positioned widget card inside a dashboard. Supports drag-to-move and resize in edit mode.
+Positioned widget card inside a dashboard. Supports drag-to-move and resize in edit mode; the final drag/resize position is what gets persisted.
 
 **Props (under `options`):**
 | Prop | Type | Default | Description |
@@ -280,22 +330,37 @@ Data-driven widget that delegates to sub-components by type.
 
 ## timeline
 
-MUI Lab Timeline for displaying events chronologically. Horizontal or vertical orientation.
+The mobile renderer supports the shared normal and tracking contracts. In normal mode, `activeTemplate` can override `eventTemplate` for events mapped with `status: active`; both templates receive the event as `item`. Mobile renders horizontal timelines as a scrolling row and does not visually implement `alternateSides` or `showTodayMarker`. Query-backed sources can use static `events` as a failure fallback.
+
+MUI Lab Timeline for chronological events or milestone-based tracking progress.
+
+**Modes:**
+- `normal` (default): date-range timeline with day/week/month/year view controls.
+- `tracking`: vertical milestone timeline. Events are matched to `milestones[].key` through mapped event `key`; matched milestones are `completed`, unmatched milestones are `pending`, and unmatched events can be shown as `extra`.
 
 **Props:**
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `orientation` | `horizontal \| vertical` | `horizontal` | Layout mode |
-| `view` | `day \| week \| month \| year` | `week` | Time view |
-| `startDate` / `endDate` | `string` | — | Initial date range |
-| `eventSources` | `EventSource[]` | — | Same pattern as calendar |
-| `eventTemplate` | `ComponentProps` | — | Custom event template |
-| `options.height` | `string \| number` | `400` | Component height |
-| `options.showTodayMarker` | `boolean` | `true` | Today marker |
-| `options.enableZoom` | `boolean` | `true` | View switcher |
-| `options.enableNavigation` | `boolean` | `true` | Prev/next/today buttons |
-| `options.alternating` | `boolean` | `true` | Alternate sides (vertical) |
-| `options.dateFormat` | `string` | `MMM DD` | Date format |
+| `mode` | `normal \| tracking` | `normal` | Timeline behavior |
+| `orientation` | `horizontal \| vertical` | `horizontal` | Layout mode; tracking renders vertical |
+| `view` | `day \| week \| month \| year` | `week` | Time view for normal mode |
+| `startDate` / `endDate` | `string` | current week | Initial date range for normal mode |
+| `eventSources` | `EventSource[]` | — | GraphQL/static event sources |
+| `eventTemplate` | `ComponentProps` | — | Custom event template for normal mode |
+| `milestones` | `Milestone[]` | `[]` | Tracking milestones |
+| `options.height` | `string \| number` | `400`/`auto` | Component height |
+| `options.showTodayMarker` | `boolean` | `true` | Today marker in normal mode |
+| `options.enableZoom` | `boolean` | `true` | View switcher in normal mode |
+| `options.enableNavigation` | `boolean` | `true` | Prev/next/today buttons in normal mode |
+| `options.alternateSides` | `boolean` | `true` | Alternate sides in vertical mode |
+| `options.showTwoColumns` | `boolean` | `true` | Show date/status opposite event content in vertical mode |
+| `options.dateFormat` | `string` | `MMM DD` | Moment date format |
+| `options.timeFormat` | `string` | `h:mm A` | Moment time format |
+| `options.extraEvents` | `show \| hide` | `hide` | Show events that do not match a milestone in tracking mode |
+
+**EventSource:** `query.command`, `query.variables`, `query.path`, and `query.mapping` live under the `query` object. Mapping supports `id`, `key`, `date`, `title`, `description`, colors, icons, and additional fields. Tracking sources should map `key`. The component does not filter mapped events by `includeInTracking` or `isInactive`; apply those filters in the GraphQL query or source mapping when needed.
+
+**Milestone:** `{ key, label?, description?, icon? }`. `label` can be localized (`{ en-US: "Delivered" }`).
 
 **Events:** `onEventClick` (data: `event`)
 
@@ -307,12 +372,17 @@ props:
   view: month
   options:
     enableNavigation: true
-    alternating: true
+    alternateSides: true
+    showTwoColumns: true
   eventSources:
     - query:
-        command: "query($id: Int!) { orderHistory(orderId: $id) { id title date type } }"
+        command: "query($id: Int!) { orderHistory(orderId: $id) { id title date type includeInTracking isInactive } }"
         variables: { id: "{{ number orderId }}" }
-        path: orderHistory
+        path: data.orderHistory
+        mapping:
+          id: "{{ item.id }}"
+          date: "{{ item.date }}"
+          title: "{{ item.title }}"
   eventTemplate:
     component: card
     name: eventCard
@@ -329,8 +399,78 @@ props:
           props: { eventId: "{{ event.id }}" }
 ```
 
+```yaml
+component: timeline
+name: orderTracking
+props:
+  mode: tracking
+  orientation: vertical
+  options:
+    showTwoColumns: true
+    alternateSides: false
+    extraEvents: hide
+  eventSources:
+    - query:
+        command: >
+          query($organizationId: Int!, $orderId: Int!) {
+            order(organizationId: $organizationId, orderId: $orderId) {
+              trackingEvents {
+                trackingEventId
+                eventDate
+                description
+                includeInTracking
+                isInactive
+                eventDefinition { eventName }
+              }
+            }
+          }
+        variables:
+          organizationId: "{{ number organizationId }}"
+          orderId: "{{ number orderId }}"
+        path: order.trackingEvents
+        mapping:
+          key: "{{ item.eventDefinition.eventName }}"
+          id: "{{ item.trackingEventId }}"
+          date: "{{ item.eventDate }}"
+          title: "{{ item.eventDefinition.eventName }}"
+          description: "{{ item.description }}"
+  milestones:
+    - key: Shipment Created
+      label: { en-US: Shipment Created }
+    - key: In Transit
+      label: { en-US: In Transit }
+      icon: truck
+    - key: Delivered
+      label: { en-US: Delivered }
+      icon: check-circle
+```
+
 ---
 
+## planner
+
+Use `planner` when columns are ordinal positions within grouped resource rows, not time buckets. Items flow through extraction (`queries[].itemsPath`), grouping (`rows.groupBy`), stable sorting (`columns.orderBy`), and index-based placement.
+
+```yaml
+component: planner
+name: dispatchPlanner
+props:
+  queries:
+    - name: work
+      query: { command: 'query Work { work { items } }', path: work.items }
+    - name: resources
+      query: { command: 'query Resources { resources { items } }', path: resources.items }
+  rows: { groupBy: resourceId, fromQuery: resources, key: id, headerWidth: 240 }
+  columns: { orderBy: [{ field: sequence, direction: asc }], appendEmpty: true, label: 'Move {{ index }}', width: 400 }
+  itemTemplate: { component: card }
+```
+
+Optional templates cover row headers, empty cells/state, and summaries. Events are `onItemClick`, `onCellClick`, `onRowClick`, and `onItemsLoaded`. Explicit row-header and column widths are required for alignment when rows virtualize.
+
+`dotsMenu.items` adds dataGrid-style card actions. Items support `label`, `permission`, templated `disabled`, and `onClick`; actions receive the full item context without also triggering `onItemClick`.
+
+Set `columns.appendEmpty: true` to render one trailing empty ordinal slot beyond the largest group, ensuring every lane has an append target.
+
 ## timeline-grid
 
 CSS Grid-based timeline with swim lanes, drill-down, and virtual scrolling.
@@ -358,7 +498,7 @@ CSS Grid-based timeline with swim lanes, drill-down, and virtual scrolling.
 | Variable | Type | Description |
 |----------|------|-------------|
 | `dataSources` | `Record<string, TimelineEvent[]>` | Per-source events filtered to the column, keyed by `query.name` |
-| `column` | `ColumnDefinition` | Column metadata (`id`, `label`, `date`, `startDate`, `endDate`) |
+| `column` | `ColumnDefinition` | Column metadata (`id`, `label`, `date`, `startDate`, `endDate`, `startDateLocal`, `endDateLocal`) |
 | `columnIndex` | `number` | Zero-based column index |
 | `totalCount` | `number` | Total event count for the column across all sources |
 
@@ -366,7 +506,7 @@ CSS Grid-based timeline with swim lanes, drill-down, and virtual scrolling.
 | Event | Data | Description |
 |-------|------|-------------|
 | `onEventClick` | `item, view` | Event clicked |
-| `onCellClick` | `column, row, date, view` | Empty cell clicked |
+| `onCellClick` | `column, row, date, view` | Cell clicked; `column.startDate`/`endDate` are UTC ISO strings and `column.startDateLocal`/`endDateLocal` are local wall-clock `YYYY-MM-DDTHH:mm:ss` strings |
 | `onViewChange` | `previousView, newView, startDate, endDate` | View changed |
 | `onNavigate` | `direction, view, startDate, endDate` | Navigation |
 | `onEventsLoaded` | `events, eventCount, view, dataRange` | Data loaded |
@@ -374,6 +514,8 @@ CSS Grid-based timeline with swim lanes, drill-down, and virtual scrolling.
 
 **Column drill-down:** Click column header: year->month, month->week, week->day.
 
+**Cell click date fields:** In `onCellClick`, prefer `column.startDateLocal` / `column.endDateLocal` when passing the clicked calendar range to local-day queries or dialogs. `column.startDate` / `column.endDate` remain UTC ISO instants for absolute timestamp use cases.
+
 ```yaml
 component: timeline-grid
 name: scheduleGrid
@@ -453,9 +595,14 @@ OAuth2 authorization flow button. Opens popup for auth, exchanges code for token
 | `scopes` | `string[]` | Requested scopes |
 | `additionalParams` | `Record<string, string>` | Extra auth URL params |
 | `additionalHeaders` | `object` | Extra token request headers |
+| `oauthWorkflowId` | `string` | Optional workflow ID for server-side token exchange through `executeWorkflow` |
 | `label` | `ILocalizeString` | Button label (default: `Authorize`) |
 | `className` | `string` | Button CSS class |
 
+**Callback route:** configure OAuth providers with `/oauth2/callback`. The app redirects that stable URL to `/{locale}/oauth2/callback` and preserves the query string.
+
+**Workflow exchange:** when `oauthWorkflowId` is set, the callback passes `organizationId` inside `ExecuteWorkflowInput` together with `credentials`, `tokenUrl`, and `headers`. The `organizationId` is saved before opening the popup because the callback popup starts with a fresh Redux store.
+
 **Events:** `onToken` — fires with `{ token }` when OAuth completes.
 
 ```yaml
@@ -467,6 +614,7 @@ props:
   clientSecret: "{{ quickbooksClientSecret }}"
   authorizationUrl: "https://appcenter.intuit.com/connect/oauth2"
   tokenUrl: "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer"
+  oauthWorkflowId: "workflow-uuid-for-token-exchange" # optional
   scopes:
     - com.intuit.quickbooks.accounting
   onToken:

package/skills/cxtms-workflow-builder/SKILL.md

@@ -68,7 +68,7 @@ npx cxtms create workflow <name> --template <template>
 
 **`webhook`** — endpoint: `POST /api/v2/orgs/{organizationId}/webhooks/{workflowId}`. The endpoint is anonymous (`[AllowAnonymous]`) and rate-limited (10/sec, 100/min per IP). Two inputs are auto-injected by the controller: `payload` (parsed JSON body or raw string) and `request` (object with `headers`, `body`, `remoteIpAddress`). Control the HTTP response via `response` and `statusCode` outputs. Update `webhookSecret` configName to your app config path. Customize the `ValidateWebhook` step for your auth method (header secret, HMAC signature, etc.). Use `executionMode: Sync` when the caller needs a response; use `Async` for fire-and-forget (returns immediately). Keep `runAs: "system"` since the endpoint is anonymous. Add `additionalProperties.cors.allowedOrigins` to restrict CORS if needed.
 
-**`public-api`** — requires a top-level `api` section defining the REST endpoint. Set `api.path` with route params (e.g., `/orders/{orderId}`), `api.method` (GET/POST/PUT/PATCH/DELETE), `api.authentication` (`none`, `bearer`, `apiKey`), `api.document` (swagger doc name, default `"public"`), and `api.category` (swagger tag). Configure `api.rateLimit` with `perSecond`/`perMinute`. Each input uses `props.in` (`path`, `query`, `header`, `body`) to specify where the parameter comes from, and `props.format` for OpenAPI type hints (e.g., `uuid`, `date-time`). Outputs use `props.type`, `props.description`, and `props.schema` to describe the response for OpenAPI docs. Must use `executionMode: Sync`. Control HTTP response via `response` and `statusCode` outputs.
+**`public-api`** — requires a top-level `api` section defining the REST endpoint. Set `api.path` with route params (e.g., `/orders/{orderId}`), `api.method` (GET/POST/PUT/PATCH/DELETE), `api.authentication` (`none`, `bearer`, `apiKey`), `api.document` (swagger doc name, default `"public"`), and `api.category` (swagger tag). Configure `api.rateLimit` with `perSecond`/`perMinute`. Each input uses `props.in` (`path`, `query`, `header`, `body`) to specify where the parameter comes from, and `props.format` for OpenAPI type hints (e.g., `uuid`, `date-time`). Body inputs may define `props.schema` with recursive OpenAPI schema fields (`type`, `properties`, `required`, `items`, `format`, `description`, `enum`); body inputs without a schema render as an object request body. Prefer `api.responses` for response documentation. Legacy `response` outputs can still use `props.type`, `props.description`, and recursive `props.schema` to describe the single `200` response. Must use `executionMode: Sync`. Control HTTP response via `response` and `statusCode` outputs.
 
 **All templates** include workflow-level `events` (`onWorkflowStarted`, `onWorkflowCompleted`, `onWorkflowFailed`) and activity-level `events` (`onActivityStarted`, `onActivityCompleted`, `onActivityFailed`) with Log steps. Replace/extend these with notification tasks (Email/Send, HttpRequest, Workflow/Execute) as needed. (`onWorkflowExecuted` is a deprecated alias for `onWorkflowCompleted` — use `onWorkflowCompleted` in new workflows.)
 
@@ -191,10 +191,25 @@ events:                                     # Workflow-level event handlers
 For template expressions and value directives: see [ref-expressions-template.md](skills/cxtms-workflow-builder/ref-expressions-template.md)
 For NCalc conditions and functions: see [ref-expressions-ncalc.md](skills/cxtms-workflow-builder/ref-expressions-ncalc.md)
 
-**`{{ path }}`** — in step inputs. Single `{{ }}` returns raw object. Multiple returns string interpolation.
-**`[variable]`** — in conditions and `expression:` directives. NCalc syntax.
-**Value directives**: `expression`, `coalesce`, `foreach`, `switch`, `extends`, `$raw`
-**38 custom functions** + NCalc built-ins. Key ones: `isNullOrEmpty()`, `any()`, `all()`, `count()`, `sum()`, `first()`, `last()`, `contains()`, `join()`, `split()`, `format()`, `now()`, `addDays()`, `formatDate()`, `if()`, `groupBy()`, `concat()`, `distinct()`
+**`{{ path }}`** — in step inputs. Single `{{ }}` returns raw object. Multiple returns string interpolation. Supports sub-expressions `(variableName)` inside filter brackets for dynamic matching.
+**`[variable]`** — in conditions and `expression:` directives. NCalc syntax. **Warning**: empty strings are silently converted to `null` — always use `isNullOrEmpty()` instead of comparing to `''`. See [ref-expressions-ncalc.md](skills/cxtms-workflow-builder/ref-expressions-ncalc.md) Pitfalls section.
+**Value directives**: `expression`, `coalesce`, `foreach`, `switch`, `extends`, `$raw`, `$eval`, `resolve`, `decrypt`/`encrypt`
+**Type converters** (prefix in `{{ }}`): `int`, `decimal`, `bool`, `boolOrFalse`, `boolOrTrue`, `datetime`, `string`, `emptyIfNull`, `nullIfEmpty`, `luceneString`, `transliterate`, `transliterateUa`, `fromJson`, `toJson`, `trim`, `toLocalTime`
+**51 custom functions** + NCalc built-ins. Key ones: `isNullOrEmpty()`, `any()`, `all()`, `count()`, `sum()`, `first()`, `last()`, `contains()`, `join()`, `split()`, `format()`, `now()`, `addDays()`, `addHours()`, `dateDiff()`, `formatDate()`, `if()`, `groupBy()`, `concat()`, `distinct()`, `select()`, `zip()`, `regex()`, `fromJson()`
+
+### Resolution Pipeline
+
+Variables resolve through a 6-stage pipeline:
+1. **Declaration** — `variables:` section sets static/computed/expression values
+2. **Step input resolution** — `inputs:` values resolved per step
+3. **Template resolution** — `{{ }}` expressions parsed by `TemplatedVariableParser` (type converters, sub-expressions, property paths)
+4. **NCalc evaluation** — `conditions` and `expression:` directives evaluated by `ExpressionEvaluatorNCalc`
+5. **foreach scoping** — `item` and `index` variables injected per iteration
+6. **Output mapping** — step results stored as `ActivityName.StepName.outputKey`
+
+### Runtime Boundary
+
+Workflow `{{ }}` (server-side `TemplatedVariableParser`) and app module `{{ }}` (client-side custom template engine) are **different runtimes** with different syntax and capabilities. Workflow expressions support type converters, value directives, and NCalc conditions. App module expressions support their own operations: `eval`, `format`, `formatTz`, `hasPermission`, `isNullOrEmpty`, `any`, `isEqual`/`isEquals`, `moreThan`, `lessThan`, `dateDiff`, `daysBetween`, `daysUntil`, `daysAgo`, `isDateBefore`, `isDateAfter`, `round`, `trim`, `parse`, `startsWith`, `endsWith`, `includes`/`contains`, `isTrue`, `localStorage`, `sessionStorage`, `fromConfig`, `encodeURIComponent`.
 
 ### Null-Safe Operator `?` — USE BY DEFAULT
 
@@ -214,6 +229,30 @@ collection: "Activity?.Step?.output?.items?"
 url: "{{ config?.baseUrl? }}"
 ```
 
+### `fromConfig` Whole-Config Variables Include `organizationConfigId`
+
+When a workflow-level variable loads an organization config without a `key`, the runtime injects `organizationConfigId` into the returned object alongside the config custom values. Use this ID when a later `OrganizationConfig/Update@1` step needs to update the same record.
+
+```yaml
+variables:
+  - name: config
+    fromConfig:
+      configName: "apps.myApp"
+
+activities:
+  - name: UpdateConfig
+    steps:
+      - task: "OrganizationConfig/Update@1"
+        inputs:
+          organizationId: "{{ int organizationId }}"
+          organizationConfigId: "{{ int config.organizationConfigId }}"
+          organizationConfig:
+            baseUrl: "{{ config?.baseUrl? }}"
+            lastSyncAt: "{{ datetime now }}"
+```
+
+If `fromConfig.key` is provided, the variable resolves to only that keyed value and does not include `organizationConfigId`.
+
 **Engine-level null safety for object inputs**: Task inputs resolved as complex objects (e.g., `headers`, `columnMappings`, configuration objects) are automatically null-safe at the engine level. If an optional object input is omitted from YAML, the engine returns `null` instead of throwing — no `?` suffix needed on the YAML key itself. The `?` operator is still required in template expressions and NCalc paths that reference those objects.
 
 **When `?` is NOT needed** (guaranteed system variables):
@@ -386,7 +425,7 @@ npx cxtms workflow execute workflow.yaml --vars '{"mode": "preview"}' --file imp
 
 `--file varName=path` uploads the local file to the server via presigned URL and sets the resulting URL as the named variable. Can be specified multiple times.
 
-Returns execution result including `executionId`, `isAsync`, `outputs` (for Sync workflows).
+Returns execution result including `executionId`, `isAsync`, `outputs` (for Sync workflows). When retry safety matters, pass a stable `executionId` per business operation so duplicate `executeWorkflow` attempts replay the stored result instead of running side effects again.
 
 ### Execution Logs
 

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

@@ -14,6 +14,7 @@
 - Order sub-entity tasks (OrderCommodity, OrderCharge, OrderDocument, OrderTrackingEvent, OrderEntity)
 - Inventory tasks (InventoryItem Create, Update, Delete)
 - Other entity tasks (Movement, Country, Cities, Rate, TrackingEvent/Import)
+- Dispatch route generation tasks
 - Notification tasks (Create)
 - Note tasks (Create, Update, Delete, Import, Export, RenameThread)
 - AccountingTransaction/ApplyCredit task
@@ -46,6 +47,39 @@ Imports postal codes (CSV, JSON, Excel). Supports upsert via `matchByFields`.
 **Outputs:** `result.success`, `result.added`, `result.updated`, `result.errors`, `result.totalProcessed`, `result.hasErrors`
 Input priority: `stream` > `fileUrl` > `postalCodes`. Task catches exceptions and returns them in `result.errors`.
 
+## Dispatch Routes
+
+| Task | Description |
+|------|-------------|
+| `DispatchRoutes/Generate@1` | Generate daily draft dispatch routes from enabled templates |
+| `OrderMove/Create@1` | Create an order move with nested legs |
+| `OrderMove/Update@1` | Sparse-update a move and reconcile nested legs |
+| `OrderMove/Delete@1` | Soft-delete a move and its legs |
+
+### DispatchRoutes/Generate@1
+
+Creates draft dispatch routes for enabled templates whose `daysOfWeek` contains the requested route date. Idempotent per template/date: existing generated routes are skipped.
+
+```yaml
+- task: "DispatchRoutes/Generate@1"
+  name: GenerateDispatchRoutes
+  inputs:
+    organizationId: "{{ inputs.organizationId }}"
+    dispatchRouteStatusId: "{{ inputs.dispatchRouteStatusId }}"
+    routeDate: "{{ inputs.routeDate }}"
+  outputs:
+    - name: createdCount
+      mapping: "createdCount"
+    - name: skippedCount
+      mapping: "skippedCount"
+    - name: createdRouteIds
+      mapping: "createdRouteIds"
+```
+
+**Inputs:** `organizationId` (string, required), `dispatchRouteStatusId` (string, required), `routeDate` (string?, `yyyy-MM-dd`, defaults to today UTC), `dispatchRouteTemplateId` (string?, generate one template only).
+
+**Outputs:** `createdCount`, `skippedCount`, `createdRouteIds`. Generated routes copy template name, route type, division, and stops; driver/equipment assignment happens after generation.
+
 ## Generic Entity Change
 
 | Task | Description |
@@ -88,11 +122,18 @@ Input priority: `stream` > `fileUrl` > `postalCodes`. Task catches exceptions an
     entity:
       customer: "{{ inputs.customerId }}"
       status: "Draft"
+    values:
+      commodities:
+        - description: "{{ inputs.description }}"
+          pieces: "{{ inputs.pieces }}"
+          billToContactId: "{{ inputs.customerId }}"
   outputs:
     - name: order
       mapping: "order"
 ```
 
+For `Order/Create@1`, nested `values.commodities[*].billToContactId` is supported and is applied to the created commodity. Use it for multi-customer consolidations so downstream charge filtering can match commodity freight to the correct bill-to contact.
+
 ```yaml
 - task: "Order/Update@2"
   name: UpdateOrder
@@ -115,6 +156,7 @@ Imports order data from an external feed. Supports create and upsert (match-by-f
     options:
       orderMatchByFields: ["customValues.externalId"]
       commodityMatchByFields: ["customValues.lineId"]
+      commodityMatchConflict: Error
       skipValues: "NullOrEmpty"   # default — preserves existing data when feed stops sending a field
   outputs:
     - name: result
@@ -131,6 +173,7 @@ Imports order data from an external feed. Supports create and upsert (match-by-f
 | `inventoryItemMatchByFields` | string[] | null | Fields to match existing inventory items on commodities. |
 | `tagMatchByFields` | string[] | null | Fields to match existing tags. |
 | `commodityMatchByFields` | string[] | null | Fields to match existing commodities on update. |
+| `commodityMatchConflict` | `Link` \| `Error` | `Link` | Handling when a matched top-level commodity belongs to another order of the same type. `Error` skips it and adds an import error. |
 | `linkTrackingEventsToCommodities` | boolean | false | Link imported tracking events to first-level commodities. |
 | `skipValues` | `None` \| `Null` \| `NullOrEmpty` | `NullOrEmpty` | Strip null/empty values before updating existing records. `NullOrEmpty` (default) prevents feeds that stop returning a field from wiping existing data (e.g. ETA after delivery). Use `None` to allow explicit null overwrites. |
 
@@ -141,6 +184,8 @@ Imports order data from an external feed. Supports create and upsert (match-by-f
 
 **Order/Import commodity fields**: When importing commodities, you can supply `packageTypeName` (string) instead of `packageTypeId`. The import handler resolves the name to an ID using an N+1-safe per-import cache (one DB query per unique package type name).
 
+Commodity matches are shared across the entire import session. Nested container commodities match positionally within their parent, preserving repeated same-key lines without duplicating them on re-import.
+
 ## Contact
 
 | Task | Description |
@@ -149,6 +194,30 @@ Imports order data from an external feed. Supports create and upsert (match-by-f
 | `Contact/Update` | Update contact |
 | `Contact/Delete` | Delete contact |
 
+**Contact import behavior:** backend contact imports validate `DivisionId` against the target organization. Invalid division IDs are ignored; new contacts default to the importing user's division when no valid division is provided. Nested `division.divisionName` can be supplied and is resolved to an organization division before import.
+
+## OrganizationConfig
+
+| Task | Description |
+|------|-------------|
+| `OrganizationConfig/Update@1` | Update an existing organization configuration record with dynamic values |
+
+```yaml
+- task: "OrganizationConfig/Update@1"
+  name: UpdateOrgConfig
+  inputs:
+    organizationId: "{{ int inputs.organizationId }}"
+    organizationConfigId: "{{ int vars.config.organizationConfigId }}"
+    organizationConfig:
+      values:
+        enabled: true
+  outputs:
+    - name: result
+      mapping: "result?"
+```
+
+**Inputs:** `organizationId` (int, required), `organizationConfigId` (int, required), `organizationConfig` (object, required dynamic values). Returns an empty object on success. Query by config name first if you do not already have the ID.
+
 ## Contact Address
 
 | Task | Description |
@@ -156,7 +225,32 @@ Imports order data from an external feed. Supports create and upsert (match-by-f
 | `ContactAddress/Create` | Create address |
 | `ContactAddress/Update` | Update address |
 | `ContactAddress/Delete` | Delete address |
-| `ContactAddress/Import` | Bulk import addresses |
+| `ContactAddress/Import` | Bulk import addresses; ID-first upsert when `ContactAddressId` or `contactAddressId` is present |
+
+**Selective import fetch:** `ContactAddress/Import@1` matches rows by `ContactAddressId`/`contactAddressId` first, then by `matchByFields`. Rows are bound as dictionaries, so primary-key columns and custom inbound column names survive even when there is no DTO property. When `matchByFields` is set, the importer builds batched Lucene filters from the incoming row values and fetches only candidate `AddressType.Other` addresses for the target contact. If `matchByFields` is omitted, it falls back to loading all `Other` addresses for that contact. Use stable fields such as `AddressLine`, `CityName`, `CountryCode`, `PostalCode`, and `StateCode` for large imports.
+
+
+### ContactAddress/Import@1
+
+Bulk imports contact addresses for one `organizationId` + `contactId` from file/stream/import data. The import reads rows as dictionaries, so column mappings and aliases are supported.
+
+```yaml
+- task: "ContactAddress/Import@1"
+  name: ImportContactAddresses
+  inputs:
+    organizationId: "{{ int inputs.organizationId }}"
+    contactId: "{{ int inputs.contactId }}"
+    fileUrl: "{{ inputs.fileUrl }}"
+    fileType: "Csv"
+    matchByFields: [AddressLine, AddressLine2, CityName, CountryCode, PostalCode, StateCode]
+    columnMappings:
+      City: CityName
+  outputs:
+    - name: result
+      mapping: "result?"
+```
+
+**Behavior:** rows with `ContactAddressId` or `contactAddressId` match existing addresses by ID first; otherwise `matchByFields` is used. New rows default to `AddressType.Other`. `City` aliases to `CityName`; `StateCode` is used directly or `StateName` is resolved. `Longitude` + `Latitude` set location. Rows missing country or state context are skipped.
 
 ## Contact Payment Method
 
@@ -172,7 +266,7 @@ Imports order data from an external feed. Supports create and upsert (match-by-f
 | Task | Description |
 |------|-------------|
 | `Commodity/Create` | Create commodity |
-| `Commodity/Update` (v1, v2) | Update commodity |
+| `Commodity/Update` (v1, v2) | Update commodity; supports scan custom-value cascade flags `cascadeToChildren` and `promoteParentWhenAllChildren` |
 | `Commodity/Split` | Split commodity into multiple |
 | `Commodity/Repack` | Repack commodities |
 | `Commodity/Unpack` | Unpack commodity |
@@ -298,8 +392,8 @@ Imports order data from an external feed. Supports create and upsert (match-by-f
 | `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 |
+| `TrackingEvent/Create` | Create a single tracking event and link to an order, commodity, dispatch route, or dispatch route stop |
+| `TrackingEvent/Import` | Batch import tracking events into exactly one order, dispatch route, or dispatch route stop |
 
 ```yaml
 # Create a single tracking event linked to a commodity (or a list of commodities)
@@ -319,6 +413,8 @@ Imports order data from an external feed. Supports create and upsert (match-by-f
 
 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.
 
+For dispatch milestones, pass `dispatchRouteId` or `dispatchRouteStopId` to `TrackingEvent/Create@1`. For `TrackingEvent/Import@1`, provide exactly one of `orderId`, `dispatchRouteId`, or `dispatchRouteStopId`; route and stop imports do not auto-link commodities.
+
 ```yaml
 # Batch import tracking events
 - task: "TrackingEvent/Import@1"

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

@@ -5,10 +5,12 @@
 - Operators (comparison, logical, arithmetic, ternary, membership)
 - Iterator variables (`[each.*]` and `[item.*]`)
 - 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.)
+- String functions (isNullOrEmpty, length, lower, upper, replace, format, base64, fromJson, regex, coalesce, etc.)
+- Date functions (now, parseDate, addDays, addHours, dateDiff, formatDate, dateFromUnix, dateToUtc, toLocalTime)
 - Math functions (Abs, Ceiling, Floor, Round, Min, Max, etc.)
 - Domain functions (convertWeight, convertDimension)
+- Variable resolution details
+- Pitfalls (empty string null trap)
 
 For template expressions `{{ path }}` used in step inputs, see [ref-expressions-template.md](ref-expressions-template.md).
 
@@ -85,6 +87,8 @@ Functions use two iterator variable names:
 | `trim([value])` | Trim whitespace. Returns `""` for null |
 | `format('{0}-{1}', [prefix], [id])` | String.Format style. Variadic args. Returns null if format is null |
 | `base64([value])` / `fromBase64([encoded])` | Base64 encode/decode. Handles string, byte[], JToken |
+| `fromJson([str])` | Parse JSON string to Dictionary or JArray. Returns `null` for null input |
+| `regex([str], 'pattern')` | Regex match. Returns match result |
 | `bool([value])` | Convert to boolean: null->`false`, empty string->`false`, "true"/"false"->parsed, non-zero number->`true`, any object->`true` |
 | `transliterate([value])` | Unicode to ASCII (Unidecode). Returns `""` for null |
 | `transliterateUa([value])` | Ukrainian-specific transliteration. Returns `""` for null |
@@ -101,6 +105,7 @@ Functions use two iterator variable names:
 | `now('yyyy-MM-dd', 'en-US')` | Formatted current time as string |
 | `addDays([date], 30)` | Add days (decimal, can be negative). Accepts DateTime, DateTimeOffset, string |
 | `addHours([date], 2)` | Add hours (decimal, can be negative). Same type handling |
+| `dateDiff([start], [end], 'unit')` | Difference between two dates in specified unit |
 | `formatDate([date], 'dd/MM/yyyy')` | Format date using InvariantCulture (culture optional). Returns `null` for null or unparseable input. Accepts `DateTime`, `DateTimeOffset`, or string (including `DateTimeOffset`-shaped strings from `toLocalTime`) |
 | `formatDate([date], 'dd/MM/yyyy', 'en-US')` | Format date with explicit culture |
 | `dateFromUnix([unixTime])` | Unix timestamp (seconds) -> `DateTimeOffset`. Accepts int, long, decimal, string |
@@ -135,3 +140,31 @@ Custom: `ceiling([value])` -- same as `Ceiling` but handles type conversion to d
 |----------|-------------|
 | `convertWeight([weight], 'Kg', 'Lb')` | Weight unit conversion. Returns `decimal` rounded to 5 places |
 | `convertDimension([length], 'Cm', 'In')` | Dimension unit conversion. Returns `decimal` rounded to 3 places |
+
+---
+
+## Variable Resolution Details
+
+- `[variableName]` → workflow variable dictionary lookup via `GetPropertyValue()`
+- `[order.status]` → dot-path traversal through nested dictionaries/reflection
+- Without `?` → throws `InvalidOperationException` on missing path
+- With `?` → returns null instead of throwing
+- Empty string → null conversion (see Pitfalls below)
+- `FormatException` → retries with numeric string conversion (`"42"` → `42m`)
+
+## Pitfalls
+
+### Empty String Null Trap
+
+The NCalc engine silently converts `""` (empty string) to `null` **before** evaluating expressions. This happens in `EvaluateParameter` — it uses `string.IsNullOrEmpty()` (not `IsNullOrWhiteSpace`), so whitespace-only strings like `" "` pass through as-is.
+
+**Consequence**: `[myVar] != ''` is **always true** when the variable is empty, because the empty string becomes `null` and `null != ''` evaluates to `true`.
+
+**Rule**: Never compare against empty string. Always use `isNullOrEmpty()` instead:
+```yaml
+# WRONG — always true when myVar is empty
+expression: "[myVar] != ''"
+
+# CORRECT
+expression: "isNullOrEmpty([myVar]) = false"
+```

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

@@ -24,6 +24,8 @@ inputs:
 
 **Date string normalization in step inputs**: When a string value is merged into a step's input dictionary (via `AddRangeN`), the engine auto-detects date/datetime strings and converts them to ISO format. Common formats recognized: ISO (`2024-03-15`), US (`03/15/2024`), EU (`25/12/2024`), datetime with offset (`2024-03-15T15:30:45+05:00` → UTC). Empty strings are converted to `null`. OLE Automation date numbers (e.g., `"45752"`) are also recognized as dates — but only when the field name includes a date/time keyword (e.g., `departureDate`, `pickupTime`). A numeric string like `"45752"` for a field named `amount` is kept as-is.
 
+**DateTime assignment in dynamic entity updates**: Values assigned to `DateTime` or nullable `DateTime` entity fields are normalized to UTC before persistence. Offset-bearing strings and local/offset values are shifted to the equivalent UTC instant. Zone-less strings and `DateTime` values with an unspecified kind are assumed UTC without changing their wall-clock value. Empty strings become `null` only for nullable fields; use ISO 8601 with `Z` or an explicit offset whenever the source represents a known instant.
+
 ### Type Converters (prefix in {{ }})
 
 ```yaml
@@ -180,9 +182,10 @@ Used in `collection:` (foreach), `mapping:` (outputs), and variable resolution.
 | `list[*]` | Flatten/wildcard (all items) | `containers[*].commodities` |
 | `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[-1]` | Tree-depth filter from end (meaningful after `[**]` recursive flatten) | `tree[**][-1]` |
 | `list[condition]` | Filter by condition. LHS supports dotted nested paths | `items[status=Active]`, `activity[status.type=D]` |
 | `dict['key']` | Dictionary key access | `customValues['myField']` |
+| `dict[variableName]` | Dynamic key — resolves variableName as property path, uses result as dict key | `customValues[mode]` |
 | `list[*].{f1 f2}` | Field selector (projection) | `items[*].{name description}` |
 | `list[*].{alias:source}` | Field selector with alias | `items[*].{id:commodityId}` |
 | `list[*].{alias:_.parent}` | Field selector referencing parent | `items[*].{parentId:_.orderId}` |
@@ -190,3 +193,14 @@ Used in `collection:` (foreach), `mapping:` (outputs), and variable resolution.
 **Wildcard traversal into Dictionary/JObject**: After `[*]`, subsequent path segments drill into Dictionary keys and JObject properties on each item. Dictionary-like values are preserved intact (not flattened) so multi-hop paths work: `items[*].customValues.chapter_en` extracts the `chapter_en` key from each item's `customValues` dictionary. This also works with nested dictionaries (`items[*].meta.locale.name`) and JObject items from JSON payloads.
 
 **JArray primitive unwrapping**: When `GetPropertyValue` encounters a JArray where every element is a JValue (primitive), it automatically unwraps the array into a `List<object>` of plain .NET values. This ensures downstream iteration (e.g., `select()`, `zip()`, `foreach`) works with primitives rather than JValue wrappers.
+
+### Sub-expressions
+
+Parenthesized `(variableName)` inside filter brackets resolves the inner variable first, then uses its value as the filter match target:
+
+```yaml
+# selected_status resolves to e.g. "Active", then items is filtered where status matches
+filteredName: "{{ order.items.[status=(selected_status)].[0].name }}"
+```
+
+The inner variable `(selected_status)` is resolved through the same property path engine before the filter expression is evaluated. This enables dynamic filtering where the match value comes from a workflow variable rather than a literal.