Outlining Nexleaf Integration

Basic Conceptual Alignment Arch Diagram


2017-08-29 NexLeaf Integration Meeting notes (includes Auth architecture such as service token approach)

2017-09-06 NexLeaf Integration Meeting notes

Task List

Software development regarding implementation to begin for both teams (OpenLMIS and Nexleaf) in November 2017

Originally created on 2017/10/12 check in call with: Josh ZamorBrandon Bowersox-Johnson, Rachel Powers (Deactivated), Mary Jo Kochendorfer (Deactivated)Chongsun AhnMartin LukacTerence Honles

TaskComponentDetailsResponsibleStatus as of Nov 2017
Minimum Integration
OLMIS-3135 - Getting issue details... STATUS Auth

OLMIS-3135: Service Accounts

(Service accounts – backend connections/tokens with Nexleaf)

Service Account

Create account or meta data with group structure to ensure that domain, path, tokens (access service account) for accessing openLMIS are known to the components in the NL system which will consume the data.

Future: single sign-on
Not in scope for Minimum Integration / first phase

Master Data Alignment
OLMIS-3385 - Getting issue details... STATUS

OLMIS-3385: OpenHIE's mCSD Facility Registry 

Epic Name:OpenHIE's mCSD Facility Registry

Description: Support Care Services Update Consumer/Provider for Facility Registries

So OpenLMIS can be a "consumer and provider"

Needed for FHIR

Geographic hierarchies
This may be addressed in the facility registry via the location resource in FHIR.

OLMIS-3386 - Getting issue details... STATUS

OLMIS-3386: For interoperability with Nexleaf, provice FHIR Device resources for OpenLMIS CCE Inventory

For interoperability with Nexleaf, provice FHIR Device resources for OpenLMIS CCE Inventory

NexLeaf product being a consumer of the facility registry
Nexleaf needs to know how to read FHIR resources to discover facilities and CCE. Nexleaf needs to build a sync tool to do initial discover and updating (scheduled? push button?) of master data from openLMIS.Nexleaf

Tech design for CCE Inventory sync

Need to hold joint planning/tech design to identify the approach or the mappings of certain fields. There are 3 possible options on the table. #1 and #3 are the best.

OpenLMIS, Nexleaf
CCEquipment catalog synchronization

OpenLMIS share their Equipment List with Nexleaf. Both sides ensure there is consistent mapping between fields indicating the make and model.

Needs to know make/model of devices at each facility. Need to make sure CCE catalog in both OpenLMIS and Nexleaf are synced

OpenLMIS, Nexleaf

OLMIS-3136 - Getting issue details... STATUS
OLMIS-3136: Allow CCE Inventory Alerts to be pushed into OpenLMIS OpenLMIS

Advocacy & Long-Term
PQS Catalog Standardization

Larger advocacy to get standardized, consistent, non-disappearing PQS list that is available as CSV/Excel (and not just PDF).

Standard REST API (HL7 FHIR?) for the PQS database

OpenLMIS, Nexleaf
ATOM feed to query for changes from a facility registry
Maybe this includes advocacy with FHIR and OpenHIE communities? Promote this as a future standard?OpenLMIS, Nexleaf

what else?

we could look at fields in SELV API; talk about what we know about our users; what specifically means "needs attention" for us; what is the combination of Nexleaf metrics that tips something into the Non-Functional status?

Notes from  : Who is the person looking at the information in OpenLMIS? We will want to make sure the person taking care of the equipment has time to address. Decided we focus on 

What is the type of information exchanged?

