OpenSRP and OpenLMIS Integration Path Forward

Background

The OpenSRP - OpenLMIS integration can be conducted in a number of ways. Originally, the idea was to build a mobile stock management component in OpenSRP and link it to OpenLMIS. The goal of this integration was to build the functionality to make it easier to track orderables at the clinic level in OpenSRP, integrate lot, expiration and trade item information within the nurses workflows and use this information to integrate with OpenLMIS for Stock Based orders and shipments. A proof of concept was delivered in March that provided an integration based on Ideal Stock Amounts between OpenSRP's 6 CommodityTypes. The integration created an order in OpenLMIS from Nifi after the stock on hand information was extracted from the OpenSRP server. Additionally, the integration included the ability for OpenSRP to receive a shipment from OpenLMIS and apply the quantity received to the OpenSRP stock control module.

There is budget remaining to continue the mobile integration between OpenSRP and OpenLMIS with the goal to deliver a mobile stock management feature at minimum with the stretch goal of delivering proof of delivery and orders based on Ideal Stock Amounts.

A number of developments have occurred in the OpenLMIS community that impact our strategy with this remaining budget.

• The community has developed an OpenLMIS mobile strategy the clearly states the community would like an independent mobile reference application that can be used with OpenLMIS v3.
• There is donor interest to adapt the SIGLUS mobile app to be compatible with OpenLMIS v3. (SIGLUS is a robust Android app that integrates with a custom OpenLMIS v2 server)
• The User Interface for OpenLMIS v3 is built on Angular v1.x. The final release for Angular v1.x will be in July 2018 and it will then begin the final 3 year long term support phase. The entire user interface will need to be upgraded to another version of Angular, or another framework before July 2021. The community has begun discussions on this transition.

Key Risks

• Risk: It might be too hard of a problem or too much work for the current budget to try addressing the "orderables" concept with the OpenLMIS v3 Commodity Model (commodity types, trade items, and lots) while also addressing the "legder" concept (CQRS event model).
  • Ways to mitigate this risk:
    • Slow down and assess this more deeply before we make a choice between tech options.
    • Do more in-person with Josh or other experts on v3 model so deliverabes can understand the "orderables" model and the "ledger" model.
    • Reduce the scope to tackle the "ledger" concept first, and not try to tackle the "orderables" concept. We could break this work up into smaller parts rather than try to achieve the "whole enchilada" at once.
• If we haven't done a big enough risk assessment, then we may not be able to deliver the feature set.
• What is the UI and back-end server doing?
  • What is the difference between stock events and stockcard line items as well as the stockcards?
• Discussion:
  • The OpenSRP system already has a read-only ledger type concept.
    • Conclusion: The ledger aspect is not as big a risk, now that we have talked about it. The risk is really around the "orderables" model.
  • How do we stay "DRY" and build the business rules about conflicts and sync into offline devices.
  • Josh: Our scope could be reduced if we get rid of centralized lot management.
    • Decentralized lot management would make this project easier.
    • Josh: "Move away from synchronization". Separate the data from the business logic. Ensure the business logic is similar/aligned in both systems.
• When offline, we need to be able to follow the same business logic

Decision

With which of the following options should we proceed?

• OpenSRP Orderables - Android Native: Build out orderables in OpenSRP and integrate with Nifi
• OpenSRP Stock Management - ReactNative: Convert OpenSRP's stock control module to ReactNative and build out orderables
• Embed SIGLUS Stock Management in OpenSRP: Extract the SIGLUS Stock Management and Inventory features and make them available as a component within OpenSRP.
• SIGLUS Stock Management to OpenLMIS v3: Adapt SIGLUS Stock Management and Inventory features to be compatible with OpenLMIS v3 and integrate it with OpenSRP
  If we adopt SIGLUS, we have two approaches:
  • Native v3 support in Android Client: Develop native support for OpenLMIS v3 in the Android Client so that it directly interacts with the OpenLMIS v3 server
  • v3 Support through middle layer or microservice: Do not change the Android Client. Instead, develop a middle layer or microservice that handles the transactions between the OpenLMIS v3 architecture and the SIGLUS Android Client.

Detailed Options

OpenSRP Orderables - Android Native

This was the original scope of the project. This option focuses on expanding the existing stock management module in OpenSRP to include the orderable concept where individual orderables, lots and expiration dates are tracked in the application. These features will be built in Android Native.

Pros:

• We are building on top of an existing stock management module that's integrated with OpenSRP.
• Deep integration with OpenSRP which benefits the OpenSRP community

Cons:

• This approach does not conform to the OpenLMIS v3 strategy of building an independent application
  • This functionality would only exist inside the OpenSRP app, and running it depends on having an OpenSRP server running.
• This approach would not result in a product that is as mature as adapting SIGLUS
• Components are not able to be reused outside of Android

Risks:

• None

Compounding Factor: If developed in OpenSRP the Ona team feels that they can deliver the stretch goals of a proof of delivery integration that applies the orders to the database. Creating Orders from OpenSRP to OpenLMIS remains a stretch goal.

OpenSRP Stock Management - ReactNative

This option focuses on building stock management components using the React JavaScript Framework. React is a JavaScript framework that allows programmers to build user interface components and features that can be used in websites and mobile apps on Android and iOS devices. The current OpenSRP Stock Control module is built in Android Native, so we would have to convert that code to ReactNative. Once converted, the components could theoretically be used in the OpenLMIS v3 web user interface and can become part of the transition away from Angular v1.x.

Pros:

• Ona has React JavaScript developers on staff
• Possibility of a single mobile and web codebase:
  • In theory, these components could be stored in a singular code base for both the Android app and web UI. Updating one stock management component in React would update both the mobile and web UI.

Cons:

• The OpenLMIS community has not decided on a JavaScript framework to replace Angular v1.x If they choose something other than React, these components will not be as useful.
• We would have to rewrite parts of OpenSRP Android Client in a different framework.
• This approach does not conform to the OpenLMIS v3 strategy of building an independent application.

Risks:

• The React and Angular communities say it's possible, but we have not tested embedding React components in Angular v1.x.
• Embedding React components within Angular will require a learning curve for OpenLMIS v3 developers and will require a transition period.

Embed SIGLUS Stock Management in OpenSRP

This option focuses on extracting the stock management and inventory components of the SIGLUS Android Client and adding them to OpenSRP. The SIGLUS Android client is very mature compared to the other mobile apps in this space (Logistimo, mSupply and OpenSRP). We would explicitly extract these components from SIGLUS because they can be run independently and hook into the OpenSRP data model so the OpenSRP server and Nifi still manage the transactions from the OpenSRP Android client and OpenLMIS. This module would not directly interact with the OpenLMIS server. This module could be built as a standalone stock management app that interacts with the OpenSRP server, Nifi and OpenLMIS. Note that it would also require an OpenMRS server to maintain the locations, geographic hierachy and user accounts.

Pros:

• This approach utilizes an existing OpenLMIS mobile platform that has been field tested
• OpenSRP will get a more mature stock management product than could be built otherwise
• The teams would get an understanding of SIGLUS and could be better positioned to perform this work in the future.
• The OpenSRP team would do a design review of SIGLUS and likely improve the user experience

Cons:

• If used as a reference application for OpenLMIS, implementers would have a dependency on OpenSRP server and OpenMRS.
• This approach only partially conforms to the OpenLMIS v3 strategy of building an independent application
  • There is still a dependency for the data to all flow through OpenSRP server (the product list, all metadata, the stock events, etc).
• OpenLMIS will have to maintain both a web (JavaScript) and mobile (Android Native) codebase

Risks:

• The SIGLUS source code utilizes the GNU AGPL which is a copyleft license. OpenSRP Implementers who choose to implement the adapted SIGLUS stock management module would have to accept a dual license.
• Minimal schedule risk: Our Android team hasn't yet identified the level of effort for this extraction.

SIGLUS Stock Management to OpenLMIS v3

This option focuses on upgrading the SIGLUS stock management and inventory modules to be compatible with OpenLMIS v3. SIGLUS mobile has many more features including requisitions, kits and disease specific reporting that will not be transitioned. In this scenario, we would develop a mechanism to integrate OpenSRP with the SIGLUS android client where both apps are running on the same device and the user would click a link in OpenSRP to open the SIGLUS stock management app. In this action, we would develop a mechanism to transfer consumption data between the OpenSRP and SIGLUS Android Client (i.e. number of children immunized today).

If we choose this route, SIGLUS would be the preferred stock management application for OpenSRP, but would require a hard dependency on an OpenLMIS server. Below are pros and cons for this strategy. once decided, we must also weigh a sub-strategy on how we proceed with the SIGLUS stock management upgrade.

