Tetra LabX Agent Installation Guide (v2.0.0)

🚧

IMPORTANT

The Tetra LabX Agent must be installed in the same time zone as the LabX host server. If the Agent and LabX host servers are in different time zones, the Agent won't be able to interpret the timestamps returned by the LabX server.

This installation guide is for Tetra LabX Agent version 2.0.0.

This page describes how to do the following:

• Install the Tetra LabX Agent
• Configure the firewall settings
• Configure the Tetra LabX Agent
• Configure the Tetra LabX Agent Integration Services
• Start and Stop the Tetra LabX Agent

📘

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.

Install the Tetra LabX Agent

TetraScience provides an installation package (.msi). To access the server and run the installation package, you must log in as an Administrator. The default Tetra LabX Agent installation path is: C:\TetraScience\Tetrascience.Agent.LabX.v2.0.0.

After the Tetra LabX Agent is successfully installed on the server, you can access its Windows-based Management Console under the TetraScience folder from the Windows Programs.

Configure Firewall Settings

Based on where you installed the Tetra LabX Agent, you may need to set firewall ports.

• If you installed the Tetra LabX Agent on the same server where LabX is installed and running, then no firewall action is required.
• If you installed the Tetra LabX Agent to run on a different server from where LabX is installed and running, then:
  1. If you installed the Tetra LabX Agent on the LabX server properly, then these required firewall port exceptions should already be set automatically:
     • Port 51155
     • Port 51156
     • Port 51157 (if it is HTTPS connection)
  2. To communicate with the LabX Integration Service on the Agent server, you must add at least one outbound firewall exception. The default HTTP LabX InstrumentService endpoint is:
     http://<address of server>:51155/LabX/BasicSystemIntegrationService.

Configure the Tetra LabX Agent

After you have successfully installed the Tetra LabX Agent, use the Windows-based Management Console to continue the Agent configuration.

The Management Console is divided into five sections:

• Windows Scheduled Task
• LabX Group User
• Agent Configuration
• LabX Task Configuration
• LabX Audit Trail Configuration

Section 1: Set Windows Scheduled Task

You can increase the Agent's reliability by ensuring that it remains online without having to manually check it each day.

1. Select Yes to enable the Windows Scheduled Task to check Agent Service Status option on a daily basis.
2. Specify the time in the Run Time field when you want the scheduled Windows task to check on the status of the LabX Agent service.

• If the Agent is stopped, then the scheduled Windows task automatically restarts the Agent service.
• If the Agent is running, nothing further happens.
• If you manually stop the Tetra LabX Agent, then the Windows task is removed, and the Windows Task that you create runs under the LocalSystem account.

Section 2: LabX Group User

The LabX Group User is the service account that runs the Tetra LabX Agent.

• If you leave the User Name field blank, then the Tetra LabX Agent runs using the Windows predefined LocalSystem account.
• If the Tetra LabX Agent monitors the network's shared folders, then we suggest that you provide a service account that:
  • Has at least read and List folder content permission of the network shared folders (including the subfolders and files contained in those folders).
  • Is part of the local user group of the host server.
  • Requires log on as service permission.

When the you enter the LabX Group User Name and Password, the Agent validates the account immediately. If the user name and password are correct, then the Tetra LabX Agent displays a Valid status next to the field.

Section 3: Agent Configuration

Use this section to configure the Agent connection the Tetra Data Platform. TetraScience provides several options to connect the Tetra Data Platform. Click this link to select the best option for your company's needs.

S3 Direct Upload

To have the Tetra LabX Agent directly upload files to the AWS S3 bucket bypassing the Agent API, set the S3 Direct Upload option to Yes. When you set this option to Yes, you can upload a maximum file size of one TB. No is the default setting.

• If you use the S3 Direct Upload option with GDC, you must add an L7 Proxy Data Connector in the same Data Hub where you set up the GDC. Additionally, the port of the L7 Proxy Data Connector is open. To learn more about GDC, see this link.
• To learn more about Agents without connectors, see this link.

📘

SQLite Database File Backups

To enable the Tetra LabX Agent to automatically perform regular backups of the SQLite database file, set the S3 Direct Upload option to Yes. When you enable this option, the SQLite database file (which stores agent configuration data) is uploaded to the backup bucket in the Data Lake. If a Tetra LabX Agent failure occurs, you can restore the database file from the backup bucket and continue processing.

If you do not use not use the S3 Direct Upload option, then we recommend that you create periodic backups of the Tetra Agent database, which is typically stored in the installation folder under C:\TetraScience<agent>\Bin\Database. In the event of a failure (for example, if the host server drive is lost), this would enable the data extraction to continue from where it left off without having to re-upload all of the data.

Advanced Settings

1. Click Advanced Settings to open the Agent Configuration Advanced Settings pane.

You can specify the time intervals for these fields (default value for each field is 30 seconds):

