Open Web Apps Module

A packaged app is an Open Web App that has all of its resources (HTML, CSS, JavaScript, app manifest, and so on) contained in a zip file. This module allows uploading Open Web Apps (OWA) to OpenMRS using the user-interface at runtime. A packaged app is a ZIP file with an app manifest in its root directory. The manifest must be named manifest.webapp. The Mozilla page on apps provides a detailed description.

Purpose of packaged apps

The purpose of packaged apps is to create custom UI on-top of OpenMRS REST API. An OpenMRS implementation will often have unique requirements. Apps provide a convenient way to customize the user interface and lowers the barrier to programmer entry, by allowing choice of any web technologies. Apps do not have permissions to interact directly with the OpenMRS Java API. Instead, apps are expected to use functionality and interact with OpenMRS REST Web Services.

Creating apps

Apps are constructed with HTML, JavaScript and CSS files. Although these can also be in Python, PHP, ASP etc., but such app deployment scenario will be described later. Apps need a special file called manifest.webapp which describes the contents of the app. This file should be in the format specified by the W3C Manifest for Web Applications. A basic example of the manifest.webapp is shown below:

basic manifest.webapp

{
    "version": "0.1",
    "name": "My App",
    "description": "My App is a Packaged App",
    "launch_path": "index.html",
    "icons": {
        "16": "img/icons/mortar-16.png",
        "48": "img/icons/mortar-48.png",
        "128": "img/icons/mortar-128.png"
    },
    "developer": {
        "name": "Me",
        "url": "http://me.com"
    },
    "default_locale": "en",
    "activities": {
        "openmrs": {
            "href": "*"
        }
    }
}

The manifest.webapp file must be located at the root of the project. Among the properties, the icons->48 property is used for the icon that is displayed on the list of apps installed in OpenMRS. The activities property is an openmrs-specific extension meant to differentiate between a standard Open Web App and apps that can be installed on OpenMRS. The * value for href is converted to the appropriate URL when the app is uploaded and installed in OpenMRS. This value can then be used by the application's JavaScript and HTML files to make calls to the OpenMRS REST Web Services API and identify the correct location of OpenMRS server on which the app is installed. e.g. once the above app is installed on the OpenMRS demo server, its activities section will get changed as below:

activities section manifest.webapp

"activities": {
    "openmrs": {
        "href": "https://demo.openmrs.org/openmrs"
    }
 }

To read the JSON structure into Javascript, you can use a regular AJAX request and parse the JSON into an object. Most Javascript libraries provide some support, for instance with jQuery it can be done like this:

get OpenMRS server JQuery example

$.getJSON( "manifest.webapp", function( json ) {
    var apiBaseUrl = json.activities.openmrs.href + "/ws/rest/v1";
} );

The app can contain HTML, Javascript, CSS, images and other files whic may be required to support it. The file structure could look something like this:

OWA folder structure

/
/manifest.webapp    #manifest file (mandatory)
/css/               #css stylesheets (optional)
/img/               #images (optional)
/js/                #javascripts (optional)

Note that it is only the manifest.webapp file which must be placed in the root. It is upto the developer to organize CSS, images and Javascript files inside the app as needed. All the files in the project should be compressed into a standard zip archive. Note that the manifest.webapp file must be located on the root of the zip archive (do not include a parent directory in the archive). The zip archive can then be uploaded into OpenMRS.

Creating apps in PHP/ASP/Python or another webserver (hacky/whacky method)

The OWA module allows you to configure the location where your apps get installed on the server (owa.appFolderPath global property). It also allows you to set the base URL (owa.appBaseUrl) where the apps can be accessible from. This means that if you configure your owa.appFolderPath on www folder of apache2, then it gets deployed onto Apache2 instead of your OpenMRS tomcat or another servlet container. If you can configure a reverse proxy nginx/apache2 nicely, users will assume its a normal app that is actually served from apache/nginx or what server have you.

Configuring the OWA module after installation

The module requires the following global properties to be set before it can be used. All of these properties are mandatory and have default values. When user deploy Open Web Apps module

App Base URL:

What this does: This is the default base URL for OWA apps.

Example: If you have installed app called ‘OWA Commons Angular’ which starts with index.html page, then app’s URL will be <App Base URL specified in settings>/Owa-Commons-Angular/index.html

How you should enter it: Complete relative path like ‘scheme://host:port/path‘ or /path

Example: http://localhost:8080/openmrs/owa or /openmrs/owa

App Folder Path:

What this does: This property specifies the default location where the apps are stored on the disk. After uploading an App, if user want to make some real time changes in app (JavaScript or HTML) then user can make changes in the same folder which is specified in this property and reload the ‘Manage Apps’ page or reload app’s index page to view changes. There is no need to deploy app again.

How you should enter it: folder path

App Store URL:

What this does: This is the default URL for the OpenMRS appstore. This will be used in future release to download apps already present in above appstore.

How you should enter it: ‘scheme://host:port/path‘

Downloads

https://addons.openmrs.org/#/show/org.openmrs.module.open-web-apps-module

Basic app: https://github.com/namratanehete/owabasicapp

Screenshots

Upload module:

Add Open Web Apps module by downloading .omod file from the link provided in downloads section.

View Module:

To manage apps(Upload/delete), Go to “Administration --> Manage Apps”.

Manage Apps page:

Upload App:

To upload new app, click “Browse” button and select zip file of an app.

Click “Upload” button. You can view newly uploaded app in ‘Manage Apps’ section.

Open App:

To open an app, click on name of the app.

Delete App:

To delete an app, Click delete icon of the desired app. Prompt will be asked to confirm app deletion. Click “OK” to delete an app. App will be deleted and you can no longer see app in "Manage Apps" section. or press “Cancel” to cancel deletion of app.

Change settings:

To change settings of Apps, Go to “Administration --> Settings (User Open Web Apps Module). Or if user is already in “Manage Apps” page, then click “Settings” link present on top left corner near “Manage Apps” link. Make changes in settings and click “Save” button.