Name

<assign> — update the values of variables with new data

Synopsis

<assign validate="yes|no"? standard-attributes>
   standard-elements
   (
   <copy keepSrcElementName="yes|no"? ignoreMissingFromData="yes|no"?>
      from-spec
      to-spec
   </copy>
   |
   <extensionAssignOperation>
      assign-element-of-other-namespace
   </extensionAssignOperation>
   )+
</assign>

throws bpel:invalidVariables, bpel:selectionFailure, bpel:subLanguageExecutionFault, bpel:uninitializedVariable, bpel:mismatchedAssignmentFailure, bpel:uninitializedPartnerRole

Description

The <assign> activity can be used to copy data from one variable to another, as well as to construct and insert new data using expressions. The <assign> activity can also be used to copy endpoint references to and from partnerLinks.

Each <assign> is made up of any number of <copy> entries which are each made up of a "to-spec" (lvalue), and a from-spec (rvalue).

• ignoreMissingFromData - (optional) Should the bpel:selectionFailure standard fault be suppressed?
  • yes - suppress standard faults
  • no - (default) do not suppress standard faults

The ignoreMissingFromData element has been implemented in ODE 1.3+ (i.e., it is coming soon). See ODE-141 for issue tracking.

• validate - (optional) validate modified variables?
  • yes - the <assign> activity validates all the variables being modified by the activity. If the validation fails the [bpel:invalidVariables#invalidVariables] fault is thrown.
  • no - (default) do not validate the modified variables

    ODE currently disregards the value of this attribute — validation is never performed.

• <copy> - defines a lvalue, rvalue pair.
  • keepSrcElementName - (optional) should the element name of the destination (as selected by the to-spec) be replaced by the elementname of the source (as selected by the from-spec)?
    • yes - element names are replaced
    • no - (default) element names are not replaced
  • <from> - specifies the rvalue (see here)
  • <to> - specifies the lvalue (see here)

• <extensionAssignOperation> - a container for assignment extensions. If the element contained within the extensionAssignOperation elements not recognized by ODE and is not subject to a mustUnderstand="yes" requirement from an extension declaration then the element will be ignored.

  Since version 2.0 ODE fully supports extensionAssingOperation functionality.

From/To-Spec Variants

The <assign> activity copies a type-compatible value from the source ("from-spec") to the destination ("to-spec"), using the <copy> element. The from-spec must be one of the following variants:

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

<from/>  <!-- DO NOT USE -->

<from variable="BPELVariableName" extension="QName" />   <!-- non-standard extension -->

The <from extension="QName" /> from-spec variant is not part of the WS-BPEL 2.0 specification. It is a non-standard ODE extension.

The to-spec must be one of the following variants:

<to variable="BPELVariableName" part="NCName"?>
   <query queryLanguage="anyURI"?>?
      queryContent
   </query>
</to>

<to partnerLink="NCName" />

<to variable="BPELVariableName" property="QName" />

<to expressionLanguage="anyURI"?>expression</to>

<to/> <!-- DO NOT USE -->

<to variable="BPELVariableName" extension="QName" /> <!-- ODE SPECIFIC -->

The <to extension="QName" /> to-spec variant is not part of the WS-BPEL 2.0 specification. It is a non-standard ODE extension.

A to-spec must return an lvalue. If a to-spec does not return an lvalue then a bpel:selectionFailure will be thrown. In the context of XPath, an lvalue is a node-list containing a single node from a variable or a partnerLink identified by the to-spec (e.g. the XPath expression concat("foo""bar") is not an lvalue).

XPaths used as lvalues must begin with an XPath VariableReference.

Assignment is an atomic operation; that is, either all <copy> s succeed, or no changes are made.

In ODE, each <copy> is atomic.

Variable Variant

Selects value stored in a BPEL variable.

<to|from variable="BPELVariableName" part="NCName"?>
   <query queryLanguage="anyURI"?>?
      queryContent
   </query>
</to|from>

• variable - (required) name of the variable.
• part - (optional) if the type of this variable is a WSDL messageType this attribute may be used to provide the name of a part within that variable. This attriubte must not be used When the variable is defined using XML Schema types (simple or complex) or element
• <query> element may be used to select a value from the source or target variable or message part. The computed value of the query must be one of the following:
  • a single XML node, for example an attribute or an element
  • text (i.e. a text node, CDATA section, string-valuedXPath-expression, etc...)

PartnerLink Variant

Allows manipulation of the endpoint references associated with partnerLinks.

<from partnerLink="NCName" endpointReference="myRole|partnerRole" />

<to partnerLink="NCName"  />

• partnerLink - name of partnerLink
• role - the role or "side" of the partnerLink
  • myRole - the endpoint reference of the process
  • {partnerRole}} - the partner's endpoint reference

