Dictionary and array functions in Jitterbit Integration Studio

Introduction

Dictionary and array functions provide storage structures for information in scripts. See the Related Functions in the side panel for additional functions that can be used with arrays.

Difference between arrays and dictionaries

Though very similar in many ways as a method to store information, arrays and dictionaries differ in these important characteristics:

• Arrays
  • Elements are ordered
  • Elements are retrieved by position
• Dictionaries
  • Elements are stored without regard to order, and have no intrinsic order
  • Elements are retrieved by a key

The syntax for setting and retrieving an element is similar (both can use the square-bracket notation) but the arrays have no keys associated with elements, and must store all items sequentially, with no gaps. Dictionaries can be sparse, with keys populated only as required.

Which one to use depends on the nature of the information. Dictionaries lend themselves to information that varies in how it is retrieved. Arrays are often better for ordered sets.

Set and retrieve values in arrays and dictionaries

// Example of an array
$org.lookup.currency = Array();
$org.lookup.currency[1]="USD";
$org.lookup.currency[2]="EUR";

// currency will be "USD"
currency = $org.lookup.currency[1];

// Example of a dictionary
$common.dictionary.message = Dict();
AddToDict($common.dictionary.message, 'OP_START', 'Start');
AddToDict($common.dictionary.message, 'OP_END', 'End');
AddToDict($common.dictionary.message, 'API_PARMS', 'API Parameters');

// message will be "API Parameters"
message = $common.dictionary.message['API_PARMS'];

Find values in dictionaries and arrays

For dictionaries, the HasKey function lets you test if a key is present. For an array, you can use the FindValue function in a similar fashion by passing two instances of the array to the function:

arr = {1, 2, 3};
value = 1;
t = (FindValue(value, arr, arr) == value);
// t will be 1 (true)

value = 4;
t = (FindValue(value, arr, arr) == value);
// t will be 0 (false)

AddToDict

Declaration

bool AddToDict(dictionary dict, string key, type arg)

Syntax

AddToDict(<dict>, <key>, <arg>)

Required parameters

• dict: An existing dictionary
• key: Key to be used in the dictionary
• arg: Value to be placed at that key

Description

Adds a value to a dictionary for a specific key.

The key must be a string or have a string representation, with null keys not allowed. Any value is allowed, even null values.

Returns true if the value was added and the new key added to the dictionary or false if the key already existed and the value at that key was instead updated. If the first argument is not defined or is not a dictionary, it will be initialized to an empty dictionary before the value is added.

See also the Dict function.

Examples

// Initialize a dictionary prior to use
d = Dict();


// Adds a value to a dictionary "d" if a key doesn't already exist
If(!HasKey(d, "key"), AddToDict(d, "key", "value"));

// To directly assign a key-value, use this syntax:
d["key"] = "value";

Array

Declaration

array Array()

Syntax

Array()

Description

Creates an empty array. Though arrays don't need to be initialized prior to use, this method can be used to be explicit or to reset an already-existing array. Arrays are zero-based, and values are retrieved using indexes.

Examples

// Create an empty array and set values
arr = Array();
arr[0] = "value1";
arr[1] = "value2";

// Create an array and set the first value directly:
arr2[0] = "value";

// Arrays can be created with { } syntax:
arr3 = {};

Collection

Declaration

array Collection()

Syntax

Collection()

Description

An alias for Array. See the function Array.

CollectValues

Declaration

array CollectValues(dictionary dict, array names)

Syntax

CollectValues(<dict>, <names>)

Required parameters

• dict: An existing dictionary
• names: An array of keys to be looked up in the dictionary

Description

Returns an array containing the values corresponding to the names in the argument array, returned in the same order as the keys in the array.

Examples

// Retrieve a map from a source instance
map = GetSourceInstanceMap([Values$Value.]);
names = Array();
names[0] = "Attr1";
names[1] = "Attr2";
// Array containing the values of
// the attributes named in the names array
values = CollectValues(map, names);

Dict

Declaration

dictionary Dict()

Syntax

Dict()

Description

Creates an empty dictionary. A dictionary is a collection of name-value pairs where the value is retrieved based on a string key value. Any value is allowed, even null values. The key must be a string or have a string representation. Null keys are not allowed. See also the AddToDict function.

Examples

// Creating a dictionary "myDictionary"
myDictionary = Dict();

// Assigning a value ("text") to the key "myKey"
myDictionary["myKey"] = "text";
// Using the AddToDict function instead
AddToDict(myDictionary, "myKey", "text");

GetKeys

Declaration

array GetKeys(dictionary dict)

Syntax

GetKeys(<dict>)

Required parameters

• dict: An existing dictionary

Description

Returns an array of the keys in a dictionary. The argument must be an existing dictionary.

Examples

