Archetype Designer - template building manual
- Heather Leslie
- Silje Ljosland Bakke
- Silje Ljosland Bakke (Unlicensed)
Getting Started
Locate the online Archetype Designer at https://tools.openehr.org/designer/
Sign up and log in using Google, Microsoft or GitHub accounts.
Choose a repository
Create a new repository
If you wish to create a new repository, click on the ‘New Repository’ button.
Name your repository and click on the ‘Create’ button.
You will need to add archetypes and templates to the repository.
Open an existing repository
Alternatively, click on the repository name of your choice to open it.
The ADL Designer will open to display a list of the archetypes and templates contained in the selected repository.
Create a new template
Click on the 'New' button and select the 'Template' option.
Select the Rm type (or class)
In this manual we will start the template using the default COMPOSITION archetype as the basis for this template, however a template can be created using any type of archetype.
Select the root archetype id
Select the Encounter COMPOSITION as the container archetype for the template.
Name the template
Type the name of the template in the ‘Template Id field'. In this example, we intend to represent the clinical content in a hypothetical Admission note.
Click on the Create button to create the template, displayed below.
Create the template
Template name
The name of the active template is always displayed in the top blue tab.
In addition, the name of the template is also displayed at the top of the tree form – in this case 'Admission note' with the italicised annotation of NAME (from 'Encounter'), indicating that the Encounter archetype has been renamed for the purpose of creating a new Admission note template.
Note: A star next to the template name indicates that the template has changes that need to be saved.
The 'Definition' tab is the default view for every new template.
At this point the template comprises only the Encounter archetype as the container for future clinical content.
Add metadata descriptions
Select the Description tab
Click on the 'Description' tab to be able to add optional details about the template.
There are two subtabs - Header and Attribution.
Header subtab
Template Id – this can be edited
Lifecycle – select from a dropdown list. This is usually managed automatically within a CKM environment, but may be useful if using within a local governance environment.
Keywords – these can assist in searching for a specific template within a CKM environment
Purpose – the reason for creation of data set
Use – information about how the data set is intended to be use
Misuse – information about circumstances in which the data set should not be used, potentially including information about alternative templates that might be used as a valid alternative
Copyright – this will usually be managed automatically within a CKM environment
Other details – which are usually set within a CKM environment
License
Custodian organisation
Original namespace
Original publisher
Custodian namespace
Attribution subtab
Build Uid – usually automatically generated in a CKM environment
Author name
Organisation
Email
Date originally authored – default is today's date.
Contributors – names and details of all individuals who contributed to the development of the template.
Translators – may be available to add details of translators if the base archetype has translations available.
Adding clinical content
The clinical content is added to the 'Content' SLOT in the tree, one archetype at a time.
Archetypes that are allowed for that SLOT are displayed in the right hand column.
At this location within a COMPOSITION archetype, it is valid to add SECTION or ENTRY classes of archetypes.
Add an archetype
Search for, select and add content
To find a specific archetype type some text into the Search field – either the name of an archetype or the class. In this example, searching for 'adh' results in a single archetype being displayed – the SECTION archetype for 'Ad hoc heading'.
Clicking on any archetype in the right column will insert it into the content area of COMPOSITION container.
Add more archetypes in the same way, with the new archetypes being added one under the other, at the root level of the template.
Clicking on the same archetype multiple times will add multiple instances of the same archetype, all named slightly differently to ensure that there will never be two archetypes with the same name in the template.
Nesting additional content
Click on the ‘Plus' icon so that it turns into a 'Minus’.
This opens up a SLOT in which more content items can be added.
The archetypes that are allowed to be inserted in the SLOT are displayed in the right list. Archetypes that have been identified by the archetype designers as those that are likely to be inserted at this point are indicated by a green icon at the top of the list. Other archetypes that are still allowed are indicated by a grey icon. If no archetypes have been identified as preferred, then all have a green icon.
Refining content
Refining each archetype
Setting archetype occurrences
Identifying valid occurrences
In the 'Ad hoc heading' example, the archetype can be set between 0..1 (optional, single occurrence) through to 0..* (optional, unlimited occurrences).
The actual number of occurrences set in this template is shown at #2.
Changing occurrences to suggested alternative
Clicking on the yellow occurrences option in the below example will set the occurrences to 'zero', effectively removing the archetype instance from the template.
Changing occurrences to another valid alternative
Click on the occurrences field to edit directly:
First number: 0 = optional; 1 = mandatory
Second number: 0 = not active/present in the use case; * = unlimited occurrences; number ≥ 1 will limit the number of occurrences to the number entered.
Click on the 'tick' to save the change.
Rename an archetype
Double click on the archetype name to activate the 'edit' mode. Rename and click on the 'Enter' button to same.
The alternative method is to click on the 'Rename' button in the archetype menu.
Cloning an archetype
Click on the 'Clone' button in the archetype menu in order to create a copy of the archetype, automatically renamed (by adding a number to the end of the archetype concept name) to ensure that there will never be two archetypes with the same name in the template, and including any constraints that have been applied to the original archetype.
Extract as a (partial) template
Click on the 'Extract template' button to be able to be able to save a portion of the template as a separate, reusable partial template.
Delete an archetype
Click on the 'Delete' button to remove an archetype from the template.
Move an archetype up or down the tree
Click on the up or down arrows to move an archetype up or down the tree, relative to surrounding archetypes.
Viewing/navigating data elements in each archetype
Toggle the '+/-' button to view or hide the archetype structure, which can differ between classes of archetypes.
In the example above, each of the 3 archetypes contains data and a protocol. Toggle the '+/-' button next to 'data' to view or hide the 'data' structure. In this example, the Blood Pressure and Pulse/Heart beat archetype contain 2 events – the default 'Any event' and a named, specified event. The Body temperature archetype contains only the default 'Any event'.
Toggle the '+/-' button next to each event to view the data specific for each event.
Toggle the '+/-' button next to the data for each event or each protocol to view the data elements.
Refining each data element
Setting data element occurrences
Changing occurrences to zero occurrences alternative
Clicking on the yellow occurrences option in the below example will set the occurrences to 'zero', effectively removing the archetype instance from the template.
Changing occurrences to another valid alternative
Click on the occurrences field to edit directly:
First number: 0 = optional; 1 = mandatory
Second number: 0 = not active/present in the use case; * = unlimited occurrences; number ≥ 1 will limit the number of occurrences to the number entered.
Click on the 'tick' to save the change.
Setting multiple data elements to zero occurrences simultaneously
It is possible to set zero occurrences on multiple items of data in one operation by holding down the Shift key on your keyboard and selecting a list of data elements, or holding down the Ctrl key and selecting the data elements one by one. Then click on 'Prohibit all' button in the right frame.
Rename a data element
Double click on the data element name to activate the 'edit' mode. Rename and click on the 'Enter' button to same.
The alternative method is to click on the 'Rename' button in the data element menu.
Move a data element up or down the tree
Click on the up or down arrows to move an archetype up or down the tree, relative to surrounding archetypes.
Clone a data element or event
Click on the 'Clone' button in the data element or event menu in order to create a copy of the archetype, automatically renamed (by adding a number to the end of the element name) to ensure that there will never be two elements with the same name in the template, and including any constraints that have been applied to the original element.
Cut and paste a data element
An alternative way to move a data element within the same archetype is to cut and paste.
A data element can be moved by cutting the data element using the 'Cut' button. The data element will appear ghosted
Click on 'Paste' button on the data element located below the new position to move the data element to the new location. The cut data element will be moved to the new position.
Managing run-time name constraints
If a data element name has brackets around it, it means that run-time name constraints have been set in the archetype. Click on the 'Internal codes' button in the right panel to select a name option for this template.
Unselect the option/s that are not required.
The data element will have been renamed to the remaining selected name constraint.