Incremental deployment allows to deploy all content changes in the source database since the last successful deployment which are in the configured scope of the content deployment job.
To implement this functionality content deployment makes use of so called “change tokens”.
Understanding Change Tokens
A very common issue with content deployment is that incremental content deployment fails with the following error message:
The changeToken refers to a time before the start of the current change log
But what does this actually mean?
What we have seen in the earlier article series about the content deployment and migration API to perform an incremental deployment we have to pass in a change token that will be used as a reference to identify which objects need to be exported.
Using a change token, an application can determine “what content has changed” within a given scope since the change token has been generated.
To do this the information included in the change token is compared against Change log.
About the Change Log
The Change log is stored in the EventCache table of the content database. This table stores the information about all content changes in the content database. Each entry in the Change log contains among other things the following information:
- A sequential number (Id) identifying the row in the event cache table
- The timestamp (EventTime) when the change has happened
- The type of the object (ObjectType) that has changed
- Identification (one or multiple IDs) of the object that was changed
- URL to the object that was changed (if the object has a URL)
- The type of modification (EventType) such as add, delete, … (see table below)
The following article contains some more details about these entries:
The change log stores information for a timeframe that can be configured in the Web application general settings:
About the Change Token
Each time the change log is queried for changes, it returns the changes together with a Change Token which corresponds to a database entry up to which the querying application has been synchronized. This change token is of the format Int1; Int2; Guid; Time; Int3.
- Int1: Contains version information for the change token. Currently this value is always 1.
- Int2: The scope the change token has been requested for. For example, if you ask for changes in the site collection this value will have the scope “Site”. If you request changes for a sub site, it will contain the scope “Web”. See the following table for possible values. Related to content deployment and the underlying API, this value is always 1 as content deployment always generates a change token with a scope of the whole site collection.
- Guid: Guid of the object the change token belongs to. If the change token was requested for a site collection this will be the Id of the SPSite object.
- Time: Timestamp (in ticks) of the change the token belongs to.
- Int3: change number in the event cache table the change belongs to.
The following scopes are possible for a change token:
Change Token Scope
When it comes to troubleshooting change token problems, it is also important to be able to analyze the change token itself – e.g. to see the date/time of the change it represents.
The following method allows to decrypt the change token into a better readable format:
This code will create output like the following:
Change Log, Change Token and SharePoint Object Model
The Change log can be queried for changes at four different scopes: Content Database, site collection, site or list scope. Depending on the application and what scope the application is interested in defines which scope needs to be used. For example, if an application is only interested in changes in a specific list, it can query for changes at the list scope. On the other hand, if changes across the entire database need to be monitored, then the change log can be queried at the content database scope.
The GetChanges method can be used to query for changes:
When you have a SPChangeCollection you can evaluate each change individually. Each SPChange object exposes the properties:
- ChangeToken – change token for this change
- ChangeType – see here
- SiteId – the unique ID identifying the site collection
- Time – the timestamp when this change happened
You can cast the individual SPChange objects to the exact change to get further information. For example, SPChangeWeb exposes the ID of the changed site. SPChangeFolder exposes the unique ID of the folder and the unique id of the site.