This guide shows how to configure and use Tetra Empower Agent versions 5.3.x after an Agent is installed by using the local Agent Management Console. It also describes how you can configure Empower project settings and initiate scan requests for Empower projects remotely from the Tetra Data Platform (TDP) user interface.

To install the Agent, see the Tetra Empower Agent Installation Guide (v5.3.x).

Agent Management Console Configuration

You can use the Agent Management Console to do the following:

• Configure Tetra Empower Agent settings
• Select which Empower Projects will be extracted
• Activate the Injection Service to monitor injections as well as non-experiment summary and processing
• Activate the Archive Service to archive Empower projects to the TDP
• Review injection summaries to troubleshoot issues

To get started, do the following.

Open the Agent Management Console

To open the Agent Management Console on the host server, do the following:

1. On the Agent's host server, open Windows Programs.
2. In the Windows Programs menu, choose TetraScience Agent Empower. The Agent Management Console appears.

Configure the Agent

To configure the Tetra Empower Agent after it's installed, do the following:

1. In the Agent Management Console, select the hamburger menu icon in the left navigation menu. Then, choose Configuration. The Agent Configuration page appears.

📘

NOTE

The Configuration page provides settings to save, start, and stop the agent along with its connectivity settings to Waters Empower software and the Tetra Data Platform (TDP). This tab also provides settings to manage the Injection and Archive services as well as non-experiment data ingestion.

2. Configure the Agent by filling out the fields in the following sections on the Configuration page:

• Agent Status
• Empower Database
• Empower Group User
• Connector
• Empower Agent Output Settings

Change the Agent's Status

The Agent Status section indicates the current state of the Agent's processing status, which can be any of the following:

• Agent Not Started
• Running

To save, start, or stop the Agent, do the following:

• To save the Agent configuration, choose Save.
• To start the Agent after configuring new settings, choose Start. When the Agent starts, the status indicator shows Running.
• To stop a running Agent, choose Stop. When the Agent stops, the status indicator shows Agent Not Started. (The Stop button can be selected only if the Agent is running.)

Automate Status Checks by Using Windows Task Scheduler

To avoid needing to check the Agent’s service status manually, it’s recommended that you create a Windows task to perform daily status checks.

To create a Windows task, do the following:

1. Under Windows Scheduled Task to check Agent Service Status, choose Yes.
2. For Run Time, enter the time that you want the status check to run each day. If the Agent is stopped, then the scheduled Windows task restarts the Agent service automatically. If the Agent is running, it continues to run, and the Windows task will run at the time you selected.

📘

NOTE

If you manually stop the Agent, the task is removed from Windows Task Scheduler. When you run the Agent without specifying an Agent Group User account, the task runs under the LocalSystem account.

Configure Empower Database Settings

The Agent must be able to access your Empower Oracle Database to fetch date and time values for the files it uploads to the TDP.

To provide the Agent access to your Empower Oracle Database, you must provide the following information in the Empower Database section of the Configuration page:

📘

NOTE

You can find the Oracle Host Name, Service Name, and Port information in the tnsnames.ora file on the Empower client machine. The file is typically in the following folder: <Oracle Client Install folder>\\network\\admin\\

• For Database Name, enter the Empower database name used to log in to Empower.
• For User Name, enter the Empower user name.
• For Password, enter the Empower user’s password.
• For Oracle Host Name, enter the Oracle Host name. Make sure you enter the host name as it appears in the tnsnames.ora file on the Empower client machine where the Agent is running.
• For Service Name, enter the Oracle Service name. Make sure that you enter the service name as it appears in the tnsnames.ora file on the Empower client machine where the Agent is running.
• For Port, enter the Oracle Port. Make sure that you enter the port as it appears in the tnsnames.ora file on the Empower client machine where the Agent is running.
• Then, choose Test Connection to test the connection to the Empower Database.

🚧

IMPORTANT

Make sure that the Empower account used in User Name has the correct privileges to extract the projects. If the Agent will be used to create a Sample Set Method in Empower, more privileges may be required. Refer to the FAQ section for details on what privileges the Empower user needs for various data ingestion and sample set method creation functions.

Configure the Empower Group User

The Empower Group User is the user account (typically a Windows service account) that runs the Tetra Empower Agent.

To configure the Empower Group User, do the following:

1. In the Empower Group User section, for User Name, enter the user account's user name.
2. For Password, enter the user account's password.

📘

NOTE

This user accesses the Empower File Server to fetch raw data. It's recommended that you create the user account in the same Organization Unit as Empower, so that it has the privileges required to access the Empower File Server. If the Empower Group User section is left blank, then the Agent assumes the Local System user.

Configure Connector Settings

The Connector section on the Configuration tab provides settings to do any of the following:

• Set the S3 Direct Upload option.
• Allow the Agent to receive commands from the TDP.
• Establish a data connection between the Agent and the TDP.
• Specify the Destination Id so that files from multiple Agents can be uploaded to the same Amazon S3 bucket. (Usually, it helps to split the load into multiple agents for scaling horizontally.)
• Enable or disable Injection and Archival services.

Set the S3 Direct Upload Option

To have the Agent upload files directly to your Amazon Simple Storage Service (Amazon S3) bucket, set the S3 Direct Upload option to Yes. Yes is the default setting for new installs. When upgrading the Agent, the setting from the previous version of the agent is retained.

If you choose this option, keep in mind the following:

• If you use the S3 Direct Upload option with a Tetra Data Hub that uses a Generic Data Connector (GDC), you must add an L7 Proxy Connector in the same Hub where you set up the GDC. The port of the L7 Proxy Connector must also be open. For more information, see GDC Connections.

📘

SQLite Database File Backups

To have the Agent 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 Tetra Data Lake. If an Agent failure occurs, you can restore the database file from the backup bucket and continue processing.

If you don't use the S3 Direct Upload option, it's recommended that you create periodic backups of the Agent database, which is typically stored in the installation folder under C:\\TetraScience\<agent>\\db. 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.

Allow the Agent to Receive Commands from the TDP

To allow the Agent to securely receive and run commands from the TDP, set the Receive Commands option to Yes. The default setting is No.

In Tetra Empower Agent v5.1.x and higher, there are TetraScience APIs available that allow you to do the following:

• Fetch a Sample Set Method from Empower into TDP
• Create a Sample Set Method in Empower from TDP

To be able to use these APIs, the Receive Commands setting must be set to Yes.

Establish a Data Connection Between the Agent and the TDP

To set up a data connection between the Agent and the TDP, enter the following information in the Connector section on the Configuration tab:

🚧

IMPORTANT

When establishing a connection between the Agent and the TDP, keep in mind the following:

• Agent ID is required.
• The connection URL is required only if you're uploading RAW files to the TDP.
• Before you use your Agent ID and connection URL, it’s strongly recommended that you verify both with your TetraScience Customer Success Team.

1. For Agent Id, enter the Agent’s ID. The Agent ID is a Universal Unique Identifier (UUID) value that’s used to connect the Agent to the TDP. To find your Agent ID, do the following:

• Sign in to the TDP.
• In the left navigation menu, choose Data Sources. Then, choose Agents. The Agents page appears.
• In the AGENT column, find the name of the Agent that you’re configuring. The Agent ID is listed below the Agent name.

2. For Connection Url, enter the complete connection URL of the Connector or integration type that you’re using:

• TDP (No Connector) URL: <https://api.tetrascience-dev.com/v1/data-acquisition/agent/>
• Hub: http://10.100.1.2:8443/generic-connector/v1/agent
• Generic Data Connector (GDC) URL: <http://10.100.1.1:8888/generic-connector/v1/agent>

3. (For “TDP (No Connector)” setups only) If you’re using an Agent without a Connector, make sure that you do the following:

• For Org Slug, enter your organizational slug. To get your organizational slug, see Viewing Organization Details. The organizational slug is required when using a JSON Web Token (JWT). Adding the slug to this field attaches it to the Agent’s API request headers.
• For Authorization, select Add/Edit. Then, enter your JWT in the dialog that appears. To get a JWT, see Generate a JSON Web Token for an Existing Service User. Then, choose Save to encrypt and save the JWT. The Agent validates the connection immediately and displays the updated connection status next to the Connection Url field.

🚧

IMPORTANT

If the Upload Raw Files to TDP setting in the Agent Run Time section (this is described later in this page) is set to No, the Agent will not connect to the TDP to upload files. The status here will still show Connected.

Configure Advanced Settings

You can configure the following options by selecting Advanced Settings on the Configuration page:

• Data Connection status check every: Indicates how often the software checks the status of the connection (heartbeat) between the TDP and the Agent. If the TDP doesn't receive a heartbeat message for more than five minutes, the platform assumes that the Agent is offline. The default value is 30 seconds.
• Agent log files upload every: Indicates how often the Agent uploads log files to the Data Lake. The default value is 300 seconds.

To keep the recommended settings, or to save the new values you entered, choose OK. Only consider changing these values if connection checks (heartbeat) frequency needs to be changed, or if logs files are needed to be uploaded to the TDP at a different frequency.

Enable or Disable the Injection and Archive Services

You can enable two services within the Tetra Empower Agent:

• Injection Service: Monitors Empower injections and non-experiment data and processing
• Archive Service: Archives Empower projects to the TDP and provides the ability to restore Project Archives back to Empower from the TDP

To activate the Injection Service, choose Yes under Enable Injection Service. To configure the Injection Service, see Configure Injection Service Settings.

To activate the Archive Service, choose Yes under Enable Archive Service. To configure the Archive Service, see Configure Archive Service Settings.

Configure Injection Service Settings

The Injection Service monitors Empower injections and non-experiment data and processing, converts it to JSON format and uploads it to the TDP.

To configure the Injection Service, first enable the Injection Service on the Configuration page in the Connector section. Then, enter the following information in the Agent Management Console to configure the service.

Configure Batch Size Settings

Use the Batch Size section to set the number of Injections being processed simultaneously. The default size is 8. As a System Administrator, you can adjust it based on the hours of the day. You can set the number up to 10 or 12, if the host server has robust hardware specifications. You can also adjust the number lower, if the Agent consumes more CPU and memory than the host server allows.

Configure Error Handling Settings

To configure error handling settings for the Injection Service, enter the following in the Error Handling section:

• For Continue Scan on ToolKit 105 Error, choose Yes or No. 105 Error is the abbreviation of an unhandled ToolKit error, 0x80010105. This setting is to determine if the Agent should continue scanning when encountering this error. The default value is No.
• For Continue Generation on Toolkit Error, choose Yes or No. This option indicates if the Agent should continue to generate the RAW JSON for an Injection if certain Empower SDK Toolkit errors are encountered, or not.
  • Click Yes to allow the Tetra Empower Agent to continue with RAW JSON generation, even if the errors occur. Please note, that this may result in incomplete RAW JSON data. The following are some of the errors that may be encountered by the toolkit during Injection generation:
    • Error 105 - Error fetching Channel Chromatography data
    • Error 214 - Could not fetch requested method
    • Error 408 - Method could not be opened in the Project
    • Error 429 - LCCalibration: the requested calibration could not be fetched
    • Error 42F - An option is required in order to access this interface
    • Error 267 An option is required to open this method. Please make sure this option is enabled in the project
    • Error 40e Cannot open Method because it is being edited by another user
  • If the RAW JSON is generated, the Agent will add metadata indicating the encountered error codes to that RAW JSON.

🚧

IMPORTANT

If you choose Yes for Continue on Toolkit Error, it is possible that, even if the errors listed above (and there may be other toolkit errors) are present, incomplete data could be copied to the RAW JSON files.

If any unhandled errors occur, use this section to set the retry policies for both injection RAW file generation and injection upload.

• If errors occur during extracting the Injection data from Empower, the agent will retry to extract the injection for the number of times specified in the Injection Processing field (or fewer times, if successful). The default value is 3.
• If errors occur during upload of the Injection RAW JSON to the TDP, the agent will retry to upload the the file for the number of times specified in the Injection Upload field (or fewer times, if successful). The default value is 50.

Configure Empower Agent Output Settings

The Agent outputs RAW JSON files before uploading them to TDP. To configure the directory where the Agent outputs these files, enter the following information in the Empower Agent Output Settings section:

• For Output Folder, enter the directory where you want the Agent to output RAW JSON files.
• For Required Free Disk Space (GB), enter the minimum required free disk space required for the Agent to process an injection. The default setting is 10 GB.

📘

NOTE

The free disk space refers to the output disk. When the Agent processes an injection, it first checks if the machine meets or exceeds the minimum required free disk space value. If the machine meets the required free disk space, then it processes the injection. If it does not, then the machine writes a log message while the Agent pauses and waits for other injections in progress to finish processing. The Agent then waits for files to finish uploading to the TDP before it attempts to process the new injection again.

🚧

RAW Files May Use a Large Amount of Disk Space

If you decide to retain the RAW files, be aware that RAW files may use most of the disk space. If the available disk space is less than what you've indicated in the Required Free Disk Space setting, then the Agent will pause the Injection generation. Use the Injection Summary page to check the available disk space.

Configure Agent Run Time Settings

You can use the Agent Run Time section to configure the following:

• Set the Agent to upload the RAW files to the TDP.
• Set to keep RAW files in the local drive after the files are uploaded successfully.
• Set the Data Precision Specification option when ingesting the injection data from Empower.
• Set the scan interval in minutes for how often the Tetra Empower Agent periodically scans Empower projects to detect new or reprocessed injections.
• Set advanced properties, such as the number of processors you want to use to generate injections, scan time interval, and generation timeout.

To configure Agent Run Time settings, do the following:

• If you set the Upload Raw Files to TDP field to Yes, then the Keep Local RAW File After Upload field is automatically set to Yes. If you set the Upload Raw Files to TDP field to No, the Agent will not connect to the TDP and only generate files to store them locally.
• If you set the Keep Local RAW File After Upload field to No, then the RAW files are deleted from the output folder after the RAW files have been successfully uploaded to the TDP.
• If you set the Data Precision Specification to Empower, the data (Peak, Result, and Sign-Off data) extracted from Empower Software follows the precision set in the Empower Client. If Oracle is selected, data precision is maintained up to 17 decimal places.

Configure Agent Run Time Advanced Settings

The Advanced Settings option in the Agent Run Time section provides settings to manage scan, generation, and upload throughput. These are advanced options, and the recommended settings are included as default values.

• Normal Generation Processor #: The agent can prioritize injections based on when they have been created/modified (more details in the next section). This setting provides the number of processes the agent will allocate to injections that are assigned Normal priority. This setting leverages the hardware of machines that have multiple cores, which allows you to specify how many processes you want the Tetra Empower Agent to use to generate Empower injections. Each process handles one project at a time; specifying several processes allows the Tetra Empower Agent to process several projects in parallel and expedite processing time. The default value is 2.
• New Injection Generation Processor #: The agent can prioritize injections based on when they have been created/modified (more details in the next section). This setting provides the number of processes the agent will allocate to injections that are assigned High priority (these are recently created or modified injections that will be generated before historical/older injections). This setting leverages the hardware of machines that have multiple cores, which allows you to specify how many processes you want the Tetra Empower Agent to use to process Empower injections. Each process handles one project at a time; specifying several processes allows the Tetra Empower Agent to process several projects in parallel and expedite processing time. The default value is 1.
• 3D MS GetSpectra Generation Processor #: The agent provides an option to specify how 3D MS data cubes will be generated for every project (see Project tab settings later in this document for more details). If for a selected project, the 3D MS Method is specified as GetSpectra, then any injection in that project (irrespective of priority) will be processed by processes defined here. This setting leverages the hardware of machines that have multiple cores, which allows you to specify how many processes you want the Tetra Empower Agent to use to generate Empower injections. Each process handles one injection, which contains a 3D MS channel, at a time; specifying several processes allows the Tetra Empower Agent to process several 3D MS injections in parallel and expedite processing time. The default value is 1.

