Xylem Connector Runner

Polls one or more Xylem controllers through /api/v1/livedata using HTTP Digest Authentication. The runner validates and normalizes each response, then sends documents and metrics through the connector SDK.

Configuration

The connector extends the standard connector configuration with controllers:

{
  "controllers": [
    {
      "id": "test-01",
      "baseUrl": "http://localhost:8000",
      "endpoint": "/api/v1/livedata",
      "username": "ADMIN",
      "password": "1111",
      "timeoutMs": 5000,
      "intervalSeconds": 10
    }
  ]
}

Each controller is polled independently. Optional controller fields are name, location, endpoint, and timeoutMs. The endpoint defaults to /api/v1/livedata.

API Payload

The endpoint returns a live-data envelope containing controller metadata, sensors, and notifications:

{
  "webServer": "1.1.8",
  "payloadType": "livedata",
  "payloadVersion": "0.3.4",
  "controllerTime": 1786440563,
  "controllerType": "",
  "controllerSerial": "00000011",
  "controllerName": "Controller A",
  "controllerSW": "4.00",
  "sensors": [],
  "notifications": []
}

Sensors contain identity and state fields. sensorPod is optional because some controller responses omit it. mainValue and subValue are optional and may contain:

• valueState, such as VALID, INVALID, or OFL;
• numeric value when available;
• UoM, display fields, and an optional numeric range.

Unknown fields are accepted by the Zod schemas so newer controller payloads do not fail solely because they contain additional fields. Required structural fields and value types are still validated.

Parsing And Normalization

xylem-live-data.schema.ts validates the complete JSON response before any records are sent. xylem-metrics.utils.ts then normalizes the payload:

• Controller metadata is copied into all related records.
• Controller documents use the API controller serial as their stable identity.
• Sensor documents use controllerSerial:sensorId as their stable identity.
• Notifications use controllerSerial:notificationId as their stable identity.
• Value-location documents identify the controller, sensor, and main/sub value location. They retain units, ranges, sensor metadata, and controllerTimestamp, but not the actual reading.
• Numeric readings are emitted separately as value metrics.
• controllerTime is retained as record data; sender event timestamps use platform receipt time.

INVALID and OFL readings remain visible as records without a numeric value.

Ingestion

Documents are sent with sender.documents() and stable keyField values:

| Collection | Content | | --------------- | ----------------------------------------- | | controllers | Current controller metadata | | sensors | Current sensor metadata | | values | Available measurement locations and units | | notifications | Every notification, upserted by identity |

Metrics are sent with sender.metrics() in separate metadata-compatible groups:

| Collection | Metric body | Metadata | | ------------------ | -------------------------- | ----------------------------------------------------- | | values | { value } | Controller, sensor, value kind, unit, sensor metadata | | sensor_status | { state_code } | Controller, sensor, raw state, sensor metadata | | connector_status | { state_code, duration } | Controller and raw poll status |

Metric dimensions are stored in sender metadata; metric bodies contain only measure values. The Cube template therefore uses metadata.* for dimensions and data.* for measures.

Status Mapping

Sensor states map to numeric codes:

| Xylem state | Code | | ----------- | ---: | | INACTIVE | 0 | | MEASURING | 1 | | Unknown | -1 |

Controller poll status maps failure to 0, success to 1, and unknown states to -1. Unknown sensor states generate a warning containing controller and sensor identity.

Error Handling

Controllers are isolated: one controller's failure does not stop other controllers. Transport, HTTP, JSON, validation, and ingestion failures produce a failed connector-status metric. A malformed response is not partially normalized before validation.

Building

Run npm exec nx build connector-runner-xylem to build the library.

Running unit tests

Run npm exec nx test connector-runner-xylem to execute the unit tests via Jest.