Jitterbit Script language in Integration Studio

Introduction

The Jitterbit Script language can be used in all types of scripts within Harmony, including within operations and transformations. Scripts are created in Jitterbit Script language by default. This page provides information specific to the Jitterbit Script language, such as syntax, data types, operators, escape sequences, and control structures. Also see related pages for creating a script, using the script editor, and testing a script.

Syntax

In Jitterbit Script, scripts must be enclosed within a <trans> opening tag and </trans> closing tag, unless using functions that specifically call for code to be placed outside of these tags, such as several Database functions.

Within those tags, a Jitterbit Script consists of built-in functions, variables, or logic to execute, separated by a semi-colon (;).

The result that is returned is the returned value of the last statement of the script before the closing </trans> tag.

Comments

Within the <trans> ... </trans> tags, the use of two forward slashes // marks the start of a single-line comment and affects the text to the end of that line. Comments are not part of the script that is run or the transformed result.

For example, a comment on a single line might look like this:

<trans>
// This is a comment
DbLookup(...)
</trans>

You can also use a block-style comment:

<trans>
/* This is a multi-line comment
This line is also a comment
This is the final line of the comment */
DbLookup(...)
</trans>

Control structures

The Jitterbit Script language does not include control statements such as if or while loops. Instead, you can use Jitterbit functions to achieve the same functionality.

See the Case, If, and While functions under Logical functions. The Eval function under General functions can be used as a "try-catch" statement.

A maximum of 50,000 loop iterations is allowed for each individual loop in Jitterbit Scripts. To increase the allowed number of iterations per loop, see jitterbit.scripting.while.max_iterations in Scripting Jitterbit variables.

Regular expressions

Harmony supports regular expressions as means of specifying and recognizing strings of text, including particular characters, words, or character patterns. Harmony supports the regular expression syntax from the Perl 5 programming language.

<trans>
RegExMatch(<input>,<expression>,...)
</trans>

Escape sequences

Harmony recognizes these escape sequences when used in literal strings:

Literal strings must be surrounded by double quotes (") or single quotes (').

Any other quote must be escaped if used in the string. For example:

$str = "String with line break.\nThat's the last line.";

$str = 'Rob "The Gronk" Gronkowski';

$str = "Rob \"The Gronk\" Gronkowski";

Operators

This is a summary of the operators supported by Jitterbit Script. Jitterbit Script attempts to convert the arguments to enable the operation. If this is not possible, an error is reported.

Arithmetic

Logical

Comparison

Use the following operators to compare the values of two arguments of the same data type:

Negation

!IsNull($org.workorder.id)

Array

\(a={"London","Paris","New York"};<br/>\)b={{"John",25},
    {"Steve",32},
    {"Daniel",26}
   };
$c={"\"quoted\"", '"quoted"'};

Operator precedence

This table shows the precedence of the operators, from highest to lowest:

Component palette

The script component palette provides access to various components that can be used within a script. You can use components within a script by dragging or double-clicking them from the component palette, using the autocomplete feature, or manually typing or pasting in the correct syntax.

You can access the script component palette on the right side of the project designer and script editor:

Source objects

The Source Objects tab is present only for scripts created within a transformation.

Within a transformation script, you can reference source data by inserting a field's reference path, or you can reference source data nodes by inserting a node's reference path. Inserting a field's reference path in a transformation script maps the source object to a target field (see Mapping source objects). Although nodes cannot be mapped to target fields, they are able to be used as arguments with some XML functions and Dictionary and array functions. Nodes can also be used to create conditions on target nodes (see Conditional mapping).

To add a field or node reference path to a transformation script (Jitterbit Script only), use one of these methods:

• Drag the object from the palette to the script to insert the object's reference path.
• Double-click the object in the palette to insert the object's reference path at your cursor's location within the script.
• Manually enter the reference path to the source object.

This example assigns a source object to a global variable in a transformation mapping:

<trans>
$org.calculate.operand1=root$transaction.request$body$Calculate$input.Operand1$;
</trans>

This example uses a node path with an XML function:

<trans>
GetXMLString([root$transaction.response$body$queryResponse$result$records.Case$Account$]);
</trans>

For information on how field and node reference paths are constructed, see Reference path notation in Nodes and fields.

Functions

The Functions tab provides a list of functions available to use in a script.

Within a script, you can use functions by inserting the function syntax.

To add the function syntax to a script (Jitterbit Script or JavaScript), use one of these methods:

• Drag the function from the palette to the script to insert the function syntax.
• Double-click the function in the palette to insert the function syntax at your cursor's location within the script. On inserting the function syntax, the first function argument becomes highlighted and your cursor is moved to the end of the argument.
• Begin typing the function name and then press Control+Space to display a list of autocomplete suggestions. Select a function to insert the function syntax.
• Manually enter the function syntax.

For more information, see the documentation for each function by category under Functions.

Variables

The Variables tab provides access to variables that are available to reference globally throughout a project, including global variables, project variables, and Jitterbit variables.

Within a script, you can use variables by inserting the variable syntax (see the documentation for each variable type under Variables).

To add the variable syntax to a script (Jitterbit Script or JavaScript), use one of these methods:

• Drag the variable from the palette to the script to insert the variable syntax.
• Double-click the variable in the palette to insert the variable syntax at your cursor's location within the script.
• Begin typing the variable name and then press Control+Space to display a list of autocomplete suggestions. Select a variable to insert the variable syntax.
• Manually enter the variable syntax.

Global variables are accessed either by typing a $ sign before the variable name or by using the Set and Get functions.

Global variable names can be composed from these characters: letters (a-z, A-Z), numbers (0-9), periods, and underscores. Other characters, such as hyphens, are not recommended and may cause issues. (Note that in the case of local variables, the period character is not recommended either.)

This example references a global variable using $ to create a global dictionary:

<trans>
$org.lookup.currency=Dict();
$org.lookup.currency[1]="USD";
$org.lookup.currency[2]="EUR";
</trans>

This example assigns a global variable to another global variable using the Set and Get functions:

<trans>
Set("op2", Get("op"));
</trans>

Note that for certain Jitterbit variables, because they include a hyphen, you must reference them by using either the Set or Get functions:

<trans>
Get("jitterbit.source.http.response.header.Content-Type");
</trans>

Local variables, although not listed within the Variables tab, are not listed because they are not available globally. However, you can still use them locally within a script. Local variables have these characteristics:

• A local variable is defined and used only within a specific script. Therefore, conflict between a local variable's value in the current script vs. the value of a local variable with the same name in another script is not a concern.
• The local variable cannot be defined or retrieved by the Set or Get functions.
• RunScript can pass arguments to the script, for example RunScript(SCRIPT_ID, 5, "abc",...). Values in the script can be assigned to predefined local variables _1, _2, .... In this example, _1 represents the integer value of 5, while _2 represents the string value "abc". The local variable must be defined before it can be referenced, except in the case of the input arguments _1, _2, ... described above.
• The ArgumentList function is available for redefinition of a list of local variables as input arguments.

For more detailed information on each type of variable and examples, refer to Variables.

Plugins

The Plugins tab provides a list of plugins that can be run inside a script.

Within a script, you can use a plugin as an argument for the RunPlugin function by inserting the plugin reference path (see Plugins called in a script).

To add a plugin reference path to a script (Jitterbit Script only), use one of these methods:

• Drag the plugin from the palette to the script to insert both the RunPlugin function and the plugin reference.
• Double-click the plugin in the palette to insert the plugin reference at your cursor's location within the script.
• Begin typing the plugin name and then press Control+Space to display a list of autocomplete suggestions. Select a plugin to insert the plugin reference.
• Manually enter the plugin reference.

The plugin reference is contained within <TAG> and </TAG> tags and is constructed of the type of the project component (plugin), followed by a colon (:), followed by the plugin name from the XML manifest. This example uses the RunPlugin function with a reference to the HMAC-SHA1 generator plugin:

<trans>
RunPlugin("<TAG>plugin:http://www.jitterbit.com/plugins/pipeline/user/HMACSHA1Generator</TAG>");
</trans>

Note that the plugin name from the XML manifest is not necessarily the same as the display name in the Management Console.

Operations

The Operations tab provides a list of operations in the project that are available to reference in a script.

Within a script, you can use an operation as an argument for functions by inserting the operation reference path.

To add an operation reference path to a script (Jitterbit Script only), use one of these methods:

• Drag the operation from the palette to the script to insert both the RunOperation function and the operation reference.
• Double-click the operation in the palette to insert the operation reference at your cursor's location within the script.
• Begin typing the operation name and then press Control+Space to display a list of autocomplete suggestions. Select an operation to insert the operation reference.
• Manually enter the operation reference.

The operation reference is contained within <TAG> and </TAG> tags and is constructed of the type of the project component (operation), followed by a colon (:), followed by the user-provided operation name. This example uses the RunOperation function with a reference to an operation named My Example Operation:

<trans>
RunOperation("<TAG>operation:My Example Operation</TAG>");
</trans>

In addition to using the RunOperation function, you can also use the operation reference with other functions from the Functions tab that take the operation reference as an argument. These include functions listed in General functions that use an operationInstanceGUID, operationId, or operationTag as a parameter. For example:

• CancelOperation
• GetLastOperationRunStartTime
• GetOperationQueue
• RunOperation
• WaitForOperation

Notifications

The Notifications tab provides a list of notifications in the project that are available to reference in a script.

Within a script, you can reference a notification as an argument for the SendEmailMessage function by inserting the notification reference path.

To add a notification reference path to a script (Jitterbit Script only), use one of these methods:

• Drag the notification from the palette to the script to insert both the SendEmailMessage function and the notification reference.
• Double-click the notification in the palette to insert the notification reference at your cursor's location within the script.
• Begin typing the notification name and then press Control+Space to display a list of autocomplete suggestions. Select a notification to insert the notification reference.
• Manually enter the notification reference.

The notification reference is contained within <TAG> and </TAG> tags and is constructed of the type of the project component (email), followed by a colon (:), followed by the user-provided email notification name. This example uses the SendEmailMessage function with a reference to an email notification named My Example Email Notification:

<trans>
SendEmailMessage("<TAG>email:My Example Email Notification<TAG>");
</trans>

Scripts

The Scripts tab provides a list of all other standalone project component scripts in the project — written in either Jitterbit Script or JavaScript — that are available to reference in a script.

Within a script, you can reference another script as an argument for the RunScript function by inserting the script reference path.

To add a script reference path to a script (Jitterbit Script only), use one of these methods:

• Drag the script from the palette to the script to insert both the RunScript function and the script reference.
• Double-click the script in the palette to insert the script reference at your cursor's location within the script.
• Begin typing the script name and then press Control+Space to display a list of autocomplete suggestions. Select a script to insert the script reference.
• Manually enter the script reference.

The script reference is contained within <TAG> and </TAG> tags and is constructed of the type of the project component (script), followed by a colon (:), followed by the user-provided script name. This example uses the RunScript function with a reference to a script named My Example Script:

<trans>
RunScript("<TAG>script:My Example Script</TAG>");
</trans>

Endpoints

The Endpoints tab provides a list of endpoints in the project that are available to reference in a script.

Within a script, you can reference endpoints as an argument for functions by inserting the connection or activity reference path.

To add a connection or activity reference path to a script (Jitterbit Script or JavaScript), use one of these methods:

• Drag the connection or activity from the palette to the script to insert the appropriate reference.
• Double-click the connection or activity in the palette to insert the appropriate reference at your cursor's location within the script.
• Begin typing the connection or activity name and then press Control+Space to display a list of autocomplete suggestions. Select a connection or activity to insert the appropriate reference.
• Manually enter the connection or activity reference.

The types of endpoints that can be used within scripts depends on if there are functions that support taking the specific type of connection or activity reference as an argument. The endpoint references must be used in conjunction with those functions in order to be valid in the script.

Connections and activities that can be used in the script appear within categories that list the number of each item available under each category. Activity names are preceded by square brackets containing the type of interaction with the data resource that is specific to the activity type (for example, Read, Write, Query, Upsert, GET, POST, etc.). In order to show up here, connections and activities must already be configured within the project. For example, if there is a single configured HTTP connection in the project, with two activities configured using that connection, they appear grouped as follows:

Connection references are contained within <TAG> and </TAG> tags and are constructed of the type of the project component (endpoint), followed by a colon (:), followed by the type of endpoint, followed by the user-provided connection name. For example:

<TAG>endpoint:database/My Example Database</TAG>

Activity references are longer, as the connection reference from which they are associated must also be included in the path. Activity references are contained within <TAG> and </TAG> tags and are constructed of the type of the project component (activity), followed by a colon (:), followed by the type and name of the connection, followed by the type of activity, followed by the user-provided activity name. For example:

<TAG>activity:database/My Example Database/database_query/Query Employees</TAG>

Depending on the specific connection or activity type as listed below, you can use functions from the Functions tab that take a connector reference as an argument. The functions described below are available to be used with the listed connections and activities.

Data types

All source objects and global variables that are not null have a data type associated with them. Various data types can be changed using the functions in the Conversion functions category.

These data types are supported in Jitterbit Scripts:

Arrays

An array is a collection of variables. 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.

Set an array

You can set values in an array using the Set function 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 global variable, you can set the value of an array variable 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 variables 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>

As arrays are zero-indexed, the first element is at index 0 and the last element is at index (size-1). To append data to an array, pass either a negative index value or the size of the array (Length($arr)). Setting an element with an 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.

Here 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);

