Registration integration

Interoperating with a National ID system at the point of registration, both synchronously and asynchronously.

In the OpenCRVS UI, when a registrar clicks the "Register" button on a fully complete and validated declaration, the legal authority has been given to create a birth registration. It is then possible to integrate with a National ID system, both synchronously and asynchronously.

Synchronous integration - birth & death

Once internal audit has taken place of that action in the "workflow" microservice, the following endpoint in the configurable countryconfig microservice is called while the registration is in a WAITING_VALIDATION status:

/event-registration

The entire registration data payload is sent to this endpoint as a FHIR Bundle.

The JWT token that is sent to this payload can be used in asynchronous operations explained below.

In our example we create a birth / death registration number at this point and return the amended payload to OpenCRVS. Any synchronous interaction with a National ID system can take place here.

If a 200 is returned from this handler, the record will proceed to register, gaining a REGISTERED status, and appear in the Ready To Print work queue.

If any error occurs such as a 500, the record will be placed in a REJECTED status with the reason being equal to whatever error code or message is available.

The following library can return a graceful rejection message.

@hapi/boom badImplementation

Aynchronous integration - birth & death

It is possible to use the same endpoint asynchronously. But first, the following setting must be set to true in application-config.ts:

EXTERNAL_VALIDATION_WORKQUEUE: true

This configuration setting enables a work-queue "In external validation" that can hold records in a WAITING_VALIDATION status until an asynchronous process completes.

The JWT token that is sent to the /event-registration endpoint & the birth / death registration number that is generated here, must be stored by your asynchronous process and used in the next operation.

Using the JWT, you can call the gateway microservice GraphQL endpoint confirmRegistration resolver.

You can decode the JWT and retrieve the internal record uuid - the variable id used in the payload.

POST https://gateway.<your_domain>/graphql
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "operationName": "confirmRegistration",
  "query": "mutation confirmRegistration(
        $id: ID!
        $details: ConfirmRegistrationInput!
      ) {
        confirmRegistration(id: $id, details: $details)
      }",  
  "variables": {
      "id":"<record uuid from JWT>",
      "details": {
        "identifiers": [{
          "type": "NATIONAL_ID",
          "value": "<optionally store created natonal id at birth for use in OpenCRVS search / certificate>"
        }],
        "registrationNumber": "<Birth / Death Registration Number>",
        "comment": "<optionally store an audit log comment>",
      }
  }
}