An open domain-driven platform for developing flexible e-health systems
About this Website | Wiki | Jira | CKM

Getting Started

Overview

Two resources need to be configured at first time used of the ADL Workbench. The first is the 'reference models' (RMs) which are imported in the form of schema files expressed in the openEHR 'basic meta-model' (BMM) format. Multiple RMs can be imported, enabling comparison of models, classes as well as archetypes based on different models.

The second resource that must be configured is the 'profiles' that define where archetypes and templates are to be found.

Basic Configuration

Setting RM Schemas

At installation, the AWB is normally set up to point to a set of reference model schemas copied from the openEHR reference models Git repository. You may want to check which Reference Model schemas are enabled initially. Choose RM Schemas > Configure Schemas to do this. The dialog looks as follows.

Options dialog

You can check all RM schemas that apply to archetypes in any repository you might define. The only time you would leave a schema unchecked is if you have more than one version of the same schema and you want to choose a specific one. Several RM schemas are provided with the AWB, which are copies of the controlled versions found in the openEHR/adl-archetypes GitHub repository. See the Tool Configuration section for details on configuring RM schemas.

Setting up archetype repositories

The first time you start the tool if you are a new user, you will be asked for a repository. The following dialog will appear:

This page describes how to proceed.

Using the Tool

Docking

The AWB layout is docking-based, which means that the key components are all dockable 'tools'. This screenshot shows multiple editor tabs, the Catalog tool, and various minimised tools at the bottom and right hand side. Docking can be used to arrange editor tools side by side, as shown here, and to 'pop' a tool out into an independent window, as shown here.

In general, docking is controlled in the normal way for the platform you are working on, e.g Windows, or the various GUI toolkits used on Linux and MacOS.

General layout

The AWB has two facilities, the archetype compiler/viewer and the 'tester'. The main form shows the compiler/viewer, while the tester is normally minimised to the right. The Viewer looks as follows.

Expanded view in explorer

Overview

Initial view in explorer

Overview with RM icons

Archetype and Template Catalog

On the left side of the tool are two explorers, making up the 'Catalog' tool in AWB. The upper one is used to navigate all archetypes and templates, within the class hierarchy of the reference model on which the archetypes are based. Reference and working repository artefacts are merged in this view, and colourised so that the origin remains visible. The 'show entire ontology' option on the options panel can be used to force all classes in the hierarchy to be shown rather than just those which have archetypes in the current repository. Archetypes that appear below other archetypes are either specialisations, templates or template components. (Remember that the latter artefact types are technically just specialised archetypes.)

The lower explorer is used exclusively for templates and template components, and shows compositional relationships due to slot-filling, rather than specialisation in its hierarchy. The two explorers are linked, so that choosing an artefact node in the lower one automatically chooses the same artefact in the upper one, allowing its lineage to be visible.

Reference Model Browser

A second tool available on the left side of the main screen is the Reference Model (RM) browser. This enables multiple reference models to be visualised and explored in detail. Each reference model that is loaded has its package and class structure shown as a tree. Since RM schemas can be nested, classes may come from different schemas. Right-clicking on a class enables the original schema in which a class was defined to be edited.

Archetype Tool


Classes can be viewed from different reference models, in a side-by-side fashion by using the docking controls, as shown here.

Reference Model Tool

In the Reference Model schema browser, the context menu of each schema includes an option for viewing the schema. When selected, this view shows the schema meta-data in a tool in the same area as the Archetype and Class Tools.

The Address Bar

At the top of the tool is an address bar that can be used to search for either elements of reference models, e.g. classes, or archetypes, depending on which of the Archetype/template catalog or RM browser is in focus.

Archetype and Class Tool area

The middle area of the screen is dedicated to viewing archetypes, templates and browsing the reference model. Two types of tool are used for this - the Archetype Tool and the Class Tool. Any number of each tool can be launched. The first Archetype Tool starts just by left clicking on an archetype or template in the Catalog. New Archetype Tools are launched by right-clicking and selecting 'New Tool' from the context menu. The same applies to starting a Class Tool - just left or right-click on a Class in the Catalog area.

The Archetype Tool

The Archetype Tool enables a single archetype to be visualised in many ways. In the toolbar, the 'view' controls (to the right of the Archetype id text box) allow selection of differential and flat views. With one of these selected, the notebook tab controls allow viewing of the following aspects of an archetype:

Archetype Tool


  • Description view: the Administrative and Descriptive meta-data of the archetype, as well as the terminology binding summary;
  • Definition view: a 'node map' visualising the formal definition of the archetype, including various controls on the right side;
  • Paths view: all paths extracted from the archetype, with various controls for fine-tuning the view;
  • Slots view: a two-part view, consisting of:
    • the slots in the archetype, with the archetypes from the rest of the repository that match the slot constraints;
    • other archetypes whose slots the current archetype can fill;
  • Terminology view: a structured view of the ontology section of the archetype or template, including term bindings and ref set bindings;
  • Annotations view: a structured view of archetype annotations, for those archetypes that include them;
  • ADL view: a view showing the ADL text in either the source differential form or of the generated flat archetype.

The Class Tool

The class tool is designed to allow the user to explore the reference model starting from a given class. It provides 4 views: properties, ancestors, descendants and closure. The Properties view shows all properties defined in the class and its ancestors, grouped on the basis of the class in which each property was declared in. This is known as the 'flat' view of the class.

The Ancestors and Descendants views show the inheritance tree above and below the focal class, including multiple inheritance.

The Closure view displays the properties and allowing the user to navigate through the entire property reachability closure by clicking open attributes at will. Because this computation is resource-intensive, the user can regulate the depth of the closure to explore. This means that the closure will in general only be partially computed, and it is up to the user to right click on terminal nodes they want to expand.

Since the reference model includes numerous attributes whose static type is either abstract or otherwise has descandants, the Closure view allows the user to choose to display these by right-clicking on a node.

Class Tool properties view

Properties

Ancestors view

Ancestors

Descendants view

Descendants

Closure view

Closure

Using the ADL Workbench with the Archetype Editor

You can use the ADL Workbench as a convenient way to launch the Archetype Editor on individual archetypes. The AWB provides an easy way to see all archetypes, as well as performing ADL 1.5 validation, not currently available in the Archetype Editor. Firstly, download the Archetype Editor, and then configure it as the editor for archetypes, as described here.

Artefact overview

The ADL Workbench is designed to parse and validate archetypes. Technically speaking, 'archetypes' are any artefact conforming to the openEHR Archetype Definition Language (ADL) and Archetype Object Model (AOM) specifications (see lower part of the specifications page), or the older EN13606-2 specification, which is a snapshot of the openEHR AOM 1.4 specification. The latest ADL 1.5 specification defines 4 logical kinds of artefact. These include three kinds of archetype, and the 'operational template'. The latter is generated from a template, and is used as the basis for all further downstream transformations. The various artefact types and their file formats are shown below.

Artefact type Description Source file types Flat file type
archetype a theme-based definition of multiple data points/groups, using the archetype constraint formalism .adls (ADL 1.5)
.adl (ADL 1.4)
.adlf
template a use-case specific definition of content, consisting of data items from various archetypes .adls
template_component a component of a template .adls
operational_template the inheritance-flattened form of a template, used as the basis for all further transformations
.opt

Acknowledgements: Atlassian (Jira, Confluence) | NoMagic (MagicDraw UML) | AsciiDoctor (publishing) | GitHub (DVCS) | LAMP dev community