// Retrieving the keys from the dictionary "myDictionary"
// using GetKeys and then looping through the array
// to retrieve all the values in the dictionary
// and writing them to the Operation Log
keys = GetKeys(myDictionary);
i=0;
While(i < Length(keys),
 WriteToOperationLog(myDictionary[keys[i]]);
 i++;
);

GetSourceAttrNames

Declaration

array GetSourceAttrNames(node n)

Syntax

GetSourceAttrNames(<n>)

Required parameters

• n: A string reference path expression to a node in the current transformation

Description

Returns an array containing the names of the attributes of a node, in the order that the attributes appear in the node.

Compare with the function GetSourceInstanceMap which returns a map of the keys (the attributes) and values for a node.

To enter an n path into the function, drag and drop the desired XML node folder from the Source Objects tab of the script component palette to the script to insert its qualified path at the location of your cursor, or enter its reference path manually. For more information, see the instructions on inserting source objects.

Examples

// Appends all the attributes together without having
// to explicitly reference their source data elements
map = GetSourceInstanceMap([Values$Value.]);
names = GetSourceAttrNames([Values$Value.]);
i = 0;
n = Length(names);
str = "";

While(i < n,
  str = str + map[names[i]];
  i++;
);

GetSourceElementNames

Declaration

array GetSourceElementNames(node n)

Syntax

GetSourceElementNames(<n>)

Required parameters

• n: A string reference path expression to a node in the current transformation

Description

Returns an array containing the names of the simple sub-elements for a node in the order that the attributes appear in the node.

Compare with the function GetSourceInstanceElementMap which returns a map of a node.

To enter an n path into the function, drag and drop the desired XML node folder from the Source Objects tab of the script component palette to the script to insert its qualified path at the location of your cursor, or enter its reference path manually. For more information, see the instructions on inserting source objects.

Examples

// Appends all the attributes together without having
// to explicitly reference their source data elements
map = GetSourceInstanceElementMap([Values$Value.]);
names = GetSourceElementNames([Values$Value.]);

// The values as an array of values from the sub-elements
values = CollectValues(map, names);

GetSourceInstanceArray

Declaration

array GetSourceInstanceArray(node n)

Syntax

GetSourceInstanceArray(<n>)

Required parameters

• n: A string reference path expression to a node in the current transformation

Description

Returns an array containing the attribute's value from an element node. The value in the array is labeled with the attribute's name, and can be retrieved either by its index or by its name as in a dictionary data element.

As an alternative to this function, see GetSourceInstanceMap.

To enter an n path into the function, drag and drop the desired XML node folder from the Source Objects tab of the script component palette to the script to insert its qualified path at the location of your cursor, or enter its reference path manually. For more information, see the instructions on inserting source objects.

Examples

arr = GetSourceInstanceArray([Values$Value.]);
// To retrieve the value of the "Attr1" attribute:
// If "Attr1" is the first attribute name, you can use:
v = arr[0];
// Or, you can use the name "Attr1":
v = arr["Attr1"];

GetSourceInstanceElementArray

Declaration

array GetSourceInstanceElementArray(node n)

Syntax

GetSourceInstanceElementArray(<n>)

Required parameters

• n: A string reference path expression to a node in the current transformation

Description

Returns an array containing the sub-element's value from an element node. The value in the array is labeled with the name of the sub-element, and can be retrieved either by its index or by its name as in the dictionary data element.

As an alternative to this function, see GetSourceInstanceElementMap.

To enter an n path into the function, drag and drop the desired XML node folder from the Source Objects tab of the script component palette to the script to insert its qualified path at the location of your cursor, or enter its reference path manually. For more information, see the instructions on inserting source objects.

Examples

arr = GetSourceInstanceElementMap([Values$Value.]);
// To retrieve the value of the "e1" sub-element:
// If "el" is the first sub-element, you can use:
v = arr[0];
// Or, you can use the name "e1":
v = arr["e1"];

GetSourceInstanceMap

Declaration

dictionary GetSourceInstanceMap(node n)

Syntax

GetSourceInstanceMap(<n>)

Required parameters

• n: A string reference path expression to a node in the current transformation

Description

Returns a dictionary (map) containing the attribute name and its value from an element node.

As an alternative to this function, see GetSourceInstanceArray.

To enter an n path into the function, drag and drop the desired XML node folder from the Source Objects tab of the script component palette to the script to insert its qualified path at the location of your cursor, or enter its reference path manually. For more information, see the instructions on inserting source objects.

Examples

map = GetSourceInstanceMap([Values$Value.]);
v = map["Attr1"];
// Returns the value of the "Attr1" attribute

GetSourceInstanceElementMap

Declaration

dictionary GetSourceInstanceElementMap(node n)

Syntax

GetSourceInstanceElementMap(<n>)

Required parameters

• n: A string reference path expression to a node in the current transformation

Description

Returns a dictionary (map) containing the sub-element's value from an element node.

As an alternative to this function, see GetSourceInstanceElementArray.

