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

 

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

};

_service.Execute(req);

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”.

2. Upsert an Account using Alternate key

KeyAttributeCollection acckeys = new KeyAttributeCollection();

acckeys.Add(“emailaddress1”, “someone3@example.com”);

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.