@cxtms/cx-schema 1.8.0 → 1.8.2

package/.claude/skills/cx-core/SKILL.md

@@ -1,21 +1,11 @@
 ---
 name: cx-core
-description: >
-  Provides shared CXTMS entity field reference — domain entities, field names, enums, and customValues patterns.
-  Use when the user asks about CX entity fields, enums, customValues, entity relationships, or needs domain reference for Orders, Contacts, Commodities, Jobs, etc.
+description: Shared CargoXplorer entity field reference — domain entities, field names, enums, and customValues patterns
 argument-hint: <entity name or question about fields>
 ---
 
 Shared domain reference for CargoXplorer entities. Used by `cx-workflow` and `cx-module` skills for entity field names, types, navigation properties, enums, and customValues extension patterns.
 
-## CX Server Authentication & Management
-
-For CLI authentication, PAT tokens, org management, and releasing: see [ref-cli-auth.md](ref-cli-auth.md)
-
-## GraphQL Querying & Audit History
-
-For running GraphQL queries via CLI, filter syntax (Lucene), pagination, audit change history, and field discovery: see [ref-graphql-query.md](ref-graphql-query.md)
-
 ## Feature File Layout
 
 All modules and workflows are organized under feature directories:
@@ -31,21 +21,49 @@ When creating new modules or workflows, always place them under the correct feat
 - `features/<feature_name>/modules/<name>-module.yaml`
 - `features/<feature_name>/workflows/<name>.yaml`
 
-Use `--feature <feature_name>` with `cxtms create` to automatically place files in the correct location.
+Use `--feature <feature_name>` with `cx-cli create` to automatically place files in the correct location.
 
 ## Entity Field Reference
 
-Read the relevant entity reference file when needed for the current task. Do not load all files upfront.
+### Primary Entities
+
+!cat .claude/skills/cx-core/ref-entity-order.md
+!cat .claude/skills/cx-core/ref-entity-contact.md
+!cat .claude/skills/cx-core/ref-entity-commodity.md
+!cat .claude/skills/cx-core/ref-entity-accounting.md
+
+### Order Sub-Entities & Related
+
+!cat .claude/skills/cx-core/ref-entity-order-sub.md
+!cat .claude/skills/cx-core/ref-entity-job.md
+
+### Pricing & Accounting Lookups
+
+!cat .claude/skills/cx-core/ref-entity-rate.md
+
+### Shared & Lookup Entities
+
+!cat .claude/skills/cx-core/ref-entity-shared.md
+!cat .claude/skills/cx-core/ref-entity-geography.md
+
+### Warehouse & Inventory
+
+!cat .claude/skills/cx-core/ref-entity-warehouse.md
+
+### Notifications
+
+!cat .claude/skills/cx-core/ref-entity-notification.md
 
 | Category | Entities | Reference |
 |----------|----------|-----------|
-| **Primary** | Order, Contact, Commodity, AccountingTransaction | [ref-entity-order.md](ref-entity-order.md), [ref-entity-contact.md](ref-entity-contact.md), [ref-entity-commodity.md](ref-entity-commodity.md), [ref-entity-accounting.md](ref-entity-accounting.md) |
-| **Order sub** | OrderEntity, TrackingEvent, EventDefinition, LinkedOrder, OrderDocument | [ref-entity-order-sub.md](ref-entity-order-sub.md) |
-| **Job** | Job, JobOrder, JobStatus | [ref-entity-job.md](ref-entity-job.md) |
-| **Pricing** | Rate, Lane, Discount, AccountingItem, AccountingAccount, PaymentTerm | [ref-entity-rate.md](ref-entity-rate.md) |
-| **Shared** | Tag, Attachment, Division, EquipmentType, PackageType, Note/NoteThread | [ref-entity-shared.md](ref-entity-shared.md) |
-| **Geography** | Country, State, City, Port, Vessel, CustomCode, ModeOfTransportation | [ref-entity-geography.md](ref-entity-geography.md) |
-| **Warehouse** | InventoryItem, WarehouseLocation, CargoMovement (Order variant) | [ref-entity-warehouse.md](ref-entity-warehouse.md) |
+| **Primary** | Order, Contact, Commodity, AccountingTransaction | ref-entity-order/contact/commodity/accounting.md |
+| **Order sub** | OrderEntity, TrackingEvent, EventDefinition, LinkedOrder, OrderDocument | ref-entity-order-sub.md |
+| **Job** | Job, JobOrder, JobStatus | ref-entity-job.md |
+| **Pricing** | Rate, Lane, Discount, AccountingItem, AccountingAccount, PaymentTerm | ref-entity-rate.md |
+| **Shared** | Tag, Attachment, Division, EquipmentType, PackageType, Note/NoteThread | ref-entity-shared.md |
+| **Geography** | Country, State, City, Port, Vessel, CustomCode, ModeOfTransportation | ref-entity-geography.md |
+| **Warehouse** | InventoryItem, WarehouseLocation, CargoMovement (Order variant) | ref-entity-warehouse.md |
+| **Notification** | Notification, UserNotification | ref-entity-notification.md |
 
 ## CustomValues Pattern
 

package/.claude/skills/cx-core/ref-entity-notification.md

