Populate and Use a Dictionary¶

Introduction¶

A dictionary is a special kind of global variable that builds an array of key-value pairs. A frequent use case is as a cross-reference list, such as when a data source provides a key and a target requires a value based on that key.

Populate a Dictionary¶

A required best practice is to first initialize the dictionary using the Dict function:

$dict.mylist = Dict()

A dictionary entry can then be created using the AddToDict function:

AddToDict(<dict name>,<key>, <value>)

There are scenarios where we want to simply capture the keys in the dictionary and any values are irrelevant. In that case, it is acceptable to use:

AddToDict(<dict name>, <key>, true)

Another scenario is where the value itself is a list, so we want to first check if the dictionary entry exists, and then get the value and append it back to the dictionary. This can also be used to sum values. HasKey is used in this case:

my_value = <data from source>;
my_key = <data from source>;
If(HasKey($dict.mylist,my_key)  // Check if my_key is in the dictionary
, // If true
value = $dict.mylist[my_key]; // Get the original value
new_value = value + “|” + my_value; // Append the new value
AddToDict($dict.mylist,new_value); // Write the new appended value back to the dictionary
, // If false
AddToDict($dict.mylist,my_value);
);

Read a Dictionary¶

If an attempt is made to read a value from a dictionary and the key does not exist, this is treated as a failure. A best practice is to always first use HasKey to verify that the key exists. See the third line in the above code for an example. As dictionary entries are always in alphabetical order and are always unique, using AddToDict with an existing key will overwrite the entry.

Dictionaries are frequently read to generate a list of data that is read with a While loop:

arr = Array();
arr = KeyList($dict.mylist);
i = 0;
While(i < Length(arr),
value = $dict.mylist[i];
<some action>
i++);

Dictionaries are also used in transformation conditions as a filter. Assume a dictionary is populated and a transformation needs to read a source and only process records if the dictionary value is in the record. The condition of the target transformation would have a script such as this:

pass = true;
If(!HasKey($dict.mylist,<mapped value from source record>), pass = false);
pass;

The scope of dictionaries, like all global variables, is limited to the instance of the operation thread. But they are not thread-safe. Be careful when populating a dictionary when using the asynchronous option with RunOperation. The dictionary will not retain its data between multiple threads.