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.
This guide is for version 4.0.0 of the software.
Agent Management Console is divided into eight sections as shown in the screenshot below.
This indicates the Agent's running status. Statuses are listed below:
- Agent Not Installed
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.
- 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.
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.
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.
S3 Direct Upload
If you turn on this option, the Agent uploads the files directly to the AWS S3 bucket bypassing GDC or UDI.
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.
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.
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
- UDI URL is
- GDC URL is
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.
Agent ID is a mandatory field. The Connection Url is optional when not uploading the Raw files to TDP.
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.
Error Retry (Times)
Retry policies for Injection RAW file generation and upload if any unhandled error occurs in either of the cases.
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 Not upload Injection, the Keep Local RAW File After Upload is automatically set as Yes.
If you choose to keep the Raw file local, please beware of the potential issue that the Raw files can take most of the disk space. 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.
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.
Starting from v4.0.0, Empower Agent is able to generate Raw files from Empower Audit Trails (System Audit Trails, Project Audit Trails, and the logs from Message Center).
Non-Experiment data shares the same configuration settings as Injection data, in terms of whether uploading to TDP or retained locally.
After you finish the configuration, save the changes and start the Agent. When the Agent is running, all of the parameters are disabled.
In case, you like to modify the parameters, you need to Stop the Agent first.
Usually, 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.
You can choose one of the following Result Sign Off options for a Project.
- Not Required
- Level 1 Required
- Level 2 Required
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.
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.
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.
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
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
You can check the processing summary for Non-Experiment data. All three types of data streams are included:
The project name is applied to ProjectAuditTrail. For SystemAuditTrail and MessageCenter, the Agent uses the Empower Database Name.
Additional data fields include:
- Total Generated Records
- Last Processing Time
- Latest log (in JSON format)
This can occur if the Group User Account running the Tetra Empower Agent is not part of the Empower User Group.
Check whether the Agent is up running from Management Console. If it stops unexpectedly, restart the Agent from Management Console.
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.
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.
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.
If you need more information about the Tetra Empower Agent, check the FAQ section to learn more or contact your CSM.
Updated about 2 years ago