Querying 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 >

Querying XML-based information in cases (with scopes)

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 getCaseAsString method, which is oriented to querying information in any case, while relying on what is stored in its scope.

 

Example

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

Such process uses the following data model:

 

xmlhelper_02datamodel

 

 

Therefore and in order to obtain information which has already been inputted for a case of this process, in an XML-compliant structure, you may rely on the CEntityXmlHelper.getCaseAsString method and obtain an string with all such information within.

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

 

xmlhelper_ex2_rule

 

 

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

var app_schema = CHelper.getXSD("App", "SimplePurchaseRequest");

CHelper.trace("my_trace",app_schema);

var app_result = CEntityXmlHelper.getCaseAsString(Me.Case.Id, app_schema, null, "");

CHelper.trace("my_trace",app_result);

 

Consider that the CEntityXmlHelper.getCaseAsString method receives 4 inputs:

The first one which is the case identifier.

Note that you may use Me.Case.Id if you need information from the same case where you are executing the expression, but you may also retrieve information from a different case by ensuring you have its ID stored in a data model attribute.

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

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.

 

xmlhelper_03schema

 

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

The third one is an XSL (or XSLT) definition in a string (i.e an XML transformation file), defining how you want to transform the output so that it has different information (filtered) or different naming in its structure. This input is entirely optional and not depicted in the example below but detailed in a section at the end of this article.

The fouth one is an XPath Context definition in a string, defining where Bizagi will start to interpret the schema. This input is entirely optional and not depicted in the example below but detailed in a section at the end of this article.

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

 

xmlhelper_ex2_formatted

 

The sample response, as shown above, is:

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

<SimplePurchaseRequest key="852">

  <Requestdate>2017-10-05T16:43:27.557</Requestdate>

  <Requester entityName="WFUSER" key="6">

     <userName>tomh</userName>

     <fullName>Tom Hall</fullName>

     <domain>agilityCorp</domain>

     <idUser>6</idUser>

     <contactEmail>tomh@agilityCorp.com</contactEmail>

  </Requester>

  <Requestedproduct entityName="Requestedproduct" key="3">

     <Paytoaddress>1KfvVqDNo6fb8girHiNa1kEoH4ASD26s92</Paytoaddress>

     <Name>Translation services</Name>

     <Code>TS</Code>

     <PriceBitcoins>0.00113</PriceBitcoins>

     <Price>250.00</Price>

  </Requestedproduct>

  <Vendors>

     <Vendors key="1">

        <Applicable>1</Applicable>

        <Vendor entityName="Vendor" key="1">

           <Code>V001</Code>

           <Name>IBM</Name>

        </Vendor>

     </Vendors>

     <Vendors key="2">

        <Applicable>1</Applicable>

        <Vendor entityName="Vendor" key="3">

           <Code>V003</Code>

           <Name>Apple</Name>

        </Vendor>

     </Vendors>

     <Vendors key="3">

        <Applicable>0</Applicable>

        <Vendor entityName="Vendor" key="4">

           <Code>V004</Code>

           <Name>Microsoft</Name>

        </Vendor>

     </Vendors>

     <Vendors key="4">

        <Applicable>1</Applicable>

        <Vendor entityName="Vendor" key="2">

           <Code>V002</Code>

           <Name>Dell</Name>

        </Vendor>

     </Vendors>

  </Vendors>

</SimplePurchaseRequest>

 

note_pin

Obtaining information which is stored in Bizagi's scopes means that you will also get information that has not been persisted by the completion of an activity (is not visible from other points of the processes other than the actual activity).

 

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.getCaseAsString 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_ex2_trace

 

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 main process entity (SimplePurchaseRequest), explicitly named as SimplePurchaseRequest as well (as referenced in the sample expression):

 

xmlhelper_ex2_simpleprocess_schema

 

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

 

note_pin

Often, obtaining information from a case in an XML-structured string will allow you to use it for different requirements such as creating new cases based on other closed ones, or using that information to trigger a business event (i.e, set event) among others.

 

Using transformation files (XSL)

Consider the same example shown above, however this time, you may have the CEntityXmlHelper.getCaseAsString method apply an XLS transformation for you, so that the returned output has a different structure (i.e., possibly to have fewer information and formatted with different markup definitions such as HTML tags or any others). In this example we'll be adding an XPath Context parameter to let Bizagi know we are aiming to use SimplePurchaseRequest as the starting point of our schema.

 

The same example will be using now the third input parameter which is the following transformation file:

 

xmlhelper_ex2_XSL_file

 

Notice this sample transformation file will only make use of the information at Requestdate and the Code of the Requestedproduct, while renaming the tags for such detail:

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

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">

 <xsl:output method="xml" version="1.0" encoding="utf-8" indent="yes" />

 <xsl:template match="/">

 <xsl:for-each select = "SimplePurchaseRequest">

         <Root>

                 <xsl:for-each select = "Requestdate">

                         <Requested><xsl:value-of select = "."/></Requested>

                 </xsl:for-each>

                 <xsl:for-each select = "Requestedproduct/Code">

                         <Product><xsl:value-of select = "."/></Product>

                 </xsl:for-each>

         </Root>

 </xsl:for-each>

 </xsl:template>

</xsl:stylesheet>

 

This means that the rule now looks like this:

 

xmlhelper_ex2_XSL_rule

 

With the code of the expression shown in the image above having:

var processentity_schema = CHelper.getXSD("SimplePurchaseRequest", "SimplePurchaseRequest");
CHelper.trace("my_trace",processentity_schema);
var processentity_xsl = '<?xml version="1.0" encoding="utf-8"?>'
+ '<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">'
+ '<xsl:output method="xml" version="1.0" encoding="utf-8" indent="yes" /><xsl:template match="/">'
+ '<xsl:for-each select = "SimplePurchaseRequest"><Root><xsl:for-each select = "Requestdate"><Requested>'
+ '<xsl:value-of select = "."/></Requested></xsl:for-each><xsl:for-each select = "Requestedproduct/Code">'
+ '<Product><xsl:value-of select = "."/></Product></xsl:for-each></Root></xsl:for-each></xsl:template></xsl:stylesheet>';
var processentity_result =
CEntityXmlHelper.getCaseAsString(Me.Case.Id, processentity_schema, processentity_xsl, "SimplePurchaseRequest");
CHelper.trace("my_trace", processentity_result);

 

Therefore, this method using such transformation file yields the following output:

 

xmlhelper_ex2_XSL_output