BridgeGate™

Tutorial 11: Using Variable Collections

Table of Contents

Getting Started with the Variable Collection Tutorial

In this exercise we will be demonstrating the use a collections within BridgeGate™ to aggregate, manipulate, and write outbound data. If you are already familiar with the Variable object used on the Outbound Template, then you are already half way to understanding the Variable Collection. The main difference between the two is that the Variable Collection is just that; it is an array of Variable objects you can use in any way needed to accomplish tricky or cumbersome business logic.

Several examples of using a Variable Collection will be demonstrated here, with the intent being to show you general usage, not an exhaustive list of options. Variable Collection is just another feature, and when combined with other features in BridgeGate™, the number of ways you can use a Variable Collection becomes too vast for the scope of this tutorial.

The sample templates used for this tutorial are variations of Tutorial 1 - Introduction, with modifications made to demonstrate adding values to, performing operations on, and looping over variable collections.

Adding Values to a Variable Collection

You add values to a Variable Collection just as would a Variable. The major different is select which position in the array you would like to put the value. The default location is the 'NEXT' available position. Other values include a literal number, such as '2' to indicate you want to add a value to the second position, overwriting any current value there.

Adding items to a variable collection is straight forward, and it's the easiest part of the process. Your business logic will dictate when and how you add items to a variable collection. Here are a couple scenarios we will demonstrate.

Scenario 1: Adding data to a variable collection at the same time you are writing data to output.

Scenario 2: Looping over inbound data to add to a variable collection only.

Note: Adding a value to location #1, the adding a value to location #20, will leave 18 empty values in between. Subsequent looping over the Variable Collection will produce 18 iterations with no value.

Performing Operations on a Variable Collection

Once you have your data in a Variable Collection, you can manipulate it to accomplish a task. There are several types of built in operations available on the variable collection screen to perform a calculation or manipulation automatically, or you can loop over a variable collection via a Loop and perform business logic on the fly. Here are a couple scenarios we will demonstrate.

Scenario 3:

You want to remove duplicate items from the variable collection, and only use the unique/distinct values

You want to sort in Ascending/Descending order

You want to write the entire variable collection into a single record (i.e. flatten the structure into a single record)

Scenario 4:

You want to determine the total count of the items in the variable collection

You want to determine the minimum value of items in the variable collection

You want to determine the maximum value of items in the variable collection

You want to determine the average value of items in the variable collection

Looping over Variable Collections

You loop over variable collections when you want to write the data to your outbound data, or when you want to perform operations on the data that require you to individually get each item from the variable collection, and pass them into plugins, sequences, custom db fields, conditional field lists, etc. Here are a couple scenarios we will demonstrate.

Scenario 5: You want to loop over the variable collection to write the data.

Scenario 6: You want to loop over the variable collection and conditionally write that data, if the data meets certain criteria.

Example 1

All of the examples for this tutorial use the same inbound template. Example 1 also uses the example1 outbound template, and the example1 workflow. We will use this example to demonstrate scenario 1 of 'Adding Values to a Variable Collection', scenario 3 of 'Performing Operations on a Variable Collection', and scenario 5 of 'Looping over Variable Collections'.

In this example we have an outbound template that has already been set up to loop over the inbound data and write it out in a different format than it was read, from Tab Delimited to CSV. However, we will also be adding a variable collection to the loop in order to collect the 'Ship to State' field from each record. When all the inbound records have been iterated over, we will then sort the variable collection in ascending order, and removing any duplicate States from the collection. Finally, we write the States out using the trailer of the outbound template.

Example 2

All of the examples for this tutorial use the same inbound template. Example 2 also uses the example2 outbound template, and the example2 workflow. We will use this example to demonstrate scenario 2 of 'Adding Values to a Variable Collection', scenario 3 of 'Performing Operations on a Variable Collection', and scenario 5 of 'Looping over Variable Collections'.

In this example we have an outbound template that does not loop over the data we want to collect; we will have to add a Loop specifically for this purpose. When all the inbound records have been iterated over, we will then perform mathematical operations on the variable collection. We can easily determine the total count of items in the variable collection, as well as the minimum value, maximum value, and average value in the collection. To do this, we will be looping over the 'Overall Total' field of the inbound data, which contains the order total. Finally, we write the results of our mathematical operations out using the trailer of the outbound template.

Note: All values must be value numbers

Note: 'use record delimiter at end of record' is unchecked while looping over data to collect it.

Example 3

All of the examples for this tutorial use the same inbound template. Example 3 also uses the example3 outbound template, and the example3 workflow. We will use this example to demonstrate scenario 6 of 'Looping over Variable Collections'.

A hypothetical business requirement for this example would be to send a list of SKUs to another department that needs to be notified when a certain category of SKUs are being ordered. To accomplish this, we have an outbound template that does not loop over the data we want to collect; we will have to add a Loop specifically for this purpose. When all the inbound records have been iterated over, we will then sort the variable collection in ascending order, and removing any duplicate SKUs from the collection. Finally, we write the SKUs out using the trailer of the outbound template, only if the SKU ends with the SKU designator 'VAL'.