GDL2 Guideline Tutorial IV – BSA 

After you have created your first calculator and learning how to adapt your calculator to be used in an EHR, it is time to create your first guideline from scratch. Here we create a guideline to calculate Body Surface Area (BSA). The structure of the BSA calculator is very similar to the MAP calculator except that it uses three archetypes (two input and one output). Since in the following example we are using standardized archetypes available in this folder, we recommend to compress the folder’s content into a zip file and use this file going forward.

After creating the zip file and starting the GDL Editor in Docker (if not already running) you can start creating your first guideline from scratch using the following steps.

0. Start the GDL Editor (if not yet running) or click Guideline > Create new guideline (if the Editor is already running).

  • If the Editor is not running start Docker and type docker run -p 8080:8080 cdsplatform/gdl2-editor:2.4.4 command in it. This will start the GDL Editor in the background.
  • After Docker started Docker in the background (10-20 seconds), you should be able to access GDL Editor in any browser on your computer. Type: http://localhost:8080/gdl2-editor/ or http://192.168.99.100:8080/gdl2-editor/ into your browser depending on your configuration. If neither link works, it is possible the IP address (i.e. the first 4 numbers) might be different depending on your environment. You can see what IP address you should use by checking the initial screen of Docker (you can scroll up in the terminal if it already disepeared)
  • If your Editor is already running click on the Guideline > Create New Guideline menu item (see screenshot).

    Screenshot about creating a new guideline in the Editor

    Screenshot about creating a new guideline in the Editor. To create a new guideline click on the Guideline > Create New Guideline menu item (red box).

  • This will show a dialog box asking for your confirmation. If you have all your previous work saved click on the Upload file button. If you forgot to save anything click on the cross sign to cancel the upload. You can continue to create your new guideline by repeating the previous step after saving your work.

    Dialog box when creating a new guideline in the Editor

    Dialog box when creating a new guideline in the Editor. The Editor asks you whether to continue (all unsaved changes will be lost). Make sure all your previous work is saved. If yes, click on the check mark (red box).


1. Import the zip file using the Guideline > Import Archetype/FHIR Profile menu item.

  • Click on the Guideline > Import Archetype/FHIR Profile menu item (see screenshot).

    Location of the Import Archetype/FHIR Profile menu item

    Location of the Import Archetype/FHIR Profile menu item. To import archetypes click on this menu item.

  • Click on the Upload file button in the dialog box.

    Dialog box when importing Archetype

    Dialog box when importing Archetype. To continue click on the Upload file button in the dialog box.

  • Choose the zip file you have created and click on the Open button in your OS language.

    Dialog box for file selection

    Dialog box for file selection. To import all archetypes choose the zip file you have created and click on the Open button in your OS language.

  • This will load all the archetypes inside the zip file. While the archetypes are loading you will see the following screen. When this screen disepears you can continue to use the Editor.

    Screenshot when loading archetypes

    Screenshot when loading archetypes. While the archetypes are loading you will see the following screen. When this screen dissepears you can continue to use the Editor.


2. Fill the Description tab by naming your guideline Body Surface Area and optionally filling the other fields in the Description tab.

On the Description tab in the editor you can write some description about your project. It is recommended that you fill in most of the fields on this page (a possible fill can be seen here). While you are learning, you can leave out most of the fields except the name field, which is obligatory to fill in. We recommend to give a name which makes sense. Here we use Body Surface Area as this project is meant to calculate Body Surface Area.

Screenshot about the filled Description tab.

Screenshot about the filled Description tab. Name (red box) is obligatory, other fields can be left empty although it is recommended to fill the fields within the yellow field.


3. Instantiate openEHR-EHR-OBSERVATION.height archetype as input with a Height/Length element and Event time being max.

  • Start the instantiation by dragging the archetype instantiation button to the INPUT entities field.
  • To choose what file to instantiate click on the Data binding label.
  • To choose which archetype to instantiate, look for openEHR-EHR-OBSERVATION.height.v1 archetype. Since you will see many archetypes in the dialog box, it is worth to filter them by name. Type height in the Filter field and you will see only the relevant archetypes. Click on the openEHR-EHR-OBSERVATION.height.v1 archetype and then click on the check mark

    Dialog box to choose the archetype to instantiate.

    Dialog box to choose the archetype to instantiate. You can search for the archetypes typing inside the Filter field (green box). You can choose the desire archetype by clicking on it in the main window in the dialog box (i.e. height can be selected by clicking within the yellow box). To confirm your selection click on the check mar (red box).

  • To start to instantiate Height/Length as input data, drag the Element instantiation button to the newly instantiated archetype.

    Screenshot about initiating Height/Length as input.

    Screenshot about initiating Height/Length as input. To start to instantiate Height/Length as input data, drag the Element instantiation button (red box) to the newly instantiated archetype (yellow box).

  • Click on the Element label in the new row in the archetype.
  • It will open a dialog box. In the element selection dialog box, select Height/Length element and then click on the check mark.

    Dialog box to select the input element.

    Dialog box to select the input element. In the element selection dialog box, select the required element (yellow box) and then click on the check mark (red box).

  • To start to instantiate Event time, drag the Element instantiation button to the newly instantiated archetype.
  • Click on the Element label in the new row in the archetype.

    Screenshot about instantiating Event time for height.

    Screenshot about instantiating Event time for height. First, drag Element instantiation to the height archetype and then click on the Element label (red box) in the new row

  • It will open the same dialog box as earlier. In the element selection dialog box, select Event time and then click on the check mark.

    Dialog box to select the Element

    Dialog box to select the Element. In the element selection dialog box, select Event time(yellow box) and then click on the check mark (red box).

  • Drag the function predicate button to the newly instantiated archetype.

    Screenshot about how to tell the Editor to choose the latest measurement in the EHR.

    Screenshot about how to tell the Editor to choose the latest measurement in the EHR. To start drag the function predicate button (red box) to the newly instantiated archetype (yellow box).

  • Click on the Element label in the row starting with “f with Element”.

    Second step of telling the Editor to choose the latest measurement in the EHR

    Second step of telling the Editor to choose the latest measurement in the EHR. To continue click on the Element label in the row starting with "f with Element".

  • This will show you an Element selection dialog box. In the element selection dialog box, select Event time and then click on the check mark.

    Dialog box to select the Element

    Dialog box to select the Element. In the element selection dialog box, select Event time(yellow box) and then click on the check mark (red box).

  • Select max in the drop down list to tell the Editor that the calculation needs the latest measurements (i.e. with the maximal Event time).

    Last step of telling the Editor to choose the latest measurement in the EHR

    Last step of telling the Editor to choose the latest measurement in the EHR. To finish select max in the drop down list (red box) to tell the Editor that the calculation needs the latest measurements (i.e. with the maximal Event time).


4. Instantiate openEHR-EHR-OBSERVATION.body_weight archetype as input with a Weight element and Event time being max.

  • Repeat the steps inside step 3 replacing openEHR-EHR-OBSERVATION.height with openEHR-EHR-OBSERVATION.body_weight and Height/Length with Weight.
  • After finishing all the steps. You should see the following screen.

    Screenshot after finishing instantiating body_weight.

    Screenshot after finishing instantiating body_weight. You can check the result within the red box.


5. Instantiate openEHR-EHR-OBSERVATION.body_surface_area archetype as output with a Body Surface Area output.

  • Start the instantiation by dragging the archetype instantiation button to the OUPUT entities field.

    First screenshot about defining the output

    Screenshot about initiating Body Surface Area as output. To start to instantiate BSA as output data, drag the Archetype instantiation button (red box) to the Output enteties field (yellow box).

  • To choose what file to instantiate click on the Data binding label.
  • To choose which archetype to instantiate, click on the openEHR-EHR-OBSERVATION.body_surface_area.v1 archetype and then click on the check mark.
  • To start to instantiate Body Surface Area as output data, drag the Element instantiation button to the newly instantiated archetype.
  • Click on the Element label in the new row in the archetype.
  • It will open a dialog box. In the element selection dialog box, select the required element (Body Surface Area) and then click on the check mark.
  • After finishing all the steps you should see the following screen.

    The definition of the output

    The definition of the output. After completing all the steps for defining the output you should see this definition (red box).


6. Create a rule named BSA calculation which sets the magnitude attribute of Body Surface Area according to the Dubois BSA formula.

  • Click on the Rule list label to open the tab.

    The location of the Rule list label in the Editor

    The location of the Rule list label in the Editor. To open the Rule list tab click on the Rule list label (red box) in the Editor.

  • To add a new rule click on the Add new rule label.

    Screenshot about adding a new rule

    Screenshot about adding a new rule. To add a new rule click on the Add new rule label (red box).

  • To name the new rule type the name of the rule inside the Name field then click the mark. Here we name the rule Calculate BSA.

    Dialog box about naming the new rule

    Dialog box about naming the new rule. To name the new rule type the name of the rule inside the Name field (yellow box) then click the mark (red box). Here we name the rule Calculate BSA.

  • To start to create the calculation rule, drag the Set Attribute button to the Rule actions field. You can adjust the layout of the screen, by dragging the line between the frames.

    First step to enter the Dubois BSA formula into the Editor

    First step to enter the BSA formula into the Editor. To start to enter the formula drag the Set Attribute button (red box) to the Rule Actions field (yellow box). You might have to scroll down to the Set Attribute button. To avoid this you can adjust the layout of this tab by dragging the vertical bar (highlighted with a green line) in it.

  • After dragging the Set Attribute button to the Rule actions field continue the rule creation by clicking on the Element@attribute label in the new empty rule.

    Screenshot about creating the rule for BSA Calculation

    Screenshot about creating the rule for BSA Calculation. After dragging the Set Attribute button to the Rule actions field continue the rule creation by clicking on the Element@attribute label (red box) in the new empty rule.

  • Select which output data you want to set with your calculator. Select the @magnitude attribute below the Body Surface Area archetype and confirm your selection by clicking the check mark sign.

    Dialog box to select the attribute

    Dialog box to select the attribute. To continue the rule creation you have to select which output data you want to set with your calculator. Select the @magnitude attribute (yellow box) below the Body Mass Index archetype and confirm your selection by clicking the check mark sign (red box).

  • The formula for Dubois Body Surface Area is:
    BSA = Weight^0.425*Height^0.725*0.007184
    To enter the mathematical formula the Editor should calculate click on the Expression label.

    Screenshot about setting the mathematical formula

    Screenshot about setting the mathematical formula. To enter the mathematical formula the Editor should calculate click on the Expression label (red box).

  • To use an input data in the formula, select it from the list on the right side of the dialog box. First, select the @magnitude attribute of Weight.

    Screenshot about using input data in the formula

    Screenshot about using input data in the formula. To use an input data in the formula, select it from the list on the right side of the dialog box. Here we select the @magnitude attribute (inside the red box) of Weight.

  • After double-clicking an element in the right side of the panel, it will appear inside the expression editor.

    Screenshot showing the result of selecting an input data

    Screenshot showing the result of selecting an input data. After double-clicking an element in the right side of the panel, it will appear inside the expression editor (see red box).

  • After you have Weight in the expression editor start to complete the expression by writing a ^ symbol (exponent), the number 0.425 and a * symbol (multiplication). 

    Screenshot about editing the expression

    Screenshot about editing the expression. After you have Weight in the expression editor write a ^ symbol, the number 0.425 and a * symbol in the editor.

  • Insert the Height/Length magnitude after the multiplication symbol by searching for the @magnitude attribute below Height/Length and double clicking on it. Follow up by writing a ^ symbol and the number 0.725. 

    Screenshot about inserting Height/Length into the expression

    Screenshot about inserting Height/Length into the expression. To insert Height/Length search for the @magnitude attribute below Height/Length (red box) and double click on it. Then write a ^ symbol and the number 0.725 in the editor (yellow box).

  • To complete the expression, write a * symbol (multiplication) and the number 0.007184. After doing the adjustments you should have the same expression in the expression editor as in the screenshot. To save this expression click on the check mark.

    Screenshot about completing the expression

    Screenshot about completing the expression. To complete the expression write a * symbol and the number 0.007184 (red box).


7. Use the Execute tab to check your guideline.

  • To test whether the formula works correctly click on the Execution label in the second row of the Editor.

    Screenshot showing the location of Execution label

    Screenshot showing the location of Execution label. To test whether the formula works correctly click on the Execution label (red box).

  • In the execution tab, click on the Refresh button to see the guideline you have made.

    Screenshot about the Execution tab when opened

    Screenshot about the Execution tab when opened. To continue with the execution tab click the Refresh button (red box).

  • Enter meaningful data inside the Execution tab, choosing arbitrary times for Event time (using the calendar icon next to the respective input fields). A possible fill can be seen in the screenshot. To continue click on the Execute button.

    Screenshot about entering data in the Execution tab

    Screenshot about entering data in the Execution tab. To test your formula enter meaningful data inside the Execution tab, choosing arbitrary times for Event time (using the calendar icon next to the respective input fields). A possible fill can be seen in the screenshot (inside yellow box). To continue click on the Execute button (red box).

  • After successfully executing your guideline, you will see the result inside the execution results field. The body surface area (without decimals) is shown within this field.

    Screenshot showing the result of the execution

    Screenshot showing the result of the execution. After successfully executing your guideline, you will see the result inside the execution results field. The body surface area is shown within this field (see red box).


8. Save your guideline as BSA.v0 .

  • To save your guideline click on the Guideline > Save Guideline to a File menu item.

    Screenshot about saving your guideline

    Screenshot about saving your guideline. To save your guideline click on the Guideline > Save Guideline to a File menu item (red box).

  • A dialog box will ask you to name your guideline. Write a name to the File Name field, we recommend using BSA.v0. To confirm your choice click on the check mark .

    >Screenshot about naming your file

    Screenshot about naming your file. To name your file write a name to the File Name field (yellow box), we recommend using BSA.v0. To confirm your choice click on the check mark (red box).

  • Depending on your browser and your browser configuration your browser might show a dialog box asking to confirm that you want to save. If it does, make sure Save file is selected, then click on the OK button. The screenshot shows an example where this happened while creating a BMI calculator. (Depending on your browser and settings you might have to do slightly different steps here.)

    Dialog box shown by your browser (optional)

    Dialog box shown by your browser. Your browser might show a similar dialog box (depending on your browser settings). Make sure Save file is selected (yellow box), then click on the OK button (red box).

  • Your OS will show a dialog box to choose the location of your file to be saved (in some browser settings, this might be omitted and your file will be saved in a default location). If you see the dialog box, make sure the file’s name is displayed correctly in the File Name field, then click on the Save button in your OS language. The screenshot shows an example where this happened while creating a BMI calculator.

    Last step of saving your guideline

    Last step of saving your guideline. Choose the location of your file to be saved, make sure its name is displayed correctly in the File Name field (yellow box), then click on the Save button in your OS language (red box).