Variables

Variables are dynamic key/value pairs which can be used to configure your application at runtime. So, by using Variables, rather than static texts, you can master the following scenarios at ease:

  • Workflow-Application customizations (branding, multi-tenancy)

  • Different runtime settings (staging vs. production)

  • Company data (name, address, contacts)

  • Simple Rule Values (e.g. credit account)

To see and configure Variables at runtime, use the Engine Cockpit Variables View on the Axon Ivy Engine.

Editor

The Axon Ivy Designer delivers a Yaml-Editor to edit the <project>/config/variables.yaml file, where you can maintain you variables.

 1Variables:
 2  # This is the end-user doc for 'myTextVar', describing it's value and use-case.
 3  myTextVar: value
 4
 5  # This is a boolean variable
 6  myBooleanVar: false
 7
 8  # This is a number variable
 9  myNumberVar: 123456
10
11  # This is a password variable
12  # [password]
13  myPasswordVar: mySecret
14
15  # This is a daytime variable
16  # [daytime]
17  myDaytimeVar: '13:37'
18
19  # This is a enum variable with possible predefined values
20  # [enum: hi, hello, hallo, ciao, salut]
21  myEnumVar: hi
22
23  # This is a file variable. 
24  # It's perfect to contain large and complex datas, 
25  #  as the value is not defined in variables.yaml directly. 
26  #  Rather it's value is loaded
27  #  from an external file, which is located 
28  #  at (<project>/config/variables/myFileVar.json).
29  # The file extensions 'json' and 'txt' are supported.
30  # [file: json]
31  myFileVar: 
32
33  # wrapper for complex files stored in a sub-directory
34  myAppSettings:
35    # The value of this variable is read from the file
36    #  (<project>/config/variables/myAppSettings/myStatisticPrefs.json)
37    # [file: json]
38    myStatisticPrefs:

  • Name The name is identifier for the Variable (e.g myTextVar)

  • Default value The default value is the value (e.g value for the myTextVar)

  • Description The description is can be added before the Variable itself, started by a #

  • Metadata You can specify additional meta data for a Variable. Strings, Boolean values and numbers are recognized by the default value, but there are other types you can define:

    • password: This tells the engine that the value of this Variable should be written encrypted to the YAML files.

      Tip

      If you add a password variable in the Axon Ivy Designer, you get an validation warning, that the variable is not encrypted. You can fix this via a Problems View > QuickFix or right click in the Yaml-Editor > Encrypt passwords

    • daytime: This value will be interpreted as daytime

    • enum: The enum annotation will give you the possibility to define possible values for this Variable.

    • file: The file annotation configures the value of this Variable to be read from an external file. This file can be a .json or a .txt file. If your Variable is called myFile and it should be a json file, then your file must be located at <project>/config/variables/myFile.json. Alternatively the variables prefix can also be part of the file-name rather than a parent directory. So, the file <project>/config/variables.myFile.json could also serve the value for the variable called myFile.

Tip

If your variable has password or secret in its name (e.g., hidePasswordMenu) and no type is explicitly set, the Axon Ivy Engine will automatically treat this variable as a password to increase the security of it. If this behavior does not suit your needs, you can override it by explicit setting the type (e.g., with # [boolean], # [string] or # [number]).

Warning

The indentation spaces needs to be the same in the whole yaml file.

Environments for Variables

You can override the default value of a Variable for a particular Environment, by adding a <project>/config/_<environment>/variables.yaml file and defining your Variables in there. This can be useful if you need different values for the same Variable, if this is used in different software development stages (“testing”, “productive”). You don’t have to provide the metadata (e.g description) again:

1Variables:
2  myVariable: value from environment

How to Access Variables

To access the Variables in your code, you can use the var method. In IvyScript, you can use the namespace and name of the Variable to get access to your defined Variables. In addition, this approach has the advantage that you receive validation notifications when a Variable is removed by a developer.

For example, if you have a Variable with the namespace my.namespace and the name myVariable, you can access it in IvyScript as follows:

ivy.var.my_namespace_myVariable;

You can also use the var method with get to access the Variable, but without the advantage of validation of the Variable’s existence:

ivy.var.get("my.namespace.myVariable");

If you want to access Variable Metadata, you can use the var method with variable. This object contains additional metadata for that Variable:

ivy.var.variable("my.namespace.myVariable").description();