Designer > Implementing a BPMN Task or Event in BPEL > Assign
  

Assign

Select a FROM Type and then complete the Copy operation by making other appropriate selections. Add, edit, copy, delete, and reorganize Copy operations and scripts for the selected Assign activity.
BPMN Implementation: Script task, None/Start/End throw event
The assign activity updates the content of variables. It updates variables in several ways:
You can also use assign to copy endpoint references to and from partner links for dynamic selection of service partners.
If desired, you can validate the value of variables against their XML or WSDL definitions.
Tip: You can take a shortcut to creating an assign by creating data assignments within a receive, invoke, reply, and people activity. For details, see Output Variable.
Required Properties
Optional Properties
Copy
optional attributes:
Keep Source Element Name. See Validating Variables
Ignore Missing From Data. See Copy Operation with Ignore Missing From Data Attribute.
Name. See Selecting Activity Labels
 
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
 
Validate. See Validating Variables
 
Extension Attributes and Extension Elements. See Declaring Extension Elements and Attributes.
To add an assign activity to the process:
  1. 1. From the Task palette, drag a script task to the Process Editor canvas.
    2. You can add a background color to the script task.
  2. 2. Double-click the assign to open the Operations dialog.
    3. Alternately, in the Properties view, click in the Value field of the Copy Operations and select the Dialog (...) Button.
  3. 3. Select New Copy or New Script.
  4. 4. For a New Script, the Script Builder opens where you can create an expression to execute. The script operation avoids the need for defining a from/to specification that a copy operation uses.
  5. 5. For a New Copy, in the From section, select a Type.
    6. From Type
    Description
    Upon Selection of this Type...
    Expression
    An XPath (or other language) expression to perform computations on variables and properties. Must return a string, number or Boolean.
    You can create the expression with an Expression Builder. For more information, see Using the Expression Builder
    Literal
    A constant that conforms to an XML schema definition. The type can be indicated inline using xsi:type
    Do one of the following:
    Type in literal value (for example, 100)
    Select the Literal Contents Dialog (...) Button to open a larger editing area
    Generate literal contents for a complex variable, described in Using the XML Data Wizard and Copy Operation Literal Contents Examples.
    Assign a dynamic endpoint reference. See Copy Operation Dynamic Endpoint Reference Example.
    Opaque
    Name representing private application data. Use this option only for an abstract process. For more information, see Creating an Executable vs. an Abstract Process.
    No other choices are allowed
    Partner
    This selection generates a list of partner links and roles
    Select a partner link and role defining an endpoint reference
    Variable
    A WSDL message variable and optional part name
    A WSDL message property
    XML schema simple type or element
    Select a variable name, and optionally, a part name and query. For more information, see Using the Query Builder. Queries are allowed only in executable processes.
    Variable Property
    A WSDL message property
    Select a variable name and property
  6. 6. In the To section, select a Type. The To type must be compatible with the From type, as shown.
    7. This From type
    Must match this To type
    Message-type variable
    Message-type variable with matching type
    XML schema type variable
    A variable containing a schema type
    XML element type variable
    A variable containing the same element
    Literal
    Must have a matching XML schema type
    Expression
    Expression or Variable
    Partnerlink
    partner role
  7. 7. If desired, enable the Keep Source Element Name check box, applicable only for element-based variables. The source element name is used as the name of the resulting destination element. See Element to Element Copy Operation with Keep Source Element Name Attribute.
  8. 8. If desired, enable the Ignore Missing From Datacheck box to avoid a selection failure if the source variable is missing optional data. See Copy Operation with Ignore Missing From Data Attribute.
  9. 9. Click OK. You can add multiple operations to an Assign. They are executed in the order shown in the Operations dialog and also in the Outline view.
  10. 10. If desired, in the Properties view, set the Validate property to yes to validate all variables used in the assign's Copy operations.
