Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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 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 actionsOther types of variables that can be used globally throughout a project include project variables and Jitterbit variables, which are set differently.

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

  • 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 purposes.
  • Using values a value created in one part of a transformation at a later stage in of that same transformation. For  For example, a record number may be initialized and incremented for every each record inserted into a target to identify its item number.
  • Using values 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 , for example, those operations that are linked to a prior operation within the same or different workflow 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

You can create and update global variables using Jitterbit Script in scripts and transformations, or using JavaScript in 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 ). See Script Types and Creation). In addition, global  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 these characters: letters (from alphanumeric characters (the letters a-z , and A-Z), numbers (and the digits 0-9), periods(.), and underscores (_). (Other characters, such as hyphens, are not recommended and may as they cause issues.) Global variable names are case-insensitive; for example, a variable called GlobalVar is treated the same as globalvar.

It can be a good idea practice to use periods or underscores to prefix when defining global variables so that they are easy to look up laterfind. For example, a global variable created in a Jitterbit Script named org.account.filename is first prefixed  begins with org, then followed by account, etc. to  effectively organize organizing it when in a list among other similarly constructed global variables. However, note Note that for global variables created in JavaScript (or for Jitterbit Script global variables that might later be used in JavaScript, it is recommended to use ) 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 defined by beginning with a dollar sign $ or by  or by calling the Set() function.:

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

Anchor
javascript
javascript
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.

Warning

WARNING: The Jitterbit.GetVar and Jitterbit.SetVar functions are designed to allow the use of variables that contain periods within the variable name. However, using periods in a variable name is not recommended. As the value will be converted to a string when the variable is set, these variables cannot be used with complex data types such as arrays, dictionaries, or JSON objects. Instead, it is recommended that you create Jitterbit variables without periods and instead use underscores in place of periods and use the standard dollar sign $ syntax described below.

Names without periods 

:

  • Name does not include a period (recommended): A global variable that does not contain any periods a period in its name can be created initially or updated using the command using var $, or updated using a dollar sign $name or updated simply by using $name without var.:
    • var $:Using var and beginning with a dollar sign $, the code example var $serverURL The expression var $ServerURL="https://www.example.com/" creates or updates a global variable called "serverURL"variable ServerURL with a string value of "of https://www.example.com" /. New global variables that are being initialized  A new global variable must precede the $ with var.
    • $:  Prefixed with a dollar sign $, the code example $serverURLThe expression $ServerURL="https://www.example.com/" updates the same global variable called "serverURL"variable ServerURL with the same same string URL. This works only for global variables that are already initializedexist.
  • Names with periods (not recommendedName includes a period (recommended only for Jitterbit variables and JavaScript object values): A global variable that contains periods in its name can be created initially or updated or retrieved in JavaScript only with the Jitterbit.SetVar function.  and Jitterbit.GetVar functions. As these functions are not intended for user-defined global variables, see Jitterbit Variables for more information.

    Warning

    WARNING: The JavaScript Jitterbit.SetVar

    : Using 

    and Jitterbit.

    SetVar, the code example 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 Harmony system

    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 connectionConnection, 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.

Converting a Global Variable to a Project Variable

If you have already created a global variable that you want to be a project variable, you can convert it.

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:

Image Removed

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.

Using Global Variables

Retrieving Global Variables in Scripts or Transformations

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

Warning

WARNING: There is a known issue that mapping variables with periods in the variable name dondoesn'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.

HTML Comment
hiddentrue

https://jitterbit.atlassian.net/browse/DOCS-1603

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:

Image Removed

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 Jitterbit Script.
  • Manually enter the appropriate syntax for Jitterbit Script.

JavaScript

In JavaScript used within scripts created within 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.

Warning

WARNING: The Jitterbit.SetVar and Jitterbit.GetVar functions are designed to allow the use of variables that contain periods within the variable name. 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.

  • Names without periodsName does not include a period (recommended): The value of a global variable that does not contain any periods a period in its name can name can be retrieved by prefixing beginning with a dollar sign $.:
    $: Prefixed with a dollar sign $, the code example $serverURLexpression $ServerURL retrieves the value of the global variable "serverURL"called ServerURL.
  • Names Name with periods: The value of a global  (recommended only for Jitterbit variables and JavaScript object values): A variable that contains periods a period in its name can be updated or retrieved in JavaScript only with the Jitterbit.SetVar and Jitterbit.GetVar function.
    • Jitterbit.GetVar: Using Jitterbit.GetVar, the code example 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 to read the global value from the Harmony system.

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

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.

Anchor
adding-a-global-variable-to-a-script
adding-a-global-variable-to-a-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:

Image RemovedImage Added

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 JavaScriptthe script language.
  • Manually enter the appropriate syntax for for Jitterbit Script or JavaScript.

Anchor
using-global-variables-in-configuration-screens
using-global-variables-in-configuration-screens
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:

Anchor
single-variable
single-variable
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 solid (such as ) if the global variable has a default value, or empty empty (such as ) if it does not.

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

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

Anchor
variables-with-additional-input
variables-with-additional-input
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:

Anchor
variables-with-default-values
variables-with-default-values
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
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, since the as a global variable obtains its value at runtime, during testing the syntax may be invalidated during testing invalid if no default value is 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:

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

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

Anchor
viewing-dependencies
viewing-dependencies
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
  • , it is writing a value to the variable and
is therefore
  • referencing myVar1 for write access.
  • If a script contains $myVar2=$myVar1
 then
  • , it is referencing myVar2 for write access and myVar1 for read access.
  • If a script contains If(myVar1=='abc', TRUE, FALSE)
 then
  • , 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:

Anchor
converting-a-global-variable-to-a-project-variable
converting-a-global-variable-to-a-project-variable
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:

Image Added

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.

Anchor
checking-for-null-or-undefined-values
checking-for-null-or-undefined-values
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 the  returns true if a global variable with that the name GlobalVariableName has not yet been defined. This can be used to check if a global variable has been defined or not.

Anchor
setting-and-accessing-array-variables
setting-and-accessing-array-variables
Setting and Accessing Array Variables

Multiexcerpt include
MultiExcerptNamearrays
PageWithExcerptJitterbit Script

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 a project. Together, these types of variables were formerly referred to as global data elements in Jitterbit Harmony. For additional information, refer to documentation on project variables and Jitterbit variablesYou can create arrays of global variables, also known as array variablesSee Arrays for information on setting and retrieving values from array variables.

Panel
borderColor#65379B
titleColor#FFFFFF
titleBGColor#65379B
titleOn This Page
Table of Content Zone

Table of Contents
maxLevel3
minLevel2

Panel
borderColor#FF7C4C
titleColor#FFFFFF
titleBGColor#FF7C4C
titleRelated Articles
Panel
borderColor#00B886
titleColor#FFFFFF
titleBGColor#00B886
titleRelated Topics

HideElements
metastrue

Last updated: 

Lastmodifieddate