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

...

• 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

...

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.

...

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

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.

...

...

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)
• 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?

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

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

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.

Image Removed

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.

Image Removed

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 logicDO 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

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

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.

Image Added

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.

Image Added

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

...