4.2.6.1 Working with events

All technical concepts related to Events are collated in this README

Using concepts introduced in the README above, along with an understanding of the metadata properties associated with an event, you can configure any type of event you like in OpenCRVS.

Serving events to OpenCRVS Core

Events that are configured in your countryconfig service are made available to core from this endpoint.

Examples for birth and death are provided, along with an example tennis club membership event (just to demonstrate the flexibility of OpenCRVS as a general registry showing usage of more form components).

Your first configuration is probably going to be: to comment out the tennis club membership example event from this handler and any mention of the tennis-club-membership Event ID from associated user scopes in the roles.ts file.

Configuring a new v2 event with EventConfigInput

In OpenCRVS ≥ 1.9, each event in your country configuration is defined in the src/form/v2 directory.

The central building block is an EventConfigInput object – a Zod-validated input shape for the EventConfig type in opencrvs-core (packages/commons/src/events). This object captures, for a single event:

• the event identifier (critical)

• the declaration form (what users fill in to declare the event) with the associated review form used in Declare and Validate event.

• the search form (the fields available in Search for a record) and deduplication algorithm query

• the summary configuration (what you see in the record “card” when you click an item in a workqueue or search result)

• the title, template, label, and dateOfEvent field mapping

• the print certificate form (the fields available in Print Certificate)

• the correction form (the fields available in Correct Record)

Core reads an array of these configs from your countryconfig /custom-event endpoint and uses them to power the event flows described in the events README

Where v2 event configs live

All v2 events are defined under:

src/form/v2/

✅ When adding a new v2 event, only work inside src/form/v2. Ignore the legacy src/form/<event> directories used in v1.8 – the v2 engine is completely separate.

The birth event at src/form/v2/birth/index.ts is your reference implementation for how to construct an EventConfigInput for an event.

---

Configure the declaration form

The declaration form configuration is a complex subject. Covered in the next section 4.2.6.2 Configure an event declaration form

---

Configure the search form

Next, configure the search form portion of EventConfigInput, which controls the “Search for a record” UI for this event.

Conceptually, the search form is:

• A set of search fields (e.g. name, registration number, event date range, place).

• Grouped into basic / advanced panels if desired.

• Mapped to backend query parameters or index fields.

Typical design:

• Quick search

  • A small set of highly discriminative fields (e.g. registration number, national ID, or name + date of event).

• Advanced search

  • Additional filters (location, informant type, status, office, etc.).

Process:

1. Decide which fields users genuinely need to search on for this event.

   • Start from what is actually stored and indexed in Core.

2. Re-use existing field definitions where it makes sense (e.g. same labels and message IDs) but remember:

   • Search fields typically don’t need the heavy validation of the declaration form.

   • They do need to map reliably to backend query fields.

3. Define the search form structure for the event, using whichever v2 helpers birth uses for its search config.

In the EventConfigInput:

export const yourEventConfig: EventConfigInput = {
  // ...
  searchForm: buildSearchForm(),           // fields & groups used in “Search for a record”
  // ...
}

When Core loads this config, it uses it to render the search UI for that event and construct the query payload for the Search for a record flow.

---

Configure the summary (workqueue / search result card)

Finally, configure the summary portion of EventConfigInput – the little “card” you see when you:

• click a record in a workqueue, or

• select a record from the search results and view its details. documentation.opencrvs.org

This summary usually shows:

• key identity info (names)

• event specifics (event date, place)

• registration details (registration number, office)

• current status (Registered, Requires updates, etc.)

Process:

1. Identify the minimal set of fields that allow a registrar to:

   • confirm they have the right record, and

   • quickly assess its status.

2. Map each summary item to an underlying field path or handlebar (often the same as used for certificates and FHIR mappings).

3. Arrange them in a sensible order and grouping (e.g. top line: name and registration number; second line: event date and place; third line: status and office).

In the EventConfigInput:

export const yourEventConfig: EventConfigInput = {
  // ...
  summary: buildSummaryConfig(),           // fields shown in record “card”
}

When Core renders a workqueue or search results, it uses this summary config to build the compact record view.

---

Configuring Actions inside EventConfigInput

Every v2 event must define an actions array inside its EventConfigInput. These actions tell OpenCRVS Core what workflows are available for this event, and which forms are used during each workflow step.

The actions array has multiple responsibilities:

1. Configure the “review” form used when reviewing a completed declaration

2. Configure the “print” form used when printing a certificate

3. Configure the “correction” form used when requesting a correction

4. Configure the deduplication query for detecting duplicate events via Elasticsearch

