cxtms 1.9.13

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

@@ -0,0 +1,80 @@
+# File Transfer Tasks Reference
+
+SFTP/FTP file transfer operations. Use `FileTransfer/Connect` to establish a session, perform file operations, then `FileTransfer/Disconnect`.
+
+## Connection Lifecycle
+
+```yaml
+activities:
+  - name: Transfer
+    steps:
+      - task: "FileTransfer/Connect@1"
+        name: Connect
+        inputs:
+          host: "{{ sftpConfig.host }}"
+          port: "{{ sftpConfig.port }}"
+          username: "{{ sftpConfig.username }}"
+          password: "{{ sftpConfig.password }}"
+          protocol: "sftp"
+        outputs:
+          - name: connection
+            mapping: "connection"
+
+      - task: "FileTransfer/ListFiles@1"
+        name: ListFiles
+        inputs:
+          connection: "{{ Transfer.Connect.connection }}"
+          path: "/incoming"
+        outputs:
+          - name: files
+            mapping: "files"
+
+      - task: foreach
+        name: ProcessFiles
+        collection: "Transfer.ListFiles.files"
+        item: "file"
+        steps:
+          - task: "FileTransfer/DownloadFile@1"
+            name: Download
+            inputs:
+              connection: "{{ Transfer.Connect.connection }}"
+              path: "{{ file.path }}"
+            outputs:
+              - name: content
+                mapping: "content"
+
+          - task: "FileTransfer/MoveFile@1"
+            name: Archive
+            inputs:
+              connection: "{{ Transfer.Connect.connection }}"
+              sourcePath: "{{ file.path }}"
+              destinationPath: "/processed/{{ file.name }}"
+
+      - task: "FileTransfer/Disconnect@1"
+        name: Disconnect
+        inputs:
+          connection: "{{ Transfer.Connect.connection }}"
+```
+
+## Available Tasks
+
+| Task | Description |
+|------|-------------|
+| `FileTransfer/Connect` | Establish SFTP/FTP connection |
+| `FileTransfer/Disconnect` | Close connection |
+| `FileTransfer/ListFiles` | List files in remote directory |
+| `FileTransfer/DownloadFile` | Download file content |
+| `FileTransfer/UploadFile` | Upload file to remote |
+| `FileTransfer/MoveFile` | Move/rename remote file |
+| `FileTransfer/DeleteFile` | Delete remote file |
+
+## Upload Example
+
+```yaml
+- task: "FileTransfer/UploadFile@1"
+  name: Upload
+  inputs:
+    connection: "{{ Transfer.Connect.connection }}"
+    path: "/outgoing/report.csv"
+    content: "{{ GenerateReport.Export.file }}"
+```

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

