OpenHIM Mediators are separate micro services that run independently to the OpenHIM and perform additional mediation tasks for a particular use case. The common tasks within a mediator are as follows:
Message format adaptation - this is the transformation of messages received in a certain format into another format (eg. HL7 v2 to HL7 v3 or MHD to XDS.b).
Message orchestration - this is the execution of a business function that may need to call out to one or more other service endpoint on other systems. (eg. Enriching a message with a client’s unique identifier retrieved from a client registry then sending the enriched message to a shared health record).
Mediators can be built using any platform that is desired (some good options are pure Java using our mediator engine, Node.js, Apache Camel, Mule ESB, or any language or platform that is a good fit for your needs).
The only restriction is that the mediator MUST communicate with the OpenHIM-core in a particular way.
Mediators must register themselves with the OpenHIM-core, accept request from the OpenHIM-core and return a specialised response to the OpenHIM-core to explain what that mediator did.
If you are interested in developing your own mediators, see the documentation available here and see the tutorials page for specific examples to get you started.
Security guidance: Mediator authorization to OpenCRVS data#
OpenCRVS FHIR Resources contain sensitive patient data. When you are writing your mediator, it is your responsibility as an OpenCRVS implementor in your nation to ensure that you security check the accessing client.
The following steps are essential:
Your mediator must be hosted on the OpenCRVS stack, as it communicates to auth and OpenHIM internally through Docker Swarm.
The mediator's exposed client endpoints must be protected by SSL so that data is encrypted in transit. Use the traefik.toml file to set up an outside, SSL protected endpoint.
The endpoints must enforce JWT authentication
The endpoints must check the validity of the JWT by verifying the token with the OpenCRVS auth service, following the example code.
The endpoints must check the scope of the JWT before permitting any further requests for sensitive patient data.
Once the mediator has been written, tested and peer reviewed, it must be penetration tested by an equivalent independent, CREST equivalent certified penetration testing organisation before deployment.
The following sequence diagram describes a Mediator that is developed to receive information from an OpenCRVS Webhook. But Mediators can be developed to perform any action.
Requesting the FHIR Composition for a birth event#
The payload of the birth registration event webhook contains the FHIR Composition id, that can be used to retrieve all subsequent details for the registration.
Therefore, the FHIR Composition id is a powerful identifier and should only be accessible by approved government systems, such as those using health or nationalId JWT scopes. If you are proposing a new webhook in a feature request, consider the resourceType that your service requires, based on the explanation of the FHIR resources in the rest of this page. You should not need to expose the composition id in your mediator if your client service doesnt require it.
The unique id for the FHIR resource target that this webhook refers to.
Requesting the FHIR Patient data for individiuals associated with the event#
The FHIR patient resource contains all names, addresses, contact details, gender details and other information.
It also contains an array of identifiers for which the created National ID, alongside other IDs such as Social Security or Birth Registration Number can be stored.
For standardised addresses ie: states, districts and other administrative structure levels, configurable FHIR Location resources can be loaded into OpenCRVS and referred to by their resource id in the address.
You can read more about FHIR Locations in later sections below.
YOUR MEDIATOR MUST FOLLOW THE SECURITY GUIDANCE ABOVE, BEFORE PERMITTING ACCESS TO SENSITIVE, IDENTIFIABLE PATIENT DATA
You can request all resources via OpenHIM in subsequent individual requests following this example URL for a Patient, to retrieve the details of the mother. So the format is your-openhim-core-url / resourceType / id :
Created from the previous composition like this:
The address type can be PERMANENT and CURRENT both or either may be required depending on civil registration legislation in the country. Address lines, districts and states can be set to FHIR Location ids (explained below) to ensure statistical standardisation.
Requesting the FHIR Task for a birth event contianing the Birth Registration Number#
The FHIR Task FHIR Bundle contains valuable audit information regarding the event. It contains the generated Birth Registration Number from the event which is later saved into the Patient's identifiers.
To request the FHIR Task FHIR Bundle associated with the event use the Composition id:
The extensions contain contact details for the event. regLastLocation contains a FHIR Location reference for the administrative area where the birth was registered. regLastOffice contains a FHIR Location reference for the civil registration office where the birth was registered. regLastUser contains a FHIR Practitioner reference for the civil registration officer who registered the event.
The businessStatus code will be either REGISTERED or CERTIFIED for a valid registration.
Requesting the FHIR Observations for a birth event#
A number of other configurable and unidentifiable data points can be captured for the event lifecycle, such as; who was present at the birth, what was the birth weight etc.
For this kind of data, we use FHIR Observations.
To request all the Observations associated with the event use the birth-encounter resource reference:
Authorization: Bearer <token>
Multiple FHIR Resources are returned in a FHIR Bundle containing an entry array.
You will find many FHIR Location ids throughout the resources, such as place of birth, patient addresses, places of registration etc.
These return FHIR Location resources that refer either to either facilities with address and contact details, or administrative areas such as districts and states.
FHIR Locations also contian multiple identifiers including an ID that should be defined by your government statistical department and aligns across all systems.
In OpenCRVS we extend FHIR Locations to include other statistical data related to calculating civil registration performance estimates such as the crude birth rate & populations for a location by year.
The following sequence diagram describes a Mediator that is designed to receive information from an OpenCRVS Webhook and submit it to a MOSIP or National ID system webhook.
This use case would be for generating a National ID from a birth event. The process is likely to be asynchronous so a webhook should be designed in the National ID system also.
OpenCRVS is not currently designed to store biometric data and processing biometrics is outside the scope of a civil registration system currently. But the OpenCRVS team is working in partnership with Simprints - last mile biometric identification for universal health coverage to define an architecture where OpenCRVS could integrate with the SImprints device and include a link to the Simprints biometrics in a FHIR Observation.
The format of the biometrics must conform to CBEFF XML for compatibility with MOSIP.