Using variables in a Python/HCL script

When you create a Python/HCL script in the Robots script editor, you can create two different kinds of variables:

  • Python variables regular Python variables defined in the body of the script

  • HCL variables HCL variables defined in the Variables window

The two kinds of variables serve different purposes, explained in the sections that follow.

HCL also automatically assigns values to built-in system variables based on the Diligent One organization where a script runs, and the mode in which the script runs (development or production). For more information, see system_variable[] method.

You can use all three kinds of variables together in the same script.

Python variables

Python variables in a Python/HCL script work in the same way that they work in any Python script. If values in a script are subject to change, you can reference variables in the script logic rather than literal values. You can create Python variables anywhere in the script that you need them.

Example of Python variables

The example below loops through a list of numbers and squares each number in the list. Because the numbers in the list change, the script logic uses variables instead of literal values:

  • list_of_numbers – a variable assigned to the list of numbers

  • v_number – a variable assigned to a single number in the list

  • v_squared_number – a variable assigned to the result of v_number * v_number

With each iteration of the for loop, the values of the v_number and v_squared_number variables update.

list_of_numbers = [1, 2, 3, 4, 5]
for v_number in list_of_numbers:
    v_squared_number = v_number * v_number
    print(v_squared_number)

Script output:

1
4
9
16
25

HCL variables

HCL variables serve two main purposes:

  • They provide the basis for task input parameters in robot tasks.

  • They provide secure storage of sensitive information such as passwords and authentication tokens.

In Robots, neither of these requirements can be accomplished with Python variables. You must use HCL variables.

The Variables window

In the Robots script editor, the Variables window provides a centralized location for defining any HCL variables required by a script. In particular, the Variables window is where you define any script variables that store input values provided by users when they run or schedule a robot task. For example:

  • a v_department variable that allows users to specify a particular department when they run or schedule a task

  • a variable that securely manages an authentication credential required to access a data source, such as a password or an authentication token

You can also use the Variables window to define an HCL variable that is used only in the context of the script – for example, v_org_id. However, the easier approach in this situation is to create a standard Python variable in the body of the script rather than defining an HCL variable.

Variable definition fields

Number Description
1

Name contains the variable name, such as v_department
2

Type specifies the variable type
3

Value the initial value assigned to the variable when running a script interactively in the script editor

Robot task input fields

Number Description
4

Task input specifies that the variable is used with a task input parameter in the Task Designer

  • User input required the user must provide an input value when running or scheduling a robot task

  • User input optional the user can skip providing an input value when running or scheduling a robot task
5

Task input label creates a label for the input parameter that the user sees in the Task Designer – for example, Enter a department

Task input description (optional) creates a description for the input parameter that adds additional detail that could be helpful to the user

Use the Variables window to define an HCL variable

Define an HCL variable such as v_department or v_password for use with a robot task input parameter in the Task Designer.

Note

HCL variables are primarily intended for use with robot task inputs such as script configuration options, or passwords or tokens. For script variables not used with task inputs, the easier approach is to define a standard Python variable in the body of the script.

Create a basic variable definition

  1. From the Robots script editor, click Manage variables .

  2. In the Variables window, click Add variable.

  3. Specify the following values to create the basic variable definition:

    Field Description
    Name

    Specify the variable name. For example: v_department or v_password.

    Note

    A variable that stores a Diligent One token must use this exact name: v_hb_token

    For information about acquiring a Diligent One token, see Creating and managing HighBond access tokens.
    Type

    Select the variable type:

    • Character for text

    • Password for securely managing passwords or tokens

    • System user (available with toolkits) for authorizing Diligent One platform operations without reference to an actual user, similar to a service account

      Caution

      Do not edit system user variables unless you have a reason to do so.
    Value

    Enter a variable value. The value for a password variable can be up to 8 KB in length.

    The value you enter is the initial value assigned to the variable when running a script interactively in the script editor.

    Note

    For a variable associated with a task input, the value is available in the script editor only. It does not carry over as a default value in the Task Designer.

Configure an associated task input parameter

If the variable is used with a task input parameter in the Task Designer, you need to specify additional settings.

  1. Click the toggle to enable Task input.

    Enable this setting to ask the user for a value in the Task Designer. The variable stores the value input by the user when running or scheduling the task.

  2. If you want to allow the user to skip providing an input value, select User input optional.

    Certain values can alter script behavior but may not be required for the script to run. For example, optional user-specified start and end dates can limit analysis to only a particular range of the data.

  3. In Task input label, enter the label that the user will see in the Task Designer for this parameter.

    For example, Enter a department or Enter your Diligent One token.

  4. Optional. In Task input description, add additional detail that helps the user provide an input value for the parameter.

Save the variable definition

  1. Click Save and close to save the variable definition and exit the Variables window.

  2. Click Save and commit to save the script with the updated variable definition.

    Note

    You need to save and commit the script to permanently save the variable definition.

  3. Type a commit message and click Commit.

    A message appears confirming whether committing the script was successful.

Re-run the script

Saving the contents of the Variables window automatically clears the session memory in the script editor. Any imported Python libraries, Python dictionaries, generated dataframes, or variable values stored in memory are no longer available. If you run a script cell that depends on something previously stored in memory, you get an error or an unexpected result.

To restore the session memory to its previous state, re-run the entire script, or re-run all prerequisite cells.

Use an HCL variable in a script

To use an HCL variable in a script, you need to reference the variable using specific HCL syntax.

Reference an HCL character variable

To reference an HCL character variable use the following syntax: hcl.variable["variable_name"]

For example:

print(hcl.variable["v_department"])

Script output:

Operations

For detailed information about the required syntax, see variable[] method.

Reference an HCL password variable

To reference an HCL password variable use the following syntax: hcl.secret["variable_name"].unmask()

For example:

print(hcl.secret["v_hb_token"].unmask())

Script output:

zq025f72938e4s...

For detailed information about the required syntax, see secret[] method.

Assign an HCL variable to a Python variable

For convenience, you can assign an HCL variable value to a regular Python variable and then subsequently just reference the Python variable.

For example:

department = hcl.variable["v_department"]
print(department)
token = hcl.secret["v_hb_token"].unmask()
print(token)

Script output:

Operations
zq025f72938e4s...