Fieldmotion API Getting started

Reporting dashboards and targets

Create a dashboard group

POST /a/ReportDashboardGroup_new

Create an empty dashboard group owned by the authenticated user.

When to use this endpoint

Create a named empty group before adding its widgets with ReportDashboard_new. Save sharing and display options separately with the group metadata setter; new-dashboard groups need the mode marker at creation.

Authentication and permissions

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

New groups are owned by the authenticated user. 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.
isNewInteger-compatibleNoOnly a value comparing equal to 1 writes {"isNew":1} into group metadata. Other values leave default metadata.

Example request

$result = FM_api('ReportDashboardGroup_new', ['name'=>'Sales','isNew'=> '1']);

Example response

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

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":"parameter too long: name. max length 100 characters"}The trimmed name exceeds the 100-character limit.
{"error":"reporting write failed"}A database write failed. Transactional operations roll back instead of returning success.

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

Behaviour and edge cases

  • Duplicate names are permitted; no widgets or shares are created.
  • Without isNew=1, metadata is left NULL. Dashboard lists separate modes by marker presence, not its truth value. A failed insert returns an error instead of success.

Side effects

  • Inserts a group with the current user as owner, Unix creation/edit timestamps, and cache invalidation. No activity, notification, or target changes occur.

See it in Fieldmotion

CRM1

Create a dashboard group in the report dashboard selector. Filter browser Network requests for ReportDashboardGroup_new.

CRM2

New-dashboard creation supplies isNew=1; classic dashboard creation leaves it unset. Filter browser Network requests for ReportDashboardGroup_new.

Related endpoints