Archetype Designer Primer

Introduction

The purpose of this guide is to introduce the user to the concept of archetypes and to demonstrate how to create and model an archetype using the Archetype Designer provided by Better and openEHR. The modelling process described in this document has been written primarily for users who wish to create novel archetypes for clinical decision support (CDS) applications. Therefore, several concepts and features of archetypes have been intentionally omitted or discussed only briefly. Resources containing more in-depth information are available on the Links & Resources page. There is also a link to Cambio Healthcare Systems CDS Apps Showcase Page on GitHub available in this section, containing over 100 demo applications (using 250+ archetypes and 200+ guidelines).

The guide has been written by the Clinical Modelling Group at Cambio Healthcare Systems. If you have any questions or would like to provide feedback on this document, please send us a message by visiting the Contact Us page.

What is an Archetype?

Archetypes are at the core of the openEHR specification. They are computable, and human-readable, reusable discrete models of health information and serve as containers for standardized clinical data definitions structured in a way that can easily be understood and maintained by healthcare professionals. Each archetype represents a discrete clinical concept and is intended to be exhaustive, containing every possible data element that makes clinical sense about the specific concept. An archetype can be described as a governance unit for a set of data elements allowing a broad definition and minimal constraints to allow sharing and reuse across different healthcare settings and clinical scenarios. It is commonly expressed in Archetype Definition Language (ADL), though ‘more friendly’ XML and JSON formalisms also exist. In addition, archetypes support all the ISO 639 languages and archetyped data will always have the same meaning regardless of context, what system or what language is being used; thus fulfilling the concept of semantic interoperability. As an example, archetypes exist for heart rate, blood pressure, Apgar score, weight, height and body temperature – all discrete clinical concepts. They are the concept-level foundational building blocks of healthcare data, or an electronic health record system (EHR).

To become operational, archetypes are logically aggregated and constrained to create context-specific data sets and documents known as Templates, examples of which include an antenatal visit, a discharge summary or a patient review. Archetypes and Templates constitute the openEHR Archetype/Knowledge model, provide formal definitions of clinical content, and are the concern of the healthcare professional. On the other hand, how health data is represented in a patient record as well as the basic entities for representing information in an EHR, is provided by the openEHR Reference/Information model and is the concern of the IT professional.

An example of an archetype is shown below:

Getting Started

Archetype Designer

The Archetype Designer is the primary tool for authoring and editing archetypes. It is a Web-based openEHR Archetype and Template visual design tool which enables the development of ADL1.4 and ADL2 archetypes.

AD allows created archetypes to be saved in a local repository or an external Github repository. The application is developed and maintained by Better/openEHR Foundation and it can be accessed at: http://www.openehr.org/archetypedesigner

Create an account for free by using one of the social media options e.g Google, Microsoft or or GitHub. We recommend to sign up using the GitHub option as it simplifies the integration with a GitHub repository.

Before creating a new archetype, it is in the spirit of the openEHR reuse philosophy to first check if a published version (final iteration) of that archetype already exists in any publicly accessible archetype repository. See the Links & Resources page for a list of major public archetype repositories.

Creating an Archetype

Creating a Repository

Before it is possible to create or re-use archetypes a repository is required to be created which is going to contain all the archetypes and templates. Create a new repository, by clicking on the “New Repository” button.

Clicking on the “New Repository” button will display a dialog box where it is possible to select the repository type and name. Select “Local folder” in order to create a repository accessible only in the Archetype Designer, or “GitHub” to integrate with an existing GitHub repository.

Start-up Menu

When a repository is selected, the following start-up menu is displayed. Here it is possible to choose between creating a new model (archetype or template), importing existing models or opening existing archetypes or templates.

To create a new archetype, click on the “New” button and select either the Archetype option or any of the other types (Observation, Evaluation, Instruction, Action) in the list.

In the dialog box the model is set to openEHR-EHR by default (which denotes the resultant archetype is modelled after the openEHR EHR specification) and cannot be changed in the latest Archetype Designer version.

The RM type field can be used to specify the type of archetype that will be modeled. If the type was specified already in the previous step then the RM field will display the selection by default.

The Concept field can be used to name and create the id for the archetype.

Our CDS applications are primarily based on observation and evaluation archetypes. A detailed explanation of the available archetypes is provided in the next section.

