Fieldmotion API Getting started

Digital Waste Tracking

Create the standard waste receipt Forms

POST /a/DigitalWasteTracking_formCreate

Create a configured Job Form and linked waste-item table with stable receipt field IDs.

When to use this endpoint

Use as a starting template, then inspect its fields/mapping and receiving-site choices. It creates new Forms every time; it does not find or reuse an earlier template.

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 Forms Edit through Core_requirePermission('edit', 'pageForms'), including this configuration read.

Parameters

This endpoint has no operation-specific parameters.

Example request

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

Example response

{
  "ok": 1,
  "id": 410,
  "table_form_id": 411
}

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":"form edits are disabled for this account"}The shared Form edit lock applies.
{"error":"permission denied"}The required page action is absent; the shared permission helper retains its legacy roleless fallback.
{"error":"Unable to save Digital Waste Tracking data. Reload before retrying."}A Form/link/audit write or commit failed.

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

Behaviour and edge cases

  • Mutations also honour features2.disableFormEdits through the shared Form helper; temporary Form-editor identities retain that helper’s exception. Reading configuration does not invoke this edit lock.
  • Creates Digital Waste Receipt Items first (Form type 3), then Digital Waste Receipt (type 0). Both use report_type=1 and portal_visibility=1; generated fields have required=0, report=1, hidden=0 and readonly=0. Stable field IDs are generated from milliseconds, monotonically within the request.
  • The main Form includes receiving-site override, receipt time, carrier/broker contacts and registration, transport/vehicle, consignment/reason, special handling, movement references and a Waste Items subform. The table covers the sixteen allowed waste mappings, including weight, POPs, hazards and disposal/recovery codes.
  • Enables digital_waste_tracking metadata, stores the current account default profile ID and maps all generated fields/table IDs. Receiving Site Override is a Select containing active profile name:id lines. Later profile changes need profileChoicesSync.
  • Both Form insert IDs, child parent-link metadata and creation history are checked in one transaction. Failure at any step rolls back the pair rather than leaving a partial template. Successful repeated requests still create independent Form pairs; there is no creation idempotency key.
  • Mutations use a checked tenant PDO transaction with the tenant-owner lock, preserving a caller’s savepoint. Writes and history commit together; a failed write/audit rolls back. A controlled save error asks callers to reload before retrying. No migration or deletion-lifecycle change is included.

Side effects

  • Creates two Forms, synchronizes parent links, invalidates Forms cache and logs creation. No Job or provider receipt is created.

See it in Fieldmotion

CRM1

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

CRM2

Settings > Digital Waste Tracking > Create receipt form calls DigitalWasteTracking_formCreate; the returned id opens the new Job Form editor.

Related endpoints