@@ -0,0 +1,210 @@
+# Flow Workflow YAML Reference
+
+## Contents
+- Flow top-level structure (workflowType, entity, states, transitions, aggregations)
+- Flow entity section (entity name, type, includes, query)
+- Flow states section (initial, final, parent hierarchy, onEnter/onExit steps)
+- Flow transitions section (manual, auto, event triggers; from/to states; conditions)
+- Flow aggregations section (reusable collection expressions: all, any, sum, count)
+
+Flow workflows are declarative state machines for entity lifecycle management. Use `workflowType: Flow` in the workflow section.
+
+## Top-Level Structure
+
+```yaml
+workflow:
+  workflowId: "<uuid>"
+  name: "Flow Workflow Name"
+  workflowType: Flow                        # Required - identifies this as a Flow workflow
+  executionMode: Async
+  isActive: true
+  priority: 75                              # 0-100, default 50
+  tags: ["tag1"]
+  agentInstruction: "AI guidance"           # Optional
+  concurrency:
+    enabled: true
+    group: "groupName"
+    waitTime: 30
+
+entity:                                     # Required for Flow (replaces activities)
+  name: <EntityName>
+  type: <EntityType>                        # Required for Order, AccountingTransaction, Contact
+  includes: [<navigation-paths>]            # Optional
+  query: "<graphql-query>"                  # Optional
+
+states: [...]                               # Required, at least 1 state
+transitions: [...]                          # Required, at least 1 transition
+aggregations: [...]                         # Optional
+```
+
+## Entity Section
+
+Specifies which entity's lifecycle this flow manages.
+
+### Valid Entity Names
+Order, Commodity, AccountingTransaction, Workflow, OrganizationConfig, Contact, AppModule, Attachment, OrderCommodity, TrackingEvent, JobOrder
+
+### Entity Types (required for specific entities)
+
+**Order** requires type: Brokerage, ParcelShipment, Quote, WarehouseReceipt, AirShipmentOrder, OceanShipmentOrder, LoadOrder, DeliveryOrder
+**AccountingTransaction** requires type: Invoice, Bill, CreditMemo
+**Contact** requires type: Customer, Carrier, Vendor, Driver, Employee
+
+```yaml
+entity:
+  name: Order
+  type: ParcelShipment
+  includes:
+    - Commodities
+    - Customer
+    - Charges
+  query: "{ commodities { id, quantity }, customer { name, email } }"
+```
+
+## States Section
+
+Each state represents a status in the entity lifecycle.
+
+```yaml
+states:
+  - name: Draft                             # Required, unique
+    stage: Entry                            # Optional grouping label
+    isInitial: true                         # At most 1 initial state
+  - name: Active
+    stage: Processing
+  - name: AwaitingPickup
+    parent: Active                          # Hierarchical state
+  - name: InTransit
+    parent: Active
+    onEnter:                                # Steps on entering this state
+      - task: "Email/Send"
+        inputs:
+          template: in_transit_notification
+    onExit:                                 # Steps on exiting this state
+      - task: "Utilities/Log@1"
+        inputs:
+          message: "Leaving InTransit"
+  - name: Delivered
+    stage: Complete
+    isFinal: true                           # Terminal state, no outgoing transitions
+    requireConfirmation: true               # User must confirm before entering
+    query: "{ charges { id, amount } }"     # State-specific data query
+```
+
+### State Rules
+- **name**: Required, must be unique across all states
+- **isInitial**: At most one state can be initial. When an entity has null status, the engine resolves it to the initial state automatically.
+- **isFinal**: Final states cannot be transition sources
+- **parent**: References another state; parent cannot be initial or final; children inherit parent transitions
+
+## Transitions Section
+
+Define how entities move between states.
+
+```yaml
+transitions:
+  - name: submit                            # Required, unique
+    displayName: "Submit Order"             # Optional UI label
+    from: Draft                             # Single state
+    to: Submitted                           # Must be a leaf state (no children)
+    trigger: manual                         # manual | auto | event
+
+  - name: auto_approve
+    from: Submitted
+    to: Approved
+    trigger: auto                           # Evaluated automatically
+    priority: 10                            # Higher = checked first (default 50)
+    conditions:
+      - expression: "Order.Amount < 1000"
+
+  - name: payment_received
+    from: AwaitingPayment
+    to: Paid
+    trigger: event                          # External event-driven
+    eventName: PaymentConfirmed             # Required when trigger is 'event'
+
+  - name: bulk_transition
+    from:                                   # Array of source states
+      - Draft
+      - Submitted
+    to: Cancelled
+    trigger: manual
+
+  - name: force_cancel
+    from: "*"                               # Wildcard: any non-final state
+    to: Cancelled
+    trigger: manual
+    steps:                                  # Steps during transition
+      - task: "Utilities/Log@1"
+        inputs:
+          message: "Force cancelled"
+```
+
+### Trigger Types
+- **manual**: User-initiated or API call
+- **auto**: Automatic evaluation based on conditions; sorted by priority descending
+- **event**: External event-driven; requires `eventName`
+
+### Auto-Transitions and Cross-Entity Support
+
+Auto-transitions can fire on related entities. For example, an Order status change can trigger a Commodity flow transition via the `OrderCommodities` join table.
+
+```yaml
+states:
+  - name: Pending
+    autoTransitions:
+      - to: InTransit
+        trigger:
+          entityType: Order
+          event: StatusChanged
+        conditions:
+          - "order.orderStatusName == 'Shipped'"
+        priority: 1
+```
+
+**Cross-entity resolution:**
+| Triggering Entity | Flow Entity | Resolution |
+|-------------------|-------------|------------|
+| Order | Commodity | Via `OrderCommodities` join table |
+
+### From States
+- Single state: `from: Draft`
+- Multiple states: `from: [Draft, Submitted]`
+- Wildcard (any non-final state): `from: "*"`
+
+### Execution Order
+1. Validate transition from current 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
+
+Reusable data queries for conditions.
+
+```yaml
+aggregations:
+  - name: allItemsReceived                  # Required, unique
+    expression: "all(Order.Commodities, item.ReceivedQuantity >= item.Quantity)"
+  - name: totalWeight
+    expression: "sum(Order.Commodities, item.Weight)"
+  - name: hasAnyDamaged
+    expression: "any(Order.Commodities, item.IsDamaged)"
+  - name: itemCount
+    expression: "count(Order.Commodities)"
+  - name: chargesByType
+    expression: "sum(Order.Charges, item.Amount)"
+    parameter: chargeType                   # Optional parameter
+```
+
+### Valid Aggregation Functions
+- **all(collection, predicate)** - All items match
+- **any(collection, predicate)** - At least one matches
+- **sum(collection, selector)** - Sum values
+- **count(collection)** - Count items
+- **first(collection)** - First item
+- **last(collection)** - Last item
+- **distinct(collection, selector)** - Unique values
+- **groupBy(collection, selector)** - Group by value

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

