@jigx/core-sdk 1.0.0 → 1.2.0-rc

package/docs/pattern-rest-acumatica.md

@@ -0,0 +1,660 @@
+# Pattern: REST Integration (Acumatica)
+
+## Best-practice boundary
+
+Use this file to define how Acumatica REST functions are built, not when UI flows should call them.
+
+The best-practice architecture is:
+
+1. Save all user edits to local tables first.
+2. Mark records with local sync state (`Remote = "new"` / `"dirty"`).
+3. Let a centralized sync workflow select unsynced records and push them to Acumatica.
+
+Do not treat inline remote writes from create/edit screens as the default pattern. Some older projects do this, but it is legacy behavior and should not be copied into new apps unless there is a documented exception.
+
+DoorPro is one such legacy/project-specific example: it contains direct Acumatica write functions for order submission. Those functions are useful as integration references, but they are not the source of truth for outbound sync architecture.
+
+## Acumatica conventions (remember these)
+
+- **HTTP method**: PUT for creates/updates (Acumatica-specific — not POST)
+- **`useLocalCall: true`** — always, for all REST functions
+- **`accessToken`** header parameter with `type: 'acuerp'` and `value: 'acuerp'` — Jigx handles OAuth token collection, storage, and injection automatically
+- **URL pattern**: `https://{acumaticaURL}EntityName` — `acumaticaURL` comes from the config table (e.g., `jigx.acumatica.com/entity/Default/23.200.001/`)
+- **Config field names are case-sensitive**: use `acumaticaURL` for REST and `acumaticaOdataURL` for OData everywhere, including config data, datasource access, function params, and action parameters
+- **$expand parameter**: Passed from the action (not hardcoded on the function), location `query`
+- **No msgBody parameter**: Use queries to fetch data at execution time (see Queries section)
+
+## Per-line InventoryID / LineType decisions
+
+When a parent record submits multiple child lines, do not use a parent-level flag to decide
+whether every child line should be a stock item or a non-stock item. Store the mode on each
+local child row and calculate the Acumatica line fields per row.
+
+This matters when the user can mix strict catalog/matrix-backed lines with generic quote lines.
+For example, a door quote may contain one line that should use a validated stock `InventoryID`
+and another line that should use a generic non-stock `InventoryID`.
+
+Pattern:
+
+- Save a per-line boolean such as `onlyValidDoorConfiguration` on the child row.
+- Default new rows to the strict/validated mode when that is the desired UX, but preserve explicit `false`.
+- In the Acumatica payload map, compute `$strictLine` from the current row, not from the parent quote.
+- For strict rows, send the generated/validated inventory code as `InventoryID`, set `LineType` to `"Inventory Item"`, and usually omit `Description` so Acumatica can use the stock item's description.
+- For generic rows, send the agreed generic non-stock code such as `DOORQUOTE`, set `LineType` to `"Non-Stock Item"`, include a user-facing `Description`, and keep the generated/internal configuration code in the line `note`.
+
+## Record sync state (`Remote` field)
+
+All records include a `Remote` field to track sync state. Always use strings (never mix boolean/string):
+
+| Value | Meaning |
+| --- | --- |
+| `"new"` | Created locally, never synced to Acumatica |
+| `"dirty"` | Previously synced, has local changes pending |
+| `"remote"` | In sync with Acumatica |
+
+New records set `"Remote": "new"` in the save expression. After successful sync, the function's upsert-merge operation sets it to `"remote"`.
+
+This state exists specifically to support local-first persistence with deferred outbound sync. The screen/form save action should update the local record and its `Remote` state only. A separate sync action is responsible for selecting records in `"new"` / `"dirty"` state and calling the remote function.
+
+For incomplete local records, use a separate local readiness state such as `LocalState = "draft"`.
+Do not overload `Remote` to mean "not ready to sync yet".
+
+A datasource selects unsynced records:
+
+```typescript
+app.addDatasource
+  .sqlite({ datasourceId: 'data-select-customer-to-save', provider: 'dynamic' })
+  .entity('default/customers')
+  .query(`SELECT id, data FROM [default/customers] WHERE json_extract(data, '$.Remote') = 'new' OR json_extract(data, '$.Remote') = 'dirty' LIMIT 1`)
+  .jsonProperties('data')
+  .isDocument(true)
+```
+
+For real batch sync, prefer a datasource that selects all syncable rows, not just `LIMIT 1`.
+The sync action then passes that datasource collection into `executeEntities(...)`.
+
+## Acumatica create vs update behavior
+
+Acumatica determines create vs update based on the JSON body:
+
+| Body contains | Behavior |
+| --- | --- |
+| No `id` or key field | Creates a new record |
+| `id: <guid>` (top-level, not `.value`) | Updates by internal ID |
+| Key field (e.g., `CustomerID`) without `id` | Looks up by key field, updates if found |
+
+For `new` records we strip `id` from the body (via inputTransform) so Acumatica creates. For `dirty` records we include `id` so Acumatica updates.
+
+## $expand — getting child objects in the response
+
+Acumatica responses only include top-level fields by default. To get nested/child objects, pass a `$expand` query parameter listing the objects to include.
+
+For nested expansion (child of child), use `/` notation: `ShippingContact/Address`.
+
+Arrays are not allowed as children of children in Acumatica.
+
+Example expand value for Customer:
+
+```
+BillingContact/Address,ShippingContact/Address,PrimaryContact/Address,MainContact/Address,Files
+```
+
+Pass `$expand` from the action as a `functionParameter`, not hardcoded on the function definition. Different callers may need different expansions.
+
+For lookup/reference syncs, the same rule still applies in practice: if a screen reads nested fields like
+`MainContact.Address` or `LocationContact.Address`, the lookup sync must request those expansions explicitly.
+Do not assume the child objects will exist in local data just because the screen references them.
+
+Before implementing a new lookup/reference sync, inspect the screen fields and the available schema,
+then propose the likely `$expand` list up front and confirm it if there is any ambiguity.
+
+Default working rule:
+
+- derive a candidate `$expand` list from the nested fields the UI needs
+- show that list early during planning if the endpoint or child shape is not already settled
+- ask for confirmation when the schemas suggest multiple plausible child objects
+- only then wire the sync
+
+This is especially important for reference entities where top-level fields may look sufficient at first,
+but the real UI requirement depends on nested contact/address/status objects.
+
+For customer-location contact display, prefer `LocationContact.FullName` and fall back to
+`LocationContact.DisplayName`. `LocationContact.Attention` is also not consistently populated, so
+fall back to `LocationContact.JobTitle` before dropping to customer-level contact fields.
+
+If you add a new `$expand` to a lookup sync, remember that unchanged Acumatica rows will not be
+returned by a standard `LastModifiedDateTime` diff sync. In practice that means local cached rows
+can remain structurally stale even though the sync succeeds. The default recipe should therefore be:
+
+- keep normal sync incremental
+- add a separate explicit `Force Sync` action for full lookup refresh when needed
+- use that action during testing or rollout until the cached rows have been refreshed locally
+
+## Defining a REST function
+
+Standard parameters for Acumatica REST functions:
+
+| Parameter | Location | Purpose |
+| --- | --- | --- |
+| `acumaticaURL` | path | Base URL from config table |
+| `accessToken` | header | OAuth token (type `acuerp`) |
+| `$expand` | query | Child objects to include in response |
+| `id` | body | Local record ID (used by queries and operations) |
+| `remote` | body | Sync state (used by inputTransform/operations) |
+
+The `id` and `remote` body parameters are not sent to the API — the `inputTransform` builds the request body from the query result.
+
+```typescript
+const fn = app.addFunction
+  .rest({
+    functionId: 'rest-put-customer',
+    method: 'PUT',
+    url: 'https://{acumaticaURL}Customer',
+    useLocalCall: true,
+  })
+
+fn.params.path('acumaticaURL', { required: true })
+fn.params.header('accessToken', 'acuerp', { required: true, type: 'acuerp' })
+fn.params.query('$expand', { type: 'string', required: false })
+fn.params.body('id', undefined, { type: 'string', required: true })
+fn.params.body('remote', undefined, { type: 'string', required: true })
+```
+
+## Queries — fetching fresh data at execution time (preferred pattern)
+
+When an `executeEntity` call is queued (e.g., user is offline), the function parameters are snapshot at queue time. If the local data changes before the queue processes, the snapshot is stale.
+
+**The preferred pattern** is to pass only the record `id` (not the full data) and use a `queries` section on the function to fetch the latest data from the local table when the command queue item is processed.
+
+```typescript
+// No msgBody parameter — data comes from queries at execution time
+fn.params.body('id', undefined, { type: 'string', required: true })
+fn.params.body('remote', undefined, { type: 'string', required: true })
+
+fn.query('get-customer-to-save', {
+  statement: 'SELECT id, data FROM [Customers] WHERE id = @id',
+  resultType: 'record',
+  jsonColumns: ['data'],
+  parameters: { id: '=@ctx.parameters.id' },
+  tables: ['Customers'],
+})
+```
+
+Query results are accessed via `@ctx.queries.<queryName>`. With `jsonColumns: ['data']`, the data column is auto-parsed.
+
+The action only passes `id` and `remote` — no data parameter:
+
+```typescript
+buttons.add.executeAction({
+  action: ACTION.CUSTOMER_SAVE_REMOTE,
+  parameters: {
+    id: '=@ctx.datasources.data-select-customer-to-save.id',
+    remote: '=@ctx.datasources.data-select-customer-to-save.data.Remote',
+  },
+})
+```
+
+Use this pattern unless you specifically need queue-time data snapshots.
+
+This is the preferred default for batch sync as well. The action passes identifiers and sync
+metadata, and the function re-queries the latest local row before constructing the Acumatica body.
+
+## inputTransform — shaping the request body
+
+The inputTransform is a JSONata expression that transforms the query result before sending to the API. It operates on `@ctx.queries` and `@ctx.parameters`, and its result becomes the HTTP request body.
+
+For Acumatica:
+- Always strip `Remote` (internal tracking field, not an Acumatica field)
+- Strip `id` + the entity's key field (`CustomerID`, `ContactID`) when `new` — Acumatica assigns these on creation
+- Keep them when `dirty` — Acumatica needs them to identify the record to update
+
+```typescript
+// Customer — strip id + CustomerID when new
+fn.inputTransform(
+  '=$sift(@ctx.queries.get-customer-to-save.data, function($v, $k) { $k != "Remote" and (@ctx.parameters.remote != "new" or ($k != "id" and $k != "CustomerID")) })',
+)
+
+// Contact — strip id + ContactID when new
+fn.inputTransform(
+  '=$sift(@ctx.queries.get-contact-to-save.data, function($v, $k) { $k != "Remote" and (@ctx.parameters.remote != "new" or ($k != "id" and $k != "ContactID")) })',
+)
+```
+
+Each entity has its own key field to strip. The pattern is: `$k != "id" and $k != "<EntityKeyField>"`.
+
+Also set the key field's form control to `isDisabled: true` on create screens — it's assigned by Acumatica, not the user.
+
+## Operations — processing the response
+
+Operations run after the HTTP response is received. They update the local database with the response data.
+
+### 1. find-replace: Update local ID with Acumatica ID (new records only)
+
+When Acumatica creates a record, it assigns a GUID (`id`/`NoteID`). We replace our local UUID with Acumatica's GUID so the record ID matches going forward.
+
+```typescript
+fn.operation()
+  .findReplace(
+    '=@ctx.parameters.id',        // find: our local UUID
+    '=@ctx.response.body.id',     // replace: Acumatica's GUID
+    ['customers'],                 // in this table
+    false,                         // includeCommandQueue: false
+  )
+  .when('=@ctx.parameters.remote = "new"')
+```
+
+`includeCommandQueue: false` skips the command queue table. Set to `true` when related records in other tables have queued commands that reference this ID.
+
+The `when` condition ensures we only do the find-replace for new records — unnecessary for dirty records since the ID already matches.
+
+### 2. find-replace: Update local ID in related tables (parent-child)
+
+When a parent record (e.g., Customer) is created in Acumatica, child records (e.g., Contacts) reference the parent via a local UUID. After sync, replace that UUID with the Acumatica-assigned key so relationships stay intact.
+
+```typescript
+// Replace local customer UUID with Acumatica CustomerID in contacts table
+fn.operation()
+  .findReplace(
+    '=@ctx.parameters.id',                    // find: local UUID
+    '=@ctx.response.body.CustomerID.value',   // replace: Acumatica CustomerID
+    ['contacts'],                              // in the contacts table
+    false,
+  )
+  .when('=@ctx.parameters.remote = "new"')
+```
+
+This works because find-replace searches for the string value across all data in the specified table. When a contact has `"BusinessAccount": {"value": "local-uuid"}`, the local UUID string gets replaced with the Acumatica CustomerID.
+
+**Key insight**: The replace value for the parent table uses `@ctx.response.body.id` (the GUID), but for child tables use the business key (`CustomerID.value`) because that's what child records reference via `BusinessAccount.value`.
+
+This parent-first then child-sync ordering is the standard recipe when child rows depend on a
+key returned by Acumatica. Sync the parent first, update child references via operations, then
+execute child sync.
+
+### 3. upsert-merge: Merge response into local record
+
+Merge the full Acumatica response (which includes calculated fields, expanded child objects, etc.) with `Remote: "remote"` to mark as synced.
+
+```typescript
+fn.operation().upsertMerge(
+  'customers',
+  '=$merge([@ctx.response.body, {"Remote": "remote"}])',
+)
+```
+
+`upsert-merge` merges the JSON response with the existing local record — it doesn't replace the entire record. This preserves any local-only fields.
+
+### 4. success markers for multi-call sends
+
+When one user action performs more than one Acumatica REST call, do not mark the
+overall business record as sent after merely enqueueing the calls. Give the send
+attempt a `sendBatchId`, pass it as an output parameter to every REST function,
+and let each function write its own success marker from a success-only
+`operation().upsertMerge(...)`.
+
+```typescript
+fn.params.output('opportunityID', { required: true, type: 'string' })
+fn.params.output('sendBatchId', { required: true, type: 'string' })
+
+fn.operation().upsertMerge(
+  'quoteAcumaticaStatus',
+  `={
+    "id": @ctx.parameters.opportunityID,
+    "opportunityID": @ctx.parameters.opportunityID,
+    "sendBatchId": @ctx.parameters.sendBatchId,
+    "linesSent": true,
+    "linesSentAt": $now()
+  }`,
+)
+```
+
+The final REST function in the batch should query the status row for the same
+`sendBatchId` and only mark the overall record as sent when all required prior
+markers exist. Store the final state in a Dynamic Data table, not only in local
+state, so other users and devices can see that the quote/order was already sent.
+
+```typescript
+fn.query('send-status', {
+  statement: 'SELECT id, data FROM [default/quoteAcumaticaStatus] WHERE id = @opportunityID LIMIT 1',
+  resultType: 'record',
+  jsonColumns: ['data'],
+  parameters: { opportunityID: '=@ctx.parameters.opportunityID' },
+  tables: ['default/quoteAcumaticaStatus'],
+})
+
+fn.operation()
+  .upsertMerge(
+    'salesInfoAnswers',
+    `={
+      "id": @ctx.parameters.opportunityID,
+      "sentToAcumatica": true,
+      "sentToAcumaticaAt": $now(),
+      "lastAcumaticaSendBatchId": @ctx.parameters.sendBatchId
+    }`,
+  )
+  .when(
+    '=@ctx.queries.send-status.data.linesSent = true and @ctx.queries.send-status.data.sendBatchId = @ctx.parameters.sendBatchId',
+  )
+```
+
+This avoids false positives: failed REST calls run error handlers/queue failure
+logic and never execute success operations, so the overall sent flag is written
+only after every required Acumatica step has succeeded for the same batch.
+
+## Calling the function from an action
+
+These examples show how a sync action calls the REST function. They do not mean the jig screen should call Acumatica directly as part of the primary save flow.
+
+The action passes remote function inputs through `parameters`:
+
+```typescript
+workflow.actions
+  .executeEntity({
+    instanceId: 'save-customer-remote',
+    function: 'rest-put-customer',
+    parameters: {
+      acumaticaURL: '=@ctx.datasources.data-select-config.data.acumaticaURL',
+      accessToken: 'acuerp',
+      $expand: 'BillingContact/Address,ShippingContact/Address,...',
+      id: '=@ctx.action.parameters.id',
+      remote: '=@ctx.action.parameters.remote',
+    },
+})
+  .rest('none', 'functionCall')
+```
+
+Important: `parameters` are passed only to the function call. `data(...)` is written only by the execute action. They are no longer merged.
+
+For batch sync from a header action, the UI should pass a datasource collection of syncable rows:
+
+```typescript
+header.actions.executeAction({
+  title: 'Sync',
+  action: ACTION.SYNC_ALL,
+  icon: 'cloud-sync',
+  parameters: {
+    records: '=@ctx.datasources.syncable-records',
+  },
+  when: '=$count(@ctx.datasources.syncable-records) > 0',
+})
+```
+
+Then the global action fans out over that collection:
+
+```typescript
+workflow.actions
+  .executeEntities({
+    instanceId: 'sync-records',
+    function: 'rest-put-customer',
+    parameters: `=@ctx.action.parameters.records.{
+      "acumaticaURL": @ctx.datasources.data-select-config.data.acumaticaURL,
+      "accessToken": "acuerp",
+      "$expand": "BillingContact/Address,ShippingContact/Address,PrimaryContact/Address,MainContact/Address",
+      "id": $.id,
+      "remote": $.data.Remote
+    }`,
+  })
+  .rest('none', 'functionCall')
+```
+
+### Method behavior
+
+| Method | Behavior |
+| --- | --- |
+| `functionCall` | Only calls the REST function. No local entity write. |
+| `save`, `create`, `update` | Calls the function AND saves data to the specified local entity. |
+
+Use `functionCall` as the default for Acumatica REST calls unless otherwise specified.
+
+## File uploads to Acumatica
+
+Acumatica file uploads are usually not sent to the entity endpoint itself. They use a dedicated
+`files/...` route that includes the remote parent record id / NoteID in the URL.
+
+Example shape:
+
+```typescript
+const fn = app.addFunction.rest({
+  functionId: 'rest-put-parent-photo',
+  method: 'PUT',
+  url: 'https://{acumaticaURL}files/PX.Objects.FS.ServiceOrderEntry/ServiceOrderRecords/{recordId}/{filename}',
+  useLocalCall: true,
+})
+
+fn.params.path('acumaticaURL', { required: true })
+fn.params.header('accessToken', 'acuerp', { required: true, type: 'acuerp' })
+fn.params.path('recordId', { required: true })
+fn.params.path('filename', { required: true })
+fn.params.header('Content-Type', undefined, { required: true, type: 'string' })
+fn.params.body('file', { required: true, type: 'image' })
+fn.params.output('photoId', { required: true, type: 'string' })
+
+fn.conversion('file', 'local-uri', 'buffer')
+```
+
+Use this pattern when:
+
+- files are stored locally as device `fileUrl` / `uri`
+- the upload endpoint expects binary body content
+- the parent record must exist remotely before the upload can succeed
+
+Important rules:
+
+- upload one file per function call
+- pass only function inputs through `parameters`
+- keep local file storage separate from the remote upload route
+- prefer `local-uri -> buffer` conversion for binary upload
+- if you need local row metadata after the call, pass that metadata through output parameters and
+  update local tables with function operations
+
+### Getting the correct upload URL
+
+Do not guess the `files/...` route from memory.
+
+Preferred order:
+
+1. inspect the swagger for the entity's file links / upload routes
+2. inspect an actual Acumatica response for the entity's `_links` or file path patterns
+3. if the route is still ambiguous, ask for the full upload URL before implementing
+
+This should be confirmed early in planning, the same way `$expand` lists are confirmed early for
+nested lookup data.
+
+## UI flow rule: save local, sync centrally
+
+For create/edit forms:
+
+- Save to the local entity first.
+- Set `Remote` to `"new"` for new records or `"dirty"` for updates.
+- Return control to the user without waiting for Acumatica.
+
+Then, outside the form save flow:
+
+- A centralized sync action, sync queue, or orchestrator selects unsynced rows.
+- That sync workflow calls the REST function using the record `id` and current `remote` state.
+- On success, the response is merged locally and the row is marked `"remote"`.
+
+This keeps the user workflow resilient offline, reduces coupling between form UX and network behavior, and makes retries/failure handling consistent across the app.
+
+### Calling from a jig
+
+Pass only `id` and `remote` — the function's query fetches the latest data:
+
+```typescript
+header.actions.executeAction({
+  title: 'Save Single Customer',
+  action: ACTION.CUSTOMER_SAVE_REMOTE,
+  parameters: {
+    id: '=@ctx.datasources.data-select-customer-to-save.id',
+    remote: '=@ctx.datasources.data-select-customer-to-save.data.Remote',
+  },
+})
+```
+
+## Error handlers for REST PUT functions
+
+Add standard error handlers to every Acumatica REST function. The handlers cover authentication, permissions, validation, timeouts, throttling, empty responses, and not-found errors.
+
+Use a shared helper to keep error handling consistent across functions:
+
+```typescript
+// app.ts
+app.script('acumaticaerrors.js', readScriptFile('acumaticaerrors.js'))
+
+// functions/acumatica-error-handlers.ts
+export function addAcumaticaPutErrorHandlers(fn: RestFunctionBuilder, entityLabel: string): void {
+  fn.error('=@ctx.response.status = 401')
+    .notification(true)
+    .alert({ icon: 'on-error-sad', title: '401 - Not authenticated', description: '...' })
+
+  fn.error('=@ctx.response.status = 422')
+    .notification(true)
+    .details(`=$acumaticaerrors.findNestedErrors(@ctx.response.body,
+      "Acumatica rejected the request. Review the values and try again.")`)
+    .alert({ icon: 'on-error-sad', title: '422 - Data Validation error',
+      description: `=$acumaticaerrors.findNestedErrors(@ctx.response.body,
+        "Acumatica rejected the ${entityLabel}. Review the values and try again.")` })
+    .operation('=@ctx.response.body')
+    .upsertReplace('rest-put-errors')
+
+  // 503, 504, 429 — retry with delay
+  fn.error('=@ctx.response.status = 503')
+    .retry({ delay: 5000, maxRetries: 3 })
+    .notification(true)
+    .alert({ icon: 'on-error-sad', title: '503 - Acumatica Unavailable', description: '...' })
+    .operation('=@ctx.response.body')
+    .upsertReplace('diff-sync-errors')
+
+  // ... additional handlers for 403, 404, 429, 504, empty body, non-JSON response
+}
+```
+
+Apply to each function:
+
+```typescript
+addAcumaticaPutErrorHandlers(fn, 'customer')
+addAcumaticaPutErrorHandlers(fn, 'contact')
+```
+
+### Standard error handler list
+
+| Status | Action | Retry | Error table |
+| ---: | --- | --- | --- |
+| 401 | Alert: not authenticated | no | — |
+| 403 | Alert: no permission | no | `diff-sync-errors` |
+| 404 | Alert: not found | no | — |
+| 422 | Alert: validation error with `$acumaticaerrors.findNestedErrors()` | no | `rest-put-errors` |
+| 429 | Alert: throttled | 3x @ 5s | `diff-sync-errors` |
+| 503 | Alert: unavailable | 3x @ 5s | `diff-sync-errors` |
+| 504 | Alert: timeout | 3x @ 5s | `diff-sync-errors` |
+| 200 + empty body | Alert: no data returned | 3x @ 5s | `diff-sync-errors` |
+| 200 + non-JSON | Alert: unexpected response | no | `diff-sync-errors` |
+
+Add `diff-sync-errors` and `rest-put-errors` tables to the database definition.
+
+The `entityLabel` parameter customizes error messages per entity (e.g., "Error saving customer" vs "Error saving contact").
+
+### Parsing Acumatica 422 validation responses
+
+Acumatica `422 Unprocessable Entity` responses often bury useful validation text in
+nested `error` fields, sometimes under `Details`, and those strings can be escaped.
+Do not show the raw `"Function failed with 422 Unprocessable Entity"` message to the
+user. Register a small app script that recursively scans the response body, collects
+every nested `error` value, unescapes it, deduplicates messages, and returns a concise
+user-facing string:
+
+```javascript
+// scripts/acumaticaerrors.js
+export function findNestedErrors(body, fallback) {
+  // Recursively scan objects/arrays for keys named "error" and return:
+  // Acumatica validation failed:
+  // - First validation message
+  // - Second validation message
+}
+```
+
+Use it in the `422` handler description and details so the notification and error
+details contain the Acumatica validation messages rather than the generic HTTP status.
+
+### Retrying failed command-queue calls with corrected payloads
+
+`action.retry-queue-command` replays the command exactly as it was queued. Use it only when
+the original payload is still correct and the failure was transient or the remote data has been
+fixed.
+
+For validation errors where the local app can offer a fallback payload, do not retry the original
+command. Instead:
+
+1. Show a warning that explains the validation failure and the two recovery choices.
+2. If the user confirms the remote master data was fixed, call `action.retry-queue-command`.
+3. If the user chooses the fallback, delete the failed queue command with `action.delete-queue-command`.
+4. Execute a new REST function call with the corrected fallback payload.
+
+Example: an Acumatica service-order detail call can fail with 422 when an inventory ID does not
+exist. If the user wants to keep the exact inventory ID, retry the queued command after the item
+has been added in Acumatica. If the user chooses generic non-stock quote items, delete the failed
+command and send a new payload using the generic non-stock inventory IDs. Retrying the original
+command would keep sending the missing inventory ID.
+
+## Batch sync: executeEntities with parameters map
+
+When multiple records need syncing, use `executeEntities` (plural) with a `parameters` map expression. Jigx calls the function once per item in the array.
+
+**Important**: Use `executeEntities` (not `executeEntity`) — only `executeEntities` supports the map pattern.
+
+```typescript
+// Action accepts an array of records
+action.addParameter('records', { type: 'array', required: true })
+
+// executeEntities maps each record to a function call
+workflow.actions
+  .executeEntities({
+    instanceId: 'save-customer-remote',
+    function: 'rest-put-customer',
+    parameters: `=@ctx.action.parameters.records.{
+      "acumaticaURL": @ctx.datasources.data-select-config.data.acumaticaURL,
+      "accessToken": "acuerp",
+      "$expand": "BillingContact/Address,...",
+      "id": $.id,
+      "remote": $.data.Remote
+    }`,
+  })
+  .rest('none', 'functionCall')
+```
+
+The JSONata `.{ }` operator maps each item in the array. `$.id` and `$.data.Remote` reference the current item's fields.
+
+`parameters` are sent to the function only. If the action also calls `.data(...)`, that payload is what gets saved to the entity.
+
+### Calling from the sync action
+
+Pass the full datasource array:
+
+```typescript
+workflow.actions.executeAction({
+  action: 'act-customer-save-remote',
+  parameters: {
+    records: '=@ctx.datasources.data-select-customer-to-save',
+  },
+  when: '=$count(@ctx.datasources.data-select-customer-to-save) > 0',
+})
+```
+
+The datasource returns all new/dirty records (no `LIMIT 1`, no `isDocument`).
+
+### Sequencing for parent-child
+
+Push parents before children — children may depend on IDs assigned to parents by the remote system:
+
+1. Push customers (find-replace updates CustomerID in contacts table)
+2. Push contacts (now has correct CustomerID in BusinessAccount.value)
+3. Pull customers (diff sync)
+4. Pull contacts (diff sync)
+
+**Acumatica-specific**: Acumatica does not accept arrays of objects — each record must be sent individually. The `executeEntities` map pattern handles this automatically.
+
+## Config table for integration settings
+
+Store the Acumatica base URL and other integration config in a `config` table. See [pattern-datasources.md](pattern-datasources.md#config-table) for the full pattern.
+
+Access: `=@ctx.datasources.data-select-config.data.acumaticaURL`