Versions Compared

Key

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

Overview

Multiexcerpt include
MultiExcerptNamedesign-studio-banner
PageWithExcerptDesign Studio

Jitterbit Variables

Jitterbit 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 project variables—are also available globally throughout a project. They are set differently, as described in Global Variables and Project Variables.)

The Jitterbit variables are always available throughout your project. They are predefined by Jitterbit or set in the Jitterbit configuration file.

The most common use cases for Jitterbit variables are to read a variable so that you can gather information about what occurred during an operation or to fetch global information such as the name of the current source file. Less frequently, Jitterbit variables are written to when changing default settings used for processing the operation chain.

As these variables are predefined variables, projects very rarely create or change the default value of a Jitterbit variable. However, when using a Private Agent, Jitterbit variables can be created or their default value modified. See Creating New Variables or Setting Defaults on Private Agents below for details.

Refer to these pages for documentation on the predefined Jitterbit variables:

Children Display

Display of Jitterbit Variables

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 on a page under this section.

Setting Jitterbit Variables in Scripts or Transformations

While the most common use case for Jitterbit variables is to read information, there are some Jitterbit variables that you may want to set in order to communicate something to an agent. In Cloud Studio, Jitterbit variables can be set using either Jitterbit Script or JavaScript, in the same way that any global variable can be set.

Tip
TIP: Refer to the documentation for each Jitterbit variable for information on which variables can be set and what they can be set to.

Jitterbit Script

In Jitterbit Script used within scripts and transformations, the value of a Jitterbit variable can be set by beginning with a dollar sign $ or by calling the Set() function.

  • $: Using the dollar sign $ syntax, $jitterbit.api.response="Success" sets the API response (jitterbit.api.response) to return the string "Success" to the requesting application. 
  • Set: Using the Set() function, Set("jitterbit.api.response", "Success") sets the API response (jitterbit.api.response) to return the string "Success" to the requesting application.

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

JavaScript

In JavaScript used within scripts created as a project component, Jitterbit variables predefined by Jitterbit are able to be set only with the Jitterbit.SetVar() function. This is because all Jitterbit variables predefined by Jitterbit contain periods within the variable name.

  • Jitterbit.SetVar: Using Jitterbit.SetVar, the code example Jitterbit.SetVar("$jitterbit.api.response", "Success") sets the API response to return the string "Success" to the requesting application.

In scripts and transformations, Jitterbit variables will also be displayed in the Variables tab of the script component palette, inside the Jitterbit Variables sub-tab. See Adding a Jitterbit 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 $-prefacing when setting (and retrieving) a variable. Use only one syntax. Mixing the two different syntaxes for the same variable can cause issues at runtime.

Retrieving Jitterbit Variables in Scripts or Transformations

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

Warning

WARNING: There is a known issue that mapping variables with periods in the variable name don't work correctly, resulting in an incorrect target field mapping in the transformation. Until this issue is resolved, Jitterbit variables are unable to be directly referenced within a transformation. Scripting can be used to create a workaround mechanism to pass values.

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 Jitterbit variable:

  • $: Prefixed with a dollar sign $, the code example $jitterbit.operation.error retrieves the value of the Jitterbit variable "jitterbit.operation.error".
  • Get: Using the Get() function, the code example Get("jitterbit.operation.error") returns the same value.

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

JavaScript

In JavaScript scripts within an operation, Jitterbit variables predefined by Jitterbit are able to be accessed only with the Jitterbit.SetVar() and Jitterbit.GetVar() functions. This is because all Jitterbit variables predefined by Jitterbit contain periods within the variable name.

  • Jitterbit.GetVar: Using Jitterbit.GetVar, the code example Jitterbit.GetVar("$jitterbit.operation.error") returns the value of the Jitterbit variable called "jitterbit.operation.error". Note that a leading dollar sign $ is optional before the name when retrieving values. The names jitterbit.operation.name and $jitterbit.operation.name are equivalent when retrieving values.
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 $-prefacing when setting (and retrieving) a variable. Use only one syntax. Mixing the two different syntaxes for the same variable can cause issues at runtime.

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

Using Jitterbit Variables in Definition Screens

In a definition screen (during the configuration of sources or targets), you can reference Jitterbit variables using the [JitterbitVariableName] syntax.

For example, if you're using the Jitterbit 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 [jitterbit.source.filename].

You can define a default value in curly brackets { } immediately following the Jitterbit variable name within the square brackets [ ]. For example:[jitterbit.source.filename{example.csv}].

Though you can use variables when specifying a value of a configuration field, the default values of the variable values will not work when testing in scripts, Script Pad, or using Formula Builder Debugging. The default values will work when the script is run as part of an operation or at runtime.

Creating New Variables or Setting Defaults on Private Agents

Those using Private Agents can programatically change the default behavior of Jitterbit variables as well as create new Jitterbit variables through the Private Agent configuration file. However, note that this is used only in rare use cases implemented by advanced users. Most use cases can be handled by creating a project variable rather than a Jitterbit variable. Creating or updating Jitterbit variables is not available for the Cloud Agent Groups.

Changing default values or creating new Jitterbit variables is done from these 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.

Jitterbit variable names can be composed of these characters: letters (a-z, A-Z), numbers (0-9), periods, and underscores. Other characters are not recommended and may cause issues.

Info
NOTE: Upon upgrading a Private Agent, the configuration file is preserved, and is not overwritten with the latest version.
Warning
WARNING: When creating new Jitterbit variables, using periods in a variable name is not recommended if you plan to access them with JavaScript. Instead, it is recommended that you create Jitterbit variables that do not contain periods and instead use underscores in place of periods. Refer to information on global variables, which is also applicable to Jitterbit variables.

For more information about editing or creating Jitterbit variables, see Editing the Configuration File - jitterbit.conf.

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
titlePages in This Topic

Children Display

Panel
borderColor#8C9CB4
titleColor#FFFFFF
titleBGColor#8C9CB4
titleSearch in This Topic
Page Tree Search
Panel
borderColor#00B886
titleColor#FFFFFF
titleBGColor#00B886
titleRelated Topics
Content by Label
showLabelsfalse
max1000
showSpacefalse
sorttitle
cqllabel = "script-overview" and space = "DOC"

HideElements
metastrue
titletrue

Last updated:

Lastmodifieddate