The CreateMonitoredItem Service allows specifying a filter for each MonitoredItem. The MonitoringFilter is an extensible parameter whose structure depends on the type of item being monitored. The parameterTypeIds are defined in Table 145. Other types can be defined by additional parts of this multi-part specification or other specifications based on OPC UA. The ExtensibleParameter type is defined in 7.17.

Each MonitoringFilter may have an associated MonitoringFilterResult structure which returns revised parameters and/or error information to Clients in the response. The result structures, when they exist, are described in the section that defines the MonitoringFilter.

Table 145 – MonitoringFilter parameterTypeIds

Symbolic Id

Description

DataChangeFilter

The change in a data value that shall cause a Notification to be generated.

EventFilter

If a Notification conforms to the EventFilter, the Notification is sent to the Client.

AggregateFilter

The Aggregate and its intervals when it will be calculated and a Notification is generated.

The DataChangeFilter defines the conditions under which a DataChange Notification should be reported and, optionally, a range or band for value changes where no DataChange Notification is generated. This range is called Deadband. The DataChangeFilter is defined in Table 146.

Table 146 – DataChangeFilter

Name

Type

Description

DataChangeFilter

structure

trigger

Enum

DataChangeTrigger

Specifies the conditions under which a data change notification should be reported. The DataChangeTrigger enumeration is defined in 7.10.

If the DataChangeFilter is not applied to the monitored item, STATUS_VALUE is the default reporting behaviour.

deadbandType

UInt32

A value that defines the Deadband type and behaviour.

ValueNameDescription

0 NoneNo Deadband calculation should be applied.

1 AbsoluteAbsoluteDeadband (see below)

2 PercentPercentDeadband (This type is specified in OPC 10000-8).

deadbandValue

Double

The Deadband is applied only if* the trigger includes value changes and* the deadbandType is set appropriately.

Deadband is ignored if the status of the data item changes.

DeadbandType = AbsoluteDeadband:

For this type the deadbandValue contains the absolute change in a data value that shall cause a Notification to be generated. This parameter applies only to Variables with any Number data type.

An exception that causes a DataChange Notification based on an AbsoluteDeadband is determined as follows:

Generate a Notification if (absolute value of (last cached value - current value) > AbsoluteDeadband)

The last cached value is defined as the last value pushed to the queue.

If the item is an array of values, the entire array is returned if any array element exceeds the AbsoluteDeadband, or the size or dimension of the array changes.

DeadbandType = PercentDeadband:

This type is specified in OPC 10000-8

The DataChangeFilter does not have an associated result structure.

The EventFilter provides for the filtering and content selection of Event Subscriptions.

If an Event Notification conforms to the filter defined by the where parameter of the EventFilter, then the Notification is sent to the Client.

Each Event Notification shall include the fields defined by the selectClauses parameter of the EventFilter. The defined EventTypes are specified in OPC 10000-5.

The selectClauses and whereClause parameters are specified with the SimpleAttributeOperand structure (see 7.7.4.5). This structure requires the NodeId of an EventType supported by the Server and a path to an InstanceDeclaration. An InstanceDeclaration is a Node which can be found by following forward hierarchical references from the fully inherited EventType where the Node is also the source of a HasModellingRule reference. EventTypes, InstanceDeclarations and Modelling Rules are described completely in OPC 10000-3.

In some cases the same SimpleAttributeOperand.browsePath will apply to multiple EventTypes. If the Client specifies the BaseEventType in the SimpleAttributeOperand.typeDefinitionId then the Server shall evaluate the SimpleAttributeOperand.browsePath without considering the SimpleAttributeOperand.typeDefinitionId.

Each InstanceDeclaration in the path shall be Object or Variable Node. The final Node in the path may be an Object Node; however, Object Nodes are only available for Events which are visible in the Server’s AddressSpace.

The SimpleAttributeOperand structure allows the Client to specify any Attribute; however, the Server is only required to support the Value Attribute for Variable Nodes and the NodeId Attribute for Object Nodes. That said, profiles defined in OPC 10000-7 may make support for additional Attributes mandatory.

