The OpenLMIS Community is pleased to announce the 3.0 release of OpenLMIS!
After 8 months of hard ass work!!!!!!!!!!!!!!!!!!!!!!! re-architecture effort for OpenLMIS for OPENLMIS IS DONE!!! Requisitions, based on an all-new micro-service architecture. This stable release is the first to utilize the new architecture and is a bold step in the direction of “shared investment, shared benefit” that is the rallying cry of the OpenLMIS Community. 3.0 is the first of more planned dot releases to fill out the long-term vision of providing a full feature logistic management information system which ministries of health and organizations can utilize to manage their supply chain. Please reference the Living Product Roadmap for the high-level estimated release schedule through version 3.3.
Background
Early contributions to OpenLMIS by PATH, USAID, Rockefeller Foundation, the Bill & Melinda Gates Foundation, the UN Commission on Life-Saving Commodities, JSI, ThoughtWorks and others first helped shape the product and define its original code base (v.0.9) for deployments in Tanzania and Zambia in late 2013 under the name “eLMIS.” In 2015, eLMIS was also deployed in Cote D’Ivoire, and OpenLMIS software development continued with the v1.0 release, which was deployed by VillageReach to manage vaccine distribution in Mozambique and Benin.
As new installations of OpenLMIS were developed and deployed, a key challenge was the inability to easily extend the code base, which resulted in a “code fork” between the early implementations and the later v1.0 implementations. In an effort to address the fork the community agreed to begin working toward a common master branch, and at the September 2015 all-community meeting, the community also agreed that a single, “core” code line was required. This effort to re-work the OpenLMIS code is referred to as the "Re-Architecture" of OpenLMIS.
VillageReach and partners have worked to make the re-architecture process as transparent as possible through clear documentation available on the OpenLMIS Wiki. The OpenLMIS Re-Architecture Acceleration Brief outlines the plan and approach for this effort, the high level architecture is captured at Architecture Overview (v3), and the Re-Architecture Concept Note provides a detailed, clear explanation of the re-architecture plan and approaches.
OpenLMIS is open source, and all source code for this 3.0 release is available on GitHub for collaboration: <INSERT LINK>. That repository contains the reference distribution, and each service lives in its own GitHub repository as well.
Key Objectives
- Improve end-to-end visibility within the supply chain
- Extensibile architecture to support shared benefit and value
- Architectural goals and technical improvements
Sustain the majority of 2.0 OpenLMIS feature set
Key Features
- Offline data entry
- Column header definitions
- Configurable system setup
Key messages or things we should be sure to include in the Release Notes
- technical documentation is coming
- no examples of extension due to prioritization (link to PC decision)
- semantic versioning (pull from Brandon's presentation)
- New product/commodity model
importance of staying up-to-date with latest version (for shared value)
- check in/status snapshot on BMGF re-architecture goals; be honest about what's done and left to do
Components
This release is Version 3.0.0 of the OpenLMIS Reference Distribution.
This release includes the components listed below. Each component is in its own public GitHub repo and versioned independently:
Reference Data Service 3.0.0
The reference data service stores master data lists used across services and associated business logic for managing those entities. For example, adding and editing facility and product lists.
Configurable geographic hierarchy for reporting
Configurable requisition approval process through the definition of requisition groups and supervisory nodes.
Product management. Ability to create, activate/deactivate, association between classification and tradeitems to support GS1 standards (see for details Medical Commodities: OpenLMIS Model for GS1)
Program management
- Facility management
Requisition Service 3.0.0
The requisition service contains the business logic and feature set to support the requisitioning of products and commodities using a pull based replenishment cycle.
Create, submit, authorize, and approve regular requisitions within a replenishment cycle or irregularly as an emergency requisition. The approval process is configurable and supported through role based access controls.
- Create requisitions for supervised facilities and not just your home facility.
Online and offline data entry within the requisition form.
Useful data entry validations and rules to improve data quality. For example, beginning balance is taken from the SOH of the previous requisition.
Dynamic display of the total requisition cost based on the requested and approved quantities depending on which state the requisition is in.
Comments (new functionality)
Ability to delete to a requisition
View list of requisitions to see what status they are within the approval process.
Approvers can reject a requisition so that the submitter can correct and address issues.
Skip a requisition period
Skip products (line items)
Convert a requisition to an order for integration, printing, etc.
- Printing
- Program specific requisition templates with configurable fields for adjusted consumption and averaged consumption (can support AMC)
Requisition Reference UI 3.0.0
- User interface for requisition services
Fulfillment Service 3.0.0
- External fulfillment Facility FTP Settings
In addition, other supporting components have their own GitHub repos, including: a template service; a service-base; an example service with example extensions and one example-extension along with an extension template; deployment scripts; contract tests; a logging service; tailored docker-ized distributions of nginx and postgres; a docker image for developer tooling called docker-dev and UI build tools called dev-ui; a scalyr monitoring tool; a library for shared Java code called service-util; and configuration files.
New Architecture and Build Environment
OpenLMIS 3.0 is built with an all-new architecture that better supports customizations and extensions. The goal is to enable different OpenLMIS implementations in different countries while still sharing one global, open source codebase.3.0 Beta may look similar to version 2, but under the hood the architecture and technology are a leap forward. Developers interested in following along in our progress are welcome to visit our Developer Documentation Guide and attend our Technical Committee calls.
Micro-services
OpenLMIS used to be one monolithic system, and it is now split into independent services that provide RESTful APIs for different functional areas. 3.0 Beta already provides services for Requisition, Reference data, Notifications, and Auth, which is powered by OAuth 2. The services find each other using Service Discovery, powered by Consul.
Each service has its own API with a RAML specification and automatically-generated online API documentation: http://openlmis.readthedocs.io/en/latest/api/
The database storage for each service is separated into its own schema with its own ERD diagram automatically generated: http://openlmis.readthedocs.io/en/latest/erd/ (drill in to see any Live ERD)
All the services are bundled together in a distribution code-named 'Blue', which includes: all back-end APIs; an AngularJS web application providing the front-end UI; and an NGINX proxy to make it simple to route to all the services via one URL.The new micro-services architecture of OpenLMIS 3 allows individual components to be used, customized or extended in a modular way. Learn more in the wiki (includes architectural diagrams): https://openlmis.atlassian.net/wiki/pages/viewpage.action?pageId=51019809
Docker Containers
Version 3 of OpenLMIS is built with containers and ready for the cloud. Each service runs in its own Docker container, and Docker Compose ties multiple services together with other third-party components like Consul and NGINX. Every OpenLMIS 3 service and the Reference UI are published to Docker Hub as a deployable image. The 'Blue' distribution uses Docker Compose to allow you to swap in or out components and run an entire OpenLMIS system. Containerization makes it easier for developers to get involved in OpenLMIS and makes deployments to production more predictable and repeatable.
Extensibility
Two approaches to extensibility are supported along with examples and documentation: First, Extension Points are built into services in areas where we expect extension and customization will be needed. Second, individual micro-services could be added in or swapped out in order to provide a new or altered area of functionality. The team has built working examples and documentation of each, and will continue to include extension points into areas of functionality as they are built. To learn more about the OpenLMIS 3.0 extension architecture and use cases, see: https://openlmis.atlassian.net/wiki/x/IYAKAw
For an example extension point and documentation, see: https://github.com/OpenLMIS/openlmis-example#extension-points-and-extension-modules
OAuth 2 Compatibility
OpenLMIS 3.0.0-Beta implements OAuth so that the product can easily integrate with other systems in a single sign-on environment.
Automated Testing
In a micro-service world, automated testing is even more important. OpenLMIS 3.0 Beta includes new patterns and tools for automated test coverage at all levels. Unit tests continue to be the foundation of our automated testing strategy, as they were in previous versions of OpenLMIS. But 3.0 Beta introduces a new focus on integration tests, component tests, and contract tests (using Cucumber).Test coverage for unit and integration tests is being tracked automatically using Sonar (see http://sonar.openlmis.org). Check the status of test coverage at: http://sonar.openlmis.org/
CI/CD Pipelines
Continuous Integration and Deployment have also seen significant investment in 3.0 Beta. Jenkins is used to automate builds and deployments trigged by code commits. The CI/CD process includes running automated tests, generating ERDs, publishing to Docker Hub, deploying to Test and UAT servers, and more. Furthermore, documentation of these build pipeline allows any OpenLMIS implementation to close this configuration and employ CI/CD best practices. See the status of all builds online: http://build.openlmis.org/
Learn more about OpenLMIS CI/CD on the wiki: https://openlmis.atlassian.net/wiki/pages/viewpage.action?pageId=87195734
Reference User Interface
The reference UI is one single-page application built with AngularJS, and it is structured to allow extension and customization. The router allows areas of functionality to be added or removed and the menu dynamically includes them.
Updated Product Model
The new product model incorporates lessons learned from previous versions of OpenLMIS in the area of stock management and local fulfillment. It also uses the GS1 logical model and implements supply chain best practices (such as support for lots, packaging, GTINs, etc). Read more and see diagrams of the new Product Model on the wiki: Medical Commodities: OpenLMIS Model for GS1
And More
We've also invested in other areas of the platform that are important for OpenLMIS to be a trusted, global platform: security, localization, and over 240 JIRA tickets in total. Follow along in JIRA: (https://openlmis.atlassian.net/projects/OLMIS/issues/OLMIS-400?filter=allopenissues) ...or get involved in the committees or on the developer email list (see http://openlmis.org/openlmis-community/).
Documentation
- For the Community (including Implementors, Partners, Country staff): The Confluence Wiki includes technical designs and requirements and is the hub for all community and project resources.
- For Developers: ReadTheDocs includes developer documentation such as README files from each component, including API docs. The wiki also includes a Developer Guide section that is a helpful starting point for developers getting started with OpenLMIS 3.
- JIRA tickets also contain a record of all specifications and test plans for the features in OpenLMIS 3.
Status: Stable and Recommended
Version 3.0.0 is a stable release. It is production-ready and recommended for new deployments of OpenLMIS.
On-Going Updates and Support
Version 3.0.0 will be updated with bug fixes, security updates, and performance improvements in patch releases that will happen on an as-needed schedule (3.0.1, 3.0.2, etc). In addition, new functionality will come out quarterly in minor releases and will be backwards-compatible (3.1, 3.2, 3.3, etc). See the Releases wiki page for details.
Comparing Versions 1, 2 and 3
The 3.0 release does not contain every single feature of 1.x and 2.x. Many of the 1.x and 2.x-based systems deployed in numerous countries include significant customizations. The 3.0 release contains a core set of features—with emphasis on Requisition and Fulfillment—that are built in a micro-services architecture so they can be extended and customized to meet country-specific needs.
Now that 3.0 has been released, the priorities for what features are added for 3.1, 3.2 and 3.3 are set by the Product Committee and Governance Committee. The goal of the OpenLMIS Community is to continue shrinking the "gap" between previous versions and 3.x so that more countries can migrate to 3.x and benefit from a shared, common platform. This will reduce the on-going operating costs for all users and will bring consistent global benefits such as GS1 compliance, track-and-trace capability, and common analytics and metrics.
How to Upgrade to 3 from a Previous Version
There is not an automated, push-button migration from 1.x/2.x into 3.x. Countries already using a previous version of OpenLMIS are encouraged to review the feature-set in version 3 and let the community know what features are a priority for their ability to migrate to 3.x. There is a "Gap Analysis" project led by PATH and including JSI and VR that is collecting and prioritizing these requirements and identifying the migration path for users of 1.x and 2.x to move to OpenLMIS version 3. For more information or to get involved, contact the OpenLMIS Community Manager, Tenly Snow, or contact Brian Taliesin at PATH.
Browser and Device Compatibility
Past versions of OpenLMIS have officially supported Firefox. For OpenLMIS 3.0, we prioritized support of Chrome because of global trends, statistics provided by the OpenLMIS community, along with its developer tools and its auto-updating nature.
Browser versions that were included in testing and bug fixes are:
- Chrome 52+ (test on Chrome 52 and Chrome latest)
- Firefox 48+ (test on Firefox 48 and Firefox latest)
Operating systems that were included in testing and bug fixes are:
- Windows 7 (still the most widely used in Mozambique, Zambia and Benin and globally)
- Windows 10
The QA team also did some testing on Linux (Ubuntu) and Mac.
Devices tested were all desktop browsers including use of a pointer (mouse, trackpad, etc). OpenLMIS 3.0 has not been tested with touch screen interfaces such as iPad, tablets or smartphones.
We have asked for OpenLMIS implementations to share their google analytics to better inform how we prioritize and invest in browser and device support going forward.
For details, see the Test Strategy. Contact the Product Committee to share your priorities for browser and device support.
Multi-Language Support
OpenLMIS 3 has translation keys and strings built into each component, including the API services and UI components. English is the only language that is 100% complete as of this 3.0 release. The community is encouraging the contribution of translations using Transifex, a tool to manage the translation process. Because of the micro-service architecture, each component has its own translation file and its own Transifex project. See the OpenLMIS Transifex projects to get started.