Alternate Keys in Dynamics CRM 2015 Online Spring Update

Ahmed Anwar, 24 April 2015

Alternate keys is a new feature introduced in Spring Update and it is one of three features that significantly improves integrations/synchronizations with other systems.

When synchronising data with other systems, you might deal with annoying problems when mapping records with different Data Types. Currently, I am working on a project to sync data between Microsoft Dynamics CRM and Zendesk using Microsoft Sync Framework. In this project I sync Cases in CRM with Tickets in Zendesk. For your information, Zendesk is a Customer Support service to receive/answer tickets from your customers using a Website or APIs. As we know, the data type of Primary Keys in CRM is GUID. However, the data type in Zendesk is long. If you want to pull a ticket from Zendesk and push it and CRM, you would need a mechanism to convert a Long to a GUID. Well, to avoid complexities of how to translate GUIDs to Longs and vice versa, Alternate Keys is the magic answer to this dilemma.

As you can see, without alternate keys, you would have to implement an intermediate layer to translate/convert GUIDs to Longs but After Alternate Keys, all you need is to create a new field in CRM with same data type from the external system and tell CRM that this is an Alternate Key. After the Alternate Key is active and indexed, you are ready to consume it in your code.

Creating Alternate Keys  

To create a new Alternate Key, we first need to create a Field to tell CRM that it is going to be the Alternate Key. Alternate Keys can use two types of Data Types either Single Line of Text, Whole Number or Decimal Number.    
In my case, the field in CRM is Single Line of Text. Unfortunately, CRM only uses System.Int32 but not System.Int64, so the workaround is to parse the field to long.

Entity lead = GetLeadFromCrm();
string leadAlternateKey = lead.GetAttributeValue<string>("mag_zendeskid");
long valueToZendesk = long.Parse(leadAlternateKey);

Create the field as Single Line of Text and go to Keys and click New.

Enter your Display name and press TAB to set the schema name. Select the field you just created and click Add.

Click Save and Close

Now your Alternate Key is active and ready to be used.

Consume Alternate Keys in SDK Messages  

The following code snippets show how to use Alternate Keys in CRUD operations for Entity and Entity Reference.

Entity

1. Create – Alternate Keys are NOT allowed. Must use GUID

        string myStringAlternateKey = "123";
        Entity account = new Entity("account", "mag_zendeskid", myStringAlternateKey);
        account["name"] = "the name of the account";
    // NO, you can't use this constructor if you want to create a record
    // you would end up getting exception: A record with the specified key values
    does not exist in account entity
    crmService.Create(account);

2. Update – Alternate Keys are allowed

        string myStringAlternateKey = "123";
        Entity account = new Entity("account", "mag_zendeskid", myStringAlternateKey);
        account["name"] = "the name of the account";
    crmService.Update(account);

3. Delete – Alternate Keys are NOT allowed. Must use GUID

crmService.Delete("account", new Guid("<GUID>"));

4. Retrieve – Alternate Keys are NOT allowed. Must use GUID

        crmService.Retrieve("account", new Guid("<GUID>"),
        new ColumnSet("column1"));

Entity Reference  

1. Create – Alternate Keys are allowed

string myStringAlternateKey = "123";
Entity contact = new Entity("contact);
    // Link a contact to a parent account using Alternate Key
    contact["parentcustomerid"] = new EntityReference("account", "mag_zendeskid",
    myStringAlternateKey);
    crmService.Create(contact);

2. Update – Alternate Keys are allowed

string myStringAlternateKey = "123";
Entity contact = new Entity("contact", new Guid("4C6D87A9-C7E3-E411-80E6-
C4346BACBE48"));
    // Link a contact to a parent account using Alternate Key
    contact["parentcustomerid"] = new EntityReference("account", "mag_zendeskid",
    myStringAlternateKey);
    crmService.Update(contact);  

Here is a simple table showing when to use Alternate keys for each SDK operation:

Please note that Alternate Keys only work using SDK Messages, meaning this feature has not added any benefits to the UI experience for users.