How to: Define Filters for External Item Picker Controls

This topic shows you how to refine the search results in the External Item picker by defining filters on your external content type using Microsoft SharePoint Designer 2010.

Applies to: SharePoint Server 2010

For example, suppose you are searching for an "Artist" whose name is "Kim". This artist evidently exists in the external system as seen in the search results in Figure 1.

Figure 1. Choose an External Item

But the External Item picker is doing the following:

• Effectively showing Kim

• Also showing additional results that do not meet the search criteria.

• Returning the following ambiguous error message: "Search criteria cannot be met as Filters are not defined for the External Content Type. Contact your system administrator."

Why did the External Item picker return all the additional matches? As the error message suggests, the problem in this example is that the "Artist" external content type does not have a filter defined. And when an external content type lacks a filter, the default behavior is to show the first 200 items and to not filter the search results. In this case also, the warning is displayed in the picker.

Now, in a scenario in which you have thousands of items to pick from, you will need to have a good set of filters defined on your external content type so that end-users can find the items they are searching for and quickly narrow their search.

For all these reasons, it is recommended that you define at least one filter on your external content type.

Fortunately, you can easily create filter definitions in SharePoint Designer 2010. You must define filters on the Read List operations, which correspond to the Finder methods in the BDC metadata model. The following section describes how to add a filter for an external content type.

Defining a Filter for an External Content Type

In SharePoint Designer 2010, you use the Filter Parameters Configuration dialog box, shown in Figure 2, to configure a filter for the Read List operation.

Figure 2. Defining filters for the Read List operation

To define a filter for an external content type

1. To open the Filter Parameters Configuration dialog box in SharePoint Designer 2010, double-click the Read List operation, and then click Next.

2. Click Add Filter Parameter.

3. To configure the External Item picker, click the (Click to Add) link on the Properties panel Figure 3 shows the Filter Configuration dialog box that opens.

   Figure 3. Configure new filter

   

4. In the New Filter field, type a filter name.

5. Select a filter field to use. In this example, you want to filter by artist name, so select the ArtistName field.

6. Define the type of filter to use. For a complete list of filter types and how they work, see Types of Filters Supported by the Business Data Connectivity Service. Two frequently used filters types are Comparison and Wildcard. For this example, the artist name can have multiple words (such as "Franz Kohl"). The following list states what occurs when using each filter type:

   • Comparison  If you use the "equal" operator, the user is expected to type the full artist name to find items. As a result, this filter only applies if the user types "Franz Kohl" and does not work with only "Franz" or "Kohl".

   • Wildcard  If you use the wildcard filter type, the filter is sent to the external system with wildcards. In this case, the filter applies if the user types "Franz" or "Kohl" and all the artists that have the string "Franz" or "Kohl" as part of their name are returned.

7. Finally, identify what to do if the filter value is null. You must select this option if you have an external list associated with this external content type. Otherwise, you will see no items when browsing the list because the filter value will be null.

8. Add more filter parameters as you need, and add an AND/OR operator behavior. For instance, you can filter by last name AND zone.

   Important

   When integrating specifically with databases, Business Connectivity Services tools generate the necessary queries to enable the designed filters. If you are using other types of Business Connectivity Services data sources such as web services, Windows Communication Foundation (WCF) services, or .NET assemblies, you have to ensure that your filters are part of their API before you can model them in SharePoint Designer.

   The following is an example of the search results in the picker when selecting a "wildcard" type of filter on the artist name and searching for "Karen".

   Figure 4. Choose an External Item with filters applied

   

After multiple filters are defined on the external content type, the External Item picker combines the resulting items of each filter of each Read List operation of the external content type. For increased efficiency, it is recommended that you do not have a high number of filters or Finders on each external content type as this can potentially result in calling a high number of operations on the external content type and can decrease performance.