FilterDescriptor

Filters are the fundamental way in which the Business Data Catalog captures user (or system) input and plumbs it through to the backend API invocation. FilterDescriptors describe where in a complex series of parameters, a filter value should be inserted. This is accomplished by 'tagging' the TypeDEscriptors representing complex parameters of a Method definition to flag where the insertion should happen. It is important to note that the backend must supply the functionality for filtering; the FilterDescriptors merely form a mechanism to surface this to the end user. FilterDescriptor objects are owned (contained) inside Method objects. They are subsequently referred by TypeDescriptor objects

Users may want to retrieve the instances of an entity that match some criteria. For example, a user may want to display the customers whose names begin with "A" or the orders made by a certain customer. The API used to retrieve customers requires that this user input be passed in as the third String parameter in the invocation. The metadata author will create a FilterDescriptor of a Wildcard Type, and then tag the third parameter's root TypeDescriptor with this newly created FilterDescriptor. Many such FilterDescriptors may be associated with a single Method (API).Users then choose the filter they want at run time, specify a value for it, and the Business Data Catalog passes that filter's value to the back-end method, inserting it into the exact location where the backend expects it, which causes it to then returns only the rows the user wants to see.

For example, assume the Finder method for the Customer entity is defined as follows:

SELECT * FROM Customers WHERE CustomerID >= lo

Assume the method has default parameter value of lo = 0. The FilterDescriptor metadata states that if the user overrides the lo value, it can limit the range of instances returned. The user, in this case, the user can provide the lo value and see specific results.

Note

FilterDescriptor is a metadata object whereas filters are run-time objects. FilterDescriptor objects describe the filters available on a method.

Filtering Patterns

Line-of-business (LOB) systems provide various filtering mechanisms. The Business Data Catalog abstracts common patterns so it can provide users with the same filtering semantics, regardless of the data source. The Business Data Catalog supports the following filters and filtering patterns:

• Wildcard filter   Limits the instances returned to those where field like value, where value may contain the asterisk (*) wildcard character. Users can use this filter type to present more user-friendly filters such as "starts with" and "contains."

Note

The Business Data Catalog uses the wildcard character specified in the LobSystem object metadata for filtering purposes.

• Comparison filter   Limits the instances returned to those where the condition is met. SQL supports it with the WHERE clause.

• Limit filter   Limits the number of instances returned to n. SQL supports it with the SELECT TOP clause. By using a Limit filter, you can prevent long waits, time outs and also prevent users from issuing bad queries that request large amounts of data.

• UserContext   Limits the instances by the current user's context. This filter tells the Business Data Catalog to append the current Microsoft Windows user's domain\username to the method call.

• Username   Limits the instances by a single sign-on (SSO) user name. This filter tells the Business Data Catalog to pass the user name from SSO as part of a parameter to the method call.

• Password   Works with the Username filter. This filter tells the Business Data Catalog to pass the password from SSO as part of a parameter to the method call.

  Note

  The back-end method definition should support the filters. Only then can you, in a context-sensitive manner, use filters to reflect in the front-end application the functionality that is available in the back end. The metadata simply declares which filters a method supports.

• UserProfile    A simple filter type you can specify in the FilterDescriptor definition. To use this filter, declare a filter of the type "UserProfile" and add a System.String property with the name "UserProfilePropertyName", whose value is the name of a user profile property. The Business Data Catalog will look up the current user's profile, read the value of the property with this name, and plumb that through to the back-end invocation.

• SSOTicket   Tells the Business Data Catalog to pass the SSO ticket from SSO as part of a parameter to the method call.

• LastIdSeen   Enables chunking for IDEnumerator enumeration members. For Web services and other non-streaming back-end applications, you should use the LastIdSeen filter in your IDEnumerator member to improve performance, as shown in the following example:

  SELECT TOP 100 Id FROM Customers WHERE Id>=@LastIdSeen
  ORDER BY Id
  

User filters such as Comparison declare which inputs users can override, and system filters such as UserContext and UserProfile allow the Business Data Catalog to securely set values such as user token.

Important

If a metadata author creates bad metadata that takes a user name as a user-controllable filter and returns sensitive personal data, a user may see another user's data. To avoid this, use UserContextFilter to pass in the user name to the method call.

Clients query the metadata repository to determine which filters the system supports and render their user interfaces accordingly.

Example

<FilterDescriptors>
      <FilterDescriptor Type="Wildcard" Name="Name">
         <Properties>
            <Property Name="UsedForDisambiguation" 
               Type="System.Boolean">true</Property>
         </Properties>
      </FilterDescriptor>
   <FilterDescriptor Type="Wildcard" Name="ProductNumber" />
</FilterDescriptors>

Schema

Child	Type	Occurs	Default	Limits / Accepted Values	Description
Type	Attribute (bdc:FilterDescriptorType)	1..1	true	Limit Comparison Wildcard UserContext Username Password LastId SsoTicket UserProfile	Specifies the type of filter.

Properties

Following are the properties that the FilterDescriptor object accepts for both database and Web service systems.

Important

Properties are case-sensitive.

Property	Type	Required	Default Value	Limits/Accepted Values	Comments
UsedForDisambiguation	System.Boolean	No	false	true false	If true, this filter is used in the business data picker to generate the list of possible matches.
CaseSensitive	System.Boolean	No	false	true false	If true, the Business Data Web Parts and Business Data picker tell the user this filter is case sensitive.
IsDefault	System.Boolean	No	false	true false	If true, this filter is selected by default in the Business Data picker.

See Also

Tasks

AdventureWorks SQL Server 2000 Sample
How to: Get Started with Using the Runtime Object Model
How to: Get Started with Using the Administration Object Model

Concepts

FAQ: Business Data Catalog
Business Data Catalog: Glossary