Display-layout groups
Update display-layout headers
/a/LayoutGroup_updateData
Revise several fields on one or more display-layout headers
When to use this endpoint
Rename a group, change its modal size, or revise header metadata without replacing the field tree. The dashboard edit action uses this route. Editing the field tree instead uses Layouts_saveField; changing tableName here does not convert existing field rows.
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
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Scalar or request array | Yes | One ID or a native array of IDs. Scalars integer-convert; arrays are processed sequentially, not in a transaction. No positive-ID validation is added. id is the selector, not an editable field. |
name / tableName | Strings | For create | Group name and main-table map key (for example customer). Creation requires non-null, nonempty strings, but does not trim whitespace; update validates a supplied empty value, not omitted fields. No table-key allowlist, uniqueness check or explicit length bound is configured in the map, although the representative schema has 100-character columns. |
userID | Integer | No | Integer-converted stored user_id; defaults to 0 on creation. Not automatically set to the acting user and not used to restrict getList. |
metaModalSize / metaType | Text values | No | Individual keys modalSize and type within meta. CRM2 uses modal-lg or modal-xl and type 0 (Layout) or 1 (Table List); the server does not allowlist these values. Keys are merged into the stored metadata object rather than replacing the other keys. |
meta | JSON object or JSON text | No | Whole metadata column, not a merge. A request array/object is serialized; when sending text, supply valid encoded JSON. No metadata schema validation is performed. Map order matters when combined with individual keys: metaModalSize runs before whole meta and can be overwritten; metaType runs after it. Prefer one complete meta object or individual keys, not a mixture. |
createdate / lastEdited | Unix seconds or parseable datetime | No | Mapped timestamp fields. Creation defaults both to now; numeric values are used directly and nonnumeric datetime strings use PHP server-timezone parsing. Blank maps to 0. Readonly map labels are UI hints, not write protection. A changed updateData/updateField stamps last_edited automatically; do not use lastEdited as a concurrency token. |
Example request
$result = FM_api('LayoutGroup_updateData', [
'id' => '1042',
'name' => 'Customer summary',
'metaModalSize' => 'modal-xl',
]);Example response
{"ok":1}For a scalar ID, no changed values returns {"warning":"No Change."}; no selected row returns {"warning":"No data."}; only unknown supplied fields returns {"warning":"no updated fields."}. An ID-only request can return ok without a row lookup. These warnings need not include ok.
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":"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: id"} | id missing/null. |
{"error":"missing or invalid parameter: name"} | A supplied required text field is empty; tableName has the analogous error. Omitted fields are not required on update. |
{"error":"Unable to update record"} | The row UPDATE returns false. For ID arrays an error also includes updatedIds (earlier attempted IDs) and failedId. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Omitted/null keys are left unchanged. Only mapped supplied fields are updated; metadata key setters retain other keys while whole meta replaces them. Changed rows receive current Unix-second last_edited. There is no optimistic locking.
- Multiple IDs are processed in request order. Only an error stops the loop; missing-row/no-change warnings are not errors and the final bulk reply is simply ok=1. Earlier changes are not rolled back, and updatedIds denotes earlier attempts rather than proof each one changed.
- The map’s readonly flags do not prohibit writing createdate through updateData. Supplying lastEdited alongside changed fields can conflict with the helper’s automatic timestamp assignment; omit it in normal requests.
- 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 layout_groups, invalidates that table’s cache and logs changed mapped fields through Core_log. Does not rewrite child layouts, reassign page defaults, emit email or schedule work. History/log writes occur after the main write without a handler-level transaction.
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
Open CRM2 Settings → Display Layout Dashboard (pageSettingsDisplayLayouts). Its create/edit/delete helpers resolve the layoutGroup map to the corresponding LayoutGroup route; filter browser developer tools for that exact function name. Screen visibility is not a substitute for the API administrator check. Edit a dashboard card’s name/modal size. The helper sends id/name/metaModalSize plus an ignored restricted=false control; the client clears its cached layout after the reply.
Related endpoints
- LayoutGroups_getList discovers IDs and metadata for layout selectors.
- LayoutGroup_createData creates a header only; LayoutGroup_copy also copies the existing field tree.
- LayoutGroup_updateData changes several header fields; LayoutGroup_updateField changes one mapped field across IDs.
- LayoutGroup_deleteData removes a group and performs separate field-row cleanup.