Fieldmotion API Getting started

Reporting dashboards and targets

Set a dashboard group’s date filters

POST /a/ReportDashboards_setDuration

Overwrite durationType, daysFrom, and daysTo in every widget filter in a group.

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

ParameterTypeRequiredDescription
groupIDInteger-compatibleYesPositive active group ID, editable by the caller.
daysFrom / daysToInteger-compatibleYesStored verbatim after integer coercion. Relative-day offsets are usual; report consumers interpret custom durationType=1 values as Unix timestamps.
durationTypeInteger-compatibleYesDate-mode identifier. No mode/range validation or preset calculation occurs here.

Example request

$result = FM_api('ReportDashboards_setDuration', ['groupID'=> '12','daysFrom'=> '-30','daysTo'=> '0','durationType'=> '0']);

Example response

{"ok":"1"}

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: groupID"}Required groupID is absent or invalid.
{"error":"missing or invalid parameter: durationType"}Required durationType is absent or invalid.
{"error":"missing or invalid parameter: daysFrom"}Required daysFrom is absent or invalid.
{"error":"missing or invalid parameter: daysTo"}Required daysTo 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.

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

Behaviour and edge cases

  • One bound JSON_SET update replaces all three keys atomically, preserving other filter keys. SQL NULL filters are initialized as an empty JSON object.
  • Only active widgets in the editable group are affected. Missing/deleted/unreadable groups fail; a valid empty group succeeds unchanged.
  • Bounds must be integers and durationType nonnegative. No date ordering or report-mode allowlist is enforced; the endpoint does not calculate presets.

Side effects

  • Updates active widget edit times and invalidates their cache in a transaction. No group timestamp, report execution, target change, or activity is written.

See it in Fieldmotion

CRM1

Group-level dashboard date/preset controls submit the chosen numeric bounds. Filter browser Network requests for ReportDashboards_setDuration.

CRM2

Classic dashboard date controls use this endpoint; the UI calculates presets before submitting. Filter browser Network requests for ReportDashboards_setDuration.

Related endpoints