DRAFT: O3 EMR How-To Guide Outline

ABOUT: Michael Bontyes & Grace Potma are collaborating here to assemble the ideal How-To outline, so we can improve / evolve what is currently at om.rs/o3setup. 

Decision MakingReview O3Install O3Configure O3Integrate O3 w/ other systemsCustomizing & Developing on O3Maintaining O3


  • Finding Providers 
  • National Implementations 

Implementation Team, trying to decide: 

  • Should we use the OpenMRS EMR? 
  • What are the advantages?
  • How mature is the solution? Where is it currently used? Success stories? 
  • What features does it offer?
  • What steps can we expect in the transition?

 ICT members of the team. They have additional questions like: 

  • Is there a comparison of what we have now vs what comes w/ O3?
  • What is already done in O3?
  • How can we try this out quickly, ourselves? How do we:
    • Set it up? 
    • Make it look more familiar to the users - eg colors, logos? UI? Content?
    • Set up the sections and forms our users, our departments need?
  • What if we want to build our own features? 
  • Who can we turn to for help?
  • What do we do if we see gaps?

Configuration and deployment questions 

  • Run O3 on Docker (as the web server approach is suggested rather than OpenMRS SDK)
    • Use the Demo version - ok
    • Use a fresh installation without demo data - how to?
    • How to specify the O3 version and where to find the WAR file - how to?
    • How to fork O3 and build your custom Docker images (recommended approach by Ian and Raff, rather than using host volumes)
      • Fork O3
      • Modify Dockerfiles
      • CD/CI pipelines 
      • Commit images
      • Update docker-compose.yml
  • Configure the backend modules
    • Find modules and generate OMODS https://addons.openmrs.org/search
    • Add modules in the configuration file - ok
    • Locally compile OMOD from GitHub repo using Docker image
      docker run --rm -v "$(pwd)":/opt/maven -w /opt/maven maven:3.8.6-openjdk-18-slim mvn clean install
  • Configure the frontend modules
  • Configure the frontend UI 


    Modify logo style
    Main navigationModify 

  • Configure the content 
    • How to manage metadata? 
    • Where to define the content of the modules - in progress
    • How to manage forms + validation + calculated field - how to in O3 UI or Ampath? Form bank > Form Bank
    • How to use field validation (for email and phone number for example) - how to?
    • How to use Initializer configuration files - ok - how to reload? run startup.sh
    • How to use OpenConceptLab for concept management - bugs/errors to investigate
      • How to populate a source
      • How to create collections
      • How to reuse existing concepts from other sources
      • How to map concepts to standardized concepts (CIEL, ICD, SNOMED)
      • How to sync concepts in OpenMRS 3
        • Using the Initializer module
        • Using the sync module 
    • How to use Liquibase - how to? Using a module or iniz extend?
  • Configure the language
    • Administration language - how to?
    • UI language - how to?
    • Form language - how to?
  • Manage O3 and patient data
    • How to manage backups - how to?
    • How to sync data across environments - how to?
    • How to anonymize data - how to?
    • How to print a patient file for handover purposes or data regulation compliance?  - how to?
  • Integrate O3 with DHIS2
  • Integrate O3 with Superset dashboard
  • CD-CI pipelines
    • Github actions
  • Containerization
    • Run docker-compose
  • Orchestration

  • What is the recommended practice to modify and reload configuration files within Docker infra (initiated with the 3.x docker-compose) for:

    ConfigScopePathExisting documentationFile example
    OpenMRS WAR filesOpenMRS Core/openmrs/distribution/openmrs_core
    path for war file? needed for distro
    Initializer filesLocations, Programs, Concepts, etc./openmrs/distribution/openmrs_config
    reload without restart O3?
    Modules + OMOD files

    ID Gen, Appointments, Cohort, OCL, etc.

    Data filter?

    Repos for OMODs? Or OMOD generation best practice?
    OWAs files

    SPA modulesesm-patient-chart-app
    form builder
    spa-build-config.json? (this is where the O3 RefApp configures which apps to use: https://github.com/openmrs/openmrs-distro-referenceapplication/blob/main/frontend/spa-build-config.json)

    /usr/share/nginx/html/importmap.json ? > web app config modules

    modules minified? 

    /etc/nginx/nginx.conf > server config

    SPA UI configPatient chart order JSONpath? to overwrite default config or customize one?
    in /usr/share/nginx/html/config.json
    Localization files for OpenMRSAdmin translations/openmrs/l18n ?
    Localization files for O3 UI Transifex?path?
    Liquibase filesCreate users?path?
    Runtime properties


    Theming files like logos and iconsopenmrs_logo_white.gifpath?

    startup.shOMRS home, config folder, modules, database config, catalina options, server startup

    in backend container

    Image layers?
    path? config?

  • VIM in container? > -u root
  • OCL org and source creation

  • Options to map custom configuration within vanilla O3 containers to be validated:
    1. Option 1: Docker commits - push : ok
    2. Option 2: Map the backend container in the docker-compose.yml with:

          image: openmrs/openmrs-reference-application-3-backend:${TAG:-nightly}
            - db
            - ./distro:/openmrs/distribution
    3. Option 3: Sync with a GitHub repository within startup.sh?

  • What is the recommended practice to back up or sync O3 data across environments? (also for organization-specific demos for example)

  • How to start with a vanilla O3 setup? (No demo data, no unnecessary modules, etc.)