Global variables in Jitterbit Design Studio

Introduction

Global variables are one of the three types of global data elements available in Harmony. (The two other types of global data elements—project variables and Jitterbit variables—are also available globally throughout a project. They are set differently, as described in Project variables and Jitterbit variables.)

Global variables are first declared in an operation, after which they become available to be referenced in the same or downstream operations and scripts. Downstream operations or scripts are those that are linked within an operation chain or the RunOperation or RunScript functions.

Global variables can also be used as a source or target within the operation as described in Global variable source and Global variable target.

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 a value 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 events, as well as those that are linked through the RunOperation() function. Global variables can also be used within the same transformation.

Defined global variables are available in the Data Elements tab of the script builder accessible from the scripts and transformations screens.

Create and update global variables

In Design Studio, global variables are created or updated using either Jitterbit Script or JavaScript.

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 and may 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 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.

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 within an operation, 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.

Retrieve global variable values in scripts or transformations

In Design Studio, the value of a global 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 global variable name or use the Get() function to retrieve the value of a global variable:

• $: Prefaced with a dollar sign $, the code example $ServerURL returns the value of the global variable ServerURL.
• Get: Using the Get() function, the code example Get("ServerURL") returns the value of the global variable ServerURL.

JavaScript

In JavaScript scripts within an operation, the syntax used for retrieving 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.

• 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 variable values available outside the script.

Use global variables in definition screens

In a definition screen (such as during the configuration of sources or targets), you can reference global variables using the [GlobalVariableName{DefaultValue}] syntax.

For example, to provide a value for a server URL in a web service call, you can use the global variable syntax [ServerURL] instead of a hard-coded value. The value assigned to the global variable ServerURL would then be used at runtime.

To specify a default value, use curly brackets { } immediately following the global variable name within the square brackets [ ]. For example, the following will evaluate to the value of the global variable ServerURL if the variable is defined; if not defined, http://server/index.asp is used:

[ServerURL{http://server/index.asp}]

At operation runtime, a default value defined in a definition screen is used only if the variable value has not been set during runtime. This is different during script testing, where—as any upstream script values will not yet have been instantiated— any default value defined within a definition screen is used instead.

If you don't want the global variable to be interpreted, use a backslash "\" to escape the square bracket set "[" and "]". This can be useful temporarily while testing. For example, the following expression 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}]

Global variable how-tos

See these sections for tips on using global variables in your projects:

• Check for null or undefined values
• Set and access array variables

Check for null or undefined values

A global data element that has not been defined is considered to have a null value.

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

Set and access array variables

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