2019-11-13: OpenMRS University: OpenMRS Dev Set up for FHIR Module and Microfrontends

Dear community,

This week’s OpenMRS University brings together the work of the Microfrontends Squad and the FHIR Squad.

Have you wanted to:

  • Gain a birds-eye view understanding of the OpenMRS reference application architecture?
  • Understand how the FHIR Module is integrated into the RefApp distribution?
  • Understand how the MF project integrates into the OpenMRS distribution?
  • Set up a local dev environment for working on the FHIR module using the OpenMRS SDK?
  • Set up a local dev environment for MF ESM modules?

If so, this is the OpenMRS University session for you!

Please join us this Wednesday, 13 November 2019 at 7:30pm IST | 5pm Nairobi | 4pm Cape Town | 2pm UTC | 9am Boston | 6am Seattle



thanks @jennifer for the reminder, this will be interesting :+1:

1 Like

Check out the Webinars Github Page for a complete view of this tutorial that includes all linked images

Webinar 3 - OpenMRS Dev Setup for FHIR Module and Microfrontends

Video: (coming soon)



This tutorial will be focused on setting up a local development environment using the OpenMRS SDK. The approach can be generalized for work on any existing or new OpenMRS modules, but for this tutorial we will focus on the FHIR module and the Microfrontends Project. The MF project includes an OpenMRS module that allows OpenMRS to support the client-side SPA-based frontend to OpenMRS.

Please feel free to send feedback / suggestions for improving this tutorial! This content is based on the availble documentation along with vital input from @psbrandt, and we’re definitely looking to improve it with input from the community.

Note: We won’t focus on implementation-specific installation and setup that might concern you for deploying production-ready solutions. See the Implementers Guide for guidance on that.

End Goal

You should be able to see the following screens after a successful setup, all running off of the local machine:

OpenMRS SPA Login

(click here for full set of screenshots)

Learning Objectives

  1. Gain a birds-eye view understanding of the OpenMRS reference application architecture.

  2. Understand how the FHIR Module is integrated into the RefApp distribution.

  3. Understand how the MF project integrates into the OpenMRS distribution.

  4. Set up a development environment for working on the FHIR module using the OpenMRS SDK.

  5. Set up a development environment for working on Microfrontend ES Modules.

Referenced Resources

OpenMRS Architecture Overview


OpenMRS Architecture

OpenMRS is designed using a Modular Architecture that allows for flexible customizations of functionality to fit the specific needs of the different places that OpenMRS is used.

Today, we will be mostly working with the OpenMRS Reference Application, which consists of the OpenMRS core application and a set of default modules that provide generic functionality. A list of the modules included in the Ref App can be found here: https://github.com/openmrs/openmrs-distro-referenceapplication/blob/master/package/src/main/resources/openmrs-distro.properties. To test out the functionality of the Ref App, you can take a look at the OpenMRS Demo.

The OpenMRS FHIR Module

One of the modules that comes bundled with the reference application is the OpenMRS FHIR Module. We will examine how to develop and deploy new features in this module. You can read more about the OpenMRS FHIR Module project on this OpenMRS Wiki Page.

If you’re interested in getting further involved in this project, join the [OpenMRS FHIR Squad] and check out the #fhir channel on the OpenMRS Slack.

tech review

SPA Module

