Reference Qualifiers

Reference Qualifier allows for creating filters to select the data on certain conditions and return it to a reference field.

Reference field stores the ID of a record of a specified table. That is, this field contains reference to the records and fields in the referenced table.

Reference Qualifiers can consist of:

• reference to the table
• reference qualifier type
• reference condition created through Condition Builder
• dynamic filter options created as described below.

You can create the reference qualifier for a table, and its child tables, by defining a reference qualifier through an appropriate interface.

You can also modify the reference qualifier on extended tables through the Column Overriding. Only one reference qualifier per field, form or table can be defined.

There are two methods of using a reference qualifier:

• Simple Reference Qualifier
• Dynamic Reference Qualifier.

Simple Reference Qualifier

In Simple reference qualifier, AND/OR statements are used to configure filters. Use them when filtering conditions are not quite specific. For example, to filter only active users from the Users dictionary, AND/OR only companies from the Pacific timezone from the Companies dictionary. See Condition Builder to learn more about filters.

To create a simple reference qualifier, please complete the steps below:

1. Navigate to System Settings → All Columns.
2. Find the column you want to create a reference qualifier for, using a search string on the top of the list, and enter it.
3. Click the Reference Qualifier tab.
4. Choose the Simple option from the choice list.
5. Specify a condition for this reference qualifier using the Condition builder. You can create complex AND and OR filters, more than one in one condition.
6. (optional) Select the Reference Qualifier Fixed checkbox to fix filters in the breadcrumbs when using this field. This functionality will block using the Condition Builder functionality, and the is_fixed=TRUE directive appears in the URL.

Dynamic Reference Qualifier

How to create a dynamic reference qualifier

To create a dynamic reference qualifier, please complete the steps below:

1. Navigate to System Settings → All Columns.
2. Find the column you want to create a reference qualifier for, using a search string on the top of the list, and open it.
3. Click the Reference Qualifier tab.
4. Choose the Dynamic option from the choice list.
5. Specify a dynamic filter to use in this reference qualifier using the Dynamic Reference Qualifier dictionary field.
6. (optional) Select the Reference Qualifier Fixed checkbox to fix filters in the breadcrumbs in the dictionary when using this field. This functionality will block using the Condition Builder functionality.

Example of work

For example, we are going to take the Assigned To field that is the reference to the User (user) table. By default, when we start typing something in this field, then all values in this field appear in the lookup and can be chosen. It happens because the reference qualifier is not set, and it does not limit the reference lookup. You can choose any user, from any department, in any state, even an inactive user (for example, the retired user). To prevent such issues, use the reference qualifier like described below or in the way your task requires.

Use case

We need to limit the users list which can be assigned to tasks (by specifying their name in the Assigned To field). For example, only a Customer Support member can be assigned to tasks.

To configure a reference qualifier in this way, complete the steps below:

1. Open the form that contains the field you need to configure.
2. Right-click on the Assigned To field title and select the Configure field item from the context menu appeared.
3. In the Column configuration form appeared, select the Reference Qualifier tab.
4. Start configuring your qualifier:
   1. Reference Qualifier Type - Simple
   2. Reference Qualifier Condition - [Department]  [is]  [Customer Support]
5. Click Save or Save and Exit to apply changes.

After that, type a user name that is not a Customer Support staff member. You will find out that autosuggest service does not provide any options.

Good to Know

1. Make sure that all users have access to the field on which you are adding a qualifier. Otherwise, the qualifier will hide records for users that do not have access to the specified field due to ACL Rules.
2. As mentioned above, the Reference Qualifier tab on the column creation form is available only for fields of Reference or List types. For fields of other types, use Condition Builder Options. To speed up dynamic filter creation, use Default values functionality (you can base on the default values defined in the Script field of the Filter Option Dynamic (sys_filter_option_dynamic) table).