From Business Process Management, BPM and Workflow Automation Wiki | BizAgi BPMS

<keywords content="keywords"> keys, business, business keys, code, codes, unique, constraint, unique constraint, businesskey, business key </keywords>

Using business keys in Bizagi

Overview

When invoking web methods of Bizagi's SOA layer (to create cases, advance activities, update information into the data model, etc), it is frequent to want to find and update existing records.

To reference these records, we use business keys definitions for certain columns of entities which identify in an unique manner the entity's records.

Using business keys can be done through 2 approaches in Bizagi: by predefining in our data model (in the Development environment) which attributes make up the business keys in an entity, or by including an explicit reference of the "businessKey" attribute in the XML.

Predefining business keys

When business keys are predefined in Bizagi’s entities, a simpler XML can be built when invoking a web method of Bizagi's SOA Layer, for updating or inserting information.

Additionally and through this approach, it is possible to use compound keys in entities or even make queries of entities related to other entities which have their own business keys.

Predefinition of business keys is a best practice for our project's early phases and data model definition. It will also allow Bizagi to execute automatically validations when attempting to insert records with an existing value for its business key (to avoid duplicates).

Definition

To define business keys in Bizagi Studio. go to the modules view.

In the Entities module, locate the entity to which business keys are to be defined, right click on it and select Advanced properties.

The [Entity name] Advanced Properties window opens, in this case Client Advanced Properties.

Select the Business Key tab, check the Enable Business Key box and select from the list of attributes those that are to be business keys.

In this example TypeOfID and IdNumber are selected.

Using Predefined business keys

Having already defined the business keys of an entity, when sending an XML with information we do not need to worry about the two possible scenarios: if the record already exists or not.

Example

In the following example, we part from having defined the business keys for the Client entity. Data will be updated for a client in response to certain requests made by an external system.

If the client does not exist, then a new client will be created with the information supplied by the external system.

The XML starts off from the application entity and goes through the relationships until the entity to be updated is reached. Bizagi reads and understands from this XML that it has to update a Client with type of ID code 01 and ID number 1223334444.

If the record exists it is updated, if not it is created.

It is important to note that data from related entities that have been identified as business keys that it must exist only once in those entities, or else an error will be thrown.

In this case, the attribute TypeOfID relates to Client with IdentificationType, so it is understood that in the entity IdentificationType a record EXISTS with Code = 01.

Alternatives (use of "businessKey")

When no predefined business keys have been set in the entities advanced properties, you may choose to include the businessKey attribute explicitly in the sent XML.

Importance of business keys

Predefined business keys on entities arise from the need to work with information controlled by the business itself, such as: codes, series numbers, numbers of identification, etc (and not with the surrogate keys or Bizagi entities generated 'ids').

Business keys provide Bizagi more information about the data it uses, giving it more control over business information for validations and updates.

If for example, a client would only be searched by its IdNumber the following XML could be used:

Here the main concern is in duplicating the necessary information so that an update or insertion can be made (the business key and its value must be specified in the attribute businessKey).

This allows filtering and finding the record, and it will also need to be included as a child node in Client if an insertion is needed.

Otherwise in a future query the record might be duplicated.

Additional consideratio (One-to-Many Relationships)

To predefine business keys in one-to-one relationships is a very common situation, however that for one-to-many relationships this concept does not apply properly. If a record in a one-to-many relationship is required, then it is recommended to  use business keys and specify the businessKey attribute in the XML with the desired filter. For example, businessKey="IdNumber = '1223334444'". If in addition a filter by type of identification is required but the id is not known, if the process supports SCOPES, Bizagi can resolve the expression businessKey="IdNumber = '1223334444' and TypeOfID.Code = '01'".

Related Articles

• View information about Bizagi's SOA Layer.

• View an example of the join seach dialog use to input new records with business keys validations.

<comments />