Extended XPath 2.0 support

IBM BPM, V8.0.1, All platforms > Authoring services in Integration Designer > Developing monitor models > What are monitor models? > Expression support
Extended XPath 2.0 support

Business events can contain complex XML that might contain constructs such as repeating elements (sequences), information that is qualified by parent, child, or sibling nodes, or information whose location or interpretation depends on other content.
For processing such complex event content, Business Monitor provides the built-in functions.

Built-in functions
Function Purpose
wbm:serialize(...) Extract and convert XML document fragments from an inbound event into a single string.
wbm:evaluate(...) Evaluate XPath 2.0 expressions on the string representation of an XML document and produce a string result.
wbm:send-events(...) Create and send an outbound event for each item in a sequence. These events can be received as inbound events and used to create new monitoring contexts, one per item.
wbm:escape-special-characters(...) Replace all special characters so that the string representation of the XML can be displayed in a web browser (for example, replace < with <).

Each of these functions is described below. The sample expressions used in the descriptions assume that incoming order events contain content similar to the following example, which the orderPart event part definition refers to:
<ord:order xmlns:ord="http://www.example.org/order">
        <ord:orderNumber>F0004391</ord:orderNumber>
        <ord:orderEntryTimestamp>2009-01-17T17:56:25-05:00</ord:orderEntryTimestamp>
        <ord:customer>
            <ord:name>The Other Company</ord:name>
            <ord:shippingAddress>
                <ord:street>1000 Main Street</ord:street>
                <ord:city>Any Town</ord:city>
                <ord:state>XY</ord:state>
                <ord:zip>10001</ord:zip>
            </ord:shippingAddress>
        </ord:customer>
        <ord:items>
            <ord:item ord:sku="190123">
                <ord:description>my item</ord:description>
                <ord:due>2009-01-20-05:00</ord:due>
                <ord:quantity>32</ord:quantity>
                <ord:price>12.20</ord:price>
            </ord:item>
            <ord:item ord:sku="030234">
                <ord:description>your item</ord:description>
                <ord:due>2009-01-22-05:00</ord:due>
                <ord:quantity>12</ord:quantity>
                <ord:price>1604.98</ord:price>
            </ord:item>
            <ord:item ord:sku="030405">
                <ord:description>her item</ord:description>
                <ord:due>2009-01-23-05:00</ord:due>
                <ord:quantity>125</ord:quantity>
                <ord:price>199.25</ord:price>
            </ord:item>
        </ord:items>
        <ord:deliveryDates>
            <ord:date>2009-01-20-05:00</ord:date>
            <ord:date>2009-01-22-05:00</ord:date>
            <ord:date>2009-01-23-05:00</ord:date>
        </ord:deliveryDates>
        <ord:tax>2673.38</ord:tax>
        <ord:total>44556.41</ord:total>
    </ord:order>
The following namespace declarations are used on this page.
xmlns:wbm="http://www.ibm.com/xmlns/prod/websphere/monitoring/6.2.0/functions" 
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ord="http://www.example.org/order"
wbm:serialize(...)

To retrieve some or all of an event's XML content (the information in the xs:any slot) into a string, use the wbm:serialize(...) function.
wbm:serialize( $xml as xs:anyType? ) as xs:string? 

wbm:serialize( $xml as xs:anyType?, $delimiter as xs:string? ) as xs:string?
where:
$xml is a path into an incoming event and is subject to the constraints found in event parts:
wbm:serialize( newOrderEvent/orderPart/ord:customer/ord:shippingAddress )

wbm:serialize( newOrderEvent/orderPart/ord:items/ord:item/@ord:sku, ", " )
The first example might return a string representation of a shipping address. The second example might return a comma-separated list of SKU numbers of ordered items.
For another example using the wbm:serialize() and wbm:evaluate() functions, see "Adding metrics and key performance indicators (KPIs)."

wbm:evaluate(...)

To evaluate an XPath 2.0 expression on a serialized XML document, use the wbm:evaluate(...) function.
wbm:evaluate( $xml as xs:string?, $xpath as xs:string, $delimiter as xs:string ) as xs:string?

wbm:evaluate( $xml as xs:string?, $xpath as xs:string, $delimiter as xs:string, $var1 as xs:string? ) as xs:string?

wbm:evaluate( $xml as xs:string?, $xpath as xs:string, $delimiter as xs:string, $var1 as xs:string?, $var2 as xs:string? ) as xs:string?
...
where:

$xml is a serialized XML document.
$xpath is a valid XPath 2.0 expression (see http://www.w3.org/TR/xpath20/).
$delimiter is used as a delimiter when the evaluation of $xml results in two or more items whose string representations are concatenated to form the result.
$var1 to $var5 are optional arguments (at most, five can be passed) and are substituted for the XPath variables $var1 to $var5 in $xpath.

The wbm:evaluate(...) function evaluates an XPath 2.0 expression on a serialized XML document, and returns a serialized form of the result. If the first argument ( $xml) is empty, an empty sequence is returned.
If the XPath expression ( $xpath) contains any variables in the set $var1 to $var5 for which no argument is passed, an empty sequence is substituted for those variables. If values are passed for more variables than are found in the expression, the extra values are ignored. The $xpath argument must be a literal.
The following examples assume that newOrderEvent designates an inbound event subscription that is within scope for the model element defining the expression, and that orderPart is one of its event parts:
wbm:evaluate( wbm:serialize( newOrderEvent/orderPart/ord:items ), "fn:sum( ord:items/ord:item[ord:price > 1000]/ord:quantity )", "" )

wbm:evaluate( wbm:serialize( newOrderEvent/orderPart/ord:items ), "ord:items/ord:item[ord:due < xs:date($var1)]/@ord:sku", ", ", xs:string(earlyDate) )
Both examples use the wbm:serialize() function to extract a list of items from an order event. The first example then calculates the total number of items over $1 000. Because the result of this expression will always be a single number, the delimiter string is irrelevant.
The second example returns a comma-separated list of the SKU numbers of items whose due date is earlier than the date in the earlyDate metric. Notice that the xs:date value in that metric is converted to xs:string to be passed into the wbm:evaluate() function, and then back to xs:date to be used in a comparison.
For another example using the wbm:serialize() and wbm:evaluate() functions, see Adding metrics and key performance indicators (KPIs) in "Monitoring events from an SAP enterprise information system (EIS) without mediation."

Although the first argument of the wbm:evaluate() function must be a valid XML document, the XML fragments returned by the wbm:serialize() function may not always be valid XML documents. For this reason, the wbm:serialize() must return an XML string with a single root element.

wbm:send-events(...)

To send an outbound event for each item in a sequence, use the wbm:send-events(...) function.
wbm:send-events( $xml as xs:string?, $forEachItemIn as xs:string, $outboundXml as xs:string ) as xs:integer

wbm:send-events( $xml as xs:string?, $forEachItemIn as xs:string, $outboundXml as xs:string, $var1 as xs:string? ) as xs:integer

wbm:send-events( $xml as xs:string?, $forEachItemIn as xs:string, $outboundXml as xs:string, $var1 as xs:string?, $var2 as xs:string? ) as xs:integer
...
where:

$xml is a serialized XML document.
$forEachItemIn is an XPath expression that determines the sequence. It must be a valid XPath expression (see http://www.w3.org/TR/xpath20/).
$outboundXml is an XPath expression that is evaluated for each item in the sequence. The result becomes the content of a new outbound event that is then sent. $outboundXml must also be a valid XPath expression.
$var1 to $var5 are optional arguments (at most, five can be passed) that define the values for the XPath variables $var1 to $var5 in $forEachItemIn as well as $outboundXml.

The wbm:send-events(...) function sends outbound events for each item in a sequence, one event per item. The sequence is determined by evaluating $forEachItemIn on the XML document. For each item in the resulting sequence, $outboundXml is evaluated and its result becomes the content of a new outbound event, which is then sent. Typically, these events are returned to Business Monitor and used to create new monitoring contexts for each item. The events can be received anywhere: in a child context, in a parent context, back in the same context that produced them, or in a completely unrelated monitoring context. They are new incoming events that are processed in the same way as any other incoming event.
The built-in variable $currentItem can be used in the $outboundXml expression to refer to the current sequence item, and the built-in variable $currentItemPos can be used to refer to its position within the sequence. Sequence positions start with 1.
If the XPath expression contains any variables in the set $var1 to $var5 for which no argument is passed, an empty sequence is substituted for those variables. If values are passed for more variables than are found in the expression, the extra values are ignored.
The wbm:send-events(...) function returns the number of events that have been sent. If the first argument is empty, 0 is returned and no event is sent. The second and third argument must be literals.

The following example assumes that the xs:string metric allItems contains a list of items (possibly produced by a function like wbm:serialize( newOrderEvent/orderPart/ord:items )):
wbm:send-events( allItems, "ord:items/ord:item[ord:due < xs:date($var1)]", "$currentItem", xs:string(earlyDate) )
The expression passed as the second argument results in the set of all items whose due date is earlier than the date stored in the earlyDate metric. For each of those items, an outbound event is created and sent, with the current item as its content.

The following example assumes that the xs:string metric theOrder contains a string representation of an order document (possibly produced by a function like wbm:serialize( newOrderEvent/orderPart )):
wbm:send-events( theOrder, "ord:order/ord:items/ord:item", "$currentItem, ord:order/ord:deliveryDates/ord:date[$currentItemPos]" )
The expression passed as the second argument is evaluated and results in the sequence of all order items. For each of those items, an outbound event is created and sent. The event content is the item followed by the date that corresponds to the position of that item in a list of delivery dates.

wbm:escape-special-characters(...)

To replace special characters in serialized XML so that the resulting XML can be displayed in a web browser, use the wbm:escape-special-characters(...) function.
You can run this function on the serialized XML produced by wbm:serialize() or wbm:evaluate().
wbm:escape-special-characters( $xml as xs:string? ) as xs:string?

wbm:escape-special-characters( $xml as xs:string?, $spacesForTab as xs:integer? ) as xs:string?
where:

$xml is a serialized XML document.
$spacesForTab is the number of non-breaking spaces to substitute for a tab character. In the single-argument version of this function, the number is 4. In the two-argument version, if this argument is empty or negative, no replacement is made and tab characters remain unaffected.

The wbm:escape-special-characters(...) function performs the following character replacements.

Character replacements
Original After running wbm:escape-special-characters()
< <
> >
& &
" "
' '
<tab>      (unless set to some other number of spaces by the $spacesForTab argument)

The following examples format the shipping address for display in a web browser. The second example replaces each tab character with two spaces.
wbm:escape-special-characters( wbm:serialize( newOrderEvent/orderPart/ord:customer/ord:shippingAddress ) )

wbm:escape-special-characters( wbm:serialize( newOrderEvent/orderPart/ord:customer/ord:shippingAddress ), 2 )
Expression support

Function	Purpose
wbm:serialize(...)	Extract and convert XML document fragments from an inbound event into a single string.
wbm:evaluate(...)	Evaluate XPath 2.0 expressions on the string representation of an XML document and produce a string result.
wbm:send-events(...)	Create and send an outbound event for each item in a sequence. These events can be received as inbound events and used to create new monitoring contexts, one per item.
wbm:escape-special-characters(...)	Replace all special characters so that the string representation of the XML can be displayed in a web browser (for example, replace < with <).

Original	After running wbm:escape-special-characters()
<	<
>	>
&	&
"	"
'	'
<tab>	(unless set to some other number of spaces by the $spacesForTab argument)