OpenSRP and OpenLMIS Integration

OpenLMIS Integration

This project is executed in two phases. The first phase (January - April) focused on creating a proof of concept to have the OpenSRP android client create orders based on ideal stock amounts, receive shipments and apply those shipments to the OpenSRP stock control module. The software development and requirements for this phase was documented in this wiki page and a video is available at this link.

Phase 2 is defined at a high level in this document and a detailed level in the Mobile Stock Management Integration Design Spec.

This phase 2 scope is currently under negotiation

Goal: Be able to track stock movements (issue/receive, adjust/wastage, stock take) and receive incoming shipment information. This would include recording VVM status on receipts and stock takes.


  • Need to sort out authentication/login
  • Syncing and aligned object models for facilities, orderables (Ideal stocking amounts, max stock policy), programs, schedules, periods and necessary reference data is figured out (clear source systems). Define what standards would be used and source information. We believe facilities will be tricky since the service delivery points may not align with locations will supply.

Use cases:

  • As a mobile user, I want to track my stock movements (issue, receive, adjust) and stock levels on a mobile device so that I can manage my internal workflows in areas with limited internet connectivity and electricity.

  • I want my stock movements and stock levels to be pushed into OpenLMIS so my supervisors can see what the stock levels (and wastage rates) are at my facility from the OpenLMIS user interface

     Click here to expand...
    • Things to consider:
      • Product list sync
      • Need to sync up the reasons for adjustments (need to be specific to program). For reporting purposes we have a set of reasons for adjustments.
      • Wastage is considered an adjustment in our system (may be the same in OpenSRP but found in a different section so calling it out)
        • Need to discuss January and March. 
        • Need to get input from OpenSRP UI design team/Roger.
        • For March, we need to sync reasons.
      • AFTER January TBD: Set a VVM status for receipts and stock takes
      • AFTER January TBD: Lot and expiration date information. Currently OpenLMIS manages centrally. Would be able to have multiple lots 'open'. (may not be needed in phase 1)
        • Need to discuss workflow further: outtake/intake, record received lot numbers in OpenSRP.
      • Move to Phase 2 after March/after v3.3: Do we want to tie receipts to locations? Closing out issues/transfers from other locations?
      • Move to Phase 2 after March/after v3.3: Would we want to support multiple programs in phase one?
  • As a mobile user, I want to be notified of incoming/upcoming shipments when they are marked as shipped in OpenLMIS. 
    • In other words: As an Immunization Nurse, I want to know be notified in advance of an upcoming shipment.
    • I want to be able to see the ordered and shipped amount of each orderable that will arrive in the shipment
    • I want to receive and reject stock and confirm the Proof Of Delivery.
    • I want to be able to confirm receipt of a shipment and adjust stock quantities received.

Stretch Goals:

  • Populate/make a requisition (or make an order)
  • Automagically notify for re-order based on stock levels/thresholds.

