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 built-in functions.

Table 1. 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(...)`	This function works with the Common Event Infrastructure (CEI). 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.
`send-events(...)`	This function works with the Dynamic Event Framework. 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 Table 2: Inbound event paths referencing event content.
$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.

The wbm:serialize(...) function retrieves XML fragments from incoming events, serializes them, and returns them as one string. The first version of the function is equivalent to the second version with an empty delimiter string. The function returns an empty sequence only if the evaluation of $xml results in an empty sequence.

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: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.

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 EIS scenario: Adding metrics and key performance indicators (KPIs) in "Monitoring events from an SAP enterprise information system (EIS) without mediation."

Note: Although the first argument of the wbm:evaluate() function must be a valid XML document, the XML fragments returned by the wbm:serialize() function might 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 using CEI, 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.

`send-events(...)`

To send outbound events using the Dynamic Event Framework, use the send-events(...) function in the monitor model.

To use this function, copy the BusinessMonitorFunctions855.jar file to a monitor model project in IBM® Integration Designer.

Locate the BusinessMonitorFunctions855.jar file in install_root/scripts.wbm/xpath-ext.
Add the UDF JAR file to a monitor model project in Integration Designer. See Managing user-defined functions.
Important: When the JAR file is added to a monitor model project, an error is noted on the External Function Libraries panel. The end of the error message indicates that a required class com.ibm.bpm.def.spi.EventPointData was not found. Ignore this error. Do not add the com.ibm.bpm.def.jar file to the class path in an attempt to resolve the error. Making this addition to the class path prevent a monitor model from being generated.

The following example shows how to use the send-events function:

your prefix:send-events(wbm:serialize(IB_DEF_OrderReceived/RootData), "xmlns:order='http://VinnysPizza/pizzaOrder.xsd' order:Order/order:lineItems","$currentItem")

where:

The first argument is a serialized XML document (wbm:serialize(IB_DEF_OrderReceived/RootData in the example).
The second argument determines the sequence of outbound events that are emitted ("xmlns:order='http://VinnysPizza/pizzaOrder.xsd' order:Order/order:lineItems" in the example). Single quotes are required around namespace declarations (such as xmlns:order). Multiple namespace declarations can be used as long as they are delimited by spaces. The order:Order/order:lineItems portion of the argument specifies the location in the XSD structure for the outbound event content.
The third argument is an XPath expression that is evaluated for each item in the sequence and sets the content of the outbound event.

Outbound events sent by the send-events function are sent with the following event point keys. These event point keys are auto-generated and cannot be changed.

Application Name: The monitor model ID
Version: The monitor model version
Component type: MC (for "monitoring context")
Component name: Usually the monitoring context ID
Element type: Either INBOUND_EVENT, TRIGGER, or UNKNOWN
Element name: Usually the ID of the element
Nature: Either FIRE, ENTRY, or UNKNOWN

Inbound event definitions that use the events sent by the send-events function should specify an event point filter similar to the following example:

monitor model ID/*/*/*/*/*/*

The second part of the event point filter could include a monitor model version, but a wild card (*) is suggested instead. When model version information is included in an event point filter, remove any dash, colon, T, or Z characters. The form is 20150602110500 rather than 2015-06-02T11:05:00Z.

`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.

Table 2. 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 )