Skip to Content

Jitterbit's Harmony Listening Service


Jitterbit's Harmony Listening Service is an application service that runs on a Private Agent and is consumed by certain Cloud Studio connectors that have listening capabilities. The listening service provides asynchronous event handling for operations deployed on the agent.

Connectors with Listening Activities

The following connectors and activities use the listening service. These activities are released as a beta version. Feedback on bugs and suggested enhancements can be provided through your Customer Success Manager (CSM).


To use a listening activity, a Private Agent Group with one or more agents is required. Listening activities cannot be used with Jitterbit's Cloud Agent Groups. Not all connectors support the listening service.

These prerequisites must be met when the Private Agent Group contains a single agent or multiple agents:

For Private Agent Groups that contain multiple agents, these additional prerequisites must be met for the agents to communicate with each other:

  • The agent version must be 10.78 or higher (for 10.x Private Agents), or 11.8 or higher (for 11.x Private Agents).
  • All agents must have these ports available:
    • 5701
    • 5801
  • All agents must be within the same network group.
  • If there are \(N\) agents in the agent group, at least \((N / 2) + 1\) must be running for the listening service to work.
  • Set the value for agent.sdk_framework.listeners.eventsQueue in each agent's jitterbit-agent-properties.config file to be less than or equal to the number of processor cores on the agent host server. Alternatively, set agent.sdk_framework.listeners.matchEventsQueueToAvailableCores to true.

Once an operation is deployed, the Cloud Studio project must have the listening service enabled at both the operation level and the activity level as described in Enable the Listening Service on the Operation and Activity below. This is manual step performed at the time of project design or project management.

Enable the Listening Service on the Agent

The listening service is disabled by default on the agent and must be enabled manually following these steps:

  1. On each Private Agent, open in a text editor.

    This file is located in <JITTERBIT_HOME>/Resources/, where <JITTERBIT_HOME> is replaced with the Private Agent root directory.

  2. Add this line to the file to enable the listener framework:

  3. Restart the agent.


To fully benefit from the listening service's load-balancing and fault-tolerance features, it is recommended to have three or more Private Agents in the Agent Group.

Enable the Listening Service on the Operation and Activity

The listening service must be enabled on both the operation and the listening activity. The service can be toggled at the operation level from the Cloud Studio operation or at the operation or activity level from the Management Console Projects page as described below.

Cloud Studio Operation

Once an operation with a listener activity is deployed, an Events Disabled toggle appears at the bottom of the operation on the design canvas. By default, event listening is disabled.

Amazon SQS Receive Message Activity operation

To enable event listening for the operation, click the toggle:

consume topic activity events enabled

This action will also enable event listening on any listening activities that it contains, as indicated by the color of the listener icon in the top right of the activity:

  • A green listener icon listener enabled indicates listening is enabled for this activity.
  • A gray listener icon listener disabled indicates listening is not enabled for this activity.

Disabling event listening in an operation also disables event listening on any listening activities that it contains. Events received but not yet processed when listening is disabled are not lost and are processed as normal.

Management Console Projects Page

Once an operation with a listener activity is deployed, the operation and its listening activities are displayed on the Management Console Projects page in the Listeners tab:

projects listeners

  • Search: Enter any part of the activity, operation name, or listener status into the search box to filter the list of listening activities. The search is not case-sensitive.

  • Refresh: Click the Refresh icon refresh to refresh the list of listening activities.

  • Activity: The name of the listening activity using a shortened form of the connector activity type followed by the user-provided connection name.


    The user-provided name of the listening activity is not shown.

    Click the disclosure triangle disclosure triangle next to the activity to reveal the names of each operation that the activity is used in.

  • Listener Status: The state of listening is provided for each activity and operation. Click to toggle the listening state between On (enabled) and Off (disabled). Note:

    • Disabling event listening for an activity will automatically disable listening for all operations it is used within. However, enabling event listening for an activity does not affect the state of any operations it is used in.
    • Operations can be enabled and disabled for event listening individually.
    • Changing the state is synced with the Cloud Studio UI in both directions. That is, toggling the listening state in the Management Console affects the state in Cloud Studio. Similarly, enabling or disabling events on a Cloud Studio operation affects the state in the Management Console. A refresh may be required to update the display.

System Architecture

This diagram displays how an event message moves through the system architecture when using a single Private Agent:

listening service system architecture

  1. An operation containing a connector configured with an event listening activity is deployed and enabled for listening. One listening activity can be used in many operations and projects to receive the same event but process it differently.
  2. The listening service within the agent will start a listener for that operation.
  3. The listener will start actively listening for any event notifications from the endpoint.
  4. When an event happens at the endpoint, it publishes an event notification that can be received by its subscribers.
  5. The listener picks up the event notification message.
  6. If there is one agent in the agent group, the listener relays the event message to the operation. If the agent group contains the minimum number to allow full listening service capabilities, the event message is passed to the agent with the least workload.
  7. On receiving the event notification, the operation will trigger a downstream operation.

When the listening service is disabled, agents in an agent group communicate directly with Harmony. When enabled, and a minimum number of agent nodes are active, agents communicate with each other to form a cluster. The first agent registered is nominated as the cluster leader. The leader is responsible for receiving messages and distributing them to cluster members for processing. The cluster leader distributes the load among all the agents and ensures that no two agents process the same message.


Messages sent to an agent can be stored in a database. If the agent fails, the database provides a persistent store of messages that can be resent when the agent comes back online. Persistence using the internal PostgreSQL database is enabled by default for single-agent clusters. For clusters with more than one agent, persistence must be manually enabled as follows:

  1. On each Private Agent, edit <JITTERBIT_HOME>/Resources/ where <JITTERBIT_HOME> is replaced with the Private Agent root directory.
  2. Add these lines to the file:

  3. Restart the agent.

The settings agent.sdk_framework.queueStore.type=dbinternal and agent.sdk_framework.persistence.type=dbinternal cause the agent to use the local PostgreSQL database for persisting messages.

To configure an external JDBC-enabled database or Redis server, all agents within the agent group must use the following settings, where the database user has permissions to create, read, update, and delete data, and to create tables:

JDBC-enabled database persistent store settings (Example)


Redis persistent store settings (Example)



#Optional - pool configuration


Run the following command on the agent host server to get the status of the agent and the restore process:

curl localhost:46912/axis/v1/cdk/internal/members


Message not delivered

The cluster message delivery retry mechanism uses the following setting in the <JITTERBIT_HOME>/Resources/ file:


This is the number of minutes after which a retried message is deleted.

If set to -1, messages are never deleted and are stored indefinitely.

Restore after agent failure

If an agent fails with persistence enabled, you can manually restore it using these steps:

  1. On the failed agent's server, edit <JITTERBIT_HOME>/Resources/ and add the following:

  2. Start the agent.

  3. Use the REST API to query the status of the agent.
  4. When the status for leaderNodeState is RESTORED, stop the agent.
  5. Edit <JITTERBIT_HOME>/Resources/ and remove or comment out the line added in step 1.
  6. Start the agent.