Working with lists

Show me how

This video shows you how to work with lists. It explains how to retrieve values from related objects fields, work with multi-valued fields, create and manipulate lists, and apply functions to items in a list.

About lists

A common requirement for a calculation is to get values from multiple objects and do something with the list of values that is retrieved.

To get the values from multiple objects, define an Input Field operation that designates what object type and field you want to retrieve. You can optionally apply a condition to get only specific values. For more information, see Applying a condition to get only specific objects in a list. You can also optionally sort the values in ascending or descending direction either by the chosen field or another field on the object type.

The result of such an Input Field operation is a list of values.

For example, for a calculation on the Loss Event object type, the Estimated Loss operation retrieves values in the OPSS-LossIm:Estimated Loss field on all child LossImpact objects. If there are four child objects, the result is like this:

5000.00, 10000.00, 15000.00, 20000.00

If the list were sorted in descending order, it would be:

20000.00, 15000.00 10000.00 5000.00

Expressions in subsequent operations can refer to the Estimated Loss operation and apply functions either to the entire list or individual items in the list using an index. The term index refers to positions in the list, where the index starts counting at zero. In the previous example, the value 20000.00 is in index position 0, 15000.00 is in position 1, and so on.

The same principle applies if an Input Field operation retrieves values from a field that contains multiple values, for example, a multi-actor field. You can optionally apply a condition to get only specific values. You can also optionally sort the values in ascending or descending direction either by the chosen field or another field on the object type.

Some functions can be applied to all items in a list, regardless of the type of data in the list. For example, the count function can be used for any list. Given the previous example, the result of the following two example expressions is 4.

count ([$Estimated Loss$])

count ([$Child:LossImpact/OPSS-LossIm:Estimated Loss$])

Some functions can be applied to lists of specific data types. For example, for a list that contains numerical values, you can use the sum, max, and min functions.

For example, a Set Field operation can contain this expression that sets Estimated Gross Loss on the parent Loss Event to sum of the results in the Estimated Loss operation:

if exists (SUM ([$Estimated Loss$]) )then SUM ([$Estimated Loss$])  else currency(0.00, 'USD')

The result of the Set Field operation would be 50000.00 (20000.00 + 15000.00 + 10000.00 + 5000.00).

For a list that contains string values, you can use functions that split, join, and concatenate string values.

Some functions use the index so that you can access specific positions in the list, for example, you can use the at function to access specific items in a list. For example, if the Estimated Loss operation results in the following list:

5000.00, 10000.00, 15000.00, 20000.00

The following expression results in 5000.00, the value of the item in the first position (index position zero).

The following expression results in 15000.00, the value of the item in the third position (index position two).

You can also add and remove items from the list. For example, the following expression appends items to a list:

append( [$Estimated Loss$], 30000.00, 40000.00, 50000.00 )

Results in the following list:

5000.00, 10000.00, 15000.00, 20000.00, 30000.00, 40000.00, 50000.00 

Applying a condition to get only specific objects in a list

You can optionally apply a condition to get only specific objects in a list. For example, say that for a calculation on Risk objects, you want to get a count of child Control objects. But you only want to count Control objects whose Operating Effectiveness is set to Effective. Define an input field named GetControls for Control objects and specify a Filter By condition where Operating Effectiveness is equal to Effective. Then define an operation with the expression count ([$GetControls$]). The result is a count of Control objects whose Operating Effectiveness is set to Effective.

Setting an Output Field value when the expression result is a list

Special rules apply when an expression result is a list of values but the Set Field operation contains an Output Field that sets a single field value.