Guideline Migration Tutorial


This tutorial provides a step-by-step demonstration on how to migrate a guideline created in the GDL1 editor to the GDL2 editor format. The tutorial includes all steps taken to migrate the guideline CHA2DS2-VASc.v1 and explains how to deal with mismatches between the platforms including cases caused by:

  • EHR/CDS/INPUT/OUTPUT domain mapping mismatches
  • Non-instantiated elements used as predicates
  • The Event time attribute value

The tutorial also includes a section for how to create a test fixture for the migrated guideline.

Import guideline from GIT Repository

1 – Click on “Guideline” in the menu and choose “Import Guideline from GIT Repository”.

2 – Choose the GitHub common-clinical-models repository

3 – Click on “Next”.

4 – Select the master branch.

5 – Select a guideline and click on “Import guideline”.

Ensure correct migration regarding domains

In GDL1, the domains used were EHR and CDS, where data elements recieved from the electronic health record were in the EHR domain and data elements that had been processed by the guidelines were in the CDS domain. So in cases where the output of one guideline is used as input of another guideline, for example when assessing a calculated score, both data elements would be in the CDS domain. 

In GDL2, all incoming data elements are in the INPUT domain and all guideline processed, outgoing data elements are in the OUTPUT domain. In most cases, INPUT correspond to the GDL1 domain EHR and OUTPUT correspond to the GDL1 domain CDS, and this mapping is carried out automatically when a GDL1 guideline is imported in the GDL2 Editor



However, in the abovementioned cases where the output of one guideline is used as input of another guideline and both data elements are in the CDS domain in GDL1, this will be mapped as both data elements being in the OUTPUT domain in GDL2 and manual editing is needed in order to move the correct data element to the INPUT domain.

6 – Make sure input data elements are in the INPUT domain and output data elements are in the OUTPUT domain.

7 – Go to the Execution tab and press “Refresh” to see that all data elements of the INPUT domain have corresponding input fields for the execution.

Here, two Event time fields are missing. 

When trying to execute the guideline and error occurs, which is shown by the exclamation mark on the “Execute” button. This is due to the Event time being used as a predicate without having been instantiated as a data element. 

Instantiate elements used as predicates

8 – Go to the Definitions tab and instantiate the Event time element in all archetypes using Event time in the Function Predicate. If there are predicates for other elements that are not yet instatiated, instatiate them as well.  

9 – Go to the Execution tab, click on Refresh and verify that the newly added Event time elements exist

10 – Fill in all input fields and execute the guideline. In this case there is another error. When hovering over the execution button, an error message appears indicating error with the attribute value for variable currentDateTime. This is due to a difference between GDL1 and GDL2 where GDL2 does not use the attribute value for DateTime elements.

Remove the attribute “value” from currentDateTime elements

11 – One way to solve the attribute value issue is to save the modified guideline and open it in an editor (for example Notepad++ as used in this tutorial) and search the file for “.value” or “currentDateTime.value”. 

12 – Remove the attribute value from the currentDateTime variables only. Do not remove “.value” from other variables, see second image below

DO NOT remove above shown “.value”.

Re-import the updated file and verify changes

13 – Save the file locally and import it in the editor. Execute the guideline and verify the results. Some cases for execution are not yet fully implemented in the GDL2 editor, such as camparison using “==” and using decimal values as input. This is however supported in the underlying engine and can be tested using the Test tab. 

Test the guideline using the Test tab

14 – Copy the generated test fixture in the Execution tab.

15 – Paste the test fixture into the Test tab, click on Execute to verify the test passing.

Create a test fixture

16 – The test case can be renamed from “case_1” to something more descriptive.
In this case “female_65-74_all_diagnoses_score_8”, to summarize the input and output values

17 – More test cases can be added following the structure of the first one to test multiple variations simultaneously. 

18 – Click on the “Save” button in the Test tab to save the test fixture as a .yml file. 

19 – Now the test fixture can be re-uploaded and run whenever needed.