Tetra Chromeleon Agent Installation and Configuration (Version 2.0.2)

πŸ“˜

Upgrade

For information on upgrading Tetra Agents, see this topic: https://developers.tetrascience.com/docs/upgrade.

This guide describes how an IT Administrator can install and configure the Tetra Chromeleon Agent (version 2.0.2). It describes how to:

  • Select and set up a data connection
  • Install the Tetra Chromeleon Agent
  • Configure the Tetra Chromeleon Agent
  • Select the Data Vault
  • Monitor Tetra Chromeleon Agent progress and server system metrics

πŸ“˜

Agent Requirements

Before you begin, ensure that your environment meets the prerequisites listed here.

Select and Set Up Data Connection

The Tetra Chromeleon Agent generates RAW files which are uploaded to the Tetra Data Platform (TDP) through a Data Connector.

To enable secure file transfers, TetraScience provides two available data connectors:

Before you install the Tetra Chromeleon Agent, you must set up one of these data connectors. To determine which data connector to select, click this link for details.

Install the Tetra Chromeleon Agent

TetraScience provides a Microsoft Installation Package (.msi) file to install the Chromeleon Agent in the host server. To access the server and run the installation package, you must log in as an Administrator.

  1. To obtain the link to the .msi installation package, please contact your TetraScience Customer Success Manager (CSM).
  2. Once you have the link, download the Tetra Chromeleon Agent to a machine
    that runs a supported version of Thermo Fisher Chromeleon.
  3. Double-click the Tetra Agent installation file to start the installation wizard. The installation wizard guides you through the prompts. The default Tetra Chromeleon Agent installation path is: C:\Tetrascience\Tetrascience.Agent.Chromeleon.v2.x.x.
  4. After the Tetra Chromeleon Agent is successfully installed on the server, you can access its Windows-based Management Console under the TetraScience folder from the Windows Programs. Select TetraScience Agent Chromeleon from the Windows Programs list to open the Agent.
288288

Tetra Chromeleon Agent path

Configure the Tetra Chromeleon Agent

After you have successfully installed the Tetra Chromeleon Agent, use the Windows-based Management Console to continue the Agent configuration.

11471147

Click Configuration from the menu on the left. The Management Console is divided into five sections:

  • Agent Status
  • Windows Task Scheduler
  • Agent Configuration
  • Agent Group User
  • Service Settings

πŸ“˜

NOTE

Chromeleon stores the time stamps as universal time (Greenwich time). However, the date notation is displayed according to regional settings made in the operating system.

Chromeleon generally displays time in the regional time plus the offset to the coordinated universal time (UTC). The coordinated universal time is the time standard commonly used across the world and is independent of location and daylight saving time. The regional time is dependent on the time settings of the computer the time was acquired on.

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

Section 1: Agent Status

This section indicates the current state of the Agent's processing status:

  • Agent Service Not Installed
  • Stopped
  • Running

Here is how to save, start, and stop the Agent.

  • To save the Tetra Chromeleon Agent configuration, click Save.
  • To start the Tetra Chromeleon Agent with the new configuration settings, click Start. When the Tetra Chromeleon Agent starts, the status indicator shows Running for an Agent that is successfully up and running.
630630

Agent Running Status

  • When the Tetra Chromeleon Agent starts, the Stop button is enabled. To stop the Tetra Chromeleon Agent, click Stop.

Section 2: Windows Task Scheduler

You can increase the Agent's reliability by ensuring that it remains online without having to manually check it each day.

598598

Windows Task Scheduler

If you enable this option, the Agent creates a Windows Task that checks the status of the Agent's service daily at the run time you specify. Enter the time in the Run Time field.

  • 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 Agent, then the Windows task is removed, and the Windows Task that you create runs under the LocalSystem account.

Section 3: Agent Configuration

Use this section to configure the Agent connection to the Tetra Data Platform. TetraScience provides several options to connect the Tetra Data Platform. Click this link to select the best option for your company's needs.

910910

Agent Configuration Section

S3 Direct Upload

To have the Tetra Chromeleon 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 one 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 CDC, see this link.

Enable Queue

To enable the Agent to receive commands from the Tetra Data Platform, set the Enable Queue option to Yes. When you set this option to Yes, the Agent keeps polling the queue messages sent from the Tetra Data Platform. The messages provides instructions to the Agent. In version 1.2.0, only the Sequence Creation Command can be received. No is the default setting.

πŸ“˜

TDP Commands and Queue Security

Although queues enable TDP to send commands to the Tetra Agent, the command execution request process is secured.

  • TDP does not send actual commands, but rather messages that request commands for execution.
  • The Tetra Agent has its own queue to receive messages from TDP and is not shared by any other agent.
  • When queues are enabled, the Tetra Agent proactively reads the queue for messages containing command execution requests and determines whether to initiate the command execution. You can control whether to enable local command execution by toggling the Enable Queue option for the Tetra Agent.
  • The Tetra Chromeleon Agent can only execute certain a limit set of pre-built commands. As of version 1.2.0, the Tetra Chromeleon Agent can only execute the Sequence Creation Command.

For more information on how to initiate the Sequence Creation Command, see this topic.

Advanced Settings

Click Advanced Settings to open the Agent Configuration Advanced Settings pane.

481481

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 Agent. If the Tetra Data Platform does not receive a message indicating that the 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 Lake.
  • Agent log files upload every - Indicates how often to upload log files to the Tetra Lake.

πŸ“˜

SQLite Database File Backups

To enable the Tetra Chromeleon 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 Chromeleon 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 Chromeleon 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 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.
  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.

πŸ“˜

Note

Authorization, Bearer is optional. If you do not provide it, then the Tetra Chromeleon Agent adds it automatically.

Section 4: Agent Group User

The Agent Group User is the service account that runs the Tetra Chromeleon Agent.

913913

Agent Group User

πŸ“˜

Group user tip

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

When you enter the Chromeleon Group User Name and Password, the Agent validates the account. If the user name and password are correct, then the Tetra Chromeleon Agent displays a Valid status next to the field.

Section 5: Service Settings

Use this section to configure the Tetra Chromeleon Agent's settings at run time. You'll also use this section to enter the user name, password, and role for Chromeleon (local or LDAP authenticated Chromeleon users) when User Mode is enabled in Chromeleon.

896896

Service Settings

  1. Set the Processing Interval (Seconds) field to indicate how often the Tetra Chromeleon Agent runs the Injection extract task in the specified time interval. The extract task includes scanning Chromeleon to detect new or modified injections, and the generation of the RAW injection file.
  2. Select the Injection Service Output Folder to where you want to temporarily store the generated RAW file. After the files have been uploaded to the Tetra Data Platform successfully, the RAW file is deleted from the temporary folder to save disk space.
  3. Check the Ignore Recycle Bin box to skip the generation of any deleted injections in data vaults.
  4. Check the Decode Injection URL box to escape URL encoding in the injection path created in S3. If you are upgrading from a previous version of the agent, this may result in new RAW JSON files for changed injections in new S3 path. To know more, please read here before enabling this feature.
  5. Enter information in the User Name, Password, and Role fields so that the Tetra Agent can access Chromeleon based on a specific user account. You can enter information here about a Chromeleon local user or an LDAP authenticated user. The User Name and Password must be for a valid Chromeleon user account. A busy indicator appears while the user account is being verified. You will not be able to Start the agent until the account is verified.

If Chromeleon User Mode is enabled, User Name, Password, and Role are mandatory. The Agent validates the account before the Agent starts.

If Chromeleon User Mode is disabled, the User Name, Password, and Role fields will be disabled too. An additional message is also displayed.

Set the Data Vault

The Tetra Chromeleon Agent can access all of the Data Vaults that the 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:

  1. From the Management Console, verify that the Tetra Chromeleon Agent has been started and has a status of Running.
  2. Select Data Vault from the left of the Management Console to open the Data Vault dialog. The Data Vault list takes a minute or two to populate.
704704

Data Vault

  1. Select the Data Vaults from which you want the Tetra Chromeleon Agent to extract injections.

Processing Summary

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

  1. Select Summary from the left of the Management Console to open the Summary dashboard:
910910

Summary Dashboard

From the summary page, you can review see how many total injections have been scanned in a given Data Vault, and how many injections have been generated and uploaded. If any failure occurs, the numbers display here. If there are any errors, the error message, and related injection URL displays on the right.

In addition to the Injection processing summary, the Agent includes system metrics on the host server as well. That information is uploaded to the Tetra Data Platform.

The Processing Summary dashboard displays this 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 - A pending state. When the Tetra Chromeleon Agent stops, the Pending To Generate state is reset to zero. Any file that was not completely generated is removed from the Tetra Chromeleon Agent's database and resets the counter. When the Tetra Chromeleon Agent restarts, it calculates how many files it needs to generate and starts from the beginning instead of resuming from where the file generation left off.
  • Pending For Upload - A pending state. When the Tetra Chromeleon Agent stops, the Pending For Upload state is reset to zero. Any file that was not completely uploaded is removed from the Tetra Chromeleon Agent's database and resets the counter. When the Tetra Chromeleon Agent restarts, it calculates how many files it needs to upload and starts from the beginning instead of 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

This section displays any detailed error messages.

System Messages

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)
  • Available Memory (in MB)

Cultural Settings

Chromeleon cultural settings, such as decimals or dots for numbers date format and length, as well as the negative number formats are set on the Chromeleon Host Server machine in the Windows OS. The Tetra Chromeleon Agent captures this information in RAW JSON file for each injection in the Agent Context, Agent Host Server sections of file. Here is an example:

{
"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"
            }
      }
    ...
  }

The Negative Number Format indicates how negative numbers are formatted. See the following table for details.

RAW JSON NameAssociated Pattern
0 - Parenthesisβ€œ(n)”
1 - LeadingNegativeWithNoSpaceβ€œ-n”
2 - LeadingNegativeWithSpaceβ€œ- n”
3 - TrailingNegativeWithNoSpaceβ€œn-”
4 - TrailingNegativeWithSpaceβ€œn -”