Tetra Empower Agent User Manual (Version 3.3.0)

This guide explains how to use the Tetra Empower Agent, including connection details. This manual describes how to configure the agent, use the project panel, monitor processing, and troubleshoot issues.

Version

This guide is for version 3.3.0 of the software.

Configuration

Empower Agent Management Console

Agent Management Console is divided into eight sections as shown in the screenshot below.

1. Agent Status
   It indicates the Agent's running status. There has a couple of status as below:

   • Agent Not Installed
   • Running
   • Stopped

When the System Administrator sets up all of the required parameters completely, she can click the Start button to start the Agent or click the Stop button when the Agent is running.

2. Empower Database
   Empower Database Name, DB User Name, and Password are required to access Empower. Please make sure this account has the right privilege for the projects to be extracted.

3. Empower Group User Account.
   This is the account running TetraScience Empower Agent, this user account is suggested to be in the same Organization Unit as Empower so that it has the privilege to access Empower File Server to fetch raw data.

4. Connector

   S3 Direct Upload

   When turning on this option, the Agent is going to upload the files directly to the AWS S3 bucket bypassing GDC or UDI.

   Please check the links if you like to learn more about GDC or UDI.

   When using the S3 Direct Upload option with GDC, an L7 Proxy Data Connector should be added in the same Data Hub where the GDC is set up. Also, the port of the L7 Proxy Data Connector is open.

📘

NOTE:

To allow the agent to automatically perform regular backups of the SQLite database file, ensure that the S3 Direct Upload option is enabled. When this option is enabled, the SQLite database file, which stores agent configuration data, is uploaded to the backup bucket in the data lake. Should an agent failure occur, you can restore the database file from the backup bucket so that processing can continue.

Connection Url

The prerequisite is to set up an Agent from GDC or UDI.

• Agent ID is a UUID (Enter in section 4)
• Examples of the URL from GDC or UDI as below
  • GDC URL is http://10.100.1.1:8888/generic-connector/v1/agent
  • UDI URL is https://api.tetrascience-dev.com/v1/uda/

It is strongly suggested to verify the Agent ID and URL with TetraScience Delivery Engineer before using it.

Please make sure to enter the full URL to Connection Url

Additional note when using UDI:

If the user uses the UDI, it is required to attach Org Slug and JWT token to the header.
Please reference the doc regarding UDI to learn how to get JWT Token.

The user clicks Add/Edit button of Authorization, a model window pops up to enter the JWT Token

When the header values are saved, the model window closes. The Agent validates the connection immediately. The connection status is shown in front.

Currently, TetraScience Empower Agent contains two Services, Injection Service and Archive Service. The user can enable either of them or both. Just a friendly reminder that this User Manual focuses on Injection Service only.

Agent ID is part of the information used for connecting the TetraScience Data Platform. It can be retrieved from the TetraScience Data Platform when setting up GDC or UDI.

5. Batch Size
   The number of Injections being processed simultaneously. 8 is the default size. The System Administrator can adjust it based on the "hours" of the day. The number can be set up to 10 or 12 if the host server has better hardware specifications. The number also can be adjusted lower, if, the Agent consumes more CPU and Memory than is allowed in the host server.

6. Error Retry (Times)
   Retry policies for Injection RAW file generation and upload if any unhandled error occurs in either of the cases.

7. Agent Run Time
   The System Administrator can define the Agent runtime configuration. She can decide whether it is needed to send Heart Beat to the Data Platform, whether the Agent needs to upload the RAW file to the Data Platform and whether the RAW files should be kept in the local drive after the files are uploaded successfully.

Empower Injection RAW file output folder. This folder path should be valid.

TetraScience Empower Agent periodically scans Empower projects to detect if there has any new injection or reprocessed injection. Interval of Scan indicates the time period for this scan.

When the required parameters are set up, System Administrator clicks Start to run Agent. The screenshot below shows the Agent is successfully running.

When the Agent is running, all of the parameters are disabled.

