This guide shows how to install, configure, and operate the Tetra Metrohm OMNIS Connector versions 1.0.x. The Connector is a containerized application that receives analysis results from Metrohm OMNIS by using a webhook (the OMNIS CALL WEB API command) and uploads them to the Tetra Data Platform (TDP). A background polling loop queries the OMNIS Integration API to recover any uploads that did not reach TDP.

📘

NOTE

The Connector deployment involves two roles:

• TDP / DevOps administrator: Installs the Connector and then configures it in the TDP user interface. Start at Prerequisites and follow the install flow top-to-bottom.
• OMNIS administrator: Sets up the OMNIS Sample Profile and Operating Procedure so OMNIS sends data to the Connector. Start at OMNIS Operating Procedure Setup.

See Hand Off to the OMNIS Administrator for the specific values the TDP administrator must pass to the OMNIS administrator.

Data Flow

┌──────────────┐      CALL WEB API      ┌──────────────────────┐    Upload     ┌─────┐
│ Metrohm OMNIS│ ──────────────────────►│  Metrohm OMNIS       │ ────────────► │ TDP │
│              │ (webhook + Basic Auth) │  Connector           │   (HTTPS)     │     │
└──────────────┘                        └──────────────────────┘               └─────┘
       ▲                                           │
       │       Integration API (poll)              │
       └───────────────────────────────────────────┘
              Retry: re-fetch failed samples

Install a Tetra Metrohm OMNIS Connector

Prerequisites

System Requirements

• Linux OS with Docker installed. For a standalone deployment, provision a Linux host with Docker.
• Minimum resources: 0.5 vCPU, 1 GB memory, and a persistent storage volume for batch and retry state (a few GB is enough; see Persistent Storage). On a standalone host, size above this for the OS and Docker.
• Bi-directional network access between OMNIS and the Connector. OMNIS reaches the Connector's webhook port; the Connector reaches the OMNIS Integration API.
• Outbound HTTPS from the Connector to TDP v4.0.0 or later.

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

Provision a Tetra Hub or Standalone Instance

If your organization does not already have a Tetra Hub or a Standalone Connector host on the network that can reach OMNIS, provision one now. If you already have either deployed for another connector, you can skip ahead to Metrohm OMNIS Requirements.

To set up a 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.

⚠️

WARNING

Standalone deployments require a webhook-port patch before you run the installer. The TDP-generated install-connector.sh script is built for outbound-only Connectors and does not expose the inbound webhook port by default. Before you execute the installer, read Webhook Port Configuration → Standalone deployments below for the required sed patch. Without the patch, the Connector binds the webhook port inside the container but OMNIS cannot reach it from the host.

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.

Metrohm OMNIS Requirements

The Tetra Metrohm OMNIS Connector requires the following OMNIS configuration:

• 3rd Party Data Integration license to enable the OMNIS Integration API that the Connector depends on. A 3rd Party Data Integration license may be required to exchange data between OMNIS and external software. The license is activated in OMNIS under Settings → Software licenses. Contact your Metrohm representative to confirm licensing.
• OMNIS User Management activated (a prerequisite for the 3rd Party Data Integration API). Save pending changes and stop any running determinations, then go to Settings → Advanced settings → User management and click Activate user management. Restart the OMNIS Software afterward (Standalone only; Client/Server does not need a restart). This action cannot be reversed once enabled.
• OMNIS Web API enabled, exposing the Integration API on port 5002 and the OAuth2 token endpoint on port 5003. The token URL is then https://<your-omnis-host>:5003/connect/token and the Web API root is https://<your-omnis-host>:5002/openapi. The Web API is enabled during OMNIS installation. To enable it on an existing system, contact your Metrohm representative. For more information, see Data Integration in the TetraConnect Hub. For access, see Access the TetraConnect Hub.
• An Operating Procedure configured with the CALL WEB API command to send analysis results to the Connector's webhook endpoint.
• A dedicated OMNIS Technical User for Integration API access (required for automatic retry). In OMNIS User Management, create a user (for example, tdp-omnis-connector) with a read-only (retrieve-only) API role and a non-expiring password. See your OMNIS documentation for the steps.
• Record the Technical User's username and password, along with the OAuth2 Client ID (and Client Secret, if required), to enter later when you configure the Connector in TDP. The Client ID comes from your OMNIS administrator, not the Connector (see Configure the OAuth2 Client in OMNIS below).

Configure the OAuth2 Client in OMNIS

