Fieldmotion API Getting started

Departments

Set department assets

POST /a/Department_setAssets

Replace a department’s legacy asset-ID list and mirror additions/removals into each affected asset.

When to use this endpoint

Use Department_setAssets for the CRM1 Departments table’s asset picker. CRM2 writes the department’s mapped assets field directly and does not call this reciprocal updater.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler performs no additional page or role-permission check.

The lookup and any write use the authenticated tenant; an ID from another tenant cannot be addressed through this call.

Parameters

ParameterTypeRequiredDescription
idInteger stringYesDepartment ID after integer conversion; it must be greater than zero.
valsStringYes in practiceComma-separated IDs or JSON-looking numeric array text. Every character except digits and commas is removed before splitting. Use [] to clear the list.

Example request

$result = FM_api('Department_setAssets', [
	'id' => '42',
	'vals' => '[51,52]',
]);

Example response

{
  "oldIds": ["50"],
  "ok": 1
}

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":"missing or invalid parameter: id"}The department ID is absent or integer-converts below 1.
Runtime warning or type errorvals is absent or supplied as a native array rather than text. The handler reads and transforms it without validating its shape.

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

Behaviour and edge cases

  • The sanitizer turns both 51,52 and [51,52] into the same two IDs. Nonnumeric text is discarded rather than rejected.
  • oldIds is the previous department value after the same character stripping/splitting; an empty old value is returned as [""].
  • Assets newly present in vals gain the department ID in their comma-separated departments column. Removed assets have that ID removed.

Side effects

  • Updates affected assets’ departments, last_edited, and edited_uuid. Only the removal branch explicitly advances the assets cache marker.
  • Replaces the department’s assets string, but does not update its last_edited, invalidate its cache, or write audit history.

See it in Fieldmotion

CRM1

Open Users → Departments and edit the Assets cell. The chosen array is serialized and sent as vals.

CRM2

CRM2’s Departments page edits assets via Department_updateData, which does not update asset rows.

Related endpoints