The second project we will focus on is the Microfrontends Project. This excellent OpenMRS Talk post - and this followup - give a great overview of the motivations behind the Microfrontends approach. The project is under current development by the [OpenMRS Microfrontend Squad](https:// wiki.openmrs.org/display/projects/Frontend+-+SPA+and+Microfrontends).

The OpenMRS SPA module is not included with the Reference Application distribution, and we will have to deploy it to our OpenMRS instance using the OpenMRS SDK.

If you’re interested in more information, you can join the #microfrontend channel on the OpenMRS Slack and follow the development process on Github.

The Import Map and Frontend Javascript Modules (ESM)


The Full Picture

At the end of this tutorial, your local development enviroment should look as follows:

  • An OpenMRS server running the latest OpenMRS Referance Application distribution.

  • A cloned OpenMRS FHIR module codebase that is compiled locally and used by the OpenMRS server.

  • A cloned OpenMRS SPA module codebase that is compiled locally and used by the OpenMRS server.

  • Cloned codebases for the FHIR and Home Microfrontend javascript modules that compile and are served up locally, and connect to the OpenMRS server using the mentioned SPA module.

Walkthrough Tutorial

Related Resources

1. Install Dependencies


Install JDK 8:


> java -version

java version "1.8.0_221"

Java(TM) SE Runtime Environment (build 1.8.0_221-b11)

Java HotSpot(TM) 64-Bit Server VM (build 25.221-b11, mixed mode)


Install Maven:


mvn --version

Apache Maven 3.6.2 (40f52333136460af0dc0d7232c0dc0bcf0d9e117; 2019-08-27T08:06:16-07:00)

Maven home: C:\lib\apache-maven-3.6.2\bin\..

Java version: 1.8.0_221, vendor: Oracle Corporation, runtime: C:\java\jdk1.8.0_221\jre

Default locale: en_US, platform encoding: Cp1252

OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"





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

> mvn openmrs-sdk:help

[INFO] Scanning for projects...




OpenMRS SDK 3.13.2

For more info, see SDK documentation: https://wiki.openmrs.org/display/docs/OpenMRS+SDK

2. Clone Relevant Codebases

OpenMRS FHIR Module

git clone https://github.com/openmrs/openmrs-module-fhir.git

OpenMRS SPA Module

git clone https://github.com/openmrs/openmrs-module-spa.git

Javascript Modules

In this example, we will clone the openmrs-esm-home and the openmrs-esm-api codebases, but feel free to choose whichever openmrs-esm-* projects you’d like.

git clone https://github.com/openmrs/openmrs-esm-api.git

git clone https://github.com/openmrs/openmrs-esm-login.git

3a. Install MySQL


> bin\mysqladmin -u root -p version

Enter password: *****

bin\mysqladmin Ver 8.42 Distrib 5.7.27, for Win64 on x86_64

Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.




3b. OR install Docker

> docker -v

Docker version 19.03.4, build 9013bf5

4. Set up OpenMRS RefApp


We will use the OpenMRS SDK to create a local development server running the OpenMRS Reference Application Distribution.

> mvn openmrs-sdk:setup -DserverId=openmrs-dev -Ddistro=referenceapplication:2.9.0 -DdbUri=jdbc:mysql://localhost:3306/openmrs -DdbUser=openmrs -DdbPassword=openmrs


What port would you like your server to use? (default: '8080'):

> 8080

If you want to enable remote debugging by default when running the server,

specify the port number here (e.g. 1044). Leave blank to disable debugging.

(Do not do this on a production server) (default: 'no debugging'):

> 1044

Which database would you like to use?:

1) MySQL 5.6 (requires pre-installed MySQL 5.6)

2) MySQL 5.6 in SDK docker container (requires pre-installed Docker)

3) Existing docker container (requires pre-installed Docker)

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

> <1 OR 2>


Note: JDK 1.8 is needed for platform version 2.1.4.

Which JDK would you like to use to run this server?:

1) JAVA_HOME (currently: C:\java\jdk1.8.0_221\jre)

2) Other...

>> 1

[INFO] Server configured successfully

[INFO] ------------------------------------------------------------------------


[INFO] ------------------------------------------------------------------------

[INFO] Total time: 02:48 min

[INFO] Finished at: 2019-10-21T15:22:18-07:00

[INFO] ------------------------------------------------------------------------

Demo Patients


For the OpenMRS Reference Application, just set the setting named

referencedemodata.createDemoPatientsOnNextStartup to the number of demo

patients you want created and restart the application.

The setting referencedemodata.createDemoPatientsOnNextStartup is accessible

through the new UI via Home > System Administration > Manage Global Properties.

It is also accessible through the old admin UI in Maintenance > Advanced Settings.

Test the Ref App:

mvn openmrs-sdk:run -DserverId=openmrs-dev

[INFO] Scanning for projects...


[INFO] ------------------< org.apache.maven:standalone-pom >-------------------

[INFO] Building Maven Stub Project (No POM) 1

[INFO] --------------------------------[ pom ]---------------------------------


[INFO] --- openmrs-sdk-maven-plugin:3.13.2:run (default-cli) @ standalone-pom ---

Checking if port 8080 is in use... [free]

Connect remote debugger with port 1044

Forking a new process... (use -Dfork=false to prevent forking)

Listening for transport dt_socket at address: 1044




INFO: Starting ProtocolHandler ["http-bio-8080"]

Open a browser and go to http://localhost:8080/openmrs/.

You should see the following page:

OpenMRS Initial Setup

Let the setup process complete in peace :smile: It might take quite some time :sleepy:




OpenMRS Login Screen

Enter the very secure admin\Admin123 username and password combo, choose a location to “login” from, and you should see the following screen at http://localhost:8080/openmrs/referenceapplication/home.page:

OpenMRS Homepage

5. Build and deploy FHIR and SPA OpenMRS modules


Go to System Administration > Advanced Administration > Manage Modules.

You should see the following list of modules - note the FHIR module version, and the absense of the OpenMRS SPA module.

OpenMRS Modules Pre

We’ll deploy local versions of our modules using the cloned codebases from earlier.

> cd <path-to-cloned>/openmrs-module-fhir

mvn openmrs-sdk:deploy -DserverId=openmrs-dev

Would you like to deploy fhir 1.20.0-SNAPSHOT from the current directory? [Y/n]:

> Y

Do you want to update module 'fhir' in version '1.18.0' to version '1.20.0-SNAPSHOT'? [Y/n]:

> Y




[INFO] ------------------------------------------------------------------------


[INFO] ------------------------------------------------------------------------

[INFO] Total time: 35.814 s

