This page provides a high level design of the OpenLMIS and OpenSRP integration for the minimum viable product integration for stock management (Phase 1).

Overview

We will focus on a server side integration between OpenSRP server and OpenLMIS. OpenSRP Server acts as a mobile workforce management tool for the mobile deployment, independently managing the health workforce, patient information and stock card information. The core integration will focus on exchanging information on the server side and making an easy-to-configure mobile application. This allows us to leverage the full capabilities of the OpenSRP server and exchange only the pertinent information with OpenLMIS.

Assumptions

• End users will not interact directly with the OpenLMIS system. Instead, OpenSRP server will have a single connection that will mitigate all transactions.
• This integration focuses on vaccines.
• This integration focuses on a single program. Multiple program support is out of scope.
• The facility is the lowest point of reporting in OpenLMIS. Facility suballocations of orderables from the facility to Community Health Workers do not need to be tracked in OpenLMIS.
• Features are targeted to function on an Android Tablet that have screen sizes of 7 inches and greater as the primary input device. We are not currently targeting screen sizes that are smaller than 7 inches, such as smartphones.

Core Integration Points

Authentication

OpenSRP server will authenticate with OpenLMIS using OAuth credentials. Mobile app users will not directly interact with OpenLMIS.

...

Is there a specific user that we will authenticate as to get an OAuth grant?

Reference Data Alignment

OpenSRP and OpenLMIS need to align metadata in order to function. Core alignment will happen at the server side with that pushed down to the mobile client. OpenSRP has an internal mechanism for dynamically defining views without having to update the application (originally developed for the TB Reach application). We intend to use this feature to inform a number of touch points in the mobile client. OpenLMIS is the clear source of truth.

Facility Information

OpenSRP server has a representation of a facility within the health system. A facility is a physical location. OpenSRP inherits the facility list from OpenMRS, which is able to pull the facility lists from DHIS2 using the DHIS2 location sync module.

...

Is this any change? If we have an ID to ID mapping, I'd assume changing the facility name in either system wouldn't require human intervention. I'm not entirely clear on why we would need human intervention, if there's a way to avoid, or what would need to be changed in the future to avoid it.

Orderables/Immunizations

The core integration focuses on immunization workflows. The LMIS domain includes a concept of orderables, which are medical commodities. The OpenSRP stock management system doesn't include a concept of orderables. Instead, stock is managed by the immunization type and the system assumes the health care worker is able to link the immunization type against the orderable product. This integration will maintain the current health-specific workflows and add a new section that allows for the management of a specific set of orderables in the OpenSRP app.  BIT CONFUSED WHAT YOU MEAN BY NEW SECTION. PLEASE ELABORATE A BIT MORE

...

• Do we need to have a concept of a grouped consumption package for orderables? For example, the OPV consumption package includes 1 unit of productCode OPV20 and 1 unit of oralSyringe5ml. (Assumption: Yes) . I DON'T KNOW IF WE HAVE TO WORRY ABOUT THIS USE CASE FOR IMMUNIZATION. 
• Is CommodityType a better grouping mechanism here?
• We don't need all orderables that are in OpenLMIS, only a subset. What is the best mechanism to filter this subset of orderables? Should we filter this by program, or by the map?   CAN ORDERABLES BE IN MULTIPLE PROGRAMS IN OPENLMIS OR IS IT A 1-1 RELATIONSHIP? IF WE CAN CREATE PROGRAMS WITH ARBITRARY ORDERABLES THEN IT WOULD BE IDEAL POTENTIALLY USE THE PROGRAM AS THE FILTER.  THAT WAY WE CAN MANAGE THIS ON THE OPENLIMS SIDE.  I SEE THE MAPPING AS A POTENTIAL CONSTANT WE WOULD WANT TO STORE IN OPENLMIS.  IE) AN ORDERABLE TO PROGRAMMATIC MAPPING.  WE SHOULD PROBABLY CALL IT THAT VS. OPENSRP 

Program Information

OpenLMIS has a representation of a program, which is tightly linked to requisitions, funding and orderables. The current scope of work focuses on supporting one program in OpenSRP and we must ensure that we represent the core program information within the OpenSRP server.

...

• Name
• reasonType
• reasoncategory
• isFreeTextAllowed

Information Exchange

The reference data mentioned above will serve as the core information model that allows OpenSRP server to interact with OpenLMIS. The reference data defines "what" is exchanged and this section focuses on "how" information will be exchanged. The core architecture will feature a server-side service between the OpenSRP server and OpenLMIS that reduces the complexity of the microservice APIs and custom tailors it for mobile app management, ensuring high availability and fault tolerance in the event that OpenLMIS or OpenSRP are unavailable. This service will be responsible for executing server-side business logic, ensuring changes in both systems are appropriately mapped and information is exchanged. It will also be able to notify system administrators where there are errors in the information exchange process.

