More ways to search a record in Dynamics CRM 2015 Update 1 – Alternate Keys

By | April 27, 2015


Prior to Microsoft Dynamic CRM 2015 Update 1 the only way to identify the records in CRM was the record guid. Now with the introduction of the Alternate Keys in Dynamics CRM 2015 Update 1 we can use alternate keys to uniquely identify a record in CRM in place of the primary key (GUID).

Features of Alternate Key:

  1. Provides a way to uniquely identify record.
  2. Alternate keys can be Composite keys i.e. more than one attributes can be selected to define the alternate key, thus providing a way to define a key as a combination of multiple attributes.
  3. Every Alternate Key you define creates an index behind the scene.
  4. Once you define alternate keys for an entity it acts as inbuilt duplicate detection rule i.e. it will throw an error as can be seen below if you will try to create a record with the same alternate key value which is already set for some another record.


Create Alternate Key

Let us go through the steps to create an Alternate Key.

Alternate Keys are associated with an Entity and therefore you need to create them as a part of entity customizations.

Navigate to Settings -> Customization -> Entity to find a new “Keys” tab added along with Forms and Fields tabs.




On the “Keys” tab click the “New” button to add new keys for the entity.

When you click on “New” you get a list of “Fields” for the entities from which you can choose which Fields to set as Alternate keys. Following screen shot shows a list of fields for Account entity from which we can select to create as Alternate Key.


Only attributes of following types can be added as Alternate Keys –

  1. Decimal Number
  2. Whole Number
  3. Single Line of Text

Note : Per entity you can define a maximum of 5 Alternate Keys only.

Alternate Keys Implementation through Code

Prior to Alternate keys, if we had to say add a new opportunity for a customer. We would like to first search for the customer and get the Guid so that we could assign that as the customer when creating an order. This meant we had to send out an explicit search request prior to the actual operation of creating an order.

With Alternate Keys such explicit calls are no longer required. Platform improvements made with the implementation of Alternate Keys actually take care of this internally.

Let’s check the code to see how we can use this

  1. Lets Create a new Contact and set the parentcustomerid using keys.

KeyAttributeCollection keys = new KeyAttributeCollection();

keys.Add(“accountnumber”, “ASH0011”);

Entity contactEntity = new Entity(“contact”);

contactEntity[“lastname”] = “Test last name 1”;

contactEntity[“parentcustomerid”] = new EntityReference(“account”, keys);

contactEntity[“fax”] = “1234579856”;

CreateRequest req = new CreateRequest


Target = contactEntity



This will automatically search for the “Account” from the keys and set it as “parentcustomerid” on the Contact created.

If the keys that are specified in the code do not exist then it will throw an error “A record with the specified key values does not exist in account entity”.

  1. Upsert an Account using Alternate key

KeyAttributeCollection acckeys = new KeyAttributeCollection();

acckeys.Add(“emailaddress1”, “”);

acckeys.Add(“telephone1”, “555-0152”);


Entity accountEntity = new Entity(“account”, acckeys);

accountEntity[“name”] = “Test Account name 1”;

accountEntity[“fax”] = “12345745678”;


UpsertRequest upreq = new UpsertRequest();

upreq.Target = accountEntity;

UpsertResponse resp = (UpsertResponse)_service.Execute(upreq);


When we execute the above code if an Account already exists with the Alternate Keys specified in the code then it will update the Account which has the matching Alternate keys and “RecordCreated” attribute is returned as “False” in Upsert response else it will create a new Account record and set the specified Alternate keys as the corresponding attributes values on Account so that we need not provide them separately and the “RecordCreated “ is returned as “true”. In above sample code you can find that we have created two Alternate keys (composite keys) i.e. “emailaddress1” and “telephone1” so if the values specified for both the keys i.e. “emailaddress1” and “telephone1” matches with another record than in this case it will find that matching record and update that existing record. If any one of the keys value matches than it will create a new record.


2 thoughts on “More ways to search a record in Dynamics CRM 2015 Update 1 – Alternate Keys

    1. Inogic

      It is not necessary to create Composite key explicitly in CRM because it is totally based on your requirement.

      For Example:

      1. Suppose you want to create unique Account records based on ‘Account Name’, then you need to add ‘Account Name’ column as a key which is nothing but an Alternate Key. So whenever new account gets created, it will check ‘Account Name’ and if it finds that the ‘Account Name’ already exists, then it will throw the duplicate error message and you won’t be allowed to create record..

      2. Regarding ‘Composite Key’, it is nothing but a key (i.e. Alternate Key) with the difference that here we can add more than one columns in a key so it is called ‘Composite Key’.

      For example:

      Suppose you want to create unique Account records based on ‘Phone Number’ and ‘Email Address’. In that case we need to create key which has both these columns explicitly added in it. So whenever new account gets created, it will check the ‘Phone Number’ and ‘Email Address’ while creating record and if the same ‘Phone Number’ and ‘Email Address’ exists, then it will throw the duplicate error message and you won’t be allowed to save.

      Hope this helps.


Comments are closed.