Getting Started with OpenMRS SDK

Installation Prerequisite

JDK, Maven, MySQL

In a Ubuntu/Debian system do:

apt-get install default-jdk maven2 mariadb

In my Debian machine default-jdk is a meta package that points to openjdk-7-jdk. So to install JDK 1.8:
$ apt-get install -t jessie-backports openjdk-8-jdk

To install OpenMRS sdk, run:

mvn org.openmrs.maven.plugins:openmrs-sdk-maven-plugin:setup-sdk

It’s required that we first create a server instance for us to be able run OpenMRS platform or a distribution.
Run mvn openmrs-sdk:setup and continue with the installation.

You will be prompted to choose a server type. OpenMRS server can be of type Distribution or Platform. I recommended that you choose Distrubtion, as Platform version only includes the back-end system, and APIs.

To run the server simply run:

mvn openmrs-sdk:run

If you’ve created multiple servers, you’ll be prompted with a list of servers to choose from.

Wait for the server to start. A log output similar to INFO: Starting ProtocolHandler ["http-bio-8080"] is a good indication that your server is up and running.

Once the server is running, it should be accessible from:

All the server content goes in the directory ~/openmrs/. To list out all the installed modules of a particular server you could do:

ls ~/openmrs/<server-name>/modules


To reset a server to its initial state:

mvn openmrs-sdk:reset

You can pass the -Dfull flag, if you want to wipeout all the manually installed modules.

mvn openmrs-sdk:reset -Dfull


To deploy an existing OpenMRS module from the repository, simply run:

mvn openmrs-sdk:deploy

You’ll be prompted to enter groupId, and the artifactId of which the module you may want to deploy. Say for example you want to deploy the OpenMRS REST Module. First you may want to find its groupId, and the artifactId. These values can be found in its projects pom.xml.

Developing, Deploying and Testing an existing OpenMRS module:

Say for example you want fix a bug in OpenMRS reference application module.
First you may clone the source code of the module that you want to work on.

mvn openmrs-sdk:clone

This command eliminates the hassle of having to manually fork, clone, and to add a upstream remote which is basically a helper command for the steps shown below:

- Fork the repository
- Then clone the forked repository
    git clone<yourGitUser>/openmrs-module-referenceapplication.git
- Add remote upstream
    git remote add upstream

This will clone the git repository to your current working directory. cd in to the project directory and start making necessary changes. Once done build the project by running mvn clean install

If built ran successfully, you could (re)deploy the module with the made changes just by running

mvn openmrs-sdk:deploy

Make sure to run deploy from the projects root directory.

You’ll be prompted with Would you like to deploy -SNAPSHOT from the current directory? [Y/n] which you should answer Y (yes) for it to be deployed into your server.

Finally, run the server to test the changes you made:

mvn openmrs-sdk:run

Fixing a Bug

Bug Bug: Formatter plugin in root pom configured with wrong javaCompilerVersion variable

The bug is about mis-configured maven-java-formatter-plugin. In the pom.xml, plugin is configured with an undefined variable ${javaCompilerVersion} which should be changed to ${java.version}. Please see the diff to see how it is being fixed.

Once you know the module to work on, you will want to get a local copy of its source. Here in our case you’d run:
mvn openmrs-sdk:clone and provide with the values org.openmrs.module and for the groupId and artifactId subsequently.

cd in to the cloned directory. Before start working on a fix, it is advised that we create a separate git branch and to name it after the JIRA ticket.

git checkout -b RESTWS-614 master
mvn openmrs-sdk:pull 

Pull changes from the upstream so it is synced with the latest changes made to the upstream. This will help avoid merge conflicts when pushing your changes.

Then work on a fix. Here in our case it is simply about refactoring ${javaCompilerVersion} to ${java.version}.

Build the project, and make sure all tests pass.

mvn clean install

In case you want to skip tests, and to speed things up, you could do:

mvn clean install -DSkipTests

Lets deploy the module and test the changes.

mvn openmrs-sdk:deploy
mvn openmrs-sdk:run

If you’re happy with the result, and all the changes are committed, make a PR:

mvn openmrs-sdk:pr


Run the server in the debug mode:

mvn openmrs-sdk:run -Ddebug

In Intellij Idea this can be done by adding a new Remote configuration into your ‘Run/Debug Configurations’.

Debugging OpenMRS module with Intellij

You only need to change the value specified in the port field to the value of port which your server is listening. Here in my machine the default port for the OpenMRS server is set to 1044.

If the debugger fails to attach to the server, try running server in a different debug port:

mvn openmrs-sdk:run -Ddebug=1099

Fixes for common issues:

    • Caused by: java.lang.ClassNotFoundException:

Try creating and running a new server instance: mvn openmrs-sdk:setup

Happy Contributing!

Leave a comment

Your email address will not be published. Required fields are marked *