Agent registration for Jitterbit private agents

Introduction

Before a private agent can process Integration Studio or Design Studio project operations, it must successfully register with a Harmony server. The first time an agent starts, it reads registration information from either a user, a file, or environment variables, then stores it in the PostgreSQL TranDB database. The registration information provided and stored includes the URL of the Harmony server, the Harmony account and organization to use, and the private agent's name and group.

This page describes the following ways to register a private agent:

Manual registration: For this, you must add an agent to a group in the Management Console before you install a private agent. Registration information is collected by the installer on Microsoft Windows, and by jitterbit-config command prompts or program options on Linux. With Docker private agents, this information is provided as environment variables.
Automatic registration: With this method, a private agent is added to a group, registered, and optionally de-registered automatically. Automatic registration is most useful for containerized agents, but it can also be used on Linux agents.

Note

You cannot use a proxy with automatic registration.

Manual Registration

To use manual registration with containerized private agents, set values for the following environment variables:

Environment variable	Description
`HARMONY_ORIGIN`	The login URL for your Harmony account, `https://REGION.jitterbit.com`, where `REGION` is one of `na-east`, `emea-west`, or `apac-southeast`.
`HARMONY_USERNAME`	Your Harmony account username.
`HARMONY_PASSWORD`	Your Harmony account password.
`HARMONY_ORG_NAME`	Your Harmony organization name.
`HARMONY_AGENT_GROUP_NAME`	The agent group name and environment name, separated by an underscore.
`HARMONY_AGENT_NAME`	The agent name.

Example

docker run -it \
-e HARMONY_ORIGIN=https://na-east.jitterbit.com \
-e HARMONY_USERNAME=example@jbexample.com \
-e HARMONY_PASSWORD=P@55w0rd \
-e HARMONY_ORG_NAME="Example Org" \
-e HARMONY_AGENT_GROUP_NAME="Example Agent Group_Example Env" \
-e HARMONY_AGENT_NAME=ExampleAgent \
jitterbit/agent

Tip

Put the values in a file and use the --env-file Docker option instead of multiple -e options.

Automatic Registration

Automatic registration works with Docker and Linux private agents. It uses the following environment variables or equivalent keys and values in a JSON format register.json file:

Environment variable	`register.json` parameter	Value type	Description
`AUTO_REGISTER`	(None)	Boolean (`true` or `false`)	Enable automatic registration.
`HARMONY_ORIGIN`	`cloudUrl`	String	The URL of the Harmony cloud: `"https://REGION.jitterbit.com"` where `REGION` is `na-east`, `emea-west`, or `apac-southeast`.
`AUTO_REGISTER_ENCRYPTED_USERNAME`	`username`	String	Encrypted version of your Harmony account username. (First line of output from `jitterbit-utils -e USERNAME PASSWORD`.) Ignored if `token` is set.
`AUTO_REGISTER_ENCRYPTED_PASSWORD`	`password`	String	Encrypted version of your Harmony account password. (Second line of output from `jitterbit-utils -e USERNAME PASSWORD`.) Ignored if `token` is set.
Currently no matching variable	`token`	String	Agent registration access token. If provided, `username` and `password` are ignored.
`AUTO_REGISTER_DEREGISTER_ON_DRAINSTOP`	`deregisterAgentOnDrainstop`	Boolean (`true` or `false`)	If `true`, agent is removed when stopped. Set to `false` to allow the agent to re-register when restarted. (See also `DeregisterAgentOnDrainstop`.)
`AUTO_REGISTER_AGENT_GROUP_ID`	`agentGroupId`	Integer	The ID number of the agent group to join.
`AUTO_REGISTER_AGENT_NAME_PREFIX`	`agentNamePrefix`	String	The agent name. These tokens are expanded: `%ip%`: server IP address; `%host%`: server hostname; `%guid%`: a random 8-character ID.
`AUTO_REGISTER_RETRY_COUNT`	`retryCount`	Integer	Number of retries when agent fails to register. Range: 0-300. Default: 10.
`AUTO_REGISTER_RETRY_INTERVAL_SECONDS`	`retryIntervalSeconds`	Integer	Number of seconds between retries. Range: 5-600. Default: 5.

To use environment variables for automatic agent registration, create a file of variables and values, then use the --env-file option for docker run to start the private agent. Alternatively, use the -e/--env option to set environment variables individually.

To use a register.json file, create it in a conf subdirectory with the following contents:

conf/register.json

{
    "cloudUrl": "https://REGION.jitterbit.com",
    "username": "ENCRYPTED USERNAME",
    "password": "ENCRYPTED PASSWORD",
    "agentNamePrefix": "PREFIX",
    "agentGroupId": AGENT_GROUP_ID,
    "deregisterAgentOnDrainstop": true,
    "retryCount": 10,
    "retryIntervalSeconds": 5
}

Start the containerized agent with the conf directory mounted to the container's /conf directory. (See Automatic registration with register.json file for an example.)

To use the register.json file on non-containerized Linux private agents, move or remove the /opt/jitterbit/Resources/credentials.txt file, create a /opt/jitterbit/Resources/register.json file as shown above, then restart the agent.