@@ -0,0 +1,85 @@
+# Notification Entity Reference
+
+Real-time notification system. Notifications are org-scoped with per-user read tracking via `UserNotification`.
+
+## Notification
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `notificationId` | `int` | PK |
+| `organizationId` | `int` | FK to Organization |
+| `title` | `string` | Required |
+| `message` | `string?` | Body text, supports Markdown |
+| `type` | `NotificationType` | System=0, OrderUpdate=1, TaskAssignment=2, Alert=3, Info=4 |
+| `priority` | `NotificationPriority` | Low=0, Normal=1, High=2, Urgent=3 |
+| `targetUserId` | `string?` | If set, targets one user; if null, broadcasts to all active org users |
+| `entityType` | `string?` | Linked entity type (e.g. "Order", "Job") |
+| `entityId` | `int?` | Linked entity PK |
+| `expiresAt` | `DateTime?` | Optional expiration |
+| `created` / `lastModified` | `DateTime` | Audit fields (from `AuditableEntity`) |
+| `createdBy` / `lastModifiedBy` | `string` | Audit fields |
+
+### Domain Methods
+
+- `ChangeTitle(string)`, `ChangeMessage(string?)`, `ChangeType(NotificationType)`, `ChangePriority(NotificationPriority)`, `ChangeExpiresAt(DateTime?)`
+
+---
+
+## UserNotification
+
+Per-user read state join entity.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `userNotificationId` | `int` | PK |
+| `notificationId` | `int` | FK to Notification |
+| `userId` | `string` | FK to ApplicationUser |
+| `isRead` | `bool` | Default false |
+| `readAt` | `DateTime?` | Set when marked read |
+
+### Domain Methods
+
+- `MarkAsRead()` — sets `IsRead = true`, `ReadAt = UtcNow`
+- `MarkAsUnread()` — resets both
+
+---
+
+## GraphQL
+
+### Queries
+
+- `getNotification(organizationId, notificationId)` → single notification for current user (projected from UserNotification)
+- `getNotifications(organizationId, filter?, search?, orderBy?)` → offset-paged list for current user; default sort: `-notification.created`
+- `getUnreadNotificationCount(organizationId)` → int
+
+### Mutations
+
+- `createNotification(organizationId, values)` → creates Notification + UserNotification rows; publishes to subscription topic per user
+- `markNotificationRead(organizationId, notificationId)` → bool
+- `markAllNotificationsRead(organizationId)` → int (count marked)
+- `deleteNotification(organizationId, notificationId)` → DeleteResult
+
+### Subscriptions
+
+- `onNotificationReceived(organizationId, userId)` → real-time via PostgreSQL NOTIFY/LISTEN
+  - Topic: `{organizationId}_{userId}_notifications`
+
+### GraphQL DTO (projected from UserNotification)
+
+Flattens `Notification` + `UserNotification` into single DTO: `notificationId`, `organizationId`, `title`, `message`, `type`, `priority`, `targetUserId`, `entityType`, `entityId`, `expiresAt`, `isRead`, `readAt`, `created`, `createdBy`, `lastModified`, `lastModifiedBy`, plus resolved `createdUser` / `updatedUser`.
+
+---
+
+## Targeting Logic
+
+On `CreateNotification`:
+1. If `targetUserId` is provided → single `UserNotification` row
+2. If null → queries all active `UserEmployee` records in org → one `UserNotification` per user
+3. After save, publishes `NotificationDto` to each user's subscription topic via `INotificationEventSender`
+
+## Infrastructure
+
+- `NotificationConfiguration` — EF Core config: title max length, indexes on `OrganizationId`, composite index on `(OrganizationId, Created DESC)` for paging
+- `UserNotificationConfiguration` — indexes on `UserId`, `NotificationId`, composite on `(UserId, IsRead)`
+- `NotificationEventSender` — uses HotChocolate `ITopicEventSender` to publish to subscription topics
+- Real-time delivery: PostgreSQL `NOTIFY/LISTEN` channel (configured in `DependencyInjection`)

package/.claude/skills/cx-core/ref-entity-order-sub.md

@@ -40,6 +40,13 @@ Represents a party role (Shipper, Consignee, Carrier, etc.) on an order.
 - `attachments` — filterable collection
 - `getOrderEntityAttachments(idPropertyName, filter, orderBy, search)` — resolver
 
+### Import Behavior (Order/Import)
+
+When importing order entities via `Order/Import@1`:
+- The `contact` and `contactAddress` nested objects are excluded from direct field mapping and processed separately.
+- **ContactAddress matching** uses `ImportOrderOptions.ContactAddressMatchByFields` — scoped to organization and (when persisted) to the resolved contact. Supports Lucene filter-based matching on any ContactAddress field (e.g., `["addressLine", "postalCode"]`). If null/empty, falls back to matching by `contactAddressId` only.
+- Both contacts and contact addresses are cached per import session to prevent duplicate creation.
+
 ### EntityTypes Enum
 
 Shipper=0, Consignee=1, Carrier=2, Vendor=3, UltimateConsignee=4, NotifyParty=5, Intermediate=6, ForwardingAgent=7, DestinationAgent=8, PickupFrom=9, DeliverTo=10, DeliveryCarrier=11, ReceivedBy=12, USPPI=13

