This guide is for the Tetra UNICORN Agent, version 3.5.0 and describes how to:

• Install the Tetra UNICORN Agent
• Configure the Tetra UNICORN Agent and its services
• Monitor Agent Progress and Server System Metrics

📘

Windows Management Console User Interface

As of version 3.0.0, the Tetra UNICORN Agent provides a Windows-based Management Console User Interface for easy configuration.

Install the Tetra UNICORN Agent

To install the Tetra UNICORN Agent:

1. Run the Windows Installation Package (msi file). You can select either:

• Upgrade to perform an upgrade and migrate the existing Agent database and configuration files from a previous version.
• New Installation to install a new Agent and replace the existing Agent database and configuration files.

📘

Upgrade Option

If you select Upgrade, the Agent retains the configuration settings and database from the previous version. As a result, any files that were generated from UNICORN are not regenerated and uploaded to the TetraScience Data Platform (TDP).

2. After the UNICORN Agent has successfully installed, click the Tetra Agent UNICORN shortcut from the Windows Program Menu to open the Windows-based Management Console.
3. From the Management Console, you can configure the Tetra UNICORN Agent settings and review the Agent progress.

Configure the Tetra UNICORN Agent and its Services

You can use the Management Console to:

• Start and stop the Agent
• Set a Windows Scheduled task
• Configure the UNICORN Agent
• Configure the UNICORN Agent services
• Set up the data connection to the Tetra Data Platform (TDP)

Section 1: Start and Stop the Agent

This section indicates the Agent's processing using these statuses:

• Agent Service Not Installed
• Running
• Stopped

• To save the UNICORN Agent configuration changes, click Save.
• To start the UNICORN Agent with the new configuration settings, click Start. When the UNICORN Agent starts, the status indicator shows Running for an Agent that is successfully up and running.
• When the UNICORN Agent starts, the Stop button is enabled. To stop the UNICORN Agent, click Stop.

Section 2: Set Windows Scheduled Task

You can increase the Agent's reliability by ensuring that it remains online without having to manually check it each day.

1. Select Yes to enable the Windows Scheduled Task to check Agent Service Status option on a daily basis.
2. Specify the time in the Run Time field when you want the scheduled Windows task to check on the status of the UNICORN Agent service.

• If the Agent is stopped, then the scheduled Windows task automatically restarts the Agent service.
• If the Agent is running, nothing further happens.
• If you manually stop the UNICORN Agent, then the Windows task is removed, and the Windows Task that you create runs under the LocalSystem account.

Section 3: Configure the UNICORN Agent

Area A: UNICORN Agent Services

The Tetra UNICORN Agent provides two services:

• HDA Service - Used to detect the UNICORN result files through OPC HDA.
• AE Service - Detects the alarm and events raised from the UNICORN Instrument service.

Select Yes to enable one service, or both of these services.

Area B: Advanced Settings

1. Click Advanced Settings to open the Agent Configuration Advanced Settings pane.

You can specify the time intervals for these fields (default value for each field is 30 seconds):

• Data Connection status check every - Indicates how often the software checks the status of the connection (heartbeat) between the Tetra Data Platform and the UNICORN Agent. If the Tetra Data Platform does not receive a message indicating that the UNICORN Agent is "alive" for more than 5 minutes, it assumes that the Agent is offline.
• File Upload Job runs every - Indicates how often to upload files to the Data Lake.
• Agent log files upload every - Indicates how often to upload log files to the Data Lake.

📘

Software Version 3.4 Update

To improve readability, the After a watched file is modified, wait for it to stop changing field was renamed to File Upload Job runs every, and the Upload Log File field was renamed to Agent log files uploads every.

Area C: S3 Direct Upload

To have the Tetra UNICORN Agent directly upload files to the AWS S3 bucket bypassing GDC or CDC, set the S3 Direct Upload option to Yes. When you set this option to Yes, you can upload a maximum file size of five TB. No is the default setting.

• If you use the S3 Direct Upload option with GDC, you must add an L7 Proxy Data Connector in the same Data Hub where you set up the GDC. Additionally, the port of the L7 Proxy Data Connector is open. To learn more about GDC, see this link.
• To learn more about CDC, see this link.

📘

SQLite Database File Backups

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

If you do not use not use the S3 Direct Upload option, then we recommend that you create periodic backups of the Tetra Agent database, which is typically stored in the installation folder under C:\TetraScience<agent>\Bin\Database. 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.

Area D: Agent ID and Connection URL

Before you set up a Tetra UNICORN Agent from GDC or CDC, you must enter:

• (Required) An Agent ID. The Agent ID (a UUID) is used to connect the Tetra Data Platform. You can retrieve Agent ID from the Tetra Data Platform when you set set up GDC or CDC.
• A full connection URL from GDC or CDC (as shown in these URL examples):
  • GDC URL is http://10.100.1.1:8888/generic-connector/v1/agent
  • CDC URL is https://api.tetrascience-dev.com/v1/uda/

📘

Verify the Agent ID and Connection URL

• Agent ID is required. The Connection URL is required if you are uploading RAW files to the Tetra Data Platform; optional if you are not.
• Before you use the Agent ID and URL with the Tetra Data Platform, we strongly suggest that you verify both with your TetraScience Customer Success Team.

If you use the CDC Connector, then you must:

1. When using the JWT token, the Org Slug field is required. Enter the Org Slug to attach it to the header.
2. Enter the JWT token in the Authorization field to attach it to the header. To learn how to get the JWT token, see CDC.
3. Click Add/Edit to open a dialog and enter the JWT token.
4. Click Save to close the dialog and encrypt and save the JWT token. The Agent validates the connection immediately and displays the updated connection status next to the Connection URL field.

Section 4: Configure UNICORN Services

Configure HDA Service

The Tetra UNICORN Agent HDA Service is used to detect the UNICORN result files through OPC HDA.
To enable and configure the HDA Service:

1. When you select Yes for the Enable Unicorn HDA field, the HDA Unicorn information displays at the bottom of the Management Console pane:

2. Set the Interval in Seconds field to indicate how often the Tetra Agent scans UNICORN to detect the new result files.
3. Select the HDA Output Folder to where you want to temporarily store the generated RAW files before uploading. You can use the default (C:\Temp) location, or provide a different folder. If the folder does not exist, then the Agent creates the folder.
4. Select Yes to Allow Restart HDA Services to allow the Agent to restart the HDA service, if required. For details, click here.
5. Set Detect changes for last to x number of months to detect any changes from the Result file generated from x months to the current date. For details, click here.
6. The table specifies the UNICORN path containing: Domain Name, Host, and Default Address of the HDA folder. If required, a UNICORN Agent can monitor multiple addresses spaces. To create a new path, click New Path, or double-click the existing path in the table open the Unicorn Path Editor pane:

To define a valid path, you must enter:

• Domain Name - Must be a unique name that identifies the UNICORN Host. It is used as part of File Path when the file is uploaded to the Tetra Data Platform.
• Host - Local server name or IP address. It is part of the connection string used to access UNICORN OPC HDA.
• ProgId - Static value UNICORN_HDAServer12.1 is used to identify UNICORN OPC. It is used by the OPC protocol.
• Default Address - UNICORN HDA folder path. To learn how to find the address, click here. The folder name is case-sensitive.
• Metadata - A key/value pair that specifies the metadata associated with the output files uploaded to the Tetra Data Platform. You can add or edit metadata as needed.
• Tags - Specifies tags associated with the files uploaded to the Tetra Data Platform.

📘

Metadata and Tags

To learn more about metadata and tags, including which characters you can use, see this topic.

Re-upload options enable you to automatically upload new versions of data when the Evaluation Log Book or Evaluation Notes change.

🚧

Experimental Feature

The Re-upload Options feature is marked as experimental because the integration with UNICORN does not provide a native API to detect Evaluation Notes or Evaluation Log Book changes. The Agent infers those changes by parsing the UNICORN logs (and in some cases, it is not accurate), resulting in unnecessary re-uploads. Use this feature if you need the latest version of the Evaluation Log Book or Evaluation Notes, but be aware that you will have multiple versions of the same file, and that new version of data may re-trigger pipelines.

To regenerate and re-upload the result files:

1. Click Re-upload from the Action column in the address path.
2. Set the Reupload Start Date and Reupload End Date. The Tetra Agent will upload any files that were created or updated within this date timeframe. If you leave the Reupload End Date blank, then the Agent uses the current date as the end date.
3. Click OK.

(Features available as of v3.5.0) The Agent verifies the folder path and the user permission when iterating the folder paths. It regenerates and re-uploads the result files using the Result Creation Date within the selected time range.
The Agent also displays an icon in front of every folder path to indicate whether the folder path is valid; a green checkmark for valid, or an orange warning triangle for invalid. The Agent keeps checking the folder paths at each interval, and updates the status if there are any changes.
For more control over data management, you can enable or disable re-uploading folders based on these changes:

• Evaluation Log Book Change
• Evaluation Note Change

Click the check box next to the Evaluation change (s) you want to include. If these changes are excluded, then no automatic re-uploads are generated when an evaluation log book or evaluation note changes.

Configure AE Service

The AE service detects the Alarm and Events generated from the UNICORN Instrument service.
To enable and configure the AE Service:

1. When you select Yes for the Enable Unicorn AE field, the AE Unicorn information displays at the bottom of the Management Console pane:

Similar to the HDA Service, the Agent can detect the Alarms and Events from multiple paths. When necessary, you can delete an existing path.

2. To define a valid path, you must enter:

• Host - Local server name or IP address hosting the UNICORN Agent. We recommend that you use a real machine name or IP address as the host.
• ProgId - Static value UNICORN_AEServer11.System1.1 is used by OPC to identify the UNICORN AE service.
• Metadata - A key/value pair that specifies the metadata associated with the files uploaded to the Tetra Data Platform. You can add or edit metadata as needed.
• Tags - Specifies tags associated with the files uploaded to the Tetra Data Platform.

3. Click Save to save the configuration and start the Agent.

🚧

Daily Agent Run Schedule

After you complete the initial installation and configuration, you can use a Windows Task script to re-start the Tetra UNICORN Agent (for example, you can set it to run at 1:00 AM) and ensure that it runs constantly. For details, see [link] (https://developers.tetrascience.com/docs/using-windows-schedule-task-to-schedule-agent-services).

Monitor Agent Progress and Server System Metrics

To review the UNICORN Agent's run time progress and host server's system metrics, select Summary to open the Summary dashboard:

Section 1: HDA Processing Summary

This section displays the HDA Service status where you can review how many UNICORN HDA result files were detected, generated, and uploaded. If any failure occurs, the numbers display here.

Section 2: Error Messages

This section displays any detailed error messages that occurred during the result file generation and file upload. It displays the file name and error messages.

Section 3: Host Server System Metrics

This section displays the host server system metrics and messages every minute and provides these metrics:

• Data Connection (connection status between the Agent and the Tetra Data Platform)
• Available Disk Space (in GB)
• Disk Usage (as a % of the total)
• CPU Usage (as a % of the total)
• Memory Usage (in MB)