Updating XML-based information in cases (with scopes)

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Process wizard > Business Rules > Business Rules examples > XML Helper object >

Updating XML-based information in cases (with scopes)


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 saveCaseAsString method, which is oriented to inserting or updating information for any given case, while relying on what is stored in its scope.



In the following sample process, assume we have a process called SimplePurchaseRequest.

Such process uses the following data model:






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.

Note that you will need to make sure you use an schema for the process entity of the process to which you have an instance's case ID.





The generated schema includes any attributes you will consider to update or insert:




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 saveEntitiesAsString SOAP web method (when using Bizagi's web services API).

For more information about this expected structure and filtering options, refer to Save Entities.



Note that if you will be assigning information to the case, which are existing records, then you may rely on the definitions of business keys of the particular entities involved in order to avoid creating new records during the invocation.

For more information on how to reuse your existing business key definitions, refer to Using business keys in XMLs.


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:




If this checkbox is unmarked we strongly suggest the input parameter businessKey be set to false.


Now in order to save XML-compliant information into a given case, you may rely on the CEntityXmlHelper.saveCaseAsString 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 processentity_input = '<?xml version="1.0" encoding="utf-8"?><BizAgiWSParam><Entities>' +

'<SimplePurchaseRequest><WalletID>cc95807e-b896-4d0d-9299-73d111f8cee7</WalletID>' +

'<Requestedproduct><Code>TS</Code></Requestedproduct><Approved>0</Approved>' +

'<Vendors><Vendors><Applicable>0</Applicable><Vendor><Code>V001</Code><Name>IBM</Name></Vendor>' +

'</Vendors><Vendors><Applicable>0</Applicable><Vendor><Code>V003</Code><Name>Apple</Name></Vendor>' +

'</Vendors><Vendors><Applicable>1</Applicable><Vendor><Code>V004</Code><Name>Microsoft</Name></Vendor>' +

'</Vendors><Vendors><Applicable>1</Applicable><Vendor><Code>V002</Code><Name>Dell</Name></Vendor>' +



var processentity_result =  CEntityXmlHelper.saveCaseAsString(idCase, processentity_input, ignoreBusinessKey);




idCase: the ID of the case you want to consult. You can use Me.Case.Id.

processentity_input: XML with entities information

ignoreBusinessKey: boolean attribute that if sets to TRUE ignores business keys definitions in entities. We recommend leave it as FALSE.


Notice that because records in Vendor already exist (having information in the Code attribute using: V001, V002, V003 and V004 values as business keys), then such records will not be created but referenced for this case.

The complete information to update considers:

Assigning 4 existing Vendor records to a collection, having the 2 first ones set as Applicable=No and the other 2 with Applicable=Yes:


Setting information for the Wallet ID attribute:


Setting information for the approved attribute (being a boolean set to false)


Assigning an existing record requested product by its Code:



Though the CEntityXmlHelper.saveCaseAsString method does not return a response, updated information will be reflected immediately on the applicable current activity handling the scope (you may verify this by working on the processes via the Work Portal).





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.