OpenMRS SDK

Overview

OpenMRS SDK allows for rapid development of modules and the OpenMRS Platform code. It is an ever expanding project with a rich feature-set, outlined below. Operating System compatibility was also taken into account, allowing users to install the SDK and be up and running within a few minutes on Windows, Linux and Mac OS X.

Release Notes

• 3.7.0 (released on 2017/01/20)
  
  

• 3.6.0
  
  

• 3.5.0 (released on 2016/11/29)
  
  

• 3.4.0 (released on 2016/10/12)
  
  

• 3.3.0 (released on 2016/09/05)
  
  

• 3.2.0 (released on 2016/08/18)
  
  

  
  
  
  

• 3.1 (released on 2016/08/03)
  
  

• 3.0 (released on 2016/07/13)
  
  

• all release notes...

Installation

Requirements

JDK 1.8

To make sure that you have  JDK 1.8 installed properly, open up a console/terminal and enter:

on Windows:

on Linux/Mac:

It should say:

If you do not have similar output or the Java version does not start from 1.8, then you have to install JDK. Follow Oracle's guide.

Maven 3.x

To make sure that you have Apache Maven 3.x installed, open up a console/terminal and enter:

You should see:

If you do not have similar output, you are missing the Maven, please go ahead and install it. Here are tutorials for Windows, Mac OSX, Ubuntu.

Miscellaneous 

Although Git is not necessary for OpenMRS SDK to work, we recommended you to install it as well. See here.

You will also want to make sure that your maven has enough memory available for building code, running tests and servers. Please set the MAVEN_OPTS system property to "-Xmx768m -XX:MaxPermSize=512m". It depends on your OS on how you set it up. See http://stackoverflow.com/a/2820738 for Windows or http://unix.stackexchange.com/a/117470 for Unix/Linux.

If you are using an IDE for calling openmrs-sdk commands, please make sure to configure VM arguments in run configurations accordingly.

You will also need MySQL 5.7 for development of most OpenMRS modules. Please follow MySQL's guide.

Once completed, let's move on to setting up the SDK.

Setup

To setup the OpenMRS SDK you just need to open up a terminal/console and enter:

Once it is finished, you can make sure the OpenMRS SDK works by running the following command:

It should produce the following output:

If that is the case, you have successfully installed the SDK.

Upgrade

You can upgrade to the latest version of the OpenMRS SDK by running:

Basic usage

Let's start from creating a server to run the OpenMRS platform or a distribution. 

When asked specify server id, which you will later use to run your server. You can have as many servers as you want. Each server can run a different set of modules and use a different database.

Next type '1' to setup a distribution or '2' to setup the OpenMRS platform without any modules.

Note that for running a distribution you will most likely need to have MySQL 5.7 installed.

Answer all remaining wizard questions, which may include selecting a version of platform or distribution, database connection details, JDK path.

Next let's create a module.

You will need to choose what type of module you want to create. It is either a platform module, which can be run on any server or OpenMRS Reference Application module, which needs to be run on a server with the OpenMRS Reference Application distribution installed.

A new directory named after the artifactId (basicexample by default) will be created for you with all the initial code constituting any OpenMRS module.

Let's build, deploy and run the module on the server.

You will be asked to choose the server id, which you want this new module to be deployed to. If you do not want to be asked for the server id each time you run the module, just use:

When running the server for the first time, you will see:

You need to go to http://localhost:8080/openmrs/ to complete the setup. You should see a page with the installation progress. Once done you will be redirected to the login page. Use admin as the username and Admin123 as the password.

Documentation

The OpenMRS SDK consists of a number of commands. In this section we will cover different use cases for them. By default all OpenMRS SDK commands work in a wizard mode that is, if there are any parameters required, but not provided, you will be asked for them.

Setting up servers

The openmrs-sdk:setup command allows you to easily create instances of servers running OpenMRS. You can have as many servers on your machine as you wish. They are stored in ~/openmrs (Linux/Mac) or  %userprofile%\openmrs (Windows).

The OpenMRS SDK supports setting up a server with a plain platform or any distribution.

Databases

Servers can be configured to use H2 or MySQL 5.7 database. We also support databases running in a docker container. The H2 database is only supported by some modules. If you choose to install the Reference Application distribution, you must use the MySQL database.

The SDK comes with the H2 database so you do not have to install anything to use it. The MySQL 5.7 database needs to be installed prior to using it with the SDK. Please refer to installation instructions.

An H2 database is stored in a directory under ~/openmrs/server_id/database

A MySQL database with initial schema is created, if it does not exist when running setup. If you include @DBNAME@ in a dbUri, it will be replaced with "your_server_id".

The db docker container support comes in two flavours. One is letting SDK create and manage a MySQL 5.7 docker container for you. The other is creating a DB docker container manually and specifying container Id, label or name and connection details when setting up a server. The db docker container will always be started (if not already running) before starting the OpenMRS server.

Distributions

The SDK supports setting up a server with a distribution. The OpenMRS distribution consists of a platform and a set of modules.

