...

For each mediator to communicate with the OpenHIM-core it will need to be able to talk to the OpenHIM's interfaces. There are 2 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

Some thoughts:

Have a interface where a mediator can contact the OpenHIM and register itself. Registering will allow the following function:

• Allow the OpenHIM-core to display the registered mediators
• The mediators register their endpoint (host path, other details) with the core, this allows the OpenHIM to allow a user to easily configure a mediator by name
• ...

Communicate transaction metadata

Some thoughts:

Then mediators can populate a token with metadata about the transaction as they process it. this token can then be returned to the core to provide insight into what the mediators did. This metadata can include:

...

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>"

...