Querying XML-based information in entities

<< Click to Display Table of Contents >>

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

Querying XML-based information in entities

Overview

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 getEntitiesAsString method, which is oriented to querying information in entities without having XPath navigation.

This entails that such method's use is optimal when working with Parameter type entities.

 

Example

In the following sample process, assume we have a Parameter entity called Vendor.

Such entity has the following records and we would want to fetch only those being VendorType = 1.

 

xmlhelper_ex1_vendors

 

This means exactly fetching: IBM, Apple and Microsoft.

 

Therefore and in order to obtain these records in an XML-compliant structure (instead of an array with objects), you may rely on the CEntityXmlHelper.getEntitiesAsString method and obtain an string with such information within.

Do this inside of an expression box, in a Bizagi business rule:

 

xmlhelper_ex1_rule

 

 

The overall expression shown in the image above is coded with the following:

var vendor_query = "<?xml version='1.0' encoding='utf-8'?><BizAgiWSParam><EntityData>"

+ "<EntityName>Vendor</EntityName><Filters><![CDATA[VendorType=1]]></Filters></EntityData></BizAgiWSParam>";

var vendor_schema = CHelper.getXSD("Vendor", "VendorDefaultSchema");

CHelper.trace("my_trace",vendor_schema);

var vendor_result = CEntityXmlHelper.getEntitiesAsString(vendor_query, vendor_schema);

CHelper.trace("my_trace",vendor_result);

 

Consider that the CEntityXmlHelper.getEntitiesAsString method receives 2 strings:

The first one named vendor_query in the example above, which is an XML-structured definition of the records you want to retrieve from Bizagi's data model.

This definition specifies the name of the Entity hosting those records (<EntityName>Vendor</EntityName>), and any filtering specification (<Filters><![CDATA[VendorType=1]]></Filters>) that ensures you get only those records you want to fetch.

The expected structure of this XML is the same one used for the getEntitiesAsString SOAP web method (when using Bizagi's web services API).

For more information about this expected structure and filtering options (for example, filter information in a string <![CDATA[VType='A']]>), refer to Get Entities.

 

The second one named vendor_schema in the example above, which is an XSD definition in a string, defining the fields you want to get for those applicable records.

How to use an XSD schema is described in the section below.

 

Similarly, the CEntityXmlHelper.getEntitiesAsString method will return an XML-structured string with the information of applicable records, as presented below for this specific example:

 

xmlhelper_ex1_formatted

 

The sample response, as shown above, is:

<?xml version="1.0" encoding="UTF-8"?>

<BizAgiWSResponse>

  <Entities>

     <Vendor key="1">

        <Code>V001</Code>

        <Name>IBM</Name>

        <VType>A</VType>

     </Vendor>

     <Vendor key="3">

        <Code>V003</Code>

        <Name>Apple</Name>

        <VType>A</VType>

     </Vendor>

     <Vendor key="4">

        <Code>V004</Code>

        <Name>Microsoft</Name>

        <VType>A</VType>

     </Vendor>

  </Entities>

</BizAgiWSResponse>

 

CHelper.trace() and CHelper.getXSD()

Notice in the example above, that though two other methods are being used optionally (both CHelper.trace and CHelper.getXSD) these will often can be used together with CEntityXmlHelper.getEntitiesAsString for other purposes:

CHelper.trace: Allows you to print out custom traces of values and responses in the execution of the rules.

The image below shows what the sample expression prints out:

 

xmlhelper_ex1_traces

 

For more information about the use of this tracing option, refer to Validating business rules.

 

CHelper.getXSD: Allows you to obtain a predefined schema for any entity, as configured in Bizagi Studio.

The image below shows the registered schema for the Vendor entity, explicitly named as VendorDefaultSchema (as referenced in the sample expression):

 

xmlhelper_ex1_schema

 

For more information about predefining schemas, refer to Bizagi's data model XML schemas.