This documentation is intended to enable administrators, implementers, and developers to set up and configure an OpenMRS Frontend 3.0 application (aka 3.x, aka O3).

If you haven't seen the O3 Project Overview yet, do that first.

Part 1: Build and Deploy the OpenMRS 3 Frontend

Step 1: Choose your install / serve path

There are several ways to deploy the OpenMRS 3 Frontend, depending on your needs and technical capabilities. Here we will cover 2 options–deploying the frontend using Tomcat and the OpenMRS WAR or deploying the frontend using nginx: 

• Option 1: OpenMRS Server: Install using OpenMRS tooling + Apache Tomcat. In this case, you will build and assemble using the OpenMRS SDK and served from the OpenMRS server itself using the OpenMRS SPA Module. This is the simplest kind of deployment. Implementations with many Java-familiar team members, who know Tomcat inside and out, may strongly prefer this approach. This also simplifies your architecture as there is only one server involved.
  
  • Example distribution using this approach: Palladium
• Option 2: Web Server: Serve the frontend using nginx, Apache server etc. This approach enforces separation from the backend; the frontend runs completely independently. This ensures that your frontend will run regardless of whether the backend stops sucessfully, etc.Teams concerned about load balancing may prefer this approach. (Of course, if the backend fails, you won't be able to use the frontend client, but the separation between frontend and backend gives you a way to communicate tothe user that there is something wrong with the backend. Whereas for users using the OpenMRS server/Tomcat approach, their system might be entirely inaccessible.) 
  • Example distribution using this approach: AMPATH

Step 2: Add Essential Modules

The following modules are essential to run the O3 frontend (note: if these modules are new to you, just install the latest version of each).

1. FHIR2 Module (1.2.2+)
2. REST Module (2.24.0+)
3. SPA Module (1.0.8+) (only required if you want to serve from Tomcat; not needed for the nginx approach)
4. ID Gen (4.6.0+)

These are the key to communication with your existing OpenMRS backend. Add these modules to your environment (i.e. your existing implementation). 

Step 4: Check your backend dependencies using the O3 Implementer Tools

1. Go to your O3 environment and sign-in as a system administrator.
2. Click the Implementer Tools icon to open the implementer tools (only visible to Admin users).  
3. Click the tab called Backend Modules
4. Scroll through the list to see the Required Version of your modules to adequately support your O3 interface. 

Step 5: Celebrate!

We'd love to hear from you if you successfully set up O3. Please share your success with us by posting on talk.openmrs.org that you were successful. And if you ran into any issues, please share those, and feel free to update this documentation!

Example Distribution

To create an example distribution using the OpenMRS 3.0 SPA as frontend you'll need to think of three things:

1. The app shell (namely what settings you'll need to include it)
2. What frontend modules to include (their names and versions)
3. The configuration for these frontend modules

The parts of (2) and (3) also flow in directly or indirectly into the settings defined for (1).

Let's start with (1):

  npx openmrs build --spa-path /openmrs/spa/ --api-url /openmrs/ --config-url config.json --importmap importmap.json

Using this command you'll build a new app shell that will be placed at /openmrs/spa/. The OpenMRS API is supposed to be on the same server (at least reachable from the browser) at /openmrs/ (e.g., a call to /openmrs/ws/rest/v1/session yields the session, so /ws is rooted at /openmrs).

The command above also defines two more things: The frontend modules from (3) are determined by an importmap.json which will be available in the same directory as the SPA (i.e., reachable at /openmrs/spa/ from the browser). Likewise, a configuration file is specified; the file config.json will be loaded from the SPA's path, too.

Now that you'll have your files for the app shell its time to look at how to get the remaining ones.

The frontend modules from (2) can be assembled using:

  npx openmrs assemble --mode survey

This will run a command-line survey iterating over all (publicly) available frontend modules. If included, the survey will ask you what version to take.

Once completed, you'll have a valid importmap.json as well as a directory with all files corresponding to the different frontend modules referenced in this importmap.json.

Finally, you'll also need a configuration. Ideally, you can just write some JSON that represents such a configuration, however, in the real world this will not be so easy.

Our recommended approach is to actually start with an empty JSON file just containing {}. With this empty configuration you can fire up your application shell and actually set it all up as you want to. The frontend module @openmrs/esm-implementer-tools-app will help you to do exactly that.

When you completed your customization in the frontend you can download your individual config.json. Now you can put it besides all the other files to complete your own distribution.

Known Issues

• FHIR and FHIR2 clash on older Platform versions (2.0-2.3.x): Platform versions 2.0.0-2.3.x came with the old FHIR module (v1) pre-bundled. FHIR2 wasn’t bundled until Platform 2.4. Adding the new FHIR2 OMOD while using one of these older platform versions conflicts with the bundled v1 FHIR module. If your Platform version is still running the original FHIR module,remove that module and install the FHIR2 module. Talk Thread for more details and questions here. 
• Cohort Module version <=3.0.0-SNAPSHOT can break the application when deployed withopenmrs-module-emrapi: There is a fix for the Cohort Module that fixes this. See this talk thread for details. 
• SQL issues when using the Initializer module: Apparently these can begin to challenge each other. More information to come. We suspect the initializer module and other modules that insert data needs to update/insert instead of just inserting data.
• npx openmrs build fails on npx version 8.*.?. Current working build uses npx version 6.14.15, node v16.13.0
• FHIR module liquibase error on 1.3.0 - Deploying v1.2.1 and then updating sequentially to 1.3.0 should run migrations needed and solve the issue.
• See Also: O3 Dev Docs FAQs o3-dev.docs.openmrs.org/#/main/faq

Part 2: Configure Your O3 Application

What an OpenMRS 3 frontend configuration file looks like

OpenMRS 3 frontend configuration files are JSON files containing module names as top-level elements. All configuration elements are optional. The available configuration elements for each module should be documented in the module’s wiki page or README file.

Here’s an example:

{
  "@openmrs/esm-login-app": {
    "logo": {
      "src": "https://pbs.twimg.com/media/C1w_czvWgAAWONL.jpg"
    }
  },
  "@openmrs/esm-home-app": {
    "buttons": {
      "enabled": false
    }
  }
}

Alternatively you can provide your config file as a JavaScript file. It will look just about the same, but with some magic words at the beginning:

exports = {};
exports.default = {
  "@openmrs/esm-login-app": {
    logo: {
      src: "https://pbs.twimg.com/media/C1w_czvWgAAWONL.jpg"
    }
  },
  "@openmrs/esm-home-app": {
    buttons: {
      enabled: false
    }
  }
}

How to configure your OpenMRS 3 implementation

You can pass  --config-url  parameters to the build tool  npx openmrs build.

The following command will build an application that looks for config files at the URLs  /openmrs/spa/abc/config.json  and  https://example.com/config.json :

 npx openmrs build --config-url abc/config.json --config-url https://example.com/config.json

Config files will be merged, with values from subsequent files overriding those coming previously. For example, if  abc/config.json  has contents

{
  "@openmrs/esm-login-app": {
    "logo": {
      "src": "https://pbs.twimg.com/media/C1w_czvWgAAWONL.jpg",
      "alt": "Our beautiful logo"
    }
  }
}

and  https://example.com/config.json  has contents

{
  "@openmrs/esm-login-app": {
    "logo": {
      "alt": "Our all-star logo"
    }
  }
}

Then the login page will display the logo given by the first config and the alt text given by the second config.

In this way, you can break up your configuration files into hierarchies, per module, per groups of modules, or however else you please.

See  npx openmrs build --help .

Configure the Layout of a Chart Page

Coming Soon

Part 3: More Advanced Configuration

Configuring O3 Forms

Configuring your Metadata

We highly recommend using Initializer to set up your config. Example 3.x RefApp Configuration folders that are consumed by Initializer can be found here. 

Step-by-step documentation on setting up sites with OCL-created concepts via Iniz is here (this is especially helpful is you need to roll-out at many offline sites).

Configure the Lab Filter feature

The Lab Filter feature enables you to set up custom filter views - eg based on standard medical hierarchies, or even based on your own custom ideas (e.g. "Our Favorite HIV-Related Tests"), like this:

To set up your own preferred Filters and Test Hierarchies, follow the steps in the esm-patient-test-results-app README here. 

Add full feature sets with OMRS Packages

Packages will be added through a build step, e.g., by running the SDK’s build-distro command. This functionality is yet to be built. More detail coming soon. 

Questions?