Adding Assign Actions
This chapter provides details on adding different kinds of assign actions to a DTL transformation. It contains the following sections:
For virtual documents, do not manually change escape sequences in the data transformation; Ensemble handles these automatically.
For information on adding other kinds of actions, see the next chapter.
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.
Ensemble 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, such as transforming from an EnsLib.HL7.MessageOpens in a new tab to an EnsLib.EDI.XML.DocumentOpens in a new tab, 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 the chapter “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 an Ensemble 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,” earlier in this book. Make sure that the expression is valid in the scripting language you chose for the data transformation; see “Specifying Transformation Details,” earlier in this book.
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 Ensemble messages.
-
Repeating fields in Ensemble 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 Ensemble 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,” earlier in this book. Make sure that the expression is valid in the scripting language you chose for the data transformation; see “Specifying Transformation Details,” earlier in this book.
-
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 Ensemble messages. You can also use this action with XML virtual documents; see the Ensemble XML Virtual Document Development Guide.
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,” earlier in this book. Make sure that the expression is valid in the scripting language you chose for the data transformation; see “Specifying Transformation Details,” earlier in this book.
-
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 Ensemble messages. You can also use this action with XML virtual documents; see the Ensemble XML Virtual Document Development Guide.
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,” earlier in this book. Make sure that the expression is valid in the scripting language you chose for the data transformation; see “Specifying Transformation Details,” earlier in this book.
-
Click Save.
For example:
Removing a Collection Item
This section applies to collection properties (lists and arrays) in standard Ensemble messages. You can also use this action with XML virtual documents; see the Ensemble XML Virtual Document Development Guide.
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 Ensemble 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 Ensemble messages. You can also use this action with XML virtual documents; see the Ensemble XML Virtual Document Development Guide.
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: