Tetra UNICORN Agent Installation Guide (Version 2.6.x)

Installation

The user installs the UNICORN Agent by executing the Installation package downloaded from TetraScience.

Starting from version 2.6.0, UNICORN Agent is able to upgrade the Agent automatically without uninstalling the previous version first.

When the user selects the option of Upgrade, the Agent will uninstall the current version of the Agent and then install the new version. The Sqlite database and configuration file from the previous version will be kept and migrated to the new version.

When the user selects the option of New Installation, the Agent will uninstall the current version of UNICORN Agent, and install the new Agent without retaining the Sqlite database and configuration file from the previous version. The user needs to configure the Agent from scratch.

Configuration

📘

What You Need to Prepare

On the Unicorn application machine

• Manually create the output and archive folders with the path defined in the config.json file

On TetraScience platform

• Create a Data Hub and install it on a Data Hub machine. If you don't know what a Data Hub is, check out https://developers.tetrascience.com/docs/introduction
• Find the Data Hub IP. It's shown on the right-hand side of the Data Hub name
• Create a Generic Data Connector v2 under the Data Hub. You need to give a port number for each connector you create, and this port should be open on the machine to accept traffic from agents

config.json

• (Optional) prepare metadata or tags if needed. Each file uploaded by this agent will be tagged with the metadata and tags you provided. They can be used for filtering, searching, pipeline triggers when the files become available in the Tetrascience Data Lake.

👍

What you can find on TetraScience platform

• agent.id - Unique Agent ID (UUID). It will be automatically generated when you add an agent to a connector.
• dataConnector.ip - the endpoint of the Data Connector. It's the combination of the Data Hub machine domain name or IP plus the connector port you entered when setting up the connector.

The default agent package installation location is under C:\TetraScience\TetraScience.Agent.unicorn.v.2.x.x

0. Before we start running the agent, we need to configure it. The configuration file is located at C:\TetraScience\TetraScience.Agent.unicorn.v.2.x.x\Config\config.json
1. Change id to the agent ID provided by TetraScience
2. Change ip to the Data Hub IP and the Connector's port number
3. Change host to your UNICORN network domain name or IP
4. Double check if defaultAddress matches with the path you want to pull data from. You can add subfolders to make it more granular. If any questions regarding how to find out the address, please check here. Please be aware the folder name is case sensitive.

{
  "agent": {
    "id": "<agent Id>",           // provided by TestraScience
    "dataConnector": {
      "ip": "<ip>:<port number>", // datahub ip and connector port number
      "interval": {
        "statusCheck": 10,        // configurable time interval in seconds
        "batch": 30,              // configurable time interval in seconds
        "stream": 30,             // configurable time interval in seconds
        "agentLog": 10            // configurable time interval in seconds
      }
    },

    "servicesIncluded": [         // service to be run
      "unicornHda", "unicornAe"   // usually you don't need "unicornAe". Hda is for experiment data, Ae is for alerts and events
    ],

    "servicesAvailable": {        // service configuration 
      "unicornHda": {
        "interval": 120,
        "outputFolder": "C:\\Temp\\Unicorn\\HDA",
        "paths": [
          {
            "domainName": "<UNICORN server domain name, used for File Path to avoid name collision if using localhost or 127.0.0.1 as host",
            "host": "<UNICORN server domain name or ip>",
            "progID": "UNICORN_HDAServer12.1",
            "defaultAddress": "\\Default\\Folders\\DefaultHome\\",
            "excludeFolder": [
              "Logbook",
              "System"
            ],
            "metadata": {},
            "tags": ""
          }
        ]
      },
      "unicornAe": {              // <-- usually you don't need this section
        "interval": 30,
        "outputFolder": "C:\\temp\\Unicorn\\AE",
        "archiveFolderAfterUpload": "C:\\temp\\Unicorn\\Archive",
        "paths": [         
          {
            "host": "<UNICORN server domain name or ip>",
            "progID": "UNICORN_AEServer11.System1.1",
            "metadata": {},
            "tags": ""
          }
        ]
      }
    }
  }
}

Install and Start Unicorn Agent

📘

What You Need to Prepare

To ensure a smooth start, please make sure the following OPC Service and UNICORN services are up and running

• OpcEnum
• UNICORN HDA Service
• UNICORN Instrument Server
• UNICORN Support Service

Install the Agent service

The user opens a Window Command Console (Run As Admin), navigates the installation folder (the default is C:\TetraScience\TetraScience.Agent.unicorn.v.2.x.x\Bin

The user can install the Agent by typing the command line as below. The Agent can be run under a specific user account.

Tetrascience.Agent.unicorn.exe Install -username "DOMAIN\Service Account"-password "your password"

If the user account is not specified, Local System account will be used to run the Agent.

The console will display Install has completed message once finished.

User can verify the agent is correctly installed from checking Windows Services (the instance ID will be different for you agent)

Start the Agent

The user can start the Agent by running the command line as below

Tetrascience.Agent.unicorn.exe Start

Stop the Agent

In case, the user needs to stop the Agent, for example, the user needs to modify the configuration file, config.json. The user can run the following command:

Tetrascience.Agent.unicorn.exe Stop

🚧

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.