3.2.0 Release Notes - 1 September 2017

Status: Stable

3.2.0 is a stable release, and all users of OpenLMIS version 3 are encouraged to adopt it.

Release Notes

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

This release represents another major milestone in the version 3 series, which is the result of a software re-architecture that allows more functionality to be shared among the community of OpenLMIS users.

3.2.0 includes new features in stock management, new administrative screens, targeted performance improvements and a beta version of the Cold Chain Equipment (CCE) service. It also contains contributions in the form of pull requests from the Malawi implementation, a national implementation that is now live on OpenLMIS version 3.

3.2.0 represents the first milestone towards the Vaccines MVP feature set.

After 3.2.0, there are further planned milestone releases and patch releases that will add more features to support Vaccine/EPI programs and continue making OpenLMIS a full-featured electronic logistics management information system (LMIS). Please reference the Living Product Roadmap for the upcoming release priorities. Patch releases will continue to include bug fixes, performance improvements, and pull requests are welcomed.


Important: If you are upgrading to 3.2.0 and using your own database solution (i.e. Amazon RDS), and not the Postgres image in the Reference Distribution, please make sure you have the Postgres “uuid-ossp” extension installed. If you are using the Postgres image from the Reference Distribution, then this extension will be installed for you once you pull the latest image from DockerHub. For more information about this change, please see the Postgres section, and OLMIS-2681 under the Requisition Service section.

Important: 3.2.0 requires a data load script that must be run once in order to properly upgrade from an older version 3 to 3.2.0. To run this script, add refresh-db to your Spring profile. An example: export spring_profiles_active="refresh-db". You only need to run it the first time you start the server after upgrading to 3.2.0. For more information about this change, please see OLMIS-2811 under the Reference Data Service section.

Important: 3.2.0 contains a data migration script that must be applied in order to upgrade from older version 3 to 3.2.0. This migration has its own GitHub repo and Docker image. See Adjustment Reason Migration. If you are upgrading from any previous version of 3 to 3.2.0, see the README file which has specific instructions to apply this migration. For background on this migration, see Connecting Stock and Requisition Services.

Important: Requisition Service now requires use of the Stock Management service. Data collected on requisition forms uses adjustment reasons from the Stock service and submits data to stock cards. Certain columns on the Requisition Template are now required. See Requisition Template Column Dependencies and Calculations as well as more details in the Requisition component below.

All other changes are backwards-compatible. Any changes to data or schemas include automated migrations from previous versions back to version 3.0.1. All new or altered functionality is listed in the sections below for New Features and Changes to Existing Functionality.

For background information on OpenLMIS version 3’s micro-service architecture, extensions/customizations, and upgrade paths for OpenLMIS versions 1 and 2, see the 3.0.0 Release Notes.

Download or View on GitHub

OpenLMIS Reference Distribution 3.2.0

New Features

This is a new section to flag all the new features.

  • Stock Management: is not an official release and added a notification and new support for recording VVM status.

  • Administrative Screens: view supply lines, geogrphic zones, requisition groups and program settings.

  • beta version of the new Cold Chain Equipment (CCE) service: which includes the support to upload a catalog of cold chain equipment, add equpiment inventory (from the catalog) to facilities, and manually update the functional status of that equipment. Review the wiki for details on the upcoming features.

  • Performance: targeted improvements were made based on the first implementation’s use and results. Improvements were made in server response times, which impacts load time, and memory utilization. In addition, new tooling was introduced to provide the ability to track performance improvements and bottlenecks.

  • Reference data

  • Report service is now a separate component (see Report component below)

Changes to Existing Functionality

Version 3.2.0 contains changes that impact users of existing functionality. Please review these changes which may require informing end-users and/or updating your customizations/extensions:

  • Requisition Service now uses Stock Management to handle adjustment reasons and to store stock data in stock cards. This change does not alter end-user functionality in Requisitions, but it does allow users with Stock Management rights to begin viewing stock cards with data populated from requisitions. This change also requires a data migration script to upgrade older version 3 systems to 3.2.0. (See Requisition component below.)

API Changes

Some APIs have changes to their contracts and/or their request-response data structures. These changes impact developers and systems integrating with OpenLMIS:

  • Auth Service uses Authorization header instead of access_token (see Auth OLMIS-2871 below)

  • Fulfillment Service and Requisition Service changed some dates from ZonedDateTime to LocalDate (see OLMIS-2898 below)

  • ReferenceData contains changes to Facility search and Geographic Search APIs (see component below)

  • Requisition Service now requires use of the Stock Management service and connects to Stock service to handle adjustment reasons and store data on stock cards (see Requisition component)

  • Configuration settings endpoints (/api/settings) are no longer available; use environment variables to configure the application (see OLMIS-2612 below)

  • postgres database now requires one additional extension: uuid. It is already included in the postgres component (see postgres component below), but those hosting on Amazon AWS RDS will need to add the extension.

