Tetra SDC Connector v2

The Tetra SDC Connector (SDCC) v2 is a standalone, containerized application that enables bi-directional communication between the Tetra Data Platform (TDP) and AGU Sm@rtLine Data Cockpit (SDC). SDC is a middleware that captures measurements from sensors and analyzers and exports them through REST API export interfaces. Users can configure the Connector to periodically poll export interfaces for sample and measurement results. The Connector also allows integrating systems to submit measurement order requests to SDC through the TDP Command Service.

Prerequisites

  • AGU SDC version 3.0 or higher
  • (Optional) Tetra Hub v2. The SDCC v2 can be deployed as a standalone service on the AWS Cloud or to a Tetra Hub v2 (for on-premises networking requirements). If deployed to a Tetra Hub v2, internal networking/firewalls rules to allow communication between SDCC and the Hub must be configured. For more information, contact your customer success manager (CSM).

Design Overview

AGU SDC exports measurements and sample results through REST API export interfaces. The Tetra SDC Connector (SDCC) v2 periodically polls these interfaces for available results, and then uploads them to the TDP. Data ingestion capabilities were expanded from SDCC v1 to support the upload of both measurement and sample results. Measurement orders can also now be submitted to SDC programmatically through TDP Command Service.

Architecture

The following diagram shows an example SDCC v2 architecture:

SDC Connector V2 Architecture

SDC Connector V2 Architecture

Dataflow Example

The following diagram shows an example SDCC v2 dataflow:

SDC Connector V2 Architecture

SDC Connector V2 Dataflow

Operational Guide

To set up an SDCC v2, do the following.

Configure the SDC Export Interface

To configure export interface(s) in AGU SDC where the Connector will poll to obtain measurements or sample results, do the following:

  1. Sign in to AGU SDC. Then, open the Export Interfaces page by doing the following:
    • In the left navigation menu, select the hamburger menu icon.
    • Choose Settings. Then, choose Interfaces.
    • Select the Export Interfaces icon.
SDC Connector V2 Architecture
  1. Select the New button. The Create export interface workflow appears.
SDC Connector V2 Architecture
  1. Define the export interface by doing the following:
    • For Description, enter a name for the export interface (for example, Exports-to-TDP)
    • For Export type, select RestPdf.
    • For Event type, choose whether the interface exports measurement results (Measurement) or sample results (SampleResult).
    • Choose Save. The Export Interface Exports-to- workflow appears.
  2. Edit your export interface to match the following Common configurations:
SDC Connector V2 Architecture
  • For Active, select the check box.

📘

NOTE

Active interfaces add data to the queue. Inactive interfaces do not add data to the queue. However, inactivating a queue doesn't delete results from the queue; it only prevents new results from being added.

  • For All parameters, select the check box.

📘

NOTE

Selecting All parameters is required for proper file versioning in the TDP. If the All parameters check box isn't selected , then the exports will create partial files in the TDP, where each file contains a fraction of all results.

  • (Optional) For Diagnostics, select the check box. This option isn't required, but is helpful for troubleshooting purposes.
  1. Configure your export interface to export data from specific divisions in the Division assignment configurations.
SDC Connector V2 Architecture
  1. Configure your export interface to export data from a specific instrument make and model in the Device type assignment configurations.

🚧

IMPORTANT

AGU SDC can't export data from a specific instrument ID. All instruments of a specific make and model export together.

SDC Connector V2 Architecture

Create a Tetra SDC Connector v2

  1. Sign in to the TDP. Then, in the left navigation menu, choose Data Sources and select Connectors. The Connectors page appears.
  2. Choose Create Connector. The Create Connector page opens.
Connectors landing page

Connectors landing page

  1. For NAME, enter a name for the connector, such as Test SDC Connector. This field is required
  2. (Optional) For DESCRIPTION, enter a description of the Connector.
  3. For HUB OR CLOUD, select the deployment mode (Hub or Cloud) from the drop-down list.

📘

NOTE

If you select Hub for the deployment mode, an SDC Connector container is deployed in the selected Tetra Hub v2. If you select Cloud, a standalone instance running the SDC Connector is deployed.

  1. For CONNECTOR TYPE, select common AGU SDC from the drop-down list.
  2. For CONNECTOR VERSION, select the latest version available.
  3. Choose Create. After a few seconds, the Connector instance is created and appears online.
Create Connector page

Create Connector page

📘

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.

Connector Details page: Configuration tab

Connector Details page: Configuration tab

Configuration Parameters

The following tables lists the configuration parameters that are required for the Tetra SDC Connector (SDCC) v2.

