Invoke
BPMN Implementation: Send task, Service task, Rule task, Message throw event
The invoke activity directs a Web service to perform a one-way or request-response operation. It specifies the participant that provides the service and the operation to invoke. The invoke activity must specify the data for the message transmitted and may specify an output variable or variable part in the case of a synchronous request-response Web service invocation. See Participants for descriptions of concepts important to this activity.
An invoke activity can be compensated, or reversed. For more information, see Compensation.
An invoke activity can also include fault handling when the invoke is added to a scope. Alternately, any faults associated with the invoked service can be handled at the process level, if desired.
An invoke activity can also include fault handling when the invoke is added to a scope. Alternately, any faults associated with the invoked service can be handled at the process level, if desired. For more information, see Fault Handling.
Required Properties | Optional Properties |
|---|
Participant (Partner Link) | Name. See Selecting Activity Labels |
Operation | Port Type |
Input Variable See Input Variable. or toPart fromVariable See From Variable to Part. | Correlations. See Correlation. |
| Output Variable See Output Variable and From Part to Variable. |
| Input and Output assignments |
| Join Condition. See Creating a Join Condition for an Incoming Link |
| Suppress Join Failure. See Process Properties |
| Comment. See Adding Comments to a Process |
| Documentation. See Adding Documentation to a Process |
| Setting Visual Properties and Using Your Own Library of Images |
| Execution State. See Viewing the Execution State of an Activity or Link |
| Extension Attributes and Extension Elements. See Declaring Extension Elements and Attributes. |
To add an invoke activity to the process manually:
- 1. Drag a Send task (or other BPMN implementation mentioned above) to the Process Editor canvas.
- 2. You can add a background color to the send, service, and rule tasks.
In the Properties view, select the following values:
- a. Optionally type in a Name.
- b. In the Participant drop-down, select New Partner Service Provider. See Creating a New Partner Service Interface.
- c. Select a participant's Operation from the picklist.
- 3. In the Input tab, do one of the following:
- - Select Single Variable from the Assignment Type and select a variable.
- - Select a XPaths or XQuery. For details, see From Part to Variable.
- 4. Optionally, select an output variable or a to part. For details, see From Variable to Part.
- 5. Select other optional properties as desired.
A simple example of using an invoke activity in a process is shown in the following illustration.
For another shortcut for creating an invoke activity, see Creating an Activity by Starting with a WSDL Interface.
XML Syntax
<invoke partnerLink="NCName" portType="QName"? operation="NCName"
inputVariable="NCName"? outputVariable="NCName"?
standard-attributes>
standard-elements
<correlations>?
<correlation set="NCName" initiate="yes|join|no"?
pattern="request|response|request-response"/>+
</correlations>
<catch faultName="QName"? faultVariable="NCName"?
faultMessageType="QName"? faultElement="QName"?>*
activity
</catch>
<catchAll>?
activity
</catchAll>
<compensationHandler>?
activity
</compensationHandler>
<toParts>?
<toPart part="NCName" fromVariable="BPELVariableName"/>+
</toParts>
<fromParts>?
<fromPart part="NCName" toVariable="BPELVariableName"/>+
</fromParts>
</invoke>
Example:
<invoke name="invokeapprover" partnerLink="approver"
portType="lns:loanApprovalPT" operation="approve"
inputVariable="request" outputVariable="approval">
From Part to Variable
Select a variable part and assign it to a process variable. Select New to create a From Part or To Part specification to add to the list.
Receive, onMessage (pick activity), onEvent (event handler), invoke, and people activities can copy message parts to process variables, eliminating the need to create an assign activity to do the copy. You can specify a from pan instead of a variable for a receive, onMessage, and onEvent activity. You can also specify a from pan in place of the output variable for an invoke or people activity.
If the WSDL operation uses a message containing exactly one part which itself is defined using an element, then the Web service interaction activity can use the fromPart element for the activity's variable. The fromPart declarations are used in place of the activity's variable declaration. In the case of an invoke or people activity, the fromPart declaration replaces the output variable.
Select the part and variable from the list of in-scope variables. For an onEvent activity, specify a variable name, and the variable is created implicitly.
The following example show the XML source for a From Part assignment.
<onEvent operation="asyncOp" partnerLink="requestPLT">
<fromParts>
<fromPart part="one" toVariable="myNewVariable"/>
</fromParts>
<scope/>
</onEvent>
From Variable to Part
Select New to create a From Part or To Part specification to add to the list. Or select a process variable and assign it to a variable part
Reply and invoke activities can copy a process variable to a message part, eliminating the need to create an assign activity to do the copy. For the invoke, you can specify a to part instead of an input variable, and for the reply, you can specify a to part instead of the variable.
If the WSDL operation uses a message containing exactly one part which itself is defined using an element, then the Web service interaction activity can use the toPart element for the output variable. The toPart declarations are used in place of the activity's output variable declaration.
The following example shows the XML source for a To Part assignment.
<invoke outputVariable="twoWayRequest"
name="InvokeWithManagedCorrelation" operation="asyncOp"
partnerLink="requestPLT" portType="ns1:asyncRequestPT">
<toParts>
<toPart fromVariable="V1" part="one"/>
</toParts>
</invoke>
Input Variable
The input for an invoke, reply, or people activity can be constructed within the Input (or Data) tab of the activity's Properties view. Use the Input (or Data) tab of the invoke, reply or people activity as follows:
The input for an invoke or reply activity can be constructed within the Input (or Data) tab of the activity's Properties view. Use the Input (or Data) tab of the invoke or reply as follows:
Assignment Type
- •Single Variable. Select a variable if no input preparation is desired via an assign activity. Select an existing process variable or select New Variable. The variable must be of the operation's input message type, or, if the operation requires only one part, the variable's type can be the element type of the one part.
- •XPaths. Select XPaths if you want to use a table to map from data within existing variables or a literal to the contents of the input message. The table uses XPath expressions that allow you to select nodes from a variable to assign to the input variable as well as compute values (strings, numbers, or Boolean values) from the content of variable. See Adding XPaths below.
- •XQuery. Select XQuery if you want to fill each input message part with a single query written in the XQuery expression language. This language allows you to create a query that looks like an XML document, but where pieces of the document are constructed using a superset of the XPath expression syntax. It supplements XPath with a SQL-like "FLWOR expression" (FOR, LET, WHERE, ORDER BY, and RETURN) for performing joins. See Adding XQuery below.
For example XPath and XQuery expressions, see Selecting XPath or XQuery for Expression Building.
Tip: If you want to use Javascript to prepare some or all of an input message, create an assign activity instead of using the Input tab. Each copy operation in an assign can use a different expression language.
Adding XPaths
- 1. On the Input (or Data) tab of an invoke, reply, or people activity, ensure that the Assignment Type is XPaths.
- 2. On the Input (or Data) tab of an invoke or reply activity, ensure that the Assignment Type is XPaths.
- 3. In the table, select Add to populate the b column.
- 4. In the To Path column, select the child node of the part, if needed.
- 5. In the E/L column, select the From type: Expression or Literal.
- 6. In the From column, select the Dialog (...) Button at the end of the table cell. For a literal, select Generate and notice that the literal XML document is generated for you based on the type needed for the chosen To Part and To Path. To add an expression, fill in the Expression text box. For a shortcut, see Using Content Assist.
For more information on expression languages, see Using the Expression Builder.
The following is an example of a literal mapping:
- 7. Optionally, in Copy Attachments, select a variable that can have attachments that you want to copy to or from. Note that you must copy all attachments. If you want only some attachments, you can add an Assign activity before the activity. See Adding an Attachment for details.
- 8. When you use XPaths, a temporary variable called parameters is created to contain the parts. For details, see Viewing Container Variables below.
Adding XQuery
For easy XQuery development, see Writing XQuery Functions.
- 1. On the Input (or Data) tab of an invoke, reply, or people activity, ensure that the Assignment Type is XQuery.
Notice that a XML template is generated for the message part. If desired, after editing the document, you can regenerate the template.
- 2. Fill in the XQuery expressions as desired for each element. Optionally, select Builder to open the Query Builder to insert expressions or functions into the query.
The following is an example of an XQuery mapping.
- 3. Optionally, copy attachments, as described above in the XPaths discussion.
Viewing Container Variables
Iif you use XPaths or XQuery, a container variable is added to the Process Variables view, called parameters. Similarly, if you are copying attachments to the input variable, you will see the container variable, attachmentCopyResult. These variables are hidden by default since they are used only temporarily at runtime to process parts of a full variable. Select Show Internal Variables to make them visible.
Output Variable
The output from a receive, invoke (for a request-response operation) or people activity (containing a task) can require that data is mapped to a process variable.
The output from a receive or invoke (for a request-response operation) can require that data is mapped to a process variable.
Assignment Type
- •Single Variable. Select a variable from the list to put the output of the activity into that variable. The variable must be of the operation's output message type, or, if the operation reply has only one part, the variable's type can be the element type of the one part. Select an existing process variable or select New Variable.
- •Parts To Variables. Select Parts To Variables if you want each reply message part to map to a different variable. For details, see From Part to Variable.
- •XPaths. Select XPaths if you want to use a table to map from data within existing variables to the contents of the input message. The table uses XPath expressions that allow you to select nodes from a variable to assign to the input variable as well as compute values (strings, numbers, or Boolean values) from the content of variable. See Adding XPaths in the Input Variable topic.
Viewing Container Variables
If you use XPaths, a container variable is added to the Process Variables view, called result. Similarly, if you add are copying attachments to the input variable, you will see the container variable, attachmentCopyResult. These variables are hidden by default since they are used only temporarily at runtime to process parts of a full variable. Select Show Internal Variables to make them visible.
