Mirth Connect is an incredibly helpful tool for executing health integrations. However, to fully leverage its capabilities and avoid common pitfalls, some experience is essential. In this article, we offer a series of tips and best practices for approaching integration, aimed to help you prevent future difficulties and improve the maintainability of your integrations.

Undoubtedly, these tips will save us a lot of time, effort and headaches.

Care for your integration architecture #

Clearly understand the flow before development begins #

When starting an integration, there’s a tendency to jump into developing channels and connectors without a comprehensive view of the required architecture on Mirth Connect.

It’s crucial to have a clear understanding of the integration’s information flow: types of information, recipient and sender systems, processing, etc. We can map this out using various types of diagrams like flowcharts, sequence diagrams, use cases, etc. Utilizing diagrams will help us identify unclear parts of our integration and reconsider aspects that we could potentially improve.

Diagrams can be created using a pencil and paper or their electronic counterparts such as Dia, yEd, Draw.io, or Microsoft Visio.

Decide each channel’s functionality #

Mirth Connect channels are powerful, yet it’s preferable to have more channels with smaller functions than fewer channels covering too much. It’s worth finding the right level of granularity. This strategy will give our integration system greater flexibility and scalability.

A good strategy is to group channels into different processing phases: those responsible for receiving from other systems, routing information, transforming information, or sending to other systems.

Choose how to implement functionality #

Once we understand how our integration works and how to organize its functionality, we can consider how to implement these communication flows.

It’s important to think about the design of the channels, connectors, and their communications. For example:

• Types of connectors and data types used for each channel.
• Connections to databases and file systems.
• Connections to external systems.

Don’t hesitate to revisit the first step and re-examine the flow, channel organization, or any other aspect of the integration. Reviewing these aspects during the design phase is infinitely easier than after development begins.

Separate specific processing from the integrated system #

It’s common to need data processing specific to the integrated application, and an easy solution might be to modify our Mirth Connect channel to handle this specific processing. However, this is not a good practice as it causes tight coupling between the integrated system and the integration engine. High coupling will lead to many headaches in the future when updating, adding functionality, or reusing system parts.

Consider that the integrated application might change in the future, and if we have specific processing for that system in our Mirth Connect channel, it won’t be easily reusable.

We recommend that all specific processing of the integrated system be done independently of the Mirth Connect integration engine. This can be achieved, for example, through web services or database stored procedures, treating it as if it were another external system from the integration engine’s perspective. This will give our Mirth Connect developments greater reusability as they will be independent of the integrated systems.

Use the ConfigurationMap #

As in other programming areas, another bad practice involves repeatedly using certain parameters and configurations as we develop channels and connectors.

Many of us have repeated database connections across channel configurations, filters, and transformers. Mirth Connect’s structure lends itself to this, and before we know it, the development is so advanced that it’s practically impossible to change any of these configurations.

A practical solution to avoid configuration repetition is the use of Mirth Connect’s ConfigurationMap. This map acts as a centralized repository for managing global variables and configuration parameters that affect all channels. Using the ConfigurationMap, we can easily modify common values in one place, simplifying the management and updating of our integrations.

This resource is highly useful for establishing:

• Database connections.
• Activation and deactivation of syntactic or semantic message validations.
• Log levels or alerts.
• Limits and frequencies of polling for database queries.
• HL7 versions used.
• Execution environments (debug, development, and production).
• Common retry policies and delivery guarantees.
• Patient identifiers for the health system.
• Configurations for acknowledgment of receipt and application (ACK).
• Management of asynchronous error notification.
• Control of inactivity in external systems.
• Configurations for proprietary periodic cleaning tasks.

Moreover, many of the aforementioned configurations should be structured at the level of the external system to be integrated. This is because different systems might use various HL7 versions, different ACK management, or different retry policies.

Use Code Templates for repeated functionality #

Like configurations, it’s also common and not advisable to repeat entire code snippets across channels and connectors as needed. For instance, validating mandatory fields in common segments of HL7 messages like the MSH, or extracting patient identifier information from the PID in different HL7 message types.

To minimize code repetition in Mirth Connect, code templates are invaluable. This feature lets us create and store code snippets and custom functions for use across multiple channels. By using code templates, we ensure consistency and reduce maintenance efforts, enabling the use of the same parametrized code in different messaging processing stages.

Some examples where we can use them:

• Database executions.
• Message validation.
• Message construction.
• Building web service calls.

A smart strategy here allows us to keep code well-organized and structured throughout all processing phases of our integration system. This isn’t easy to achieve when starting to work with Mirth Connect.

Be cautious with polling channels #

Mirth Connect has a category of readers for defining some connector types for sources, which are configured based on a polling frequency that determines how often the channel executes.

Well, it’s wise to follow some tips to avoid certain problems that these types of connectors can cause.

Limit database queries #

A connector might stop running due to a problem. Although Mirth Connect has its queue management, if there’s no limit on database queries, reactivating the connector could lead to overload with too much information, causing difficult-to-solve errors in our integration.

To prevent these cases, it’s important to set a limit on database queries for these types of connectors.

Reuse database connections #

There are cases where it’s necessary to set a very low polling frequency (less than a second) to work with real-time systems.

In these cases, Mirth Connect by default opens and closes a database connection each time we poll. This can cause issues with the database’s connection pool.

To improve this behavior, it’s possible to store database connections in Mirth Connect variables for reuse in these types of connectors.

Manage alerts carefully #

It’s common to include polling channel connectors in Mirth Connect alerts. Although this seems logical, it can have serious consequences.

If there’s a database failure or a change causing the query to fail with a high polling frequency, the system will trigger an alert every time it polls. Besides the consequences on the Mirth Connect server itself, this can overload the email system if alerts are reported via email.

To avoid these cases, we recommend managing alerts externally to Mirth Connect for these types of connectors.

Check the execution order of the Run On-Update Statement script #

A widely used feature in the source connector of polling channels is the Run On-Update Statement, which allows executing an UPDATE statement on database records affected in the main query, for example, to update their status.

Depending on the version of Mirth Connect, this script is executed before or after the connector’s transformers. Assuming one order of execution and being wrong can lead to unexpected problems when our integration is operational. Therefore, it’s crucial to ensure whether this script executes before or after the transformers.

Establish a strategy for Global Channel Configuration #

As previously mentioned in the article about channels and connectors, the global configuration of each channel (summary), among other things, allows defining the initial state of the channel after deployment (stopped or started) and the characteristics of message storage in the database (not storing filtered messages, only with errors, duration in days, etc.).

The advisable configuration varies depending on which processing phase the channel is in and the type of connector used for the source. These configurations must be defined when structuring the channels of our integration engine and strictly adhered to.

For example, a golden rule for us is:

All channels with reader sources in a routing phase should start stopped and without storing information in the database.

This way, we won’t overload the Mirth Connect database if there are errors in high-frequency polling and avoid dangerous situations in case the Mirth Connect service unexpectedly restarts. Like alerts, managing these types of errors should be done externally and controlled.

When establishing a strategy, we must also consider other best practices like storing only errors for a production environment or properly setting the number of days that messages will be stored (enough to correct them but not so many as to overflow the storage space).

All the above will depend on the initial analysis of the integration and the characteristics of the server where Mirth Connect is installed.

Use custom Java classes #

Another powerful feature in Mirth Connect is the ability to include custom-developed Java classes. This is necessary in some integrations to adapt certain connectors to special circumstances where the default connectors are not suitable.

This link to the Mirth Connect wiki explains how to do it.

Version the Mirth Connect code #

Mirth Connect allows the exporting of configurations, channels, alerts, global scripts, and code templates to XML format. These XML files, when structured appropriately, can be used to maintain version control of our Mirth Connect developments using version control tools such as GIT.

Conclusion #

In summary, following good practices and well-thought-out strategies will greatly enhance the efficacy and sustainability of integrations in Mirth Connect. From the clear structuring of integration architecture to the use of tools like ConfigurationMap and code templates, each step plays a crucial role in creating robust and maintainable solutions.

By adopting these practices, not only do we facilitate the development and management of our integrations, but we also prepare ourselves better to adapt to future changes and efficiently scale our solutions. Remember, investing time in planning and organizing your integrations in Mirth Connect not only saves effort in the long run but also ensures the quality and reliability of your integrated health systems.