Designing openEHR templates using the Archetype Designer

Shilpi Dasgupta

Shaonli Dasgupta

Business Analyst

Designing openEHR templates using the Archetype Designer

OpenEHR is a standard specification in health informatics that ensures both Syntactic and Semantic health data interoperability. A key feature of openEHR is the development of computable, human-readable, discrete clinical models/concepts called Archetypes. To know more about archetypes read Understanding OpenEHR Clinical Knowledge Manager.

A combination of two or more such archetypes leads to the creation of what is referred to as “Templates”. A Template is a set of archetypes with constraints applied as desired; however, the template is by itself, a giant and specialized archetype. Different types of Templates can be designed by re-using the same archetypes or using newly created archetypes.

Templates are created from Archetypes in the Archetype Designer Tool. This creation of templates forms a crucial step in the overall health interoperability workflow as depicted in the figure below:

Role of Templates and Archetype Designer tool in the health data interoperability

The Archetypes can be created from the Archetype Designer tool and then imported into the openEHR Clinical Knowledge Manager-an online repository of Archetypes. The desired Archetypes are then exported in the ADL format into the Archetype Designer Tool within which templates can be created. The newly created template can be exported and through the OpenEHR REST API gets stored into the OpenEHR CDR by conversion into Compositions. Clinical applications built on top of such OpenEHR CDRs can then access the data by querying using Archetype Query Language.

Templates form the gateway for the technical downstream artefacts such as GUI screen forms, message definitions, and document definitions.

Creating a Template is dependent on the use case, specialty, domain, and location. So, templates can be used to logically represent a use case such as data within Discharge Summary or a Radiology Report.

Types of Templates

There are two types of templates: Operational template (OPT) and OpenEHR template (OET).

Templates are developed in a simple XML format known as OpenEHR Template or “.oet format”.

The Operational Template (OPT) is an XML artefact that is generated from the OET template by modelling tools. The OPT is a compiled template that produces a flattened format expressed in XML, that can be read and used by a machine. The OPT template is a dynamically created object from an OET template.

Workflow depicting the process of creating templates from Archetypes

Process of creating templates from archetypes

Archetype Designer Tool

Archetype Designer is a web-based clinical modelling tool that allows for the visual authoring of openEHR archetypes and templates. This tool features an intuitive visual interface that can be accessed simultaneously by multiple users in web browsers.

The tool is used to create openEHR templates by combining archetypes. It also allows users to further constrain archetype elements within a template to suit a particular use case.

Archetype Designer tool can be used to design both openEHR Archetypes and templates from the archetypes present in the repository. Archetypes need to be designed de novo whereas the templates need to be designed from the various archetypes present in the repository.

Building/designing templates within Archetype Designer Tool

Some key points to keep in mind while building a template using Archetypes are as below:

  1. Different types of archetypes are used to aggregate to build a template, such as the Composition Archetype used at the top level followed by Section, Entry and Cluster Archetypes which are included within Composition as required.
  2. Composition is the root archetype and is mandatory to be included. An example can be a “report” type. Then, this composition needs to be filled with specific archetypes for the use case of this template, that will fill up the slots, such as “Blood Pressure” (observation), and “Service” (action). Composition functions like a container document for clinical data and can be considered equivalent to an Encounter, Report, Discharge Summary. Actual information gets captured in the entries usually within Sections. Archetypes can be made fit for a particular use case by constraining them such as changing the multiplicity of the occurrences or making the mandatory items being optional or vice-versa.
  3. Choosing an archetype for a template and eventually, a form should be done by identifying the form fields first and matching them with the archetypes and the specific items within them.
  4. There could be several Archetypes used in a form and one needs to aggregate or constrain them to make them fit for purpose. Archetypes are meant to include the maximum possible information for a particular concept. E.g for a Problem/Diagnosis concept, the corresponding Archetypes will include the maximum possible elements relating to Problem/Diagnosis. However, we might not need all the elements possible in a particular use case. Therefore, the Archetypes are constrained by removing unwanted elements, setting default values, creating terminology mappings, and creating coded text.

Following are the steps describing the creation of templates from archetypes within the Archetype Designer Tool:

Creating a Template using the Archetype Designer Tool

The following steps need to be followed to create a simple template using the Archetype Designer tool:

The Archetype Designer tool can be accessed from:
One can Sign up and log in using Google, Microsoft, or GitHub accounts.

Creating/Choosing a Repository and adding Archetypes from the CKM

After logging in we need to choose a repository. One can choose an existing Repository or create a new one.

A Repository can be considered as a container that holds the Archetypes and templates. Clicking on the “New Repository” button will display a dialog box allowing the user to name and then create the new repository

To add the archetypes to the repository we need to download that from Clinical Knowledge Manager (CKM). One needs to go to the CKM and then click on Archetypes and then Bulk Export (as shown in the screenshot below), following which the archetypes can be added to the Repository.

Downloading Archetypes from CKM

