MACM and mHero Design

mHERO + mACM Design Document

This is a design documetn for an implementation of [mACM http://t.co/9UErFc369V ] 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: data store

Data Store

The data store is MongoDB. 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 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 [[http://hl7.org/fhir/2015May/communication.html | Commu\ nication ( 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 neede\ d.

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 (potentnially multiple) platforms for sending an alert (VUMI, Comm-Care, e-mail, etc.).

= Inter-Lnked 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:otherI\
D/> 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

<pre><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 organizationa\

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

Search Paramters: 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 Paramters: FHIR Communication

These are the search paramters requried 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 Paramters: mACM Standard

The search paremeters 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

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

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

UPDATE DISSEMINATION

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

pCM will look up the Commununication by the ID parameter. When it finds the Communication resource it will:

• add onto the communication.dissemination list

with the timestamp and text content of the response according to the mACM standard.

• update the timestamp of the Communication resource