Fieldmotion API Getting started

Reporting dashboards and targets

Create a dashboard widget

POST /a/ReportDashboard_new

Store a widget’s report source, layout, filters, and optional notes inside a dashboard group.

When to use this endpoint

Create or select a dashboard group first, then save its configuration. Creation does not fetch reporting results; the dashboard client subsequently loads and renders its stored widgets.

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

ParameterTypeRequiredDescription
nameStringYesTrimmed, nonblank name, limited to 100 characters by Core_maxLengthError.
group_idInteger-compatibleYesPositive destination group ID. The group must exist, be active, and be editable by the caller.
apiStringYesStored report-source identifier, not executed or validated. CRM1 uses report API names; the CRM2 new-dashboard editor stores report-template IDs as text.
grid / filterJSON stringsYesSerialized JSON object/array layout and report-specific filters. Malformed or scalar JSON is rejected; properties are not report-schema validated.
notesStringNoDefaults to an empty string.

Example request

$result = FM_api('ReportDashboard_new', ['name' => 'Sales', 'group_id' => '12', 'api' => 'Report_getQuotesTargetAttainment', 'grid' => json_encode(['x'=>0,'y'=>0,'w'=>6,'h'=>4]), 'filter' => json_encode(['durationType'=>0,'daysFrom'=>-30,'daysTo'=>0])]);

Example response

{"ok":"1","id":71}

On a successful insert, id is the new widget ID. The handler returns ok as 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":"missing or invalid parameter: name"}Required name is absent or invalid or blank.
{"error":"missing or invalid parameter: group_id"}Required group_id is absent or invalid.
{"error":"missing or invalid parameter: api"}Required api is absent or invalid.
{"error":"parameter too long: name. max length 100 characters"}The trimmed name exceeds the 100-character limit.
{"error":"missing or invalid parameter: grid"}Required grid 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: filter"}Filter is missing, malformed JSON, or scalar JSON.

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

Behaviour and edge cases

  • Creates configuration only; it does not execute reports or create targets.
  • The active destination group is permission-checked under the creation transaction. Duplicate names are allowed; no idempotency key exists.
  • Missing filter now correctly reports missing or invalid parameter: filter; failed inserts return an error rather than an ID of false.

Side effects

  • Transactionally inserts the widget with Unix creation/edit times and invalidates the widget cache. No group metadata, activity history, notification, or report calculation is changed.

See it in Fieldmotion

CRM1

Add a report widget in the dashboard editor. Layout and filter values are JSON-stringified before creating it. Filter browser Network requests for ReportDashboard_new.

CRM2

Classic Report Dashboard and the new-dashboard editor both create widgets here; their api conventions differ. Filter browser Network requests for ReportDashboard_new.

Related endpoints