API DocumentationProduct Documentation
Product Documentation

Tetra Empower Agent Installation Guide (v5.3.x)

Suggest Edits

This guide describes how a system administrator can install and run Tetra Empower Agent versions 5.3.x.

To configure and use the Agent after it's installed, see the Tetra Empower Agent User Manual (v5.3.x).

🚧

IMPORTANT

This version of the Tetra Empower Agent has changes that impact the Tetra Empower intermediate data schemas (IDS) and their parsers. Using this version of the Tetra Empower Agent with an incompatible or older version of the protocol and IDS will break your pipelines.

Please make sure that you have the compatible versions of the Tetra Empower IDS parsers and update the pipelines and processes to use the new protocols and IDS, so that pipelines continue to work as expected. For more information about the compatible IDS, protocol, and task script versions, see the Tetra Empower v5.x.x release notes.

To install and run Tetra Empower Agent v5.3.x, do the following:

  1. Verify the prerequisites:
    • Make sure that hardware and software requirements are met
    • Make sure that you have the required user account credentials
  2. Set up a data connection.
  3. Install the Tetra Empower Agent.
  4. Verify the installation.
  5. Verify the data connection:
    • Verify the connection to empower
    • Verify the empower group account
    • Verify connection settings
    • Verify injection configuration settings
    • Save and start the Agent
    • Verify that the Tetra Empower Agent can retrieve Empower data

For instructions, see the procedures in each of the following sections.

🚧

Important Upgrade Considerations

If you're upgrading the Tetra Empower Agent from the previous version, make sure that you always back up the Agent’s SQLite database first. The Agent's SQLite database is in the following location:<existing_empower_agent_installation>\db\applicationdb.sqlite

Step 1: Verify the Prerequisites

Hardware and Software Requirements

🚧

IMPORTANT

For the Tetra Empower Agent to automatically detect injection changes in an Empower project, the project must have Full Audit Trail enabled. This feature can only be activated when you first create an Empower project. If a project doesn't have Full Audit Trail enabled, the Agent can only process new injections, but not changes to any existing injections. For more information, see the Empower Software Audit Trails and Logs White Paper.