All Changes by Component

Version 3.2.0 of the Reference Distribution contains updated versions of the components listed below. The Reference Distribution bundles these component together using Docker to create a complete OpenLMIS instance. Each component has its own own public GitHub repository (source code) and DockerHub repository (release image). The Reference Distribution and components are versioned independently; for details see Versioning and Releasing.

Auth Service 3.1.0

Improvements which are backwards-compatible:

  • OLMIS-1498: The service will now fetch list of available services from consul, and update OAuth2 resources dynamically when a new service is registered or de-registered. Those tokens are no longer hard-coded.

  • OLMIS-2866: The service will no longer used self-contained user roles (USER, ADMIN), and depend solely on referencedata’s roles for user management.

  • OLMIS-2871: The service now uses an Authorization header instead of an access_token request parameter when communicating with other services.

Source: Auth CHANGELOG

CCE Service 1.0.0-beta

This component is a beta of new Cold Chain Equipment functionality to support Vaccines in medical supply chains. This API service component has an accompanying beta CCE UI component.

CCE 1.0.0-beta includes many new features:

  • Create and update a cold chain equipment catalog

  • Add equipment inventory to facilities

  • Update the functional status of equipment inventory

For details, see the functional documentation: Cold Chain Equipment Management

Warning: This is a beta component, and is not yet intended for production use. APIs and functionality are still subject to change until the official release.

Fulfillment Service 6.0.0

Contract breaking changes:

  • OLMIS-2898: Changed POD receivedDate from ZonedDateTime to LocalDate.

New functionality added in a backwards-compatible manner:

  • OLMIS-2724: Added an endpoint for retrieving all the available, distinct requesting facilities.

Bug fixes and improvements (backwards-compatible):

  • OLMIS-2871: The service now uses an Authorization header instead of an access_token request parameter when communicating with other services.

  • OLMIS-3059: The search orders endpoint now sorts the orders by created date property (most recent first).

Source: Fulfillment CHANGELOG

nginx v4

Improves stability and reliability of the application when individual services stop and start in their lifecycle. Also performance is improved by reducing latency under load between nginx and Services through configuration tuning.

  • OLMIS-2840: Allow services to stop and start without crashing consul-template.

  • OLMIS-2957: Reduce nginx latency.

Notification Service 3.1.0

Bug fixes, security and performance improvements (backwards-compatible):

  • OLMIS-2871: The service now uses an Authorization header instead of an access_token request parameter when communicating with other services.

Source: Notification CHANGELOG

Postgres 9.6-postgis

The postgres image in OpenLMIS 3.2.0 has changed slightly to include the uuid-ossp extension, in order to randomly generate UUIDs in SQL (this new requirement was introduced in OLMIS-2681). Because the change is minor and does not change the version of Postgres, we have released an updated image with the same version number (9.6-postgis). When using the 3.2.0 release, as long as you use docker-compose pull, it will pull the correct version of the postgres image.

Reference Data Service 8.0.0

Breaking changes:

  • OLMIS-2709: Facility search now returns smaller objects.

  • OLMIS-2698: Geographic Zone search endpoint now is paginated and accepts POST requests, also has new parameters: name and code.

New functionality added in a backwards-compatible manner:

  • OLMIS-2609: Created rights to manage CCE and assigned to system administrator.

  • OLMIS-2610: Added CCE Inventory View/Edit rights, added demo data for those rights.

  • OLMIS-2696: Added search requisition groups endpoint.

  • OLMIS-2780: Added endpoint for getting all facilities with minimal representation.

  • Introduced JaVers to all domain entities. Also each domain entity has endpoint to get the audit information.

  • OLMIS-3023: Added enableDatePhysicalStockCountCompleted field to program settings.

  • OLMIS-2619: Added CCE Manager role and assigned CCE Manager and Inventory Manager roles to new user ccemanager.

  • OLMIS-2811: Added API endpoint for user’s permission strings.

  • OLMIS-2885: Added ETag support for programs and facilities endpoints.

Bug fixes, security and performance improvements, also backwards-compatible:

  • OLMIS-2871: The service now uses an Authorization header instead of an access_token request parameter when communicating with other services.

  • OLMIS-2534: Fixed potential huge performance issue.

  • OLMIS-2716: Set productCode field in Orderable as unique.

