Reporting dashboards and targets
Save several widget layouts
/a/ReportDashboards_setGrid
Save grid positions/sizes from a dashboard’s drag-and-resize layout.
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.
The group owner or an effective edit-share recipient may create/edit/delete widgets or save layout/date filters. A view share alone is read-only. 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 |
|---|---|---|---|
grids | Native array of objects | Yes | Native array of objects with a positive widget id and layout fields. id/content are removed; remaining fields are JSON-encoded and bound to SQL. All widgets must be active and editable. |
Example request
$result = FM_api('ReportDashboards_setGrid', ['grids'=>[['id'=> '71','x'=> '0','y'=> '0','w'=> '6','h'=> '4']]]);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":"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: grids"} | Grids is absent or invalid or not a native array, or a member is malformed. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- All records are validated and authorized before writes. The complete batch commits together; invalid/missing/uneditable records or a failed write roll back every grid change.
- Empty native arrays succeed unchanged. Multiple editable groups are allowed. Duplicate widget IDs use the last supplied layout; unchanged layouts still receive an edit timestamp.
- Do not send JSON text or malformed records; there is no coordinate/size constraint.
Side effects
- Transactionally updates widget grids/edit times and invalidates the widget cache. No group edit, activity history, notification, or report query occurs.
See it in Fieldmotion
CRM1
Move/resize dashboard widgets; gridstack save calls this bulk endpoint. Filter browser Network requests for ReportDashboards_setGrid.
CRM2
Classic and new dashboard layout saves use this endpoint rather than ReportDashboard_setGrid. Filter browser Network requests for ReportDashboards_setGrid.
Related endpoints
ReportDashboardGroups_listfinds groups visible to the current user.ReportDashboards_listloads stored widget configuration.ReportDashboardGroup_setMetaedits group metadata and sharing.