package/.claude/skills/cx-core/ref-entity-order.md

@@ -113,6 +113,7 @@ These are virtual fields that filter `orderEntities` by type:
 | `notesSummary` | `OrderNoteSummaryGqlDto` | `.totalCount` (int), `.hasAny` (bool) — batched DataLoader, backed by DB view |
 | `notesCount(threadFilter)` | `int` | |
 | `changeHistory(startDate, endDate, maxResults)` | `[ChangeHistory]` | Audit trail |
+| `getCommoditiesWithRelatedOrder(orderType!, filter?)` | `[Commodity]` | Leaf commodities linked to related orders of specified type. Traverses commodity hierarchy, excludes wrappers. |
 
 ## OrderTypes Enum
 

package/.claude/skills/cx-core/ref-entity-shared.md

@@ -154,3 +154,23 @@ No customValues. Linked to carriers via `CarrierEquipment` join.
 | `isDeleted` | `bool` | Soft delete |
 
 **Navigation:** `thread` (NoteThread)
+
+---
+
+## Secret
+
+Encrypted key-value store for sensitive configuration (API keys, tokens, credentials). Encrypted at rest with AES-256; scoped to organizations via qualified naming.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | `int` | PK |
+| `secretName` | `string` | Qualified name: `org/{organizationId}/{secretName}`. Unique index. Max 500 chars. |
+| `encryptedValue` | `string` | AES-256 encrypted, base64-encoded (random IV prepended) |
+| `createdAt` | `DateTime` | |
+| `updatedAt` | `DateTime` | |
+
+**Table:** `secrets` (snake_case columns)
+**Provider:** `PostgresSecretManager` (default) or `AzureKeyVault` via `SecretManager:Provider` config.
+
+**GraphQL mutations:** `setSecret(organizationId, secretName, secretValue)`, `deleteSecret(organizationId, secretName)`.
+**Org scoping:** Commands validate user org membership; qualified name `org/{orgId}/{name}` is built by the command handler.

package/.claude/skills/cx-module/ref-components-forms.md

@@ -162,6 +162,7 @@ Polymorphic form field — renders different input types based on `type` prop.
 | `quill` | Rich text editor (Quill) |
 | `object` | JSON object editor |
 | `yaml` | YAML editor |
+| `secret` | Encrypted secret input — stores `${secret:qualifiedName}` reference. Requires `secretPath` prop for naming. |
 
 **Select/Async options (under `options`):**
 | Prop | Type | Description |

package/.claude/skills/cx-workflow/SKILL.md

@@ -279,13 +279,13 @@ Implicit variable: `iteration` (zero-based).
 
 | Category | Tasks | Load Reference |
 |----------|-------|----------------|
-| Utilities | SetVariable, Log, Error, HttpRequest, Map, Template, Import, Export, CsvParse | `!cat .claude/skills/cx-workflow/ref-utilities.md` |
+| Utilities | SetVariable, Log, Error, HttpRequest, Map, Template, Import, Export, CsvParse, UnzipFile | `!cat .claude/skills/cx-workflow/ref-utilities.md` |
 | Query & Workflow | Query/GraphQL, Validation, Workflow/Execute | `!cat .claude/skills/cx-workflow/ref-query.md` |
-| Entity CRUD | Order, Contact, Commodity, Job, Charge, Discount, Inventory, Movement | `!cat .claude/skills/cx-workflow/ref-entity.md` |
+| Entity CRUD | Order, Contact, Commodity, Job, Charge, Discount, Inventory, Movement, Transmission | `!cat .claude/skills/cx-workflow/ref-entity.md` |
 | Communication | Email/Send, Document/Render, Attachment, PdfDocument/Merge | `!cat .claude/skills/cx-workflow/ref-communication.md` |
 | File Transfer | Connect, Disconnect, ListFiles, Download, Upload, Move, Delete | `!cat .claude/skills/cx-workflow/ref-filetransfer.md` |
 | Accounting | AccountingTransaction, Payment, Number/Generate, SequenceNumber | `!cat .claude/skills/cx-workflow/ref-accounting.md` |
-| Other | User, Auth, Caching, EDI, Flow/Transition, Notes, AppModule, ActionEvent | `!cat .claude/skills/cx-workflow/ref-other.md` |
+| Other | User, Auth, Caching, X12/Parse, EDIFACT, Flow/Transition, Notes, AppModule, ActionEvent | `!cat .claude/skills/cx-workflow/ref-other.md` |
 
 ## Entity Field Reference (cx-core)
 

package/.claude/skills/cx-workflow/ref-entity.md

