A Collection is a type of variable that holds a set of items. A Collection is always one of the following types:

  • Simple Collection: Contains a list of values. Each value is of the same data type (number, date, etc.)
  • Object Collection: Contains a list of items (objects) that are each made up of a set of fields. Objects are defined in the Admin Console as custom variable types.

Collections are often used to receive values from an outside service via an Integration Point.

Once you define a Collection type variable, you can use it in many different ways in your Interaction. Usually a Collection is used together with the Allocator element to manipulate values in the Collection (and an Interaction) according to your needs.

Note: A Collection can be defined at both the user level (available for use in the current Interaction) or at the system level (available globally for all Interactions).

Common use cases for manipulating a Collection are found below.

Adding a Value to a Collection

In this use case, a value is added to an existing simple Collection. The value can be hard coded, or it can be taken from any other existing variable of the same data type. (For example, you can add another number to a Collection of numbers.) In runtime, the value is added to the end of the existing Collection content.

  1. From the Interaction map, hover over a step and select Nagivation Logic > Allocator.
    The Allocator Editor opens.
  2. In the field on the left side of the allocation, enter @ and then, from the Variables list, select the Collection to which you want to add values.

  3. In the field on the right side of the allocation, enter the value you want to add. Alternatively, enter @ and then, from the Variables list, select the variable to add.
    In the following example, the fourth item from a second Collection is added to the first Collection:

  4. To add additional values to the Collection, click  and then repeat Steps 2-5.
  5. At the lower right corner of the page, click Create Allocator.
    The Allocator Editor closes, and the allocator step appears on the Interaction map.
    In runtime, the specified values will be added to the end of the Collection.

Getting the Size of a Collection

In this use case, the size of a Collection (simple or object) is allocated into a number variable.

  1. From the Interaction map, hover over a step and select Nagivation Logic > Allocator.
    The Allocator Editor opens.
  2. In the field on the left side of the allocation, enter @ and then, from the Variables list, select the relevant variable. Alternatively, create a new variable. The variable type must be Number.
  3. Click the list of operators in the center of the Allocator Editor, and select the Equals operation.

  4. In the field on the right side of the allocation, enter @ and then, from the Variables list, select the .length variable for the relevant Collection.

  5. At the lower right corner of the page, click Create Allocator.
    The Allocator Editor closes, and the allocator step appears on the Interaction map. 
    In runtime, the Collection size is allocated into the specified variable.

Accessing an Item From a Collection

In this use case, an indexed item from a simple or object Collection is allocated into a variable. This variable can then be used in another Interaction element (e.g., a Paragraph).

  1. From the Interaction map, hover over a step and select Nagivation Logic > Allocator.
    The Allocator Editor opens.
  2. In the field on the left side of the allocation, enter @ and then, from the Variables list, select the relevant variable. Alternatively, create a new variable.
    Make sure that the variable you select is of the same data type as the Collection you want to access.
  3. Click the list of operators in the center of the Allocator Editor, and select the Equals operation.
  4. In the field on the right side of the allocation, enter @ and then, from the Variables list, select the .elementAt variable for the relevant Collection.

  5. In the parentheses at the right side of the variable name, enter the index of the item you want to access.
    Keep in mind that the index count begins at 1 (not zero).


  6. At the lower right corner of the page, click Create Allocator.
    The Allocator Editor closes, and the allocator step appears on the Interaction map.
    In runtime, the Collection size is allocated into the specified variable.

Removing an Item From a Collection

In this use case, an indexed item from a simple or object Collection is removed from the Collection. After its removal, the next value (and all subsequent values) in the Collection are relocated to take the place of the value that was removed.

Note: Removing an item with the RemoveAt operator only removes it from this instance of the Collection in this Interaction. It does not delete the item from its referenced Collection source variable.

  1. From the Interaction map, hover over a step and select Navigation Logic > Allocator.
    The Allocator Editor opens.
  2. In the field on the left side of the allocation, enter @ and then, from the Variables list, select the Collection to which you want to remove a value.

  3. Click the list of operators in the center of the Allocator Editor, and select the RemoveAt operation.
  4. In the field on the right side of the allocation, enter the number for the position of the variable you want to remove.

  5. At the lower right corner of the page, click Update Allocator.
    The Allocator Editor closes, and the allocator step appears on the Interaction map.
    In runtime, the specified Collection variable will be removed from the Collection.

Transferring Variables Between Collections

In this use case, all variable values from one Collection are transferred to a second Collection using the AddAll operator. You might want to perform this activity in order to append a local set of Collection values to values that are stored elsewhere.

  1. From the Interaction map, hover over a step and select Navigation Logic > Allocator.
    The Allocator Editor opens.
  2. In the field on the left side of the allocation, enter @ and then, from the Variables list, select the local Collection to which you want to add the complete list of values.

  3. Click the list of operators in the center of the Allocator Editor, and select the AddAll operation.
  4. In the field on the right side of the allocation, enter the source Collection from which you want to transfer the variables.
  5. At the lower right corner of the page, click Create Allocator.
    The Allocator Editor closes, and the allocator step appears on the Interaction map.
    In runtime, all source Collection variables will be transferred to the specified target Collection for use in the current Interaction.

 

Revision:

Comments