List

Extended supports lists, which are a data structure that can contain many elements. When printed as text, lists are displayed using square brackets [] → [<element1>, <element2>, ...]

The elements can be of any other data type, such as numbers, strings, booleans and objects. Lists can be created using the LIST() function.

myList := LIST(1, 2, 3, 4, 5)
myList                              // [1, 2, 3, 4, 5]

The elements of a list are not restricted to a single data data type. Multiple data types can be used.

myList := LIST(55, "taco", TRUE)
myList                             // [55, taco, true]

The indexing for Lists starts at 0. This means that the first element is located at index 0, the second element is at index 1, the third element is at index 2 and so on.

Queries and certain token expressions will resolve to lists.

Expression	Result
`this.object.children`	List of the first-level children of the object.
`SELECT Kpi`	List of all the model KPIs.

List Operators & Functions

LIST

The LIST() function is used to create an empty list, or a list of specified items. Items can be of any datatype supported by Extended.

Syntax	Result
`LIST()`	Creates an empty list
`LIST([<item1>], [<item2>], ...)`	Creates a list containing the specified items

items: [Optional] Items to be added to the list.

Examples

myList := LIST(1, 2, 3, 4, 5)
myList                              // [1, 2, 3, 4, 5]

myList := LIST(o.100, o.101, o.102)
myList                              // [Corporate Org, EMEA Org, Asia Org]

CONTAINS

The CONTAINS operator can be used to check if a list contains an item.

Operator	Definition
`CONTAINS`	Checks if a list contains an item

Examples

myList := LIST(1, 2, 3, 4, 5)
myList                              // [1, 2, 3, 4, 5]
myList CONTAINS 1                   // True

IN [ 5.3.0.0 +]

The IN operator can be used to check if an item is in a List of items.

Operator	Definition
`IN`	Checks if an item is within a List

Examples

myList := LIST(1, 2, 3, 4, 5)
1 IN myList                                 // True
6 IN myList                                 // False

inactiveUsers := SELECT User WHERE inactive                     // All Users marked as inactive
oldOwnerKpis := SELECT Kpi WHERE measureOwner IN inactiveUsers  // All Kpis with a Measure Owner (single reference property) that is inactive

NOT

The NOT operator can be used to invert the value returned by the IN and CONTAINS operators. It is not supported for other uses.

Operator	Definition
`NOT`	Inverts the value of `CONTAINS` and `IN` operators.

Examples

myList := LIST(1, 2, 3, 4, 5)
myList NOT CONTAINS 1                                                   // False
myList NOT CONTAINS 6                                                   // True
1 IN myList                                                             // True
6 IN myList                                                             // False

regularKpis := SELECT Kpi WHERE measureOwner NOT IN g.managers          // All Kpis with a Measure Owner that is not in the managers group

/* All Risks that have not been assigned the Reputation Risk Category
 * assignedRiskCategories is a multi-select reference property
 * t.CATEGORY_REPUTATION is one of the possible reference choices for assignedRiskCategories
 */
nonRepRisks := SELECT ManualRiskFactor
    WHERE assignedRiskCategories NOT CONTAINS t.CATEGORY_REPUTATION

Methods

Methods that can be chained onto lists, or list variables, to perform specific actions.

as

The as() method takes a property as a parameter and returns a list consisting of that property’s value for each item in the original list.

Syntax	Return Value
`<list>.as(<property>)`	List of `property` values of each item in the original list

Examples

basketballKpis := list(t.KP001, t.KP002, t.KP003)
basketballKpis.as(responsible)                          // [Michael Jordan, Larry Bird, Hakeem Olajuwon]

The avg() method returns an average of all the numeric values in the list. Any non-number values in the list are excluded from the average calculation. If the list does not contain any numbers, NA will be returned.

Syntax	Return Value
`<list>.avg()`	The average of the numbers in the list

Examples

myList := LIST(50, 100)
myList.avg()                                      // 75

myList2 := LIST(50, "ABC", "999", 100, false)
myList2.avg()                                     // 75

