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.

Feature Auth-1: OpenSRP Server or the Mobile Backend will need to be able to authenticate 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.

OpenLMIS has an internal representation of a facility as well. Though the supply chain hierarchy is different from the geographic hierarchy in many areas, the bottom unit of the facility is the common unit.

Feature Facility-1: Store a list of OpenLMIS locations in OpenSRP

Feature Facility-2: Map facility codes between OpenSRP at the point of service.

There should be a common understanding of a brick and mortar facility in both OpenSRP and OpenLMIS. This is the end of the OpenLMIS supply chain, a delivery destination. All users in OpenSRP are mapped to a brick and mortar facility. The OpenSRP facility can also be a point of aggregation, assuming orderables are suballocated to community health workers. We assume this suballocation does not need to be tracked by OpenLMIS. 

Decision Point: This map could be housed in one of the following places:

• DHIS2 - The OpenLMIS facility code can be added as a field in the DHIS2 org unit. If we do this, we would need to pull down these values in the dhis2 location sync module as a location attribute and link any transactions to this location.
• OpenMRS - We could add the hierarchy as a location attribute and import it into OpenMRS. All transactions with OpenLMIS would have to include this field.
• (Recommended) OpenSRP - We could create a database table in OpenSRP server or JSON config file that stores the map between the OpenMRS and OpenLMIS facility ID. This map would have to be manually created and maintained.  CRAIG CAN YOU EXPLAIN THIS A BIT MORE?

Feature Facility-3: OpenSRP will need to regularly poll the OpenLMIS and OpenMRS servers for changes to the facility list and notify an administrator

Alternatively, something that is neither OpenSRP nor OpenLMIS can be responsible for syncing data. Can we make explicit that realt-time sync is not in scope if we are using a polling strategy

Changes to the facility lists in either system will require an intervention by the system administrator to ensure mapping is appropriately flowed. Changes can happen in OpenLMIS and in OpenMRS and we need a standard mechanism to notify a human in the event that there are changes in either system. This should be raised as a database flag, email or ticket in the operational support system.

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

OPV Illustrative Example

OPV stands for Oral Polio Vaccine. It's a product that comes in a vial that can serve about 20 children. The vaccine is given orally in two doses. On the medical side (OpenSRP) we record that a child was given a dose of OPV (OPV-1 or OPV-2) at a specific schedule. On the commodity side, we keep track of the physical stock item, the vial. Ultimately, we aim to link the 20 children who were given an OPV dose to the vial. In order to achieve this, we need to merge the medical and commodity domains at the point of service.

Orderable Feature-1: Store orderables in OpenSRP server

We need to develop a data model and REST API to store orderables in OpenSRP to be able to track the orderable products on the server side. This will allow us to populate the fields in the android client, map orderables to immunizations and interact with the OpenLMIS server. Note: We only need to store a subset of orderables in the OpenSRP server, not the entire OpenLMIS orderable list.

This data model needs to be based off of the following data models in OpenLMIS:

• Orderables
  • productCode
  • name
  • dispensingUnit
  • netContent - Number of doses available
• CommodityType - Allows for grouping of orderables (See discussion point below in Orderable Feature-2)

DO WE NEED TO CREATE A REST API OR CAN'T THIS JUST BE STORED AS A STATIC JSON OBJECT.  WE WOULD ONLY NEED AN API IF WE ARE GOING TO BE DISTRIBUTING DIFFERENT ORDERABLES TO DIFFERENT WORKERS.  IT MIGHT BE EASIER TO JUST A FILE PER PROGRAM.  WE COULD THEN JUST HAVE OPENSRP LOOK FOR THE FILE FOR WHATEVER PROGRAMS ARE REFERENCED.  THIS MIGHT BE A LOT EASIER THEN TRYING TO MANAGE AN API.  WE COULD ALSO POTENTIALLY GENERATE THE FILE IN AN EXTERNAL MIDDLEWARE OR VIA SOMETHING LIKE NIFI.

ON APP SIDE WE NEED TO FIGURE OUT WHAT WE DO WHEN WE HAVE TWO DIFFERENT PROGRAMS.  IE) ONE OPENSRP APP WITH SAY CHILD HEALTH AND FAMILY PLANNING.  WE PROBABLY ONLY WANT TO HAVE ONE STOCK MODULE BUT THEN ALLOW SWITCHING BETWEEN PROGRAMS FOR THAT HEALTH WORKER WITH THE STOCK APP. 