@@ -0,0 +1,157 @@
+# Other Tasks Reference
+
+## Contents
+- User & Auth tasks (User CRUD, verification codes, OAuth2 authentication)
+- Caching tasks (SetCache and GetCache for in-memory key-value storage)
+- EDI & Structured File Parsing tasks (EDI/Parse for X12/EDIFACT, StructuredFile/Parse)
+- Flow/Transition task (trigger state machine transitions programmatically)
+- Note tasks (Create, Update, Delete, NoteThread/Rename, bulk Import/Export)
+- AppModule tasks (Create, Update, Delete app modules)
+- ActionEvent/Create task (trigger UI notifications or webhooks)
+
+## User & Auth
+
+| Task | Description |
+|------|-------------|
+| `User/Create` | Create user account |
+| `User/Update` | Update user |
+| `User/Delete` | Delete user |
+| `User/GetVerificationCode` | Get phone verification code |
+| `User/GetEmailVerificationCode` | Get email verification code |
+| `User/GetResetPasswordToken` | Get password reset token |
+| `Authentication/OAuth2` | Execute OAuth2 authentication flow |
+
+```yaml
+- task: "Authentication/OAuth2"
+  name: Authenticate
+  inputs:
+    provider: "{{ oauthConfig.provider }}"
+    clientId: "{{ oauthConfig.clientId }}"
+    clientSecret: "{{ oauthConfig.clientSecret }}"
+    tokenUrl: "{{ oauthConfig.tokenUrl }}"
+  outputs:
+    - name: token
+      mapping: "accessToken"
+```
+
+## Caching
+
+| Task | Description |
+|------|-------------|
+| `Caching/SetCache` | Store value in in-memory cache |
+| `Caching/GetCache` | Retrieve value from cache |
+
+```yaml
+- task: "Caching/SetCache@1"
+  name: CacheRate
+  inputs:
+    key: "rate-{{ inputs.carrierId }}"
+    value: "{{ Data.GetRate.rate }}"
+    ttl: 3600
+```
+
+```yaml
+- task: "Caching/GetCache@1"
+  name: GetCachedRate
+  inputs:
+    key: "rate-{{ inputs.carrierId }}"
+  outputs:
+    - name: rate
+      mapping: "value"
+```
+
+## EDI & Structured File Parsing
+
+| Task | Description |
+|------|-------------|
+| `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: "X12/Parse@1"
+  name: ParseX12
+  inputs:
+    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 |
+|------|-------------|
+| `Flow/Transition` | Trigger a Flow state transition programmatically |
+
+```yaml
+- task: "Flow/Transition@1"
+  name: TransitionOrder
+  inputs:
+    entityName: "Order"
+    entityId: "{{ inputs.orderId }}"
+    transition: "approve"
+```
+
+## Notes
+
+| Task | Description |
+|------|-------------|
+| `Note/Create` | Create a note |
+| `Note/Update` | Update a note |
+| `Note/Delete` | Delete a note |
+| `NoteThread/Rename` | Rename note thread |
+| `Notes/Import` | Bulk import notes |
+| `Notes/Export` | Bulk export notes |
+
+## App Module
+
+| Task | Description |
+|------|-------------|
+| `AppModule/Create` | Create app module |
+| `AppModule/Update` | Update app module |
+| `AppModule/Delete` | Delete app module |
+
+## Action Events
+
+| Task | Description |
+|------|-------------|
+| `ActionEvent/Create` | Create action event (triggers UI notifications or webhook) |
+
+```yaml
+- task: "ActionEvent/Create"
+  name: NotifyUser
+  inputs:
+    eventName: "OrderStatusChanged"
+    data:
+      orderId: "{{ inputs.orderId }}"
+      newStatus: "{{ Data.GetOrder.order.status }}"
+```

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

@@ -0,0 +1,105 @@
+# Query, Validation & Workflow Tasks Reference
+
+## Query/GraphQL
+
+Executes internal GraphQL queries against the CX backend. The query runs via MediatR to the internal GraphQL engine.
+
+```yaml
+- task: "Query/GraphQL"
+  name: GetOrder
+  inputs:
+    query: |
+      query($organizationId: Int!, $orderId: Int!) {
+        order(organizationId: $organizationId, orderId: $orderId) {
+          orderId
+          orderNumber
+          status
+          customer {
+            contactId
+            name
+          }
+        }
+      }
+    variables:
+      organizationId: "{{ organizationId }}"
+      orderId: "{{ inputs.orderId }}"
+  outputs:
+    - name: order
+      mapping: "order"
+```
+
+The query result is a dictionary. The `mapping` path extracts from the result. Output stored at `ActivityName.GetOrder.order`.
+
+**Notes**:
+- `organizationId` is always available as a system variable
+- Variables support template expressions: `"{{ int organizationId }}"`
+- Multiple queries can be in one step (returns merged results)
+
+## Validation/Validate@1
+
+Validates data against rules. Commonly used in Before entity triggers to block invalid changes.
+
+Two rule types:
+- **`rule: "required"`** — checks that `value` is not null or empty
+- **Condition expression** — evaluates an NCalc `conditions` expression (no `rule` property needed)
+
+```yaml
+- task: "Validation/Validate@1"
+  name: ValidateOrder
+  inputs:
+    rules:
+      - rule: "required"
+        value: "{{ Data.GetOrder.order.status? }}"
+        message: "Order status is required"
+      - conditions: "[Data.GetOrder.order.status] != 'Cancelled'"
+        message: "Cannot modify cancelled orders"
+      - conditions: "[Data.GetOrder.order.amount] > 0"
+        message: "Amount must be positive"
+```
+
+If validation fails and `continueOnError` is false (default), execution stops and a `ValidationException` is returned. Set `continueOnError: true` to collect errors in the `errors` output instead:
+
+```yaml
+- task: "Validation/Validate@1"
+  name: ValidateOrder
+  continueOnError: true
+  inputs:
+    rules:
+      - rule: "required"
+        value: "{{ Data.GetOrder.order.status? }}"
+        message: "Order status is required"
+      - conditions: "[Data.GetOrder.order.amount] > 0"
+        message: "Amount must be positive"
+  outputs:
+    - name: errors
+```
+
+## Workflow/Execute
+
+Executes a child workflow. Can run sync (wait for result) or async (fire and forget).
+
+```yaml
+- task: "Workflow/Execute@1"
+  name: RunChild
+  inputs:
+    workflowId: "<uuid>"
+    workflowInputs:
+      orderId: "{{ inputs.orderId }}"
+      customerId: "{{ Data.GetOrder.order.customer.contactId }}"
+```
+
+The child workflow's outputs are available as step outputs: `ActivityName.RunChild.outputName`.
+
+**Circular call detection**: The executor maintains a call stack and throws if a workflow calls itself recursively.
+
+## Workflow/Create, Workflow/Update, Workflow/Delete
+
+CRUD operations on workflow definitions (not executions). Rarely used in standard workflows.
+
+```yaml
+- task: "Workflow/Create"
+  name: CreateWorkflow
+  inputs:
+    name: "Generated Workflow"
+    document: "{{ workflowYaml }}"
+```