[INFO] Finished at: 2019-10-28T11:52:22-07:00

[INFO] ------------------------------------------------------------------------

> cd <path-to-cloned>/openmrs-module-spa

mvn openmrs-sdk:deploy -DserverId=openmrs-dev




[INFO] ------------------------------------------------------------------------


[INFO] ------------------------------------------------------------------------

[INFO] Total time: 5.785 s

[INFO] Finished at: 2019-10-28T11:54:31-07:00

[INFO] ------------------------------------------------------------------------

Now, restart the server: mvn openmrs-sdk:run -DserverId=openmrs-dev

Your modules page should look like this:

OpenMRS Modules

6. Set up Microfrontends dev environment.

Related Resources


  • Git

  • Node and NPM

Note: npm run build in the Packmap instructions caused an error in NPM 8.9, but worked as documented in npm 10. Look into this requirement and document it.

The MF UI requires a couple of different assets to be served (as specified here):

We need to package the MF ESM packages for local development, as described here

> git clone https://github.com/openmrs/packmap.git

> cd packmap/examples/openmrs-example

> npm install

> npm run build

The packmap/examples/openmrs-example/openmrs/frontend will include the files that need to go in the frontend folder for the OpenMRS server, so we copy the contents over:

cp <path-to-packmap-directory>/examples/openmrs-example/openmrs/frontend <path-to-openmrs-server-root>/frontend

Now, we should be able to access the Microfrontends UI at this address: https://localhost:8080/openmrs/spa

However, we need to make sure that we set an exception for local SSL connections using the following guide for trusting insecure localhost SSL certificates.

7. Postman


In order to more easily send and analyse API requests to the local OpenMRS server, we can use Postman. In order for the requests to get through the authentication, we can set up the capture of Chrome cookies using the Postman interceptor. As a result, requests sent from the native Postman app will use the same session cookies as the Chrome browser, allowing us to log in using the browser, capture the generated cookies using the Interceptor, and then switch to sending requests using Postman.

  1. Download and install Postman from https://www.getpostman.com/

  2. Download and install the Postman Interceptor Bridge for your OS from here: https://learning.getpostman.com/docs/postman/sending-api-requests/interceptor-extension/#installing-the-interceptor-bridge

  3. Install the Postman Interceptor Chrome Extension from here: https://go.pstmn.io/interceptor-download

  4. Start Postman and click the satellite button in the top corner. Click on the Cookies tab, and you should see a message that says Interceptor Connected and a green dot.

  5. Turn on Cookie caputre and put in your local dev address/port in the Domains section. Your screen should look like this:

Postman Setup

8. Test the Setup

OpenMRS Reference Application

To test out our OpenMRS Ref App, we will create a patient using the UI. We will then use the built-in FHIR Client to send a GET request to our OpenMRS FHIR Server, and try to retrieve the created patient as a FHIR resource.

Prereq: Make sure Postman is running and capturing your browser cookies like explained here

  1. mvn openmrs-sdk:run -DserverId=openmrs-dev

  2. Open your browser and go to localhost:8080/openmrs and login as admin\Admin123

  3. Create a patient - be creative!

  4. Note the UUID of the patient in the url

  5. Check whether the FHIR module is installed correctly. You should be able to access the following resources:

  1. Go to >Admin>AdvancedAdmin>FHIR Module

  2. OpenMRS the FHIR Client and replace the patient id w/ your patient’s uuid

  3. send the request and make sure you get the correct json FHIR resource representing your patient

  4. Copy the request url and create a Postman request using it. Make sure you’re caputring the cookies!

OpenMRS Microfrontend UI

To test out the Microfrontends setup, we’ll use the config module to change the logo of the OpenMRS MF login screen.

Webinar Questions

This is a list of questions that came up during the webinar, along with eventual answers/clarifications

(nothing here yet!)

Additional Screenshots

OpenMRS Admin

OpenMRS SPA Login

OpenMRS SPA Home



Thank you for the presentation I have really benefited just waiting for the video as I practice the deployment part. @jennifer thanks for the reminder.

1 Like

I set up this but I’m having the following questions.

It isn’t available on HTTPS but with HTTP. May I know how to setup https? Or is it a typo?

2. When I generate the import-map.json along with the frontend content using packmap it builds the UI same as in this tutorial:

But it’s different than https://openmrs-spa.org/openmrs/spa/home. So I enabled the dev tools and override the import map with this map (openmrs-spa.org’s import map).

Now it works perfectly but the home page is still empty. Also, it displays Oops! An unexpected error occurred. on the home page. (Full console log: https://pastebin.com/sgxmZMzS) Other UIs such as login, find patient works fine.

Can someone help me to solve this?


@FlorianRappl @rmkanda @jecihjoy @fali @dkibet Do you have any idea on this?

Hi @jayasanka I would need to know a bit more to really help you.

Maybe contact me on slack in the #microfrontends channel such that we could have a look at this together.

1 Like

Thanks @florianrappl!