Flattened archetype is lacking terminology and language bindings

I’ve been using java-libs to flatten a template, i.e., apply all of its constraints and print the resulting archetype. This is working wonderfully - but the end result is missing terminology and language bindings - this makes it rather unusable when generating a UI, for instance.

The relevant section in the AOM2 page does not really elaborate on the process (referring to the ADL Workbench for reference). The experimental OPT format mentions the following:

the flattened form of all terminology sections of all referenced archetypes are included in the component_terminologies section.

But this format is not an option for me since (AFAICT) it is not supported by java-libs.

Updating the Flattener code is an option but seems complex since internal node-ids would have to be updated (these are typically re-used in archetypes, e.g., at0004) to have unique terminology bindings across the archetypes.




1 Like

I would rather use the tree structure not a flattened archetype or template if your goal is UI generation. Either way in the java ref impl, the AOM mantains a flat map of node => constraint at the CObject IIRC.

Thanks - I ended up biting the bullet and extending the Flattener by pulling in terminology and language bindings from the component archetypes.

1 Like

Sorry, viewing the code I misinterpreted the purpose of the flattener. The flattener is doing what modelers do in the Template Designed: creating an OET template from references to archetypes in ADL, so basically getting the OPT from an OET and a set of archetypes. So it’s not really flattening anything, but resolving the references.

I don’t know your requirements, but in general you don’t need to work with archetypes directly in software, you get the OPT which has the references already resolved. In the OPT the terminology part of each archetype is already included. Though you might have a good reason to do all this programmatically, I would recommend using a modeling tool to generate the OPTs and work just with the OPTs, it will make your life easier. On a side not I did worked just with archetypes before, doing the full stack: automatic UI generation, automatic data validation, automatic data storage/binding, automatic search and retrieval using archetype ids and paths, etc… and this was a pain! When I decided to work only with OPTs, the code was way simpler.

As reference to that ‘archetype only’ approach:

Hi Pablo,

Thanks for your reply, Pablo. Unfortunately there does not seem to be tooling support for OPT at this time (please feel free to correct me!). The .opt files I found at the CKM are in XML and the syntax seems quite verbose (likely due to XML…) - it would take me far too long to manually write code to query those models. (Are these OPT v1.4 instead of OPT v2? The files don’t specify a version …)

Hence my current approach - “flattening” the .oet file into a single archetype, and then using the Archetype API to query the model. The Flattener resolves the references and applies the constraints - with some additional code to pull in the terminology and language bindings - the end result meets my needs, and as mentioned, I can use the java-libs API to query the model. (Again, if you know of tooling to query OPT files (as those found at CKM) feel free to let me know …)

It seems that OPT2 has been under development since 2016 - judging by the amendment record - and the spec is still incomplete - are people using OPT2? Or are they relying on OPT 1.4?

1 Like

Hey William,

There is tolling freely available. Two tools I’ve tested are the Template Designer and LinkEHR (some links might be broken)


OPT is verbose since it contains all the nodes from all the archetypes referenced, which is what you want in production, to avoid resolving references at runtime, which is time consuming and could lead to inconsistencies, e.g. an archetype is deleted or modified.

Though you can easily transform the XML into JSON to save some bytes :slight_smile:

OPTs available are 1.4 in AOM 2 OPTs and archetypes use the same constraint model.

What you do with flattening is exactly (IMHO) what the OPT has inside, but tooling can do that for you.

Though there are more implementations going to AOM 2, OPTs were not yet migrated to that model, and AFAIK most of current OPT used in production are 1.4

If you are exploring tools and libraries, I would recommend to take a look at Archie, which handles AOM2 by default GitHub - openEHR/archie: OpenEHR library implementing ADL 2, AOM 2, BMM, RM 1.0.4 and many tools

Hi William,

there is some functionality around OPT as part of our openEHR SDK: GitHub - ehrbase/openEHR_SDK

For example, you can create the more developer friendly web template format from the OPT. Not yet 100% bug free regarding some edge cases but might be helpful to you.

Hi Pablo,

There is tolling freely available. Two tools I’ve tested are the Template Designer and LinkEHR (some links might be broken)

Sorry I meant software libraries for querying OPT files - I know archie can be used for generating them. (Since OperationalTemplate is a subclass of Archetype, archie can likely be used for querying them as well - but read on below on why that wasn’t an option in my case.)

My general use case: I wanted to work with Vital Signs template from CKM, which has a zip file and OPT template (XML). AFAIK archie cannot read the OPT XML format, and java-libs cannot be used for parsing OPT either.

So, I turned to the zip file: the OET file is also in XML, and, again, AFAIK, archie doesn’t support the format so it cannot be used for flattening. But the oet-parser in java-libs works like a charm, and has a flattener; my current extension of the class also pulls in terminology and language bindings.

Anyhow that has been my journey :slight_smile: I think I wouldn’t be the only one taking this route - starting from a simple CKM example and working from there.

OPT is verbose since it contains all the nodes from all the archetypes referenced, which is what you want in production, to avoid resolving references at runtime, which is time consuming and could lead to inconsistencies, e.g. an archetype is deleted or modified.

