New CRM SDK Feature - Alternate Keys

16 April 2015

Daniel Cai

The latest Microsoft Dynamics CRM 2015 Update 1 release (v7.1) introduces a number of platform enhancements. Alternate Key is one of the coolest features available in this release. The primary benefit of this feature is to provide an alternative way to identify a CRM record.

Traditionally we use CRM entity's primary key field to identify a CRM record, which stores GUID values. This becomes a challenge when we try to integrate CRM data with third-party database or application systems, which might use some natural keys to identify a record. With the introduction of the Alternate Key feature in CRM 2015 Spring release, it makes our job much easier when writing data integration code.

Create CRM Alternate Keys using CRM UI

To create an alternate key in CRM UI, you would navigate to Settings - Customizations, and choose Customize the System.

Then you will be able to create new alternate keys under the specific entity's Keys section.

You will then be able to define the Alternate Key.

You would need to give a name in order to identify the key. There is a Display Name, and there is a logical Name which includes your customization prefix.

The alternate key could be made up by one or more CRM fields depending on your business requirement.

When creating an alternative key, CRM kicks off a system job that creates a db index at CRM database server side, the purpose of the db index is to enforce the uniqueness of key while offering an optimal query performance. Depending on the number of existing CRM records that you have for the concerned entity in CRM system, it could take a while to create the index. You can see the most recent status of the index creating job.

Note that only a small number of CRM fields are available to be selected as the key fields. Your selection is limited to the following three types of CRM fields.

String
Integer
Decimal

Unfortunately Date/Time, Lookup and OptionSet fields cannot be used as the key fields in this release, which could be something that you might want to use sometimes.

You can alternatively use SDK to create CRM Alternate Keys. You will be looking at CreateEntityKeyRequest message if you ever want to do so.

Use Alternate Key in Your Code

You can use CRM alternate key in the following two scenarios.

Update
Upsert (a new capability introduced in CRM 2015 Spring release, which will be further discussed in a following post)

The following code snippet demonstrates its use for Update action.

using (var service = new OrganizationService(crmConnection))
{
    // Use alternate key (accountnumber) field to identify an account record
    Entity account = new Entity("account", "accountnumber", "ACT-12345");

    // Set new credit limit;
    account["creditlimit"] = new Money(100000);

    // Entity reference using alternate key (emailaddress1) on contact entity
    account["primarycontactid"] = new EntityReference("contact", "emailaddress1", "[email protected]");

    UpdateRequest request = new UpdateRequest() { Target = account };
    UpdateResponse response = (UpdateResponse)service.Execute(request);
}

Note that the new SDK introduced new constructors for both Entity and EntityReference classes which you can utilize to reference the key that you have created for the concerned entity. An alternative way is to use KeyAttributes property to set values for each key field.

using (var service = new OrganizationService(crmConnection))
{
    // Use alternate key (accountnumber) field to identify an account record
    Entity account = new Entity("account")
    {
        KeyAttributes = new KeyAttributeCollection
        {
            {"accountnumber", "ACT-12345" }
        }
    };

    // Set new credit limit;
    account["creditlimit"] = new Money(100000);

    // Entity reference using alternate key (emailaddress1) on contact entity
    account["primarycontactid"] = new EntityReference("contact")
    {
        KeyAttributes = new KeyAttributeCollection
        {
            {"emailaddress1", "[email protected]"}
        }
    };

    UpdateRequest request = new UpdateRequest() { Target = account };
    UpdateResponse response = (UpdateResponse)service.Execute(request);
}

In the case that a CRM record cannot be found using the provided key value, you will receive the following error exception (where account is the entity name).

A record with the specified key values does not exist in account entity

In my next blog post, I will show you how to use CRM Alternate Key for UpsertRequest.

A couple of final notes before we conclude this blog post.

You need to have a Update 1 (v7.1) instance in order to utilize this new feature.
You would need to use CRM SDK 7.1.0-preview to compile the code.
For more details about the Alternate Key feature, please refer to the following SDK documentation links.
- Define alternate keys for an entity
- Use an alternate key to create a record

Hope you have liked this feature as much I do.

Read the full New SDK Capabilities Blog Series: