Skip to main content

Creating Data Transformations

This topic describes generally how to create and edit data transformations for interoperability productions.

You can also visit Online Learning to try Creating a Data TransformationOpens in a new tab.

Building DTLs During a Migration

If you intend to migrate to InterSystems IRIS for Health from other vendors, and you have a body of existing source and target messages, you can streamline the process of creating the necessary DTLs:

  • You can automatically generate a starting DTL that performs the simpler transformations.

  • You can compare the target messages output from the generated DTL to the original target messages, quickly identifying message segments that require attention.

To build a post-migration DTL using an existing body of source messages and target messages, follow the instructions at DTL Generator.

Creating a Transformation

To create a transformation:

  1. If you do not have the Data Transformation Builder page already open, then in the Management Portal, select Interoperability > Build > Data Transformations.

  2. Click New.

    If you are currently viewing a transformation and you have made changes but have not yet saved them, InterSystems IRIS® prompts you to confirm that you want to proceed (which will discard those changes).

    InterSystems IRIS then displays a dialog box where you can specify the basic information for the transformation.

  3. Specify some or all of the following information:

    • Package (required)—Enter a package name or click the arrow to select a package in the current namespace.

      Do not use a reserved package name; see Reserved Package Names.

    • Name (required)—Enter a name for your data transformation class.

    • Description—Enter an description for the data transformation; this becomes the class description.

    • Source Type and Source Class—Specifies the type of messages that this transformation will receive as input.

      Choose one of the following:

      Or click the search icon for Source Class and then select the class.

    • Source Document Type (applicable only if the messages are virtual documents)—Enter or choose the document type of the source messages. You can choose any type defined in the applicable schemas loaded into this namespace.

    • Target Type and Target Class—Specifies the type of messages that this transformation will generate as output. See the choices for Source Type and Source Class.

    • Target Document Type (applicable only if the messages are virtual documents)—Enter or choose the document type of the target messages. You can choose any type defined in the applicable schemas loaded into this namespace.

    Apart from Package and Name, you can edit all these details later.

  4. Specify details on the Transform tab. See Specifying Transformation Details.

  5. Then add actions as needed.

Opening an Existing Transformation

To open a transformation:

  1. Click Open.

    If you are currently viewing a transformation and you have made changes but have not yet saved them, InterSystems IRIS prompts you to confirm that you want to proceed (which will discard those changes).

  2. Click the package that contains the transformation.

    Then click the subpackage as needed.

  3. Click the transformation class.

  4. Click OK.

Specifying Transformation Details

For a transformation, the Transform tab displays details that apply to the transformation as a whole. You may or may not have already specified some of these details. Other details can be edited only here. These details are as follows:

  • Name (read-only)—Complete package and class name of the data transformation class.

  • Create—Specifies how the transformation should create the target message. Choose one of the following:

    • new—Create a new object of the target class (and type, if applicable), before executing the elements within the data transformation. This is the default.

    • copy—Create a copy of the source object to use as the target object, before executing the elements within the transform.

    • existing—Use an existing object, provided by the caller of the data transformation, as the target object. See the following subsection.

  • Source Class—Specifies the type of messages that this transformation will receive as input. For details, see Creating a Transformation.

  • Source Document Type (applicable only if the messages are virtual documents)—Specifies the document type of the source messages.

  • Target Class—Specifies the type of messages that this transformation will generate as output. For details, see Creating a Transformation.

  • Target Document Type (applicable only if the messages are virtual documents)—Specifies the document type of the target messages.

  • Language—Specifies the language you will use in any expressions in this DTL. This can be python or objectscript.

  • Report Errors—Specifies whether InterSystems IRIS should log any errors that it encounters when executing this transform. If you select this option, InterSystems IRIS logs the errors as Warnings in the Event Log. InterSystems IRIS also returns a composite status code containing all errors as its return value. This option is selected by default.

  • Ignore missing source segments and properties—Specifies whether to ignore errors caused by attempts to get field values out of absent source segments of virtual documents or properties of objects. If you select this option, InterSystems IRIS suppresses these errors and does not call subtransforms where the named source is absent. This option is selected by default.

    You can precisely control the behavior by including tests and conditional logic branches to confirm that any required elements are present.

  • Treat empty repeating fields as null—Specifies whether InterSystems IRIS skips the following actions for repeating fields when the fields are empty:

    • foreach actions—If you select this option, InterSystems IRIS does not execute foreach actions on repeating fields that are empty.

    • assign actions—If you select this option, InterSystems IRIS does not execute assign actions on repeating fields if you use shortcut notation to indicate that both the source and target fields are repeating fields, and the source field is empty. For example, if the source.{PV1:AdmittingDoctor()} field is empty and you select this option, then InterSystems IRIS does not execute the following action:

      <assign value='source.{PV1:AdmittingDoctor()}' property='target.{PV1:AdmittingDoctor()}' action='set'.

      However, InterSystems IRIS does execute the following similar action since the target field is not a repeating field:

      <assign value='source.{PV1:AdmittingDoctor()}' property='target.{PV1:AdmittingDoctor(1)}' action='set' />

      This option is cleared by default.

  • Description—Description of the data transformation.

Using the Create existing Option

For Create, the existing option enables you to specify the target as an existing object, which results in a performance improvement. This option applies when you invoke a series of transformations programmatically (or perform other sequential processing). You would use this option in cases like the following scenario:

  • You have three transformations that you want to perform in sequence:

    1. MyApp.ADTTransform—Uses the new option for Create.

    2. MyApp.MRNTransform—Uses the existing option for Create.

    3. MyApp.LabXTransform—Uses the existing option for Create.

  • You invoke the transforms as follows:

    do MyApp.ADTTransform.Transform(message,.target)
do MyApp.MRNTransform(target,.newtarget)
do MyApp.LabXTransform(newtarget,.outmessage)

Undoing a Change

To undo the previous change, click the Undo button .

Saving a Transformation

To save a transformation, do one of the following:

  • Click Save.

  • Click Save As. Then specify a new package, class name, and description and click OK.

  • Click Compile. This option saves the transformation and then compiles it.

Compiling a Transformation

To compile a transformation, click Compile. This option saves the transformation and then compiles it.

Deleting a Transformation

To delete a transformation, you use a different page in the Management Portal:

  1. In the Management Portal, click Interoperability > List > Data Transformations.

  2. Click the row that displays its name.

  3. Click the Delete button.

  4. Click OK to confirm this action.

See Also

Adding and Editing ActionsNext section
Previous sectionIntroduction to the New DTL Editor
FeedbackOpens in a new tab