Skip to main content

Variables

Variables serve as meta-structural objects designed for storing and transmitting data within the application, either within the form or across different components like external APIs and Widgets. Similar to fields, variables play a crucial role in managing data. However, they distinctively operate behind the scenes, as they are not visually presented on the form, and you cannot directly incorporate them onto the canvas.

There are four types of variables as declared by their source:

  • Internal variables: Locally defined and exclusive to the form where they are created.
  • External variables: Globally defined outside the form, these variables are passed to the form as inputs.
  • Static variables: Read-only variables, which are defined by the form-renderer library and are available in every form.
  • AQL variables: Locally defined, these variables are employed to retrieve values from an AQL result.

You can access variables by clicking on the Variables button in the left panel:

Internal Variables​

Internal variables are locally defined and can be used only inside the form where they were defined. They are used to store data that is not displayed on the form itself, but is needed for the form to work properly, to store temporary calculations, or to pass data between different parts of the form.

Creating internal variables is a straightforward process: navigate to the "Internal variables" tab and initiate the creation by clicking the "Create new" button.

  • Name: The name of the variable. Name must satisfy the following conditions:
    • It must be unique. No other variable can have the same name.
    • It must be at least 3 characters long.
    • It cannot be 'aql',
    • It can only match alphanumeric characters, a hyphen or an underscore
  • Type: Variable type is the value type of the variable. Variable type can be a
    • string (text)
    • number
    • array
    • object (JSON key/value pair)
    • boolean (true/false)
  • Mandatory: If the variable is mandatory and doesn't hold a value, a describable error will be displayed on the form.
  • Value: The initial value of the variable. It is the value that the variable will have when the form is first opened.
  • Test value: The test value is a value that you define during building a form. If a value does not exist, then the test value will be taken when creating and previewing the form. Be aware that during runtime, the test value will not be used.

External Variables​

External variables serve as read-only entities dedicated to transmitting data from parent applications to the form. Unlike internal variables, their values cannot be determined within the form itself. Instead, a parent application is responsible for setting their values and passing them to the Form Renderer as inputs.

IMPORTANT External variables are globally defined at the project level. Once created, they become accessible across all forms within the project.

Even though external variables can be created within the Form Builder, it's crucial to note that their deletion is not performed within this interface. To remove external variables, navigate to the project Administration.

Creating an external variable is similar to creating an internal variable, with the key distinction being that the value field for external variables is disabled during the creation process.

NOTE: Some of the external variables have the "lock" icon next to them. They are defined by Better EHR Studio and locked. You can only override their test value. Some examples of locked external variables include: ehrId, terminologyURL, and openEhrUrl.

ehrId​

Because passing the ehrId to a form is almost always necessary, the ehrId variable always exists. EhrId is integrated into the whole structure of the Form Renderer.

terminologyUrl​

terminologyUrl is the URL of the terminology adapter that a form can use.

openEhrUrl​

openEhrUrl holds the URL of the openEHR server that a form can use. If the parent application does not pass a value for openEhrUrl, the form renderer will automatically assign the openEHR server URL to the variable.

Static Variables​

Static variables, immutable and unalterable, cannot be added or removed, and their values remain constant. Static variables are calculated automatically by the form-renderer library during runtime and depend on the definition of a form.

Static variables include:

  • authHeaderValue: EHR Server Authentication header value (i.e. 'Bearer doaih8398hfaohfoisa83')
  • compositionId: CompositionId with which the user wants to pre-populate the form data. Undefined if compositionId is not provided
  • currentDate: variable tells us the current date. Can be used for setting the default value of DV_DATE field. Is in 'yyyy-MM-dd' format.
  • currentDateTime: variable tells us the current date. Can be used for setting the default value of DV_DATE_TIME field. Is in the 'yyyy-MM-ddTHH:mm+GMT' format.
  • currentPage: tells the user on which page he currently is.
  • dateFormat: Current date format.
  • formLanguage: Current language of the form.
  • formName: Name of the form.
  • formVersion: Version of the form.
  • isFormPrefilled: Form is prefilled, if the composition is provided (has fields specified) or if the compositionId is provided.
  • isReadOnly: is a form in the read-only mode.
  • platformURL: platformUrl is the URL to which this renderer is connected to. URL also has /rest/v1 appended.
    warning
    As of Studio version 3.9, platformUrl is deprecated, please use openEhrUrl instead.

You can see all possible variables in the Static section of the Variables tab and by clicking on each, you can read their description.

AQL Variables​

An AQL variable is a variable that gets its value and type from an AQL result.

You can create an AQL variable from an AQL view or AQL value. AQL views are stored AQL queries - please visit the Views documentation for more information. An AQL value is the result of an AQL query.

When creating an AQL variable from an AQL value, Better EHR Studio will redirect you to AQL Builder, where you can use templates for easier AQL building.

AQL Building Variables​

Whenever you create an AQL variable, you also create an AQL query. This query can use parameter values, e.g. a parameter to limit the search result.

NOTE: To create a new AQL variable use the :variable_name notation. Variable input fields will be automatically added to the AQL Builder.

Variables in AQL building

The above example has the ehrId, offset, and limit variables.

External Variables and Backward Compatibility​

Before the release of Studio version 3.8, external variables were confined within individual forms, lacking the ability to be shared across different forms within the same project. This setup proved inefficient, requiring duplication of variables when needed in multiple forms.

With the advent of Studio version 3.8, a significant enhancement was introduced: project-level external variables. This pivotal shift allows external variables to be defined at the project level, promoting seamless sharing across all forms within the project.

Version Compatibility: Forms created in versions preceding 3.8 remain editable on version 3.8 and function correctly when used in versions older than 3.8.

If you open a form created in versions before 3.8, please be aware of the following scenarios before editing the form:

  • If you edit an external variable, and that variable does not exist globally in the project, that external variable, along with all other external variables in that form that are not available globally, will be created
  • When you open the form, all the variables that are globally defined will be available in the form.
  • If the form contains an external variable with the same name as an external variable that is defined globally, then the locally defined variable will be used.
  • If the form contains an internal variable with the same name as an external variable that is defined globally, then Form Builder will consider it as an error that needs to be fixed. You either need to rename the variable, or delete it.