Errata exists for this version of the document.
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 31 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_2.
Table 31 – HistoryUpdateDetails parameter TypeIds
|
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 Structured History 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 |
Replace data |
This function replaces existing Structured History 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 Structured History 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 |
Remove data |
This function removes Structured History Data 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 may 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 (See OPC 10000-5) may be ignored. The Server may 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 32 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 |
Value determines which action of insert, replace, or update is performed.
|
||||||||
|
updateValues[] |
DataValue |
New values to be inserted or to replace. |
Setting performInsertReplace = INSERT_1 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.
Setting performInsertReplace = REPLACE_2 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.
Setting performInsertReplace = UPDATE_3 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.6) 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.
Table 32 defines the UpdateStructureDataDetails structure.
Table 33 – UpdateStructureDataDetails
|
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. |
Structured History Data provides metadata describing an entry in the history database. The Server shall define what uniqueness means for each Structured History Data structure type. For example, a Server may only allow one Annotation per timestamp which means the timestamp is the unique key for the structure. Another Server may allow Annotations to exist per user, so a combination of a username and timestamp may 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 ‘Structured History Data 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.
Setting performInsertReplace = INSERT_1 inserts Structured History Data such as Annotations into the history database at the specified parameters for one or more Properties of HistoricalDataNodes.
If a Structured History Data 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.
Setting performInsertReplace = REPLACE_2 replaces Structured History Data such as Annotations in the history database at the specified parameters for one or more Properties of HistoricalDataNodes.
If a Structured History Data entry does not already exist at the specified parameters, then the StatusCode shall indicate Bad_NoEntryExists.
Setting performInsertReplace = UPDATE_3 inserts or replaces Structured History Data such as Annotations in the history database at the specified parameters for one or more Properties of HistoricalDataNodes.
If a Structure History Data 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.
Setting performInsertReplace = REMOVE_4 removes Structured History Data 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 Structured History Data does not already exist at the specified parameters, then the StatusCode shall indicate Bad_NoEntryExists.
Table 34 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.
|
||||||||||
|
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.5.4 for HistoryEventFieldList definition). |
This function is intended to insert new entries, e.g., backfilling of historical Events.
Setting performInsertReplace = INSERT_1 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 range that can be stored then the related operationResults entry shall indicate Bad_OutOfRange. If the selectClause does not include fields which are mandatory for the EventType 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 valid EventIds. A Server shall be able to generate an appropriate default value for the EventId field. If a Client does specify the EventId in the selectClause and it matches an existing Event then the statusCode shall indicate Bad_EntryExists. A Client shall use a HistoryRead to discover any automatically generated EventIds.
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 may 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.
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_2 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.
This function is intended to unconditionally insert/replace Events, e.g., synchronizing a backup Event database.
Setting performInsertReplace = UPDATE_3 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.
All of the restrictions, behaviours, and errors specified for the Insert functionality (see 6.8.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.
Table 35 defines the DeleteRawModifiedDetails structure.
Table 35 – DeleteRawModifiedDetails
|
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. |
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.
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.
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.
Table 36 defines the structure of the DeleteAtTimeDetails structure.
Table 36 – DeleteAtTimeDetails
|
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. |
The DeleteAtTime structure deletes all raw values, modified values, 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.
Table 37 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. |
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.