3.0.0-beta - 28 October 2016

Release Notes

The OpenLMIS Community is pleased to announce the beta release of OpenLMIS 3.0!

The initial offering to come out of the re-architecture effort for OpenLMIS, 3.0.0-beta contains one slice of functionality, Requisitions, based on an all-new micro-service architecture. This 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 Beta is a proof of concept for this architecture and is not a feature-complete release. It does not contain every feature that the eventual 3.0 OpenLMIS stable release will. Further features will be added to the system as we work toward the full 3.0 release scheduled for the end of February, 2017. 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.0-beta release is available on GitHub for collaboration: https://github.com/OpenLMIS/openlmis-blue. That repository contains the reference distribution, and each service lives in its own GitHub repository as well.

Key Objectives

OpenLMIS 3.0 is built with an all-new architecture that better supports customizations and extensions. The goal is to enable multiple OpenLMIS implementations in different countries while still sharing one global, open source codebase. This concept is at the heart of shared investment, shared benefit.  3.0.0-beta may look similar to version 2, but under the hood the architecture and technology are a leap forward. 

Specifically, the key goals of the 3.0 Beta are to demonstrate:

• New micro-services architecture
• Ability to support extensions
• Basic feature set within requisitioning 

Again, the 3.0.0-Beta release is not a feature-complete release, meaning it does not contain every feature that 3.0 will contain. Instead, it focuses on demonstrating one slice of functionality, requisitions, based on an all-new micro-service architecture. Further features will be added to the system as we work towards the 3.0 release. 

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/).

UI Functionality within Requisitions

The 3.0.0-beta release demonstrates the fundamentals of the system's ability to support various levels of configuration with users, products, programs, facilities, geographic levels/zones, and more. Within the new reference User Interface, you can log in as an administrator and step through the main process flow for requesting products, within a program, and moving that requisition to approval.

As a “administrator” user, I will be able to:

• Login and logout
• Initiate a regular requisition and be able to select a program, type (regular) and current processing period.
• Populate a requisition form (create requisition view) based on a template. Some basic data entry validations implemented. The form includes, header, list of products, seve columns from the requisition template.
  • Beginning Balance
  • Total Received Quantity
  • Total Losses / Adjustments 
  • Total Consumed Quantity (default user input, but can also be calculated)
  • Stock on Hand (calculated)
  • Requested Quantity 
  • Requested Quantity Explanation 
• Delete a requisition
• Save a requisition
• Submit a requisition
• Authorize a requisition
• View of list of requisitions waiting for approval
• Approve a requisition
  • The approval form includes, two columns from the template (Approved Quantity and Remarks)
• Reject a requisition

Implemented and Available via API

In addition to features available within the UI, there are also features implemented and available via API endpoints. For the entire list of current APIs, please visit: http://openlmis.readthedocs.io/en/latest/api/index.html

• Convert approved requisitions to orders
• View orders
• Generate an order file based on an order template
• Reset password functionality
• Create, read, update delete reference data
• Requisition groups
• Schedules/periods
• Supervisory nodes
• Supply lines
• Products (Medical Commodities: OpenLMIS Model for GS1)
• Users
• Geographic zones and levels

Tickets Completed in 3.0.0-beta