Template hide-on-form

Requirement

From Post-workshop discussions

We agreed the following requirements on slack:

you might want to 'hide' any node in an archetype (within authoring tool env);
you might want to 'show' any attribute node not already constrained (constrained, or on a constrained path = show by default);
you might want to alias any attribute node (constrained or unconstrained);
Aliasing automatically implies 'show'.

From the Workshop

IM: Just crystallising my thoughts on this.

1. This is about adjusting or documenting the template data model to make it easier for clinical reviewers and/or implementers to understand. GUI annotations per-se are out of scope. The main target of the markup is to make aspects of the RM (archetyped or not) more or less visible in the data model that we present to reviewers/implementers. I'm going to call this RM attribute annotation for now but it includes locatable nodes as well as simple RM attributes.

2. The .oet format has 3 kinds of RM attribute annotation.

a) HideOnForm/HTML

This tells downstream rendering tools e.g. TD and CKM HTML renders to omit a particular RM attribute. Typically

a) Hide an Element that has a fixed default value that does not need to be made visible to clinical reviewers.

b) Hide an intermediate RM branch node to hide some of the complexity of the data structure e.g empty protocol branches or item/event trees. Visually this is about flattening the tree by hiding mandatory branches.

    <Context>
      <Rule path="/context/other_context[at0001]" hide_on_form="true" />
      <Rule path="/context/other_context[at0001]/items[at0002]" max="0" />
      <Rule path="/context/other_context[at0001]/items[at0005]" max="0" />
      <hide_on_form>true</hide_on_form>
    </Context>

This is a critical feature that needs to be supported as-is since we make considerable use of it in shaping template views e.g. in CKM.

b) Show / re-label RM attributes

One of the major problems we face with current tooling/reviews and passing on guidance to developers is making clear if/how and where we need to make use of non-archetyped RM attributes e.g composer, context.start_time, entry.provider. Whilst some of these are arguably universal, in many cases the optimum mix of RM attributes that should be exposed is highly dependent on the local use-case. Having some sort of mechanism that would allow us to actively annotate the template to make selected RM attributes visible would be very helpful, better still if these can be given local aliases to match local requirements e.g. Map composer to author, if that is what local documentation/requirements call it. This doe does not need to appear in data, this is purely for documentation

Ocean started adding this facility called RM annotations in .oet but it was never properly supported in downstream tools.

  <view>
    <constraints path="[openEHR-EHR-COMPOSITION.report.v1]/content[openEHR-EHR-SECTION.adhoc.v1 and name/value='Patient details']/items[openEHR-EHR-OBSERVATION.exam.v1]/data[at0001]/origin">
      <items id="VisibleInView">
        <value>Date sample taken</value>
      </items>
    </constraints>
  </view>

The <value> element here allows for a local override of 'origin'.

Both of these do end up in the .opt as constraints

<constraints path="[openEHR-EHR-COMPOSITION.report.v1]/context/other_context[at0001]">
      <items id="pass_through">
        <value>true</value>
      </items>
    </constraints>
    <constraints path="[openEHR-EHR-COMPOSITION.report.v1]/content[openEHR-EHR-SECTION.adhoc.v1 and name/value='Patient details']/items[openEHR-EHR-OBSERVATION.exam.v1]/data[at0001]/origin">
      <items id="VisibleInView">
        <value>origin</value>
      </items>
    </constraints>

Per-node annotations

  <annotations path="[openEHR-EHR-COMPOSITION.report.v1]/content[openEHR-EHR-SECTION.adhoc.v1 and name/value='Imaging diagnostics']/items[openEHR-EHR-SECTION.adhoc.v1 and name/value='Echocardiogram']/items[openEHR-EHR-OBSERVATION.imaging_exam_uk.v0]/data[at0001]/events[at0002]/data[at0003]/items[openEHR-EHR-CLUSTER.imaging_location_gel.v0]/items[at0002]">
    <items>
      <item>
        <key>Notes.Authors Note</key>
        <value>GEL::33645.1</value>
      </item>
    </items>
  </annotations>

This is used for a number of purposes including GUI hints but I don't think that is particularly sensible. The example above though it says 'Author's note' is actually mappings to the Genomics England master dataset metadata code.

I think this is supported ok in AD.

Candidate Solution

From monday discussion: paths to unconstrained RM elements with visibility marker and optional aliases on a per language basis.

rm_visibility = <
    ["/path/to[at0012]/archetype/node[at124]/path/to/rm/attribute"] = <
        visibility = <"show">
        alias = < –- optional
            ["en"] = <"name in english">
            ["de"] = <"name in german">
        >
    >
    ["/path/to[at0013]/archetype/node[at124]/path/to/rm/attribute"] = <
        visibility = <"hide">
    >
>

Alternative (TB):

rm_visibility = <
    ["/path/to[at0012]/archetype/node[at124]/path/to/rm/attribute"] = <
        visibility = <"show">
        alias = <[local::al12]>
    >
    ["/path/to[at0013]/archetype/node[at124]/path/to/rm/attribute"] = <
        visibility = <"hide">
    >
>

terminology
    term_definitions = <
        ["en"] = <
            ["ad12"] = <
                text = <"name in English">
                description = <"description in English">
            >
            ...
        >
        ["de"] = <
            ["ad12"] = <        
                text = <"name in German">
                description = <"description in German">
            >
            ...    
        >
    >