For a shortcut to creating new assigns or adding Copy operations to an existing assign, you can use drag-and-drop features in the Process Variables view. For more information, see Using Variables in a Copy Operation.
Copy Operation XML Syntax
<assign validate="yes|no"? standard-attributes>
standard-elements
(<copy keepSrcElementName="yes|no"?
ignoreMissingFromData="yes|no"?>
from-spec (see below)
to-spec (see below)
</copy> |
<extensionAssignOperation>
...assign-element-of-other-namespace...
</extensionAssignOperation>) +
</assign>
From-Spec XML Syntax
The From element can be in one of these forms:
<from variable="BPELVariableName" part="NCName"?
<query queryLanguage="anyURI"?>?
queryContent
</query>
/from>
<from partnerLink="NCName"
endpointReference="myRole|partnerRole"/>
<from variable="BPELVariableName" property="QName"/>
<from expressionLanguage="anyURI"?>expression</from>
<from><literal>literal value</literal></from>
In an abstract process, you can also use:
<from opaque="yes">
Opaque data is private application data that you do not want to expose to your business partners. It is effectively an abstract process placeholder for some real data that you intend to use in an executable process.
To-Spec XML Syntax
The To element can be in one of these forms:
<to variable="BPELVariableName" part="NCName"?
<query queryLanguage="anyURI"?>?
queryContent
</query>
/to>
<to partnerLink="NCName"/>
<to variable="BPELVariableName" property="QName"/>
<to expressionLanguage="anyURI"?>expression</to>
Examples:
Example 1
<assign>
<copy>
<from>'yes'</from>
<to part="accept" variable="approval"/>
</copy>
</assign>
<assign>
<copy>
<from>$po.lineItem[@prodCode=$myProd]/amt * $exchangeRate
</from>
<to>$convertedPO.lineItem[@prodCode=$myProd]/amt</to>
</copy>
</assign>
Example 2: XML for a Script Operation
<bpel:assign>
<bpel:extensionAssignOperation>
<bpel:documentation>new script operation
</bpel:documentation>
<ext3:script>abx:createAttachment('request',
'text/plain',
abx:base64Encode("Test attachment") )</ext3:script>
</bpel:extensionAssignOperation>
</bpel:assign>
See also:

Tips for Copy Operations

Select a FROM Type and then complete the Copy operation by making other appropriate selections. Add, edit, copy, delete, and reorganize Copy operations and scripts for the selected Assign activity.
Here are a few types when using a Copy operation:

Copy Operation Query and Expression Examples

Add, edit, copy, delete, and reorganize Copy operations and scripts for the selected Assign activity. Select a FROM Type and then complete the Copy operation by making other appropriate selections.
Example 1: Query selection
Example 2: Expression using built-in BPEL function
See Using the Expression Builder for more information.

Copy Operation Literal Contents Examples

Select a FROM Type and then complete the Copy operation by making other appropriate selections. Add, edit, copy, delete, and reorganize Copy operations and scripts for the selected Assign activity. For a complex type or element, you can generate an XML data file. If the Generate button is greyed out, the variable selected is not of a compatible type. For any variable, use this editor to type in appropriate literal values. Select any matching type or element from the drop-down list to create a XML data file for the root element.
Copy Operation Literal Contents Examples
Type in a literal value for copying to a simple variable, variable property, expression, or partner link, as shown in Example 1. Generate XML data for a complex variable, as shown in Example 2.
Example 1: Literal value
The expression above assigns a string to variable part that is a string. If the variable part were an integer, Process Developer would not report an error, rather it would generate a zero value. Process Developer converts any illegal values to zero for numeric type conversions.
Example 2: Literal contents generation used to initialize a complex variable
Do the following:
  1. 1. In the TO panel, select a complex variable (and optionally one of its parts) that you want to generate XML data for.
    2. If you do not select a TO target first, an unfiltered list of top-level schema elements or complex types that the process is importing are available. If no elements or types are available, the Generate button is unavailable.
  2. 2. Select the Dialog (...) Button below the Literal Contents text box to open a larger edit box.
  3. 3. Select Generate. The Generate button is available only if there are top-level schema elements or complex types in the imported WSDL. The list is filtered if you have selected a known type or element in the TO panel.
  4. 4. Fill in the details for generating data, as described in Using the XML Data Wizard.
  5. 5. Edit details of the generated data in the Literal Contents edit box, if desired, as shown in the example.
  6. 6. Click OK to view the copy operation, as shown in the example.

Copy Operation Dynamic Endpoint Reference Example

Select a FROM Type and then complete the Copy operation by making other appropriate selections. Add, edit, copy, delete, and reorganize Copy operations and scripts for the selected Assign activity.
Here is an example of how to specify a copy operation for dynamic assignment of a service. The service name would be supplied as an input to the Assign activity.
Be sure to declare the WS-Addressing namespace when you refer to endpoint references. Process Developer supports several versions of the WS-Addressing specification, as described in Endpoint References and WS-Addressing Considerations.
To implement this assignment, type in a valid endpoint reference in the Literal Contents text box. Click the Dialog (...) Button below the text box to open a larger edit box, if desired. Copy from a Literal to a Partner Link, as shown:
Example:
<assign>
<copy>
<from>
<wsa:EndpointReference
xmlns:s="http://www.active-endpoints.com/wsdl/bpr-epr"
xmlns:wsa=
"xmlns:wsa="http://www.w3.org/2005/08/addressing">
<wsa:Address>anyURI</wsa:Address>
<wsa:ServiceName>tns:Service</wsa:ServiceName>
</wsa:EndpointReference>
</from>
<to partnerLink="mypartnerLink"/>
</copy>
</assign>

Element to Element Copy Operation with Keep Source Element Name Attribute

Select a FROM Type and then complete the Copy operation by making other appropriate selections. Add, edit, copy, delete, and reorganize Copy operations and scripts for the selected Assign activity.
Use Keep Source Element Name to replace the element at the destination with a copy of the entire element at the source, including children and attribute properties. This attribute supports XSD substitution groups and choice.
If Keep Source Element Name is disabled, then the resulting value for element-based variable in the destination (that is, the TO side) has its original namespace and local name properties.
If Keep Source Element Name is enabled, then the resulting value for the element-based variable in the destination uses the name of the element-based variable in the source (that is, the FROM side).
Given the following schema snippet:
<xsd:element name="poHeader">
<xsd:complexType>
<xsd:sequence>
<xsd:choice>
<xsd:element name="shippingAddr"
type="tns:AddressType" />
<xsd:element name="USshippingAddr"
type="tns:USAddressType" />
</xsd:choice>
<xsd:element name="billingAddr"
type="tns:AddressType" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
Given the following process variable values prior to the copy operation:
poHeaderVar1
poHeaderVar2
<tns:poHeader>
<tns:poHeader>
<tns:USshippingAddr verified="true">
 
<tns:street>123 Main Street</tns:street>
 
<tns:city>SomeWhere City</tns:city>
<tns:shippingAddr pobox="true" />
<tns:country>USA</tns:country>
 
<tns:zipcode>98765</tns:zipcode>
 
</tns:USshippingAddr>
 
</tns:poHeader>
</tns:poHeader>
Given the following copy operation:
<assign>
<copy keepSrcElementName="yes">
<from>$poHeaderVar1/tns:USshippingAddr</from>
<to>$poHeaderVar2/tns:shippingAddr</to>
</copy>
</assign>
The resulting value of poHeaderVar2 is:
<tns:poHeader>
<tns:USshippingAddr verified="true">
<tns:street>123 Main Street</tns:street>
<tns:city>SomeWhere City</tns:city>
<tns:country>USA</tns:country>
<tns:zipcode>98765</tns:zipcode>
</tns:USshippingAddr>
</tns:poHeader>

Copy Operation with Ignore Missing From Data Attribute

Select a FROM Type and then complete the Copy operation by making other appropriate selections. Add, edit, copy, delete, and reorganize Copy operations and scripts for the selected Assign activity.
Use Ignore Missing From Data to avoid a selection failure when copying data that can not exist in the source variable. If enabled for a copy operation, then any from-spec that selects zero elements, attributes, or text items causes the copy operation to have no effect. The to-spec for the copy operation is not evaluated and nothing changes in the target variable. If this attribute is not enabled, then the regular bpel:selectionFailure fault is raised if the from-spec selects zero items.
Consider the sample below where a customer record could contain special instructions for package delivery. If these instructions exist in the record then they should be copied over to the data sent to the shipping service. If they do not exist, then the default instruction of "NONE" remains in place.
Case 1: Optional Data is Present
Sample data before the copy operation:
<CustomerRecord>
<Id>100256</Id>
<ShippingAddress>... </ShippingAddress>
<DeliveryInstructions>
Please leave at the back door
</DeliveryInstructions>
</CustomerRecord>
<ShippingRecord>
...
<SpecialHandling>NONE</SpecialHandling>
</ShippingRecord>
Copy Operation:
<copy ignoreMissingFromData="yes">
<from>$customerRecord/DeliveryInstructions/text()</from>
<to>$shippingRecord/SpecialHandling</to>
</copy>
Result after copy operation:
<ShippingRecord>
...
<SpecialHandling>Please leave at the back door
</SpecialHandling>
</ShippingRecord>
Case 2: Optional Data is Missing
Sample data before the copy operation:
<CustomerRecord>
<Id>100256</Id>
<ShippingAddress...>... </ShippingAddress>
</CustomerRecord>
<ShippingRecord>
...
<SpecialHandling>NONE</SpecialHandling>
</ShippingRecord>
Copy Operation:
<copy ignoreMissingFromData="yes">
<from>$customerRecord/DeliveryInstructions/text()</from>
<to>$shippingRecord/SpecialHandling</to>
</copy>
Result after copy operation:
<ShippingRecord>
...
<SpecialHandling>NONE
</SpecialHandling>
</ShippingRecord>
For further details on selection failure settings, see: Using the Process Developer Disable Selection Failure Fault Extension.