Key Values

Use Key values to perform update, delete, and upsert operations on a specific record without having to first perform a seek operation.

A primary key value or an alternate key value can be used as match criteria:

• Primary Key — A unique GUID value that is generated for all objects whenever a new record is added in Dynamics 365.
• Alternate Key — An optional, unique ID value you define in Dynamics 365. Any decimal, integer, or string field can be used to define either a simple alternate key, defined by a single field, or a complex alternate key, defined by multiple fields.

  An alternate key has both a display name that appears in the interface, and a key name that Dynamics 365 uses to identify the field. By default, the key name is the display name with a new_ prefix. For example, if you define the display name as MyKey, the key name assigned is new_MyKey.

  Note: Alternate keys are only available with Dynamics CRM 2015 Update 1 (v7.1) and later.

  When you define an alternate key, it is validated for uniqueness for existing records within the Dynamics 365 entity for which the alternate key is defined. The status of that validation determines the state of the alternate key, which can be any of the following:

  • Pending — Key value is being validated.
  • Active — Key value has been validated.
  • Inactive — Key value failed validation.

  Alternate key behavior differs between the update and delete operations, and the upsert operation:

  • Update or Delete — TIBCO Scribe® Insight uses an alternate key to more efficiently identify the record you want to update or delete. For example, if you define First Name and Title as a complex alternate key with an update or delete operation:
    • If you define the lookup links for this operation with just the alternate key fields, First Name and Title, your DTS uses the alternate key and performs the specified operation on all records where both those fields match the specified criteria, without having to perform a seek step first.
    • If you define the lookup links for this operation with only one of the alternate key fields, Title, your DTS:
      1. Performs a seek on the records and returns all the records matching the specified field value.
      2. Performs the update or delete operation on those returned records.
    • If you define the lookup links for this operation with the alternate key fields and another field, First Name, Title, and State, your DTS:
      1. Performs a seek on the records and returns all the records matching the combination of these three field values.
      2. Performs the update or delete operation on those returned records matching the above criteria.

    Only an active key can be used. Pending and inactive alternate keys are ignored, and the operation is performed as if no alternate key is defined, as in the third scenario in the example above.

  • Upsert — A new virtual field, vfAlternateKeyName, is provided to define the alternate key name that is used by that Dynamics 365 entity as the external ID/match criteria for the upsert operation. In addition, you must map all the fields defined in this alternate key in your DTS upsert step. Only an active key can be used. Pending and inactive alternate keys cause an error to occur.

    If you do not provide an alternate key in this virtual field, the primary key is used as the external ID/match criteria for the upsert operation.

    • If you map a non-existent, pending, or inactive key name to vfAlternateKeyName, the following error occurs: Cannot find the unknown_key_name alternate key.
    • If you provide an existing key name to vfAlternateKeyName, but only map part of the alternate key, the following error occurs: Value required for field alt_key_name to satisfy the specified alternate key.
    • If you provide an existing key name to vfAlternateKeyName and also map a primary key, the following error occurs: Cannot specify both a primary key and a vfAlternateKeyName value on an upsert operation.

See Also

Using The Adapter Objects