Technical Details of OpenMRS upgrade from 2.1.7 to 2.4.2

List of libraries upgraded from OpenMRS 2.1.7 to 2.4.2

Below are the list of libraries that got upgraded as part of latest OpenMRS 2.4.2 upgrade.

Please refer to the pom.xml for list of both OpenMRS and Bahmni modules that got upgraded as part of the OpenMRS 2.4.2.

Basic and Optional Modules List

For Bahmni to up and running and to able to access the EMR modules like reg, clinical, programs, IPD, Admin, Patient Doc Upload, Radiology upload below modules needs to be part of the distro.

We have divided modules into 2 parts

1. Basic Modules

2. Optional Modules

Basic Modules by Stage: The below are the set of modules that are required to bring Bahmni up and running. The below table depicts the dependency graph of the modules. With every stage we should be able to see the openmrs UI loading fine. At the end of the Stage 5 we should be able to see Bahmni UI loading fine.

Optional Modules: These are the modules can be added based on the functionality we need and these modules doesn’t have direct dependency of loading other modules as we have seen in the basic moduels.

• Appointments Module

• Operation Theatre Module

• Bahmni.ie.apps module

• FHIR2

• FHIR2-extension module(depends on FHIR2)

Upgrade Strategy

We have followed incremental upgrade strategy where the approach is to upgrade one version at a time(eg: 2.1.6 to 2.2.0) in all the Bahmni basic modules and build the module successfully.

Open

Steps for upgrade (for single omod)

1. Upgrade openmrs version in a omod( eg: bahmni-core.omod)

2. Handle all the API breaking changes as per the openmrs version in the module 

3. Fix all the failing unit test cases as per the OpenMRS changes.

4. Fix all the failing integration test cases as per the OpenMRS changes

For Optional modules we followed direct upgrade of OpenMRS version from 2.1.7 to 2.4.2

Once the upgrade is done for basic modules we tried to bring up the Bahmni env with all the basic modules. Once the env is stable then we incrementally added the upgraded optional modules.

List of issues faced during the upgrade

We have divided issues into below three categories

1. Module upgrade time issues(from one openmrs version to other)

2. Run time env issues(with Openmrs 2.4.2)

3. API Changes

Module upgrade time issues

1. Integration tests would fail with bean creation exception. The below snippet needs to be added in the TestingApplicationContext.xml

2. Change <ref local> property to <ref bean> tag because of spring upgrade in moduleApplicationContext.xml

3.  javax-servlet requires version upgrade

If we see the below error as part of running the integration tests upgrade javax-servlet version to from 2.x to 4.1

4. Spring class annotation updation because of spring version upgrade

• org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter to org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter

• org.springframework.web.servlet.mvc.annotation.DefaultAnnotationHandlerMapping to org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping

5. mockStatic Issue, getting mockStatic function from below two libraries, Needed to use the one coming from PowerMockito for fixing tests

https://github.com/openmrs/openmrs-module-bedmanagement/pull/59/commits/2d99a781fce9243b8f7b29b7dddcf6c21a3ee5d0

7. Remove deprecated spring annotation to resolve runtime errors

https://github.com/Bahmni/openmrs-module-episodes/commit/ef39e696319364842612aafefe80c48581681990

8. As per migration in openmrs of renaming column name from precise to allow_decimal needed to make migration changes

https://github.com/Bahmni/bacteriology/commit/8cfae96cd2293bfbdbb81fed40cd571ff8dce1ce

9. Upgrade powermock-api-mockito to powermock-api-mockito2 in pom.xml

Runtime Issues

1. Module is not loading because of the failing liquibase migration. Check the openmrs.log or openmrs modules UI page to get to the specific failing migration. Please check this card for more details.

2. Spring bean creation exception as shown in the code snippet.

Eg: 1. more than one bean is available for the specific class

2. No qualifying bean available.

Resolution:

• more than one bean is available for the specific class: This issue would come if the bean is instantiated through moduleapplicationContext.xml (through component-scan) and @Autowire the same bean. So the spring would find two instances of the same class and not able to select one.

• No qualifying bean available: bean instantiated to @Component might not work sometime. Make sure the bean is injected through moduleapplicationContext.xml or class constructor

API Changes

1. Program attribute type, patient program, patientProgram attribute moved from bahmni-core to openmrs-core repositores. So the respective package names requires change.

2. Patient Program Attribute Resource moved from bahmni-core to webservices.rest. The existing API would work. No change required.

3. Condition table schema has changed. New columns got added and change in the exiting column name.

Steps to upgrade custom module

1. Update library versions and module versions in the pom.xml file along with openmrs-core version. Please refer to this section for the versions. Eg: openmrs-core version needs to be updated to 2.4.2 in the pom.xml file of the custom module

2. Change the mockito versions as per the pom.xml from bahmni-core/pom.xml

3. Fix the compile time issues: Make sure

   • there are no compile time issues once we have updated the relevant module versions in the pom.xml file.

   • api/pom.xml and omod/pom.xml has module versions are parameterised and passed from main module pom.xml

Note: Please refer to the API change section to see whether any packages are moved from bahmni to openmrs repo’s. Based on that make the relevent changes.

4. Fix the unit test cases: Make sure the test cases are passing with the module changes. 

Note: Refer to Module upgrade time issues section

5. Fix the integration test cases: Please check this section for any issues.

By the end of the above steps we should have the module build has passed and the upgrade of the openmrs 2.4.2 is completed in the custom module. Now deploy the omod file in the Bahmni env and restart the openmrs service.

Note: Refer to run time issues section if the module has not loaded