Skip to end of metadata
Go to start of metadata

Introduction

Global variables are one of the types of global data elements available in Jitterbit Harmony. The other types of global data elements—project variables, Jitterbit variables, and filename keywords—are also available globally throughout a project. They are set differently, as described in Project VariablesJitterbit Variables, and Filename Keywords, respectively. However, as all global data elements share the same namespace, their names must be unique when compared against all other global data elements.

Global variables are first declared in an operation, after which they become available to be referenced in the same or downstream operations and scripts within an operation chain. They can be used as a source or target within the operation as described in Variable Read and Variable Write.

Downstream operations may be within the same or downstream workflows, as linked with operation actions

You may want to use global variables if your use case involves sharing information with subsequent parts of an operation chain, such as in these examples:

  • Using values created in one transformation in a later transformation. For example, a session ID (returned from a login web service) may be required when calling subsequent web services for authentication.
  • Using a value created in one part of a transformation at a later stage of that same transformation. For example, a record number may be initialized and incremented for each record inserted into a target to identify its item number.
  • Using a value returned in one transformation in the configuration of components in subsequent operations. For example, the URL setting returned by one transformation may be used to set the web service URL of a subsequent web service call.

Global variables pass through chained operations. These include operations that are linked to a prior operation within the operation chain using "on success" or "on failure" operation actions, as well as those that are linked through the RunOperation() function. Global variables can also be used within the same transformation.

Display of Global Variables

Defined global variables are displayed in several places:

  • From the project pane, global variables are displayed in the Components tab in the Global Variables category. From here you can see if the global variable is referenced elsewhere in the project and view dependencies.
  • From the script editor, global variables are displayed in the component palette on the right within the Variables tab in the Global Variables sub-tab. This location provides easy access for inserting global variable references in scripts, including within transformation scripts in script mode.
  • From transformation mapping mode, global variables are displayed within the Variables tab on the left in the Global Variables category. This location provides easy access for inserting global variable references during transformation mapping in mapping mode.
  • From endpoint configuration screens, global variables can be accessed and used in any fields that have a variable icon . As an alternative to selecting a global variable, you can manually enter the variable reference using the standard square bracket syntax.

Creating and Updating Global Variables

Global variables are created or updated using either Jitterbit Script (in scripts and transformations) or JavaScript (only in scripts created as a project component). See Script Types and Creation for information on creating the different types of scripts. Global variables configured in a Variable connection are created or updated automatically (see Variable Connection).

Global Variable Names

Global variable 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.) Global variable names are case-insensitive; a variable called GlobalVar is treated the same as globalvar.

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 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 causes issues at runtime. Further information is provided in the JavaScript subsection below.

Jitterbit Script

In Jitterbit Script used within scripts and transformations, a global variable can be defined by beginning with a dollar sign $ or by calling the Set() function:

  • $: Using the dollar sign $ syntax, $ServerURL=URL creates or updates a global variable called ServerURL with the value of URL (the name of another variable or the name of a field in a transformation).
  • Set: Using the Set() function, Set("ServerURL", URL) creates or updates a global variable called ServerURL with the value of URL (the name of another variable or the name of a field in a transformation).

JavaScript

In JavaScript used within scripts created as a project component, the syntax used for setting a global variable depends on whether the global variable name contains a period:

  • Name does not include a period (recommended): A global variable that does not contain a period in its name can be created or updated using var $name or updated simply by using $name without var:
    • var $The expression var $ServerURL="https://www.example.com/" creates or updates a global variable ServerURL with a string value of https://www.example.com/. A new global variable must precede the $ with var.
    • $: The expression $ServerURL="https://www.example.com/" updates the same global variable ServerURL with the same string URL. This works only for global variables that already exist.
  • Name includes a period (recommended only for Jitterbit variables and JavaScript object values): A variable that contains periods 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.

Variable Endpoint

During configuration of a Variable Connection, a global variable can be created or updated automatically.

That is, if during configuration you provide the name of a variable that does not yet exist, a global variable will be created automatically. If you provide the name of a global variable that already exists, it will become associated with the Variable endpoint.

For details on creating or updating a global variable using this method, see Variable Connection.

Retrieving Global Variables in Scripts or Transformations

The value of a global variable can be returned using either Jitterbit Script (in scripts or transformations) or using JavaScript (only in scripts created as a project component).

WARNING: There is a known issue that mapping variables with periods in the variable name doesn't work correctly, resulting in an incorrect target field mapping in the transformation. Until this issue is resolved, rename the variable by replacing any periods with underscores or removing periods another way.

Jitterbit Script

In scripts and transformations, you can begin with a dollar sign $ or use the Get() function to retrieve the value of a global variable:

  • $: Prefixed with a dollar sign $, the code example $serverURL retrieves the value (or field in a transformation) of the global variable called "serverURL".
  • Get: Using the Get() function, the code example Get("serverURL") returns the same value (or field in a transformation).

In scripts and transformations, existing global variables will also be displayed in the Variables tab of the script component palette inside the Global Variables sub-tab. See Adding a Global Variable to a Script below.

JavaScript

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

  • Name does not include a period (recommended): The value of a global variable that does not contain a period in its name can be retrieved by beginning with a dollar sign $:
    $: Prefixed with a dollar sign $, the expression $ServerURL retrieves the value of the global variable called ServerURL.
  • Name 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 the section on Jitterbit variables for more information.

In scripts and transformations, existing global variables will also be displayed in the Variables tab of the script component palette inside the Global Variables sub-tab. See Adding a Global Variable to a Script below.

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 a global variable are lost. Only if the JavaScript successfully completes will a modified global variable be available outside the script.

Adding a Global Variable to a Script

In either Jitterbit Script or JavaScript used within scripts created within an operation, existing global variables will also be displayed in the Variables tab of the component palette inside the Global Variables sub-tab:

Add a variable to the script using one of these methods:

  • Drag the variable from the palette to the script. The appropriate syntax for the script language will be inserted.
  • Begin typing the variable name and then press Control+Space to display a list of autocomplete suggestions. Select a variable to insert the appropriate syntax for the script language.
  • Manually enter the appropriate syntax for Jitterbit Script or JavaScript.

Using Global Variables in Configuration Screens

During configuration of various project components, including endpoint configuration using connectors, you can use global variables in any fields that have a variable icon .

You can use global variables as:

Single Variable

To use a single variable as the only value within the field, click the variable icon  to display a list of keywords and variables.

Within the list, the type of each keyword or variable is indicated by the icon next to the name:

  •  for filename keyword
  •  for global variable
  •  for project variable
  •  for Jitterbit variable

The icon's background will be solid (such as ) if the global variable has a default value, or empty (such as ) if it does not.

From the list, hover over the variable name to preview information about it:

NOTE: The value for a global variable always appears to be empty, even if you have already provided a default value in an upstream script. At this time, it is not possible to add a description. More information about specifying default values is provided later on this page under Variables with Default Values.

Select a variable to replace the contents of the field. Any existing input entered within the field, if present, will be replaced with the variable. A single variable used as input in a field is displayed in a pill format similar to that shown below:

To review information about the variable, hover over the variable pill:

To change the pill format to text to use with additional input, with each variable displayed within square brackets [ ] , click the collapse icon 

To clear the field, click the remove icon .

Variables with Additional Input

To use a variable along with other field input, including with other keywords or variables, enter an open square bracket [ into the field. From the list, hover over the variable name to preview information about it. Select a variable to insert the variable at the location of your cursor, anywhere in the string:

Variables entered using this method are displayed as text within square brackets [ ] within the field. Enter any additional input or add multiple keywords or variables using the same method described above:

Variables with Default Values

To define a default value, specify it within curly brackets { } immediately following the global variable name, within the square brackets [ ]:

When default values are specified, the global variable value will be used if it is defined, else the default value will be used.

TIP: When using a global variable in a WHERE clause, such as in a database or Salesforce query, we recommend specifying a default value so that script testing is possible. Otherwise, as a global variable obtains its value at runtime, during testing the syntax may be invalid if no default value has been specified.

If you don't want the global variable to be interpreted, use a backslash "\" to escape the square bracket set "[" and "]".

For example, the following will not use the value of serverURL even if it is defined, but will instead always use http://server/index.asp:

\[serverURL{http://server/index.asp}]

CAUTION: Within file paths that contain backslashes, a single backslash will be interpreted as initiating an escape sequence if it is followed by a square bracket set "[" and "]".

Additional backslashes may be used to achieve the desired result. For example, \\server\share\\[Directory{testing}] will be interpreted as \\server\share\testing if the variable Directory is not defined, else \\server\share\"value of Directory" will be used.

To avoid this issue, it is recommended to convert file paths to URL format (e.g. C:/directory/path).

Viewing Global Variable Dependencies

The dependencies of a global variable are other components that depend on the variable because they are either reading from—or writing to—the global variable. Once a global variable has been created and used in a project, you can view these dependencies.

After a global variable is created, menu actions for that global variable are accessible from the project pane. In the Components tab, hover over the global variable name and click the actions menu icon  to open the actions menu. From the menu, select View Dependencies:

This changes the view in the project pane to display other parts of the project that the global variable is dependent on. In dependency view, the name of the selected global variable appears along the top, below the existing search and filter capabilities. The global variable name is followed by a list of Dependencies that the variable is dependent on. This list is organized by categories such as Activity and Script and further classified under Read or Write to indicate the access type of a particular variable reference:

For example:

  • If a script contains $myVar1='abc', it is writing a value to the variable and referencing myVar1 for write access.
  • If a script contains $myVar2=$myVar1, it is referencing myVar2 for write access and myVar1 for read access.
  • If a script contains If(myVar1=='abc', TRUE, FALSE), it is referencing myVar1 for read access.

Each category can be expanded or collapsed using the disclosure triangles  .

To close out of dependency view, click the close icon .

Global Variable How-tos

See these sections for details on using global variables in projects:

Converting a Global Variable to a Project Variable

You can convert an already-existing global variable into a project variable.

Global variables can be converted into project variables during project variable configuration. While configuring a project variable, enter the name of an existing global variable into the name field. On attempting to save, a prompt will ask you to confirm that you want to convert the global variable into a project variable:

On clicking Continue, all references to and dependencies of the global variable will be transferred to the project variable. This includes references to the former global variable within scripts, which will now reference the project variable. (Keep in mind that a value for a project variable set in a script will override a default value specified in the project variable configuration during execution of the operation chain.)

For more details on project variables, see Project Variables.

Checking for Null or Undefined Values

A global variable that has not been defined has a null value.

For example, IsNull(Get("GlobalVariableName")) returns true if a global variable with the name GlobalVariableName has not yet been defined. This can be used to check if a global variable has been defined or not.

Setting and Accessing Array Variables

You can create arrays of global variables, also known as array variablesSee Arrays for information on setting and retrieving values from array variables.

On This Page

Last updated: Apr 10, 2020

  • No labels