OpenMRS SDK 2.x

Overview

OpenMRS SDK (latest version - 2.1, released on 2015/11/18) 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.

The SDK was proposed as a GSoC 2013 Project, which was then developed by Chris Niesel and raff (Mentor) throughout the length of GSoC 2013.

In GSoC 2015 the OpenMRS SDK was reworked by Dmytro Trifonov and raff (Mentor) to support OpenMRS 2.x and provide better integration with IDEs by the mean of a maven plugin.

Feedback 

Please help us improve SDK. We kindly ask you to report any problems in JIRA or in notes. Please include the output of openmrs-sdk:help in your problem description. In order to test SDK on your computer please go through the Step By Step instructions that you find below.

Release Notes

• 2.1 (released on 2015/11/18)
  

  key	summary	type	assignee	reporter	priority	status	resolution
  Unable to locate Jira server for this macro. It may be due to Application Link configuration.

• 2.0.3 (released on 21/09/2015)
  

  key	summary	type	assignee	reporter	priority	status	resolution
  Unable to locate Jira server for this macro. It may be due to Application Link configuration.

• 2.0.2 (released on 27/08/2015)
  

  key	summary	type	assignee	reporter	priority	status	resolution
  Unable to locate Jira server for this macro. It may be due to Application Link configuration.

• all release notes...

Installation

1. Development Environment Check

Before we get started with the installation of the OpenMRS SDK you have to make sure that if you are planning on working in conjunction with GitHub, that you have
Git installed. For a howto on how to do that see here.

Once Git is installed, you have to make sure that you have the Apache Maven installed. To see if you do, open up a console/terminal and enter

mvn -v

You should see output like this:

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.

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 "-Xmx2048m -XX:MaxPermSize=1024m". It depends on your OS 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.

Once completed this, let's move onto setting up the sdk.

2. Setting up OpenMRS SDK

For setup the SDK you just need to open the terminal and execute:

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

Once it is finished, you can make sure the SDK works. To do so, open up a terminal/console and issue the following:

mvn openmrs-sdk:help

The output it gives, should be similar of that below:

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

3. Upgrading OpenMRS SDK

If your SDK version isn't the latest version, you can update it using -U option with any SDK command.

For example, execute mvn openmrs-sdk:help -U, to be sure that you have the latest version installed.

Examples of usage

Creating a module

OpenMRS Platform module

The SDK allow you, the user to create a basic module, with little effort! All that you have to do is, make sure you have a console/terminal window open and make sure you are
in a directory that you have write access to.  If that is the case, you just issue the following:

mvn openmrs-sdk:create-platform-module

This will now prompt you for various inputs, the default value/name is already assigned, which you can change if you input your own.
Once the creation process is finished, you can now start working on your module. Be sure that you initialize a git project and push it to 
your Github account for easy development access. 

OpenMRS Reference Application 2.x module

Similarly as creating OpenMRS 1.x module, you can create module for OpenMRS 2.x. For that, you can execute command:

mvn openmrs-sdk:create-module 

Creating a server

OpenMRS Platform server

For running and testing OpenMRS modules we need to create and configure an OpenMRS server instance. For creating a OpenMRS platform server you can use setup-platform command.

Example:

mvn openmrs-sdk:setup-platform -DserverId=test -Dversion=1.11.2

mvn openmrs-sdk:setup-platform

You can pass server attributes for the server. To get full list of them, see setup-platform section of this documentation.

If command will executed without errors, server will be created in $HOME/openmrs/<serverId> directory. 

OpenMRS Reference Application 2.x server

Similarly as create platform server, you can create OpenMRS Reference Application (RA) 2.x server, using setup command.

Example:

mvn openmrs-sdk:setup -DserverId=test2 -Dversion=2.1 -DdbDriver=mysql -DdbUser=root -DdbUri=jdbc:mysql://localhost:3306/@DBNAME -DdbPassword=12345

