Title: XPath Extensions
Category: documentation

## Overview
Apache ODE extends the default XPath coverage provided by the [WS-BPEL](/ws-bpel-20.html) specification mostly by adding support for [XPath 2.0](http://www.w3.org/TR/xpath20/) and by offering a few utility extension functions to make some assignments easier.

<a name="XPathExtensions-XPath2.0"></a>
### XPath 2.0

To use XPath 2.0 in your processes just use the following _queryLanguage_ and _expressionLanguage_ attributes:


    queryLanguage="urn:oasis:names:tc:wsbpel:2.0:sublang:xpath2.0"
    expressionLanguage="urn:oasis:names:tc:wsbpel:2.0:sublang:xpath2.0"


If you want support at the process just add these attributes to your root _process_ element. If you want to stick with XPath 1.0 but want XPath 2.0 support for a specific assignment you can also define these attributes on an _assign_ element.

<a name="XPathExtensions-ExtensionFunctions"></a>
### Extension Functions

All extension functions are defined in the ODE extension namespace: http://www.apache.org/ode/type/extension. This namespace will be associated with the _ode_ prefix in the following examples.

<a name="XPathExtensions-insert-before"></a>
#### insert-before

This is a function that allows you to insert one or more siblings (specified by the $siblings argument in the signature below) before the first node of children (specified by the $children argument), all of whose nodes must have the same parent (specified by the $context argument).

<div class="caption">Insert Before</div>

    :::text
    ode:insert-before($context as node(), $children as node()*, $siblings as node()*) as node() 


By design, this function is non-updating in that it preserves the identity and properties of its arguments (i.e., they don't try to change the XML in-place). Instead, a modified copy of the context node is created, essentially giving it a new identity. Further, it returns a single R-value item, as opposed to a sequence. The example below illustrates how it may be used in the context of an assign activity:


    <assign>
      <copy>
        <from>ode:insert-before($parent, $parent/child::node[position()=last()], $siblings)</from>
        <to variable="parent"/>
      </copy>
    </assign> 


For those familiar with the [XQuery Update Facility](http://www.w3.org/TR/2008/CR-xquery-update-10-20080801/), the above example is semantically equivalent to the expression shown below:

<div class="caption">XQuery Equivalent</div>

    :::text
    insert nodes $siblings before $parent/child::node[position()=last()] 


<a name="XPathExtensions-insert-after"></a>
#### insert-after

This is a function that allows you to insert one or more siblings (specified by the $siblings argument in the signature below) after the last node of children (specified by the $children argument), all of whose nodes must have the same parent (specified by the $context argument).

<div class="caption">Insert After</div>

    :::text
    ode:insert-after($context as node(), $children as node()*, $siblings as node()*) as node() 


By design, this function is non-updating in that it preserves the identity and properties of its arguments (i.e., they don't try to change the XML in-place). Instead, a modified copy of the context node is created, essentially giving it a new identity. Further, it returns a single R-value item, as opposed to a sequence. The example below illustrates how it may be used in the context of an assign activity:


    <assign>
      <copy>
        <from>ode:insert-after($parent, $parent/child::node(), $siblings)</from>
        <to variable="parent"/>
      </copy>
    </assign> 


For those familiar with the [XQuery Update Facility](http://www.w3.org/TR/2008/CR-xquery-update-10-20080801/), the above example is semantically equivalent to the expression shown below:

<div class="caption">XQuery Equivalent</div>

    :::text
    insert nodes $siblings after $parent/child::node()



<a name="XPathExtensions-insert-as-first-into"></a>
#### insert-as-first-into

This is a function that allows you to insert the node(s) (specified by the $children argument in the signature below) as the first child(ren) of a given context node (specified by the $context argument).

<div class="caption">Insert As First Into</div>

    :::text
    ode:insert-as-first-into($context as node(), $children as node()*) as node() 


By design, this function is non-updating in that it preserves the identity and properties of its arguments (i.e., they don't try to change the XML in-place). Instead, a modified copy of the context node is created, essentially giving it a new identity. Further, it returns a single R-value item, as opposed to a sequence. The example below illustrates how it may be used in the context of an assign activity:


    <assign>
      <copy>
        <from>ode:insert-as-first-into($parent, $children)</from>
        <to variable="parent"/>
      </copy>
    </assign> 


For those familiar with the [XQuery Update Facility](http://www.w3.org/TR/2008/CR-xquery-update-10-20080801/), the above example is semantically equivalent to the expression shown below:

<div class="caption">XQuery Equivalent</div>

    :::text
    insert nodes $children as first into $parent 


<a name="XPathExtensions-insert-as-last-into"></a>
#### insert-as-last-into

This is a function that allows you to insert the node(s) (specified by the $children argument in the signature below) as the last child(ren) of a given context node (specified by the $context argument).

<div class="caption">Insert As Last Into</div>

    :::text
    ode:insert-as-last-into($context as node(), $children as node()*) as node() 


By design, this function is non-updating in that it preserves the identity and properties of its arguments (i.e., they don't try to change the XML in-place). Instead, a modified copy of the context node is created, essentially giving it a new identity. Further, it returns a single R-value item, as opposed to a sequence. The example below illustrates how it may be used in the context of an assign activity:


    <assign>
      <copy>
        <from>ode:insert-as-last-into($parent, $children)</from>
        <to variable="parent"/>
      </copy>
    </assign> 


For those familiar with the [XQuery Update Facility](http://www.w3.org/TR/2008/CR-xquery-update-10-20080801/), the above example is semantically equivalent to the expression shown below:

<div class="caption">XQuery Equivalent</div>

    :::text
    insert nodes $children as last into $parent 



<a name="XPathExtensions-delete"></a>
#### delete

This is a function that allows you to delete one or more node(s) (specified by the $children argument in the signature below) from its parent (specified by the $context argument).

<div class="caption">Delete</div>

    :::text
    ode:delete($context as node(), $children as node()*) as node() 


By design, this function is non-updating in that it preserves the identity and properties of its arguments (i.e., they don't try to change the XML in-place). Instead, a modified copy of the context node is created, essentially giving it a new identity. Further, it returns a single R-value item, as opposed to a sequence. The example below illustrates how it may be used in the context of an assign activity:


    <assign>
      <copy>
        <from>ode:delete($parent, $children)</from>
        <to variable="parent"/>
      </copy>
    </assign> 


For those familiar with the [XQuery Update Facility](http://www.w3.org/TR/2008/CR-xquery-update-10-20080801/), the above example is semantically equivalent to the expression shown below:

<div class="caption">XQuery Equivalent</div>

    :::text
    delete nodes $children 


<a name="XPathExtensions-rename"></a>
#### rename

This is a function that allows you to rename the context node (specified by the $context argument in the signature below) as per the given name (specified by $item, which is either a QName, Element or String).

<div class="caption">Rename</div>

    :::text
    ode:rename($context as node(), $name as item()) as node() 


By design, this function is non-updating in that it preserves the identity and properties of its arguments (i.e., they don't try to change the XML in-place). Instead, a modified copy of the context node is created, essentially giving it a new identity. Further, it returns a single R-value item, as opposed to a sequence. The example below illustrates how it may be used in the context of an assign activity:


    <assign>
      <copy>
        <from>ode:rename($person, fn:QName("http://www.example.com/example", "manager"))</from>
        <to variable="person"/>
      </copy>
    </assign> 


For those familiar with the [XQuery Update Facility](http://www.w3.org/TR/2008/CR-xquery-update-10-20080801/), the above example is semantically equivalent to the expression shown below:

<div class="caption">XQuery Equivalent</div>

    :::text
    rename $person as fn:QName("http://www.example.com/example", "manager")


<div class="alert alert-warning"><h4 class="alert-heading">Assign Assumptions</h4>
    The WS-BPEL requires that "for a copy operation to be valid, the data referred to by the from-spec and the to-spec MUST be of compatible types." Hence, make sure that when you rename an element, the new name refers to a type that is compatible with the target variable. In other words, it should be of a substitutable (essentially stronger) complex type.
</div>

<a name="XPathExtensions-split-to-elements"></a>
#### split-to-elements 

It's impossible to split a given string into a sequence of elements using assignments. The only possible alternative is XSL which is a lot of complexity for a very simple usage pattern. The _ode:splitToElements_ function splits a given string (that can be a variable reference) into several elements by using a specific separators. Here is an example:


    <assign>
      <from>ode:split-to-elements($authorizeMessage.credential/userList, ',', 'user')</from>
      <to>$authorizedUsers</to>
    </assign>


If the source element contains a list like "joe, paul, fred" the target variable will be assigned the sequence of elements:

    :::xml
    <user>joe</user>
    <user>paul</user>
    <user>fred</user>


Alternatively this function can take a fourth parameter that would be the namespace of the elements used to wrap the split strings:

    :::text
    ode:split-to-elements(stringToSplit, separator, targetElement, targetNamespace)


<div class="alert alert-info"><h4 class="alert-heading">Deprecated Name</h4>
    This function was formerly known as splitToElements, which may still be used, but is deprecated.
</div>

<a name="XPathExtensions-combine-url(base,relative)"></a>
#### combine-url(base, relative)

Takes the relative URL and combines it with the base URL to return a new absolute URL. If the relative parameter is an absolute URL, returns it instead.
This function is similar to [func-resolve-uri](http://www.w3.org/TR/2004/WD-xpath-functions-20040723/#func-resolve-uri). However the latter is available in XPath 2.0 only.

<a name="XPathExtensions-compose-url(template,\[name,value\](name,value\.html)*)"></a>
#### compose-url(template, \[name, value\]*)
<a name="XPathExtensions-compose-url(template,pairs)"></a>
#### compose-url(template, pairs)

Expands the template URL by substituting place holders in the template, for example, ('/order/\{id\}', 'id', 5) returns '/order/5'. Substitute values are either name/value pairs passed as separate parameters, or a node-set returning elements with name mapping to value. The functions applies proper encoding to the mapped values. Undefined variables are replaced with an empty string. This function returns an URL.
See also the [URI Template spec](http://bitworking.org/projects/URI-Templates/spec/draft-gregorio-uritemplate-03.html).

<a name="XPathExtensions-expand-template(template,\[name,value\](name,value\.html)*)"></a>
#### expand-template(template, \[name, value\]*)
<a name="XPathExtensions-expand-template(template,pairs)"></a>
#### expand-template(template, pairs)

Similar to `composeURL` but undefined variables are *_not_* replaced with an empty string. They are ignored. As a result with incomplete mapping may return a new URL template.

<a name="XPathExtensions-dom-to-string"></a>
#### dom-to-string

This is a function that serializes a DOM node (specified by the $node argument in the signature below) into a string.

<div class="caption">Dom To String</div>

    :::text
    ode:dom-to-string($node as node()) as xs:string


<a name="XPathExtensions-process-property"></a>
#### process-property

This is a function that allows you to retrieve the value of a property, defined in deploy.xml for the current process, with the given name (specified by the $name argument in the signature below, which is either a QName, String, Element or Single-Valued List).

<div class="caption">Process Property</div>

    :::text
    ode:process-property($name as item()) as node() 


Basically, this method gives you a way to reference properties, defined in deploy.xml for a given process, directly in the BPEL code for that process. The $name argument refers to any schema item that resolves to a QName. The return value is the child node of the property element with the given name.

The example below illustrates how it may be used in the context of an assign activity:


    <assign>
      <copy>
        <from>ode:process-property("auctionEpr")</from>
        <to partnerLink="partnerLink"/>
      </copy>
    </assign> 


where, the property called "epr" is defined in the corresponding deploy.xml as follows:


    <deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03"
                       xmlns:tns="http://ode/bpel/process">
       <process name="tns:negotiate">
           <property name="auctionEpr">
               <sref:service-ref
                    xmlns:sref=" http://docs.oasis-open.org/wsbpel/2.0/serviceref"
                    xmlns:addr="http://example.com/addressing"
                    xmlns:as="http://example.com/auction/wsdl/auctionService/">
                    <addr:EndpointReference>
                        <addr:Address>http://example.com/auction/RegistrationService&lt;/addr:Address>
                        <addr:ServiceName>as:RegistrationService</addr:ServiceName>
                    </addr:EndpointReference>
                </sref:service-ref>
            </property>...
        </process>
    </deploy>


<div class="alert alert-info"><h4 class="alert-heading">Release Information</h4>
    This function will be available in the 1.3 or higher version of ODE.
</div>

<a name="XPathExtensions-PredefinedProcessProperties"></a>
#### Predefined Process Properties

<a name="XPathExtensions-Localhostinfo(nameandIPaddress)"></a>
##### Localhost info (name and IP address)


    <bpws:assign>
      <bpws:copy>
        <bpws:from>ode:process-property('ode.localhost.name')</bpws:from>
        <bpws:to>$output.payload</bpws:to>
      </bpws:copy>
    </bpws:assign>
    
    <bpws:assign>
      <bpws:copy>
        <bpws:from>ode:process-property('ode.localhost.address')</bpws:from>
        <bpws:to>$output.payload</bpws:to>
      </bpws:copy>
    </bpws:assign>


<a name="XPathExtensions-ExtensionVariables"></a>
### Extension Variables

<a name="XPathExtensions-InstanceId"></a>
#### Instance Id

    :::text
    $ode:pid


<a name="XPathExtensions-ProcessQName"></a>
#### Process QName

    :::text
    $ode:processQName


<a name="XPathExtensions-CurrentEventDateTime"></a>
#### CurrentEventDateTime
This is equivalent to current-dateTime() XPath function, which works with instance replayer. 

    :::text
    $ode:currentEventDateTime


<div class="alert alert-info"><h4 class="alert-heading">Release Information</h4>
    1.3.4 or higher
</div>