Dynamics CRM - Entity Change Tracking

With the release of Dynamics CRM 2015 Online Update 1, Microsoft has provided developers many different ways to optimize performance when integration with other systems.  We already covered Alternate Keys in a previous post which help increase performance by reducing the need to make retrieve API calls in order to find the primary key of a record.  In this post I will cover Entity Change Tracking, another feature of 2015 Online Update 1 which increases performance when needing to send data to an external system by retrieving only a subset of data that has changed since the last retrieval. 

So how does it work?

First you need to enable Change Tracking for the specific entity you want to use it on.  You can do this through the Entity customizations as shown below.

Then the RetrieveEntityChanges request can be used in code to get a list of entity records that have changed since the last retrieval.  If it is the first request then you’ll want to pass in an empty string or null to the DataVersion property but subsequent requests should use a token (which is returned from RetrieveEntityChangesRespone) in order to retrieve a list of records that have been changed since the last request.

string token = "";

var records = new List<Entity>(); 
    
var request = new RetrieveEntityChangesRequest(); 
request.EntityName = "account"; 
request.Columns = new ColumnSet("name"); 
request.PageInfo = new PagingInfo() { Count = 5000, PageNumber = 1, ReturnTotalRecordCount = false }; 
request.DataVersion = token;    
    
while (true) 
{ 
     var response = (RetrieveEntityChangesResponse)orgService.Execute(request); 
    
     records.AddRange(response.EntityChanges.Changes.Select(x => (x as NewOrUpdatedItem).NewOrUpdatedEntity).ToArray()); 
     records.ForEach(x => Console.WriteLine(x.Id)); 
     if (!response.EntityChanges.MoreRecords) 
     { 
         token = response.EntityChanges.DataToken; 
         Console.WriteLine(token); 
         break;    
     } 
        
     request.PageInfo.PageNumber++; 
     request.PageInfo.PagingCookie = response.EntityChanges.PagingCookie; 
}   

Running this code using LinqPad in a brand new Online trial org with no token provided a list of 10 records that have been changed:

c15e1260-e2cf-e511-80de-a45d36fd127c
c35e1260-e2cf-e511-80de-a45d36fd127c
c55e1260-e2cf-e511-80de-a45d36fd127c
c75e1260-e2cf-e511-80de-a45d36fd127c
c95e1260-e2cf-e511-80de-a45d36fd127c
cb5e1260-e2cf-e511-80de-a45d36fd127c
cd5e1260-e2cf-e511-80de-a45d36fd127c
cf5e1260-e2cf-e511-80de-a45d36fd127c
d15e1260-e2cf-e511-80de-a45d36fd127c
d35e1260-e2cf-e511-80de-a45d36fd127c

And then the DataToken:

568840!02/10/2016 21:11:27

Running the same code above but passing in the token of “568840!02/10/2016 21:11:27” will now yield no results as expected as Account records haven’t been changed since we made our RetrieveEntityChanges request.

As you can see, this new request will be very handy when there is a need to synchronize data to external systems.  Now you can easily optimize performance by only synchronizing records that have been changed since the last sync.