JMS connector Listen and Acknowledge activities in transacted sessions in Jitterbit Design Studio

Purpose

A Transacted Session for a JMS Listen Activity allows a user to receive a message and work with its data, all within a transaction.

While the message is dispatched to the Jitterbit system, the broker (such as Apache ActiveMQ) locks the message so that other listeners cannot pick up the same message. When the user is satisfied with the processing of the message, they then use an Acknowledge Activity to notify the broker to remove the locked message from the queue (action: JBXCommit); in other words, the message was successfully processed and it is no longer needed.

There are cases where—while processing the message in the process flow—it becomes appropriate to release the message back to the queue so that it can be processed again or by a different listener. In those cases, the Acknowledge Activity can be used to let the broker know to release the lock on the message and let it be processed again (action: JBXRollback).

One such case is failure events. Typically, messages are dispatched to the Jitterbit System and then on to a Jitterbit private agent. While the operation runs through the business logic, it's possible that the agent may crash, the server may shut down, or an exception can occur. In any of these events, where an explicit JBXCommit was not sent back to the broker, the broker will rollback the message to avoid losing the data. Rollback means that the message is released back to the queue for re-processing by any active consumers of that queue.

Overview

To use transacted sessions with the Jitterbit JMS Connector, certain settings must be used. This document covers those settings and gives example scenarios showing how transactions may be used.

JMS Listen activity

The JMS Listen Activity is set up as described on JMS connector listen activities. To take advantage of client-based acknowledgment, the Transacted Session property must be set to True.

When a Transacted JMS Listener picks up a message, it will wait until:

• Receives an acknowledgment of JBXCommit:
  In this event, the session is committed and the message is removed from the broker.
• Receives an acknowledgment of JBXRollback:
  In this event, the session is rolled back, the lock is removed by the broker and the message is put back in the queue.
• Disconnection of Connection or Session to the broker (private agent stopped or crashed, server shutdown or crashed, etc.):
  In this event, the broker will perform an auto-rollback to preserve the message. The rollback will only happen as long as an explicit JBXCommit was not received by the broker.
• Acknowledgment Timeout is reached:
  In this event, a rollback acknowledgment is automatically sent to the broker to release the message back into the queue. This threshold is there to address cases where an operation gets stuck in a very long-running state that is outside of the acceptable range of message processing.

JMS Acknowledge activity

The JMS Acknowledge Activity allows controlling the fate of a message by sending either the JBXCommit or JBXRollback action. This is accomplished by specifying the activity in the Acknowledge Request Transformation.

• AcknowledgmentAction
  • Valid values: "JBXCommit" or "JBXRollback"
  • Case-insensitive, but must be spelled as listed
  • When entered in the transformation, include the opening and closing double quotes as it is a String type

• AcknowledgmentMessageID

  • Valid value: The JMS Message ID of the message received by the JMS Listener

  • This ID can be extracted and saved into a global variable upon receiving the message in the Listen Response Transformation (see screenshot)

    

  • The global variable can then be used for the AcknowledgmentMessageID property in the Acknowledge Request Transformation

Acknowledgment timeout

This property allows the user to specify the number of seconds after which a message is automatically rolled back. This prevents a message from being either stuck in processing forever or for more than an acceptable time frame. This property must be set in the Send/Publish Request Transformation for the JMS SendOrPublish Activity.

Examples

In these examples, we receive a message from a JMS Listen Activity, extract the JMS Message ID and save it in a variable. Then, we attach a JMS Acknowledge Activity as the "On Success" operation. If everything goes well with the JMS Listen Activity, the Acknowledge Activity simply commits the transaction (removing the message from the queue) as we are done processing that message. Similarly, another JMS Acknowledge Activity can be created and attached as the "On Failure" operation.

It is important to note that in many use-cases, the JMS Acknowledge should not be the very next operation in the "On Success" chain if there is additional work to be done with the message data. Instead, the JMS Acknowledge Activity should be added when all (or almost all) operations have successfully completed and we no longer need the message.

Variation 1

JMS Listener with Acknowledgment of Commit with OnSuccess and Acknowledgment of Rollback with OnFailure events.

Variation 2

This variation shows the use of an additional Business Logic operation that performs additional work with the message data. In this variation, if either the Listener or the business logic fails, a roll back will occur. If everything passes and the Business Logic finishes successfully, then it will commit the transaction.

Variation 3

This variation is very similar to the previous scenario. However, instead of committing automatically OnSuccess of the Business Logic operation, we use a call to the Jitterbit RunOperation() function in the Customer Logic Script to control exactly when in the script we want to commit:

RunOperation("<TAG>Operations/4. JMS Acknowledge (Commit)</TAG>", true);

and a similar call in the script if there is an error and the transaction needs to be rollbacked:

RunOperation("<TAG>Operations/3. JMS Acknowledge (Rollback)</TAG>", true);

This puts the onus on the developer to determine the conditions for success or failure. However, in certain use cases, this may be essential for the control desired.

Tips and suggestions

Setting acknowledgment timeout when not using the Jitterbit system

The acknowledgment timeout property is available (on the SendOrPublish Activity) if a message is being sent to a queue from within Jitterbit. But what if you want to control the timeout but have a different system inserting the messages in the queue? The solution: when creating a message, simply add an Integer property in the JMS Message with the key JBXAcknowledgmentTimeout and a value of the required timeout in seconds_._

JMS Messages are automatically being committed even without calling the Acknowledge Activity

Check to make sure the JMS Listener is configured with Transacted Session set to True. Confirm that there is no related Acknowledge Activity that is getting fired off.

Messages that fail keep getting picked up again and failing again

If—when a failure happens—messages are rolled back, they will be placed back in the queue. Since there is a listener on the queue, it will pick the message up and try to process it again. One solution is to tweak the broker's (for example, Apache ActiveMQ) Redelivery Policy to fine-tune delays and count for the Dead Letter Queue (DLQ).

Messages that keep failing eventually disappear

If a message's Delivery Mode was set to PERSISTENT_,_ then the message isn't getting lost. It has simply been moved to the Dead Letter Queue (DLQ), as configured by the broker. If a message's Delivery Mode was NON_PERSISTENT_,_ then the message was lost after a certain number of re-deliveries (if it exceeds the broker's setting for maximum redeliveries).