Workqueues

Configuring workqueues

A workqueue is a filtered list of records shown in the OpenCRVS UI. Each workqueue applies a query against the event index and presents the matching records in a table. To learn more, see Workqueues

A list of configured workqueues

Configuring workqueues

Workqueues are configured to the countryconfig under src/api/workqueue/workqueueConfig.ts.

Wrap your workqueue array in defineWorkqueues() from @opencrvs/toolkit/events. The helper parses each entry against WorkqueueConfig and warns about common misconfigurations.

Note: Access to any workqueues requires the record.search scope. The scope's options further narrow which records the user actually sees inside the workqueue, so a user might only be able to access a subset of the workqueue's matching records.

Example:

// src/api/workqueue/workqueueConfig.ts
import {
  ActionType,
  EventStatus,
  InherentFlags,
  defineWorkqueues,
  user
} from '@opencrvs/toolkit/events'

export const Workqueues = defineWorkqueues([
  {
    slug: 'assigned-to-you',
    icon: 'PushPin',
    name: {
      id: 'workqueues.assignedToYou.title',
      defaultMessage: 'Assigned to you',
      description: 'Title of assigned to you workqueue'
    },
    query: { assignedTo: { type: 'exact', term: user('id') } },
    action: { type: ActionType.READ }
  },
  {
    slug: 'pending-registration',
    icon: 'PenNib',
    name: {
      id: 'workqueues.pendingRegistration.title',
      defaultMessage: 'Pending registration',
      description: 'Title of pending registration workqueue'
    },
    query: {
      status: { type: 'exact', term: EventStatus.enum.DECLARED },
      flags: {
        anyOf: ['validated'],
        noneOf: [InherentFlags.POTENTIAL_DUPLICATE]
      },
      'legalStatuses.DECLARED.createdAtLocation': {
        type: 'within',
        location: user('primaryOfficeId')
      }
    },
    action: { type: ActionType.READ }
  }
])

Default workqueues

OpenCRVS core provides two workqueues that you do not need to configure. They are not affected by the workqueue scope's ids list — their visibility is determined by the role's record scopes instead.

Workqueue	Shown when	Contents
Drafts	The role has the record.create scope	Records the user has started filling in but not yet submitted. Stored locally on the client until declared.
Outbox	The role has any record.* scope	Records the user has triggered actions on that are queued for synchronization with the server. Useful for offline work — the queue drains once back online.

Controlling visibility of workqueues

A configured workqueue is only visible to users whose role grants the workqueue scope for its slug. The scope carries an ids option listing the slugs the role may see.

// src/data-seeding/roles/roles.ts
{
  id: 'REGISTRATION_AGENT',
  // ...
  scopes: defineScopes([
    // ... other scopes
    {
      type: 'workqueue',
      options: {
        ids: [
          'assigned-to-you',
          'recent',
          'requires-completion',
          'in-external-validation',
          'pending-validation',
          'pending-updates',
          'pending-approval',
          'pending-certification',
          'pending-issuance',
          'correction-requested'
        ]
      }
    }
  ])
}

Notes:

• A workqueue defined in workqueueConfig.ts but not listed in any role's workqueue scope is never shown.

• Two roles may share the same workqueue by listing the same slug in both — there is no per-role override of the underlying query. To give different roles a different view, define separate workqueues with different slugs.

• The Outbox and Drafts workqueues are not affected by ids — they appear automatically.

For the full scope configuration, see Users.

WorkqueueConfig schema

<TODO will be added when openapi is synced>