Adding Assign Actions
This topic provides details on adding different kinds of assign actions to a DTL transformation.
For virtual documents, do not manually change escape sequences in the data transformation; InterSystems IRIS® handles these automatically.
For information on adding other kinds of actions, see Adding Other Actions.
For information about working with groups of actions, see Working with Groups of Actions .
Introduction
There are five kinds of assign actions: set, clear, remove, append, and insert. After you create any kind of assign action, you can change the type. To do so, select a different value in the Action drop-down in the Action tab.
InterSystems IRIS represents each assign action with a connector line in the DTL diagram.
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.
If you instead 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.
Copying the Source Message
To create an assign action that copies the source message:
-
Drag the circle tab to the right of the source message. Hold down the mouse button.
-
Drag the cursor to the triangle tab to the left of the target message until its box changes color.
-
Release the left mouse button.
Copying a Value from a Source Property to a Target Property
To create an assign action that copies a value from a source property to a target property:
-
Drag a value from a source property to a target property. To do this:
-
Click the circle tab to the right of the source property. Hold down the mouse button. The display looks similar to this:
-
Drag the cursor to the triangle tab to the left of the target property until its box changes color. The display looks similar to this:
-
Release the left mouse button. The display looks similar to this:
The table below the diagram now shows the details of the assign action.
-
-
Optionally edit the details on the Action tab.
This assign action uses set.
Copying Values of All Sub-properties
If parent properties in the source and target are identical and the source and target have the same type, you can assign the values of all the sub-properties at once. In this case there is no need to expand the parent properties to reveal the sub-properties. Simply drag the cursor from the parent property on the source side to the parent property on the target side.
In the following DTL diagram, the single connector between the EVN property on the source side and the EVN property on the target side includes all of the following sub-properties of EVN:
-
EventTypeCode
-
RecordedDateTime and all of its sub-properties
-
DateTimePlannedEvent and all of its sub-properties
-
EventReasonCode
-
OperatorID, all of its iterations, and all of its sub-properties
-
EventOccurred and all of its sub-properties
This assign action uses set.
If the source and target types are different, you cannot use this feature to assign subproperties, even if the structures appear to be parallel. For such a transformation, you must assign each leaf node of a structure independently and add a for each action to process iterations. See Adding a For Each Action for details on the for each action.
Assigning a Literal Value to a Target Property
To assign a literal value to a target property:
-
Select the target property.
-
Click set from the Add Action drop-down list. The Action tab for this operation displays.
-
Type a literal numeric or string value in the Value field:
-
A numeric literal is just a number. For example: 42.3
-
A string literal is a set of characters enclosed by double quotes. For example: "ABD"
Note:This string cannot include XML reserved characters. For virtual documents, this string cannot include separator characters used by that virtual document format. For details, see Syntax Rules.
-
-
Click Save.
Using an Expression for the Value of a Target Property
A literal value, as described in the previous section, is a simple kind of expression. In some cases, you might want to use a more complex expression as the value of a target property. To do so, either:
-
To create an expression that uses a function, click the search button next to the Value field. This invokes the Data Transform Function Wizard, which is described in the following subsection.
-
To create a more complex expression, type the expression into the Value field.
See Valid Expressions. Make sure that the expression is valid in the scripting language you chose for the data transformation; see Specifying Transformation Details.
Using the Data Transform Function Wizard
To use the Data Transform Function Wizard:
-
Select a Function from the drop-down list.
More fields display as needed to define the expression.
If you select Repeat Current Function from the drop-down list, a copy of the current function is inserted as a parameter of the itself, which creates a recursive call to the function.
-
Edit the fields as needed. For instructions, see the context-sensitive help in the dialog.
-
Click OK to save your changes and exit the wizard.
Assigning a Value to a Collection Item
This section applies to the following kinds of collections:
-
Collection properties in standard production messages.
-
Repeating fields in XML virtual documents.
To change the value of an item from a collection:
-
Select the target list property or array property.
-
Click set from the Add Action drop-down list. The Action tab for this operation displays.
-
In the Property field, edit the value in parentheses so that it identifies the item to change.
For array properties, use the key of the array item. For list properties, use the index of the list item. For repeating fields in virtual documents, use the index of the segment or field.
For example, suppose that you originally see this:
target.MyArrayProp.(1)
Edit the field to contain this instead:
target.MyArrayProp("key2")
-
Edit Value to contain a literal value or other valid expression.
See Valid Expressions. Make sure that the expression is valid in the scripting language you chose for the data transformation; see Specifying Transformation Details.
-
Click Save.
For example:
Or, edit the Property field to remove the trailing .(1) from the displayed value. Then use key to specify identify the item to change, as described in the next section. For example:
Inserting a List Item
This section applies to list properties (but not array properties) in standard production messages. You can also use this action with XML virtual documents; see Routing XML Virtual Documents in Productions.
To insert an item into a list:
-
Select the target list property or array property.
-
Click insert from the Add Action drop-down list. The Action tab for this operation displays.
-
In the Property field, remove the trailing .(1) from the displayed value.
For example, suppose that you originally see this:
target.MyListProp.(1)
Edit the field to contain this instead:
target.MyListProp
-
Edit Value to contain a literal value or other valid expression.
See Valid Expressions. Make sure that the expression is valid in the scripting language you chose for the data transformation; see Specifying Transformation Details.
-
For key, identify the index position for the new item.
For example:
5
-
Click Save.
For example:
Appending a List Item
This section applies to list properties (but not array properties) in standard production messages. You can also use this action with XML virtual documents; see Routing XML Virtual Documents in Productions.
To insert an item into a list:
-
Select the target list property or array property.
-
Click append from the Add Action drop-down list. The Action tab for this operation displays.
-
In the Property field, remove the trailing .(1) from the displayed value.
For example, suppose that you originally see this:
target.MyListProp.(1)
Edit the field to contain this instead:
target.MyListProp
-
Edit Value to contain a literal value or other valid expression.
See Valid Expressions. Make sure that the expression is valid in the scripting language you chose for the data transformation; see Specifying Transformation Details.
-
Click Save.
For example:
Removing a Collection Item
This section applies to collection properties (lists and arrays) in standard production messages. You can also use this action with XML virtual documents; see Routing XML Virtual Documents in Productions.
To remove an item from a collection:
-
Select the target list property or array property.
-
Click remove from the Add Action drop-down list. The Action tab for this operation displays.
-
In the Property field, remove the trailing .(1) from the displayed value.
For example, suppose that you originally see this:
target.MyArrayProp.(1)
Edit the field to contain this instead:
target.MyArrayProp
-
For key, identify the item to remove.
For array properties, use the key of the array item. For list properties, use the index of the list item. For repeating fields in virtual documents, use the index of the segment or field.
For example:
"key2"
-
Click Save.
For example:
Clearing a Collection Property
This section applies to collection properties (lists and arrays) in standard production messages. You can also use this action with XML virtual documents; see Routing XML Virtual Documents in Productions.
To clear the contents of a collection:
-
Select the target list property or array property.
-
Click clear from the Add Action drop-down list. The Action tab for this operation displays.
-
In the Property field, remove the trailing .(1) from the displayed value.
For example, suppose that you originally see this:
target.MyArrayProp.(1)
Edit the field to contain this instead:
target.MyArrayProp
-
Click Save.
For example: