Note: Due to a bug in the upgrade from 3.0.0 to 3.0.1, we recommend starting with 3.0.1 or newer. See all releases.

Release Notes

The OpenLMIS Community is excited to announce the 3.0.0 release of OpenLMIS!

After undertaking the re-architecture effort, the OpenLMIS Community is proud to present the stable release of version 3 of OpenLMIS. The release focuses on supporting the requisitioning of stock through our requisition service 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 key vision of the OpenLMIS Community. 3.0.0 is the first of more planned dot releases to fill out the long-term vision of providing a full-feature logistics management information system (LMIS) 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 for next feature releases and beyond.

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 Côte d’Ivoire, and OpenLMIS software development continued with the version 1.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 identified was the inability to easily extend the code base, which resulted in a “code fork” between the early implementations and the later 1.0 and 2.0 versions implemented. In an effort to address the fork, the community agreed to begin working toward a common master branch at the September 2015 all-community meeting. The undertaking of this effort, to create a shared code base and provide a core set of services, 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 release is available on GitHub for collaboration. The GitHub repositories contain the reference distribution, which contains multiple components, each with source code in GitHub under the OpenLMIS Organization.

Table of Contents

Key Objectives

Improve end-to-end visibility within the supply chain with underlying architecture to support track and trace
Extensible architecture and mechanisms to allow maximum benefit to shared benefit vision
Support a configurable feature set to manage a sub-national health supply chain using a pull based replenishment approach

Key Features

New offline data entry while requisitioning stock
API driven to improve interoperability
Extensible architecture to support shared value and benefit across community members

Version 3.0.0 Features and Services

This release is Version 3.0.0 of the OpenLMIS Reference Distribution. The reference distribution bundles together all the different components and micro-services that make up OpenLMIS. Each of the following has its own public GitHub repository (source code), DockerHub repository (release image) and is versioned and released independently:

Auth Service 3.0.0

Provides OAuth 2 compatible authentication that powers the login process and can easily integrate with other systems in a single sign-on environment.

Reference Data Service 3.0.0

The reference data service stores master data lists used across services. It provides business logic and APIs for managing those entities. It includes:

- Facility management. Create, modify, activate and deactivate facilities and associated properties.
- Configurable geographic hierarchy for reporting.
- Definition of requisition groups and supervisory nodes that are used by the configurable requisition approval process.
- Product management. Create, modify, store relevant attributes (such as pack size and price per pack), assign to groups and categories for display purposes, assign to programs and facility types for tailored approved product lists, associate between product classification types and TradeItems to support track and trace within GS1 standards (see for details Medical Commodities: OpenLMIS Model for GS1).
- Program management. Create, modify, and add any number of programs.
- User management. Create, modify, update passwords and details. Provides role-based access control.

Reference UI 3.0.0

Provides a Reference UI application for using OpenLMIS in a web browser. It can be customized for implementation-specific needs. It is multi-lingual for translation, and it is component-based to build one UI application from multiple components. See sections about Extensibility and Multi-Language Support below.

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.

- Customize program specific requisition form templates. Can define display order, select options for data input and define number of periods to aver for averaged consumption (can support AMC).
- 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.
- Skip products (line items) if there isn't a need to request stock. Can be disabled by program requisition template.
- Leave comments on a requisition for other users to see and understand context (new behavior for 3.0).
- Ability to delete to a requisition.
- View list of requisitions to see what status they are within the approval process.
- Users with approval permissions can reject a requisition so that the submitter can correct and address issues.
- Skip an entire requisition period if given the permissions to do so.
- Convert a requisition to an order (handled by the Fulfillment Service; see below).
- Print a requisition at any point throughout the workflow.
- Notifications sent via email to the requisition creator upon each approval or status change.
- Provides two reports that are the most commonly-used for Requisition data and oversight.
- All this Requisition functionality is provided as a RESTful API that is used by the UI (below) and by other components of OpenLMIS.

Requisition Reference UI 3.0.0

Provides the UI screens for the requisition functionality. This is pulled into the Reference UI by the build system.

Fulfillment Service 3.0.0

The fulfillment service contains the business logic and feature set to support external fulfillment and updating an electronic proof of delivery with received amounts against the original order.

- Configurable order file template.
- Generate orders and transfer files via FTP.
- FTP settings are configurable.
- Send an order file to an FTP, see the Facility FTP Settings for details.
- View and search for orders to see the status of the orders.
- Manage the POD to record received quantities against the original orders.
- Send order files to FTP.
- Print order files (PDF/CSV).

Notification Service 3.0.0

Sends email notifications for events, such as Requisition status notifications.

In addition to each of these components, other supporting components have their own GitHub repos, including: a template service and 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 a UI build image 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 version 3 is built with an all-new architecture that better supports customizations and extensions. The goal is to enable different OpenLMIS implementations in different countries to share one global, open source codebase. Some features of 3.0.0 may look similar to version 2, but under the hood the architecture and technology are a leap forward.

Micro-services

OpenLMIS version 1 and 2 were each monolithic applications, whereas OpenLMIS version 3 is split into independent services that provide RESTful APIs for different functional areas. These services have a consistent web-based user interface powered by a UI build that creates one UI application out of multiple components. Each service has its own API with a RAML specification and automatically-generated online API documentation. The database storage for each service is separated into its own schema with its own ERD diagram automatically generated, link (drill in to see any Live ERD).

