GDL Editor Primer

Download and install the GDL Editor

Before getting started, the GDL Editor (GE) needs to be downloaded and installed. The GE is an open-source, java-based, multiplatform application used to create, edit and run GDL files. GDL files (guides or guidelines) contain the clinical knowledge and application logic required for computerized clinical decision support. Because of its reliance on the openEHR reference model and archetype model, the program is natural language- and reference terminology agnostic. The GDL Editor is used to define sets of rules as well as trigger events based on statements obtained from a reference clinical guideline. In addition to defining guideline rules and triggers, the GE also generates data entry forms based on the underlying archetypes which allow the user to input data that triggers the rules. When integrated with an EHR system, input data can be automatically acquired from the patient records triggering the decision support logic resulting in the relevant guideline-based recommendation.

The GE requires Java Runtime Environment (JRE) 1.6 (or higher), and output files are saved as GDL files. The application is developed and maintained by Cambio Healthcare Systems.

Download the GDL Editor at: http://bit.ly/gdl_editor

Creating the Guideline

After downloading and installing the GDL Editor, the following start up screen will be displayed upon launching the program. The GDL editor will first need to be configured to point to the correct file path that contains the archetypes upon which it relies. To do this, click on Configuration in the menu bar, select Repository and then set the respective folder locations for archetypes and other resource files.

The GDL editor contains nine tabs.

Description: basic information about the guideline.
Definitions: references to the archetypes used in the rules and preconditions.
Rule list: allows managing of all the constructed rules.
Preconditions: a list of required conditions for the execution of a rule.
Defaults: allows for building rules that ensure the model runs smoothly by setting up baseline values.
Terminology: coded mapping for each of the terms used within the guidelines.
Binding: mapping of the local codes used in the guideline to external terminologies.
GDL: the output of the editor in GDL format.
HTML: the output of the editor in HTML format.

Metadata

Under the Description tab, the metadata should be filled in. The available sections are shown in the image below.

Similar to the metadata insertion in the Archetype Designer (AD), one is able to insert the name of the guide, author details, copyright, keywords and contributors, as shown on the left side of the image above. The text fields on the right side of the Description tab, numbered 1-5 above, can be filled in directly. Keywords and contributors can be added by using the plus sign (6). The pencil icon can then be used to edit the entered text.

Once all the metadata is filled in, ensure the model is saved by using the Save guide button.

Definitions Tab

When the Definitions tab is clicked, the following view will be displayed. The right side contains the selection of definitions that can be used in this screen of the editor.

The most commonly used in basic models are:

Archetype instantiation, which is the first item to create as this allows for the GE to assign an already existing archetype required to build the model.
Element instantiation, which is a part of the instantiated archetype allowing specific elements to be assigned from the selected archetype.
Predicate (Function), which is used, for example, to create an event time element which can be used to ensure the values used in the tool are always the most recent.

Archetype instantiation is dragged and dropped into the main modelling area. Upon clicking on Archetype, a window revealing the list of archetypes contained in the configured folder is opened. Here the “Basic Demographic” archetype, which provides data for age and sex etc., has been selected.
Element instantiation is dragged and dropped on top of the already instantiated archetype. When the Element field is clicked, a window opens that allows one to choose the specific element of interest; here “Birthdate” has been selected.
Predicate (Function) is dragged and dropped on top of the instantiated archetype. When the Element field is clicked, a window opens up that allows one to choose the specific element of interest; here, “Event time” is selected. From the drop-down menu max has then been selected; this function will ensure the most recent data from the linked openEHR is used.

Multiple archetypes may be instantiated depending on the model being built. In addition, the same archetype can be instantiated in different formats: EHR domain for input values, and CDS domain for output values. The domain is selected in the window opening upon clicking on Archetype.

In this image, both an EHR and a CDS domain of the “Basic Demographic”-archetype has been instantiated. The EHR contains the birthdate element, allowing users to enter it using the date data type in the GE. There is also the Predicate (Function) element to ensure the model will use the most up-to-date value from the EHR. This instantiation will contain the user input.

The second instantiated archetype is of the CDS domain, containing the age element as displayed. This element is a quantity data type which will allow the model to store the actual age value. The birthdate input along with the current date entry will allow the age value to be calculated using a simple rule.

Rule List

Once all the archetypes have been instantiated, rules can be constructed by heading to the Rule list tab. In order to demonstrate this in a simple way, the two basic demographic archetypes that were instantiated can be used to model a basic rule.

As can be seen from the image above, when one clicks on the Rule list tab, an empty rule area is shown. Upon clicking the Add rule button, the RuleName box opens into which the rule name can be entered.

Once the rule has been named, the editor displays the following editing screen:

The empty modelling area related to the rule can be filled with the conditions listed on the right side of the screen.

In the example above, the rule has been named: “Calculate Age”. The purpose of this rule is to calculate the age of the patient by subtracting the patient’s birthdate from the current date.

There are four comparison conditions:

Compare (DataValue), which allows one to use comparators such as
= (equal to),
!= (not equal to),
> (greater than), etc. to compare elements to a variety of other items.
Compare (NullValue), which allows one to compare an element with a null value.
Compare (Element), which allows one to compare an element with another element.
Compare (Attribute), which allows one to compare an element using its attributes.

There is also an “Element exists” condition, as well as an “Or operator” and a “Not operator”. In addition, there is a “Rule (Fired)” condition that checks whether a particular rule was fired or not as a condition for further triggering.

In order to calculate the age, one condition is required: the Element exists.

Drag and drop the Element exists condition from the Conditions box on the right side into the main modelling area.

Then click on the Element field to choose the element Birthdate:

Next, select exists from the drop-down menu.

