Release date: 17 November 2023

🚧

IMPORTANT

For the Tetra Empower Agent v5.2.0 and Tetra Data Schema v15 release, all of the associated Tetra Data components must be updated together. These components include the intermediate data schema (IDS), protocol, task script, and agent. Any prior versions of the IDS (v13 and earlier) will be incompatible with Tetra Empower Agent v5.1.0 and higher.

TetraScience has released its next version of the Tetra Empower Agent, version 5.2.0. This release focuses on reducing data latency and improving the Agent’s performance and usability by introducing new functionalities and enhancements, such as the following:

• Multiple Agents can now connect to the same Empower Server, which allows the system to scale horizontally
• Ability to set Scanning Priority for projects
• Shorter delays when the Agent loses connectivity
• Ability to configure the maximum number of projects included during the scan process (set with a default value of 20 that helps optimize performance and reliability)

This release also includes several bug fixes for scanning, injection generation, and project-user access permissions.

Here are the details for what’s new in Tetra Empower Agent v5.2.0.

Prerequisites

📘

NOTE

Tetra Empower Agent release notes will now include the recommended protocol version (task script and IDS) that is compatible with each version of the Empower Agent.

The following Tetra Data components are required for the Tetra Empower Agent v5.2.0:

• Tetra Data
  • lcuv-empower IDS v15.0.0
    • empower-raw-to-ids Protocol v8.1.0
    • Task Script v14.1.0

New Functionality

New Functionality includes features not previously available in the TDP or Tetra Empower Agent. These features may or may not affect "intended use" for GxP validation purposes.

Multiple Agents Can Now Upload Data to the Same Location

Customers can now configure multiple Agents to upload data to the same Amazon Simple Storage Service (Amazon S3) bucket within the TDP by specifying a Destination Id on the Connection Configuration page of the Agent Management Console.

New Scanning Priority Settings for Projects

Empower projects can now be assigned a Scanning Priority in the Agent Management Console: High or Normal. A separate process runs the High priority scans and there are fewer High priority projects thus reducing scan latency.

📘

NOTE

Setting Scanning Priority at the project level overrides the Agent's time-based, automatic prioritization settings.

Empower Server Connectivity Is Now Monitored

The Agent’s connectivity to the Empower server is now monitored. If connectivity is lost, the Agent also now automatically terminates any scan and generation processes that are running, so they no longer need to wait for a timeout to occur first.

To deactivate this functionality, customers can turn off the Enable Empower Connection Status Check toggle in the Advanced Settings dialog in the Agent Management Console.

Enhancements

Enhancements are modifications to existing functionality that improve performance or usability, but don't alter the function or intended use of the system.

New Max Number of Projects per Scan Process Setting

A new Max Number of Projects per Scan Process field in the Advanced Settings dialog in the Agent Management Console gives customers the ability to configure the maximum number of projects that are scanned by a single scan process. The default value is set to 20 to help optimize both performance and reliability.

📘

NOTE

Decreasing the default Max Number of Projects per Scan Process value can help maintain a more strict priority ordering, if desired. Including a smaller number of projects in each scan can help reduce the risk of delaying the scan of later projects within the batch when the scan encounters an error.

Local States for the Project/User Access Permission Non-Experiment Service Can Now Be Cleared

Customers can now clear the local state for the Agent’s Project/User Access Permission Non-Experiment service. Clearing this local state causes a complete scan and generation of Project / User access permissions, rather than an incremental generation, and can be helpful when the service’s local state is no longer valid. (Issue #2854)

To clear the local state, customers can now select the Clear Cache button on the Injection Service - Non-Experiment Summary - Project/User Access Permission tab in the Agent Management Console.

Additional Enhancements

Logging improvements for errors that occur when fetching projects from Empower during generation.

Bug Fixes

The following bugs are now fixed:

Scanning Process Bug Fixes

• Out of memory (OOM) exceptions are now handled during scanning, and the Agent terminates the scan process, rather than trying to scan the remaining projects in each batch. The remaining projects in the batch are now added as a separate batch for later scanning.
• Unrecoverable errors are now handled during priority scanning. The Agent then terminates the scan process immediately.
• Empower Software Development Kit (SDK) errors that are unrecoverable (those error codes ending in 105) are now handled. The Agent now fetches result objects and immediately terminates the scan process. During testing, these errors have proven to persist until the process ends and a new process is launched.
• A separate, configurable timeout and batch size for project priority scanning is now available in the Advanced Settings dialog of the Agent Management Console.

Generation Process Bug Fixes

• Access to the channel data files when retrieving raw data is now validated by the Agent. Generation now fails if the data file isn't accessible, because the SDK returns without error when fetching 2D channel data and returns an empty data cube.
• Corrupted state (error code 0xc0000005) and OOM exceptions that were previously unhandled during scanning and generation are now handled and have improved logging. (Issue #2649)
• Injection results are now fetched by using paging to avoid issues when a single injection has a large number of results.
• Injections that fail generation because they exceed the generation timeout are now retried with a longer timeout.
• For Empower 3 pre SR3, the Agent now ingests the injections immediately if injection data acquisition is complete. If the data acquisition isn't complete, the Agent will ingest the injection after the maximum number of acquisition hours that are configured. Previously, the Agent always waited for the maximum number of acquisition hours before ingestion.

Project / User Access Permission Process Bug Fixes

• The Agent can now handle and recover from being in an Invalid state in the local store when the state was caused by errors generated when retrieving Project/User Access Permission non-experiment data.

📘

NOTE

After upgrading to Tetra Empower Agent v5.2.0, any local state stored for the Project/User Access Permission non-experiment data that’s not valid will be removed so that it can be regenerated.

• Optimized Agent processing of Project / User Access Permissions to avoid unnecessary processing. The output remains unchanged.
• The non-experiment generation process timeout is now separately configurable in the Advanced Settings dialog of the Agent Management Console by using the NonExperiment console Timeout (minutes) field.
• Projects that aren't accessible by the Empower user account that the Agent is using are no longer scanned by the Project / User Access Permission scanning process. Because of this update, inaccessible projects will no longer cause error logs during scans.

User Interface Bug Fixes

The number of pending uploads reported in the Agent Management Console now displays accurately.

Deprecated Features

There are no new deprecated features in this release. For more information about TDP deprecations, see Tetra Product Deprecation Notices.

Known and Possible Issues

The following are known and possible issues that were previously identified:

Tetra Empower Agent

• When the agent generates RAW JSONs, the agent uses the Sample Set Method name to include the sample set method information in the RAW JSON. This is the only toolkit method available. Customers might have changed the Sample Set Method. If you're using the Sample Set Method in the RAW JSON or IDS JSON, it's recommended that customers compare the SampleSet.SampleSetMethodDate in the RAW JSON and the sample.set.method.created_at in the IDS JSON with the time of the injection to confirm which Sample Set Method is referred to.
• If the Empower project name has non-ASCII characters (for example, accents or dieresis), the order of projects displayed in the Empower project browser and agent management console may not be the same.
• Sample Set Method information for an Injection through the toolkit provides the Sample Set Method name of the approved Sample Set Method version instead of the Sample Set Method ID of the version used to set up the sample set. This may or may not be the Sample Set Method version that was actually used for the sample set in the Injection.

Operating Suggestions

• If you're not interacting with the agent management console frequently, it's recommended to start the agent, close the management console, and then let the agent run in the background.
• If the Empower server or client is under maintenance, it's recommended to stop the Tetra Empower Agent. Remember to restart the agent when Empower is back online. The unfinished tasks will be resumed by the agent once it is started again.
• If the Empower Oracle service is stopped, then stop the agent and restart the agent after the Oracle service is back online.

Upgrade Considerations

To upgrade the agent, see Common Tetra Agent Upgrade and Installation Information. To update the protocol, see Edit a Pipeline.

This version is compatible as a direct upgrade from Tetra Empower Agent v5.1.0. During the upgrade, keep in mind the following:

• The upgrade for the Tetra Empower Agent v5.1.0 and Tetra Data Schema v15.0.0 release is NOT backward-compatible. This means the RAW files generated by this agent cannot be processed by previous protocol versions. The agent is now also able to generate 3D MS data cubes with correct data precision.
• Performance-wise, the new protocol’s runtime will be longer when compared to the previous protocol versions because of the IDS structure change and the newly added fields. From our internal testing, customers can expect an increase in runtime (tens of seconds) for Empower data without 3D Mass Spec data. For Empower data with 3D Mass Spec data, customers can expect a longer runtime because of the newly added Parquet file creation for 3D MS data. The time increase will be dependent on the size of the 3D MS data. The larger the data, the more time it will take to generate the Parquet file.
• If data generated by previous agent versions needs to be available with the latest IDS version released with this release, customers will need to configure the protocols with empower-raw-to-ids protocol v8.1.0 and re-upload all of the previously generated injections by using Rerun Project(s) in the management console and by selecting all of the projects in the list. Keep in mind that re-uploading all of the projects may take considerable time.
• If 3D MS data precision is required, configure the 3D MS Method as GetSpectra for the specific projects in the Project grid, save the changes, and start the agent. Keep in mind that 3D MS data cubes generation using GetSpectra Toolkit method is significantly slower than generating 3D MS data cubes with the Get3D Toolkit method and will increase the generation time for each injection.
• Support for Empower-Audit-Trail, Empower-Project-User, and Empower-message-center Tetra Data is currently in development and testing, and will be available in a future release (targeting Q4 2023).

Other Release Notes

To view other Tetra Agent and Tetra Data release notes, see Tetra Agent and Tetra Data Release Notes.

To view other TDP release notes, see Tetra Data Platform (TDP) Release Notes.