Archetype Designer Guide for UCL Standards & Interoperability Course
- 1 Getting Started
- 2 Create and populate a new repository
- 3 Open an existing repository
- 4 Create a new template
- 5 Add metadata descriptions
- 5.1 Select the Description tab
- 5.1.1 Header subtab
- 5.1.2 Attribution subtab
- 5.1 Select the Description tab
- 6 Adding clinical content
- 7 Refining content
- 7.1 Refining each archetype
- 7.2 Viewing/navigating data elements in each archetype
- 7.3 Refining each data element
- 7.4 Refining per data type
- 7.4.1 Free text
- 7.4.2 Coded text
- 7.4.3 Quantity
- 7.4.4 Proportion
- 7.4.5 Count
- 7.4.6 DateTime
- 7.4.7 Ordinal
- 7.4.8 Boolean
- 7.4.9 Choice
- 7.4.10 Any - unspecified data type
- 7.4.11 Duration
- 7.4.12 Hide removed items
- 8 Open an existing template
Getting Started
These instructions will give an overview of using the Better Archetype Designer, archetype/template tool, adapted from the generic Template Building guidance .
Archetype Designer is an online web-browser based product that will work on most browsers. Google Chrome or Mozilla Firefox are recommended and some versions of Internet Explorer may not work correctly.
Locate the online ADL Designer at https://tools.openehr.org/designer
Create an account using one of the social media accounts e.g Google, Microsoft or or GitHub
then login
Create and populate a new repository
Create a new repository
To create a new repository, click on the ‘New Repository’ button.
Choose Local Folder for 'Repository type', name your repository and click on the ‘Create’ button.
You will need to add archetypes and templates to the repository.
Import archetypes and templates from another repository
Although you can start to create your own archetypes and templates from scratch, it is much more common to import a set of existing archetypes and templates to re-use or adapt.
We suggest that you Import a pre-built set that has been developed for this course.
These are held on the Apperta Clinical Knowledge Manager (CKM) tool. This is a tool used to discuss, curate and publish archetypes and templates pertinent to the UK. It makes use of a number of models drawn from the openEHR International CKM, a number of which are used in the pre-built set which you are about to import
Click here and you will be taken to
Press the ‘Export Resources (Zip)’ button and download the zip file onto a folder on your machine.
Choose the ‘Import’ option at the top of the Archetype Designer screen and you will get this dialog which allows you to select the zip file that you downloaded from CKM , or drag and drop onto the grey dropspace.
Ensure that ‘Import concepts with warning’ is unticked and ‘Overwrite existing’ is ticked.
Now press ‘Upload’ or ‘Upload all’. The zip file will now be uploaded and imported.
Make sure you wait until the Status Icon appears - it should be a Green tick.
One the Status icon has appeared you can press ‘Close’.
You should now see the repository populated with a number of archetypes and templates.
At a later stage you may create more than one repository if you wish e.g. one for experimentation, one for F2F training, one for coursework.
Click on the ‘Repositories’ option at the top of the screen. This will list all of the repositories within your account. Unless you have done further work, you should only see the repository you have just created.
Open an existing repository
Now click on on your new repository name 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. When you save a template, it will ask you to provide versioning information - you can just accept whatever suggestion is given.
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 a data element up or down the tree, relative to surrounding data elements.
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 data element or event, 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.
Refining per data type
Free text
Add a set of values to a free text data element
It is possible to add a value set to a free text data element in a template.
Click on the 'Edit values' button.
Add values, and click on the 'Enter' key to move to the next field.
Click on the 'Save' button to save the new value set.
It is also possible to add many values at once by copying an existing list of values separated by line breaks, and pressing pasting them into the first new value field
Bind a value set to a data element
Select 'External coded' option in the right panel. Add a terminology name to the 'Terminology' field. This can be a terminology such as 'ICD-10' or 'SNOMED-CT', or a local code set. Local code sets must have unique names.
Either enter a valid URI to refer to an externally-defined encoded value set, or select 'Add Valueset' to add a locally encoded set of values in the template.
Coded text
Restricting predefined set of values
It is not possible to add or rename preexisting values from an archetype, however it is possible to 'disable' values, effectively setting them to zero occurrence. Unselect the values that are not required by removing the 'tick'.
Quantity
Constrain the available units
The available units in a Quantity data element are displayed in the right panel. It is possible to disable units in the template if they are not relevant. Uncheck unwanted units.
Set limits on values in a sheet type. Change Max and Min values
The maximum and minimum attributes of a unit in a Quantity data element are displayed in the right panel. It is possible to add constraints or to adjust the minimum and maximum values where the archetype has already set values.
Proportion
Select the type of proportion if this has not already been set in the archetype.
If previously set in the archetype, a new type of proportion cannot be added.
If multiple choices for the type of proportion were present in the archetype, it is possible to deselect one or more as long as at least one type remains selected.
Addition of the default values for the numerator and denominator are able to be added for proportion types that have these attributes.
Count
If no minimum or maximum values were set in the archetype, then values can be set for each.
If previously set in the archetype the minimum and maximum values can be further constrained but not loosened. The minimum value can be raised and the maximum can be reduced.
A default value can also be set in the template.
DateTime
If the default ‘Any Date’ type was unconstrained in the archetype, then the DateTime data type can be further constrained to ‘Full date’, ‘Partial date’ or ‘Partial date with month’.
If the type was previously set in the archetype only ‘Partial date’ can be further constrained to ‘Partial date with month’. A specified type cannot be loosened back to ‘Any Date’ in the template.
A default value can also be set in the template.
Ordinal
It is not possible to add new ordinal values in the template, but it is possible to remove ones that are not required for the use case.
A default value can also be set in the template.
Boolean
If both of the ‘True’ and ‘False’ values are available in the archetype, then it is possible to constrain it further in the template by removing one option.
If only one option is available in the archetype, then it is not possible to modify this in the template.
A default value can be set in the template.
Choice
The ‘Choice’ data type is actually an set of two or more data types made available in the archetype. It allows for a selection of one or more of those selected data types to be made available in a template.
Remove unwanted data types by clicking on the 'X' in the right panel.
Set constraints for each available type using the ‘Types’ drop-down list.
It is possible to set the default value for each data type in the template.
Any - unspecified data type
The ‘Any’ data type is actually an unconstrained set of all data types made available in the archetype. It allows for a selection of one or more data types to be made available in a template.
Remove unwanted data types by clicking on the 'X' in the right panel.
Set constraints for each available type using the ‘Types’ drop-down list.
It is possible to set the default value for each data type in the template.
Duration
If the duration data type has been unconstrained in the archetype, it is possible to select specific time units by deselecting the checkbox for ‘Allow all time units’ and to set minimum and maximum values for the lowest value/unit combination and highest value unit combination - for example, 0 seconds to 100 years.
It is possible to set the default value and units.
Hide removed items
To get an overview when building a template, it can be useful to hide items that have been set to zero occurrence in the template. Click on the 'Hide removed nodes' button in the top panel to visually remove all data elements set to zero occurrence.
Open an existing template