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:
-
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.
-
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.
-
Open an InterSystems Terminal.
-
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"
-
Run the setup tool:
Do ##class(EnsLib.InteropTools.HL7.Setup).Run()
-
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:
-
In the InterSystems Terminal, change to the namespace that you created for the migration. For example:
Set $namespace="MyNamespace"
-
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.")
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.
-
Open an InterSystems Terminal.
-
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"
-
Run the setup tool:
Do ##class(EnsLib.InteropTools.HL7.Setup).Run()
-
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:
-
In the InterSystems Terminal, change to the namespace that you created for the migration. For example:
Set $namespace="MyNamespace"
-
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.")
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.
-
Open an InterSystems Terminal.
-
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"
-
Run the setup tool:
Do ##class(EnsLib.InteropTools.HL7.Setup).Run()
-
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:
-
In the InterSystems Terminal, change to the namespace that you created for the migration. For example:
Set $namespace="MyNamespace"
-
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.")