Fusion 23.4.0 Connect Help Center

# Agent installation and configuration

Fusion uses a processing agent, installed on one or more host servers within the Fusion environment, to communicate with your datasets and to process your data. These installed agents work cooperatively in an agent cluster to optimize performance, load balance, and maintain high availability.

When determining the number of agents needed to process the data in your datasets, consider the following:

- the amount of data to be processed and the network-connected regions in your environment.

- expected daily throughput during initial data processing and future data processing.

Requirements for the server on which the agent is installed

Operating System

Ensure that you are running a supported operating system with all currently "critical" and "important" updates installed from update.microsoft.com.

- Windows Server 2016 from English Installation Media (Standard, Datacenter)

  The "Server with Desktop Experience" installation option is required. Additional language packs may be added after OS installation.

- Windows Server 2019 from English Installation Media (Standard, Datacenter)

  The "Server with Desktop Experience" installation option is required. Additional language packs may be added after OS installation.

- Windows Server 2022 from English Installation Media (Standard, Datacenter)

  The "Server with Desktop Experience" installation option is required. Additional language packs may be added after OS installation.

Ports in use

The processing agent uses the following ports on the host server. Ensure these ports are available.

Ports | Agent component
--- | ---
7957 | AgentAPI
7432 | PostgreSQL; will bind to the local loopback addresses of 127.0.0.1 (IPv4) and ::1 (IPv6)
7500, 7502 | CFS (Connector Framework Server)

General

The following requirements must be met for the server hosting the processing agent. Applications listed must exist on the host server prior to installing the agent.

- If processing file system documents from a host machine that has long paths enabled, long paths must also be enabled on the agent host.

- Ensure the public certificate presented by the external proxy is trustable by agent hosts. Depending on the certificate presented, this may include importing a private certificate authority (CA) certificate to the local Windows certificate store.

  IMPORTANT: If a private CA is used, ensure the private CA’s certificate is removed if the agent is uninstalled.