To install and run Tetra Empower Agent v5.3.x, the following hardware and software versions are required:

  • One of the following Microsoft Windows versions:
    • Microsoft Windows 10 Enterprise or Professional, 64-bit editions
    • Microsoft Windows Server 2016 Standard or 2019 Standard
  • .NET Framework 4.8
  • 16 GB RAM minimum (64 GB RAM is recommended)
  • 8 Core CPU
  • 300 GB of free disk space minimum (The required disk space needs to accommodate both the project data fetched from the Empower Oracle database and the project RAW files from the Empower File System.
  • Empower 3 Service Release 2 or higher Client Software (English Edition)
  • If installing Empower software on an English-language computer, make sure that you confirm that the Windows region settings are configured for English (United States). The symbols for English (United States) use decimal formatting, not comma formatting, which is important when displaying numeric values (for example: 12.56, not 12,56)

🚧

IMPORTANT

You must install the Tetra Empower Agent at the same workstation where the Empower 3 Client Software is running. The Tetra Empower Agent is compatible with Empower 3 Service Release 2 or higher. If the Empower 3 Client version is earlier than Service Release 2, then you must upgrade the Empower 3 Client software. For detailed system requirements, see the Client Software section in the Empower 3 System Administrator Guide.

User Account Credentials

To run Tetra Empower Agent v5.3.x, you must have the following valid user account credentials.

Empower Database User Account

The Empower Database User Account provides access to the Empower database through the Empower Toolkit. Projects that can be extracted by using the Tetra Empower Agent are contingent on the access permissions granted to the User Group associated with the Empower Database User Account.

The account's Default User Type must have the following permissions:

  • View Audit Trails
  • Backup Projects
  • Delete Projects
  • Restore Projects
  • Lock Projects
  • Unlock Projects
  • Create Projects at root

Empower Oracle TNS Names Details

Empower Oracle TNS Names details provides access to the Empower database through the Empower client (the required information can typically be found in the <Oracle Client Install folder>\\network\\admin\\tnsnames.ora file in the Oracle folder of the Empower client machine).

Oracle TNS Names Details

Oracle TNS Names Details extracts the datetime fields in a consistent ISO format.

Group User Account

The Group User Account runs the Tetra Empower Agent and accesses the Empower file server. You must ensure that the Group User Account that runs the Tetra Empower Agent is part of the Empower User Group in the Active Directory Organizational Unit, and has the same privileges as the standard Empower User, which requires read-only permissions to access the Empower RAW data on the Empower File System.

The Group User Account must also meet the following requirements from Empower and Windows:

  • Windows Log on as a service permissions to run the Agent as a Windows Services program
  • The date time and decimal format settings of the Group User's Windows Profile must match the settings from the current login user that's configuring the Agent

Step 2: Set Up a Data Connection

The Tetra Empower Agent generates RAW JSON files that are uploaded to the TDP either directly or through a Data Connector. Before you install the Tetra Empower Agent, you must set up the agent's data connection to the TDP by using one of the following methods:

  • TDP (No Connector): Connects Agents directly to the TDP and AWS APIs, or through a proxy that you configure in the Agent host server's settings. For instructions, see TDP (No Connector) Connections.
    -or-

For more information, see Agent Deployment Options.

Step 3: Install the Tetra Empower Agent

TetraScience provides a Microsoft Installation Package (.msi) file to install the Tetra Empower Agent on the host server.

To get the installation package and install the Agent, do the following:

  1. Get the link to the .msi installation package by contacting your TetraScience customer success manager (CSM).
  2. After you have the link to the installation package, download the Agent to a machine that runs a supported Empower version.

🚧

IMPORTANT

To access the server and run the installation package, you must sign in as an Administrator.

  1. Move the downloaded files to a local folder.
  2. In the local host server's terminal, run the following command to install the software: TetraScience.Agent.Empower.v5.3.0.msi

Default Installation Folder Location

C:\TetraScience\TetraScience.Agent.Empower.v5.3.0\

After the Tetra Empower Agent is installed, the TetraScience Agent Empower shortcut is added to the Windows All Program Group menu. To initialize the Tetra Empower Agent, you must add the configuration settings.

📘

NOTE

To restrict access to the local Tetra Agent Management Console, you can edit the Agent’s installation folder’s permissions to grant least privilege access. For more information, see Restrict Access to Agent Installation.

Step 4: Verify the Installation

Confirm that the Tetra Empower Agent was installed on the local drive by verifying the following:

  • The TetraScience Empower Agent is installed under the C:\\TetraScience directory by default.
  • Under the TetraScience folder, TetraScience.Agent.Empower.v5.3.x appears.
  • The following subfolders appear under the TetraScience.Agent.Empower.v5.3.x folder:
    • bin
    • bin64
    • db
    • logs
  • The TetraScience folder is added to the Windows Start Menu, which includes the TetraScience Agent Empower application

📘

NOTE

To launch the TetraScience Empower Agent Management Console, select the TetraScience Agent Empower link in the Windows Start Menu.

Step 5: Verify the Data Connection

To verify that the Agent can connect to Waters Empower Software and the TDP, do the following.

Verify the Connection to Waters Empower

To verify that the Agent can connect to Waters Empower, do the following:

  1. On the host server, open the Tetra Empower Agent Management Console. Then, in the left navigation menu, under Menu, choose Configuration.

  2. Populate the the following fields in the Empower Database section:

  • For Database Name, enter your Waters Empower Database Account.
  • For User Name, enter your Waters Empower User Account.
  • For Password, enter your Waters Empower User password.
  • For Oracle Host Name, enter your Waters Empower Database Oracle Host Name (you can get this information from tnsnames.ora file).
  • For Service Name, enter your Waters Empower Database Oracle Service Name (you can get this information from tnsnames.ora file).
  • For Port, enter your Waters Empower Database Oracle Port (you can get this information from tnsnames.ora file).
  1. Select Test Connection. Then, do one of the following based on if the connection test is successful or not:
  • If the connection was successful, a dialog appears. Select OK to confirm the connection to the Empower system.
    -or-
  • If the connection was not successful, then check the database account name, Empower user account credentials, and the Oracle host information. Then, repeat the steps in this section to verify the connection.

Verify the Empower Group Account

The Empower Group User is the Windows user that the Agent service runs as locally. It is recommended that you create a service user account specifically for the Tetra Empower Agent.

To verify the Empower Group Account credentials, do the following:

  1. On the host server, open the Tetra Empower Agent Management Console. Then, in the left navigation menu, under Menu, choose Configuration.
  2. For User Name, enter the Waters Empower User Group Account.
  3. For Password, enter the user password.

After focus leaves the password field, the Tetra Empower Agent validates the account immediately.

Verify Connector Settings

To verify that the Agent can communicate with the TDP, do the following:

  1. From the Tetra Empower Agent Management Console, in the left navigation menu, under Menu, choose Configuration.
  2. Verify that the S3 Direct Upload toggle is set to active (the default value is set to active). For more information, see S3 Direct Upload (Recommended).
  3. Select the Receive Commands toggle so that it's set to active (the default value is set to inactive).
  4. (Optional) To reset the default settings for data connection status checks and Agent log file uploads, select Advanced Settings. The Agent Configuration Advanced Settings dialog appears, which includes the following settings:
    • Data Connection status check every: Indicates how often the software checks the status of the connection (heartbeat) between the TDP and the Agent. If the TDP doesn't receive a heartbeat message for more than five minutes, the TDP assumes that the Agent is offline. The default value is 30 seconds.
    • Agent log files upload every: Indicates how often the Agent uploads log files to the Data Lake. The default value is 300 seconds.
    • To keep the recommended settings, or to save the new values you entered, choose OK. Only consider changing these values if connection checks (heartbeat) frequency needs to be changed, or if log files need to be uploaded to the TDP at a different frequency.
  5. For Agent Id, enter the Agent ID (you can find this on the Agents page in the TDP).
  6. For the Connection Url field, enter the complete URL of the Tetra Hub, Generic Data Connector (GDC) attached to a Data Hub, or No Connector, based on your connection type.
  7. (For “TDP (No Connector)” setups only) If you’re using an Agent without a Connector, make sure that you do the following:
    • For Org Slug, enter your organizational slug. To get your organizational slug, see Viewing Organization Details. The organizational slug is required when using a JSON Web Token (JWT). Adding the slug to this field attaches it to the Agent’s API request headers.
    • For Authorization, select Add/Edit. Then, enter your JWT in the dialog that appears. To get a JWT, see Generate a JSON Web Token for an Existing Service User. Then, choose Save to encrypt and save the JWT. The Agent validates the connection immediately and displays the updated connection status next to the Connection Url field.
  8. (Optional) To specify the Destination Id for allowing the files to be uploaded to the same S3 location from multiple agents. Destination Id is a UUID. This feature helps to split the load into multiple agents for scaling horizontally.
  9. Verify Enable Injection Service is set to Yes and Enable Archive Service is set to Yes.
    After you enter the information, the Tetra Empower Agent immediately validates the connection status.

Verify Injection Configuration Settings

To confirm that the Empower Injection configuration settings, do the following:

  1. In the Agent Management Console, open the Configuration page.
  2. In the Empower Agent Output Settings section, for Output Folder, enter a valid folder path .
  3. In the Agent Run Time section, for Injection make sure that Upload Raw File to TDP is set to Yes.
  4. For Data Precision Specification, leave the default option, Empower.

Save and Start the Agent

In the Agent Management Console, select the Save button at the top of the page. Then, select the Start button and verify that the Agent Status displays as Running.

Verify that the Tetra Empower Agent Can Retrieve Empower Data

When the Tetra Empower Agent is running, you can validate the detection, generation, and upload of a Tetra Empower Agent RAW JSON file by doing the following:

  1. Open the Tetra Empower Agent Management Console. Then, under Menu in the left navigation menu, select Injection Service and choose Project.
  2. Choose Refresh to retrieve the most recent list of Empower projects.
  3. From the Project list, select a test project (for example, Demo).
  4. Select the 3D MS Method option for the selected project. The default setting is Get3D. You can also select None or GetSpectra. To understand how this impacts the injection generation, see Tetra Empower Agent User Manual (Version 5.3.x).
  5. Choose Save.

🚧

IMPORTANT

When selecting Empower as the option for Data Precision Specification, make sure that you verify the setting of Number of Digits of Precision for Area and Height in the Processing tab from Empower Project Properties.
The Agent will output the values with the specified precision.

image

Verify Processing Status

To check the file processing status, do the following:

  1. From the Tetra Empower Agent Management Console, navigate to the Injection Summary tab, and review the Tetra Empower Agent status.
  2. After the Agent completes its routine scan and generates the RAW file, you can validate these tasks listed in the Processing Summary section:
    • Scanned Injections: Number of injections the Agent detected for the Demo project
    • Generated RAW File: Number of injections the Agent retrieved for the Demo project
    • Uploaded: Number of injections the Agent uploaded to the Tetra Data Platform

The count for each step listed in the Processing Summary section should match the total injection count in the Waters Empower client.

Verify That the Generated RAW Files Are Uploaded to the TDP

To confirm that the RAW files are uploaded to the TDP, do the following:

  1. Sign in to the TDP.
  2. In the left navigation menu, choose Search. A menu appears.
  3. From the menu, choose Search. The Search page appears.
  4. Check the RAW files of project Demo in the search results.
  5. Verify that the total number of RAW files from project Demo equals 131.

Next Steps

To configure and use the Agent after it's installed, see the Tetra Empower Agent User Manual (v5.3.x).

📘

NOTE

When configuring the Agent, you can use a Windows task script to automatically restart the Tetra Empower Agent each day at a specific time. This setup ensures that the Agent remains online without having to check it each day. For instructions, see Windows Scheduled Task Settings in the Tetra Empower Agent User Manual (v5.3.x).

Updated about 4 hours ago