Excel Template Business Key

The business key column is identified by ''_opKey'' keyword and indicates that the column contains the unique business key of the entity.

It is the single most important concept in Master Data: the business key is what decides whether a row creates a new entity or updates an existing one.

Business key versus Data Hub id

Golden rule

Choose a business key that never changes, and guarantee its uniqueness yourself.

Insights does not enforce either. Change the key of an existing entity and the next upload will not rename it — it will create a second one alongside. Reuse a key across two entities and the engine picks one of them, non-deterministically.

Important

The business key differs from the Verity Insights Id

  • Verity Insights automatically sets the entity Id upon entity creation
    • it is immutable
    • it is guaranteed to be unique per entity type (site, source, ...)
    • it is never recycled for another entity of the same type, even if the original entity is deleted
  • the end user freely chooses the business key
    • it is mutable, meaning that Verity Insights does not prevent the modification of the business key of an existing entity
    • it does not guarantees that the business key is unique across entity types, it is upon the producer of the Master Data Upload File to ensure the uniqueness. If more than one entity have the same business key, only one entity (the first one in a non-deterministic way) will be considered by Verity Insights or MDE

Specifying ''_opKey'' alone is not enough, the MDE must know where to store/find the business key of the entity. You must associate the ''_opKey'' keyword with the entity property holding the business key using the ''+'' operator.

This tells MDE to use the source Name to store the business key of a source

Storing the business key in multiple entity properties (e.g. ''_opKey + _opSource.Name + _opSOurceForm.Form.Group.Field '' implies the following rules

  • the business key value is stored in all specified properties
  • if the list of properties contains multiples "system" properties (e.g. ''_opKey + _opSource.Name + _opSource.SerialNumber''), there is no deterministic way to know which property the MDE will use to retrieve an existing entity
  • if the list of properties contains multiples form properties and no system property (e.g. ''_opKey + _opSOurceForm.Form.Group.Field1 + _opSOurceForm.Form.Group.Field2''), there is no deterministic way to know which property the MDE will use to retrieve an existing entity
  • if the list of properties contains one "system" property and one or multiple form property (e.g. ''_opKey + _opSource.Name + _opSOurceForm.Form.Group.Field''), the MDE will always use the "system" property to retrieve an existing entity
Warning

Although the MDE will not complain, specifying a partial property to store the business key will not work as expected, the MDE will read the entire property the find an existing entity

DOCS 2026.08 REVIEWED 2026-08-28 Documentation changelog →