CRM Online 2015 Update 1 – Alternate Keys

Very often in CRM implementations, we find ourselves writing plugins to validate the unicity of records and prevent the creation of duplicates. One example is having contacts uniquely identified by an email address. That can be useful for user login from portals (unique emails in CRM), or when integrated systems need to connect to CRM and perform operations on existing records (no need to synchronize the CRM ID, use an existing alternate identifier to access your data).

The Dynamics CRM Online 2015 Update 1 brings a new and exciting functionality to handle this type of scenario very easily: Alternate Keys.

Alternate keys enable data integration in an efficient manner. Users can now define an attribute in a Microsoft Dynamics CRM entity to correspond to a unique identifier (or combination of columns) used by an external data store. Use this alternate key to uniquely identify a record in CRM in place of the primary key. This feature enhances the developer and customer experience by:

  • Reducing roundtrips to look up record IDs from other unique columns.
  • Increasing overall throughput of bulk data processes, especially with CRM Online.
  • Simplifying programming from external systems without CRM record IDs.

How to Define an Alternate key?

  1. Navigate to the Customization area and expand the target entity
  2. Select “Keys”
  3. Click New to define a new key

  1. Define a name for your key
  2. Select the attribute(s) that define your key from the “Available Attributes” and add them to the “Selected Attributes” columns
  3. Click OK

Once this is completed, CRM will create an asynchronous system job that will create the database index to enforce uniqueness and optimize lookup performance. The process can be lengthy if there are lots of existing records in the table for which the new key is created. The possible statuses the after creating an alternate key are the following:

  • Pending (waiting for the asynchronous job to start)
  • In Progress (system job – and SQL job – running)
  • Active
  • Failed

It’s worth noting that if there is existing data that violates the uniqueness defined by the new key, the job will fail and the key will not be activated. Looking at the asynchronous job will give you details of the failure as shown in the screenshot below.

This is great because it forces an initial cleanup of your system data before you can use existing fields as alternate keys.

Now that you’ve created an alternate key, you can run a quick test to validate that the new unique key is being enforced by the system. To that, simply create two records with the same key (in my case, 2 contacts with the same email address). You will get “Duplicate Record” error message as shown below.

So how about code? What can I do from a coding perspective?

The process of creating, retrieving and deleting Alternate Keys can be done using the API. Read more about the new SDK requests that allow to manage the alternate keys on MSDN.

It only makes sense that we can now create instances of Entities and EntityReference classes using alternate keys. You can read more on this on MSDN. Here are the new constructors for the Entity and EntityReference tables:

public Entity (string logicalName, Guid id) {…}
public Entity (string logicalName, string keyName, object keyValue) {…}
public Entity (string logicalName, KeyAttributeCollection keyAttributes) {…}
public EntityReference(string logicalName, Guid id) {…}
public EntityReference(string logicalName, string keyName, object keyValue) {…}
public EntityReference(string logicalName, KeyAttributeCollection keyAttributeCollection) {…}

This is a very exciting feature. Hopefully, it will soon make it to the On-Premise version of Dynamics CRM so we can all benefit from it!


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s