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). The O3 Project Overview is also helpful.

Setup OpenMRS 3 With OpenMRS SDK

You can quickly set up an instance of OpenMRS 3 using the OpenMRS SDK. There are two ways to set up OpenMRS 3 with the SDK: using the O3 distribution or a custom distro.properties file.

Prerequisite

Before starting, make sure that:

1. You have installed:
   • Java (the current version of OpenMRS server requires Java 8) 
   • Maven 

Setup the O3 distribution with the SDK.

If you are running the SDK for the very first time, install it by opening your terminal and run the following command:

$ mvn org.openmrs.maven.plugins:openmrs-sdk-maven-plugin:setup-sdk

1) To set up a new backend server, run the following command:

$ mvn openmrs-sdk:setup

By default, the SDK will use the next version of OpenMRS SPA core. However, if you prefer to use a specific version, you can manually change it by following these steps:

• Identify the desired version number from the list of available versions. You can find the version list at https://www.npmjs.com/package/openmrs?activeTab=versions.
• In your command line or terminal, run the following command

$ mvn openmrs-sdk:setup -DappShellVersion={version}

To ignore 'peerDependencies' when building the frontend, you can use the following command:

$ mvn openmrs-sdk:setup -DignorePeerDependencies=true

By setting the 'ignorePeerDependencies' property to 'true', you can mitigate the following error:

Module not found: Error: Can't resolve '@openmrs/esm-react-utils' in '/tmp/openmrs-sdk-node11424498487737231975/npm-cache/_npx/9145365975c7e340/node_modules/@openmrs/esm-styleguide/src/error-state'

2) Assign a server ID to your server when prompted.

3) You will be presented with the following options. Select "O3 Distribution".

You can set up the following servers:
1) 2.x Distribution
2) Platform
3) O3 Distribution
Which one do you choose? [1/2/3]:

4) Choose the desired version of O3 when prompted. Enter the corresponding number:

You can deploy the following versions of O3:
1) Reference Application 3.0.0-SNAPSHOT
2) Reference Application 3.0.0-beta.8
3) Reference Application 3.0.0-beta.6
4) Reference Application 3.0.0-beta.2
5) Other...
Which one do you choose? [1/2/3/4/5]:

5) The SDK will install the necessary modules. Follow the prompts to configure the server port, database details, and Java version as required.

6) Once the setup is complete, you can run the OpenMRS 3 instance using the following command:

$ mvn openmrs-sdk:run -DserverId=serverName

7) Now that the OpenMRS server is up and running, you can access it through your web browser. The URL for the OpenMRS server is "localhost:{port}/openmrs" (default: "localhost:8080/openmrs").

8) When you visit the link, OpenMRS will start the initial setup process. After completing the setup, you will be redirected to the legacy login page.

9) To access the OpenMRS 3 UI, you can visit "localhost:{port}/openmrs/spa/" in your web browser.

10) To log in to OpenMRS, you can use the default username and password:

• Username: admin
• Password: Admin123

11) Feel free to explore the OpenMRS 3 interface and start using the features and functionalities of the system.

Set up the O3 with a custom distro.properties file (advanced users)

1) Create a distro.properties file that includes the necessary modules and configuration properties. You can find the module versions in the following links:

• Backend modules: distro.properties
• Module versions: pom.xml
• Frontend modules: spa-assemble-config.json
• SPA module: pom.xml
• Configuration versions: tags

2) our distro.properties file should follow this format:

name=Ref 3.x distro
version=3.0.0
war.openmrs=2.6.1-SNAPSHOT
config.referenceapplication-distro=3.0.0-SNAPSHOT
omod.addresshierarchy=2.15.1
omod.appointments=1.6.0
omod.appointments.groupId=org.bahmni.module
omod.attachments=3.0.0
omod.calculation=1.3.0
omod.cohort=3.4.0
omod.fhir2=1.9.0
omod.htmlwidgets=1.11.0
omod.idgen=4.10.0
omod.initializer=2.5.0
omod.legacyui=1.15.0
omod.metadatamapping=1.6.0
omod.metadatasharing=1.9.0
omod.openconceptlab=2.1.0
omod.ordertemplates=1.0.2-SNAPSHOT
omod.owa=1.14.0
omod.queue=1.0.0-alpha.1
omod.referencedemodata=2.4.0-SNAPSHOT
omod.reporting=1.25.0
omod.reportingrest=1.14.0
omod.serialization.xstream=0.2.16
omod.serialization.xstream.type=omod
omod.spa=1.0.10-SNAPSHOT
omod.webservices.rest=2.40.0-SNAPSHOT
spa.frontendModules.@openmrs/esm-active-visits-app=next
spa.frontendModules.@openmrs/esm-appointments-app=next
spa.frontendModules.@openmrs/esm-cohort-builder-app=next
spa.frontendModules.@openmrs/esm-devtools-app=next
spa.frontendModules.@openmrs/esm-dispensing-app=next
spa.frontendModules.@openmrs/esm-fast-data-entry-app=next
spa.frontendModules.@openmrs/esm-form-builder-app=next
spa.frontendModules.@openmrs/esm-form-entry-app=next
spa.frontendModules.@openmrs/esm-generic-patient-widgets-app=next
spa.frontendModules.@openmrs/esm-home-app=next
spa.frontendModules.@openmrs/esm-implementer-tools-app=next
spa.frontendModules.@openmrs/esm-login-app=next
spa.frontendModules.@openmrs/esm-offline-tools-app=next
spa.frontendModules.@openmrs/esm-openconceptlab-app=next
spa.frontendModules.@openmrs/esm-outpatient-app=next
spa.frontendModules.@openmrs/esm-patient-allergies-app=next
spa.frontendModules.@openmrs/esm-patient-appointments-app=next
spa.frontendModules.@openmrs/esm-patient-attachments-app=next
spa.frontendModules.@openmrs/esm-patient-banner-app=next
spa.frontendModules.@openmrs/esm-patient-biometrics-app=next
spa.frontendModules.@openmrs/esm-patient-chart-app=next
spa.frontendModules.@openmrs/esm-patient-conditions-app=next
spa.frontendModules.@openmrs/esm-patient-forms-app=next
spa.frontendModules.@openmrs/esm-patient-list-app=next
spa.frontendModules.@openmrs/esm-patient-medications-app=next
spa.frontendModules.@openmrs/esm-patient-notes-app=next
spa.frontendModules.@openmrs/esm-patient-programs-app=next
spa.frontendModules.@openmrs/esm-patient-registration-app=next
spa.frontendModules.@openmrs/esm-patient-search-app=next
spa.frontendModules.@openmrs/esm-patient-test-results-app=next
spa.frontendModules.@openmrs/esm-patient-vitals-app=next
spa.frontendModules.@openmrs/esm-primary-navigation-app=next

3) Run the following command, providing the path to your distro.properties file:

$ mvn openmrs-sdk:setup -Ddistro=distro.properties

Creating Docker Configuration for OpenMRS 3 Distribution Using the OpenMRS SDK

1) Open your terminal and run the following command

$ mvn openmrs-sdk:build-distro

2) When prompted to specify the build directory for generated files, press Enter to accept the default value 'docker', or enter a different directory name if desired.

Specify build directory for generated files (-Ddir, default: 'docker') (default: 'docker'): 

3) You will be presented with the following options. Select "O3 Distribution".

You can setup the following servers:
1) 2.x Distribution
2) O3 Distribution

4) Choose the desired version of O3 when prompted. Enter the corresponding number:

You can deploy the following versions of O3:
1) Reference Application 3.0.0-SNAPSHOT
2) Reference Application 3.0.0-beta.9
3) Reference Application 3.0.0-beta.8
4) Reference Application 3.0.0-beta.6
5) Reference Application 3.0.0-beta.2
6) Other...

Which one do you choose? [1/2/3/4/5/6]:

5) After the build process completes, open your terminal and navigate to the build directory you specified in step 2. Run the following command to start the O3 distribution using Docker Compose:

$ docker compose up

Part 1: Build and Deploy the OpenMRS 3 Frontend

Backend Pre-Requisites

If you don't yet have an OpenMRS backend set up, follow these instructions first. (Note: Recommended version numbers are shown here because systems based on recent OpenMRS platform versions (v2.4.0+) will be able to run these, and older versions of MySQL and Tomcat having been End-of-Lifed by their supporters.)

1. Install Java (v11)
2. Install MySQL (v8) - Create “openmrs” database, “openmrs” database user and grant privileges on the “openmrs” database to the “openmrs” user.
3. Install apache-tomcat-8.5 or 9 
4. Install nginx. Configure nginx to proxypass to tomcat.
5. Download the OpenMRS Platform war file and place it in tomcat’s webapps directory.
6. Start tomcat. Open a browser and navigate to the address configured in nginx. Follow the installation setup and get OpenMRS platform running.

if it’s for development or to build a distro, we’d still recommend using the SDK rather than doing everything by hand. For building a distro with the SDK, you’ll at least need to install Maven. If you want to build a distro without the SDK or setup the frontend, you’d need a recent version of Node. Only developers need Git. 
You can skip setting up nginx unless you’re actually deploying to production. It’s not a value-add to have it running locally.