Orderable Feature-2: Allow system administrators to configure the list of orderables that will be stored in OpenSRP and link them to the immunization schedule

OpenSRP server only needs to 'know' about a subset of orderables and link them to the immunization schedule concept in the health domain. This definition will need to be defined in the OpenSRP server by a system administrator. This list of orderables will be used to create views in the android client.

Sample ZEIR Vaccine Schedule JSON

Sample Orderable map:

OpenSRP marks all vaccines with a "name" and "type" in the vaccine schedule. The "name" represents the type and sequence for multi-sequence vaccines (OPV 1, OPV 2, etc.). The "type" does not include sequence information (OPV). The OpenSRP_Stock_Type should map to the vaccine type in the immunization schedule and the Orderable_productCode should map to the OpenLMIS orderable productCode. This productCode links back to the data model setup in Orderable Feature-1.

INSTEAD OF SAYING OPENSRP_STOCK_TYPE WOULD IT MAKE MORE SENSE TO SAY HEALTH EVENT OR SOMETHING LIKE THAT? 

\Discussion:

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

Program Feature-1: Store program metadata in OpenSRP server so it can be used in transactions with OpenLMIS

We must store the following program information in OpenSRP Server:

• program_name
• program_code

Both of the above are needed when sending information to the OpenLMIS API?

We need to store Program specific Stock Adjustment Reasons (Named Stock Card Line Item Reasons). This allows us to track the adjustment reasons that need to be collected in the client.

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

Below is a list of core information that will be exchanged:

• Information from OpenLMIS to be sent to OpenSRP
  • Orderables - This will be dynamically populated from OpenLMIS, but only a subset of Orderables will be populated.
  • Facilities - This will be populated by OpenLMIS
  • Program - This will be populated by OpenLMIS, but will include a maximum of 1 program for this phase. The program information is required for exchanging information between systems.
  • Program Adjustment Reasons - This will be populated by OpenLMIS and will drive elements in the Android client single select menu and UI. Specifically, is this a drop-down menu in OpenSRP that's generate from data pulled from the OpenLMIS API?
• Information in OpenSRP to be sent to OpenLMIS (See Discussion Point Below)
  • Report Stock levels per Orderable
  • Report wastage levels per Orderable

Discussion: What is the actual OpenLMIS API destination of the information from OpenSRP?

When we talk about exchanged, is this exchanged once then never again, will it check and update on a schedule, will it check and update with human intervention?

WE NEED TO DISCUSS HOW THESE STATIC JSON FILES WILL BE GENERATED.  THESE CAN BE DONE VIA OPENSRP OR POTENTIALLY VIA A NIFI PROCESS (PETER LET'S DISCUSS IF THIS IS VIABLE)

Below is a list of information that is required in OpenSRP server, but will not be exchanged with OpenLMIS:

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

SEE NOTES ABOVE.  WE PROBABLY NEED TO ADD A PROGRAM TOGGLE IF YOU HAVE MORE THEN ONE PROGRAM.  IE) IF WE HAVE FAMILY PLANNING, ANC AND CHILD HEALTH ON OPENSRP. I'D LIKE TO HAVE A SINGLE STOCK COMPONENT AND NOT 3.  SO WE WOULD NEED TO BE ABLE TO SWITCH BETWEEN PROGRAMS HERE.  THIS CAN JUST BE A PULL DOWN FILTER.  WE SHOULD SEE IF THERE IS EVER A SCENARIO WHERE THEY WOULD WANT TO VIEW STOCK ACROSS PROGRAMMES (PROBABLY UNLIKELY AND NOT WORTH THE ADDED COMPLEXITY)

Feature Stock Management-1: Allow for the dynamic population of the stock landing view based on server side configuration

Discussion: The OpenSRP child immunization module has a concept of service delivery zones, allowing for groups of CHWs to manage a group of patients as a component of a facility. Users are mapped as part of a team to these zones. Should we include this as part of the Stock Control module? The bigger question is whether we expect CHWs to use the stock management module on their tablets to perform suballocation activities. If so, this view and all subsequent views would have to be tailored to account for business logic.

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.

Changes to be made:

• Stock Control > OPV: The text "OPV" will be populated based on the orderable name that's imported by OpenLMIS
• OPV Stock: This will be populated based on the orderable name that's mapped in the OpenSRP stockType to Orderable map
• 13 vials: The number of vials will be populated based on the metadata from the orderable information imported by OpenLMIS, including the unit of measure
• (New) Number of Doses: We will add an item approximating the number of doses available based on the metadata that's imported from OpenLMIS
• (New) Days out of Stock: We will add an indicator to this screen that measures the days this orderable has been out of stock
• Note: stock numbers are in vials: This item in the bottom will be populated based on the unit of measure for the orderable.

Navigation:

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.

Changes to be made:

• OPV Stock Received: The blue header text "OPV" will be dynamically populated based on the name of the orderable
• Date OPV stock received: The text "OPV" will be dynamically populated based on the name of the orderable. No functionality will change on this widget
• Received from: This radio button will change to two fields:
  • Location: A location hierarchy widget will be available based on the OpenLMIS locations. We require We require the OpenLMIS locations in this widget because they may have a number of dispensaries that are not captured in the OpenMRS/DHIS2 location hierarchy.
  • CHW: A list of CHWs will be available in a single select menu so users can choose a CHW when they are returning stock that was previously issued.
• Vials OPV received: The text "Vials" will be populated based on the unit of measure imported from OpenLMIS and the text "OPV" will be replaced with the name of the orderable imported from OpenLMIS
• (new) VVM: A radio button will be displayed with the VVM number (1-4)

Navigation:

We will not change the navigation on this view.

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.

Changes to be made:

• OPV Stock Issued: The blue header text "OPV" will be dynamically populated based on the name of the orderable
• Date OPV stock issued: The text "OPV" will be dynamically populated based on the name of the orderable. No functionality will change on this widget
• Issued to: This radio button will change to two fields:
  • Location: A location hierarchy widget will be available based on the OpenLMIS locations. We require We require the OpenLMIS locations in this widget because they may have a number of dispensaries that are not captured in the OpenMRS/DHIS2 location hierarchy.
  • CHW: A list of CHWs will be available in a single select menu so users can choose a CHW to allocate stock to.
• Vials OPV issued: The text "Vials" will be populated based on the unit of measure imported from OpenLMIS and the text "OPV" will be replaced with the name of the orderable imported from OpenLMIS
• (new) VVM: A radio button will be displayed with the VVM number (1-4)
• Wasted Vials: The text "Vials" will be populated based on the unit of measure imported from OpenLMIS
• (new) Wasted Reason: If the "Wasted Vials" field is populated, a new "Wasted Reason" field will display with a radio button that's populated by the OpenLMIS program specific adjustment metadata. If the users are able to enter a free text reason, this radio button will include an "other" option that will toggle the next field
• (new) Wasted Reason Free Text Field: This field will be displayed if the orderable includes a Boolean operator stating that users can enter a free text reason for wastage

Navigation:

We will not change the navigation on this view.

Discussion:

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

Changes to be made:

• OPV Stock Loss/Adjustment: The blue header text "OPV" will be dynamically populated based on the name of the orderable
• Date OPV stock loss/adjustment: The text "OPV" will be dynamically populated based on the name of the orderable. No functionality will change on this widget
• Reason for OPV adjustment: The text "OPV" will be dynamically populated based on the name of the orderable. Additional items will be added to the radio button:
  • Wastage
  • Expiration
  • VVM/CCE Failure 
• If Wastage is selected display the following fields
  • (new) Wasted Reason: This field will display with a radio button that's populated by the OpenLMIS program specific adjustment metadata. If the users are able to enter a free text reason, this radio button will include an "other" option that will toggle the next field
  • (new) Wasted Reason Free Text Field: This field will be displayed if the orderable includes a Boolean operator stating that users can enter a free text reason for wastage
• Vials OPV adjustment: The text "Vials" will be populated based on the unit of measure imported from OpenLMIS and the text "OPV" will be replaced with the name of the orderable imported from OpenLMIS
• Business Logic Change: If Wastage, Expiration or VVM/CCE failure are selected, only negative integers will be able to be saved.

