Using the Expression Builder
Select from the Variables, Functions, and Operators pick lists to create an expression in the Expression/Condition text box.
You can select among the many function types to create an expression for Copy Operations, link transitions, and other BPEL constructs. See the procedure below for details on building an expression.
See also Selecting XPath or XQuery for Expression Building.
Examples
- •Expected Expressions for Conditions, Counters, and Other Values
- •Example XPath Expressions
- •Example XQuery Expressions
Functions
- •Boolean Functions
- •BPEL Functions
- •Node Set Functions
- •Number Functions
- •Process Developer Custom Functions: General
- •String Functions
See also the BPEL for People Functions in Process Developer Human Tasks Help
Customization
- •Custom Functions Overview
- •Writing XQuery Functions
- •Select Expression Language
For Copy Operations in the Assign activity as well as for links and other constructs, you can create XPath (or another selected language) expressions that result in a string, number, or Boolean.
For details, see the XPath 1.0 specification at http://www.w3.org/TR/xpath.
To build an expression:
- 1. Select an activity that uses expressions, such as the assign, wait, or on alarm branch of a pick activity.
- 2. In the Properties view for the activity, select the appropriate property. For example, in an assign activity, select Copy Operations, and select Expression as a Copy/From type to display the following dialog:
- 3. Select the variables, functions and operators from the three boxes to build an expression, following these tips:
- - Build expressions faster with shortcuts. See Using Content Assist.
- - Expand a variable to see and use the parts and properties. For detailed descriptions of variables, see Using Variables.
- - Select a variable, part, function, or operator and select Insert
- - For working with variable attachments, see Custom Functions for Manipulating Attachments.
- - Add your own custom functions, as described in Creating POJO and XQuery Custom Functions.
- 4. Select Evaluate to substitute a sample value for a variable part and simplify the expression to view its value.
Using Content Assist
Select from the Variables, Functions, and Operators pick lists to create an expression in the Expression/Condition text box.
Content assist is a shortcut for making selections from the variables and functions available for building an expression. Instead of expanding a variable to drill-down to a part to insert into the expression text box, you can select the part within the expression text box.
To use content assist:
- 1. In the builder (expression, query, or other), place your cursor in the expression text box, located below the Insert button.
- 2. To select a function, select Ctrl + spacebar. A list of functions appears that you can select from.
- 3. To select a variable, part or element, select Ctrl + spacebar as follows:
- a. If the cursor is after a $, a list of available variables appears, if applicable.
- b. If the cursor is after a period (.), and if the context is in an XPath expression, a list of valid part names appears, if applicable.
- c. If the cursor is after a slash (/), and if the context is in an XPath expression, a list of valid element names appears, if applicable.
BPEL Functions
This section describes the following functions:
bpel:doXslTransform(style-sheet-uri node-set)
Returns the result of an XSL transformation of a single element node set using the specified style sheet.
Parameters:
- •style-sheet-uri: URI for the XSL file.
- •node-set: XPath node set providing the source document for the transformation.
Example syntax:
bpel:doXslTransform("project:/myStylesheets/A2B.xsl", $A)
Optional parameters (must appear in pairs if specified)
- •string: XPath string parameter providing the qualified name of an XSLT parameter.
- •object: XPath object parameter providing the value for the named XSLT parameter.
Examples
The following examples show complex document transformation and iterative document construction.
Example 1. Complex Document Transformation.
A common pattern in a WS-BPEL process involves receiving an XML document from one service, converting it to a different schema to form a new request message, and sending the new request to another service. Such document conversion can be accomplished using XSLT via the bpel:doXslTransform function, as shown in the following example.
In the sequence, a service is invoked, and the result (foo:AElement) copied to variable A. The assign activity transforms the contents of variable A to bar:BElement, and copies the result to variable B. Variable B is used to invoke another service. The style sheet, A2B.xsl, contains the XSL rules for converting documents of schema foo:AElement to schema bar:BElement.
Example 2. Iterative Document Construction.
Suppose that a document is constructed by repeatedly calling a service and accumulating the result in a variable, as shown in the following example:
The optional parameters given in the doXslTransform call specify that the XSLT parameter named NewItem is set with the value of the process variable OutVar. To allow the XSLT style sheet access to this value, it contains a global (top-level) parameter with a name matching that given in the third parameter of the function call shown above.
<xsl:transform version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" ...>
<!-- NewItem variable set by WS-BPEL process;
defaults to empty item -->
<xsl:param name="NewItem">
<foo:itemElement />
</xsl:param>
...
</xsl:transform>
The style sheet contains a template that appends the value of global parameter NewItem (the value of OutVar from the process instance) to the existing list of items in the PO variable.
<!-- line 1 --> <xsl:template match="foo:itemElement">
<!-- line 2 --> <xsl:copy-of select="." />
<!-- line 3 --> <xsl:if test="position()=last()">
<!-- line 4 --> <xsl:copy-of select="$NewItem" />
<!-- line 5 --> </xsl:if>
<!-- line 6 --> </xsl:template>
This template copies all existing items in the source document (lines 1 & 2) and appends the contents of the XSLT parameter NewItem to the list of items (lines 3 & 4). It tests to see if the current node is at the end of the item list (line 3) and copies the result-tree fragment from the XSLT parameter NewItem to follow the last item (line 4).
If PO has a value of:
<foo:poElement>
<foo:itemElement>item 1</foo:itemElement>
</foo:poElement>
at the beginning of an iteration of the while loop and the invoke activity returns a value of <foo:itemElement>item 2</foo:itemElement>, evaluation of the from expression will result in a value of:
<foo:poElement>
<foo:itemElement>item 1</foo:itemElement>
<foo:itemElement>item 2</foo:itemElement>
</foo:poElement>
When the copy operation completes, it becomes the new value of the PO variable.
Adding an XSL Style Sheet to Process Server
A style sheet that you reference in a doXslTransform function is automatically recognized by Process Developer and is added to a BPR archive for deployment.
bpel:getVariableProperty(VariableName propertyName)
Returns property data from a selected variable in a BPEL process.
Parameters:
- •VariableName: The name of the variable to retrieve data from
- •propertyName: the name of the property in the variable that contains the data
Process Developer Custom Functions General
The following topics describe Process Developer custom functions:
abx:base64Encode(stringValue charSet )
Returns the Base64 encoded string.
Parameters:
- •stringValue: The string to be encoded
- •charSet: The optional named character set to use for encoding. The default is UTF-8.
abx:elementToXMLString(element)
Returns an XML string given an element.
abx:getAllHTTPHeaders(partnerLinkName)
Returns a map of HTTP header values from the last message received on the PartnerLink in the business process. Applies to any type of inbound HTTP request without regard to whether the payload is SOAP, XML, or JSON.
Parameter:
- •partnerLinkName: The name of the PartnerLink to retrieve data from
abx:getHTTPHeader(partnerLinkName headerName)
Returns the value of any HTTP header from the last message received on the PartnerLink in the business process. Applies to any type of inbound HTTP request without regard to whether the payload is SOAP, XML, or JSON.
Parameters:
- •partnerLinkName: The name of the PartnerLink to retrieve data from.
- •headerName: The name of the header
abx:getInboundSOAPHeader(partnerLinkName)
Returns SOAP message header block from the last message received on the PartnerLink in the business process.
Parameter:
- •partnerLinkName: The name of the partner link to retrieve data from
abx:getProcessId()
Returns the process Id of the currently executing or completed process on the Process Server.
abx:getProcessInitiator()
Returns the principal attached to the createInstance message or anonymous if there are no credentials or principal associated with the message.
abx:getProcessName()
Returns the process name (local part only) of the currently executing process.
abx:isVariableInitialized(variable)
Returns true if variable is initialized.
abx:resolveURN(string)
Returns the resolved location of the URN using the URN/URL mapping facility of the server. Takes a single string parameter as input. For example, abx:resolveURN('urn:localhost:AssessRisk')
abx:setProcessTitle(titleString)
Set the display title of an active process on the Active Processes page of the Process Console. Does not replace the process name.
abx:xmlStringToElement(string)
Returns the Element given an XML string.
Attachment Functions
These functions are described in Custom Functions for Manipulating Attachments.
Boolean Functions
You can use the following Boolean functions:
boolean(object)
The Boolean function converts its argument to a Boolean as follows:
- •A number is true if and only if it is neither positive or negative zero nor NaN
- •A node-set is true if and only if it is non-empty
- •A string is true if and only if its length is non-zero
Parameter:
- •object: An object of a type other than the four basic types is converted to a Boolean in a way that is dependent on that type.
not(boolean)
Returns true if its argument is false, and false otherwise.
true()
Returns true.
false()
Returns false.
lang(string)
The lang function returns true or false depending on whether the language of the context node as specified by xml:lang attributes is the same as or is a sub-language of the language specified by the argument string. The language of the context node is determined by the value of the xml:lang attribute on the context node, or, if the context node has no xml:lang attribute, by the value of the xml:lang attribute on the nearest ancestor of the context node that has an xml:lang attribute. If there is no such attribute, then lang returns false. If there is such an attribute, then lang returns true if the attribute value is equal to the argument ignoring case, or if there is some suffix starting with - such that the attribute value is equal to the argument ignoring that suffix of the attribute value and ignoring case.
Catalog Functions
These custom functions are capable of loading any resource out of the Process Server catalog and updating a resource in the catalog. The loaded resource is returned to the expression language as an XML document. For example, you can extract configuration information from process definition, such as alarms or endpoint references, and keep it in the catalog where it can be changed and shared across process definitions. The use of the catalog also enables a process to have different configuration information based on its deployment environment. For example, a development environment can have one type of configuration information while a production environment can have another. The configuration information is in XML format. Be sure to import the resource XML files into the project to make them available for simulation and for automatic export to a BPR archive. For details, see Importing WSDL, Schema, and Other Resources and Creating and Deploying a Business Process Archive Contribution.
abx:getCatalogResource(location)
Returns the document containing the resource content. The location is the string containing the catalog location URL. The example below returns the element or document that was stored using putCatalogResource(), by the location. You can use this function in a copy operation to assign the element back to a variable, for example.
If the request header uses application/json or the resources ends with .tojson (for example, /avccatalog/project:/path/mydoc.xml.tojson), you do not have to write a process to proxy the request if the endpoint is /avccatalog. Also, if the request header has application/json, you do not have to write a proxy if the endpoint is /catalog.
Example:
abx:getCatalogResource("project:/myProject/resources/resource.xml")
In a copy operation, an example of copying From this function (to a variable) is as follows. Note that the expression language is XQuery.
<ns1:catalogEntry xmlns:ns1='http://activevos/samples/catalog/functions'>
<ns1:catalogLocation>
<ns1:location>{data(
$requestOperation.catalogOp/
ns1:catalogLocation/ns1:location )
}</ns1:location>
<ns1:typeURI>{data( $requestOperation.catalogOp/
ns1:catalogLocation/ns1:typeURI )}</ns1:typeURI>
</ns1:catalogLocation>
<ns1:content>{abx:getCatalogResource( data(
$requestOperation.catalogOp/ns1:
catalogLocation/ns1:location))}</ns1:content>
</ns1:catalogEntry>
abx:putCatalogResource(location typeURI document)
Updates or adds the catalog resource at the passed location. This function returns a Boolean so you can use it in the From side of a copy operation and copy it to a variable of type Boolean. The example below puts the document or element in variable $V1 in the catalog with the identifier project:/myProject/resources/resource.xml and defined as type http://www.example.org/2009/03/. If the type is a WSDL, you can use the WSDL namespace. If you do not specify the type, then the namespace of the element for $V1 is automatically used.
Example:
abx:putCatalogResource( "project:/myProject/resources/resource.xml" , "http://www.example.org/2009/03/", $V1)
In a copy operation, an example of copying from this function (to a Boolean variable) is:
From:
abx:putCatalogResource( string($requestOperation.catalogOp/ns1:catalogLocation/ns1:location/text()), $requestOperation.catalogOp/ns1:content/*)
To:
funcResponse
Parameters:
- •location: The string containing the catalog location url. The location is a hint
- •typeURI: Optional string containing the resource namespace type (element namespace used if not passed).
- •document: The xml content (document or element) to be put in the catalog resource.
The function returns a Boolean true or false value.
Fault Functions
The Fault custom functions are useful in cases where partner services have not properly implemented their interfaces by declaring fault messages. Some WSDL operations do not declare a fault message, and when the service throws a fault, it cannot be caught in a normal way, by a catch or catchAll handler. Use these functions to catch undeclared faults. Use the functions within a process variable within an activity triggered by a catch or catchAll fault handler. For example: via an XPath expression $soapFault/faultstring/text().
For details on catching undeclared faults, see Catching Undeclared and SOAP Faults.
See example of a returned value below the following faults.
The fault functions you can use are:
getFaultCode()
Returns Fault Code QName, if any, from the event that triggered the fault handler
getFaultDetail()
Returns Fault Detail element, if any, from the event that triggered the fault handler
getFaultString()
Returns Fault message string, if any, from the event that triggered the fault handler.
Here is an example of a returned fault message:
<SOAP-ENV:Fault xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>the_fault_string</faultstring>
<detail/>
</SOAP-ENV:Fault>
getSOAPFault()
Returns SOAP Fault element, if any, from the event that triggered the fault handler
I18N Functions
Use this function to output a localized message in a REST service. The output message is used by Process Central request forms.
Use this function to output a localized message in a REST service.
getLocalizedMessage(key, locationHint, locale, [arg1, argN]
Returns the value of a key for an externalized string in a specified locale. The key is from a message properties file, created for Process Central process request forms. Use this function in a REST-based process to send localized data back to the output message of a process request form. In a REST process, the browser locale is available, allowing you to localize returned data.
Parameters:
- •key: required string - the key name from the message properties file created in Process Developer. The value for the key is returned by the function.
- •locationHint: required string - The catalog location URL for the default properties file. The location is a hint.
- •locale: required string - the locale for the message, such as en_US or fr_CA or fr. Empty string for the default locale. The locale is based on the browser locale.
- •arg1: optional string or object - Argument to replace text within the key value string
- •argN: optional string or object - Same as arg1, the number of args will vary depending on how many placeholders are in the key value
Example:
abx:getLocalizedMessage('loan.description','project:/myLoanApprovalProject/deploy/messages.properties', 'fr', $loanAmount)
Note that the arg1, argN object syntax is based on Java messageformat.
JSON Functions
Use these JavaScript Object Notation (JSON) functions in conjunction with REST endpoints, where the request and or the response can be JSON. For details see
Using a REST-based Service.
The JSON functions you can use are:
jsonToXml(jsonString)
Convert the JSON string to an XML element. This string can represent for an array.
The following examples show how four different array representations are transformed into XML:
- •The root element and the value is a JSON object.
JSON:
{"foo":{"name":"foo","desc":"foo desc"}}
XML:
<foo desc="foo desc" name="foo"/>
- •The root element and the value is an array. A wrapper object element containing a sequence of elements representing the values of the array is created.
JSON:
{"foo":[{"name":"foo","desc":"foo desc"},{"name":"foo2","desc":"foo2 desc"}]}
XML:
<json:object xmlns:json="http://schemas.activebpel.org/JSON/2013/10/10/aeJSON.xsd">
<foo desc="foo desc" name="foo"/>
<foo desc="foo2 desc" name="foo2"/>
</json:object>
- •A root object exists but there is no root element. The JSON object is wrapped into an object element.
JSON:
{"name":"foo","desc":"foo desc"}
XML:
<json:object xmlns:json="http://schemas.activebpel.org/JSON/2013/10/10/aeJSON.xsd"
desc="foo desc"
name="foo"/>
- •A root array exists but there is no root element. The array is wrapped in an array element and each object becomes a sequence of object elements.
JSON:
[{"name":"foo","desc":"foo desc"},{"name":"foo2","desc":"foo2 desc"}]
XML:
<json:array xmlns:json="http://schemas.activebpel.org/JSON/2013/10/10/aeJSON.xsd">
<json:object desc="foo desc" name="foo" />
<json:object desc="foo2 desc" name="foo2" />
</json:array>
xmlToJson(element)
Returns the element as a JSON string. The element is the XML document or element to convert.
Node Set Functions
You can use the following node set functions:
count(node-set)
Returns the number of nodes in the argument node-set.
id(object)
The id function selects elements by their unique ID. When the argument to id is of type node-set, then the result is the union of the result of applying id to the string-value of each of the nodes in the argument node-set. When the argument to id is of any other type, the argument is converted to a string as if by a call to the string function; the string is split into a whitespace-separated list of tokens (whitespace is any sequence of characters matching the production S); the result is a node-set containing the elements in the same document as the context node that have a unique id equal to any of the tokens in the list.
last()
Returns a number equal to the context size from the expression evaluation context.
local-name( node-set )
The local-name function returns the local part of the expanded-name of the node in the argument node-set that is first in document order. If the argument node-set is empty or the first node has no expanded-name, an empty string is returned. If the argument is omitted, it defaults to a node-set with the context node as its only member.
name( node-set )
The name function returns a string containing a QName representing the expanded name of the node in the argument node-set that is first in document order. The QName must represent the expanded-name with respect to the namespace declarations in effect on the node whose expanded-name is being represented. Typically, this is the QName that occurred in the XML source. This need not be the case if there are namespace declarations in effect on the node that associate multiple prefixes with the same namespace. However, an implementation can include information about the original prefix in its representation of nodes; in this case, an implementation can ensure that the returned string is always the same as the QName used in the XML source. If the argument node-set is empty or the first node has no expanded name, an empty string is returned. If the argument is omitted, it defaults to a node-set with the context node as its only member.
namespace-uri( node-set )
The namespace-uri function returns the namespace URI of the expanded-name of the node in the argument node-set that is first in document order. If the argument node-set is empty, the first node has no expanded-name, or the namespace URI of the expanded name is null, an empty string is returned. If the argument is omitted, it defaults to a node-set with the context node as its only member.
position()
Returns a number equal to the context position from the expression evaluation context.
Number Functions
The number functions that you can use are:
ceiling(number)
Returns the smallest (closest to negative infinity) number that is not less than the argument and that is an integer.
floor(number)
Returns the largest (closest to positive infinity) number that is not greater than the argument and that is an integer.
number(object)
Converts object to a number.
round(number)
Returns the number that is closest to the argument and that is an integer.
- •If there are two such numbers, then the one that is closest to positive infinity is returned.
- •If the argument is NaN, then NaN is returned.
- •If the argument is positive infinity, then positive infinity is returned.
- •If the argument is positive zero, then positive zero is returned.
- •If the argument is negative infinity, then negative infinity is returned.
- •If the argument is negative zero, then negative zero is returned.
- •If the argument is less than zero, but greater than or equal to -0.5, then negative zero is returned.
sum(node-set)
Returns the sum, for each node in the argument node set, of the result of converting the string-values of the node to a number.
String Functions
The string functions that you can use are:
concat(string1 string2 string3... )
Concatenates the passed strings. Can be passed any number of strings to concatenate.
contains(string string)
Returns true if the first string contains the second string.
normalize-space(string)
Returns the passed string with the leading and trailing spaces trimmed off.
starts-with(mainString lookForString)
Returns true if the first string starts with the second string.
string(object)
Converts the passed object to a string.
string-length(string)
Returns the length of the passed string.
substring(string number number)
Returns the part of the string starting at the first number (the first character being 1) and optionally for the length indicated by the second number.
substring-after(string string)
Returns the first part of the string that occurs after the first occurrence of the second string
substring-before(string string)
Returns the part of the first string that is before the first occurrence of the second string.
translate(string string string)
Returns the first argument string with occurrences of characters in the second argument string replaced by the character at the corresponding position in the third argument string. For example, translate("bar","abc","ABC") returns the string BAr. If there is a character in the second argument string with no character at a corresponding position in the third argument string (because the second argument string is longer than the third argument string), then occurrences of that character in the first argument string are removed. For example, translate("--aaa--","abc-","ABC") returns "AAA". If a character occurs more than once in the second argument string, then the first occurrence determines the replacement character. If the third argument string is longer than the second argument string, then excess characters are ignored.
