Collection functions

This section describes the collection functions that are available for use on list and map values in expressions.

empty-list

Returns an empty list value. This function is useful when you want to clear the values of an existing list value. For example, to remove all the items in a list value, use the Set Value service to set the value of the list to empty-list().

Syntax

    empty-list()

Parameters

None.

Returns

A list value that contains no items.

Example

The following table represents a mapping in an execute operation that the Set Value service provides. The mapping uses the empty-list function to remove the items from the listVar variable, which holds document values.

Location

Expression

/process_data/listVar

empty-list()

After the list values are cleared, the listVar variable is still configured to hold document values.

empty-map

Returns an empty map value. This function is useful when you want to clear the values of an existing map value. For example, to remove all the items in a map value, use the Set Value service to set the value of the map to empty-map().

Syntax

    empty-map()

Parameters

None.

Returns

A map value that contains no items.

Example

The following table represents a mapping in an execute operation that the Set Value service provides. The mapping uses the empty-map function to remove the items from the mapVar variable, which holds string values.

Location

Expression

/process_data/mapVar

empty-map()

After the map values are cleared, the mapVar variable is still configured to hold string values.

get-map-keys

Retrieves the keys from a map value.

Syntax

    get-map-keys(Expression)

Parameters

Expression is an XPath expression that resolves to a map value.

Returns

A list value that contains string values that represent map keys.

Example

A map variable named varmap includes the key-value pairs (username, admin) and (password, 1234). The following example returns a list value that includes the string values username and password:

get-map-keys(/process_data/varmap)

get-collection-size

Retrieves the number of items in a data collection.

Syntax

    get-collection-size(node-set)

Parameters

node-set is an XPath expression that resolves to the data node that represents a list or map variable.

Returns

An integer that contains the number of data items in the node-set.

Example

A list variable named varlist contains six data items. The following example returns 6:

get-collection-size(/process_data/varlist)

get-list-item-count

Returns the number of items in a list that are equal to a given string value. Optionally, returns the number of items that have a property that is equal to a given string value.

Syntax

get-list-item-count(list, strToMatch [, strPropertyName])

Parameters

list is an XPath expression that resolves to the list value.

strToMatch is the value to match with items in the list. This value can be a string value or any type of value that can be coerced to a string, such as a number or XML.

strPropertyName is an optional string value that represents the name of the property of the items in the list to match with strToMatch.

Returns

An int value that represents the number of matching items in the list.

Example

The list variable named strList contains the items ’blue’,’red’, and ’blue’. The following expression returns the value 2: 

get-list-item-count(/process_data/strList, 'blue')

The list variable named docList contains the attachments and notes that are submitted with a task from Workspace. The list contains two file attachments and one note. The following expression returns the value 1: 

get-list-item-count(/process_data/docList, 'note', 'wsattachtype')

For an example that uses this function with a TaskResultCollection value, see Assessing review and approval results.

get-list-item-percentage

Returns the percentage of items in a list that are equal to a given string value. Optionally, returns the number of items that have a property that is equal to a given string value.

Syntax

    get-list-item-percentage(list, strToMatch [, strPropertyName])

Parameters

list is an XPath expression that resolves to the list value.

strToMatch is the string value to match with items in the list. This value can be any type that can be coerced to a string, such as a number or XML.

strPropertyName is an optional string value that represents the name of the property of the items in the list to match with strToMatch.

Returns

A double precision value that represents the number of matching items in the list.

If you save the returned value in a string variable, the value is coerced to a string.

Example

The list variable named strList contains the items ’blue’, ’red’, and ’blue’. The following expression returns the value 66.667:

get-list-item-percentage(/process_data/strList, 'blue')

The list variable named docList contains the attachments and notes that are submitted with a task from Workspace. The list contains two file attachments and one note. The following expression returns the value 33.333:

get-list-item-percentage(/process_data/docList, 'note', 'wsattachtype')

get-map-values

The get-map-values function returns the values that are stored in a map variable.

Syntax

    get-map-values(Expression)

Parameters

Expression is an XPath expression that resolves to a map value from which you can retrieve the keys.

Returns

A list value that contains string values that represent the map values.

Example

A map variable named varmap includes the key-value pairs (username, admin) and (password, 1234). The following expression returns a list value that includes the string values admin and 1234: 

get-map-values(/process_data/varmap)

get-map-values-for-keys

Returns the values stored in a map value that correspond with a given list of keys.

Syntax

    get-map-values-for-keys(Expression1, Expression2)

Parameters

Expression1 is an XPath expression that resolves to a map value from which you can retrieve the values.

Expression2 is an XPath expression that resolves to a list value that contains the keys for the values that you want to retrieve.

Returns

A list value that contains string values that represent the map values.

Example

A map variable named varmap stores customer email addresses. A customer ID is used as the key, and the email address is the value. A list variable named varlist contains several customer IDs. The following expression returns the values from varmap that correspond with the customer IDs stored in varlist:

get-map-values-for-keys(/process_data/varmap, /process_data/varlist)