All the services are bundled together in the Reference Distribution, which includes: all back-end APIs; an AngularJS web application built from multiple components; and an NGINX proxy to make it simple to route to all the services via one URL.

The new micro-services architecture allows individual components to be used, customized or extended in a modular way. Learn more in the wiki (includes architectural diagrams).

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 Reference Distribution uses Docker Compose to allow you to swap in or out components and run an entire OpenLMIS system. Containerized versions of each service and of developer tooling makes it easier for developers to get involved in OpenLMIS and makes deployments to production more predictable and repeatable.

Extensibility

A prime focus of version 3 is enabling extensions and customizations to happen without forking the codebase.

There are multiple ways OpenLMIS can be extended, and lots of documentation and starter code is available:

The Reference UI supports extension by adding CSS, overriding HTML layouts, adding new screens, or replacing existing screens in the UI application. See the UI Extension Architecture and Guide.
The Services can be extended using extension points in the Java code. The core team is eager to add more extension points as they are requested by implementors. For documentation about this extension mechanism, see these 3 READMEs: openlmis-example-extensions README, openlmis-example-extension module README, and openlmis-example service README.
Customization can also be achieved by adding in or swapping out individual micro-services in order to provide new or altered functionality.
Some features may require both API and UI extensions/customizations. The Technical Committee worked on a Requisition Splitting Extension Scenario that illustrates how multiple extension techniques can be used in parallel.
Implementations of examples were deprioritized and will be completed in subsequent releases. See notes from the Product Committee meeting on January 17 2017.

To learn more about the OpenLMIS extension architecture and use cases, see Architecture Overview Version 3.

Automated Testing

In a micro-service world, automated testing is even more important. OpenLMIS 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. This release 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. Check the status of test coverage on Sonar.

CI/CD Pipelines

Continuous Integration and Deployment have also seen significant investment in OpenLMIS. 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 pipelines allows any OpenLMIS implementation to clone this configuration and employ CI/CD best practices. See the status of all builds online: http://build.openlmis.org/

Learn more about the CI/CD on the wiki at CI/CD documentation index.

Updated Product Model for GS1

The new product model incorporates lessons learned from previous versions of OpenLMIS in the area of stock management and local fulfillment. It has also incoporated best practices from GS1 standards and the BI&A logical reference model to implement 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 more. Follow along in JIRA ...or get involved in the committees or on the developer email list.

Documentation

The available documentation for 3.0.0 is a step forward, and the core team is committed to continue improving it:

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.

Version 3 also has a Contribution Guide for people interested in contributing code, bug reports, translations, or documentation.

Status: Stable and Recommended

Version 3.0.0 is a stable release. It is production-ready and recommended for all 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).

The core team is committed to making these patch and minor releases backwards-compatible and easy to apply during the 3.x.x development. In order to achieve the "shared value" community goals, it is important that implementations of version 3 stay up-to-date with these releases. See the Releases wiki page for details.

Comparing Versions 1, 2 and 3

This 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 version 3 has been released, the priorities for what features are added future releases 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.

Upgrading to Version 3 from a Previous Version

There is not an automated, push-button migration from version 1 and 2 into 3. 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 version 3. 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 more information or to get involved, email 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 version 3, 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 version 3 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 version 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 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.

Contributors

Many organizations and individuals around the world have contributed to OpenLMIS version 3 by serving on committees, bringing the community together, and of course writing code and documentation. Below is a list of those who contributed code or documentation into the GitHub repos. If anyone who contributed in GitHub is missing, please contact the Community Manager. This list was compiled from GitHub by pulling the Contributors from each repository that is part of version 3.0.0.

Teams AYIC/TOP: Paweł Albecki, Grzegorz Araminowicz, Mikołaj Bas, Paulina Borowa, Sebastian Brudziński, Weronika Ciecierska, Anna Czyrko, Paweł Gesek, Nikodem Graczewski, Jakub Hopen, Szymon Kaczorowski, Krzysztof Kaczmarczyk, Jakub Kondrat, Leszek Kukiełka, Mateusz Kwiatkowski, Paweł Lal, Lucyna Laska, Łukasz Lewczyński, Paweł Nawrocki, Klaudia Pałkowska, Przemysław Studziński, Piotr Szafranski, Michal Trojanowski

Team ILL: Chongsun Ahn, Brandon Bowersox-Johnson, Mary Jo Kochendorfer, Ben Leibert, Nick Reid, Josh Zamor

Additional Contributors: Yi Deng, Cui Pengfei, Anna Shaw

Special Thanks to: Kaleb Brownlow, Lindabeth Doby, Tenly Snow, Jake Watson, Laskhmi Balachandran, Guarav Bhattacharya, Brian Taliesin, Carl Leitner, Ashraf Islam, Elias Muluneh and all who attended the Product Committee, Technical Committee and Governance Committee meetings, and the many funders, supporters, implementors, partners, and those working around the world to make medical supply chains work for all people.

Tickets Completed

The following table is a list of stories and tasks completed for the version 3 release, which includes tickets from beta and 3.0. For details and additional sorting options, please view the filter in JIRA.

type	key	epic link	summary	components	status

Refresh

Browser not supported