Note, that SNAPSHOT versions for RA based server also supported. For example, you can create OpenMRS 2.3-SNAPSHOT based server. 

Example:

mvn openmrs-sdk:setup -DserverId=test3 -Dversion=2.3-SNAPSHOT

Creating server from properties file

During module development, sometimes we need to execute module on other machine (for example, on a remote server), but using the similar OpenMRS server instance (with a same configuration). Basically there are two ways to do that: move all server files to remote, or run setup command with required parameters, and install all required user modules. But you can move server much easier, using server properties file (see installation.properties).
For that, copy server properties file on remove server,  and then execute:

mvn openmrs-sdk:setup -Dfile=serverdata/installation.properties

The same server, as original for this properties file, will be created. The same option also will work for setup-platform command.
If any other option except file will be added, it will override options of a file. For example:

mvn openmrs-sdk:setup -Dfile=serverdata/installation.properties -DserverId=test3

In this case, server will be created with a name "test3", even if other name selected in installation.properties file. In the same way you can override all available server attributes (see setup, setup-platform).

Installing module on server

To install module on selected server, just execute install task with required parameters (see install options). Note, that before installing a module on server you must install it lo local maven repo (launch mvn clean install for this)

Example:

mvn openmrs-sdk:install -DartifactId=mymodule -Dversion=1.1 -DserverId=test2

Also you may not pass any module parameters for this command, for this you must execute install task directly from module folder, and current module will be installed (parameters will be fetched from module pom file)

Example:

cd <modulename>
mvn openmrs-sdk:install -DserverId=test2

Uninstalling module from server

To uninstall module from server, just execute uninstall command (see uninstall options)

Example:

mvn openmrs-sdk:uninstall -DserverId=test2 -DartfactId=mymodule

Watching module for changes

Since SDK 2.1 it is possible to enable the uiframework development mode for modules. You can add any module to server's list of watched modules by going to modules source code main directory and typing:

mvn openmrs-sdk:watch -DserverId=test2

You can also list watched modules for the given server typing:

mvn openmrs-sdk:info -DserverId=test2

If you want to stop watching a module type:

mvn openmrs-sdk:unwatch -DserverId=test2 -DartifactId=mymodule

Running a server

OpenMRS 1.x instance with an embedded Database 

Within the module that you just created, you can choose to run OpenMRS platform with an Embedded Database to test the module you are working on.
First, you need to create server:

mvn openmrs-sdk:setup-platform

Than you need to install you module to server. For that, execute next: 

cd <module-name>
mvn clean install openmrs-sdk:install

Plugin will ask you for a serverId of server, you must put the id of just created server. After that, you can execute it:

mvn openmrs-sdk:run

If you run this command from the server folder, the server will start immediately. Otherwise plugin will ask you for a serverId.

If the server starts successfully, you can access a fully running OpenMRS instance by going to http://localhost:8080/openmrs 
If a previous install of OpenMRS did not happen, an automatic installation will be done. When the wizard is finished, the page will refresh and
you can login using:

User: admin
Password: Admin123 

The module you were working on, providing it was built without any error, should be visible on the administration page. 

OpenMRS Reference Application 2.x instance with an external database

Steps for creating OpenMRS 2.x server, and starting, are mostly the same as for 1.x. First, setup 2.x server:

mvn openmrs-sdk:setup

Besides serverId, you must put database driver class, database URI, login and pass for database user.

And finally, install module to server, and run selected server (These steps are absolutely the same as for OpenMRS 1.x)

cd <module-name>
mvn clean install
mvn openmrs-sdk:install
mvn openmrs-sdk:run

Running a server from server folder

OpenMRS SDK 2 supports an option of running a server without passing any parameters (serverId). For this, you can execute run task directly from server folder.

Example:

cd $HOME/openmrs/<serverId>
mvn openmrs-sdk:run

After that, server <serverId> will be executed.

Running a server from module folder

