Send HL7 Messages to AWS SQS with Mirth Connect

Introduction

Amazon Simple Queue Service (SQS) is a common landing point when HL7 data leaves the interface engine for the cloud: a queue decouples Mirth Connect from whatever consumes the data next, whether that is AWS Lambda, a container service, or an analytics pipeline. This guide sends HL7 messages from Mirth Connect, or its open-source fork OIE (Open Integration Engine), to an SQS queue.

It covers creating the queue, the IAM permissions Mirth needs, the AWS SDK for Java v2 library to add (just one jar, because the engine already ships the rest), a transformer script that sends each message, and the errors you are most likely to see. The script was tested on OIE 4.6.0 against a FIFO queue.

Create a Queue in AWS SQS

You can create an Amazon SQS queue through the AWS Management Console, the AWS CLI, or an AWS SDK. These steps use the AWS Management Console.

1. Navigate to SQS: Once logged in, find the “Services” menu and select “SQS” under the “Application Integration” section or use the search bar to find SQS.

2. Create a New Queue: Click the “Create queue” button. You will have the option to create a “Standard queue” or a “FIFO queue”. Standard queues offer maximum throughput, best-effort ordering, and at-least-once delivery. FIFO queues preserve the order messages are sent in and remove duplicates, which usually matters for HL7 (an A08 should not overtake the A01 it updates).

3. Configure Your Queue: Fill in the “Name” for your queue and configure additional settings as needed, such as message retention period, delivery delay, maximum message size, etc. Each setting has a tooltip explaining its function. For a standard queue, most default configurations work for basic needs. For a FIFO queue, you’ll need to provide a .fifo suffix in the queue name.

4. Set Permissions (Optional): You can adjust the queue’s permissions to allow other AWS accounts to send messages to the queue.

5. Finish the New Queue: Click the “Create queue” button at the bottom of the page, then copy the queue’s URL from its details page. The script below needs it.

Set Up the IAM Policy

Mirth needs permission to send to the queue. If Mirth runs on AWS (EC2, ECS or EKS), attach the policy to the instance or task role and skip access keys entirely. Otherwise, attach it to a dedicated IAM user whose access keys Mirth will use.

1. Navigate to the IAM Dashboard: In the AWS Management Console, find and select “IAM” under the Services menu to open the IAM dashboard.

2. Create a New Policy:

   • In the IAM dashboard, select “Policies” from the navigation pane on the left side.
   • Click the “Create policy” button.
   • Choose the JSON tab to manually enter the policy.

3. Enter the Policy JSON: In the JSON tab, use this policy document as a template. Replace arn:aws:sqs:*:*:YourQueueName with your queue’s ARN. Sending only needs sqs:SendMessage; the other actions let the same identity read the queue while you test.

   {
       "Version": "2012-10-17",
       "Statement": [{
           "Effect": "Allow",
           "Action": [
               "sqs:SendMessage",
               "sqs:ReceiveMessage",
               "sqs:DeleteMessage",
               "sqs:GetQueueAttributes",
               "sqs:GetQueueUrl"
           ],
           "Resource": "arn:aws:sqs:*:*:YourQueueName"
       }]
   }

4. Review and Name the Policy:

   • After entering the JSON policy, click “Review policy.”
   • Give your policy a name and description that clearly identifies its purpose, e.g., SQSReadWriteAccess.
   • Click “Create policy” to finalize.

5. Attach the Policy:

   • Navigate to “Roles” (or “Users”) in the IAM dashboard and select the role or user Mirth will use.
   • In the “Permissions” tab, click “Add permissions.”
   • Choose “Attach policies directly” and search for the policy you created by name.
   • Select the policy and add it.

Add the AWS SDK for Java v2 SQS Library

Mirth Connect and OIE already ship the AWS SDK for Java v2: the File connector’s Amazon S3 support uses it, and its jars live in the engine’s server-lib/aws folder. You only need to add the one module that isn’t there, SQS, in the same version.

1. Find the bundled version. List server-lib/aws in your Mirth or OIE installation and read the version off sdk-core-<version>.jar. On OIE 4.6.0 it is 2.15.28.
2. Download the SQS module in that version from Maven Central: https://repo1.maven.org/maven2/software/amazon/awssdk/sqs/<version>/sqs-<version>.jar (for OIE 4.6.0, sqs-2.15.28.jar).
3. Copy it into the custom-lib folder in the Mirth or OIE home directory. The [Default Resource] under Settings → Resources loads that folder; click Reload Resource there, or restart the service.

Don’t add the latest SQS jar, and don’t add a full set of newer SDK jars. The SQS module needs the SDK core it was built with, and the engine’s bundled core is older; mixing versions is the most common reason this integration fails (see Troubleshooting below). AWS ended support for the older v1 SDK (com.amazonaws) at the end of 2025, so new channels should use v2.