// Another way to set the n:th entry of an array
Set($arr, "value", Length($arr));

// Sets the value to a new variable at the end of the array
Set($arr, "value", -1);

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

Access 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 global variable, you can get a specific variable by specifying its index (or indices for a multi-dimensional array such as a record-set) as the second argument.

Some 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("<TAG>endpoint:database/My Database</TAG>", "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 variable 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 a variable beyond the end of the array results in an array out-of-range error.

These are examples of retrieving values from an array:

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

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

// Get the n:th variable 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.

<trans>
// Script to build and return an array
a = Array();
a[Length(a)] = "A";
a[Length(a)] = "B";
a[Length(a)] = "C";
a;
</trans>

<trans>
// Call the script to retrieve the array
$Arr = RunScript("<TAG>script:Build Array</TAG>");
</trans>

Dictionaries

In Jitterbit Script, a dictionary is a special type of global variable array that holds key-value pairs. The steps and functions are:

1. Initialize the dictionary using the Dict function:

   $d = Dict();
   

2. Load data with a key and a value:

   $d['4011'] = 'Banana';
   $d['4063'] = 'Tomato';
   

3. Check if the key already exists in the dictionary using the HasKey function:

   HasKey($d,'4011'); // Returns true
   

   In the example, we have already loaded the key '4011' so HasKey would return true.

   HasKey($d,'4089'); // Returns false
   

   If the key were not already loaded, for example '4089' the HasKey would return false.

4. Look up the value in the dictionary by passing the key and getting back the value:

   $d['4011']; // Returns 'Banana'
   

   In this example, the value returned would be Banana.

With dictionaries, keep these characteristics in mind:

• The scope of dictionaries is limited to the workflow. For example, if an operation loads $MyDict with 10,000 records, only those operations that are linked using "on success" or "on failure" paths, or with RunOperation, have access to that dictionary. But, if an operation uses chunking and threading, and has a transformation that populates a dictionary, the dictionary is inconsistent. This is because Harmony does not take the values assigned to variables by multiple operation threads and concatenate into a single value set. This is true for all global variables or arrays. Use the default chunking/threading values when building an operation that populates dictionaries.
• Dictionaries, because they use a binary search, are fast at finding keys and returning values. A key can usually be found within five to six tries. In contrast, compare this type of search to looping through a 10,000-record array to find a key.
• Dictionaries are not written to memory, so they do not materially impact available server memory for processing.