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

ValueDescription
feed-entity-countStatus / 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)

ParameterDefaultDescription
feed_entity_projectionsstatus,priorityCSV 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.
periodDomain PULSE_SETUP/DATE_RANGEExactly 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_typePROJECTEXTRACTCSV of MESSAGE_TYPE values to include, e.g. PROJECTEXTRACT or PROJECTEXTRACT,RRTFM. Filters every section.
view_typeMVLine-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_typePControls 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) or entity_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

SectionFieldHow it's computed
statusby_status[]$group on effective STATUS over the scoped base match. Includes "AO" entry when approach_deadline is set.
statustotal_countΣ by_status[].count — denominator for the pie chart.
statusnew_tasks_todayeffective STATUS = N AND CREATE_DTM ∈ [today 00:00, today 23:59:59.999] (session TZ). Returns 0 when today is outside the period window.
priorityby_priority[]Domain FEED_STATUS filtered by the same overlap predicate as status → $group on PRIORITY → $sort. Callers sum entries for "high/urgent" tiles.
prioritytotal_countΣ by_priority[].count.
dueby_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 entryEND_DATE_TIME window
today00:00:00.000 → 23:59:59.999 today
this_weekMonday 00:00 → Sunday 23:59:59.999 of the current ISO week
last_weekMonday 00:00 → Sunday 23:59:59.999 of the previous ISO week
this_monthDay 1 00:00 → last-day 23:59:59.999 of the current month
last_monthDay 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_typeAssignment filter applied
MVUSER_ID = userId OR (USER_ID = "-1" AND PROFILE_ID ∈ profiles AND DEPT_ID ∈ depts)
SVnone — all records for the unit (and message type) are included
DVUSER_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 feedBucket
STATUS ∈ [C, F, E, W]actual STATUS
STATUS = OO
STATUS ∈ [N, R, P] and today > END_DATE_TIMEO (synthesized)
STATUS ∈ [N, R, P] and today ≥ END_DATE_TIME − H hours and today ≤ END_DATE_TIMEAO
otherwiseactual STATUS

Worked example — feed with END_DATE_TIME = 2026-06-10 18:00:00 and approach_deadline = 72 (72 hours):

API called atBucket the feed lands in
2026-06-07 17:59:59actual STATUS (N/R/P) — comfortable
2026-06-07 18:00:00AO — today ≥ end − 72 h
2026-06-10 18:00:00AO — last instant of the AO window
2026-06-10 18:00:01O — synthesized, today > end

Error Scenarios

ScenarioHTTPError CodeMessage
Missing X-reflexis-csrf-token-X header400E112X-reflexis-csrf-token-X header is mandatory
Invalid or expired token401E204Invalid or expired token
Invalid retrieve-type value400E209 (INVALID_DASHBOARD_RETRIEVE_TYPE)Invalid retrieve_type. Allowed values: feed-entity-count
Invalid feed_entity_projections value400E149Invalid projection value. Allowed: status, priority, due
Invalid view_type value400E210Invalid view_type value. Allowed: MV, SV, DV.
Invalid entity_type value (not P, T, or ALL)400E212Invalid entity_type value. Allowed: P, T, ALL.
Invalid period format (not YYYYMMDD,YYYYMMDD)400E151Invalid `period` value '…'. Expected YYYYMMDD,YYYYMMDD (e.g. 20260601,20260630).
Malformed date part in period400E151Invalid `period[0]` value '…'. Expected YYYYMMDD (e.g. 20260601).
First date after second date in period400E147from_date must not be after to_date
Invalid approach_deadline (non-numeric)400E156Invalid approach_deadline value. Must be a positive integer (hours).
v_request_type present but blank, whitespace-only, or not ru400E370Invalid v_request_type provided
v_request_type=ru and unit_id absent or blank400E107Unit id is mandatory
Mongo / aggregation failure500E351Unable to compute dashboard counts

Empty count_data is 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

NameTypeRequiredDescription
retrieve-typestringYesRetrieve 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

NameTypeRequiredDescription
approach_deadlineintegerNoHours. 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_typestringNoControls 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_projectionsstringNoComma-separated subset of status, priority, due. Each selected family is computed in a single Mongo aggregation; omitted families are not queried.
message_typestringNoCSV of MESSAGE_TYPE values to include, e.g. PROJECTEXTRACT or PROJECTEXTRACT,RRTFM. Defaults to PROJECTEXTRACT. Filters every section.
periodstringNoDate 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_idstringNoTarget 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_typestringNoRequest 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_typestringNoLine-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; 0 or 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; 0 or 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

PropertyTypeRequiredDescription
statusstringYesAlways "ER" for error responses
errorCodestringYesApplication-level error code (e.g. E204, E112, E302)
responsestringYesHuman-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

PropertyTypeRequiredDescription
statusstringYesAlways "ER" for error responses
errorCodestringYesApplication-level error code (e.g. E204, E112, E302)
responsestringYesHuman-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

PropertyTypeRequiredDescription
statusstringYesAlways "ER" for error responses
errorCodestringYesApplication-level error code (e.g. E204, E112, E302)
responsestringYesHuman-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"
}