MACM and mHero Design

pACM: the mHERO + mACM Design Document

This is a design document for an implementation of mACM with mHERO.

It is not intended to support the "Disseminate and Report Alert Status" option.

Software Architecture

This is the suggested architecture

• node.js: web services b/c of the highly asynchronous nature
• mongodb or basex: data store

Data Store

There are two options for the data store.

The data store needs to have the following requirements:

• there should be a record for each Communication resource
• these records should be retrievable by searches

Note, in the data model for a mACM Alert as a FHIR Communication resource, there are several optional fields. If these search fields are not required for the functionality of mACM we do not need to support searching by them (e.g. communication.medium).

Data Store - MongoDB

The data store is MongoDB store data as native JSON.

MongoDB Data Store Schema

MongoDB should have the following schema:

• rapidpro: parent node for managing rapidpro interactions
  • rapidpro.contact_communication: key value pairs where the key is a RapidPro contact id. The value for the key is the message communication.id for the created FHIR resource. This associative array will be used to cross-reference contacts with for RapidPro webhook calls (see 'Flow Events').
• resources: node for putting all created FHIR resources
  • resources.communication: node for putting all FHIR Communication resources that were created. Child nodes should are the Communication resources created on the POST
• queue/$DELIVERYPLUGIN queues for the messages needed to be delivered by a particular delivery plugin. the delivery plugin we are concentrating on is 'rapidpro'

Data Store - BaseX

In this case, we would be storing as native XML.

Data Model

This is defined by the mACM standard in particular according to the required fields and the search parameters. It is based on a FHIR Communication ( DSTU 2 Ballot) resource with some extension points as defined in the mACM profile.

We will use the "mACM" code of the "communication.category" data field.

XML and JSON

FHIR requires both JSON and XML representations of the Communication resources and the Bundle of Communication resources. A translator between the various resources in XML and JSON is needed.

We may be able to use:

 https://github.com/lantanagroup/FHIR.js

although we would need to update the FHIR version from DSTU to DSTU2 Ballot

Linking to Other Systems

RapidPro

There should be a "Send Alert" workflow. This will be an alert workflow that can accept an short text content to send. It should also accept an ID parameter, the "communication._id" from when the alert was created.

This "Send Alert" workflow should be triggered for any valid contacts found in the Report alert - see the Inter-Linked Registry and Client Registry below.

If there is a response back, then RapidPro should call a webhook on pACM to "UPDATE DISSEMINATION STATUS" of the Communication resource. It needs to send back:

• The timestamp
• The commmunincation._id
• The text content of the response

Note: in the future, we may want to use other (potentially multiple) platforms for sending an alert (VUMI, Comm-Care, e-mail, etc.).

Inter-Linked Health Worker Registry

This is linked to a CSD compliant InfoManger playing the role of the OpenHIE Inter-Linked Registry (ILR).

The OpenInfoMan software should be used for the ILR and the url, username and password to access the ILR should be a configuration option.

This will only be invoked if the communication.recipient is:

• a Practitioner resource or a reference to a Practitioner resource.
• an Organization resource or a reference to an Organization resource.

In the case of a Practitioner, pACM should query the OpenInfoMan for a

<csd:provider/>

with @entityID attriubute equal to "urn:uuid:$ID" where $ID is the "communcation.id". If there is a matching results, then it should look for an

<csd:otherID/>

with @assigningAuthority attribute equal to

  $HOST/$SLUG

where:

• $HOST is the configuration option which is the base URL for the rapidpro instance. For example www.rapidpro.org
• $SLUG is the configuration option which is the slug for the RapidPro organizational workspace

In the case of an Organization, pACM should query the OpenInfoMan for a

<csd:organization/>

with @entityID attriubute equal to "urn:uuid:$ID" where $ID is the "communcation.id". This is for optional support later and should look at the organizational contact in the CSD standard/

When a valid RapidPro contact is found, then the "Send Alert" workflow in RapidPro is started

Client Registry

This won't be supported at the moment, but should allow support for it in the future.

This will only be invoked if the communication.recipient is:

• a Patient resource or a reference to a Patient resource.
• a RelatedPerson resource or a reference to a RelatedPerson resource.

Sequence Diagrams

Sequence Diagrams: Report Alert

<sequencediagram style="modern-blue">

   title mACM + HWR + RapidPro
   Alert Reporter->Alert Aggregator: report alert ITI-84 (Create Alert)
   alt invalid contact
       Alert Aggregator->Alert Reporter: FHIR error code
   else valid contact
        Alert Aggregator->Alert Reporter: HTTP 200
   end
opt Contains reference to Health Worker
       Alert Aggregator->HWR: ITI-73 to lookup RapidPro ID
       HWR->Alert Aggregator: return RapidPro ID\n(same transaction used by iHRIS)
   else Contains reference to Patient/Subject-of-Care
       Alert Aggregator->Client Registry: PDQ or PDQm transaction to lookup RapidPro ID
       Client Registry->Alert Aggregator: return RapidPro ID
   end

   alt no RapidPro contact
       Alert Aggregator->Alert Aggregator:update dissemination status with failed to deliver status code
   else valid RapidPro contact
       Alert Aggregator->RapidPro: start "mACM Alert" workflow on RapidPro contact
       RapidPro->Alert Aggregator: webhook at start of flow to confirm receipt
       Alert Aggregator->Alert Aggregator: update dissemination status with attempted to deliver status code
       RapidPro->Human: Send Text
       Human->RapidPro: return text
       RapidPro->Alert Aggregator: webhook at end of flow to send SMS response
       Alert Aggregator->Alert Aggregator: update dissemination status\n with confirmed response status code and text of response
   end

</sequencediagram>

Sequence Diagrams: Query for Alert Status

<sequencediagram style="modern-blue">

   title mACM + HWR + RapidPro

   Alert Reporter->Alert Aggregator: report alert ITI-85 (Query for Alert Status)

   alt request is invalid
       Alert Aggregator->Alert Reporter: FHIR error code
   else
       Alert Aggregator->Alert Aggregator: search data store for matching Communication resources\nput Communcation resources in Bundle
       Alert Aggregator->Alert Reporter: HTTP 200 with Bundle of Communication resources
   end

</sequencediagram>

Web Services

The web services are defined according to the mACM standard which is based on a FHIR Communication resource.

All web services shall support:

• XML: application/xml+fhir
• JSON: application/json+fhir

See:

 http://hl7.org/fhir/2015May/http.html#2.1.0.6

GET

It is defined by

 http://hl7.org/fhir/2015May/http.html#2.1.0.8

POST

This is for the mACM Report Alert (ITI-84) transaction. Creates a new Communication resource.

It is defined by

 http://hl7.org/fhir/2015May/http.html#create

If no recipient is identified for the alert, then a Communication resource for the alert will be created with an entry in the communication.dissemination list with the dissemination status code "rejected".

If there is a recipient for the alert, then a Communication resource for the alert is created and stored in the data store and the FHIR response will be return accoring to:

 http://hl7.org/fhir/2015May/http.html#create

Now pACM will attempt to deliver it through the RapidPro workflow. On successfully starting the workflow, pACM will:

• set communication.status to "in-progress".
• set the timestamp of the Communication resource

If pACM cannot communicate with RapidPro then pACM will:

• add onto the communication.dissemination list with the timestamp, add the communication.dissemination.status code "failed" for failed delivery, and set communication.status to "failed"
• update the timestamp of the Communication resource
• wait a set time (configurable) to retry sending the message (if the communication.status is note "completed")

SEARCH

This is for the mACM Query for Alert Status (ITI-85) transaction.

It is defined by

  http://hl7.org/fhir/2015May/http.html#search

The search parameters are composed of three sets, the commmon FHIR search parameters, the FHIR communication search parameters, and the search parameters defined for the mACM extension.

Search Parameters: FHIR Common

There are the search parameters required for all FHIR resources:

http://hl7.org/fhir/2015May/search.html#all

which are:

• communication._id
• communication._language
• communication._lastUpdated
• communication._profile
• communication._security
• communication._tag

Search Parameters: FHIR Communication

These are the search parameters required for a communication resource:

 http://hl7.org/fhir/2015May/communication.html#search

which are:

• communication.category
• communication.encounter
• communication.identifier
• communication.priority
• communication.characterisitic

Search Parameters: mACM Standard

The search parameters are defined in section 3.85.4.1.2 of mACM.

• communication.period
• communication.priority
• communication.characterisitic
• communication.dissemination.timestamp
• communication.dissemination.code
• communication.dissemination.location
• communication.dissemination.recipient

UPDATE DISSEMINATION STATUS

This is intended to be called by a webhook from RapidPro when ever a contact sends a text back.

When the RapidPro webhook is called, it sends the RapidPro contact ID (NEED TO VERIFY). The mongodb table node "rapidpro.contact_communication" can be used to look up the ID of the communication resource that was created when the flow started.

When pACM receives an "mt_dlvd" event type from RapidPro (see here ), pACM will:

• add onto the communication.dissemination list with the timestamp and communication.dissemination.status code "in-progress"
• update the timestamp of the Communication resource, and set communication.status to "in-progress" (if the communication.status is not already "completed")

When pACM receives an "flow" event type from RapidPro (see here ), paCM will:

• add onto the communication.dissemination list with the timestamp, text content of the response according to the mACM standard in the communication.dissemination.response, and the code "completed" should be stored in communication.dissemination.status
• update the timestamp of the Communication resource, and set the communication.status to "completed"

Note that