Edit

Share via

Define alternate keys to reference records

  • Article

This topic applies to Dynamics 365 Customer Engagement (on-premises). For the Power Apps version of this topic, see: Define alternate keys using Power Apps portal

With alternate keys, you can assure an efficient and accurate way of integrating data from external systems. It’s especially important in cases when an external system doesn’t store the record IDs (GUIDs) that uniquely identify records. The alternate keys are not GUIDs and you can use them to uniquely identify records. You must give an alternate key a unique name. You can use one or more entity fields to define the key. For example, to identify an account record with an alternate key, you can use the account name and the account number. You can define alternate keys without writing code, or you can define them programmatically. Note that while you can define alternate keys in the user interface (UI), they can only be used programmatically, in code.

Some of the benefits of the alternate keys feature include:

  • Faster lookup of the records.

  • More robust bulk data operations.

  • Simplified programming with data imported from external systems without record IDs.

Important

  • You can't use a field that is in use by existing records as an alternate key. This will result in a duplicate records error.
  • Fields that have field level security enabled can’t be used as an alternate key. More information: Field level security to control access

To learn more about alternate keys programmability, see:
Define alternate keys for an entity
Use an alternate key to create a record

Define alternate keys

  1. Open solution explorer.
  2. Go to Components > Entities > Entity <X> > Keys.
  3. Select New.
  4. On the form, fill in the required fields (Display Name and Name) and then select and add the fields to the key.
  5. Save the key.

The example below uses the Account Number field in the alternate key definition.

Define alternate key for the account entity.

Note

You can define up to five different keys for an entity.

See also

Create and edit web resources
Define alternate keys for an entity (Developer Guide) Use an alternate key to create a record (Developer Guide)