@@ -102,6 +102,8 @@ Input priority: `stream` > `fileUrl` > `postalCodes`. Task catches exceptions an
       notes: "Updated by workflow"
 ```
 
+**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).
+
 ## Contact
 
 | Task | Description |
@@ -273,6 +275,66 @@ Output `result`: `{ added, updated, skipped, failed, total, errors[] }`.
 | `Note/Export` | Export notes for an entity |
 | `Note/RenameThread` | Rename a note thread |
 
+## Transmission
+
+| Task | Description |
+|------|-------------|
+| `Transmission/Create` | Create transmission record linked to orders |
+| `Transmission/Update` | Update transmission fields (dynamic) |
+| `Transmission/Delete` | Delete transmission record |
+
+Records inbound/outbound message transmissions (EDI, API, Email, Webhook) linked to orders.
+
+```yaml
+- task: "Transmission/Create@1"
+  name: CreateTransmission
+  inputs:
+    organizationId: "{{ int organizationId }}"
+    transmission:
+      orderIds: "{{ orderIds }}"
+      channel: "EDI"
+      direction: "Outbound"
+      messageType: "214"
+      sender: "{{ senderISA }}"
+      receiver: "{{ receiverISA }}"
+      status: "Pending"
+      endpoint: "{{ endpoint }}"
+      protocol: "SFTP"
+  outputs:
+    - name: transmission
+      mapping: "transmission"
+```
+
+```yaml
+- task: "Transmission/Update@1"
+  name: UpdateTransmission
+  inputs:
+    organizationId: "{{ int organizationId }}"
+    transmissionId: "{{ int Main?.CreateTransmission?.transmission?.id? }}"
+    transmission:
+      status: "Sent"
+      completedAt: "{{ now() }}"
+```
+
+```yaml
+- task: "Transmission/Delete@1"
+  name: DeleteTransmission
+  inputs:
+    organizationId: "{{ int organizationId }}"
+    transmissionId: "{{ int inputs.transmissionId }}"
+  outputs:
+    - name: success
+      mapping: "success"
+```
+
+**Create inputs:** `organizationId` (int, required), `transmission` object — `orderIds` (required, at least one), `channel`, `direction` (Inbound/Outbound), `messageType`, `sender`, `receiver`, `status`, `endpoint`, `protocol`, `correlationId` (auto-generated if omitted), `parentId`, `httpStatus`, `byteSize`, `retryCount`, `maxRetries`, `nextRetryAt`, `errorCode`, `errorMessage`, `customValues`, `headers`, `payloadRef`, `scheduledAt`, `startedAt`, `completedAt`, `durationMs`.
+
+**Create outputs:** `transmission` (full TransmissionDto).
+**Update inputs:** `organizationId`, `transmissionId`, `transmission` (dynamic partial fields).
+**Delete outputs:** `success` (boolean).
+
+**Status enum:** Pending, InProgress, Sent, Received, Delivered, Acknowledged, Rejected, Error, RetryScheduled, Cancelled, Expired, Accepted.
+
 ## Accounting Transaction (Additional)
 
 | Task | Description |

package/.claude/skills/cx-workflow/ref-expressions-ncalc.md

@@ -98,6 +98,22 @@ Functions use two iterator variable names:
 | `dateToUtc([date])` or `dateToUtc([date], 'en-US')` | Convert to UTC. Optional culture for string parsing |
 | `toLocalTime([date], 'America/Chicago')` | Convert UTC datetime to local time in IANA timezone. Returns `null` if date or timezone is invalid |
 
+### Business Date Math (in Lucene filter expressions)
+
+The filter engine (`FilterBy`) supports business-aware date math units in Lucene date expressions:
+
+| Unit | Aliases | Description |
+|------|---------|-------------|
+| `BHOUR` | `BHOURS` | Add/subtract business hours (respects weekly schedule + holidays) |
+| `BDAY` | `BDAYS` | Add/subtract business days (skips non-working days) |
+
+**Usage**: These units are used in **Lucene filter strings** (not NCalc expressions). They require an `IBusinessDateMathResolver` and are resolved via the organization's business calendar.
+
+```
+dueDate: [NOW TO NOW+3BDAYS]
+pickupDate: [* TO NOW-8BHOURS]
+```
+
 ### Math Functions (NCalc built-in)
 
 `Abs(x)`, `Ceiling(x)`, `Floor(x)`, `Round(x, decimals)`, `Min(x, y)`, `Max(x, y)`, `Pow(x, y)`, `Sqrt(x)`, `Truncate(x)`

package/.claude/skills/cx-workflow/ref-expressions-template.md

@@ -106,6 +106,16 @@ orderData:
     notes: "{{ newNotes }}"
 ```
 
+**`resolve`** -- Entity ID lookup by querying a GraphQL collection:
+```yaml
+customerId:
+  resolve:
+    entity: "Contact"                        # Entity type (auto-pluralized for query)
+    filter: "name:{{ customerName }}"         # Lucene filter (template-parsed)
+    field: "contactId"                       # Field to return (default: <entity>Id)
+```
+Results are batched and cached per unique `entity|filter|field` combination by `ResolvePreProcessor` before step execution. Cache misses return `null`. Useful inside `foreach` mappings where many items reference the same entity — only one query per unique filter value.
+
 **`$raw`** -- Prevent template parsing (pass as-is):
 ```yaml
 template:

package/.claude/skills/cx-workflow/ref-flow.md

@@ -152,10 +152,11 @@ transitions:
 
 ### Execution Order
 1. Validate transition from current state
-2. Execute `onExit` steps (from source state)
-3. Execute transition `steps`
-4. Update entity status
-5. Execute `onEnter` steps (on target state)
+2. Evaluate conditions (all must pass)
+3. Execute `onExit` steps (from source state)
+4. Execute transition `steps` (step inputs merged + template expressions resolved)
+5. Update entity status
+6. Execute `onEnter` steps (on target state)
 
 ## Aggregations Section
 

package/.claude/skills/cx-workflow/ref-other.md

@@ -64,20 +64,48 @@
 
 | Task | Description |
 |------|-------------|
-| `EDI/Parse` | Parse EDI documents (X12, EDIFACT) |
+| `X12/Parse` | Parse X12 EDI documents (850, 856) |
+| `EDIFACT/Parse` | Parse EDIFACT messages (IFTMIN) |
+| `EDIFACT/Generate` | Generate EDIFACT messages (IFTMIN) |
+| `EDI/Parse` | **Deprecated** — alias for X12/Parse, use `X12/Parse` instead |
 | `StructuredFile/Parse` | Parse structured files |
 
 ```yaml