...

• Orderable to stockType Map - This will be manually configurable using a JSON map and will be able to be pushed from the OpenSRP server to the Android client during sync event (does not require an apk update). This will drive views and menus in the Android client. 
• OpenSRP to OpenLMIS facility Map - This map is used for information exchange purposes. All clinic activities in OpenSRP are currently mapped to the locations that are defined in OpenMRS/DHIS2. Every time information is exchanged, the location will be mapped from the OpenMRS facility code to the OpenLMIS facility code to ensure accurate reporting to OpenLMIS.

Android Client Stock Management

This section includes the functional requirements and views to be developed in the OpenSRP Stock Management Module. The current stock management views focus on presenting a simplified "stock card" system, where the high level landing page lists the stock cards available and subsequent screens focus on tracking the stock related transactions for that stockType. The core development in the Android client focuses on building dynamic views of stock card items based on the information in OpenLMIS. The first major features will focus on augmenting the current stock management features available in the OpenSRP Android client with dynamic views and updated business logic to support the concept of orderables. The second major feature will focus on creating a dispensary focused "bulk update" view that allows for issuing, adjusting and receiving multiple orderables in a single transaction.

Introducing Orderables to the Android Client

The OpenSRP Android client currently has the ability to track stock issues and wastage from the perspective of the nurse giving the immunizations. The stock cards are currently hardcoded based on the stockType, not the orderable. This interface will be reworked to allow for dynamic population of orderables, expanded fields on wastage and modified business logic linking the patient consumption to the orderable.

Stock Control Landing View - List of available Stock Cards

This view presents the list of available stock cards that can be managed in the system. The user touches a particular card to view, transact and plan for the use of that single orderable. The OpenSRP stockType (i.e. OPV) will be converted to an orderable item on the stock management home screen. The current view includes the stockType as you can see below. This view will now be populated by the orderable name that's defined in the OpenSRP Orderable to stockType map and the screen will have additional orderables such as syringes, based on what has been defined in the map. The items in this view will be configured from the OpenSRP server and updated when there is a sync.

...

PROBABLY NOT AT THIS TIME.  I THINK WE SHOULD CHECK TO SEE IF OPENLMIS CAN HANDLE TRANSFER BETWEEN FACILITIES.  IE) WE CAN INCLUDE AS OPTION THE FACILITY LIST IF YOU WANT TO TRANSFER TO ANOTHER PLACE. RIGHT NOW I THINK YOU JUST TYPE SOMETHING IN TEXT.  OPENSRP SIDE WE DON'T REALLY HAVE TO SUPPORT ANY SPECIAL LOGIC OTHER THEN A FACILTY LIST SELECTOR.  WE'LL HAVE TO MAKE SURE OPENLMIS CAN SUPPORT IT THOUGH ON THE BACKEND.

Stock Card View - Current Stock

Once a user touches the orderable item from the landing view, they are directed to the Stock Card View. This view is the primary area where stock is managed for a particular orderable. This view will not change significantly but the information on it will be populated from the Orderable metadata that is imported from OpenLMIS.

...

The navigation buttons of Received, issued and Loss/Adj will not be changed

Stock Card View - Received

When the user touches the "received" button on the screen above, they will be redirected to a page to enter new orderables that were received.

...

Discussion: Do we need to account for open vials?

Stock Card View - Issued

When the user touches the "Issued" button from the Stock Card View - Current Stock View, they will be redirected to a page to enter new orderables that were received.

...

• Do we need to dynamically populate a list of CHWs by facility from the OpenSRP server to the client? How do we currently keep track of suballocation to CHWs?
• Should we display the bold text on this screen defining the number of children vaccinated today?
• Do we need to account for open vials?

Stock Card View - Loss/Adjustment

When the user touches the "Issued" button from the Stock Card View - Current Stock View, they will be redirected to a page to enter losses and adjustments.

...

Discussion: Do we need to add any other reasons for adjustment? Should this be a dynamic field?

Stock Card View - Stock Planning

When the user touches the "Stock Planning" tab from the Stock Card View - Current Stock View, the following tab will open.

...

Discussion: Who is the target audience for this view? Does this view need to be augmented with any other information like wastage reasons?

Underlying Business Logic Changes

Currently, the business logic involved in consumption, wastage and prediction are all hardcoded based on the stockType. We will need to add the feature to dynamically define the stock card business logic that's run on the Android client. This business logic needs to be scoped for each type of orderable that is part of the vaccine program. This business logic, along with other information, needs to be defined in the server and synced to the Android Client.

...

I'm wary of dynamic business logic, would this look like a set of algerbraic functions that all must be satisfied?

Bulk Orderable Update

