Project variables in Jitterbit Design Studio

Introduction

Project variables are one of the three types of global data elements available in 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.

Design Studio

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 GlobalVar is treated the same as globalvar.

  Note

  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.account.filename begins with org, followed by account, etc. effectively organizing it by domain when in a list among other similarly constructed global variables. Note that for global variables created in JavaScript (or for Jitterbit Script global variables that might later be used in JavaScript) we recommend using underscores instead of periods. Using periods in user-defined global variables in JavaScript causes issues at runtime. Further information is provided in the JavaScript subsection below.

  Warning

  If you plan to use your project variables in JavaScript later, it is recommended to use underscores instead of periods. More information is provided below in Use project variables in scripts or transformations.

• 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.

  Caution

  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.

Management Console

Once a project variable has been created, you can edit it in the Management Console under the Projects page of the Project Variables tab.

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.

Citizen Integrator

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 Design Studio, the value of a project variable can be returned using either Jitterbit Script or JavaScript.

Jitterbit Script

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.username returns 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 org.netsuite.auth.username.

JavaScript

In JavaScript used within scripts created within an operation, the syntax used for retrieving the value of a project variable depends on whether the project variable name contains a period.

• 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_username returns the value of the project variable called org_netsuite_auth_username.

• Names with periods (recommended only for Jitterbit variables and JavaScript object values): A variable that contains a period in its name can be updated or retrieved in JavaScript only with the Jitterbit.SetVar and Jitterbit.GetVar functions. As these functions are not intended for user-defined global variables, see Jitterbit variables for more information.

  Warning

  The JavaScript Jitterbit.SetVar and Jitterbit.GetVar functions are designed specifically to access the predefined Jitterbit variables. They are not to be used to access user-defined global variables.

  In JavaScript, do not mix and match your usage of SetVar (and GetVar) with $-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.

  If a JavaScript fails, any changes made to the value of a global variable are lost. Only if the JavaScript successfully completes are modified global variables available outside the script.

Use project variables in definition screens

In a definition screen (during the configuration of sources or targets), you can reference project variables using the [ProjectVariableName] syntax.

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 [org.netsuite.auth.username].