-- task: "EDI/Parse@1"
-  name: ParseEdi
+- task: "X12/Parse@1"
+  name: ParseX12
   inputs:
-    content: "{{ Transfer.Download.content }}"
-    format: "X12"
+    ediData: "{{ Transfer.Download.content }}"
+    transactionSet: "850"
+    validateSchema: true
   outputs:
     - name: parsed
       mapping: "document"
 ```
 
+```yaml
+- task: "EDIFACT/Parse@1"
+  name: ParseEdifact
+  inputs:
+    edifactData: "{{ Transfer.Download.content }}"
+    messageType: "IFTMIN"
+  outputs:
+    - name: parsed
+      mapping: "document"
+```
+
+```yaml
+- task: "EDIFACT/Generate@1"
+  name: GenerateEdifact
+  inputs:
+    messageType: "IFTMIN"
+    data: "{{ shipmentData }}"
+  outputs:
+    - name: edifactData
+      mapping: "edifactData"
+    - name: messageType
+      mapping: "messageType"
+```
+
 ## Flow
 
 | Task | Description |

package/.claude/skills/cx-workflow/ref-utilities.md

@@ -1,17 +1,5 @@
 # Utilities Tasks Reference
 
-## Contents
-- Available utility tasks (summary table of all Utilities/* tasks)
-- SetVariable task (set variables in activity and global scope)
-- Log task (log variables and messages to workflow logger)
-- Error task (throw workflow error to halt execution)
-- HttpRequest task (HTTP calls to external APIs with action events)
-- Map task (extract and reshape data into new variables)
-- Template task (Handlebars template rendering)
-- CsvParse task (parse CSV content into structured data)
-- Export task (export data to file format)
-- Import task (import data from file content)
-
 ## Available Tasks
 
 | Task | Description |
@@ -28,8 +16,64 @@
 | `Utilities/MoveFile@1` | Move file |
 | `Utilities/ValidateReCaptcha` | Validate reCAPTCHA |
 | `Utilities/ValidateHMAC` | Validate HMAC signatures |
+| `Utilities/UnzipFile@1` | Extract files from ZIP archive (local path or URL) |
 | `Utilities/ResolveTimezone@1` | Resolve IANA timezone and UTC offset from lat/lng coordinates |
 
+## UnzipFile@1
+
+Extracts files from a ZIP archive. Accepts a local file path (from `saveToFile` or previous step) or a URL (`file://`, `http://`, `https://`). Files are extracted to a workflow-scoped temp directory with auto-cleanup.
+
+```yaml
+- task: "Utilities/UnzipFile@1"
+  name: ExtractArchive
+  inputs:
+    filePath: "{{ Main?.DownloadArchive?.result?.FilePath? }}"
+    filePattern: "*.csv"
+  outputs:
+    - name: files
+      mapping: "Files?"
+    - name: count
+      mapping: "Count?"
+```
+
+**Inputs:** `filePath` (string, local path) OR `fileUrl` (string, URL — `file://`, `http://`, `https://`). Optional: `filePattern` (glob pattern, e.g. `*.csv`, `data_*.json`).
+**Outputs:** `Files` (string[] — full paths to extracted files), `Count` (int — number of matched files).
+Provide one of `filePath` or `fileUrl`. Common pattern: HttpRequest with `saveToFile: true` → UnzipFile with `filePath`.
+
+```yaml
+# Download + unzip + import pipeline
+- task: "Utilities/HttpRequest@1"
+  name: Download
+  inputs:
+    url: "{{ downloadUrl }}"
+    method: GET
+    saveToFile: true
+  outputs:
+    - name: result
+      mapping: "response?"
+
+- task: "Utilities/UnzipFile@1"
+  name: Unzip
+  inputs:
+    filePath: "{{ Main?.Download?.result?.FilePath? }}"
+    filePattern: "*.csv"
+  outputs:
+    - name: files
+      mapping: "Files?"
+
+- task: foreach
+  name: ProcessFiles
+  collection: "Main?.Unzip?.files?"
+  steps:
+    - task: "Utilities/Import@1"
+      name: ImportFile
+      inputs:
+        fileUrl: "file://{{ item }}"
+        format: "csv"
+```
+
+---
+
 ## ResolveTimezone@1
 
 Resolves IANA timezone ID and current UTC offset from geographic coordinates using offline boundary lookup (GeoTimeZone).
@@ -127,6 +171,21 @@ Performs HTTP requests to external APIs.
 
 Response available at `ActivityName?.CallApi?.result?`.
 