The current stock control view focuses on single stock card transactions one orderable at a time. We will add a new area to the Android client that allows dispensary technicians to make changes to multiple orderables. This user interface is targeted at store managers who need to issue, adjust or receive multiple orderables in a single transaction. Examples include issuing multiple orderables to a single third party, stock take adjustments, large wastage adjustments and receive a shipment.

...

Action 1: Issue Stock - Issue multiple orderables to a single third party

This action allows a store manager to issue multiple stock items to a single third party in a single transaction. The store manager will be presented with a form that allows them to define the destination and choose the quantity of each orderable to issue from the list of orderables that are currently in stock.

Data Entry Screen

• Section: Issue to - This section allows the user to select the third party who will receive the stock.
  • Field: Location - This list will be populated by the OpenSRP facility list.
  • Field: Person - This list is populated by users who are part of the facility as defined by the OpenSRP team management module
  • Business logic:
    • Only one location or person can be selected in this section.
    • Stock cannot be issued to the location that is currently active in the app
    • One of these fields must be selected to be able to save the form.
    • The selection in this section can be changed after the orderables are selected with no change to the orderable section
• Section: Orderables - This section allows the user to choose which orderables to issue and the quantity to issue
  • (The UI for this section has not yet been defined)
  • Field: Select Orderable by name and unit - This field allows the user to select an orderable of orderables that are currently in stock (value >0)
  • Field: Issue Quantity - This field allows the user to specify the quantity of units to issue
  • Field: VVM - If a VVM is available for this product, the user must select the VVM of the orderable (number 1 - 4)
  • Business logic:
    • Orderable name and unit are auto populated by the OpenLMIS metadata
    • Issue Quantity cannot exceed the available number of units on hand
    • Issue Quantity is a required field
    • VVM is only displayed if the orderable has a VVM. In which case, VVM is a required field.

Form Save Android Client Business Logic

• Once the form is saved each orderable is decremented by the issue quantity and values are updated across the entire stock management module
• The user is redirected to the Stock Control Landing View

...

• Does the user need to be able to issue stock up the OpenLMIS hierarchy?
• What is the OpenSRP server side business logic that needs to be captured before it is sent to OpenLMIS?
• Are there any other sections that should be added to this view?
• Do we need to handle the case where stock is issued to a community health worker who is able to login to the same Android device without requiring a sync to the server?
• Future Idea: Should we prepopulate the orderables section with any information based on the field selected in the "Issue to" section?

Action 2: Adjustment -  Stock take

This action allows a store manager to perform a stock take. The view includes a list of all orderables that are available to the facility. The list of available orderables are defined by OpenLMIS and maintained in the OpenSRP orderable map. The end user will not have the ability to add orderables that have not already been added in the OpenSRP server. Note that the Android client will need to sync if the system administrator has updated the list of available orderables.

...

• Section: Orderables - This section displays a tabular view of all orderables that are in available to this facility. Each orderable signifies a single row.
  • (The UI for this section has not yet been defined)
  • Column: Orderable name
  • Column: Orderable unit
  • Column: Stock on Hand - This shows the current stock on hand for the orderable
  • Column: Physical Count - This field allows the user to capture the number counted
  • Column: Calculated difference: - This is a calculated field that calculates the physical count minus the stock on hand values and displays in whole units
  • Column: VVM - If a VVM is available for this product, the user must select the VVM of the orderable (number 1 - 4)
  • Business logic:
    • Each orderable represents in a row in the table
    • Orderable name and unit are auto populated by the OpenLMIS metadata
    • All orderables are displayed on this screen
    • VVM is only displayed if the orderable has a VVM. In which case, VVM is a required field.

Form Save Android Client Business Logic

• Once the form is saved each orderable is adjusted to the physical count quantity and values are updated across the entire stock management module
• The user is redirected to the Stock Control Landing View

...

• Do we need to include open vials in this stock take?
• Do we need to account for different VVM?
• How do we define the order of the orderables that are displayed on this screen?
• What is the server side business logic?
• Future Idea: Facilities may request that we order the orderables specifically tailored to their environment so it's easier to take stock.

Action 3: Adjustment -  Bulk Wastage Event

This action allows a store manager to make bulk adjustments in the event of a large wastage like a Cold Chain Equipment failure or natural disaster. The view includes a list of all orderables that are currently in stock at the facility.

...

• Field: Wastage Reason - This single select field is populated from the program specific adjustment reason.
• Section: Orderables - This section displays a tabular view of all orderables that currently have a stock value greater than 0. Each orderable signifies a single row in the table.
  • (The UI for this section has not yet been defined)
  • Column: Orderable name
  • Column: Orderable unit
  • Column: Stock on Hand - This shows the current stock on hand for the orderable
  • Column: Amount Wasted - This field allows the user to capture the number wasted
  • Column: Calculated stock on hand: - This is a calculated field that calculates the new stock on hand value by subtracting the amount wasted from the stock on hand value (stock on hand - amount wasted). This field displays in whole units.
  • Business logic:
    • Each orderable represents in a row in the table
    • Orderable name and unit are auto populated by the OpenLMIS metadata
    • All orderables are displayed on this screen
    • Amount wasted cannot be greater than the current stock on hand.

