If you are building an integration in Boomi that connects to an external ActiveMQ broker (like version 5.19.x) while also utilizing Boomi’s internal Atom Queues, you might run into a fatal issue: your Atom crashes and refuses to restart.
Here is a breakdown of why this happens and the exact steps to fix it.
The Problem: Classpath Collisions
To connect to an external ActiveMQ broker, Boomi requires the specific ActiveMQ client driver (e.g., activemq-client-5.19.1.jar).
The standard Boomi documentation often suggests dropping custom JAR files directly into the Atom’s userlib or userlib/jms directories. However, if you are also using Atom Queues, this creates a massive problem.
Boomi’s Atom Queues are powered by an embedded version of ActiveMQ. When you enable them, Boomi automatically loads its own internal ActiveMQ JARs into the JVM. When you manually place your new activemq-client JAR into the userlib folder, Boomi tries to load both versions at startup.
The result? A fatal classpath collision (usually a java.lang.NoSuchMethodError or LinkageError). The Atom crashes, and the service will not restart until the conflict is resolved.
The Solution: Connector-Scoped Custom Libraries
To fix this, we need to stop loading the external ActiveMQ JAR globally and instead isolate it so it is only used when your specific JMS Connection is triggered. We do this using Boomi’s Custom Library feature.
Step 1: Resuscitate the Atom
First, you must remove the conflicting file to get your Atom back online.
Navigate to your Atom's installation directory on your server.
Go to the userlib or userlib/jms folder and delete the activemq-client-x.x.x.jar you manually placed there.
Restart your Boomi Atom service. It should now boot up successfully.
Step 2: Upload the JAR via the Platform
Stop putting files directly on the server. Let Boomi manage them.
Log into the Boomi platform.
Navigate to Settings > Account Information and Setup > Account Libraries.
Upload your activemq-client-x.x.x.jar file.
Step 3: Create the Custom Library Component
This is the crucial step where the magic happens.
Go to the Build tab and create a new Custom Library component.
Important: Set the Custom Library Type to Connector (Do not set it to General).
Select your specific JMS Connection from the Connector Type dropdown.
Select the JAR file you uploaded in Step 2 to include it in this library.
Step 4: Deploy
Save the Custom Library component.
Click Create Packaged Component and deploy it to your Atom's environment.
Why This Works
By setting the Custom Library type specifically to Connector, you are telling the Boomi JVM to load that specific activemq-client JAR only when that exact JMS connection is executing.
It keeps the JAR completely hidden from the rest of the Atom, preventing any conflicts with Boomi's internal Atom Queues. Your external connection works flawlessly, and your internal queues keep humming along!
Top comments (0)