Templates Primer

Owned by Thomas Beale
Last updated: 07-Jun-2011Version comment
10 min read

Formalism

The '1.5' version of the openEHR Archetype Definition Language (ADL) and Archetype Object Model (AOM) is a major upgrade of ADL 1.4, fixing numerous small problems and limitations of ADL/AOM 1.4 (ISO 13606-2), as well as adding the ability to express templates in a seamless way. A further specification for the Template Object Model (TOM) and Operational Template (OPT) defines how templates are deployed. The draft specifications for ADL 1.5, AOM 1.5 and the TOM/OPT can be found at the bottom of the specifications page .

We can think about archetypes and templates from two viewpoints:

  •  Functional – what they do;
  •  Architectural – what they look like inside.

Functional view - what do archetypes and templates do?

Archetypes

Archetypes are used to express re-usable structured data-item definitions in the form of constraints on a reference model. Archetypes are defined based on topic, independent of use context. The 'blood gases measurement' archetype for example includes all the data points that might be used in any form of blood gas observation. There are many archetypes that contain data points that relate to the same topic, but would never be used in the same situation together, e.g. in the BP measurement archetype, the systolic, diastolic and pulse pressure values are defined, but the latter is always used on its own, never with the former two.

Composition of archetypes is supported via 'slots' where other archetypes can be attached. This allows decomposition and reuse. This enables the creation of larger structures consisting of a composition of smaller archetypes. Archetypes can also be specialised i.e. in the object-oriented inheritance sense, for example the heart-rate archetype can be specialised to include extra elements for fetal heart rate.

Archetypes support the binding of data nodes, names and values to concepts from external terminologies. They are also multi-lingual, and support all languages that can be expressed in Unicode.

Templates

Templates are used to create definitions of content such as a particular document or message, required for specific use cases, such as specific screen forms, message types or reports. Typical examples include 'acute care discharge summary', 'GP referral' and radiology report'. They use archetypes by:

  •  Choosing a root archetype;
  •  specifying 'slot-fillers', that reference an archetype, to create the overall structure;
  •  removing unneeded archetype data items by further constraining various existence and occurrences constraints to 0..0;
  •  further constraining remaining data items in various ways, e.g. making optional data items mandatory, adjusting cardinality, refining terminology value sets;
  •  defining terminology bindings.

Once a template is defined, it is then compiled, to produce a flattened form, i.e. the result of all the reference archetypes and templates compressed through the specialisation relationship. This is known as an operational template ('OPT'), is usually expressed in XML, and is the definitive machine-usable form of a template.

The OPT is further processed into concretely usable artefacts such as:

  •  XSDs for message definitions; this approach completely replaces hand-built XML message and document definitions;
  •  Code skeletons / APIs, e.g. for Java, C#, any other language ; these code skeletons provide an easy way for programmers to 'set' and 'get' the data of the specific message or document;
  •  GUI screen forms for data capture, data display;
  •  Other kinds of visualisation;
  •  Converters to published standard messages, documents etc.

These downstream generated artefacts allow message implementers, software developers, and data managers to build software and systems without any significant training or understanding of archetypes, templates, openEHR, Snomed, or any other complex health informatics concept. Note that any of the above artefacts can be generated in any of the languages for which translations exist, allowing for example, german- and chinese-language XML schemas and programming APIs to be used in relevant environments. The data created by all of the above artefacts can always be converted back into standard openEHR data, meaning that semantic integrity has been retained, without requiring that the architectural complexity be visible in the developer space.

In summary, it enables the outputs of a knowledge engineering activity, such as run by a national e-health programme or corporation, to be converted into 'everyday' developer artefacts which can be used to make software, systems and data that obey the knowledge models.

Queries

A key engineering feature of archetypes is support for portable queries. Data queries in openEHR are built based on the archetypes (specifically, paths from the archetypes) as well as terminology, but have no dependence on the particular way the data are stored. As a result, the same queries can be used in different openEHR installations, as long as the archetypes are shared, but making no other assumptions. This means that for the first time, applications such as decision support and business intelligence become a realistic possibility.

Architectural View

The archetype formalism is completely generic, assuming only well known object-oriented semantics. This means that the formalism has no dependency on any particular information model (a.k.a. 'reference model', in health informatics). Archetypes can therefore be defined based on any reference model.

Without delving into the technical complexities, a good way to understand how archetypes work by thinking of them as specifications of legal configurations of reference model instances. This is essentially the function of the 'instructions' that come with LEGO to describe how to build a dog, a house or a car from the same set of bricks. In this case, the bricks are like reference model instances (the reference model itself is the same thing as an engineering specification for the bricks, something that LEGO users never see, but is of course required in the LEGO factory). Note that the LEGO bricks we know in the real world are just one 'reference model'. The archetype formalism will allow archetypes to be written against any reference model, which would be like enabling model descriptions for e.g. Fischer-Technik, Meccano and other similar modelling toys.

Two further things are useful to understand. Firstly, archetypes are not fixed 'cookie cutter' definitions. On the contrary, like some LEGO model descriptions, they contain a lot of flexibility, including optionality, choice of classes, value ranges and so on. This enables numerous similar but not identical configurations of data to conform to the same archetype. The second point is that archetypes work by binding coded terms, defined within the archetype, to Reference Model class names. For example the ELEMENT class from the openEHR RM can be bound or 'overloaded' with the codes at0011, at0012 and at0013, meaning 'haemoglobin', 'red cell count' and 'packed cell volume'. This internal coding provides a reliable way to connect data instances with concept codes from multiple external terminologies, and as such enables the preferred use of external terminologies with data to be defined on a focussed and incremental basis.

ADL/AOM 1.5 has made it possible to express a template using the same formalism used to express archetypes – templates are in fact just a kind of archetype specialisation. In serial syntax form, this is ADL, while in object form it is the AOM. The XML form is based on the AOM.

Tooling and Development

Development Process

The typical development process is as follows:

  •  Requirements analysis, to determine the data, structure and terminology requirements of a message or document;
  •  Iteratively:
    •  Source and/or design archetypes containing the required data-items; create and maintain archetypes with an archetype editor tool;
    • Develop templates that express the required overall structure, remove the unneeded data items, make other data items mandatory (as required), and specify terminology bindings;
    • Review the resulting template in its 'flat' form, known as an 'operational template' (i.e. with all slot-filling evaluated and all specialisation relationships compressed, or flattened)
  • Generate various output forms of the operational template including:
    • XML form, for use in further transformations or tools;
    • Documentary, e.g. HTML ADL, web forms or other reviewable / publishable formats;
    •  XML Schema.

The process is illustrated below. In the initial iteration, the post-operational template file generators are not implemented. The XML schema is accordingly built by hand in the same form that will ultimately be generated.

In the above, one of the important artefacts for future iterations is the RM/schema profile, which defines the rules for which classes and which attributes from the underlying reference model should be kept in the schema generation process.

It is important to understand that 'archetype development' and 'template development' should be understood as two fairly separate activities. The former tends to be done at a national and international level, and is done based on concepts of good practice, by health professionals and other domain experts. It does not directly try to account for particular use case scenarios.

Template development on the other hand is done at national and lower jurisdiction or enterprise levels, and is mainly concerned with re-using existing archetypes for the purposes at hand, e.g. national discharge summary, medication message, and so on.

A key challenge in this ecosystem is that it is mainly the second sphere of activity in which concrete requirements and empirical knowledge is gathered, yet it is not the main arena in which archetypes are authored. For example, national / local modellers will usually have a very good idea of national adverse event/reaction reporting requirements. How can internationally authored archetypes for adverse reaction and related topics take account of these local needs? A strong feedback mechanism is required between more grass-roots levels and the international sphere, to ensure that the international activity is heavily informed by empirical input from real operational environments. This is the area that openEHR knowledge governance and tools like CKM try to address.

A second dimension of the development challenge is that clinical and other domain specialists do not have time to learn complicated formalisms like ADL, nor even generally learn all the details of the openEHR or other reference models. It has been found by experience that they can review archetypes and templates, and provide most efficient and expert input when the relevant artefacts are converted to screen forms of a quality approaching that found in realistic operational systems – in other words, the toolsneed to address the cognitive space of typical users, not that of tool-builders. Various of the tools below do support this, but further development is needed in this area. The UK NHS / Microsoft 'Common User Interface' (CUI) has provided significant utility in this area.

Tools

Today there are various tools for working with archetypes and templates. The openEHR Foundation's aim is to provide an open set of tools and/or services for

  •  testing and validating the ADL and AOM specifications (i.e. a 'reference compiler'),;
  •  authoring archetypes and templates;
  •  generating the 'operational template' XML artefact;
  •  visualising and demonstrating the artefacts in a form comprehensible by experts;
  •  managing these artefacts online.

To date some of these tools have been proprietary (due to the bootstrapping nature of the openEHR effort) and some are open. With the advent of ADL 1.5, a clear path exists for building the next generation of fully open tools.

Note that these are not the only tools possible, indeed there is now a new market for commercial development of tools, particularly 'downstream' converters and generators taking the OPT as input. Such tools are not described here.

The ADL Workbench – a reference compiler

The ADL Workbench (AWB) is an open source tool that acts as the reference tool for the ADL syntax, and also the AOM object model. It is reference model driven, meaning that it can be used with any reference model for which a schema has been written. Currently schemas exist for the Release 1.0.2 openEHR reference model, and a draft for the EN13606-1 model. Its current release (26 July 2010) implements 90% of the ADL 1.5 draft specifications, including templates. It can be (and has been) wrapped by other tools such as archetype editors; it can also be freely ported to other languages. By Q3 2010, this tool will also generate standard operational template XML.

All ports or alternative ADL/AOM based tools should ideally be tested against this tool to ensure they produce the same results against the test archetype repository.

Authoring tools

The most widely used archetype authoring tool is the Ocean Informatics Archetype Editor, an open source tool that currently wraps the ADL 1.4 AWB compiler, and is being upgraded to use the ADL 1.5 compiler.

To date, due to the lack of a template specification, templates have been expressed in an openly available, but proprietary format developed by Ocean Informatics, with a commercial tool known as the Template Designer. With the advent of ADL 1.5, a future version of this tool would now be based on standard ADL / AOM, and of course be open source.

Demonstrators

Future versions of these tools need to take account of the 'cognitive' relevance aspect described above by being capable of visualising the models in ways directly comprehensible to the experts who review them. This may be done within the authoring tools to some extent, but may also be done in a more comprehensive way by the use of reference / demonstrator applications that can illustrate not just the structure of date, but provide a realistic workflow experience, enabling domain experts to truly understand the consequences of the models for data capture, display and querying.

The open source Opereffa framework, developed at CHIME, UCL provides this kind of experience, and is under ongoing development with direct input from NHS clinical professionals.

Management Tools

The primary archetype / template management tool to date is the Ocean Informatics produced Clinical Knowledge Manager (CKM). This is based on a commercial but openly specified Java asset management platform, and implements validation, access control, workflows, releases, lifecycle management, and many other functions. It provides an openly specified service interface for other systems to interrogate and access the asset repository.

The future of Tooling

In terms of technology, preference among government agencies for Eclipse/Java based tooling may mean that the next generation of authoring tools is likely to be implemented in this technology. It appears that the ADL Workbench and CKM tools will continue as they are, since the future requirements of these tools appear unlikely to change substantially.

Commercial vendors appear most likely to implement post-OPT downstream tools that integrate with their technology offering.