This makes actions one of the most important parts of an event’s configuration.

What each action represents

OpenCRVS Core defines a fixed set of ActionTypes (e.g. READ, DECLARE, VALIDATE, REGISTER, PRINT_CERTIFICATE, REQUEST_CORRECTION, etc.). Each event chooses which of those actions it supports, and optionally:

• the form used for that action

• the deduplication query

• the label for buttons, menus and logs

The action objects in the actions array look like this:

actions: [
  {
    type: ActionType.READ,
    label: { ... },
    review: REVIEW_FORM
  },
  {
    type: ActionType.PRINT_CERTIFICATE,
    label: { ... },
    printForm: CERTIFICATE_COLLECTOR_FORM
  },
  {
    type: ActionType.REQUEST_CORRECTION,
    label: { ... },
    correctionForm: CORRECTION_FORM
  },
  {
    type: ActionType.DECLARE,
    label: { ... },
    review: REVIEW_FORM,
    deduplication: {
      id: '...',
      label: { ... },
      query: dedupConfig
    }
  }
]

Let’s break down what each kind of action is for.

---

Action Type 1: Review Form

“Used when reviewing a completed declaration”

Actions such as:

• READ

• DECLARE

• VALIDATE

• REGISTER

…include a:

review: <FORM>

This review form is displayed when:

• a registrar opens a declaration to check data before submitting it

• a validator reviews the record

• a registration officer is confirming the final registration

This form typically shows all collected data in a read-only or semi-editable manner with consistent grouping.

For example:

{
  type: ActionType.READ,
  label: { ... },
  review: BIRTH_DECLARATION_REVIEW
}

---

Action Type 2: Print Certificate Form

“Used when printing (collecting) a certificate”

When a registration is complete, registrars may issue a certificate.

Actions of type:

• PRINT_CERTIFICATE

…must define a:

printForm: <FORM>

This print form captures any additional fields required only at the time of certificate issuance, such as:

• identity of the person collecting the certificate

• proof of identity

• certificate serial number (if applicable to the country)

• certificate fees associated

Example:

{
  type: ActionType.PRINT_CERTIFICATE,
  label: { ... },
  printForm: BIRTH_CERTIFICATE_COLLECTOR_FORM
}

---

Action Type 3: Correction Form

“Used when performing corrections after registration”

Corrections require a separate workflow from declaration.

Actions of type:

• REQUEST_CORRECTION

…must define a:

correctionForm: <FORM>

This form captures all required fields when someone requests modifications after the event is registered, e.g.:

• reason for correction

• supporting documentation

• identity of the requester

• corrected fields

Example:

{
  type: ActionType.REQUEST_CORRECTION,
  label: { ... },
  correctionForm: CORRECTION_FORM
}

This ensures all countries can enforce their specific legal requirements for post-registration changes.

---

Deduplication configuration

“Defines the Elasticsearch query used to detect duplicates”

Some actions (e.g. DECLARE, VALIDATE, REGISTER) may include a deduplication section:

deduplication: {
  id: 'birth-deduplication',
  label: { ... },
  query: dedupConfig
}

This has three parts:

Property	Purpose
id	A unique identifier for this deduplication configuration
label	User-facing label (e.g. “Detect duplicate”)
query	The actual Elasticsearch query used to find potential duplicate registrations, configured using these helpers.

How it works

When a user triggers an action that includes a dedupe config:

1. Core takes the event data from the form

2. Runs the dedupConfig Elasticsearch query

3. Displays a list of possible duplicates before continuing

Typical dedupe fields include:

• person’s name

• date of event

• place of event

This prevents:

• double registration

• clerical duplication

• fraud

You may define multiple dedupe-enabled actions if your workflow requires checking duplicates at different stages.

---

Testing your new event end-to-end

After wiring everything up:

1. Run OpenCRVS Core + your countryconfig (as per usual dev setup).

2. Hit the /custom-event endpoint and confirm:

   • Your new event appears with the correct eventType / key / version.

   • declarationForm, searchForm and summary sections are present in the payload.

3. In the UI:

   • Declare the new event and walk through all sections/groups:

     • required/optional fields behave as expected

     • conditionals and validation work

   • Register the event, reviewing, printing and correcting it. Verify forms / views / certificates behave as expected.

   • Use Search for a record:

     • confirm your new search form appears,

     • filters apply correctly and return the expected records.

   • Click a result / workqueue item:

     • confirm the summary card matches your configuration.

---

Further reading:

An explanation regarding how events are stored in the database.

OpenCRVS API Documentation

https://api.opencrvs.org/develop/events/index.html