Form Save Android Client Business Logic

• Once the form is saved each orderable is adjusted to the calculated stock on hand quantity and values are updated across the entire stock management module
• The user is redirected to the Stock Control Landing View

...

• Do we need to include open vials?
• How do we define the order of the orderables that are displayed on this screen?
• What is the server side business logic?

Action 4: Receive Stock - Receive multiple orderables from a single third party

This action allows a store manager to receive multiple stock items from a single third party in a single transaction. The store manager will be presented with a form that allows them to define the source and choose the quantity of each orderable that was received from the list of available orderables. The list of available orderables are defined by OpenLMIS and maintained in the OpenSRP orderable map. The end user will not have the ability to add orderables that have not already been added in the OpenSRP server. Note that the Android client will need to sync if the system administrator has updated the list of available orderables.

Data Entry Screen

• Section: Received from - This section allows the user to select the third party who sent the stock.
  • Field: Location - This list will be populated by the OpenLMIS facility list.
  • Field: Person - This list is populated by users who are part of the facility as defined by the OpenSRP team management module
  • Business logic:
    • Only one location or person can be selected in this section.
    • Stock cannot be received from the location that is currently active in the app
    • One of these fields must be selected to be able to save the form.
    • The selection in this section can be changed after the orderables are selected with no change to the orderable section
• Section: Orderables - This section allows the user to choose which orderables are received and the quantity received
  • (The UI for this section has not yet been defined)
  • Field: Select Orderable by name and unit - This field allows the user to select an orderable of orderables that are currently in stock (value >0)
  • Field: Quantity Received - This field allows the user to specify the quantity of units to that are received
  • Field: VVM - If a VVM is available for this product, the user must select the VVM of the orderable (number 1 - 4)
  • Business logic:
    • This section is prepopulated by the list of all available orderables to the facility as defined in the OpenSRP orderable map
    • Orderable name and unit are auto populated by the OpenLMIS metadata
    • Quantity Received is a required field
    • VVM is only displayed if the orderable has a VVM. In which case, VVM is a required field.

Form Save Android Client Business Logic

• Once the form is saved each orderable is updated by the quantity received and values are updated across the entire stock management module
• The user is redirected to the Stock Control Landing View

...

• Does the user need to be able to issue stock based on the OpenSRP hierarchy?
• What is the OpenSRP server side business logic that needs to be captured before it is sent to OpenLMIS?
• Are there any other sections that should be added to this view?
• Do we need to handle the case where stock is received from a community health worker who is able to login to the same Android device without requiring a sync to the server?
• Future Idea: Should we prepopulate the orderables section with any information based on the field selected in the "Issue to" section?

OpenSRP Server Side Configurable Views, Business Logic and Data Model

OpenSRP Server has a mechanism for defining configurable views and data models for the Android Client and syncing those from the server down to the client. This feature allows system administrators to define a view and data model in JSON. Every time the Android client syncs, the view and data model is able to update. This feature is essential for the dynamic list of orderables and associated business logic in OpenLMIS.

...

Currently, the views and data model are configurable in Enketo forms. Each orderable will require specific business logic and calculations. We will need to define a way to systematically sync business logic and calculations so we can guarantee that the calculations in the user interface and on the tablet are appropriately calculated when there are updates to an orderable from the server.

Other Features Not Yet Specified

Cold Chain Equipment

The SOW includes an activity to track the status of cold chain equipment at the facility. These workflows need to be defined jointly. The feature could be as simple as an SMS interaction from OpenLMIS directly to the health worker, a Boolean toggle on in the OpenSRP Android client, or more complex to keep track of Cold Chain Equipment serial numbers.

Could also view functionality over time in the Android, probably not needed, but I'd assume time series functionality will be important in the reporting.

Advanced Stock Notification / Proof of Delivery

The Advanced Stock Notification (ASN) and Proof of Delivery (POD) are currently being specified by OpenLMIS. These workflows will need to be jointly defined by the OpenLMIS and OpenSRP teams. In theory, OpenSRP server could receive a JSON payload from the OpenLMIS server, push that down to the Android client, and prep the proof of delivery for easy validation in the UI. The teams need to specify the workflows and features independent of the activities that have been specified in this document.

Which may include extensions so that OpenLMIS can push data to external servers

Mobile Role Based Access Controls

As of the MVP, all users will be able to access the stock management module and perform all activities. In the future, we should introduce a role based access control system in the mobile app that allows only a subset of users to access the stock management transactions.

Out of Scope

This section includes a list of items that are out of scope for phase 1.

...