Skip to end of metadata
Go to start of metadata

Introduction

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 become available to use across your project, such as within sources and targets, scripts, and transformations.

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.

Creating and Updating 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 as they cause issues.) Project variable names are case-insensitive; a variable called GlobalVar is treated the same as globalvar .

    NOTE: I t 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.

CAUTION: Any edits to project variables using the Management Console take effect immediately.

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.

Retrieving 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).
  • GetUsing 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.

Using 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].

On This Page

Last updated: Jun 12, 2020