Self service portal APIs

[euanmillar]

Problem statement

Customer wants to register the birth from home. If we expose more of our internal GraphQL APIs to system clients, and build out webhooks for status transitions, then a custom built self-service portal can interoperate successfully provided they develop their own solutions to the following assumptions:

Assumptions

3rd party is required to build the self-service portal with own customer authentication mechanism and own mechanism to generate a certificate from the SVG template (that includes handlebars) and a record from the Record Search API or webhook
Record Search API can be used to validate user info on the self-service portal side before allowing an authorised user access to the print certificate API.
No user authentication or authorisation needs to be coded in OpenCRVS. All handled by the 3rd party. 3rd party exposes API access to system client tokens at their own risk.
3rd party maintains own database of submitted notifications at their own risk and can update the status of each record using webhooks.
3rd party is responsible for generating the SVG using handlebars.js and a record returned from the Record Search API, once the record is registered with any corrections included.
OpenCRVS takes on zero penetration testing responsibility for the self-service portal.

Requirements

1. An API to submit a complete declaration, with all data in the form & supporting documents.
2. Every status transition needs to submit a webhook
3. Expose the certificate SVGs to system clients.
4. Allow system clients access to the markBirthAsCertified GraphQL mutation to audit track the printing of a certificate by a 3rd party system.

Tech tasks

Initially I thought that we should iterate the Event Notification API to include FHIR properties for all values. But, system clients might be able to use the GraphQL mutation that Field Agent's use to send complete declarations. The query is called (createBirthRegistration)[https://github.com/opencrvs/opencrvs-core/blob/e22eb27249bbc28c76b426bd7268da89ab9c9bfc/packages/gateway/src/features/registration/root-resolvers.ts#L342].

To see this mutation in action and understand all the parameters you should send to it, do this:

1. Login as a Field Agent
2. Complete the full declaration form, sign the form and add image attachments
3. Submit the form with the Network tab open. You will see the query dispatch.

Try this as a system client.

Create a system client so that you can get hold of a valid JWT after authorisation

Attempt to post a similar GraphQL payload to the gateway createBirthRegistration mutation.
Check if you get any bugs in the backend when doing so.

If you do, let's meet to discuss what needs to be done and create more technical tasks for review by OpenCRVS internal Tech Arch team before continuing

• Iterate the Record Search API to return all statuses to system clients. Currently it only returns REGISTERED, CERTIFIED & ISSUED records. If you edit this line to support these statuses: DECLARED_STATUS, REJECTED_STATUS & VALIDATED_STATUS, then that is all you need to do
• Create a new system client type SELF_SERVICE_PORTAL, and a scope and option to create this system client.
• Enable system clients access to the application config request http://localhost:2021/config in order to gain access to the certificate SVGs block and fonts used. This gist shows how this can be done. The config request returns a JSON object containing a "certificates" array. In the array are URLs from the client like this for the SVG and additionally URLs to all font files used in the cert.
• This is optional if you would like to interoperate from your national system portal using webhooks rather than using the search API explained in the previous step. Iterate webhook dispatch so that all statuses send a webhook. Payload only needs to contain Tracking ID and status.

Now that your external system has access to the certificate SVGs and fonts, then you can use the Record Search API to retrieve a record for printing. You will need to combine the returned record from search with the SVG using the handlebars that are available in the cert in the correct places. For inspiration, you can see how the core React application applies data to a cert using handlebars here.

Once you have created a printable certificate for the citizen and they have downloaded the PDF for printing, you must call the markBirthAsCertified and markBirthAsIssued resolvers. This marks the registration as ISSUED. This initiates the required audit logs and payment.

• Enable system clients access to the markBirthAsCertified and markBirthAsIssued GraphQL request to system clients enabling: Certificate audit via self service portal for any legacy birth and death events.

First, register a birth then print a certificate in the UI (DO NOT SELECT PRINT IN ADVANCE) and keep the network tab open so that you can see the full payload that is sent to both resolvers

Use this payload to build your solution using Postman or Yaak. Add the SELF_SERVICE_PORTAL scope to the markBirthAsCertified & markBirthAsIssued resolvers and ensure that when using the API there are no backend errors.

