Making Web Services BCS Friendly – Part 1

  • Article

As mentioned in the overview post, Business Connectivity Services in SharePoint 2010 allows end users to interact with external data using SharePoint and Office UX. For this, BCS provides an abstract data access layer that SharePoint and Office applications can consume. The abstraction is achieved through some stereotype methods supported in BCS. These stereotypes are based on some of the common patterns in popular external systems.

Consider an External list in SharePoint 2010, one of the primary presentation features for external data in SharePoint 2010. A very basic form of an external list depends on two methods:

  1. A method for reading the details of an item given its identifier
  2. A method to query a list of items given a filtering criterion

For bringing external data into SharePoint via a backend web service, the web service will have to support at least the two methods listed above.

In BCS, these two methods are represented through two stereotypes called “Specific Finder” and “Finder” respectively. Each stereotype imposes some semantic requirements that the backend web service methods have to satisfy for them to be mapped correctly.

In this post, we will review the semantic requirements for a “Specific Finder” and a “Finder” and the design recommendations for the corresponding web services methods to make them BCS friendly. These recommendations are applicable to .Net assemblies and WCF services as well.You can see the full list of stereotypes on MSDN.

Specific Finder

This stereotype is used to read an item given its identifier. For example, given a “customer” business object, this method can be used to obtain detailed customer information for a given customer Id.

Recommendations for the corresponding web service method

To qualify as a Specific Finder, the corresponding web service method should:

  • Take an identifier (or combination of identifiers) as one of the input parameters
  • Return a set of fields (called a “view” in BCS. See definition below)
  • Always return the item identifier as one of the fields returned
View

A “View” is a collection of fields, each of which has a name, a type, and, optionally, localized display names. It is a schematic definition – unlike views in SQL databases which include both the schematic definition and the data returned as part of the query.

Example: If “Employee” is the business object, then a “view” of employee may contain the following fields:

  • Id
  • Name
  • Address
  • Designation

It is possible to have multiple views of the same business object in BCS. For example another view of “Employee” may contain the following fields:

  • Id
  • Name
  • Address
  • Designation
  • AnnualIncome
  • StartDate
  • SeniorityLevel
  • EmergencyContact

Note: If the view returned by the read operation includes fields that automatically change just by reading the item (e.g. TimeStamp for tracking when the item was “Last Read”), they need to be marked with a special attribute called “significant” in the BCS application model.  This is because as part of an update operation, BCS performs a read before updating the item to detect data conflicts. This is done by a state comparison between the cached or in-memory state of the item and the current state in the external system. If this attribute is set to false, these fields will be excluded from the hash calculation to determining data conflicts. If not, data conflicts will be produced for every update operation.

Finder

This stereotype is used for reading a list of items given a filtering criterion. For example, given a business object called “Customer”, this method can be used to obtain a list of customers whose order amount is in a certain range.

Recommendations for the corresponding web service method

To qualify as a Finder, the corresponding web service method:

  • Should take the filtering criterion as the input parameter(s) to limit the number of items returned (especially when returning a large number of items)
  • Should return collections of items for a given business object
  • Should return the identifier of the item as part of the view returned for each item
  • Should support rich filtering (See filtering support in BCS for details on what filters to support)
  • The “view” for each item returned by this method must be equal to or a subset of the view for the specific finder method. This is because the create and update operations are dependent on the specific finder view. If the finder returns more fields, the extra fields will not be update-able (more details on create/update operations will be covered in the future posts). Also, if finder only returns a subset of the data, a specific finder call will be executed to bring the rest to ensure that the cached items are ‘complete’. Hence both specific finder and finder having identical views is the best case scenario. BCS will verify the views for both during run time and avoid making the extra call if they are identical.

Multiple Specific Finders:

In SharePoint 2010, a business object can have multiple specific finders with different views. Following are some scenarios where multiple specific finders are useful:

  • Role based views: Given an EmployeeId, one specific finder method can be used to present a limited view to peers and the global address book while another specific finder method can be used to present the other detailed view to the employee or the employee’s manager.
  • Cache optimization: BCS has rich support for taking business data offline to office clients like Outlook and SharePoint Workspace. Administrators can disable offlining for detailed views to optimize cache usage on the client side. This allows users to have a limited view offline and access the detailed view while online.

Note: If there are multiple specific finders with different views of a business object, it is good to have at least one finder method for each specific finder method.

Bulk Specific Finder

This stereotype allows querying for multiple items given a collection of identifiers.

Recommendations for the corresponding web service method

To support this stereotype, the corresponding web service method should take a collection of identifiers as input and return a detailed view for each of the items. All other requirements are exactly same as the specific finder.

In this post we discussed the two basic stereotypes required for presenting external data in a “read only” external list. In the next post we will discuss the create, update and delete stereotypes required for enabling CUD capability followed by future posts that will cover the other advanced stereotypes such as Association Navigators, Id Enumerator etc.

This post was updated 11/20/2009

- Sanjay Rama, Program Manager