SharePoint List Synchronization

Article
10/20/2016

Applies to: SharePoint Foundation 2010

Implementations of the Microsoft Sync Framework in SharePoint Foundation provide two important capabilities: synchronization of lists and synchronization of document libraries. The following discusses list synchronization and the important features that support it.

List Synchronization

To support the synchronization of lists, it is necessary for all list items to have unique identifiers for tracking version updates. SharePoint Foundation uses the UniqueId property to support this requirement.

List Item Versioning

List items that are accepted or returned by knowledge-based functions are associated with two Sync Framework version change units – one change unit for the server version of the list item and another for the content version. The server change unit version is updated when there are changes to the read-only server fields; the content change unit version, on the other hand, is updated when any other portion of the list item is changed.

The respective server and content change unit versions are always evaluated for updates as a pair, even when updates are only to read-only server fields and no updates to the client are required. Following is a list of the read-only server fields that are associated with changes to the server change unit.

Read-Only Server Fields

1	ID
2	ows_hiddenversion
3	ContentTypeId
4	ContentType
5	Modified
6	Created
7	Author
8	Editor
9	FileRef
10	FileDirRef
11	LastModified
12	CreatedDate
13	FileSize
14	FSObjType
15	PermMask
16	CheckoutUser
17	VirusStatus
18	InstanceID
19	_CheckinComment
20	_Level
21	_IsCurrentVersion
22	_HasCopyDestination
23	_CopySource
24	_ModerationStatus
25	_ModerationStatus
26	WorkflowVersion

Updates to the Server

List item updates are captured on the server during upload operations. This prevents update collisions among browser clients that may try to update the same item at the same time. Updating on server upload is necessary because the Sync Framework uses a core SharePoint version field (ows_hiddenversion) to detect synchronization conflicts. Additionally, there are some item updates that are triggered by server-side actions – for example, updates to the Author field that are based on the ID of the user who uploads the item.

After these server actions are complete, updates must be synchronized back to the clients. If these changes are limited to read-only server fields, then only the server version is updated and the content version is left untouched. However, if there are changes to other than read-only server fields, or if item content is changed, then both the server and content versions are updated. This operation is treated as a browser update made by the user.

Note that actions that are made by the following server-side operations result in changes to the item content version, and therefore require updates to the client:

Antivirus check
IRM action
Parsing operations such as link repairs or property demotion
Schema changes to the list or content type
Document event-handler updates

Change Enumeration

Because update metadata is captured on upload to the server, only changes recorded on the server are maintained in the change log and provided in the change enumeration. In other words, a change enumeration reflects the most recent state of client-provided knowledge that is present on the server; this knowledge state is used to query the change log and get the set of changes that may be of interest to the client. Then, the Sync Framework checks items in the query result set against client knowledge and then determines whether a specified item should be sent to the client.

Note that the client knowledge may maintain a set of query exceptions – either item ranges or specific items – that filter out unwanted items from the result set.

Batching Changes to List Items

Rather than a continuous stream, concurrency updates are provided in item batches that are transferred in packets. The client specifies the batch size and the individual items are returned in the order they appear in the change log.

Batches are passed to the client along with a copy of the server knowledge. After processing the changes, clients then add new server knowledge to their own knowledge store. Finally, the client sets the most recently acquired server version to the server version field of the last received item.

A client may specify one or more exceptions with respect to its knowledge for items in a specified batch. Using exceptions ensure that a client does not get false conflicts in cases where a synchronization operation is interrupted. There are both positive and negative exceptions. Positive exceptions have full server knowledge for items in batches that it receives, while negative exceptions have the initial client knowledge for items that it skips in the batch. Note, however, that because processing exceptions on the server degrades server performance, clients should avoid using exceptions for batching changes and instead should organize batches based on the server knowledge.

Exceptions

The server detects and uses exception information in the following cases:

Change Enumeration
- The server passes items through a contains() function that filters out specified items from the result set.
- The server returns exception information in the MadeWithKnowledge element of the GetListItemChangesWithKnowledge(String, String, XmlNode, XmlNode, String, XmlNode, String, XmlNode, XmlNode) method.
Conflict Detection
- When a conflict is detected on the server side, the server creates an exception for the conflicting item.
Item Updates
- The server ignores change unit exceptions in synchronization knowledge. It does not store change unit exceptions in server knowledge if it receives this information from the client.

Detecting and Resolving Conflicts

Conflicts on the server occur when the ows_hiddenversion field on the server item differs from the value of the ows_hiddenversion field received from the client. When such a conflict occurs, the server does not attempt to resolve the conflict. Instead, the server adds the item exception to its knowledge and returns the error back to the client.

Conflicts occur on the client when version of the server knowledge is not congruous with client knowledge. When this occurs, the client must use the item's content version to resolve the conflict. In this scenario, the server version is ignored in the effort to resolve the conflict.

The most serious conflicts arise when the content version of the server item is not congruous with the client knowledge and the content version of the client item is not congruous with server knowledge. This is referred to as a "true" conflict. The Sync Framework cannot resolve such a conflict and the user must address the conflict through the user interface.

False conflicts occur when the server version of the item is not congruous with client knowledge, but the content versions is congruous with either the server or client knowledge. This type of conflict is resolved automatically by client without user intervention. If the client content version is congruous with server knowledge, then the server item wins the resolution race.

When either a true or a false conflict is resolved in favor of the client version, the client creates a union set that combines its knowledge with that of the server and sets the ows_hiddenversion field on the client item to the value that exists on the server item. It then synchronizes the client version of the item to the server state.