Saltar al contenido

Jitterbit private agents on Microsoft Windows

Introduction

This page shows you how to install and run a private agent on Microsoft Windows.

Install

To install a private agent, check the Prerequisites, then follow the steps in the Download and Run installer sections.

Prerequisites

You must have the following:

  • A host that meets the system requirements.

  • Your Harmony account username and password.

  • Your Harmony organization name.

  • The name and ID of a private agent group.

  • Access to a Microsoft Windows administrator account on the host. Use it for all actions on this page.

The following are optional:

  • Add an agent in the Management Console. If you don't have any unregistered private agents in the agent group, one is automatically created with a name that includes the host's name and IP address.

  • A PostgreSQL database server is installed automatically. To use your own, you must set it up before installing the private agent, and have ready its name or IP address, its port number, and the details of the database administrator account.

The following are recommended:

  • Disable Windows compression and encryption on the following folders:

    Description Default location
    Private agent folder C:\Program Files\Jitterbit Agent\
    System temporary folder C:\Windows\Temp\
    PostgreSQL data folder C:\PostgreSQL\14\data\ (Private Agent 11, version 11.0 and higher.)
    C:\PostgreSQL\9.6\data\ (Private Agent 10, version 10.37 and higher.)

  • Follow the performance tuning configuration guide.

Download

To download the private agent software, go to the Harmony Portal Downloads page. (If you have already added an agent on the Management Console Agents page, click the agent's Download Jitterbit Agent icon.)

Download one of the following private agent Windows packages:

  • Windows (x64): (Recommended) The standard installer package (.exe file). The Quick Install mode installs all components to their default locations. In the Advanced mode, you can set the install location and configure your own PostgreSQL database server.

  • Windows Quiet Agent Installer (x64): The quiet installer (.zip file). This uses a configuration file to allow for unattended installation.

Run installer

Follow the steps for the installer type:

  1. Run the downloaded .exe file.

  2. Perform the following tasks when prompted. Click Next > to progress through each wizard page:

    1. License Agreement: Accept the license agreement.

    2. Login Credentials: Enter your Harmony username and password.

      • Enable Proxy: (Optional) Click to enter your proxy server information.

    3. Select Organization: Select your organization.

    4. Select Agent Group/Environment: Select your agent group. If you have associated an environment to it, the environment name is shown in parentheses.

    5. Select Agent: (Optional) If there is one unregistered agent in the agent group, it is selected automatically. If there are two or more agents in the group, you are prompted to select the one to register with.

  3. At the Select Install Mode prompt, select either Quick Install or Advanced:

    • Quick Install: This mode installs the private agent to the default location (C:\Program Files\Jitterbit Agent), installs a PostgreSQL database server, installs the psqlODBC driver, creates a jitterbitpostgres local Microsoft Windows user, and installs Microsoft Visual C++ Redistributable packages. If an existing PostgreSQL installation is found, the installer switches to advanced mode.

      1. Enter and verify a password for the PostgreSQL database server being installed. The password should not include accented characters (such as é) or any of the following: + @ $ % & [ ] { } ( ) , ; ? ^ = £.

      2. At each step of the PostgreSQL installation, click Next >.

      3. On the last page of the installer, click Finish. You can confirm the organization, agent group, and agent registration on the Installation Summary page.

    • Advanced: This mode lets you install the agent software to a different location, and choose an existing PostgreSQL server.

      1. (Optional) On the Choose Destination Folder page, click Change to set the install location.

      2. On the Database administrative credentials page, enter the details of an existing PostgreSQL database server.

  4. On the last page of the installer, click Finish. (If installation fails, enable the option Show the Windows Install log before clicking Finish.)

  1. Extract the contents of the downloaded .zip file.

  2. In the extracted folder, edit config64.ps1, and set values for the following parameters:

    Parameter Default Description
    $Jitterbit_user_name "" Harmony account username.
    $Jitterbit_password "" Harmony account password.
    $Postgres_super_user "postgres" PostgreSQL superuser account username.
    $Postgres_super_password "" Superuser account password.
    $Postgres_service_account "postgres" Service account username for PostgreQSL on Windows.
    $Postgres_service_password "" Service account password.
    $Postgres_agent_username "" Account username for the private agent process.
    $Postgres_agent_password "" Account password for the private agent process.
    $Agent_group_id "" Private agent group ID number.
    $Agent_id "" Private agent ID number.
    $Agent_install_dir "C:\Program Files" Install location.

    Tip

    There is more information on each parameter in the file.

  3. Edit silent_install64.ps1, find the $JitterbitArgList parameter, then check or change the value of KO_INSTALL_MODE:

    • KO_INSTALL_MODE=\"1\": Install a private agent and a PostgreSQL database server.

    • KO_INSTALL_MODE=\"2\": (Default) Install a private agent only. For this option you must have an existing PostgreSQL database server installed.

  4. In a command prompt, run the following commands:

    Set-ExecutionPolicy Unrestricted
silent_install64.ps1
    • Line 1: Allow PowerShell script execution.
    • Line 2: Run the silent installer.

If the configured values are correct, the installation proceeds without further intervention, and the private agent starts. You can check its status in the Management Console, or by watching the log file C:\Program Files\Jitterbit Agent\log\jitterbit-agent.log.

If installation fails, check the log\Installer.log log file for more information.

Upgrade

A minor version private agent upgrade (10.x to 10.y or 11.x to 11.y) requires the agent to be stopped and restarted.

For a major version upgrade (10.x to 11.y), you must uninstall and re-install the private agent, the PostgreSQL database server, and the PostgreSQL database driver. You must also manually backup and restore the private agent configuration files.

Minor version upgrade

For a minor version upgrade, follow these steps:

  1. Download an installer package.

  2. Stop the agent.

  3. Make backup copies of the following files:

    Location File
    C:\Program Files\Jitterbit Agent\ jitterbit.conf
    C:\Program Files\Jitterbit Agent\ JdbcDrivers.conf
    C:\Program Files\Jitterbit Agent\Resources\ jitterbit-agent-config.properties
    C:\Program Files\Jitterbit Agent\apache\conf\ httpd.conf
    C:\Program Files\Jitterbit Agent\apache\conf\extra\ All .conf files
    C:\Program Files\Jitterbit Agent\apache\conf\ssl.crt\ All .crt files
    C:\Program Files\Jitterbit Agent\apache\conf\ssl.key\ All .key files

  4. (Optional) If you must upgrade other agents in the same group, you can minimize the impact of agent downtime by using a rolling upgrade approach. To do this, open jitterbit-agent-config.properties file for editing, and add or set the property agent.starting.standby=true. (This keeps the agent in Starting status and prevents it from processing operations until the property value is set to false.)

  5. Run the installer:

    Run the downloaded standard installer and respond to the InstallShield wizard prompts.

    Follow the install steps for the quiet installer, but in the silent_install64.ps1 file, set KO_INSTALL_MODE=0.

    The agent starts automatically.

  6. (Optional) If you are doing a rolling upgrade with the property value agent.starting.standby=true, and before upgrading another agent in the same group, monitor the agent log file for the following message:

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

    This message indicates that the agent has completed environment synchronization. When it appears, edit jitterbit-agent-config.properties again, delete the property agent.starting.standby (or set it to false), then restart the agent.

  7. Compare the following files with your backup copies and restore any changed settings:

    Location File
    C:\Program Files\Jitterbit Agent\ jitterbit.conf
    C:\Program Files\Jitterbit Agent\ JdbcDrivers.conf
    C:\Program Files\Jitterbit Agent\Resources\ jitterbit-agent-config.properties
    C:\Program Files\Jitterbit Agent\apache\conf\ httpd.conf
    C:\Program Files\Jitterbit Agent\apache\conf\extra\ All .conf files

    Tip

    Use a compare and merge tool, such as WinMerge.

  8. If you have backup .crt or .key files that are not already in C:\Program Files\Jitterbit Agent\apache\conf\ssl.crt\ or C:\Program Files\Jitterbit Agent\apache\conf\ssl.key\ respectively, copy them to those locations.

  9. Stop and start the agent.

Major version upgrade

For a major version upgrade, follow these steps:

  1. Download an installer package.

  2. Stop the agent.

  3. Make backup copies of the following files:

    Location File
    C:\Program Files\Jitterbit Agent\ jitterbit.conf
    C:\Program Files\Jitterbit Agent\ JdbcDrivers.conf
    C:\Program Files\Jitterbit Agent\Resources\ jitterbit-agent-config.properties
    C:\Program Files\Jitterbit Agent\apache\conf\ httpd.conf
    C:\Program Files\Jitterbit Agent\apache\conf\extra\ All .conf files
    C:\Program Files\Jitterbit Agent\apache\conf\ssl.crt\ All .crt files
    C:\Program Files\Jitterbit Agent\apache\conf\ssl.key\ All .key files

  4. Uninstall the following programs:

    • Jitterbit Agent: The Jitterbit private agent software.
    • PostgreSQL 9.6: The private agent's PostgreSQL database server.
    • psqlodbc: The PostgreSQL ODBC database driver.

  5. (Optional) Delete the PostgreSQL data directory C:\Program Files\PostgreSQL\9.6\data.

  6. Install the new private agent. The agent starts automatically.

  7. Compare the following files with your backup copies and restore any changed settings:

    Location File
    C:\Program Files\Jitterbit Agent\ jitterbit.conf
    C:\Program Files\Jitterbit Agent\ JdbcDrivers.conf
    C:\Program Files\Jitterbit Agent\Resources\ jitterbit-agent-config.properties
    C:\Program Files\Jitterbit Agent\apache\conf\ httpd.conf
    C:\Program Files\Jitterbit Agent\apache\conf\extra\ All .conf files

  8. If you have backup .crt or .key files that are not in C:\Program Files\Jitterbit Agent\apache\conf\ssl.crt\ or C:\Program Files\Jitterbit Agent\apache\conf\ssl.key\ respectively, copy them to those locations.

  9. Stop and start the agent.

Uninstall

To completely uninstall a private agent and its PostgreSQL database server, follow these steps:

  1. Stop the agent.

  2. Make backup copies of the following files:

    Location File
    C:\Program Files\Jitterbit Agent\ jitterbit.conf
    C:\Program Files\Jitterbit Agent\ JdbcDrivers.conf
    C:\Program Files\Jitterbit Agent\Resources\ jitterbit-agent-config.properties
    C:\Program Files\Jitterbit Agent\apache\conf\ httpd.conf
    C:\Program Files\Jitterbit Agent\apache\conf\extra\ All .conf files
    C:\Program Files\Jitterbit Agent\apache\conf\ssl.crt\ All .crt files
    C:\Program Files\Jitterbit Agent\apache\conf\ssl.key\ All .key files

  3. Uninstall the following programs:

    • Jitterbit Agent: The Jitterbit private agent software.
    • PostgreSQL: The private agent's PostgreSQL database server. (The version depends on the private agent version.)
    • psqlodbc: The PostgreSQL ODBC database driver.

  4. Delete the PostgreSQL data directory C:\Program Files\PostgreSQL\<VERSION>\data for the same database version.

  5. Delete the jitterbitpostgres PostgreSQL service user account.

Manage

A private agent is managed via entries in the Microsoft Windows Start menu, or with commands entered in a command prompt.

Start

A private agent starts automatically with the host. It can take several minutes for a private agent to complete synchronization and be in running status.

To start an agent, use either of these options:

  • From the Microsoft Windows Start menu, select Jitterbit Agent > Start Jitterbit Services.

  • In a command prompt, run this command:

    "C:\Program Files\Jitterbit Agent\StartServices.bat"

Stop

An agent can be stopped by a drain stop or a hard stop, using any of the methods shown in the following table:

Drain stop Hard stop
Management Console
Windows Start menu
Command prompt

Warning

A hard stop can result in data loss. A drain stop avoids data loss by waiting a configurable period (set by default to 180 seconds in agent.drainstop.api.wait) for any outstanding API calls to complete before shutting down the agent.

You must start a stopped private agent by logging into the server and running a command, or by restarting the host. Agents cannot be started remotely.

If the agent started with automatic registration, it is automatically unregistered when stopped.

Drain stop

To drain stop an agent, use either of these options:

  • From the Harmony Portal menu, select Management Console > Agents. From the Action column of the agent to be stopped, select Action > Drain Stop, then click OK in the confirmation dialog.

  • In a command prompt, run this command:

    "C:\Program Files\Jitterbit Agent\bin\JitterbitUtils.exe" --drain-stop

Hard stop

To hard stop an agent, use either of these options:

  • From the Microsoft Windows Start menu, select Jitterbit Agent > Stop Jitterbit Services.

  • In a command prompt, run this command:

    "C:\Program Files\Jitterbit Agent\StopServices.bat"

Pause

A private agent can be paused. In this state, the agent finishes any operations currently being processed, and does not process further operations. In the Management Console, the status is shown as Stopping.

To pause a private agent on Microsoft Windows, run this command in a command prompt:

JitterbitUtils.exe --drain-pause

To resume a paused agent on Microsoft Windows, use the Start command.

Status

To see the agent's status, use either of these options:

  • From the Harmony Portal menu, select Management Console > Agents.

  • Look for the following services in the Microsoft Windows Computer Management utility, or in a command prompt with sc.exe query "<SERVICE>":

    • Jitterbit Apache Server

    • Jitterbit Cleanup

    • Jitterbit Process Engine

    • Jitterbit Scheduler

    • Jitterbit Tomcat Server

    • JitterbitPgBouncer

    • JitterbitVerboseLogShipper (service name Jitterbit-Verbose-Log-Shipper)