distinct

Returns a list with duplicate elements removed. For information on how Object Equality is handled see Object Equality.

Syntax	Return Value
`<list>.distinct()`	List with all the unique elements

Examples

animals := LIST("dogs", "cats", "tigers", "dogs", "elephants", "cats", "dogs")

animals.distinct()                      // [dogs, cats, tigers, elephants]

The code above creates a list containing several duplicate elements, and then removes the duplicate elements.

filter

Returns a list containing the elements of the original list that met a condition.

Syntax	Return Value
`<list>.filter(<condition>)`	List containing the elements that met the `condition`

condition: An expression resolving to a boolean.

Examples

myKpis := LIST(t.200, t.201, t.202)            // KPIs Revenue, Upsell Revenue, and Net Income
myKpis.filter(name = "*Revenue*")              // [Revenue, Upsell Revenue]

The code creates a list of KPI objects, and then the filter iterates over each KPI in the list and checks the condition. The condition looks for KPIs that have a name that contains “Revenue”. The expression returns a list of all the KPIs that met this condition.

first

Returns the first element, or the first n elements of a list.

Syntax	Return Value
`<list>.first()`	The first element of the list
`<list>.first([<n>])`	List containing the first `n` elements

n: [Optional] The number of elements to be returned. If not specified, the first element is returned.

Examples

myBands := LIST("Dire Straits", "Rainbow", "Deep Purple")
myBands.first()                                                 // Dire Straits
myBands.first(2)                                                // [Dire Straits, Rainbow]

The initial use of first in the code above returns the first element Dire Straits. The second use returns a list containing the first two elements [Dire Straits, Rainbow].

item

Returns the element at a given index. The indexing for Lists starts at 0. This means that the first element is located at index 0, the second element is at index 1, the third element is at index 2 and so on.

Syntax	Return Value
`<list>.item(<n>)`	The element at index `n`

n: The index of the desired element

Examples

myBands := LIST("Dire Straits", "Rainbow", "Deep Purple")
myBands.item(1)                                                 // Rainbow
myBands.item(2)                                                 // Deep Purple

join

The join() method concatenates all of the items in a list and returns a String. If the items in the list are not Strings, their String representation will be used. The method takes a separator String as an argument, which will be placed between each of the former list items in the returned String.

Syntax	Return Value
`<list>.join(<separator>)`	String with the concatenated list items, separated by the separator

separator: The separator String to be concatenated between the list items.

Examples

myList := LIST("ABC", "DEF", "GHI")
myList.join("")                                 // "ABCDEFGHI"

myKpis := SELECT Kpi
myKpis.join(";")                                // "109 Turnover;108 Net Promoter Score;107 Revenue"

myKpis := SELECT Kpi
myKpis.as(name).join(";")                       // "Turnover;Net Promoter Score;Revenue"

last

Returns the last element, or the last n elements of a list.

Syntax	Return Value
`<list>.last()`	The last element of the list
`<list>.last([<n>])`	List containing the last `n` elements

n: [Optional] The number of elements to be returned. If not specified, the last element is returned.

Examples

myBands := LIST("Dire Straits", "Rainbow", "Deep Purple")
myBands.last()                                                 // Deep Purple
myBands.last(2)                                                // [Rainbow, Deep Purple]

The initial use of last in the code above returns the last element Deep Purple. The second use returns a list containing the last two elements [Rainbow, Deep Purple].

max

Returns the largest value in a list. Any non-number values in the list are excluded. If the list does not contain any numbers, NA will be returned.

Syntax	Return Value
`<list>.max()`	The largest value in the list

Examples

myList := LIST(55, 1, 24)
myList.max()                            // 55

myList := LIST(55, "Hello", o.100, 78)
myList.max()                            // 78

myList := LIST("A", "B", "C")
myList.max()                            // NA

merge

Returns a list containing all the elements from two lists. Any duplicate elements are removed.

Syntax	Return Value
`<list1>.merge(<list2>)`	List with all the distinct elements from list1 and list2

