Project variables are one of the three types of global data elements available in Jitterbit Harmony. (The two other types of global data elements—global variables and Jitterbit variables—are also available globally throughout a project. They are set differently, as described in Global Variables and Jitterbit Variables.)
Project variables are first created via Design Studio. Once a project variable is created, you may set values for them either through Design Studio, the Management Console, or Citizen Integrator, providing the flexibility to set and change parameters and credentials without redeploying the project.
Project variables are set before runtime of the operation and are available to use across all project items, including sources and targets, scripts, and transformations. If you change the value of a project variable during operation runtime, the variable is treated as a global variable with the changed value persisting only for the duration of the operation chain. That is, changing a project variable's value at runtime does not update its value for the entire project.
Common uses of project variables include endpoint credentials, filenames, or variables that can change from environment to environment. This includes any variable that you want to be able to edit through the Management Console or Citizen Integrator.
Create and Update Project Variables¶
You create and update project variables from within Design Studio. Once created in Design Studio, project variables can be updated in the Management Console and Citizen Integrator.
Within your project within Design Studio, these are the ways to create a new project variable:
- Go to File > New > New Project Variable; or
- In the tree on the left, right-click on the Project Variables section and select New Project Variable; or
- In the top toolbar, click the formula icon .
A configuration screen will open in the main view of Design Studio where you can edit your project variable. You can return to an existing project variable configuration using the tree on the left under Project Variables:
The project variable configuration screen will look similar to this example:
Name: The name field is the variable name that you are declaring. The name field cannot be left empty and must not contain spaces. The name will replace the default "NewProjectVariable" placeholder as seen in the tree on the left. You cannot leave the name of the project variable as the default placeholder. Names can be composed from alphanumeric characters (the letters a-z and A-Z, and the digits 0-9), periods (.), and underscores (_). (Other characters, such as hyphens, are not recommended and may cause issues.) Project variable names are case-insensitive; a variable called
GlobalVaris treated the same as
It can be a good practice to use periods or underscores when defining global variables so that they are easy to find. For example, a global variable created in a Jitterbit Script named
org, followed by
Default Value: Enter a default value for the project variable, if applicable. If you do not want a default value, leave this field blank. The default, if provided, will be used as the initial value, which can be modified through scripting.
Hide Value: Select the checkbox to hide the project variable value by replacing it with asterisks when displaying in the user interface. You may want to use this if the value contains sensitive information that you do not want visible in the user interface. Clearing the Hide Value checkbox will remove any existing value entered as the Default Value.
Hiding the value does not prevent the value from being accessible in a script. It only hides the display of the value.
Label: Enter a label to describe the variable name, if desired. This label will appear when you hover your cursor over the variable name in scripts.
Description: Enter a description to provide further details about the variable, if desired.
To open the project variable for editing, use the Action dropdown to select Edit:
In the popup, you can edit the value, show or hide the value, or edit the description.
Any edits to project variables using the Management Console take effect immediately.
Once a project variable has been created, it can be used within Citizen Integrator recipes. See Citizen Integrator - Configure Recipe for more information.
Retrieve Project Variables in Scripts or Transformations¶
In scripts and transformations, you can begin with a dollar sign
$ followed by the project variable name or use the
Get() function to retrieve the value of a project variable:
$: Beginning with a dollar sign
$, the example of
$org.netsuite.auth.usernamereturns the same value (or field in a transformation).
Get: Using the Get() function, the example of
Get("org.netsuite.auth.username")gets the value (or field in a transformation) of the project variable called
Name does not include a period (recommended): The value of a project variable that does not contain any periods in its name can be retrieved by beginning with a dollar sign
$: Beginning with a dollar sign
$, the example of
$org_netsuite_auth_usernamereturns the value of the project variable called
Jitterbit.GetVarfunctions. As these functions are not intended for user-defined global variables, see Jitterbit Variables for more information.
Jitterbit.GetVarfunctions are designed specifically to access the predefined Jitterbit variables. They are not to be used to access user-defined global variables.
$-prefixing when setting (and retrieving) a variable. Use only one syntax. Mixing the two different syntaxes for the same variable can cause issues at runtime.
Use Project Variables in Definition Screens¶
In a definition screen (during the configuration of sources or targets), you can reference project variables using the
For example, if you're using the project variable as part of a filename or as a property of a different object that is not in a script, then you can reference it using brackets such as