Skip to main content

HL7 Migration Tool

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

Currently, you can migrate transformations from:

In all cases, first make sure you have JRE installed.

Prerequisite: Set Up Java Environment

Before setting up or running the HL7 Migration Tool, you must:

  1. Install a current version of a Java Runtime Environment (JRE). Note that it is possible to have multiple versions of a JRE on your system, using the path to the newest one for instructions in this guide.

  2. If the JAVA_HOME environment variable doesn’t reflect a valid version, specify the full path for the Java JRE as needed in the instructions below.

Cloverleaf

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 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"
    
  3. Run the setup tool:

    Do ##class(EnsLib.InteropTools.HL7.Setup).Run()
    
    
    
  4. Answer the prompts of the setup tool.

    Prompt Enter:
    Please enter a valid type Cloverleaf
    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:\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.exe.
    Path to java (*.java) files The path to the *.java files. Be sure to include a trailing \. For example, c:\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",
"c:\Migration\antlr-4.7.2-complete.jar",
"c:\java\jdk-13.0.1\bin\java.exe")

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"
    
  2. If you want to convert multiple *.tbl files at once, put them in a directory and enter:

    set status = ##class(MyPkg.MyCloverleaf).TableImport("c:\migration\tables\","CL.Lookup.")
    

    Where:

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

    • c:\migration\tables\ contains the 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 CL.Lookup.codes. 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(MyPkg.MyCloverleaf).TableImport("c:\migration\tables\input.tbl","CL.Lookup.")
    

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="MyNamespace"
    
  2. For each Cloverleaf transformation file, enter:

    set status = ##class(MyPkg.MyCloverleaf).CodeWalk("c:\migration\transforms\cloverleaf_sample.xlt","/ClassName=Sample.DTL /SourceDocType=2.7:ACK /TargetDocType=MyCustom2.7:ACK /TableGroupName=CL.Lookup. /Reprocess=1",.tOutput)
    

    Where:

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

    • /SourceDocType is the schema and DocType structure of the incoming HL7 message. To view available schemas and DocType structures, open the Management Portal and navigate to Interoperability > Interoperate > HL7 v2.x > HL7 v2.x Schema Structures. If you need to add the schema in your InterSystems product, the Message Analyzer can help.

    • /TargetDocType is the target schema and DocType structure. The SourceDocType is being transformed into the TargetDocType.

    • /TableGroupName is the name of the lookup table prefix specified while migrating the Cloverleaf lookup table files. If the transformations did not use lookup tables, you can omit this parameter.

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

eGate

The Migration Tool allows you to convert eGate tables and transformations into InterSystems lookup tables and DTL classes. The Migration Tool only works if the eGate 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 custom code, loops, and routing rules. Code that is not migrated automatically is inserted as comments in the DTL code.

Set Up 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"
    
  3. Run the setup tool:

    Do ##class(EnsLib.InteropTools.HL7.Setup).Run()
    
  4. Answer the prompts of the setup tool.

    Prompt Enter:
    Please enter a valid type eGate
    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.MyEGate.
    Java ClassPath The path and file reference to the ANTLR jar file. For example, c:\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.exe.
    Path to java (*.java) files The path to the *.java files. Be sure to include a trailing \. For example, c:\Migration\eGate\java\

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

set status =  ##class(EnsLib.InteropTools.HL7.Setup).Run("eGate","MyPkg.MyEGate",
"c:\Migration\antlr-4.7.2-complete.jar",
"c:\java\jdk-13.0.1\bin\java.exe")

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

Run Migration Tool

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

Converting Lookup Tables

Depending on the eGate environment, you may have multiple lookup tables 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 file or a directory containing multiple files. To convert an eGate lookup table:

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

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

    set status = ##class(MyPkg.MyEGate).TableImport("c:\migration\tables\","eGate.Lookup.","*.txt")
    

    Where:

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

    • c:\migration\tables\ contains the eGate lookup table files. Be sure to end with a trailing \.

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

    • *.txt specifies the file extension of the eGate lookup table files.

    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 eGate lookup file, enter:

    set status = ##class(MyPkg.MyEGate).TableImport("c:\migration\tables\input.txt","eGate.Lookup.")
    

