Multi-value Tokens

A multi-value token is a token that contains two or more values.

Example: Your workflow has a Retrieve Field Values activity that retrieves all the values of the multi-value field "E-mail." The field contains three e-mail addresses. The token generated by the activity is a multi-value token, containing all three e-mail addresses.

Appearance

The way the values in a multi-value token appear depends on where the token is used and its syntax. For instance, if you place a multi-value token in the body of a sticky note or an e-mail, only the first value will be inserted into the sticky note. Using the token editor or the syntax below, you can have the token be replaced by one or all of its values separated by commas, line breaks, spaces, or a variety of other delimiters. If you use the token to populate a multi-value field, each of the token's values will populate a single value of the multi-value field.

Indexing

Each value in a multi-value token is given an index, which is a number that specifies where each value occurs in the list of values. Values are generally given an index number according to the order in which they are added--the higher the number, the newer the value. You can extract a single value from a multi-value token, based on its index, using the token editor or using the token syntax described below.

Example: If a value has an index of "1", this means that it is the oldest value.

Note: The Scripting Activities, custom activities, or the Assign Field Values activity may change the order of values in a multi-value token so that the indices do not reflect the order in which values were added.

Multi-value token syntax

Most multi-value tokens have the syntax as single-value tokens: %(ActivityName_TokenName) or %(TokenName), but some have _All appended to their syntax: %(ActivityName_TokenName_All) or %(TokenName_All)

You can modify the way a multi-value token is replaced by its values using the token editor or the syntax below.

  • Syntax to specify the delimiter used to separate values:

    • Use the following syntax: %(RetrieveFieldValues_Field_All#[delimiter]#). For example, %(RetrieveFieldValues_Field_All#[ | ]#) will use <blank space>|<blank space> as the delimiter, such as 1 | 2 | 3.

    Note: Numbers cannot be used as delimiters because they are reserved for indexes. (See below).

  • Syntax to specify that the token will be replaced by only a single value:

    • If you only need a single value in a multi-value token, use the following syntax: %(RetrieveFieldValues_Field_All#[n]#) where n equals the index number of the value you want. For example, %(RetrieveFieldValues_Field_All#[3]#) will replace the token with the third field value. If [n] is less than zero, Workflow will count from the bottom up. For example, %(RetrieveFieldValues_Field_All#[-1]#) will replace the token with the last value, while %(RetrieveFieldValues_Field_All#[-5]#) will replace the token with the fifth value from the end.

    Note: If you are counting values from the top down and you specify an index greater than the total number of values in the token, the token will be replaced by the last value. If you are counting values from the bottom up and you specify an index with an absolute value greater than the total number of values in the token, the token will be replaced by the first value.

    Note: Specifying a range of index numbers for the token to be replaced by will not work. For example, %(RetrieveFieldValues_Field_All#[1-3]#) will replace the token with the values at index numbers 1, 2, and 3. Instead, 1-3 will be used a delimiter. To have the token be replaced by a range of token values, use the Assign Token Values activity.