This guide is for the Tetra UNICORN Agent, version 3.6.0. It describes how to:

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

📘

NOTE

If you want to upgrade, see these instructions: https://developers.tetrascience.com/docs/upgrade.

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.

📘

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 Tetra Data Platform (TDP).

• New Installation to install a new Agent and replace the existing Agent database and configuration files.

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 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. If you want to process files in any of the directories, click No for HDA Logon Required. If you want to process files that are in a specific user's directory only, click Yes for HDA Logon Required. You'll need to add a username and password. For more information on this security feature, see the HDA Logon Required section later in this document.
7. The table specifies the UNICORN path containing: Domain Name, Host, and Address Space 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.
• Address Space - 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 where the "Result Creation Date" is within this date timeframe. The "Result Creation Date" in UNICORN is the original testing date or the date when the result file was imported into a UNICORN system from another UNICORN system. If you leave the Reupload End Date blank, then the Agent uses the current date as the end date.
3. Click OK.

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 the rules for the Tetra UNICORN Agent to determine file change:

• 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).

The Tetra UNICORN Agent does two account verifications automatically in the following two scenarios.

• When the Windows Configuration UI launches first time.
• When the user click the Start button to start the service.
  To avoid unexpected behavior from OPC, please create a dedicated user account to restrict the OPC access from Tetra UNICORN Agent.

Passing User Credentials (HDA Logon Required)

You can pass user credentials via the Tetra UNICORN Agent when extracting UNICORN Result files through Open Platform Communications Historical Data Access (OPC HDA). Use this feature, to allow the Tetra UNICORN Agent access to only the subdirectories and files under the user’s directory.

To do this, you’ll need to do two things.

• Enable the Logon Required HDA Clients in UNICORN and Set Up User Accounts
• Configure the HDA Login Required Setting in the Tetra UNICORN Agent

Enable the Logon Required HDA Clients in UNICORN and Set Up User Accounts

To do this complete the following steps in UNICORN.

1. Enable “Logon required HDA clients“ in UNICORN. The setting can be found in Tools -> Options -> OPC Settings.

2. Lock the UNICORN Default user account since the Default is a built-in UNICORN account with Administrator privilege.

3. Create an Access Group and choose the OPC folders for that Access Group. For example, you can create an Access Group called Users and select the TetraScience folder. (You can select multiple folders.)

4. Create a dedicated user account and assign the user to the Access Group created above, and use that account on the Tetra UNICORN Agent. For example, create a user, UNICORN_Test and assign the user to the new created Access Group “Users”.

📘

Dedicated User Account

We recommend you use a dedicated user account instead of using a normal user account with Evaluation Logbook change turned on to detect the Result File change. Here’s why.

When OPC accesses/opens the Result file, UNICORN creates a record in Evaluation Logbook. The Tetra UNICORN Agent ignores the entries in the Evaluation Logbook that contain “User: <User_Name>“ (If there is not HDA authentication required, the <User_Name> is OPC).

If the <User_Name> is a normal user account, Tetra UNICORN Agent cannot tell if the entries is created by the real user or the Agent itself.

📘

Multiple Access Groups Is Not Supported

When passing the user credential to OPC, OPC cannot support multiple Access Groups. OPC only allows access to the folders specified by one Access Group. OPC cannot access folders combined from multiple Access Groups that the user is able to access outside of OPC.

📘

User Name Limitation and Case Sensitivity

If the user name is the same as any folder name in the OPC address path, the OPC iterates the folder recursively. Please note that the User Name is case sensitive. For example, if there is a UNICORN local user, called TS and there is a folder with the same name (TS) in OPC path. This can cause the OPC to iterate recursively from folder TS.

In the screenshot above, there is a UNICORN local user, called TS and there is a folder with the same name (TS) in OPC path. This can cause the OPC to iterate recursively from folder TS.

Configure the Tetra UNICORN Agent with HDA Logon Required Option

To do this, complete the following steps.

