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 (current version: 2.0-beta) 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.

Step By Step

Describe the basics here. Download and install instructions, module creation and running openmrs with an embedded h2 (for OpenMRS 1.9.4+) and an external mysql db. 

Step 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.

Step 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.

How to create a Basic Module for OpenMRS 1.x

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.  

Creating module for OpenMRS 2.x

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

Running OpenMRS 1.x 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:

Plugin will ask you for serverId, and if success, server will be created in $HOME/openmrs folder.
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. 

Running OpenMRS 2.z 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)

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:

CommandDescriptionOptions
helpDisplays all available commands and their information.N/A
create-platform-moduleCreates module for OpenMRS 1.xN/A
create-moduleCreates module for OpenMRS 2.xN/A
runRuns previously created OpenMRS server
-DserverId=Server Id of server which will be executed (if you are not in the server directory)
setup-platformCreates OpenMRS 1.x server
-DserverId=Server Id of new server (must be unique)
-Dversion=OpenMRS version
-DdbDriver=

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"

-DdbUri=Uri for JDBC connection (optional)
-DdbUser=Database user name (optional)
-DdbPassword=Database user password (optional)
setupCreates OpenMRS 2.x server
-DserverId=Server Id of new server (must be unique)
-Dversion=OpenMRS version
-DdbDriver=

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

"postgresql" for "org.postgresql.Driver"

-DdbUri=Uri for JDBC connection
-DdbUser=Database user name
-DdbPassword=Database user password
install-moduleInstalls module to selected server (you must install it to local repository before, using "mvn clean install")
-DserverId=Server Id for server, where module will be installed (optional, if command executed from server folder)
-DartifactId=Artifact Id of module which will be installed (optional, if command executed from module folder)
-DgroupId=Group Id of module which will be installed (optional, if command executed from module folder)
-Dversion=Version of module which will be installed (optional, if command executed from module folder)
"LATEST" is also a possible value.
uninstall-moduleRemoves module from selected server
-DserverId=Server Id for server, where module will be removed (optional, if command executed from server folder)
-DartifactId=Artifact Id of module which will be removed from server (optional, if command executed from module folder)
-DgroupId=Group Id of module which will be removed from server (optional, if command executed from module folder)
upgrade-platformUpgrades OpenMRS platform server to selected version.
-DserverId=Server Id for server, which will be upgraded (optional, if command executed from server folder)
-Dversion=Target version for upgrade
upgradeUpgrades OpenMRS 2.x server, or OpenMRS Platform server to 2.x. User modules will be saved
-DserverId=Server Id for server, which will be upgraded (optional, if command executed from server folder)
-Dversion=Target version for upgrade
resetUpdates server to default state (database data, configuration, and optionally user modules)
-DserverId=Server id of server, which will be reset (optional, if command executed from server folder)
-Dfull=Remove user modules during reset. default value "false"
deleteRemove selected server
-DserverId=Server Id of server, which will be removed

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

Project Resources

  • No labels