list2: A list to be merged with the first list.

Examples

fruits1 := LIST("nectarines", "bananas", "grapes")
fruits2 := LIST("rasberries", "pears", "mangos")
fruits1.merge(fruits2)                                  // [nectarines, bananas, grapes, rasberries, pears, mangos]

fruits3 := LIST("nectarines", "apples", "kiwi")
fruits1.merge(fruits3)                                  // [nectarines, bananas, grapes, apples kiwi]

The first 3 lines merge two entirely different lists. The output is a list with all of their elements. The last 2 lines merge two lists which share an element "nectarines". The output is list with all unique elements. The duplicate nectarines is removed.

min

Returns the smallest value in a list. Any non-number values in the list are excluded. If the list does not contain any numbers, NA will be returned.

Syntax	Return Value
`<list>.min()`	The smallest value in the list

Examples

myList := LIST(55, 1, 24)
myList.min()                            // 1

myList := LIST(55, "Hello", o.100, 78)
myList.min()                            // 55

myList := LIST("A", "B", "C")
myList.min()                            // NA

remove

The remove() method can be used to remove an item, or a list of items, from a list. If there is more than one instance of an item in the list, all instances of the item will be removed.

Syntax	Return Value
`<list>.remove(<item>)`	Removes the item `item` from the list
`<list1>.remove(<list2>)`	Removes all the items in `list2` from the list

item: The item to be removed from the list
list2: The list of items to be removed from the list

Examples

myList := list(1, 3, 5, 1, 1, 1, 7)
myList.remove(1)                                                // [3, 5, 7]

myList := list(t.KP001, t.KP002, t.KP003, t.KP004, t.KP005)
badItems := list(t.KP001, t.KP003)
myList.remove(badItems)                                         // [t.KP002, t.KP004, t.KP005]

reverse

Returns a version of the list in reversed order.

Syntax	Return Value
`<list>.reverse()`	List in reverse order

Examples

numberList := LIST(1, 100, 55, 3, 89)
numberList.reverse()                    // [89, 3, 55, 100, 1]

size

Returns the number of elements in a list.

Syntax	Return Value
`<list>.size()`	Number of elements

Examples

myFruits := LIST("Nectarines", "Bananas", "Grapes")
myFruits.size()                                             // 3

sort

Returns an ascendingly sorted version of a list based on natural order, or based on an expression. Natural order will order things alphabetically, except for strings containing numbers. Numbers in strings are handled as the entire number. For example a9 would be sorted before a1111111 because 9 is smaller than 1111111

Syntax	Return Value
`<list>.sort()`	List sorted by natural order
`<list>.sort([<expression>])`	List sorted by expression

expression: [Optional] An expression for sorting. Typically a property for sorting a list of objects.

Examples

numberList := LIST(1, 100, 55, 3, 89)
numberList.sort()                               // [1, 3, 55, 89, 100]
objectList := LIST(t.200, t.201, t.202)         // KPIs "Revenue", "Net Promoter Score", "Customer Satisfaction"
objectList.sort(name)                           // [Customer Satisfaction, Net Promoter Score, Revenue]

The first 2 lines of the code above make a list of numbers, and then sort it using natural order. The last 2 lines of the code above make a list of KPI objects, and then sort the list based off the name property of the KPI.

sortReverse

The sortReverse() method returns a descendingly sorted version of a list.

Syntax	Return Value
`<list>.sortReverse()`	List sorted by natural order
`<list>.sortReverse([<expression>])`	List sorted by expression

expression: [Optional] An expression for sorting. Typically a property for sorting a list of objects.

Examples

numberList := LIST(1, 100, 55, 3, 89)
numberList.sortReverse()                        // [100, 89, 55, 3, 1]
objectList := LIST(t.200, t.201, t.202)         // KPIs "Revenue", "Net Promoter Score", "Customer Satisfaction"
objectList.sort(name)                           // [Revenue, Net Promoter Score, Customer Satisfaction]

sum