+**`saveToFile` mode**: When `saveToFile: true`, the response body is saved to a temp file instead of being returned in memory. The response object changes to `{ StatusCode, Headers, FilePath }`. Use this for large file downloads, then pass `FilePath` to downstream tasks like `UnzipFile` or `Import`.
+
+```yaml
+- task: "Utilities/HttpRequest@1"
+  name: DownloadArchive
+  inputs:
+    url: "{{ downloadUrl }}"
+    method: GET
+    saveToFile: true
+  outputs:
+    - name: result
+      mapping: "response?"
+# result.FilePath contains the temp file path
+```
+
 **Action events**: When an HTTP request operates on a specific entity (e.g., sending parcel info for an order), enable `actionEvents` in the inputs so the system can track and notify about the request. Include `eventDataExt` with the entity ID to link the event to the entity.
 
 ```yaml
@@ -183,7 +242,7 @@ Renders a Handlebars template string with data.
 
 ## CsvParse@1
 
-Parses CSV content into structured data.
+Parses CSV content into structured data. CSV headers are automatically trimmed of whitespace, BOM characters, and other special characters to ensure reliable column matching.
 
 ```yaml
 - task: "Utilities/CsvParse@1"
@@ -214,7 +273,7 @@ Exports data to file format.
 
 ## Import@1
 
-Imports data from file content.
+Imports data from file content or URL. Supports `file://` URLs for local files (e.g. from UnzipFile output).
 
 ```yaml
 - task: "Utilities/Import@1"
@@ -226,3 +285,17 @@ Imports data from file content.
     - name: data
       mapping: "data?"
 ```
+
+```yaml
+# Import from local file (e.g. extracted from ZIP)
+- task: "Utilities/Import@1"
+  name: ImportLocalFile
+  inputs:
+    fileUrl: "file://{{ localFilePath }}"
+    format: "csv"
+  outputs:
+    - name: data
+      mapping: "data?"
+```
+
+**`file://` URL support**: Import, Order/Import, PostalCodes/Import, and Notes/Import all accept `file://` URLs via UrlStreamHelper. This enables pipeline patterns: HttpRequest (saveToFile) → UnzipFile → Import (file://).

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@cxtms/cx-schema",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "description": "Schema validation package for CargoXplorer YAML modules",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "cx-cli": "dist/cli.js",
-    "cxtms": "dist/cli.js"
+    "cx-cli": "dist/cli.js"
   },
   "scripts": {
     "build": "tsc",

package/schemas/actions/all.json

@@ -21,6 +21,7 @@
     { "$ref": "if.json" },
     { "$ref": "consoleLog.json" },
     { "$ref": "openBarcodeScanner.json" },
-    { "$ref": "resetDirtyState.json" }
+    { "$ref": "resetDirtyState.json" },
+    { "$ref": "clipboard.json" }
   ]
 }

package/schemas/actions/clipboard.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "clipboard Action",
+  "type": "object",
+  "properties": {
+    "clipboard": {
+      "type": "object",
+      "properties": {
+        "data": {
+          "description": "Data to copy — string, object, array, or template expression."
+        },
+        "path": {
+          "type": "string",
+          "description": "Dot-notation path to extract from each array item or single object."
+        },
+        "template": {
+          "type": "string",
+          "description": "Per-item template string with {{ }} expressions. Takes precedence over path."
+        },
+        "format": {
+          "type": "string",
+          "enum": ["lines", "json", "csv"],
+          "description": "Output format for arrays. Default: lines."
+        },
+        "separator": {
+          "type": "string",
+          "description": "Separator between items when format is lines. Default: newline."
+        },
+        "message": {
+          "oneOf": [
+            { "type": "string" },
+            { "$ref": "../schemas.json#/definitions/localized" }
+          ],
+          "description": "Custom success notification message."
+        }
+      },
+      "required": ["data"],
+      "x-examples": [
+        { "data": "{{ selectedRows }}", "path": "trackingNumber" },
+        { "data": "{{ selectedRows }}", "template": "{{ trackingNumber }}{{ eval (customValues?.spot ? 'S' : '') }}", "message": "Copied!" },
+        { "data": "{{ selectedRows }}", "format": "json" }
+      ]
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/workflows/flow/entity.json

@@ -92,6 +92,21 @@
           }
         }
       }
+    },
+    {
+      "if": {
+        "properties": {
+          "name": { "const": "Commodity" }
+        }
+      },
+      "then": {
+        "properties": {
+          "type": {
+            "type": "string",
+            "description": "CommodityType code. Optional — if omitted, the flow applies to all commodity types."
+          }
+        }
+      }
     }
   ],
   "additionalProperties": false,
@@ -105,6 +120,10 @@
     {
       "name": "Contact",
       "type": "Customer"
+    },
+    {
+      "name": "Commodity",
+      "includes": ["commodityStatus", "commodityEvents.trackingEvent.eventDefinition"]
     }
   ]
 }

package/schemas/workflows/tasks/all.json

@@ -118,9 +118,18 @@
     {
       "$ref": "template.json"
     },
+    {
+      "$ref": "resolve-timezone.json"
+    },
+    {
+      "$ref": "unzip-file.json"
+    },
     {
       "$ref": "tracking-event.json"
     },