Install Our Sample Channel from GitHub

1. Download our sample channel xml from our GitHub repository: https://github.com/SagaHealthcareIT/MirthHL72SQS/blob/main/HL72SQS_channel.xml
2. Import the new channel into Mirth Connect.
3. Open the source transformer’s “Step to Send to SQS”. It holds the SDK v2 script shown below. Set your region and queue URL, and your access key and secret unless Mirth runs with an IAM role.
4. Deploy the new channel.

The Transformer Script (AWS SDK for Java v2)

// Build a small JSON document from the HL7 message
var hl7JsonObject = {};
hl7JsonObject.first_name = msg['PID']['PID.5']['PID.5.2'].toString();
hl7JsonObject.last_name = msg['PID']['PID.5']['PID.5.1'].toString();
hl7JsonObject.mrn = msg['PID']['PID.3'][0]['PID.3.1'].toString();
var json_hl7 = JSON.stringify(hl7JsonObject);

var sqsKey = "your access key";       // or $cfg('awsAccessKey') from the configuration map
var sqsSecret = "your secret key";    // or $cfg('awsSecretKey')
var sqsRegion = "us-east-1";
var queueUrl = "https://sqs.us-east-1.amazonaws.com/123456789012/hl7-adt.fifo";
var sqsMessageGroupId = "adt";        // FIFO queues only

// Create the SQS client once per deployment and reuse it
var sqs = globalChannelMap.get('sqsClient');
if (sqs == null) {
    sqs = Packages.software.amazon.awssdk.services.sqs.SqsClient.builder()
        .region(Packages.software.amazon.awssdk.regions.Region.of(sqsRegion))
        // Remove the next two lines to use the instance or task role on AWS
        .credentialsProvider(Packages.software.amazon.awssdk.auth.credentials.StaticCredentialsProvider.create(
            Packages.software.amazon.awssdk.auth.credentials.AwsBasicCredentials.create(sqsKey, sqsSecret)))
        .build();
    globalChannelMap.put('sqsClient', sqs);
}

var request = Packages.software.amazon.awssdk.services.sqs.model.SendMessageRequest.builder()
    .queueUrl(queueUrl)
    .messageBody(json_hl7)
    .messageGroupId(sqsMessageGroupId)                                        // FIFO queues only
    .messageDeduplicationId(channelId + '-' + connectorMessage.getMessageId()) // FIFO queues only
    .build();

var response = sqs.sendMessage(request);
logger.info('Sent to SQS, message id ' + response.messageId());
channelMap.put('sqsMessageId', response.messageId());
channelMap.put('json_hl7', json_hl7);

For a standard (non-FIFO) queue, delete the two lines marked “FIFO queues only”. The deduplication ID uses the channel and Mirth message IDs, so a message that is reprocessed within SQS’s five-minute deduplication window is not queued twice. Because the client is cached in the global channel map, redeploy the channel after changing the region or credentials.

Testing & Validation

Let’s test the new workflow by sending a sample HL7 message from Mirth Connect and then verifying it in the AWS Console. If you need a sample message to send or want to confirm the segments before queuing, you can inspect the HL7 message in our free browser-based HL7 Workbench.

1. Use the “Send Message” feature in the Mirth Connect Administrator Dashboard to send a sample message to AWS.
2. Check the channel messages; the server log shows Sent to SQS, message id ... for each one.
3. Now let’s check our new SQS queue:
   1. Click “Send and receive messages” in the queue screen at the top right.
   2. Click “Poll for messages” at the bottom.
4. Success! You’ve successfully routed an HL7 message to AWS SQS Service.

Troubleshooting

• Cannot call property builder in object [JavaPackage software.amazon.awssdk.services.sqs.SqsClient]: the SQS class did not load. Either the jar is not in custom-lib (or the resource was not reloaded), or its version does not match the engine’s bundled SDK. Use the SQS jar with the same version as sdk-core in server-lib/aws.
• AccessDenied (is not authorized to perform: sqs:sendmessage): the IAM policy is missing, attached to a different user or role, or names a different queue ARN.
• The request must contain the parameter MessageGroupId: the queue is FIFO and the group ID line was removed. For a standard queue the opposite applies: remove both FIFO lines.
• AWS.SimpleQueueService.NonExistentQueue (The specified queue does not exist): the queue URL is wrong, or the region in the script does not match the queue’s region.

Conclusion

HL7 is only one example of a data format you can route to SQS with Mirth Connect. Once in SQS, the data can feed AWS Lambda for serverless processing, Amazon S3 for durable storage, or Amazon DynamoDB, supporting applications such as patient monitoring, EHR data pipelines, and real-time alerting.

Have questions or need help working with AWS or Mirth Connect?