Skip to end of metadata
Go to start of metadata


This page covers system requirements and instructions on downloading, installing, configuring, restarting, upgrading, rolling back, and uninstalling the Harmony Private Agent on a Windows system. Prior to installation, we recommend reviewing Agent Groups High Availability and Load Balancing and Private Agents Best Practices Tech Talk.

NOTE: As of Jitterbit Harmony release 10.34, 32-bit Private Agents will no longer be available for download. If you are currently using a 32-bit agent and want to follow our recommendation of staying on the current release, download a 64-bit agent and perform an upgrade. Instructions for upgrading to a 64-bit agent are available. This change does not affect Cloud Agents.

Known Issues

  • Windows Private Agents: Unable to install 64-bit agent with Two-Factor Authentication (TFA)
    • Summary: Installing a 64-bit Windows Private Agent fails if TFA is active.
    • Additional Info: The installer displays an error dialog.
    • Workaround: Temporarily disable TFA and install the 64-bit Windows Private Agent. After installation, enable TFA.

System Requirements

Best Practices

  • Supported systems: Install the Private Agent on a tested and supported system as listed on this page. For optimal results, we recommend you follow these prerequisites and requirements for the operating system, PostgreSQL database, and hardware.
  • High availability and load balancing: Prior to installation, review the recommendations for high availability (active/active) and load balancing as described in Agent Groups High Availability and Load Balancing.
  • Server installation: For production environments, we recommend installing the Private Agent on a server. Agent installation on a desktop machine is recommended only for development, quality control, or testing environments.
  • Clean installation: Do not install the Private Agent on a server that is already running another database. The agent installs and runs its own PostgreSQL database. Running the agent on a server that is already running an Oracle or SQL Server database may cause performance issues.
  • Same timezone: We recommend that all agents in a Private Agent Group have the same timezone. Because the timezone of configured schedules is dependent upon the Private Agent timezone, schedule runs may be unpredictable if the timezones are different.
  • Uninstalling: Before uninstalling, we recommend you copy the config files and security certificates of your current installation in the event you want to reinstall with the same configuration at a later time.

Operating System Requirements

The Windows version of the Jitterbit Harmony Private Agent requires a 64-bit OS and is supported for these versions:

  • Windows 8 and 8.1
  • Windows 10

  • Windows 11
  • Windows Server 2012 and 2012 R2
  • Windows Server 2016
  • Windows Server 2019
  • Windows Server 2022

NOTE: Jitterbit does not test against or support software versions no longer supported by Microsoft.

Prerequisite Software Requirements

The Windows version of the Jitterbit Harmony Private Agent requires:

  • Windows updates: Install all Windows security and "critical" updates prior to installing or upgrading Jitterbit Harmony Private Agents. There are known Microsoft issues when installing on systems that don’t have the latest updates (such as KB2966870 and KB3140245).

  • .NET: Microsoft .NET Framework 4.5 or above may be required.

  • NTFS: The install partition must be NTFS-formatted.

  • Compression: Do not use Windows compression on the Jitterbit folder, PostgreSQL folder, or temp folder on the machine where the Jitterbit Private Agent is installed and running. Using Windows compression will drastically slow down processing of Jitterbit operations and transformations.

CAUTION: Jitterbit recommends that a Windows local Administrator account be used to install the agent.

WARNING: If installing an agent that is prior to version 10.3, please review Troubleshoot Error 1722 prior to installing the agent.

Java Runtime Environment

The Jitterbit Harmony Agent package is bundled with a 64-bit version of the Java 8 Runtime Environment (JRE) and does not require a separate Java runtime. Jitterbit automatically installs the required Java Runtime Environment 8.x specifically for Jitterbit to use so that it does not conflict with other Java installations that may already be installed.

Unlimited Strength Java Cryptography Extension Requirement

For the agent to securely communicate with resources such as servers, the Java Runtime Environment used by the agent should be using the Java Cryptography Extension (JCE) with Unlimited Strength Jurisdiction Policy Files. If you are using the JRE that is shipped with the agent, it is using JCE with Unlimited Strength Jurisdiction Policy Files.

If you substitute a different JRE for the one shipped with the agent, you will need to replace the policy files included with the JRE with Unlimited Strength Jurisdiction Policy Files, if it is not already using them. To install the Java Cryptography Extension Unlimited Strength Jurisdiction Policy Files:

  1. Go to the Oracle website to download the ZIP file containing Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files.
  2. Unpack the ZIP to extract the local_policy.jar and US_export_policy.jar JAR files.
  3. Copy and replace the existing JAR files found in <JITTERBIT_HOME>\jre\lib\security, replacing <JITTERBIT_HOME> with the path to your Private Agent root directory.
  4. Restart the Jitterbit Private Agent.

PostgreSQL Requirements

PostgreSQL is installed as part of the Harmony Private Agent installation. This instance of PostgreSQL is for use only with and by Jitterbit.

  • Do not install PostgreSQL separately prior to installing Jitterbit. The Jitterbit installation automatically installs the 64-bit, 9.6.11 version of PostgreSQL with the PostgreSQL 9.3 ODBC driver. (Private Agent upgrades do not upgrade an existing PostgreSQL installation to this version; they are left as-is.)
  • Do not use a plus sign (+) as part of the PostgreSQL password when installing a Harmony Private Agent. The maximum number of characters for a PostgreSQL password is eight (8). We recommend that you not use accented characters (such as é) or any of these characters in the PostgreSQL password: + @ $ % & [] {} () , ; ? ^ = £
  • Do not have any other databases configured or running on the Jitterbit PostgreSQL instance.
  • Do not use the Jitterbit PostgreSQL database/server as part of any Jitterbit operations and transformations.
  • Do not use Windows compression on the Jitterbit folder, PostgreSQL folder, or temp folder on the machine where Jitterbit is installed and running. Using Windows compression will drastically slow down processing of Jitterbit operations and transformations.
  • PgBouncer may be required for high-load environments. Jitterbit Harmony Linux Private Agent version 10.6 and later and Jitterbit Harmony Windows Agent versions 8.21 and later automatically install PgBouncer. If you already have an existing installation of PgBouncer and experience issues upgrading, contact support for assistance.

Hardware Requirements

These are the minimum requirements for hardware and virtual machines for Jitterbit Harmony Private Agents:

  • Quad-core processor
  • 8 GB RAM
  • 50 GB available hard drive space; this includes space for the software, parallel processing, and temporary storage that can grow quite large while running an operation

  • Minimum of 100 MB/s (megabytes per second) transfer rate on the hard drive
  • High-speed Internet connection
  • A direct hardware installation or an installation on a virtual machine from VMWare, VirtualBox, Amazon AWS, or Rackspace that is configured for the specific requirements outlined above
  • Optimal configuration of the system and overall environment; if not optimally configured, sporadic and unpredictable problems can result from poor disk IO, limited/out of memory, limited/out of disk space, power failures, and/or abrupt system restarts

  • Access to outbound port 443 (HTTPS) to communicate with Harmony. Port 443 is normally allowed by corporate server firewalls.

  • Access to specified inbound ports as needed; generally, inbound ports do not need to be opened

It is recommended that the Jitterbit API platform be used for inbound messages or data. Where a Private Agent is used to receive a message directly (such as an outbound message from Salesforce) in lieu of the Jitterbit API platform, then the inbound ports 443 (with SSL) or 46909 (HTTPS) could be opened. Custom ports may be used for specific requirements if they are redefined in the Private Agent configuration and are allowed by any corporate firewall.

Downloading the Private Agent

These instructions on downloading a Windows Private Agent assume you have already created an Agent Group and Private Agent(s) for your organization within the Management Console. Refer to Agents > Agent Groups and Agents > Agents for more information.

  1. Log in to the Jitterbit Harmony Portal and go to the Management Console > Agents > Agent Groups
  2. In the upper portion of the screen, select the Agent Group row. The lower half of the screen should now list the Available Agents within the selected Agent Group.
  3. In the lower portion of the screen, select the agent row. Then click the Action dropdown on the far right and select Download for Windows EXE.
  4. The Windows agent executable can be downloaded, stored locally, and reused as needed for any additional Private Agents as they are added.

Installing a Private Agent

Installing more than one agent in an Agent Group automatically allows for high availability. Installing multiple agents in an Agent Group also automatically allows for load balancing. See Agent Groups High Availability and Load Balancing for additional information. Before installing, check that all software requirements and notices have been met.

On each agent within the Agent Group:

  1. Run the downloaded Windows agent executable file, and follow the prompts.
  2. At the Login Credentials prompt, enter your Jitterbit Harmony credentials (the email address and password you use to log on to

    CAUTION: If your organization and account use single sign-on (SSO), your normal SSO credentials will not work. You must use Harmony credentials to install Private Agent(s). See Installing a Private Agent in Registering and Logging In Using Jitterbit Harmony SSO for more information.
  3. Follow the prompts to select your organization, agent, etc. The available options are those you have already configured from the Management Console.

    NOTE: You must be a member of an organization role that has either Admin or Agent-Install permissions. See Organizations and the section on Managing Permissions, Roles, and Members for more information.
  4. At the Select Install Mode prompt, choose the mode depending on whether you are installing PostgreSQL or have an existing installation of PostgreSQL that you would like to use:

    • Quick Install (Recommended): Installs all components needed to run a Private Agent including a PostgreSQL agent database and driver. Use this option if you have never installed PostgreSQL or a Private Agent on this computer before, or if you have properly uninstalled all components following the instructions in Uninstalling a Private Agent.

      NOTE: When you are prompted to set up your PostgreSQL password, note that the password must conform to your system's password policies regarding length and complexity.
    • Advanced: Installs a Private Agent and configures a Private Agent database to use an existing installation of PostgreSQL. You will need to provide your PostgreSQL credentials. You may wish to use this option if you want to manage passwords separately within each application.

  5. After installation, the agent should start automatically. You can check the status of the agent in the Management Console (Menu > Agents), which should be "Running."

    NOTE: It can take more than a minute for the Jitterbit Harmony Agent to start up and register with Jitterbit Harmony.
    WARNING:  If you experience errors related to PostgreSQL, see Troubleshoot PostgreSQL ErrorsIf you experience an Error 1722 message, see Troubleshoot Error 1722. If you are still experiencing any problems during installation, please contact support.

Restarting a Private Agent

Restarting agent services is required whenever you have made changes to your agent configuration. Restarting the agent can also be a good troubleshooting step if you are experiencing issues, which may be resolved upon restarting.

Though the agent can be stopped and then restarted directly from the machine where the Private Agent is installed, it is best if it is first stopped from the Management Console using the "Drain Stop" command, and then restarted using the commands on the Private Agent machine itself.

The "Drain Stop" command will wait for a period of time to complete existing operations and refuse to accept new ones. Long-running operations may be canceled instead of completing.

NOTE: When an agent drain stop is initiated, the agent will now wait 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.

Once stopped, the agent can only be restarted manually from the Private Agent machine directly.

  1. From the Management Console, select "Drain Stop" from the menu for the agent. The agent will then stop.
  2. The agent can then be restarted from the machine where the Private Agent is installed, either by:
    • From the Windows Start Menu: Run "Start Jitterbit Services" to restart the service; or
    • From the Private Agent installation directory: Run StartServices.bat to restart the service.

Once the Private Agent is started successfully, the status of the agent in the Jitterbit Harmony Management Console (Menu > Agents) will be "Running." You can also use Windows Services to check that the Jitterbit Services are all up and running:

If—after restarting the agent—you see that not all Jitterbit services have restarted, you should try stopping and restarting the Private Agent. If a second attempt does not resolve the situation, you should contact support.

Upgrading a Private Agent

WARNING: Upgrading from a 32-bit to a 64-bit Windows Private Agents

  • Existing 32-bit agent versions must be uninstalled prior to upgrading (see instructions for Windows Uninstall).
  • Existing PostgreSQL and PostgreSQL driver (psqlODBC or pODBC) installations must be uninstalled.
  • Existing 32-bit ODBC drivers are not supported.

NOTE: If you are upgrading an existing 64-bit version agent to a higher 64-bit version agent, you do not need to uninstall the existing agent before upgrading. 

Upgrading the Private Agent on Windows can be done using similar instructions as for Installing a Private Agent. Follow the prompts to upgrade your Private Agent installation. You do not need to uninstall an existing agent prior to upgrading.

If you are upgrading an existing 64-bit version agent to a higher 64-bit version agent, you do not need to uninstall the existing agent before upgrading. 

A Private Agent takes a very short time to upgrade—on the order of three minutes—depending on the server. If having any outage is a concern, you can use high availability (two or more agents) and have no downtime. If your current subscription does not have additional agents available for this, contact your Customer Success Manager (CSM).

  1. Back up the configuration files and security certificates (optional; see Uninstalling a Private Agent below).
  2. Check if you need to uninstall the agent first, based on the installed agent type: is it 32-bit (located in C:\Program Files (x86)\Jitterbit Agent) or 64-bit (located in C:\Program Files\Jitterbit Agent)?
  3. Install the new version of the agent (see Installing a Private Agent above).
  4. To use the backup files (optional):
    1. Stop agent services (see Restarting a Private Agent above).
    2. Place the saved config files and security certificates in the installation directory.
    3. Start agent services (see Restarting a Private Agent above).
WARNING: If you experience an error related to PostgreSQL, see Troubleshoot PostgreSQL Errors. If you experience an Error 1722 message, see Troubleshoot Error 1722. If you are still experiencing any problems during the upgrade, please contact support.

Rolling Back a Private Agent

It is not expected to need to revert to a previous version of a Private Agent. However, should it be required, these are the steps:

  1. Back up your config files and security certificates (optional, see Uninstalling a Private Agent below).
  2. Uninstall the agent (see Uninstalling a Private Agent below).
  3. Remove all Jitterbit-related files (see Uninstalling a Private Agent below).
  4. Install the selected version of the agent (see Installing a Private Agent above).
  5. To use your backup files (optional):
    1. Stop agent services (see Restarting a Private Agent above).
    2. Place your saved config files and security certificates in the installation directory.
    3. Start agent services (see Restarting a Private Agent above).

Uninstalling a Private Agent

Before uninstalling, it is recommended to copy the config files and security certificates for your current installation in case you want to reinstall with the same configuration in the future. These are typically located at:

# 32-bit Agents
C:\Program Files (x86)\Jitterbit Agent\jitterbit.conf
C:\Program Files (x86)\Jitterbit Agent\apache\conf\httpd.conf
C:\Program Files (x86)\Jitterbit Agent\JdbcDrivers.conf
C:\Program Files (x86)\Jitterbit Agent\Resources\
C:\Program Files (x86)\Jitterbit Agent\Resources\credentials.txt

# 64-bit Agents
C:\Program Files\Jitterbit Agent\jitterbit.conf
C:\Program Files\Jitterbit Agent\apache\conf\httpd.conf
C:\Program Files\Jitterbit Agent\JdbcDrivers.conf
C:\Program Files\Jitterbit Agent\Resources\
C:\Program Files\Jitterbit Agent\Resources\credentials.txt
# 32-bit Agents
C:\Program Files (x86)\Jitterbit Agent\apache\conf\extra\
C:\Program Files (x86)\Jitterbit Agent\apache\conf\ssl.crt\
C:\Program Files (x86)\Jitterbit Agent\apache\conf\ssl.key\

# 64-bit Agents
C:\Program Files\Jitterbit Agent\apache\conf\extra\
C:\Program Files\Jitterbit Agent\apache\conf\ssl.crt\
C:\Program Files\Jitterbit Agent\apache\conf\ssl.key\
CAUTION: To be able to use your backup files in a future installation, you must stop services while you move the files over, then restart services once completed (see Restarting a Private Agent).

To uninstall a Private Agent, these steps are recommended to remove both the Private Agent and the PostgreSQL installation:

  1. Uninstall these applications (this can be done from the Control Panel under Programs and Features > Uninstall a program):
    • Jitterbit Agent
    • PostgreSQL (the version may vary from what is shown below)
    • PostgreSQL driver (may be referred to as either psqlODBC or pODBC; the version may vary from what is shown below)
  2. Delete the Jitterbit PostgreSQL user. This can be done in several ways:

    • Open the Local User and Group Management window either from the Control Panel under User Accounts > Edit local users and groups or by using a Windows Command Prompt to enter the command lusrmgr.msc. Right-click the user jitterbitpostgres and select Delete.

    • Open the User Accounts window by using a Windows Command Prompt to enter the command netplwiz. Select the user jitterbitpostgres and click Remove.
    • Use a Windows Command Prompt to enter this command:

      net user jitterbitpostgres /delete
  3. Delete the Windows user folder for the jitterbitpostgres user from the Users folder of the file system:

  4. Delete the PostgreSQL folder from the Program Files folder of the file system:

  5. Delete the PostgreSQL folder from the Program Files (x86) folder of the file system:


Error 1722

There are multiple reasons the Private Agent installation could fail with this error message:

Error 1722. There is a problem with this Windows Installer package. A program run as part of the setup did not finish as expected. Contact your support personnel or package vendor. ...

The most common reason for this failure is a conflict with an existing version of Microsoft Visual C++ Redistributable.

Microsoft Visual C++ Redistributables

Private Agents require Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017, 2019 to be installed before installing a Private Agent. Microsoft now includes the same redistributable files for Visual Studio C++ 2015, 2017, and 2019. Install the appropriate version to match your Windows version:

  • 32-bit Windows: Install the file vc_redist.x86.exe
  • 64-bit Windows: Install the file vc_redist.x64.exe

NOTE: If installing a Private Agent that is prior to version 10.3, and Visual Studio libraries such as the earlier versions of Visual Studio C++ Redistributable for Visual Studio 2017 or higher are already installed, the installation will fail. A workaround is to download and install the appropriate files available at Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017, 2019 and then install the Private Agent. 

As of Jitterbit Harmony version 10.3, this has been fixed. Installation on a machine that already has a version of Visual C++ Redistributable for Visual Studio higher than 2015 is now successful. If you are still experiencing issues, please contact support.

PostgreSQL Errors

In certain cases, after uninstalling a Windows Private Agent and then attempting to reinstall the agent, users may receive an error related to the PostgreSQL database.

This error has been known to occur on systems where the PostgreSQL installation associated with the Private Agent has not been completely removed.

To resolve the error, users should follow the steps above in Uninstalling a Private Agent to completely remove the Jitterbit PostgreSQL user account. The instructions for manually removing all PostgreSQL files are in steps 2 through 5.

Once this is done, you should be able to complete a new agent installation. If you are still experiencing issues, please contact support.

Windows Private Agents Installed on an Azure Server

When using a Windows Private Agent installed on a Microsoft Azure server, you may experience lost connections. Azure sets the the websocket idle timeout to 4 minutes, while the Private Agent default to ping Jitterbit Harmony is set to 5 minutes.  To resolve this issue, reduce the interval for the agent heartbeat:

  1. Make a backup copy of the file and save it to another location. This file can be found in the \Program Files (x86)\Jitterbit Agent\Resources directory in Windows
  2. Open the file in a text editor.
  3. Find the agent.heart.beat.interval setting:

    #Agent heart beat interval (IN MINUTES)
  4. Change the setting to agent.heart.beat.interval=3.

  5. Save the changes and restart the agent.

IPv6 Issues

Some customers have experienced issues when Internet Protocol version 6 (IPv6) is enabled. In these instances, we recommend disabling IPv6 and IP Helper.

To disable IPv6:

  1. On Windows, open Control Panel > Network and Internet > Network Connections.
  2. Open the Properties of a connection.
  3. Clear the checkbox for Internet Protocol Version 6 (TCP/IPv6):

To disable IP Helper:

  1. On Windows, open Services.
  2. Locate IP Helper in the list of services. Then right-click on IP Helper and select Properties.
  3. In the IP Helper Properties, click Stop to stop the service, and change the Startup type to Disabled:

Connection Slot Error

You may receive an error similar to this:

FATAL: remaining connection slots are reserved for non-replication superuser connections

To resolve, see Fixing Errors Caused by postgresql.conf Settings with Windows 64-bit Private Agents.

  • No labels