Fieldmotion API Getting started

User roles

Update one user-role field

POST /a/UserRole_updateField

Apply one mapped value to one or more user roles as a client administrator.

When to use this endpoint

Use UserRole_updateField only for trusted administrator bulk edits. CRM2’s normal role screens use UserRole_updateData.

Authentication and permissions

The acting user must be a client administrator. This check runs before Core_requireLogin, so unauthenticated/non-admin requests return {"error":"not an admin"}.

No pageUserRoles_edit role-permission check is made once the administrator test passes.

Parameters

ParameterTypeRequiredDescription
id / idsInteger string or native arrayYesOne role ID or a native list. id wins if both keys are present; missing IDs are ignored.
fieldMapped keyYesOne of id, name, cDate, or lastEdited. The map does not stop callers from changing the primary ID.
valScalarYesReplacement value. Blank is accepted for quoted fields; Unix timestamps accept numeric values or date text.

Example request

$result = FM_api('UserRole_updateField', [
	'id' => '12',
	'field' => 'name',
	'val' => 'Senior dispatch supervisor',
]);

Example response

{
  "ok": 1,
  "oldData": [
    {"id": "12", "name": "Dispatch supervisor"}
  ]
}

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":"not an admin"}The acting context is not a client administrator.
{"error":"missing or invalid parameter: field"}field is absent.
{"error":"missing or invalid parameter: val"}val is absent.
{"error":"missing or invalid field"}The field is not mapped.
{"error":"missing or invalid parameter: id/ids"}Neither target key is present.

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

Behaviour and edge cases

  • No matching row or all-equal values return {"ok":"1","warning":"no change required"} with a string success value.
  • Changed rows automatically receive current Unix last_edited; this overrides a direct lastEdited value.
  • The response’s oldData contains raw ID plus the pre-update storage value for matching rows.

Side effects

  • Updates matching roles, invalidates the user-roles cache, and writes one generic audit event covering changed IDs.
  • Does not change role access or assigned users.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found.

CRM2

No direct production caller was found; normal CRM2 editing uses UserRole_updateData.

Related endpoints