Wiki Spaces
Documentation
Projects
Resources
Get Help from Others
Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack
Important!
This version is outdated. Please use latest SDK version: OpenMRS SDK
Overview
OpenMRS SDK 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.
Download
Screencast
To be added.
Feedback
Please help us improve SDK. We kindly ask you to report any problems in JIRA or in notes. Please include the output of omrs-version 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 Java Development Kit(JDK) installed. To see if you do, open up a console/terminal and enter
javac -version
You should see output like this:
SDK requires Java 1.7+. You must have the JAVA_HOME environment variable set. See here.
If you do not have similar output, you are missing the JDK, please go ahead and install it.
Here are tutorials for Windows, Mac OSX, Ubuntu.
Once completed this, lets move onto installing the sdk.
Step 2. Installing OpenMRS SDK
Now go ahead and download your operating system's compatible version of the OpenMRS SDK installer.
You will require Administrative privileges to install the SDK, thus make sure that you have those privileges associated with your user account.
The installation is fairly straightforward.
On Windows and Mac OS X you just need to double click on the downloaded installer. On Linux you need to do:
chmod +x omrsdk-... sudo ./omrssdk-...
Once it is finished, you can make sure the SDK works. To do so, open up a terminal/console and issue the following:
omrs-version
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
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:
omrs-create-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.
Running OpenMRS with an embedded Database
Notice: This only works with OpenMRS version 1.9.4+
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.
To do so, be sure you are in the module directory. Once there you can either issue in the console:
omrs-run
or
omrs-create-project
next issue
omrs-run
Once you followed either of those two methods, you can now access a fully running OpenMRS instance by going to http://localhost/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 with an external database
You follow the same steps needed to create a module, however the steps are a bit different post module creation. In order for you, the developer to run
OpenMRS with an external server you need to modify the omrs-run command that is issued. Please issue:
omrs-run -Pinstall-wizard
or
omrs-create-project
next issue
omrs-run -Pinstall-wizard
This modification will cause OpenMRS, when accessed via the browser to prompt the you, the developer for all info required to connect to a SQL Database.
You use the exact same credentials as above to access the web-interface.
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. The latter will be discussed further down.
| Command | Description | Options | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| omrs-version | Displays version and runtime information for the OpenMRS-SDK | N/A | ||||||||||
| omrs-info | Displays all available commands and their information. | N/A | ||||||||||
| omrs-run | Runs an OpenMRS instance of the latest version unless specified otherwise |
| ||||||||||
| omrs-create-project | Creates an OpenMRS Project. |
| ||||||||||
| omrs-create-module | Creates an OpenMRS Module. |
| ||||||||||
| omrs-clean | Cleans an OpenMRS-SDK Project or Module Project of temporary files. | N/A | ||||||||||
| omrs-clean-install | Cleans OpenMRS-SDK Temp files, and compiles module. | N/A | ||||||||||
| omrs-install | Compiles all files to create a runnable module. | N/A |
Working on OpenMRS Core
OpenMRS SDK uses the following features of OpenMRS core 1.9.4+. We provide them here for the reference. Examples listed below refer to Jetty, however they can be used when running OpenMRS on any application server.
| Feature | Usage |
|---|---|
| Installation-script command line property | Once you have cloned an OpenMRS-core github repository you are able to specify an Use mvn jetty:run -DOPENMRS_INSTALLATION_SCRIPT=<path to script> to set the path to the custom installation script. |
| Automatic installation feat. H2 Database | If you want to install OpenMRS after you have compiled the project with the alterations, Use mvn jetty:run -Pinstall-h2 to automatically install OpenMRS with the default installation script located in the classpath. |
| AppData directory command line property | If you wish to set the Application Data directory to a custom location for easy configuration access mvn jetty:run -DOPENMRS_APPLICATION_DATA_DIRECTORY=<path to custom dir> to adjust the Application Data directory. |
Project Resources
| Element | Repository |
|---|---|
| OpenMRS-SDK | https://github.com/openmrs/openmrs-sdk |
| SDK-Archetype | https://github.com/openmrs/openmrs-maven-archetype-project |
| JIRA | https://tickets.openmrs.org/browse/SDK |
Overview
Content Tools
Feedback on this page? Questions?
Copyright © 2004-2016 OpenMRS Inc. By using this site, you agree to the OpenMRS Privacy Policy.
Text is available under the Creative Commons 4.0 International Attribution License (CC BY 4.0).
Software is available under the Mozilla Public License 2.0 with Healthcare Disclaimer (MPL 2.0 HD).
"OpenMRS" is a registered trademark and the OpenMRS graphic logo is a trademark of OpenMRS Inc.
5 Comments
Ryan Crichton
What does omrs-create-project actually do? It's not clear from the documentation how this differs from omrs-run. When should we use one over the other?
Rafal Korytkowski
omrs-create-project creates a configuration to run OpenMRS with omrs-run. You can create a project in your workspace for multiple modules (if you work on a distro) or you can create a project inside a module for just that module. If you call omrs-run from a module without calling omrs-create-project first, omrs-run will call omrs-create-project anyway.
Ryan Crichton
Ok, I see. So if I am working on multiple modules I can use omrs-create-project outside of a module folder to create a blank OpenMRS instance where I can manually load in all the modules that I need?
Is there any way to automatically load in multiple modules?
Rafal Korytkowski
To achieve that go to the openmrs project folder and call "omrs-add-module -a .../relative/path/to/module". Repeat that command for all modules you want to add to your project. Note that there's a bug in this command such that the order of builds is wrong. Go to openmrs project pom.xml and reorder modules section so that the server is last.
Willa Mhawila
Rafal Korytkowski I am running omrs-create-project but all I get is a print of my system specifications as shown below. Nothing actually happens unless I am missing something.
Executing: /Applications/omrssdk-1.0.7/apache-maven/bin/mvn archetype:generate -s /Applications/omrssdk-1.0.7/apache-maven/conf/settings.xml -DinteractiveMode=false -DartifactId=openmrs-project -DgroupId=org.openmrs -Dversion=1.0.0 -v 1.9.7 -DarchetypeArtifactId=maven-archetype-openmrs-project -DarchetypeGroupId=org.openmrs.maven.archetypes -DarchetypeVersion=1.0.2 -Dpackage=org.openmrs
Apache Maven 3.1.0 (893ca28a1da9d5f51ac03827af98bb730128f9f2; 2013-06-27 22:15:32-0400)
Maven home: /Applications/omrssdk-1.0.7/apache-maven
Java version: 1.6.0_65, vendor: Apple Inc.
Java home: /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home
Default locale: en_US, platform encoding: MacRoman
OS name: "mac os x", version: "10.9.5", arch: "x86_64", family: "mac"
I decided to follow that with omrs-run command anyway and I end up getting an error at the end [See here].
Any help is highly appreciated.