Define 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. Select Keys and click new, which will open shown screen.



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

Alert

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.

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

Programmatically:

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

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
                    };
                    _orgService.Execute(req);
                }

Notes:

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.