When modelling archetypes for CDS applications, the observation type is most commonly used. Observation archetypes are used to document and store data components and values related to a given clinical concept that can be observed or gathered at a specific point in time. One example of an observation archetype would be blood pressure, where one can store information about components of the clinical concept; i.e. systolic blood pressure, diastolic blood pressure, mean arterial pressure, patient position during measurement (sitting or lying down), etc. These individual components or properties of the clinical concept are referred to as data elements (a more detailed description on the data element types supported by the Archetype Designer is available later in this document). Other examples of observation archetypes are height, weight, and pulse oximetry. Information about the timing of the observation/measurement is often relevant in observation archetypes.

Evaluation archetypes are the second most commonly used archetypes for CDS applications. They are typically used to store an assessment or evaluation of data obtained from one or more observation archetypes. The corresponding evaluation archetype for the blood pressure example would include potential interpretations of the blood pressure – such as normal blood pressure, hypertension, or hypotension. Additional examples of evaluations are adverse reaction, diagnosis and family history. Evaluation archetypes do not typically require a time component.

Elements

The data elements of an archetype represent the individual components, subcomponents, or properties related to the relevant clinical concept, as well as their derivatives (e.g. blood pressure has a systolic component; mean arterial pressure is a derivative). The values of these elements may take the form of textual data, numerical data, date/time stamps, Boolean variables or even another archetype (a special type of nested archetype). The Tree tab in the archetype page is where the data elements and their attributes (description, unit of measurement, permissible values etc.) are added.

The vertical toolbar highlighted in red is where we can select from one or more options of the different data element types for use in the data definition of our archetype.

Each icon available in the toolbar is described below:

To add elements to the archetype, simply click the data element types of interest from the vertical toolbar and they will be added to the tree under the data node.

To change the name of the data element, click on the Rename button or double click on element name.

Text Element

When the possible values of a data element consist of only textual or alphanumeric characters, the text element type is used. The text element type allows users to enter free text into a textbox (choose Free text) or select from options presented by an external reference terminology set (choose Coded text). The terminology option is rarely used during archetype authoring, but if required it may be defined elsewhere in the modelling process.

Text box

Adding a text element (text box):

Click on the T (Text element) from the toolbar.
The default element name is DV_TEXT. Enter an appropriate name for the element after double clicking on the text field (here a data element has been created and renamed to Comment).
We have chosen Free text which ensures the user will be presented with a textbox where they can enter data in free text.
Add metadata in the description box to elaborate further on the purpose of the element.

Drop-down List

Adding a coded text element (drop-down list):

Click on the T2167 (Coded text element) from the toolbar.
Name the coded text element (in our example, “Patient is participating in a clinical trial”).
The Internal coded radio button is selected by default.
Using the Edit button create a drop-down list with 3 alternatives: Yes, No, and Unknown. After each value has been created, an at-code is assigned automatically as shown above. The first alternative in the list is “Yes” and has been allocated the at-code: at0013.
Include a description (e.g. “Whether or not this patient is participating in a clinical trial.”)

Repeat step 4 to include additional alternatives in the drop-down list. Each new term will be assigned a unique at-code. To remove an item from the list, click on the Edit button and in the dialog box use the delete button when the mouse is over an item. Drag and drop an item to rearrange the order of the terms in the list.

Quantity Element

The quantity data type is used when creating a data element that takes only numerical values with units. It supports integers and decimal numbers (float data type). Below is an example from the bicarbonate deficit archetype:

Adding a quantity element:

Click on the Q (Quantity element) from the toolbar.
Name the element.
In the Units field, click on the plus sign to add units (example below).
Add a description for the element.

Adding Units

Adding units to the quantity element:

Once the plus sign is clicked in the Units field, a dialog box will appear shown in the images above. To add a set of units (mmol/L in this example), use the following steps:

Use the text box to search for Concentration and select it from the list.
Use the text box to search for mole and select {Amount (mole)/Volume} ({384/129}) from the list.
Choose mmol (millimole) in the left list.
Choose L (litres) in the right list.
Click Add to build the complete unit of mmol/L.

Repeat this process to add multiple units to the list of available options. For example, in addition to mmol/L it is possible to include mEq/L, µmol/L, or any other unit that is expected to be encountered in practice when measuring bicarbonate concentration.

Count Element

A count element can be used to store positive and negative integers. Most commonly, it is the element of choice for Total score when the other elements contained in the archetype are ordinals. The count element cannot be used for decimal numbers and has no units.