For from-specs, the role attribute must be specified, while for the to-spec, the assignment is only possible to the partnerRole, hence there is no need to specify the role. Therefore, the to-spec can only refer to a <partnerLink> of which the declaration specifies the partnerRole attribute. The type of the value referenced by partnerLink-style from/to-specs is always a <sref:service-ref> element.

An attempt during process execution to read a partner link before its partnerRole EPR is initialized results in the bpel:uninitializedPartnerRole standard fault. Partner roles of partner links are read when they are referenced in an <invoke> or the <from> part of a <copy> in an <assign> activity.

Property Variant

Allows data manipulation using properties. The property value generated by the from-spec is generated in the same manner as the value returned by the bpel:getVariableProperty() function.

<to|from variable="BPELVariableName" property="QName" />

• variable - name of the variable referenced
• property - name of the property to apply to the variable

Expression Variant

In the Expression Variant, an expression language (typically XPath), is used to calculate a value.

<to|from expressionLanguage="anyURI"?>expression</from>

• expressionLanguage - (optional) identifies the expression language
• expression - the expression; syntax is determined by the expression language.

The computed value of the expression must be one of the following:

• a single XML node, for example an attribute or an element
• text (i.e. a text node, CDATA section, string-valuedXPath-expression, etc...)

Literal Variant

The Literal Variant allows a literal value to be given as the rvalue.

<from><literal>literal value</literal></from>

• literal value - value to be assigned

The type of the literal value may be optionally indicated inline with the value by using XML Schema's instance type mechanism (xsi:type). The literal content must be either a single element or text. An empty <literal/> element is equivalent to an empty text node.

Empty Variant

The empty variant exist for extensibility purposes; it is not supported by ODE.

<from|to/>

Variable Extension Variant (non-standard extension)

The variable extension variants are non-standard extensions implemented by ODE to allow manipulation of protocol-specific properties from within a BPEL process.

<from variable="BPELVariableName" extension="QName" />

• variable - message variable to read
• extension - qualified name of the extension

The variable referenced by this variant must be message-typed. The following extensions are supported:

The use of this feature is not encouraged. Processes using this feature will not be compatible with WS-BPEL 2.0 conformant systems.

Insert Variant (non-standard extension)

See copy with insert attribute

Faults

• bpel:invalidVariables - A modified variable does not conform to its schema and the validate flag was set to yes.

  ODE does not perform schema type validation, hence this fault is never thrown.

• bpel:selectionFailure - The node(s) selected by a from/to-spec is (are) invalid. This includes cases when the to-spec returns a node that is not an lvalue, when multiple nodes are selected, or when no node is selected.
  
• bpel:subLanguageExecutionFault - Evaluating the expression (in the expression variant), or the query (in the variable variant) generated an error. For example, if a divide-by-zero is attempted.
  
• bpel:uninitializedVariable - The variable referenced in the from-spec has not been initialized.
  
• bpel:mismatchedAssignmentFailure - The nodes selected by the to-spec and from-spec are not compatible. This could occur if for example an attempt was made to assign a text node to an element variable, or an element variable was assigned to a message variable.

Examples

The following assigns a childless element bar in namespace http://example.com to an element-typed variable myFooBarElemVar:

<assign>
   <copy>
      <from>
         <literal xmlns:foo="http://example.com">
            <foo:bar />
         </literal>
      </from>
      <to variable="myFooBarElemVar" />
   </copy>
</assign>

The following assigns the string "FooBar" to a string-typed variable myStringVar:

<assign>
   <copy>
      <from>
         <literal>
            <![CDATA[FooBar]]>
         </literal>
      </from>
      <to variable="myStringVar" />
   </copy>
</assign>

The following assigns the string "" (i.e. the empty string) to a string-typed variable myStringVar:

   <copy>
      <from>
         <literal />
      </from>
      <to variable="myStringVar" />
   </copy>
</assign>

The following illustrates copying one variable (c1) to another (c2) as well as copying a variable part (address part of variable c1) to a variable of compatible element type (c3):

<assign>
   <copy>
      <from variable="c1" />
      <to variable="c2" />
   </copy>
   <copy>
      <from>$c1.address</from>
      <to variable="c3" />
   </copy>
</assign>