Skip to end of metadata
Go to start of metadata

Global variables are declared in an operation and are then available to be referenced in the same or downstream operations and scripts within an operation chain. They may also be used as a source or target within the operation as described in Global Variable Source and Global Variable Target.

NOTE: Other types of global data elements include project variables and Jitterbit variables, which are set differently but are also available to use globally throughout your project.

Examples of use cases where you might use global variables include:

  • Use values created in one transformation in another transformation. For example, a sessionID returned from a login web service is required when calling subsequent web services for authentication purposes.
  • Use values created in one part of a transformation at a later stage in that transformation. For example, RecordNumber is initialized and incremented for every record inserted into a target to identify its item number.
  • Use values returned in one transformation in the definition settings of subsequent operations, for example, the URL setting returned by one transformation is used to set the web service URL of a subsequent web service call.

In all of these instances, you can use global variables to share the information in question with other parts of the operation or transformation.

Global variables pass through chained operations. For examples, those that are linked to a prior operation within the operation chain using On Success or On Failure actions, 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

Variable Names

Variable names can be composed from these characters: letters (a-z, A-Z), numbers (0-9), period, and underscore. Other characters are not permitted. (Note that in the case of local variables, the period character is not allowed.)

Jitterbit Script

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

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

NOTE: When creating new global variables, it can be a good idea to prefix your global variables so that they are easy to look up later. For example, a global variable org.account.filename is first prefixed with org, then account, etc. to effectively organize it in a list among other global variables.

NOTE: If you plan to use your Jitterbit global variables in JavaScript later, it is recommended to use underscores instead of periods.

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.

NOTE: The Jitterbit.SetVar and Jitterbit.GetVar functions are intended for use only with variables that contain periods. However, using periods is not recommended because the value will be converted to a string when the variable is set, and thus cannot be used with complex data types such as arrays, dictionaries, and JSON objects. Instead, it is recommended to create Jitterbit variables that do not contain periods, for example by using underscores in place of periods and using the standard dollar sign $ syntax described below.

  • Name does not use periods (recommended): A global variable that does not contain any periods in its name can be created for the first time or updated using var $, or updated using a dollar sign $ without var.
    • var $: Using var and beginning with a dollar sign $, the example of var $ServerURL="https://www.example.com/" creates or updates a global variable called ServerURL with a value of  https://www.example.com/. New global variables that are being created for the first time must precede the $ with var.
    • $: Beginning with a dollar sign $, the example of $ServerURL="https://www.example.com/" updates the same global variable called ServerURL with the same URL. This works only for global variables that are already created.
  • Name uses periods (not recommended): A global variable that contains periods in its name can be created for the first time or updated only with the Jitterbit.SetVar function. 

    • Jitterbit.SetVar: Using Jitterbit.SetVar, the example of Jitterbit.SetVar("$Server.URL", "https://www.example.com/") creates or updates a global variable called Server.URL with a value of https://www.example.com/ that will be treated as a string. Note that the dollar sign $ must be included within the variable name, or the variable will not be global to the Jitterbit engine.

Use Global Variables 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 use the Get function or begin with a dollar sign $ to retrieve the value of a global variable.

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

JavaScript

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

NOTE: The Jitterbit.SetVar and Jitterbit.GetVar functions are intended for use only with variables that contain periods. However, using periods is not recommended because the value will be converted to a string when the variable is set, and thus cannot be used with complex data types such as arrays, dictionaries, and JSON objects. Instead, it is recommended to create Jitterbit variables that do not contain periods, for example by using underscores in place of periods and using the standard dollar sign $ syntax described below.

  • Name does not use periods: The value of a global 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 $ServerURL gets the value of the global variable called ServerURL.
  • Name uses periods: The value of a global variable that contains periods in its name can be retrieved only with the Jitterbit.GetVar function.
    • Jitterbit.GetVar: Using Jitterbit.GetVar, the example of Jitterbit.GetVar("$Server.URL") returns the string value of the global variable called Server.URL. Note that the dollar sign $ must be included within the variable name.

Use Global Data Elements in Definition Screens

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

For example, if you have a web service call where you want to provide a value for the server URL, use the global variable syntax [ServerURL] instead of a hard-coded value.

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

TIP: When using a global variable in a WHERE clause, such as in a database or Salesforce query, it is recommended to specify a default value so that script testing is possible. Otherwise, since the global variable obtains its value at runtime, the syntax may be invalidated during testing if no default value is 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}]

NOTE: 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).

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 the global variable with that name has not yet been defined. This can be used to check if a global variable has been defined or not.

Set and Access Array Variables

An array is a collection of data elements. Each member in the collection can be of any supported type, including arrays. The members of an array can be accessed using the Get() and Set()methods or using the [] array syntax. Arrays are zero-indexed, and indices are numeric, sequential, and cannot be skipped. 

You can also create arrays of global variables. An array global variable is an array of other global variables that in turn can be arrays. 

Setting an Array

You can set values in an array using the Set() method with this syntax:

type Set(string name, type value [, int index1, int index2, ...])

This sets the value of the global variable with the given name to value, and returns the value. If the first argument is an array or the name of an array data element, you can set the value of an array element by specifying its index (or indices for multi-dimensional arrays) as the third argument.

Not all the items in an array have to be of the same type. For example, you can create an array that holds a date, an integer, and a string. You can even create arrays inside other arrays.

This example creates an array with three elements of different types where each entry represents the current date and time:

<trans>
$right_now = Now();
Set($now, $right_now, 0);
Set($now, Long($right_now), 1);
Set($now, String($right_now), 2);
</trans>

Arrays are zero-indexed, i.e. the first element is at index 0 and the last element is at index size-1. To append data to an array, pass a negative index value or the size of the array. Setting an element with index larger than the size of the array results in an index out of range error. Setting non-array data elements can also be done using the $de_name syntax.

These are examples of setting values in an array:

// Set the n:th entry in an array to the string "value"
Set($arr, "value", n-1);

// Set the n:th entry of the m:th array
Set($record_set, "value", m-1, n-1);

// This is another way to set the n:th entry of the m:th array
Set($arr, "value", Length($arr));

// Sets the value to a new element at the end of the array
Set($arr, "value", -1);
NOTE: For additional syntax that can be used to define values in an array, see the Dictionary and Array Functions.

Accessing an Array

You can access the items of an array using the Get() method with this syntax:

type Get(string name[, int index1, int index2, ...])

This returns the value of the global variable with the given name. If the first argument is an array or the name of an array data element, you can get a specific element by specifying its index (or indices for a multi-dimensional array such as a record-set) as the second argument.

Some Formula Builder functions have array return values. For example, SelectNodesFromXMLAny()returns the results of an XPath query as an array. As another example, DbExecute() returns a record set as a two-dimensional array: rows first, then columns. This returns the selected data as an array of arrays (representing the selected rows and columns):

<trans>
$resultSet = DbExecute("Project Name/Sources/Database Name", "select Result from SimpleCalculatorResults");
$firstRow = Get($resultSet, 0);
$thirdColumnOfSecondRow = $resultSet[2][3];
$secondColumnOfThirdRow = Get($resultSet, 3, 2);
</trans>

Arrays are zero-indexed. To access the n:th element of an array called "arr", use Get("arr", n-1). For multi-dimensional arrays you need to specify all the indices. To access the n:th column of the m:th row in an array called ResultSet you would use Get("ResultSet", m-1, n-1). Attempting to get an element beyond the end of the array will result in an array out-of-range error.

These are examples of retrieving values from an array:

// Return the third array element
Get($arr, 2);

// Another way to return the third array element
Get("arr", 2);

// Get the n:th element of the m:th array in arr
Get($arr, m-1, n-1);

This example shows how you can first create a script that builds and returns an array. The second block shows running that script and assigning its returned value to a variable.

Build Array
<trans>
// Script to build and return an array
a = Array();
a[Length(a)] = "A";
a[Length(a)] = "B";
a[Length(a)] = "C";
a;
</trans>
Call Script to Get Array
<trans>
// Call the script to retrieve the array
$Arr = RunScript("<TAG>Scripts/Build Array</TAG>";
</trans>
NOTE: For additional syntax that can be used to access values in an array, see the Dictionary and Array Functions.

Other Types of Global Variables

Project variables and Jitterbit variables, which are also referred to as predefined global variables, are also considered to be global variables because they are available to use globally across your project. Together, these types of variables are referred to as global data elements in Jitterbit.

Project Variables

Project variables are set before runtime of the operation and become available to use across your project, for example within sources/targets, scripts, and transformations.

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.

Common uses of project variables include for endpoint credentials, filenames, or variables that can change from environment to environment. Or, any variable that you want to be able to edit through the Management Console or Citizen Integrator.

NOTE: Refer to documentation on Project Variables for additional information.

Jitterbit Variables

The Jitterbit system defines some global data elements that are always available throughout your project, known as Jitterbit variables or as predefined global variables. These can be used to easily fetch global information such as the name of the current source file and other useful information.

When designing your project, Jitterbit variables are available in the Data Elements tab of the script builder accessible from the scripts and transformations screens. Each Jitterbit variable predefined by Jitterbit is documented under the Reference section.

If using a Private Agent, you can also programmatically change the behavior of Jitterbit by changing the default value of a predefined Jitterbit variable or by creating and predefining your own Jitterbit variable. Creating or updating Jitterbit variables is not available for the Cloud Agent Group.

This is done from the following sections of the Private Agent configuration file:

  • [PredefinedGlobalVariables]
    Check or change default values for Jitterbit variables.
  • [PredefinedServerGlobalDataElement]
    Define your own custom Jitterbit variables and default values.
NOTE: For more information about editing or creating Jitterbit variables, see Editing the Configuration File - jitterbit.conf.
On This Page

Related Topics

Last updated:  Feb 14, 2019