saveEntityAsString

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Bizagi from external applications > Bizagi API > SOAP web services > Available SOAP web services > EntityManagerSOA Web methods >

saveEntityAsString

Overview

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

For further information these Work Portal options, please refer to Entities Administration.

 

 

note_pin

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

 

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="http://www.w3.org/2001/XMLSchema">

 <xs:element name="BizAgiWSParam">

         <xs:complexType>

                 <xs:sequence>

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

                                 <xs:complexType/>

                         </xs:element>

                 </xs:sequence>

         </xs:complexType>

 </xs:element>

</xs:schema>

 

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.

Note that when relying on business keys, it is strongly recommended to rely on that definition as held in Bizagi Studio, as described at Using business keys in XML files.

This means avoiding the explicit use of the business key clause directly in XMLs (as described above).

For further information about the expected structured for the business information contained in this Entities element, refer to Bizagi's data model XML schemas.

 

note_pin

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

 

SaveEntity_Image002

 

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:

SaveEntity_Image006

 

 

For further information about when to use each option, refer to Using business keys in XMLs.

 

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

 

note_pin

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

SaveEntity_Image003

 

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

 

 

Output

 

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="http://www.w3.org/2001/XMLSchema">

 <xs:element name="Entities">

         <xs:complexType/>

 </xs:element>

</xs:schema>

 

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:

SaveEntity_Image004

 

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

 

SaveEntity_Image005

 

Populating or synchronizing users

This method can be used to either populate users or synchronize them from an external repository and into Bizagi.

For more information and an example, refer to Synchronizing users via web.

 

Related Web methods

To update information for a Process instance (information in Master entities of a case), it is both recommended and more frequent to use other methods such as performActivityAsString, setEventAsString.

This is so because cases are likely to have active states in which end users are modifying information in pending Activities.

For further information about these other two methods, refer to the WorkflowEngineSOA Web service.

 

It is also possible that you may want to first retrieve the schema for the Entity to use in this method. In this scenario and to do this dynamically, use the getEntitySchemaStr or getEntitySchema methods.

For further information, refer to the getEntitySchemaStr article.