@jigx/core-sdk 1.0.0 → 1.2.0-rc

package/docs/pattern-sync.md

@@ -0,0 +1,653 @@
+# Pattern: Data Sync (Acumatica)
+
+## Overview
+
+Syncing data from Acumatica involves:
+1. An **initial sync** action called from `index.onLoad`
+2. Individual **sync entity** calls per table (REST GET functions)
+3. **Continuation** for large datasets ($top/$skip pagination)
+4. **Diff sync** for subsequent syncs (only fetch changes since last modified)
+5. **Sync status tracking** via local tables and Jigx sync scopes
+6. **Progress display** via UI components bound to sync state
+
+This file covers both:
+
+- **Inbound sync**: Acumatica -> local tables
+- **Outbound sync orchestration**: local changes -> Acumatica
+
+The default architecture is local-first. User flows save locally and update sync state. A centralized sync workflow is responsible for pushing outbound changes to Acumatica.
+
+## Local-first outbound sync state
+
+For outbound business records, distinguish two concerns:
+
+- **Sync state** in `Remote`
+- **Local readiness state** such as `draft`
+
+### `Remote` values
+
+Use `Remote` only for sync tracking:
+
+- `new`: created locally, never synced
+- `dirty`: previously synced, changed locally since last successful sync
+- `remote`: currently in sync with Acumatica
+
+### Local draft/readiness state
+
+Incomplete records should remain local-only and must not be selected for outbound sync.
+Use a separate local state such as `LocalState = "draft"` when a record is not yet
+complete enough to send to Acumatica.
+
+For example, a service order can remain a local draft until:
+
+- minimum required header fields are present
+- at least one detail line exists
+
+Do not overload `Remote` to mean "not ready yet". `Remote` is for sync history, not
+business completeness.
+
+## Core rule: never make Acumatica the primary save path
+
+For app data entry and edit flows:
+
+- The form saves to local tables first.
+- The save action sets sync state (`Remote = "new"` or `"dirty"`).
+- The user flow completes without depending on an immediate Acumatica round-trip.
+
+Remote writes happen later through a centralized sync action, queue, or orchestrator that scans for unsynced records and processes them consistently.
+
+Do not use an inline "save form -> immediately PUT to Acumatica" flow as the default recipe pattern.
+
+## Batch sync from local datasources
+
+The preferred outbound pattern is:
+
+1. Save locally from the form or tabs flow.
+2. Mark the row `new` or `dirty`.
+3. Select syncable rows from local SQLite with a datasource.
+4. Trigger a global sync action from the UI.
+5. Use `executeEntities(...).rest('none', 'functionCall')` with a parameter map so one
+   function call is executed per selected local row.
+
+Important:
+
+- The sync selection comes from local datasources, not live form state.
+- The sync button location is a UI choice. A header button is often the best UX for list
+  screens, but that does not change the underlying local-first pattern.
+- For lookup/reference entities, decide the required nested shape before wiring the sync.
+  Use the schemas and UI fields to propose the likely `$expand` list early, and confirm it if
+  there is ambiguity.
+- If you change the sync shape for an entity, for example by adding a new `$expand` child object,
+  unchanged remote rows will not be returned by a pure `LastModifiedDateTime` diff filter.
+  In that case either clear/rebuild the local cache for that entity, or force the sync for that
+  entity until local rows have been refreshed into the new shape.
+- During testing, prefer a separate explicit `Force Sync` UI action rather than permanently forcing
+  that entity in the normal diff-sync path. That keeps production sync incremental while still
+  giving you a controlled way to refresh cached lookup rows after shape changes.
+
+## Force Sync for lookup/reference data
+
+This is a repeatable best practice, not a one-off workaround:
+
+1. Keep the normal lookup sync incremental and diff-based.
+2. If a lookup's local shape changes, for example a new `$expand` child object is now required,
+   do not permanently set the normal sync to `force: true`.
+3. Add a separate explicit `Force Sync` action in the UI, usually in the list header.
+4. That action should re-run the lookup syncs with:
+   - `force: true`
+   - empty diff filter / full fetch semantics
+5. Use `Force Sync` during testing, rollout, or recovery when cached local rows must be rebuilt.
+
+Why:
+
+- Existing local rows may be structurally stale even when their `LastModifiedDateTime` has not changed.
+- A normal diff sync will skip those rows, so newly required nested data like expanded child objects
+  will never appear locally.
+- Permanently forcing the normal sync hides the real issue and makes production sync heavier than it
+  needs to be.
+
+Use this pattern for any cached reference/lookup entity, not just Acumatica customer locations.
+
+Example shape:
+
+```typescript
+header.actions.executeAction({
+  title: 'Sync',
+  action: 'act-sync-all',
+  icon: 'cloud-sync',
+  parameters: {
+    records: '=@ctx.datasources.syncable-records',
+  },
+  when: '=$count(@ctx.datasources.syncable-records) > 0',
+})
+```
+
+```typescript
+workflow.actions
+  .executeEntities({
+    instanceId: 'sync-records',
+    function: 'rest-put-record',
+    parameters: `=@ctx.action.parameters.records.{
+      "acumaticaURL": @ctx.datasources.data-select-config.data.acumaticaURL,
+      "accessToken": "acuerp",
+      "id": $.id,
+      "remote": $.data.Remote
+    }`,
+  })
+  .rest('none', 'functionCall')
+```
+
+## Query-time payload construction (required default)
+
+Remote functions should not depend on stale screen snapshots. The default recipe is:
+
+1. Pass identifiers and sync metadata through `parameters`
+2. Use `fn.query(...)` to fetch the latest local row at execution time
+3. Join to other local tables if necessary
+4. Use `inputTransform` to construct the exact Acumatica JSON body
+
+This is the recommended default for:
+
+- single-record sync
+- batch sync
+- parent-child aggregate sync
+
+If the Acumatica endpoint supports inline child arrays, the function can join/query the
+child rows and emit one payload. If it does not, use the parent-then-child pattern below.
+
+## Parent-child sync ordering
+
+When child records depend on a parent key assigned by Acumatica:
+
+1. Sync parent records first
+2. In the parent function, use `findReplace` / search-and-replace operations to update
+   local child references from the temporary local id/key to the Acumatica-assigned key
+3. Sync child records after the parent function completes
+
+This is the standard multi-step pattern for cases like customer -> contacts.
+
+If the endpoint supports inline child sync in one payload, that can replace the
+two-step flow. But do not assume inline child persistence just because the child array
+appears in the swagger.
+
+## Parent-first media/file upload pattern
+
+Optional attachments still follow the same local-first rule:
+
+1. Save the parent record locally.
+2. Save photo/file rows locally in a separate child table.
+3. For unsynced parents, store a temporary remote target reference on the child rows such as
+   `tmp:<localParentId>`.
+4. Sync the parent first.
+5. In the parent REST function, use `findReplace` to replace the temporary remote target on the
+   child table with the real Acumatica record id / NoteID returned by the response.
+6. Sync file rows after the parent completes.
+7. Upload files one-by-one with `executeEntities(...).rest('none', 'functionCall')`.
+
+Why:
+
+- Acumatica file upload endpoints usually require the remote parent `id` / `NoteID` in the URL.
+- There is no batch media upload pattern to rely on.
+- The file rows can remain fully local and offline-capable until the parent is remote.
+
+For sync selection, keep photo/file uploads separate from the parent datasource:
+
+- parent datasource: `Remote in ('new', 'dirty')` and business state is syncable
+- file datasource: `Remote in ('new', 'dirty')` and remote target no longer points to the
+  temporary placeholder
+
+This keeps parent record sync and child file upload retries independent.
+
+## Legacy example warning
+
+Some older or cloned projects contain direct Acumatica write calls inside business flows. Treat those as project-specific legacy implementations, not best practice.
+
+In particular, DoorPro is a useful reference for Core SDK structure, screens, local modeling, and reference-data sync, but its outbound Acumatica write pattern is not the recipe standard.
+
+### Project-specific submit actions still need explicit guards
+
+When a project intentionally keeps a direct "Send to Acumatica" submit action, keep
+the action visible and validate on press instead of silently disabling it. The user
+should get a diagnostic modal that lists every actionable blocker, for example:
+
+- the quote is not marked as `Order`
+- another quote has already been selected as the order for the appointment
+- required line items are missing
+- the PDF has never been generated
+
+If the quote is otherwise sendable but is not marked as `Order`, use a confirm
+flow instead of a hard-stop modal:
+
+1. Explain that only the active `Order` quote can be sent.
+2. Ask whether to make this quote the active order and send it now.
+3. If confirmed, set any other quote for the same appointment back to `Quote`.
+4. Set the current quote to `Order`.
+5. Regenerate the PDF before submitting, because the order type changed and the
+   previously generated PDF is now stale.
+6. If canceled, do not change quote state and do not submit anything.
+
+If the only blocker is a stale generated artifact, prefer a confirm flow:
+
+1. Warn that the PDF is outdated.
+2. Ask whether to regenerate and continue.
+3. If confirmed, regenerate inside the same sequential action list and pass the
+   fresh output URI to the submit/upload step.
+4. If canceled, do not submit anything.
+
+For future edit-lock or re-enable-editing rules, write a first-class dynamic status
+record after successful submit. At minimum store the quote id, service order id or
+number, status (`sent`), submitted timestamp, PDF URI, and quote total. Do not infer
+submission state only from the existence of a remote command queue item or PDF.
+
+### Project-specific submit retries
+
+For direct submit flows that intentionally call Acumatica from a business action,
+do not invent a parallel retry stage table if the failed calls are already in
+`_commandQueue`.
+
+Use `_commandQueue` as the retry source of truth:
+
+- Query `_commandQueue` for failed REST function commands related to the current
+  business record.
+- Include a stable business id such as `opportunityID`, quote id, or parent id in
+  the function call `parameters` so future failed command rows can be filtered back
+  to the correct screen. Extra parameters can be useful queue metadata even when the
+  REST function does not send them to the remote endpoint.
+- Display those failed rows in a dedicated error/retry tab.
+- Retry failed commands with `action.retry-queue-command`, in ascending queue `id`
+  order, so only failed calls are requeued.
+- Do not rerun successful remote steps during targeted retry. For example, if service
+  order lines succeeded and PDF upload failed, retry only the failed PDF upload command.
+- When the user starts a full submit cycle again from the main submit action, delete
+  the current quote's failed queue rows first because the user is intentionally
+  restarting the cycle. Do this after the user confirms the submit, not on validation
+  failures or canceled confirms.
+
+This keeps targeted retry and full restart separate:
+
+- **Retry tab**: requeue failed commands only, in queue order.
+- **Send action**: clear previous failed commands and start a new full send cycle.
+
+## Initial sync action
+
+A global action (`act-initial-sync`) is called from `index.onLoad`. It contains a sequential action list of `executeAction` calls to individual sync actions. This runs when the app loads for the first time.
+
+```typescript
+// app.ts — triggers on first app load
+app.onLoad.executeAction({
+  action: 'act-initial-sync',
+})
+```
+
+The initial sync action orchestrates all individual sync calls:
+
+```typescript
+const action = app.addAction({ actionId: 'act-initial-sync' })
+const workflow = action.action.list({ concurrency: 'sequential' })
+
+// Create sync scope to track all sync entities
+workflow.actions.startSyncScope({
+  instanceId: 'sync-scope-initial',
+  syncEntities: ['get-customers-diff', 'get-contacts-diff'],
+})
+
+// Individual sync calls
+workflow.actions.executeAction({ action: 'act-customers-sync' })
+workflow.actions.executeAction({ action: 'act-contacts-sync' })
+
+// Mark initial sync complete
+workflow.actions.executeEntity({ instanceId: 'mark-sync-complete' })
+  .local('SyncStatus', 'save')
+  .data({ id: 'initialSync', status: 'complete', completedAt: '=$now()' })
+```
+
+This initial sync pattern is for inbound/reference-data sync. Do not mix outbound business-record submission into this app-start flow.
+
+For standalone test apps, it is useful to wire the same initial-sync action to a root screen's pull-to-refresh event so testers can retry reference-data sync without killing and reopening the app:
+
+```typescript
+const refreshActions = screen.onRefresh.list({
+  instanceId: 'refresh-reference-data',
+  concurrency: 'sequential',
+}).actions
+
+refreshActions.executeAction({
+  instanceId: 'refresh-run-initial-sync',
+  action: ACTION.INITIAL_SYNC,
+})
+```
+
+If the app seeds local mock data during `app.onLoad`, repeat that seed step before the refresh sync. Keep this to test/mock entry screens unless the production app intentionally supports manual reference-data refresh from that screen.
+
+### REST-backed local reference tables
+
+Large reference tables or matrix tables can be synced into local SQLite tables through REST instead of Dynamic Data. Use this when the table is too large for comfortable Dynamic Data imports or when you want a backend to own compression, seeding, and paging.
+
+Recommended pattern:
+
+- Define the table as a local entity, for example `doorMatrixItems`, not `default/doorMatrixItems`.
+- Expose a REST endpoint that accepts `$top` and `$skip` and returns rows with stable `id` fields.
+- Keep the row shape identical to the Dynamic Data shape so datasources can switch between local REST and Dynamic Data later.
+- Authenticate the REST endpoint with the Jigx token by adding an `accessToken` header parameter with `type: jigx` and `value: jigx`.
+- Validate that token in the backend against Jigx Strata before returning rows.
+- Accept both `Authorization: Bearer <token>` and raw `Authorization: <token>` on custom backends. Jigx mobile can send the token as the `Authorization` header value without the `Bearer` prefix even when the function parameter is named `accessToken`.
+- Add the REST sync action to the global initial-sync action before any dropdowns or indexes that depend on the table.
+- Create SQLite expression indexes after sync for every JSON field used by high-cardinality filters, joins, or sorted dropdowns.
+
+Use continuation for paging:
+
+```typescript
+fn.continuation.when('=$count(@ctx.output.data) = $number(@ctx.output.top)')
+fn.continuation.parameters.query('$skip', {
+  value: '=$number(@ctx.output.skip) + 5000',
+  type: 'number',
+  required: true,
+})
+```
+
+Keep the backend and mobile batch sizes aligned. A batch size of 5000 works well for large local SQLite matrix sync when the payload remains within practical mobile memory and network limits.
+
+## Sync scopes — tracking sync progress
+
+Jigx tracks sync entity calls via **sync scopes**. Each sync entity gets an `instanceId`. A sync scope groups them and tracks their state.
+
+### _syncScope system table
+
+The `_syncScope` table is a system table with actual columns (not id/data pattern):
+
+| Column | Type | Description |
+| --- | --- | --- |
+| `id` | string | Sync scope identifier |
+| `state` | string | `synced`, `syncing`, `failed`, `notStarted` |
+| `synced` | number | Count of synced entities |
+| `syncing` | number | Count of currently syncing entities |
+| `failed` | number | Count of failed entities |
+| `notStarted` | number | Count of not-started entities |
+| `lastStartedAt` | number | Timestamp of last start |
+| `lastSyncedAt` | number | Timestamp of last successful sync |
+| `lastFailedAt` | number | Timestamp of last failure (null if none) |
+| `details` | string | JSON object with per-entity state: `{"get-customers-diff": {"state": "synced"}}` |
+
+### Using sync scopes for integrity
+
+- Check if initial sync completed: query SyncStatus table for `initialSync` record
+- Check if sync was interrupted: `_syncScope.state = 'syncing'` with `syncing > 0`
+- Resume interrupted sync: re-call the initial sync action on next app load
+- Track per-entity failures: parse `details` JSON for individual entity states
+
+## Sync status tracking
+
+Track sync progress in a local `SyncStatus` table:
+
+```yaml
+# SyncStatus record
+id: 'initialSync'
+status: 'syncing' | 'complete' | 'failed'
+currentStep: 'Syncing Customers...'
+currentProgress: 2        # current step number
+totalSteps: 5             # total steps
+completedAt: '2026-04-06T...'
+```
+
+The initial sync action updates this record at each step — see `act-initial-sync` in the reference implementation.
+
+### Sync integrity ideas to consider
+
+- **Detect interrupted sync**: On app load, check if `_syncScope.state = 'syncing'` with `syncing > 0` — means a previous sync didn't finish. Re-trigger the sync.
+- **Detect failed sync**: Check `_syncScope.failed > 0` or `SyncStatus.status = 'failed'`. Show a retry option to the user.
+- **Resume vs restart**: If only some entities failed (check `details` JSON per-entity state), consider resuming from the failed entity rather than restarting the full sync.
+- **First-time detection**: Check if `SyncStatus` has an `initialSync` record with `status = 'complete'`. If not, the app has never completed initial sync — block UI or show onboarding.
+
+See [pattern-sync-progress.md](pattern-sync-progress.md) for UI patterns to display sync progress.
+
+## Outbound sync orchestration
+
+For records created or edited in the app:
+
+1. Save the record locally.
+2. Mark `Remote` as `"new"` or `"dirty"`.
+3. Let a centralized sync action select unsynced records.
+4. Call the Acumatica REST function from that centralized sync workflow.
+5. On success, merge the response locally and set `Remote` to `"remote"`.
+6. On failure, keep the local record and leave it unsynced for retry/diagnostics.
+
+Recommended separation of concerns:
+
+- **Forms/screens** own local validation and local persistence.
+- **REST functions** own request/response shaping.
+- **Central sync actions** own record selection, ordering, retries, and failure handling.
+
+This separation is the reason the Acumatica REST recipe uses `id` + query-time fetch rather than passing the entire record payload from the jig.
+
+## REST GET functions for sync
+
+Define a REST GET function for each entity to sync. The function fetches records from the remote system and stores them locally via `forRowsWithMatchingIds` + `records`.
+
+### Acumatica-specific: REST vs OData differences
+
+Acumatica exposes two API styles. Use REST endpoints where possible — the response is already nested and matches the local schema.
+
+| Aspect | REST endpoint | OData endpoint |
+| --- | --- | --- |
+| URL config field | `acumaticaURL` | `acumaticaOdataURL` |
+| Response format | Nested JSON with `.value` wrappers | Flat fields |
+| Records location | Top-level array (`@ctx.response.body`) | Under `value` array (`@ctx.response.body.value`) |
+| outputTransform | Simple — add `id` + `Remote` | Complex — reshape flat → nested with `.value` wrappers |
+| Date handling | ISO format with timezone | Needs timezone conversion (hard-code or from config) |
+| Counting for continuation | `$count(@ctx.output.data)` | `$count(@ctx.output.data)` (after transform) |
+
+For non-Acumatica systems, the same patterns apply — just adapt the URL, auth, response format, and outputTransform to match the API.
+
+### REST GET function pattern
+
+```typescript
+const fn = app.addFunction.rest({
+  functionId: 'rest-get-contacts',
+  method: 'GET',
+  url: 'https://{acumaticaURL}Contact?$filter=(BusinessAccount ne null) and (BusinessAccount ne \'\')',
+  useLocalCall: true,
+})
+
+fn.params.path('acumaticaURL', { required: true })
+fn.params.header('accessToken', 'acuerp', { required: true, type: 'acuerp' })  // Acumatica-specific: acuerp OAuth
+fn.params.query('$top', { value: '1000', type: 'string', required: true })
+fn.params.query('$skip', { value: '0', type: 'string', required: true })
+fn.params.query('$filter', { type: 'string', required: false })    // Used for diff sync
+fn.params.query('$expand', { type: 'string', required: false })    // Acumatica-specific: expand child objects
+```
+
+**Acumatica-specific**: `accessToken` with type `acuerp` triggers Jigx OAuth for Acumatica. `$expand` requests child objects in the response. For other systems, replace with the appropriate auth and query parameters.
+
+### outputTransform
+
+The outputTransform normalizes the API response for local storage and wraps it for continuation tracking. It must produce `{ top, skip, data }` where `data` is the record array.
+
+```yaml
+outputTransform: |
+  ={
+    "top": @ctx.parameters."$top",
+    "skip": @ctx.parameters."$skip",
+    "data": $map(@ctx.response.body, function($item){
+      $merge([$item, {"id": $item.CustomerID.value}, {"Remote": "remote"}])
+    })
+  }
+```
+
+The `$merge` adds an `id` field (mapped from the API's key field) and `Remote: "remote"` to mark records as synced.
+
+**Acumatica-specific**: For REST endpoints, the response is already nested with `.value` wrappers — the transform is simple. For OData endpoints, the response is flat and needs complex reshaping to match the schema. OData dates also need timezone conversion (see OData section below). The `id` is mapped from `CustomerID.value` (Customer) or `ContactID.value` (Contact) — each Acumatica entity has its own key field.
+
+### records and forRowsWithMatchingIds
+
+```yaml
+records: =$.data
+forRowsWithMatchingIds: true
+```
+
+`forRowsWithMatchingIds: true` updates existing rows matched by `id` instead of replacing all rows. Essential for diff sync — only changed records are updated.
+
+`records` points to the array of records from the outputTransform.
+
+## Continuation — paginating large datasets
+
+For large datasets, Jigx supports automatic pagination via the `continuation` block on REST functions.
+
+### How it works
+
+1. First call uses initial `$top` and `$skip` values (e.g., 1000 and 0)
+2. After response, the `when` condition checks if the returned count equals `$top`
+3. If true, Jigx makes another call with updated parameters (incrementing `$skip`)
+4. Repeats until `when` is false (fewer records returned than `$top`)
+
+### REST continuation pattern
+
+```yaml
+continuation:
+  parameters:
+    $filter:
+      location: query
+      required: false
+      type: string
+    $skip:
+      location: query
+      required: true
+      type: number
+      value: =$number(@ctx.output.skip) + 1000
+    $top:
+      location: query
+      required: true
+      type: number
+      value: 1000
+    accessToken:
+      location: header
+      required: true
+      type: acuerp
+      value: acuerp
+    acumaticaURL:
+      location: path
+      required: true
+      type: string
+  url: https://{acumaticaURL}Contact?$filter=(BusinessAccount ne null) and (BusinessAccount ne '')
+  when: =$count(@ctx.output.data) = $number(@ctx.output.top)
+```
+
+Key points:
+- All original parameters are redeclared in the continuation block
+- `$skip` increments by the `$top` value each iteration
+- `$filter` preserves its original value from the first call
+- `when` compares output record count to requested top — stops when fewer records returned
+- `url` must be repeated in the continuation block
+- Use `@ctx.output` (not `@ctx.response.body`) to access the transformed output
+
+### Recommended batch sizes
+
+~1000 records per batch works well. **Acumatica-specific**: Acumatica performs well with 1000-record batches for REST and up to 10000 for OData. Adjust based on the system's rate limits and payload sizes.
+
+## Diff sync — fetching only changes
+
+After initial sync, subsequent syncs should only fetch records modified since the last sync. The approach: find the latest timestamp in local data, then ask the remote system to return only records changed after that time.
+
+### Max last-modified datasource
+
+```typescript
+app.addDatasource
+  .sqlite({ datasourceId: 'data-select-customers-max-last-modified', provider: 'local' })
+  .entity('Customers')
+  .query("SELECT max(json_extract(data, '$.LastModifiedDateTime.value')) as LastModifiedDateTime FROM [Customers]")
+```
+
+Note: this datasource does NOT use `jsonProperties` — it returns a computed scalar, not an `id`/`data` row.
+
+### Passing the filter to the sync action
+
+The filter is built conditionally — empty on initial sync (no local data), populated on subsequent syncs:
+
+```yaml
+# In the sync action's parameters:
+$filter: >
+  =@ctx.datasources.data-select-customers-max-last-modified.LastModifiedDateTime
+  ?
+    "(LastModifiedDateTime gt datetime'" & @ctx.datasources.data-select-customers-max-last-modified.LastModifiedDateTime & "')"
+  :
+    ""
+```
+
+If no records exist yet (initial sync), the filter is empty — fetches all records. On subsequent syncs, only records modified after the latest local timestamp are fetched.
+
+**Acumatica-specific**: Both REST and OData endpoints accept the `$filter` query parameter with OData filter syntax. Important difference in date type keyword:
+
+- **REST endpoints**: Use `datetimeoffset` — fields are `Edm.DateTimeOffset`
+  ```
+  (LastModifiedDateTime gt datetimeoffset'2026-04-06T05:07:00.397+00:00')
+  ```
+- **OData endpoints**: Use `datetime` — fields are `Edm.DateTime`
+  ```
+  (LastModifiedDateTime gt datetime'2026-04-06T05:07:00')
+  ```
+
+Using the wrong keyword causes a 500 error: `"A binary operator with incompatible types was detected"`. The field name may vary by endpoint — check the schema.
+
+For other systems, adapt the filter format to match their API (e.g., `?since=2026-04-05T10:30:00Z`, `?modified_after=...`).
+
+### Custom REST diff sync
+
+For custom REST services that are not OData, keep the same local-max pattern but pass the
+timestamp as the API's expected query parameter instead of building an OData `$filter`.
+
+Example:
+
+```typescript
+app.addDatasource
+  .sqlite({ datasourceId: 'data-select-matrix-max-last-modified', provider: 'local' })
+  .entity('matrixItems')
+  .query(
+    `SELECT max(coalesce(
+      json_extract(data, '$.lastModifiedDateTime'),
+      json_extract(data, '$.createdDateAndTime')
+    )) as lastModifiedDateTime FROM [matrixItems]`,
+  )
+```
+
+Then pass that value into the REST sync function:
+
+```typescript
+parameters: {
+  lastModifiedDateTime:
+    '=@ctx.datasources.data-select-matrix-max-last-modified.lastModifiedDateTime ? @ctx.datasources.data-select-matrix-max-last-modified.lastModifiedDateTime : ""',
+  $top: 5000,
+  $skip: 0,
+}
+```
+
+The custom endpoint should return only rows where its modified timestamp is greater than
+the supplied value, and should include the row's `lastModifiedDateTime` in each returned
+record so the next sync can compute a new local max. Preserve the same
+`lastModifiedDateTime` parameter in continuation requests while incrementing `$skip`.
+
+## Acumatica-specific: OData timezone handling
+
+OData responses from Acumatica use a different datetime format than REST. A timezone conversion function is needed in the outputTransform:
+
+```jsonata
+$tz := "+02:00";
+$tzSign := $substring($tz, 0, 1) = "-" ? -1 : 1;
+$tzH := $number($substring($tz, 1, 2));
+$tzM := $number($substring($tz, 4, 2));
+$tzOffsetMs := $tzSign * ($tzH * 60 + $tzM) * 60 * 1000;
+$pic := "[Y0001]-[M01]-[D01]T[H01]:[m01]:[s01].[f001]";
+$fmtDT := function($d) {
+  $d ? $fromMillis($toMillis($d & "Z") + $tzOffsetMs, $pic) & $tz : undefined
+};
+```
+
+Ideally, store the timezone value in the config table and fetch it via a query in the function, rather than hardcoding.
+
+## Error handlers for GET functions
+
+GET sync functions use a similar error handler set as PUT functions but with additional handling:
+- **Status 0**: Connection error — device is offline
+- **Status 400**: Bad request — invalid filter syntax
+- **Status 500**: Server error — Acumatica internal error
+- Longer retry delays for 429/504 (16s vs 5s) since sync is background work
+
+See [pattern-rest-acumatica.md](pattern-rest-acumatica.md#error-handlers-for-rest-put-functions) for the shared error handler pattern.