Introduction to DTL Tools

Background

A data transformation creates a new message that is a transformation of another message. It is common for a production to use data transformations, to adjust outgoing messages to the requirements of the target systems.

A DTL transformation is a transformation that you create and edit the transformation visually in the DTL editor, available in either the Management Portal or Studio. The DTL editor is meant for use by nontechnical users. The term DTL represents Data Transformation Language, which is the XML-based language that Ensemble uses internally to represent the definition of a transformation that you create in this editor.

You can invoke a data transformation from a business process, another data transformation, or a business rule. Note that there is overlap among the options available in business processes, data transformations, and business rules. For a comparison, see “Comparison of Business Logic Tools” in Developing Ensemble Productions.

Introduction to the Data Transformation Builder Page

The Data Transformation Builder page enables you to create, edit, and compile DTL transformations.

To access this page in the Management Portal, click Ensemble > Build > Data Transformations.

When you display this page, it shows the last transformation you opened in this namespace, if any. This page has the following areas:

• The ribbon bar that the top displays options you can use to create and open DTL transformations, compile the currently displayed transformation, change the zoom display of the diagram, and so on.

  For information on these options, see the chapter “Creating Data Transformations.”

• The upper part of the left area displays the DTL diagram. The next section provides details on this area.

• The lower part of the left area displays a table that lists the actions defined in the DTL transformation. When Ensemble uses this transformation, it performs these actions in order as listed here.

• The right area displays three tabs:

  • Transform — Enables you to edit information about the transformation. For details, see “Specifying Transformation Details,” later in this book.

  • Action — Enables you to edit details of the selected action. Later chapters describe the details for assign actions and for other kinds of actions.

  • Tools — Enables you to launch a wizard to test the currently displayed transformation. For details, see “Testing Data Transformations,” later in this book.

• You can resize these three areas.

Introduction to the DTL Diagram

The following shows the DTL diagram for the sample DTL class Demo.ZenService.Dtl.OperationToResponseReportOpens in a new tab, which is in the ENSDEMO namespace:

Note the following points:

• The left area displays the source message. The header above the column displays the name of the source message class, and the boxes in the column display properties of the source message.

• The right area displays the target message in the same way.

• The top area includes a scroll button for each of these areas.

• The diagram shows connectors that represent actions within the transformations. The actions displayed here copy values from source properties to target properties.

• The middle area (the blue column) displays an icon on each connector line. The purpose of these icons is to enable you to select the connectors more easily. (You can select a connector line anywhere on its length, but it is easier to click the icons shown in this middle area.)

The following shows another example (not included in ENSDEMO):

In this case, the source and target classes are more complex. Note the following additional points:

• The FavoriteColors property is defined as list of strings. This property is displayed here with parentheses () at the end of its name.

  In this example, Allergies is another collection property.

• The Address property is defined as an object that has the Street, City, and ZipCode properties. Notice that the box for this property contains a triangle inside it.

  In the left column, this property is displayed in expanded mode, so that you can see the properties. The triangle in the box is not solid and is pointing down.

  The right column, this property is displayed in collapsed mode. The triangle in this box is solid and is pointing to the right.

• For the Address properties, the connector is shown with a dashed line on the side where the Address is collapsed. This indicates that there are hidden sub-properties on this side of the assign action.

The following shows the DTL diagram for another sample, Demo.HL7.MsgRouter.ORMLastNameTransformOpens in a new tab, which is also in the ENSDEMO namespace. In this case, the source and target messages are virtual documents (which are discussed in Ensemble Virtual Documents).

Notice that all the properties displayed are either collection properties (shown with parentheses at the ends of their names) or contain sub-properties. It is common for virtual documents to be complex as shown in this example. Also note that in the column header, below each class name, there is an additional label. These labels indicate the DocType of the source and target messages. For information on DocType, see Ensemble Virtual Documents.

Controlling the Display

You can control the display of the Data Transformation Builder page in multiple ways:

• You can click a View option in the ribbon bar:

  

  Use the buttons to view both the transform diagram and the action list in the left pane of the page, or instead to collapse the section you do not want to see.

• You can select a zoom option from the drop-down list in the ribbon bar. By default, this list displays 100%. Click a value in the list to shrink or enlarge the size of the DTL diagram.

• Use the scroll bars in the header area of the DTL diagram, as described in the previous section.

• Collapse and expand the display of properties, as described in the previous section.

Introduction to the Data Transformation List Page

The Data Transformation List page lists the data transformation classes defined in the current namespace. To access this page, click Ensemble > List > Data Transformations.

This page lists two kinds of transformations:

• DTL transformations are displayed in blue. You can double-click one to open it in the Data Transformation Builder.

• Custom transformations are displayed in black. These classes are based on Ens.DataTransformOpens in a new tab and do not use DTL. You must edit these in Studio.

To use this page, select a transformation class and then click one of the following commands in the ribbon bar:

• Edit — (DTL transformations only) Click to change or view the data transformation using the Data Transformation Builder.

• Test — Click to test the selected transformation class using the Test Transform wizard.

  For details, see the chapter “Testing Data Transformations,” later in this book.

• Delete — Click to delete the selected transformation class.

• Export — Click to export the selected transformation class to an XML file.

• Import — Click to import a data transformation that was exported to an XML file.

You can also export and import these classes as you do any other class in Ensemble. You can use the Globals page of the Management Portal (select System Explorer > Globals) or use the Export and Import commands on the Tools menu in Studio.

Other Tools

You can also invoke a data transformation programmatically, which can be useful for testing purposes. For details, see the chapter “Testing Data Transformations.”

Also, because data transformations are classes, you can edit them and work with them in the same way that you do any other class. For example, you can edit them in Studio, although the Ensemble documentation does not discuss this in any detail.

Using Data Transformations

You can invoke a data transformation from the following parts of a production:

• From another DTL data transformation. See “Adding a Subtransform Action,” in the chapter “Adding Other Actions.”

• From a BPL business process. See “<transform>” in the Ensemble Business Process Language Reference.

• From a business rule. See “Selecting the Transformation and Target of a Send Action” in Developing Business Rules.

• From a custom business process or a custom DTL transformation. To do so, execute it programmatically as described in the chapter “Testing Data Transformations.”