The sum() method returns a sum of all the numeric values in the list. Any non-number values in the list are excluded from the sum calculation. If the list does not contain any numbers, NA will be returned.

Syntax	Return Value
`<list>.sum()`	The sum of the numbers in the list

Examples

myList := LIST(10, 15, 50)
myList.sum()                                  // 75

myList2 := LIST(10, o.100, "hello", 49, 20)
myList2.sum()                                 // 79

tree [ 5.2.0.1 +]

The tree() method creates a structure of nested lists called a treelist. These treelists greatly simplify the process of making tree tables. tree() takes two optional parameters: an expression resolving to a list of children used to create the treelist, and an expression resolving to a boolean that determines whether a level of children should be collapsed. The tree() method will continue to descend levels based on the first parameter (children expression) until nothing is returned. The table() method works with treelists.

Syntax	Result
`<object>.tree()`	Treelist of `object` and all the descendants of `object`
`<object>.tree([<childExp>])`	Treelist of `object` and all the objects returned by `childExp` expression
`<object>.tree([<childExp>], [boolExp])`	Treelist of `object` and all the objects returned by `childExp` expression, sublists collapsed if `boolExp` was true
`<objectList>.tree()`	Treelist of all descendants of the objects in `objectList`
`<objectList>.tree([<childExp>])`	Treelist of `objectList` and all the objects returned by `childExp` expression
`<objectList>.tree([<childExp>], [boolExp])`	Treelist of `objectList` and all the objects returned by `childExp` expression, sublists collapsed if `boolExp` was true

childExp: An expression resolving to a list of objects. These objects will be considered children of the current level. If no expression is specified, .children will be used.
boolExp: An expression resolving to a boolean. If true, the list of objects returned by childExp will be collapsed. If no expression is specified, the list of objects will not be collapsed.

Examples

root.organisation.tree(organisations)                       // treelist of all the organizations in the system

topOrg := o.100
topOrg.tree(children.filter(className = "Scorecard))        // treelist of all the scorecards under topOrg

managers := g.managers.members                              // Group of users
managers.tree(subordinates)                                 // Treelist of managers and their subordinates.
                                                            // Where subordinates is a custom user reference property added to User

myKpis := SELECT Kpi
myKpis.tree(indicators)                                     // Treelist of Kpis, their children indicators, and any descendant indicators

union

Returns a list containing all the elements from two lists. Any duplicate elements are still included.

Syntax	Return Value
`<list1>.union(<list2>)`	List with all the elements from list1 and list2

list2: A list to be joined with the first list.

Examples

list1 := LIST("abc", "abc", "abc")
list2 := LIST("abc", "abc", "abc")
list1.union(list2)                      // [abc, abc, abc, abc, abc, abc]

The code above makes two lists consisting solely of duplicate elements. After the union, the result is a list containing all of these elements.

Storing Returned Lists

The methods above do not modify the original list. Instead they return a new list with the modifications. If you wish to use the new list later in the code, you must store it in a variable.

fruits1 := LIST("Apples", "Oranges", "Plums", "Apples")
fruits1.distinct()                                      // [Apples, Oranges, Plums]
fruits1                                                 // [Apples, Oranges, Plums, Apples]
fruits1 := fruits1.distinct()
fruits1                                                 // [Apples, Oranges, Plums]

In the code above we can see that if we reassign the variable fruits1 to the value returned by the expression fruits1.distinct() the new list is stored. Otherwise fruits remains with the same elements it was initiated with.

List

List Operators & Functions

LIST

Examples

CONTAINS

Examples

IN [ 5.3.0.0 +]

Examples

NOT

Examples

Methods

as

Examples

avg

Examples

distinct

Examples

filter

Examples

first

Examples

item

Examples

join

Examples

last

Examples

max

Examples

merge

Examples

min

Examples

remove

Examples

reverse

Examples

size

Examples

sort

Examples

sortReverse

Examples

sum

Examples

tree [ 5.2.0.1 +]

Examples

union

Examples

Storing Returned Lists