Keys concept in Dynamics CRM and its Usage

  • Traditionally, insert and update have always been separate requests in Dynamics CRM
  • The logic to identify whether to create a record or update a record is always to avoid such confusion the keys concept have been introduced.
  • Initially the keys concept has been introduced in the update spring release of CRM 2015.


The keys concept is not included in previous versions of CRM.

About Keys: 

Keys can be called as alternate unique identifier for an entity.

Let me provide a small example of it

As we know that each and every record of an entity has an unique identifier named as Primary Key(GUID)

This GUID is used to identify a record based on its uniqueness.

So the key will serves as an alternate key for the record in order to identify based on the uniqueness of field.

This keys is completely field related.

For each entity the maximum number of keys(alternate keys) cannot be more than 5.

The keys support only 3 data types in CRM

  • Single Line Text
  • Decimal Number
  • Whole Number


Usage of Keys in Dynamics CRM:

The keys concept will be useful in dynamics CRM when we use the UPsertRequest

So to get clarification about keys, we have to know about the UPSERT request and how it will be benefited to us

UPSERT Request:

The UPSERT request is the request which is of the combination of insert(create) and update in CRM

EX: suppose if we have some data which is to be placed in an entity in CRM. But we don’t know whether the data has already been created in CRM or not.

So in order to avoid those confusion state the UPSERT command will takes a prominent role.

  • It returns Boolean value of “response.Record Created” as either true or false
  • If it returns true then, a record is created in CRM with the specified data
  • Else it updates the existed record in that entity based on the keys we are provided.


Brief example about creation of keys and the usability of it in dynamics CRM

How to create keys:

clip_image001Go to settings –> customization

clip_image002Default solution Entity to find a new “Keys” tab added along with Forms and Fields tabs.


Fig: key creation in entity

  • As the initial stage is to create an alternate key in entity with respective data types that it supports
  • When you click on keys it opens a select new button.
  • Then it opens a page which shows you the list of available attributes of that entity that supports the keys.
  • Then select the field that you want to make the specific attribute as alternate key to that entity.
  • Now we have some specific data which is to be inserted in that entity
  • Since the point is we don’t know whether the data is already existed or not in that entity

Here the UPSERT request plays a significance role


// defines the Alternate key which uniquely identifies the record

KeyAttributeCollection testkeys = new KeyAttributeCollection();

testkeys .Add(“new_emailaddress”,””);

// create Test Custom entity object by specifying the entity logical name and Alternate key

Entity testCustomEntity = new Entity (“new_testcustomentity”, testkeys);

// specifying fields to update

testCustomEntity ["new_name"] = “SAMPLE TEST123″;

testCustomEntity ["new_houseallowances "] = 12.6;

testCustomEntity ["new_hobbies"] = new OptionSetValue(100000005);

// Creating Upsert request

UpsertRequest upreq = new UpsertRequest();

upreq.Target = testCustomEntity;

// Executing Upsert request

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

When we execute the above code, then the UPSERT request will checks whether the entity contains the specified key data

The request has a property named target which takes the entity object along with the key that was specified

If any record exists with the specified email address in the above code,, then the request returned response(RequestCreated) will returns to false

So the update request will be executed and the record is updated with the specified values

The output will be given below




So in this way the UPSERT request works in dynamics CRM

Benefits of Keys:

1) Create or update record in a single call

2) No duplication of data is allowed.i.e. If we create another record with the same email address that specified above it will arises the business process error that the attribute with data has already existed. Provide some unique value.

No Comments

Add a Comment

  1. (max length 2000)
  2. captcha refresh captcha