Installing the Engage Agent

On this page

Install the Engage Agent

Install the Engage Agent on a separate machine from Archer so the products do not compete for system resources.

Task 1: Run the Engage Agent Setup Wizard

In Windows, open File Explorer.
Go to the installation folder.
Right-click Archer Engage Agent Setup x.x.x.x.msi, and select Install.
In the Engage Agent Setup Wizard, click Next.
Read and accept the End-User License Agreement.
On the Destination Folder page, either select the default folder or change the installation folder, and click Next.
On the Configuration File and File Repo Path page, do the following:
1. In the Configuration File Location field, select a location for the Engage Agent configuration file. The configuration file is a .json file that contains settings related to Engage for Business Users, such as Archer instance mapping and the Configuration Service endpoint. When you successfully complete the installer, the .json file is automatically created at the selected location.
  
  Important: If you store the configuration file in a network share, the service user specified must have read and write access.
2. In the File Repository Location field, do one of the following:
  - Keep the default path.
  - Click Browse and select the location where you want the Engage Agent to store and process log files.
    
    Important: If you download files to a network share, the service user specified must have read and write access.
3. Click Next.
On the Service Account page, select a log on account, then click Next.

Important: If you choose the Specific Account option, you must enter an account name and password.
On the Archer Configuration Service Setup page, do the following:
1. In the Archer Configuration Service REST URL field, enter the URL for the Archer Configuration Rest Service. For example:
  
  https://[ServicesServer]:13200/ConfigService/rest/
  
  Note: If upgrading an existing service install, this field is locked and populated with the previous setting.
  
  Important: If a proxy is enabled at the system level, you must disable that proxy. This is completed in the Archer Control Panel. For more information, see the Archer Control Panel Help.
2. Do one of the following:
  - If you have already imported the certificates on the local machine as detailed in Importing certificates into the certificate store, choose Select Certificate From Store.
  - If you have not imported the certificate on the local machine, do the following:
    1. Choose Select Certificate From Disk.
    2. In the Path to the Certificate field, click Browse.
    3. Select the location where you saved the certificate .
    4. (Optional) If the certificate has a password, enter it in the Password field.
3. Click Next.
  
  Note: If you get an error message that reads “Config service not reachable. Please verify the service URL”, see Troubleshooting Engage On-Premises.
On the Portal Region page, select the portal region to connect the Archer Engage Agent, then click Next.
Specify the certificate to leverage SSL.
1. Do one of the following:
  - If you have already imported the certificate on the local machine as detailed in Importing certificates into the certificate store, choose Select Certificate From Store.
  - If you have not imported the certificate on the local machine, do the following:
    1. Choose Select Certificate From Disk.
    2. In the Path to the Certificate field, click Browse.
    3. Select the location where you saved the certificate.
    4. (Optional) If the certificate has a password, enter it in the Password field.
2. Click Next.
Click Install.
Click Finish.

Note: Installer logs can be found in the temp directory (Windows Key + R > %temp%)

Task 2: (Optional) Start the Engage Agent

In case the Engage Agent does not start automatically after installation, follow these steps:

In Windows, open the Services desktop app.
Select Engage Agent.
Click Start from the service's shortcut menu.

Configure the Engage Agent

Configure your installation by performing the following tasks.

Task 1: Set Up the Portal Provision URL

The PortalDataStore.json file must be updated to your environment's specifications before publishing. If the URL is incorrect, you can not publish to your Engage Portal.

Open the PortalDataStore.json file.
In the ArcherInstances section, keep all default settings.

(Optional) In the RetrieveSettings sections, edit the following settings:

Property	Description
DownloadUrlQueueSize	Size of the queue to download the submitted assessments.
ThreadCount	Number of threads to complete service.
PollingInterval	Waiting time in milliseconds between 2 retrieve operations.

(Optional) In the ArcherSettings section, edit the following settings.

Property	Description
ConfigBaseUrl	Archer Config Service Base URL
InstallationDEK	Keep default settings
BypassSslErrors	If you want to bypass the SSL errors during communication, set it as true. Use it with caution.

In the MultipartSettings section, edit the following settings.

Property	Description
UploadPartSize	The data uploaded to the Portal is split in parts. These parts are in MBs with a default size of 10 MB.
DownloadPartSize	The data downloaded from the Portal is split in parts. These parts are in MBs with a default size of 25 MB.

Note: The part size must be a whole number greater than or equal to the default value. If the part size is less than the default, it considers the default value itself.

(Optional) In the CertificateProperties section, edit the following settings.

Property	Description
StoreName	Store name in the certificate manager where Archer Configuration certificate is stored.
CertificateName	Name of the Archer Configuration Certificate.

(Optional) In the ProxySettings section, edit the following settings.

