Mobile Report Alert (ITI 84)

The Mobile Alert (ITI-84 transaction) is initiated by reporters to trigger the mACM Message mediator to send an alert. The ITI-85 transaction is a Communication Request FHIR resource with the following constraints. More details are available in the IHE profile. The below is an example (not the telecom field is currently invalid since it needs to be of type array)

{
  "resourceType": "CommunicationRequest",
  "status": "active",
  "contained": [{
    "resourceType": "Practitioner",
    "id": "practitioner",
    "name": "John Doe",
    "telecom": {
      "use": "official",
      "system": "phone",
      "value": "+27720000000"
    }
  }, {
    "resourceType": "Organization",
    "id": "requester",
    "name": "National Department of Health"
  }
  ],
  "payload": {
    "contentString": "Test Message",
    "contentAttachment": {
      "title": "Hello",
      "content-type": "text/plain",
      "language": "en"
    }
  },
  "priority": "routine",
  "category": [{
    "coding": {
      "system": "1.3.6.1.4.1.19376.1.2.5.1",
      "code": "alert",
      "display": "Alert"
    },
    "text": "Alert message"
  }
  ],
  "authoredOn": "2019-05-10T08:18:16.012312Z",
  "requester": {
      "reference": "#organization"
  },
  "recipient": [{
    "reference": "#practitioner"
  }],
  "extension" : [{
      "url" : "CommunicationRequest.channel",
      "valueString" : "sms:twilio"
  }]}

The following sequence diagram shows the sequence of messaging between the relevant components as a result of the Alert Reporter sending an ITI-84 Communication Request into the Mediator.

Reporter

• The alert reporter is responsible for triggering alerts by sending a CommunicationRequest FHIR resource to the component.
• The component allows for extra elements to be defined in the resource while still adhering to the FHIR CommunicationRequest core profile.

mACM Messaging Mediator

• The component will receive a request to process a CommunicationRequest resource and will persist the resource to Hearth.
• Hearth responds with an identifier for the newly persisted CommunicationRequest. The identifier is later used as part of Query for Alert Status [ITI-85] transaction.
• The component triggers an API call to an external messaging service like Twilio or RapidPro via the relevant channel. Channels are small adaptor components inside the mACM Messaging Mediator that are responsible for interacting with external messaging services.
• The channel immediately responds with an external identifier and delivery status for the newly sent message.
• After successfully executing the sending of a message to an external system via a channel, the component creates a new Communication FHIR resource. The newly created resource is then linked to the original CommunicationRequest resource and also persisted to Hearth.
• The Communication resource is used to capture the delivery status of a message and can be used as part of the results for the ITI-85 transaction.
• Responses are sent to the alert reporter using the Operation Outcome FHIR resource. The resource is used to handle both successful and failed transactions.
• The Operation Outcome resource is used in conjunction with normal HTTP status codes. The component supports HTTP status code 202 for success, 400 for invalid requests(failed validations), 404 for unsupported API endpoints, and 500 for any server errors.

Channel-Service

• Twilio Channel is an example of a Channel-Service. It is one of many external messaging services that can be used for the sending of messages. The mediator comes with default implementations for Twilio and Clickatell services.
• Some messaging services support message delivery updates via webhooks. The component supports these services by exposing a webhook endpoint for each channel and service.
• Each service adapter is allowed to handle the webhook call and produce data required for creating a new Communication resource. A new Communication resource linked to the original CommunicationRequest resource is then created and persisted to Hearth.

Hearth

• Hearth acts as the default FHIR store for the component and is responsible for persisting: CommunicationRequest resource sent by the reporter.
• Communication resources containing message delivery statuses after a message is sent to a service Communication resources containing message delivery statuses from webhooks, where supported. Some services support webhooks and send message delivery statuses to a predefined callback URL when an appropriate handler is defined. By default, all handlers capture the data from the webhook and respond with the required data for building a communication resource. The Communication resource is then linked to an existing CommunicationRequest resource in Hearth and then persisted.