The Connector authenticates to the OMNIS Integration API with an OAuth2 client, which the OMNIS administrator configures on the OMNIS side. The OAuth2 client and the Technical User (created above) are two separate things, and both are required.

Ask your OMNIS administrator to provide an OAuth2 client for the Connector that allows the password authentication flow and grants the Integration API scope. For production, the client should require a client secret, and that secret must be shared with the TDP administrator.

Enter the OMNIS Client ID (and OMNIS Client Secret, if the client requires one) in the Connector's TDP configuration exactly as provided. For the detailed client configuration steps, see your OMNIS documentation or contact your Metrohm representative.

OMNIS Operating Procedure Setup

📘

NOTE

Before you begin, get the webhook URL and webhook credentials (username and password) from your TDP administrator. See Hand Off to the OMNIS Administrator for the full list.

Configure the OMNIS Operating Procedure with these steps, in order:

1. TDP Update Success identifier: Add a Numeric identifier named TDP Update Success on your Sample Profile or Operating Procedure. It holds the upload outcome: 1 for success, 0 for failure.

2. CALL WEB API command: Add a CALL WEB API command that POSTs to the Connector's webhook endpoint (for example, http://<connector-host>:<port>/api/samples). Build the body with OMNIS formula syntax, for example:

   JSON

   {
       "payload": {
           "sampleName": <<'Name.CurrentSample'>>,
           "subsampleName": <<'Name.CurrentSubsample'>>,
           "sampleData": {
               "sampleLocation": <<'Sample Location.CurrentSampleData'>>
           },
           "subsampleData": {
               "temperature": <<'Temperature.CurrentSubsampleData'>>
           }
       }
   }

   Replace the field and variable names with those from your Sample Profile and Operating Procedure. Two settings on this command are mandatory:

   • Name the command exactly Send data to TDP. OMNIS auto-generates a variable named Finished.Send data to TDP from the command name; the CALC formula in step 3 reads it.

     ⚠️

     WARNING

   If you use a different name than Send data to TDP for the command, the formula will not resolve and the retry system will never see failures.

   • Disable "Cancel after error" on the command. If left enabled, an HTTP failure stops the Operating Procedure before the CALC command runs, so TDP Update Success is never written and the retry system has nothing to detect.

3. CALC command: Add a CALC command named Call Web API validation after the CALL WEB API command, with Result Name TDP Update Success and the formula Abs('Finished.Send data to TDP' - 2):

   CALL WEB API result	Finished.Send data to TDP	Formula	TDP Update Success
   HTTP success (200)	1	Abs(1 - 2) = 1	1
   HTTP failure	2	Abs(2 - 2) = 0	0

📘

NOTE

The Connector reads two OMNIS identifiers by name, with English-locale defaults. If your OMNIS uses different names, set OMNIS Identifier: TDP Success (default TDP Update Success) and OMNIS Identifier: Determination Start (default Determination start) in the Connector configuration.

Create a Tetra Metrohm OMNIS Connector

In the TDP:

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 Metrohm OMNIS 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

Set these parameters in the TDP UI. Environment variables serve as a fallback for local development.

⚠️

WARNING

Webhook authentication is required. The Connector won't start without Webhook Auth Username and Webhook Auth Password. Configure these before activating the Connector.

The parameters below are listed in the same order they appear in the TDP UI.

📘

NOTE

TLS for the OMNIS Integration API. The Connector verifies the OMNIS server's TLS certificate. Because most on-premises OMNIS servers present a self-signed or private-CA certificate on ports 5002 and 5003, supply your OMNIS CA bundle to the Connector container and set Custom CA Certificate Path to that PEM file so verification succeeds against it. Use Disable Certificate Validation only as a temporary step during development or pre-production when a CA bundle is not yet available, and switch back to Custom CA Certificate Path before going to production.

Webhook Port Configuration

The Connector's webhook server listens on port 9000 by default. OMNIS sends every CALL WEB API request to this port (or to a different port if you override the default on a Standalone deployment).

Tetra Hub Deployments

The Hub configures the port at deployment time. Use port 9000 in the OMNIS CALL WEB API URL.

⚠️

WARNING

Do not change the webhook port on Hub v2. The port is baked into the Hub deployment from the connector manifest. Setting OMNIS_WEBHOOK_PORT to a different value through the TDP user interface causes a port mismatch: the Connector binds to the new port inside the container, but the Hub keeps routing inbound traffic to port 9000, so OMNIS can no longer reach it. Custom ports are only supported on Standalone deployments (see below).

Standalone deployments

