Function: GETITEMVALUES

 

Description
GETITEMVALUES returns attribute or calculated values from multiple other items. Use it to gather lists/arrays of values (e.g., costs, statuses) for sets of items — often combined with WHERE, IF, SUM and other functions to produce roll-ups or aggregated results.

Unlike GETITEMVALUE (single value), GETITEMVALUES returns an ARRAY of values.

 

Syntax
GETITEMVALUES(itemIdentifier, codeValue)
GETITEMVALUES(itemIdentifier, codeValue, type)

 

Parameters
- itemIdentifier — The identifier(s) of the source items whose values you want. Defaults to name if type omitted. Can be:
  - A single name/ID (returns a single-item array)
  - An array of names/IDs using square brackets: ['ITEM 1','ITEM 6']
  - A WHERE expression that evaluates to one or more items: WHERE(Parent=={name})
- codeValue — The attribute or calculated value code to return (e.g., "Cost", "RAG Status").
- type (optional) — How to interpret itemIdentifier: "name" (default), "Internal ID", or "External ID".

 

Return Value
ARRAY — an array of values of the specified codeValue for the matching items. The element type matches the referenced attribute/calculation (NUMBER, DATE, TEXT, BOOLEAN, etc.). If no items match, returns an empty array or NULL depending on context.

Examples

1) Return costs for ITEM 1 and ITEM 6
Formula
GETITEMVALUES(['ITEM 1','ITEM 6'], 'Cost')
Result
[Cost_of_ITEM_1, Cost_of_ITEM_6] (e.g., [99, 103])

 

2) Return values for children (using Parent relationship)
Formula
GETITEMVALUES(WHERE(Parent == {name}), 'Cost')
Result (for a parent with children cost 100 and 101)
[100, 101]

 

3) Sum child costs to produce a parent total
Formula
SUM(GETITEMVALUES(WHERE(Parent == {name}), 'Cost'))
Result
201 (for child costs 100 + 101)

 

4) Single-item array returned when identifier is one item
Formula
GETITEMVALUES('ITEM2', 'Cost')
Result
[100]

 

Notes
- Default lookup is by name; specify type when using internal/external IDs.
- Use square brackets [] for literal arrays of identifiers and to indicate array literals.
- Combine with aggregation (SUM, AVERAGE), filters (WHERE), or mapping functions to produce roll-ups or derived arrays.
- When GETITEMVALUES receives identifiers that resolve to no items, it yields an empty array or NULL; handle accordingly.
- For single-value needs, consider GETITEMVALUE; for multi-item results use GETITEMVALUES.