How to: Add Filter Parameters to Operations to Limit Instances from the External System

Applies to: SharePoint Server 2010

End users may want to retrieve the instances of an external content type that match some criteria, say in an external list. For example, a user may want to display only the customers who live in "New Jersey" or the orders made by a certain customer. To enable this functionality, the designer of the external content type can add filters to the required operations. In the state filter example above, the designer can create a filter parameter of Comparison Type, and then tag the State field in the Finder method with this newly created filter. Many such filters may be associated with a single method (API). Users then choose the filter they want at run time and specify a value for it, and the BDC 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 return only the rows the user wants to see.

Filters are the fundamental way in which the Business Data Connectivity (BDC) service captures user (or system) input and plumbs it through to the back-end API invocation. Filters describe where a filter value should be inserted in a complex series of parameters. This is accomplished by 'tagging' the input or return 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 filters only form a mechanism to surface this to the end user.

Line-of-business (LOB) systems provide various filtering mechanisms. The BDC abstracts common patterns so that it can provide users with the same filtering semantics, regardless of the data source. The BDC supports the several filters and filtering patterns. For details, see Types of Filters Supported by the Business Data Connectivity Service

User filters such as Comparison declare which inputs users can override, and system filters such as UserContext and UserProfile allow the BDC 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.

See Also

Tasks

How to: Add a Comparison Filter to a Method Instance That Returns Data