Skip to main content

Retrieve grouping metadata for tenant system fields

GET 
/roster-upload/system-fields

Returns the grouping rules that apply to each of the tenant's system fields, keyed by the field's mappedKey.

When to use: call this while building the column mapping screen, to decide whether a mapped column additionally needs an Entity Group or a Separator input from the user. Pair it with POST /roster-upload/{templateId}/column-mapping, which returns the fields themselves but not their grouping rules.

Preconditions: supply the tenant-id header and the jobType query parameter; both are required and a missing or blank value returns 400. The tenant must have the column mapping feature enabled and the caller must hold the UPDATE_ROSTER_UPLOAD permission - both failures return 403, distinguished by the reason field of the error body (FEATURE_DISABLED identifies the feature-flag case). Tenant-specific schema paths are used when the tenant has them configured; otherwise the platform default schemas apply.

What you get back: an object keyed by mappedKey, where each value carries up to four grouping descriptors - valueArrayGrouping (the column holds several values in one cell, separated by a delimiter), objectArrayGrouping (the column contributes to one entry of a repeating object, such as a license), objectGrouping (the column contributes to a single nested object, such as user-defined fields), and entityInstanceGrouping (the column belongs to a numbered instance of an entity, such as a second practice location). A field with no grouping rules is returned with all four descriptors absent. Read-only; no state is mutated.

Request​

Responses​

Grouping rules for the tenant's system fields, keyed by the field's mappedKey.