How Are Changes Propagated to the External System?

Applies to: SharePoint Server 2010

In this article
Create Operation
Update Operation
Delete Operation

When external data is changed locally, the write operations are not immediately routed to the external system but are routed to the cache. The cache puts these operations in the operation queue executes them one-by-one. The time at which an operation in the queue will be executed cannot be predicted and depends on the cache refresh interval, availability of the external application and several other factors. The following section describes how the cache executes the different write operations.

Create Operation

When you create an entity instance in your application in cached mode, a Create operation is added to the operation queue. Business Connectivity Services creates an entity instance locally and assigns a temporary ID to the newly created entity instance in the cache until the entity instance can be created in the external application and its real ID can be obtained. The temporary ID (a GUID) is returned to the calling application as part of the EntityInstance reference.

Note

You can use the IsTemporary flag on the Identity field of the offline entity instance to determine if the identity is temporary.

When the operation is executed in the external application and if the operation was successful, the ID of the newly created entity instance is updated with the actual ID from the external system and the entity instance is marked for refresh, so that the values of any computed fields can be refreshed. If the call failed, the entity instance is marked as InError and any exceptions are recorded in the cache.

Update Operation

When you update an entity instance in your application in cached mode, the changes are recorded in the cache. An Update operation is added to the queue and the original data of the entity instance before the local update is recorded in the cache. When the runtime gets to executing this operation, it calls the SpecificFinder first to get the latest information from the external application and compares it with the original state to make sure that the data has not been changed in the external application by another user or application. If no conflicts are detected, an Update method instance call is made to the external application. If the operation was successful, the entity instance is marked refresh, so that the values of any computed fields can be refreshed. If the call failed, the entity instance is marked as InError and any exceptions are recorded in the cache. If a conflict is detected, the entity instance is again marked as InError and a ConflictDetectedException is recorded in the cache on the entity instance.

On the other hand, if the SpecificFinder throws an ObjectNotFoundException or ObjectDeletedException, it means that another user or another application already deleted this entity instance in the external application and in that case, the Update operation is marked as failed.

Delete Operation

When you delete an entity instance in your application in cached mode, the delete is recorded in the cache. A Delete operation is added to the queue and the original data of the entity instance before the local delete is recorded in the cache. When the runtime gets to executing this operation, it calls the SpecificFinder first to get the latest information from the external application and compares it with the original state to make sure that the data has not been changed in the external application by another user or application. If no conflicts are detected, a Delete method instance call is made to the external application. If the operation was successful, the entity instance in the cache is marked as Deleted. If the call failed, the entity instance is marked as InError and any exceptions are recorded in the cache.

On the other hand, if the SpecificFinder throws an ObjectNotFoundException or ObjectDeletedException, it means that another user or another application already deleted this entity instance in the external application and in that case, no errors are returned, the entity instance is deleted from the cache and the Delete operation is simply marked successful.