Converting Transformations

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

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

    Set $namespace="MyNamespace"
    
  2. For each eGate transformation file, enter:

    set status = ##class(MyPkg.MyEGate).CodeWalk("c:\migration\transforms\eGate_sample.tsc","/ClassName=Sample.DTL /SourceDocType=2.7:ACK /TargetDocType=MyCustom2.7:ACK /TableGroupName=eGate.Lookup. /Reprocess=1",.tOutput)
    

    Where:

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

    • c:\migration\transforms\eGate_sample.tsc is the eGate transformation file.

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

    • /SourceDocType is the schema and DocType structure of the incoming HL7 message. To view available schemas and DocType structures, open the Management Portal and navigate to Interoperability > Interoperate > HL7 v2.x > HL7 v2.x Schema Structures. If you need to add the schema in your InterSystems product, the Message Analyzer can help.

    • /TargetDocType is the target schema and DocType structure. The SourceDocType is being transformed into the TargetDocType.

    • /TableGroupName is the name of the lookup table prefix specified while migrating the eGate lookup table files. If the transformations did not use lookup tables, you can omit this parameter.

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

DataGate

The Migration Tool allows you to convert DataGate tables and transformations into InterSystems lookup tables and DTL classes. The Migration Tool only works if the DataGate 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 custom code, loops, and routing rules. Code that is not migrated automatically is inserted as comments in the DTL code.

Set Up 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"
    
  3. Run the setup tool:

    Do ##class(EnsLib.InteropTools.HL7.Setup).Run()
    
  4. Answer the prompts of the setup tool.

    Prompt Enter:
    Please enter a valid type DataGate
    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.MyDataGate.
    Java ClassPath The path and file reference to the ANTLR jar file. For example, c:\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.exe.
    Path to java (*.java) files The path to the *.java files. Be sure to include a trailing \. For example, c:\Migration\DataGate\java\

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

set status =  ##class(EnsLib.InteropTools.HL7.Setup).Run("DataGate","MyPkg.MyDataGate",
"c:\Migration\antlr-4.7.2-complete.jar",
"c:\java\jdk-13.0.1\bin\java.exe")

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

Run Migration Tool

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

Converting Lookup Tables

Depending on the DataGate environment, you may have multiple lookup tables 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 file or a directory containing multiple files. To convert a DataGate lookup table:

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

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

    set status = ##class(MyPkg.MyDataGate).TableImport("c:\migration\tables\","DataGate.Lookup.","*.txt")
    

    Where:

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

    • c:\migration\tables\ contains the DataGate lookup table files. Be sure to end with a trailing \.

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

    • *.txt specifies the file extension of the DataGate lookup table files.

    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 DataGate lookup file, enter:

    set status = ##class(MyPkg.MyDataGate).TableImport("c:\migration\tables\input.txt","DataGate.Lookup.")
    

Converting Transformations

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

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

    Set $namespace="MyNamespace"
    
  2. For each DataGate transformation file, enter:

    set status = ##class(MyPkg.MyDataGate).CodeWalk("c:\migration\transforms\DataGate_sample.tsc","/ClassName=Sample.DTL /SourceDocType=2.7:ACK /TargetDocType=MyCustom2.7:ACK /TableGroupName=DataGate.Lookup. /Reprocess=1",.tOutput)
    

    Where:

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

    • c:\migration\transforms\DataGate_sample.tsc is the DataGate transformation file.

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

    • /SourceDocType is the schema and DocType structure of the incoming HL7 message. To view available schemas and DocType structures, open the Management Portal and navigate to Interoperability > Interoperate > HL7 v2.x > HL7 v2.x Schema Structures. If you need to add the schema in your InterSystems product, the Message Analyzer can help.

    • /TargetDocType is the target schema and DocType structure. The SourceDocType is being transformed into the TargetDocType.

    • /TableGroupName is the name of the lookup table prefix specified while migrating the DataGate lookup table files. If the transformations did not use lookup tables, you can omit this parameter.

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

FeedbackOpens in a new tab