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).


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.



Consider that this definition needs to be done before deploying the entity into a production environment. This is so in order to maintain the data integrity of values in that entity (mainly because you should not be editing a business key definition once an entity in production already has values in it).



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:




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:






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.