Business keys

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Process wizard > Data Modeling >

Business keys


A Business key is the column or set of columns that uniquely identifies each row in an entity.

Through definitions of business keys, you guarantee that the information held in the key column (or columns) of each record will differentiate it from all the other records in the same entity (avoid duplicates).

Bizagi will not allow inserting a new row that has a same business key value than that one of an existing row.


For example, if we take a parameter Country having its business key set to use ISO country code information (i.e a ISO code column in it), then Bizagi validates that no two rows can have a "US" ISO code.

This definition ends up producing a unique constraint for information.


The image below illustrates another common example, having a Customer entity using a Document type along with the Document number as its business key:




Note that in this example, Jack White does not have a different business key and therefore, creating this record wouldn't be allowed (his combination of Document type and Document number is identical to John Smith's information).



By default, when creating entities, Bizagi will include a surrogate key which is used mainly for internal purposes.

However in addition to this key, it is a recommended practice that you explicitly define business keys for your entities as applicable (for instance, most likely in all parameter entities and only for a few master entities).

This is even more important if you plan on integrating the information of this entity with another system (so that these rely on common, unique codes).


Benefits of using business keys

Using business keys provide advantages related to data integrity, performance, and related to integration and security:

When creating a new record, you avoid data duplicates by having Bizagi automatically validate that a record with the same business key value does not already exist.

Business keys are automatically indexed in order optimize the searching of specific records, and this will represent a significant advantage when having a large number of records.

When integrating with other systems, you rely on unique codes for certainty that both Bizagi and the external system are referring to a same logical record.

When integrating with other systems, information you exchange with, and send over to other systems, would be in codes.

This is compliant to some industry-specific standards, such as HIPAA for the health sector, and it enforces the concept of security by obscurity (in addition to any other security measures on top), by not sending sensitive business information in an intuitive or easy-to-read fashion.


Other examples

Business keys definitions for your entities will allow you to easily avoid duplicate rows in many scenarios such as the below examples:

Customer entity set to use the person's Social Security number as business key, so that no other person (record) with the same Social Security number is allowed in that entity.

Product entity set to use a product's code as business key, so that no other product is created with the same product code.

A ProductPrice entity holding the history of prices of products, and set to use a combination of product id and start date, defining the price for that product on that given date. This way, there would be no two records of a same product having possible different prices for a same date.


What you need to do

You define business keys through Bizagi Studio by editing the properties of each entity in which you want to set a business key.



While Bizagi lets you select a related entity as an attribute of the business key, this is not a recommended practice, and it may cause problems in rules and policies.



To define a business key, open your project with Bizagi Studio and go to the Expert view.

In the Entities module, locate your entity and right-click it to select Advanced properties




Select the Business Key tab and tick the Enable Business Key checkbox to select from the list of attributes, the one (or ones) which will make up the business key definition. 

In the example below, DocumentType and DocumentNumber are chosen as a compound business key for the Customer entity:



Some external databases use a related entity as an attribute of the business key. This may cause problems with your rules and policies. We strongly suggest that you change this Business key definition before replicating data.




Note that if DocumentType is a reference attribute of another entity (a Document Type entity), then having a business key definition on that other entity would be expected as well (though not mandatory) in order to guarantee that each reference to Document Type refers to an actual different business record:




Virtualization and Replication considerations

If you need to virtualize or replicate an entity, it is mandatory that the entity has a business key. For virtualization or replication, business keys cannot be created when the attribute is a relationship to other entities, including nested relationships, for example, Parent entity - Child entity - grandchild entity.


You can see further information in considerations with primary and business keys.


Integration considerations

When having business keys defined for your entities consider the following aspect if you are using Bizagi's API web services (SOA layer) so that an external application can send out information to Bizagi:


If you are running your processes in a .NET platform, referencing records in Bizagi (to update or create unique ones) through the XML information sent via web services, needs to be done without including the businessKey clause as an XML attribute:




Notice that in the above example, we would be updating the Company of the Customer having Document type=1 AND Document number=123456789.



Since version 10.8 Business keys data types are taken as Bigint instead of Integer, ensuring a vast amount of keys are available for a very long usage of the product.