Open Web App Development Workflow

This page will briefly discuss the development workflow for developing Open Web Apps. For a description of what Open Web Apps are, see the wiki page. Much of this document is derived from the Developing an HTML+JS Open Web App Quickly wiki page.

1. Setup OpenMRS

In order to develop Open Web Apps, you will need an OpenMRS server running locally. The ways to do this are described below.

Standalone

The quickest and easiest way to set up a server locally is to download the latest standalone server from the OpenMRS downloads page. You will need Java 1.7+ to run the standalone server. Once it's downloaded, extract the ZIP archive and run the jar file either by double clicking it or executing the following command:

Run the OpenMRS standalone server

The first time you run the server you will be asked if you want to insert dummy data into the system. This is recommended if you want some data to play with.

SDK

Another easy way to run an OpenMRS server is to use the OpenMRS SDK. To use this method you must have MySQL 5.6, Java 1.7+ and Maven 3+ installed. Newer versions of MySQL, even with compatibility options, will not work. To install and configure the OpenMRS SDK, run the following:

Install the OpenMRS SDK

To create a new OpenMRS Platform server, run the following:

Create a Platform Server

Finally, navigate to the server directory (probably ~/openmrs/platform) and run:

Run a Platform Server with the SDK

It is also possible to run a Reference Application server using the SDK. See the SDK docs for instructions on how to do this.

Enterprise

The enterprise install is usually meant for production environments, and involves installing MySQL and Tomcat manually, then downloading the OpenMRS Platform WAR file from the OpenMRS downloads page and deploying it to Tomcat. See the full documentation here.

Docker

To set up and instance of the OpenMRS Platform using Docker, follow the instructions in the README file in this repository. To support rapid local deploys, you'll need to make the following change to your docker-compose.yml file:

Support Local Deploys to Docker

This will create an owadata directory at /host/location/of/ on your Docker host and map that to the Open Web Apps data directory in the container. Once you've scaffolded your app (see section #3 below), edit the LOCAL_OWA_FOLDER variable in gulpfile.js to point to this directory in order to support local deploys.

2. Install the Open Web Apps module

This is described on the Open Web Apps Module page. It's the same as installing any other other module

3. Scaffold Your Open Web App

A boilerplate Open Web App along can be scaffolded using the Yeoman OpenMRS OWA generator. You will need NodeJS 6+ installed to do this. See the install instructions here.

Once you have NodeJS installed, you need to install Yeoman, as follows: 

Install OWA Generator Dependencies

You can then install the generator:

Install OWA Generator

Next, create a directory for your Open Web App and change into it. Then run the following to scaffold your app:

Scaffold Open Web App

This will start up the Yeoman generator. The output should be something like:

Open

Follow the options in the Yeoman generator in order to scaffold the app. Depending on your setup options it might look something like this when you are done: 

Open

Ensure that the APP_ENTRY_POINT inside webpack.config.js is set to the proper location of your OWA's index.html. Congratulations, you have successfully scaffolded your app!

AngularJS Dependency Changes

It's possible that you can encounter TypeErrors if your OWA is using Angular 1.x. Inside package.json in the OWA's root folder, remove the ^ before the version number of each dependency related to Angular. Run npm install afterwards to install the correct versions of those dependencies. See here for more information. 

You may also have to remove the following snippet found inside home.js if you are still encountering issues:

Dependency code snippet

4. Development

All the Open Web App files are in the app directory, everything else is used for building and managing packages. Any files you add manually must be added in the app directory.

The app/manifest.webapp files contains the information that OpenMRS needs to host your app. See the Open Web Apps Module documentation for details. The launch_path property contains the path to your app entry point. This is the page that will be loaded when you click on your app in OpenMRS.

General Tips

If you're building your OWA with Angular, all code should be inside components and designed in a modular manner. This will help facilitate an upcoming migration to a more recent version of Angular. 

If you're building your OWA with React, please refer to and follow the style guide. There are also React Components available for use.

For the latest information on which technologies to use, check the OpenMRS Radar which is updated quarterly. 

Building The App

To build and package your app in a distributable file, use npm Webpack.  

Scaffold Open Web App

This creates a zip file in the app directory. You can then upload this to an OpenMRS implementation using the Open Web Apps Module.

Local Deployment

To speed up the development workflow, we can deploy directly to the app data directory on the filesystem, again using using npm Webpack:

Scaffold Open Web App

 The app should now show up in your OpenMRS implementation (Administration -> Open Web Apps Module -> Manage Apps) and will look something like this: 

If you have issues using Webpack to deploy the app, ensure that the deploy directory is correct. Open the config.json file in the apps directory and make sure that LOCAL_OWA_FOLDER points to the correct directory. For example: 

^{{
"LOCAL_OWA_FOLDER": "/Users/username/openmrs-standalone-2.5/appdata/owa",
}}

Using Browsersync

npm can use Browsersync to watch the files as you development and dynamically reload the app as you make changes to the code. Each time you save a file in the app's directory, the app will reload and display in the browser. This is an extremely useful tool. To use browsersync run the following command in your app's directory: 

Build App

If you have issues getting browsersync to work, ensure that the app is being injected. Open the config.json file in the app directory and make sure that APP_ENTRY_POINT points to the correct path. Your config.json file should look 

^{{
"LOCAL_OWA_FOLDER": "/Users/username/openmrs-standalone-2.5/appdata/owa",
"APP_ENTRY_POINT": "http://localhost:8081/openmrs-standalone/owa/appList/index.html"
}}

5. Add Home Screen Link

Since you've built a standalone app, you want to let people access it from the OpenMRS home screen. In the Standalone or the Reference Application, you can do this by going to System Administration -> Manage Apps -> Add App Definition and then adding a definition like:

Home Page Link Config

You can see the available icons at http://demo.openmrs.org/openmrs/uicommons/icons.page.

For more details about Adding Icon to Reference Application Homepage, just visit Adding OWA Icon to the Reference ApplicationHomepage

Resources

• Open Web Apps Module
  
  

• Developing an HTML+JS Open Web App Quickly
  
  

• Screencast - OpenMRS OWA Web Apps Development Workflow (this screencast is excellent, but references an older workflow using bower and gulp, which have been dropped from the workflow)

• Screencast - OpenMRS Open Web App (OWA) Development Tutorial (this screencast is consistent with newer workflow)

• Release Open Web Application