lmxopcua/docs/HistoricalDataAccess.md

Historical Data Access

LmxNodeManager exposes OPC UA historical data access (HDA) by querying the Wonderware Historian Runtime database. The HistorianDataSource class translates OPC UA history requests into SQL queries against the Historian's History and AnalogSummaryHistory views, and the node manager overrides wire the results back into the OPC UA response.

Wonderware Historian Runtime Database

The Historian stores time-series data in a SQL Server database named Runtime. Two views are relevant:

• Runtime.dbo.History -- Raw historical samples with columns DateTime, Value (numeric), vValue (string), and Quality.
• Runtime.dbo.AnalogSummaryHistory -- Pre-computed aggregates bucketed by wwResolution (milliseconds), with columns like Average, Minimum, Maximum, ValueCount, First, Last, StdDev.

Both views require TagName in the WHERE clause. This is a Historian constraint -- the views are optimized for tag-scoped queries and do not support efficient cross-tag scans.

Configuration

HistorianConfiguration controls the historian connection:

public class HistorianConfiguration
{
    public bool Enabled { get; set; } = false;
    public string ConnectionString { get; set; } =
        "Server=localhost;Database=Runtime;Integrated Security=true;";
    public int CommandTimeoutSeconds { get; set; } = 30;
    public int MaxValuesPerRead { get; set; } = 10000;
}

When Enabled is false, the HistorianDataSource is not instantiated and the node manager returns BadHistoryOperationUnsupported for history read requests.

Raw Reads

HistorianDataSource.ReadRawAsync queries the History view for individual samples within a time range:

SELECT TOP (@MaxValues) DateTime, Value, vValue, Quality
FROM Runtime.dbo.History
WHERE TagName = @TagName
  AND DateTime >= @StartTime AND DateTime <= @EndTime
ORDER BY DateTime

The TOP clause is included only when maxValues > 0 (the OPC UA client specified NumValuesPerNode). Each row is converted to an OPC UA DataValue:

• Value column (double) takes priority over vValue (string). If both are null, the value is null.
• SourceTimestamp and ServerTimestamp are both set to the DateTime column.
• StatusCode is mapped from the Historian Quality byte via QualityMapper (the same OPC DA quality byte mapping used for live MXAccess data).

Aggregate Reads

HistorianDataSource.ReadAggregateAsync queries the AnalogSummaryHistory view for pre-computed aggregates:

SELECT StartDateTime, [{aggregateColumn}]
FROM Runtime.dbo.AnalogSummaryHistory
WHERE TagName = @TagName
  AND StartDateTime >= @StartTime AND StartDateTime <= @EndTime
  AND wwResolution = @Resolution
ORDER BY StartDateTime

The aggregateColumn is interpolated directly into the SQL (it comes from the controlled MapAggregateToColumn mapping, not from user input). The wwResolution parameter maps from the OPC UA ProcessingInterval in milliseconds.

Null aggregate values return BadNoData status rather than Good with a null variant.

Quality Mapping

The Historian stores standard OPC DA quality bytes, the same format used by MXAccess at runtime. The quality byte is passed through the shared QualityMapper pipeline (MapFromMxAccessQuality → MapToOpcUaStatusCode), which maps the OPC DA quality families to OPC UA status codes:

Historian Quality Byte	OPC DA Family	OPC UA StatusCode
0-63	Bad	Bad (with sub-code when an exact enum match exists)
64-191	Uncertain	Uncertain (with sub-code when an exact enum match exists)
192+	Good	Good (with sub-code when an exact enum match exists)

See Domain/QualityMapper.cs and Domain/Quality.cs for the full mapping table and sub-code definitions.

Aggregate Function Mapping

MapAggregateToColumn translates OPC UA aggregate NodeIds to Historian column names:

OPC UA Aggregate	Historian Column
AggregateFunction_Average	Average
AggregateFunction_Minimum	Minimum
AggregateFunction_Maximum	Maximum
AggregateFunction_Count	ValueCount
AggregateFunction_Start	First
AggregateFunction_End	Last
AggregateFunction_StandardDeviationPopulation	StdDev

Unsupported aggregates return null, which causes the node manager to return BadAggregateNotSupported.

HistoryReadRawModified Override

LmxNodeManager overrides HistoryReadRawModified to handle raw history read requests:

1. Resolve the NodeHandle to a tag reference via _nodeIdToTagReference. Return BadNodeIdUnknown if not found.
2. Check that _historianDataSource is not null. Return BadHistoryOperationUnsupported if historian is disabled.
3. Call ReadRawAsync with the time range and NumValuesPerNode from the ReadRawModifiedDetails.
4. Pack the resulting DataValue list into a HistoryData object and wrap it in an ExtensionObject for the HistoryReadResult.

var dataValues = _historianDataSource.ReadRawAsync(
    tagRef, details.StartTime, details.EndTime, maxValues)
    .GetAwaiter().GetResult();

var historyData = new HistoryData();
historyData.DataValues.AddRange(dataValues);
results[idx] = new HistoryReadResult
{
    StatusCode = StatusCodes.Good,
    HistoryData = new ExtensionObject(historyData)
};

HistoryReadProcessed Override

HistoryReadProcessed handles aggregate history requests with additional validation:

1. Resolve the node and check historian availability (same as raw).
2. Validate that AggregateType is present in the ReadProcessedDetails. Return BadAggregateListMismatch if empty.
3. Map the requested aggregate to a Historian column via MapAggregateToColumn. Return BadAggregateNotSupported if unmapped.
4. Call ReadAggregateAsync with the time range, ProcessingInterval, and column name.
5. Return results in the same HistoryData / ExtensionObject format.

Historizing Flag and AccessLevel

During variable node creation in CreateAttributeVariable, attributes with IsHistorized == true receive two additional settings:

if (attr.IsHistorized)
    accessLevel |= AccessLevels.HistoryRead;
variable.Historizing = attr.IsHistorized;

• Historizing = true -- Tells OPC UA clients that this node has historical data available.
• AccessLevels.HistoryRead -- Enables the HistoryRead access bit on the node, which the OPC UA stack checks before routing history requests to the node manager override. Nodes without this bit set will be rejected by the framework before reaching HistoryReadRawModified or HistoryReadProcessed.

The IsHistorized flag originates from the Galaxy repository database query, which checks whether the attribute has Historian logging configured.