OpenMRS has always had a web application component however, the web application focused primarily on basic administrative features and lacked most content, leaving it up to modules and administrators to provide EMR functionality and content. OpenMRS 2.x is our new major release line with a new vision: to provide a starter set of content along with basic EMR workflows (e.g., registration, basic reports, etc.). OpenMRS 2.x is built on top of a mix of pre-existing OpenMRS modules, and new ones, and the distribution includes the legacy OpenMRS user interface, alongside a new user interface, written from scratch and aimed at point-of-care use. Thus existing modules and forms can still be accessible in OpenMRS 2.x, until they can be rewritten in the new user interface.
Motivation to build the reference application was due to the work done for the Mirebalais project and we continued with that momentum to develop and release OpenMRS 2.0. It is still early in the maturity of the OpenMRS 2.x line, and you'll surely find occasional Mirebalais references, and hacky ways that code is split across projects.
Developing for OpenMRS 2.x is different from developing for the 1.x application in several ways:
- Development is expected to be done via modules
- We are using the a custom UI framework which involves usage of of spring controllers but used a little differently and groovy server pages(GSPs) as the view technology, for more about the framework and using it see UI Framework, this is intended to make development easier, faster and more fun.
- as mentioned above, we support controller-free HTML + JS + REST approaches as well
- Development is strongly CI driven, if any anything gets broken on our bamboo server, fixing the build becomes the top priority.
- We use Compass and Sass to build our CSS
The basis of OpenMRS 2.x (and the reason we're able to let new UI Framework-based modules and new HTML+JS+REST-based modules live alongside the classic UI) is the App Framework, which introduces the concept of Apps and Extensions, allowing us to build smaller independent pieces of functionality, and loosely couple them.
You should use an IDE to do OpenMRS EMR development. There are core OpenMRS developers who use both IntelliJ and Eclipse.
Please do not commit any IDE-specific files to the source code repository. If you are creating a new OpenMRS 2.x module, or you are the first to work on a module with your particular IDE, please modify the .gitignore file as appropriate (e.g. ignore *.iml and *.idea)
We suggest that you create an "OpenMRS Reference Application" Project and you import OpenMRS core, as well as any OpenMRS modules you will be working on (including new ones you create) as IntelliJ "Modules" in that Project.
We suggest using git at the command line to clone modules from github and then using "Import Modules" to add them into your IntelliJ project.
We suggest that you clone OpenMRS core and modules with git at the command line and import them into Eclipse with the m2e plugin. If you do not know how to work with Eclipse see Getting Started as a Developer for specific instructions.
Contributing code to the core and modules
If you expect to contribute any bug fixes to OpenMRS core and the modules, follow the fork + pull-request git workflow at Using Git
OpenMRS 2.x is generally released on top of the latest stable release of the OpenMRS Platform at the time of its release (e.g. OpenMRS 2.1 was distributed with OpenMRS Platform 1.10.0, and OpenMRS 2.2 is distributed with OpenMRS Platform 1.11.2), but individual modules that make up the OpenMRS 2.x application generally are designed to require lower versions of openmrs-core (and an inspired implementation can mix and match them on top of a potentially-lower version of the OpenMRS Platform).
When working on OpenMRS 2.x you generallyshouldmake bugfixes to openmrs-core for any issues you discover, but you should implement any new features in modules (since new features since are not typically backported to the already-released lines).
You need to check out openmrs-core so that you can run OpenMRS under jetty. This is documented elsewhere on the wiki. We recommend that you make your own fork of the main repository, so that you can submit bugfixes as pull requests.
After cloning the git repository check out the branch that the current OpenMRS 2.x build is based on (e.g. at time of writing this is the 1.11.x branch, => "git checkout -b 1.11.x origin/1.11.x"). To verify this is still the right branch to check out, look at https://github.com/openmrs/openmrs-distro-referenceapplication/blob/master/pom.xml, look at the value of the openMRSVersion property, and get the release branch associated with that property value (e.g. <openMRSVersion>1.11.3</openMRSVersion> => branch 1.11.x).
In order to be able to run openmrs-core you need to install a SQL database, most commonly MySQL.
To run OpenMRS, use the "mvn jetty:run" goal in the webapp module of openmrs-core.
In eclipse you can set this up as a Run Configuration like:
- Goals: jetty:run
Set the following VM options to use our preferred webapp name, give OpenMRS sufficient memory, and enable rapid UI development (replacing with correct pointers to the source code you have checked out):
(See the Development Mode section of Using the UI Framework in Your Module for an explanation of the uiFramework.development setting.)
First-time setup wizard: No demo data
When you go through the OpenMRS first-time setup wizard the first time you run the OpenMRS webapp, make sure you choose not to install demo data.
Building and running the reference application
Most development work on OpenMRS 2.x can be done without needing to check out all the code for all modules in the distribution. You should be able to implement new features by working on the specific module that includes the app in question, or by creating a module with new functionality. To run the reference application, you need compiled versions of all modules in the distribution.
Building the latest distribution
After checking out OpenMRS core, you should check out the OpenMRS Reference Application distribution at https://github.com/openmrs/openmrs-distro-referenceapplication. Running "mvn clean install" in this project will assemble the modules that make up the latest version of OpenMRS 2.x.
You probably want to create a script to run this maven goal, and then copy the assembled modules into your OpenMRS modules folder. For example you might put the following in the root of the openmrs-distro-referenceapplication folder.
Running the above script from the root of the distro project and then re-running openmrs-core's jetty:run target will run the latest version of OpenMRS 2.x.
Running OpenMRS 2.x in a production-like environment.
The target environment for CI, and other servers is Tomcat7 running on Ubuntu 12.04. If you'd like create a virtual machine in your environment for testing, see the wiki page: Developer How-To Launch a Local Instance of the Reference Application.
Typically our CI setup will constantly be building the latest versions of the above modules. The only way to be sure you have the equivalent build yourself is to update and build all of these modules regularly.
Writing your own module on top of OpenMRS 2.x
You may write new OpenMRS 2.x functionality by creating your own module, without needing to make any modifications to the existing codebase.
- If you intend for your module to be shared with the broader community, you should require the lowest feasible supported version of openmrs-core given the functionality you need to create. If you are building a module just for your implementation, your module should require the version of openmrs-core being used at the implementation.
- If you intend to host the module project on github, you will need to create a repo for it on github as described at Creating a github repo.
To share your code on github, from the command line, go to the module project directory and run the git commands below:
Remember to exclude any IDE specific files
It is a json descriptor file that you have to add to omod/resources/apps directory in your module, as shown in the example below:
The file name MUST end with '_app.json' to be able to be picked up by the framework.
Meaning of the properties: (*=required)
id*: The application wide unique extension id, it is recommended that it starts with the module namespace e.g org.openmrs.module.moduleId.myExtId
extensionPointId*: The id of the extension point to attach to
label: A message code for the short text to display below the icon
icon: The icon to use for the app
order: Determines the order in which the app appears, apps with lower order numbers get to be displayed first while those with higher ones come last on the home page
requiredPrivilege: The privilege the logged in user must have to be able to view the app
See an example of how this is set up by looking at an existing OpenMRS 2.x module, for example the reportingui module. (See everything that mentions ruby, sass, or compass in pom.xml and omod/pom.xml.)
- Every time you do a maven build (in the process-resources phase), the contents of omod/src/main/compass/sass will be compiled into omod/src/main/resources/styles (so they can be picked up by the UI Framework)
If you are doing active CSS development, and want these files compiled every time you change them, do this from the omod folder:
Developing the core of the OpenMRS 2.x
If you are a core developer, you will most likely need to clone the following modules:
- EMR API
- UI Commons
- App UI
- Core Apps
- Reference Application
All modules can be built by running mvn clean install. If some module is not building for you, please check its status in our CI. If it is green, then it means that it is only your local problem and you need to resolve it yourself. If you need assistance, please contact us.
We are using Bamboo, running at https://ci.openmrs.org. Automated tests are run against http://devtest01.openmrs.org:8080/openmrs and you may do manual testing against http://devtest02.openmrs.org:8080/openmrs. The scripts that deploy to these servers are run after every commit, we encourage devs to look at the CI server a couple of minutes after they commit their code to ensure no plans are broken as a result of their commit. (Failures are emailed to the email@example.com mailing list and reported by OpenMRSBot on our IRC channel.) After completing significant functionality, you should manually verify that it works there. Note that deployment to devtest02 only happens if the ui tests are run successfully against devtest01.