Working with lists
Lists are a means to access and work with multiple values for objects and fields.
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).
at ([$Estimated Loss
$], 0)
The following expression results in 15000.00, the value of the item in the third position (index position two).
at
([$Estimated Loss
$], 2)
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.
When an expression result is... | Output Field is set to ... |
---|---|
One related object | The field value from that object |
Multiple related objects but they all have the same field value | The value from the objects |
Multiple related objects, where only one object has a value and the others are not set | The value from the one object |
Multiple related objects, where they have different values | No value is set and a calculation error is issued. |