Property	Description
UseProxy	Indicates if the service needs proxy to connect to the internet. Note: If set true, update the rest of the entries in this table.
ProxyHost	Hostname (or IP) of proxy to connect internet
ProxyPort	Proxy Port number to connect internet
Username	Proxy username to connect internet
Password	Proxy password to connect internet Note: When you restart the service, this plain text value is encrypted and stored.
EncryptedPassword	Keep default settings
Domain	Proxy domain to connect internet

(Optional) In the ArcherProxySettings section, edit the following settings.

Property	Description
UseProxy	Indicates if the service needs proxy to connect Archer Config Service. Note: If set true, update the rest of the entries in this table.
ProxyHost	Hostname (or IP) of proxy to connect Archer Config Service
ProxyPort	Proxy Port number to connect Archer Config Service
Username	Proxy username to connect Archer Config Service
Password	Proxy password to connect Archer Config Service Note: When you restart the service, this plain text value is encrypted and stored.
EncryptedPassword	Keep default settings
Domain	Proxy domain to connect Archer Config Service

(Optional) In the RestoreSettings section, edit the following settings.

Property	Description
ResetTenant	Keep default settings unless instructed otherwise by Archer support.

(Optional) In the TimeoutSettings section, edit the following settings.

Property	Description
RequestTimeout	Timeout values for API calls in milliseconds

(Optional) In the Portal section, verify the region of the PortalProvision URL is the same as the region selected during installation:

Region	URL
US	https://api.engage.archerirm.us/admin
EMEA	https://api.engage.archerirm.eu/admin
APJ	https://api.engage.archerirm.com.au/admin
CA	https://api.engage.archerirm.net/admin

(Optional) In the RepoPath section, edit the following settings.

Property	Description
LoggingRepo	Path to store service logs
FileRepo	Path to store intermediate during the retrieve operation

Task 2: Check and Update the Configuration Certificate

If the Configuration certificate changed after installation, do the following:

In the certificate store on the Archer server, install the new or required certificate.
In the PortalDataStore.json file, update the CertificateName and StoreName.
Restart the Engage Agent.

Task 3: Add a Proxy Setting to PortalDataStore.json

To route traffic through a proxy, do the following:

Open PortalDataStore.json.
Populate the following fields:
- UseProxy
  
  Important: To enable proxy, set the UseProxy field to true.
- ProxyHost
- ProxyPort
- Username
- Password
  
  Note: The Password field encrypts and populates in the EncryptedPassword field after you restart the Engage Agent.
- Domain

Sample Proxy Node Setting in PortalDataStore.json

"ProxySettings": {

"UseProxy": true,

"ProxyHost": "HostName",

"ProxyPort": "3128",

"Username": "admin",

"Password": "",

"EncryptedPassword": "ccxuLqjxc04G/y2y+lvv/w==",

"Domain": "" }

Task 4: (Optional) Enable Info Level Logging

To enable info level logging, do the following:

In the directory where the Engage Agent was installed, open the nlog.config file.
In the rules node, locate the minlevel value.
Change the minlevel value to Info.
Save the file.
Restart the Engage Agent.

Task 5: (Optional) Change the Engage Agent Configuration Settings

If the installer is re-run on a machine where the agent is already installed, you can change every input except the Configuration Service URL.

Note: If you do not point to the existing portal data store, the instances served by the Configuration Service URL are synchronized again.

In the PortalDataStore.json file, in the ArcherSettings section, update the ConfigBaseURL entry to point to the new configuration service URL.
Under CertificateProperties section, ensure the CertificateName and StoreName values are valid for the new ConfigBaseURL.
Restart the Engage Agent.
Verify that the Engage Agent can connect to the newly specified Configuration Service.

Note: The Engage Agent matches on Instance Name, so any Instance Name served by the new configuration service uses existing configuration settings for that name that exist in PortalDataStore.json. The instance continues to be tied to the same tenant in Engage. If the configuration service has instance names that are not found in PortalDataStore.json, on the first publish request from that instance, a new portal tenant is onboarded from that instance and the configuration and credential details are added to PortalDataStore.json.

Task 6: (Optional) Change the Server Location for the Engage Agent

You can change the server where the Engage Agent is installed.

For example, should your server hardware begin to fail and you need to move to a new location, update the new location in this step.

Before you begin

If your SSL Certificate or Configuration Certificate has changed between installations, you must re-establish the trust for the new certificate for your Archer server. For more information, see Changing Configuration Settings.
If you are not using a shared network drive to store the PortalDataStore.json file, you must copy that file from the old server to the new server.

Procedure

Install the Engage Agent on the new server.
When prompted, select the folder location of the PortalDataStore.json as the File Store Path.
For detailed installation instructions, see Installing the Engage Agent.

ADDRESS	ABOUT ARCHER	CUSTOMERS
13200 Metcalf Ave	Events	Archer Academy
Suite 300	Resources	Archer Exchange
Overland Park, KS 66213	Services	Support
	About Us	Archer Community