cxtms 1.9.13

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

@@ -0,0 +1,342 @@
+# Entity CRUD Tasks Reference
+
+## Contents
+- Entity/Change task (generic entity modification in Before triggers)
+- Order tasks (Create, Update, Delete, Get, Copy, Split, Import, etc.)
+- Contact tasks (Create, Update, Delete)
+- ContactAddress tasks (Create, Update, Delete, Import)
+- ContactPaymentMethod tasks (Create, Update, SendChargedAmount, VerifyChargedAmount)
+- Commodity tasks (Create, Update, Split, Repack, Unpack)
+- CommodityTrackingNumber tasks (Create, Update, Delete)
+- Job tasks (Create, Update, Delete, Assign, Unassign)
+- Charge tasks (Create, Update, Delete, DynamicUpdate, Calculate)
+- Discount task (Update)
+- Order sub-entity tasks (OrderCommodity, OrderCharge, OrderDocument, OrderTrackingEvent, OrderEntity)
+- Inventory tasks (InventoryItem Create, Update, Delete)
+- Other entity tasks (Movement, Country, Cities, Rate, TrackingEvent/Import)
+- Note tasks (Create, Update, Delete, Import, Export, RenameThread)
+- AccountingTransaction/ApplyCredit task
+
+All entity tasks follow the `Namespace/Operation@Version` pattern. Outputs are stored as `ActivityName.StepName.outputKey`.
+
+## PostalCodes
+
+| Task | Description |
+|------|-------------|
+| `PostalCodes/Import@1` | Import postal codes from file URL, stream, or inline data |
+
+### PostalCodes/Import@1
+
+Imports postal codes (CSV, JSON, Excel). Supports upsert via `matchByFields`.
+
+```yaml
+- task: "PostalCodes/Import@1"
+  name: ImportPostalCodes
+  inputs:
+    organizationId: "{{ int inputs.organizationId }}"
+    fileUrl: "{{ inputs.fileUrl }}"
+    matchByFields: ["code", "countryCode"]
+  outputs:
+    - name: importResult
+      mapping: "result?"
+```
+
+**Inputs:** `organizationId` (int, required), `fileUrl` (string?), `fileType` (FileType?), `stream` (Stream?), `postalCodes` (List?), `matchByFields` (string[]?)
+**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`.
+
+## Generic Entity Change
+
+| Task | Description |
+|------|-------------|
+| `Entity/Change` | Generic entity change — modify custom values on the tracked entity. Designed for **Before** triggers where the entity hasn't been persisted yet. |
+
+```yaml
+- task: "Entity/Change@1"
+  name: SetDefaults
+  inputs:
+    changes:
+      customValues:
+        region: "{{ parseAddress(Order.ShipToAddress).state }}"
+        lastModifiedBy: "{{ currentUser.name }}"
+```
+
+> **Note**: Async "Before" triggers are forbidden. Before triggers must use `executionMode: Sync`.
+
+## Order
+
+| Task | Description |
+|------|-------------|
+| `Order/Create` | Create a new order |
+| `Order/Update` (v1, v2) | Update order fields |
+| `Order/Delete` | Delete an order |
+| `Order/Get` | Get order by ID |
+| `Order/Copy` | Copy/duplicate an order |
+| `Order/Split` | Split order into multiple |
+| `Order/Purge` | Purge order data |
+| `Order/Import` | Import order from external data |
+| `Order/RecalculateCharges` | Recalculate all charges |
+| `Order/GenerateTrackingNumber` | Generate tracking number |
+| `Order/GetCargoMovementByPalletQuery` | Query cargo movements by pallet |
+
+```yaml
+- task: "Order/Create@1"
+  name: CreateOrder
+  inputs:
+    orderType: "ParcelShipment"
+    entity:
+      customer: "{{ inputs.customerId }}"
+      status: "Draft"
+  outputs:
+    - name: order
+      mapping: "order"
+```
+
+```yaml
+- task: "Order/Update@2"
+  name: UpdateOrder
+  inputs:
+    orderId: "{{ inputs.orderId }}"
+    entity:
+      status: "Active"
+      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 |
+|------|-------------|
+| `Contact/Create` | Create contact |
+| `Contact/Update` | Update contact |
+| `Contact/Delete` | Delete contact |
+
+## Contact Address
+
+| Task | Description |
+|------|-------------|
+| `ContactAddress/Create` | Create address |
+| `ContactAddress/Update` | Update address |
+| `ContactAddress/Delete` | Delete address |
+| `ContactAddress/Import` | Bulk import addresses |
+
+## Contact Payment Method
+
+| Task | Description |
+|------|-------------|
+| `ContactPaymentMethod/Create` | Create payment method |
+| `ContactPaymentMethod/Update` | Update payment method |
+| `ContactPaymentMethod/SendChargedAmount` | Send charged amount notification |
+| `ContactPaymentMethod/VerifyChargedAmount` | Verify charged amount |
+
+## Commodity
+
+| Task | Description |
+|------|-------------|
+| `Commodity/Create` | Create commodity |
+| `Commodity/Update` (v1, v2) | Update commodity |
+| `Commodity/Split` | Split commodity into multiple |
+| `Commodity/Repack` | Repack commodities |
+| `Commodity/Unpack` | Unpack commodity |
+
+## Commodity Tracking Number
+
+| Task | Description |
+|------|-------------|
+| `CommodityTrackingNumber/Create` | Create tracking number |
+| `CommodityTrackingNumber/Update` | Update tracking number |
+| `CommodityTrackingNumber/Delete` | Delete tracking number |
+
+## Job
+
+| Task | Description |
+|------|-------------|
+| `Job/Create` | Create job |
+| `Job/Update` | Update job |
+| `Job/Delete` | Delete job |
+| `Job/Assign` | Assign job to user/driver |
+| `Job/Unassign` | Unassign job |
+
+## Charge
+
+| Task | Description |
+|------|-------------|
+| `Charge/Create` | Create charge |
+| `Charge/Update` | Update charge |
+| `Charge/Delete` | Delete charge |
+| `Charge/DynamicUpdate` | Dynamic update (partial fields) |
+| `Charge/Calculate` | Calculate charge amount |
+
+```yaml
+- task: "Charge/Create@1"
+  name: CreateCharge
+  inputs:
+    orderId: "{{ inputs.orderId }}"
+    chargeType: "Freight"
+    amount: "{{ Data.GetRate.rate.amount }}"
+    currency: "USD"
+  outputs:
+    - name: charge
+      mapping: "charge"
+```
+
+## Discount
+
+| Task | Description |
+|------|-------------|
+| `Discount/Update` | Update discount |
+
+## Order Sub-Entities
+
+| Task | Description |
+|------|-------------|
+| `OrderCommodity/Create` | Link commodity to order |
+| `OrderCommodity/Update` | Update order-commodity link |
+| `OrderCommodity/Delete` | Remove commodity from order |
+| `OrderCharge/Create` | Create order charge |
+| `OrderDocument/Create` | Create order document |
+| `OrderDocument/Send` | Send order document |
+| `OrderTrackingEvent/Create` | Create a single tracking event on an order |
+| `OrderEntity/ChangeCustomValue` | Change custom field value |
+
+```yaml
+# Create a single tracking event
+- task: "OrderTrackingEvent/Create@1"
+  name: AddPickupEvent
+  inputs:
+    orderId: "{{ inputs.orderId }}"
+    organizationId: "{{ inputs.organizationId }}"
+    eventDefinitionName: "Picked Up"
+    eventDate: "{{ utcNow() }}"
+    description: "Package picked up from shipper"
+    location: "{{ order.shipFromAddress?.city }}"
+    includeInTracking: true
+    sendEmail: false
+    skipIfExists: true
+    customValues?:
+      carrierId: "{{ carrier.contactId }}"
+      carrierEventCode: "PU"
+```
+
+## Inventory
+
+| Task | Description |
+|------|-------------|
+| `InventoryItem/Create` | Create inventory item |
+| `InventoryItem/Update` | Update inventory item |
+| `InventoryItem/Delete` | Delete inventory item |
+
+## Other
+
+| Task | Description |
+|------|-------------|
+| `Movement/Create` | Create cargo movement |
+| `Country/Create`, `Country/Update`, `Country/Delete` | Country CRUD |
+| `Cities/Import` | Import cities |
+| `Rate/Update` | Update rate |
+| `TrackingEvent/Import` | Batch import tracking events into an order |
+
+```yaml
+# Batch import tracking events
+- task: "TrackingEvent/Import@1"
+  name: ImportEvents
+  inputs:
+    orderId: "{{ order.orderId }}"
+    events: "{{ trackingEvents }}"
+    matchByFields:
+      - "eventDate"
+      - "customValues.eventType"
+      - "customValues.locationId"
+    skipIfExists: true
+    createEventDefinitions: true
+    matchByEventDefinition:
+      - "customValues.carrierId"
+      - "customValues.carrierEventCode"
+    eventDefinitionDefaults:
+      includeInTracking: true
+  outputs:
+    - name: result
+      mapping: "result?"
+```
+
+Each event in the `events` array: `eventDefinitionName` (required), `eventDate`, `description`, `location`, `includeInTracking`, `sendEmail`, `isInactive`, `customValues` (object).
+
+Output `result`: `{ added, updated, skipped, failed, total, errors[] }`.
+
+## Note
+
+| Task | Description |
+|------|-------------|
+| `Note/Create` | Create note in a thread |
+| `Note/Update` | Update note content |
+| `Note/Delete` | Delete a note |
+| `Note/Import` | Bulk import notes |
+| `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 |
+|------|-------------|
+| `AccountingTransaction/ApplyCredit` | Apply credit memo to invoices |

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

@@ -0,0 +1,128 @@
+# NCalc Expressions & Functions
+
+## Contents
+- NCalc expression syntax `[variable]` (in conditions and expression directives)
+- Operators (comparison, logical, arithmetic, ternary, membership)
+- Iterator variables (`[each.*]` and `[item.*]`)
+- Collection functions (any, all, count, sum, first, last, distinct, groupBy, join, etc.)
+- String functions (isNullOrEmpty, length, lower, upper, replace, format, base64, etc.)
+- Date functions (now, parseDate, addDays, formatDate, dateFromUnix, etc.)
+- Math functions (Abs, Ceiling, Floor, Round, Min, Max, etc.)
+- Domain functions (convertWeight, convertDimension)
+
+For template expressions `{{ path }}` used in step inputs, see [ref-expressions-template.md](ref-expressions-template.md).
+
+## NCalc Expressions: `[variable]` (in conditions and expression directives)
+
+Used in `conditions[].expression`, `switch` case `when`, and `expression:` value directives. Variables use **square bracket** `[name]` syntax.
+
+```yaml
+conditions:
+  - expression: "[status] = 'Active' AND [amount] > 100"
+  - expression: "isNullOrEmpty([Data.GetOrder.order?]) = false"
+  - expression: "any([changes], [each.key] = 'Status') = true"
+```
+
+**Parameter resolution rules**:
+- Empty strings are converted to `null` (so `""` is treated as no value)
+- Numeric strings are auto-converted to `decimal` when needed (e.g., `[price] > 100` works even if price is the string `"150"`)
+- Dot paths resolve deep: `[Activity.Step.output.nested.field]`
+- Optional suffix `?` prevents errors: `[order.customer?.name?]`
+
+### Operators
+
+| Type | Operators |
+|------|-----------|
+| Comparison | `=`, `!=`, `<>`, `<`, `>`, `<=`, `>=` |
+| Logical | `AND`, `OR`, `NOT` (also `&&`, `\|\|`, `!`) |
+| Arithmetic | `+`, `-`, `*`, `/`, `%` |
+| Ternary | `if(condition, trueVal, falseVal)` |
+| Membership | `in(value, val1, val2, ...)` |
+
+### Iterator Variables
+
+Functions use two iterator variable names:
+- **`[each.*]`** -- used by: `any`, `all`, `sum`, `join` (3-arg)
+- **`[item.*]`** -- used by: `first`, `last`, `groupBy`
+
+### Collection Functions
+
+| Function | Description |
+|----------|-------------|
+| `any([items], [each.prop] = 'val')` | True if any item matches expression. Without expression: checks if collection contains the value |
+| `all([items], [each.prop] > 0)` | True if all items match. Returns `false` for null/empty collections |
+| `count([items])` | Count items in list or JToken. Returns `0` for non-collections |
+| `sum([items], [each.amount])` | Sum values as `decimal`. Optional `[each.*]` accessor. Skips nulls |
+| `first([items])` or `first([items], [item.name])` | First item or evaluate expression on first item. Returns `""` if empty |
+| `last([items])` or `last([items], [item.name])` | Last item or evaluate expression on last item. Returns `""` if empty |
+| `distinct([items])` | Remove duplicates. Uses deep comparison for dictionaries |
+| `reverse([items])` | Reverse collection or string |
+| `contains([source], 'needle')` | String contains, JArray contains, list contains, or dict key/value contains |
+| `removeEmpty([items])` | Remove null and whitespace-only items |
+| `concat([list1], [list2], ...)` | Concatenate multiple collections into flat list. Variadic args. Skips nulls |
+| `groupBy([items], [item.cat])` | Group by one or more key expressions. Returns `[{key, items}]`. Multi-key: keys joined with `\|` |
+| `join([items], [each.name], ',')` | Join collection with `[each.*]` accessor and separator (3-arg) |
+| `join([items], ',')` | Join collection directly with separator (2-arg) |
+| `split([str], ' ')` | Split string by first character of separator. Returns `List<string>` |
+| `elementAt([items], 0)` | Get element at index (zero-based) from list |
+
+### String Functions
+
+| Function | Description |
+|----------|-------------|
+| `isNullOrEmpty([var])` | True if null, empty string, or empty list |
+| `length([var])` | String length or collection count. `0` for null strings and non-collections |
+| `lower([name])` / `upper([code])` | Case conversion. Handles string, JToken, any `.ToString()` |
+| `left([code], 3)` / `right([code], 3)` | Left/right N characters. Returns full string if shorter than N |
+| `substring([str], 0, 5)` | Extract substring starting at position for given length |
+| `replace([str], 'old', 'new')` | String replacement. Returns null if any arg is null |
+| `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 |
+| `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 |
+| `parseAddress([address])` | Parse address -> `{StreetNumber, StreetName}`. Handles US and EU formats |
+
+### Date Functions
+
+| Function | Description |
+|----------|-------------|
+| `parseDate([str])` | Parse date string to DateTime. Supports common formats (ISO, US, etc.) |
+| `now()` | Current UTC `DateTime` |
+| `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 |
+| `formatDate([date], 'dd/MM/yyyy', 'en-US')` | Format date with culture. Accepts DateTime or string |
+| `dateFromUnix([unixTime])` | Unix timestamp (seconds) -> `DateTimeOffset`. Accepts int, long, decimal, string |
+| `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)`
+
+Custom: `ceiling([value])` -- same as `Ceiling` but handles type conversion to double.
+
+### Domain Functions
+
+| Function | Description |
+|----------|-------------|
+| `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 |

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

@@ -0,0 +1,161 @@
+# Template Expressions & Value Directives
+
+## Contents
+- Template expression syntax `{{ path }}` (in step inputs)
+- Type converters (int, decimal, bool, fromJson, toJson, etc.)
+- Value directives (expression, coalesce, foreach, switch, extends, $raw, $eval, encrypt/decrypt)
+- Property path syntax (dot paths, array indexing, wildcards, filters, projections)
+
+There are **two distinct syntaxes** for referencing variables, used in different contexts. This file covers **template expressions** used in step inputs. For NCalc conditions and functions, see [ref-expressions-ncalc.md](ref-expressions-ncalc.md).
+
+## Template Expressions: `{{ path }}` (in step inputs)
+
+Used in step `inputs` values. Resolves variable paths from scoped variables.
+
+```yaml
+inputs:
+  orderId: "{{ inputs.orderId }}"                    # Simple reference
+  url: "{{ chopinConfig.baseUrl }}/api/v1"           # String interpolation
+  order: "{{ Data.GetOrder.order }}"                 # Raw object (single {{ }})
+  name: "Order {{ Data.GetOrder.order.orderNumber }}" # String interpolation (multiple)
+```
+
+**Key behavior**: A single `{{ path }}` returns the **raw object** (preserving type). Multiple `{{ }}` in a string returns string interpolation (each resolved value is `.ToString()`).
+
+### Type Converters (prefix in {{ }})
+
+```yaml
+organizationId: "{{ int organizationId }}"
+amount: "{{ decimal totalAmount }}"
+isActive: "{{ bool isActive }}"
+flag: "{{ boolOrFalse someFlag }}"        # null -> false
+flagOn: "{{ boolOrTrue someFlag }}"       # null -> true
+notes: "{{ emptyIfNull notes }}"          # null -> ""
+notes: "{{ nullIfEmpty notes }}"          # "" or whitespace -> null
+config: "{{ fromJson configJsonString }}" # JSON string -> dict/array
+payload: "{{ toJson someObject }}"        # object -> JSON string
+name: "{{ trim value }}"
+search: "{{ luceneString query }}"        # escape & quote for Lucene
+```
+
+| Converter | Returns | Null handling |
+|-----------|---------|---------------|
+| `string` | `string` | null. Reads `Stream` to string if value is Stream |
+| `int` | `int` | Throws on null |
+| `decimal` | `decimal` | Throws on null |
+| `bool` | `bool` | Throws on null |
+| `boolOrFalse` | `bool` | `false` if null |
+| `boolOrTrue` | `bool` | `true` if null |
+| `datetime` | `DateTime` | Throws on null |
+| `emptyIfNull` | same type | `""` if null, `0` for int?, `0m` for decimal? |
+| `nullIfEmpty` | same type | `null` if empty/whitespace string or empty collection |
+| `luceneString` | `string` | null |
+| `transliterate` | `string` | null (Unicode -> ASCII via Unidecode) |
+| `transliterateUa` | `string` | null (Ukrainian-specific rules) |
+| `fromJson` | `dict` or `array` | null. Empty string -> empty dict |
+| `toJson` | `string` | `""` if null |
+| `trim` | `string` | null |
+| `toLocalTime` | `DateTime` or `string` | null. Syntax: `{{ toLocalTime path 'TimezoneId' 'format?' }}` |
+
+### Value Directives (in YAML input mappings)
+
+**`expression`** -- Evaluate NCalc expression as a value:
+```yaml
+amount:
+  expression: "[price] * [quantity]"
+```
+
+**`coalesce`** -- First non-null value from a list:
+```yaml
+displayName:
+  coalesce:
+    - "{{ customer.name? }}"
+    - "{{ customer.email? }}"
+    - "Unknown"
+```
+
+**`foreach`** (value context) -- Transform collections inline:
+```yaml
+commodities:
+  foreach: "sourceCommodities"
+  item: "item"                             # default: "item"
+  conditions: "[item.isActive] = true"     # optional NCalc filter per item
+  continueOnError: false                   # optional, skip errors
+  mapping:                                 # dict -> List<dict>, string -> List<object>
+    name: "{{ item.name }}"
+    quantity: "{{ item.qty }}"
+```
+
+**`switch`** (value context) -- Value-based switch (case-insensitive match):
+```yaml
+perLb:
+  switch: "{{ contact.commissionTier }}"
+  cases:
+    "tier1": "{{ rate.customValues.commission_per_lb_tier1 }}"
+    "tier2": "{{ rate.customValues.commission_per_lb_tier2 }}"
+  default: "0"
+```
+
+**`extends`** -- Extend/merge an existing object or array:
+```yaml
+orderData:
+  extends: "{{ existingOrder }}"           # base object or array
+  defaultIfNull: {}                        # fallback if extends is null
+  mapping:                                 # dict: merge overrides. array: append items
+    status: "Updated"
+    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:
+  $raw: "This {{ won't }} be parsed"
+```
+
+**`$eval`** -- Parse JSON string then evaluate as template:
+```yaml
+dynamicConfig:
+  $eval: "{{ configJsonString }}"
+```
+
+**`decrypt`** / **`encrypt`** -- AES-CBC encryption (optional key/IV, has defaults):
+```yaml
+apiKey:
+  decrypt:
+    encryptedValue: "{{ encryptedApiKey }}"
+    key: "{{ encryptionKey }}"             # optional Base64 AES key
+    initializationVector: "{{ iv }}"       # optional Base64 IV
+```
+
+---
+
+## Property Path Syntax (in collection, mapping, variable paths)
+
+Used in `collection:` (foreach), `mapping:` (outputs), and variable resolution.
+
+| Pattern | Description | Example |
+|---------|-------------|---------|
+| `a.b.c` | Dot-separated nested path | `order.customer.name` |
+| `prop?` | Optional access (null if missing) | `order.customer?.name?` |
+
+> **Note**: Object-type task inputs (e.g., `headers`, `columnMappings`) are automatically null-safe at the engine level. Omitting an optional object input from YAML returns `null` without errors. The `?` suffix remains required in template expression paths and NCalc conditions.
+| `list[0]` | Array index | `items[0]` |
+| `list[^1]` | Index from end (last item) | `items[^1]` |
+| `list[*]` | Flatten/wildcard (all items) | `containers[*].commodities` |
+| `list[**]` | Recursive flatten (all depths) | `containerCommodities[**]` |
+| `list[-1]` | Depth filter (leaves only) | `tree[**][-1]` |
+| `list[condition]` | Filter by condition | `items[status=Active]` |
+| `dict['key']` | Dictionary key access | `customValues['myField']` |
+| `list[*].{f1 f2}` | Field selector (projection) | `items[*].{name description}` |
+| `list[*].{alias:source}` | Field selector with alias | `items[*].{id:commodityId}` |
+| `list[*].{alias:_.parent}` | Field selector referencing parent | `items[*].{parentId:_.orderId}` |