Skip to main content
Version: V3.2

External Connections

An External Connection (also written as ExtConnection) is an Edge Gateway type that represents an external service (any system that is not a Capture Edge Gateway hardware device) that needs to push data directly into the Capture platform.

Terminology

In the UI you will see External Connection when selecting an offline gateway type. In technical contexts and API responses the same concept is often abbreviated ExtConnection.

When to use an External Connection​

Use an External Connection when:

  • You have a custom application, script, or backend service that already collects or processes data and needs to store results in Capture.
  • You are integrating a legacy system, third-party tool, or ERP/MES that can make HTTP requests but cannot run the Capture Edge Gateway software.
  • You want to push data from a scheduled job or batch process (for example, a Python script or a CI pipeline step).
  • You need a machine-level identity and dedicated authorization token for an external sender, so that ingestion can be controlled, revoked, or audited independently.
Logger vs External Connection
Logger (Edge Gateway device)External Connection
HardwarePhysical or virtual gateway deviceAny HTTP-capable service or script
SoftwareRuns Capture Edge softwareRuns your own code
ConfigurationFull edge configuration (collector, syncer, …)Not applicable
Data flowCollects data from connected sources, syncs to cloudPushes data directly to the Capture Data API
AuthenticationDevice JWT via CloudManagerJWT token obtained via Auth API

How it works​

Your service / script
       │
       │  HTTP POST  (JWT or API token)
       ▼
Capture Data API  ──► Cloud storage (retention)
  1. You register the external connection in Capture (see below). This creates an identity and lets you attach a retention target.
  2. Your service authenticates against the Capture Auth API and receives a short-lived JWT token.
  3. Your service pushes data to the Capture Data API using that token. Capture stores the data in the configured retention.

Because the external connection has its own registered identity, Capture can track, monitor, and revoke access independently of other gateways.

Registering an External Connection​

External Connections are registered as offline gateways. There is no hardware that announces itself, so you create the record manually.

  1. Go to Sources → Edge Gateways.
  2. Click Add Edge Gateway (+ button).
  3. Choose Offline gateway.
  4. Select the type External Connection.
  5. Fill in:
    • Company: the company this sender belongs to.
    • Name: a descriptive name for the external service (e.g. erp-export-service).
    • Activation UID: the GUID of the external service (see Finding the Activation UID).
  6. Optional:
    • Fleet: group with other gateways that share assets.
    • Retentions: select where incoming data should be stored. (Required if you want data to land anywhere.)
    • No data alerts: alert if the sender stops pushing data.
  7. Click Confirm.
Retentions

Without a retention target, data pushed by the external connection has nowhere to go. Assign at least one retention during registration, or update the gateway detail page afterwards.

Finding the Activation UID​

Unlike a physical gateway, the Activation UID for an External Connection is the GUID that your service uses to identify itself. You generate or obtain this GUID on your side and then enter it here during registration.

Generating a GUID: Any standard UUID v4 is valid. Examples:

  • Linux/macOS: uuidgen
  • Python: python3 -c "import uuid; print(uuid.uuid4())"
  • Online: any UUID generator tool

Store the GUID securely; you will use it when authenticating (as the username in the auth request).

Pushing data from your service​

Once the External Connection is registered in Capture, your service can authenticate and start pushing data.

Step 1: Authenticate​

Call the Capture Auth API with the credentials issued for this External Connection:

curl -X POST "https://portal.captureplatform.com/Auth" \
  -H "AuthVersion: V0.0.1" \
  -H "Content-Type: application/json" \
  -d '{
    "Username": "<extconnection-username>",
    "Password": "<extconnection-password>"
  }'

The response is a JWT token (valid for 2 hours). Use it in subsequent data push requests.

Credentials

The username and password for an External Connection are managed in the Capture platform (Identity / user management).
Contact your Capture administrator if you need these credentials.

Step 2: Push data​

Use the Data API to push time-series data:

curl -X POST "https://portal.captureplatform.com/api/data" \
  -H "AuthVersion: V0.0.1" \
  -H "DataVersion: V0.0.3" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt-token>" \
  -d '{
    "Metrics": [
      {
        "Name": "production_output",
        "Tags": {
          "machine": "press_01",
          "shift": "morning"
        },
        "Fields": {
          "parts_count": 342,
          "reject_rate": 0.02
        },
        "Timestamp": "1708876800"
      }
    ]
  }'

See the Insert Data reference for the full request schema, field types, blob uploads, and CDC (Change Data Capture) support.

Configuration​

Unlike a Logger (physical edge gateway), an External Connection does not have an edge configuration. There is no collector, syncer, or local storage to configure because your external service manages its own data collection and simply calls the Capture API.

What you can configure on the External Connection in the Capture platform:

SettingWhereNotes
Name / Company / FleetSettings tabStandard gateway metadata.
RetentionsCloud Storage tabWhere incoming data is written. Required for data to land.
VariablesVariables tabNot commonly needed for ExtConnections; available for advanced use.
AlertsAlerts tab"No data" alert if the sender stops pushing.
MessagesMessages tabLogs from the ExtConnection, if any are emitted.

Monitoring​

Once your external service starts pushing data, you can monitor it like any other gateway:

  • Last data package column: when was the last time data arrived from this connection.
  • Explore Data: inspect the incoming data from the gateway detail page.
  • Alerts: configure a "No data" alert so you are notified if the external sender goes silent.
No heartbeat expected

An External Connection does not emit heartbeats. Only the last data package timestamp is meaningful for monitoring purposes.

Common pitfalls​

Token expiry

JWT tokens are valid for 2 hours. Your service must re-authenticate before the token expires or handle 401 responses by refreshing the token.

No retention assigned

If no retention is linked to the External Connection, data will be accepted but not stored anywhere. Verify in the Cloud Storage tab of the gateway detail page.

Activation UID mismatch

The Activation UID entered during registration must exactly match the GUID your service uses when authenticating. A mismatch will prevent authorization.

Next steps​