1. Mirth Connect
2. Home
3. Upgrade Guides (Official)

Created by Gerald Bortis, last modified by Jacob Brauer on Jan 18, 2012

Welcome to Mirth Connect 2.0! For the most part, the upgrade process from 1.8.x is managed by Mirth Connect on startup (for example, updating of channel properties). However, there are a few steps that must be performed before upgrading to tell Mirth Connect where your database is, as well as some minor changes to some of the updated connectors. To upgrade your existing 1.8.2 installation to 2.0, please follow this simple guide.

Please read this!

Icon

It is important to follow all of the steps below, to ensure that you do not lose any data. We recommend printing this guide as a reference before starting the upgrade process.

Mirth Connect 2.0 now requires Java 1.6 or higher.

Icon

From here on, $MIRTH_HOME refers to the Mirth Connect installation directory.

Congratulations! Most of the upgrade process is done automatically when the appliance is upgraded. You may however need to update some of your channels. You will be notified before the upgrade of any channels that may require changes, which can be found in the Channel updates section.

1. Before you upgrade =====================

Certain libraries, properties, and configuration files will need to be manually copied over. Copy them to a location outside of your existing 1.8.x $MIRTH_HOME directory before uninstalling Mirth Connect 1.8.x. Once Mirth Connect 2.0 is installed, follow the directions in step 3, "After the upgrade".

1. Backup server configuration: Before proceeding, it's important that you backup your existing server configuration. This can be done through the Mirth Connect Administrator under Settings. The server configuration includes channels, code templates, alerts, and global scripts. User accounts will not be backed up.

2. server.id: Create a backup of $MIRTH_HOME/server.id

3. server.properties: Create a backup of $MIRTH_HOME/server.properties

4. Message Pruner settings: Make note of your current Message Pruner settings in the Plugins view of the Mirth Connect Administrator. These will not be migrated during the upgrade

5. Custom Java libraries (JAR files): If you added custom libraries, back them up from $MIRTH_HOME/lib/custom

6. Custom database drivers: If you have added custom database drivers, make sure to back them up in the above step. You will also need to back up your additions to $MIRTH_HOME/conf/custom/dbdrivers.xml

7. Custom extensions: Custom extensions will not be migrated during the upgrade. You will need to install an updated extension that is compatible with Mirth Connect 2.0

8. Java JVM parameters: If you have added any Java JVM parameters (wrapper.java.additional.1 property) or changed any of the default heap size settings in the $MIRTH_HOME/conf/wrapper.conf file, make note of these.

9. Logger settings: Make note of any changes you may have made to $MIRTH_HOME/conf/log4j.properties

10. Upgrading ============

Make sure that you have exited and stopped the Mirth Connect Administrator, Server Manager, and Server/Service before proceeding.

1. Create a backup of the $MIRTH_HOME/mirthdb
2. Run the Mirth Connect 1.8.x uninstaller. Make sure to remove the Mirth directory if it was not deleted.
3. Run the Mirth Connect 2.0 installer.
4. If you have chosen to install the Mirth Connect Service, stop it now using the Mirth Connect Server Manager.
5. Rename the mirthdb directory in your installation directory to mirthdb_old.
6. Restore the backup of your previous mirthdb directory into the new Mirth Connect 2.0 installation directory.

1. Create a backup of your database using your preferred database administration tool (ex. pgAdmin, MySQL Administrator).

2. Make note of the value of the database property in $MIRTH_HOME/conf/mirth.properties, and create a copy of $MIRTH_HOME/conf/database-SqlMapConfig.properties (ex. postgres-SqlMapConfig.properties, mysql-SqlMapConfig.properties).

3. Run the Mirth Connect 1.8.x uninstaller. Make sure to remove the Mirth directory if it was not deleted.

4. Run the Mirth Connect 2.0 installer.

5. If you have chosen to install the Mirth Connect Service, stop it now from the Mirth Connect Server Manager.

6. Restore the previous properties file to $MIRTH_HOME/conf/database, replacing the existing file.

7. After the upgrade ====================

8. server.id: Restore the file to $MIRTH_HOME/appdata (this location is the default and is specified during the installation process)

9. server.properties: Restore the file to $MIRTH_HOME. Note that the properties from this file will be restored on server startup and the file will be removed. If the file cannot be removed, stop the server and remove it manually.

10. Custom Java libraries (JAR files): Restore your custom libraries to $MIRTH_HOME/custom-lib

11. Custom database drivers: Make sure you restored your custom database drivers in the above step, and restore your changes to $MIRTH_HOME/conf/dbdrivers.xml. Note that a selectLimit attribute has been added for each driver. This is used to improve performance when retriving the database metadata (table and column names) from the connector panel. It is optional and can be set to an empty value.

12. Java JVM parameters: Add any Java JVM parameters that were in $MIRTH_HOME/conf/wrapper.conf to the mirthconnect_service.vmoptions (if using the service) or Mirth Connect.vmoptions (if using the stand-alone server) file, one property per line. For example:

    -Xmx512m
    -Dyour.property.name=value
    

