Skip to main content

Uniphore Customer Portal

Collections and Allocators: Use Case Examples

A Collection is a type of User or Session Variable that contains a set of items. It is always one of the following types:

  • Simple Collection: Contains a list of values. Each value is of the same primitive data type (number, date, etc.)

  • Object Collection: Contains a list of items (objects) that are each made up of a set of fields. For example, a customer's Object Collection might be made up of the fields First Name, Last Name, Account ID, Phone Number, etc. Objects that are available for use in a Collection are defined in the X-Console using Custom Types, Enums, Rules, or Intents.

Tip

A Collection can be defined as both a User Variable (available for use in the current Flow) or as a Session Variable (available globally for all Flows in the account).

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

After you define a Collection type variable, you can use it in many different ways in your Flow. Typically, the Collection is used together with the Allocator element to change or update the values in the Collection according to the needs of the Flow.

Some common use cases for manipulating a Collection are found below.

Adding a Value to a Collection

In this common use case, a new 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.) At runtime, the value is added to the end of the existing Collection content.

  1. From the Flow map, create an Allocator in the desired location. The Allocator Editor will open.

  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.

    203688523-AllocatorEditorLeftSide.png

  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:

    203688593-AllocatorEditorRightSide.png

  4. To add additional values to the Collection, click the 203539736-Icon_add.png Plus icon and then repeat Step 2 through Step 3.

  5. At the lower right corner of the page, click Create Allocator. The Allocator Editor closes, and the allocator step appears on the Flow map.

During 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 Flow map, create an Allocator in the desired location. The Allocator Editor will open.

  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.

    203688633-AllocatorEquals.png

  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.

    203688643-CollectionSize.png

  5. At the lower right corner of the page, click Create Allocator. The Allocator Editor closes, and the allocator step appears on the Flow map.

During 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 element (e.g., a Paragraph).

  1. From the Flow map, create an Allocator in the desired location. The Allocator Editor will open.

  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.

    203539786-ElementAt.png

  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).

    203688653-ElementAt1.png

    Caution

    If you assign an .elementAt index location whose number is greater than the total number of indexed items in the requested Collection, then the executing Flow will terminate with an exception during runtime.

  6. At the lower right corner of the page, click Create Allocator. The Allocator Editor closes, and the allocator step appears on the Flow map.

During 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 Flow. It does not delete the item from its referenced Collection source variable.

  1. From the Flow map, create an Allocator in the desired location. The Allocator Editor will open.

  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.

    203688523-AllocatorEditorLeftSide.png

  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.

    211353926-CollectionsAllocatorsUse_RemoveValue_281116.png

  5. At the lower right corner of the page, click Update Allocator. The Allocator Editor closes, and the allocator step appears on the Flow map.

During 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 Flow map, create an Allocator in the desired location. The Allocator Editor will open.

  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.

    115017339383-AddAllTransferCollection_191017.png

  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 Flow map.

During runtime, all source Collection variables will be transferred to the specified target Collection for use in the current Flow.

In this section: