Introduction to System Filters

  • Article

Filters are used by Microsoft Business Connectivity Service (BCS) to give values to input parameters while invoking a Method on the External System (LobSystem). But there could be some parameters whose values should be provided by the system (example: username, password) and not from the user. Filters that provide values to these input parameters are called System Filters.

Here is an example Scenario of when to use System Filter: Jim has a web service operation that creates a file. The method takes filename, user name, and password. File name will be passed as user input, but username and password will have to be passed from the system. Jim needs a solution to pass these values without requesting them from the user.

Solution: Jim will have to configure username and password filters for the parameters that match username and password. Jim will also have to specify the “SecondarySSOApplicationID” and “SSOProviderImplementation” on the External System Instance, which will be used by the filters to fetch username and password values. This will make the system provide username and password as values to input parameters.

The different types of System Filters that are supported are:

  • ActivityID (Activity Identifier Filter)
    Activity Identifier Filter is used while calling operations on an external system, and the value to be passed as input parameter should represent a context identity of the invoking operation.
    BCS sets aGUID that represents the current operation context as the value on the input parameter which is associated with the ActivityID filter.  
     
  • Password (Password Credential Filter)
    Password credential filter is used while calling operations on external system and the value to be passed as input parameter should represent a password stored in Secure Store.
    BCS gets the credentials that map to the External System Instance (LobSystemInstance) properties “SecondarySsoApplicationId” and “SsoProviderImplementation”. It uses the password obtained from credentials as the value for the input parameter which is associated with the Password filter. Note: SecondarySSOApplicationId is different from SSOApplicationId, SecondarySSOApplicationId is used by UserName filter and Password filter. For more information read SecondarySSOApplicationID property on LobSystemInstance .
     
  • SSOTicket (Single sign on Ticket Filter)
    Single sign on ticket filter should be used while calling an operation on the External System and the value to be passed as an input parameter should represent a sign on ticket for the user from the Secure Store. The target service or application can then redeem this ticket to get the user credentials.
    BCS uses the “SSOProviderImplementation” property specified in the External System Instance and requests this provider to issue an SSOTicket. This SSOTicket is passed as the input parameter which is associated with the SSOTicket filter.
     
  • UserContext (User Context Filter)
    User Context Filter should be used while calling an operation on the External System.The value to be passed as an input parameter should represent the user context.
    • In this case, BCS uses the “UserContextType” property on the Filter (FilterDescriptor) to find a value to set on the input parameter. If the “UserContextType” specified is “MachineId”, the value passed to the input parameter will be the unique id for machine’s operating system installation.
    • If the “UserContextType” specified is “QualifiedUserName”, the value passed to the input parameter will depend:
      • If the login mode for user is Windows classic, the value will be the windows logon name for the user. This will contain the domain name and the user name (example: domainname /username).
      • If the login mode for user is Claims based, then value passed will be the unique value that identifies the user (example: membership:username, username@provider.com).
         
  • UserCulture (User Culture Filter)
    User Culture Filter should be used while 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 invoking the operation.
    BCS uses the “Format” property on the Filter to find a value to set on the input parameter.
  • UserName (User Name Credential Filter)
    User Name Credential Filter should be used while calling an operation on the External System and the value to be passed as an input parameter should represent the User Name stored in Secure Store.
    BCS gets the credentials that map to the External System Instance properties “SecondarySsoApplicationId” and “SsoProviderImplementation”. It uses the user name obtained from credentials as the value for the input parameter which is associated with the UserName system filter. Note: SecondarySSOApplicationId is different from SSOApplicationId, it’s used by UserName filter and Password filter. For more information read SecondarySSOApplicationID property on LobSystemInstance .
     
  • UserProfile (User Profile Filter)
    User Profile Filter should be used while calling an operation on the External System and the value to be passed as an input parameter should be a property on the current user’s profile.
    BCS uses the “UserProfileProvider” and the “UserProfilePropertyName” properties 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.

Configuring System Filters

SPD approach:

System Filters can be configured for input parameters via SPD. The steps to configure System Filters via SPD are:

  1. Open SPD
  2. Click on “OpenSite” and open a site.
  3. Click on “External Content Types” on “Site Objects” pane on the left of SPD.
  4. Click on “New External Content Type” ribbon button to create new external content type.
  5. Click on “Operations Design View” ribbon button to create new methods for external content type.
  6. Click on “Add Connection” button and discover a data source connection.
  7. Enter the method configuration wizard used to design the operations, by right clicking a data source node and selecting the operation that is required.
  8. Move to the Input Parameter Configuration to define filters for input parameters.
  9. Click on the “Click to Add” next to filters to configure filters. The screen shot below shows the link that is used to create filters.clip_image002
  10. Select New Filter and give it a name.
  11. Use the Filter Type combo box to choose a System Filter as shown in the screen shot below:
    image

Hand Written Approach:

System Filters can be configured by making changes to the model file by hand. The steps to follow to configure System Filters are:

  1. Open the Model file.

  2. Find the method whose input parameters should be configured with system filters.

  3. Add FilterDescriptors section or modify if one already exist, to add filter descriptors that point to system filters. An example to configure SsoTicket System filter is shown below.

    <FilterDescriptors>
      <FilterDescriptor Type="SsoTicket" Name="NameofSsoTicketFilter">
      <!-- properties omitted -->
      </FilterDescriptor>
    </FilterDescriptors>

  4. Configure your desired input parameter’s type descriptor to point to this FilterDescriptor created in the previous step. An example to configure the above created FilterDescirptor is shown below:

    <Parameter Direction="In" ...>
      <!-- properties omitted –>
      <TypeDescriptor FilterName="NameofSsoTicketFilter" ...>
        <!-- properties omitted –>
      </TypeDescriptor>
    </Parameter>

- Tittu Jose, Software Development Engineer