Create and Use Alternate key in Microsoft Dynamics 365

Alternate Keys in MS Dynamics 365

The global unique identifier (GUID) is used as the primary key for all entries in Dynamics 365 Customer Satisfaction. These are the main identifiers for everything involved. Customer Engagement’s unique identification may be used as a key for integration with other data sources by adding a column to the outside database tables. This provides a handy local pointer that can be used to quickly and easily access the customer engagement data. It is not always possible to update the external database, though.

alternate keys in microsoft dynamics 365

Alternate keys allow you to map a field in a customer experience entity to a column in an external database that serves as a unique identifier. Instead of the primary key, this secondary key may be used to describe a document in Customer Loyalty. You need the ability to specify which record properties serve as identifiers. After you’ve determined which entity properties are truly special, you can use the UI for customizing the database to define them as alternative keys. Information on how to define substitute keys in the database schema may be found here.

Alternate keys can be generated either programmatically or via the configuration settings. Create alternate keys to access CRM records for guidance on how to make changes with the available tools.

Creating an object of type Entity Key Metadata is the initial step in defining foreign keys in code (or using Entity Key Metadata Entity Type if working with the Web API). The important properties are stored in this class. Once the qualities of a key have been established, you may generate keys for an entity using Create Entity Key. The entity identifier and entity key metadata fields are used as inputs for this message to generate the key.

When generating replacement keys, keep in mind the following limitations

Valid attribute types in key definition:

There are following attributes includes in alternative key:

Attributes types:

  • Decimal attribute
  • Integer attribute
  • Data type attribute
  • Date time attribute
  • Pick list attributes
  • Lookup attributes

Display name of attributes:

  • Decimal number
  • Whole number
  • Display single line text
  • Data time
  • Lookup
  • Pickup list


Dynamics 365 Communication on-premises editions do not support Date Time, Lookup, or Pick list properties.

Create and update operations require proper attributes.

It is required that all attributes used as part of a key allow for both creation and updates.

Access Level

Field-level security cannot be applied to attributes. Neither logic nor inheritance can be used to determine a person’s characteristics. Most of the logical and inherited characteristics are set to read-only. Despite their writ ability, many of the characteristics of entities like Account and Contact that store addresses are conceptual and cannot be included in a key.

Size of a Valid Key

The system checks that the key’s overall size complies with the platform’s requirements, such as a limit of 900 bytes per key and 16 rows per key for a SQL-based index. An error will be shown if the key lengths don’t conform to the requirements.

Instances where a single entity might have many alternate key definitions
the maximum number of alternative key configurations for a single entity in a Consumer Engagement instance is 5.

Characters outside the norm in the key value

The get and patch operations will fail if the data contained in a field used in an alternate key contains any of the following characters: /, >, *, %, &,:,. This method is effective if you are solely concerned with ensuring uniqueness, but it is not recommended if you plan to use the keys for data integration purposes, in which case you should generate them on fields that will not contain such characters.

Relative and delete alternative key

The alternative keys can be retrieved or removed through the user interface for customization. The SDK, however, includes the subsequent two messages for retrieving and erasing alternate keys programmatically:

Message request class                                        Description

Retrieve entity key request                                 retrieved the specified alternate key

Message request class                                        description

Delete entity key request                                    deletes specified alternate key

Using the new Keys property of Entity Metadata, you may get a list of all the keys associated with an entity (Entity Metadata Entity Type or Entity Metadata class). It takes in an entity’s keys in array form.

Monitor index creation for alternate key:

Database indexes are used by alternate keys to enforce originality and enhance lookup efficiency. Index building might be time-consuming if there are a lot of preexisting records in a table. By delegating index construction to a background process, you can make the customization UI or solution import more reactive. The index creation asynchronous job can be accessed via the Entity Key Metadata. A sync Job variable (Entity Key Metadata Entity Type or Entity Key Metadata). If you want to know where the index creation task for a key stands, you can check its Entity Key Metadata .Entity KeyIndexStatus field.

Any of the below could describe the current status:

  • Failed
  • Pending
  • In progress
  • Active

If index creation fails while creating an alternate key using the API, you can investigate the specifics of the failure, fix the issues, and revive the key request with the Reactivate Entity Key method.
If an index generation job is in progress when the alternative key is deleted, the job will be aborted and the index will be removed.
Construction of Entity References with aliases

The new function Object () [native code] also allows you to construct the entity reference without a main ID and with only one key attribute.


public EntityReference(string logicalName, Guid id) {…}

public EntityReference(string logicalName, string keyName, object keyValue) {…}

public EntityReference(string logicalName, KeyAttributeCollection keyAttributeCollection) {…}

One that can be considered an entity A reference consists of the entity’s logical name and either the entity’s primary key GUID or a group of attributes that together form that key.

Other sources of information for message processing

Values passed in for lookup attributes via Entity Reference in Create Request and Update Request can now make use of Entity Reference using alternate keys set in Key Attributes to specify the associated record. Entity references of this type will be converted to their primary ID counterparts before the communications are handled.

Use of non-standard keys with restrictions

When using other keys, you must consider the following details and Potential catches:

If just one identifier is given, that one will be used as the primary. It will check the key attribute collection if one is not provided. An exception will be thrown if the key attribute collection is missing.

The ID attribute of the entity or entity reference is set to the provided value if the supplied Key Attribute Collection contains at least one attribute that is the main

key of the entity and the result is valid.

If the key characteristics are supplied, the system will try to match those attributes against the keys specified for the entity. There will be an error thrown if no match is found. If a match is found, the values entered into those attributes will be checked for accuracy. If correct, it will look up the record with those particular key values and insert that ID into the corresponding field of the entity reference.

An error will be generated if you attempt to use a set of attributes that is not declared as a unique key.

Marketing Department

Marketing Department

Stallions Solutions’ marketing team is responsible for branding and supporting business development & marketing efforts. We are composed of exceptional graphic designers, technical & creative content writers, and digital marketing specialists. Our content-producing approach is highly professional – from ideation to final article, all marketing experts play their role to generate an amazing piece of content. Our marketing team understands what our customers expect from the business and thus aims to meet those demands.





Recent Posts

Scroll to Top