Configuration ParameterDescription
SDC URLURL for the SDC server including protocol, hostname and port. If port is not specified, the default port for protocol will be used (for example, https://yoursdcserver.com:8080)
UsernameUsername of the SDC user with permissions to create measurement orders and request data from an export interface.
PasswordPassword for the user.
Client IDIf provided, the Connector will use it for OAuth 2.0 authentication
Client SecretIf provided, the Connector will use it for OAuth 2.0 authentication
Measurement Result Export Interface IDsComma-separated list of SDC Measurement Result Export Interface IDs to poll (for example, 2, 4)
Sample Result Export Interface IDsComma-separated list of SDC Sample Result Export Interface IDs to poll (for example, 1, 3)
Polling IntervalInterval, in minutes, of how often data will be uploaded to the TDP. The minimum value is 1 minute. The default value is 10 minutes.
Max Results per IntervalMaximum number of results to upload per polling interval. If not specified, no limit is enforced.
Disable SSL Certificate VerificationIf checked, SSL/TLS certificate verification is deactivated. The default value is false.

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.

Connector Details page: Information tab

Connector Details page: Information tab

Connector Details

The following table provides the Connector details available on the Information tab on the Connector Details page.

Field NameDescription
CONNECTION- ENABLED
- DISABLED
Note: When disabled, no container is running for the connector.
NAMEName of the connector
NETWORK- ONLINE: Container is created and can be reached by the TDP.
- OFFLINE: Container cannot be reached by the TDP.
HEALTH- HEALTHY: Everything is fine, connector doesn’t see any issues.
- WARNING: There is some issue but it’s not critical.
- CRITICAL: Critical issue that prevents connector from running. Connector cannot upload data or execute some commands even in case its operational status is running.
- N/A: The connector doesn’t have a health status yet. This generally indicates that a connector was created but has not been configured.
MODE- IDLE: Connector is enabled, but should not be uploading data. The connector may accept and execute commands. When the connector is first created, its MODE status is IDLE by default.
- RUNNING: Connector is enabled, should be running and uploading data. The connector may accept and execute commands.
- DISABLED: Connector container is shut down.
HOST- Cloud: Connector was deployed as a standalone server in the Cloud
- Hub: Connector was deployed in Tetra Hub v2
CONNECTOR IDThe connector’s ID
TYPEConnector type
VERSIONThe connector’s version
LAST SEENLast NETWORK check
DESCRIPTIONUser-defined connector’s description

Edit the Connector

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

Edit Connector Information page

Edit Connector Information page

Connector Information That You Can Edit

The following table provides the connector information that can be edited after a Connector is created.

Field NameDescription
Disabled/Enabled (toggle)Toggle this field to enable/disable the connector
NAMEConnector’s name
DESCRIPTIONConnector’s description
CONNECTOR VERSIONConnector version
Add / Edit AttributesSelect this option to add or edit labels, metadata, and tags associated with the connector.

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.

Connector Details page: Health tab

Connector Details page: Metrics tab

Integrate Data

Measurement and sample results that are exported to configured exported interface(s) will be uploaded to TDP. After data is uploaded to the TDP, you can enrich and harmonize the data by using any of the following available scripts, protocols, and intermediate data schemas (IDS):

  • Task script: common/sdc-measurement-raw-to-ids:v2.0.0
  • Protocol: common/sdc-measurement-raw-to-ids:v2.0.0
  • IDS: common/agu-sdc:v2.0.0

Submit Measurement Order

Measurements can be created programmatically in AGU SDC through a TetraScience CreateMeasurementOrder command.

To create a TetraScience TetraScience.SDCConnector.CreateMeasurementOrder command, an API call must be made to the Create Commands API. The Connector passes the payload.measurementOrderRequestBody to the SDC REST API.

Required parameters

  • SampleNumber
  • SampleType
  • DeviceNumber

The following command data can be posted to the Command API to make a measurement in the SDC Sandbox:

{
    "targetId": "7e71ceea-0503-4031-9b56-97c686245e25",
    "action": "TetraScience.SDCConnector.CreateMeasurementOrder",
    "expiresAt": "2025-12-30T23:58:43.749Z",
    "payload": {
        "ttl": 600,
        "measurementOrderRequestBody": {
            "SampleNumber": "Sample987",
            "ExternalId": "LIMS12345",
            "SampleType": "Advanced Instruments OsmoTECH PRO default",
            "DeviceNumber": "AIOsmotechPro123456"
        }
    }
}
Parameter NameRequiredDescription
targetIdYesConnector UUID from the Connector Details page
actionYesMust be TetraScience.SDCConnector.CreateMeasurementOrder
expiresAtYesDeadline after which incomplete commands are considered expired
payload.ttlNoNumeric timeout for the HTTP request, in seconds ( Connector default is 300,000)
payload.measurementOrderRequestBodyYesThese contents are posted to SDC’s REST API /SDC/Measurements, and are handled by SDC directly. The requestBody contents can vary based on which instrument is used. For more information, see the SDC User Manual and REST Configuration procedure.