Merge dashboard-group metadata

When to use this endpoint

Load the saved dashboard/group configuration first, then send this edit from its settings or layout controls. Re-read the configuration after an uncertain write: the handler reports validation, permission, lookup, and write failures as application errors.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. All lookups and writes are tenant-local.

Only the group owner may manage its name, sharing/settings, or deletion. View/edit shares do not grant group-management rights. None disables its share array; otherwise string user IDs or All grant that share. No reporting-feature or additional CRM2 page-role check is applied.

For signed form requests, sign numeric scalar values as strings, including values inside native nested arrays. Send JSON text only for parameters explicitly accepting JSON strings; see Getting started.

These reporting handlers require tenant schema upgrade 794 before deployment. No request path creates or repairs schema.

Parameters

Parameter	Type	Required	Description
`id`	Integer-compatible	Yes	Positive integer ID in the authenticated tenant. Malformed, fractional, zero, or negative values are rejected; deleted records are unavailable.
`val`	JSON object string	Yes	Top-level keys to replace; untouched keys survive. Arrays are replaced wholesale. Sharing uses `sharedUser`/`sharedUserEdit` arrays with string user IDs and `All`/`None` tokens.

Example request

$result = FM_api('ReportDashboardGroup_setMeta', ['id'=> '12','val'=>json_encode(['sharedUser'=>['7'],'sharedUserEdit'=>['7']])]);

Example response

{"ok":"1"}

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":"report group is not existing."}`	The group does not exist.
`{"error":"missing or invalid parameter: id"}`	Required `id` is absent or invalid.
`{"error":"missing or invalid parameter: val"}`	Required `val` is absent or invalid.
`{"error":"no permission to access api"}`	The group is not readable/editable, or the operation requires ownership and the caller is not its owner.
`{"error":"reporting write failed"}`	A database write failed. Transactional operations roll back instead of returning success.
`{"error":"missing or invalid parameter: val"}`	The patch is not a JSON object or a supplied share array/value is invalid.
`{"ok":"1","warning":"no change required"}`	The decoded merged metadata equals the stored value.

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

Behaviour and edge cases

Only the owner may save group settings or sharing. The JSON value must be an object; invalid/scalar/null JSON returns a validation error.
The merge is shallow: supplied top-level arrays/objects replace their old values, and omitted keys survive. There is no metadata-key allowlist.
Share arrays must contain string positive user IDs or All/None tokens. Values are deduplicated; related user existence is not checked.
Decoded semantic equality returns no-change without an edit. Omitting a key preserves it; null for an ordinary key stores JSON null, not deletion.
CRM display metadata includes columnCount, colorList, displayNumber, and barStackSum. These are client-consumed, not server-validated display settings.

Side effects

Permission and metadata merge occur transactionally; a changed value advances group last_edited and invalidates its cache. No history or notification is written.

See it in Fieldmotion

CRM1

Group configuration/sharing saves serialized metadata here. Filter browser Network requests for ReportDashboardGroup_setMeta.

CRM2

Sharing/settings dialogs JSON-stringify their patch and call this endpoint. Filter browser Network requests for ReportDashboardGroup_setMeta.

Related endpoints

ReportDashboardGroups_list finds groups visible to the current user.
ReportDashboards_list loads stored widget configuration.