Connector plug-in - AVEVA PI System

Overview#

The AVEVA PI System connector reads a customer-hosted AVEVA PI Data Archive over its PI Web API REST interface (HTTPS) and publishes PI Points to Atlas as a read-only source. It supports both recorded history on demand and live values pushed by the PI system in real time. Choose this connector when your PI infrastructure already runs PI Web API 2018+ (Basic auth) or 2023+ (Bearer/OIDC); for a SQL Server-backed AVEVA product, see the Aveva.Historian connector instead.

Type string#

Aveva.PiSystem

Use this value verbatim in the Type field of your connector configuration.

Configuration#

Connection setup#

Prerequisites on the PI infrastructure#

• A PI Data Archive (the historian), running on Windows, licensed, and reachable from the connector host over HTTPS.
• A PI AF Server (Asset Framework) - required infrastructure even though v1 addresses only PI Points; AF-attribute support is planned.
• A PI Web API host, minimum PI Web API 2018 for Basic auth, or PI Web API 2023+ if Bearer/OIDC is used.
• A current PI System Access (PSA) license (or AVEVA Flex / PI Data Infrastructure equivalent) - confirm the exact SKU with AVEVA.

The connector needs no native client libraries or Windows-side installation; it speaks to PI Web API purely over HTTPS as a REST/JSON client.

Steps#

1. Verify network reachability. Ensure the connector host can reach the PI Web API hostname on port 443 (HTTPS).

2. Choose an authentication mode.

   • Basic auth: Prepare a PI username and password with read access to the desired PI Points.
   • Bearer/OIDC: Prepare a client ID and secret from your OIDC identity provider, and confirm the token endpoint URL.

3. Assemble the Base URL. This is typically https://<pi-server>/piwebapi (case-sensitive). Use the Test button to verify reachability and confirm authentication before saving.

4. Define Topics. For each topic, supply an operator-chosen name (e.g. Temperature or Plant/Area) and a PI Point name filter using PI Web API glob syntax (e.g. Plant.*.Temp* or *). Topics are optional; without them, the connector advertises no binding paths.

5. Save the configuration. The connector picks up changes without a restart (hot-reload). If you edit authentication credentials or the base URL, existing subscriptions are faulted and re-subscribed against the new settings.

Binding paths#

The connector advertises two types of binding paths:

Catalog paths (browse)#

Format: {InstanceId}/{Topic}

Reading a catalog path browses PI Points matching that topic's name filter and returns a rowset with columns [name, description, unit]. The name column holds the stable PI Point path (never the opaque WebID, which is resolved at browse time and never persisted).

Example: An instance ID of pi-main with a topic named Temperatures and name filter Plant.*.Temp* produces the catalog path pi-main/Temperatures. Reading this path browses all PI Points whose names match the filter and returns their metadata.

Per-tag data paths (history and live)#

Format: {InstanceId}/{NameFilter}/{Tag}

Where {NameFilter} is the exact name filter from the topic configuration, and {Tag} is a PI Point name matching that filter (no wildcards in the tag itself). The tag is everything after the name filter, slashes included.

Example: If a topic with name filter Plant.*.Temp* contains a PI Point named Plant.LineA.TempSensor1, the per-tag path is pi-main/Plant.*.Temp*/Plant.LineA.TempSensor1.

Tag names that contain a slash

The tag part of the path is everything after the name filter, slashes included. A tag whose name is itself a path, such as one written by the Ignition module (which names each tag after its Ignition tag path), is bound by writing the name exactly as it appears in the source:

pi-main/Plant*/Plant/LineA/TempSensor1

Here the tag is Plant/LineA/TempSensor1.

• Do not escape the slashes. %2F, \/ and square brackets around the tag are not decoded; they become part of the tag name, so the path matches nothing.
• Instance-map variables still work inside the tag, for example .../Line[Num, 00]/Process/humidity.
• Overlapping name filters: if one configured name filter starts with another followed by / (Plant* and Plant*/LineA), a path is matched against the longer one first. .../Plant*/LineA/TT1 is tag TT1 under Plant*/LineA, never tag LineA/TT1 under Plant*.

Version: tag names that contain / bind from the first Timebase release after 2.0.0, which needs both Atlas and Connect from that release. In 2.0.0 the tag part of the path is a single segment, so a path to such a tag is never routed: the domain compiles and the property stays empty, with nothing logged.

Both catalog and per-tag paths can be used with the Preview function to fetch recent data without entering a full subscription.

Recorded history#

A per-tag path's GetRange operation reads PI Web API's recorded (raw or compressed) archive stream over the requested time window (constrained by Default lookback if unbounded). The connector returns a rowset with columns:

• Timestamp - ISO-8601 UTC, mapped losslessly onto ticks.
• Value - A numeric column (double) unless any value is an operator-defined PI digital state (e.g. "Open"/"Closed"), in which case the rowset switches to a string column. System-state values (e.g. "Shutdown", "I/O Timeout") are masked to null with Quality=0 rather than poisoning a numeric column.
• Quality - Synthesized from PI Web API's Good, Questionable, and Substituted flags: 192 (Good) when good and neither questionable nor substituted; 64 (Uncertain) when good but questionable or substituted; 0 (Bad) when not good, or when the value is a PI system-state (system states are always treated as Bad regardless of the Good flag).

Interpolated and aggregate retrieval (e.g. /interpolated, /summary) are out of scope for v1; only recorded history is supported.

Live subscriptions#

A per-tag path is subscribable. The connector acknowledges subscriptions as Active immediately, then asynchronously fetches a snapshot (the tag's most recent recorded value over Default lookback) and pushes it as SnapshotComplete. Live updates then arrive via PI Web API's Stream Updates mechanism (one register-and-poll marker per distinct PI Point WebID, refcounted across all local subscribers on that point). On marker expiry or transient poll failure, the connector re-registers and re-snapshots with bounded backoff; if the retry budget is exhausted, the subscription faults so Atlas can re-route rather than being silently starved.

Every active subscription advances its watermark on the Heartbeat interval even if the tag goes quiet, using the Allowed latency to tolerate late-arriving values.

Test and preview#

• Test calls PI Web API's landing page endpoint and reports the server version. Use it to verify the Base URL, certificate trust settings, and authentication before saving.
• Preview (for catalog or per-tag paths) fetches recent data without a full subscription - bounded to 50 entries to keep response times quick.

Both operations never throw; they return a failure status with a diagnostic message on any error.

Connection status#

The instance's status in Connect says whether it can reach PI Web API, separately from whether it started. Connect checks about every 20 seconds, by asking the server for its information document, and the check never writes anything to PI Web API. A blank or malformed Base URL, a credential PI Web API refused, or a server certificate the connector will not trust reads Connection Fault at once, with the reason. A PI Web API that cannot be reached reads Connecting… for a minute and then Connection Fault; the subscriptions are kept through the outage and resume when it answers. See Plugin Instance States, Connection Status and Retries for the status model and the retry ladders.

Troubleshooting#

Distinctions from sibling connectors#

This connector addresses AVEVA PI System (PI Data Archive via PI Web API over HTTPS). For AVEVA Historian (a SQL Server-backed product), use the Aveva.Historian connector instead, which connects directly to the Historian's SQL database.