3.20.0 Release Notes - October 1, 2026

Status: Stable

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

New Features

  • Barcode Scanning (GS1) - Stock Management users can scan GS1 barcodes on the Issue, Receive, Adjustment and Physical Inventory screens. The scanned GTIN is resolved to its trade item and product, and the lot code and expiry date are read from the barcode. When a scanned lot does not exist yet, or its expiry date differs from the stored one, the user confirms before continuing. Trade items carry a validated GTIN, which can be filtered on and imported or exported through the trade item CSV. Scanning is enabled per deployment with the GS1_SCANNING flag.

  • Transaction History and Reversing Stock Movements - A new Transaction History view lists issues, receives and adjustments with their document numbers, and each stock event can be printed as a PDF report. Selected issue, receive and adjustment lines can be cancelled from the new Reverse Transaction view, which records a reversing adjustment and keeps the original event. The stock card and Transaction History show “Reversing” and “Reversed by” links between the two movements. Cancelling requires the new STOCK_EVENTS_CANCEL right.

  • Cancelling Orders - An order that cannot be fulfilled can be cancelled from the shipment view instead of confirming an empty shipment. Cancelled orders have the new CANCELLED status and are shown on the home page.

  • Supplying Facility Stock on Hand in Requisition Approval - Approvers can see the stock on hand at the supplying facility for each product. The new supplyingFacilityStockOnHand requisition template column is disabled by default, and the data is shown only to users who can view stock cards at the supplying facility.

  • Translated Reports with a Configurable Global Header - Jasper reports are translated into the language of the user, with the translation bundle sourced from Transifex and an optional deployment-specific override bundle. All stock, fulfillment, requisition and report service prints share a configurable global header with a logo. The requisition print is now generated by the report service.

  • Embedded Superset Dashboards - Superset dashboards can be embedded through the Superset Embedded SDK with a short-lived guest token, configured per dashboard report with an Embedded UUID. The previous OAuth iframe remains available as a fallback.

  • Pack Size Column - A read-only Pack Size column is shown on requisition, order create and stock management screens, and in the requisition and stock reports.

  • Default Issue and Receive Reasons - Implementations can preselect a reason on the Issue and Receive screens with the defaultIssueReasonId and defaultReceiveReasonId configuration keys.

Improvements

  • Stock event processing was reworked for performance. Concurrent stock events for the same facility and program are now processed one at a time, and stock on hand is recalculated in place.

  • Requisition second approval and requisition search are faster, and requisition search no longer fails for users with many permissions.

  • Packs and doses quantity inputs and displays are more compact, and quantities in packs print in the same format as on screen.

  • Long free-text values in table cells, such as remarks, reasons and Proof of Delivery notes, wrap instead of being cut off, and are limited to their stored length with a character counter.

  • Validation messages in the stock management and requisition grids are shown consistently when a row is left and on submit.

  • All backend services expose a Prometheus metrics endpoint at /actuator/prometheus.

  • Account lockout can be managed through the API. The auth service has a new endpoint to unlock a locked-out user, and the reference data user search accepts a lockedOut filter. The Reference UI has no screen for this yet, and account lockout stays disabled unless MAX_UNSUCCESSFUL_AUTH_ATTEMPTS and LOCKOUT_TIME are set.

  • Service registration in Consul is more reliable, and the Consul registration scripts no longer depend on axios.

  • The fulfillment service supports extension Flyway migrations shipped in db/extension/.

  • French, Spanish and Portuguese translations were updated.

Bug Fixes

  • Printing a report no longer returns a blank PDF when the report service fails. The error is shown instead.

  • Translated report labels wrap instead of being cut off, and no longer overlap their values or the report title.

  • The Pick Pack List report includes trade items shipped against commodity type order lines.

  • The Periodic Stock On Hand Summary report no longer drops identical legitimate movements, and prints “All” instead of null when no facility is selected.

  • Requisition-less orders store the ordered quantity in packs, so the Fulfill view and the order PDF no longer inflate it.

  • The CCE catalog upload accepts an unmodified export and reports conflicting rows with a readable message.

  • Notification toasts are visible again, and system notifications refresh without logging in again.

  • A role without rights no longer breaks the administration screens.

  • Apostrophes and placeholders in translated messages are displayed correctly.

  • The manual order retry endpoint re-attempts the FTP transfer and reports its real outcome.

Compatibility

Stock Management - calculated stock on hand de-duplication: the stock management 5.4.0 migration removes duplicate rows from stockmanagement.calculated_stocks_on_hand and adds a unique index on (stockcardid, occurreddate). The table holds derived data, but the removed rows cannot be restored after the migration. Take a database backup before upgrading.

