The XML Helper object is part of Bizagi's business rules API, and it provides data access for your processes when working with XML-structured information, as described at XML Helper object.
This section illustrates an example on how to use one of the methods featured by this object, the saveEntityAsString method, which is oriented to inserting or updating information directly in entities without having XPath navigation.
This entails that such method's use is optimal when working with Parameter type entities.
In the following sample process, assume we have a Parameter entity called Vendor.
Such entity has the following records and we would want to add one new record and update an existing one.
This means exactly adding Samsung, and updating the name for Cisco to Cisco Systems.
To do this, it you should first look up the definition of the expected XML structure of your entity, by relying on the schema definitions created in Bizagi Studio:
For more information about predefining schemas, refer to Bizagi's data model XML schemas.
You may rely on the XSD schema definition to generate an XML having the information while ensuring it is compliant, by relying on many available free services in the internet such as http://xsd2xml.com/.
However, consider that this is just a portion of what you need to send inside of the XML-structured string.
Wrap the previous portion of the Vendor XML content inside a <BizAgiWSParam> root element having an <Entities> sub-element inside:
<?xml version="1.0" encoding="utf-8"?><BizAgiWSParam><Entities>...</Entities></BizAgiWSParam>
This will make sure that you send out an input which complies to the same one used for the saveEntityAsString SOAP web method (when using Bizagi's web services API).
For more information about this expected structure and filtering options, refer to Save Entities.
Given that we will be updating one record in this entity, we will need to make sure that business keys definitions are set for that entity.
In other words, having defined in Bizagi Studio which attribute or attributes make up a unique constraint for each of the records.
In this example, Vendor records are identified uniquely by their Code:
And for these records to be inserted and updated in the way shown in this section, it is advisable to unmark the checkbox in Bizagi Studio's configuration that enforces the use of business keys as a clause in XMLs:
Now in order to save XML-compliant information into a given entity, you may rely on the CEntityXmlHelper.saveEntityAsString method.
Do this inside of an expression box, in a Bizagi business rule:
The overall expression shown in the image above is coded with the following:
var vendor_input = '<?xml version="1.0" encoding="utf-8"?><BizAgiWSParam><Entities><Vendor><Code>V006</Code>'
+ '<Vendor businessKey="Code=\'V005\'"><Code>V005</Code><Name>Cisco Systems</Name>'
var vendor_result = CEntityXmlHelper.saveEntityAsString(vendor_input);
Notice that because a Vendor with Code V005 already exists and the Code attribute is that entity's definition of its business key, then such record will have its information updated (only what has been sent, which is the Name portion of information).
The CEntityXmlHelper.getEntitiesAsString method will return an XML-structured string with information having the IDs of newly created records or updated records, as presented below for this specific example:
The sample response, as shown above, is:
<?xml version="1.0" encoding="utf-8"?>
Notice in the example above, that CHelper.trace is being used as well (optionally), given that it will allow you to print out custom traces of values and responses in the execution of the rules.
For more information about the use of this tracing option, refer to Validating business rules.