Overview
This Web method is used to update information in an Entity in Bizagi's data model (from an external application). This method is available for Parameter Entities, Master Entities, and WFUSER entity.
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.
In the Production environment it can be used to affect entities managed in Production exclusively.
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.
•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.
|
•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. •When adding records with Business keys, send all the attributes which compound their key, even if one or more values are empty. By default, Bizagi will assign null to the empty values. |
Input Example
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 Method Input
<BizAgiWSParam>
<Entities>
<City>
<Name>Cartagena</Name>
<Code>4</Code>
<Country businessKey="Code='1'"/>
</City>
<City key="2">
<Name>Bogota D.C.</Name>
</City>
<City businessKey="Code='3'" >
<dsblCity>true</dsblCity>
</City>
</Entities>
</BizAgiWSParam>
SaveEntityAsString Method Input
<entityInfo>
<![CDATA[<BizAgiWSParam>
<Entities>
<City>
<Name>Cartagena</Name>
<Code>4</Code>
<Country businessKey="Code='1'"/>
</City>
<City key="2">
<Name>Bogota D.C.</Name>
</City>
<City businessKey="Code='3'" >
<dsblCity>true</dsblCity>
</City>
</Entities>
</BizAgiWSParam>]]>
</entityInfo>
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 Method Input - with business key predefined
<BizAgiWSParam>
<Entities>
<City>
<Name>Cartagena</Name>
<Code>4</Code>
<Country>
<Code>1</Code>
</Country>
</City>
</Entities>
</BizAgiWSParam>
SaveEntityAsString Method Input - with business key predefined
<entityInfo>
<![CDATA[<BizAgiWSParam>
<Entities>
<City>
<Name>Cartagena</Name>
<Code>4</Code>
<Country>
<Code>1</Code>
</Country>
</City>
</Entities>
</BizAgiWSParam>]]>
</entityInfo>
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.
|
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 Bogota 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 - Update information
In this example we illustrate how to update information of a given Process instance (case):
SaveEntity Method Input - Update information
<BizAgiWSParam>
<Entities idCase="1">
<Vacations>
<VacationRequest>
<Applicant>
<IdentificationNumber>159753</IdentificationNumber>
</Applicant>
</VacationRequest>
</Vacations>
</Entities>
</BizAgiWSParam>
SaveEntityAsString Method Input - Update information
<entityInfo>
<![CDATA[<BizAgiWSParam>
<Entities idCase="1">
<Vacations>
<VacationRequest>
<Applicant>
<IdentificationNumber>159753</IdentificationNumber>
</Applicant>
</VacationRequest>
</Vacations>
</Entities>
</BizAgiWSParam>]]>
</entityInfo>
In this scenario, we use the idCase attribute (setting the IdentificationNumber to 159753 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 involved (Master or Parameter).
For Parameter Entities, the involved keys (IDs) of inserted, modified or disabled records will be obtained as follows:
SaveEntity Method Output - Parameter Entities
SaveEntityAsString Method Output - Parameter Entities
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 Method Output - Master Entities
SaveEntityAsString Method Output - Master Entities
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 Get Entity Schema article.
Last Updated 1/6/2022 5:13:08 PM