This guide is for the Tetra UNICORN Agent, version 3.7.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 to a newer version of UNICORN, 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. The Windows Task that you created runs under the LocalSystem account.

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

Section 3: Configure the UNICORN Agent

UNICORN Agent Services

The Tetra UNICORN Agent provides two services:

• HDA Service: Detects the UNICORN result files through OPC Historical Data Access.
• Alarms and Events (AE) Service: Detects the alarm and events raised from the UNICORN Instrument service.

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

🚧

IMPORTANT

The Alarms and Events (AE) Service is in beta release currently and may require changes in future Tetra UNICORN Agent releases. For more information, or to activate this feature in your TDP environment, contact your customer success manager (CSM).

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 TDP 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 Tetra Data Lake.
• Agent log files upload every - Indicates how often to upload log files to the Tetra 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.

S3 Direct Upload

To have the Tetra UNICORN Agent directly upload files to the AWS S3 bucket bypassing agent integration, 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 using an Agent without a Connector, 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 Tetra 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.

Agent ID and Connection URL

Before you set up a Tetra UNICORN Agent from your Agent, you must enter:

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

📘

Verify the Agent ID and Connection URL

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

If you do not use a 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 this reference.
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 Result files using:

• Evaluation Log Book Change
• Evaluation Note Change
• Results created in the last x number of days.
  You can learn more about the results created in the last x number of days here.

6. If you want to control the access to UNICORN using a specific UNICORN account, you need to turn on the HDA logon required option from UNICORN and, in the UNICORN Agent, select Yes for HDA Logon Required. You'll also need to add a username and password. For more information on this security feature, see the HDA Logon Required section later in this topic.
7. The table specifies the UNICORN path containing: Domain Name, Host, and the Address Space of the Result File 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 window.

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 TDP.
• Host - Local server name or IP address. It is part of the connection string used to access UNICORN OPC HDA service.
• ProgId - Static value UNICORN_HDAServer12.1 is used to identify UNICORN OPC HDA service. It is used by the OPC protocol. (Currently, this value, cannot be changed. This value is valid for UNICORN 6.x and 7.x.)
• 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 TDP. You can add or edit metadata as needed.
• Tags - Specifies tags associated with the files uploaded to TDP. Tags are comma-delimited strings that are associated with output files uploaded to TDP.

📘

Metadata and Tags

To learn more about metadata and tags, including which characters you can use, see this topic. There's also more information about Metadata and Tags near the end of this topic.

Regeneration options (by detecting changes) enable you to automatically upload new versions of data when the Evaluation Log Book or Evaluation Notes change.

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 reuploads are generated when an evaluation log book or evaluation note changes.

🚧

Experimental Feature

The Detect changes feature is an experimental feature 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 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 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.
3. Click OK.

The Agent verifies the folder path and the user permission when iterating the folder paths. It reuploads 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.

Configure AE Service

🚧

IMPORTANT

The Alarms and Events (AE) Service is in beta release currently and may require changes in future Tetra UNICORN Agent releases. For more information, or to activate this feature in your TDP environment, contact your customer success manager (CSM).

The AE service detects the alarm and events generated from the UNICORN Instrument service.

To enable and configure the AE Service, do the following:

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 TDP. You can add or edit metadata as needed.
• Tags - Specifies tags associated with the files uploaded to TDP.

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)

📘

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.

You can pass user credentials via the Tetra UNICORN Agent when extracting UNICORN Result files through the UNICORN OPC HDA Service. Using this feature allows the Tetra UNICORN Agent to only access the user has permissions for.

To configure this please contact your CSM for the detailed steps.

Potential Issues and Limitations

Data Integrity Risks

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.

Method Run Issues

To determine if the Method run completes, the Agent checks the pattern using a regular expression. A date time stamp needs to be evaluated. however, the date-time format is based on the hosting machine. Currently, the supported Date time format is MM/dd/yyyy. When the Agent is deployed to new clients, it is better to check the Date time format in the host machine. The Agent might need to include an additional date time format.

There have been situations that the Method run finishes with errors. The event log looks like this: An error occurred that caused the run to end and the result to be saved. Error description: Instrument network connection lost during run (System). If it happens that the Result file is not generated by the UNICORN Agent, a potential solution for the end-user is to open the Result file from UNICORN Evaluation Module, which will add a new entry to Evaluation Log. With that, the Agent can generate the Raw file

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 TDP.)
• Available Disk Space (in GB)
• Disk Usage (as a % of the total)
• CPU Usage (as a % of the total)
• Memory Usage (in MB)