6.9 HistoryUpdateDetails parameter
6.9.1 Overview
The HistoryUpdate Service defined in OPC 10000-4 can perform several different functions. The historyUpdateDetails parameter is an Extensible Parameter that specifies which function to perform and the details that are specific to that function. See OPC 10000-4 for the definition of Extensible Parameter. Table 61 lists the symbolic names of the valid Extensible Parameter structures. Some structures will perform different functions based on the setting of its associated parameters. For simplicity a functionality of each structure is listed. For example, text such as ‘using the Replace data functionality’ refers to the function the HistoryUpdate Service performs using the Extensible Parameter structure UpdateDataDetails with the performInsertReplace enumeration parameter set to REPLACE.
| Symbolic Name | Functionality | Description |
|---|---|---|
| UpdateDataDetails | Insert data | This function inserts new values into the history database at the specified timestamps for one or more HistoricalDataNodes The Variable’s value is represented by a composite value defined by the DataValue data type. |
| UpdateDataDetails | Replace data | This function replaces existing values into the history database at the specified timestamps for one or more HistoricalDataNodes. The Variable’s value is represented by a composite value defined by the DataValue data type. |
| UpdateDataDetails | Update data | This function inserts or replaces values into the history database at the specified timestamps for one or more HistoricalDataNodes. The Variable’s value is represented by a composite value defined by the DataValue data type. |
| UpdateStructureDataDetails | Insert data | This function inserts new StructuredHistoryData or Annotations into the history database at the specified timestamps for one or more HistoricalDataNodes. The Variable’s value is represented by a composite value defined by the DataValue data type. |
| UpdateStructureDataDetails | Replace data | This function replaces existing StructuredHistory Data or Annotations into the history database at the specified timestamps for one or more HistoricalDataNodes. The Variable’s value is represented by a composite value defined by the DataValue data type. |
| UpdateStructureDataDetails | Update data | This function inserts or replaces StructuredHistoryData or Annotations into the history database at the specified timestamps for one or more HistoricalDataNodes. The Variable’s value is represented by a composite value defined by the DataValue data type. |
| UpdateStructureDataDetails | Remove data | This function removes StructuredHistoryData or Annotations from the history database at the specified timestamps for one or more HistoricalDataNodes. The Variable’s value is represented by a composite value defined by the DataValue data type. |
| UpdateEventDetails | Insert events | This function inserts new Events into the history database for one or more HistoricalEventNodes. |
| UpdateEventDetails | Replace events | This function replaces values of fields in existing Events into the history database for one or more HistoricalEventNodes. |
| UpdateEventDetails | Update events | This function inserts new Events or replaces existing Events in the history database for one or more HistoricalEventNodes. |
| DeleteRawModifiedDetails | Delete raw | This function deletes all values from the history database for the specified time domain for one or more HistoricalDataNodes. |
| DeleteRawModifiedDetails | Delete modified | Some historians can store multiple values at the same Timestamp. This function will delete specified values and qualities for the specified timestamp for one or more HistoricalDataNodes. |
| DeleteAtTimeDetails | Delete at time | This function deletes all values in the history database for the specified timestamps for one or more HistoricalDataNodes. |
| DeleteEventDetails | Delete event | This function deletes Events from the history database for the specified filter for one or more HistoricalEventNodes. |
The HistoryUpdate Service is used to update or delete, DataValues, Annotations or Events. For simplicity the term “entry” will be used to mean either DataValue, Annotation, or Event depending on the context in which it is used. Auditing requirements for History Services are described in OPC 10000-4. This description assumes the user issuing the request and the Server that is processing the request support the capability to update entries. See OPC 10000-3 for a description of Attributes that expose the support of Historical Updates.
If the HistoryUpdate Service is called with two or more of DataValues, Events or Annotations in the same call the Server operational limits MaxNodesPerHistoryUpdateData and MaxNodesPerHistoryUpdateEvents (defined in OPC 10000-5) can be ignored. The Server can return the service result code Bad_TooManyOperations if it is not able to handle the combination of DataValues, Events or Annotations. It is recommended to call the HistoryUpdate Service individually with DataValues, Events or Annotations.
Table 62 defines the HistoryUpdateDetails structure.
| Name | Type | Description |
|---|---|---|
| HistoryUpdateDetails | Structure | |
Its representation in the AddressSpace is defined in Table 63.
| Attribute | Value | |||||
| BrowseName | HistoryUpdateDetails | |||||
| IsAbstract | True | |||||
| References | NodeClass | BrowseName | DataType | TypeDefinition | Other | |
|---|---|---|---|---|---|---|
| Subtype of the Structure DataType defined in OPC 10000-3 | ||||||
| Conformance Units | ||||||
|---|---|---|---|---|---|---|
| Historical Access Update Value |
6.9.2 UpdateDataDetails structure
6.9.2.1 UpdateDataDetails structure details
Table 64 defines the UpdateDataDetails structure.
| Name | Type | Description |
|---|---|---|
| UpdateDataDetails | Structure | The details for insert, replace, and insert/replace history updates. |
nodeId | NodeId | Node id of the Object to be updated. |
performInsertReplace | PerformUpdateType | This enumeration determines which action of Insert, Replace, or Update is performed. The Delete enumerated value is not allowed and will result in a Bad_InvalidArgument error. |
updateValues[] | DataValue | New values to be inserted or to replace. |
Its representation in the AddressSpace is defined in Table 65.
| Attribute | Value | |||||
| BrowseName | UpdateDataDetails | |||||
| IsAbstract | False | |||||
| References | NodeClass | BrowseName | DataType | TypeDefinition | Other | |
|---|---|---|---|---|---|---|
| Subtype of the HistoryUpdateDetails DataType defined in Table 62. | ||||||
| Conformance Units | ||||||
|---|---|---|---|---|---|---|
| Historical Access Insert Value | ||||||
| Historical Access Delete Value | ||||||
| Historical Access Update Value | ||||||
| Historical Access Replace Value | ||||||
6.9.2.2 Insert data functionality
Setting performInsertReplace = INSERT inserts entries into the history database at the specified timestamps for one or more HistoricalDataNodes. If an entry exists at the specified timestamp, then the new entry shall not be inserted; instead the StatusCode shall indicate Bad_EntryExists.
This function is intended to insert new entries at the specified timestamps, e.g., the insertion of lab data to reflect the time of data collection.
If the Time does not fall within range that can be stored then the related operationResults entry shall indicate Bad_OutOfRange.
6.9.2.3 Replace data functionality
Setting performInsertReplace = REPLACE replaces entries in the history database at the specified timestamps for one or more HistoricalDataNodes. If no entry exists at the specified timestamp, then the new entry shall not be inserted; otherwise, the StatusCode shall indicate Bad_NoEntryExists.
This function is intended to replace existing entries at the specified timestamp, e.g., correct lab data that was improperly processed, but inserted into the history database.
6.9.2.4 Update data functionality
Setting performInsertReplace = UPDATE inserts or replaces entries in the history database for the specified timestamps for one or more HistoricalDataNodes. If the item has an entry at the specified timestamp, then the new entry will replace the old one. If there is no entry at that timestamp, then the function will insert the new data.
A Server can create a modified value for a value being replaced or inserted (see 3.1.7) however it is not required.
This function is intended to unconditionally insert/replace values and qualities, e.g., correction of values for bad sensors.
Good as a StatusCode for an individual entry is allowed when the Server is unable to say whether there was already a value at that timestamp. If the Server can determine whether the new entry replaces an entry that was already there, then it should use Good_EntryInserted or Good_EntryReplaced to return that information.
If the Time does not fall within range that can be stored then the related operationResults entry shall indicate Bad_OutOfRange.
6.9.3 UpdateStructureDataDetails structure
6.9.3.1 UpdateStructureDataDetails structure details
Table 64 defines the UpdateStructureDataDetails structure.
| Name | Type | Description |
|---|---|---|
| UpdateStructureDataDetails | Structure | The details for Structured Data History updates. |
nodeId | NodeId | Node id of the Object to be updated. |
performInsertReplace | PerformUpdateType | Value determines which action of insert, replace, or update is performed. |
updateValues[] | DataValue | New values to be inserted, replaced or removed. Such as Annotation data for Annotations. |
Its representation in the AddressSpace is defined in Table 67.
| Attribute | Value | |||||
| BrowseName | UpdateStructureDataDetails | |||||
| IsAbstract | False | |||||
| References | NodeClass | BrowseName | DataType | TypeDefinition | Other | |
|---|---|---|---|---|---|---|
| Subtype of the HistoryUpdateDetails DataType defined in Table 62. | ||||||
| Conformance Units | ||||||
|---|---|---|---|---|---|---|
| Historical Access Structured Data Replace | ||||||
| Historical Access Structured Data Update | ||||||
| Historical Access Structured Data Insert |
6.9.3.2 Specified Uniqueness of StructuredHistoryData
StructuredHistoryData provides metadata describing an entry in the history database. The Server shall define what uniqueness means for each StructuredHistoryData structure type. For example, a Server can only allow one Annotation per timestamp which means the timestamp is the unique key for the structure. Another Server can allow Annotations to exist per user, so a combination of a username and timestamp can be used as the unique key for the structure. In 6.8.3.3, 6.8.3.4, 6.8.3.5, and 6.8.3.6 the terms ‘StructuredHistoryData exists’ and ‘at the specified parameters’ means a matching entry has been found at the specified timestamp using the Server’s criteria for uniqueness.
In the case where the Client wishes to replace a parameter that is part of the uniqueness criteria, then the resulting StatusCode would be Bad_NoEntryExists. The Client shall remove the existing structure and then Insert the new structure.
6.9.3.3 Insert functionality
Setting performInsertReplace = INSERT inserts StructuredHistoryData such as Annotations into the history database at the specified parameters for one or more Properties of HistoricalDataNodes.
If a StructuredHistoryData entry already exists at the specified parameters the StatusCode shall indicate Bad_EntryExists.
If the Time does not fall within range that can be stored then the related operationResults entry shall indicate Bad_OutOfRange.
6.9.3.4 Replace functionality
Setting performInsertReplace = REPLACE replaces StructuredHistoryData such as Annotations in the history database at the specified parameters for one or more Properties of HistoricalDataNodes.
If a StructuredHistoryData entry does not already exist at the specified parameters, then the StatusCode shall indicate Bad_NoEntryExists.
6.9.3.5 Update functionality
Setting performInsertReplace = UPDATE inserts or replaces StructuredHistoryData such as Annotations in the history database at the specified parameters for one or more Properties of HistoricalDataNodes.
If a StructureHistoryData entry already exists at the specified parameters then it is deleted and the value provided by the Client is inserted. If no existing entry exists then the new entry is inserted.
If an existing entry was replaced successfully then the StatusCode shall be Good_EntryReplaced. If a new entry was created the StatusCode shall be Good_EntryInserted. If the Server cannot determine whether it replaced or inserted an entry then the StatusCode shall be Good.
If the Time does not fall within range that can be stored then the related operationResults entry shall indicate Bad_OutOfRange.
6.9.3.6 Remove functionality
Setting performInsertReplace = REMOVE removes StructuredHistoryData such as Annotations from the history database at the specified parameters for one or more Properties of HistoricalDataNodes.
If a Structure History Data entry exists at the specified parameters it is deleted. If StructuredHistoryData does not already exist at the specified parameters, then the StatusCode shall indicate Bad_NoEntryExists.
6.9.4 UpdateEventDetails structure
6.9.4.1 UpdateEventDetails structure detail
Table 68 defines the UpdateEventDetails structure.
| Name | Type | Description |
|---|---|---|
| UpdateEventDetails | Structure | The details for insert, replace, and insert/replace history Event updates. |
nodeId | NodeId | Node id of the Object to be updated. |
performInsertReplace | PerformUpdateType | Value determines which action of insert, replace, or update is performed. The Delete enumeration value is not allow and will result in a Bad_InvalidArgument error. |
filter | EventFilter | If the history of Notification conforms to the EventFilter, the history of the Notification is updated. |
eventData[] | HistoryEventFieldList | List of Event Notifications to be inserted or updated (see 6.6.4 for HistoryEventFieldList definition). |
Its representation in the AddressSpace is defined in Table 69.
| Attribute | Value | |||||
| BrowseName | UpdateEventDetails | |||||
| IsAbstract | False | |||||
| References | NodeClass | BrowseName | DataType | TypeDefinition | Other | |
|---|---|---|---|---|---|---|
| Subtype of the HistoryUpdateDetails DataType defined in Table 62. | ||||||
| Conformance Units | ||||||
|---|---|---|---|---|---|---|
| Historical Access Replace Event | ||||||
| Historical Access Update Event | ||||||
| Historical Access Insert Event |
6.9.4.2 Insert event functionality
This function is intended to insert new entries, e.g., backfilling of historical Events.
Setting performInsertReplace = INSERT inserts entries into the Event history database for one or more HistoricalEventNodes. The whereClause parameter of the EventFilter shall be empty. The selectClause shall, as a minimum, provide the following Event fields: EventType, and Time. It is also recommended that the SourceNode and the SourceName fields are provided.
If one of the required fields is not provided then the statusCode shall indicate Bad_ArgumentsMissing. If the historian does not support archiving the specified EventType then the statusCode shall indicate Bad_TypeDefinitionInvalid. If the SourceNode is not a valid source for Events then the related operationResults entry shall indicate Bad_SourceNodeIdInvalid. If the Time does not fall within a range that can be stored then the related operationResults entry shall indicate Bad_OutOfRange. The selectClause shall include all mandatory fields that are configured to be stored for the EventType. If the selectClause does not include a mandatory field then the statusCode shall indicate Bad_ArgumentsMissing. If the selectClause specifies fields which are not valid for the EventType or cannot be saved by the Historian then the related operationResults entry shall indicate Good_DataIgnored. Additional information about the ignored fields shall be provided through DiagnosticInformation related to the operationResults. The symbolicId contains the index of each ignored field separated with a space and the localizedText contains the symbolic names of the ignored fields.
The EventId is a Server generated opaque value and a Client cannot assume that it knows how to create unique EventIds. A Server shall automatically generate an EventId when not provided by the Client. If a Client does specify the EventId in the selectClause and it matches an existing EventId then the statusCode shall indicate Bad_EntryExists.
If any errors occur while processing individual fields then the related operationResults entry shall indicate Bad_InvalidArgument and the invalid fields shall be indicated in the DiagnosticInformation related to the operationResults entry.
The IndexRange parameter of the SimpleAttributeOperand is not valid for insert operations and the StatusCode shall specify Bad_IndexRangeInvalid if one is specified.
A Client can instruct the Server to choose a suitable default value for a field by specifying a value of null. If the Server is not able to select a suitable default then the corresponding entry in the operationResults array for the affected Event shall be Bad_InvalidArgument.
6.9.4.3 Replace event functionality
This function is intended to replace fields in existing Event entries, e.g., correct Event data that contained incorrect data due to a bad sensor.
Setting performInsertReplace = REPLACE replaces entries in the Event history database for the specified EventIds for one or more HistoricalEventNodes. The selectClause parameter of the EventFilter shall specify the EventId Property and the eventData shall contain the EventId which will be used to find the Event to be replaced. If no entry exists matching the specified EventId then no replace operation will be performed; instead, the operationResults entry for the eventData entry shall indicate Bad_NoEntryExists. The whereClause parameter of the EventFilter shall be empty.
If the selectClause specifies fields which are not valid for the EventType or cannot be saved or changed by the historian then the operationResults entry for the affected Event shall indicate Good_DataIgnored. Additional information about the ignored fields shall be provided through DiagnosticInformation related to the operationResults. The symbolicId contains the index of each ignored field separated with a space and the localizedText contains the symbolic names of the ignored fields.
If fatal errors occur while processing individual fields then the operationResults entry for the affected Event shall indicate Bad_InvalidArgument and the invalid fields shall be indicated in the DiagnosticInformation related to the operationResults entry.
6.9.4.4 Update event functionality
This function is intended to unconditionally insert/replace Events.
Setting performInsertReplace = UPDATE inserts or replaces entries in the Event history database for the specified filter for one or more HistoricalEventNodes.
The Server will, based on its own criteria, attempt to determine if the Event already exists; if it does exist then the Event will be deleted and the new Event will be inserted (retaining the EventId). If the EventID was provided then the EventID will be used to determine if the Event already exists. If the Event does not exist then a new Event will be inserted, including the generation of a new EventId, if the provided EventId does not match the unique requirements in the Server for EventIds.
All of the restrictions, behaviours, and errors specified for the Insert functionality (see 6.9.4.2) also apply to this function.
If an existing Event entry was replaced successfully then the related operationResults entry shall be Good_EntryReplaced. If a new Event entry was created then the related operationResults entry shall be Good_EntryInserted. If the Server cannot determine whether it replaced or inserted an entry then the related operationResults entry shall be Good.
6.9.5 DeleteRawModifiedDetails structure
6.9.5.1 DeleteRawModifiedDetails structure detail
Table 70 defines the DeleteRawModifiedDetails structure.
| Name | Type | Description |
|---|---|---|
| DeleteRawModifiedDetails | Structure | The details for delete raw and delete modified history updates. |
nodeId | NodeId | Node id of the Object for which history values are to be deleted. |
isDeleteModified | Boolean | TRUE for MODIFIED, FALSE for RAW. Default value is FALSE. |
startTime | UtcTime | Beginning of period to be deleted. |
endTime | UtcTime | End of period to be deleted. |
Its representation in the AddressSpace is defined in Table 71.
| Attribute | Value | |||||
| BrowseName | DeleteRawModifiedDetails | |||||
| IsAbstract | False | |||||
| References | NodeClass | BrowseName | DataType | TypeDefinition | Other | |
|---|---|---|---|---|---|---|
| Subtype of the HistoryUpdateDetails DataType defined in Table 62. | ||||||
| Conformance Units | ||||||
|---|---|---|---|---|---|---|
| Historical Access Delete Value |
These functions are intended to be used to delete data that has been accidentally entered into the history database, e.g., deletion of data from a source with incorrect timestamps. Both startTime and endTime shall be defined. The startTime shall be less than the endTime, and values up to but not including the endTime are deleted. It is permissible for startTime = endTime, in which case the value at the startTime is deleted.
6.9.5.2 Delete raw functionality
Setting isDeleteModified = FALSE deletes all Raw entries from the history database for the specified time domain for one or more HistoricalDataNodes.
If no data is found in the time range for a particular HistoricalDataNode, then the StatusCode for that item is Bad_NoData.
6.9.5.3 Delete modified functionality
Setting isDeleteModified = TRUE deletes all Modified entries from the history database for the specified time domain for one or more HistoricalDataNodes.
If no data is found in the time range for a particular HistoricalDataNode, then the StatusCode for that item is Bad_NoData.
6.9.6 DeleteAtTimeDetails structure
6.9.6.1 DeleteAtTimeDetails structure detail
Table 72 defines the structure of the DeleteAtTimeDetails structure.
| Name | Type | Description |
|---|---|---|
| DeleteAtTimeDetails | Structure | The details for delete raw history updates. |
nodeId | NodeId | Node id of the Object for which history values are to be deleted. |
reqTimes [] | UtcTime | The entries define the specific timestamps for which values are to be deleted. |
Its representation in the AddressSpace is defined in Table 30.
| Attribute | Value | |||||
| BrowseName | DeleteAtTimeDetails | |||||
| IsAbstract | False | |||||
| References | NodeClass | BrowseName | DataType | TypeDefinition | Other | |
|---|---|---|---|---|---|---|
| Subtype of the HistoryUpdateDetails DataType defined in Table 62. | ||||||
| Conformance Units | ||||||
|---|---|---|---|---|---|---|
| Historical Access Delete Value |
6.9.6.2 Delete at time functionality
The DeleteAtTime structure deletes all raw values, ModifiedValues, and Annotations in the history database for the specified timestamps for one or more HistoricalDataNodes.
This parameter is intended to be used to delete specific data from the history database, e.g., lab data that is incorrect and cannot be correctly reproduced.
6.9.7 DeleteEventDetails structure
6.9.7.1 DeleteEventDetails structure detail
Table 74 defines the structure of the DeleteEventDetails structure.
| Name | Type | Description |
|---|---|---|
| DeleteEventDetails | Structure | The details for delete raw and delete modified history updates. |
nodeId | NodeId | Node id of the Object for which history values are to be deleted. |
eventIds [] | ByteString | An array of EventIds to identify which Events are to be deleted. |
Its representation in the AddressSpace is defined in Table 30.
| Attribute | Value | |||||
| BrowseName | DeleteEventDetails | |||||
| IsAbstract | False | |||||
| References | NodeClass | BrowseName | DataType | TypeDefinition | Other | |
|---|---|---|---|---|---|---|
| Subtype of the HistoryUpdateDetails DataType defined in Table 62. | ||||||
| Conformance Units | ||||||
|---|---|---|---|---|---|---|
| Historical Access Delete Event |
6.9.7.2 Delete event functionality
The DeleteEventDetails structure deletes all Event entries from the history database matching the EventId for one or more HistoricalEventNodes.
If no Events are found that match the specified filter for a HistoricalEventNode, then the StatusCode for that Node is Bad_NoData.