The configuration of the flag would live within Nexleaf and a generic set of data will be passed. Based on configuration in Nexleaf.

  • % of time out of range (uptime)
  • For X duration
  • Potentially number of alarms
  • May be different flags for different levels (MJ: I wasn't clear if this was said so feel free to delete)

What would be the format of the information?

  • Martin will come up with a JSON proposal for that.

Does OpenLMIS store the data? Can previous days get updated?

  • For now, no.
  • Josh: Let's hold off on addressing this and we'll get back to it.
  • For the future conversation, MJ Thoughts: perhaps storage goes into our data warehousing strategy but would different from triggering the flag. 

How frequently should there be updates?

  • For the future conversation.

Discussed on  
  • Can OpenLMIS users not edit the functionality status if a device has RTM?
    • Yes, they will update the functionality status based on the information from RTM.
    • How or do we snooze the needs attention flag? Rachel Powers (Deactivated)
    • Need to understand that if the duration is longer (long window of time), once the fridge performance improves the alarm may continue since it will take longer
      • To mitigate this:
        • can have flag be set 'event based' so it is only set the first time the condition is met. This depends on how OpenLMIS will store and communicate state.
        • the window can be shortened
        • having a snooze/clear within OpenLMIS as questioned above
        • send snooze/clear back to Nexleaf (no prefered)

          Additional questions post-call:
        • should NexLeaf send an "all good" to automatically turn OFF the Needs Attention flag once the criteria have been met? (no preferred)

To be discussed on  
  • Additional questions: does FHIR Device support functional and utilization status? 
  • (added 10/25): Should OpenLMIS communicate information back to Nexleaf?
    (added 10/25): Snoozing functionality & needs
  • does OpenLMIS keep an 'audit log' of the history of functionality status changes over time? (whether it was set manually or set by the RTM service account?) 
  • discuss how future roadmaps for OpenLMIS and Nexleaf dovetail but do not overlap here; EG, Nexleaf is working on an 'issue tracker' type capability; OpenLMIS roadmap has a 'needs attention' flag on CCE equipment 

Architecture note: Languages should also be supported. ISO standard

OpenLMIS 3.0 upgrade in existin countries
Is there an OpenLMIS-using country planning to scale up to 3.0 and start using these features?
- Conversation is definitely happening in Mozambique, but no clear plans yet. Can keep team updated on updates with other countries as well

What this achieves: Shared facility list, shared CCE inventory device list, OpenLMIS consumes alerts from ColdTrace, standardization of catalog devices (long term).

Notification API proposal

Notifications will take the following form and be expressed as JSON objects

  • alert_id [string] - opaque identifier (UUID etc)
  • equipment_id [string] - opaque identifier (UUID etc)
  • start_ts [int] - microseconds since epoch
  • end_ts [nullable] - microseconds since epoch
  • status [string] - Human readable description of the alert
  • alert_type [string] - pre defined set of alert types [temp out of range, uptime out of range, etc...]

They can be received through a webhook (HTTP POST), or listed (HTTP GET) per equipment through an API endpoint e.g. `/coldtrace/api/v2/alerts/<equipment_id>`

(webhook would be immediate, GET request would be on OpenLMIS schedule.)

Nexleaf would send trigger for Needs Attention, also sends end of alert once functionality is improved

What quantifies the notification? Is it only once a day? 

 Proposed timeline for integration

  • MVP integration complete by March? 
  • Slow burn over the next three months.
  • Second week in February is demo to Gavi, so we will likely want to showcase part of the integration work and/or talk about it.
  • Spread out level of effort

Check-in Meetings

Check-in Meeting  

Martin: We can talk through the tasks on our end. We also wanted to review the fields/data model in openlmis that are available for the facilities/equipment/etc.

  • paralells the OpenLMIS service accounts → called configuration management 
    • storing information on service account
    • Rules used for triggering notifications
  • Syncing service (geo zones, facilities, equipment, etc.)
    • download, match, stored (manually triggered) 
    • Assumption: NexLeaf will assume it doesn't have any of the information
  • Notifications themselves
    • Rules
    • Next step, define the status codes together. Will do something basic for the demo

Josh: Lets look at these two FHIR tickets relating to meta-data alignment around facilities: https://openlmis.atlassian.net/browse/OLMIS-3387 and the subsequent https://openlmis.atlassian.net/browse/OLMIS-3389 . These haven’t started yet, and only the first has made it into an active sprint, however you will see where some of our fields will map to in FHIR Location and we can discuss what won’t be delivered in these tickets (Searching, feeds, etc).

  • Next: How do we want to find changes (difs)
  • After we implement the first two, we should look into OLMIS-3915 and how we want to support it

Follow up

  • Martin inquired about learning more about Data Warehousing. MJ shared Reporting and Data Warehouse Strategy and asked if Martin could let her know what areas he is interested in digging more into. MJ can schedule a meeting with Peter at Ona.
  • Check in on scheduling for the week of Jan 22.

Check-in Meeting  

In person check in


  • Updates
    • VR has started on the FHIR representation tickets.
    • Nexleaf added more detail the API notification and status
    • Date for the GAVI demo is the week of March 19
  • Discuss the API proposal (are we ready for this conversation?) When does it need to be resolved by to meet the end of March deadline? https://docs.google.com/document/d/1cwdTIOtPbuf1O2_s5BPgEKEAps9HyU4A9TEbM6Owmk0/edit#
    • Decided to include a language dictionary of those requested using the ISO
    • Josh asked about performance implications but Terrance doesn't think there will any.
    • Josh: How do we interpret start and end time stamps? CT will send the status ID and when the alert started and will resend when the same alert ID ends.
    • Josh: For the first cut, we will wait for the POST. 
    • Terrance: We will want to decide a retry policy to make sure we had a OpenLMIS server awknowledgement. Terrance and Martin will determine what is reasonable for the retry policy.
    • Discussion on the cce or devide ID. Terrance and Martin will determine what is best.
  • Review what key decisions need to be made by when to release by the end of March.
    • How will testing be handled?
    • What will the demo data look like?
    • Discuss the actual demo and what we want to show stakeholders.
    • Nexleaf
      • Define the web hooks with an appropriate retry policy
      • Implementing the API
    • VR
      • Define the OpenLMIS spec for the needs attention flag
      • Master data alignment implementation
  • Learn more about the scope of issue tracking and managing the maintanence of equipment 
  • Talk about future opportunities 

Check in Meeting  

Next week discuss

  • Status
  • Testing?

Check in Meeting  

  • Update on ColdTrace API development, retry logic, etc
  • Update on needs attention design for OpenLMIS
  • Next, OpenLMIS needs to consume API
  • Demo data
    • Data is from october/september 2017
    • OpenLMIS has zones, devices
    • Will wait till VR gives the go ahead on which places

Testing - next time

Check in Meeting  

  • Update on ColdTrace API development and OpenLMIS development:
    • Two OpenLMIS bugs are fixed
  • Question from VR: Date/time question, any resolution?
    • Nexleaf is still discussing the standard
  • Question from VR: When will Nexleaf be ready to start sending alerts?
    • Nexleaf will specify the post API
  • OpenLMIS update

Contracting testing - Next week

Demo data - Next week

  • Data is from october/september 2017
  • OpenLMIS has zones, devices
  • Will wait till VR gives the go ahead on which places

Current thinking for the demo (DRAFT)

  • Facility: Dep—sito Distrital Cuamba (still need to define the HF but I think it is Matias, Cuamba)

  • Devices: 

Draft User journey
Narrative and Key things to note
Issues/concerns/missing/questions (MJ Notes)
1As the DIVO, view the CCE equipment inventory at the district store and note the "needs attention flag" due to the integration with ColdTrace

Describe out the integration is based in the FHIR standards of location and device. Any system can utilize/leverage.

Note the alert thresholds we set up in ColdTrace to trigger the needs attention flag.

(question) do we want to show the integration in further detail by logging into ColdTrace.

2As the DIVO, I can add/modify CCE inventory at my store.Don't go through the whole process.Don't go through the whole process.
3As the DIVO, I can update the needs attention flag to non-functional

Check in Meeting  

Reminder that Demo is in Martin Lukac will let us know if he is in town and can join in Geneva.

  • Update on ColdTrace API development and OpenLMIS development. 
    • Still chatting with Ashraf and the date/time.
    • Chongsun: PUT API is in review and in the test server
  • Question from Terence Honles: Are there cases where there are sibilings (regarding areas and sites)? 
    • The depth of the model goes to Facility level
    • VillageReach will let Nexleaf know when we update our facility model (start supporting locations within locations)
  • Contract testing - let's discuss and address once we get message from ColdTrace

Demo data - let’s target devices at:

  • Health Facility: Lurio, Cuamba and
  • District Facility: Dep—sito Distrital Cuamba

Check in Meeting  

  • Update from Nexleaf
    • By next check in the API should be done
    • Terence will QA  OLMIS-4105 - Getting issue details... STATUS
  • Update from VR
    • In QA  OLMIS-4105 - Getting issue details... STATUS
    • In progress  OLMIS-4127 - Getting issue details... STATUS
    • Will put it in  OLMIS-4196 - Getting issue details... STATUS

Next meeting:

  • Contract testing - let's discuss and address once we get message from ColdTrace
  • Mary Jo Kochendorfer (Deactivated) would like to discuss access to ColdTrace demo in case there are questions from Gavi stakeholders

Check in Meeting  

  • Update from Nexleaf
    • Terence tested  OLMIS-4105 - Getting issue details... STATUS  and have a couple things to work through.
    • Next week you'll be working on the demo data
  • Update from VR
    • Updated the resource and demo data based on back and forth on  OLMIS-4105 - Getting issue details... STATUS .
    • Service Accounts uncovered a bug (when we restart the application) OLMIS-4257 and demo data OLMIS-4249
    • Serial number OLMIS-4196, Josh is working on it this sprint

Demo data questions

  • Should we sync up the demo data so they are aligned?
  • On the coldtrace side, how can we 'send an alert'?
  • Version 3 Demo: Supporting Documentation : Martin Lukac to update
    • One piece of equipment will have an active alert
    • One piece of equipment will have an old alert
    • user: divo1, password: password
  • Martin Lukac would you help me with a slide on ColdTrace and brief summary of the blog we did? Thanks!

Check in Meeting  

Update from NexLeaf

  • tested the serializtion numbers, works good

Update from VR

  • View the historical alerts
  • Planning to wrap up  OLMIS-4257 - Getting issue details... STATUS  and  OLMIS-4249 - Getting issue details... STATUS  shortly

Check in Meeting  

Mary Jo to give an update on what happened. Indicated that we'd like to do the demo again in the upcoming 3.3 webinar.

Automatic dismissing of alerts

Outstanding item which could be changed updated in the future. It might be problematic if OpenLMIS dismisses the alert (makes it inactive) when there is an end date in the message. Unclear what the best behavior is given that OpenLMIS isn't currently in used. 


  • Need to alert to Terence when we restart and before the webinar

Josh, Mary Jo, Martin talked about PQS standards.

Out of Scope:

  • Synchronizing user accounts & permissions across platforms
  • Achieving a shared, standardized PQS catalog (this is a long term goal that is not covered by this)

Open Questions:


What does a "change in functionality status" mean to us/our users? Does that include only changes to functionality statuses (working, not working) or does it also include alerts about no data available? It's easier to do red, yellow, green, rather than functional/non-functional

Decided that we use a "needs attention flag"Resolved.

What kind of information does Nexleaf need back from OpenLMIS around the needs attention flag.Decided that OpenLMIS will not send information back.Resolved

How will the Needs Attention Flag work on the OpenLMIS side?

OLMIS-4106 - Getting issue details... STATUS

See above


OLMIS-4106 - Getting issue details... STATUS