Program Data Technical Design Proposal

Program Data Requirements

For OpenLMIS, there is a certain need to collect programmatic data during the requisition process (and possibly other processes); this is called "program data". In order for OpenLMIS to support program data, several requirements need to be fulfilled:

  • Form design - determining what data needs to be captured and how, and designing a form to facilitate that data capture
    • This part of the system should be able to accommodate a user that is mostly non-technical (can use Excel or an interactive form designer tool to design forms)
  • Data capture - entering data into and completing a form as part of the requisition process
    • This part of the system should be able to accommodate a user that is completely non-technical (simple, straightforward form of entering relevant data; cues of what is incomplete)
    • There is additional value if this feature can be done offline
  • Reporting on data - taking the data, running reports and doing visualization on it
    • This part of the system should be able to accommodate a user that is mostly non-technical (can use reporting tool to generate reports or interact with tool

Ideal Solution and MVP

For implementing Program Data in OpenLMIS, there is a difference between an ideal solution and a minimum-viable product (MVP). An ideal solution would fulfill all of the above requirements and:

  • Have full offline support (easy to go offline, capture data and sync it back to the server once online)
  • Have an integrated look and feel with OpenLMIS, particularly during the data capture process
  • Have a fully-featured form designer, to handle different possible complex forms
  • Support a complex model for role-based access control (RBAC), similar to OpenLMIS
  • Support mobile (smart phone or tablet) based collection


However, the ideal solution will take multiple iterations to accomplish, and the first iteration should focus on an MVP. This would fulfill the requirements in the previous section and:

  • No offline support for now
  • No integrated look and feel
  • Have a form designer to support basic forms
  • Have a single "admin" user for access

MVP Proposal with DHIS2

DHIS2 has features to facilitate both form design and data capture. Forms can be designed through the Tracker web app, or form metadata can be imported through the APIs. Data can be collected using the robust Data Entry web app (and potentially others in the DHIS2 ecosystem), which has some offline support. A user, as part of their requisitioning process, could enter programmatic data into DHIS2. As part of the same requisitioning process, that user uses OpenLMIS to perform the requisition. In order for OpenLMIS not to complete the requisition unless the dependent program data has been completed, OpenLMIS needs to query DHIS2 to check for completeness.

Therefore, an MVP for Program Data with OpenLMIS and DHIS2, would require creating a new Program Data microservice. It would look as such:

  • This service would handle requests from consumers–Requisition service for MVP, but other services in the future like stock management or informed push
    • Input: a program data composite (facility, program, processingPeriod, and possibly isEmergency)
    • Output: true/false depending on whether that program data is complete
  • To answer these requests, it would make an external call to DHIS2 to get relevant data (integration piece)
    • Authenticate with a DHIS2 "admin" user dedicated to OpenLMIS integration
      • NOTE: this "admin" user does not have to be an admin of the system, but has the correct DHIS2 permissions to return data required by OpenLMIS
    • Call to DHIS2 APIs, /api/<version>/dataValueSets
    • Input: a mapped program data composite between OpenLMIS and DHIS2
      • An OpenLMIS Facility maps to a DHIS2 Org Unit
      • An OpenLMIS Program maps to a DHIS2 Program
      • An OpenLMIS Processing Period maps to a DHIS2 Period)
    • Output: dataValueSet result, with completeDate if program data is complete)

A diagram with the interactions:

Component Diagram for the Program Data Microservice:


A look at how this proposal fulfills the Program Data requirements:

  • Form design - forms can be designed through the Tracker web app, or form metadata can be imported through the APIs
  • Data capture - data can be collected using the robust Data Entry web app (and potentially others in the DHIS2 ecosystem)
    • Offline support - DHIS2 can support much of the requirements out-of-the-box:
      • DHIS2 (desktop client) has support for "intermittent connections" (based on info received from DHIS2 training)
      • Additionally, it appears that the client-server setup has support for connectivity interruptions measured in seconds/minutes, but not hours/days. For more complete offline support, there is an option to create an offline instance that syncs with an online server during connectivity
  • Reporting on data
  • Have a single "admin" user for access - Since DHIS2 does have authentication support (including OAuth2) and appears to have some RBAC, it should be easy enough to create an "admin" user for OpenLMIS to use

Post-MVP Iterations

Future iterations would satisfy more of the requirements in the ideal solution. In particular,

  • Support for Informed Push should be straightforward, as it would access the same Program Data endpoint with the same criteria (facility, program, processingPeriod). See interaction diagram above.
  • Offline data capture support
  • Support a complex model for role-based access control (RBAC), similar to OpenLMIS - DHIS2 appears to have RBAC, similar to how OpenLMIS is set up, so it should be possible to create mappings of users between systems and potentially single sign-on (SSO)
  • Integrated "look and feel" - with SSO, it may be possible to put access to DHIS2 in an iframe in the OpenLMIS UI, but effort would be required to give it the same "look and feel"

OpenLMIS: the global initiative for powerful LMIS software

Chongsun Ahn (Unlicensed)
April 20, 2017

I have added a note.