Fieldmotion API Getting started

Display-layout groups

Set one display-layout header field

POST /a/LayoutGroup_updateField

Set one mapped display-layout header field across selected groups

When to use this endpoint

Use for a one-field batch edit where each selected group receives the same value. Header updates run through the checked mapped updateData path inside one tenant transaction/savepoint, with history per changed group. Values use field/val, and the reply includes pre-write rows. It is not a field-tree editor.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Mutations require the client-administrator bit checked by Core_isClientAdmin (including the tenant-owner fallback), not merely access to the Display Layout Dashboard screen. The handlers also require login; create/update/delete check administrator status before their login guard, while copy checks login first.

Groups belong to the authenticated tenant. No per-group ownership, userID, department or page-role restriction is added. userID is a stored field, not an authorization boundary. No tenant feature toggle is consulted by these handlers.

Parameters

ParameterTypeRequiredDescription
fieldStringYesExact writable map key: userID, name, tableName, createdate, lastEdited, metaModalSize, meta, metaType. Unknown keys and id fail; the selector cannot be used to change primary IDs.
valField-dependentYesNew value, not value. Null counts as missing; empty required name/tableName values fail through mapped update validation. Numeric fields integer-convert, timestamps accept Unix seconds or server-parsed dates, meta accepts an object/valid JSON text, metadata-key fields merge that key. No map-level length bound is configured.
id / idsScalar or request arrayOneid wins when present/non-null, otherwise ids. Supply positive integer scalars or a nonempty native array of positive integers; malformed values, zero/negative IDs and JSON-encoded array strings fail. IDs are deduplicated; existing rows are locked and processed in ascending ID order. Missing IDs are omitted.

Example request

$result = FM_api('LayoutGroup_updateField', [
	'ids' => ['1042', '1088'],
	'field' => 'metaModalSize',
	'val' => 'modal-xl',
]);

Example response

{"ok":1,"oldData":[{"id":"1042","meta":"{\"type\":\"0\",\"modalSize\":\"modal-lg\"}"}]}

oldData contains existing selected rows before modification, not only changed rows. Each has id and the underlying column (meta for metadata keys), not the alias. A missing/all-unchanged selection can return {"ok":"1","warning":"no change required"}; that legacy no-op ok is a string.

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":"you are not an admin"}Not a client administrator.
{"error":"Unable to complete layout group operation. Check the saved state before retrying."}A transaction/read/write/commit failure prevents confirmed completion; inspect saved state before retrying an uncertain response.
{"error":"missing or invalid parameter: field"}field absent/null.
{"error":"missing or invalid parameter: val"}val absent/null.
{"error":"missing or invalid field"}Unknown field key.
{"error":"missing or invalid parameter: id/ids"}Neither non-null selector supplied.
{"error":"Unable to update record"}A mapped row UPDATE fails; earlier edits in this operation are rolled back.
{"error":"missing or invalid parameter: name"}A required name/tableName value is empty; invalid timestamps return invalid date errors naming the mapped field.

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

Behaviour and edge cases

  • Mapped updateData normalizes numeric values and compares metadata values before deciding whether a change is needed. Changed rows receive current Unix-second last_edited; no-op rows are not logged as edits.
  • Both direct-column and metadata-key edits run once per existing row inside a tenant transaction, using a savepoint when the caller already has one. A later failed write rolls back earlier group edits/history from this operation. There is no optimistic timestamp token, and missing IDs alone are a successful no-op.
  • No direct mobile-app or m-service caller for this family was found. These groups configure CRM display layouts; they are not reusable document presets, form definitions, or a tenant-wide change to existing business-object data.

Side effects

  • Updates the chosen column/key plus last_edited, requests layout_groups cache invalidation and calls the existing mapped Core_log history path for each changed group with a scalar target ID. Child layouts and screen-default assignments are not changed.

See it in Fieldmotion

CRM1

No production CRM1 caller for this layout-group family was found in client source. The administration workflow described here is CRM2; API tests and fixture setup are not evidence of a CRM1 screen.

CRM2

No direct production caller for LayoutGroup_updateField was found. CRM2’s Display Layout Dashboard edits headers through the mapped updateData helper instead; endpoint tests currently guard missing-parameter/admin responses.

Related endpoints