Cookies help us deliver our services. By using our services, you agree to our use of cookies.
Views

Difference between revisions of "MACM and mHero Design"

From IHRIS Wiki

Jump to: navigation, search
Line 24: Line 24:
 
The data store is MongoDB store data as native JSON.  
 
The data store is MongoDB store data as native JSON.  
  
===Data Store - BaseX ===
 
In this case, we would be storing as native XML.
 
  
===Data Store Schema===
+
====MongoDB Data Store Schema====
 
MongoDB should have the following schema:
 
MongoDB should have the following schema:
 
* rapidpro: parent node for managing rapidpro interactions
 
* rapidpro: parent node for managing rapidpro interactions
Line 33: Line 31:
 
* resources: node for putting all created FHIR resources
 
* 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
 
** resources.communication: node for putting all FHIR Communication resources that were created.  Child nodes should are the Communication resources created on the POST
 +
 +
===Data Store - BaseX ===
 +
In this case, we would be storing as native XML.
 +
  
 
===Data Model===
 
===Data Model===

Revision as of 12:12, 6 October 2015

pACM: the mHERO + mACM Design Document

This is a design documetn 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: 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

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

\n
    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

Sequence Diagrams: Query for Alert Status

\n
    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

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