To enter an n path into the function, drag and drop the desired XML node folder from the Source Objects tab of the script component palette to the script to insert its qualified path at the location of your cursor, or enter its reference path manually. For more information, see the instructions on inserting source objects.

Examples

map = GetSourceInstanceElementMap([Values$Value.]);
v = map["e1"];
// Returns the value of the "e1" sub-element

HasKey

Declaration

bool HasKey(dictionary dict, string key)

Syntax

HasKey(<dict>, <key>)

Required parameters

• dict: An existing dictionary
• key: A key to check in the dictionary

Description

Checks whether a dictionary contains a specified key. Returns false if the first argument is not a dictionary or if the key was not found. As an equivalent function that works for arrays, see the examples of the FindValue function.

Examples

// Update the value in a dictionary "myDictionary"
// only if the key already exists
If(HasKey(myDictionary, "key"),
    myDictionary["key"] = "value");

Map

Declaration

dictionary Map()

Syntax

Map()

Description

An alias for Dict. See the function Dict.

MapCache

Declaration

string MapCache(dictionary dict, string key, string value)

Syntax

MapCache(<dict>, <key>, <value>)

Required parameters

• dict: An existing dictionary
• key: A key to check in the dictionary
• value: A value to be used (and stored) if the key is not in the dictionary

Description

This function caches a key/value pair to a dictionary. If the key already exists in the dictionary, the corresponding value will be returned; otherwise, the third argument will be evaluated, and that value would be stored in the dictionary for the key.

Examples

// Creating a dictionary "myDictionary"
// and caching values in it,
// if they don't already exist
myDictionary = Dict();
i=0;
a=MapCache(myDictionary, "key1", ++i);
b=MapCache(myDictionary, "key2", ++i);
c=MapCache(myDictionary, "key1", ++i);
result = i;
// The result will be
// result=2, a=1, b=2, and c=1
// as c's value will be retrieved
// rather than incremented

ReduceDimension

Declaration

array ReduceDimension(array arrayMultiD)

Syntax

ReduceDimension(<arrayMultiD>)

Required parameters

• arrayMultiD: A multi-dimensional array

Description

Given a multi-dimensional array with n _dimensions, the function returns an array with _n-1 dimensions. The lowest dimension of the input array will disappear, and their members will be collected to the next level dimension.

Examples

prices = ReduceDimension(orders$company.order#.detail#.price);
// If orders$company.order#.detail#.price
// is a 2-dimensional source data element array,
// the function will return a one-dimensional array

a = {{"0_0", "0_1"}, {"1_0", "1_1"}};
result = ReduceDimension(a);
// result will be {0_0, 0_1, 1_0, 1_1}

RemoveKey

Declaration

bool RemoveKey(dictionary dict, string key)

Syntax

RemoveKey(<dict>, <key>)

Required parameters

• dict: An existing dictionary
• key: A key to check in the dictionary

Description

Removes a key-value pair with a specific key from a dictionary. The key must be a string or have a string representation, and null values are not allowed. Returns true if the key-value pair was removed and false if the key didn't exist.

Examples

// Removes a key-value pair if it
// exists in dictionary "myDictionary"
If(HasKey(myDictionary, "key"),
    RemoveKey(myDictionary, "key"));

SortArray

Declaration

void SortArray(array arrayToSort[, bool isAscending])

void SortArray(array arrayToSort, int index[, bool isAscending])

Syntax

SortArray(<arrayToSort>[, <isAscending>])

SortArray(<arrayToSort>, <index>[, <isAscending>])

Required parameters

• arrayToSort: An array to be sorted
• index: For multi-dimensional arrays, index of array to be sorted on (default 0)

Optional parameters

• isAscending: If the array is to be sorted in ascending order (the default)

Description

Sorts an array by reference. The return value is undefined and should be ignored.

In the first form, the second parameter (optional) specifies the sort order.

In the second form, for multi-dimentional arrays, the function sorts the array according to a zero-based index specified in the second parameter (required). In the second form, the third argument (optional) specifies the sort order.

The default sort order is ascending in both forms.

After the function returns, the array will be sorted in-place. If specified, it will be sorted according to the index.

Multiple sorting of the same array is possible by applying the SortArray function repeatedly.

Examples

// Sorting a one-dimensional array
arr1 = {"Carol", "Bob", "Alice"};
SortArray(arr1);
// arr1 is now {Alice, Bob, Carol}

// Sorting a two-dimensional array
arr2 = {{"a", 20, 1}, {"bc", 7, 12}, {"x", 20, 13}, {"d", 5, 4}};

// Sort arr2, order by third column, descending
SortArray(arr2, 2, false);
// arr2 is now {{x, 20, 13}, {bc, 7, 12}, {d, 5, 4}, {a, 20, 1}}

// Sort arr2, order by second column, ascending
SortArray(arr2, 1);
// arr2 is now {{d, 5, 4}, {bc, 7, 12}, {x, 20, 13}, {a, 20, 1}