Types of Filters Supported by the Business Data Connectivity Service

Applies to: SharePoint Server 2010

Filters are the fundamental way in which the Business Data Connectivity (BDC) service captures user input (or system input) and provides it to the back-end API invocation. Filters describe where a filter value should be inserted in a complex series of parameters. This is done by "tagging" the input or return parameters of a method definition to flag where the insertion should occur. The back-end API invocation must supply the functionality for filtering. The filters form only a mechanism to surface this to the user.

External 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 several filters and filtering patterns. User filters, such as Comparison, declare which inputs users can override. System filters such as UserContext and UserProfile enable the BDC to securely set values such as a user token. For details, see Table 1. Clients query the metadata repository to determine which filters are supported by the system and to render their user interfaces accordingly.

Important

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

Table 1 describes the filters that are supported by the BDC.

Table 1. Filter values

Value	Filter Type	Description
ActivityId	System Filter	Used when calling an operation on an external system and the value to be passed as an input parameter should represent a context identity of the invoking operation. Business Connectivity Services sets a GUID that represents the current operation context as the value on the input parameter that is associated with the ActivityId filter.
Batching	User Filter	Used when querying the external system. Its value can be set automatically by any client application, to the last value of the filter that was obtained from the external system. This value can then be used by the external system to resume an enumeration of items or changes.
BatchingTermination	User Filter	Used when querying the external system. The value returned by the external system indicates whether additional calls are necessary to get the remaining data.
Comparison	User Filter	Used when querying an external system. An external system can compare a ComparisonFilter value with the value of a particular field of a set of EntityInstances and can return only those EntityInstances where the field values pass the comparison test.
Input	User Filter	Used when calling an operation in an external system. An external system can use the value of an InputFilter as an additional argument for the operation.
InputOutput	User Filter	Used when calling an operation in an external system. An external system can use the value of an InputOutputFilter as an additional argument for the operation, and additional results of an operation that cannot be captured by ReturnTypeDescriptor can be retrieved as a value of the InputOutputFilter.
LastId	User Filter	Used when querying an external system. Its value can be set automatically by any client application, to the identifier values from the last item read from the external system in a finder that returns the data in multiple chunks. This value can then be used by the external system to return remaining items, starting from the next item.
Limit	User Filter	Used when querying an external system. Its value can be interpreted as a limit on the number of external items (EntityInstances) that are returned when the method that it belongs to is called.
Output	User Filter	Used when calling an operation in an external system. Additional results of an operation that cannot be captured by ReturnTypeDescriptor can be retrieved as a value of the InputOutputFilter.
PageNumber	User Filter	Used when querying the external system. Its value represents the zero-based index of the page that the external system should return for a multipage result.
Password	System Filter	Used when calling operations on an external system and the value to be passed as an input parameter should represent a password that is stored in the Secure Store. Business Connectivity Services gets the credentials that map to the SecondarySsoApplicationId property and the SsoProviderImplementation property of the external system instance (LobSystemInstance). It uses the password that is obtained from the credentials as the value for the input parameter that is associated with the Password filter. Note SecondarySSOApplicationId is different from SSOApplicationId. SecondarySSOApplicationId is used by the UserName filter and the Password filter. For more information, see BDC Custom Properties and LobSystemInstance Element in LobSystemInstances (BDCMetadata Schema).
SSOTicket	System Filter	Used when calling an operation on an external system and the value to be passed as an input parameter should represent a sign-on ticket from the Secure Store for the user. The target service or application can then redeem this ticket to get the user credentials. Secure Store uses the SSOProviderImplementation property that is specified in the external system instance and requests this provider to issue an SSOTicket. This SSOTicket is passed as the input parameter that is associated with the SSOTicket filter.
Timestamp	User Filter	Used when calling an operation on the external system. Its value represents the time when the client last called this function. This value can then be used by the external system to report changes after the specified time.
UserContext	System Filter	Used when calling an operation on the external system and the value to be passed as an input parameter should represent the user context. In this case, Business Connectivity Services uses the UserContextType property on the filter (FilterDescriptor) to find a value to set on the input parameter. If the UserContextType that is specified is MachineId, the value passed to the input parameter is the unique ID of the computer's operating system installation. If the UserContextType that is specified is QualifiedUserName, the value that is passed to the input parameter is one of the following: If the login mode of the user is Windows Classic, the value is the Windows logon name for the user. This contains the domain name and the user name (for example, domainname/username). If the login mode for the user is claims-based, then the value passed is the unique value that identifies the user (for example, membership: username, username@provider.com).
UserCulture	System Filter	Used when calling an operation on the external system and the value to be passed as an input parameter should represent the culture of the user environment that is invoking the operation. Business Connectivity Services uses the Format property on the filter to find a value to set on the input parameter: If the value of the Format property is RFC1766, the value passed to the input parameter is the name of the culture. For more information, see CultureInfo.Name. If the value of the Format property is TwoLetterISO, the value passed to the input parameter is the two-letter ISO language name of the culture. For more information, see CultureInfo.TwoLetterISOLanguageName. If the value of the Format property is ThreeLetterISO, the value passed to the input parameter is the three-letter ISO language name of the culture. For more information, see CultureInfo.ThreeLetterISOLanguageName. If the value of the Format property is ThreeLetterWindows, the value passed to the input parameter is the three-letter Windows language name of the culture. For more information, see CultureInfo.ThreeLetterWindowsLanguageName. If the value of the Format property is LCID, the value passed to the input parameter will be the LCID of the culture. For more information, see CultureInfo.LCID.
UserName	System Filter	Used when calling an operation on an external system and the value to be passed as an input parameter should represent the user name that is stored in the Secure Store. Business Connectivity Services gets the credentials that map to the SecondarySsoApplicationId property and the SsoProviderImplementation property of the external system instance. It uses the user name that is obtained from the credentials as the value for the input parameter that is associated with the UserName system filter. Note SecondarySSOApplicationId is different from SSOApplicationId. SecondarySSOApplicationId is used by the UserName filter and the Password filter. For more information, see BDC Custom Properties and LobSystemInstance Element in LobSystemInstances (BDCMetadata Schema).
UserProfile	System Filter	Used when calling an operation on an external system and the value to be passed as an input parameter should be a property on the current user's profile. Business Connectivity Services uses the UserProfileProvider property and the UserProfilePropertyName property that are specified on the filter to find a value to set on the input parameter. UserProfileProvider is used to fetch the current user's profile and UserProfilePropertyName contains the property name whose value on the user profile should be passed to the input parameter.
Wildcard	User Filter	Used when querying an external system. Its value represents a pattern of regular characters and wildcard characters that is matched against the value of a particular field of the set of EntityInstances. The external system returns only those EntityInstances whose field values match the specified pattern.