Rules & Multi-Valued List Fields

Rule that access multi-valued list fields have a number of specific points that you should understand. The examples in this section all assume you have a multi-valued list field with a name of FRUITS, and that valid values within the list are apple, pear, orange, banana and raspberry.

Setting Values in a Multi-Valued List Field

For each assignment you make of a value within a multi-valued field, you are selecting that value. For example, if you want to set both apple and orange you would use:

FRUITS = ['apple','orange'];

The quotes around the values are optional, unless you have a space character within the value.  For example, this is a valid statement:

FRUITS = [apple, 'orange', 'honeydew melon'];

If you want to set a single value of pear within the list you use a simple assignment statement.

FRUITS = 'pear';
 
Note that when you assign one or more values to a multi-valued field with an assignment, you are adding to the existing list values.  For example, if the list contains both apple and orange and you execute this:
 
FRUITS = ['orange', 'raspberry'];
 
the list will then contain apple, orange and raspberry.

Adding a Value to an Existing Multi-Valued List Field

FRUITS += 'strawberry';

Clearing All Values from a Multi-Valued List Field

Simply set the the list as follows:
 
FRUITS = '';

or

FRUITS.{clear};

Checking Values Exist within a List

This syntax will find whether the single value of orange is currently set within the multi-valued list:

if (FRUITS.{contains 'orange'}) { ... };

This syntax will find whether the values of pear, orange and banana are currently set within the multi-valued list:

if (FRUITS.{contains 'pear', 'orange', 'banana'}) { ... };

This syntax will find whether the values of pear, and orange are currently set within the multi-valued list, but the value of banana is not within the multi-valued list:

if (FRUITS.{contains 'pear', 'orange'} && FRUITS.{excludes 'banana'}) { ... };

Check Values in a Multi-Valued List Field are Contained Within a Different Multi-Valued List Field

The following syntax allows you to check whether all the selected values in one multi-value list field are selected and contained within a different multi-value list field.  Say you have two multi-valued list fields, named LIST_FIELD_1 and LIST_FIELD_2.  When a user selects various fields in both these lists in an add or edit screen and then updates the issue, you might want to have a rule that checks whether all the selected values in LIST_FIELD_2 are selected in LIST_FIELD_1.  The rule may look like this:

<== preupdate ==>
if (LIST_FIELD_2.{changed} && LIST_FIELD_1.{contains LIST_FIELD_2}) {
    MY_TEXT_FIELD = 'LIST_FIELD_1 contains all the values in LIST_FIELD_2';
}

Assignments with Multi-Valued Fields

You can assign the selected values in a multi-valued list field to a text, text area, print text, or an HTML Area field.  When you make the assignment, the  text, text area, print text, or HTML Area field will contain the entire list of selected values, delimited with semi-colons.