In case, System Administrator likes to modify the parameters, she needs to Stop the Agent first.

Project Panel

Project Selection

Usually, one Empower Database can contain hundreds or even thousands of Projects. It is flexible for System Administrator to select the Projects she wants to process. Initially, the Project list contains all of the Projects with which the Empower DB User can access. The System Administrator can select the Projects to enable the Agen to generate the RAW files. Also, the Agent is keeping monitoring the Project change to detect new and updated Injections. The System Administrator needs to click Save button to make the changes persisted.

In case, new Empower projects are added to Empower System, the Agent can detect them from its periodical Scan job. The new Projects are included in the Project list, the System Administrator can apply the same way by manually selecting the projects for processing if the option, Auto enable new projects, doesn't turn on.

If the user unselects the check box when the Agent is in the middle of generating the Injection Raw files from that particular Project, The generation process will continue till the Agent extracts all of the Injections from that Project, Then the Agent will stop monitoring the project for future changes.

Enabled, a toggle, allows the users to select or unselect all of the projects in the Project list in a convenient way.

When the TetraScience Empower Agent is running, the System Administrator can monitor the progress by checking the status from the Processing Status.

During the processing, the Conversion Status indicates the overall status. Status has three options.

• No Injection: The Project is not selected
• Pending: The Project is selected but has not been processed yet.
• Generated: The Injection in the Project has been processed completely. In case, it is in the middle of the processing, it will show how many percentages of total injections have been processed.

Result Sign Off Option

The System Administrator can choose one of the following Result Sign Off options for a Project.

• Not Required
• Level 1 Required
• Level 2 Required

Auto enable new projects

This feature was introduced in version 3.3.0 of the software.

This option determines if the Agent is going to extract the injections automatically from the projects being added to Empower.

Please note this option only applies to the projects that are added or imported to the Empower after that option is saved.

Processing Summary

The TetraScience Empower Agent detects and generates the injections from the enabled Projects. This section provides clarity on agent scanning, generation, and upload activities. All date/time displayed are local time.

Processing Summary contains a dashboard including the following information:

• Number of injections scanned by the agent
• Number of Injections that raw files generated
• Number of Injections that are failed to generate
• Number of the Injections have been uploaded
• Number of injections pending for upload
• Number of Injections failed to upload
• Exception messages

System Administrators can select an individual project from the drop-down list. The data in the dashboard will change according to the selection. The dropdown list can be cleared to go back to All Projects. Note that only enabled projects will be included.

In case, the System Administrator like to re-generate Injection RAW files from any of the projects, she can select the Project(s) and click Rerun Project(s) button.

System Administrator can choose Re-upload Injections for the Project(s). The Agent will reupload the generated RAW files to the Data Platform. Please be aware, if System Administrator has turned off the option, Keep Local RAW File After Upload, the Agent will regenerate the Injections.

There have two possible types of errors that occur during processing.

• Injection Generation Error
• Injection Upload Error

When an error occurs, the Injection information is captured and shown in the data grid with a detailed error message. The Agent will retry the failed ones multiple times based on the setting specified in Management Console. System Administrators can regenerate and re-upload the failed injections manually by clicking the buttons above the data grid.

Troubleshooting

Missing Result and Chromatogram Data

It is due to the Group User Account running the Tetrascience Empower Agent is not part of the Empower User Group.

Injection JSON is not generated

Check if the Agent is up running from Management Console. If it stops unexpectedly, restarts the Agent from Management Console.

Previous Version Empower Project is not generated

Empower V3 can automatically upgrade Project with the Previous version. System Admin still needs to double-check it by opening the Project from Empower Client application to make sure it can be accessed by Empower. A manual conversion might be required.

Channel Data missing from the output

That is because the accounting running Empower Agent is not part of Empower User Group in Active Directory when Empower Software was installed initially.

Need Additional Information regarding TetraScience Empower Agent

Please check FAQ section to learn more about TetraScience Empower Agent or connect a TetraScience Delivery Engineer directly.