Assign a value to a property within an object.
<assign property="propertyname" value="expression" />
|property||Required. The property that is the target of this assignment.||A string of one or more characters.|
|value||Required. Provides a value for the property.||An ObjectScript expression that provides a valid value for the property.|
|action||Optional. If value is a collection property (list or array), then use action to specify the type of assignment to perform. The default is a set action.||One of the following values: set, clear, remove, append, insert. See the actions section for details.|
|key||Optional, except in some cases when value is a collection property (list or array). If so, then use this key to specify the element upon which the assignment will be performed.||A string of one or more characters. This string is an expression that evaluates to a key.|
|<annotation>||Optional. A text string that describes the <assign> element.|
The DTL <assign> element is used from within a DTL <transform> element to specify a target property and an expression whose value will be assigned to it. Generally, this expression involves values from the source object for the data transformation, but they may also be literal values. All properties involved in a DTL <assign> activity must be properties within the source or target object for the data transformation.
The source and target objects are generally production message body objects, as described in the “Messages” chapter of Developing Productions. These consist of a message header and a message body object.
Properties in the standard production message body can be data types, objects, or collections of either. Collection properties are declared with either [ Collection = list ] or [ Collection = array ] in the class definition. You can refer to the properties on the standard production message body using dot syntax as for any object property.
Properties in a virtual document require the unique syntax described in the following sections of the book Using Virtual Documents in Productions:
Actions of the <assign> Element
There are several types of DTL <assign> operation, as specified by the optional action attribute. Aside from the default of set, these variations are intended to handle assignments involving collection properties within a standard production message body. The following table describes the actions of the <assign> element.
|set||Sets the value of the specified property to that of the value attribute. Note that the value attribute contains an expression and can itself refer to an object or property of an object.||The following statement sets the value of the target BankName property:<assign property='target.BankName' value='process.BankName' action='set'/>|
|append||Adds the target element to the end of a list property|
|clear||Clears the contents of the specified collection property. The value and key attributes are ignored. (Applies to collection properties only.)||The following statement clears the contents of the collection property List:<assign property='target.List' action='clear' />|
|insert||Inserts a value into the specified collection property. If the key attribute is present the new value is inserted after the position (an integer) specified by key; otherwise, the new item is inserted at the end. (Applies to list collection properties only.)||The following statement inserts a value into the array collection property Array using the key primary:<assign property='target.Array' action='insert' key='primary' value='source.Primary' />|
|remove||Removes an item from the specified collection property. The value attribute is ignored. (Applies to collection properties only.)|
Virtual documents do not use any action value other than set.
The set action sets the value of the specified property to that of the value attribute. Note that the value attribute contains an expression and can itself refer to an object or property of an object:
<assign property='target.SSN' value='source.SSN' />
If the target property is an array collection, then the value of the key attribute specifies an item in the array, otherwise the key attribute is ignored.
If the target property is a collection and the value attribute specifies a collection of the same type, then the collection contents are copied into the target collection:
<assign property='target.List' value='source.List' />
The default action for the assign element is the set operation; if action is not specified, then the assign specifies a set operation.
Objects and Object References
If you <assign> from the top-level source object or any object property of another object as your source, the target receives a cloned copy of the object rather than the object itself. This prevents inadvertent sharing of object references and saves the effort of generating cloned objects yourself. However, if you want to share object references between source and target you must <assign> from the source to an intermediate temporary variable, and then <assign> from that variable to the target.
To create a target object that is an exact copy of the source, do not use:
<assign property='target' value='source' />
Instead use the create='copy' attribute in the containing <transform> element.
The create option may have one of the following values:
new — Create a new object of the target type, before executing the elements within the data transformation. This is the default.
copy — Create a copy of the source object to use as the target object, before executing the elements within the transform.
existing — Use an existing object, provided by the caller of the data transformation, as the target object.