# Flattened archetype is lacking terminology and language bindings
**Category:** [REQUESTS](https://discourse.openehr.org/c/tool-requests/95)
**Created:** 2021-07-07 19:50 UTC
**Views:** 846
**Replies:** 21
**URL:** https://discourse.openehr.org/t/flattened-archetype-is-lacking-terminology-and-language-bindings/1691
---
## Post #1 by @william_vw
I've been using [java-libs](https://github.com/openEHR/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](https://github.com/openEHR/java-libs/blob/master/oet-parser/src/main/java/org/openehr/am/template/Flattener.java) 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.
Thoughts?
Thanks,
William
---
## Post #2 by @pablo
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.
---
## Post #3 by @william_vw
Thanks - I ended up biting the bullet and extending the [Flattener](https://github.com/openEHR/java-libs/blob/master/oet-parser/src/main/java/org/openehr/am/template/Flattener.java) by pulling in terminology and language bindings from the component archetypes.
---
## Post #4 by @pablo
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:
https://www.youtube.com/watch?v=QqFTU2RC7eI
https://www.slideshare.net/pablitox/ehrgen-demo-presentation
https://github.com/ppazos/open-ehr-gen-framework
---
## Post #5 by @william_vw
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?
---
## Post #6 by @pablo
Hey William,
There is tolling freely available. Two tools I've tested are the Template Designer and LinkEHR (some links might be broken)
https://www.openehr.org/downloads/modellingtools/
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 https://github.com/openehr/archie
---
## Post #7 by @birger.haarbrandt
Hi William,
there is some functionality around OPT as part of our openEHR SDK: https://github.com/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.
---
## Post #8 by @william_vw
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:
---
## Post #9 by @william_vw
Hi @birger.haarbrandt ,
Thanks, I will look into it!
---
## Post #10 by @birger.haarbrandt
[quote="william_vw, post:8, topic:1691"]
Sorry I meant software libraries for querying OPT files
[/quote]
What do you mean by that? It would be great if you can elaborate a bit more on your goals.
---
## Post #11 by @pablo
Hi William, this is a little library / toolkit I wrote to deal with OPTs https://github.com/ppazos/openEHR-OPT
That is open source. Then there is the SaaS I created above that https://toolkit.cabolabs.com/
---
## Post #12 by @william_vw
@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 ..
---
## Post #13 by @birger.haarbrandt
Have you checked https://github.com/medblocks/medblocks-ui?
Additionally, please check the above mentioned SDK (or directly the REST endpoints in EHRbase: https://github.com/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.
---
## Post #14 by @pablo
[quote="william_vw, post:12, topic:1691"]
thanks a lot, will look into it!
[/quote]
You will see it has a very simple form generator from an OPT :)
---
## Post #15 by @william_vw
(for some reason, my posts have been flagged as spam and hidden .. no idea why ..)
---
## Post #16 by @siljelb
Discourse has some automatic checks on posts from new users. I've manually restored your posts, hopefully it's okay now. 😊
---
## Post #17 by @william_vw
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.
---
## Post #18 by @joostholslag
That sounds a lot like what medblocks by @Sidharth_Ramesh does. https://github.com/sidharthramesh/medblocks
---
## Post #19 by @Sidharth_Ramesh
Hey @william_vw
Creator of [medblocks-ui](https://github.com/medblocks/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](https://github.com/medblocks/vscode-medblocks-ui/blob/master/src/defaultTransform.ts#L59).
And that maps to:
```
```
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:
```
```
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.
---
## Post #20 by @pieterbos
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 https://github.com/openEHR/archie/pull/261/files. It should already be able to parse OPT 1.4 into AOM 2 directly in https://github.com/openEHR/archie/pull/261/files#diff-9681ba0a83b9833c853535f5e4447601239a41ef373d253237698103fce8562dR21-R33 .
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.
---
## Post #21 by @pieterbos
Ok, turns out I had some more time than expected. The branch of archie in https://github.com/openEHR/archie/pull/261 now actually converts at least some 1.4 OPTs to a working ADL 2 template.
The resulting template is int differential source form, which can relatively easily be edited by hand or with tools. It can be converted to OPT 2 easily as well with the existing Archie tools, or the visual studio code extension.
This is still very experimental, but might be worth a try. Even just loading an OPT 1.4 into AOM 2 and to use it from there with the at-style nodes and adl 1.4 semantics is possible, and path lookup will work.
---
## Post #22 by @pieterbos
OPT 1.4 -> OPT 2 conversion should now mostly work in that branch. Still very experimental and somewhat untested, but if you're willing to experiment and perhaps manually fix some minor issues in the ADL output, it could work.
---
**Canonical:** https://discourse.openehr.org/t/flattened-archetype-is-lacking-terminology-and-language-bindings/1691
**Original content:** https://discourse.openehr.org/t/flattened-archetype-is-lacking-terminology-and-language-bindings/1691