Frontend Pre-Requisites

In order to successfully build the OpenMRS frontend, you will need to have appropriate versions of Node and NPM installed. The appropriate version will vary depending on the versions of frontend modules you are using, but the general rule of thumb is that the latest community-supported releases should support the active LTS version of NodeJS at the time of release. At the time of writing (June 2022), this is Node 16.15.1 and NPM 8.11.0. Newer versions of Node and NPM are likely to be supported, but substantially older versions will likely not work. Note that if you use the OpenMRS SDK option to build the frontend, an appropriate version of Node and NPM will be installed for you.

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 to the 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: Pick the esms you want

O3 Apps Directory: https://om.rs/o3apps

Before you clone or fork an O3 repo: What you should know 

Ask yourself a few questions: 

1. Are we willing and able to maintain this code for the forseeable future? Yes, it might be easier/faster to build it ourselves now, but do we want to be on the hook to maintain this ourselves in 1 year? 3 years? The repos that are part of the OpenMRS organization on GitHub - especially anything used by the O3 RefApp - benefit from support from OpenMRS Community members like volunteers, senior devs at aid organizations, contractors, and a small number of staff to maintain them. 
2. Have we searched the O3 App Directory and the OpenMRS Talk forum to check that someone else hasn't already built this idea? 

We especially advise against cloning/forking/customizing esm-core, because:

(1) esm-core is literally the core of the O3 product, and this would essentially fork yourself from the O3 product, and;

(2) We maintain esm-core through time from Senior Frontend engineers from all over the world - often with specialized expertise in microfrontends. This means the costs of forking and maintaining a forked version of core will be immense.

What should I do if I have feedback for esm-core or a specific feature/esm app?

We welcome feedback! (Note that as OpenMRS has extremely limited central resources, change requests are more likely to happen if you can also contribute some resources - many orgs working on O3 make their desired features happen by partnering with other groups and co-sharing resources (e.g. BA time, designer time, dev time, etc) - see live examples of this in the Care section of the Product Roadmap here, where the blue tags show you the orgs working together to make a feature happen.) 

Examples: How to share feedback & make change happen
1) Share & refine your idea on our O3 Calls and/or Forums Use any of these forums to share your idea. The more detail the better so folks can understand the reasons behind your interest/concern. Some folks use recorded videos eg via Loom.
O3 Squad Calls	Dev blockers, dev ideas/concerns. Meets on Zoom weekly every Thursday - see live Events calendar here for the latest time & call link.	Example:
O3 Product Design Calls	New feature ideas, wireframe sharing & mockup feedback, requirements discussions.  Meets on Zoom weekly every Monday - see live Events calendar here for the latest time & call link.	Example:
OpenMRS "Talk" Forum (Join Talk here)	We even track all O3-relevant topics by using the label "o3".	Example:
OpenMRS Slack (Join our Slack here)	Either the #openmrs3 or the #openmrs3-helpme channel. Easy way to start sharing an idea to gauge interest.   #ux-design-advisory	Example:
Github RFCs (for big changes with large impacts)	Once you have enough details on how you would technically like to implement an idea/change, you are also welcome t	Example:
2) Partner to get more done, together
Partner with another Organization using O3	Many orgs working on O3 make their desired features happen by partnering with other groups and co-sharing resources (e.g. BA time, designer time, dev time, etc). Benefits: Less people per org and faster time, more use in production, completeness of requirements, and shared future maintenance burden.	Example: See the Care section of the Product Roadmap here, where the blue tags show you the orgs working together to make a feature happen.

Step 6: 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 with openmrs-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"
    }
  }
}

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

HFE Form Support in O3

There are 3 possible approaches you could take: 
https://github.com/palladiumkenya/openmrs-module-afyastat/blob/1519b9e0b6a7d6b0ac8ac9e1cfe4cbab5c608aa8/README2.md#automation-of-html-to-json-schema-migration 

Configuring your Metadata

If you are making a one time setup of your metadata then 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 if you need to roll-out at many offline sites).

And if you need to update your metadata frequently then you can use OCL for metadata management and use OpenMRS Open Concept Lab module to import concepts using Subscription URL and token or direct import from file.

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? 

• Slack Help Community: You can contact the global community of O3 implementers for support in the OpenMRS slack channel called #openmrs3-helpme (if you do not already have an OpenMRS Slack account, sign up here first.)
• Daily O3 Troubleshooting: Every weekday we have a 30-min daily drop-in for help. Details: Mon-Thurs at 5pm UTC at this link our O3 dev leads host Community Coffee Chats to help with O3 Troubleshooting. GCal info here.