Wiki Spaces

Documentation
Projects
Resources

Get Help from Others

Q&A: Ask OpenMRS »
Discussion: OpenMRS Talk »
Real-Time: IRC Chat

Documentation

Skip to end of metadata
Go to start of metadata

Overview

OpenMRS SDK (latest version - 2.0.2) allows for rapid development of modules and the OpenMRS core 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 Rafał Korytkowski (Mentor) throughout the length of GSoC 2013.

In GSoC 2015 the OpenMRS SDK was reworked by Dmytro Trifonov and Rafal Korytkowski (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.

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

You should see output like this:

SDK requires Maven 3+ installed. You can download Maven from here and install.

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.
Once completed this, lets move onto setting up the sdk.

2. Setting up OpenMRS SDK

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

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

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

Useful tip

 For all commands, you may not pass any attributes. In this case, all required parameters will be prompted in interactive mode.

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:

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:

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:

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:

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

Example:

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:

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:

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 setupsetup-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:

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:

Uninstalling module from server

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

Example:

Running a server

OpenMRS 1.x instance with an embedded Database 

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

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

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

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:

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)

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:

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:

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:

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:

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

Example:

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:

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:

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:

Upgrade Reference Application based server

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

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:

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 OpenMRS-Core. 

Each command can be executed by:

Each option must be passed with next format:

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

All supported commands listed below:

CommandDescriptionOptions

help

Displays all available commands and their information.N/A

create-platform-module

Creates module for OpenMRS 1.xN/A

create-module

Creates module for OpenMRS 2.xN/A

run

Runs previously created OpenMRS server
serverIdServer Id of server which will be executed (if you are not in the server directory)
jetty.portPort to run OpenMRS (optional) default value: 8080

setup-platform

Creates OpenMRS 1.x server
serverIdServer Id of new server (must be unique)
versionOpenMRS version
dbDriver

Database driver type (optional) default value: "org.h2.Driver" (or "h2")

Shortcuts: "h2" for "org.h2.Driver", "mysql" for "com.mysql.jdbc.driver",

"postgresql" for "org.postgresql.Driver"

dbUriUri for JDBC connection (optional)
dbUserDatabase user name (optional)
dbPasswordDatabase user password (optional)
addDemoDataAdd demo data to server (optional) default value: false
file

File to get required server parameters (server properties file) (optional).
If this option used with one of parameters above, they will overwrite attribute values
from file. 

setup

Creates OpenMRS 2.x server
serverIdServer Id of new server (must be unique)
versionOpenMRS version
dbDriver

Database driver type. Shortcuts: "h2" for "org.h2.Driver", "mysql" for "com.mysql.jdbc.driver",

"postgresql" for "org.postgresql.Driver"

dbUriUri for JDBC connection
dbUserDatabase user name
dbPasswordDatabase user password
fileFile to get required server parameters (server properties file) (optional).
If this option used with one of parameters above, they will overwrite attribute values
from file. 

install

Installs module to selected server (you must install it to local repository before, using "mvn clean install")
serverIdServer Id for server, where module will be installed (optional, if command executed from server folder)

artifactId

Artifact Id of module, which will be installed (optional, if command executed from module folder)
groupIdGroup Id of module, which will be installed (optional, if command executed from module folder)
versionVersion of module, which will be installed (optional, if command executed from module folder)
"LATEST" is also a possible value.

uninstall

Removes module from selected server
serverIdServer Id for server, where module will be removed (optional, if command executed from server folder)
artifactIdArtifact Id of module, which will be removed from server (optional, if command executed from module folder)
groupIdGroup Id of module, which will be removed from server (optional, if command executed from module folder)

upgrade-platform

Upgrades OpenMRS platform server to selected version.
serverIdServer Id for server, which will be upgraded (optional, if command executed from server folder)
versionTarget version for upgrade

upgrade

Upgrades OpenMRS 2.x server, or OpenMRS Platform server to 2.x. User modules will be saved
serverIdServer Id for server, which will be upgraded (optional, if command executed from server folder)
versionTarget version for upgrade

reset

Updates server to default state (database data, configuration, and optionally user modules)
serverIdServer id of server, which will be reset (optional, if command executed from server folder)
fullRemove user modules during reset. default value "false"

delete

Remove selected server
serverIdServer Id of server, which will be removed

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

AttributeDescription
connection.usernameUsername for database connection
connection.urlURL for database connection
server.idUnique name of a server
connection.driver_classDatabase driver class
connection.passwordPassword for database connection
admin_user_passwordDefault admin password (used for first launch)
user_modulesComma-separated list of user modules.
add_demo_dataAdd demo data to server (platform server only)
database_nameDatabase name for server (usually generated automatically)
openmrs.versionWeb App version (non-platform server only)
openmrs.platform.versionOpenMRS version

Example

installation.properties

Project Resources

  • No labels