Title: assign

<a name="assign-Name"></a>
## Name
`<assign>` --- update the values of variables with new data
 
<a name="assign-Synopsis"></a>
## Synopsis
<div class="caption">Usage</div>

    <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](#invalidVariables)`, `[bpel:selectionFailure](#selectionFailure)`, `[bpel:subLanguageExecutionFault](#subLanguageExecutionFault)`, `[bpel:uninitializedVariable](#uninitializedVariable)`, `[bpel:mismatchedAssignmentFailure](#mismatchedAssignmentFailure)`, `[bpel:uninitializedPartnerRole](#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](#selectionFailure)` standard fault be suppressed? 
    - `yes` - suppress standard faults
    - `no` - (default) do not suppress standard faults

<div class="alert alert-info">
    The `ignoreMissingFromData` element has been implemented in ODE 1.3+ (i.e., it is coming soon).  See [ODE-141](http://issues.apache.org/jira/browse/ODE-141) for issue tracking.
</div>

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

<div class="alert alert-info">
    ODE currently disregards the value of this attribute --- validation is never performed.
</div>

 - `<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](#variants))
    - `<to>` - specifies the lvalue (see [here](#variants))
    - `<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.

<div class="alert alert-info">
    Since version 2.0 ODE fully supports `extensionAssingOperation` functionality.
</div>

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

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

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

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

A to-spec must return an lvalue. If a to-spec does not return an lvalue then a `bpel:[selectionFailure](selectionfailure.html)` 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). 
<div class="alert alert-note">
    XPaths used as lvalues must begin with an XPath VariableReference.
</div>

Assignment is an atomic operation; that is, either all `<copy>` s succeed, or no changes are made.
<div class="alert alert-warning">
    In ODE, each `<copy>` is atomic.
</div>

<a name="assign-VariableVariant"></a>
#### 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...)

<a name="assign-PartnerLinkVariant"></a>
#### 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](#uninitializedpartnerrole.html)` 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.

<a name="assign-PropertyVariant"></a>
#### 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

<a name="assign-ExpressionVariant"></a>
#### 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...)

<a name="assign-LiteralVariant"></a>
#### 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.

<a name="assign-EmptyVariant"></a>
#### Empty Variant
The empty variant exist for extensibility purposes; it is not supported by ODE. 

    <from|to/>


<a name="assign-VariableExtensionVariant(non-standardextension)"></a>
#### 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:
<table>
<tr><th>Extension Namespace</th><th>Name</th><th>Description
</tr>
<tr><td>urn:ode.apache.org/axis2-il/headers/</td><td>in</td><td>When using the AXIS2 integration layer, this extension returns the headers that were received with the message but that did not map to any message parts in the portType. The return value will be a wrapper element(with the same name as the  extension) containing the SOAP header elements. </td></tr>
<tr><td>urn:ode.apache.org/axis2-il/headers/</td><td>out</td><td>When using the AXIS2 integration layer, this extension holds the headers that should be sent with the mesage but are not mapped to any message parts in the portType. The rvalue should be a wrapper element (with the same name as the  extension) containing the SOAP header elements to be sent.</td></tr>
</table>

<div class="alert alert-warning">
    The use of this feature is not encouraged. Processes using this feature will not be compatible with WS-BPEL 2.0 conformant systems.
</div>

<a name="assign-InsertVariant({color:red}non-standardextension{color})"></a>
#### Insert Variant ({color:red}non-standard extension{color})

See [copy with insert attribute](copy-with-insert-attribute.html)

<a name="assign-Faults"></a>
### Faults
{anchor:invalidVariables}
- `bpel:[invalidVariables](invalidvariables.html)` - A modified variable does not conform to its schema and the `validate` flag was set to `yes`. 
<div class="alert alert-note">
    ODE does not perform schema type validation, hence this fault is never thrown.
</div>
{anchor:selectionFaulure}
- `bpel:[selectionFailure](selectionfailure.html)` - 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. 
{anchor:subLanguageExecutionFault}
- `bpel:[subLanguageExecutionFault](sublanguageexecutionfault.html)` - 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.
{anchor:uninitializedVariable}
- `bpel:[uninitializedVariable](uninitializedvariable.html)` - The variable referenced in the from-spec has not been initialized.
{anchor:mismatchedAssignmentFailure}
- `bpel:[mismatchedAssignmentFailure](mismatchedassignmentfailure.html)` - 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. 

<a name="assign-Examples"></a>
### 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>