API ReferenceProduct Documentation
Product Documentation

Tetra LabX Connector

Suggest Edits

The Tetra LabX Connector is a standalone, containerized application that communicates with the Mettler-Toledo LabX system integration service. It monitors the system for new tasks, transfers finished task results to the Tetra Data Platform (TDP), and provides the ability to create new tasks.

Operational Guide

The following procedures show how to install and operate the Tetra LabX Connector.

Install a Tetra LabX Connector

To install a Tetra LabX Connector, do the following.

Prerequisites

The Tetra LabX Connector requires the following.

System Requirements

  • Linux OS
  • Docker installed
  • Outbound network access to TDP v4.0.0 or higher
  • Outbound network access to all LabX instances the Connector will contact

If LabX is running in an on-premises network, the Connector should run either on an on-premises Tetra Hub or as a standalone deployment on an on-premises Linux server.

📘

Network requirements for multiple LabX instances

To use the Connector to contact multiple instances, the host machine for the Connector must be able to access all relevant LabX instances.

LabX Server Requirements

The Tetra LabX Connector requires the following LabX server configuration:

  • LabX software version 10 or higher (v13 or higher recommended)

    🚧

    IMPORTANT

    The Connector uses LabX SDK APIs (BasicIntegrationService and/or SystemIntegrationService) to fetch data from LabX. In LabX v12 and earlier, METTLER TOLEDO acknowledged that the use of the LabX SDK APIs can lead to an increase in CPU and memory consumption. They have since implemented a fix for this in LabX v13. For optimal performance with the Tetra LabX Connector, it is recommended that customers upgrade to LabX v13.

  • Apply LabX "System Integration" license key to allow the Agent to access LabX integration service
  • A valid LabX user account
  • Firewall configured to allow connections (see Configure Firewall Settings)

Configure Firewall Settings

According to Mettler-Toledo's system integration guide, LabX listens on ports 51155, 51156, and 51157 (if HTTPS is used). The server hosting the LabX integration service must allow inbound traffic on these ports to allow the Tetra LabX Connector to reach it. The relevant firewall rules should be introduced as part of the LabX installation. You can confirm that the rules are set by looking at Windows Defender Firewall with Advanced Security > Inbound Rules.

(Optional) Provision a Tetra Hub or Standalone Instance

To set up an on-premises Tetra Hub, see Create and Install a Tetra Hub.

To set up a standalone Connector deployment, see the Standalone Connector Installation and Upgrade Guide in the TetraConnect Hub. For access, see Access the TetraConnect Hub.

For more information about deployment options, see Connector Deployment Options.To learn about TDP networking best practices, see Recommended Architectures for Network Connectivity to Private Cloud and On-Premises Components in the TetraConnect Hub.

Create a Tetra LabX Connector

To create a Tetra LabX Connector, do the following:

  1. Sign in to the TDP. Then, in the left navigation menu, choose Data Sources and select Connectors. The Connectors page appears.
  2. Follow the instructions in Create a Pluggable Connector. For CONNECTOR TYPE, make sure that you select LabX Connector.

📘

NOTE

After the Connector is created, the initial MODE status is set to IDLE by default. To activate the Connector, you must configure its settings. For instructions, see the Configure the Connector section.

Configure the Connector

On the Connectors page, select the name of the Connector that you created. Then, select the Configuration tab to configure the required settings.

Configuration Parameters

The Tetra LabX Connector requires the following configuration parameters.

Polling Configuration

  • Parameter Name: polling_configuration
  • Type: Array of JSON objects
  • Required: Yes

This parameter contains an array of JSON objects, each representing a LabX instance that the Connector will poll.

