This design is being created at the moment and will change and evolve often
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 2 major interactions the mediators should have with the OpenHIM-core:
- Mediators register themselves with the core
- Communicate metadata about transactions that the mediator processes
- 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>/mediator
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 name: "", // a human readable name for the mediator host: "", // the hostname or IP address where the mediator can be reached defaultChannelConfig: { // (optional) a map of default channel to add for this mediator "<channel_name1>": { ... }, // a channel object as defined by the OpenHIM-core "<channel_name1>": { ... } }, routes: { // (optional) a map of routes that represent the endpoints that the mediator can be contacted on "<route_name1>": { ... }, // a route object as defined by OpenHIM-core "<route_name2>": { ... } } }
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. This object should take the following form:
{ "type": "openhim-response-type", // a static string that contain the response type, this should always contain this string "response": { ... }, // a response object as defined by OpenHIM-core "orchestration": { ... }, // an orchestration object as defined by OpenHIM-core "properties": { // 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 metrics object MUST be formatted as follows (see https://github.com/jembi/openhim-core-js/issues/104):
"metrics": { "openhim.<channel id>.<route name>.<orchestration name>.num_tx": "62", "openhim.<channel id>.<route name>.<orchestration name>.<call name>.num_tx": "16", ... }
Reporting metrics via the metrics service
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.<channel id>.<route name>.<orchestration name>.num_tx": "62"
"openhim.<channel id>.<route name>.<orchestration name>.<call name>.num_tx": "16"