Planning Step 4: Identify the Filters Required for Each Entity

Applies to: SharePoint Server 2010

To determine the filters required for each external content type, you look at each of the input parameters of each Web method and determine how you want the Business Data Connectivity (BDC) service to get the value of that parameter at run time; for example, in Business Data Web Parts, and so on. If you want the user to specify the value at run time, you use one of the user filters. Or, if you want the BDC to provide that value automatically, you use one of the system filters or provide default values in the metadata itself.

For example, consider the GetCustomers method in the SampleWebService proxy. It takes two input parameters: name and limit. If you want the user of a Business Data List Web Part to filter the results of the GetCustomers method by providing values such as "Name like 'Jo%'" or "Name contains 'John'", you associate a FilterDescriptor with the name input parameter.

The back-end Web service method should support the filters you declare; otherwise, the Web method might not return the results you want. First, check the documentation of your Web method to see what filtering capabilities it supports. Then, declare FilterDescriptors in the metadata.

For example, if you look at the GetCustomers Web method in the proxy, you can see that this method takes two input parameters, name and limit, as shown in the following code.

    public Customer[] GetCustomers(string name, [System.Xml.Serialization.XmlElementAttribute(IsNullable=true)] System.Nullable<int> limit) {
        object[] results = this.Invoke("GetCustomers", new object[] {
                    name,
                    limit});
        return ((Customer[])(results[0]));
    }

Now let's assume the documentation for this Web method states the usage of this method as shown in the following code.

GetCustomers(name, limit)  where
name: A string representing the customer's name. This parameter accepts wildcards (that is, '%' representing any string of characters).
limit: A number that limits the number of customers returned in the result set.

This clearly tells you that you can associate the input parameters name and limit with wildcard and limit filters, respectively.

You name each of the filters as you want it to appear to the users, for example, in the Business Data Web Parts. The UsedForDisambiguation property, a property of the FilterDescriptor can be used to tell the External Data Picker control and the Business Data Web Parts to generate the list of matching candidates to the filter. The value for the Type attribute is very important in the definition of the FilterDescriptor. This value tells the BDC what kind of filter it is. It can be one of the user or system filters. The following shows the metadata XML for the GetCustomers method.

        <Method Name="GetCustomers">
          <FilterDescriptors>
            <FilterDescriptor Type="Wildcard" Name="Name" />
            <!-- Limit filter tells Business Data Catalog to bring back 
            only the specified number of rows back from the line-of-business 
            application.-->
            <!-- Notice that the back-end method should support this 
            functionality to return only the specified number of rows. 
            For a sample, see SampleWebService.-->
            <FilterDescriptor Type="Limit" Name="Limit" />
          </FilterDescriptors>
          <Parameters>
            <Parameter Direction="In" Name="name">
              <TypeDescriptor TypeName="System.String" AssociatedFilter="Name" Name="name" />
            </Parameter>
            <Parameter Direction="In" Name="limit">
              <TypeDescriptor TypeName="System.Int32" AssociatedFilter="Limit" Name="limit" />
            </Parameter>
            <Parameter Direction="Return" Name="Customers">
              <TypeDescriptor TypeName="SampleWebServiceProxy.Customer[], SampleWebService" IsCollection="true" Name="ArrayOfCustomer">
                <TypeDescriptors>
                  <TypeDescriptor TypeName="SampleWebServiceProxy.Customer, SampleWebService" Name="Customer">
                    <TypeDescriptors>
                      <TypeDescriptor TypeName="System.String" IdentifierName="CustomerID" Name="CustomerID" />
                      <TypeDescriptor TypeName="System.String" Name="Name" />
                      <TypeDescriptor TypeName="System.Int64" Name="WorkPhoneNumber" />
                      <TypeDescriptor TypeName="System.Int64" Name="MobilePhoneNumber" />
                      <TypeDescriptor TypeName="System.String" Name="Industry" />
                      <TypeDescriptor TypeName="System.String" Name="WebSite" />
                    </TypeDescriptors>
                  </TypeDescriptor>
                </TypeDescriptors>
              </TypeDescriptor>
            </Parameter>
          </Parameters>
          <MethodInstances>
            <MethodInstance Type="Finder" ReturnParameterName="Customers" ReturnTypeDescriptorName="ArrayOfCustomer" ReturnTypeDescriptorLevel="0" Name="FindCustomerInstances" />
          </MethodInstances>
        </Method>

For a list of the filters supported by the BDC, see Types of Filters Supported by the Business Data Connectivity Service.

Next Steps

Planning Step 5: Determine In, Out, and Return Parameters for each method