connector-runner-qlink

Connector runner for the QLink MIS/ERP Interface by Nyquist Systems.

QLink exposes a REST API that allows external systems to subscribe to production-event notifications via webhooks. This connector supports one or more QLink machines, subscribing each on startup and forwarding every notification to the transAI platform as a metric.

How it works

1. On start() the connector launches a local HTTP server to receive callbacks.
2. For each configured machine it calls POST /qlink/v1/subscribe with a machine-specific callback URL and the configured notification types.
3. QLink posts JSON notifications to that URL whenever a production event occurs.
4. The connector forwards each notification to the platform via sender.metrics(), enriched with machineId, machineName (if set), and collection.
5. On stop() each machine calls DELETE /qlink/v1/unsubscribe:<id> to clean up. QLink handles deduplication server-side, so a missed unsubscribe is not critical.

Configuration

Minimal

{
  "connectorType": "qlink",
  "callbackHost": "192.168.1.10",
  "machines": [
    {
      "machineId": "tubescan-1",
      "endpointUrl": "http://192.168.1.50:5217",
      "apiKey": "0815"
    }
  ]
}

Multiple machines

{
  "connectorType": "qlink",
  "callbackHost": "192.168.1.10",
  "port": 3080,
  "webhookPath": "/qlink-notifications",
  "machines": [
    {
      "machineId": "tubescan-1",
      "machineName": "TubeScan Floor 1",
      "endpointUrl": "http://192.168.1.50:5217",
      "apiKey": "0815",
      "collection": "qlink_notifications",
      "notificationTypes": ["ProductionStart", "ProductionStop", "RollCut"]
    },
    {
      "machineId": "tubescan-2",
      "machineName": "TubeScan Floor 2",
      "endpointUrl": "http://192.168.1.51:5217",
      "apiKey": "0816"
    }
  ]
}

Configuration fields

Root level:

{
  "callbackHost": "Required — externally reachable hostname/IP that QLink will POST to",
  "port":         "Local port the webhook server listens on — default: 3080",
  "webhookPath":  "Base HTTP path for notification endpoints — default: /qlink-notifications",
  "machines":     "Required — array of machine configurations"
}

Per machine:

{
  "machineId":         "Required — unique identifier, used in the webhook path",
  "endpointUrl":       "Required — base URL of the QLink REST API, e.g. http://host:5217",
  "apiKey":            "Required — API key for HTTP Basic authentication",
  "machineName":       "Optional — human-readable display name added to every metric",
  "collection":        "Optional — platform collection name — default: qlink_notifications",
  "notificationTypes": "Optional — subset of event types to subscribe to — default: all"
}

Available notification types

[
  "InspectionStart",
  "InspectionStop",
  "ProductionStart",
  "ProductionStop",
  "AutoWasteStart",
  "AutoWasteStop",
  "RollCut",
  "PdfReportGenerated"
]

Authentication

QLink uses HTTP Basic authentication with only the API key as the credential — no username prefix. The Authorization header sent with every request is:

Basic base64(<apiKey>)

Example — apiKey: "0815" → Authorization: Basic MDgxNQ==

Webhook endpoints

Each machine gets its own endpoint based on machineId:

POST http://<callbackHost>:<port><webhookPath>/<machineId>

Example with two machines:

POST http://192.168.1.10:3080/qlink-notifications/tubescan-1
POST http://192.168.1.10:3080/qlink-notifications/tubescan-2

Platform output

Every notification is forwarded as metrics with machine metadata:

{
  "NotificationType": "ProductionStart",
  "OrderID": "order-123",
  "OrderDescription": "My Order",
  "timestamp": "2026-04-28T10:00:00.000Z",
  "machineId": "tubescan-1",
  "machineName": "TubeScan Floor 1"
}

machineName is omitted when not configured. All notifications go to qlink_notifications by default (configurable per machine via collection).

Building

npx nx build connector-runner-qlink

Testing

npx nx test connector-runner-qlink