3. openEHR Template Management¶

Date: 2026-01-03

Status¶

Accepted

Context¶

Open CIS uses EHRBase as its openEHR Clinical Data Repository. EHRBase requires Operational Templates (OPT) to be registered before compositions can be created against them. Without the template, composition creation fails with a 400 error.

Templates define the structure of clinical data by constraining openEHR archetypes. For example, a "Vital Signs" template combines observation archetypes for blood pressure and pulse within an encounter composition archetype.

Templates must be uploaded to EHRBase before the application can store clinical data, but developers may forget this step when setting up a new environment. Different environments like development, staging, and production need consistent template configurations to ensure the same clinical data structures work everywhere. Creating proper OPT files from scratch requires specialized tooling and expertise that would slow down development and introduce a barrier to entry for new contributors.

Decision¶

We will implement automatic template registration on API startup, using pre-built templates from the openEHR community.

Template Storage: OPT files are stored in api/templates/ directory, named {template_id}.opt
Startup Registration: On API startup, the application:
Checks which templates are already registered in EHRBase
Uploads any missing required templates
Logs success/failure for each template
Required Templates: The list of required templates is maintained in src/ehrbase/templates.py:
```
REQUIRED_TEMPLATES = [
    "IDCR - Vital Signs Encounter.v1",
]
```
Graceful Degradation: If EHRBase is unavailable or template upload fails:
The API continues to start
A warning is logged
Features requiring that template will fail gracefully

Template Source¶

IDCR Vital Signs Template¶

We use the IDCR - Vital Signs Encounter.v1 template from the RippleOSI/Ripple-openEHR repository:

Source: https://github.com/RippleOSI/Ripple-openEHR/blob/master/technical/operational/IDCR%20-%20Vital%20Signs%20Encounter.opt
Generated by: Ocean Template Designer Version 2.8.94Beta
Last Updated: ~2017 (repository inactive for ~7 years)

Why This Template?¶

Production-Ready: Created by clinical informaticists for real-world use
Well-Structured: Proper OPT format with full archetype constraints
Comprehensive: Includes blood pressure, pulse, temperature, respiration, oximetry, and more
Open Source: MIT licensed, freely available

Archetype Versions¶

Due to the template's age (~2017), it uses v1 versions of archetypes:

Archetype	Version in Template	Latest CKM Version
`blood_pressure`	v1	v2
`pulse`	v1	v2
`encounter`	v1	v1 (unchanged)

Trade-off: Using older archetype versions is acceptable for a learning project. The fundamental data model is the same; v2 versions typically add optional fields or improve constraints. For production use, consider creating a new template with v2 archetypes.

Template Structure¶

The IDCR - Vital Signs Encounter.v1 template includes:

COMPOSITION (openEHR-EHR-COMPOSITION.encounter.v1)
└── SECTION (openEHR-EHR-SECTION.vital_signs.v1)
    ├── OBSERVATION (openEHR-EHR-OBSERVATION.blood_pressure.v1)
    ├── OBSERVATION (openEHR-EHR-OBSERVATION.pulse.v1)
    ├── OBSERVATION (openEHR-EHR-OBSERVATION.body_temperature.v1)
    ├── OBSERVATION (openEHR-EHR-OBSERVATION.respiration.v1)
    ├── OBSERVATION (openEHR-EHR-OBSERVATION.indirect_oximetry.v1)
    ├── OBSERVATION (openEHR-EHR-OBSERVATION.avpu.v1)
    ├── OBSERVATION (openEHR-EHR-OBSERVATION.news_uk_rcp.v1)
    └── EVALUATION (openEHR-EHR-EVALUATION.clinical_synopsis.v1)

FLAT Path Structure¶

The template uses a section-based structure affecting FLAT paths:

vital_signs/blood_pressure:0/any_event:0/systolic|magnitude
vital_signs/blood_pressure:0/any_event:0/diastolic|magnitude
vital_signs/pulse_heart_beat:0/any_event:0/rate|magnitude

Creating Custom Templates¶

If you need to create a new template (e.g., for v2 archetypes or additional observations):

Ocean Template Designer (free): https://tools.openehr.org/designer/
Better Archetype Designer: https://tools.better.care/
ADL Designer: https://tools.openehr.org/designer/

The workflow: 1. Import required archetypes from CKM (Clinical Knowledge Manager) 2. Create a template constraining those archetypes 3. Export as OPT 1.4 format 4. Place the .opt file in api/templates/ 5. Update REQUIRED_TEMPLATES in src/ehrbase/templates.py 6. Update service code with new template ID and FLAT paths

Consequences¶

Positive¶

New environments automatically get required templates
Developers don't need to manually upload templates
Template configuration is version-controlled
Consistent behavior across environments
Using community templates saves development time

Negative¶

OPT files are large and complex XML (~256KB for vital signs)
Using older archetype versions (v1 vs v2)
Dependent on external template sources for updates
Template upload adds startup time (minimal)

Neutral¶

Templates are EHRBase-specific (other CDRs may need different formats)
Template IDs must match between OPT files and application code

File Locations¶

api/
├── templates/
│   └── IDCR - Vital Signs Encounter.v1.opt  # OPT template (from Ripple)
├── scripts/
│   └── upload_templates.py                   # Manual upload script
└── src/
    └── ehrbase/
        └── templates.py                      # Template management code

PRD-0004: Vital Signs Chart
EHRBase documentation: https://ehrbase.readthedocs.io/
openEHR CKM: https://ckm.openehr.org/
Template source: https://github.com/RippleOSI/Ripple-openEHR