[llms-txt]: # (For AI agents: the complete documentation index is at https://developers.tetrascience.com/llms.txt — markdown versions of any page are available by appending .md to the URL.) 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](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. {623}

Tetra Agent UNICORN Installation options 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. {1250}

Tetra UNICORN Agent Management Console # 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 {756}

Agent Processing Status * 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. {630}

Windows Scheduled Task ## 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. {485}

Agent Configuration Advanced Settings 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](https://developers.tetrascience.com/docs/agent-common-behavior#generic-data-connector-aka-gdc). * To learn more about CDC, see [this link](https://developers.tetrascience.com/docs/agent-common-behavior#user-defined-integration-aka-udi). > 📘 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](https://developers.tetrascience.com/docs/restore-agent-from-backup) 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\\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](https://developers.tetrascience.com/docs/agent-common-behavior#user-defined-integration-aka-udi). 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](https://developers.tetrascience.com/docs/common-issues-and-solution#any-impact-to-unicorn-if-the-agent-restarts-hda-services-when-the-experiment-is-running). 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](https://developers.tetrascience.com/docs/common-issues-and-solution#what-is-the-impact-of-detect-changes-for-last-x-month-on-the-file-generation). 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: {625}

UNICORN Path Editor {984}

Unicorn HDA Service configuration 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](https://developers.tetrascience.com/docs/common-issues-and-solution#how-to-find-out-the-unicorn-hda-address-space). 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](https://developers.tetrascience.com/docs/basic-concepts-metadata-tags-and-labels). 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**. {538}

Re-upload result files within specified date range 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: {894}

UNICORN AE Service configuration Similar to the HDA Service, the Agent can detect the Alarms and Events from multiple paths. When necessary, you can delete an existing path. {636}

AE Path Editor 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](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. ![406](https://files.readme.io/14ad2d2-options.png "options.png") 2. Lock the UNICORN Default user account since the Default is a built-in UNICORN account with Administrator privilege. ![945](https://files.readme.io/155e22a-unicornusersetup.png "unicornusersetup.png") 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.) ![981](https://files.readme.io/969676a-accessgroupandnetworkusers.png "accessgroupandnetworkusers.png") 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”. ![949](https://files.readme.io/1a40714-unicornusersetup2.png "unicornusersetup2.png") > 📘 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: \“ (If there is not HDA authentication required, the \ is OPC). > > If the \ 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. ![425](https://files.readme.io/293687a-tswitharrows.png "tswitharrows.png") 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 \, \\Folder or \\Folder\DefaultHome. Path 2 * Not connected * Address is invalid. This can be because of the following issues: \, \\Folder , \\Folder\DefaultHome or \\Folder\DefaultHome\. 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. ![1334](https://files.readme.io/c8f6d66-browsesample.png "browsesample.png") 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. ![588](https://files.readme.io/79e6dd7-useraccountlock.png "useraccountlock.png") 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. ![992](https://files.readme.io/71fb470-1bf582a-locked.png "1bf582a-locked.png") # 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: {1195}

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)