Agent installation and configuration

Data Discovery uses a processing agent, installed on one or more host servers within the Data Discovery environment, to communicate with your repositories 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 repositories, 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.

Minimum resources

The host for the agent requires the following minimum resources:

  • Number of CPUs (include virtualized CPUs): 4

  • RAM: 8GB

TIP: This is equivalent to an AWS c5.xlarge instance or an Azure A4v2 virtual machine.

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 2012 R2 (Standard, Datacenter)

    The “Server with a GUI” installation option is required.

  • Windows Server 2016 (Standard, Datacenter)

    The "Server with Desktop Experience" installation option is required.

  • Windows Server 2019 (Standard, Datacenter)

    The "Server with Desktop Experience" installation option is required.

SQL

Ensure that you are running a supported version of SQL with all currently "critical" and "important" updates installed from update.microsoft.com up to and including the current Cumulative Update for the version.

TCP/IP Protocol must be installed and enabled (Mixed Mode Authentication)—not just Windows authentication.

  • SQL 2016 SP2 (Standard, Enterprise, Express; on all supported Windows Servers)

  • SQL 2017 (Standard, Enterprise, Express; on all supported Windows Servers)

  • SQL 2019 (Standard, Enterprise, Express; on Windows Server 2016, 2019)

General

  • 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 that you have administrative rights on each server. You cannot perform the installation unless you have administrative rights to perform the required tasks.

  • Microsoft Outlook 2013 x64 to process PST files located on file systems.

  • SMTP (currently optional)

  • Current Visual Studio 2010 Runtime

  • .NET 4.6.2+

    • For Windows Server 2012 R2, this is a selectable Windows Feature. The base version is ".NET Framework 4.5" which is then updated using Windows Update.

    • Windows Server 2016 and 2019; this is a selectable Windows Feature. The base version is ".NET Framework 4.7 Advanced Services".

  • PowerShell 3.0+

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

  • Micro Focus Content Manager 9.4

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

  • File system CIFS shares

  • Microsoft Exchange Server 2013 and 2016, 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.

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

  1. Create at least one agent cluster in the Connect application.

  2. Download the agent.

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

    Install the agent on any additional agent host servers.

  4. If completing the minimal installation method, configure the agent on the first agent host server.

    Configure the agent on any additional agent host servers.

  5. Define antivirus exclusions to ensure optimal agent performance.

  6. Configure cloud connection web proxy settings (Optional) if Data Discovery is installed in the cloud.

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

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

Download the agent

The agent is downloaded from the Agent Clusters page of Connect.

