Skip to main content
Previous section   

Migration Tool

The Migration Tool currently supports converting Cloverleaf lookup tables and transformations into components in an interoperability production.


The Migration Tool allows you to convert Cloverleaf tables and transformations into InterSystems lookup tables and DTL classes. The Migration Tool only works if the Cloverleaf transformation was designed to take in an HL7 message and convert it to another HL7 message.

The Migration Tool is designed to convert basic transformation logic into a DTL class, and is not intended to handle Cloverleaf custom code, loops, and routing rules. Basic TCL commands are converted, but most commands, such as loops, will have to be added to the DTL class after the migration. Code that is not migrated automatically is inserted as comments in the DTL code.

Set Up Java Environment

Before running the Migration Tool, you must:

  1. Install a current version of a Java Development Kit (JDK); it is possible to have multiple versions of a JDK on your system, using the path to the newest one for instructions in this guide. Though the examples in this guide use a JDK from Oracle, you can also use OpenJDK.

  2. Create a directory structure that contains a directory for the ANTLR jar file and a directory for .java files needed by the Migration Tool. For example, create the following directory structure:

    Copy code to clipboard
  3. Copy files from your InterSystems installation directory structure to the appropriate location in the new directory structure:

    1. Copy <InterSystems-install-dir>\dev\InteropTools\antlr\antlr-4.7.2-complete.jar to the c:\InterSystems\Migration directory.

    2. Copy the java files <InterSystems-install-dir>\dev\InteropTools\java\Cloverleaf\*.java to the c:\InterSystems\Migration\Cloverleaf\java directory.

  4. Open a terminal window for your OS and set the classpath to the antlr-4.7.2–complete.jar file. For example, run:

    set CLASSPATH=c:\InterSystems\Migration\antlr-4.7.2-complete.jar
    Copy code to clipboard

    For UNIX®, use EXPORT CLASSPATH. You do not have to set the classpath permanently.

  5. Using the full path to your JDK, compile the java files. For example, run:

    c:\java\jdk-13.0.1\bin\javac.exe c:\InterSystems\Migration\Cloverleaf\java\*.java
    Copy code to clipboard

Setup the Migration Tool

Before running the Migration Tool, you must create a working namespace in your InterSystems product and run a setup method.

  1. Open an InterSystems Terminal.

  2. Enter the following commands to change to the HSLIB namespace, create a new namespace for the migration, and change to that new namespace:

    Set $namespace = "HSLIB"
    Do ##class(HS.Util.Installer.Foundation).Install("MyNamespace")
    Set $namespace = "MyNamespace"
    Copy code to clipboard
  3. Run the setup tool:

    Do ##class(EnsLib.InteropTools.HL7.Setup).Run("Cloverleaf")
    Copy code to clipboard
  4. Answer the prompts of the setup tool.

    Prompt Enter:
    Classname A new classname used to hold settings defined by the setup tool. This is the class that is used to execute the migration. For example, MyPkg.MyCloverleaf.
    Java ClassPath The path and file reference to the ANTLR jar file. For example, c:\InterSystems\Migration\antlr-4.7.2-complete.jar.
    Path to java executable The path and file reference to the java executable on your machine. For example, c:\java\jdk-13.0.1\bin\java\java.exe.
    Path to java (*.java) files The path to the *.java files. Be sure to include a trailing \. For example, c:\InterSystems\Migration\Cloverleaf\java\

Alternatively, you can pass the parameters to the setup tool like:

set status =  ##class(EnsLib.InteropTools.HL7.Setup).Run("Cloverleaf","MyPkg.MyCloverleaf",
Copy code to clipboard

If this command fails, you can view any errors by entering Do $SYSTEM.Status.DisplayError(status).

Run Migration Tool

Because the Cloverleaf transformation files can reference data lookup tables, you should convert all of the Cloverleaf lookup tables before converting the transformation files.

Converting Lookup Tables

Depending on the Cloverleaf environment, you may have multiple lookup tables (*.tbl) to convert before converting the transformations. Each lookup table is converted into a persisted lookup table in your InterSystems product. You can run the Migration Tool on a single *.tbl file or a directory containing multiple files. To convert a Cloverleaf lookup table:

  1. In the InterSystems Terminal, change to the namespace that you created for the migration. For example:

    Set $namespace="MyNamespace"
    Copy code to clipboard
  2. If you want to convert multiple *.tbl files at once, put them in a directory and enter:

    set status = ##class(EnsLib.InteropTools.HL7.Cloverleaf).TableImport("c:\migration\tables\input_directory\","CL.Lookup.")
    Copy code to clipboard


    • input_directory contains the *.tbl Cloverleaf files. Be sure to end with a trailing \.

    • CL.Lookup. is a prefix to the InterSystems tables created with the lookup codes. For example, if a Cloverleaf file is codes.tbl, then the InterSystems lookup table would be This parameter can be any valid package name, but be sure to end with a trailing period ( . ).

    To check whether the conversion was successful, enter write status. It will display 1 if it was successful.

    To run the Migration Tool on a single Cloverleaf lookup file, enter:

    set status = ##class(EnsLib.InteropTools.HL7.Cloverleaf).TableImport("c:\migration\table\input.tbl","CL.Lookup.")
    Copy code to clipboard

Converting Transformations

Once you have converted the lookup tables used by the HL7 transformations, you are ready to convert the Cloverleaf transformation files into DTL classes. For each Cloverleaf transformation file (*.xlt):

  1. In the InterSystems Terminal, change to the namespace that you created for the migration. For example:

    Set $namespace="CLOVERLEAF"
    Copy code to clipboard
  2. For each Cloverleaf transformation file, enter:

    set status = ##class(MyPkg.MyCloverleaf).CodeWalk("c:\migration\transforms\cloverleaf_sample.xlt","/ClassName=Sample.DTL /TableGroupName=CL.Lookup. /Reprocess=1",.tOutput)
    Copy code to clipboard


    • MyPkg.MyCloverleaf is the name of the class you specified while setting up the Migration Tool.

    • c:\migration\transforms\cloverleaf_sample.xlt is the Cloverleaf transformation file.

    • /ClassName specifies the name of the new DTL class created by the Migration Tool.

    • /TableGroupName is the name of the lookup table prefix specified while migrating the Cloverleaf *.tbl files.

    • /Reprocess specifies whether to overwrite an existing DTL class. /Reprocess=1 overwrites the class.

    • .tOutput captures information generated by the Migration Tool.

    You can check for errors by entering write status. If the conversion was successfully, a 1 appears in the Terminal.

By default, the new DTL is compiled after being created by the Migration Tool. To prevent the DTL from being compiled, specify /BuildDTL=0 as a parameter of the CodeWalk method.

Previous section