🚧

Optimize for Your Empower Infrastructure

The ability of the processes from these three generation processor settings, along with the injection scan, injection upload, and non-experimental generation processes (if configured), to perform optimally will depend on the virtual machine (VM) that is set up for the Agent. During testing, six or 10 processors were adequate when running Empower Services on a small instance, t2.large. However, that may depend on your Empower Services needs (for example, how many concurrent sessions it should support, the load of each session, and so on).

Make sure that the instance(s) running the EmpowerDB and Empower file server can sustain the load from the set Generation Processes. Using too many processes may increase the risk of overloading the instance(s) and reduce their service availability.

• Interval of Scan (minutes): Provides the frequency for the agent to scan Empower again after the time defined here. If the previous scan is still continuing, then the next scan cycle will wait for it to finish and then start the scan after the time defined here. The default value is 2 minutes.
• Upload Max Parallelism #: Provides the setting for maximum parallel processes for upload. The upload continuously processes generated RAW files and this instructs the agent how many processes to use. The default value is (total CPU cores available -1).
• Max Number of Projects Per Scan Process - Instead of scanning all of the projects in one process, the Agent separates the whole list into multiple batches with a default size of 20. This size may be set to 1 to improve reliability, but it will introduce some overhead.
• Scan process Timeout (minutes) -This setting is to prevent the scan process from hanging due to unhandled Empower ToolKit errors. The default is 600 minutes. If you change the setting of Max Number of Projects Per Scan Process, you might need to adjust this setting as well. Please consult your Tetra support engineer.
• Generation process Timeout (minutes) - This setting is to prevent the injection generation process from hanging due to unhandled Empower ToolKit errors. The default is 600 minutes.
• Non-experiment process Timeout (minutes) -This setting is to prevent the Non-experiment data extract process from hanging due to unhandled Empower ToolKit errors. This setting is applied for all four types of Non-Experiment data extraction, “Extract System Audit Trail“, “Extract Project Audit Trail“, “Extract Message Center“ and “Extract Project/User Access Permission“.
• Project prioritization process Timeout (minutes) - The Tetra Empower Agent has a dedicated process to determine the project priority. This setting specifies a timeout value to restart the process to reduce the impact of the unhandled Empower ToolKit errors.
• Batch size of the project priority scan - Similar to other scan processes, the Tetra Agent tries to process the project scan in batch to reduce the potential impact of ToolKit unhanded errors. The default size is 100.
• Injection Generation Max Timeout (minutes): This setting is used for injections where there are no 3D MS data cubes or has 3D MS data cubes but the 3D MS generation method is not GetSpectra at the project level. This is the maximum time the agent will use to generate an injection (once it has started the generation process for the injection). If the injection cannot be generated in the specified time, an error is logged (consider increasing the time if there are such errors). The default value is 60 minutes.
• Injection Generation Retry Timeout (minutes) - This setting is applied when injection generation fails and the Tetra Empower Agent needs to retry the generation. The default value is 180 minutes.
• Injection GetSpectra Generation Max Timeout (minutes): This setting is used for injections where there are 3D MS data cubes and the 3D MS generation method is GetSpectra at project level. This is the maximum time the agent will use to generate an injection (once it has started the generation process for the injection). If the injection cannot be generated in the specified time, an error is logged (consider increasing the time if there are such errors). The default value is 180 minutes.
• Enable Empower Connection Status Check - The default is Yes. The Agent checks the Empower connection periodically. If it doesn’t connect successfully, the Agent will terminate the processes to scan or generate the injection. It improves the reliability by avoiding processes hanging due to Empower errors.
• Interval for Empower Connection Status Check (seconds): The time interval to run the Empower Connection check.

Configure Injection Generation Boundary Parameters Settings

The Injection Generation Boundary Parameters section is designed as a fail-safe should Empower indicate that the injection processing hangs in the incomplete state, even though it actually is complete.

The Injection Generation Boundary Parameters section includes the following settings:

• Maximum Acquisition Duration: Indicates how long the Tetra Agent should wait before uploading an incomplete injection processed file. If the injection remains incomplete, the agent will keep scanning and waiting until the injection reaches complete status or reaches the Maximum Acquisition Duration hours after the Last Modified Date of the Channel RAW data file.

📘

NOTE

The default value for the Maximum Acquisition Duration is 72 hours, which is the maximum amount of time that the LAC/E can hold the data in buffering mode. You can adjust this number to accommodate needs specific for your infrastructure. This value can be configured to be any integer from 1 to 150, but we strongly recommend that this value not be less than 72 hours to match the LAC/E buffering duration.

• Tolerance Percentage: Run Time Tolerance is used when comparing the injection run time with the range of timestamps in the injection data. This comparison is used to determine whether an injection has completed or is still in progress, and is only used in versions of Empower where the injection completion status is not available. The actual duration of data collected may not exactly match the planned injection run time, so this configurable tolerance is used in the comparison. If the difference between the last timestamp and the injection run time is in the range of the tolerance percentage, the injection is considered complete. The default value of Run Time Tolerance is 1% and can be set up to 50%. This field is used for Empower 3 Pre-SR3 implementations only.

📘

NOTE

To avoid Data Integrity issues, the Agent will not generate the RAW JSON file until the acquisition process is finished.

• For Empower SR3 and above, the Agent uses the injection status and channel status to determine when injection information is complete.
• Pre-SR3, the Agent uses the injection runtime and the datacube timestamp to determine when injection information is complete.

• Prioritize Injections created/modified in last (hours): Provides the option to specify the number of hours, which the Agent will use to identify any injections that have been created or modified in that window back from now. These injections will be assigned high priority and will be generated before other injections with normal priority are generated. The number of processes used to generate these injections (and the project containing those injections) is defined in Agent Run Time → Advance Settings. The default value is 72 hours. We recommend that you keep this value the same as the Maximum Acquisition Duration setting.

Configure Non-Experiment Settings

To extract and review processing summaries for non-experiment data, configure the following settings in the Non-Experiment section:

The Empower Agent can generate RAW files from the following Empower data streams:

• System Audit trails
• Project Audit trails
• Message Center logs
• Empower Project/User Access permission

Choose Yes for the data stream you want to extract. Non-experiment data shares the same configuration settings as Injection data for uploading to the TDP, and retaining generated data locally.

The Time Interval (minutes) setting can be configured to specify the frequency of generating the non-experiment data. The default value is 60 minutes.

Manage the Empower Projects That the Agent Scans

To manage which projects from Empower the Agent scans and generates, select Project from the left navigation menu. A list of your Empower projects that the Agent's Empower User can access appears.

Projects are arranged in alphabetical order, maintaining the parent-child relationship that is set up in Empower. When new Empower projects are added, the Agent detects them from its periodical scan job and adds those new projects to the Project list automatically.

One Empower Database can contain hundreds to thousands of projects. You can select the projects you want to process. As a System Administrator, you can select which projects the Agent uses to generate the RAW files. Additionally, the Agent constantly monitors any project changes to detect new and updated Injections.

You can configure any of the following on the Project page:

• Save: After making any configuration changes, remember to save settings.
• Refresh : Refreshes the list of projects manually.
• Auto Enable New Project: Select the Auto Enable New Project check box to have the Agent extract the Injections automatically from the projects added to Empower. This feature applies only to those projects that were added or imported to the Empower Agent after you changed and saved the check box setting.
• Auto Enable New Child: When this option is selected, the newly added project will be enabled automatically if its parent project is enabled. Also, the newly added project will inherit the Sign Off Result Option and 3D MS Method from its parent project. When the Auto Enable New Project is selected, the Auto Enable New Child option is selected automatically.
• Enabled: This selection box allows you to manually select or unselect which projects the agent should scan and extract data from. If a project is unselected which injections from it are being generated, the agent will complete generating all injections from it at that time. Subsequently the project will not be scanned and any new or modified injections will not be generated.
• Project : Shows the Empower project name.
• Generation Status: Shows the generation status of the project. The Generation Status has the following possible states:
  • No Injection—Project is not selected.
  • Pending Generation—Project is selected but has not been processed yet.
  • Generation In Progress ( x )—Injections in the project are processing. The X percentage is calculated from the count of total injections and the number of injections have been generated.
  • Generated—Injections in the project have been processed completely. If it is in the middle of processing, it will show how many percentages of total Injections have been processed.
  • There can also be other error messages which are returned from ToolKit during injection scanning.
• Priority: Shows the scan priority assigned to the project. If there are any injections for a project that have been modified within the time provided in Prioritize Injections created/modified in last (hours) setting, the priority is High, else the priority is Normal. Based on the priority, there are dedicated processes to generate the injections (see Configuration → Agent Run Time → Advanced Settings for details).
• Set Priority - As a System Administrator, you can explicitly set the project priority. When this checkbox is checked, the associated Priority field will turn into a dropdown with values as High and Normal. It overwrites what is calculated by the Agent. When the user unchecks this field, the Agent will use the priority calculated by the Agent.
• Last Scanned: Shows the date and time when the project was last scanned by the agent.
• Sign Off Result Option: Provides settings to manage if injection data will be generated by an agent based on sign offs performed in Empower. These are the available options that you can select for the Sign Off Result Option for a project (default is Not Required):
  • Not Required
  • Level 1 Required
  • Level 2 Required
• 3D MS Method: Provides settings to configure which toolkit method will be used to generate 3D MS data cubes, if any injection for the selected project has them. The options are (default is Get3D):
  • None : No 3D MS data cubes will be generated by an agent even if an injection contains that data in Empower
  • Get3D: Will use Get3D toolkit method to generate the 3D MS data cubes. This may result in data that is not precise as Get3D “bins” the results and rounds them.
  • GetSpectra: Will use the GetSpectra toolkit method to generate 3D MS data cubes. This will provide the most precise data from Empower for 3D MS. However, please note this method will be slower to generate the injection. Dedicated process(es) will generate 3D MS with GetSpectra method. The number of processes used for this is defined in 3D MS GetSpectra Generation Processor # setting. Refer to FAQs to know more about the difference between Get3D and GetSpectra methods for 3D MS data cubes.

Review Injection Summaries

To re-upload project data or to review a summary of injection processing, injection processing errors, and system health metrics, choose Injection Summary in the left navigation menu. The Injection Summary page appears.

View Project Data and Re-Upload

The dropdown shows All Projects option as well individual project names, which the Agent has scanned and found injections to be generated. The Processing Summary (see next section for details) shows the injection processing summary for the selected project. If All Projects is selected, then Processing Summary will show data for all projects that the Agent has processed.

The Rerun Project(s) button allows you to re-upload data for selected projects. This will open a project tree to select one or more projects. The projects displayed here are those which are selected in the Project tab and that the Agent has already generated injections for. The projects list is alphabetically ordered and will have parent-child tree similar to how it is displayed in the Project tab.

Choose OK to re-upload all the injections for the selected projects. All projects may be re-uploaded using this option.

View a Processing Summary

The Processing Summary shows the scan, generation, and upload status of injections for a selected project (or all projects).

The Processing Summary displays the following information:

• Scanned Injections: Number of Injections scanned by the agent
• Pending Generation: Number of Injections that have been scanned but not generated yet by the agent
  • 3D MS w/ GetSpectra: Number of Injections which have 3D MS data cubes, and corresponding 3D MS Method in project is GetSpectra, that have been scanned but not generated yet by the agent
• Generated: Number of scanned Injections for which that RAW files generated
• Failed to Generate: Number of scanned Injections that failed to generate a RAW file
• Pending Upload: Number of generated Injections waiting to be uploaded to the agent
• Uploaded: Number of Injections that have been uploaded to TDP successfully
• Failed to Upload: Number of Injections that the agent failed to upload to TDP
• Last Refresh: Timestamp of latest Injection processing summary displayed in local time

Review Injection Generation Error and Injection Upload Errors

To review injections that were scanned but couldn't be generated because of an error, look at the Injection Generation Error tab.

To review injections that were generated, but couldn't be uploaded to the TDP because of an error, look at the Injection Upload Error tab.

To regenerate and re-upload the failed injections manually, select a row in the grid and click Regenerate failed injections or Reupload failed injections in the appropriate grid.

Review System Messages

The Tetra Empower Agent generates host server system metrics every minute and provides the following metrics:

• Available Disk Space (in GB)
• Disk Usage (as a % of the total)
• CPU Usage (as a % of the total)
• Memory Usage (in MB)
• Available Memory (in MB)
• Upload Error Rate
• Scan Access Rate
• Data Connection (connection status between the Agent and the TDP)

📘

CPU Usage Percent is 0%

If the CPU Usage Percent shows 0%, then the user account that was defined as an Empower Group User was not included in either the Administrators group or the Performance Monitor Users group.

Review Non-Experiment Summaries

The Non-Experiment Summary section's Audit Trail tab displays the details audits the agent has extracted.

The project name is applied to ProjectAuditTrail type. For SystemAuditTrail and MessageCenter, the Agent uses the Empower Database Name.

Additional data fields include the following:

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

The Project/User Access Permission tab includes its own summary page, where you can review its Project Status, Last Process Time, and any Messages.

Empower Agent scans projects periodically. When the Agent detects any changes from Empower Project, User, User group, User type, or the methods, the Agent generates a JSON file containing all of the Empower users, user types, and projects and method names with their associated user groups.

📘

NOTE

The Empower Agent now has a Clear Cache button to clean up the local cache of Project User Permission data. This causes the Agent to generate the data from scratch rather than incrementally. It is useful when the local state is in an invalid state and is preventing the Agent from extracting the data from Empower.

You can find which events trigger file regeneration and re-upload in this section of the FAQ.

📘

NOTE

If you store Non-Experiment data in the local drive, it is moved to an Archive folder under the following directory: \<Output_Folder>\<Stream>\<Archive>\\

Configure Archive Service Settings

The Archive Service archives Empower projects to the TDP and provides the ability to restore Project Archives back to Empower from the TDP.

When the Archive Service's Auto Archive option is activated (set to Yes), the Agent archives Empower projects by following a predefined workflow determined by the Archive Run Time Settings that you configure during installation. When deactivating this option (set to No), the Agent won't archive Empower projects automatically, but users can still archive Empower projects manually.

If a project remains inactive for a specified number of days, the Agent imposes a five-day lock on the project. Then, if no activity occurs within this frame, the Agent initiates the archiving process for that project. After the backed up project is uploaded to the TDP, the project and its labels become searchable within the TDP.

To configure the Archive Service, first enable the Archive Service on the Configuration page in the Connector section. Then, activate the Auto Archive feature by doing the following:

📘

NOTE

The Auto Archive feature is applicable to all accessible Empower projects under the Tetra Empower Agent's Empower Database user account.

1. Open the Tetra Empower Agent Management Console. Then, in the left navigation menu, under Menu, choose Configuration.
2. In the Connector section, make sure that the Enable Archive Service option is set to Yes.
3. Select the Archive tab.
4. In the Archive Run Time settings section, for Auto Archive Enabled, select Yes.
5. Configure the remaining Archive Run Time settings.

The following settings are available on the Archive Run Time tab:

• Auto Archive Enabled: The Agent offers support for both manual (ad hoc) archive and automatic archive. When the Auto Archive option is activated (set to Yes), the Agent archives Empower projects by following a predefined workflow determined by the Archive Run Time Settings that you configure. When deactivating this option (set to No), the Agent won't archive Empower projects automatically, but users can still archive Empower projects manually.
• Automatically archive Empower projects if they have been inactive for x days since the last modified date: This option is activated when Auto Archive Enabled is set to Yes.
  Once activated, the Archive service applies read-only locks on any Empower projects that have not been updated for the number of days specified. For example, you could set 180 for this rule, and old projects that have not been updated for at least 180 days will be locked as automatic archive candidates. The Archive service would then periodically scan all available projects for archive candidates.

🚧

IMPORTANT

The Archive service relies on the full Audit Trail for each project to determine its last change date. Projects with Audit Trail turned off will not be eligible for automatic archive.

• Grace Period for lock-down: This option is activated when Auto Archive Enabled is set to Yes. This rule makes the Archive service hold off the archive operation after projects are locked as archive candidates from the step above. During this grace period, projects that incur changes will not be archived. The project will then be put back to the project list and will be processed during the Agent's next scan. In the example shown above, you could set 5 days as the grace period, and then projects, which are locked from the prior step, will not be archived until the end of the five-day grace period.

• Anchor Project Name: The Agent requires a valid and unlocked project to access Empower during archive or restore operations. It's recommended that you dedicate a project in Empower for this purpose. This project won't be auto archived.

• Max retry times: You can specify the maximum retry count when the archive or restore fails because of any exception.

• Archive Advanced Settings

• Archive Auto Scan Interval In Hours: Determines the frequency of project scans. The default value is set to 24 hours, meaning that the Agent will not scan Empower for project changes if it has been less than 24 hours since the last scan.

• Archive Project Refresh Command Timeout In Minutes: Determines the timeout duration (in minutes) for the Agent to detect the new projects from Empower. The default time is 600 minutes.

• Archive Project Auto Scan Command Timeout In Minutes: Specifies the timeout duration (in minutes) for the Agent to scan projects in Empower and detect any changes. The default duration is set to 600 minutes.

• Archive Project Backup Command Timeout In Minutes: Specifies the timeout duration (in minutes) for backing up a project in Empower. The default time is set to 600 minutes.

• Archive Project Restore Command Timeout In Minutes: Specifies the timeout duration (in minutes) for restoring a project in Empower. The default duration is set to 600 minutes.

• Default Archive Comment: Defines the comment that may be necessary for Empower when archiving or restoring the Empower project.

📘

NOTE

The Archive service makes sure that any of the archived project's child projects are archived before the parent projects. The Tetra Empower Agent initiates the archiving process starting from the leaf-level projects, and then recursively works upward until reaching the top-level project.

Auto Archive Workflow

🚧

IMPORTANT

If an Empower project has a Full Project Lock, the Agent will set the Auto Archive status to Failed. If this occurs, you must either remove the Full Project Lock or archive it manually. For instructions on removing the lock, see How to lock projects and sub-projects in Empower in the Waters Knowledge Base.

When Auto Archive is activated, the following workflow occurs for each project that's archived.

Excluded A Project from Auto Archiving

To exclude an Empower project from being automatically archived, do the following:

1. Open the Tetra Empower Agent Management Console. Then, in the left navigation menu, under Menu, choose Archive Service.
2. Choose Project. The Project tab appears.
3. Find the name of the project that you want to exclude from archival. Then, on the far right of that project's row, select the Exclude button.

Manually Archive a Project

📘

NOTE

Manually archived projects undergo the same workflow as Auto Archive projects in terms of Extracting, Verifying, Uploading, and Deleting.

To manually archive Empower projects, do the following:

1. Open the Tetra Empower Agent Management Console. Then, in the left navigation menu, under Menu, choose Archive Service.
2. Choose Project. The Project tab appears.
3. Find the name of the project that you want to manually archive. Then, on the far right of that project's row, select the Archive button. The project's status changes to Submit to Archive, and the project is added to the Agent's archive processing queue.

🚧

IMPORTANT

To manually archive a parent-level Empower project that has child projects, you must first archive the child projects. Empower doesn't allow orphaned child projects, so the archival of the parent-level project will fail otherwise.

🚧

IMPORTANT

The Agent will be unable to archive the project if the combined length of the Agent's Output folder path and the full project path exceeds 240 characters.

Restore an Archived Project

To restore an archived Empower project from the TDP to Empower, do the following:

1. Get the project's TDP File ID by doing one of the following:
   • In the Archive service's Project tab in the Tetra Empower Agent Management Console, find the project that you want to restore. Then, in the Message column for that project, copy the File ID that's listed.
     

   \-or-
   

   • Search for the archived Empower project in the TDP. Then, open the File Details page for the project and copy the File ID that's listed.

2. Open the Tetra Empower Agent Management Console. Then, in the left navigation menu, under Menu, choose Archive Service.
3. Choose Project. The Project tab appears.
4. Select the Restore button. The Restore dialog appears.

5. For Enter your backup project file id here, enter the project's File ID. Then, choose Restore.

6. Review the restored project's information. Then, choose Submit.

📘

NOTE

If there isn't enough space on the local drive to accommodate the downloaded and uncompressed project, the restore request cannot be submitted. When this occurs, the Agent rechecks the available space after the archived project is downloaded.
If there still isn't enough space, the restore process fails.

7. View the details of the restore process by opening the Archive Service's Summary tab for processing details. After choosing Submit on the Restore action, the project status changes to Submit to Restore and the project is added to the Agent's restore processing queue. If there is any application error or project data integrity issues, the Agent marks the status as Failed.

Restored Project File Names

Based on the restored project's state, one of the following naming conventions is appended to the project's file name after its restored to Empower:

• For a restored project, the Agent appends (restored) to the project name. For example, if a project's original name is Tetra_Test, the Agent suggests the restored project name as Tetra_Test(restored).

  

• If a project has been previously restored, the Agent appends a counter to the project name, such as Test321(restored)2 in the Project Path field.

  

• If a project with the same name already exists, the user is prompted to select a different project name.

  

Manage Transactions

You can can review all transactions related to archive or restore processes from the Archive Service's Summary tab in Tetra Empower Agent Management Console. You can also use the Summary tab to cancel archive or restore operations, or restart failed operations.

To access the Summary tab, do the following:

1. Open the Tetra Empower Agent Management Console. Then, in the left navigation menu, under Menu, choose Archive Service.
2. Choose Summary. The Summary tab appears.

View Transactions

To view details about a specific archive or restore process, select the process in the Summary page. A dialog appears that displays detailed operational activities for each transaction.

Successfully Archived Project Example

Failed Project Restore Example

Cancel an Archive or Restore Process

To cancel a running archive or restore process, select the Cancel button in that transaction's row on the Summary tab.

You can cancel processes that are in the following statuses:

• Submit to archive (Archive)
• Locked (Archive)
• Extracting (Archive)
• Downloading (Restore)

Restart an Archive or Restore Process

You can restart a failed archive or restore process in the following situations:

• The project has Full Project Lock activated in Empower. In this scenario, you can either remove the Full Project Lock in Empower or manually archive the project.

• The project encounters a data integrity issue, but you would like to still archive the project. In this scenario, you can restart the process by selecting Rerun with project integrity issue ignored. The Agent then archives the project without raising Verification Error again.

View Audit Trail

The TDP has a secure, computer-generated, time-stamped audit trail to independently record the date and time of operator entries and actions that create, modify, or logically delete electronic records. As an Org Admin user, you can access the audit trail, filter and view audit trail records, and download them to a CSV for further analysis or record keeping.

For more information, see Audit Trail.

📘

NOTE

To see an Audit Trail entry's logs, select View Change in that entry's row on the Audit Trail page in the TDP.

Data Integrity Verification

The following sections describe the data integrity verification process for Empower Project data and TDP Archive Project data.

Empower Project Data Integrity

If any data integrity errors occur, the Agent labels the process as an Integrity Error in the Tetra Empower Agent Management Console.

The Archive Service validates each project's data integrity by using the following resources:

🚧

IMPORTANT

The Agent marks archive and restore processes as Failed if the Backup.log contains Oracle-related errors, such as the following:

• EXP-00008: ORACLE error 3113 encountered
• ORA-03113: end-of-file on communication channel
• EXP-00008: ORACLE error 1041 encountered
• ORA-01041: internal error. hostdef extension doesn't exist
• EXP-00000: Export terminated unsuccessfully

TDP Archive Project Data Integrity

The Agent verifies the archived file checksum against the checksum generated by the TDP. It also ensures the data exists in the TDP before removing the project from Empower.

Project-Level Labels

The Archive Service captures the following labels from the Empower project and Empower software.

TDP UI Configuration

You can use the Agents page in the TDP UI to do the following:

• Configure Empower project settings
• Initiate scan requests for Empower projects

🚧

IMPORTANT

To view and configure Tetra Empower Agents in the TDP UI, you must sign in to the TDP as a user with an Administrator role.

Prerequisites

Before you can configure the Tetra Empower Agent in the TDP UI, you must do the following:

• Create a new Tetra Empower Agent.

• Install the Tetra Empower Agent 5.3.0 on a local host server. For more information, see the Tetra Empower Agent Installation Guide (v5.3.x).

• From the Tetra Empower Agent Management Console, select Yes for the Receive Commands option. For instructions, see Verify Connector Settings in the Tetra Empower Agent Installation Guide (v5.3.x).

Configure Empower Project Settings from the TDP UI

To configure Empower project settings from the TDP UI, do the following:

1. Sign in to the TDP as a user with an Administrator role.
2. In the left navigation menu, choose Data Sources.
3. Choose Agents. The Agents page appears.
4. Select the name of the Tetra Empower Agent that you want to configure. The Agent Details page appears.
5. Select the Configuration tab. The Agent's configuration information appears.
6. In the Project Configurations section, choose the Edit button.
7. Configure any of the available Empower Project settings.
8. Choose Save Edits. A dialog appears that asks you to confirm that you want to save your changes.
9. Choose Update Project to save the updated settings.

📘

NOTE

When new settings are saved through the TDP UI, the Tetra Empower Agent is updated locally. You can verify that the settings were applied by the date/timestamp shown under Project Configurations.

Empower Project Settings

You can configure any of the following Empower Project settings in the TDP UI. For more information about each project setting, see Manage the Empower Projects That the Agent Scans.

Initiate Scan Requests for Empower Projects from the TDP UI

To initiate scan requests for Empower projects from the TDP UI, do the following:

📘

NOTE

To help reduce upload latency, it's recommended that you scan as few paths at the same time as possible.

1. Sign in to the TDP as a user with an Administrator role.
2. In the left navigation menu, choose Data Sources.
3. Choose Agents. The Agents page appears.
4. Select the name of the Tetra Empower Agent that you want to initiate a scan request for. The Agent Details page appears.
5. Select the Configuration tab. The Agent's configuration information appears.
6. In the Project Configurations section, choose Scan Projects. Check boxes appear to the left of each project path name.
7. Select check boxes for up to 10 enabled project paths that you want the Agent to scan.
8. Choose Scan [#] Projects. A window appears showing the Empower project path(s) selected for a scan and the last time these projects were scanned. Review that these project paths are all correct. Then, select Scan Projects to initiate the scan.
9. In the Project Configurations section, review the Last Manual Scan column to see the current status of the scan for each path.