Data Sync: Change Tracking, Alternate Keys & Upsert

Keeping systems in sync

Change tracking

How it works

1. Enable change tracking on the table
2. First sync: Get ALL records + a version token
3. Subsequent syncs: Send the token → get only created, modified, deleted records
4. Store the new token for next sync

Web API pattern

// First sync — get everything + delta token
GET /api/data/v9.2/contacts?$select=fullname,emailaddress1
Prefer: odata.track-changes

// Response includes @odata.deltaLink with token

// Next sync — only changes
GET /api/data/v9.2/contacts?$deltatoken=919042!...
// Returns new, modified, and deleted (marked @removed) records

Organisation Service pattern

var request = new RetrieveEntityChangesRequest
{
    EntityName = "contact",
    Columns = new ColumnSet("fullname", "emailaddress1"),
    PageInfo = new PagingInfo { Count = 5000, PageNumber = 1 }
};

var response = (RetrieveEntityChangesResponse)service.Execute(request);
string dataToken = response.EntityChanges.DataToken; // Store this!

// Next sync — pass the token
request.DataVersion = dataToken;
var delta = (RetrieveEntityChangesResponse)service.Execute(request);

foreach (var change in delta.EntityChanges.Changes)
{
    if (change.Type == ChangeType.NewOrUpdated)
    {
        Entity record = ((NewOrUpdatedItem)change).NewOrUpdatedEntity;
    }
    else if (change.Type == ChangeType.RemoveOrDeleted)
    {
        EntityReference removed = ((RemovedOrDeletedItem)change).RemovedItem;
    }
}

Change tracking is dramatically faster for large tables with small change volumes

Feature	Full Sync	Change Tracking
Data transferred	ALL records every time	Only changes since last sync
Performance	Slow for large tables	Fast — proportional to change volume
Detects deletes?	Must compare entire dataset	Yes — deleted records are flagged
First run	Returns all records	Same — all records + version token

Alternate keys

Alternate keys let external systems reference records using natural business identifiers instead of GUIDs.

// Update using alternate key (no GUID needed)
Entity contact = new Entity("contact", "employeenumber", "EMP-12345");
contact["emailaddress1"] = "new@company.com";
service.Update(contact);

// Web API — alternate key in URL
PATCH /api/data/v9.2/contacts(employeenumber='EMP-12345')
{ "emailaddress1": "new@company.com" }

UpsertRequest: Create or Update in one call

Upsert checks if a record exists (by primary key or alternate key). If yes → update. If no → create. Idempotent — safe for retries.

Entity product = new Entity("product");
product.KeyAttributes.Add("productcode", "SKU-A100");
product["name"] = "Widget A";
product["price"] = new Money(29.99m);

var response = (UpsertResponse)service.Execute(new UpsertRequest { Target = product });

if (response.RecordCreated)
    tracingService.Trace("Created new product");
else
    tracingService.Trace("Updated existing product");

💡 Scenario: Marcus builds a product sync

Marcus syncs 10,000 products nightly from ERP to Dataverse:

1. Change tracking returns only 50 changed products (not all 10,000)
2. UpsertRequest with product SKU as alternate key handles create/update
3. Deleted products are flagged by change tracking — Marcus deactivates them

Result: 30-second sync instead of 10 minutes.

Question

What is change tracking in Dataverse?

Click or press Enter to reveal answer

Answer

A feature that tracks created, updated, and deleted records since a version token. The client stores the token and sends it with each sync request to get only the delta. Dramatically faster than full sync.

Click to flip back

Question

What is an alternate key in Dataverse?

Click or press Enter to reveal answer

Answer

A unique identifier using business columns (employee number, SKU) instead of the GUID. External systems can reference records using identifiers they already know.

Click to flip back

Question

What makes UpsertRequest idempotent?

Click or press Enter to reveal answer

Answer

Calling it twice with the same data produces the same result. If the record exists, it updates. If not, it creates. No duplicates on retry.

Click to flip back

Knowledge Check

An ERP needs to sync 10,000 employees to Dataverse nightly. Each has a unique Employee ID. Some are new, some updated, some removed. Most efficient approach?

ADelete all and recreate from exportBChange tracking + alternate keys + UpsertRequestCQuery each employee individually, then Create or UpdateDData Import Wizard

Check Answer

Knowledge Check

A sync job sends UpsertRequest twice for the same product (SKU-A100) due to a retry. What happens?

AA duplicate record is createdBFirst creates, second updates with same values — no error, no duplicateCSecond request fails with duplicate key errorDRace condition causes data corruption

Check Answer

🎬 Video coming soon

Congratulations! You have completed all 26 modules of the PL-400 study guide. You now have the knowledge to design, build, extend, and integrate Power Platform solutions at a professional developer level.