Following the creation of a new Repository or choosing an existing one, the user on clicking the repository will navigate to the screen shown below displaying a list of the archetypes and templates in the chosen repository.

Creating a new Template

In order to create a new template we need to select the 'Template' option from the 'New' button which opens up a New Template Dialog box

The Rm type field will display the “Composition” option by default. One can also choose any other archetype type as well.

The next step would be to select the appropriate Archetype in the Root Archetype ID dropdown. A Rule of thumb is to select the Encounter option out of the lot as the root Archetype.

The next step is to enter the Template ID. Again, one must always include a version following the template id.

Hitting the Create button would close the dialog box and create the template.

The name of the active template is always displayed in the top blue tab. A star next to the template name indicates that the template has changes that need to be saved.

Definition Tab: The definition tab is the default view for every template in which the user will be able to create the template.

Description tab: In this tab the user will be able to add optional details about the template. There are two sub-tabs: Header and Attribution within which the user can add the details. Header tab is selected by default.

Analytics tab: This tab displays the various analytical metrics as shown in the screenshot below:

Adding Clinical Content into the template

The “Content” seen in the screenshot below is the section within which the selected Archetypes would be placed and would eventually become the form elements in the frontend application. Clicking on the “Content” text would select the same and on the right-side panel a list of archetypes imported from the CKM can be seen. These Archetypes can be now added to the newly created template.

One can search for the appropriate Archetype in the search bar seen in the right-side panel.

Upon typing few alphabets, the matching archetype gets displayed and clicking the same will include it within the “Content” section of the template seen on the left side.

Selecting the “Reason For encounter” archetype displays a set of functionalities as follows:

Changing occurrences for the archetypes within the template

Clicking the Occurrence toggle button will set the occurrence to zero, meaning that the Archetype instance gets removed from the template.

On doing this action the user can revert it as well using the arrow pointing backwards button.

One can also specify the occurrences for the archetype as desired using the “Occurrences” field on the right-side panel.

First digit = 0—Optional

First digit = 1—Mandatory

Second digit = 0—Not present in the use case

Second digit = *— unlimited occurrences

Clicking on the tick button will save the changes made.

Rename Archetype

The next button is the Rename blue button which is used to change the name of the archetype to suit its inclusion within the template. Clicking on the button will allow the user to enter the desired name. Hitting on the tick button will display the entered name.

In case the user wishes to revert the newly entered name, clicking of the grey button next to occurrence will allow to revert the name.

Clone the Archetype

The yellow button of “Clone node” allows the user to copy/clone the archetype which gets automatically renamed by adding a number to the end of the Archetype name.

Move Archetype up or down

Clicking on the blue button with arrow pointing up will move the selected archetype up with respect to the surrounding archetypes.

Clicking on the blue button with arrow pointing down will move the selected archetype down with respect to the surrounding archetypes.

Cut and Paste Archetype

Clicking on the “Cut” button will cut the entire Archetype. User will be able to paste the same as well.

Extract Template

Clicking this button will save a portion of the template (the selected archetype) as a separate, reusable partial template.

Delete archetype

Clicking on the “Delete” button will remove the selected archetype from the template.

Hide Elements from within an Archetype

The following screenshot shows how to hide elements removed from within an Archetype using the highlighted button

This functionality will hide all the elements for which occurrence has been set to zero.

Prohibit optional elements from within an Archetype

The following screenshot shows how to “Prohibit optional elements” within an Archetype using the highlighted button

Clicking this button will delete all optional data items defined within the archetype and the user can enable the items as per the requirement. This makes it easier to choose the data items to be displayed within an archetype when a particular archetype has lots of optional items within it. Example, Blood Pressure archetype has a lot of optional items within it and by clicking this button and disabling all items at once will help the user to choose the most common requirement of displaying Systolic and Diastolic items for Blood Pressure archetype.

Viewing data within each Archetype

User can use the +/- toggle button o view or hide the archetype structure.


Refining data within Archetype

Setting data as “Free Text” or Coded text”

For a data element within an archetype, one can set the data as free text in the right-side panel

One can also bind a value set to a data element by selecting the option “External Coded”.

Upon selecting the “External Coded” option, the user will be able to select a terminology name such as “ICD 10”.

Set the units of measurement for the data elements within an archetype

The available units for data elements are displayed on the right-side panel.

The user will be able to disable units if they are not relevant by unchecking the unwanted units.

Set up max and min values for an element

It is possible for a user to be able to set up the max and min values in the right-side panel as shown below:

Setting up Proportion

It is possible to set the type of proportion if this has already not been set in the archetype. Example Spo2 is expressed in percent and the same can be selected.

Therefore, the above steps provide a snapshot of some of the important functionalities available within the Archetype Designer Tool, using which one can build a template.

Archetype Designer delivers an open-standard, specification-based tool that can be used to specify and implement clinical models. It gives clinicians and clinical domain experts a tool to model clinical content for the digital health systems they want.