4.0.0 release notes

Known issues

Check the repository for the latest known issues.

Upgrade notes

Breaking changes

To prepare for this release, read through our Preparing to Upgrade documentation.

⚠️

Be aware that as this is a major upgrade some manual steps are required - following the usual upgrade process will not work. Data migration documentation is coming soon, but in the meantime reach out on the forum for direct support in upgrading. New projects should start on 4.0.0 to make the following upgrades easier.

New architecture

This is a significant change how the CHT is deployed and updated which brings a wide range of benefits and enables more opportunities for improvements in future releases. Read more about the new architecture.

#6189: Implement Architecture v3

Updated browser and Android requirements

The requirements of clients (browsers and Android devices) has been updated to allow the CHT to use modern features and benefit from improved performance and security. Before upgrading to CHT v4.0.0 ensure that:

All Android devices are running AndroidOS v5.0 or greater. In most cases this will require replacing older devices.
All Android devices are running cht-android v1.0 or greater
All Android devices are running Android System Webview v100 or greater
Browser users have the most recent version of Chrome or Firefox

All these updates are backwards compatible so these should be rolled out before upgrading the CHT server.

Upgraded Enketo

The software the CHT uses to render forms has been updated with more features, better performance, and many bug fixes. This also introduces a few changes to behavior that may require changes to form configuration. To test your forms

Use the latest cht-conf CLI tool to validate your forms. Some additional validations were added to detect issues you may have.
Upgrade a testing instance to 4.0.0 and manually test the forms to ensure they work as expected.

#6345: Update to latest enketo-core
#7731: Update today XPath function to not return current time

Secure credentials migration

Credentials used for external integration via SIH or Outbound Push features are now stored in a different way which requires a manual upgrade step. Read about how to store credentials in 4.0.0 in the API documentation.

#5904: Cluster safe credentials

Removed deprecated features

Simprints integration and the update_sent_forms transition weren’t being used so the code has been removed.

#5939: Remove update_sent_forms transition
#7421: Remove simprints code

UI/UX changes

None.

Highlights

New architecture

The major feature of CHT v4.0.0 is a new micro service architecture. This has many benefits over the previous architecture outlined in more detail in this forum post, but in summary this allows deployments to scale to many more users than previously, deployments to be updated more easily in future, better monitoring of services, performance gains, removing quite a lot of legacy code, and easier installation.

#6189: Implement Architecture v3

API startup progress screen

Previously users who tried to log in before server start up had completed would be shown an error page which wasn’t very user friendly. Now users will be shown loading page with details about the current stage of the start up process.

#2967: Report API startup progress instead of 502

And more…

Features

#2967: Report API startup progress instead of 502
#7448: Detect unsupported browser
#7694: Add xPath function for easily adding years, months, days, etc to date value

Improvements

#6382: Use Noto font on the login page
#6564: Have an upper time limit to generating task documents
#7689: Set form version when creating contacts
#7731: Update today XPath function to not return current time
#7761: Don’t provide a default password
#7802: Allow for dynamically setting container and network names
#7859: Improve admin upgrade page UX when upgrade service fails to update containers
#7879: Switch staging server to a different URL due to breaking change
#7884: Ensure all services are set up to automatically restart

Security fixes

#5904: Cluster safe credentials
#7800: Don’t hard code COUCHDB_SECRET in docker compose files

Performance improvements

#5549: Work out what we want to do with Enketo XML, and do that thing
#7801: Use local log driver in all Docker containers
#7813: Call ‘db.close’ for ephemeral PouchDB objects to avoid memory leaks

Bug fixes

#1495: jr:choice-name works for select_one, not select_multiple
#4132: Values of non-relevant fields should be maintained until submission
#5636: Xform rendering hides choices when relevance condition and choice filter are applied to a secondary question
#5980: Forms show error message upon opening
#6589: Video and Audio continues playing even after navigating to next screen
#6803: Some Enketo radio buttons don’t get checked styling on first click
#7222: Empty integer values in Enketo forms evaluate to 0
#7237: Broken functions for xForm repeat_groups
#7298: “field required” not shown when field is read_only, required, and has calculation
#7608: API wants to build form xmls when forms are deleted
#7650: Conflicts diff script crashes because of change in view code
#7657: The reports raw content has the label in the wrong place
#7676: Zero-width unicode characters removed from SMS messages too often
#7690: Uploading a form through the app management GUI does not set the xml version
#7759: Timeouts for view requests when syncing can leave changes requests hanging forever
#7786: Translation labels missing in default config
#7792: Fix openrosa-xpath-evaluator issue with numbers using scientific notation
#7832: CERTIFICATE_MODE=OWN_CERT fails with “cannot load certificate”
#7840: API credentials endpoint fails CouchDb secret is too short
#7850: CouchDb Secret does not get set in single node
#7855: When using self signed certs, upgrade page will report “Error when fetching progress” after upgrade was successful

Technical improvements

#4517: Import medic-specific functions from openrosa-xpath-extensions
#4874: Remove continuous replication code from the API changes endpoint
#5939: Remove update_sent_forms transition
#6189: Implement Architecture v3
#6345: Update to latest enketo-core
#6846: Remove custom translations from Bamanankan
#7421: Remove simprints code
#7771: enketo-transformer is not compatible with npm 8
#7775: Wdio E2E test suite broken on master
#7812: Don’t default CouchDB password to empty string
#7815: CouchDb /_utils faulty redirect
#7817: Update release build schema to v2
#7826: Publish branch and alpha docker images in public ECR
#7864: Expose CouchDb port 5986 to the docker network

Contributors

Thanks to all who committed changes for this release!

Last updated on May 5, 2025

3.9.2 4.0.1