During module development, we need to test how out module works. For that each time we need to install a module on server, and them run. SDK allows to do it much more simple. You can execute run task directly from module folder, and selected module will be installed on server before launching automatically. 

Example:

cd <modulename>
mvn openmrs-sdk:run -DserverId=test

As usually, you may not pass serverId as a parameter of run task, in this case serverId will be prompted in interactive mode.

Running a server on different ports

Basically OpenMRS instance launching on 8080 port, but you can choose any other port for executing. For this, you can pass jetty.port option for run task.

Example:

mvn openmrs-sdk:run -DserverId=test -Djetty.port=8081

Server reset

Reset server, with saving user modules

To return server to its default state (as it was after creating) you may use reset command. All user data (database data, except user modules) will be removed. See more details about reset.

Example:

mvn openmrs-sdk:reset -DserverId=test

You may remove current server, without passing serverId option. For this, please run reset from server folder. 

Example:

cd <server>
mvn openmrs-sdk:reset

Full reset, with removing user modules

To return server to default state, including user modules removing, you may pass a full option for reset task.

Example:

mvn openmrs-sdk:reset -DserverId=test -Dfull=true

Server upgrade

Upgrade platform based servers

For upgrading OpenMRS Platform server to later version, you may use upgrade-platform command. See more details about upgrade-platform.

Example:

mvn openmrs-sdk:upgrade-platform -DserverId=test -Dversion=1.11.2

Note, that you can't make upgrade to lower version of OpenMRS Platform, only to higher.

For upgrading current server, without passing serverId option, just execute command from server folder.

Example:

mvn openmrs-sdk:upgrade-platform -DserverId=test -Dversion=1.11.2

Upgrade Reference Application based server

For upgrading Reference Application server, you can use upgrade task.
Example:

mvn openmrs-sdk:upgrade -DserverId=test -Dversion=2.2

Also you can upgrade platform server to Reference application  server. For this, also use upgrade task as described above, no any additional options required.

Fixing errors on server upgrade

If upgrading server finished with an error (for example, if you tried update server to missing server version) you can return server to previous state, which was before running upgrade.

Server files wouldn't be removed, but you just need to remove "old.properties" file to "installation.properties".

Server delete

For deleting server and all server files, use delete command. See details about delete. Please note that currently server data will not be removed from database after remove, so you need to remove this data manually. Database name for selected server you can find in installation.properties file.

Example:

mvn openmrs-sdk:delete -DserverId=test

List of commands

These commands are mainly used for working with an OpenMRS Module, however certain ones can come in handy if you are doing development on the OpenMRS core. 

Each command can be executed by:

mvn openmrs-sdk:<command> [options]

Each option must be passed with next format:

<command> -D<option>=<value>

Here is an example of executing run task, with an option "serverId" which has a value "test":

mvn openmrs-sdk:run -DserverId=test

All supported commands listed below:

Note! All parameters, except "optional" are required, and will be prompted if user will no put them 

Server properties file

Description

Server properties file - is a file, used for saving server properties, which required while running OpenMRS instance. File name of this file is usually "installation.properties", both for platform and Reference Application types of server.

Installation.properties file usually placed in $HOME/openmrs/<serverId>/installation.properties

Attributes list

Example

create_database_user=false
openmrs.platform.version=2.2
connection.username=root
connection.url=jdbc\:mysql\://localhost\:3306/openmrs-b1?autoReconnect\=true&sessionVariables\=storage_engine\=InnoDB&useUnicode\=true&characterEncoding\=UTF-8
server.id=b1
connection.driver_class=com.mysql.jdbc.Driver
connection.password=ermolenko
admin_user_password=Admin123
install_method=auto
user_modules=org.openmrs.module/ttt/1.0-SNAPSHOT,org.openmrs.module/mod2/1.1
add_demo_data=false
module_web_admin=true
has_current_openmrs_database=true
create_tables=true
database_name=openmrs-b1
openmrs.version=1.11.2
auto_update_database=false

Project Resources

MAVEN_OPTS