+    {
+      "$ref": "transmission.json"
+    },
     {
       "$ref": "user.json"
     },

package/schemas/workflows/tasks/edi.json

@@ -8,6 +8,8 @@
       "type": "string",
       "enum": [
         "EDI/Parse@1",
+        "EDIFACT/Parse@1",
+        "EDIFACT/Generate@1",
         "StructuredFile/Parse"
       ],
       "description": "Task type identifier"
@@ -39,11 +41,101 @@
       "properties": {
         "content": {
           "type": "string",
-          "description": "File content to parse"
+          "description": "File content to parse (EDI/Parse)"
         },
         "format": {
           "type": "string",
           "description": "EDI format (e.g., X12, EDIFACT)"
+        },
+        "edifactData": {
+          "type": "string",
+          "description": "Raw EDIFACT data string (EDIFACT/Parse, EDIFACT/Generate)"
+        },
+        "messageType": {
+          "type": "string",
+          "enum": ["IFTMIN", "CONTRL", "APERAK"],
+          "description": "EDIFACT message type for parse/generate tasks"
+        },
+        "sender": {
+          "type": "object",
+          "description": "Sender identification for EDIFACT/Generate",
+          "properties": {
+            "id": { "type": "string", "description": "Sender ID (Trading Partner ID)" },
+            "qualifier": { "type": "string", "description": "Partner ID code qualifier (e.g., ZZZ)" }
+          }
+        },
+        "recipient": {
+          "type": "object",
+          "description": "Recipient identification for EDIFACT/Generate",
+          "properties": {
+            "id": { "type": "string", "description": "Recipient ID (e.g., INTTRA)" },
+            "qualifier": { "type": "string", "description": "Partner ID code qualifier" }
+          }
+        },
+        "documentNumber": {
+          "type": "string",
+          "description": "Shipment Identification Number"
+        },
+        "messageFunctionCode": {
+          "type": "string",
+          "enum": ["5", "9"],
+          "description": "9 = Original, 5 = Replace"
+        },
+        "references": {
+          "type": "array",
+          "description": "Business references (BN=Booking, BM=B/L, etc.)",
+          "items": {
+            "type": "object",
+            "properties": {
+              "qualifier": { "type": "string" },
+              "identifier": { "type": "string" }
+            }
+          }
+        },
+        "parties": {
+          "type": "array",
+          "description": "Party details (HI=Requestor, CZ=Shipper, CA=Carrier, CN=Consignee)",
+          "items": {
+            "type": "object",
+            "properties": {
+              "functionCode": { "type": "string" },
+              "identification": { "type": "string" },
+              "name": { "type": "string" }
+            }
+          }
+        },
+        "goodsItems": {
+          "type": "array",
+          "description": "Goods item details (GID segment group). Numeric fields (itemNumber, numberOfPackages) are serialized as strings.",
+          "items": {
+            "type": "object",
+            "properties": {
+              "itemNumber": { "type": ["integer", "string"], "description": "Goods item number (GID/0). Auto-incremented." },
+              "numberOfPackages": { "type": ["integer", "string"], "description": "Number of outer packages (C213/7224)" },
+              "packageType": { "type": "string", "description": "Package type code, UN/ECE rec. 21 (C213/7065, e.g. CT, PK, PL)" },
+              "packageTypeDescription": { "type": "string", "description": "Package type description (C213/7065 text)" },
+              "packageTypeAgencyCode": { "type": "string", "description": "Code list responsible agency (C213/3055). Auto-set to '6' (UN/ECE) when packageType is provided." },
+              "packageTypeDescriptionText": { "type": "string", "description": "Package type description text for B/L printing (C213/7064)" },
+              "innerPackageCount": { "type": ["integer", "string"], "description": "Number of inner packages (second C213/7224)" },
+              "innerPackageType": { "type": "string", "description": "Inner package type code (second C213/7065)" },
+              "grossWeight": { "type": ["number", "string"], "description": "Gross weight value" },
+              "weightUnit": { "type": "string", "description": "Weight unit (KGM, LBR)" },
+              "description": { "type": "string", "description": "Goods description free text" }
+            }
+          }
+        },
+        "equipment": {
+          "type": "array",
+          "description": "Container/equipment details",
+          "items": {
+            "type": "object",
+            "properties": {
+              "equipmentQualifier": { "type": "string" },
+              "equipmentIdentification": { "type": "string" },
+              "sizeTypeCode": { "type": "string" },
+              "fullEmptyIndicator": { "type": "string" }
+            }
+          }
         }
       },
       "additionalProperties": true

package/schemas/workflows/tasks/httpRequest.json

@@ -105,6 +105,10 @@
             }
           }
         },