Pros:

• This approach only conforms to the OpenLMIS v3 strategy of building an independent application.
• This approach utilizes an existing OpenLMIS mobile platform that has been field tested.

Cons:

• OpenLMIS will have to maintain both a web (JavaScript) and mobile (Android Native) code base
• SIGLUS may have too many features for the existing OpenSRP user base which consists of Nurses Frontline workers
• OpenSRP will not have an embedded stock control module and will have a hard dependency on OpenLMIS in field implementations that include SIGLUS

Risks:

• The SIGLUS source code utilizes the GNU AGPL which is a copyleft license. OpenLMIS would need to decide if this license is acceptable for their mobile app offering.
• Medium Schedule Risk:
  • The Ona Android team has not evaluated this approach. There's a medium schedule risk when completing the change within the budget and time frame.
  • The interactions between the OpenSRP and SIGLUS Android clients have not been scoped. We will need to identify how metadata and user accounts are exchanged between the two applications.

Sub-Strategy Decisions

If we choose to adapt SIGLUS, we need to determine one of the following strategies for the upgrade. There are significant API and data model changes in OpenLMIS v3 that need to be adapted.

Native v3 support in Android Client

This strategy includes building Native v3 support in in the SIGLUS Android Client. Currently, the SIGLUS Android client depends on a customized version of OpenLMIS v2. All interactions from the Android client directly hit the v2 API. This option focuses on building support for OpenLMIS v3 directly in the Android client, including changing the data model to include orderables instead of just products, changing the authentication mechansims, etc. We will not retain backwards compatibility with OpenLMIS v2 in this change.

Pros:

• This approach will build a foundation of services directly in the Native Android Application that can be leveraged if SIGLUS becomes the reference application.

Cons:

• This approach will likely take longer than building a middle layer than handles mobile transactions
• OpenLMIS v3 has a very data intensive, or chatty, API that could be streamlined if mobile were to be handled by a middle layer or microservice.

Risks:

• Schedule Risk: This option hasn't been scoped and presents a greater schedule risk than the other sub-strategy

v3 Support through API Gateway (middle layer)

This strategy focuses on keeping the SIGLUS Android client as it is and building a middle layer between the SIGLUS Android client and the OpenLMIS v3 microservice APIs. In this case, we would only minimally develop SIGLUS to integrate it with OpenSRP. The middle layer would handle all transactions from the SIGLUS Android client and perform business logic to translate the mobile requests to the appropriate API calls for the OpenLMIS v3 architecture.

Pros:

• This approach will allow for distinct mobile management in the OpenLMIS v3 microservice architecture, potentially streamlining the Android interactions
• This approach will likely take less time than the other sub-strategy

Cons:

• This approach requires a long-term dependency on the OpenLMIS v2 data model in the Android client unless there is additional funding and benefit to convert the SIGLUS Android Client to be compatible with OpenLMIS v3.
• Higher maintenance cost long-term.

Risks:

• Schedule Risk:
  • The team assumes a tool like Nifi can be used to perform this interaction, which requires much less programming than doing this in Java. Nifi is already a dependency of the OpenLMIS v3 reporting architecture so we would not be adding an architectural component.

Comparison of Upgrading SIGLUS v. Developing Orderables in OpenSRP

This section focuses on a point-by-point comparison of the requirements for delivering the integration of stock management and inventory. Both options require a lot of work. The orderables data model shift from OpenLMIS v2 to v3 effectively requires that the data model of products be rewritten which impacts all business logic (presenters) and the majority of views on the Android client.

Note on OpenSRP core strategy: We will use the same interface, but make the card view dynamic to allow for a server side configuration of the orderable (commodityType and tradeItem) list. All metadata will be synced from OpenLMIS to the OpenSRP server using Nifi. We will also need to introduce a new bulk inventory process that will need to be designed.

Major areas of risk for the Upgrade SIGLUS:

• Generally, there's a schedule and cost risk of having to develop OpenLMIS microservices for this project:
  • Authentication upgrade to work with OpenLMIS v3 may require Auth microservice development
  • We will need to create a microservice from scratch to manage the mobile deployment syncing, which is a huge undertaking
• Schedule Risks:
  • Ramping up on SIGLUS to be proficient in development will take 2-3 weeks for the full time Android developers who are already proficient with OpenSRP, Nifi and the OpenLMIS APIs