We want to enable end users to change the names of some reports from their default names. For example, a ‘discharge summary’ could be renamed ‘relocation report’ or ‘death report’, depending on the circumstances. We are using theopenEHR-EHR-COMPOSITION.report.v1composition archetype as wrapper for these reports.
We considered three options and would like the community’s view on which is best-practice.
1. COMPOSITION.name
2. COMPOSITION.context.report_id
3. a customCLUSTERinserted intoCOMPOSITION.context.extension
Concerning 1: The COMPOSITION.name property is set to the name of the root node of the template by default. However, it seems possible to post a composition with a name different to that of the root node of the template.
Concerning 2: We are unsure whether storing the editable report title in COMPOSITION.context.report_id fits the data element description ‘Identification information about the report’. After all, an editable title is a form of identification, but not a unique composition identifier.
Concerning 3: We would prefer to have a mechanism that we can apply to all our report templates without the need to add an extra archetype to each o f them
My questions:
Where do you store editable report titles?
Or if you don’t yet: Where would you recommend to store editable report titles?
If it’s about the name of the report, yes I would use the name attribute, though the underlying models should allow that.
If there is no constraint in the COMPOSITION.name and the only thing you have is the text of the ontology, then no, setting a new name shouldn’t pass validation, so you can’t post a composition with a different name than that, and if you are using something that allows that, it’s not validating correctly.
Recently I opened this discussion Allowing open name constraint to support formal FOLDER models, why not? noting that the AD tool doesn’t allow to add constraints on names besides setting a DV_CODED_TEXT, though an open DV_TEXT constraint is perfectly valid/compliant, and even possible to do in the LinkEHR editor. Something like this should be in place in the archetype so your users can set any name:
COMPOSITION …. {
name matches {
DV_TEXT matches {*}
}
With that, a data validator that complies with openEHR should allow any name at the COMPOSITION level. Note that should be in the archetype, not in the template, because having that in the template and not in the archetype would break the implicit constraint name nodes have in archetypes, which are setting a fixed value from the ontology, depending on a language (terminologic/linguistic constraint).
I remember having a similar use case, when we modeled generic questionnaires using a generic COMPOSITION and a generic ADMIN_ENTRY archetype to model the questionnaire/question respectively, and the question could have any name (open constraint), and the actual template was generated from an external dictionary of questions, following the generic archetype structure. So having that open constraint for the names was a crucial part of this, and I think I did that manually because of the constraints of current modeling tools not supporting that.
From reading the spec of composition.name (inherited from LOCATABLE):
Runtime name of this fragment, used to build runtime paths. This is the term provided via a clinical application or batch process to name this EHR construct: its retention in the EHR faithfully preserves the original label by which this entry was known to end users.
I would say this is a good fit.
Using report id is not a great fit, especiallly if multiple compositions have the same name, e.g. surgery discharge summary, than the name is no longer an identifier, but you would need additional numbering or something. As a backup it could work I would think, but prefer the composition.name.
I don’t know about tooling/CDR support for setting this by the user from the UI. @ian.mcnicoll ?
Thank you for your clear and detailed explanations.
Before asking the question that came up after your reply, I would like to describe the option that stores the report title in COMPOSITION.name and our test results in more detail .
Summary of test results on several CDRs
We found two distinct behaviours when changing node names in the template and then changing them again in a concrete composition :
Root node (typically atCode at000 0)
If the root node’s name is changed in the template, that name can still be replaced by a different name in a composition and the composition can be saved without validation errors.
Example: the attached template set at0000 to “TemplatesNewRootNodeName”, but the attached composition then stored the root name as “Pulse”, which was accepted.
All other nodes
If a non-root node’s name is changed in the template and then set to a different value in a composition, saving the composition fails with a validation error.
Inspection of the .opt file
Comparing the produced .opt files shows that template name changes are represented differently for the two groups:
Root node (at0000)
The changed label is saved under <term_definitions> for at0000, e.g. in the attached tem p la te opt:
In addition to term_definitions, the node definition itself receives constraints. Concretely, a C_STRING entry with a of allowed values is ad ded, e.g.:
This acts as a constraint on permitted names and effectively prevents later overwriting in the composition .
My question
We plan to store the report title in the Composition’s root node name and do not want to change other node names. From our inspection of .opt files, root-node name changes are handled differently than other nodes (other nodes get extra constraints).
Is it safe to use the Composition root node name to store the report title using a template like the attached one, i.e. without manually updating the opt with COMPOSITION …. {name matches {DV_TEXT matches {*}})?
Thank you very much for your answer!
Test examples
Example template “test.openehr.pulse_heartbeat.v0.opt”:
sets the root node name to “TemplatesNewRootNodeName”
@emmanuel.eschmann I’m not sure which editor are you using or how you are setting the name, though:
term_definitions is a change in the terminology of the archetype/template.
C_STRING is actually a string constraint on the node.
In my opinion there shouldn’t be a difference if the node is the root or it’s internal: all the name changes should work in the same way, if those are not working in the same way in the modeling tool you are using, then it’s a problem of the tool.
I think I commented this, but you need to consider if the node doesn’t have a constraint for the name, the only constraint is the terminological one (from the ontology) and the name for a given atNNNN node should be exactly the same as the text for atNNNN in a given language (since archetypes are multi-language). So there is a constraint but it’s not part of the AOM constraint model, it’s part of the AOM ontology model.
Considering that, if you change the ontology part in the template, then that’s kind of violating the underlying ontology defined in the archetype. I think that should be invalid. But if you apply a constraint to the node’s name in the template, I think that’s valid since it’s saying “this should be the constraint, don’t look at the ontology” (this is the C_STRING). Though that constraint could be added either in the template or in specialized archetypes.
But the root node is constrained at design time. In my preliminary opinion you must not change that constraint at run time. Otherwise the (root) node is no longer understandable from the template.
If this validates (in which validator?) that seems a bug to me.
Thanks for sharing the artefact. Could you share the full composition as a canonical json please.
I’m interested where ‘templatesnewrootname’ is defined.
Edit: ah I found it. It’s in the archeype terminology/ontology as the English name for root. I missed it when Reading the template (as t.json) because I only looked at the first language. This shows another problem. The root node has a ‘text’ for each language. So if you do replace the text at run time, that new text is now different in meaning from the other languages. This is hidden in the flat format, because it uses English and you changed the English name of the root. But it’s an issue for users of other languages.
Edit2: what made you explore using the root node for the name of the report? Instead of the composition.name we discussed earlier. I still think that’s a better fit.
Small note, that is no RAW format, is CANONICAL format. The only format that is stable against all openEHR implementations, and for which we do have schemas for JSON and XML as part of the openEHR ITS specifications.
That one implementation calls it RAW it doesn’t mean that it is RAW
This surprised me. To me the composition name is an RM class attribute, usually reflected in an instance of a composition, while the root node is at Archetype (Model) level, and is the code for the root (node) of that archetype, where the archetype is a (set of) constraints on the RM class. But that to me doesn’t nescessarily imply the root node ‘text’ constraint, constrains the composition.name. So unless it’s specified in the (AM) specifications, I would ask the implementer to explain. we really need some help here from people with deeper knowledge of the specs in this area. @thomas.beale would you have time for a reply please?
