Implementing an Updater

  • Article

Applies to: SharePoint Server 2010

In this article
Description
Syntax
Remarks
Examples

Description

An Updater method instance enables you to update an existing entity instance in an external system. For example, given a business object named Customer, this stereotype can be used to update the address of a customer "John" in the external system.

If you do not define an Updater method, items cannot be updated by using the Business Connectivity Services features for the entity. For example, you cannot click the Edit Item button on the ribbon of an external list that is based on that external content type, to edit an item in the list.

BDC performs a read operation before update to detect any data conflicts.

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

Syntax

Following is the typical method signature for an Updater method:

void UpdateEntity(EntityDataType fields)
void UpdateEntity(EntityDataType fields, EntityDataType previousValuesOfFields)

Remarks

To qualify as a Updater method:

  • The Updater method should take the identifier (or combination of identifiers) of the item as input.

  • The Updater method should take all the read/write fields of a SpecificFinder method.

  • The Updater view must be equal to, or a subset of, the SpecificFinder view.

Note

We recommend that the update method be transactional to avoid potential data loss.

If there are multiple specific finders, the Updater view should be equal to, or a subset of, at least one SpecificFinder view.

As in the case of the Creator view, the Updater view must be equal to, or a subset of, the view of one of the specific finders. It must contain all of the fields in the specific finder that are not read-only. This is because the Business Connectivity Services auto generated forms are dependent on the SpecificFinder view. If not, the extra fields in the Updater view will not be updatable. Just like the create operation, Business Connectivity Services checks for this dependency and disables the update operation on the external list. Updatable identifiers (or combination of identifiers) can also be updated by this stereotype, but they are not supported by the Business Connectivity Services auto-generated forms.

Table 1 summarizes the dependencies for the Creator view and the Update view and status for create and update operations.

Table 1. 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

Field F cannot be found on the specific finder. This causes BCS to disable create operations 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

The values of field B and field E can be specified by the 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

The value of field B can be specified by the user during create, but cannot be updated later.

The 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 only on default EL forms

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

The values of field B and field E are assigned by the external system.

6.     

A

B (read-only)

C

D

E (read-only)

A

B

C

No update operation defined

Create: Allowed only on default EL forms

Update: Not allowed

Offline Create: Not allowed

Offline Update: Not allowed

The 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 the offline create operation.

Note

Ensure that you handle null values correctly. Validate whether the fields are required and do not assign null to fields that are not required.

Warning

The names of the parameters must match what is defined in the external system. Names of parameters are case-sensitive.If the names of parameters are not identical on all methods, Microsoft SharePoint Designer 2010 interprets them as different fields.

It is important to handle exceptions properly. The Updater case has a few interesting exceptions, which are listed in Table 2.

Table 2. Exceptions

Exception Name

Use This Exception When….

AccessDeniedException

User is not allowed to perform this operation on the external system.

ConflictDetectedException

Used for conflict resolution. The item was updated concurrently and was changed by another user.

LobBusinessErrorException

Guarantees that the error message is displayed to the user as is (from the external system).

ObjectDeletedException

Use this exception if the item is known to be deleted.

ObjectNotFoundException

The item is not found.

RuntimeException

If the update fails, ensure that you raise this exception to alert your users and to use the error handling features in Microsoft Outlook 2010 and Microsoft SharePoint Workspace 2010.

Examples

Code Snippet: Implementing an Updater

See Also

Concepts

XML Snippet: Modeling an Updater Method

Code Snippet: Execute an Updater Method Instance of an External Content Type