Skip to main content

Setup

The Mapping mediator can be setup within a NodeJS environment using Yarn or with Docker. In either case, it depends on MongoDB setup as a replica set. The mediator is configured using environment variables. Setting up the OpenHIM (Core and Console) is recommended but not required.

This guide is aimed at Linux users.

Follow our YouTube setup video for a step by step guide.

Prerequisites​

To store endpoint data:

Get code from Github​

To get the OpenHIM Mediator Mapping code from GitHub, execute any of the below commands to get the codebase

Cloned repository:

git clone https://github.com/jembi/openhim-mediator-mapping.git

Zipped repository:

wget https://github.com/jembi/openhim-mediator-mapping/archive/master.zip

Zipped release version. Tagged releases can be downloaded by executing the below command, and replacing the <RELEASE_VERSION> placeholder with an actual release tag: E.g v2.3.1

wget https://github.com/jembi/openhim-mediator-mapping/releases/download/<RELEASE_VERSION>/build.openhim-mediator-mapping.<RELEASE_VERSION>.zip

Setup Mongo Replica Set for Docker Env​

Note: The Mongo replica set config between the docker and yarn setup instructions are NOT interchangeable.

This set up guide will make use of Docker to run the Mongo cluster and the Mapping Mediator. The containers will connect with each other over a Docker Network.

The easiest way to setup the mongo containers is to use a docker-compose script. One is provided in the repo (docker-compose.mongo.yml)

Run the script from the project root directory with the following command:

docker-compose -f docker-compose.mongo.yml up -d

Once the containers have started up exec into one of the containers with the following command, docker exec -it mapper-mongo-1 mongo

Inside the shell enter the following:

config = {
  "_id": "mapper-mongo-set",
  "members": [
    {
      "_id": 0,
      "priority": 1,
      "host": "mapper-mongo-1:27017"
    },
    {
      "_id": 1,
      "priority": 0.5,
      "host": "mapper-mongo-2:27017"
    },
    {
      "_id": 2,
      "priority": 0.5,
      "host": "mapper-mongo-3:27017"
    }
  ]
}

rs.initiate(config)

Registering with the OpenHIM​

The mapping mediator, like most other OpenHIM mediators, can register to an instance of the OpenHIM. This gives the user a graphical interface to interact with the mediator for status information and config options(if available).

Note: For multiple instances of the mediator to register to the same instance of the OpenHIM each mediator has to have a unique urn. You can set the urn using the environment variable MEDIATOR_URN.

To get an OpenHIM Core and Console instance setup, use the docker-compose.openhim.yml script here (or your preferred method). Run the docker compose command with the following:

docker-compose -f docker-compose.openhim.yml up -d

Open a browser and navigate to http://localhost:9000. Login with the default username root@openhim.org and password openhim-password then by-pass the security warnings. For more information on how to do this see our OpenHIM set up tutorial. Finally, set your new openhim root user password.

Docker Mediator Start Up​

To register as a mediator, you will need the following environment variables:

  • OPENHIM_URL=https://openhim-core:8080
  • OPENHIM_PASSWORD={openhim_password}
  • MONGO_URL=mongodb://mapper-mongo-1:27017,mapper-mongo-2:27017,mapper-mongo-3:27017/mapping-mediator?replicaSet=mapper-mongo-set
docker run -e OPENHIM_URL=https://openhim-core:8080 -e OPENHIM_PASSWORD={openhim_password} -e MONGO_URL=mongodb://mapper-mongo-1:27017,mapper-mongo-2:27017,mapper-mongo-3:27017/mapping-mediator?replicaSet=mapper-mongo-set --network mapper-cluster-network --name mapper -d jembi/openhim-mediator-mapping:latest

Note: The Mapping Mediator is not exposed to your local machine in this case. All requests would need to go through the OpenHIM. To expose the Mapping Mediator port to your local machine include the following flag in your run command: -p 3003:3003

To see the output logs of the mapping mediator run the following command:

docker logs -f mapper

Here you should see the message: Successfully registered mediator!

Finally, go back to your browser and navigate to the Mediators section. Here you should see your mapping mediator instance registered on the OpenHIM with a recent heartbeat.

Environment Variables​

The supported environment variables are listed as follows:

Variable NameDescriptionDefault Value
SERVER_PORTThe server port to start the application on3003
LOG_LEVELThe log level at which the logs should be printed outinfo
ENABLE_LOGGINGDefine if the application should print out any logstrue
MONGO_URLThe MongoDB url for connecting to the replica set databasemongodb://localhost:27017,localhost:27018,localhost:27019/mapping-mediator?replicaSet=mapper-mongo-set
OPENHIM_URLThe URL to the OpenHIM instance.
If running the OpenHIM in a docker container substitute in the container name instead of localhost.		https://localhost:8080
OPENHIM_USERNAMEThe OpenHIM user to authenticate withroot@openhim.org
OPENHIM_PASSWORDThe OpenHIM password for the supplied user to authenticate withopenhim-password
TRUST_SELF_SIGNEDBypass the nodejs ssl certificate check on self signed certificates.
Only set this variable to true if you are using it in a non-production environment		true
OPENHIM_REGISTERSet to false if you do not wish to have this mediator register itself with the openhim instancetrue
ENABLE_LOGGINGOutput logstrue
PARSER_LIMITDefine the incoming body limit size. If the incoming body is bigger than the specified limit, the validation will fail1mb
PARSER_XML_OPTIONS_TRIMTrim the whitespace at the beginning and end of text nodestrue
PARSER_XML_OPTIONS_EXPLICIT_ROOTSet this if you want to get the root node in the resulting objectfalse
PARSER_XML_OPTIONS_EXPLICIT_ARRAYAlways put child nodes in an array if true; otherwise an array is created only if there is more than onefalse
VALIDATION_ACCEPT_NULL_VALUESThis is used to configure the validation middleware to accept null valuesfalse
VALIDATION_COERCE_TYPESAllow the validation middleware to coerce the incoming data values into the defined validation type. If the property validation type is defined as number and the value being supplied is a string, then the validation middleware will format the value into a numberfalse
DYNAMIC_ENDPOINTSDefine wether MongoDB should create a listener on the Endpoints collection to automatically apply endpoint changestrue
MEDIATOR_URNSet a unique identifier to allow for multiple openhim-mediator-mapping instances to be registered to the OpenHIM.urn:mediator:generic_mapper