• Data Connection status check every - Indicates how often the software checks the status of the connection (heartbeat) between the Tetra Data Platform and the LabX Agent. If the Tetra Data Platform does not receive a message indicating that the LabX Agent is "alive" for more than 5 minutes, it assumes that the Agent is offline.
• File Upload Job runs every - Indicates how often to upload files to the Data Lake.
• Agent log files upload every - Indicates how often to upload log files to the Data Lake.

📘

Software Version 3.4 Update

To improve readability, the After a watched file is modified, wait for it to stop changing field was renamed to File Upload Job runs every, and the Upload Log File field was renamed to Agent log files uploads every.

Agent ID and Connection URL

Before you set up a Tetra LabX Agent, you must enter:

• (Required) An Agent ID. The Agent ID (a UUID) is used to connect the Tetra Data Platform. You can retrieve Agent ID from the Tetra Data Platform when you set set up the Agent.
• A full connection URL from GDC or direct API (as shown in these URL examples):
  • GDC URL is http://10.100.1.1:8888/generic-connector/v1/agent
  • API URL is https://api.tetrascience-dev.com/v1/data-acquisition/agent/

📘

Verify the Agent ID and Connection URL

• Agent ID is required. The Connection URL is required if you are uploading RAW files to the Tetra Data Platform; optional, if you are not.
• Before you use the Agent ID and URL with the Tetra Data Platform, we strongly suggest that you verify both with your TetraScience Customer Success Team.

If you use the Connector without an Agent, then you must:

1. When using the JWT token, the Org Slug field is required. Enter the Org Slug to attach it to the header.
2. Enter the JWT token in the Authorization field to attach it to the header. To learn how to get the JWT token, see this reference.
3. Click Add/Edit to open a dialog and enter the JWT token.
4. Click Save to close the dialog and encrypt and save the JWT token. The Agent validates the connection immediately and displays the updated connection status next to the Connection URL field.

Section 4: Configure the LabX Agent Task Service

Use this section to configure and integrate the Tetra LabX Agent Integration Services for LabX tasks.

To configure the Tetra LabX Agent Task Service:

1. (Required) Enter the LabX host server name or IP address in the Server Name or IP field.
2. (Required) Enter the port number in the Port Number field. 51155 is the default HTTP port number set from the LabX Agent installation process. (51157 for HTTPS)
3. (Required) Enter a valid LabX user account in the LabX User Account Name field. The Tetra LabX Agent uses this account to log in to LabX Integration Services.
4. Enter the password for the LabX user in the LabX User Account Password field.
5. Enter the LabX Name in the LabX Name field. It is used as part of the file path in TetraScience. If it is empty, the upload process uses Server Name/IP
6. (Required) Specify a Upload Tasks Created After for when the Tetra LabX Agent selects those tasks whose creation date is later than the specified in this field.
7. (Required) Specify an Output Folder for the Tetra LabX Agent to store the generated files. After the generated files have been successfully uploaded to the TetraScience Data Platform, they are deleted.
8. (Required) Enter an integer in the Detect changes for tasks created in the last N days. After initial load from the "Upload Tasks Created After" date, agent will only detect changes in last N days repeatedly.
9. Click Save to save the configuration and start the Agent.

📘

LabX Name

Please be careful when using this configuration, since the LabX Name will be used in the Task RAW JSON's filePath in the TDP.

Section 5: Configure the LabX Agent Audit Trail Service

Use this section to configure and integrate the Tetra LabX SQL Server and load the audit trail data.

To configure the Tetra LabX Agent Audit Trail Service:
１. Check the Collect LabX audit trail checkbox to enable the audit trail service when needed.
２. (Required) Enter an integer in the Number of hours per audit trail output file field. LabX agent can generate one audit trail file per given hours
３. (Required) Enter the LabX SQL Server information in the LabX SQL Server Name or IP field. It can be an server name/IP, or an instance or port number, such as "localhost", "127.0.0.1", "localhost/instanceName" or "localhost, 1234"
４. (Required) Enter the LabX database in the LabX Database Name field, the default database name for LabX V9, V10, and V11 is LabX2010.
５. (Required) Enter the SQL server login user name in the SQL Server Username field. This is the user name for SQL Server authentication. Windows authentication is not supported.
６. (Required) Enter the SQL server login password in the SQL Server Password field.
７. Click Save to save the configuration and start the Agent.

Start and Stop the Tetra LabX Agent

This section indicates the current state of the Agent's processing status:

• Agent Service Not Installed
• Running
• Stopped

• To save the LabX Agent configuration, click Save.
• To start the LabX Agent with the new configuration settings, click Start. When the LabX Agent starts, the status indicator shows Running for an Agent that is successfully up and running.
• When the LabX Agent starts, the Stop button is enabled. To stop the LabX Agent, click Stop.

🚧

Daily Agent Run Schedule

After you complete the initial installation and configuration, you can use a Windows Task script to re-start the Tetra LabX Agent (for example, you can set it to run at 1:00 AM) and ensure that it runs constantly. For details, see [link] (https://developers.tetrascience.com/docs/using-windows-schedule-task-to-schedule-agent-services).