Read legacy report source choices

When to use this endpoint

Use this compatibility reader when a template-based client needs series IDs/names, grouping choices and raw saved presentation type. Current templates use legend definitions; retained older rows with main_field still use the legacy source resolver.

The response has legend, raw stored type and group entries with id/source. It is template metadata, not chart values or a saved Dashboard widget.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. The handler requires login. It has no reporting feature-bit or additional page/role-permission check.

The dispatcher rejects this legacy Report route for configured TeamAccess record scope, including assigned-only/parent-manager access and applicable department hierarchy scope. It returns an explicit scope error rather than a silently filtered chart.

Allowed requests read the authenticated tenant. Entity selections are report filters or label controls, not authorization; the handler does not add customer account-manager ownership filtering.

Parameters

Parameter	Type	Required	Description
`id`	Positive integer string	Yes	Report-template primary key. Blank, zero, negative, malformed and non-scalar IDs are rejected. A saved Dashboard widget/group ID is not a template ID.

Example request

$report = FM_api('Report_getRequiredData', [
	'id'=>'70',
]);

Example response

{
  "legend": [
    {
      "id": "customer-count",
      "name": "Customers"
    }
  ],
  "type": "{\"chart\":\"bar\"}",
  "group": [
    {
      "id": "customer_createDate",
      "source": "date"
    }
  ]
}

Representative current-schema template: selected series names come from its legend definitions; mapped grouping dates return the literal date marker.

type remains stored JSON text rather than an expanded object; database normalization can change JSON whitespace/key order. Legacy main_field rows can still return field-source choices or the date marker for legend.

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":"This legacy report does not support your configured record scope. Use the scoped Contracts reports or table exports."}`	The dispatcher detects configured TeamAccess record scope before the handler.
`{"error":"missing parameter: id"}`	The named parameter is omitted or null. Present blank/malformed controls return an invalid-parameter error instead; list controls must be native arrays.
`{"error":"invalid parameter: id"}`	A supplied numeric/list control is malformed, a list contains unsupported tokens, or frequency/userType/date selectors are outside 0–3. The message names the invalid control; validation precedes chart queries.
`{"error":"report template not found"}`	The requested template row is absent.
`{"error":"invalid report template configuration"}`	Saved legend/group/meta data cannot be represented safely in this metadata contract.

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

Behaviour and edge cases

The template is read without selecting a removed schema-specific column. Current rows use stored legend definitions, exposing each series id and name (falling back to its ID when the name is absent).
If a retained row has nonblank main_field, its legacy source resolver is used instead. counts resolves to one Count choice; formData reads and normalizes meta.legend.source; mapped dates return date; mapped references/static sources return their existing choices.
group_field accepts stored lists of field IDs or definitions with id/field. A matching main-table prefix is removed for the trusted field-map lookup, while the response preserves the original group ID. Unknown mappings return an empty choice list rather than malformed SQL.
Malformed legend, grouping or metadata structures return invalid report template configuration. Each definition must have a scalar ID and a scalar name if supplied. Multiple calls in the same process reload the local table map safely.
Source-choice queries retain the authenticated tenant and existing active/deleted/record-filter behavior; no new privacy or ownership contract is introduced. The dispatcher still rejects configured TeamAccess scope.
No direct production caller was found in CRM1, CRM2, the app or its m-service intermediary. Current widgets use Report_getReportType and Report_getData; this reader remains available as a compatible metadata utility.

Side effects

Reads tenant data and changes no business records, audit history, notifications, caches or schema. The source-choice resolver does not switch PHP timezone.

See it in Fieldmotion

CRM1

No production caller was found in CRM1. The saved Reports dashboard invokes Report_get plus its saved api name; this helper is not a prerequisite for the operational charts documented here.

CRM2

No direct caller was found in CRM2. Current template widgets use Report_getReportType and Report_getData. This compatible metadata reader now supports their current legend-based template schema as well as retained legacy rows.

Related endpoints

ReportDashboard_getRequestedDetails reads a saved widget definition and filters; its widget ID is not a legacy report-template ID.