17 Jul’15

Dynamics CRMDefine alternate keys for an entity

With the release of Microsoft 2015 Update 1 Microsoft has released lots of exciting features, one of them is alternate key. Traditionally we use CRM primary field to identify the records.

  1. All Microsoft dynamics entities has unique identifier known as GUID. This GUID is the Primary key of particular record.
  2. When we want to integrate CRM with an external data base, we might be able to add a column to the external database tables to have a reference to the unique identifier in CRM.
  3. But in various cases, it is possibility that we are not allowed to change their database to add the reference key to store the GUID.
  4. In that case we are not able to track the records in the system.
  5. With alternate keys we can now define an attribute in a CRM entity to correspond to a unique identifier (or unique combination of columns) used by the external data store.

Features of Alternate Key

  1. This is used to identify the duplicate records. If there are records with the specified alternate key exists in system then it will throw an error.
  2. This avoid users to write plugin to identify the duplicate records. As duplicate detection rules allows the user to create the records even if it exists in the system.
  3. Alternate key can be combination of more than on attributes.
  4. With alternate keys, you can assure an efficient and accurate way of integrating data into Microsoft Dynamics CRM from external systems. It’s especially important in cases when an external system doesn’t store the CRM record IDs (GUIDs) that uniquely identify records
  5. Faster lookup of the records.
  6. More robust bulk data operations, especially in CRM Online


Create Alternate Key

To define alternate key please follow the steps:

  1. Go to Setting → Customization, open the default solution
  2. Select the entity for which you want define alternate key, in our case it is account.
  3. 1


  1. Select Keys and click new, which will open shown screen.
  2. 2

  3. You need to add column/columns which will be used as an alternate key.
  4. Save and publish.


  1. As you can see in the below screen shot error reported from two different rule. One from duplciate detection rule and another one from alternate key.
  2. The main difference between these two are below
    1. In case of duplicate detection users are allowed to create new record.
    2. But in case of alternate key users are not allowed to create the record.

Duplicate detection Rule


Alternate Key:


Attributes Valid for Alternate Key

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

Retrieve and delete alternate keys

If you need to retrieve or delete alternate keys, you can use the customization UI to do this, without writing any code. Although, the SDK provides the following two messages to programmatically retrieve and delete alternate keys.

Message request classDescription
RetrieveEntityKeyRequestRetrieves the specified alternate key.
DeleteEntityKeyRequestDeletes the specified alternate key

To retrieve all the keys for an entity, use the new Keys property of EntityMetadata Class. It gets an array of keys for an entity.

  Using alternate keys to Update

A valid Entity used for update operations includes a logical name of the entity and one of the following:

  1. A value for ID (primary key GUID value) (or)
  2. A KeyAttributeCollection with a valid set of attributes matching a defined key for the entity


using (_orgService = new OrganizationService(connectionTarget))
                    Entity account = new Entity("account", "accountnumber", "SUB0001");
                    account["telephone1"] = "9874563210";                      
                    account["fax"] = "1234579856";

Using alternate keys to create an Entity Reference


  1. Similarly we can use alternate key to set the entity reference field.
  2. We need to define the KeyAttributeCollection of the related entity whose lookup we want to set.
    1. We don’t need to set the GUID to relate record instead we need to set the alternate key of the related entity
    2. If the specified alternate key record does not present in the system it will through an error “A record with the specified key values does not exist in account entity”
                using (_orgService = new OrganizationService(connectionTarget))
                    KeyAttributeCollection keys = new KeyAttributeCollection();
                    keys.Add("accountnumber", "SUB0001");
                    Entity contactEntity = new Entity("contact");
                    contactEntity["lastname"] = "Last Name";
                    contactEntity["parentcustomerid"] = new EntityReference("account", keys);
                    contactEntity["fax"] = "9874563210";
                    CreateRequest req = new CreateRequest
                        Target = contactEntity


  1. For Microsoft Dynamics CRM Online organizations, this feature is available only if your organization has updated to Dynamics CRM Online 2015 Update 1. This feature is not available for Dynamics CRM (on-premises).
  2. You can define up to five different keys for an entity.
Written by

Team Member


Leave a Reply

Your email address will not be published. Required fields are marked *

Time limit is exhausted. Please reload the CAPTCHA.

Want to streamline your business processes?

  • This field is for validation purposes and should be left unchanged.

Recent Articles

  • Managing mailbox through Email Archiving

    20 March’ 2018

    Introduction: Email can fill your Outlook Inbox quickly – new messages, replies, and forwards. Before you know it, yo...

    Read more
  • Workaround to Report.SAVEASPDF in NAV 2018

    20 March’ 2018

    Objective: In NAV 2017 Emailing the PDF by running the report using Report.SAVEASPDF is now not allowed in NAV 2018. Th...

    Read more
  • Dynamics 365 Client Diagnostics

    15 March’ 2018

    Main cause of Performance Issues: Bandwidth and latency are the primary characteristics which affects the performance o...

    Read more
  • Closing Blind Shift in MPOS and CPOS in Dynamics 365 for Retail

    15 March’ 2018

    Manual For closing Blind shift in POS: Blind shifts terminate the currently ongoing shift and when logged in a new shif...

    Read more
  • Persistent Filters in the Power BI Service

    13 March’ 2018

    Introduction: The feature is finally release, and it is power BI has announced general availability of persistent filt...

    Read more