Refresh receiving-site Form choices

When to use this endpoint

Run after receiving-site creation, rename or archive. Save profile_override_field_id on the Form first; this endpoint does not choose/create the override field.

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

Parameter	Type	Required	Description
`form_id`	Integer-compatible	Yes	Existing non-archived type-0 Job Form with a saved override field mapping. The target field must be Select.

Example request

$result = FM_api('DigitalWasteTracking_profileChoicesSync', [
	'form_id'=>'410',
]);

Example response

{
  "ok": 1,
  "choices": [
    "North receiving site:aaaaaaaaaaaaaaaa"
  ]
}

Errors and unusual responses

Response	Condition
`{"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":"save an override field mapping first"}`	No override field ID is saved.
`{"error":"the override field must be a Select field"}`	The matching field exists but has another type.
`{"error":"override field not found"}`	The stable ID is no longer in the Form.
`{"error":"invalid form ID"}`	The converted ID is zero.
`{"error":"permission denied"}`	The required page action is absent; the shared permission helper retains its legacy roleless fallback.

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.
Finds the override by its stable meta.id and requires its actual type to be select. Replaces extras.values with newline-separated name:id choices for active profiles, in stored profile order. Empty active catalogue produces an empty choice list.
Preserves the field identity and the remaining Form definition/metadata. Existing Job answer values are not rewritten; profile resolution splits a saved answer on colons and uses its final ID component, so renamed labels keep identity.
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

Atomically replaces the mapped Select options, stamps last_edited, invalidates Forms cache and records checked history. It does not change saved Job answers.

See it in Fieldmotion

CRM1

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

CRM2

Forms > Job Form > Digital Waste Tracking > Sync choices calls DigitalWasteTracking_profileChoicesSync after selecting/saving the override field.

Related endpoints

DigitalWasteTracking_formConfigSave — Choose a valid main override field first.
DigitalWasteTracking_profileSave — Save a site before adding it to select choices.
DigitalWasteTracking_formConfigGet — Reload stable field identities/configuration.