Skip to content

Use cases

This page shows five things people asked the openEHR Assistant to do, what it did, and which tools it called. Each one starts from a prompt a person actually typed. The last is quoted verbatim from a public openEHR forum thread, so the question and the answer can both be checked against the original.

The tool trails below are the calls the assistant made on its own; nobody named a tool in the prompt.

Compare two archetypes that look alike

"There are two archetypes on CKM that look quite similar to me: openEHR-EHR-OBSERVATION.progress_note.v1 and openEHR-EHR-EVALUATION.clinical_synopsis.v1. I don't know the implications and why one is OBSERVATION, while the other is EVALUATION. Compare them, explain when I should use one or the other."

ckm_archetype_get ×2 → ckm_template_search

The assistant retrieved both archetypes, then searched for published templates that use each one, to see how they are used in practice.

The difference is the Reference Model entry class, and it changes the structure. An OBSERVATION carries HISTORY → EVENT → ITEM_TREE, so a progress note can hold a sequence of timestamped entries: shift after shift, round after round. An EVALUATION carries a plain ITEM_TREE: a clinical synopsis is one persistent statement, with nowhere to put a time series.

The answer came back as a comparison table, a structural sketch of both, and a scenario-by-scenario mapping: shift handover and hourly ICU status to the progress note; discharge summary and referral letter to the synopsis. The choice matters early: the entry class fixes the shape of the data, and it is expensive to change once data exists.

Understand an unfamiliar archetype

"Explain what this archetype is about, what the concept behind it is, and how it aligns to other similar archetypes on CKM. Give examples of how it can be used with other archetypes in a template."

ckm_archetype_get → ckm_archetype_search (related concepts) → ckm_archetype_get on the candidates

Given openEHR-EHR-OBSERVATION.four_a_test.v1, the assistant explained the 4AT as a validated rapid screening instrument for delirium and cognitive impairment: four components, about two minutes at the bedside, and a total of 0–12 in which four or more suggests possible delirium.

It then read the modelling back out of the clinical design. The scoring is deliberately non-linear: alertness and acute change score 0 or 4, never 1 or 2, because those two carry more weight than the rest. That is why the archetype models them as ordinals with coded values rather than plain counts. Finally it placed the 4AT against its neighbours (ACVPU, GCS, and NEWS2) and noted that a "C" on ACVPU is the trigger for a full 4AT. The ADL shows the structure; the clinical intent behind it is what decides whether to reuse the archetype.

Find an archetype, or author one

"What archetype should I use to capture data for the 6-minute walk test? If there is no archetype that fits, create one. First analyse published science so you can add proper references. Re-use available CLUSTER archetypes through slots where CKM already has them."

ckm_archetype_search (varied phrasings) → ckm_template_search → type_specification_get → guide_get

The first thing it reported: no published or draft archetype for the 6MWT exists. The nearest relative, openEHR-EHR-OBSERVATION.timed_25_foot_walk.v1, uses the opposite paradigm (time over a fixed distance, rather than distance within a fixed time), so it is not a substitute.

Only then did it author openEHR-EHR-OBSERVATION.six_minute_walk_test.v0. It cited the ATS 2002 guideline and the 2014 ERS/ATS technical standard it had gathered, opened slots onto published CLUSTERs rather than re-inventing them (inspired_oxygen.v1 for supplemental oxygen, device.v1 for the oximeter, level_of_exertion.v0 for exertion context), and recommended openEHR-EHR-COMPOSITION.encounter.v1 to carry the result. openEHR modelling puts reuse first, which is why the search came before the authoring, and why the answer said plainly that nothing fitted.

Generate code from a model

"Create a DTO class in PHP that resembles the openEHR-EHR-EVALUATION.precaution.v1 archetype. Adapt the methods published on the EVALUATION type where they make sense for a DTO."

ckm_archetype_get → type_specification_get (EVALUATION)

It used two sources: the archetype for the constraint structure, and the Reference Model type specification for the class contract. The result mapped each at node to a typed property (mandatory condition with optional terminology coding, a status enum, evidence as a 0..* array, optional category and comment) and kept the CLUSTER slot and protocol extension points open. This is the step from clinical model to running software, and the place where hand-written code drifts from the archetype it claims to implement, with nothing to report the drift.

"When I try to retrieve only medicines that are linked to a particular problem using the following aql, I am getting empty response. […] If I remove the WHERE clause, both the values are returned. It would be a great help if anyone can advise on how to get the aql working."

guide_get ×3 → examples_search → type_specification_get (LINK, LOCATABLE) → ckm_archetype_get

This one is not ours. It was asked on the openEHR forum in May 2026: a prescription in which every medication_item carries an RM LINK pointing at a problem in another composition, and a query that returns nothing as soon as it filters on that link. The thread solved it in two hours: a single character was missing from the URI, so the string never matched.

Put to the assistant, the same question produced the query, the AQL rules a SQL background gets wrong (LIKE matches the whole value, and its wildcard is *, not %), and the archetype path verified against the published ADL rather than taken from the question. Then it fetched what LINK actually is, and read back the Reference Model's own words: links "should be between archetyped structures only", and "sensible links only exist between whole ENTRYs, SECTIONs, COMPOSITIONs and so on".

The links in that composition hang on medication_item, an ELEMENT, which is an interior node. The specification says that is the wrong place for them. Nobody in the thread mentioned it. The typo took two hours to find; a link on the wrong node is the kind of modelling decision that passes review and becomes expensive once there is data in the system.

Cadasto keeps the first four transcripts internally; the archetypes they reference are published on CKM, except the 6MWT draft, which was authored in the third example. The fifth is a public thread, question and answer included, so it can be read at the source.

Next: install the server and plugin, or see the full feature inventory first.