Joseph Doherty
32f26272ae
Five tools under one repo, all docs organized per DOCS-GUIDE.md: - aalogcli: .NET 4.8 / x86 CliFx CLI for reading System Platform binary logs (*.aaLGX) for LLM debugging, built on aaOpenSource/aaLog. Commands: last, tail, range, unread, fields. Stable JSON envelope under --llm-json. Build template under lib/build/ for rebuilding aaLogReader.dll. - aot: ArchestrA Object Toolkit 2014 v4.0 reference material. Dev guide (Markdown converted from CHM), API reference for the ArchestrA.Toolkit namespace, and the Monitor / Watchdog VS sample solutions. - graccesscli: .NET 4.8 / x86 CliFx CLI that automates Galaxy configuration via the ArchestrA GRAccess COM interop. Includes session daemon, IPC protocol, and llm-json envelope contract. - grdb: SQL/DDL exploration of the Galaxy Repository database. DDL captures, reusable queries, hierarchy / contained-name <-> tag-name translation notes. - histdb: LLM-oriented reference for AVEVA Historian retrieval. INSQL linked-server, extension tables, every wwXxx time-domain extension, every retrieval mode, alarm/event SQL recipes, REST API. Distilled from the 243-page Historian Retrieval Guide. Root contains: - CLAUDE.md: thin index pointing into each tool's README. - DOCS-GUIDE.md: doctrine for organizing docs for LLM consumption. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
173 lines
8.7 KiB
Markdown
173 lines
8.7 KiB
Markdown
# Historian Data REST API
|
|
|
|
For when the consumer can't (or shouldn't) speak SQL — browsers, Excel, Power BI, Tableau, web frontends. Same data as the SQL extension tables, exposed as OData over HTTPS.
|
|
|
|
## Versions
|
|
|
|
Two API versions are supported by AVEVA Insight:
|
|
|
|
| Version | Recommended? | Notes |
|
|
| --- | --- | --- |
|
|
| `v2` | **Yes** | `TagFilter` (POST/GET) on `ProcessValues`, `AnalogSummary`, `StateSummary`. Single quotes are NOT used around `DateTime` in `$filter` (except for events). Summary entities use `StartDateTime` / `EndDateTime`; raw / process value entities use `DateTime`. |
|
|
| `v1` | Legacy | Still works. Uses `datetimeoffset'...'` quoting. Includes summary entities (`Summary`, `Daily`, `Hourly`, `Minutely`) that are v1-only. |
|
|
|
|
Pick **v2** for new code unless you need a v1-only summary entity.
|
|
|
|
## Authentication
|
|
|
|
Two flavors:
|
|
|
|
- **AVEVA Historian Insight (on-premises)** — Windows integrated security via Negotiate. The user must belong to `aaAdministrators`, `aaPowerUsers`, or `aaUsers`. Most modern browsers and Excel handle this transparently.
|
|
- **AVEVA Insight (cloud)** — OpenID Connect bearer-token, or Basic auth (`username` is treated as the API key). Some clients (older Excel) lack OIDC support; Basic remains as a fallback.
|
|
|
|
There's also a "solution-specific retrieval token" path: include the token in the URL and skip the `s/<solution_id>` segment.
|
|
|
|
## Endpoint shape
|
|
|
|
```
|
|
https://online.wonderware.com/s/<solution_id>/apis/historian/<api_version>/<resource>?<query_parameters>
|
|
```
|
|
|
|
- `<solution_id>` — your Insight solution. Omitted when using a solution-specific retrieval token.
|
|
- `<api_version>` — `v1` or `v2`.
|
|
- `<resource>` — one of the resources below.
|
|
- `<query_parameters>` — OData (`$filter`, `$top`, `$skip`, `$orderby`, `$select`, `$skiptoken`) or REST-style (`TagFilter=...&Resolution=...`).
|
|
|
|
In the URL: **`%20`** is space, **`%27`** is a single quote. The Chrome JSONView viewer also accepts `+` for space, which makes URLs more readable.
|
|
|
|
## OData operators
|
|
|
|
`eq`, `ne`, `gt`, `ge`, `lt`, `le`, `and`, `or`, `not`. Use parentheses for grouping. **A `$filter` may contain at most one time clause combined with one filter clause via `and`.** The filter clause itself may use any combination of operators internally.
|
|
|
|
If you need multiple values for the same field, use `or`:
|
|
|
|
```
|
|
((Priority eq 100 or Priority eq 200 or Priority eq 500) and (Severity le 2))
|
|
```
|
|
|
|
## `TagFilter` (REST-style)
|
|
|
|
Supported on `ProcessValues`, `AnalogSummary`, `StateSummary` (`v2`+). OData filter notation, with hard limits:
|
|
|
|
- Up to **20** `AND` clauses.
|
|
- Up to **20** `OR` clauses.
|
|
- Up to **2** UDF (user-defined function) clauses.
|
|
- **Cannot mix `AND` and `OR`** in the same `TagFilter`.
|
|
- Operators must be lowercase (`and`, not `And`).
|
|
- Most attribute searches are case-insensitive; case-sensitive ones are: `InterpolationType`, `MessageOn`, `MessageOff`.
|
|
|
|
Valid:
|
|
|
|
```
|
|
.../v2/ProcessValues?TagFilter=startswith(Source,'MVDS') and TagType eq 'string'
|
|
```
|
|
|
|
Invalid (mixed-case operator):
|
|
|
|
```
|
|
.../v2/ProcessValues?TagFilter=startswith(Source,'MVDS') And TagType eq 'string'
|
|
```
|
|
|
|
## Retrieval resources (the catalog)
|
|
|
|
| Resource | Verb(s) | Purpose |
|
|
| --- | --- | --- |
|
|
| `/ProcessValues` | GET | Raw value+time+quality (VTQ) records for one or more tags. |
|
|
| `/AnalogSummary` | GET | Aggregated analog statistics (min/max/avg/integral/etc.) over a window. |
|
|
| `/StateSummary` | GET | Time-in-state summaries for discrete/string/integer tags. |
|
|
| `/Events` | GET | Events and alarms (same content as the SQL `Events` table). |
|
|
| `/Tags` | GET / POST / DELETE | Tag metadata; v2 also returns extended properties. POST manages tags in bulk. |
|
|
| `/TagProperties` | GET | List of property names available on tags. |
|
|
| `/TagPropertyValues` | GET | Distinct values seen for a given tag property. |
|
|
| `/TagGroups` | GET | Groups of tags. |
|
|
| `/TagSuggest` | GET | Autocomplete-style tag-name suggestions. |
|
|
| `/TagSearch` | GET | Search tags by partial name / property. |
|
|
| `/TagExtendedProperties` | GET | Extended (custom) tag properties. |
|
|
| `/Summary` | GET | **v1-only.** Generic summary. |
|
|
| `/Daily`, `/Hourly`, `/Minutely` | GET | **v1-only.** Pre-bucketed summary periods. |
|
|
| `/SystemParameters` | GET | **On-premises only.** Server config. |
|
|
|
|
## `RetrievalMode` and `Resolution` (REST-side names)
|
|
|
|
Same modes as the SQL `wwRetrievalMode`. The REST query parameter is named `RetrievalMode`. Supported values from the v2 spec: `BestFit`, `Counter`, `Delta`, `Full`, `Interpolated`, `Maximum`, `Slope` (and `Cyclic`, the default for analog).
|
|
|
|
`Resolution` is in milliseconds, applies to `Raw`, `ProcessValues`, and the summary entities — picks the granularity of the returned data.
|
|
|
|
## `ProcessValues` — VTQ records
|
|
|
|
```http
|
|
GET /v2/ProcessValues?$filter=FQN+eq+'plant12.pump6'+and+DateTime+gt+2017-07-13T00:00:00Z
|
|
```
|
|
|
|
Required: `FQN` (`datasource.tagname`), and a time predicate (`DateTime` for v2). Optional: `OPCQuality`, `Value`, `Text` (string tags / discrete-tag message text). Returns 200 with `{ fqn, datetime, ... }`. 404 / 401 on missing FQN / unauthorized.
|
|
|
|
## `AnalogSummary` — windowed analog stats
|
|
|
|
```http
|
|
GET /v2/AnalogSummary
|
|
?$filter=FQN+eq+'Depot.Train09'
|
|
+and+StartDateTime+ge+2017-06-09T09:00:00-07:00
|
|
+and+EndDateTime+le+2017-06-09T10:00:00-07:00
|
|
&Resolution=3600000
|
|
```
|
|
|
|
Required: `FQN`, `StartDateTime`, `EndDateTime` (RFC 3339 / ISO 8601, UTC `Z` or explicit offset). Optional: `RetrievalMode` (`Cyclic`/`Full`, default `Cyclic`), `Resolution`, `SliceBy` (split summary by another tag's value at the same time, up to 10 SliceBy tags), `SliceByValue` (filter criterion for SliceBy), `OPCQuality`. Quality logic mirrors the SQL `wwQualityRule = 'Good'`: all-Good → Good, full gap → Bad, mixed → Doubtful (`64`).
|
|
|
|
## `StateSummary` — windowed time-in-state
|
|
|
|
Same shape as `AnalogSummary` but for state-tag data. Use `RetrievalMode=Cyclic` and a `Resolution` to bucket by time.
|
|
|
|
## `Events` — alarms and events
|
|
|
|
```http
|
|
GET /v2/Events?$filter=EventTime+gt+'2017-07-13T00:00:00'
|
|
```
|
|
|
|
Note the **single quotes around the datetime** for events specifically — events break the v2 "no quotes" rule because `EventTime` is treated as a string-style column.
|
|
|
|
Filterable optional parameters include `ID` (alarm GUID), `EventTime`, `Type` (`Alarm.Set` / `Alarm.Acknowledge` / `Alarm.Clear` / `Alarm.Write` / `User.Write` / `User.Write.Secured` / `User.Write.Verified` / `Application.Write`), `Priority` (1-999, lower = higher), `Namespace`, `Severity` (1=Critical, 2=Major, 3=Minor, 4=Informational), `EventTimeUTCOffsetMins`, `ReceivedTime`, `IsAlarm`. **Property values are case-sensitive.**
|
|
|
|
## Pagination — `$skiptoken`
|
|
|
|
Responses larger than ~5000 records are paginated. The response body includes a `nextLink` containing `$skiptoken=...` — follow it to fetch the next page. You don't need to construct `$skiptoken` yourself.
|
|
|
|
## Worked browser query
|
|
|
|
```
|
|
https://online.wonderware.com/s/ik97r5/apis/historian/v2/ProcessValues
|
|
?$filter=FQN+eq+'Baytown.tank_level'
|
|
+and+DateTime+gt+2017-07-13T00:00:00
|
|
&$top=200
|
|
```
|
|
|
|
Returns up to 200 raw VTQ records since the timestamp.
|
|
|
|
## Excel / Power BI hookups
|
|
|
|
The PDF chapter (pp. 232-240) walks through:
|
|
|
|
- **Excel** — `Data → Get Data → From Web`, paste the OData URL, sign in. Excel can refresh the connection on demand.
|
|
- **Postman** — pick GET, paste URL, set Auth (Basic for cloud / Negotiate for on-prem), Send.
|
|
- **Power BI** — `Get Data → OData feed`, paste the resource root (`.../v2/ProcessValues` or similar), authenticate, then build the report.
|
|
|
|
The shape of the data Power BI sees is identical to a JSON pull, so any aggregation you'd do in Power Query mirrors what `$filter` would have selected server-side.
|
|
|
|
## SSRS — Reporting Services extension
|
|
|
|
The **AVEVA Historian SQL Server Reporting Services Extension** lets SSRS report builders consume the same `INSQL` linked server queries documented in [`05-query-recipes.md`](05-query-recipes.md). PDF p. 241. Useful when the consumer is corporate reporting infrastructure rather than ad-hoc analysts.
|
|
|
|
## Errors
|
|
|
|
| Code | Meaning |
|
|
| --- | --- |
|
|
| 200 | OK with body. |
|
|
| 401 Unauthorized | Token expired / missing membership in the `aa*` Windows groups. |
|
|
| 404 Not Found | FQN doesn't exist, or solution / resource path wrong. |
|
|
| 5xx | Historian / Insight server-side issue. Retry with backoff. |
|
|
|
|
## Cross-references
|
|
|
|
- For the full property catalog of each resource, see PDF chapter "Browser-Friendly Data Retrieval" pp. 183-240.
|
|
- For SQL equivalents of every retrieval mode the REST API exposes, see [`03-retrieval-modes.md`](03-retrieval-modes.md).
|
|
- For options that map across (`Resolution` ↔ `wwResolution`, `RetrievalMode` ↔ `wwRetrievalMode`), see [`04-retrieval-options.md`](04-retrieval-options.md).
|