Tetra UNICORN Agent Installation Guide (Version 3.x.x up to 3.4.0)

Starting from version 3.0.0, TetraScience UNICORN Agent provides a Windows Form based Management Console User Interface for easy configuration.

Installation

The user installs the Agent by running the Windows Installation Package (msi file). The installation package provides options to either have a clean installation or upgrade the Agent from the previous version. When choosing upgrade, the Agent retains the configuration setting and database from the previous version, therefore, the result files which have been generated from UNICORN won't be regenerated and uploaded to the Data Platform.

After the UNICORN Agent is successfully installed, the user can click the shortcut of TetraScience Agent Unicorn from Windows Program Menu. From there, the user can configure the Agent settings and check the Agent progress using Windows-based Agent Management Console

A. Configuration

The Management Console is divided into multiple sections, from where the user can configure the UNICORN service, set up Data Connection to Tetra Data Platform, and start/stop the Agent service.

1. Start/Stop Agent

This section has a couple of action buttons for the user to save the configuration and start the Agent. When the Agent starts, there has an indicator to see if the Agent is up and running.

When the Agent starts, the Stop button is enabled. The user can click Stop button to stop the Agent.

2. Agent Configuration

TetraScinece UNICORN Agent ships two services, HDA and AE. The user can enable at least one of the services.

The user also needs to provide the necessary information on how to connect to the Tetra Data Platform. TetraScince provides various ways to connect the Tetra Data Platform. Please reference this link to select the best option to fit your needs.

S3 Direct Upload

When turning on this option, the Agent is going to upload the files directly to AWS S3 bucket bypassing from GDC or UDI. Please beware if using the S3 Direct Upload option with GDC, an L7 Proxy Data Connector needs to be created in the same Data Hub where the GDC is set. Also, the port of the L7 Proxy Data Connector is open.

With this option turned on, the user is able to upload up to 500 GB of file.

📘

NOTE:

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. (Please check here if any question)

• Agent ID is a UUID
• Examples of the URL from GDC or UDI as below
  GDC URL is http://10.100.1.1:8888/generic-connector/v1/agent
  UDI URL is https://api.tetrascience-dev.com/v1/uda/
  It is strongly suggested to verify the Agent ID and URL with TetraScience Delivery Engineer before using it.

Please make sure to enter the full URL to Connection Url

Additional note when using UDI:

If the user uses the UDI URL, it is required to attach either API Key or JWT token to the header.
Please reference the doc regarding UDI to learn how to get API key and JWT Token.

The user clicks Edit button of Connection Headers, a model window pops up with three predefined header keys:

If the user uses API Key, she needs to put the value next to x-api-key.

If the user uses JWT token, she needs to fill both x-org-slug and Authorization.

Please note: when entering the value for Authorization, Bearer is optional. If it is not provided by the user, the Agent will add it automatically.

When the header values are saved, the model window will close. The Agent validates the connection immediately. The connection status is shown in front.

Advanced Settings

A model window allows the users to specify the time interval of sending the Agent Heartbeat and uploading output files. The default values are 30 seconds.

3 UNICORN Service Configuration

HDA Service

TetraScience UNICORN Agent HDA Service is used to detect the UNICORN result files through OPC HDA.

• HDA Output Folder Indicates the output folder to store generated Raw files temporarily. The user can use the default (C:\Temp) or provide a different one. The Agent creates the folder if the folder doesn't exist.
• Interval Indicates how often the Agent scans UNICORN to detect the new result files.
• Allow Restart HDA Services Allows the Agent to restart the HDA service if needed. Please check here for more details.
• Detect changes for last x Month Detects the changes from the Result file generated from x months to the current date. Please check here for more details.
• Path Specifies the UNICORN Hostname and HDA folder Address. The Agent can monitor multiple Addresses if needed. The user can click New Path to create a new one or double-click the record to edit.

• Domain Name, a unique name to identify the UNICORN Host. It is used as part of File Path when the file is uploaded to TetraScience Platform
• Host, the local server name or IP. It is part of the connection string to access UNICORN OPC HDA
• ProgId, UNICORN_HDAServer12.1, a static value to identify UNICORN OPC. It is used by OPC protocol.
• Default Address, the UNICORN HDA folder path. If any questions regarding how to find out the address, please check here. Please be aware the folder name is case sensitive.
• Excluded Folders, specify the folders which should be excluded from outputted file.
• Metadata, specify the metadata which can be associated with the files uploaded to the Platform. The metadata is a key/value pair. The user can add or edit the Metadata as needed.
• Tags, specify the tags which can be associated with the files uploaded to the Platform.

AE Service

The TeraScinece UNICORN Agent AE service is to detect the Alarm and Events raised from UNICORN Instrument service. Same as HDA Service, the Agent can detect the Alarms and Events from one or more paths. The user can delete an existing path as needed.

The user defines a valid path by providing the following information

• Host, the server name hosted the UNICORN. TetraScience suggests using a real machine name or IP as the Host.
• ProgId, UNICORN_AEServer11.System1.1 It is the constant value used by OPC to identify UNICORN AE service,
• Metadata, specify the metadata which can be associated with the files uploaded to the Platform. The meta data is key/value pair. The user can add or edit the Metadata as needed.
• Tags, specify the tags which can be associated with the files uploaded to the Platform.

When the user satisfies all of the configuration settings, she can click the Save button on the top and Start the Agent.

🚧

NOTE

Once installation and your initial configuration are complete, use a windows task script to start the agent daily (such as at 1:00 a.m.) to ensure that the agent continues to remain running. For information on how to do this, view this topic.

B. Summary Page

In Summary page, the user can check the Agent's run time progress and the host server's system metrics.

1. HDA Service Status, the user can see how many UNICORN HDA result files are detected, generated, and uploaded. In case, there has any failure, the numbers are displayed in the summary section.

2. This section displays the detailed error messages during the Result file generation and file upload. It shows the file name and error messages.

3. This section is to show the host server system metrics. Every minute, the Agent 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