- Ensure the Windows server is permitted to communicate through TLS 1.2, using a current “safe” cipher suite to ports 9000-9999. The Fusion back office components (commonly in the cloud) implement and require an Intermediate TLS security level (https://wiki.mozilla.org/Security/Server_Side_TLS).

  IMPORTANT: By default, most supported Windows server operating systems are pre-configured to allow communication with the back office and to dataset targets enforcing TLS 1.2 communication using a reduced safe set of ciphers (EX2019, O365, SPO). Ensure this connectivity is communicating with functional targets by using a web browser that utilizes Windows Schannel (Internet Explorer) or via the Invoke-WebRequest PowerShell cmdlet.

  It is possible to harden encryption in Windows server to restrict the native Schannel encryption component, used by the processing agent services, to specific operating modes and particular cipher suites (https://docs.microsoft.com/en-us/windows-server/security/tls/tls-registry-settings). The following are the minimum required values.

  - TLS 1.2 (Client): Enabled

  - Windows 2016/2019/2022 required cipher suites

    - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

    - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

    - TLS_DHE_RSA_WITH_AES_256_GCM_SHA384

    - TLS_DHE_RSA_WITH_AES_128_GCM_SHA256

- Ensure earlier versions of SSL and TLS in Windows Schannel are disabled and that .NET applications (particularly 4.x) use the system’s Windows Schannel configuration. See https://docs.microsoft.com/en-us/officeonlineserver/enable-tls-1-1-and-tls-1-2-support-in-office-online-server#enable-strong-cryptography-in-net-framework-45-or-higher.

- Ensure that the user you run the installation as has administrative rights on each server. You cannot perform the installation unless you have administrative rights to perform the required tasks.

- If the agent will connect using a proxy, ensure the user you are logged in as has internet access on the host machine. For full details on connecting through a proxy.

- If using Media Server for optical character recognition (OCR), Fusion agents and any Media Server host machines they interact with must be within the same network and can not have a proxy between them.

- Microsoft Outlook 2019 x64 to process PST files located on file systems.

  IMPORTANT: The default installation for Outlook 2019 is x32. Ensure you have the x64 version installed.

- SMTP (currently optional)

- Visual C++ 2019 runtime, updated to the most current version

- PowerShell 3.0+

- If processing structured data from Db2 databases, ensure the following are in place.

  - Visual C++ 2013 Redistributable, updated to the most current version

  - Additional drivers to support processing from Db2 databases are needed on the agent host machine.

    1. Download the driver package for your operating system from your Db2 web console.

    2. Unpack the driver package.

    3. Copy `IBM.data.Db2.dll` and the entire `\clidriver` directory from the unpacked driver package and place in the `\Agent\StructuredDataProcessor` directory of the Fusion installation path. By default, the Fusion installation path is `C:\Program Files\Fusion\Agent\StructuredDataProcessor`.

Supported data resources

The following resources are supported for data processing by the on-premises agent.

- OpenText Content Manager 10.1.x

  IMPORTANT: Only Microsoft SQL Server Unicode RDB datasets are supported at this time.

- File system CIFS/ SMBv2 shares

  - Must comply with SMBv2 protocol for share name restrictions.

- Microsoft Exchange Server 2016, and 2019 fully updated and patched, and Office 365

- SharePoint 2016, fully updated and patched, and Office 365

  - For SharePoint 2016, Site Collections, Web Applications, and OneDrive are supported.

  - For Office 365 SharePoint, Site Collections and OneDrive are supported.

- Google Workspace's Drive (personal Google Drives are not supported)

- Documentum 22.4 or later

- Extended ECM (xECM) 23.2.2 or later

- Structured data from the following platforms:

  - Oracle

  - Db2

  - SQL Server

  - PostgreSQL

  - MySQL

  - JDBC (through connection to Structured Data Manager)

  - Sybase

To fully install and configure the agent, perform the following tasks:

1. Download the agent.

   TIP: You will need to enter credentials for a Fusion user account that has the Manage agents permission for Connect. Create a user for this purpose and do not use these credentials for any other purpose.

2. Install the agent on the first agent host server.

   Install the agent on any additional agent host servers.

3. Configure cloud connection web proxy settings (Optional) if Fusion is installed in the cloud.

4. Define antivirus exclusions to ensure optimal agent performance.

5. If processing very large files, review the free space configuration tasks.

6. If managing structured data, complete the Structured data connection tasks.

7. If managing Content Manager data, complete the Content Manager integration tasks.

8. If managing O365 Exchange data, complete the Exchange connection tasks.

9. If managing SharePoint data, complete the SharePoint connection tasks.

10. If managing Google Drive data, complete the Google Drive connection tasks.

11. If managing Documentum data, complete the Documentum connection tasks.

12. If managing Extended ECM data, complete the Extended ECM connection tasks.

13. If connecting to datasets using custom adapters, contact Fusion support for guidance.

14. If protecting documents using Microsoft Purview Information Protection, complete the Microsoft Purview Information Protection connection tasks.

15. If performing OCR on documents, complete the Media Server connection tasks.

## Download the agent

You can download the agent from the Agent Download page.

To download the agent

1. From the primary navigation panel, click Agents > Agent Download.

   The Agent Download page opens.

2. Make note of the Gateway URL, including the port number, specified in the Assign Agent panel. You will need this information when you install the agent.

   TIP: Click the link icon () to copy the Gateway URL to your local clipboard.

3. In the Download Agent section, click DOWNLOAD.

4. Once the download has completed, navigate to the download location and copy the agent install file to the agent host server.

   NOTE: When you copy the downloaded agent file to the local directory of the agent host server, place the file in a directory as close to the root of the destination drive as possible. Errors may occur if the file path to the installation file is too long.

   Follow the instructions to install the agent.

## Install the Agent

When installing and configuring the agent on the host machines, keep the following recommendations in mind.

- You will need to enter credentials for a Fusion user account that has the Manage agents permission for Connect. Create a user for this purpose and do not use these credentials for any other purpose.

- As part of the agent installation, a PostgreSQL superuser is created. The user name and password you define must conform to PostgreSQL standards.

NOTE: When you uninstall a processing agent, Fusion does not remove configuration information in `\ProgramData\Fusion\Agent\Config`. We keep this to preserve any custom settings. If you need to fully uninstall and reinstall an agent from scratch, you can remove the `\Config` directory from the host machine.

To install the agent

1. If not already completed, copy the agent installation file (`Fusion-agent-version.exe`) to the agent host server from the download location.

2. Ensure all server requirements for the host server are in place.

3. Open the downloaded installation file (`Fusion-agent-version.exe`).

4. When the installation dialog opens, review the Introduction information, and then click Next.

   TIP: You may be informed of any missing prerequisites, some of which you will need to install manually.

   - If you are missing prerequisites that require manually installation, Cancel the wizard, install the prerequisite, and then restart the installation.

   - If you are missing prerequisites that the agent installer can update, click Install in the dialog. The agent installation will continue when the prerequisite installation completes.

   The License Agreement dialog opens.

5. Review the license information, select I accept the terms of the License Agreement, and then click Next.

   The Installation Directory dialog opens.

6. Accept the default location (`C:\Program Files\Fusion\Agent`), or click Change to select the desired location (it must be local).

   IMPORTANT: OpenText recommends installation on a dedicated drive with 200GB free space.

   Click Next.

   The PostgreSQL Credentials dialog opens.

7. Define the PostgreSQL credentials to be used for Fusion.

   Option | Description
   --- | ---
   User Name | Type the User Name of the PostgreSQL superuser to be created. Limits: Must be at least one character in length; maximum 63 characters. Can contain only letters, numbers, or underscores; the first character cannot be a number. NOTE: This is not a Windows account.
   Password | Type the desired password for the superuser to be created.
   Verify Password | Re-type the password.

8. Click Next.

9. Provide the credentials necessary for completing the installation.

   Option | Description
   --- | ---
   URL for the cloud gateway | Type the gateway URL and port number as defined in the Assign Agent panel on the Agent Download page. This is the main access point in the cloud. TIP: Click the link icon () to copy the Gateway URL to your local clipboard.
   Tenant ID | Type the tenant ID for the Fusion instance to which this agent is assigned.
   User Name | Type the User Name of a user in your tenant that will be used to connect the agent to the cloud. This user must have the Manage agents permission for the Connect component.
   Password | Type the password for the user defined.

   Click Next.

   The Ready to Install the Program dialog opens.

10. If you need to make changes, click Back to work your way back, modify as desired, and then work forward to this dialog.

    Click Install.

    The installation begins.

11. When the installation completes, click Finish.

    NOTE: The Agent Admin UI can be accessed from the Start menu. From the Start menu, click Fusion Agent > Agent Admin.

12. Set the logon account for the Fusion services.

    The user account must be a local or domain account that is in the agent host's Administrators group and has the Logon as a service permission.

    1. Using one of the following methods, stop the Fusion services.

       - Using the Service Control Panel

         1. Open the Service Control panel.

         2. Except for the Fusion PostgreSQL service, stop all other services that start with Fusion.

       - Using a PowerShell script

         1. Open PowerShell as an administrator.

         2. Change the directory to `\Agent\bin` within the agent installation path. For example, `C:\Program Files\Fusion\Agent\bin`.

         3. Using the following command, stop the Fusion services.

                _stop_all_services.ps1

    2. Open PowerShell as an administrator.

    3. Change the directory to `\Agent\bin` within the agent installation path. For example, `C:\Program Files\Fusion\Agent\bin`.

    4. Using the following command, set the logon account. Provide the requested information.

           _set_services_run_as.ps1

       Username | Type the user name of the user in the Administrators group that will be used to log on to the Fusion services. For a local user, use the format `machineNetBIOS\username`. For a domain user, use the format `domainShortName\username`. NOTE: This is different than the user defined in the installation wizard.
       Password | Type the password for the user defined.

    5. Reauthorize the agent.

13. (Optional) Configure cloud connection web proxy settings.

14. Using one of the following methods, start the Fusion services.

    - Using the Service Control Panel

      Open the Service Control panel and start all stopped services that start with Fusion.

    - Using a PowerShell script

      1. Open PowerShell as an administrator.

      2. Change the directory to `\Agent\bin` within the agent installation path. For example, `C:\Program Files\Fusion\Agent\bin`.

      3. Using the following command, start stopped Fusion services.

             _start_all_services.ps1

15. Repeat the agent installation process on any additional agent host servers.

### Reauthorize the agent

If you need to reauthorize the agent within the same tenant, you must run the credential utility and enter the credentials for the authorized user.

To reauthorize the agent

1. From the machine hosting the agent, open the credential utility, `AccessHandler.exe`.

   Default location: `C:\Program Files\Fusion\Agent\bin\AccessHandler.exe`

   TIP: For details about the entries you will make when running the credential utility, run the credential utility from a command line with the help option.

   Example: `AccessHandler.exe -h`

2. Provide the requested information.

   Option | Description
   --- | ---
   Gateway URL | Type the gateway URL and port number as defined in the Assign Agent panel on the Agent Download page. This is the main access point in the cloud. TIP: Click the link icon () to copy the Gateway URL to your local clipboard.
   Tenant ID | Type the tenant ID for the Fusion instance to which this agent is assigned.
   User Name | Type the User Name of a user in your tenant that will be used to connect the agent to the cloud. This user must have the Manage agents permission for the Connect component.
   Password | Type the password for the user defined.

3. Follow any additional guidance in the command prompt regarding success or failure of credential validation.

## Define antivirus exclusions (Optional)

To ensure that the agent runs at optimal performance, some exclusions must be defined when running an antivirus application on your agent hosts. These exclusions are specific to the Fusion agent application.

CAUTION: Although not required, OpenText strongly recommends that you exclude the services and paths defined in this section if you are running an antivirus application on your agent hosts. Not doing so, performance on these hosts will be dramatically reduced.

In your antivirus application, define the following exclusions.

- Folders to exclude:

  - The agent installation directory.

    Example: `C:\Program Files\Fusion\Agent`

- Files to exclude:

  - ACADataProcessor.exe

  - ConnectorFramework.exe

  - FileSystemProcessor.exe

  - kvoop.exe

  - postgres.exe

## Configure cloud connection web proxy settings (Optional)

The AgentAPI service controlled by the processing agent requires connectivity to the Fusion cloud components, often located away from the local network where the agent host servers are located. Although direct connectivity is ideal, use of a web proxy may be required in some environments for the agent systems to reach the Fusion cloud.

IMPORTANT: Web proxy information entered here take precedence over any system proxy information defined for the current /run as user.

To configure the cloud connection using the agent administration UI

1. On an agent host server, log on to the agent administration UI.

   From the Start menu, click Fusion Agent > Agent Admin.

2. In the navigation panel, click Advanced Settings.

   The Advanced Settings page opens.

3. In the Category list, select Agent API.

   The settings for the AgentAPI service display.

   NOTE: This defines the proxy settings for the AgentAPI service. If you need to define the proxy for all Fusion services, select Common instead of AgentAPI. If unsure, contact Fusion support.

4. Complete the following options.

   Option | Description
   --- | ---
   Proxy Address URL | Type the URL of the web proxy
   Proxy Bypass List | If applicable, type a comma delimited list of addresses that do not use the proxy server.
   Proxy Bypass on Local | Specify whether to bypass the proxy for local addresses. Select True to bypass for local addresses. Select False to not bypass for local addresses.
   Proxy Password | Type the password for the user account that will access the proxy server.
   Proxy Username | Type the username for the user account that will access the proxy server.

5. Click Save.

6. Repeat for each agent server connecting to the Fusion cloud.

## Configure free space for processing large files (Optional)

If you plan to process very large files, such as ZIP files, you may need to ensure the file size settings related to available free space on the processing agent host server. For example, you have many ZIP files that are 2+ GB but expand to 12 GB each when fully extracted. Processing may slow down and storage may be reduced to an undesirable level.

CAUTION: Do not adjust these values unless it is necessary. If you have any questions, contact Support.

To configure free space for processing large files

1. On the agent host server that will be processing very large files, log on to the agent administration UI.

   From the Start menu, click Fusion Agent > Agent Admin.

2. In the navigation panel, click Advanced Settings.

   The Advanced Settings page opens.

3. In the Category list, select Common.

   The settings for the common configurations display.

4. Make the following selections.

   1. In the Maintain Free Space MB field, update the value to `24000`.

   2. In the Mi Free Space MB field, update the value to `16000`.

5. Click Save.

6. Repeat for each agent server that will be processing very large files.

Copyright 2019-2023 Open Text
Version 23.4.0 | Last updated October 2023
Connect
Marketplace
Learn
Support portal
Documentation
Contact
Submit or view service request