The SimpleAttributeOperand structure is used in the selectClauses to select the value to return if an Event meets the criteria specified by the whereClause. A null value is returned in the corresponding event field in the Publish response if the selected field is not part of the Event or an error was returned in the selectClauseResults of the EventFilterResult. If the selected field is supported but not available at the time of the event notification, the event field shall contain a StatusCode that indicates the reason for the unavailability. For example, the Server shall set the event field to Bad_UserAccessDenied if the value is not accessible to the user associated with the Session. If a Value Attribute has an uncertain or bad StatusCode associated with it then the Server shall provide the StatusCode instead of the Value Attribute. The Server shall set the event field to Bad_EncodingLimitsExceeded if a value exceeds the maxResponseMessageSize. The EventId, EventType and ReceiveTime cannot contain a StatusCode or a null value.

The Server shall validate the selectClauses when a Client creates or updates the EventFilter. Any errors which are true for all possible Events are returned in the selectClauseResults parameter described in Table 148. Some Servers, like aggregating Servers, may not know all possible EventTypes at the time the EventFilter is set. These Servers do not return errors for unknown EventTypes or BrowsePaths. The Server shall not report errors that might occur depending on the state or the Server or type of Event. For example, a selectClauses that requests a single element in an array would always produce an error if the DataType of the Attribute is a scalar. However, even if the DataType is an array an error could occur if the requested index does not exist for a particular Event, the Server would not report an error in the selectClauseResults parameter if the latter situation existed.

The SimpleAttributeOperand is used in the whereClause to select a value which forms part of a logical expression. These logical expressions are then used to determine whether a particular Event should be reported to the Client. The Server shall use a null value if any error occurs when a whereClause is evaluated for a particular Event. If a Value Attribute has an uncertain or bad StatusCode associated with it, then the Server shall use a null value instead of the Value.

Any basic FilterOperator in Table 122 may be used in the whereClause, however, only the OfType FilterOperator from Table 123 is permitted.

The Server shall validate the whereClause when a Client creates or updates the EventFilter. Any structural errors in the construction of the filter and any errors which are true for all possible Events are returned in the whereClauseResult parameter described in Table 148. Errors that could occur depending on the state of the Server or the Event are not reported. Some Servers, like aggregating Servers, may not know all possible EventTypes at the time the EventFilter is set. These Servers do not return errors for unknown EventTypes or BrowsePaths.

EventQueueOverflowEventType Events are special Events which are used to provide control information to the Client. These Events are only published to the MonitoredItems in the Subscription that produced the EventQueueOverflowEventType Event. These Events bypass the whereClause.

Table 147 defines the EventFilter structure.

Table 147 – EventFilter structure

Name

Type

Description

EventFilter

structure

selectClauses []

SimpleAttribute

Operand

List of the values to return with each Event in a Notification. At least one valid clause shall be specified. See 7.7.4.5 for the definition of SimpleAttributeOperand.

whereClause

ContentFilter

Limit the Notifications to those Events that match the criteria defined by this ContentFilter. The ContentFilter structure is described in 7.7.

The AttributeOperand structure may not be used in an EventFilter.

Table 148 defines the EventFilterResult structure. This is the MonitoringFilterResult associated with the EventFilter MonitoringFilter.

Table 148 – EventFilterResult structure

Name

Type

Description

EventFilterResult

structure

selectClauseResults []

StatusCode

List of status codes for the elements in the select clause. The size and order of the list matches the size and order of the elements in the selectClauses request parameter. The Server returns null for unavailable or rejected Event fields.

selectClauseDiagnosticInfos []

DiagnosticInfo

A list of diagnostic information for individual elements in the select clause. The size and order of the list matches the size and order of the elements in the selectClauses request parameter. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the select clauses.

whereClauseResult

ContentFilter

Result

Any results associated with the whereClause request parameter.

The ContentFilterResult type is defined in 7.7.2.

Table 149 defines values for the selectClauseResults parameter. Common StatusCodes are defined in Table 183.

Table 149 – EventFilterResult Result Codes

Symbolic Id

Description

Bad_TypeDefinitionInvalid

See Table 183 for the description of this result code.

The typeId is not the NodeId for BaseEventType or a subtype of it.

Bad_NodeIdUnknown

See Table 183 for the description of this result code.

The browsePath is specified but it will never exist in any Event.

Bad_BrowseNameInvalid

See Table 183 for the description of this result code.

The browsePath is specified and contains a null element.

Bad_AttributeIdInvalid