If your distribution is published as a maven artifact, you can make it work with SDK by simply adding openmrs-distro.properties file under src/main/resources. That way others will be able to setup your distribution by simply typing -Ddistro=package:artifactId:version. To setup such a distribution it is not even required to clone its repository as Maven will fetch the given artifact from a remote repository.

See here how it is done for the Reference Application distribution.

If you do not use maven to publish your distribution, you can also create openmrs-distro.properties file. The openmrs-sdk:setup command will have to be run from a directory, which contains the file or with -Ddistro=path/to/openmrs-distro.properties.

See here how it is done for the Concept Dictionary OWA server.

Examples

Examples are provided as batch commands whenever possible, which means parameters are specified explicitly and you should not be asked questions. If you skip the parameters, you should be able to achieve the same following wizard questions.

Setup OpenMRS Reference Application 2.10.0 on MySQL database

Setup OpenMRS Platform 2.3.5 on H2 database

Which JDK would you like to use to run this server?:
1) JAVA_HOME (currently: C:\Program Files\Java\jdk1.8.0_172)
2) Other...

Which one do you choose? [1/2]:

Answer: 1

The server will use JAVA_HOME system variable whenever starting up. It means that if the value is changed in the system, the server will start using the new value after restart.

Setup OpenMRS Platform 2.3.0-SNAPSHOT on MySQL database

Which JDK would you like to use to run this server?:
1) JAVA_HOME (currently: C:\Program Files\Java\jdk1.8.0_172\jre)
2) Other...

Which one do you choose? [1/2]:

Answer: 1

Setup Concept Dictionary OWA distribution on H2 database

Setting up a new server...

You can setup the following servers: 1) OpenMRS Concepts OWA server 1.0 from current directory 2) Distribution 3) Platform Which one do you choose? [1/2/3]:

Answer: 1

Would you like to use the h2 database (-DdbDriver) (note that some modules do not support it)? [Y/n]:

Answer: Y

Which JDK would you like to use to run this server?:
1) JAVA_HOME (currently: C:\Program Files\Java\jdk1.8.0_172\jre)
2) Other...

Which one do you choose? [1/2]:

Answer: 1

Adding '-Drun' flag will make SDK run newly created server right after successful setup.

Setup new Server from a distribution that uses the SDK Docker for MySQL (non-interactive mode)

This will create a new server with id = "test", based on the distribution defined in the mirebalais module's openmrs-distro.properties file, providing answers to server port (8080), debug port (1044), and to use the SDK Docker container.

Deleting servers

You can delete a server by running:

The command will delete the server as well as the database it used. If the command fails for some reason, you can delete the server manually by dropping ~/openmrs/mysever (Linux/Mac) or %userprofile%\openmrs (Windows) directory.

Creating projects

Creating OpenMRS module

To create an openmrs module project in the current directory, use the openmrs-sdk:create-project command. The newly created project has basic structure and configuration files generated from an archetype. It is ready to be built and installed on an OpenMRS instance right after creation.

There are three types of projects: referenceapplication-module, content-package module and platform-module. After you choose the module type, the SDK will run a wizard, where you will have to provide information about a module to create.

Create a Content Package module

The command is in non-interactive mode and it initializes a basic OpenMRS content package project with specified details like module ID, name, version, and description, using the OpenMRS SDK Maven plugin.

Creating OWA project

To create new OWA project run 

Example

Creating Reference Application module

Creating a module has always the same workflow. The example shows how to create the Reference Application module.

In a directory where you want to have a directory with a project, run:

The wizard will appear:

What kind of project would you like to create?: 
1) Platform module 
2) Reference Application module 
3) Open Web App 

4) Content Package

Which one do you choose? [1/2/3/4]:

Answer: 2

Wizard asks for basic informations about your new module. Conventions and hints are displayed as well.

Module id uniquely identifies your module in the OpenMRS world.
It is advised to consult your module id on https://talk.openmrs.org to eliminate possible collisions. 
Module id must consists of lowercase letters, must start from a letter, can contain alphanumerics and dots,
e.g. webservices.rest, metadatasharing, reporting, htmlformentry.

Please specify 'module id': (default: 'basicexample'):

Module name is a user friendly name displayed to the user instead of the module id. 
By convention it is a module id with spaces between words.

Please specify 'module name': (default: 'Basic example'):

Describe Your module in a few sentences : 

GroupId, artifactId and version combined together identify your module in the maven repository. 
By convention OpenMRS modules use 'org.openmrs.module' as a groupId and the module id as an artifactId. 
The version should follow maven versioning convention, which in short is: major.minor.maintenance(-SNAPSHOT).

Please specify groupId (default: 'org.openmrs.module', must follow java conventions for naming packages): :

Please specify 'artifactId' (all lowercase, must start from a letter, allowed a-z, 0-9): 

Please specify 'initial version': (default: '1.0.0-SNAPSHOT'): 

Process is finished with creating project in your current directory. It should be ready to be packaged with

Creating OWA project

Run the command from any directory

Please specify a directory for OWA project (a relative or absolute path):