NOTE: You must create at least one agent cluster before you can download the agent. The download icon does not display if you have not created any agent clusters.

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

    The Agent cluster page opens.

  2. Click the download icon above the list of clusters.

    The Agent Download and Installation page opens.

  3. In the Download Agent section, click DOWNLOAD.

  4. 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.

  • When you install the agent, you have the option to install the most current supported Microsoft SQL Server Express on the agent host as part of the agent installation. SQL server is a requirement for the agent installation, so if a supported version of SQL server is installed in your environment and accessible to the agent host machine, select the "minimal" installation.

  • You must use ASCII characters for any entries that you make for user names or passwords.

  • You cannot use the @ symbol in database passwords related to the agent installation.

  • You cannot use double quote characters “” in the SQL SA password or the database creation will fail. When the SQL server receives the password, it cannot differentiate whether the double quotes are part of the password or surround the password.

  1. If not already completed, copy the agent installation file (dma.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 (dma.exe).

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

    TIP: You may be informed of any missing prerequisites.

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

    The License Agreement dialog opens.

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

    The Choose Install Folder dialog opens.

  6. Accept the default location (C:\Program Files\Micro Focus\FAS\Agent), or modify it as desired (it must be local), and then click Next.

    The Choose Install Set dialog opens

  7. Select one of the following installation options.

    • Complete installs the agent and supporting components, as well as the most current supported SQL Server Express on the agent host machine.

      This installation method automatically installs SQL Server Express with a default SQL "sa" password and configures the agent databases with a default database user and password.

      • Default sa password: P@ssw0rd

      • Default database user: FASdbuser

      • Default database user password: P@ssw0rd1234$#@!

    • Minimal installs only the agent and supporting components on the agent host machine.

      This installation method requires you to configure the agent to define the databases and credentials to access them.

      IMPORTANT: Choose this option if a supported version of SQL Server is installed in your environment and accessible to the agent host machine.

    Click Next.

    The Choose Shortcut Folders dialog opens.

  8. Specify your shortcut options.

    • Select the location where you want the program shortcuts to be placed.

    • Select whether to create the selected shortcuts for all users who log on to the agent host machine.

    Click Next.

    The Pre-Installation Summary dialog opens.

  9. Review the summary.

    If you need to make changes, click Previous to work your way back, modify as desired, and then work forward to the Pre-Installation Summary.

    Click Install.

    The components install and appropriate services are started.

    NOTE: If you selected the Complete installation option, SQL Server Express will be installed at this time. Follow any on-screen prompts to complete the SQL Server installation.

  10. When prompted, click Next on the Provide Credentials dialog. The credential utility opens a command prompt to define credentials the agent will use to connect to the environment.

    In the command prompt, enter the requested credentials for an authorized user in the tenant in which you are installing this agent.

    1. When prompted, type the Gateway URL including the port number, and then press Enter on your keyboard.

      TIP: This is the main access point in the cloud. For your convenience, this URL is provided in the Assign Agent panel on the Agent Download page in Connect.

      Example: https://machine-01.domain.com:9312

    2. When prompted, type your Tenant ID, and then press Enter on your keyboard.

    3. When prompted, type the User Name of a user in your tenant that has the Systems Administrator permission, and then press Enter on your keyboard.

    4. When prompted, type the Password for the user defined, and then press Enter on your keyboard.

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

    The Finalizing dialog opens.

  11. The databases and additional required components will be installed next; click Next.

    The Install Complete dialog opens.

  12. Review the final details and then click Done.

    The installer automatically closes when it finishes.

    The Agent Configuration opens. The initial configuration page appears. You can begin the configuration of this server immediately, or run the agent installation on any additional agent hosts and then configure each server.

    NOTE: The Agent Configuration UI can be accessed from the Start menu. From the Start menu, click Micro Focus FAS Agent > Agent Admin.

  13. If you chose the Complete installation and Outlook 2013 is installed on the host, reboot the host machine.

  14. 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.

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

    Default location: C:\Program Files\Micro Focus\FAS\Agent\bin\AccessHandler.exe

  2. When prompted, type the Gateway URL including the port number, and then press Enter on your keyboard.

    This is the main access point in the cloud.

    Example: https://machine-01.domain.com:9312

  3. When prompted, type your Tenant ID, and then press Enter on your keyboard.

  4. When prompted, type the User Name of a user in your tenant that has the Systems Administrator permission, and then press Enter on your keyboard.

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

Configure the agent

Upon completion of the agent install, the agent configuration UI opens. This configuration walks you through setting up the various components of the agent and setting connections and authentication.

  1. On the agent host server, open the Agent administration UI if it is not open already.

    From the Start menu, click Micro Focus FAS Agent > Agent Admin.

    The UI opens to the Database tab.

  2. Define the details for the name, location, and access credentials of the agent databases.

    Option Description
    Database Host

    Defines the host name of the SQL server onto which the agent databases are to be installed.

    Default: machine name of server being configured
    Port or Instance

    Defines the port number or instance name for the SQL server used for communication with the agent databases.

    Default: 1433
    Central Database Name

    Defines the name of the Central database.

    Default: fas_central_machine name of server being configured
    Server Database Name

    Defines the name of the data processor server database.

    Default: fas_dp_machine name of server being configured
    New Database User

    Defines the user name for the SQL account that the agent services use to access the agent databases (using an ODBC connection). The agent installation process creates this account if it does not exist.

    Default: FASdbuser

    Limits: Fewer than 64 characters and cannot contain the following special characters: " / \ [ ] : ; | = , + * ? < > - '
    New Database User Password Defines the password for the database user SQL account that the agent services use to access the agent databases (using an ODBC connection). The password is encrypted on-screen.
    Confirm Password Defines the password for the database user SQL account. Ensure that this entry matches the New Database User Password entry.
    SA User Name

    Defines the user name for the SQL server admin user that will have access to the agent databases. This must be "sa" or an equivalent.

    Default: sa
    SA Password Defines the password for the SQL server admin user who has access to the agent databases.

    Click NEXT.

    The Database Files tab opens.

  3. Define the details of the data files for the databases.

    Option Description
    Default Data Files Directory

    Defines the location to store the agent's SQL-generated data. This directory is local to the SQL server.

    Default: C:\Program Files\Microsoft SQL\Micro Focus FAS Agent Server\SQL version reference\MSSQL\DATA
    Number of files per filegroup

    Defines the number of files per filegroup.

    Default: the number of CPUs detected
    Data Files Directories

    Defines an alternate location to store the specific agent-generated files. These directories are local to the SQL server. Used to override the value set for the Default Data Files Directory.

    Defaults to the value set for the Default Data Files Directory. Changes to the Default Data Files Directory automatically; update the individual entries.

    Click NEXT.

    The Confirmation tab opens.

  4. Review the details for the configuration. When viewing the database data file locations, only the individual data file paths that differ from the default data file path appear. If all of the individual data files differ from the default data file path, the default data file path does not appear.

    Click NEXT.

    The Run Database Scripts tab opens.

  5. Specify the how the database creation scripts are run.

    Option Description
    Automatically run database scripts

    Specifies to automatically run the database scripts as part of this configuration process.

    Manually run database scripts

    Specifies that you will manually run the database scripts.

    This option is useful if your environment does not support installing the SQL databases over the network.

    Click NEXT.

    • If you selected to automatically run the database scripts, the Processing tab opens; skip the next step in this procedure.

    • If you selected to manually run the database scripts, the Manual Scripts tab is added and opens.

  6. If you chose to manually run the database scripts, complete the following.

    1. Review the STEPS to manually run the scripts.

    2. Log into SQL Server with the SQL server admin user that you defined in the Agent Admin.

    3. Open the specified script location and open fas_central.sql to create the central database. The file opens in SQL Server Management Studio.

      Execute the script.

    4. When the script execution finishes, open and execute fas_server.sql.

    5. When the script execution finishes, return to the Agent administration UI.

    6. On the Manual Scripts tab, click NEXT.

  7. You can view the progress of the configuration on the Processing tab.

    When the configuration process completes, click NEXT.

    The configuration is complete.

    You are redirected to the agent administration UI. If you will not be processing data in Content Manager, you can close this UI. If you are processing Content Manager data (through repositories), you will use this UI to complete the integration with Content Manager. For more information, see Content Manager integration.

  8. Repeat this configuration process on any additional agent host servers.

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 Data Discovery agent application.

CAUTION: Although not required, Micro Focus strong recommends that you exclude the services and paths defined in this section if you are running an antivirus appliction 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\Micro Focus\FAS\Agent

    • The SQL directory for the agent's SQL databases data files. If you installed the data files for your Central and Data Processor databases to different locations, exclude each data file root directory.

      Example: C:\Program Files\Microsoft SQL Server\MSSQL.x\MSSQL\DATA\Micro Focus FAS - Agent Admin

    • The directories for SQL database data files that are part of the SQL application.

  • Files to exclude:

    • ACADataProcessor.exe

    • ConnectorFramework.exe

    • FileSystemProcessor.exe

    • kvoop.exe

    • sqlservr.exe

Configure cloud connection web proxy settings (Optional)

The AgentAPI service controlled by the processing agent requires connectivity to the Data Discovery 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 Data Discovery cloud.

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

    From the Start menu, click Micro Focus FAS Agent > Agent Admin and log on with the following credentials.

    • User name: admin

    • Password: admin

  2. In the navigation panel, click Advanced Settings.

    The Advanced Settings page opens.

  3. In the Category list, select AgentAPI.

    The settings for the AgentAPI service display.

  4. Make the following selections.

    1. In the Proxy Address URL field, enter the URL of the web proxy.

    2. In the Proxy Bypass List field, enter a comma separated list of addresses that do not use the proxy server.

    3. In the Proxy Bypass on Local field, specify whether to bypass the proxy for local addresses.

    4. In the Proxy Password field, enter the password for the user account that will access the proxy server.

    5. In the Proxy Username field, enter the username for the user account that will access the proxy server.

  5. Click Save.

  6. Repeat for each agent server connecting to the Data Discovery cloud.