13. Logger settings: Restore any changes to $MIRTH_HOME/conf/log4j.properties. Note that the file has been reorganized and some entries have been removed since Mirth Connect 1.8.2.

14. Start the server: This will upgrade the database table structure with any new tables and columns. Icon If you are starting the server with the Mirth Connect Server Manager you may get an error stating the Mirth Connect Service could not be started. This might happen if the server took too long to startup while migrating the database. You can safely ignore the error if there are no errors in the mirth.log file and you can successfully login to the Mirth Connect Administrator.

15. Custom extensions: Install new versions of any custom extensions

16. Message Pruner settings: Reconfigure the message pruner with your previous settings in the Plugins view of the Mirth Connect Administrator

Channel Statistics

Icon

If after upgrading the channel statistics for all channels are reset, you probably didn't copy over your server.id file. Don't worry, your message data has been preserved and is accessible through the message browser. To restore your previous statistics, restore the server.id file.

These are changes to channels that are not done automatically during the upgrade process. Only channels with certain connectors or deprecated code references are affected by these updates.

The HTTP connector (both the listener and sender) has been rewritten for Mirth Connect 2.0 to provide new features and to be more compatible with the HTTP and REST standards. Most of the properties are automatically upgraded as part of the channel migration on server startup, but there are some changes that must be made manually.

1. In channel scripts (transformers and scripts) references to channel variables must be changed from msg['Variable'] to msg['Parameters']['Variable']. This also requires you to enable the Headers, Query, and Body option.
2. References to the message payload must been changed from msg['$payload'] to msg['Content'].
3. The Append Payload Variable has been renamed to Headers, Query, and Body. This should be checked if you need the header information included as part of your message, which will be wrapped in XML. Otherwise, the message content will be the body of the message only.
4. Rename any references from msg['$payload'] to msg['Content'].

1. If you are using POST or PUT, and you did not previously define a $payload variable, your channel will be disabled until you fill in the Content text field.

The SOAP connector (both the listener and sender) has been rewritten for Mirth Connect 2.0 using JAX-WS to provide new features and to be more compatible with web service standards. It has also been renamed to the Web Service connector. Most of the properties are automatically upgraded as part of the channel migration on server startup, but there are some changes that must be made manually.

1. This connector should be upgraded automatically, but there are some new features you should take note of, like the ability to host your own web service and HTTP authentication.
2. Clients invoking the default accept message web service method will need to update the envelope they are sending to work with the new Web Service Listener. If you are sending to this listener with Mirth Connect, simply regenerate your envelope and repopulate the argument. If you need to manually change your envelope, you can find the new default below:

   <soapenv:Envelope xmlns:ns="http://ws.connectors.connect.mirth.com/" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
     <soapenv:Header/>
     <soapenv:Body>
       <ns:acceptMessage>
         <arg0>? (string)</arg0>
       </ns:acceptMessage>
     </soapenv:Body>
   </soapenv:Envelope>
   

1. If you have a SOAP Sender, settings like your WSDL URL and SOAP Envelope will be migrated, but your channel will be disabled.
2. Edit your destination and click the Get Operations button. This should populate your Service and Port fields. Note that these fields can also be edited manually.
3. The SOAP Action field can be entered manually, if required. Its value will be placed in the HTTP request header as the SOAPAction field. This was always sent in 1.8.2, so it might be required for some web services. See this for more information.

Several Mirth Connect reference methods have been deprecated in Mirth Connect 2.0. If you are using any of them your channels should continue to work, but you will see an error message in the log every time they are called. You should update your calls to them as soon as possible, before they are removed completely (currently planned for 2.2).

1.8:
ChannelController.getInstance().getChannelName(channelId)

2.0:
ChannelController.getInstance().getDeployedChannelById(channelId).getName()

1.8:
ChannelController.getInstance().getChannelId(channelName)

2.0:
ChannelController.getInstance().getDeployedChannelByName(channelName).getId()

1.8:
router.routeMessage(channelName, message, useQueue, synchronised)

2.0:
router.routeMessage(channelName, message, useQueue)

1.8:
router.routeMessageByChannelId(channelId, message, useQueue, synchronised)

2.0:
router.routeMessageByChannelId(channelId, message, useQueue)

1.8:
Entities.getInstance()

2.0:
XmlUtil

1.8:
${encoder.encode()}

2.0:
${XmlUtil.encode()}

1.8:
SerializerFactory.getHL7Serializer()  // Used the strict parser by default

2.0:
SerializerFactory.getHL7Serializer(true, false, false)  // First parameter enables the strict parser

If you are importing channels that have been exported from Mirth Connect 2.0 RC2, you must manually modify the channel XML and change the following elements:

2.0 RC2:
<inboundTemplate>
<outboundTemplate>

2.0:
<inboundTemplate encoding="base64">
<outboundTemplate encoding="base64">

If you do not modify these elements, your inbound and outbound templates will be the Base64 encoded template from the original channel.

Document generated by Confluence on Nov 11, 2019 08:40

Atlassian