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 Making	Review O3	Install O3	Configure O3	Integrate O3 w/ other systems	Customizing & Developing on O3	Maintaining O3

Others:

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
- Find modules and generate their packages (distro.properties) - ok
- Add modules in the configuration file (import-map.json or spa-build-config.json) - ok
- Manually fetch module:
  curl -H "Accept: application/vnd.github+json" -H "Authorization: token ____________" -L -o module.zip "https://api.github.com/repos/openmrs/openmrs-esm-module-management-app/actions/artifacts/338768959/zip"
- Create or modify frontend modules (https://github.com/openmrs/openmrs-esm-template-app for example)
  - Yarn Install, dev, and build
  - Npx assemble - local package option: http://%22@openmrs/esm-template-app%22:%20%22file:///User/ibacher/openmrs-esm-template-app/dist%22,,
    Source Assemble: https://github.com/openmrs/openmrs-esm-core/blob/304fd2e7d7f20e85cf8151453e67baddf84794ab/packages/tooling/openmrs/src/commands/assemble.ts#L124
  - Yarn Publish or use
- Generate distribution (using survey or config mode) - DEV
  - 1. Build the frontend app
    npx openmrs build
    npx --legacy-peer-deps openmrs@next build --target dist --fresh (if conflicts or errors)
  - 2. Assemble frontend module (define spa path in spa-build-config.json)
    define needed frontend modules in spa-build-config.json
    npx openmrs assemble --mode config --config spa-build-config.json
  - 3. mount dist as a volume (in docker-compose)
    - ./frontend/dist/:/usr/share/nginx/html/
  - 4. commit and tag docker container (optional)
- Generate Docker image - DEPLOY
  - 1. define needed frontend modules in spa-build-config.json
  - 2. docker build -t michaelbontyes/o3_frontend:0.1 .
- Github action
  https://github.com/marketplace/actions/build-and-push-docker-images
Configure the frontend UI

Logo Filename

Modify logo style
Main navigation Modify
- Modify the UI (navigation, slots, widgets) using a custom-config.json - ok
- Dev in Docker: - ./config/custom-ui-config.json:/usr/share/nginx/html/custom-ui-config.json
- Modify the style of the UI using a custom-style.css - how to?
- Modify the logo and images of the UI - how to?
Configure the content
- How to manage metadata?
- Where to define the content of the modules - in progress
  - Registration (field mapping + configuration)
    https://github.com/openmrs/openmrs-esm-patient-management/tree/main/packages/esm-patient-registration-app
    - Basic info
    - Identifiers
    - Address hierarchy
    - Relationships
  - Lists
    - How to filter by location or privileges
  - Queues
    - How to define queries and automatically populate them?
    - How to filter by location or privileges
- 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
- K8s dashboard
  sudo kubeadm init --control-plane-endpoint=__.westeurope.cloudapp.azure.com

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

Config	Scope	Path	File example
OpenMRS WAR files	OpenMRS Core	/openmrs/distribution/openmrs_core	path for war file? needed for distro
Initializer files	Locations, Programs, Concepts, etc.	/openmrs/distribution/openmrs_config	configuration reload without restart O3?
Modules + OMOD files	ID Gen, Appointments, Cohort, OCL, etc. Data filter?	/openmrs/distribution/openmrs_modules	distro.properties Repos for OMODs? Or OMOD generation best practice?
OWAs files		/openmrs/distribution/openmrs_owas
SPA modules	esm-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)	import-map.json /usr/share/nginx/html/importmap.json ? > web app config modules modules minified? /etc/nginx/nginx.conf > server config
SPA UI config	Patient chart order JSON	path? to overwrite default config or customize one?	https://spa-modules.nyc3.digitaloceanspaces.com/@openmrs/config/config.json in /usr/share/nginx/html/config.json
Localization files for OpenMRS	Admin translations	/openmrs/l18n ?	locale_en.json
Localization files for O3 UI	Transifex?	path?	?
Liquibase files	Create users?	path?	?
Runtime properties		path?
openmrs-distro.properties
Theming files like logos and icons	openmrs_logo_white.gif	path?
startup.sh	OMRS home, config folder, modules, database config, catalina options, server startup	/usr/local/tomcat/startup.sh 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:
```
  backend:
    image: openmrs/openmrs-reference-application-3-backend:${TAG:-nightly}
    depends_on:
      - db
    volumes:
      - ./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.)


Logo	Filename
	Modify logo style
Main navigation	Modify