When to use this endpoint

Use Data Sync settings to clear a queue that has not been claimed. There is no ID parameter: cancellation is tenant-wide. If any unfinished instruction is already received by an agent, the whole request is refused; wait for completion or investigate the agent.

Authentication and permissions

Use signed API-key authentication or a logged-in CRM session on the account’s routed host. API keys act as their owner; session requests require the dispatcher’s CSRF token where configured. Tenant rows and settings belong to that authenticated account.

These handlers add no accounting page or CRM2 role check. The dispatcher has no Accounting/DataSync object-scope mapping. Settings-screen access controls are separate from these shared API handlers; CRM2 screen roles are not a CRM1 API requirement.

Parameters

This endpoint has no operation-specific parameters.

Example request

$result = FM_api('DataSyncs_cancelRun', []);

Example response

[
  "ok"
]

Database numeric values can be strings. Read the JSON error/warning fields as well as the HTTP status.

Errors and unusual responses

ResponseCondition
{"error":"not logged in"}No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
{"error":"DataSync settings are busy. Please try again."}Another tenant DataSync mutation owns the lease.
{"error":"Unable to save DataSync changes. Please reload before retrying."}A transaction/read/write/commit failed. Reload saved state before retrying.
{"error":"An accounting agent is already processing an instruction. Wait for it to finish before cancelling."}An unfinished instruction is already claimed or has an unexpected nonzero status.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • Returns the legacy one-element JSON array ["ok"], not an object with ok:1.
  • Updates unfinished datasync_instructions to status 2 and done_date=Unix now. Sets locked=0 and last_edited=Unix now for all datasyncs rows, including those without an unfinished instruction.
  • This is local queue-state cancellation. Under connection/instruction row locks, any unfinished status other than 0 refuses the whole cancellation and preserves locks. The Data Sync service claims instructions under the same connection lock. It does not terminate a process, cancel cloud sync, revoke credentials or roll back accounting writes.
  • Uses a tenant mutation lease and a checked database transaction. Queue, mapping and connection-creation writes commit together or return an error with rollback. Busy requests must be retried after reloading; an uncertain commit requires a fresh read before retrying.

Side effects

  • Atomically marks unclaimed instructions status 2 with done_date=Unix now, unlocks saved DataSync connections and advances last_edited. A claimed instruction leaves all rows unchanged; both CRM clients display the refusal and retain the confirmation dialog.

See it in Fieldmotion

CRM1

Open Settings → Data Sync. The pageSettingsDataSync screen uses this route for the operation described above; filter browser Network requests by the exact function name. Local-agent setup is separate from the cloud Finance integrations. Choose Cancel Run and confirm; the UI sends no connection selector.

CRM2

Open Settings → Data Sync. The CRM2 pageSettingsDataSync screen retains this local-agent workflow; filter browser Network requests by the exact function name. Its screen permissions do not add a role check to this shared handler. Choose Cancel Run and confirm; the UI sends no connection selector.

Related endpoints