Navigation:

We will not change the navigation on this view.

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.

Changes to be made:

• Stock Control > OPV:
  • The text "OPV" will be dynamically populated based on the name of the orderable
  • Units will be displayed in parenthesis based on the metadata populated from OpenLMIS
• OPV Planning: The text "OPV" will be dynamically populated based on the name of the orderable
• 3 month OPV stock levels:
  • The text "OPV" will be dynamically populated based on the name of the orderable. 
  • The business logic for this graph will have to change: The y-axis will only display whole numbers, not decimals
• 3 month OPV stock used: 
  • The text "OPV" will be dynamically populated based on the name of the orderable
  • Units will be displayed instead of the text "vials" in the table based on the metadata populated from OpenLMIS
• Current OPV stock:
  • The text "OPV" will be dynamically populated based on the name of the orderable
  • Units will be displayed instead of the text "vials" in the table based on the metadata populated from OpenLMIS
• Number of active children: no changes to this section
• Due OPV next month Mar 2018:
  • The text "OPV" will be dynamically populated based on the name of the orderable
  • Units will be displayed instead of the text "vials" in the table based on the metadata populated from OpenLMIS
  • The business logic will have to change based on the orderable that is populated by OpenLMIS
    • For example:
      • If we are viewing oral syringes, the calculation is 1 syringe per child.
      • Open container policies need to be added in this calculation. OPV, for example, has approximately a 28 day open container policy, allowing 1 vial to be used over the entire month.
• Average OPV waste rate: The text "OPV" will be dynamically populated based on the name of the orderable

Navigation:

We will not change the navigation on this view.

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.

Discussion:

• Does OpenLMIS provide any business logic as a service that can be consumed at the "orderable level"?
• Can we scope a specific sample set of vaccines that we will target in the MVP?
• Which business logic is OpenLMIS specific and which is OpenSRP specific (orderable vs. consumption)?

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.

Discussion:

• Is there a better name for this section?
• Do we have story points for these activities?
• Is there a better way to layout this section? Currently, it's based on actions that need to be performed

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

Discussion:

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

Data Entry Screen:

• 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

Discussion:

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

Data Entry Screen:

• 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

Discussion:

• 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

Discussion:

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

These configurable views and data model will remain manually configurable in the OpenSRP server. They will not be dynamically updated based on changes in OpenLMIS. This allows the OpenSRP system administrators to carefully consider the impact of changing the view and data model, thoroughly test the change and implement it.

Below is a running list of views, business logic and data models that need to be configured from the server:

• Stock control landing view:
  • List of stock cards
  • Orderable item metadata (name, unit of measure, dose)
  • Assumption: The order of the JSON will be the order in which the item is displayed on this view
• Stock card views:
  • Each orderable item has its own metadata that populates the view (name, unit of measure, dose)
  • Each orderable item has specific business logic when performing calculations on the wastage view
  • Each orderable item has specific business logic in the Stock Card - Stock Planning view
  • Each orderable item has an associated program adjustment reason
• Location Hierarchy:
  • The OpenLMIS location hierarchy is used to define stock issues and receipts. This widget will need to be populated from OpenSRP server
• Stock issue and receipt from Community Health Workers (suballocation):
  • Stock issues to community health workers need to be dynamically populated based on the names of the users registered in the team for that facility or zone.
• Orderable metadata
  • Name is required
  • Unit of measure is required
  • Number of doses is required
  • VVM is required
• Program metadata
  • Program name is required
  • Adjustment reasons are required
  • Program specific orderables are required - so we can link the adjustment reasons to the program for a specific orderable

Feature Configurable Views-1: Upgrade the stock management module to work with configurable views

Currently, the stock management module is static. We need to update this module to be able to work with configurable views that are synced from the server.

Feature Configurable Views-2: Add the ability to sync business logic as a server configuration for each orderable.

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.

• Trade items will not be tracked in OpenSRP. We will primarily focus on orderables at the facility level.
• Real-time notifications. There is the possibility to provide real-time advance stock notification through push messages to the OpenSRP App. However, this requires a different technical backend. The current model will only provide updates when the mobile device syncs to the OpenSRP server.
• Lots
• Requisition Creation
• Multiple programs
• Schedules
• Periods