Historical Access

The WinCC OA OPC UA server provides clients with access to historical data by supporting the OPC UA Historical Access functionality.

Tip:

Supported types of historical access:

  • Data Access
  • Alarms and Conditions

The historical data is provided by adding historical nodes/notifiers to the server address space. This chapter describes how to enable the historical access.

Server address space

The address space of the WinCC OA OPC UA server is defined via the OPCUARead, OPCUAWrite, OPCUAAlarm and OPCUAEvent groups (refer to Access to WinCC OA Data and Historical Access for further information). Each data point element assigned to one of these groups is represented by an appropriate element in the address space.

To define for which of these elements the Historical Access functionality shall be enabled, you have to additionally assign the appropriate data point elements to the OPCUAHARead data point group. This means that historical access is only enabled for data point elements that are defined both in OPCUARead/OPCUAWrite/OPCUAAlarm/OPCUAEvent as well as OPCUAHARead. Data point elements which are only defined in the OPCUAHARead group are ignored by the server.

In addition, you have to add an _archive config to data point elements for which historical data shall be read (refer to the History DB or RDB archiving chapters for further information).

For historical alerts no _archive config is needed, because the alerts are saved in the historical database if it is configured in the alert class. For historical base events, the triggering dyn_string DPE must have an _archive config, otherwise the historical events cannot be retrieved from the database.

Note:
You can change the data point group (default: OPCUAHARead) which shall be used for the OPC UA servers historical data via the config entry [opcuasrv] opcuaHAReadGroup.

Historical data access

Supported data types

Refer to Data Exchange - mapping of data types for a detailed list of data types supported by the WinCC OA OPC UA server. With the exception of LocalizedTextandBlob, historical access is available for all stated data types.

Example

  1. Create the appropriate data point elements which shall be mapped to the address space. For this example, the data point elements Node1, Node2 and Node3 were created.
  2. Add an _archive (Archiving) config to the data point elements for which historical access shall be available (in this example: Node1).
  3. Assign the data point elements (Node1, Node2, Node3) to OPCUARead or OPCUAWrite and thus to the server address space.
  4. Assign the necessary data point elements (Node1) to OPCUAHARead. This means that access to historical data is only possible for this data point element.
  5. Start the WinCC OA OPC UA server. Historical data of Node1 can be queried by OPC UA clients. OPC UA server. Historical data of Node1 can be queried by OPC UA clients.
Note:
Using the [opcuasrv] historyNumValuesPerNode config entry you can define the maximum number of values the server provides per readRaw request.

Retrieve data from the server

The WinCC OA OPC UA server supports the readRaw function. Therefore, OPC UA clients can use this function to retrieve data from the WinCC OA OPC UA server. It is possible to query several items with one readRaw call.

The readRaw function provides the following parameters:

continuationPoint
The continuation point data from a previous Read call.
timestampsToReturn
The client selected timestamp to return. Source, Server or both.
numValuesPerNode
The maximum number of values per node to return.
startTime
The start time of the time period to read.
endTime
The end time of the time period to read.
returnBounds
Flag that indicates if bounding values should be returned.
Note:
The WinCC OA OPC UA client also uses this function to retrieve historical values from a server. Refer to OPC UA Client - Historical Access and _OPCUA.Command.HistoryRead for further information on using the readRaw function. For a detailed description of the readRaw functionality please refer to the OPC UA standard.

Continuation point

The continuation point is handled by the server. If the number of returned elements is bigger than the value specified by the client, the continuation point must be used. The data is cached by the server. If the remaining data is requested by the client using the corresponding continuation point, the server memory is used to get the rest of the data. Therefore, no additional query is necessary.

Historical alarms and conditions

Supported alert types

Every configuration ins supported by the alarms and conditions feature is also supported for the historical alarms and conditions (see Historical Access).

Example

  1. Create the appropriate data point elements which shall be mapped to the address space and configure an valid alert handle on it. For this example, the boolean DPE Alarm_CameAndWent.boolean of the DPT TestUAAlarmServer was created and an _alert_hdl with an alert class "CAME or WENT must be acknowledged" was configured.

  2. Assign the data point element (Alarm_CameAndWent.boolean) to the OPCUAAlarm and OPCUAHARead DpGroup.

  3. Now use the UaExpert to connect to the server, add the EventView and Drag'n'Drop the Server -> TestUAAlarmServer_@notifier Notifier node into the Configuration.

    Figure 1. UaExpert - Event Notifier Configuration Export
  4. Now trigger the following scenario on the DPE Alarm_CameAndWent.boolean:
    • CAME
    • ACKNOWLEDGE
    • WENT
    • ACKNOWLEDGE
    In the UaExpert the following received events can be seen:
    Figure 2. UaExpert - Received Events Export
    Explanation to the received lines (for a detailed information what ActiveState, AckedState, BranchId and Retain is, please take a look at the OPC UA Specification):
    1. The line for the "came" event triggered by the CAME event of the alert (ActiveState=true, AckedState=false, Retain=true, BranchId=null)
    2. The line for the "acked came" event triggered by the acknowledgement of the CAME (ActiveState=true, AckedState=true, Retain=true, BranchId=null)
    3. The line for the "went" event triggered by the WENT event of the alert (ActiveState=false, AckedState=false, Retain=true, BranchId=null)
    4. The line for the "acked came" event in a new branch triggered by the WENT event of the alert (ActiveState=true, AckedState=true, Retain=true, BranchId=UUID)
    5. The line for the "acked came" event in the branch triggered by the acknowledgement of the WENT (ActiveState=true, AckedState=true, Retain=false, BranchId=UUID)
    6. The line for the "acked went" event triggered by the acknowledgement of the WENT (ActiveState=false, AckedState=true, Retain=false, BranchId=null)

  5. Now trigger a historical event query in the UaExpert for the time-range of the example above. In the UaExpert the following received historical events can be seen:

    Figure 3. UaExpert - Historical Events Export

Using the [opcuasrv] historyNumValuesPerNode config entry you can define the maximum number of values the server provides per readEvents request.

Retrieve data from the server

The WinCC OA OPC UA server supports the readEvents function. Therefore, OPC UA clients can use this function to retrieve historical events from the WinCC OA OPC UA server. It is possible to query several items with one readEvents call. Since OPC UA Alarms are also OPC UA Events, the alarms are also received using the readEvents function.

The readEvents function provides the following parameters:

continuationPoint
The continuation point data from a previous Read call.
numValuesPerNode
The maximum number of values per node to return.
startTime
The start time of the time period to read.
endTime
The end time of the time period to read.
filter
The wanted attributes of the historical events
Restriction:
Only the SelectClauses are supported, WhereClauses are not supported at the moment.

Continuation point

The continuation point is handled by the server. If the number of returned events is bigger than the value specified by the client, the continuation point must be used. The events are cached by the server. If the remaining events are requested by the client using the corresponding continuation point, the server memory is used to get the rest of the events. Therefore, no additional query is necessary.