The saveEntitiesAsString web method

<< Click to Display Table of Contents >>

Navigation:  » No topics above this level«

The saveEntitiesAsString web method


This Web method is used to update information in an Entity in Bizagi's data model (from an external application).

Updating information in an Entity involves: inserting new records, modifying existing ones, or disabling (logical deletion) existing records.


This method is especially used for Parameter Entities in Bizagi; given that such records (lists of values) are never modified from a Process instance.

This method receives a single input having the values to insert, modify or disable, for the attributes and relations in a start-point Entity.


For Parameter Entities, this is done in the same manner as it is done through Entities administration options at Bizagi Work Portal.

Take into account that in order to be able to administer values for Parameter Entities, the Entity itself needs to be defined as Manageable in that specific environment (Production or Development), in which this method is invoked.



The description provided in this article applies too for the saveEntity web method available in Bizagi .NET edition.

For the saveEntity method, the request and response XML's are of the native .NET XmlDocument type.

For the saveEntityAsString method the same XML structure is handled, but this parameter is sent as a string type.






Input Schema

The following shows a sample XML structure of information to send to Bizagi:


<?xml version="1.0"?>

<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="">

 <xs:element name="BizAgiWSParam">



                         <xs:element name="Entities" maxOccurs="1">








Input Parameters

BizAgiWSParam: Is the root node of the XML.

Entities: Depending on the intended use, it may contain the entities to be updated in the case of parameter entities; or hierarchy of the entity-relationship model, starting from the required Process entity, to update case data. The rest of the XML is created with the structure of the entity-relationship model.

Below are two examples, the first to update data in parameter entities and the second to show how to update data in the case.

An update can be differentiated from an insertion because the update requires the explicit specification of the primary key (or business key) of the record to be updated, e.g. key="value" (or businessKey="Attribute=value"); the insertions do not require this specification.



When disabling one specific record, note that you may use the built-in attribute called dsbl[Entity] which is included by Bizagi in every parameter entity. The example 1 shown below illustrates this possibility.


Input Example #1

In the following sample XML, three operations will be performed to the values of the parameter entity called City:


The first operation is the insertion of a new record.

The next operation is the modification of the Name value for the record with the primary key equal to two.

The last operation is the logical deletion or disabling of a record in the City Entity (valid for parameter entities).




For the first operation (insertion), note that the Entity has an attribute which references another Parameter Entity (in this example, the Entity called Country).

This being the case, we establish the relationship to an existing record in the Country Entity.

For this there are two options.


The first option is to use the XML attribute called businessKey as shown in the previous image.

This option applies when no business keys have been predefined at the Entity.


On the other hand, and if the Entity has already a business key predefined, the XML syntax to use to insert a new record should be as follows:




For the second operation (modification), we use the attribute called key.

Every Entity in Bizagi is created with an attribute set as the primary key for its records.

This attribute is named by Bizagi with the id prefix followed by the actual Entity's name (e.g. the attribute idCountry in the entity Country).



It is possible to use the businessKey attribute as a compound key. That is to say, a business key using more than 1 attribute for the primary key. For example: businessKey=" DocumentNumber='123456' and DocumentType='Passport'  ".



If this attribute's value is known beforehand, we may set it to update an existing record (as shown for the City called Bogotá D.C. in the first image)


For the third operation (logical deletion), we make use of an attribute which Bizagi automatically creates in Parameter Entities.

Such attribute is used to handle logical deletion of records (Bizagi marks those records which are disabled so that they are no longer used in new Process instances (i.e. not offered in drop-down lists), but keeps the record to maintain referential integrity for those existing instances).


In the SOA Layer, using this attribute to disable records is instantiated with the dsbl prefix followed by the actual Entity's name.

For example, the attribute shown in the first image which is called dsblCity, which applies to the City Entity.


Notice that in this example, we are disabling an existing record which has key = 3 (we also make use of the key attribute).



Input Example #2

In this example we illustrate how to update information of a given Process instance (case):



In this scenario, we use the idCase attribute (setting the DocumentNumber to 340 for a case with identifier = 9001).





Output Schema and Parameters

The following shows a sample XML structure of information returned by Bizagi:


<?xml version="1.0"?>

<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="">

 <xs:element name="Entities">





Its inner elements (Entities structure) will correspond to the schema for that given Entity.



Output Example

In the following samples XMLs, we illustrate the returned structured response from Bizagi SOA layer.

We can see a response of a successful invocation, which varies according to the Entity type involve (Master or Parameter).


For Parameter Entities, the involved keys (IDs) of inserted, modified or disabled records will be obtained as follows:



For Master Entities (for example, when modifying business information of a given case), the response XML will have a single empty node called Entities.