Adding Other Actions

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:

   • if — This row marks the beginning of actions to perform if the condition is true.

   • else — This row marks the beginning of actions to perform if the condition is false.

   • endf — This row marks the end of the if action.

3. Edit the Condition field so that it contains an expression that evaluates to either true or false.

   For example:

   source.ABC = "XYZ"
   

   

   Notes:

   • 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 earlier.

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

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:

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:

• A collection property (for a standard message) .

• A repeating property (for an Ensemble virtual document).

• A set of subdocuments in a document (for an Ensemble virtual document).

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.

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 subtransform action:

1. Select subtransform from the Select Action drop-down list.

2. On the Action tab, specify the following details:

   • Transform Class — Specifies the data transformation class to use. This can be either a DTL transformation or a custom transformation. For information on custom transformations, see “Defining Custom Transformations” in Developing Ensemble Productions. You must enter the class.

   • Source Property — Identifies the property being transformed. This may be an object property or a virtual document property path. Generally it is a property of the source message used by the transformation. You must enter the source property.

   • Target Property — Identifies the property into which the transformed value will be written. This may be an object property or a virtual document property path. Generally it is a property of the target message used by the transformation. You must enter the target property.

   • Auxiliary Property—Optionally, specifies a value that is passed to the subtransform. The subtransform accesses the value as the aux variable.

   • Disabled—Optionally, specifies that the subtransform is disabled.

   • Description—Optionally, specifies a text description of the subtransform.

   Note:

   In the case of a subtransform with Create as new or copy, it is not necessary to have a pre-existing target object.

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:

   • Value — Specify 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.

   • Description — Specify an optional description.

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:

   • Code — Specify one or more lines of code in the scripting language specified for the transformation. For rules about expressions in this code, see “Syntax Rules.”

     Ensemble automatically wraps your code within a CDATA block. This means that you do not have to escape special XML characters such as the apostrophe (') or the ampersand (&),

     Also see the notes below.

   • Description — Specify an optional description.

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:

   • SQL — Specify a valid SQL SELECT statement.

     Ensemble automatically wraps your SQL within a CDATA block. This means that you do not have to escape special XML characters such as the apostrophe (') or the ampersand (&).

     Also see the notes below.

   • Description — Specify an optional description.