Upgrade a Windows Jitterbit private agent

Introduction

Upgrading a private agent from an earlier private agent version to a later one usually can be done without uninstalling the prior agent version, as described in Upgrade an agent below. However, when upgrading from a 10.x to an 11.x Windows private agent, a complete uninstall of the agent is required.

Rolling back an agent to a previous version is also covered on this page.

Upgrade an agent

The following subsections provide instructions for minor upgrades and major upgrades, along with recommendations for large deployments.

Minor upgrade

Minor upgrades from the same major version (that is, 10.x to 10.x, or 11.x to 11.x) take only a few minutes to complete.

For a minor upgrade, generally, you use the instructions for installing a private agent and follow the prompts to upgrade the existing agent installation.

Follow these instructions for minor agent upgrades:

1. Back up the configuration files and security certificates for reference (optional; see Uninstall a private agent).

2. Install the new version of the agent (see Install a private agent).

3. To use the backup files (optional):

   1. Stop agent services (see Restart a private agent).

   2. Place your saved security certificates in the installation directory. Manually update the newly installed configuration files based on the settings in your saved files.

      Warning

      Directly copying over saved configuration files after an agent version change can cause errors. Instead, use tools like the Notepad++ Compare plugin to help you manually compare and update configuration settings. Do not change settings with defined passwords or ports such as those found in the credentials.txt file and under the [DbInfo] section of the jitterbit.conf file.

   3. Start agent services (see Restart a private agent).

Major upgrade from 10.x to 11.x

A complete uninstall of existing 10.x Windows private agents is required in order to upgrade to version 11.x Windows private agents.

To upgrade from a 10.x to an 11.x Windows private agent, follow these steps:

1. Back up the agent configuration files and security certificates for reference (optional, see Uninstall a private agent).
2. Uninstall the existing 10.x agent (see Uninstall a private agent).
3. Remove all Jitterbit-related files (see Uninstall a private agent).

4. In addition to uninstalling the agent, it is strongly recommended to uninstall the existing 9.6.x PostgreSQL database. If you don't want to uninstall the PostgreSQL database, it can remain installed but will be disabled when an 11.x Windows private agent is installed. In this case, see PostgreSQL 9.6 and 14.5 parallel installations below.

5. Install the 11.x version of the agent (see Install a private agent). On upgrading to an 11.x version of the agent, the following will occur:

   • The PostgreSQL ODBC driver will be upgraded to PostgreSQL ODBC 13.2.0.0.

   • A full sync of environments will occur. During a full sync, all projects and metadata in each environment are re-downloaded from the Harmony cloud to populate the PostgreSQL database.

     Caution

     The length of time it takes to perform a full sync depends on the number and complexity of projects in each environment. For typical environment usage, a full sync typically takes up to 10 minutes to complete. However, environments with a very large number of projects may take several hours to sync. If having an outage is a concern, see the recommendations for large deployments below.

6. To use the agent configuration backup files (optional):

   1. Stop agent services (see Restart a private agent).

   2. Place your saved security certificates in the installation directory. Manually update the newly installed configuration files based on the settings in your saved files.

      Warning

      Directly copying over saved configuration files after an agent version change can cause errors. Instead, use tools like the Notepad++ Compare plugin to help you manually compare and update configuration settings. Do not change settings with defined passwords or ports such as those found in the credentials.txt file and under the [DbInfo] section of the jitterbit.conf file.

   3. Start agent services (see Restart a private agent).

Upgrade recommendations for large deployments

If having an outage is a concern during an agent upgrade, we recommend using high availability (two or more agents) so that requests are routed to another available agent in the agent group. If your current subscription does not have agent grouping, contact your Customer Success Manager (CSM).

When a full sync is expected to occur, such as when upgrading from a 10.x to an 11.x agent version, we recommend a rolling upgrade approach, where you install new agents in standby mode one at a time in an existing agent group prior to decommissioning existing agents. This approach provides a clean rollback path should the need arise.

Starting agents in standby mode involves adding a setting to an agent's properties file (jitterbit-agent-config.properties) to make sure the agent stays out of commission and will not start to accumulate a backlog of requests before the full sync is complete.

To implement a rolling upgrade approach:

1. Install a new agent in an existing agent group following the instructions for installing a Windows private agent.

2. In the new agent's jitterbit-agent-config.properties file, add the agent.starting.standby property set to true to force the agent to stay in Starting agent status and prevent it from entering a Running state where it can accept requests.

3. Restart the agent.

4. As the agent starts up, you can monitor the sync status in the agent's jitterbit-agent.log file, looking for lines similar to those below that indicate when syncing started and completed:

   Agent synchronization for environment <123456> and agent group ID <987654> started at ...
   . . .
   Agent synchronization for environment <123456> and agent group ID <987654> completed at ...
   

5. Once logs indicate the sync is complete, remove the agent.starting.standby property or change its value to false and restart the agent.

6. When the new agent reports Running status, decommission a former agent in the agent group.

7. Repeat this process for each agent in the agent group to ensure that requests continue to be routed to a capable agent during the upgrade process.

PostgreSQL 9.6 and 14.5 parallel installations

When you install an 11.x Windows private agent, the installation will detect an existing PostgreSQL 9.6 installation from the registry and warn you that it will be disabled.

On acknowledging the warning, the existing 9.6 PostgreSQL database will be stopped, the PostgreSQL 9.6 Windows service will be disabled from running automatically, and the 14.5-1 version of PostgreSQL will be installed with the 11.x agent installation.

Roll 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, the steps are provided below for a minor downgrade and a major downgrade.

Minor downgrade

Follow these steps to downgrade from an 11.x agent to an earlier 10.x agent, or from a 10.x agent to an earlier 10.x agent:

1. Back up the agent configuration files and security certificates for reference (optional, see Uninstall a private agent).
2. Uninstall the agent (see Uninstall a private agent).
3. Remove all Jitterbit-related files (see Uninstall a private agent).

4. Install the selected version of the agent (see Install a private agent).

5. To use the agent configuration backup files (optional):

   1. Stop agent services (see Restart a private agent).

   2. Place your saved security certificates in the installation directory. Manually update the newly installed configuration files based on the settings in your saved files.

      Warning

      Directly copying over saved configuration files after an agent version change can cause errors. Instead, use tools like the Notepad++ Compare plugin to help you manually compare and update configuration settings. Do not change settings with defined passwords or ports such as those found in the credentials.txt file and under the [DbInfo] section of the jitterbit.conf file.

   3. Start agent services (see Restart a private agent).

Major downgrade

Follow these steps to downgrade from an 11.x Windows private agent to a 10.x Windows private agent:

1. Back up the agent configuration files and security certificates for reference (optional, see Uninstall a private agent).
2. Uninstall the agent (see Uninstall a private agent).
3. Remove all Jitterbit-related files (see Uninstall a private agent).

4. Uninstall the PostgreSQL 13.2.0.0 ODBC driver.

5. Uninstall the Microsoft Visual C++ driver.

6. Install PostgreSQL 9.6 prior to installing the 10.x agent. The PostgreSQL 9.6 installation can exist at the same time as the PostgreSQL 14.5 installation; there is no need to uninstall PostgreSQL 14.

7. Install the 10.x version of the agent (see Install a private agent). During the installation, the presence of PostgreSQL 9.6 will automatically be detected, and the installation process will direct you to perform an advanced installation.

8. To use the agent configuration backup files (optional):

   1. Stop agent services (see Restart a private agent).

   2. Place your saved security certificates in the installation directory. Manually update the newly installed configuration files based on the settings in your saved files.

      Warning

      Directly copying over saved configuration files after an agent version change can cause errors. Instead, use tools like the Notepad++ Compare plugin to help you manually compare and update configuration settings. Do not change settings with defined passwords or ports such as those found in the credentials.txt file and under the [DbInfo] section of the jitterbit.conf file.

   3. Start agent services (see Restart a private agent).