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

Open

then login

Create and populate a new repository

Create a new repository

To create a new repository, click on the ‘New Repository’ button.

Open

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

1. Template name

   1. The name of the active template is always displayed in the top blue tab.

   2. 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.
      
      

2. The 'Definition' tab is the default view for every new template.

3. 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

1. 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'.

2. 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

1. Click on the ‘Plus' icon so that it turns into a 'Minus’.

2. 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

1. In the 'Ad hoc heading' example, the archetype can be set between 0..1 (optional, single occurrence) through to 0..* (optional, unlimited occurrences).

2. 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