📘

NOTE

Standalone deployments let you choose any webhook port. Whatever port you choose must be used consistently in the installer patch, the OMNIS_WEBHOOK_PORT environment variable, and the OMNIS CALL WEB API URL.

The TDP-generated install-connector.sh is built for outbound-only Connectors, so it does not expose the inbound webhook port. You must patch the script to expose the port before running it. This is mandatory: without the patch, OMNIS cannot reach the Connector.

Download the installer from TDP as install-connector.sh, patch it, and execute it:

export CONNECTOR_TOKEN="<your-connector-token>"
export DOWNLOAD_IMAGE="true"

# 1. Download the installer from TDP
curl https://<your-tdp-api>/v1/data-acquisition/connectors/<connector-id>/installer \
  -o install-connector.sh \
  -H "Authorization: Bearer ${CONNECTOR_TOKEN}" \
  -H "x-org-slug: <your-org-slug>"

# 2. Patch the installer to expose the webhook port.   <-- REQUIRED, see below
#    The port must match the OMNIS CALL WEB API URL.
sed -i.bak '/--label tsArtifactSlug=\$ARTIFACT_SLUG \\/a\  -e OMNIS_WEBHOOK_PORT=9000 \\\n  -p 9000:9000 \\' install-connector.sh

# 3. Run the patched installer
sudo -E bash install-connector.sh

You can find the Connector Token, connector ID, and org slug on the connector's page in the TDP UI.

The sed command in step 2 inserts -e OMNIS_WEBHOOK_PORT=9000 and -p 9000:9000 into the installer's docker run block, which binds and exposes the webhook port. To use a different port, change 9000 in both the sed patch and the OMNIS CALL WEB API URL.

📝

To back /var/data with a specific host volume (named volume, bind-mount, NFS, or encrypted storage), see Data Integration in the TetraConnect Hub. This is optional. For access, see Access the TetraConnect Hub.

Review and Edit the Connector's Information

The Information tab on the Connector Details page shows the Connector's status and file counts (pending, uploaded, failed), and lets you edit the Labels, Metadata, and Tags applied to all files written to TDP. For details, 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.

Verify the Connector Is Working

After the Connector is running and the OMNIS Operating Procedure is configured, verify the end-to-end data flow:

1. In OMNIS, run a test Operating Procedure that includes the CALL WEB API command.
2. In the TDP UI, navigate to the Connector's page and select the Files tab.
3. Confirm that a new file appears with status SUCCESS within 30 seconds of the batch timeout (default: 15 seconds after the last sample arrives).

If the file does not appear, check the Information tab for health error codes and see Troubleshooting.

Hand Off to the OMNIS Administrator

At this point the Connector is installed, configured, and running. The OMNIS administrator now configures the OMNIS side so OMNIS sends sample data to the Connector (see OMNIS Operating Procedure Setup).

Hand off the following values:

Metrics

After the Connector is running, select the Metrics tab on the Connector Details page to monitor its health. It shows container metrics and aggregate file counts (uploaded, errored, pending).

Operational Endpoints

The Connector exposes a /health endpoint (no authentication) on the webhook port, for monitoring dashboards and load-balancer checks. The webhook endpoint itself (/api/samples) uses the same HTTP Basic Auth credentials configured for the Connector.

Access Data

Webhook Ingestion

The Connector receives analysis results from Metrohm OMNIS through the CALL WEB API command. When OMNIS completes an Operating Procedure, it sends the analysis results as a JSON payload to the Connector's webhook endpoint, and the Connector uploads them to TDP.

The CALL WEB API request travels over your local network from OMNIS to the Connector and is authenticated with HTTP Basic Authentication. Deploy the Connector on a trusted, isolated network segment alongside OMNIS. Data uploaded from the Connector to the Tetra Data Platform is encrypted in transit (HTTPS/TLS).

Upload history and status are visible in the TDP connector files panel. Files move through PENDING (upload in progress) to SUCCESS when the upload completes; failed uploads appear with status ERROR and include a human-readable failure reason.

The Connector provides at-most-once delivery: re-delivering the same content (an OMNIS re-send or a retry) does not create duplicate files in TDP.

Automatic Retry

When OMNIS credentials are configured, the Connector runs a background retry loop that recovers uploads that did not reach TDP:

1. On a configurable interval (the Retry Polling Interval, default 5 minutes), the retry system queries the OMNIS Integration API for completed runs whose upload to the Connector did not succeed.
2. For each one, the Connector re-fetches the data from OMNIS and re-attempts the upload to TDP.
3. The retry policy makes up to 5 attempts using exponential backoff with jitter; an item that still fails is moved to a Dead-Letter Queue (DLQ). See Dead-Letter Queue Recovery below.
4. During a sustained OMNIS or TDP outage, the retry system backs off automatically and reports the RetryCircuitBreakerOpen health status until service is restored.

Dead-Letter Queue Recovery

After it exhausts its retry attempts, a sample moves to a Dead-Letter Queue (DLQ). Items in the DLQ appear in the TDP connector-files panel with status ERROR and a human-readable failure reason. A self-service way to recover items from the DLQ is planned for a future release.

The DLQ is stored locally on the Connector host, so recovery is performed by a local administrator with access to that host; it cannot be performed remotely. TetraScience Support can advise on the procedure but cannot access the local DLQ directly. For help, contact TetraScience Support through the TetraConnect Hub with your Connector ID and the affected subsample ID (shown on the ERROR row in the connector-files panel).

📘

NOTE

Automatic retry requires OMNIS credentials (username, password, and Client ID). Without them, the Connector runs in webhook-only mode, with no retry.

Output Files

The Connector uploads each batch of OMNIS results to the TDP Data Lake under omnis/samples/ as a JSON file. Every upload carries a sha256 label (the file's SHA-256 digest, for integrity verification); retry-path uploads additionally carry a retried-file = "yes" label, which you can use to filter them in TDP queries.

For the detailed output file format and downstream-pipeline guidance, see Data Integration in the TetraConnect Hub. For access, see Access the TetraConnect Hub.

Persistent Storage

The Connector requires a persistent volume mounted at /var/data inside the container for its batch and retry state. On a Tetra Hub deployment this volume is provisioned automatically; no operator action is required. On a standalone deployment, the default installer persists /var/data across container restarts and host reboots.

📘

NOTE

The in-container path must remain /var/data. For advanced volume customization (Docker named volume, host bind-mount, NFS share, or encrypted storage), see Data Integration in the TetraConnect Hub. For access, see Access the TetraConnect Hub.

Troubleshooting

The Connector reports specific health error codes to TDP. Operators can see the current code on the Information tab of the connector's page in the TDP UI.

If the Connector returns HTTP 503 shortly after startup, it is waiting for its webhook credentials to load. Confirm Webhook Auth Username and Webhook Auth Password are set in the TDP UI. OMNIS calls during this brief window are recovered by automatic retry.

Limitations

The following are known limitations of the Tetra Metrohm OMNIS Connector v1.0.x:

• The OMNIS Integration API commands (such as creating samples, executing sample lists) are not exposed through TDP commands in this release. Bidirectional orchestration through TDP pipelines is planned for a future release.
• The Connector keeps uploading webhook data to the TDP while in IDLE mode. Switching the Connector to IDLE correctly stops the retry / polling loop (no more OMNIS Integration API calls, no more retry attempts), but it does not stop the webhook listener: any data OMNIS sends through CALL WEB API is still accepted and uploaded to the TDP. To fully stop uploads, Disable the Connector in the TDP UI. A fix is planned for a future release: while the Connector is in IDLE, webhook payloads will be buffered to disk and uploaded when the Connector returns to RUNNING.
• The Connector rejects request bodies larger than 20 MB (HTTP 413 Payload Too Large). Deliver large reports or attachments to TDP through a different channel.

References

The following Metrohm publications are referenced from this guide. Metrohm is the authoritative source for OMNIS configuration; consult your Metrohm representative for the most current revisions.

• OMNIS 3rd Party Data Integration API – Technical White Paper — Web API installation, identity-server configuration, Technical User setup, and OAuth2 client configuration.
• OMNIS Client/Server Software Guide — User Management activation and software license management for OMNIS Client/Server deployments.
• OMNIS Standalone Software Guide — User Management activation and software license management for OMNIS Standalone deployments.
• OMNIS Integration Overview — high-level overview of OMNIS integration capabilities.

Contact your Metrohm representative for copies of the publications listed above.

Documentation Feedback

Do you have questions about our documentation or suggestions for how we can improve it? Start a discussion in TetraConnect Hub. For access, see Access the TetraConnect Hub.

📘

NOTE

Feedback isn't part of the official TetraScience product documentation. TetraScience doesn't warrant or make any guarantees about the feedback provided, including its accuracy, relevance, or reliability. All feedback is subject to the terms set forth in the TetraConnect Hub Community Guidelines.