Workqueues

Configuring workqueues

This is technical documentation. For the functional overview of workqueues, see 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.

A list of configured workqueues

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.

Configuring workqueues

Workqueues are configured in 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 workqueue 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 workqueue config from src/api/workqueue/workqueueConfig.ts:

// 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 }
  }
])

Filtering by flags

The flags filter in a workqueue query accepts three lists of flags, which can be combined:

• anyOf — the record has at least one of the listed flags.

• allOf — the record has every one of the listed flags.

• noneOf — the record has none of the listed flags.

When more than one list is given, a record must satisfy all of them. For example, a "Pending approval" workqueue that shows only declarations that are both validated and flagged for late-registration approval:

query: {
  status: { type: 'exact', term: EventStatus.enum.DECLARED },
  flags: {
    allOf: ['validated', 'approval-required-for-late-registration'],
    noneOf: [InherentFlags.POTENTIAL_DUPLICATE]
  }
}

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