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 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
Note:
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.
C#Copy
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.
