Overview
When using the Web services of Bizagi API (SOA Layer) from an external application, you may want to rely on unique codes to make sure that both Bizagi and your external application are talking about a given, same specific record.
Unique codes are managed by Bizagi through the business keys concept; and through it, you may link new information to an existing record in Bizagi or update these values when invoking Bizagi API as well.
It is a best practice to predefine business keys for those entities of your data model in which this concept is applicable.
To view more information on how to do this for your entities, refer to Business keys.
How to reference existing records
When having predefined business keys for your entities (as recommended and shown above), you do not need to worry about whether a record already exists or not, and you may send the information within the XML so that it uses such definition to link to that particular record if it does exist.
For this, you would only need to make sure you include all the attributes of your entity which define the business key, as elements in your data model's XML.
In the following example, we part from having already defined DocumentNumber and DocumentType as the business keys for the Customer entity.
Data will be updated for that customer having Document type=1 AND Document number=123456789.
Only if that customer does not exist, then a new record will be created with the information supplied:
Alternative for entities without a predefined business key
There is an alternative when no predefined business keys have been set at a given entity (or can't be set in an existing production environment): you may choose to include the businessKey clause as an XML attribute.
The syntax to use this attribute is as follows:
<[MyEntity] businessKey="[MyBusinessKeyAttribute]=[BusinessKeyValue]">
</[MyEntity]>
Consider:
•[MyEntity]: Is the exact name of the entity does not have a predefined business key.
•[MyBusinessKeyAttribute]: Is the exact name of the attribute which should be the business key.
•[BusinessKeyValue]: Has the value that uniquely identifies the given record. Keep in mind that it should include quotes if referencing a string-type attribute.
•When having a compound businessKey definition, use AND to separate attributes. For example:
businessKey="[MyBusinessKeyAttribute1]=[BusinessKeyValue1] AND [MyBusinessKeyAttribute2]=[BusinessKeyValue2]"
Keep in mind that you may not update information directly held in attributes which make part of the business key.
|
There are two ways when using businesskeys :
•Using it as an attribute of a tag: <Applicant businessKey="DocumentNumber = '123456'">
•Or using it as an individual tag: <DocumentNumber>123456</DocumentNumber>
Be aware that can never use both at the same time. |
Important
Consider these facts when using such type of XMLs:
1. For parameter type entities, you may not update records nor create new ones parting from a business key definition.
2. You should NOT use both definitions simultaneously (the definition at the entity along with a businessKey clause at the XML), and recall that predefining business keys for entities through Bizagi Studio is the recommended practice.
Predefined business keys on entities help you work with information controlled within the business itself (such as: codes, series numbers, numbers of identification, etc), and avoid using surrogate keys which are mainly for Bizagi internal purposes).
Last Updated 1/6/2022 5:12:07 PM