ReferenceSearchFilter can contain multiple attributes used in filters. In addition, more search operators are available. There may be multiple filters configured for one attribute: one filter for one source-target template pair. After one filter has been saved, a new empty filter text area will appear for defining a new filter.

Currently ReferenceSearchFilter can be used with any reference attribute whose handler doesn't alter the default editing view of the attribute. This means that ReferenceSearchFilter does not work for example with CategoryDropDownReferenceHandler.

Configuration of ReferenceSearchFilter is done in attribute metadata editor with the EQL Editor. A filter created with the editor is automatically converted into Efecte Query Language (EQL).

Example of configuring a reference search filter using the EQL editor.

Attribute metadata editor showing an example ReferenceSearchFilter configuration. The metadata value is an EQL query, generated by the EQL Editor.

Source Template Configuration

As illustrated above, the filter configuration contains an editor for selecting source and target templates for filter, matching conditions and ordering of the results. This editor is also used in configuring some other functionality and is therefore explained in the  EQL Editor article with the exception of source template field that is specific to the reference search filter.

Source template is essential if the attribute to be edited is attached to multiple templates and it is intended to have different filters for separate templates. A filter can be set for all source templates containing the attribute. The All-value is usable also when the reference attribute is attached to one template only. However, it is not possible to attach the same filter to some, but not all, potential source templates. For this kind of usage, multiple filters must be created for all needed source templates.

Using Filtered Reference Search

 The filter is applied automatically, and by default end users cannot disable it. An administrator can optionally allow end users to disable the filter for a specific attribute — see Letting end users disable the filter below.

Letting end users disable the filter

By itself, a search filter is not something end users can bypass. If you want to let them widen the search when the filtered results don't have what they need, open the reference attribute's regular Edit attribute screen and check Show button for disabling filter, under Reference settings. This option exists on every reference and back-reference attribute, and only has a visible effect once a search filter is already configured on that same attribute.

This setting is stored as ordinary attribute metadata (name showDisableFilterButton), so if you're already on the attribute metadata editor configuring the search filter itself, you can just as well set it there directly under Other Properties instead of switching screens — either path turns the button on.

When this is on, end users see a filter icon next to the reference field that they can click to disable the filter for that search. See "Adding References to Data Cards" in the User Guide for what that looks like from the end-user side.

This applies the same way in both the Classic UI and the Agent UI — you configure it once, and both interfaces respect it, though the icon itself looks slightly different between the two (see the User Guide section linked above).

Non-matching Filtering Conditions can be Ignored by ? Character

Conditions can contain reference paths, which are not valid, if the part of the path is missing in data card's data. Such paths can be marked "ignorable" by using ? character in search condition.

For example:

select entity from entity
           where $mid_category$ in #referrer:?ce_mid_category#
           and $mid_category$ in #referrer:?ce_low_category:mid_category#
           and template.code = 'top_category'exclude

• ?ce_mid_category - if there is no value in ce_mid_category, the condition is ignored
• ?#referrer:?ce_low_category:mid_category - if there is no value in ce_low_category, the condition is ignored

This feature can be used to replace Handler - CategoryDropdownReference which can be started to select values from middle levels too.

See example template configuration:

Reference search filter example - Categorization using single template

Category feature can be implemented using one Category template only. This is usable if all levels of categorization holds the same data. In data card editor user can start selecting data values from which level he wants. Categorization is tree: a category can have multiple subcategories but only one parent.

Categorization template must have 3 attributes. Template code is "single_category_template".

• Name: a String
• Children: Multivalue reference attribute fixed to the same template. Code “children”
• Parent: Singlevalue reference to the Children-attribute. Code "parent"

The template who uses this kind of categorization can have as many sub categories as needed. Here is example with three-level categories. Pay attention to attribute codes meaning categorization levels "first", "second" and "third".

Top level category attribute refers to Category-template. Code is "first". Metadata for filtering is:

select entity from entity
where $children$ in #referrer:?second#
and $children$ in #referrer:?third:parent#
and $parent:parent$ is null
and $parent$ is  null
and template.code = 'single_category_template'

Second level category attribute refers to Category-template. Code is "second" Metadata for filtering is:

select entity from entity
where $parent$ in #referrer:?first#
and $children$ in #referrer:?third#
and $parent$ is not null
and $parent:parent$ is null
and template.code = 'single_category_template'

Third level category attribute refers to Category-template. Code is "third". Metadata for filtering is:

select entity from entity
where $parent$ in #referrer:?first:children#
and $parent$ in #referrer:?second#
and $parent$ is not null
and $parent:parent$ is not null
and template.code = 'single_category_template'

Reference Search Filter Example - Categorization Using Multiple Template

<?xml version="1.0" encoding="utf-8"?>

<templateset>
    <template>
        <id>269</id>
        <code>single_category_template</code>
        <name>Single category</name>
        <system-code>bso</system-code>
        <protected>false</protected>
        <metadata>
            <name>allow_copy_data_cards</name>
            <value>true</value>
        </metadata>
        <class>
            <id>612</id>
            <template-class-id>1154</template-class-id>
            <name>Single category</name>
            <order>0</order>
            <collapsed>false</collapsed>
            <attribute>
                <id>2762</id>
                <class-attribute-id>3208</class-attribute-id>
                <code>name</code>
                <name>Name</name>
                <datatype>string</datatype>
                <multivalue>false</multivalue>
                <output-is-always-shown>false</output-is-always-shown>
                <static>false</static>
                <hierarchy>false</hierarchy>
                <hierarchy-leafs-only>false</hierarchy-leafs-only>
                <expand-references-automatically>false</expand-references-automatically>
                <expand-complete-output-automatically>false</expand-complete-output-automatically>
                <import-referenced-data-to-referrer>false</import-referenced-data-to-referrer>
                <large-text>false</large-text>
                <query-hidden>false</query-hidden>
                <output-hidden>false</output-hidden>
                <query-header-hidden>false</query-header-hidden>
                <output-header-hidden>false</output-header-hidden>
                <visibility>visible_always</visibility>
                <field-width>40</field-width>
                <field-height>1</field-height>
                <space-demand>4</space-demand>
                <order>100</order>
                <selected>true</selected>
                <unique>false</unique>
                <required>true</required>
                <protected>false</protected>
            </attribute>
            <attribute>
                <id>2863</id>
                <class-attribute-id>3209</class-attribute-id>
                <code>parent</code>
                <name>Parent category</name>
                <datatype>reference</datatype>
                <references>
                    <reference>269</reference>
                </references>
                <multivalue>false</multivalue>
                <output-is-always-shown>false</output-is-always-shown>
                <static>false</static>
                <hierarchy>false</hierarchy>
                <hierarchy-leafs-only>false</hierarchy-leafs-only>
                <expand-references-automatically>false</expand-references-automatically>
                <expand-complete-output-automatically>false</expand-complete-output-automatically>
                <import-referenced-data-to-referrer>false</import-referenced-data-to-referrer>
                <large-text>false</large-text>
                <query-hidden>false</query-hidden>
                <output-hidden>false</output-hidden>
                <query-header-hidden>false</query-header-hidden>
                <output-header-hidden>false</output-header-hidden>
                <visibility>visible_always</visibility>
                <field-width>40</field-width>
                <field-height>1</field-height>
                <space-demand>4</space-demand>
                <order>200</order>
                <selected>true</selected>
                <unique>false</unique>
                <required>false</required>
                <protected>false</protected>
                <metadata>
                    <name>isAllowSameDataMultipleTimes</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>isReferenceShowSelected</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>reference_show_mode</name>
                    <value>ALL</value>
                </metadata>
            </attribute>
            <attribute>
                <id>2867</id>
                <class-attribute-id>3214</class-attribute-id>
                <code>children</code>
                <name>Children</name>
                <datatype>backreference</datatype>
                <references>
                    <reference>269</reference>
                </references>
                <multivalue>true</multivalue>
                <output-is-always-shown>false</output-is-always-shown>
                <static>false</static>
                <hierarchy>false</hierarchy>
                <hierarchy-leafs-only>false</hierarchy-leafs-only>
                <expand-references-automatically>false</expand-references-automatically>
                <expand-complete-output-automatically>false</expand-complete-output-automatically>
                <import-referenced-data-to-referrer>false</import-referenced-data-to-referrer>
                <large-text>false</large-text>
                <query-hidden>false</query-hidden>
                <output-hidden>false</output-hidden>
                <query-header-hidden>false</query-header-hidden>
                <output-header-hidden>false</output-header-hidden>
                <visibility>visible_always</visibility>
                <field-width>40</field-width>
                <field-height>1</field-height>
                <space-demand>4</space-demand>
                <order>300</order>
                <selected>true</selected>
                <unique>false</unique>
                <required>false</required>
                <protected>false</protected>
                <metadata>
                    <name>backreference_269_3214</name>
                    <value>269_3209</value>
                </metadata>
                <metadata>
                    <name>isAllowSameDataMultipleTimes</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>isReferenceShowSelected</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>reference_show_mode</name>
                    <value>ALL</value>
                </metadata>
            </attribute>
        </class>
    </template>
    <template>
        <id>268</id>
        <code>single_category_template_example</code>
        <name>Single category template example</name>
        <system-code>bso</system-code>
        <protected>false</protected>
        <metadata>
            <name>allow_copy_data_cards</name>
            <value>true</value>
        </metadata>
        <class>
            <id>613</id>
            <template-class-id>1155</template-class-id>
            <name>Single category</name>
            <order>0</order>
            <collapsed>false</collapsed>
            <attribute>
                <id>2762</id>
                <class-attribute-id>3213</class-attribute-id>
                <code>name</code>
                <name>Name</name>
                <datatype>string</datatype>
                <multivalue>false</multivalue>
                <output-is-always-shown>false</output-is-always-shown>
                <static>false</static>
                <hierarchy>false</hierarchy>
                <hierarchy-leafs-only>false</hierarchy-leafs-only>
                <expand-references-automatically>false</expand-references-automatically>
                <expand-complete-output-automatically>false</expand-complete-output-automatically>
                <import-referenced-data-to-referrer>false</import-referenced-data-to-referrer>
                <large-text>false</large-text>
                <query-hidden>false</query-hidden>
                <output-hidden>false</output-hidden>
                <query-header-hidden>false</query-header-hidden>
                <output-header-hidden>false</output-header-hidden>
                <visibility>visible_always</visibility>
                <field-width>40</field-width>
                <field-height>1</field-height>
                <space-demand>4</space-demand>
                <order>50</order>
                <selected>true</selected>
                <unique>false</unique>
                <required>false</required>
                <protected>false</protected>
            </attribute>
            <attribute>
                <id>2864</id>
                <class-attribute-id>3210</class-attribute-id>
                <code>first</code>
                <name>First level</name>
                <datatype>reference</datatype>
                <references>
                    <reference>269</reference>
                </references>
                <multivalue>false</multivalue>
                <output-is-always-shown>false</output-is-always-shown>
                <static>false</static>
                <hierarchy>false</hierarchy>
                <hierarchy-leafs-only>false</hierarchy-leafs-only>
                <expand-references-automatically>false</expand-references-automatically>
                <expand-complete-output-automatically>false</expand-complete-output-automatically>
                <import-referenced-data-to-referrer>false</import-referenced-data-to-referrer>
                <large-text>false</large-text>
                <query-hidden>false</query-hidden>
                <output-hidden>false</output-hidden>
                <query-header-hidden>false</query-header-hidden>
                <output-header-hidden>false</output-header-hidden>
                <visibility>visible_always</visibility>
                <field-width>40</field-width>
                <field-height>1</field-height>
                <space-demand>4</space-demand>
                <order>100</order>
                <selected>true</selected>
                <unique>false</unique>
                <required>false</required>
                <protected>false</protected>
                <metadata>
                    <name>empty_result_when_filter_invalid</name>
                    <value>true</value>
                </metadata>
                <metadata>
                    <name>filter_single_category_template_example-&gt;single_category_template</name>
                    <value>select entity from entity
where $children$ in #referrer:?second#
and $children$ in #referrer:?third:parent#
and $parent:parent$ is null
and $parent$ is  null
and template.code = 'single_category_template'</value>
                </metadata>
                <metadata>
                    <name>isAllowSameDataMultipleTimes</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>isReferenceShowSelected</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>reference_show_mode</name>
                    <value>ALL</value>
                </metadata>
            </attribute>
            <attribute>
                <id>2865</id>
                <class-attribute-id>3211</class-attribute-id>
                <code>second</code>
                <name>Second level</name>
                <datatype>reference</datatype>
                <references>
                    <reference>269</reference>
                </references>
                <multivalue>false</multivalue>
                <output-is-always-shown>false</output-is-always-shown>
                <static>false</static>
                <hierarchy>false</hierarchy>
                <hierarchy-leafs-only>false</hierarchy-leafs-only>
                <expand-references-automatically>false</expand-references-automatically>
                <expand-complete-output-automatically>false</expand-complete-output-automatically>
                <import-referenced-data-to-referrer>false</import-referenced-data-to-referrer>
                <large-text>false</large-text>
                <query-hidden>false</query-hidden>
                <output-hidden>false</output-hidden>
                <query-header-hidden>false</query-header-hidden>
                <output-header-hidden>false</output-header-hidden>
                <visibility>visible_always</visibility>
                <field-width>40</field-width>
                <field-height>1</field-height>
                <space-demand>4</space-demand>
                <order>200</order>
                <selected>true</selected>
                <unique>false</unique>
                <required>false</required>
                <protected>false</protected>
                <metadata>
                    <name>empty_result_when_filter_invalid</name>
                    <value>true</value>
                </metadata>
                <metadata>
                    <name>filter_single_category_template_example-&gt;single_category_template</name>
                    <value>select entity from entity
where $parent$ in #referrer:?first#
and $children$ in #referrer:?third#
and $parent$ is not null
and $parent:parent$ is null
and template.code = 'single_category_template'</value>
                </metadata>
                <metadata>
                    <name>isAllowSameDataMultipleTimes</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>isReferenceShowSelected</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>reference_show_mode</name>
                    <value>ALL</value>
                </metadata>
            </attribute>
            <attribute>
                <id>2866</id>
                <class-attribute-id>3212</class-attribute-id>
                <code>third</code>
                <name>Third level</name>
                <datatype>reference</datatype>
                <references>
                    <reference>269</reference>
                </references>
                <multivalue>false</multivalue>
                <output-is-always-shown>false</output-is-always-shown>
                <static>false</static>
                <hierarchy>false</hierarchy>
                <hierarchy-leafs-only>false</hierarchy-leafs-only>
                <expand-references-automatically>false</expand-references-automatically>
                <expand-complete-output-automatically>false</expand-complete-output-automatically>
                <import-referenced-data-to-referrer>false</import-referenced-data-to-referrer>
                <large-text>false</large-text>
                <query-hidden>false</query-hidden>
                <output-hidden>false</output-hidden>
                <query-header-hidden>false</query-header-hidden>
                <output-header-hidden>false</output-header-hidden>
                <visibility>visible_always</visibility>
                <field-width>40</field-width>
                <field-height>1</field-height>
                <space-demand>4</space-demand>
                <order>300</order>
                <selected>true</selected>
                <unique>false</unique>
                <required>false</required>
                <protected>false</protected>
                <metadata>
                    <name>empty_result_when_filter_invalid</name>
                    <value>true</value>
                </metadata>
                <metadata>
                    <name>filter_single_category_template_example-&gt;single_category_template</name>
                    <value>select entity from entity
where $parent$ in #referrer:?first:children#
and $parent$ in #referrer:?second#
and $parent$ is not null
and $parent:parent$ is not null
and template.code = 'single_category_template'</value>
                </metadata>
                <metadata>
                    <name>isAllowSameDataMultipleTimes</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>isReferenceShowSelected</name>
                    <value>0</value>
                </metadata>
                <metadata>
                    <name>reference_show_mode</name>
                    <value>ALL</value>
                </metadata>
            </attribute>
        </class>
    </template>
</templateset>

Reference Search Filter Example - Categorization Using Single Template - Entity Set

<?xml version="1.0" encoding="utf-8"?>
<entityset>
    <entity id="7" name="A">
        <template id="11" name="Single category" code="single_category_template"/>
        <group id="3" name="Single categories"/>
        <attribute id="37" name="Name" code="name">
            <value>A</value>
        </attribute>
        <attribute id="39" name="Children" code="children">
            <reference id="8" name="A-A" code="parent"/>
            <reference id="10" name="A-B" code="parent"/>
            <reference id="12" name="A-C" code="parent"/>
        </attribute>
    </entity>
    <entity id="8" name="A-A">
        <template id="11" name="Single category" code="single_category_template"/>
        <group id="3" name="Single categories"/>
        <attribute id="37" name="Name" code="name">
            <value>A-A</value>
        </attribute>
        <attribute id="38" name="Parent category" code="parent">
            <reference id="7" name="A"/>
        </attribute>
        <attribute id="39" name="Children" code="children">
            <reference id="9" name="A-A-A" code="parent"/>
        </attribute>
    </entity>
    <entity id="9" name="A-A-A">
        <template id="11" name="Single category" code="single_category_template"/>
        <group id="3" name="Single categories"/>
        <attribute id="37" name="Name" code="name">
            <value>A-A-A</value>
        </attribute>
        <attribute id="38" name="Parent category" code="parent">
            <reference id="8" name="A-A"/>
        </attribute>
    </entity>
    <entity id="10" name="A-B">
        <template id="11" name="Single category" code="single_category_template"/>
        <group id="3" name="Single categories"/>
        <attribute id="37" name="Name" code="name">
            <value>A-B</value>
        </attribute>
        <attribute id="38" name="Parent category" code="parent">
            <reference id="7" name="A"/>
        </attribute>
        <attribute id="39" name="Children" code="children">
            <reference id="11" name="A-B-A" code="parent"/>
        </attribute>
    </entity>
    <entity id="11" name="A-B-A">
        <template id="11" name="Single category" code="single_category_template"/>
        <group id="3" name="Single categories"/>
        <attribute id="37" name="Name" code="name">
            <value>A-B-A</value>
        </attribute>
        <attribute id="38" name="Parent category" code="parent">
            <reference id="10" name="A-B"/>
        </attribute>
    </entity>
    <entity id="12" name="A-C">
        <template id="11" name="Single category" code="single_category_template"/>
        <group id="3" name="Single categories"/>
        <attribute id="37" name="Name" code="name">
            <value>A-C</value>
        </attribute>
        <attribute id="38" name="Parent category" code="parent">
            <reference id="7" name="A"/>
        </attribute>
    </entity>
    <entity id="15" name="B">
        <template id="11" name="Single category" code="single_category_template"/>
        <group id="3" name="Single categories"/>
        <attribute id="37" name="Name" code="name">
            <value>B</value>
        </attribute>
        <attribute id="39" name="Children" code="children">
            <reference id="14" name="B-B" code="parent"/>
        </attribute>
    </entity>
    <entity id="14" name="B-B">
        <template id="11" name="Single category" code="single_category_template"/>
        <group id="3" name="Single categories"/>
        <attribute id="37" name="Name" code="name">
            <value>B-B</value>
        </attribute>
        <attribute id="38" name="Parent category" code="parent">
            <reference id="15" name="B"/>
        </attribute>
        <attribute id="39" name="Children" code="children">
            <reference id="13" name="B-B-C" code="parent"/>
        </attribute>
    </entity>
    <entity id="13" name="B-B-C">
        <template id="11" name="Single category" code="single_category_template"/>
        <group id="3" name="Single categories"/>
        <attribute id="37" name="Name" code="name">
            <value>B-B-C</value>
        </attribute>
        <attribute id="38" name="Parent category" code="parent">
            <reference id="14" name="B-B"/>
        </attribute>
    </entity>
</entityset>

Empty Result When Search Filter Cannot be Applied

By default, if a search filter can't be applied (e.g. missing reference paths) the result will contain all possible datacards. If this value is set true, the result will be empty. Default value is false.