A GraphQL payload like this to mark the birth as certified seems to be all you need:

{
  "id": "b6f13d23-5897-46ec-88ef-aef9a7aa8577", // same as id returned from record search
  "details": {
    "registration": {
      "trackingId": "BYS6VMC",
      "registrationNumber": "2025BYS6VMC",
      "certificates": [
        {
          "hasShowedVerifiedDocument": true,
          "certificateTemplateId": "birth-certificate",
          "collector": {
            "relationship": "INFORMANT"
          }
        }
      ],
      "draftId": "b6f13d23-5897-46ec-88ef-aef9a7aa8577" // same as id returned from record search
    }
  }
}

When you get a 200 from this, you must immediately call markBirthAsIssued including payment amount. A GraphQL payload like this to mark the birth as certified seems to be all you need:

{
  "id": "b6f13d23-5897-46ec-88ef-aef9a7aa8577", // same as id returned from record search
  "details": {
    "registration": {
      "trackingId": "BYS6VMC",
      "registrationNumber": "2025BYS6VMC",
      "certificates": [
        {
          "hasShowedVerifiedDocument": true,
          "certificateTemplateId": "birth-certificate",
          "collector": {
            "relationship": "INFORMANT"
          },
          "payments": {
            "type": "MANUAL",
            "amount": 7,
            "outcome": "COMPLETED",
            "date": "2025-01-30T17:29:42.504Z"
          }
        }
      ],
      "draftId": "b6f13d23-5897-46ec-88ef-aef9a7aa8577" // same as id returned from record search
    }
  }
}

• Repeat for markDeathAsCertified and markDeathAsIssued resolvers

In order to allow system client access to Events V2, first you must the Events V2 packages. Events V2 is buil around a tRPC API. Read the docs.

For Events V2, your Self Service Portal can make use of a type safe Node JS client that includes documentation.

Here is a gist of how to use it

You notice that all requests go to the "/events" endpoint in the Gateway. This is a pass-through endpoint that leads to this tRPC router: eventRouter

You will notice that a "declare" action exists. This will be equivalent to createBirthRegistration.
In another PR (TBC), you will notice a "certify" action exists. This will be equivalent to markBirthAsCertified.

• You can see here that inside createContext the user information is received. We need to check the token, if it is a system client and use the user-mgnt getSystem endpoint to get the userId (which is systemId) and primaryOfficeId. You can see how we used that endpoint in this PR.

A Task is being created by the core team to apply the Custom Users & Scopes feature to the eventRouter actions. The completion of that dependency is required before the following can be developed:

• Enable system clients access to the Events V2 "declare" endpoint supporting submission of a new Evens V2 declaration
• Enable system clients access to the Events V2 "certify" endpoint supporting: Certificate submission and audit via self service portal

Finally when Events V2 Beta is released, the payloads will be finalised for use. In the meantime, these endpoints can be monitored by using the gist.

[prinzab]

Uganda requirements

Notifiers can assess a public site to self submit an event declaration

• The notification must be sent to the Registration Officer in the place where the event occurred
• The notifier should be able to indicate where they want the certificate delivered (or to pick up??)

Note: Self Notifications shouldn't come from Health Facilities that are already known in the reference data

[rikukissa]

In Events v2, we can expose some event and action creation APIs through the @opencrvs/toolkit library. This would provide countries with a great development experience from the start, and potential incompatibilities between upgraded OpenCRVS versions and built integrations would be easily identifiable and fixable due to strict typing.

@naftis, what is the latest strategy for how the self-service portal authenticates to the core before making API requests? If I recall correctly, service clients are created manually, which doesn’t suit many real use cases. It brings me back to the idea that core could, when it starts and periodically from that moment, generate JWT integration tokens that it sends to country config. Country config would then use this token to call back to core

[naftis]

@rikukissa Webhook clients are created manually via sysadmin config UI, yes. There are different options on how the integrations could be completely moved to country-config; seeding comes into mind with notifying a configured email with the API keys.

Anyway, the way it currently works should be able to solve the issue in hand here

[euanmillar]

Pull request: #8286