Developing DTL Transformations
Adding Other Actions
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

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

For information on adding assign actions, see the previous chapter.
Adding an If Action
An if action executes other actions conditionally, depending on the value of an expression that you provide. Ensemble represents each if action as a connector line in the DTL diagram.
To add an if action:
  1. If the condition depends upon the value of a source property, click that property.
  2. Select if from the Select Action drop-down list.
    On the Action tab, the Condition field automatically contains the name of the source property that you had selected.
    The area below the diagram contains three new rows. The Actions column displays the following labels for these rows:
  3. Edit the Condition field so that it contains an expression that evaluates to either true or false.
    For example:
    source.ABC = "XYZ"
    Notes:
  4. To add actions to perform when the condition is true:
    1. Click the if row.
    2. Select an item from the Add Action drop-down list.
    3. Edit the values in the Action tab as needed.
    4. Repeat as necessary.
    You can include assign actions, if actions, and for each actions.
  5. To add actions to perform when the condition is false:
    1. Click the else row.
    2. Continue as described in the preceding item.
The details are then shown in the block below the DTL diagram. For example:
Note:
It is not required to have any actions for the if branch or for the else branch. If there are no actions in either branch, the if action has no effect.
Adding a For Each Action
The for each action enables you to define a sequence actions that is executed iteratively, once for each member of one of the following:
Ensemble represents each for each action as a connector line in the DTL diagram.
To add a for each action:
  1. Select a collection or repeating property in the source message.
  2. Select for each from the Select Action drop-down list.
    On the Action tab, the Property field automatically contains the name of the source property that you had selected.
    Also, the Key field automatically contains k1. For the for each action, the Key field specifies the name of an iterator variable.
  3. On the Action tab, the Property field should not include the iterator key within the parentheses. For example, the following is correct:
    source.{PID:PatientIdentifierList( )}
    This means that Ensemble will iterate through the PatientIdentifierList repeating fields, starting with the first one (numbered 1) and ending with the last one.
    For example:
  4. To add actions to the for each block, click the for each action and then add the appropriate actions.
The details are then shown in the block below the DTL diagram. For example (partial):
If the <foreach> applies to a collection property in a message, the sequence of activities is executed iteratively, once for every element that exists within the collection property. If the element is null, the sequence is not executed. The sequence is executed if the element has an empty value, that is, the separators are there but there is no value between them, but is not executed for a null value, that is, the message is terminated before the field is specified.
Shortcuts for the For Each Action
When you are working with virtual documents, Ensemble provides a shortcut notation that iterates through every instance of a repeating field within a document structure. This means you do not actually need to set up multiple nested for each loops to handle repeating fields; instead you create a single assign action using a virtual property path with empty parentheses within the curly bracket { } syntax. For information, see Curly Bracket {} Syntax in Ensemble Virtual Documents.
Note:
If the source and target types are different, such as transforming from an EnsLib.HL7.Message to an EnsLib.EDI.XML.Document, you cannot use this short cut for the For Each action. Use an explicit For Each action in these cases.
Avoiding <STORE> Errors with Large Messages
As you loop over segments in an HL7 message or object collections, they are brought into memory. If these objects consume all the memory assigned to the current process, you may get unexpected errors.
To avoid this, remove the objects from memory after you no longer need them. For example, if you are processing many HL7 segments in a for each loop, you can call the commitSegmentByPath() method on both the source and target as the last step in the loop. Similarly, for object collections, use the %UnSwizzleAt() method.
For example, within the innermost for each loop, include a code action that contains the following ObjectScript:
 Do source.commitSegmentByPath("ORCgrp("_tORCkey_").OBRgrp("_tOBRkey_").OBXgrp("_tOBXkey_").OBX")
 Do target.commitSegmentByPath("ORCgrp("_tORCkey_").OBRgrp("_tOBRkey_").OBXgrp("_tOBXkey_").OBX")
If you cannot make code changes, a temporary workaround is to increase the amount of memory allocated for each process. You can change this by setting the bbsiz parameter on the Advanced Memory Settings page in the Management Portal. Note that this requires a system restart and should only occur after consulting with your system administrator.
Adding a Subtransform Action
A subtransform invokes another transformation (an ordinary transformation), often within a for each loop. Subtransformations are particularly useful with virtual documents, because EDI formats are typically based on a set of segments that are used in many message types. The ability to reuse a transformation within another transformation means that you can create a reusable library of segment transformations that you can call as needed, without duplicating code transformation.
Ensemble does not represent a subtransform action in the DTL diagram.
To add a for each action:
  1. Select subtransform from the Select Action drop-down list.
  2. On the Action tab, specify the following details:
    Note:
    In the case of a subtransform with Create as new or copy, it is not necessary to have a pre-existing target object.
Example
The examples show two DTL transformation classes. The second transformation calls the first one as a subtransformation.
Adding a Trace Action
A trace action generates a trace message, which is helpful for diagnosis. If the Log Trace Events setting is enabled for the parent business host, this message is written to the Event Log. If the Foreground setting is enabled for the parent business host, the trace messages are also written to the Terminal window.
Ensemble does not represent a trace action in the DTL diagram.
To add a trace action:
  1. Select trace from the Select Action drop-down list.
  2. On the Action tab, specify the following:
The trace action generates trace message with User priority; the result is the same as using the $$$TRACE macro in ObjectScript or the WriteTrace("user") utility in Basic.
Adding a Code Action
A code action enables you to execute one or more lines of user-written code within a DTL data transformation. This option enables you to perform special tasks that are difficult to express using the DTL elements. Ensemble does not represent a code action in the DTL diagram.
To add a code action:
  1. Select code from the Select Action drop-down list.
  2. On the Action tab, specify the following:
Tip:
To write custom code that you can debug easily, write the code within a class method or a routine so that it can be executed in the Terminal. Debug the code there. Then call the method or routine from within the code action of the DTL.
Guidelines for Using Custom Code in DTL
In order to ensure that execution of a data transformation can be suspended and restored, you should follow these guidelines when using a code action:
Adding an SQL Action
An SQL action enables you to execute an SQL SELECT statement from within the DTL transformation. Ensemble does not represent an sql action in the DTL diagram.
To add an sql action:
  1. Select sql from the Select Action drop-down list.
  2. On the Action tab, specify the following:
Guidelines for Using SQL in DTL
Be sure to use the following guidelines: