Tetra Chromeleon Agent Installation and Configuration (Version 2.x)

📘

Upgrades

To learn more about Tetra Agent upgrade best practices, see Common Tetra Agent Upgrade and Installation Information.

This guide shows how IT Administrators can install and configure Tetra Chromeleon Agent versions 2.x.

To set up the Tetra Chromeleon Agent, you must do the following:

1. Select and set up a data connection
2. Install the Tetra Chromeleon Agent
3. Configure the Tetra Chromeleon Agent
4. Select the Data Vault
5. Monitor Tetra Chromeleon Agent progress and server system metrics

For instructions, see the procedures in each of the following sections.

📘

NOTE

To restrict access to the local Tetra Agent Management Console, you can edit the Agent’s installation folder’s permissions to grant least privilege access. For more information, see Restrict Access to Agent Installation.

Prerequisites

Make sure that your local environment meets the requirements listed in Supported Chromeleon Versions on the Tetra Chromeleon Agent page.

Step 1: Set Up a Data Connection

The Tetra Chromeleon Agent generates RAW files that are then uploaded to the Tetra Data Platform (TDP) through one of two methods:

• Generic Data Connector (GDC)
  -or-
• TDP (No Connector)

Before you install the Tetra Chromeleon Agent, you must set up one of these data connections. To determine which data connector is required for your use case, see Tetra Agent Integration and Connectors (For TDP Versions 3.4 and Higher).

📘

NOTE

The Cloud Data Connector (CDC) was deprecated and replaced with the TDP (No Connector) data connection in TDP version 3.4.0. For more information, see Cloud Data Connector Deprecation.

Step 2: Install the Tetra Chromeleon Agent

TetraScience provides a Microsoft Installation Package (.msi) file to install the Tetra Chromeleon Agent on the host server.

To get the installation package and install the Agent, do the following:

1. Get the link to the .msi installation package by contacting your TetraScience Customer Success Manager (CSM).
2. After you have the link to the installation package, download the Agent to a machine that runs a supported version of Thermo Fisher Chromeleon.

🚧

IMPORTANT

To access the server and run the installation package, you must sign in as an Administrator.

3. Start the installation wizard by double-clicking the Tetra Agent installation file. The installation wizard guides you through the prompts. The following is the default Tetra Chromeleon Agent installation path: C:\Tetrascience\Tetrascience.Agent.Chromeleon.v2.x.x
4. After the Tetra Chromeleon Agent is installed, open the TetraScience folder within Windows Programs. Then choose TetraScience Agent Chromeleon to open the Agent Management Console.

Step 3: Configure the Tetra Chromeleon Agent

To configure the Tetra Chromeleon Agent after it is installed on the host server, do the following:

1. In the Agent Management Console, select the hamburger menu icon in the left navigation pane. Then, choose Configuration. The Agent configuration page opens.

2. Configure the Agent by filling out the fields in the following sections on the Agent Configuration page:
   • (1) Agent Status
   • (2) Windows Task Scheduler
   • (3) Agent Configuration
   • (4) Agent Group User
   • (5) Service Settings

📘

NOTE

Chromeleon stores the time stamps as Coordinated Universal Time (UTC). However, the date notation is displayed according to regional settings made in the operating system. The regional time is dependent on the time settings of the computer the time was acquired on.

Chromeleon generally displays time in the regional time plus the offset to the UTC. The UTC is a common time standard used across the world and is independent of location and daylight saving time.

For example, India Standard Time (IST) is UTC+5:30, which means the offset to the universal coordinated time is +5:30 hours. For 17:00:00 IST, Chromeleon would then display 17:00:00 +5:30.

Configure the Agent Status

The Agent Status section indicates the current state of the Agent's processing status, which can be any of the following:

• Agent Service Not Installed
• Stopped
• Running

To save, start, or stop the Agent, do the following:

• To save the Agent configuration, choose Save.
• To start the Agent after configuring new settings, choose Start. When the Agent starts, the status indicator shows Running.
• To stop a running Agent, choose Stop. The Stop button can be selected only if the Agent is running.

Automate Status Checks by Using Windows Task Scheduler

To avoid needing to check the Agent’s service status manually, it’s recommended that you create a Windows task to perform daily status checks.

To create a Windows task, do the following:

1. Under Windows Scheduled Task to check Agent Service Status, choose Yes.
2. For Run Time, enter the time that you want the status check to run each day. If the Agent is stopped, then the scheduled Windows task restarts the Agent service automatically. If the Agent is running, it continues to run, and the Windows task will run at the time you selected.

📘

NOTE

If you manually stop the Agent, the task is removed from Windows Task Scheduler. When you run the Agent on a local system (with no group user), the task runs under the LocalSystem account.

Set Up the Agent Configuration

📘

NOTE

Make sure that you’ve set up a data connection (see Step 1: Set up a Data Connection) before completing the following procedure. You will need the Agent ID and Connection URL that you created during the data connection setup.

To set up the Agent configuration, enter the following information in the Agent Configuration section:

1. For Agent Id, enter the Agent’s ID. The Agent ID is a Universal Unique Identifier (UUID) value that’s used to connect the Agent to the TDP. To find your Agent ID, do the following:
   • Sign in to the TDP. Then, select the hamburger menu icon in the left navigation pane.
   • Choose Data Sources. Then, choose Agents. The Agents page opens.
   • In the AGENT column, find the name of the Agent that you’re configuring. The Agent ID is listed below the Agent name.
2. For Connection Url, enter the complete connection URL of the Connector or integration type that you’re using. For example URLs, see Connection URL.

🚧

IMPORTANT

• Agent ID is required.
• The connection URL is required only if you're uploading RAW files to the TDP.
• Before you use your Agent ID and connection URL, it’s strongly recommended that you verify both with your TetraScience Customer Success Team.

3. (Optional) To have the Agent upload files directly to your Amazon Simple Storage Service (Amazon S3) bucket, set the S3 Direct Upload option to Yes. If you choose this option, keep in mind the following:
   • When you activate S3 Direct Upload, you can upload a maximum file size of one terabyte.
   • If you use the S3 Direct Upload option with a GDC, you must add an L7 Proxy Connector in the same Data Hub where you set up the GDC. The port of the L7 Proxy Connector must also be open. For more information, see Generic Data Connector (GDC).

📘

SQLite Database File Backups

To configure the Tetra Chromeleon Agent to automatically perform regular backups of the SQLite database file, set the S3 Direct Upload option to Yes. When you activate S3 Direct Upload, the SQLite database file (which stores Agent configuration data) is uploaded to the backup bucket in the Tetra Data Lake. If an Agent failure occurs, you can restore the database file from the backup bucket and continue processing.

If you don't use the S3 Direct Upload option, it’s recommended that you create periodic backups of the Agent database. The Tetra Chromeleon Agent database is 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 setup allows the data extraction to continue from where it left off, without needing to re-upload all of the Agent’s data.

4. (Optional) To allow the Agent to securely receive and run commands from the TDP, set the Enable Queue option to Yes. If you choose this option, keep in mind the following:
   • When you activate the Enable Queue option, the Agent proactively polls the Amazon Simple Queue Service (Amazon SQS) messages sent from the TDP. The Agent then identifies messages that contain command requests and determines whether it should run the command or not.
   • For Tetra Chromeleon Agent v1.2.0 and higher, the Agent can receive the Sequence Creation Command only.

📘

TDP Commands and Queue Security

Amazon SQS queues allow the TDP to send commands to the Tetra Agent while keeping the command request process secured in the following ways:

• The TDP doesn't send the Agent actual commands. The TDP sends Amazon SQS messages that request commands to be run locally.
• Each Tetra Agent has its own Amazon SQS queue to receive messages from the TDP. Queues aren’t shared between agents.
• The Tetra Chromeleon Agent can run only a specific set of pre-built commands. As of Tetra Chromeleon Agent v1.2.0, the Agent can only execute the Sequence Creation Command.

5. (Optional) To configure additional Agent settings, choose Advanced Settings. The Agent Configuration Advanced Settings dialog appears and displays the following configuration options:
   • Data Connection status check every: Indicates how often the software checks the status of the connection (heartbeat) between the TDP and the Agent. If the TDP doesn't receive a heartbeat message for more than five minutes, the platform assumes that the Agent is offline.
   • File Upload Job runs every: Indicates how often the Agent uploads files to the Tetra Data Lake.
   • Agent log files upload every: Indicates how often the Agent uploads log files to the Data Lake.

📘

NOTE

The default value for all Agent Configuration Advanced Settings is 30 seconds.

6. (For “TDP (No Connector)” setups only) If you’re using an Agent without a Connector, make sure that you do the following:
   • For Org Slug, enter your organizational slug. To get your organizational slug, see Viewing Organization Details. The organizational slug is required when using a JSON Web Token (JWT). Adding the slug to this field attaches it to the Agent’s API request headers.
   • For Authorization, select Add/Edit. Then, enter your JWT in the dialog that appears. To get a JWT, see Generate a JSON Web Token for an Existing Service User. Then, choose Save to encrypt and save the JWT. The Agent validates the connection immediately and displays the updated connection status next to the Connection Url field.

📘

NOTE

Authorization, Bearer is optional. If you don't provide it, then the Agent adds it automatically.

Configure the Agent Group User

The Agent Group User is the service account that runs the Tetra Chromeleon Agent. To configure the Agent Group User, do the following:

1. In the Agent Group User section, for User Name, enter the Chromeleon group user name.
2. For Password, enter the Chromeleon group password. The Agent then validates the account. If the user name and password are correct, the Agent displays a Valid status in the console.

📘

NOTE

If you're having trouble signing in with your Chromeleon user account, try adding .\ at the front of your user name. For example, if your user name is Tetra, try using .\Tetra.

Configure Agent Service Settings

To configure the Agent's service settings, enter the following information in the Service Settings section:

1. For Processing Interval (Seconds), enter how often the Agent should run the injection extract task. The extract task includes scanning Chromeleon to detect new or modified injections and the generation of the RAW injection file.
2. For Injection Service Output Folder, enter the name of the folder where you want to temporarily store the generated RAW files. After the files are uploaded to the TDP, the RAW files are deleted from the temporary folder to save disk space.
3. (Optional) For Ignore Recycle Bin, check the box to skip the generation of any deleted injections in data vaults. This setting is available in Tetra Chromeleon Agent v2.0.1 and higher.
4. (Optional) For Decode Injection URL, check the box to escape URL encoding in the injection path created in Amazon S3. This setting is available in Tetra Chromeleon Agent v2.0.2 and higher.

🚧

IMPORTANT

If you're upgrading from a previous version of the Tetra Chromeleon Agent, selecting the Decode Injection URL option can result in new RAW JSON files for changed injections in the new Amazon S3 path. For more information, see What is the impact of changing the Decode Injection URL setting in Agent UI?

5. For Sequence Scan Batch Size and Injection Generation Batch Size, enter the batch sizes that you want the Agent to use when querying data through the Chromeleon SDK. The batch sizes that you choose need to balance the application’s footprint and overall throughput. The number can be adjusted based on the data type. Injections with 3D data fields will generate large RAW JSON files. These two settings are available in Tetra Chromeleon Agent v2.0.3 and higher.
6. (For when Chromeleon User Mode is activated only) For User Name, Password, and Role, enter the credentials of a Chromeleon local user or a Lightweight Directory Access Protocol (LDAP) authenticated user. This configuration allows the Agent to access Chromeleon through a specific user account. The credentials you enter must be for a valid Chromeleon user account. A busy indicator appears while the user account is being verified. You can’t start the Agent until the Chromeleon user account is verified.

🚧

IMPORTANT

If Chromeleon User Mode is activated, User Name, Password, and Role are required fields. The Agent validates the account before the Agent starts.

If Chromeleon User Mode is turned off, the User Name, Password, and Role fields are deactivated in the console.

Step 4: Select the Data Vault

The Tetra Chromeleon Agent can access all of the Data Vaults that the configured Chromeleon user has permission to access. Instead of generating the injections from all of the Data Vaults, you can select individual ones from the Data Vault list.

To select individual Data Vaults to scan and extract injections from, do the following:

1. In the Agent Management Console, verify that the Tetra Chromeleon Agent has been started and shows a Running status.
2. In the left navigation pane, choose Data Vault. A list of available Data Vaults appears. The Data Vaults are grouped by their Chromeleon Data Servers, which are listed in the Server Name column.

📘

NOTE

The Server Name column is available in Tetra Chromeleon Agent v2.0.3 and higher. In Tetra Chromeleon Agent v2.0.0 to v2.0.2, you can select individual Data Vaults only.

When selecting Data Vaults, keep in mind the following:

• You can select Data Vaults only when their associated Data Server is activated.
• If a Data Server or a Data Vault is unchecked when the Agent is running, the Agent will postpone the pending injection generations that belong to those Data Vaults.

Step 5: Monitor Tetra Chromeleon Agent Progress and Server System Metrics

View the Agent’s Summary Dashboard

To review the Tetra Chromeleon Agent's run time progress and host server's system metrics, do the following:

1. Open the Agent Management Console.
2. In the left navigation pane, choose Summary. The Summary dashboard opens.

Summary Dashboard Contents

Processing Summary

The Processing Summary section shows the following information:

• Total Scanned: Number of files scanned by the Agent.
• Total Generated: Number of files generated.
• Failed to Generate: Number of files that failed to generate.
• Pending To Generate: When the Agent stops, the Pending To Generate state is reset to 0. Any file that was not completely generated is removed from the Agent's database and resets the counter. When the Agent restarts, it calculates how many files it needs to generate and starts from the beginning, rather than resuming from where the file generation left off.
• Pending For Upload: When the Tetra Chromeleon Agent stops, the Pending For Upload state is reset to 0. Any file that wasn't completely uploaded is removed from the Agent's database and resets the counter. When the Agent restarts, it calculates how many files it needs to upload and starts from the beginning, rather than resuming from where the file upload left off.
• Uploaded: Number of files that have been uploaded to the Agent successfully.
• Failed To Upload: Number of files that failed to upload to the Agent.

Error Messages

The Error Messages section displays detailed error messages for any errors that occur.

System Messages

The System Messages section displays the following host server system metrics and messages, which are updated every minute:

• Data Connection (connection status between the Agent and the Tetra Data Platform)
• Available Disk Space (in GB)
• Disk Usage (as a percent of the total)
• CPU Usage (as a percent of the total)
• Memory Usage (in MB)
• Available Memory (in MB)

View Chromeleon Cultural Settings

To see Chromeleon cultural settings that are set on the host server, such as decimal or dot symbols, date formatting, and negative number formatting, do the following:

1. Open the RAW JSON file for the injection in the TDP.
2. Find the "AgentContext" and "AgentHostServer" sections. The Chromeleon Cultural settings are listed here.

Example Chromeleon Cultural Settings as They Appear in a RAW JSON File

{
"RawJsonSchemaVersion": "v2",
    "AgentVersion":"v2.0.0",
    "AgentContext": {
        "AgentHostServer": {
            "CultureInfo": "en-US",
            "ShortDate": "M/d/yyyy",
            "LongDate": "dddd, MMMM d, yyyy",
            "ShortTime": "h:mm tt",
            "LongTime": "h:mm:ss tt",
            "DecimalSymbol": ".",
            "DigitGroupingSymbol": ",",
            "NegativeSignSymbol": "-",
            "NegativeNumberFormat": "LeadingNegativeWithNoSpace"
            }
      }
    ...
  }

"NegativeNumberFormat" Patterns