SaveEntity
From Business Process Management, BPM and Workflow Automation Wiki | BizAgi BPMS
<keywords content="keywords"> saveEntity, saveentity, saveEntityAsString, saveentityasstring, save Entity, save entity, SOA Layer, soa layer, EntityManagerSOA, entitymanagersoa, Entity Manager SOA, entity manager soa </keywords>
Contents |
saveEntity
With this method, included in the EntityManagerSOA web service, it is possible to save information into a Bizagi entity. This document applies also to the method saveEntityAsString.
Description
This method has two uses; it may be used to insert or update information of parameter entities in Bizagi and also to update information of cases. saveEntity receives and returns an XmlDocument, while saveEntityAsString receives and returns an XML, but in string format.
Input Data
The schema of the expected XML is as follows (copy it from here):
Parameter 1 (XmlDocument or String Type)
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 made up of 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.
Example 1
With the following example XML, three operations will be performed to the values of the parameter entity called City.
|
Alert: Take into account that in order to be able to administer values of parameter entities, the entity needs to be defined as manageable for the specific environment in which the saveEntity is invoked. View more information and recommendations about your parameter entities administration. <span lang="ES-CO" /> |
The first operation is the insertion of a new record. Notice that it is possible that the entity has an attribute related to another parameter entity (in this example Country), so to establish the relationship with an existing record of the other entity, it is easier to do it using the XML attribute businessKey. The value of this attribute should be the same as the one shown in the example, where the attribute Code in Country has a unique value for each record.
However, if the entity related through the businesskey has also defined a businesskey for itself, the xml has to be different as well. The xml to insert a new register in case both entities have businesskeys defined should be as follows:
The next operation is the modification of the value in Name for the record with the primary key equal to two. Here the XML attribute key is used. Every entity in Bizagi is created with an attribute set as primary key; this attribute is named as idEntityName (e.g. the attribute idCountry in the entity Country). If, for the record to be updated the value in this attribute is known, use it as the value for the XML attribute key. Otherwise, it is possible to use a businessKey; the businessKey should be used as in the first operation. It may also be a compound key, that is to say, a businessKey using two attributes for example: businessKey="DocumentNumber = '123456' and DocumentType='Passport'" used in the Person entity.
The last operation is the logical deletion or disabling of a record in the City entity. Every parameter entity in Bizagi is created with a Boolean attribute used to disable a record; this attribute is named as dsblEntityName (e.g. the attribute dsblCity in the entity City). Then, using the record’s key or businessKey, the record will be disabled if the corresponding attribute is set to true. The record will still exist in the database (so that old cases using this record are not damaged), but it will not be shown in the web application (as in combo renders).
Example 2
This example shows how to update information of a specific case with the method saveEntity:
The case number (idCase in the Application entity, not creation number) is indicated by adding the XML attribute idCase into the Entities element. Below this element, include the structure of the data model, starting with the attribute in the Application entity related to the desired Process entity, and continuing through the relationships to the data that is to be updated.
Output Data
When the saveEntity is used to update parameter entities, the response is an XML with the ids (keys) of the altered records. Here is an example of the returned XML for the request in Example 1:
On the other hand, if the method is used to modify data in a case, then, given that the execution is successful, the response XML will have a single empty node (Entities). This is the only indication that the operation was performed without errors.
Go to SOA Layer <comments />