Each object contains the following fields:

  • base_url (string, required): The base URL of the LabX server (for example, https://labx.example.com)
  • username (string, required): Username for authenticating with the LabX server
  • password (string, required): Password for the LabX user account. For users without a password, use an empty string "" The password must be specifed as an organizational shared secret. The secret should be referenced in the configuration file as a JSON object with the following fields:
    • secret: A boolean value; always true
    • ssm: A string value representing the name of the secret in AWS (for example, "prod/{{ org_slug }}/org-secrets/{{ secret_name }}")
  • computer_name (string, required): Name of the computer hosting the LabX server
  • timezone (string, required): Time zone for the LabX instance. This can be either an Internet Assigned Numbers Authority (IANA) time zone name (for example, America/New_York) or a Windows time zone name (for example, Eastern Standard Time). See the Time Zone Configuration section for instructions on determining the Windows time zone name for the LabX host.
  • descriptive_name (string, recommended): User-friendly name for the LabX instance, which is used in file paths and logging. While optional, this is field is recommended.
  • destination_id (UUID, optional): If provided, this UUID replaces the Connector ID in file paths for task results written by the Connector.

Example Polling Configuration:

{
  "polling_configuration": [
    {
      "base_url": "https://labx-server1.example.com",
      "username": "labx_user",
      "password": {
        "secret": true,
        "ssm": "prod/tetrascience-documentation/org-secrets/labx-server-01-password"
      },
      "computer_name": "LABX-SERVER-01",
      "timezone": "America/New_York",
      "descriptive_name": "Main Lab LabX Instance"
    },
    {
      "base_url": "https://labx-server2.example.com",
      "username": "labx_user2",
      "password": {
        "secret": true,
        "ssm": "prod/tetrascience-documentation/org-secrets/labx-server-02-password"
      },
      "computer_name": "LABX-SERVER-02",
      "timezone": "Pacific Standard Time",
      "descriptive_name": "QC Lab LabX Instance"
    }
  ]
}

Time Zone Configuration

The timezone field in each LabX instance configuration is critical for proper timestamp handling. The Connector supports both IANA time zone names and Windows time zone names:

  • IANA time zone name examples: UTC, America/New_York, Europe/London, Asia/Tokyo
  • Windows time zone name examples: Eastern Standard Time, Pacific Standard Time, Central European Standard Time

Internally, the Connector uses IANA time zones. If the Connector recognizes the provided time zone as IANA, it will use that. Otherwise, it will check a lookup table to convert Windows time zones to IANA equivalents.

🚧

IMPORTANT

If the time zone of your LabX instance changes, you must update the Connector configuration to prevent timestamp mismatches.

📘

Finding Windows Time Zone Names

To find the correct Windows time zone name for your LabX host, run the following PowerShell command on the Windows machine hosting LabX:

Get-TimeZone

The response displays the current time zone information, including the Id field, which should be used as the timezone value in your Connector configuration.

Polling Interval

The interval in minutes between polling cycles. The Connector will check all configured LabX instances for new or updated tasks at this interval.

  • Parameter Name: polling_interval
  • Type: Number (integer)
  • Required: Yes
  • Minimum Value: 1

LabX Timeout

The timeout in seconds for HTTP requests made to LabX instances. If not specified, the default timeout of 15 seconds will be used.

  • Parameter Name: labx_timeout
  • Type: Number (integer)
  • Required: No
  • Default: 15 seconds
  • Range: 1-120 seconds

Review and Edit the Connector's Information

The Information tab on the Connector Details page displays information about the Connector, the files pending, successfully uploaded, or failed. It also provides functionality to edit a Connector’s information, metadata, and tags.

To edit the Connector's information, select the Edit button on the Connector Details page's Information tab.

For more information, see Review and Edit a Pluggable Connector's Information.

Set the Connector's Status to Running

Set the Connector's status to Running by following the instructions in Change a Pluggable Connector's Status.

Metrics

After a Connector instance is created and running, you can monitor the Connector’s health by selecting the Metrics tab on the Connector Details page. The Metrics tab displays the Connector's container metrics as well as aggregated states on total files scanned and uploaded as well as files that returned errors or are pending.

Access Data

Using the polling interval set in configuration, the Connector periodically queries LabX to find any tasks created since the last poll. The Connector then marks these tasks in its internal data store as pending upload. These will be visible from the Connector's page as files with status PENDING. During each polling interval, the Connector reviews its list of known tasks that haven't yet been uploaded. For each of these tasks, it queries LabX to see if the task is ready for upload. A task is marked ready for upload when its state in LabX is either Completed or Aborted.

Custom Commands

The Tetra LabX Connector supports several custom commands that can be sent through the TDP Command Service. These commands allow you to interact with LabX instances programmatically.

Create Task From Samples

Action: TetraScience.Connector.LabX.CreateTaskFromSamples.v1

This command creates a new task in LabX with the specified samples and method parameters.

Required Payload Fields

  • computer_name (string): Computer name where LabX is running (this must match a computer_name in the polling configuration)
  • instrument_name (string): Name of the instrument in LabX
  • method_name (string): Name of the method in LabX
  • run_name (string): Name for the run series
  • samples (array): List of sample objects (minimum 1 sample required)

Optional Payload Fields

  • scope_name (string): Scope name for the samples (defaults to "SampleScope1")
  • task_name (string): Custom task name (autogenerated if omitted)
  • method_parameters (array): Method parameters for the task

Sample Object Structure

Each sample in the samples array contains the following:

  • name (string): Sample name
  • type (string): Sample type (must be one of: "standard", "control", "reference")
  • SampleId1 through SampleId6 (string, optional): Sample identifiers

Method Parameter Structure:

Each method parameter in the method_parameters array contains the following:

  • function_name (string): Name of the method function
  • function_property_name (string): Name of the function property
  • value (string): Parameter value

Example Payload:

{
  "computer_name": "LABX-SERVER-01",
  "instrument_name": "XPE4002S_local",
  "method_name": "Simple Weighing",
  "run_name": "test_run_001",
  "scope_name": "SampleScope1",
  "task_name": "automated_task_001",
  "method_parameters": [
    {
      "function_name": "HandleAveraging",
      "function_property_name": "DefaultText",
      "value": "On"
    },
    {
      "function_name": "DisplayedUnit",
      "function_property_name": "DefaultText",
      "value": "g"
    }
  ],
  "samples": [
    {
      "name": "sample_001",
      "type": "standard",
      "SampleId1": "sample_001_id1",
      "SampleId2": "sample_001_id2"
    },
    {
      "name": "sample_002",
      "type": "standard",
      "SampleId1": "sample_002_id1",
      "SampleId2": "sample_002_id2"
    }
  ]
}

Manual Upload

Action: TetraScience.Connector.LabX.ManualUpload.v1

This command triggers a manual search for tasks from all configured LabX instances within a specified time range. Any task which has been previously detected is ignored. Previously unseen tasks are added to the Connector's data store and marked as PENDING.

Required Payload Fields

  • start_date (string): Start date in ISO format (e.g., "2023-01-01T12:00:00") and UTC time
  • end_date (string): End date in ISO format (e.g., "2023-01-01T18:00:00") and UTC time

Example Payload

{
  "start_date": "2023-01-01T12:00:00",
  "end_date": "2023-01-01T18:00:00"
}

Get Released Methods

Action: TetraScience.Connector.LabX.GetReleasedMethods.v1

This command retrieves released methods from a specific LabX instance, with optional filtering by comment content.

Required Payload Fields (one of the following)

  • computer_name (string): Computer name of the LabX instance
  • descriptive_name (string): Descriptive name of the LabX instance

Optional Payload Fields:

  • comment (string): Filter methods by comment content (returns only methods whose Comment field contains this substring)

Example Payload:

{
  "descriptive_name": "Main Lab LabX Instance",
  "comment": "Linear"
}

Limitations

The LabX API does not provide a way to determine the timezone of the LabX instance. Because of this, customers must choose the time zone for each connected LabX instance when configuring the Connector on the TDP. If the time zone of the instance changes, there may be a mismatch between the Connector and the LabX instance, which can result in data affixed with incorrect time zones.

If the Connector is using destination_id and retrieves a task previously gotten by a Tetra LabX Agent (for example, if you are using the manual upload feature and request data previously seen by the Agent) the labels usually applied by the Connector will be absent. The label information is also stored in the trace section of the file

Updated about 15 hours ago