See Table 183 for the description of this result code.

The node specified by the browse path will never allow the given AttributeId to be returned.

Bad_IndexRangeInvalid

See Table 183 for the description of this result code.

Bad_TypeMismatch

See Table 183 for the description of this result code.

The indexRange is valid but the value of the Attribute is never an array.

The AggregateFilter defines the Aggregate function that should be used to calculate the values to be returned. See OPC 10000-13 for details on possible Aggregate functions. It specifies a startTime of the first Aggregate to be calculated. The samplingInterval of the MonitoringParameters (see 7.21) defines how the Server should internally sample the underlying data source. The processingInterval specifies the size of a time-period where the Aggregate is calculated. The queueSize from the MonitoringAttributes specifies the number of processed values that should be kept.

The intention of the AggregateFilter is not to read historical data, the HistoryRead service should be used for this purpose. However, it is allowed that the startTime is set to a time that is in the past when received from the Server. The number of Aggregates to be calculated in the past should not exceed the queueSize defined in the MonitoringAttributes since the values exceeding the queueSize would directly be discharged and never returned to the Client.

The startTime and the processingInterval can be revised by the Server, but the startTime should remain in the same boundary (startTime + revisedProcessingInterval * n = revisedStartTime). That behaviour simplifies accessing historical values of the Aggregates using the same boundaries by calling the HistoryRead service. The extensible Parameter AggregateFilterResult is used to return the revised values for the AggregateFilter.

Some underlying systems may poll data and produce multiple samples with the same value. Other systems may only report changes to the values. The definition for each Aggregate type explains how to handle the two different scenarios.

The MonitoredItem only reports values for intervals that have completed when the publish timer expires. Unused data is carried over and used to calculate a value returned in the next publish.

The ServerTimestamp for each interval shall be the time of the end of the processing interval.

The AggregateFilter is defined in Table 150.

Table 150 – AggregateFilter structure

Name

Type

Description

AggregateFilter

structure

startTime

UtcTime

Beginning of period to calculate the Aggregate the first time. The size of each period used to calculate the Aggregate is defined by the samplingInterval of the MonitoringParameters (see 7.21).

aggregateType

NodeId

The NodeId of the AggregateFunctionType Object that indicates the Aggregate to be used when retrieving processed data. See OPC 10000-13 for details.

processingInterval

Duration

The period be used to compute the Aggregate.

aggregateConfiguration

Aggregate

Configuration

This parameter allows Clients to override the Aggregate configuration settings supplied by the AggregateConfiguration Object on a per monitored item basis. See OPC 10000-13 for more information on Aggregate configurations. If the Server does not support the ability to override the Aggregate configuration settings it shall return a StatusCode of Bad_AggregateListMismatch. This structure is defined in-line with the following indented items.

useServerCapabilities

Defaults

Boolean

If value = TRUE use Aggregate configuration settings as outlined by the AggregateConfiguration object.

If value=FALSE use configuration settings as outlined in the following aggregateConfiguration parameters.

Default is TRUE.

treatUncertainAsBad

Boolean

As described in OPC 10000-13.

percentDataBad

Byte

As described in OPC 10000-13.

percentDataGood

Byte

As described in OPC 10000-13.

useSloped

Extrapolation

Boolean

As described in OPC 10000-13.

The AggregateFilterResult defines the revised AggregateFilter the Server can return when an AggregateFilter is defined for a MonitoredItem in the CreateMonitoredItems or ModifyMonitoredItems Services. The AggregateFilterResult is defined in Table 151. This is the MonitoringFilterResult associated with the AggregateFilter MonitoringFilter.

Table 151 – AggregateFilterResult structure

Name

Type

Description

AggregateFilterResult

structure

revisedStartTime

UtcTime

The actual StartTime interval that the Server shall use.

This value is based on a number of factors, including capabilities of the Server to access historical data. The revisedStartTime should remain in the same boundary as the startTime (startTime + samplingInterval * n = revisedStartTime).

revisedProcessingInterval

Duration

The actual processingInterval that the Server shall use.

The revisedProcessingInterval shall be at least twice the revisedSamplingInterval for the MonitoredItem.

revisedAggregateConfiguration

Aggregate

Configuration

The actual aggregateConfiguration that the Server shall use.

The structure is defined in Table 150.