Version: 8.0.x

Create Mediator

Add Mediator#

To add a mediator, you will need to make a TLS request to the OpenHIM API for the below method and endpoint and supply the JSON object of the mediator.

Method: POST
Endpoint: {openhim_url}:8080/mediators
Payload: JSON object of the mediator

Examples#

Note: In the examples below, we are using the token authentication type to authenticate requests

Adding Mediator Example#

Languages
Sample Data

Before we can send our request to the OpenHIM API we need to ensure that we construct our valid HTTP headers to successfully authenticate with the OpenHIM API.

NodeJS
Bash

Copy the below code at the bottom of your nodejs script that handles the authentication of the OpenHIM headers as described in the authentication section.

Replace the openhimOptions values with the correct implementation details and supply the SampleData payload to submit.

// append below code to the "openhim-api.js" script containing the authentication methods.
// This is described within the authentication section

(async () => {
  const openhimOptions = {
    apiURL: 'https://localhost:8080',
    apiEndpoint: '/mediators',
    username: '[email protected]',
    password: 'openhim-password',
    rejectUnauthorized: false
  }

  const SampleData = 'SampleData'
  const headers = await genAuthHeaders(openhimOptions)

  const options = {
    method: 'POST',
    url: `${openhimOptions.apiURL}${openhimOptions.apiEndpoint}`,
    rejectUnauthorized: openhimOptions.rejectUnauthorized,
    headers: headers,
    body: SampleData,
    json: true
  }

  request(options, (error, response, body) => {
    if (error) throw new Error(error)

    console.log({
      statusCode: response.statusCode,
      body
    })
  })
})()

Execute the below command in your terminal to run the nodejs script

node openhim-api.js

Ensure that you have created your bash script to construct the HTTP authentication headers and send the request to the OpenHIM API as described in the authentication section.

Execute the below command in your terminal where the file is located with the required arguments. Replace the placeholder arguments with the correct implementation details and ensure your SampleData.json file exists with the mediator object.

./openhim-api.sh [email protected] openhim-password -v https://localhost:8080/mediators -d @SampleData.json -H "Content-Type:application/json"

The response status code will be 201 if successful.

Send heartbeat to the OpenHIM#

To send a heartbeat to the OpenHIM, you need to make a TLS request to the OpenHIM API for the below method and endpoint and supply the JSON object containing the mediator's uptime and config (an optional boolean which is used to determine whether the OpenHIM should return the latest config).

Method: POST
Endpoint: {openhim_url}:8080/mediators/:urn/heartbeat
Payload: JSON object containing mediator's uptime and config

The urn parameter is the unique resource name of the mediator. The heartbeat endpoint can only be accessed by an admin user.

The response will always have a 200 status if successful or a 404 if the mediator specified by the urn cannot be found. The response body will contain the latest mediator config that has been set on the OpenHIM-core server only if the config has changed since the last time a heartbeat was received from this mediator. Otherwise, the response body is left empty.

Sending Heartbeat Example#

Languages
Sample Data

Before we can send our request to the OpenHIM API we need to ensure that we construct our valid HTTP headers to successfully authenticate with the OpenHIM API.

NodeJS
Bash

Copy the below code at the bottom of your nodejs script that handles the authentication of the OpenHIM headers as described in the authentication section.

Replace the openhimOptions values with the correct implementation details and supply the SampleData payload to submit.

// append below code to the "openhim-api.js" script containing the authentication methods.
// This is described within the authentication section

(async () => {
  const openhimOptions = {
    apiURL: 'https://localhost:8080',
    apiEndpoint: '/mediators/:urn/heartbeat',
    username: '[email protected]',
    password: 'openhim-password',
    rejectUnauthorized: false
  }

  const SampleData = 'SampleData'
  const headers = await genAuthHeaders(openhimOptions)

  const options = {
    method: 'POST',
    url: `${openhimOptions.apiURL}${openhimOptions.apiEndpoint}`,
    rejectUnauthorized: openhimOptions.rejectUnauthorized,
    headers: headers,
    body: SampleData,
    json: true
  }

  request(options, (error, response, body) => {
    if (error) throw new Error(error)

    console.log({
      statusCode: response.statusCode,
      body
    })
  })
})()

Execute the below command in your terminal to run the nodejs script

node openhim-api.js

Ensure that you have created your bash script to construct the HTTP authentication headers and send the request to the OpenHIM API as described in the authentication section.

./openhim-api.sh [email protected] openhim-password -v https://localhost:8080/mediators/:urn/heartbeat -d @SampleData.json -H "Content-Type:application/json"

The response status code will be 200 if successful.

Install mediator channels#

To install channels that are listed in the mediator's config ( defaultChannelConfig property ), you need to make a TLS request to the below method and endpoint and supply an array with the names of the channels to install.

Method: POST
Endpoint: {openhim_url}:8080/mediators/:urn/channels
Payload: An JSON array containing the channel names

Note: If the JSON array is not supplied all the channels in the defaultChannelConfig will be installed.

Install Channels Example#

Languages
Sample Data

Before we can send our request to the OpenHIM API we need to ensure that we construct our valid HTTP headers to successfully authenticate with the OpenHIM API.

NodeJS
Bash

Copy the below code at the bottom of your nodejs script that handles the authentication of the OpenHIM headers as described in the authentication section.

Replace the openhimOptions values with the correct implementation details and supply the SampleData payload to submit.

// append below code to the "openhim-api.js" script containing the authentication methods.
// This is described within the authentication section

(async () => {
  const openhimOptions = {
    apiURL: 'https://localhost:8080',
    apiEndpoint: '/mediators/:urn/channels',
    username: '[email protected]',
    password: 'openhim-password',
    rejectUnauthorized: false
  }

  const SampleData = 'SampleData'
  const headers = await genAuthHeaders(openhimOptions)

  const options = {
    method: 'POST',
    url: `${openhimOptions.apiURL}${openhimOptions.apiEndpoint}`,
    rejectUnauthorized: openhimOptions.rejectUnauthorized,
    headers: headers,
    body: SampleData,
    json: true
  }

  request(options, (error, response, body) => {
    if (error) throw new Error(error)

    console.log({
      statusCode: response.statusCode,
      body
    })
  })
})()

Execute the below command in your terminal to run the nodejs script

node openhim-api.js

Ensure that you have created your bash script to construct the HTTP authentication headers and send the request to the OpenHIM API as described in the authentication section.

./openhim-api.sh [email protected] openhim-password -v https://localhost:8080/mediators/:urn/channels -d @SampleData.json -H "Content-Type:application/json"

The response status code will be 201 if the channels were successfully created and 400 if you provide a channel name that doesn't exist.

Ensure that the channels name supplied in the JSON array match the names of the channels supplied in the defaultChannelConfig, when the mediator was created.

  ["Save Encounter 1"]