Making Web Services BCS Friendly – Part 2

As mentioned in the overview post, Business Connectivity Services in SharePoint 2010 allows end users to interact with external data using SharePoint and Office interfaces. 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.

In Making web services BCS friendly- Part 1, we reviewed the semantic requirements for the Read methods required to present external data in the form of an external list in SharePoint 2010. In this post we will look at enabling “Create”, “Update” and “Delete” capability (CUD) and review the semantic requirements that the corresponding backend web service methods have to satisfy.

As mentioned in part 1, these recommendations are applicable to .Net assemblies and WCF services as well. You can see the full list of stereotypes on MSDN.

Creator

BCS supports create functionality through the “Creator” stereotype. This stereotype is used to create an item in the external system. For example, given a business object called “Customer”, this method can be used to create a new customer.

Part1 described a view in BCS. For a create method, the set of fields that are required to create the new item is referred to as the “Creator View”.

Recommendations for the corresponding web service method

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

• Take the fields required to create the item as input parameters
• Either take the identifier (or combination of identifiers) of the item as input – OR – Return the Identifier (or combination of identifiers) for the newly created item
• The Creator View should be equal to or a subset of the view of the specific finder method (see example below)
• If there are multiple specific finders, the creator view should be equal or subset of at least one specific finder view

Creator View and Specific Finder View

As mentioned above, the creator view must be equal to or a subset of at least one specific finder view (It may include read only fields). This is because in external lists, the BCS auto generated forms used for creating items are based on the Specific Finder view. If the creator view has extra fields, these will not be displayed on the auto generated forms and can cause problem with the create operation. To avoid this, BCS will check for this dependency and disable the create operation on the external list if the creator view is larger than the specific finder view.

If Creator View is a subset of the specific finder view, BCS will allow creation of the item with the create operation in external lists. But for offline scenarios (for instance Outlook), an update method will be required as BCS will call the update method immediately after the create method (for updating the fields that are not included in the creator view).

See examples later in this post for different scenarios in which create is allowed or not allowed.

Other notes

• The backend web service method should ensure that the create operation is transactional. The BCS stereotype merely maps to the backend method.

Updater

BCS supports update functionality through the “Updater” stereotype. This stereotype is used for updating an item given its identifier (or combination of identifiers). For example, given a business object called “Customer”, this method can be used to update the customer’s phone number.

For an update method, the set of fields that are required to update the item is referred to as the “Updater View”.

Recommendations for the corresponding web service method

To qualify as an Updater, the corresponding web service method should:

• Take the identifier (or combination of identifiers) of the item as input
• The updater view
  • Must contain all non-read only fields in the specific finder view
  • Must be equal to or a subset of the specific finder view
• If there are multiple specific finders, the updater view should be equal or subset of at least one specific finder view.

Updater View and Specific Finder View

As in case of the Creator view, the Updater view must be equal to or a subset of the view of one of the specific finders. This is because the BCS auto generated forms are dependent on the Specific Finder view. If the Updater view is not equal to or a subset of the view of one of the specific finders, the extra fields in the updater view will not be updatable. Just like the create operation, BCS will check for this dependency and disable the update operation on the external list.

Updatable identifier (or combination of identifiers) can also be updated by this stereotype BUT they are not supported by the default BCS forms.

Other notes

• The backend web service method should ensure that the update operation is transactional. The BCS stereotype merely maps to the backend method.

· The BCS update stereotype maps to a single API of the back-end. For aggregation the .NET connector should be used.

Examples

The following table summarizes the dependencies for Creator View and Update View and status for create and update operations:

Scenario #	Fields in Specific Finder View	Fields in Creator View	Fields in Updater View	Operations allowed	Notes
1.	A B (read only) C D E (read only)	A B C D E F	A C D F	Create: Not allowed Update: Not allowed Offline Create: Not allowed Offline Update: Not allowed	The field F for the creator and updater cannot be found on the specific finder. This causes BCS to disable both create and update operations.
2.	A B (read only) C D E (read only)	A B C D E	A C D	Create: Allowed Update: Allowed Offline Create: Allowed Offline Update: Allowed	Values of fields B and E can be specified by user during create but cannot be updated later.
3.	A B (read only) C D E (read only)	A B	A C D	Create: Allowed Update: Allowed Offline Create: Allowed Offline Update: Allowed	Value of field B can be specified by user during create but cannot be updated later. Value of field E is assigned by the external system and cannot be updated by the user. For offline create, the update operation is called immediately after create.
4.	A B (read only) C D E (read only)	A B	A C	Create: Allowed on default EL forms only Update: Not allowed Offline Create: Not allowed Offline Update: Not allowed	Field D cannot be updated. This inconsistency causes BCS to disable the update operation. Offline create is disabled because there is no valid update operation.
5.	A B (read only) C D E (read only)	A C D	No update operation defined	Create: Allowed Update: Not Allowed Offline Create: Allowed Offline Update: Not allowed	Values of fields B and E are both assigned by the external system.
6.	A B (read only) C D E (read only)	A B C	No update operation defined	Create: Allowed on default EL forms only Update: Not allowed Offline Create: Not allowed Offline Update: Not allowed	Value of Field D cannot be set during create and there is no valid update operation defined for setting it later. This causes BCS to disable offline create operation.

Deleter

This stereotype is used for deleting an item given its identifier. For example, given a business object called “Customer”, this method can be used to delete a customer with Id 1001.

Recommendations for the corresponding web service method

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

• Should take the identifier (or combination of identifiers) of the item as input.

In this post we discussed create, update and delete stereotypes required for enabling CUD capability. Future posts that will cover the other advanced stereotypes such as Association Navigators, Id Enumerator etc.

- Sanjay Rama, Program Manager