Overview

There are various approaches implementers can use to configure their O3 instances. These include:

Metadata configuration
Configuring individual frontend modules
Distro-level configuration

Configuring metadata

Metadata configurations get loaded through the initializer module (opens in a new tab) in O3. The initializer module, or Iniz for short, is a module that allows implementers to load metadata into their OpenMRS instances through JSON files. The various configuration files that ship with O3 are located in the distro/configuration directory of the distro reference application config (opens in a new tab) repository. The initializer module supports loading a wide variety of data and metadata types, including but not limited to:

Concepts
Locations
Person attribute types
Global properties
Encounter types
Visit types
Programs
Program workflows
Program workflow states

For more information on how to configure your O3 instance using the initializer module, read the Iniz repository's README (opens in a new tab).

Configuring individual frontend modules

Per-app configuration is available in O3 via the built-in configuration system. Each frontend module can define its own configuration schema in a config-schema.ts file inside its src directory. The following snippet is drawn from the Programs frontend module's config-schema:

src/config-schema.ts

import { Type } from '@openmrs/esm-framework';
 
export const configSchema = {
  hideAddProgramButton: {
    _type: Type.Boolean,
    _default: false,
  },
  showProgramStatusField: {
    _type: Type.Boolean,
    _description:
      'Whether to show the Program status field in the Record program enrollment and Edit program enrollment forms. If set to true, the `Program status` field is displayed in the Programs datatable',
    _default: false,
  },
};
 
export interface ConfigObject {
  hideAddProgramButton: boolean;
  showProgramStatusField: boolean;
}

The properties specified in the config schema allow implementers to tailor the behavior of the module to their needs. The configuration system also allows implementers to specify default values for the various configuration properties.

Implementers can make changes to frontend module configurations through the built-in implementer tools panel. Once you log into O3, clicking the caret arrow centered at the bottom of the screen will pull up the implementer tools. Alternatively, you can click on the cog icon in the navbar. Once open, you can look up configuration properties by searching through the configuration and modify them on the fly. Note that any tweaks made to the configuration through the implementer tools will be lost once you refresh the page. To make permanent changes to the configuration, you will need to commit those changes to your distro's configuration. The implementer tools allow you to download a temporary config file containing your changes by clicking the Download config button.

Typically, you're going to need to make multiple configuration overrides to various frontend modules. The canonical way to do this is to create a JSON configuration file that lives on your server. You can then point your SPA to this configuration file by specifying its URL in the SPA build configuration file. An example of such a config file is the Ozone Cambodia config file (opens in a new tab). Each key in the config file corresponds to a frontend module. The value of each key is an object containing the configuration properties that you want to override for that module. These properties correspond to whatever properties are defined in the module's config schema.

ℹ️

O3 loads frontend modules on demand. This means you'll only see a module's configuration properties in the implementer tools if the module itself has been loaded. If you're only seeing default keys like "Display conditions" and "Translation overrides" in a module config schema in the implementer tools, it means the relevant module likely hasn't loaded yet.

To view configuration for modules related to a specific feature, like the order basket, navigate to that section of the application (e.g., the Patient Chart). Once the module loads, you'll see all its configurable properties in the implementer tools.

Distro-level configuration

Implementers can configure their instances at the distro level using the following approaches:

distro.properties

The distro.properties file is a configuration file that describes the backend modules that make up your distribution. The reference application's default distro.properties file lives here (opens in a new tab). The most important things to include in the distro.properties are:

war.openmrs - the version of Core being used.
For each module, we'll usually have an entry stylized as omod.[module-id] = [module-version]. For example, omod.referenceapplication = 2.11.0.

Typically, you'll only want to modify the distro.properties file if you want to specify additional backend modules that you want to include in your distro. If you want to remove a backend module from your distro, you can do so by removing its entry from the distro.properties file.

spa-build-config.json

The SPA build configuration is a JSON file that allows you to specify various configuration properties that get passed to the frontend modules during the build process. The SPA build configuration file is located in the frontend directory of your distro. The reference application spa-build-config file lives here (opens in a new tab).

The SPA build configuration file is used to specify the following properties:

frontendModules - describes all the apps that make up your distro and their specific versions (as published on an NPM registry).
spaPath - the URL path which your SPA will be served from.
apiURL - the URL of the OpenMRS backend that your SPA will be communicating with. Defaults to /openmrs.
configUrls - an array of URLs pointing to JSON configuration files that will be loaded into your SPA during the build process.
defaultLocale - the default locale that your SPA will be served in. Defaults to en-GB.
supportOffline - boolean value that determines whether or not your SPA will be able to function offline. Defaults to false.
pageTitle - the default page title that will be used by your SPA. Defaults to OpenMRS.

Typically the things you'll want to customize in the SPA build configuration are the frontendModules, configUrls, and the defaultLocale. Most other things have the same defaults that you won't need to change. If you want to add a new module to your distro, you can do so by adding it to the frontendModules array. Similarly, if you want to remove a frontend module from your distro, you can do so by removing its entry from the frontendModules object.

Key repositories Configure branding