Tetra Empower Agent User Manual (Version 4.1.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 4.1.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
   This indicates the Agent's running status. Statuses are listed below:

   • Agent Not Installed
   • Running
   • Stopped

When you finish configuring the required parameters, click the Start button to start the Agent.
If needed, click the Stop button to stop the Agent from running.

2. Scheduled Windows Task

If this option is enabled, the Empower Agent creates a Windows Task that checks the status of Agent service daily, at a time you specify.

• If the Agent is stopped, the scheduled Windows Task will automatically restart the Agent service.
• If the Agent is running, nothing further happens.

If you manually stop the Empower Agent, the Windows Task is removed. The Windows Task that is created runs under the LocalSystem account.

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

4. Empower Group User Account.
   This is the account running Tetra Empower Agent. This user account could be in the same Organization Unit as Empower so that it has the privileges needed to access Empower File Server to fetch raw data.

5. Connector

   S3 Direct Upload

If you turn on this option, the Agent uploads the files directly to the AWS S3 bucket bypassing GDC or UDI.

For more information about GDC, see this link.
To learn more about UDI, see this link.

If you use 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 5)
• 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/

We strongly suggest that you verify the Agent ID and URL with TetraScience before you use it.

Enter the full URL to Connection Url

Additional note when using UDI:

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

When you click the Add/Edit button of Authorization, a model window pops up so that you can 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, the Tetra Empower Agent contains two services: Injection Service and Archive Service. You can enable either of them or both. This User Manual focuses on Injection Service only.

The Agent ID is part of the information used to connect the Tetra Data Platform. It can be retrieved from the Tetra Data Platform when setting up GDC or UDI.

📘

NOTE:

Agent ID is a mandatory field. The Connection Url is optional when not uploading the Raw files to TDP.

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

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

8. Agent Run Time
   You can define the Agent runtime configuration. You can decide whether the Agent needs to upload the RAW file to the Tetra Data Platform (TDP) and whether the RAW files should be kept in the local drive after the files are uploaded successfully.

   • If you select No for Upload The Raw File to TDP, the Keep Local RAW File After Upload is automatically set to Yes.

🚧

NOTE:

If you choose to keep the Raw file, please beware of the potential issue that the Raw files can take most of the disk space. The minimum available disk space required for the Tetra Empower Agent to process an injection is 1 GB (1 GB is the default setting). The Agent will pause the Injection generation if the available disk space is less than 1 GB.

You can check the available disk space on the Injection Summary page

Empower Injection RAW file output folder. This folder path should be valid. If you select No to Keep Local Raw File After Upload, the Raw files will be deleted from the output folder after the Raw files are successfully uploaded to TDP.

The Tetra Empower Agent periodically scans Empower projects to detect if there are new or reprocessed injections. The Interval of Scan indicates the time period for this scan.

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

9. Non-Experiment
   Starting from Tetra Empower Agent v4.0.0, the Empower Agent is able to generate Raw files from Empower Audit Trails (System Audit Trails, Project Audit Trails, the logs from Message Center, and Empower Project/User Access permission).

Non-Experiment data shares the same configuration settings as Injection data, in terms of whether uploading to TDP or retaining generated data locally.

📘

NOTE:

If the Non-Experiment data is retained in the local drive, they will be moved to an Archive folder under <Output_Folder><Stream><Archive>\

After you finish the configuration, save the changes and start the Agent. When the Agent is running, all of the parameters are disabled.

📘

NOTE:

In case, you like to modify the parameters, you need to Stop the Agent first.

Project Panel

Project Selection

One Empower Database can contain hundreds or even thousands of Projects. You can select the Projects you want to process. Initially, the Project list contains all of the Projects the Empower DB User can access. The System Administrator can select the Projects to enable the Agent to generate the RAW files. Also, the Agent is keeping monitoring the Project change to detect new and updated Injections. You must click Save button to save the changes.

If 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 you unselect 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 until 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 you to select or unselect all of the projects in the Project list.

When the Tetra 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

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

Injection Summary

Processing Summary

The Tetra 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

You 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, you like to re-generate Injection RAW files from any of the projects, you can select the Project(s) and click Rerun Project(s) button.

📘

NOTE:

Starting v4.0.0, the Re-upload feature is deprecated.

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. You can regenerate and re-upload the failed injections manually by clicking the buttons above the data grid.

System Message

The Empower Agent generates host server system metrics every minute. It gathers the following metrics:

• Data Connection. The connection status between the Agent and Tetra Data Platform
• Availability Disk Space
• Disk Usage
• CPU Usage
• Memory Usage

🚧

NOTE:

If the CPU Usage Percent shows as 0%, that is because the user account defined in section 4 isn't in either Administrator Group or Performance Monitor User Group

Non-Experiment Summary

You can check the processing summary for Non-Experiment data. All four types of data streams are included:

• ProjectAuditTrail
• SystemAuditTrail
• MessageCenter
• Project/User Access Permission

On the Audit Trail page, the project name is applied to ProjectAuditTrail. For SystemAuditTrail and MessageCenter, the Agent uses the Empower Database Name.

Additional data fields include:

• Message
• Total Generated Records
• Last Processing Time
• Latest log (in JSON format)

Project/User Access Permission has its own summary page where you can check the Project status and Last Process Time.

Empower Agent scans Projects periodically. When the Agent detects the changes from Project, User, User Group, or User Type, the Agent generates a JSON file containing all of the Empower Users, User Types, and Projects with their associated User Groups.

You can find the events which trigger file regeneration/reupload in the section of the FAQ.

Troubleshooting

Missing Result and Chromatogram Data

This can occur if the Group User Account running the Tetra Empower Agent is not part of the Empower User Group.

Injection JSON is not generated

Check whether the Agent is up running from Management Console. If it stops unexpectedly, restart the Agent from Management Console.

Previous Version Empower Project is not generated

Empower V3 can automatically upgrade Project with the Previous version. You still need 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

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

Error Code 105 in Project page

The Agent is running. But there is no injection generated. Also, the status shows 105 in the Conversion Status

This happens if there is an exception raised when Empower Toolkit connects to Empower Client.

Error 105 - The server threw an exception. (Exception from HRESULT: 0x80010105 (RPC_E_SERVERFAULT)

This is an undocumented error. The root cause is unknown. To fix this, restart the Agent.

Additional Information

If you need more information about the Tetra Empower Agent, check the FAQ section to learn more or contact your CSM.