How to configure OpenHIM Mapping Mediator
The Instant OpenHIE architecture, codebase, and documentation are under active development and are subject to change. While we encourage adoption and extension of the Instant OpenHIE framework, we do not consider this ready for production use at this stage.
OpenHIM mediators are HTTP services that are registered and tracked by the OpenHIM Core. As such, a mediator is not unique in the way it is set up for use in an Instant OpenHIE package. The only requirement is that it be packaged as a Docker image.
The OpenHIM Mapping Mediator, however, is a bit more sophisticated than the average OpenHIM mediator as it is generic and designed for re-use. This mediator usually requires an endpoint configuration(s) to be imported once the mediator is up and running. The endpoint config payload can be sent as a POST request to the
/endpoints path of the mediator. For more information on the Mapping Mediator endpoints, read here.
Note: This guide assumes that you have an existing custom package and that the OpenHIM Mapping Mediator is already set up but has not been configured with endpoints.
To import the mediator endpoint config in an Instant OpenHIE package we use the Instant OpenHIE Config Importer docker image. In your package source code repository, under the
docker directory, create an
importer directory. Your directory structure should now look like this:
Under the importer subdirectory of the docker directory, add a file named
docker-compose.config.yml with the following contents:
The previous example will set up a docker container that will run a custom Node.js script that can send the endpoint config to a running instance of the mediator. The
command for running this container waits for the mediator to be up and running before the import script (endpoint.js) is started.
Next, add the following files under a new volume subdirectory of the docker importer directory (
docker/importer/volume). Add the following files for the volume directory:
example-endpoint.json- the example endpoint configuration file to be imported. For more details on endpoint configs, visit the OpenHIM Mapping Mediator Endpoint Docs.
endpoint.js- a Node.js script that is capable of importing the
example-endpoint.jsoncontents into a Mapping Mediator instance.
Finally, update the contents of your docker
docker/compose.sh script to include the importer docker-compose file. The file could look like the following when updated:
The directory structure should now look like the following:
With all of the docker setup in place, it is now time to import the endpoint in Kubernetes.
For Kubernetes, create an importer directory under the
kubernetes directory. Under the importer directory, add the following files and directories:
example-endpoint-importer-job.yaml- similar to the
docker-compose.config.ymlof the docker scripts, this file will create a Kubernetes job that will be responsible for running the
k8s.sh- to configure, start, and stop the Kubernetes importer jobs.
kustomization.yaml- a tool for customizing Kubernetes configurations. More kubernetes information here.
volume/- this directory will be the same as its docker counterpart. You can copy the docker version and all its contents to this Kubernetes destination.
The package directory structure should now look like the following:
Add the following contents to the
Just like the docker-compose.config.yml, this script will run a
jembi/instantohie-config-importer container as a Kubernetes job. The script will wait for the OpenHIM Mapping Mediator service/pod to be ready before it executes the
Add the following code to the
This config generates a Kubernetes
configMap for the
example-endpoint-importer job based on the contents of the volume folder.
Finally, update the
k8s.sh file with the following script:
With everything set up, you should now be able to start Instant OpenHIE with your custom package and the OpenHIM Mapping Mediator should be running and successfully configured.