Skip to main content
Previous sectionNext section

Adding Assign Actions

This chapter provides details on adding different kinds of assign actions to a DTL transformation. It contains the following sections:

Important:

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 the next chapter.

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:

  1. Drag the circle tab to the right of the source message. Hold down the mouse button.

  2. Drag the cursor to the triangle tab to the left of the target message until its box changes color.

  3. 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:

  1. Drag a value from a source property to a target property. To do this:

    1. Click the circle tab to the right of the source property. Hold down the mouse button. The display looks similar to this:

      A highlighted property in the source message with a circle attached to its right, outer edge.

    2. 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:

      The mouse cursor on a line connecting the highlighted source property's circle to the highlighted target property's t

    3. Release the left mouse button. The display looks similar to this:

      The line connecting the highlighted source property's circle to the highlighted target property's triangle.

    The table below the diagram now shows the details of the assign action.

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

The connection from the source EVN property to the target EVN property includes all the sub-properties.

This assign action uses set.

Note:

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:

  1. Select the target property.

  2. Click set from the Add Action drop-down list. The Action tab for this operation displays.

  3. 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.”

  4. 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 null 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:

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

  2. Edit the fields as needed. For instructions, see the context-sensitive help in the dialog.

  3. Click OK to save your changes and exit the wizard.

null

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:

  1. Select the target list property or array property.

  2. Click set from the Add Action drop-down list. The Action tab for this operation displays.

  3. 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)
    Copy code to clipboard

    Edit the field to contain this instead:

    target.MyArrayProp("key2")
    Copy code to clipboard
  4. 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.

  5. Click Save.

For example:

The Action is set for target.MyListProp(3), and the Value field has a value of "new value".

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:

The action is set for target.MyListProp, the Value field has a value of "new value", and the Key field has a value

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 the Routing XML Virtual Documents in Productions.

To insert an item into a list:

  1. Select the target list property or array property.

  2. Click insert from the Add Action drop-down list. The Action tab for this operation displays.

  3. In the Property field, remove the trailing .(1) from the displayed value.

    For example, suppose that you originally see this:

    target.MyListProp.(1)
    Copy code to clipboard

    Edit the field to contain this instead:

    target.MyListProp
    Copy code to clipboard
  4. 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.

  5. For key, identify the index position for the new item.

    For example:

    5
    Copy code to clipboard
  6. Click Save.

For example:

The action is insert for target.MyListProp, the Value field is "value to insert", and the Key field is 5.

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 the Routing XML Virtual Documents in Productions.

To insert an item into a list:

  1. Select the target list property or array property.

  2. Click append from the Add Action drop-down list. The Action tab for this operation displays.

  3. In the Property field, remove the trailing .(1) from the displayed value.

    For example, suppose that you originally see this:

    target.MyListProp.(1)
    Copy code to clipboard

    Edit the field to contain this instead:

    target.MyListProp
    Copy code to clipboard
  4. 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.

  5. Click Save.

For example:

The action is append for target.MyListProp, the Value field is "value to append", and the Key field is a pair of qu

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 the Routing XML Virtual Documents in Productions.

To remove an item from a collection:

  1. Select the target list property or array property.

  2. Click remove from the Add Action drop-down list. The Action tab for this operation displays.

  3. In the Property field, remove the trailing .(1) from the displayed value.

    For example, suppose that you originally see this:

    target.MyArrayProp.(1)
    Copy code to clipboard

    Edit the field to contain this instead:

    target.MyArrayProp
    Copy code to clipboard
  4. 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"
    Copy code to clipboard
  5. Click Save.

For example:

The action is remove for target.MyListProp and the Key field is "key2".

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 the Routing XML Virtual Documents in Productions.

To clear the contents of a collection:

  1. Select the target list property or array property.

  2. Click clear from the Add Action drop-down list. The Action tab for this operation displays.

  3. In the Property field, remove the trailing .(1) from the displayed value.

    For example, suppose that you originally see this:

    target.MyArrayProp.(1)
    Copy code to clipboard

    Edit the field to contain this instead:

    target.MyArrayProp
    Copy code to clipboard
  4. Click Save.

For example:

The action is clear for target.MyListProp and the Key field is a pair of quotes.