1. Select HDA Logon Required in the Tetra UNICORN Agent’s Management Console.
2. Enter the UNICORN local user’s name and password.
3. The Tetra UNICORN Agent verifies the account by trying to connect to the OPC HDA. The Tetra UNICORN Agent management console displays the status as “Valid“, “Invalid“, or “Locked/Not Found“ to indicate whether the user name and password combination are correct, the account is locked, or that the user account doesn’t exist.
   Click the Verify button to verify the user name and password combination change.
   If the account is locked, you must unlock it in UNICORN.
   When the path is created by the user, the Agent verifies the path by using the user account and address entered in the path. For example:

Path 1:

• Connected
• Address is valid. The address can be <valid_username>, <valid_username>\Folder or <valid_username>\Folder\DefaultHome.

Path 2

• Not connected
• Address is invalid. This can be because of the following issues: <invalid_user>, <invalid_user>\Folder , <invalid_user>\Folder\DefaultHome or <valid_user>\Folder\DefaultHome<invalid_subpaths>.

After you create the new address path, Tetra UNICORN Agent will automatically try to connect to UNICORN OPC HDA using the specified user. The connection status will be displayed in the grid. The status is either Connected or Not Connected.

• If the status is “Not Connected”, the user should check if the specified user account can access the address path.
• If any of the paths show “Not Connected”, the user is not able to start the UNICORN Agent.

If you turn HDA Logon Required off, the user name and password fields are disabled and the Tetra UNICORN agent doesn’t pass the user credentials to OPC HDA. The Tetra UNICORN Agent won't use any authentication mechanism to access the UNICORN HDA service.

User names and passwords are saved to the local Sqlite database as encrypted data.

Result file RAW JSON Generation

The Tetra UNICORN Agent will pass the user credentials to access OPC HDA as additional parameters if they are available. The Agent generates the Result files based on the accessibility of the user credentials.

The content of the Result RAW JSON file and IDS file will remain the same by compared with previous UNICORN Agent version.

Potential Issues and Limitations

Data Integrity Risk

Since you can switch to a different user, it can lead to potential data duplication.

This approach could cause the Tetra UNICORN Agent to extract and generate the Result files from UNICORN again. Because the user account name is part of the Result File OPC Address space, Result files can have a different OPC address even though both OPC addresses point to the same result file in the UNICORN database.

For example, when the user switches the user account from “Administrator” to “UNICORN_Test”, it can lead to the following:

• The files in the folder of Administrator\Folders\Defaulthome are not accessible anymore.
• The files under the folder of Administrator\Folders\Test will be regenerated, because the files have different OPC address space after the account is switched. For example,
  • When logging in as Administrator, the Result file, Test\UNICORN_Test2\EXPORT TEST 2 , has OPC address Administrator\Folders\Test\UNICORN_Test2\EXPORT TEST 2.
  • When the UNICORN_Test user logs in, its OPC Address becomes UNICORN_Test\Folders\Test\UNICORN_Test\EXPORT TEST 2.

📘

NOTE

This could cause the same result to be uploaded multiple times. In the example above, EXPORT TEST 2 would be uploaded twice. You should be fully aware of this risk before you start to use this feature.

HDA Logon Required Setting Conflict

As we described earlier, the user needs to configure “HDA logon required” option on both UNICORN and Tetra UNICORN Agent. The setting should match in both places. The workflow we described in previous sections are the scenarios where both settings match. However, if the settings are different, it can introduce unexpected behavior.

• If “HDA logon required for clients“ is turned on in UNICORN, but off in the Tetra UNICORN Agent:

  • The connection status in the path shows “Not Connected“.
  • Tetra UNICORN Agent cannot start.
  • Tetra UNICORN Agent cannot access any Result files.

• If “HDA logon required for clients“ is off in UNICORN, but on in the Tetra UNICORN Agent:

  • The Tetra UNICORN Agent can access all of the Result files in UNICORN.
  • The Tetra UNICORN Agent can extract all of the Result files from the specified OPC address path.

UNICORN User Account lock

UNICORN can potentially lock the user account if the password is entered incorrectly. The number of
unsuccessful log on attempts before UNICORN locks is set in the Password Policy dialog, as shown below.

To avoid locking the account unintentionally by the Tetra UNICORN Agent, the Tetra UNICORN Agent adds a button in configuration UI for user to validate the account and address path.

The OPC library returns different error codes for locked accounts and invalid accounts. These are displayed next to the Verify button as shown below.

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)