OpenHIM mediators are components that mediate transaction for the OpenHIM. This includes the following sort of functionality:

• Adapting and transforming between different message formats (normalising incoming message formats and denormalising outgoing message formats)
• Performing transaction orchestration - that is executing a business process that may need to consume the interfaces of multiple other external systems and precess the result to perform some function.

There can be multiple mediators attached to the OpenHIM-core. Each of these should be independent and perform a single function. These mediators should plug into the OpenHIM-core so more mediators can be added over time and so that implementations can deploy only the mediators that are required for their use case.

Each of these mediators should be an external service so that they can deployed independently and they can be build using any technology stack that makes sense for the mediators use case as long as they can communicate with the OpenHIM-core though the defined interface. This enables great potential for scalability and also allows mediators to focus on a single concern. This follows a micro service architecture. For additional benefits and details of this architecture please see the following resources:

• http://martinfowler.com/articles/microservices.html
• https://blog.yourkarma.com/building-microservices-at-karma

For each mediator to communicate with the OpenHIM-core it will need to be able to talk to the OpenHIM's interfaces. There are 3 major interactions the mediators should have with the OpenHIM-core:

1. Mediators register themselves with the core
2. Communicate metadata about transactions that the mediator processes
3. Communicate metrics for transaction that the the mediator processes

Registering mediators

Every mediator SHALL register itself with the OpenHIM core each time it starts up. The registration process informs the OpenHIM core of some useful details:

• An identifier and name to associate with the OpenHIM-core
• The hostname or IP address of the mediator
• Default channel configuration that should be applied to the OpenHIM-core that the mediator needs
• The endpoints that the mediator exposes that the OpenHIM can contact it on.

In order to do this the mediator SHALL send a API request to the OpenHIM-core with the following format:

POST http://<openhim-core_host>:<api_port>/mediators

with a body contain the following sample structure:

{
	uuid: "<a UUID>", // A unique identifier to identify the mediator, this identifier should always stay the same even if the mediator changes
	version: "", // the version of the mediator, if this is incremented the OpenHIM-core will update the channel configuration - expects a semver string
	name: "", // a human readable name for the mediator
	defaultChannelConfig: [ // (optional) an array of default channels to add for this mediator
		{ ... }, // a channel object as defined by the OpenHIM-core
		{ ... }
	],
	endpoints: [ // (A minimum of 1 endpoint must be defined) an array of endpoints that the mediator can be contacted on
		{ ... }, // a route object as defined by OpenHIM-core - https://github.com/jembi/openhim-core-js/blob/master/src/model/channels.coffee#L5-L15
		{ ... }
	]
}

The OpenHIM-core SHALL respond with a HTTP status of 201 if the mediator registration was successful.

The OpenHIM-core SHALL respond with an appropriate 4xx status if the mediator registration could not be completed due to a bad request

The OpenHIM-core SHALL respond with an appropriate 5xx status if the mediator registration could not be completed due to server error in the OpenHIM-core

Communicate transaction metadata

The mediator SHOULD return a structured object that indicates the response that should be returned to the user as well as metadata about the actions that were performed. This structured object should be returned in the HTTP response for each request that the OpenHIM-core send to the mediator. The mediator MUST return this object with a content-type header with the value: 'application/json+openhim'. If the mediator wants to set a specific content-type to return to the client, they can set this in the response object as a header.

The JSON object returned to the OpenHIM should take the following form:

{
	"status": "Successful", // (optional) an indicator of the status of the transaction, this can be one of the following: ['Processing', 'Failed', 'Completed', 'Successful', 'Completed with error(s)']
	"response": { ... }, // a response object as defined by OpenHIM-core - https://github.com/jembi/openhim-core-js/blob/master/src/model/transactions.coffee#L13-L18
	"orchestrations": { ... }, // (optional) an array of orchestration objects as defined by OpenHIM-core - https://github.com/jembi/openhim-core-js/blob/master/src/model/transactions.coffee#L26-L30
	"properties": { // (optional) a map of properties that the HIM may want to report
		"pro1": "val",
		"pro2": "val"
	}
}

Communicating transaction metrics

The mediator MAY return transaction metrics about the transaction that is processes. There are 2 mechanism that a mediator can use to report metrics. A mediator MUST only use one of these mechanisms. Each mechanism is described in the sections below.

Reporting metrics in the response

This is the simplest mechanism. A mediator add a metrics object to the response object and inserts metrics it captures into this property. The OpenHIM-core must be be setup to use a metrics service for this function to be used. The metrics object MUST be formatted as follows (see https://github.com/jembi/openhim-core-js/issues/104):

"metrics": {
	"<metric_name>": "62", // for metrics that apply to the entire transaction
	"<orchestration_name>.<metric_name>": "16", // for metrics that apply to a particular orchestration step, the orchestration_name should reference an orchestration in the orchestrations object
	...
}

Reporting metrics via the metrics service - May be supported in the future

Metrics can also be reported directly to a metrics service if the OpenHIM-core server that the mediator is being deployed on supports this. The metrics service will be a statsd instance so metrics must be reported using statsd UDP messages. The mediator MUST submit metrics using the following naming convention:

"openhim.<mediator_uuid>.<endpoint_name>.<metric_name>"

"openhim.<mediator_uuid>.<endpoint_name>.<orchestration_name>.<metric_name>"