Fieldmotion API Getting started

Display-layout groups

Copy a display-layout group

POST /a/LayoutGroup_copy

Copy a display-layout group and recreate its field tree under a new ID

When to use this endpoint

Start a variation of an existing display layout while leaving the source group intact. Copy locks the source header/tree, then creates a new header and raw field rows with remapped parent IDs in one transaction. It does not normalize the source through the current field map.

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
idInteger IDYesExisting positive scalar integer source group ID. Zero, negatives, arrays and SQL-like expressions fail before the lookup.
nameStringYesTrimmed nonblank name for the new group, at most 100 Unicode characters. Duplicate names are allowed.

Example request

$copy = FM_api('LayoutGroup_copy', [
	'id' => '1042',
	'name' => 'Customer summary copy',
]);

Example response

{"ok":1,"id":1088,"cdate":1792832400,"table":"customer","type":"0"}

Returns the insert-helper ID, integer current Unix-second cdate, source table and source metadata type (possibly null). This cdate shape differs from createData and getList. New child rows receive new IDs and parent links rather than retaining source IDs.

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: id"}id absent/null.
{"error":"missing or invalid parameter: name"}name absent/null.
{"error":"missing or invalid data"}Source header query returns no row, including lookup failure.
{"error":"parameter too long: name. max length 100 characters"}The trimmed copy name exceeds 100 characters.

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

Behaviour and edge cases

  • Copies table_name, user_id and header metadata, including modalSize/type/hidden and other display configuration. The live assetTypeID association is deliberately omitted so a copy does not become a second layout assigned to the source Asset Type. Name is supplied by the caller and timestamps are current.
  • The raw tree retains field type, table, geometry and per-field metadata without depending on current widget maps. Fresh IDs and remapped parent links preserve nesting, even when a child ID sorts before its parent. Missing/cyclic parent relationships fail the copy rather than dropping rows. No page_settings/default-layout selection is copied or reassigned.
  • All header/child insert results are checked. A failure rolls back the new group and any earlier copied fields; an enclosing caller transaction is preserved using a savepoint. The source remains unchanged, and extra request controls cannot override the internal copy selection.
  • 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

  • Inserts a new group and new layouts rows, with cache invalidation for layout_groups/layouts. The source header/tree is read, not edited. No explicit copy Core_log, email, event or default-layout assignment is invoked.

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

On CRM2’s Display Layout Dashboard, use Copy on a card, supply a new name and save. Filter for LayoutGroup_copy; the caller sends id/name and builds the new card from id/cdate/table/type.

Related endpoints