Dashboard counts — status / priority / due tiles + distributions
GET /task/v1/dashboard/{retrieve-type}
Operation id: retrieveDashboardByType
Description
Unified dashboard endpoint for fast aggregations over the RRC_FEED collection. A single response feeds the home-page count tiles, pie chart and priority / due-date widgets.
Session-derived values (domain_id, user_id, dept_id, profile_id, time_zone_long, lang_code) are resolved from the auth token and cannot be overridden by query parameters.
unit_id is also resolved from the token in the default (store-user) mode. Exception: when v_request_type=ru (corp mode; case-insensitive) is supplied, unit_id is mandatory as a query parameter and overrides the corp session's unit for scoping every query.
Query params are auto-converted from snake_case to camelCase. All response keys are returned in snake_case.
Retrieve Types
| Value | Description |
|---|---|
feed-entity-count | Status / priority / due-date count sections. status / priority apply an overlap date filter matching /feeds/list/tasks — END_DATE_TIME ≥ fromDate AND startCol < toDate. Default period = domain PULSE_SETUP/DATE_RANGE attribute (same as list API). due always computes five fixed calendar buckets and ignores period. VISIBILITY is hardcoded to ["I", null]. Both status and priority use domain-configured FEED_STATUS codes (default N/R/P/O/C/F/E); due uses ACTIVE_FEED_STATUSES (N/R/P/O). Setting approach_deadline enables AO synthesis. |
Parameter Applicability Matrix (feed-entity-count)
| Parameter | Default | Description |
|---|---|---|
feed_entity_projections | status,priority | CSV subset of status, priority, due. Each selected family is computed in a single Mongo aggregation; omitted families are not queried. Unknown tokens fail with E149. |
period | Domain PULSE_SETUP/DATE_RANGE | Exactly YYYYMMDD,YYYYMMDD — e.g. 20260601,20260630. Anchored in session TZ. Applies an overlap predicate to status and priority: END_DATE_TIME ≥ fromDate AND startCol < toDate (same as /feeds/list/tasks). due always ignores this. When omitted, the domain's PULSE_SETUP/DATE_RANGE attribute is used (same default as /feeds/list/tasks). |
message_type | PROJECTEXTRACT | CSV of MESSAGE_TYPE values to include, e.g. PROJECTEXTRACT or PROJECTEXTRACT,RRTFM. Filters every section. |
view_type | MV | Line-of-sight scope. MV (My View) = direct assignment OR role-based. SV (Store View) = no assignment filter. DV (Dept View) = user OR dept match. Ignored when v_request_type=ru is present — effective value is always SV. |
entity_type | P | Controls which feed entities to count and the response shape. P (default) = project parents only (CLUSTER_CHILD_ID = "-1") — flat response. T = task children only (CLUSTER_CHILD_ID ≠ "-1") — flat response. ALL = both, returned as nested "projects" / "tasks" objects (two Mongo round trips per projection). Unknown value fails with E212. |
approach_deadline | (unset) | Hours. Enables AO synthesis on status when > 0; non-numeric → E156. 0 or negative disables AO (same as omitting). See Approach-deadline synthesis. |
v_request_type | (absent) | Request mode. Only accepted value is ru (corp mode); matching is case-insensitive (ru, RU, etc.). Omitted → store-user mode. When present with a non-empty value, the auth token is treated as a corp-level session: domainId, langCode, timeZoneLong come from the corp session; unit_id is mandatory; view_type is silently forced to SV (e.g. view_type=MV is ignored). Present but blank, whitespace-only, or any other non-empty value → E370. |
unit_id | (from session) | Target store unit ID. Required when v_request_type=ru; ignored otherwise. Absent or blank when required → E107. |
The response always carries from_date and to_date (epoch millis, UTC) representing the resolved period window, so clients can label charts deterministically.
Response Shape
The response always carries entity_type, feed_entity_projections, from_date and to_date (epoch millis, UTC).
Response shape depends on entity_type:
entity_type=P(default) orentity_type=T: projection sections appear directly at the top level (flat response).entity_type=ALL: projection sections are nested under"projects"and"tasks"top-level keys.
entity_type=P (default) — projects only (flat):
{
"status": "OK",
"count_data": {
"entity_type": "P",
"feed_entity_projections": ["status", "priority"],
"from_date": 1748488800000,
"to_date": 1751080799999,
"status": {
"by_status": [
{"status": "C", "count": 6},
{"status": "N", "count": 3},
{"status": "O", "count": 4},
{"status": "P", "count": 5},
{"status": "R", "count": 1}
],
"total_count": 19,
"new_tasks_today": 2
},
"priority": {
"by_priority": [
{"priority": 1, "count": 2},
{"priority": 2, "count": 3},
{"priority": 3, "count": 7}
],
"total_count": 12
}
}
}
entity_type=ALL — both projects and tasks, nested:
{
"status": "OK",
"count_data": {
"entity_type": "ALL",
"feed_entity_projections": ["status", "priority"],
"from_date": 1748488800000,
"to_date": 1751080799999,
"projects": {
"status": {
"by_status": [
{"status": "C", "count": 6},
{"status": "N", "count": 3},
{"status": "O", "count": 4},
{"status": "P", "count": 5},
{"status": "R", "count": 1}
],
"total_count": 19,
"new_tasks_today": 2
},
"priority": {
"by_priority": [
{"priority": 1, "count": 2},
{"priority": 2, "count": 3},
{"priority": 3, "count": 7}
],
"total_count": 12
}
},
"tasks": {
"status": {
"by_status": [
{"status": "C", "count": 4},
{"status": "N", "count": 1},
{"status": "O", "count": 2},
{"status": "P", "count": 3}
],
"total_count": 10,
"new_tasks_today": 1
},
"priority": {
"by_priority": [
{"priority": 1, "count": 1},
{"priority": 2, "count": 2},
{"priority": 3, "count": 4}
],
"total_count": 7
}
}
}
}
entity_type=T — tasks only (flat):
{
"status": "OK",
"count_data": {
"entity_type": "T",
"feed_entity_projections": ["status"],
"from_date": 1748488800000,
"to_date": 1751080799999,
"status": {
"by_status": [
{"status": "C", "count": 4},
{"status": "N", "count": 1},
{"status": "O", "count": 2},
{"status": "P", "count": 3}
],
"total_count": 10,
"new_tasks_today": 1
}
}
}
All projections, explicit period 20260601,20260630:
{
"status": "OK",
"count_data": {
"entity_type": "P",
"feed_entity_projections": ["status", "priority", "due"],
"from_date": 1748750400000,
"to_date": 1751327999999,
"status": { "by_status": […], "total_count": 15, "new_tasks_today": 2 },
"priority": { "by_priority": […], "total_count": 15 },
"due": {
"by_due": [
{"period": "today", "count": 3},
{"period": "this_week", "count": 8},
{"period": "last_week", "count": 5},
{"period": "this_month", "count": 20},
{"period": "last_month", "count": 15}
]
}
}
}
With approach_deadline=72 — "AO" in by_status[]; no top-level tile:
{
"status": "OK",
"count_data": {
"entity_type": "P",
"feed_entity_projections": ["status"],
"from_date": 1748488800000,
"to_date": 1751080799999,
"status": {
"by_status": [
{"status": "AO", "count": 4},
{"status": "C", "count": 6},
{"status": "N", "count": 3},
{"status": "O", "count": 5},
{"status": "P", "count": 3},
{"status": "R", "count": 1}
],
"total_count": 22,
"new_tasks_today": 2
}
}
}
Per-field semantics
| Section | Field | How it's computed |
|---|---|---|
status | by_status[] | $group on effective STATUS over the scoped base match. Includes "AO" entry when approach_deadline is set. |
status | total_count | Σ by_status[].count — denominator for the pie chart. |
status | new_tasks_today | effective STATUS = N AND CREATE_DTM ∈ [today 00:00, today 23:59:59.999] (session TZ). Returns 0 when today is outside the period window. |
priority | by_priority[] | Domain FEED_STATUS filtered by the same overlap predicate as status → $group on PRIORITY → $sort. Callers sum entries for "high/urgent" tiles. |
priority | total_count | Σ by_priority[].count. |
due | by_due[] | Five fixed calendar windows by END_DATE_TIME over ACTIVE_FEED_STATUSES (N/R/P/O). Period is ignored. |
by_due[] windows (full calendar periods, session TZ)
period entry | END_DATE_TIME window |
|---|---|
today | 00:00:00.000 → 23:59:59.999 today |
this_week | Monday 00:00 → Sunday 23:59:59.999 of the current ISO week |
last_week | Monday 00:00 → Sunday 23:59:59.999 of the previous ISO week |
this_month | Day 1 00:00 → last-day 23:59:59.999 of the current month |
last_month | Day 1 00:00 → last-day 23:59:59.999 of the previous month |
All sections are scoped by message_type, view_type (MV/SV/DV) and entity_type in buildBaseMatch. See Assignment predicates below.
Assignment predicates (view_type)
view_type | Assignment filter applied |
|---|---|
MV | USER_ID = userId OR (USER_ID = "-1" AND PROFILE_ID ∈ profiles AND DEPT_ID ∈ depts) |
SV | none — all records for the unit (and message type) are included |
DV | USER_ID = userId OR DEPT_ID ∈ depts |
Approach-deadline synthesis
When approach_deadline = H (hours, H > 0) is supplied, each candidate feed is reclassified into an _effective_status bucket as follows (first matching branch wins):
| Condition on the feed | Bucket |
|---|---|
STATUS ∈ [C, F, E, W] | actual STATUS |
STATUS = O | O |
STATUS ∈ [N, R, P] and today > END_DATE_TIME | O (synthesized) |
STATUS ∈ [N, R, P] and today ≥ END_DATE_TIME − H hours and today ≤ END_DATE_TIME | AO |
| otherwise | actual STATUS |
Worked example — feed with END_DATE_TIME = 2026-06-10 18:00:00 and approach_deadline = 72 (72 hours):
| API called at | Bucket the feed lands in |
|---|---|
| 2026-06-07 17:59:59 | actual STATUS (N/R/P) — comfortable |
| 2026-06-07 18:00:00 | AO — today ≥ end − 72 h |
| 2026-06-10 18:00:00 | AO — last instant of the AO window |
| 2026-06-10 18:00:01 | O — synthesized, today > end |
Error Scenarios
| Scenario | HTTP | Error Code | Message |
|---|---|---|---|
Missing X-reflexis-csrf-token-X header | 400 | E112 | X-reflexis-csrf-token-X header is mandatory |
| Invalid or expired token | 401 | E204 | Invalid or expired token |
Invalid retrieve-type value | 400 | E209 (INVALID_DASHBOARD_RETRIEVE_TYPE) | Invalid retrieve_type. Allowed values: feed-entity-count |
Invalid feed_entity_projections value | 400 | E149 | Invalid projection value. Allowed: status, priority, due |
Invalid view_type value | 400 | E210 | Invalid view_type value. Allowed: MV, SV, DV. |
Invalid entity_type value (not P, T, or ALL) | 400 | E212 | Invalid entity_type value. Allowed: P, T, ALL. |
Invalid period format (not YYYYMMDD,YYYYMMDD) | 400 | E151 | Invalid `period` value '…'. Expected YYYYMMDD,YYYYMMDD (e.g. 20260601,20260630). |
Malformed date part in period | 400 | E151 | Invalid `period[0]` value '…'. Expected YYYYMMDD (e.g. 20260601). |
First date after second date in period | 400 | E147 | from_date must not be after to_date |
Invalid approach_deadline (non-numeric) | 400 | E156 | Invalid approach_deadline value. Must be a positive integer (hours). |
v_request_type present but blank, whitespace-only, or not ru | 400 | E370 | Invalid v_request_type provided |
v_request_type=ru and unit_id absent or blank | 400 | E107 | Unit id is mandatory |
| Mongo / aggregation failure | 500 | E351 | Unable to compute dashboard counts |
Empty
count_datais not an error. The endpoint always returns{ "status": "OK", "count_data": { … } }even when every tile is zero, so the UI can render zero-state widgets.
Tags: MyWorkDashboard
Parameters
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
retrieve-type | string | Yes | Retrieve mode for /task/v1/dashboard/{retrieve-type}: - feed-entity-count — status / priority / due-date count sections selected via feed_entity_projections (CSV, default status,priority). Single response feeds the home-page tiles and pie chart. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
approach_deadline | integer | No | Hours. Enables AO synthesis on the status section when > 0. Non-numeric → E156. 0 or negative disables AO synthesis (same as omitting the param). When active, reclassifies active feeds (N/R/P) into a synthesized AO bucket once today >= END_DATE_TIME − approach_deadline hours and still on/before END_DATE_TIME, and into O once past END_DATE_TIME. Adds an "AO" entry in by_status[] — no separate top-level tile. Other sections (priority, due) are unaffected. |
entity_type | string | No | Controls which feed entities are counted and the response shape. - P (default) — project parents only (CLUSTER_CHILD_ID = "-1"). Flat response — projection sections appear directly in count_data. - T — task children only (CLUSTER_CHILD_ID ≠ "-1"). Flat response — projection sections appear directly in count_data. - ALL — both project parents and task children. Results are nested under "projects" and "tasks" top-level keys (two Mongo round trips per projection — use P or T to halve DB cost). Case-insensitive. Any other value is rejected with E212. Affects every section. |
feed_entity_projections | string | No | Comma-separated subset of status, priority, due. Each selected family is computed in a single Mongo aggregation; omitted families are not queried. |
message_type | string | No | CSV of MESSAGE_TYPE values to include, e.g. PROJECTEXTRACT or PROJECTEXTRACT,RRTFM. Defaults to PROJECTEXTRACT. Filters every section. |
period | string | No | Date range for status and priority sections, in YYYYMMDD,YYYYMMDD format anchored in the user's session timezone. - status + priority: overlap predicate applied to the base match — END_DATE_TIME ≥ fromDate AND startCol < toDate, where startCol = START_DATE_TIME when domain flag PULSE_SETUP/FETCH_BY_START_DATE=Y, else TXN_DTM. Same semantics as /feeds/list/tasks. - due: always ignored — due computes all five fixed calendar buckets regardless of period. toDate is exclusive internally (start of the day after the last requested day). The to_date echoed in the response is the user-visible inclusive end (23:59:59.999 of the last day). When omitted, defaults to the domain's PULSE_SETUP/DATE_RANGE attribute — the same window used by /feeds/list/tasks. |
unit_id | string | No | Target store unit ID. Required when v_request_type=ru; ignored in default (store-user) mode. When required and absent or blank, the request fails with E107. |
v_request_type | string | No | Request mode. The only accepted value is ru (corp / requested-unit). Matching is case-insensitive — ru, RU, Ru, etc. are all accepted. Omit the parameter for store-user mode. When present with a non-empty value, the auth token is treated as a corp-level session: - domainId, langCode, and timeZoneLong are resolved from the corp user's session. - unit_id becomes mandatory. - view_type is silently forced to SV regardless of the value passed by the caller (e.g. view_type=MV or view_type=DV is ignored; the request succeeds with store-wide scope). Example: v_request_type=RU&unit_id=0001&view_type=MV runs as SV. Present but blank, whitespace-only, or any other non-empty value is rejected with E370. |
view_type | string | No | Line-of-sight scope (case-insensitive). MV (default) = My View — direct user assignment OR role-based predicate. SV = Store View — no assignment filter. DV = Dept View — user OR dept match. Note: When v_request_type=ru is present (case-insensitive: ru, RU, etc.) this parameter is ignored and SV is used unconditionally — e.g. v_request_type=RU&view_type=MV still queries store-wide counts for the supplied unit_id. |
Security
- AuthTokenHeader (apiKey)
- Session authentication token validated server-side against the user session store.
Responses
200 — Flat {count_data: {entity_type, feed_entity_projections[], from_date, to_date, status?, priority?, due?}} for entity_type=P or T (default P); nested {count_data: {entity_type, …, projects?: {…}, tasks?: {…}}} for entity_type=ALL.
Content type: application/json
400 — - E209 — invalid retrieve-type for dashboard endpoint
- E149 — invalid feed_entity_projections value
- E151 — invalid period (not YYYYMMDD,YYYYMMDD format, or malformed date token)
- E147 — from_date is after to_date
- E156 — invalid approach_deadline (non-numeric;
0or negative disables AO without error) - E210 — invalid view_type value (not MV, SV, or DV)
- E212 — invalid entity_type value (not P, T, or ALL)
Content type: application/json
401 — Invalid or expired X-reflexis-csrf-token-X token (HTTP 401)
Content type: application/json
500 — Unexpected server-side error
Content type: application/json
Response models
200 — Flat {count_data: {entity_type, feed_entity_projections[], from_date, to_date, status?, priority?, due?}} for entity_type=P or T (default P); nested {count_data: {entity_type, …, projects?: {…}, tasks?: {…}}} for entity_type=ALL.
Content type: application/json
Schema
JSON object (structure varies by endpoint).
{
"type": "object",
"description": "JSON object (structure varies by endpoint)."
}
Example:
{
"status": "OK",
"count_data": {
"entity_type": "P",
"feed_entity_projections": [
"status",
"priority"
],
"from_date": 1748488800000,
"to_date": 1751080799999,
"status": {
"by_status": [
{
"status": "C",
"count": 6
},
{
"status": "N",
"count": 3
},
{
"status": "O",
"count": 4
},
{
"status": "P",
"count": 5
},
{
"status": "R",
"count": 1
}
],
"total_count": 19,
"new_tasks_today": 2
},
"priority": {
"by_priority": [
{
"priority": 1,
"count": 2
},
{
"priority": 2,
"count": 3
},
{
"priority": 3,
"count": 7
}
],
"total_count": 12
}
}
}
400 — - E209 — invalid retrieve-type for dashboard endpoint
- E149 — invalid feed_entity_projections value
- E151 — invalid period (not YYYYMMDD,YYYYMMDD format, or malformed date token)
- E147 — from_date is after to_date
- E156 — invalid approach_deadline (non-numeric;
0or negative disables AO without error) - E210 — invalid view_type value (not MV, SV, or DV)
- E212 — invalid entity_type value (not P, T, or ALL)
Content type: application/json
Schema
| Property | Type | Required | Description |
|---|---|---|---|
status | string | Yes | Always "ER" for error responses |
errorCode | string | Yes | Application-level error code (e.g. E204, E112, E302) |
response | string | Yes | Human-readable error message |
{
"type": "object",
"example": {
"status": "ER",
"errorCode": "E204",
"response": "Invalid or expired token"
},
"required": [
"status",
"errorCode",
"response"
],
"properties": {
"status": {
"type": "string",
"description": "Always \"ER\" for error responses",
"enum": [
"ER"
]
},
"errorCode": {
"type": "string",
"description": "Application-level error code (e.g. E204, E112, E302)"
},
"response": {
"type": "string",
"description": "Human-readable error message"
}
}
}
401 — Invalid or expired X-reflexis-csrf-token-X token (HTTP 401)
Content type: application/json
Schema
| Property | Type | Required | Description |
|---|---|---|---|
status | string | Yes | Always "ER" for error responses |
errorCode | string | Yes | Application-level error code (e.g. E204, E112, E302) |
response | string | Yes | Human-readable error message |
{
"type": "object",
"example": {
"status": "ER",
"errorCode": "E204",
"response": "Invalid or expired token"
},
"required": [
"status",
"errorCode",
"response"
],
"properties": {
"status": {
"type": "string",
"description": "Always \"ER\" for error responses",
"enum": [
"ER"
]
},
"errorCode": {
"type": "string",
"description": "Application-level error code (e.g. E204, E112, E302)"
},
"response": {
"type": "string",
"description": "Human-readable error message"
}
}
}
Example:
{
"status": "ER",
"errorCode": "E204",
"response": "Invalid or expired token"
}
500 — Unexpected server-side error
Content type: application/json
Schema
| Property | Type | Required | Description |
|---|---|---|---|
status | string | Yes | Always "ER" for error responses |
errorCode | string | Yes | Application-level error code (e.g. E204, E112, E302) |
response | string | Yes | Human-readable error message |
{
"type": "object",
"example": {
"status": "ER",
"errorCode": "E204",
"response": "Invalid or expired token"
},
"required": [
"status",
"errorCode",
"response"
],
"properties": {
"status": {
"type": "string",
"description": "Always \"ER\" for error responses",
"enum": [
"ER"
]
},
"errorCode": {
"type": "string",
"description": "Application-level error code (e.g. E204, E112, E302)"
},
"response": {
"type": "string",
"description": "Human-readable error message"
}
}
}
Example:
{
"status": "ER",
"errorCode": "E302",
"response": "Internal server error"
}