Use change tracking to synchronize data with external systems

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

The change tracking feature in Microsoft Dynamics 365 provides a way to keep the data synchronized in a performant way by detecting what data has changed since the data was initially extracted or last synchronized. Previously, without this new feature, it was difficult to build a reliable and efficient mechanism to determine what records had changed in Dynamics 365. This topic discusses how to retrieve changes for an entity.

In This Topic

Enable change tracking for an entity

Retrieve changes for an entity

Sample code

Enable change tracking for an entity

Before retrieving the changes for an entity, make sure that the change tracking feature is enabled for that entity. This feature can be enabled by using the customization user interface (UI) or programmatically by setting the ChangeTrackingEnabled property to True. For more information about using the customization user interface (UI), see Enable change tracking to control data synchronization.

Retrieve changes for an entity

When change tracking is enabled for an entity, you can use the RetrieveEntityChangesRequest message to retrieve the changes for that entity. The first time this message is used it returns all records for the entity and that data can be used to populate the external storage. The message also returns a version number that will be sent back with the next use of the RetrieveEntityChangesRequest message so that only data for those changes that occurred since that version will be returned.

You should be aware of the following constraints when retrieving changes for an entity:

• Only one entity will be tracked in retrieve changes. If retrieve changes is executed with no version / or token, the server will treat it as the system minimum version, returning all of the records as new. Deleted objects won’t be returned.

• Changes will be returned if the last token is within a default value of 90 days. If it is more than 90 days, the system will return all the records.

• If a client has a set of changes for an entity, say version 1, a record is created and deleted prior to the next query for changes, they will get the deleted item even if they didn’t have the item to begin with.

• Records are retrieved in the order determined by server side logic. Usually, the end user will always get all new or updated records first (sorted by version number) followed by deleted records.  If there are 3000 records created or updated and 2000 records deleted, Dynamics 365 returns a collection of 5000 records, which have the first 3000 entries comprised of new or updated records and the last 2000 entries for deleted records.

• If the new or updated item collection is greater than 5000, the user can page through the collection.

Sample code

The following code snippet shows how the RetrieveEntityChangesRequest message is used to retrieve the changes for an entity. For the complete sample, see Synchronize data with external systems using change tracking.

string token;

// Initialize page number.
int pageNumber = 1;
List<Entity> initialrecords = new List<Entity>();

// Retrieve records by using Change Tracking feature.
RetrieveEntityChangesRequest request = new RetrieveEntityChangesRequest();
request.EntityName = _customBooksEntityName.ToLower();
request.Columns = new ColumnSet("sample_bookcode", "sample_name", "sample_author");
request.PageInfo = new PagingInfo() { Count = 5000, PageNumber = 1, ReturnTotalRecordCount = false };


// Initial Synchronization. Retrieves all records as well as token value.
Console.WriteLine("Initial synchronization....retrieving all records.");
while (true)
{
    RetrieveEntityChangesResponse response = (RetrieveEntityChangesResponse)_serviceProxy.Execute(request);

    initialrecords.AddRange(response.EntityChanges.Changes.Select(x => (x as NewOrUpdatedItem).NewOrUpdatedEntity).ToArray());
    initialrecords.ForEach(x => Console.WriteLine("initial record id:{0}", x.Id));
    if (!response.EntityChanges.MoreRecords)
    {
        // Store token for later query
        token = response.EntityChanges.DataToken;
        break;

    }
    // Increment the page number to retrieve the next page.
    request.PageInfo.PageNumber++;
    // Set the paging cookie to the paging cookie returned from current results.
    request.PageInfo.PagingCookie = response.EntityChanges.PagingCookie;
}

See Also

Define alternate keys for an entity
Use an alternate key to create a record
Use Upsert to insert or update a record

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright