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. The Reference Application, on the other hand, strives to provide more of a starter set of content along with basic EMR functionality (e.g., registration, basic reports, etc.). The web application framework upon which the Reference Application is based comprises a handful of new modules that run within the existing web application and provide a new, Spring and Groovy-based framework for more agile web development. The pages that have been overriden in the reference application at the time of writing this are the home and login pages.
Motivation to build the reference application was due to the work done for the Mirebalais project so we wanted to continue with that momentum to develop the reference application. Reference application development is different in the follow 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.
- 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
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 Reference Application 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 EMR" 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.
The Reference Application is built on top of the latest release like of the OpenMRS core codebase (currently 1.9.x).
We will expect to make bugfixes to the OpenMRS core as we work on the Reference Application, but we may not add new features to core, since those are not backported to the already-released lines.
You need to check out OpenMRS 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 1.9.x branch (e.g. "git checkout -b 1.9.x origin/1.9.x")
In order to be able to run OpenMRS core you need to install MySQL.
Building the distro
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):
Running the Reference Application 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.
Most development work on the reference application can be done without needing to check out all the code for all modules in the application. You should be able to implement new features by working on the specific module that includes the app in question.
To run the reference application, you need compiled versions of all modules in the reference application distro. To get these, you need to clone https://github.com/openmrs/openmrs-distro-referenceapplication and run mvn clean package. This command will produce a zip file with omods in the target directory which you can unzip into the module directory in your Application Data directory (skip the war file). You need to restart OpenMRS to have all the modules installed and started.
If you want to get code of some modules you need to fork them and clone. Here's a partial list of modules included in the Reference Application:
|Why download the code?|
|(Uncommon) Changes to the App framework|
|(Very rare) Changes to underlying GSP-based framework.|
|UI Commons||https://github.com/openmrs/openmrs-module-uicommons||(Common for UX people, uncommon for devs) Changes to the shared OpenMRS style guide|
|EMR API||https://github.com/openmrs/openmrs-module-emrapi||Shared APIs related to building a real-time EMR (e.g. ADT, Visits, Diagnoses, MRNs)|
|Changes to global navigation (e.g. "standardEmrPage" and "header")|
|Core Apps||https://github.com/openmrs/openmrs-module-coreapps||Common apps like "Patient Dashboard" and "Find Patient"|
|Registration App||https://github.com/openmrs/openmrs-module-registrationapp||UI for the registration app (the API is in registrationcore)|
|Registration Core||https://github.com/openmrs/openmrs-module-registrationcore||https://tickets.openmrs.org/browse/RC||API for registering patients (the UI is in registrationapp)|
(TODO: Continually update this list of modules.)
If you are a core developer, you will most likely need to clone the following modules:
- App Framework
- UI Commons
- App UI
- Core Apps
- Reference Application
- EMR API
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.
Contributing code to the core 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
Maven versions plugin
Use the following command to update the pom.xml for the openmrs-distro-referenceapplication repository if you need to have the latest versions of all the modules included in the Reference Application.
If you'd like to push this change to the master branch in GitHub, please discuss the changes on the firstname.lastname@example.org mailing list before pushing.
For more info on GIT see Using Git.
- 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:
mvn process-resources -Pwatch-sass
We are using Bamboo, running at https://ci-stg.openmrs.org. We have 2 servers one at http://devtest01.openmrs.org:8080/openmrs/login.htm which the UI tests are run against and then http://devtest02.openmrs.org:8080/openmrs/ where you can go to test the latest builds, 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. 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
Remember to exclude any IDE specific files