Out of Scope:

  • As a mobile user, I want to update Cold Chain equipment functionality status.
    • Define the inventory in OpenLMIS and update the functionality status and turning off alarms from the Android App
      • The Android client receives a list of inventory items
    • They do an inventory audit from the mobile device
      • Define the CCE and location, serial number, etc. (They use the mobile to do the inventory  
    • Alternative: RapidPro daily SMS chatbot asks if working YES or NO, if not Reply with Reason.
  • MOVE TO REPORTING: As a DIVO, I want to see my supervised facilities coverage and stock-on-hand, plus my own stock levels (the magic view) so that I can set re-supply amounts.
    • Technical Options: in DHIS2? in Superset? inside OpenLMIS web app?
    • UX Options: show coverage and stock data side-by-side in a popup inside OpenLMIS on the screen where the re-supply decision is made.

Archived Content from this page:

 Click here to expand...

Mobile Proof of Concept Demo (March Delivery)

A proof of concept demo will be developed in February as a preview of the full integration. This proof of concept demo will be lightweight with the following features:

  • Minimum Functional Workflows:
    This section defines the minimum functional workflows for the proof of concept demo. Stretch activities are clearly marked with (Stretch)
    • (Optional) OpenSRP Android Client Demo prep to show current functionality
      • The OpenSRP user will login to the stock management module to see the current number of vials available for the antigen
      • The OpenSRP user will perform a number of sample immunizations in the OpenSRP child immunization app for a single antigen (OPV)
      • The OpenSRP user will return to the Stock management module, click the card for the antigen and touch the Issued button to show a reduction in the stock
    • OpenSRP Android Client Requesting Stock
      • The OpenSRP user is already at the Stock Management Module screen
      • The user will touch a button to request stock based on Ideal Stock Amounts
        • A message will appear verifying that the user is requesting stock "Please confirm that you would like to request stock based on your Ideal Stock Amounts"
      • The device syncs with OpenSRP Server
      • Nifi queries the OpenSRP Server endpoint every 'n' seconds and identifies that a new stock request has been received
      • Nifi performs internal business logic to map the stock request to the facility, user and ideal stock amount (ISA)
      • Nifi pushes an order to the OpenLMIS Orders API endpoint in the Fulfillment Microservice. An Order number is returned to Nifi.
      • OpenLMIS user logs in to verify the order was created
    • OpenLMIS Demo to convert Order to Shipment
      • OpenLMIS user walks through the order fulfillment process
      • A shipment is created
    • OpenSRP Android Client Receiving Shipment
      • Nifi queries the OpenLMIS Shipments API in the Fulfillment Service to see if a new shipment has been generated
        • (Note: Should this be the API endpoint, or should we query the Proof of Delivery Endpoint?)
      • When a new Shipment is identified, Nifi queries the Shipment/{id} API endpoint in the Fulfillment service to get the shipment details
      • Nifi performs business logic on the Shipment details to convert it to the appropriate JSON format required by OpenSRP
      • Nifi posts the JSON to the OpenSRP Server
      • OpenSRP Server receives the shipment information
      • On a regular schedule, OpenSRP Android Client Syncs with the OpenSRP Server
        • A new shipment is received
        • A notification is generated in the Stock Management Module's Shipment section (new section)
      • OpenSRP user touches the shipments section in the stock management module and they are redirected to a page showing that a shipment is available
      • OpenSRP user touches the shipment and they view details of the shipment
      • User can accept shipment
      • (Stretch) User can adjust the amounts of each orderable and touch save
        • On Save action, the antigen amounts update on the tablet
      • OpenSRP Android client will sync with OpenSRP server
      • (Stretch) Nifi Queries OpenSRP Server on a regular schedule for Proof of Delivery
      • (Stretch) Nifi performs the appropriate business logic to accept the proof of delivery and creates the appropriate JSON to post to OpenLMIS
      • (Stretch) Nifi posts the Proof of Delivery to the OpenLMIS Proof of Delivery API endpoint in the Fulfillment Service.
  • Terminology (verbs):
    We need to identify a common terminology for the end user who is stationed at the facility level to ensure they have a common experience across OpenSRP and OpenLMIS.
    • Receipts - When an end user receives stock from any source
      • Current OpenSRP Language is "Received" in the UI
      • Current OpenLMIS Language?
        • Proof of Delivery is the order plus the shipment and it's signed off on (CRAIG: See Fulfillment Process and Statuses Wiki Page)
    • Issues or Transfers - When a Stock is dispensed from an entity to another
      • Current OpenSRP language is "Issued" in the UI representing an issue from the facility to a nurse or lower level
      • OpenLMIS uses:
        • "Shipment" to represent the issuing of stock from a higher level entity to the end facility
        • "Issue" This removes something from my stock, but doesn't actually move anywhere in the supply chain. Most often used at the lowest level of the supply chain (the facility level)
        • (What gets reported up the chain?)
        • "Transfer" to represent the issuing of stock from two entities at the same level (facility to facility)
          • A transfer may be an activity that shows poor planning where one facility has too much stock and another has too little
    • Request Stock - When an entity wishes to request stock from a higher level entity in the OpenLMIS supply chain
      • OpenSRP does not currently have language
      • OpenLMIS uses the following depending on the configuration for that facility
        • "Requisition"
        • "Order"
      • (Do end users need to know the difference?)
    • Discard - When a user wishes to throw away an orderable for a number of reasons that will be implementation specific. 
      • Current OpenSRP language is "Loss/Wastage"
      • Current OpenLMIS language is "Adjustment" - There's always a reason
        • OpenLMIS adjusts primarily on physical stock counts, not day-to-day operations
        • Reporting is key here
  • How do we differentiate between the activities at the facility that have no effect up the chain and those that do.
    • CHAI came up with an idea of "Ad hoc issues and receive" (See this on the wiki)

Mobile Phase 1 (March demo, April delivery)

Mobile Phase 2 (after March)

  • As an mobile user, I want to submit a report (OpenSRP to call OpenLMIS) into OpenLMIS to generate an order for fulfillment so that I can order new stock.
    • Things to consider:
      • Are the reorder calculations done on the OpenLMIS side and only the total consumed/issued, total received , total losses and adjustments (wastage) information is pushed to OpenLMIS to create a requisition?
      • Calculate reorder amounts based on max levels of stock and estimated needs 
      • Total losses and adjustment reasons are centrally managed in OpenLMIS and are by program (i.e. EPI program has different reasons from Essential Meds)
      • How does Ideal Stock Amounts impact this?
  • As an OpenSRP user, I want to submit an emergency requisition when my stock levels drop below the 'reorder point' so that I do not have a stockout.
  • As an OpenSRP user, I want my CCE functional status updated so my suppliers know if I have functional equipment to receive more stock. (not sure this is part of the MVP or not)
    • Things to consider:
      • Syncing CCE catalog and inventory information.

Additional thoughts:

  • Campaign management (unclear what the use cases would be)
  • CCE module (add inventory to a facility, update functional status, deactivate)
  • notification of low stock based on reorder point policy
  • future features: receive a re-supply/shipment, Proof of Delivery (adjust quantities received or rejected/returned)

OpenLMIS: the global initiative for powerful LMIS software