Variables

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

  • 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 your 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 the identifier of the Variable (e.g., myTextVar)

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

  • Description You can add a description before the Variable itself, starting it 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 Axon Ivy Engine to write this Variable value in encrypted form 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 is interpreted as a time consisting of HH:mm[:ss].

    • enum: You can use this annotation to enumerate all 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 filename rather than a parent directory. So, the file <project>/config/variables.myFile.json can contain the value for the variable called myFile.

Warning

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

How to Access Variables

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

ivy.var.myVariable;

If you want to access Variable Metadata, you can also use the var keyword. This delivers an interface. From the interface, you can get a Variable object. This object contains additional metadata for that Variable.

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