Tetra LabX Agent Installation Guide (v1.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 1.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.v1.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
  2. To communicate with the LabX Integration Service on the Agent server, you must add at least one outbound firewall exception. The default 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 four sections:

• Windows Scheduled Task
• LabX Group User
• Agent Configuration
• LabX Integration Services 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 GDC or CDC, 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 CDC, 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 from GDC or CDC, 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 GDC or CDC.
• A full connection URL from GDC or CDC (as shown in these URL examples):
  • GDC URL is http://10.100.1.1:8888/generic-connector/v1/agent
  • CDC URL is https://api.tetrascience-dev.com/v1/uda/

📘

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 CDC Connector, 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 CDC.
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 Tetra LabX Agent Service

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

To configure the Tetra LabX Agent 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 port number set from the LabX Agent installation process.
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. Specify a Task Creation Date for when the Tetra LabX Agent selects those tasks whose creation date is later than the you specified in this field.
6. 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.
7. Enter or edit a key/value pair in the Metadata field that specifies the metadata associated with the files uploaded to the Tetra Data Platform. You can add or edit metadata as needed.
8. Enter or edit tags in the Tag field that are associated with the output files uploaded to the Tetra Data Platform.
9. 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).