Yes, the XML likely makes it seem more verbose than it is :slight_smile:

Hi @birger.haarbrandt ,

Thanks, I will look into it!

What do you mean by that? It would be great if you can elaborate a bit more on your goals.

1 Like

Hi William, this is a little library / toolkit I wrote to deal with OPTs GitHub - ppazos/openEHR-OPT: Java/Groovy Support of openEHR Operational Templates, Refernce Model, Data Generators and other tools for www.CaboLabs.com projects

That is open source. Then there is the SaaS I created above that https://toolkit.cabolabs.com/

@pablo thanks a lot, will look into it!
@birger.haarbrandt my current goal is to generate a UI from an openEHR template - ideally this would be done from a flattened OPT file, I think …

1 Like

Have you checked GitHub - medblocks/medblocks-ui: Web Components Library for Medblocks Ecosystem?

Additionally, please check the above mentioned SDK (or directly the REST endpoints in EHRbase: GitHub - ehrbase/ehrbase) and convert the OPT towards the WebTemplate format. This should allow you to work way more conveniently with the template.

Medblocks and EHRbase combined should give you a good foundation and examples how to generate/build UIs.


You will see it has a very simple form generator from an OPT :slight_smile:

1 Like

(for some reason, my posts have been flagged as spam and hidden … no idea why …)

Discourse has some automatic checks on posts from new users. I’ve manually restored your posts, hopefully it’s okay now. :blush:

Thanks @siljelb - I think my last post is still hidden - I was just recommending the compilation of a page with software libraries as is done with the modeling tools :slight_smile: might make it easier for future users.


That sounds a lot like what medblocks by @Sidharth_Ramesh does. GitHub - sidharthramesh/medblocks: Secure peer to peer storage for medical records

Hey @william_vw
Creator of medblocks-ui here. I have some experience with generating user interfaces from templates. I agree with @pablo that directly working with archetypes is hard. In fact, I skipped the OPT step and started working directly with web templates. EHRbase supports converting OPTs to web templates, and you can probably find the code to do that yourself.

Now coming to the problem of terminology and language bindings in the template, it all comes down to the information you have in the template. Most of the time this is set during template creation and not at the archetype level.

For example, Chief complaint inside a Problem/Diagnosis archetype: I usually set the default code to a SNOMED CT expression like so:

This gets translated to the following in the web template:

        "id" : "chief_complaint",
        "name" : "Chief Complaint",
        "localizedName" : "Chief Complaint",
        "rmType" : "DV_CODED_TEXT",
        "nodeId" : "at0002",
        "min" : 1,
        "max" : 1,
        "localizedNames" : {
          "en" : "Chief Complaint"
        "localizedDescriptions" : {
          "en" : "Identification of the problem or diagnosis, by name."
        "annotations" : {
          "comment" : "Coding of the name of the problem or diagnosis with a terminology is preferred, where possible."
        "aqlPath" : "/content[openEHR-EHR-EVALUATION.problem_diagnosis.v1]/data[at0001]/items[at0002,'Chief Complaint']/value",
        "inputs" : [ {
          "suffix" : "code",
          "type" : "TEXT",
          "defaultValue" : "<404684003",
          "terminology" : "SNOMED-CT"
        }, {
          "suffix" : "value",
          "type" : "TEXT",
          "terminology" : "SNOMED-CT"
        } ]

Now you just have to map this out to a user interface element. Probably using some code like this.

And that maps to:

<mb-search path="template/problem_diagnosis/chief_complaint" label="Chief Complaint">
        <mb-filter label="Conditions" value="<404684003"></mb-filter>

However, note that sometimes, at the application level you might want to have more control of this binding.
For example, Add Events also to the Chief Complaint section:

<mb-search path="template/problem_diagnosis/chief_complaint" label="Chief Complaint">
        <mb-filter label="Conditions" value="<404684003"></mb-filter>
        <mb-filter label="Events" value="<272379006"></mb-filter>

The output looks like:

The clinician can then choose to opt out of these filters if necessary.
Regarding language, you’ll find that in the localizedName and localizedDescription section of the web template.

1 Like

Many people seem to use the XSD to generate code for OPT 1.4. If you need to query paths within the archetype, could be worth porting the query from Archie to that - that is a small amount of code.

I have been working on converting OPT 1.4 to AOM version 2 in Archie in Opt 1.4 parser and converter by pieterbos · Pull Request #261 · openEHR/archie · GitHub. It should already be able to parse OPT 1.4 into AOM 2 directly in Opt 1.4 parser and converter by pieterbos · Pull Request #261 · openEHR/archie · GitHub .
However, that is just the ADL 1.4 content expressed in the AOM 2, with a bit of uglyness in the C_TERMINOLOGY_CODE parts.

To convert it to proper AOM 2 is a lot more work, since in OPT 2, a template is a specialization, and in OPT 1.4, that is not true, so there will be a lot of work to properly convert node ids. It is unlikely I will have time to do that soon.
The ADL 1.4 version might already work good enough though.