What is the Best Way to Upgrade Reference Application

Upgrading OpenMRS has always been simply replacing the old war file with the new version. The system goes through the update automatically. If everything is fine one is presented with the login screen with the system upgraded to the newer desired version.

I reckon the process is pretty much the same for reference application. However, since a particular version of refapp app consist of a particular platform war version and particular modules versions how would this process be like? For example, I was upgrading from refapp 2.8.0 to 2.11.0 which runs on platform 2.3.2. I replaced the war file without replacing the modules, this did not work as expected because the browser did not display any progress as always the case after clicking the green arrow. Initially I thought maybe something was interrupting the process, so I tried several times with the same result. Eventually I decided to include all modules which were formally running on refapp 2.8.0. This created a lot of issues related to context refresh error (mostly caused by inability to inject/create beans). So, I replaced all modules that are bundled with 2.8.0 with their respective upgraded versions in 2.11.0. This seems to work, also there was no any update process, that is I was taken straight to the login page. As a result I am not sure what was going on with the update process seemingly stuck initially.

The question I am posing is, is there a standard guideline for upgrading the reference application? If there isn’t maybe it is time to create one for different environments namely, docker, openmrs sdk, and plain old native tomcat/mysql installation.

With UgandaEMR we do not depend on the Reference Application, rather we use our own distro.properties file which uses the latest versions of modules as needed, allowing us to also add custom modules

pom.xml - https://github.com/METS-Programme/openmrs-module-aijar/blob/master/pom.xml

distro.properties - https://github.com/METS-Programme/openmrs-module-aijar/blob/master/api/src/main/resources/openmrs-distro.properties

To build a war file we use the OpenMRS SDK build-distro command as part of each build https://github.com/METS-Programme/openmrs-module-aijar/blob/bc14a86ce71bd9882c8f1492ab89ee07ee971d90/omod/pom.xml#L379-L400

You can also run the command standalone from anywhere via SDK

mvn openmrs-sdk:build-distro -Ddistro=org.openmrs.module:ugandaemrpoc:LATEST -U -Dbundled=true


Thanks for such a quick response. However, the question still remains, how does one upgrade a prior version of Uganda EMR? Unless I am misunderstanding your explanation, it seems what you represented provides a solution for building a specific version of Uganda EMR but not upgrading one. Could you please clarify more?

@willa if you manage your own distro such as that of UgandaEMR, upgrading to a new version is entirely up to you.

At Mekom the slightest change that needs to be (Maven) deployed makes for a new (minor or even patch) distro release. In practise a distro release is a fixed packaging of released artifacts only.

IMO the Ref App distro should merely be used as a startup point from which you start managing your own distro.


@willa basing on the last time i looked at UgandaEMR, their war file bundled all the modules. So an upgrade would be simply replacing the war file.

Simply upgrading the war file without the modules will land you in errors where certain modules need changes to address the upgraded platform.

1 Like

@mksd & @dkayiwa thanks for your replies. Cleared everything.

So if I want to keep up with the openmrs reference application would that mean creating/updating a build script with the new versions every time there is a new release?

Yes you would update to the new versions.

1 Like

@willa if you use the OpenMRS SDK, the build script is already available as I shared and the openmrs-distro.properties file removes the need for a separate distinct distro project to be managed

I like @mksd approach for a distro release for every minor change in dependencies that are deployed into production for general use which helps tracking the dependencies at points in time.

The tools are available, you just have to use them - maybe that is an opportunity for a blog post over the holidays

1 Like