+        "saveToFile": {
+          "type": "boolean",
+          "description": "When true, saves response body to a temp file instead of returning it in memory. Response returns { StatusCode, Headers, FilePath } instead of body content."
+        },
         "cache": {
           "type": "object",
           "properties": {

package/schemas/workflows/tasks/order.json

@@ -69,6 +69,51 @@
         "validateOnly": {
           "type": "boolean",
           "description": "Only validate, don't persist"
+        },
+        "data": {
+          "description": "Structured import data (for Order/Import@1)",
+          "additionalProperties": true
+        },
+        "options": {
+          "type": "object",
+          "description": "Import options (for Order/Import@1)",
+          "properties": {
+            "orderMatchByFields": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Fields to match existing orders. If null, creates new orders."
+            },
+            "contactMatchByFields": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Fields to match existing contacts for order entities."
+            },
+            "contactAddressMatchByFields": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Fields to match existing contact addresses within order entities."
+            },
+            "inventoryItemMatchByFields": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Fields to match existing inventory items on commodities."
+            },
+            "tagMatchByFields": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Fields to match existing tags."
+            },
+            "commodityMatchByFields": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Fields to match existing commodities."
+            },
+            "linkTrackingEventsToCommodities": {
+              "type": "boolean",
+              "description": "When true, imported tracking events are linked to the order's first-level (non-container) commodities. Default: false."
+            }
+          },
+          "additionalProperties": true
         }
       },
       "additionalProperties": true

package/schemas/workflows/tasks/resolve-timezone.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ResolveTimezone Task",
+  "description": "Resolve IANA timezone ID and UTC offset from geographic coordinates",
+  "type": "object",
+  "properties": {
+    "task": {
+      "type": "string",
+      "enum": ["Utilities/ResolveTimezone@1"],
+      "description": "Task type identifier"
+    },
+    "name": {
+      "type": "string",
+      "description": "Step name identifier"
+    },
+    "description": {
+      "type": "string",
+      "description": "Step description"
+    },
+    "conditions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "expression": {
+            "type": "string"
+          }
+        },
+        "required": ["expression"]
+      }
+    },
+    "continueOnError": {
+      "type": "boolean"
+    },
+    "inputs": {
+      "type": "object",
+      "description": "ResolveTimezone inputs",
+      "properties": {
+        "latitude": {
+          "type": ["string", "number"],
+          "description": "Latitude coordinate (decimal degrees)"
+        },
+        "longitude": {
+          "type": ["string", "number"],
+          "description": "Longitude coordinate (decimal degrees)"
+        }
+      },
+      "required": ["latitude", "longitude"],
+      "additionalProperties": true
+    },
+    "outputs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "mapping": { "type": "string" }
+        },
+        "required": ["name", "mapping"]
+      },
+      "description": "Outputs: timezoneId (IANA timezone string, e.g. 'America/Chicago'), utcOffset (number, hours from UTC, e.g. -5)"
+    }
+  },
+  "required": ["task", "name", "inputs"]
+}

package/schemas/workflows/tasks/transmission.json

@@ -93,7 +93,7 @@
             },
             "status": {
               "type": ["string", "integer"],
-              "enum": ["Pending", "InProgress", "Sent", "Received", "Delivered", "Acknowledged", "Rejected", "Error", "RetryScheduled", "Cancelled", "Expired", 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+              "enum": ["Pending", "InProgress", "Sent", "Received", "Delivered", "Acknowledged", "Rejected", "Error", "RetryScheduled", "Cancelled", "Expired", "Accepted", 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11],
               "description": "Transmission status"
             },
             "endpoint": {

package/schemas/workflows/tasks/unzip-file.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "UnzipFile Task",
+  "description": "Extract files from a ZIP archive (local path or URL)",
+  "type": "object",
+  "properties": {
+    "task": {
+      "type": "string",
+      "enum": ["Utilities/UnzipFile@1"],
+      "description": "Task type identifier"
+    },
+    "name": {
+      "type": "string",
+      "description": "Step name identifier"
+    },
+    "description": {
+      "type": "string",
+      "description": "Step description"
+    },
+    "conditions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "expression": {
+            "type": "string"
+          }
+        },
+        "required": ["expression"]
+      }
+    },
+    "continueOnError": {
+      "type": "boolean"
+    },
+    "inputs": {
+      "type": "object",
+      "description": "UnzipFile inputs — provide either filePath or fileUrl",
+      "properties": {
+        "filePath": {
+          "type": "string",
+          "description": "Local file path to ZIP archive (from saveToFile or previous step)"
+        },
+        "fileUrl": {
+          "type": "string",
+          "description": "URL to ZIP archive (file://, http://, https://)"
+        },
+        "filePattern": {
+          "type": "string",
+          "description": "Glob-style pattern to filter extracted files (e.g. '*.csv', 'data_*.json'). If omitted, all files returned."
+        }
+      },
+      "additionalProperties": true
+    },
+    "outputs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "mapping": { "type": "string" }
+        },
+        "required": ["name", "mapping"]
+      },
+      "description": "Outputs: Files (string[] — full paths to extracted files), Count (int — number of matched files)"
+    }
+  },
+  "required": ["task", "name", "inputs"]
+}

package/schemas/workflows/variable.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Workflow Variable",
-  "description": "Definition of a workflow variable. Valid properties: name, value, fromConfig.",
+  "description": "Definition of a workflow variable. Valid properties: name, value, fromConfig, expression.",
   "type": "object",
   "properties": {
     "name": {
@@ -12,6 +12,10 @@
     "value": {
       "description": "Static variable value or template expression"
     },
+    "expression": {
+      "type": "string",
+      "description": "NCalc expression to evaluate at runtime. Has access to all previously resolved variables. Mutually exclusive with value and fromConfig."
+    },
     "fromConfig": {
       "oneOf": [
         {