Other ways to interoperate
Direct interoperability with OpenHIM
It is possible to expose the interoperability layer: OpenHIM for direct integration with OpenCRVS' Hearth database.
Exposing OpenHIM for API access bypasses the auditing capabilities that are native to OpenCRVS. You must consider the risk and develop your own audit trail to track custom API access to citizen data should you expose OpenHIM. OpenHIM's logging history is configured to refresh after 30 days. You should fully understand OpenHIM before proceeding.
Before exposing OpenHIM, consider getting in touch with us at team@opencrvs.org in order to request an API feature. We could develop a client for you that protects citizen data with a native OpenCRVS audit trail.
Expose OpenHIM via a Traefik whitelist
In order to expose OpenHIM to be accessible on the public internet, you must comment in these lines in the docker-compose.deploy.yml file.
You must enter a comma separated list of trusted IP addresses to the whitelist property.
You need to create a DNS record to expose the api.<your-domain> endpoint to OpenHIM.
Now you can create your own microservice Mediator and register it with OpenHIM following the OpenHIM documentation.
What are OpenHIM Mediators?
Mediators are separate microservices that run independently to OpenCRVS 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, read the OpenHIM Documentation
Security guidance
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:
Mediator authorisation to OpenCRVS data
The mediator's exposed client endpoints must be protected by SSL so that data is encrypted in transit.
The endpoints must enforce JWT authentication.
The endpoints must check the scope of the JWT before permitting any further requests for business functions you feel are relevant to that scope.
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.