Alternate Keys in Dynamics CRM 2015 (Update 01)

With update 01 for Dynamics CRM 2015 came various new feature – one of them is Alternate Keys. They have several advantages. Below I will explain how to define and use Alternate Keys and what are the advantages of using Alternate Keys.

How to define Alternate Keys: To define the alternate keys, go to Go to Settings > Customizations. Choose Customize the System > Components > Entities > Entity X > Keys.

Choose New. On the form, fill in the required fields (Display Name and Name) and then choose and add the fields to the key. Save the key. Below is the example where accountnumber is used as an Alternate Key.

Only upto 5 Keys can be defined as Alternate Keys

Currently only attributes with below mentioned data types can be defined as Alternate Keys. Rest are not supported. Hopefully with new updates other data types can be included.

1. Decimal Number
2. Whole Number
3. Single line of text

Attributes of only above mentioned data types will appear in the selection window.

Now you know how to define an Alternate Key. Now, lets see what are the advantages of using Alternate Keys.

Advantages of using Alternate Keys: 

• Synchronizing CRM with other system –

Before Alternate Keys were defined developers use to either create an attribute on the Entity in CRM to store the primary key value of other system or create a column in the other system database to hold the Guid value from the CRM. This was done so that the link between the records can be maintained. With Alternate Keys now you don’t need this mechanism. Now, you can define Alternate Key which will be your other system’s primary key and the link will be maintained.

Also CRM makes sure that the Alternate Key values are uniquely defined in CRM. That means if we try to create a record with same alternate key value then CRM will throw error saying Duplicate Record.

• Duplicate check and maintaining uniqueness of the data –

Sometimes we want one attribute to be unique. We can define duplicate rule but users have the ability to bypass that rule. Well, if we define such attributes as Alternate Keys we do not need to configure duplicate rule and CRM will ensure that the value in that attribute is always unique. If one tries to create duplicate data then CRM will check for uniqueness and throw an error message saying the record is already defined in a particular X key cannot be defined again.

• Use in upsert –

As described in my earlier blog for Upsert Alternate Keys plays a vital role to define if the record will be updated or inserted. You can check the details in this blog.

Consuming Alternate Keys in SDK messages:

• Creating Entity record instance –

There are two ways you can define Entity record instance.

1. Using KeyAttributeCollection

// Use alternate key for product 
// Define the Alternate key which uniquely identifies the record 
KeyAttributeCollection productkeys = new KeyAttributeCollection(); 
productkeys.Add("sample_productcode", productCode); 

Entity productToCreate = new Entity("sample_product", productkeys);

2. Using Entity constructor

// Use alternate key for product 
// Define the Alternate key which uniquely identifies the record 

Entity productToCreate = new Entity("sample_product","sample_productcode",productCode);

Alternate Keys cannot be used to delete or retrieve a particular record. You need to use GUID for that purpose.

Also, the above defined constructor doesn’t work for Create request; you need to use usual constructor to define the entity. The above constructor is useful for UpsertRequest and for UpdateRequest

• Creating Entity Reference instance –

EntityReference can also be defined the way Entity is defined as described above.