The HistoryUpdate Servicedefined in OPC 10000-4can perform several different functions. The historyUpdateDetailsparameter is an Extensible Parameterthat specifies which function to perform and the details that are specific to that function. See OPC 10000-4for the definition of Extensible Parameter. Table 31lists the symbolic names of the valid Extensible Parameterstructures. 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 Serviceperforms using the Extensible Parameterstructure UpdateDataDetailswith 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 DataValuedata 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 DataValuedata 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 DataValuedata type.

UpdateStructureDataDetails

Insert data

This function inserts new Structured History Dataor Annotationsinto 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 DataValuedata type.

UpdateStructureDataDetails

Replace data

This function replaces existing Structured History Dataor Annotationsinto 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 DataValuedata type.

UpdateStructureDataDetails

Update data

This function inserts or replaces Structured History Dataor Annotationsinto 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 DataValuedata type.

UpdateStructureDataDetails

Remove data

This function removes Structured History Dataor Annotationsfrom 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 DataValuedata type.

UpdateEventDetails

Insert events

This function inserts new Eventsinto the history database for one or more HistoricalEventNodes.

UpdateEventDetails

Replace events

This function replaces values of fields in existing Eventsinto the history database for one or more HistoricalEventNodes.

UpdateEventDetails

Update events

This function inserts new Eventsor replaces existing Eventsin 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 Eventsfrom the history database for the specified filter for one or more HistoricalEventNodes.

The HistoryUpdate Serviceis used to update or delete, DataValues, Annotationsor Events. For simplicity the term “entry” will be used to mean either DataValue, Annotation,or Eventdepending on the context in which it is used. Auditing requirements for History Servicesare described in OPC 10000-4. This description assumes the user issuing the request and the Serverthat is processing the request support the capability to update entries. See OPC 10000-3for a description of Attributesthat expose the support of Historical Updates.

If the HistoryUpdate Serviceis called with two or more of DataValues, Eventsor Annotationsin the same call the Serveroperational limits MaxNodesPerHistoryUpdateDataandMaxNodesPerHistoryUpdateEvents(See OPC 10000-5) may be ignored. The Servermay return the service result code Bad_TooManyOperationsif it is not able to handle the combination of DataValues, Events or Annotations. It is recommended to call the HistoryUpdate Serviceindividually with DataValues, EventsorAnnotations.

Table 32defines the UpdateDataDetails structure.

Table 32– UpdateDataDetails

Name

Type

Description

UpdateDataDetails

Structure

The details for insert, replace, and insert/replace history updates.

nodeId

NodeId

Node id of the Objectto be updated.

performInsertReplace

PerformUpdateType

Value determines which action of insert, replace, or update is performed.

Value

Description

INSERT_1

See 6.8.2.2.

REPLACE_2

See 6.8.2.3.

UPDATE_3

See 6.8.2.4.

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 StatusCodeshall 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 Timedoes 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 StatusCodeshall 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 Servercan create a modified valuefor 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 StatusCodefor an individual entry is allowed when the Serveris unable to say whether there was already a value at that timestamp. If the Servercan 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 Timedoes not fall within range that can be stored then the related operationResults entry shall indicate Bad_OutOfRange.

Table 32defines the UpdateStructureDataDetails structure.

Table 33– UpdateStructureDataDetails

Name

Type

Description

UpdateStructureDataDetails

Structure

The details for Structured Data History updates.

nodeId

NodeId

Node id of the Objectto be updated.

performInsertReplace

PerformUpdateType

Value determines which action of insert, replace, or update is performed.

Value

Description

INSERT_1

See 6.8.3.3.

REPLACE_2

See 6.8.3.4.

UPDATE_3

See 6.8.3.5.

REMOVE_4

See 6.8.3.6.

updateValues[]

DataValue

New values to be inserted, replaced or removed. Such as Annotationdata 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 Datastructure type. For example, a Server may only allow one Annotationper timestamp which means the timestamp is the unique key for the structure. Another Servermay allow Annotationsto 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 Dataexists’ and ‘at the specified parameters’ means a matching entry has been found at the specified timestamp using the Server’scriteria 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 Datasuch as Annotations into the history database at the specified parameters for one or more Propertiesof HistoricalDataNodes.

If a Structured History Dataentry already exists at the specified parameters the StatusCodeshall indicate Bad_EntryExists.

If the Timedoes not fall within range that can be stored then the related operationResults entry shall indicate Bad_OutOfRange.

Setting performInsertReplace = REPLACE_2 replaces Structured History Datasuch as Annotationsin the history database at the specified parameters for one or more Propertiesof HistoricalDataNodes.

If a Structured History Data entry does not already exist at the specified parameters, then the StatusCodeshall indicate Bad_NoEntryExists.

Setting performInsertReplace = UPDATE_3 inserts or replaces Structured History Datasuch as Annotationsin the history database at the specified parameters for one or more Propertiesof HistoricalDataNodes.

If a Structure History Dataentry already exists at the specified parameters then it is deleted and the value provided by the Clientis inserted. If no existing entry exists then the new entry is inserted.

If an existing entry was replaced successfully then the StatusCodeshall be Good_EntryReplaced. If a new entry was created the StatusCodeshall be Good_EntryInserted. If the Servercannot determine whether it replaced or inserted an entry then the StatusCodeshall be Good.

If the Timedoes not fall within range that can be stored then the related operationResults entry shall indicate Bad_OutOfRange.

Setting performInsertReplace = REMOVE_4 removes Structured History Datasuch as Annotationsfrom the history database at the specified parameters for one or more Propertiesof HistoricalDataNodes.

If a Structure History Dataentry exists at the specified parameters it is deleted. If Structured History Data does not already exist at the specified parameters, then the StatusCodeshall indicate Bad_NoEntryExists.

Table 34defines the UpdateEventDetails structure.

Table 34– UpdateEventDetails

Name

Type

Description

UpdateEventDetails

Structure

The details for insert, replace, and insert/replace history Eventupdates.

nodeId

NodeId

Node id of theObject to be updated.

performInsertReplace

PerformUpdateType

Value determines which action of insert, replace, or update is performed.

Value

Description

INSERT_1

Perform InsertEvent(see 6.8.4.2).

REPLACE_2

Perform Replace Event(see 6.8.4.3).

UPDATE_3

Perform Update Event(see 6.8.4.4).

REMOVE_4

Not used.

filter

EventFilter

If the history of Notificationconforms to the EventFilter, the history of the Notificationis updated.

eventData[]

HistoryEventFieldList

List of Event Notificationsto be inserted or updated (see 6.5.4for HistoryEventFieldList definition).

This function is intended to insert new entries, e.g., backfilling of historical Events.

Setting performInsertReplace = INSERT_1 inserts entries into the Eventhistory database for one or more HistoricalEventNodes. The whereClauseparameter of the EventFiltershall be empty. The SelectClauseshall as a minimum provide the following Event fields: EventTypeand Time. It is also recommended that the SourceNodeand the SourceNamefields are provided. If one of the required fields is not provided then the statusCodeshall indicate Bad_ArgumentsMissing. If the historian does not support archiving the specified EventTypethen the statusCodeshall indicate Bad_TypeDefinitionInvalid. If the SourceNodeis not a valid source for Eventsthen the related operationResults entry shall indicate Bad_SourceNodeIdInvalid. If the Timedoes not fall within range that can be stored then the related operationResults entry shall indicate Bad_OutOfRange. If the selectClausedoes not include fields which are mandatory for the EventType then thestatusCodeshall indicate Bad_ArgumentsMissing. If the selectClausespecifies fields which are not valid for the EventTypeor 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 DiagnosticInformationrelated 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 EventIdis a Servergenerated opaque value and a Clientcannot assume that it knows how to create valid EventIds. A Servershall be able to generate an appropriate default value for theEventIdfield. If a Clientdoes specify the EventIdin the selectClauseand it matches an existing Eventthen the statusCodeshall indicate Bad_EntryExists. A Clientshall use a HistoryReadto discover any automatically generated EventIds.

If any errors occur while processing individual fields then the related operationResults entry shall indicate Bad_InvalidArgumentand the invalid fields shall be indicated in the DiagnosticInformationrelated to the operationResults entry.

The IndexRangeparameter of the SimpleAttributeOperandis not valid for insert operations and the StatusCode shall specify Bad_IndexRangeInvalid if one is specified.

A Clientmay instruct the Serverto choose a suitable default value for a field by specifying a value of null. If the Serveris not able to select a suitable default then the corresponding entry in the operationResults array for the affected Eventshall be Bad_InvalidArgument.

This function is intended to replace fields in existing Evententries, e.g., correct Eventdata that contained incorrect data due to a bad sensor.

Setting performInsertReplace = REPLACE_2 replaces entries in the Eventhistory database for the specified EventIdsfor one or more HistoricalEventNodes. The SelectClauseparameter of the EventFiltershall specify the EventId Propertyand the eventDatashall contain the EventIdwhich will be used to find the Eventto be replaced. If no entry exists matching the specified EventIdthen no replace operation will be performed; instead the operationResults entryfor the eventDataentry shall indicate Bad_NoEntryExists. The whereClauseparameter of the EventFiltershall be empty.

If the selectClausespecifies fields which are not valid for the EventTypeor cannot be saved or changed by the historian then the operationResults entryfor the affected Eventshall indicate Good_DataIgnored. Additional information about the ignored fields shall be provided through DiagnosticInformationrelated 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 entryfor the affected Event shall indicate Bad_InvalidArgument and the invalid fields shall be indicated in the DiagnosticInformationrelated to the operationResults entry.

This function is intended to unconditionally insert/replace Events, e.g., synchronizing a backup Eventdatabase.

Setting performInsertReplace = UPDATE_3 inserts or replaces entries in the Eventhistory database for the specified filter for one or more HistoricalEventNodes.

The Serverwill, based on its own criteria, attempt to determine if the Eventalready exists; if it does exist then the Eventwill be deleted and the new Eventwill be inserted (retaining the EventId). If the EventIDwas provided then the EventIDwill be used to determine if the Eventalready exists. If the Eventdoes not exist then a new Eventwill 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 Evententry was replaced successfully then the related operationResults entry shall be Good_EntryReplaced. If a new Evententry was created then the related operationResults entryshall be Good_EntryInserted. If the Servercannot determine whether it replaced or inserted an entry then the related operationResults entryshall be Good.

Table 35defines 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 Objectfor 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 startTimeand endTimeshall be defined. The startTimeshall be less than the endTime, and values up to but not including the endTimeare deleted. It is permissible for startTime= endTime, in which case the value at the startTimeis deleted.

Setting isDeleteModified = FALSE deletes all Rawentries 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 StatusCodefor that item is Bad_NoData.

Setting isDeleteModified = TRUE deletes all Modifiedentries 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 StatusCodefor that item is Bad_NoData.

Table 36defines 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 Objectfor 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 37defines the structure of the DeleteEventDetails structure.

Table 37– DeleteEventDetails

Name

Type

Description

DeleteEventDetails

Structure

The details for delete raw and delete modified history updates.

nodeId

NodeId

Node id of the Objectfor which history values are to be deleted.

eventIds[]

ByteString

An array of EventIdsto identify which Eventsare to be deleted.

The DeleteEventDetails structure deletes all Evententries from the history database matching the EventIdfor one or more HistoricalEventNodes.

If no Events are found that match the specified filter for a HistoricalEventNode, then the StatusCodefor that Node is Bad_NoData.