The condition: “Birthdate exists” ensures that there is a birthdate input from the EHR or user input before the rule is fullfilled – which is set in the bottom half of the screen.

There are five actions in the bottom half:

-Create (Entry): inserts a new entry into the working memory with the elements defined.

-Set (DataValue): set element with a data value.

-Set (NullValue): set element with a null value.

-Set (Attribute): set element with an attribute value.

-Set (Element): set element with another element.

From the actions panel, the Set (Attribute) is dragged and dropped twice to prepare the actions that will be fired once the condition is fulfilled.

These actions are to set up the age on two attributes that are placed into two instantiated Set (Attribute) entries.

The first attribute will be assigned the Age units as “a” (Latin abbreviation for anno – year):

The Age magnitude attribute, which is calculated from the current date minus the birthdate, is instantiated next:

The calculation is inserted in the following images.

The calculation is added to the Expression editor as shown above.

Clicking on Expression will open the Expression editor window.
From the element list, scroll to the Current element and double-click the year attribute. This fills the “CurrentDate/Time/year” in the editor’s top section.

Add a minus sign after the CurrentDate expression.
Scroll to the Birthdate element from the list on the right and double-click year to insert it into the expression editor. The full calculation (Current date – birthdate) expression appears at the bottom in the Expression viewer in a more human-readable form.
Once the full expression has been entered, click on Accept.

The full Calculate Age rule with its conditions and actions is shown above, and reads:

“If Birthdate exists, set Age to Current date minus Birthdate in years”

Once the rule has been completed, ensure the model is saved.
Exit the rule tab and return to the main screen.

Executing the Rules

The created rule appears in what was the empty space in the main Rule List screen as shown above. We can now test that the rule works using the Run button.

When one clicks the Run button, the panel shown opens to allow input.
Fill in the birthdate by clicking on the calendar icon and select the date of birth (bottom right). Then select the current date for the event time field.
Click on Execute.

The result is shown below – Age 40 years:

Examples of other conditions and actions are shown in the next images.

Rules that describe a range condition:

In the image above, two Compare (DataValue) condition elements are dragged and dropped into the top half of the modelling area for a rule named: “Set age between 16 years and 45 years: Yes”.

The Age element of the Basic demographic archetype in the CDS format (as it has been calculated from the birthdate as shown in the earlier part of this guide) is selected for the element types and the age: 16 years is inserted into one of them, whilst the age 45 years is inserted into the other. As the condition is an age range, greater than and less than operators are used as shown in the series of images below:

Choose the Age attribute in the first slot on both elements.
Select the <= symbol in the first drop-down menu.

The first condition is Age <= 45 years as filled in on the image; “a” is “anno” which is Latin for year.

The second condition is added in the same way and both are shown in the image below:

In order to enable a rule, we need to drag and drop an action from the right as shown. However, our model is lacking an archetype that can hold the results of the condition we set in the top half of the screen, namely what to do with a value that is in the range as indicated. Thus, to do this, we would need to create/instantiate a slot of an archetype that would be able to hold this result. If we go back to the Definitions screen of the GE, we can add an archetype (here we added the “Opioid Risk Tool” archetype) which requires an ordinal slot that handles age ranges. This is shown below:

Thus, we are now able to allocate the result in the Action (bottom) part of the rule list:

Click on Element.
Select Age 16-45.
Click on Accept.

Click on DataValue.
Select Yes from the drop-down (as this rule will fire if the age is calculated as between 16-45).
Click on Accept.

The complete set of conditions and actions are shown below.

Once the rule is complete, one can trial run it:

Click on Run in the top row.
Select the birthdate and current date.
Click on Execute.
The results are produced below; the model checks that the age (30yrs) is between 16 and 45 and sets Age 16-45 to the ordinal value of Yes.

Next, how to use the “Or” and “Not” operator conditions will be covered. The rule shown below for the “No” ordinal value can be translated into “Age is less than 16yrs or above 45 yrs”, which can be modelled with the Not operator (Not between 16 and 45) or with the range as mentioned: <16yrs or >45yrs. The Or operator is used in this example:

Drag and drop the Or operator into the conditions area.
Insert the age conditions into each or slot.
Set the age 16-45 action to No.

Most basic guideline models do not require any further steps, but more complex models set constraints in the Preconditions tab, which is the next tab along. This function provides a way to limit rule firing until a certain condition has been met.

The Defaults tab contains rules that set baselines. For instance, the order of firing of rules is important in the GE as it runs from top to bottom, and if a user inputs a field but skips a previous one, the model may not fire at all. Thus, setting default values helps to ensure the model passes through all the rules to provide responsivity to the model and a baseline or neutral result is issued once the Execute button is pressed. These baseline values can be an ordinal of 0 as either NA (Not available) or the tag attached to a zero value – usually “No”. The Opioid Risk Tool used earlier has more ordinals than the age range used above. The image below displays how some of these ordinals would be set to “No” as a baseline default value in the Default tab:

The Terminology tab works in a similar fashion to the tab of the same name in the Archetype Designer and contains codes similar to the at-codes explained in the archetype guide. Here they are called “gt-codes” and resemble the image below:

The Binding tab and associated Add Binding button allows for the binding or mapping of codes from other code systems such as ICD10 (International Classification of Diseases 10^th Edition). Again, this is discussed in more detail in later examples that utilizes this function.

The last two tabs, GDL and HTML, displays the model in either GDL or HTML format, which is close to displaying the guideline in a presentable web-based form. These screens are shown below:

GDL:

HTML:

This is the end of the basic GDL Editor guide. Tutorials with step-by-step instructions using existing models for demonstration are provided on the website cds-apps.com.