Source: ReferenceData CHANGELOG

Reference UI 5.0.3

The Reference UI bundles the following UI components together using Docker images specified in its compose file.

auth-ui 5.0.3

New functionality added in backwards-compatiable manner:

  • OLMIS-3085: Added standard login and logout events.

Bug fixes and security updates:

  • OLMIS-3124: Removed openlmis-download directive and moved it to openlmis-ui-components

  • MW-348: Added loading modal while logging in.

  • OLMIS-2871: Made the component use an Authorization header instead of an access_token request parameter when calls to the backend are made.

  • OLMIS-2867: Added message when user tries to log in while offline.

See openlmis-auth-ui CHANGELOG

cce-ui 1.0.0-beta

Beta release of CCE UI. See CCE service component below for more info.

fulfillment-ui 5.0.3

Bug fixes:

  • OLMIS-2837: Fixed filtering on the manage POD page.

  • OLMIS-2724: Fixed broken requesting facility filter select on Order View.

See openlmis-fulfillment-ui CHANGELOG

referencedata-ui 5.2.1


  • OLMIS-2780: User form now uses minimal facilities endpoint.

New functionality added in a backwards-compatible manner:

  • OLMIS-3085: Made minimal facility list download and cache when user logs in.

  • OLMIS-2696: Added requisition group administration screen.

  • OLMIS-2698: Added geographic zone administration screens.

  • OLMIS-2853: Added view Supply Lines screen.

  • OLMIS-2600: Added view Program Settings screen.

Bug fixes

  • OLMIS-2905: User with only POD_MANAGE or ORDERS_MANAGE can now access ‘View Orders’ page.

  • OLMIS-2714: Fixed loading modal closing too soon after saving user.

See openlmis-referencedata-ui CHANGELOG

report-ui 5.0.3

Big fixes:

  • OLMIS-2911: Added http method and body to jasper template paramter

See openlmis-report-ui CHANGELOG

requisition-ui 5.1.1

  • OLMIS-2797: Updated product-grid error messages to use openlmis-invalid.

New functionality that are not backwards-compatible:

Date physical stock count completed is required for submit and authorize requisition. - OLMIS-3025: Introduced frontend batch-approval functionality. - OLMIS-3023: Added configurable physical stock date field to program settings. - OLMIS-2694: Change Requisition adjustment reasons to come from Requisition object. OpenLMIS Stock Management UI is now connected to Requisition UI.


  • OLMIS-2969: Requisitions show saving indicator only when requisition is editable.

Bug fixes:

  • OLMIS-2800: Skip column will not be shown in submitted status when user has no authorize right.

  • OLMIS-2801: Disabled the ‘Add Product’ button in the non-full supply screen for users without rights to edit the requisition. Right checks for create/initialize permissions were also fixed.

  • OLMIS-2906: “Outdated offline form” error is not appearing in a product grid when requisition is up to date.

  • OLMIS-3017: Fixed problem with outdated status messages after Authorize action.

See openlmis-requisition-ui CHANGELOG

stockmanagement-ui 1.0.0

First release of Stock Management UI. See Stock Management service component below for more info.

ui-components 5.1.1

New functionality added in a backwards-compatible manner:

  • OLMIS-2978: Made sticky table element animation more performant.

  • OLMIS-2573: Re-worked table form error messages to not have multiple focusable elements.

  • OLMIS-1693: Added openlmis-invalid and error message documentation.

  • OLMIS-249: Datepicker element now allows translating day and month names.

  • OLMIS-2817: Added new file input directive.

  • OLMIS-3001: Added external url run block, that allows opening external urls.

Bug fixes:

  • OLMIS-3088: Re-implemented tab error icon.

  • OLMIS-3036: Cleaned up and formalized input-group error message implementation.

  • OLMIS-3042: Updated openlmis-invalid and openlmis-popover element compilation to fix popovers from instantly closing.

  • OLMIS-2806: Fixed stock adjustment reasons display order not being respected in the UI.

See openlmis-ui-components CHANGELOG


New features:

  • OLMIS-2543: Added interceptor for displaying server errors

See openlmis-ui-layout CHANGELOG

Dev UI

The Dev UI developer tooling has advanced to v5.

Report Service 1.0.0

This new service is intended to provide reporting functionality for other components to use. It is a 1.0.0 release which is stable for production use, and it powers one built-in report (the Facility Assignment Configuration Errors report).

Warning: Developers should take note that its design will be changing with future releases. Developers and implementers are discouraged from using this 1.0.0 version to build additional reports.

Current report functionality:

  • OLMIS-2760: Facility Assignment Configuration Errors