Adding a count element:

Click on the 123 (Count element) from the toolbar.
Name the element.
Use the Min and Max constraints to set the minimum and maximum range for the score.
Add a description for the element.

Ordinal Element

One of the simplest models to create is one with ordinals that allow users to choose between different alternatives that have an ordinal value linked to them – such as scores for a question in a protocol. The ordinal values can then be summed to create a total score (the total score in such a case would be a count element). Ordinals can also be used to simply select an alternative from a scale – see the example below of the New York Heart Association (NYHA) classification for heart failure severity.

Adding an ordinal element:

Click on the ordinal element from the toolbar.
Name the element.
Create the desired number of alternatives by using the Edit button.
Add metadata in the description box to elaborate further on the purpose of the element.

Boolean Element

Boolean elements are used when dealing with True or False statements. A similar functionality can be established using the ordinal or text elements, which is often the preferred method of choice. The reason for this is that they provide more flexibility by using other alternatives (yes/no, never/always, 0/1, etc.). The True/False Boolean values cannot be changed and due to limitations in the current software, translation into other languages is not possible. For this reason, Boolean values are only the preferred option if the application does not require the use of text for each option (usually when a checkbox is required).

Adding a Boolean element:

Click on the tick/cross (Boolean) element from the toolbar.
Name the element.
As the Boolean data type only has True/False representation, the available choices are automatically selected upon creation.

Cluster

Cluster is used when it is desirable to group certain components/subcomponents of the clinical concept in question. The asthma predictive index archetype has major and minor criteria; some of the individual data elements have been clustered to reflect this.

Adding a Cluster element:

Click on the cluster element from the toolbar.
Name the element.
Add a description for the element.

A cluster does not in itself hold any textual or numerical value directly relevant to the clinical concept, but rather serves to group the elements of interest that will contain the actual values.

After a cluster has been added, drag and drop the relevant elements (in this example, the ordinal and count elements) on the cluster where they can be further defined as described in the earlier sections.

Alternatively, new element can be added directly to the cluster if the cluster node is selected in the tree first.

Metadata

Archetype Information

Once the archetype has been created, metadata (detailed information about the archetype) should be entered. This includes clinical information, archetype description, clinical definitions, author information, copyright, date of creation, references, contributors, and keywords for the archetype.

To add metadata, click on the Tabbed tab and then on the Header tab in order to fill in the fields:

Concept name
Concept description
Keywords
Purpose
Use
Misuse
References.

Click on the Attribution tab in order to fill in the fields:

Lifecycle (use in_development for new models)
Authorship information
Contributors
Copyright (if relevant)

An example showing how metadata in the Header tab can be formatted:

Authorship

The image below depicts the Attribution tab. Here information about the primary author can be added as well as names and organizations of contributors or co-authors.

References

The image above shows the content of the last section in Header, which is the References section. This is where the archetype’s references are listed. Use the NLM system when listing references.

Languages

To translate the archetype to another language, use the following steps:

Click on the tab Terminology and select the Languages and terminologies tab.
Click on the plus button next to Translation languages list.
On the dialog box click on language field and search for the required language (search using only a language code).
Click Done.

The code of the new language will now be available to the right of the archetype id and the Archetype Designer will automatically switch to it.

Once a language has been selected, click on the Terms tab. This tab contains all of the text that belongs to the elements as well as the model concept name (at0000/Text) and concept description (at0000/Description). Simply replace the English *(en) with the selected language translation in the Text and Description columns for each term.

The metadata can be translated in a similar fashion – navigate to the Header tab and translate the metadata to the selected language.

Once the translations have been added to the archetype, details about the translator are added in the Attribution tab under Tabbed.

Terminology

Once all the metadata (Header and Attribution tabs) and elements (Tree tab) have been created, the underlying allocated at-codes can be viewed by clicking on the Terminology tab and Terms tab as shown in the image below. The the archetype concept name, elements and values are assigned an at-code as shown in the first column, thus creating a structured overview of the data available in the archetype. Therefore, it is highly recommended that this tab is used when translating the elements and values of an archetype.

The Archetype Designer supports binding of the data elements and at-codes to an external terminology set (e.g. SNOMED CT, LOINC). For CDS applications, it is generally avoided binding archetype data elements to external terminology sets from within an archetype. It is preferred instead to perform such bindings within guidelines (GDL applications used in clinical decision support) or openEHR templates.