DATABASE_URL must be a bare JDBC URL: the stock management service appends reWriteBatchedInserts=true to DATABASE_URL. A DATABASE_URL that already has a query string produces an invalid URL. To pass custom JDBC parameters, keep DATABASE_URL bare and set SPRING_DATASOURCE_URL to the complete URL, including stringtype=unspecified and reWriteBatchedInserts=true.

Lot codes: lot codes are limited to 20 characters from the GS1 character set on create and update. Existing longer codes stay readable, but a lot with such a code cannot be saved again until the code is shortened.

Trade item CSV export: the trade item CSV export includes a new gtin column.

CCE catalog upload: the upload is stricter. A row that matches two catalog items, two rows that resolve to the same item, and duplicated rows are now rejected. Changing the Model of an exported row adds a new catalog item instead of renaming the existing one.

Report generation endpoint: POST /api/reports/generate in the report service accepts service-level tokens only. Deployment-specific report translations must provide the report.pattern.labelledValue key, and changes under /config/reports require a service restart.

Order retry endpoint: GET /api/orders/{id}/retry returns the real FTP transfer result, and returns HTTP 400 when the supplying facility has no FTP transfer configured.

Stock movement cancellation: only movements recorded with stock management 5.4.0 or later can be cancelled.

Reason tags: the tags array in stock management reason payloads is no longer returned in a stable order.

Barcode scanners: scanning works with scanners in keyboard (HID) mode that send Enter or Tab after each barcode and transmit the GS1 group separator (FNC1) as key code 29 or Ctrl+]. A barcode without a terminator is discarded after 300 ms. Scanning is disabled unless GS1_SCANNING=true is set.

Analytics: the OpenLMIS Reporting analytics-core package 1.0.0 was tested with the reporting stack platform soldevelo-reporting-stack v0.1.1.

All other changes to OpenLMIS 3.x remain backwards-compatible. Any changes to data or schemas are accompanied by automated migrations from previous versions back to version 3.0.1.

All Changes by Component

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

Components with No Changes

  • UI Components and Services:
  • Infrastructure:

    • Nginx v7.1, PostgreSQL 14-debezium, Rsyslog 3 and Consul 1.15 are unchanged.

Upgrading from Older Versions

If you are upgrading from OpenLMIS 3.0.x or 3.1.x (without first upgrading to 3.2.x), please review the 3.2.0 Release Notes for important compatibility information about a required PostgreSQL extension and data migrations.

For information about upgrade paths from OpenLMIS 1 and 2 to version 3, see the 3.0.0 Release Notes.

If you are upgrading to version 3.19.1 or greater, the SUPERSET reports will need to be added manually by system administrators. A short manual is available here:

If you are upgrading to version 3.20.0, take a database backup before the upgrade and review the Compatibility section above, in particular the stock management migration and the DATABASE_URL requirement.

Test Coverage

OpenLMIS 3.20.0 was tested using the established OpenLMIS Release Candidate process. Three release candidates were deployed to the UAT environment, and chosen manual test cases were executed to address each change. Any critical or blocker bugs found during the release candidate were resolved.

Download or View on GitHub

OpenLMIS Reference Distribution 3.20.0

Known Issues

  • Batch Approval: Packs/Doses are not supported in the batch approve requisition view.

  • POD Compatibility: Packs/Doses are not supported in the POD creation.

  • Order Fulfillment: Quantity shipped must always be provided in packs.

  • Lot creation during stock events: a lot created while processing a receive or physical inventory event is not removed if the event then fails validation. It remains as an active lot without stock, and a resubmitted event reuses it.

Other bugs are collected in Jira for troubleshooting, analysis, and resolution on an ongoing basis. See OpenLMIS 3.20.0 Bugs for the current list of known bugs.

To report a bug, see Reporting Bugs.

Contributions

Many organizations and individuals around the world have contributed to OpenLMIS version 3 by serving on committees (Governance, Product, and Technical), requesting improvements, suggesting features, and writing code and documentation. Please visit our GitHub repositories to see the list of individual contributors to the OpenLMIS codebase. If anyone who contributed on GitHub is missing, please contact the Community Manager. Technical development of OpenLMIS is conducted by SolDevelo.

Further Resources

Please see the Implementer Toolkit on the OpenLMIS website to learn more about best practices in implementing OpenLMIS. Also, learn more about the OpenLMIS Community and how to get involved!