Additional built-in reports in OpenLMIS 3.2.0 are still powered by their own services. In future releases, they may be migrated to a new version of this centralized report service.

Requisition Service 5.0.0

Contract breaking changes:

  • OLMIS-2612: Configuration settings endpoints (/api/settings) are no longer available. Use environment variables to configure the application.

  • MW-365: Requisition search endpoints: requisitionsForApproval and requisitionsForConvert will now return smaller basic dtos.

  • OLMIS-2833 and OLMIS-3023: Added date physical stock count completed to Requisition; and feature can be turned on and off in Program Settings

  • OLMIS-2671: Stock Management service is now required by Requisition

  • OLMIS-2694: Changed Requisition adjustment reasons to come from Stock Service

  • OLMIS-2898: Requisition search endpoint takes from/to parameters as dates without time part.

  • OLMIS-2830: As of this version, Requisition now uses Stock Management as the source for adjustment reasons, moreover it stores snapshots of these available reasons during initiation. Important: in order to migrate from older versions, running this migration is required: https://github.com/OpenLMIS/openlmis-adjustment-reason-migration

New functionality added in a backwards-compatible manner:

  • OLMIS-2709: Changed ReferenceData facility service search endpoint to use smaller dto.

  • The /requisitions/requisitionsForConvert endpoint accepts several sortBy parameters. Data returned by the endpoint will be sorted by those parameters in order of occurrence. By defaults data will be sorted by emergency flag and program name.

  • OLMIS-2928: Introduced new batch endpoints, that allow retrieval and approval of several requisitions at once. This also refactored the error handling.

Bug fixes added in a backwards-compatible manner:

  • OLMIS-2788: Fixed print requisition.

  • OLMIS-2747: Fixed bug preventing user from being able to re-initiate a requisition after being removed, when there’s already a requisition for next period.

  • OLMIS-2871: The service now uses an Authorization header instead of an access_token request parameter when communicating with other services.

  • OLMIS-2534: Fixed potential huge performance issue. The javers log initializer will not retrieve all domain objects at once if a repository implemenets PagingAndSortingRepository

  • OLMIS-3008: Add correct error message when trying to convert requisition to an order with approved quantity disabled in the the requisition template.

  • OLMIS-2908: Added a unique partial index on requisitions, which prevents creation of requisitions which have the same facility, program and processing period while being a non-emergency requsition. This is now enforced by the database, not only the application logic.

  • OLMIS-3019: Removed clearance of beginning balance and price per pack fields from skipped line items while authorizing.

  • OLMIS-2911: Added HTTP method parameter to jasper template parameter object.

  • OLMIS-2681: Added profiling to requisition search endpoint, also it is using db pagination now.

Source: Requisition CHANGELOG

Stock Management 1.0.0

This is the first official release of the new Stock Management service. Its beta version was previously released in Reference Distribution 3.1.0. Since then, the major improvements are:

  • OLMIS-2710: Configure VVM use per product

  • OLMIS-2654 and OLMIS-2663: Record VVM status with physical stock count and adjustments

  • OLMIS-2711: Change Physical Inventory to include reasons for discrepancy

  • OLMIS-2834: Requisition form info gets pushed into Stock cards (see more in Requisition component)

  • plus lots of technical work including Flyway migrations, RAML, tests, validations, translations, documentation, and demo data.

Watch a video demo of the Stock Management functionality: https://www.youtube.com/watch?v=QMcXX3tUTHE (English) or https://www.youtube.com/watch?v=G8BK0izxbnQ (French)

Now that this is an official release, the Stock service is considered stable for production use. Future changes to functionality or APIs will be tracked and documented.

For a list of all commits since 1.0.0-beta, see GitHub commits

Components with No Changes

Other tooling components have not changed, including: the logging service and a library for shared Java code called service-util.


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.

Team Parrot: Paweł Gesek, Paweł Albecki, Nikodem Graczewski, Mateusz Kwiatkowski, Joanna Bebak, Paweł Nawrocki

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

A special thanks to the implementers working in Malawi who contributed features and improvements: Sebastian Brudziński, Weronika Ciecierska, Łukasz Lewczyński, Klaudia Pałkowska, Ben Leibert, Christine Lenihan.

Since version 3.1.2, we have received 40 pull requests from outside implementers and contributors.

Special thanks to community members: Kaleb Brownlow, Lindabeth Doby, Tenly Snow, Jake Watson, Ashraf Islam, Parambir Gill, 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.

Further Resources

View all JIRA Tickets in 3.2.0.

Learn more about the OpenLMIS Community and how to get involved!