# Workqueues
### 1. Introduction
In OpenCRVS, **Workqueues** are role-based, pre-filtered lists of vital event records, organised to help registration staff clearly see pending tasks and what needs their attention.
Instead of searching for records, users may open a Workqueue from the left-hand navigation to get a task-focused view of records at a particular status or that require a specific action, such as declaration review, validation, approval, certificate printing, or issuance.
Each Workqueue combines configurable filters with role-based visibility so that:
* Users are able to see records relevant to them at that moment in time
* Users only see queues that are relevant to their responsibilities
* Users can stay in a focused workflow with less searching and context switching
***
### 2. Feature overview
Workqueues provide a flexible mechanism for showing records relevant for the user based on workflow state, timing, location, user actions, and record data.
#### Core capabilities
OpenCRVS supports:
* Unlimited custom workqueues
* Role-based access to workqueues
* Filtering by event type and record status
* Date-based filtering using exact dates, ranges, or relative periods
* Location-aware filtering using administrative hierarchies and jurisdictions
* User- and role-based filtering (e.g. “updated by me”, “updated by registrar”)
* Filtering based on record data (e.g. date of event, event location, calculated values such as age)
Filters can be combined to create precise, task-oriented views such as:
> “All birth declarations rejected by a Registrar in the last 7 days within my district.”
***
### 3. Configuration overview
Each Workqueue is defined by a small set of parameters that control how it appears in the user interface and which records it displays.
#### 3.1 Workqueue parameters
| Property | Description |
| --------------------------- | ------------------------------------------------------------------ |
| **ID / Slug** | Unique identifier for the Workqueue. Used internally and in URLs. |
| **Icon** | Icon displayed in the left-hand navigation. |
| **Name** | User-facing display name shown in the navigation. |
| **Actions** | Required quick action from the workqueue table |
| **Query (search criteria)** | A set of filters that determine which records appear in the queue. |
#### 3.2 Supported query filters
Workqueues are powered by a flexible query system. Multiple filters can be combined to create highly targeted views of records.
| Filter | Type | Description | Examples |
| ----------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Event type(s)** | Any of | Filter records by civil event type. | Any of (Birth, Marriage) |
| **Record status(es)** | Any of | Filter records by workflow status. | Any of (Declared, Validated) |
| **Created at** | Exact date
Date range
Relative
| Filters by when the record was first created. | After 01/01/2024 |
| **Updated at** | Exact date
Date range
Relative
| Filters by when the last ~~mutating~~ action occurred. | Before 01/02/2024 |
| **Created at location** | Exact
Within
| Filters by where the create action was performed. | Exact: Ibombo |
| **Updated at location** | Exact
Within
| Filters by where the last ~~mutating~~ action occurred. | In user’s primary office
Within Langa District
|
| **Created by** | Exact
Me
| Filters by the user who created the record. | User ID: 123-456
Me
|
| **Updated by** | Exact | Filters by the user who last updated the record. | User ID: 123-123
Me
|
| **Updated by role** | Exact role
Any role
| Filters by the role of the user who last updated the record. | Registrar |
| **Record data fields** | Field-type dependent | Filters on values within the record data. Available operations depend on the field type. | Child age > 1 year
Event location = Ilanga District Hospital
Date of event between 2023–202
|
#### 3.3 Filter type options
The following matching types are used across filters:
* **Exact** – Matches a single, precise value (e.g. a specific date, user, or location).
* **Within** – Matches a location and all of its child locations in the administrative hierarchy.
* **Any of** – Matches at least one value from a selected set.
* **Range / Relative** – Matches a date range or a period relative to the current date (e.g. “last 14 days”).
* **Me** – A special selector representing the currently logged-in user.
***
### 4. Worked example
Here we illustrates how a real-world business rule is translated into a **workqueue configuration** and then into **code in the country configuration package**.
#### Business requirement: Pending validation workqueue
* Show all birth and death declarations that are ready to be reviewed by the Registration Officer, so that they can quickly identify declarations that are ready for them to validate.
* Show all birth declarations that:
* Have been declared in the Registration Officer’s administrative area
* Have not yet been validated
* Have the status “declared”
* Have not been rejected
* Do not require senior approval
#### Configuration input
| Configuration input | Value |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **id** | pending-validation |
| **Icon** | Stamp |
| **Name** | Pending validation |
| **Action** | Review |
| **Query** | Event: Birth, Death
Status: Declared
Flags: noneOf: Validated, Rejected, Approval required for late registration
|
***
### 5. Pre-configured workqueues
OpenCRVS includes several pre-configured workqueues that support common civil registration workflows. These queues can be customised, extended or removed as needed.
| Workqueue | Description |
| ------------------------- | -------------------------------------------------------------------- |
| **Drafts** | Records at draft status. Shown if user has the `record.create` scope |
| **Assigned to you** | Records currently assigned to the user |
| **Recent** | Recently created or updated records |
| **Notifications** | Incomplete declarations missing mandatory information |
| **Pending validation** | Declarations ready to be validated |
| **Pending updates** | Records flagged for additional data |
| **Potential duplicate** | Declarations that have been flagged as potential duplicates |
| **Pending registration** | Declarations that have been validated and ready to be registered |
| **Escalated** | Records that have been escalated to senior user roles |
| **Pending approvals** | Records forwarded for higher-level approval |
| **Pending certification** | Registered records ready for certificate printing |
| **Pending issuance** | Certified copies that have been printed off inadvance of issuance |
| **Pending corrections** | Records with pending correction requests |
***
### 7. Workqueue assignment and access control
Workqueues are assigned to user roles alongside other scopes. Assigning a workqueue makes the workqueue visible in the navigation pane and allows the user to see the full list of filtered records, however it **does not** grant additional “action” permissions on the records themselves.
Multiple workqueue IDs can be combined using the pipe (`|`) separator to tailor queue visibility by role and responsibility.
#### Example workqueue scope
```
workqueue[id=assigned-to-you|recent|pending-updates|pending-validation|pending-certification]
```
**Meaning:** Users with this scope can access the listed workqueues, enabling them to view and manage the corresponding filtered record sets.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://documentation.opencrvs.org/v2.0/functional/markdown/workflows/workqueues.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.