How to create your First OWA in OpenMRS

I am developing some Open Web Apps(OWA) for OpenMRS through Google Summer of code. I started with some documentations and prepared some demo OWA for the project. I briefly explained the development process here,

What is Open Web App?

Open Web apps are no different than standard websites or Web pages. OWA front-end will be developed using HTML, CSS, and JS(Angular or React) and those functionalities will be developed using REST API. You can manually run your OWA and get Output through your screens. (For OpenMRS, you want to use OpenMRS REST API which is available as a module)

So initially you want to need some knowledge about these following components to develop the OWA. Don’t Worry… ! you can learn those step by step.

  1. Experience with HTML and CSS
  2. Knowledge about Angular 1 or React JS

You want to install OpenMRS reference application and Open Web App module to run the OWA through the OpenMRS.

Follow this tutorial to setup your environment with OpenMRS reference application. After the configuration, You are able to run your reference application.

OpenMRS Reference application Login Screen

After the configuration, you can able to find out the Open Web app module under the Module management. If you haven’t installed this module, then you can download it from here, and manually upload to the Open MRS using Manage module.

Installed Open Web Apps Module(Current version 1.7)

Now we are ready to develop the Open Web App for the OpenMRS. Follow this steps to create your First OWA.

Install Yeoman generator for OpenMRS Open Web Apps

It will provide the basic OWA folder structure and files using a single command for creation. These packages are managed with npm commands. To install Yeoman generator in your environment, Follow this steps,

Open your Shell or Command prompt and type “npm install — global yo” to install the required dependencies for the yeoman

Make sure that your environment is configured with npm(Neutral Process Mechanism).
Installation progress of the Yeoman dependencies.

Install the OWA generator using “npm install — global generator-openmrs-owa” command.

Installation progress of the Yeoman OpenMRS Open web app generator

Create OWA Project using Yeoman OWA generator

After the configuration, Now you can create your first application using Yeoman Generator. Make sure, you can change your CMD/Shell directory to the NewFolder and then yo openmrs-owa” to create the new OWA project.

It will launch the OpenMRS Open Web app generator and It will ask you some important configuration details and information to create your project. That are,

a. App Name : Enter your OWA name which will represent your OWA in all 
times.
b. App Description : Enter a little bit description about your OWA and it will represent your app in the Module directory.
c. Libraries : Here you can select jQuery, Angular (version 1), and React for your development. Make sure to use your Keyboard up and down buttons or 1– 4 numbers in your keypad to select the Libraries.
d. Server Type : Select your running server type of OpenMRS.
e. GitHub username : It will represent you as the creator of this OWA in the project.
Project creation using Yeoman Open Web app creator

If you completed all the process through the Yeoman Open web app generator, then you can find out your Project in your directory.

Project Structure of the Open Web App which was created through the Yeoman

There will be some dependencies which are connected to the OWA and you can navigate the app folder to view your OWA structure. Here CSS folder will contain all the style information about your OWA, img folder will contain the images which are connected to your OWA, JS folder will contain all the Javascript files and manifest.webapp will contain all the information and configuration details about your OWA app.

Inside the app folder in your OWA project.

Finally, you want to build your OWA project and upload to the OpenMRS Open web app module to run. You can use npm run build:prod command to zip your OWA project. Initially, this command will build your OWA project and then make it as a ZIP file including related files.

The Project has been zipped using “npm run build:prod” command

You can see some files are included inside that ZIP file and all the formats will be changed due to the build command. Here, It creates one CSS file will all related CSS information and one JS file with all related JavaScript information and functions. There are some other files which represent the OWA and required materials.

File Structure inside the OWA ZIP file

Upload to the OpenMRS Open Web App Module

Now you can upload your zipped OWA into OpenMRS Open Web Apps modules to run the app. you can simply upload your OWA using browse button under the Upload App Package.

Upload App package section under the Manage Open Web Apps module
First Login to the OpenMRS and go to System Administration then go to Advanced Administration and then Click Manage apps under Open Web Apps.

Now you can see the list of uploaded OWAs in the Manage Apps sections. Simple click on an OWA to run it through your browser.

List of OWA in the Manage Apps section

Finally you will get your output through your browser…! Yah, your OWA is working successfully.


But you want to develop some more to get this following output as your DemoOWA. I will describe this parts in my another post.

Sample OWA developed using Angular 1

Reference

  1. https://www.npmjs.com/package/generator-openmrs-owa
  2. https://wiki.openmrs.org/display/docs/Open+Web+Apps+Module