Skip to Content



The Agents page of the Management Console allows Harmony organization administrators (members of a role with the Admin organization permission) the option to set up Private Agents (formerly known as Local Agents) as on-premises runtime servers that execute your integration operations. All agents in an Agent Group will be synchronized the same way so that they execute operations consistently. When you create Private Agents, you will also need to associate them with a Private Agent Group. For more information, see Agents > Agent Groups.

To access the Agents page, log in to the Harmony Portal, then click the Harmony Portal menu in the top left to hover over Management Console > Agents and select Agents:

management console agents agents


Make sure you are accessing the desired organization, which can be changed in the top navigation bar (see Changing the Selected Organization in Harmony Portal).

Manage Agents

Administrators of the organization manage the agents for that organization.

View Agents

The top section of the Agents page contains a table that shows all of the Private Agents (formerly known as Local Agents) within the organization:


This table displays information about each Private Agent, including its IP address, operating system, agent version, agent status, and the available actions you can take. You can sort this table by clicking on any column header with the exception of the Action header.

Agent Status

The Private Agents table displays statuses for agents based on their current state. This section describes statuses that can be associated with agents.


By default, newly added Private Agents will have a status of Unregistered and will not be available for executing operations until the agent software is downloaded and installed. After the agent's installation, the Unregistered status functions similarly to the Stopped status.


If deregisterAgentOnDrainstop is set to true in the agent's register.json file, it will be set to the Unregistered status when drain stopped. The DeregisterAgentOnJVMShutdown setting in the [AutoScaling] section of the jitterbit.conf file covers another instance where agents can become Unregistered.


The Starting status indicates that the agent is transitioning to the Running status.


The Running status indicates that the agent is running and has the ability to execute operations. By default, a heartbeat is sent from the agent every 5 minutes to Harmony to verify that the agent is still accessible. If the agent heartbeat is not detected at within the expected interval, the agent is set to the Unknown status.


The agent heartbeat interval can be changed by modifying the agent.heart.beat.interval setting in the agent's file.


The Stopping status indicates that a drain stop was requested for the agent. The agent is set to the Stopping status during a waiting period (120 seconds by default) prior to transitioning to the Stopped or Unregistered status depending on the agent's configuration settings.

While in the Stopping status, the agent will continue to finish running operations. Any operations still running after the drain stop is complete will be cancelled.


The Stopped status indicates that the agent is stopped and unable to execute operations, but is still registered with Harmony.


The Unknown status indicates that the agent is in an unknown state. It is caused by the agent not communicating with Harmony using its heartbeat within the expected interval (5 minutes by default) while in the Running status.

View Conflicts with the Jitterbit Configuration File

If you have remote agent configuration enabled (Organizations page under Actions > Edit Organization Policies) and there is a conflict between the remote agent configuration and local agent configuration file, you will see attachment icons next to a Private Agent name.

Note that if remote agent configuration is enabled, then the remote agent configuration file overrides any settings in the local agent jitterbit.conf configuration file. Thus, these warnings are provided for your information only, and may be expected in circumstances such as when you have made changes to the configuration file remotely via the Agents > Agent Groups page.

  • Hover over the attachment icon to see a short description of conflicting values.

  • Click on the attachment icon to view the detailed description of any conflicting values.



When you enable remote agent configuration, the current agent configuration (excluding the local PostgreSQL cache database information and local predefined global variables) will be read and stored in the cloud so that you can view and edit it remotely. Once you enable remote agent configuration, any changes you make manually to the local jitterbit.conf file located on the agent will not take effect.

If you wish to disable remote agent configuration and again be able to edit the local jitterbit.conf file manually, you can do so on the Organizations page under Actions > Edit > Organization Policies by unchecking the Enable remote Agent configuration checkbox. However, note that you will lose the current remote agent configuration that was stored in the cloud. After agent services are restarted, your agent will read from the local jitterbit.conf file.

Add Agents and Downloading Agent Software

To add a new Private Agent, click attachment. In the Add Agent dialog box, enter a name for your new agent, and use the Associate Group dropdown to select an existing Private Agent Group you would like to associate with your new Private Agent.


These special characters are not allowed in the agent name: < > # % { } | \ / ^ ~ [ ] ` ; , : ? @ = &.


If you do not yet have an existing Private Agent Group you would like to associate, click attachment to display the Add Agent Group dialog box where you can enter a name for your new Agent Group, an optional description, and choose whether to enable Cloud Logging. For more information about this option, see Agents > Agent Groups.

You should now see your new Private Agent listed in the table of agents. By default, it will have a status of Unregistered and will not be available for runtime processing until you download and install the agent software on the Private Agent.

Prior to downloading and installing Private Agents, please review these pages:

To download the agent software, use the Action dropdown on the far right and select the appropriate download option for your system.


For further instructions on downloading and installing Private Agents, see these pages:

You can also add agents and download agent software via the Agents > Agent Groups page.


You may be limited to the number of agents you can create based on your subscription plan. If you require more agents, please contact your Customer Success Manager.

Edit and Removing Agents

To edit or remove a Private Agent, use the Action dropdown on the far right. These options will be disabled if your agent is currently in the Running status. The agent must be in the Stopped, Unregistered, or Unknown statuses in order to edit or remove the agent.

  • Choose Edit to change the name of your Private Agent.
  • Choose Remove to delete the Private Agent from the organization.

Stop Agents and Downloading Agent Logs

To stop the Private Agent or to download agent logs, use the Action dropdown on the far right. These options will be disabled if your agent is currently in the Stopped or Unregistered status. The agent must be in the Running status in order to stop the agent or to download agent logs.


  • Choose Drain Stop to stop the Private Agent. The agent continues processing existing operations but refuses to accept new ones. When an agent drain stop is initiated, the agent waits 180 seconds for any APIs to finish running before the drain stop is completed. For Private Agents, the wait time can be configured within the file by setting agent.drainstop.api.wait equal to the desired number of seconds.


    If you use Drain Stop, make sure you have access to the Private Agent if you would like to restart the agent later. The agent cannot be restarted remotely from the Management Console and must be done manually on the Private Agent.

  • Choose Download Agent Log to open a prompt to select logs for detailed troubleshooting and auditing purposes. Check the logs you wish to download and click Submit to begin the download.


These logs can either be accessed via the Management Console as shown above or be stored on local file storage devices such as file shares or SFTP and accessed from within a firewall. The Agent Groups and agents do not automatically synchronize these with the cloud, as they typically include business data. By using your own storage devices, you can keep that data within a firewall or private cloud infrastructures.

By default, an Agent Group will store logs for 1 to 14 days depending on the type of log. The Agent Group can be configured to clean up this data at other intervals using the CleanupRules defined in the agent home installation directory. See Cleaning Up Drive Space.

Drain Stop Status

Drain Stop status is reported in the agent log. The log includes each phase of the stopping of the agent, the operations still running, and other details. The default Windows location for the agent log is C:\Program Files (x86)\Jitterbit Agent\log. The default Linux location for the agent log is /opt/jitterbit/log.

Open the agent log and search for entries with Drainstop (one word) or drain stop (two words) as seen here:

2020-03-23 17:03:29,021 +0000 request handler thread #2  INFO org.jitterbit.integration.server.messaging.agent.service.manager.AgentDrainStopManager:94 - Drainstop(109780): Initializing Agent drain stop
2020-03-23 17:03:40,038 +0001 request handler thread #2  INFO org.jitterbit.integration.server.messaging.agent.service.manager.AgentDrainStopManager:221 - Drainstop(109780): Stopping the heart beat service
2020-03-23 17:03:40,038 +0001 request handler thread #2  INFO org.jitterbit.integration.server.messaging.agent.service.manager.AgentDrainStopManager:237 - Drainstop(109780): Updating the status of the agent as stopped

View Installed Plugins

Plugins are available to any agent within the Agent Group. This is in order to synchronize all plugins across an Agent Group. For more information on Jitterbit-provided plugins or to add custom plugins, see Customizations > Plug-ins.

View Plugins

The bottom section of the Agents page contains a tab for Installed Plug-ins. This table displays all plugins for the Private Agent selected in the top portion of the page:


In this table, you can see a description of the plugin, the author, version, type, and available actions you can take. You can also sort this table by clicking on any column headers except Action.

View Manifest Files

To view the manifest file associated with a particular plugin, use the Action dropdown on the far right:


The XML file should display or download.

<JitterbitPlugin SpecVersion="1.0">
<PipelinePlugin SpecVersion="1.0">
<DisplayName>Jitterbit - Run Command</DisplayName>
<Author>Jitterbit, Inc.</Author>
<Description>Runs a command with optional arguments.</Description>
 Set the variable $Command with the command you want to run
 Set the variable $Arguments with the arguments to your command. Set it to an empty string if the command takes no arguments.
<DataElements All="false">
<DataElement Name="Command" Type="string" Required="true">
The command (executable, script etc) to run. This command can not have a user interface and can not wait for user input. If it does the plugin will just hang forever.
<DataElement Name="Arguments" Type="string" Required="false">
<Documentation>Optional arguments.</Documentation>
 The value describes where the plugin can be applied, e.g. Target, Source, WebServiceMethod
         Relative is where in relation to the pipeline position this plugin is executed
<PipelinePosition Optional="true" Relative="Pre" ExecutionOrder="50">Source</PipelinePosition>
<PipelinePosition Optional="true" Relative="Post" ExecutionOrder="50">Source</PipelinePosition>
<PipelinePosition Optional="true" Relative="Pre" ExecutionOrder="50">Target</PipelinePosition>
<PipelinePosition Optional="true" Relative="Post" ExecutionOrder="50">Target</PipelinePosition>
<PipelinePosition Optional="true" Relative="Inside" ExecutionOrder="50">Script</PipelinePosition>