HL7 Mirth® Migration Tool
This utility uses methods of the HS.HC.InteropTools.Mirth.SetupOpens in a new tab class to convert a ® Connect project into an InterSystems IRIS for Health or InterSystems Health Connect interoperability project.
The Mirth export must be from Mirth Connect 4.5.2. If the export is not from that version, you will need to import it into Mirth Connect 4.5.2 and then re-export it, before you can use this utility. Please refer to the Mirth Connect documentation for instructions.
The general workflow is:
-
Generate a Channel Complexity report that assesses the complexity of each channel in the Mirth® Connect project. Some channels may be too complex to convert automatically into business processes, and this report helps you determine which ones may need to be coded by hand.
-
Run the conversion tool, which converts as many channels as possible into interoperability business processes, as follows:
-
Source Connectors: File and TCP are converted to Business Services.
-
Destination Connectors: File and TCP are converted to Business Operations.
-
Routers will connect the generated Business Services and Operations that are converted from the same Mirth Channel.
-
Channels with Transformers or Filters are not automatically converted and must be converted manually.
-
If the Mirth export includes non-HL7 v2 components, they will not be converted. This includes FHIR components.
Note:This step can be executed in a way that enables you to manually convert certain Mirth® Channels into business processes before loading the converted project into your interoperability production. However, if you are confident that no Mirth Channels will require manual conversion, you can load the converted project automatically.
-
-
If necessary, create business processes to replace channels that contain Filters or Transformers.
-
If you did not load the converted project automatically, load the converted project into your interoperability production, using the Production Generator, as follows:
set status = ##class(EnsLib.InteropTools.HL7.ProductionGenerator).Load("<TargetDir>/config.csv","<TargetDir>/items.csv",.errors)-
TargetDir is the target directory of the conversion tool.
-
config.csv and items.csv are the output files from the conversion tool.
-
Channel Complexity Report
A Channel Complexity report, filename mirthexportanalysis.html, assesses the complexity of each channel in the Mirth® Connect project. It contains sections describing Channels, Source Connectors, Destination Connectors, Transformers, and Filters. You can use this report to get a high-level overview of the Mirth Connect configuration and its complexity.
To generate the Channel Complexity report use this command:
set status = ##class(HS.HC.InteropTools.Mirth.Setup).GenerateReport("<pMirthExportFile>","<pOutputDir>")
-
pMirthExportFile is the full path to the Mirth® Connect project to be assessed.
-
pOutputDir is the full path to the directory in which the report will be stored as mirthexportanalysis.html.
To interpret the Channel Complexity report:
-
Easy channels have no Filters or Transformers.
These channels will be automatically converted when you convert the project.
-
Medium channels have some Filters and/or Transformers, but none of them are JavaScript.
Since Filters and Transformers are not automatically converted, business processes related to these channels may need to be created by hand to do their work in HealthConnect or IRIS for Health.
-
Hard channels have some JavaScript Filters or Transformers.
Since Filters and Transformers are not automatically converted, business processes related to these channels may need to be created by hand to do their work in InterSystems HealthConnect or InterSystems IRIS for Health.
Converting the Project
The conversion tool will automatically convert all Easy channels into business processes for use in an InterSystems interoperability production. You can choose whether or not to load them automatically into your interoperability production.
To run the conversion tool, use this command:
set status = ##class(HS.HC.InteropTools.Mirth.Setup).Run("<pMirthExportFile>","<pPackageName>","<pOutputDir>",<pGenerateProduction>)
The full path to the Mirth® Connect project to be assessed.
The filename to be used for the new interoperability project. This is the package under which you want all generated interoperability classes to be included.
Classes that already exist within this package will not be deleted, so best practice is either to use a new package name or to delete existing classes each time you run this utility.
The full path to the directory in which the new interoperability project will be stored.
The conversion tool generates the following output files in this directory:
-
conversion.html describes which components were successfully converted and which were not.
-
config.csv contains configuration settings. These generally will not require modification, but you can edit them, for example, if you want additional control over naming schemes.
This is one of the input files loaded by the Production Generator when you load the converted project into your interoperability production.
-
items.csv contains the business processes that were generated from Mirth® Channels. You may wish to edit this file in various ways. See Converting Mirth® Channels Manually for details.
This is one of the input files loaded by the Production Generator when you load the converted project into your interoperability production.
A boolean value that determines whether the converted project should be automatically loaded via the production generator. If the Channel Complexity report indicated that the project includes only Easy channels, you may wish to run the production generator automatically; in that case, set this value to 1. If one or more channels will need to be converted by hand, set this value to 0; you can run the production generator explicitly after creating business processes to replace more complex channels.
The default value is 1.
Automatic Conversion Specifics
This section describes the specifics of what settings get converted automatically and how they are processed/modified during the conversion process.
Source Connectors are converted to business services; Destination Connectors are converted to business operations. For a business service and business operation to be created, a Source Connector and a Destination Connector in the same Channel must both be supported for conversion.
The default name of a generated business service is the name of the Channel containing the converted Source Connector.
The default name of a generated business operation is the name of the converted Destination Connector.
All default names are stripped of spaces and special characters.
A Source Connector with a properties class of com.mirth.connect.connectors.file.FileReceiverProperties will be converted to a business service of class EnsLib.HL7.Service.FileServiceOpens in a new tab.
The following settings are automatically converted:
| Mirth Setting Name | IRIS Business Service Name or Adapter Setting Name |
| host | filePath |
| fileFilter | fileSpec
Note:
Patterns in this setting are not automatically converted and will need to be manually adjusted. |
A Destination Connector with a properties class of com.mirth.connect.connectors.file.FileDispatcherProperties will be converted to a business operation of class EnsLib.HL7.Operation.FileOperationOpens in a new tab.
The following settings are automatically converted:
| Mirth Setting Name | IRIS Business Operation or Adapter Setting Name |
| host | filePath |
| OutputPattern | Filename
Note:
Patterns in this setting are not automatically converted and will need to be manually adjusted. |
A Source Connector with a properties class of com.mirth.connect.connectors.tcp.TcpReceiverProperties will be converted to a business service of class EnsLib.HL7.Service.TCPServiceOpens in a new tab.
The following settings are automatically converted:
| Mirth Setting | IRIS Business Service or Adapter Setting |
| port | Port |
A Destination Connector with a properties class of com.mirth.connect.connectors.tcp.TcpDispatcherProperties will be converted to a business operation of class EnsLib.HL7.Operation.TCPOperationOpens in a new tab.
The following settings are automatically converted:
| Mirth Setting Name | IRIS Business Operation or Adapter Setting Name |
| remoteAddress | IPAddress |
| remotePort | Port |
A Source Connector with a properties class of com.mirth.connect.connectors.jms.JmsReceiverProperties will be converted to a business service of class EEnsLib.JMSPEX.Service.
The following settings are automatically converted:
| Mirth Setting Name | IRIS Business Service or Adapter Setting Name |
| connectionFactoryClass | ConnectionFactoryName |
| clientId | ClientID |
| brokerURL | URL |
| destinationName | QueueOrTopicName |
A Destination Connector with a properties class of com.mirth.connect.connectors.jms.JmsDispatcherProperties will be converted to a business operation of class EnsLib.JMSPEX.OperationOpens in a new tab.
The following settings are automatically converted:
| Mirth Setting Name | IRIS Business Operation or Adapter Setting Name |
| connectionFactoryClass | ConnectionFactoryName |
| clientId | ClientID |
| brokerURL | URL |
Converting Mirth® Channels Manually
This section describes circumstances under which you may need to make manual changes to the items.csv output file.
-
You may wish to add entries for components that were not converted automatically. See conversion.html for components that are marked “no”. Channels that contain Transformers and Filters are not automatically converted, for example.
-
You may wish to edit service names and operation names in this file, as they cannot be edited in IRIS.
-
You might also wish to delete certain entries; for example, IRIS handles logging automatically, so you may want to delete logging entries from Mirth®.
-
You may wish to customize settings.
-
This is a good time to edit OperationType and ServiceType, if desired. These map to the IRIS business operation class and the IRIS business service class, respectively.
