Fieldmotion API Getting started

Digital Waste Tracking

Queue completed waste receipts

POST /a/DigitalWasteTracking_queue

Validate and queue up to 50 distinct Jobs while reporting per-Job failures.

When to use this endpoint

Use for bulk new-receipt submission from Operations. This queues work rather than submitting every receipt in the web request, and does not queue explicit updates to an existing receipt.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session; session dispatch applies CSRF checks. The authenticated tenant must have features2.ukDigitalWasteManagement=1. The feature is read from the account record, not trusted from request input.

Requires Jobs Edit through Core_requirePermission('edit', 'pageJobs').

Job reads and mutations enforce the authenticated tenant, active Job, TeamAccess department/assignment scope and the legacy department-based customer boundary. Collections filter before counts/pagination; explicit Job and cancellation requests check access before a service call or queue mutation.

Parameters

ParameterTypeRequiredDescription
job_idsNative array or JSON array textYes in practiceOmission becomes []; values are intval-converted, nonzero-filtered and deduplicated. Between 1 and 50 distinct nonzero values must remain. Negative IDs reach the lookup and fail per Job.

Example request

$result = FM_api('DigitalWasteTracking_queue', [
	'job_ids'=>'[1042, 1043]',
]);

Example response

{
  "ok": 1,
  "queued": [
    1042
  ],
  "errors": {
    "1043": "job_not_complete"
  }
}

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":"UK Digital Waste Tracking is not enabled for this account"}The account feature is disabled.
{"error":"invalid job IDs"}job_ids JSON is invalid or not an array.
{"error":"select between 1 and 50 jobs"}No nonzero unique IDs remain, or more than 50 remain.
{"error":"permission denied"}The required page action is absent; the shared permission helper retains its legacy roleless fallback.
{"error":"job not found or outside your record scope"}The explicit Job or queue’s Job is missing, deleted or hidden by record scope. Bulk queueing reports this per Job.

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

Behaviour and edge cases

  • An optional warnings map is keyed by Job ID when queueing succeeded but service/CRM history follow-up failed. Those Jobs remain in queued; reload rather than queueing a replacement to repair history.
  • The CRM forwards this operation to its signed on-complete service with the tenant and actor installed server-side. A caller cannot choose another tenant. Missing service configuration returns Digital Waste Tracking service is not configured; a non-JSON service reply returns Digital Waste Tracking service returned an invalid response.
  • Each Job is sent independently to the signed queue-only submission protocol. It resolves profile/data, requires Complete/Processed, validates structural/fresh reference rules and checks receipt state. There is no whole-batch transaction: successful earlier Jobs remain queued when another fails.
  • queued contains Job IDs, not cron queue IDs. errors is keyed by Job ID and contains error strings. Empty PHP associative results may serialize as []; callers must tolerate errors=[] as well as an object. Already queued and already submitted Jobs appear under errors as already_queued/already_submitted, rather than being repeated in queued.
  • The service stores global cron type 102, tenant/Job IDs and metadata {profile_id,actor_id,attempt,reason,request_hash}; it does not persist the raw receipt/API code in the queue. The Job-row transaction/marker checks coordinate queueing against cross-replica submission.
  • The worker re-previews and rejects changed hashes before send, claims only pending work, and passes expected_hash through the signed service. Safe retryable failures get at most four delayed retries (60, 300, 900, 3600 seconds plus jitter/provider Retry-After). Ambiguous outcomes stop for review instead of blind retry.
  • Queue validation can perform reference HTTP calls. queue_only is evaluated before a reference-error return, so structurally valid work can be queued even if reference acquisition failed; the worker must handle its later preview/submission result.

Side effects

  • Creates pending global queue rows and service/CRM Job history for successful items. A worker later sends provider receipts and creates mappings/notices. No all-or-nothing batch rollback.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found in the production JavaScript source. The operator workflow is implemented in CRM2.

CRM2

Digital Waste Tracking > Operations > select rows > Queue submissions sends job_ids as JSON and displays the queued count. CRM2 displays the per-Job errors and follow-up warnings alongside the queued count; warnings identify work already queued and must not trigger replacement submissions.

Related endpoints