Best way to specify Configs of OpenMRS 3.x in distro file

I have my distro file set as follows. But I am having complaints about the files that can not be found.




What is the best approach to setting up these variables


I have read guidance from the 3.x implementors guideline and seems not to suggest how to setting them up.

Thanks in advance. @corneliouzbett @bistenes

This is how i have been able to setup OpenMRS 3.X

  1. Firstly set up raw openMRS SDK server, Using reference application 2.12.0, you can choose the reference application of your choice but i would recomment refApp 2.12.0.

  2. After you have been successful. Go to the folder in the server directory called Frontend. something like <server-name/ frontend>

  3. Inside <server-name/ frontend> clone spa module inside that directory, Here we clone we don’t paste omod file.

  4. Then do mvn openmrs-sdk:deploy. During this process, you have to choose your server name and reference application 2.12.0.

  5. Then lets look for a folder named inside your server and paste this code this code Add an omod file for queue module.

  6. Then we do mvn openmrs-sdk:run. Hopefully this would be helpfull @slubwama. Best Regards

@sharif Thanks for this. Thou it seems to be quite lengthy. I though the process would be as simple as

  1. Add Spa font end modules to distro properties file eg(spa.frontendModules.@openmrs/esm-devtools-app=3.2.0)

  2. run “mvn clean install

  3. run "mvn openmrs-sdk:run/deploy -Ddistro=org.openmrs-sdk:[modulename]:[moduleversion]"

  4. Start Server with "mvn openmrs-sdk:run"

So my question still stands on the best way to set these in the distro file.


By the way, I have been able to use the four steps i have set above but it seems like some files are not pointing to the appropriate folders and files when running the spa

Some of the errors I am getting are here below.

WARN - DispatcherServlet.noHandlerFound(1251) |2022-04-27T14:24:34,894| No mapping for GET /openmrs/importmap.json
WARN - SpaServlet.getFile(166) |2022-04-27T14:24:35,143| File with path '/Users/lubwamasamuel/openmrs/ugandaemr/frontend/auto/manifest.d7f50154f66448287167e3a19324d47a.json' doesn't exist
WARN - SpaServlet.getFile(166) |2022-04-27T14:24:35,149| File with path '/Users/lubwamasamuel/openmrs/ugandaemr/frontend/auto/manifest.d7f50154f66448287167e3a19324d47a.json' doesn't exist
WARN - DispatcherServlet.noHandlerFound(1251) |2022-04-27T14:28:50,727| No mapping for GET /openmrs/frontend/headerConfig.json

It could be probably the version of modules you are using. Did you add queue omod file inside ugandaemr/modules folder

@sharif yes

@slubwama i dont have that folder inside ugandaemr/frontend/auto/ This folder doesnt exist even though i set up a fresh installation. Here is are the files I would be expecting here Unless you using a different approach than SDK

@sharif exactly. That is why I am asking about what’s the best way to set the spa settings


And out of curiosity where is it getting the auto from.

Presumably @ibacher @bistenes @zacbutko can give us some clues.

That looks like a bug i guess in the openmrs tooling , on my side i had to manually correct the file paths ie removing “auto” from the file path in the index.html and manifest.* .json files found at the root of the 3.x frontend app

1 Like

If your using the sdk , you set them right in file . see example

Some apps have been discontinued others are not actively maintained and, quite honestly, the released versions are quite a bit behind times. If you could share some actual error messages, it might be helpful in hunting things down. We do need some sort of registry of maintained 3.x apps and pointers to those versions.

Yeah, I’m not aware that we’ve documented these values in any obvious place. They are used as parameters to the call to the openmrs build, so the “documentation” for them can be found by running npx openmrs build --help.

The four values that you’ve highlighted are used to provide necessary constants to the app-shell (the core of the 3.x frontend). They are ultimately embedded as constants in the generated index.html page that constitutes the single-page application here. Looking there, I notice that there’s now an offline option which we should also support via the SDK. All of these values are dependent on how things are deployed in your application with sensible defaults (so they aren’t specifically required). Specifically:

spaPath or --spa-path or openmrsPublicPath (default: /openmrs/spa/): This is the URL (usually URL path) where the single-page application can be accessed. If you use the default 3.x RefApp setup, this value should be /openmrs/spa/. If you use module-spa, this should be the context path for your OpenMRS installation ending with /spa. For example, if you were to deploy the OpenMRS WAR file as my-openmrs-instance.war the path would be /my-openmrs-instance/spa/. For most setups using module-spa, though, this should also be /openmrs/spa/. If you have configured things so that the frontend is served from a different URL, you should fill in the URL. Ideally, this path is only a relative path and you have a single host which routes requests to the frontend or backend as appropriate or else you will likely encounters CORS issues.

apiUrl or --api-url or openmrsApiUrl (default: /openmrs/): this is the URL used as the base path to access the OpenMRS backend from the frontend. This should the relative path to wherever OpenMRS is deployed in your application. If you’re using the 3.x RefApp setup, this should always be /openmrs/. If you are using module-spa, this should be whatever the context path for your OpenMRS instance is. Normally, this is /openmrs/, but it can vary depending on the name of the WAR file deployed. E.g., if you deployed OpenMRS as my-openmrs-instance.war, the path should be /my-openmrs-instance/.

configUrls or --config-url or openmrsConfigUrls (default: []): The 3.x frontend is configurable using pretty simple JSON documents to describe how things are configured. This setting should contain a comma-separated list of URLs from which the app-shell should download to gather whatever local configurations you made. Honestly, this one has the most variation in how it is used depending on if your running openmrs build directly, using the SDK or the 3.x RefApp setup. In the 3.x RefApp setup, this value is set to the environment variable $SPA_CONFIG and the startup script will convert this variable from either a comma-separate list of values or a space-separated list of values into an appropriate JS array. If specified in the file, this should be a comma-separated list of URLs which will (eventually) be converted into an appropriate array passed to openmrs build. If you run openmrs build directly, you should likely use the --config-url argument once for each configuration file you want to load. The URL here depends on where the configuration file will be accessible from. dev3 and O3, for instance, use a configuration file served from Digital Ocean with the URL “”. There is currently no mechanism I’m aware of for automatically adding such configuration files to be served from a specific location, so the specific URLs used will be highly implementation-specific.

importmap or --importmap and a whole bunch of potential variables (default: importmap.json): this is the path to access the importmap.json generated from the run of openmrs assemble. Normally, this should be the same value specified for spaPath with importmap.json appended to the end (e.g., /openmrs/spa/importmap.json). If for whatever reason you’ve decided to separate out the importmap.json file from the rest of your distribution it should be the URL that the app shell can download the importmap.json file from.

Sorry for the mountain of text… the O3 frontend provides a lot of flexibility with how files are arranged, but this flexibility comes at the cost of a lot of explanations that are dependent on where those files are served in your configuration.

The general rule here would be: if you follow the model implementations using module-spa or the 3.x RefApp, you should not need to set any of these values except configUrls. If you don’t follow the model implementations, hopefully the above can provide you with enough guidance.


@ibacher thanks. This was helpful. Thou there are still complaints about a header mapping that can not be found.

No mapping for GET /openmrs/frontend/headerConfig.json

1 Like