This clause defines the OPC UA Service Sets and their Services. Clause 7 contains the definitions of common parameters used by these Services. Subclause 6.5 describes auditing requirements for all services.

Whether or not a Server supports a Service Set, or a Service within a Service Set, is defined by its Profile. Profiles are described in OPC 10000-7.

Each Service request has a RequestHeader and each Service response has a ResponseHeader.

The RequestHeader structure is defined in 7.33 and contains common request parameters such as authenticationToken, timestamp and requestHandle.

The ResponseHeader structure is defined in 7.34 and contains common response parameters such as serviceResult and diagnosticInfo.

Service results are returned at two levels in OPC UA responses, one that indicates the status of the Service call, and the other that indicates the status of each operation requested by the Service.

Service results are defined via the StatusCode (see 7.39).

The status of the Service call is represented by the serviceResult contained in the ResponseHeader (see 7.34). The mechanism for returning this parameter is specific to the communication technology used to convey the Service response and is defined in OPC 10000-6.

The status of individual operations in a request is represented by individual StatusCodes.

The following cases define the use of these parameters.

  1. A bad code is returned in serviceResult if the Service itself failed. In this case, a ServiceFault shall be returned instead of the Service response message. The ServiceFault is defined in 7.35.
  2. The good code is returned in serviceResult if the Service fully or partially succeeded. In this case, other response parameters are returned. The Client shall always check the response parameters, especially all StatusCodes associated with each operation. These StatusCodes may indicate bad or uncertain results for one or more operations requested in the Service call.

All Services with arrays of operations in the request shall return a bad code in the serviceResult if the array is empty.

The Services define various specific StatusCodes and a Server shall use these specific StatusCodes as described in the Service. A Client should be able to handle these Service specific StatusCodes. In addition, a Client shall expect other common StatusCodes defined in Table 182 and Table 183. Additional details for Client handling of specific StatusCodes may be defined in OPC 10000-7.

If the Server discovers, through some out-of-band mechanism that the application or user credentials used to create a Session or SecureChannel have been compromised, then the Server should immediately terminate all sessions and channels that use those credentials. In this case, the Service result code should be either Bad_IdentityTokenRejected or Bad_CertificateUntrusted.

Message parsing can fail due to syntax errors or if data contained within the message exceeds ranges supported by the receiver. When this happens messages shall be rejected by the receiver. If the receiver is a Server then it shall return a ServiceFault with result code of Bad_DecodingError or Bad_EncodingLimitsExceeded. If the receiver is the Client then the Communication Stack should report these errors to the Client application.

Many applications will place limits on the size of messages and/or data elements contained within these messages. For example, a Server may reject requests containing string values longer than a certain length. These limits are typically set by administrators and apply to all connections between a Client and a Server.

Clients that receive Bad_EncodingLimitsExceeded faults from the Server will likely need to reformulate their requests. The administrator may need to increase the limits for the Client if it receives a response from the Server with this fault.

In some cases, parsing errors are fatal and it is not possible to return a fault. For example, the incoming message could exceed the buffer capacity of the receiver. In these cases, these errors may be treated as a communication fault which requires the SecureChannel to be re-established (see 5.5).

The Client and Server reduce the chances of a fatal error by exchanging their message size limits in the CreateSession service. This will allow either party to avoid sending a message that causes a communication fault. The Server should return a Bad_ResponseTooLarge fault if a serialized response message exceeds the message size specified by the Client. Similarly, the Client Communication Stack should report a Bad_RequestTooLarge error to the application before sending a message that exceeds the Server’s limit.

Note that the message size limits only apply to the raw message body and do not include headers or the effect of applying any security. This means that a message body that is smaller than the specified maximum could still cause a fatal error.

This Service Set defines Services used to discover the Endpoints implemented by a Server and to read the security configuration for those Endpoints. The Discovery Services are implemented by individual Servers and by dedicated Discovery Servers. OPC 10000-12 describes how to use the Discovery Services with dedicated Discovery Servers.

Every Server shall have a DiscoveryEndpoint that Clients can access without establishing a Session. This Endpoint may or may not be the same Session Endpoint that Clients use to establish a SecureChannel. Clients read the security information necessary to establish a SecureChannel by calling the GetEndpoints Service on the DiscoveryEndpoint.

In addition, Servers may register themselves with a well-known Discovery Server using the RegisterServer Service. Clients can later discover any registered Servers by calling the FindServers Service on the Discovery Server.

The discovery process using FindServers is illustrated in Figure 9. The establishment of a SecureChannel (with MessageSecurityMode NONE) for FindServers and GetEndpoints is omitted from the figure for clarity.

image012.png

Figure 9 – Discovery process

The URL for a DiscoveryEndpoint shall provide all of the information that the Client needs to connect to the DiscoveryEndpoint.

Once a Client retrieves the Endpoints, the Client can save this information and use it to connect directly to the Server again without going through the discovery process. If the Client finds that it cannot connect then the Server configuration may have changed and the Client needs to go through the discovery process again.

DiscoveryEndpoints shall not require any message security, but it may require transport layer security. In production systems, Administrators may disable discovery for security reasons and Clients shall rely on cached EndpointDescriptions. To provide support for systems with disabled Discovery Services Clients shall allow Administrators to manually update the EndpointDescriptions used to connect to a Server. Servers shall allow Administrators to disable the DiscoveryEndpoint. If GetEndpoints is disabled and the Server Certificate is updated either automatically with Certificate Manager or manually, Clients will no longer be able to connect to the Server without manual re-configuration of the Client.

A Client shall be careful when using the information returned from a DiscoveryEndpoint since it has no security. A Client does this by comparing the information returned from the DiscoveryEndpoint to the information returned in the CreateSession response. A Client shall verify that:

  1. The ApplicationUri specified in the Server Certificate is the same as the ApplicationUri provided in the EndpointDescription.
  2. The Server Certificate returned in CreateSession response is the same as the Certificate used to create the SecureChannel.
  3. The EndpointDescriptions returned from the DiscoveryEndpoint are the same as the EndpointDescriptions returned in the CreateSession response, but they may be in a different order. For the content, the fields ApplicationUri, EndpointUrl, SecurityMode, SecurityPolicyUri, UserIdentityTokens, TransportProfileUri and SecurityLevel shall be compared for exact match. All other fields are ignored for the comparison.

If the Client detects that one of the above requirements is not fulfilled, then the Client shall close the SecureChannel and report an error.

A Client shall verify the HostName specified in the Server Certificate is the same as the HostName contained in the endpointUrl provided in the EndpointDescription returned by CreateSession. If there is a difference then the Client shall report the difference and may close the SecureChannel. Servers shall add all possible HostNames like MyHost and MyHost.local into the Server Certificate. This includes IP addresses of the host or the HostName exposed by a NAT router used to connect to the Server.

This Service returns the Servers known to a Server or Discovery Server. The behaviour of Discovery Servers is described in detail in OPC 10000-12.

The Client may reduce the number of results returned by specifying filter criteria. A Discovery Server returns an empty list if no Servers match the criteria specified by the Client. The filter criteria supported by this Service are described in 5.4.2.2.

Every Server shall provide a DiscoveryEndpoint that supports this Service. The Server shall always return a record that describes itself, however in some cases more than one record may be returned. Gateway Servers shall return a record for each Server that they provide access to plus (optionally) a record that allows the Gateway Server to be accessed as an ordinary OPC UA Server. Non-transparent redundant Servers shall provide a record for each Server in the RedundantServerSet.

Every Server shall have a globally unique identifier called the ServerUri. This identifier should be a fully qualified domain name; however, it may be a GUID or similar construct that ensures global uniqueness. The ServerUri returned by this Service shall be the same value that appears in index 0 of the ServerArray property (see OPC 10000-5). The ServerUri is returned as the applicationUri field in the ApplicationDescription (see 7.2).

Every Server shall also have a human readable identifier called the ServerName which is not necessarily globally unique. This identifier may be available in multiple locales.

A Server may have multiple HostNames. For this reason, the Client shall pass the URL it used to connect to the Endpoint to this Service. The implementation of this Service shall use this information to return responses that are accessible to the Client via the provided URL.

This Service shall not require message security but it may require transport layer security.

Some Servers may be accessed via a Gateway Server and shall have a value specified for gatewayServerUri in their ApplicationDescription (see 7.2). The discoveryUrls provided in ApplicationDescription shall belong to the Gateway Server. Some Discovery Servers may return multiple records for the same Server if that Server can be accessed via multiple paths.

This Service can be used without security and it is therefore vulnerable to Denial of Service (DOS) attacks. A Server should minimize the amount of processing required to send the response for this Service. This can be achieved by preparing the result in advance. The Server should also add a short delay before starting processing of a request during high traffic conditions.

Table 3 defines the parameters for the Service.

Table 3 – FindServers Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters. The authenticationToken is always null. The authenticationToken shall be ignored if it is provided.

The type RequestHeader is defined in 7.33.

endpointUrl

String

The network address that the Client used to access the DiscoveryEndpoint.

The Server uses this information for diagnostics and to determine what URLs to return in the response.

The Server should return a suitable default URL if it does not recognize the HostName in the URL.

localeIds []

LocaleId

List of locales to use.

The Server should return the applicationName in the ApplicationDescription defined in 7.2 using one of the locales specified. If the Server supports more than one of the requested locales then the Server shall use the locale that appears first in this list. If the Server does not support any of the requested locales it chooses an appropriate default locale.

The Server chooses an appropriate default locale if this list is empty.

serverUris []

String

List of Servers to return.

All known Servers are returned if the list is empty.

A serverUri matches the applicationUri from the ApplicationDescription defined in 7.2.

Response

responseHeader

ResponseHeader

Common response parameters.

The ResponseHeader type is defined in 7.34.

servers []

ApplicationDescription

List of Servers that meet criteria specified in the request.

This list is empty if no Servers meet the criteria.

The ApplicationDescription type is defined in 7.2.

Common StatusCodes are defined in Table 182.

This Service returns the Servers known to a Discovery Server. Unlike FindServers, this Service is only implemented by Discovery Servers.

The Client may reduce the number of results returned by specifying filter criteria. An empty list is returned if no Server matches the criteria specified by the Client.

This Service shall not require message security but it may require transport layer security.

Each time the Discovery Server creates or updates a record in its cache it shall assign a monotonically increasing identifier to the record. This allows Clients to request records in batches by specifying the identifier for the last record received in the last call to FindServersOnNetwork. To support this the Discovery Server shall return records in numerical order starting from the lowest record identifier. The Discovery Server shall also return the last time the counter was reset for example due to a restart of the Discovery Server. If a Client detects that this time is more recent than the last time the Client called the Service it shall call the Service again with a startingRecordId of 0.

This Service can be used without security and it is therefore vulnerable to denial of service (DOS) attacks. A Server should minimize the amount of processing required to send the response for this Service. This can be achieved by preparing the result in advance.

Table 4 defines the parameters for the Service.

Table 4 – FindServersOnNetwork Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters. The authenticationToken is always null. The authenticationToken shall be ignored if it is provided.

The type RequestHeader is defined in 7.33.

startingRecordId

Counter

Only records with an identifier greater than this number will be returned.

Specify 0 to start with the first record in the cache.

maxRecordsToReturn

UInt32

The maximum number of records to return in the response.

0 indicates that there is no limit.

serverCapabilityFilter[]

String

List of Server capability filters. The set of allowed Server capabilities are defined in OPC 10000-12.

Only records with all of the specified Server capabilities are returned.

The comparison is case insensitive.

If this list is empty then no filtering is performed.

Response

responseHeader

ResponseHeader

Common response parameters.

The ResponseHeader type is defined in 7.34.

lastCounterResetTime

UtcTime

The last time the counters were reset.

servers[]

ServerOnNetwork

List of DNS service records that meet criteria specified in the request.

This list is empty if no Servers meet the criteria.

recordId

UInt32

A unique identifier for the record.

This can be used to fetch the next batch of Servers in a subsequent call to FindServersOnNetwork.

serverName

String

The name of the Server specified in the mDNS announcement (see OPC 10000-12).

This may be the same as the ApplicationName for the Server.

discoveryUrl

String

The URL of the DiscoveryEndpoint.

serverCapabilities

String[]

The set of Server capabilities supported by the Server.

The set of allowed Server capabilities are defined in OPC 10000-12.

Common StatusCodes are defined in Table 182.

This Service returns the Endpoints supported by a Server and all of the configuration information required to establish a SecureChannel and a Session.

This Service shall not require message security but it may require transport layer security.

A Client may reduce the number of results returned by specifying filter criteria based on LocaleIds and Transport Profile URIs. The Server returns an empty list if no Endpoints match the criteria specified by the Client. The filter criteria supported by this Service are described in 5.4.4.2.

A Server may support multiple security configurations for the same Endpoint. In this situation, the Server shall return separate EndpointDescription records for each available configuration. Clients should treat each of these configurations as distinct Endpoints even if the physical URL happens to be the same.

The security configuration for an Endpoint has four components:

Server Application Instance Certificate

Message Security Mode

Security Policy

Supported User Identity Tokens

The ApplicationInstanceCertificate is used to secure the OpenSecureChannel request (see 5.5.2). The MessageSecurityMode and the SecurityPolicy tell the Client how to secure messages sent via the SecureChannel. The UserIdentityTokens tell the Client which type of user credentials shall be passed to the Server in the ActivateSession request (see 5.6.3).

If the securityPolicyUri is None and none of the UserTokenPolicies requires encryption, the Client shall ignore the ApplicationInstanceCertificate. If the securityPolicyUri is not None or one of the UserTokenPolicies requires encryption, the Server shall include the ApplicationInstanceCertificate in the EndpointDescription.

Each EndpointDescription also specifies a URI for the Transport Profile that the Endpoint supports. The Transport Profiles specify information such as message encoding format and protocol version and are defined in OPC 10000-7.

Messages are secured by applying standard cryptography algorithms to the messages before they are sent over the network. The exact set of algorithms used depends on the SecurityPolicy for the Endpoint. OPC 10000-7 defines Profiles for common SecurityPolicies and assigns a unique URI to them. It is expected that applications have built in knowledge of the SecurityPolicies that they support, as a result, only the Profile URI for the SecurityPolicy is specified in the EndpointDescription. A Client cannot connect to an Endpoint that does not support a SecurityPolicy that it recognizes.

An EndpointDescription may specify that the message security mode is NONE. This configuration is not recommended unless the applications are communicating on a physically isolated network where the risk of intrusion is extremely small. If the message security is NONE then it is possible for Clients to deliberately or accidentally hijack Sessions created by other Clients.

A Server may have multiple HostNames. For this reason, the Client shall pass the URL it used to connect to the Endpoint to this Service. The implementation of this Service shall use this information to return responses that are accessible to the Client via the provided URL.

This Service can be used without security and it is therefore vulnerable to Denial of Service (DOS) attacks. A Server should minimize the amount of processing required to send the response for this Service. This can be achieved by preparing the result in advance. The Server should also add a short delay before starting processing of a request during high traffic conditions.

Some of the EndpointDescriptions returned in a response shall specify the Endpoint information for a Gateway Server that can be used to access another Server. In these situations, the gatewayServerUri is specified in the EndpointDescription and all security checks used to verify Certificates shall use the gatewayServerUri (see 6.1.3) instead of the serverUri.

To connect to a Server via the gateway the Client shall first establish a SecureChannel with the Gateway Server. Then the Client shall call the CreateSession service and pass the serverUri specified in the EndpointDescription to the Gateway Server. The Gateway Server shall then connect to the underlying Server on behalf of the Client. The process of connecting to a Server via a Gateway Server is illustrated in Figure 10.

image013.png

Figure 10 – Using a Gateway Server

Table 5 defines the parameters for the Service.

Table 5 – GetEndpoints Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters.

The authenticationToken is always null. The authenticationToken shall be ignored if it is provided.

The type RequestHeader is defined in 7.33.

endpointUrl

String

The network address that the Client used to access the DiscoveryEndpoint.

The Server uses this information for diagnostics and to determine what URLs to return in the response.

The Server should return a suitable default URL if it does not recognize the HostName in the URL.

localeIds []

LocaleId

List of locales to use.

Specifies the locale to use when returning human readable strings.

This parameter is described in 5.4.2.2.

profileUris []

String

List of Transport Profile that the returned Endpoints shall support. OPC 10000-7 defines URIs for the Transport Profiles.

All Endpoints are returned if the list is empty.

If the URI is a URL, this URL may have a query string appended. The Transport Profiles that support query strings are defined in OPC 10000-7.

Response

responseHeader

ResponseHeader

Common response parameters.

The ResponseHeader type is defined in 7.34.

Endpoints []

EndpointDescription

List of Endpoints that meet criteria specified in the request.

This list is empty if no Endpoints meet the criteria.

The EndpointDescription type is defined in 7.14.

Common StatusCodes are defined in Table 182.

This Service is implemented by Discovery Servers.

This Service registers a Server with a Discovery Server. This Service will be called by a Server or a separate configuration utility. Clients will not use this Service.

A Server shall establish a SecureChannel with the Discovery Server before calling this Service. The SecureChannel is described in 5.5. The Administrator of the Server shall provide the Server with an EndpointDescription for the Discovery Server as part of the configuration process. Discovery Servers shall reject registrations if the serverUri provided does not match the applicationUri in Server Certificate used to create the SecureChannel.

This Service can only be invoked via SecureChannels that support Client authentication (i.e. HTTPS cannot be used to call this Service).

A Server only provides its serverUri and the URLs of the DiscoveryEndpoints to the Discovery Server. Clients shall use the GetEndpoints Service to fetch the most up to date configuration information directly from the Server.

The Server shall provide a localized name for itself in all locales that it supports.

Servers shall be able to register themselves with a Discovery Server running on the same machine. The exact mechanisms depend on the Discovery Server implementation and are described in OPC 10000-6.

There are two types of Server applications: those which are manually launched including a start by the operating system at boot and those that are automatically launched when a Client attempts to connect. The registration process that a Server shall use depends on which category it falls into.

The registration process for manually launched Servers is illustrated in Figure 11.

image014.png

Figure 11 – The Registration Process – Manually Launched Servers

The registration process for automatically launched Servers is illustrated in Figure 12.

image015.png

Figure 12 – The Registration Process – Automatically Launched Servers

The registration process is designed to be platform independent, robust and able to minimize problems created by configuration errors. For that reason, Servers shall register themselves more than once.

Under normal conditions, manually launched Servers shall periodically register with the Discovery Server as long as they are able to receive connections from Clients. If a Server goes offline then it shall register itself once more and indicate that it is going offline. The period of the recurring registration should be configurable; however, the maximum is 10 minutes. If an error occurs during registration (e.g. the Discovery Server is not running) then the Server shall periodically re-attempt registration. The frequency of these attempts should start at 1 second but gradually increase until the registration frequency is the same as what it would be if no errors occurred. The recommended approach would be to double the period of each attempt until reaching the maximum.

When an automatically launched Server (or its install program) registers with the Discovery Server it shall provide a path to a semaphore file which the Discovery Server can use to determine if the Server has been uninstalled from the machine. The Discovery Server shall have read access to the file system that contains the file.

Table 6 defines the parameters for the Service.

Table 6 – RegisterServer Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters.

The authenticationToken is always null.

The type RequestHeader is defined in 7.33.

Server

RegisteredServer

The Server to register. The type RegisteredServer is defined in 7.32.

Response

ResponseHeader

ResponseHeader

Common response parameters.

The type ResponseHeader is defined in 7.34.

Table 7 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 7 – RegisterServer Service Result Codes

Symbolic Id

Description

Bad_InvalidArgument

See Table 182 for the description of this result code.

Bad_ServerUriInvalid

See Table 182 for the description of this result code.

Bad_ServerNameMissing

No ServerName was specified.

Bad_DiscoveryUrlMissing

No discovery URL was specified.

Bad_SemaphoreFileMissing

The semaphore file specified is not valid.

This Service is implemented by Discovery Servers.

This Service allows a Server to register its DiscoveryUrls and capabilities with a Discovery Server. It extends the registration information from RegisterServer with information necessary for FindServersOnNetwork. This Service will be called by a Server or a separate configuration utility. Clients will not use this Service.

Servers that support RegisterServer2 shall try to register with the Discovery Server using this Service and shall fall back to RegisterServer if RegisterServer2 fails with the status Bad_ServiceUnsupported.

A Discovery Server that implements this Service needs to assign unique record ids each time this Service is called. See 5.4.3 for more details.

This Service can only be invoked via SecureChannels that support Client authentication (i.e. HTTPS cannot be used to call this Service).

Table 8 defines the parameters for the Service.

Table 8 – RegisterServer2

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters.

The authenticationToken is always null.

The type RequestHeader is defined in 7.33.

Server

RegisteredServer

The Server to register. The type RegisteredServer is defined in 7.32.

discoveryConfiguration []

ExtensibleParameter DiscoveryConfiguration

Additional configuration settings for the Server to register.

The discoveryConfiguration is an extensible parameter type defined in 7.13.

Discovery Servers that do not understand a configuration shall return Bad_NotSupported for this configuration.

Response

responseHeader

ResponseHeader

Common response parameters.

The type ResponseHeader is defined in 7.34.

configurationResults []

StatusCode

List of results for the discoveryConfiguration parameters.

diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the discoveryConfiguration parameters. 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 request.

Table 9 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 9 – RegisterServer2 Service Result Codes

Symbolic Id

Description

Bad_InvalidArgument

See Table 182 for the description of this result code.

Bad_ServerUriInvalid

See Table 182 for the description of this result code.

Bad_ServerNameMissing

No ServerName was specified.

Bad_DiscoveryUrlMissing

No discovery URL was specified.

Bad_SemaphoreFileMissing

The semaphore file specified is not valid.

Bad_ServiceUnsupported

See Table 182 for the description of this result code.

Table 10 defines values for the operation level configurationResults parameters that are specific to this Service. Common StatusCodes are defined in Table 183.

Table 10 – RegisterServer2 Operation Level Result Codes

Symbolic Id

Description

Bad_NotSupported

See Table 183 for the description of this result code.

This Service Set defines Services used to open a communication channel that ensures the Confidentiality and Integrity of all Messages exchanged with the Server. The base concepts for OPC UA security are defined in OPC 10000-2.

The SecureChannel Services are unlike other Services because they are not implemented directly by the OPC UA Application. Instead, they are provided by the Communication Stack on which the OPC UA Application is built. For example, an OPC UA Server may be built on a stack that allows applications to establish a SecureChannel using HTTPS. In these cases, the OPC UA Application shall verify that the Message it received was in the context of an HTTPS connection. OPC 10000-6 describes how the SecureChannel Services are implemented.

A SecureChannel is a long-running logical connection between a single Client and a single Server. This channel maintains a set of keys known only to the Client and Server, which are used to sign and encrypt Messages sent across the network to ensure Confidentiality and Integrity. The SecureChannel Services allow the Client and Server to securely negotiate the keys to use.

Logical connections may be initiated by the Client or by the Server as described in OPC 10000-6. After the connection is initiated, the SecureChannel is opened and closed by the Client using the SecureChannel Services.

An EndpointDescription tells a Client how to establish a SecureChannel with a given Endpoint. A Client may obtain the EndpointDescription from a Discovery Server, via some non-UA defined directory server or from its own configuration.

The exact algorithms used to sign and encrypt Messages are described in the SecurityPolicy field of the EndpointDescription. A Client shall use these algorithms when it creates a SecureChannel.

It should be noted that some SecurityPolicies defined in OPC 10000-7 will turn off authentication and encryption resulting in a SecureChannel that provides no security.

When a Client and Server are communicating via a SecureChannel, they shall verify that all incoming Messages have been signed and encrypted according to the requirements specified in the EndpointDescription. An OPC UA Application shall not process any Message that does not conform to these requirements.

The relationship between the SecureChannel and the OPC UA Application depends on the implementation technology. OPC 10000-6 defines any requirements that depend on the technology used.

The correlation between the OPC UA Application Session and the SecureChannel is illustrated in Figure 13. The Communication Stack is used by the OPC UA Applications to exchange Messages. In the first step, the SecureChannel Services are used to establish a SecureChannel between the two Communication Stacks which allows the secure exchange of Messages. In the second step, the OPC UA Applications use the Session Service Set to establish an OPC UA Application Session.

image016.png

Figure 13 – SecureChannel and Session Services

Once a Client has established a Session it may wish to access the Session from a different SecureChannel. The Client can do this by validating the new SecureChannel with the ActivateSession Service described in 5.6.3.

If a Server acts as a Client to other Servers, which is commonly referred to as Server chaining, then the Server shall be able to maintain user level security. By this we mean that the user identity should be passed to the underlying Server or it should be mapped to an appropriate user identity in the underlying Server. It is unacceptable to ignore user level security. This is required to ensure that security is maintained and that a user does not obtain information that they should not have access to. Whenever possible a Server should impersonate the original Client by passing the original Client’s user identity to the underlying Server when it calls the ActivateSession Service. If impersonation is not an option then the Server shall map the original Client’s user identity onto a new user identity which the underlying Server does recognize.

This Service is used to open or renew a SecureChannel that can be used to ensure Confidentiality and Integrity for Message exchange during a Session. This Service requires the Communication Stack to apply the various security algorithms to the Messages as they are sent and received. Specific implementations of this Service for different Communication Stacks are described in OPC 10000-6.

Each SecureChannel has a globally-unique identifier and is valid for a specific combination of Client and Server application instances. Each channel contains one or more SecurityTokens that identify a set of cryptography keys that are used to encrypt and authenticate Messages. SecurityTokens also have globally-unique identifiers which are attached to each Message secured with the token. This allows an authorized receiver to know how to decrypt and verify the Message.

SecurityTokens have a finite lifetime negotiated with this Service. However, differences between the system clocks on different machines and network latencies mean that valid Messages could arrive after the token has expired. To prevent valid Messages from being discarded, the applications should do the following:

  1. Clients should request a new SecurityToken after 75 % of its lifetime has elapsed. This should ensure that Clients will receive the new SecurityToken before the old one actually expires.
  2. Servers shall use the existing SecurityToken to secure outgoing Messages until the SecurityToken expires or the Server receives a Message secured with a new SecurityToken. This should ensure that Clients do not reject Messages secured with the new SecurityToken that arrive before the Client receives the new SecurityToken.
  3. Clients should accept Messages secured by an expired SecurityToken for up to 25 % of the token lifetime. This should ensure that Messages sent by the Server before the token expired are not rejected because of network delays.

Each SecureChannel exists until it is explicitly closed or until the last token has expired and the overlap period has elapsed. A Server application should limit the number of SecureChannels. To protect against misbehaving Clients and denial of service attacks, the Server shall close the oldest unused SecureChannel that has no Session assigned before reaching the maximum number of supported SecureChannels. When Session-less Service invocation is done through a transport mapping that requires the OpenSecureChannel Service, the Server shall maintain a last used time for the SecureChannel to detect the oldest unused SecureChannel.

The OpenSecureChannel request and response Messages shall be signed with the sender's private key. These Messages shall always be encrypted. If the transport layer does not provide encryption, then these Messages shall be encrypted with the receiver's public key. These requirements for OpenSecureChannel only apply if the securityPolicyUri is not None.

If the protocol defined in OPC 10000-6 requires that Application Instance Certificates are used in the OpenSecureChannel Service, then Clients and Servers shall verify that the same Certificates are used in the CreateSession and ActivateSession Services. Certificates are not provided and shall not be verified if the securityPolicyUri is None.

If the securityPolicyUri is not None, a Client shall verify the HostName specified in the Server Certificate is the same as the HostName contained in the endpointUrl. If there is a difference then the Client shall report the difference and may choose to not open the SecureChannel. Servers shall add all possible HostNames like MyHost and MyHost.mycompany.com into the Server Certificate. This includes IP addresses of the host or the HostName exposed by a NAT router used to connect to the Server. Servers shall not append the 'local' top level domain to any domains declared in their Certificate; an unqualified domain name is used if a more appropriate qualifier does not exist. Clients using a URL returned from an LDS-ME shall remove the 'local' top level domain when checking the domain against the Server Certificate.

Clients should be prepared to replace the HostName and port returned in the EndpointDescription with the HostName or the IP addresses and the port they used to call GetEndpoints. The Client shall still execute the HostName verification comparing the HostName used by the Client to create the SecureChannel with the HostName list in the Server Certificate. See Table 106 for more details.

Table 11 defines the parameters for the Service.

Unlike other Services, the parameters for this Service provide only an abstract definition. The concrete representation on the network depends on the mappings defined in OPC 10000-6.

Table 11 – OpenSecureChannel Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters. The authenticationToken is always null.

The type RequestHeader is defined in 7.33.

clientCertificate

ApplicationInstance‌Certificate

A Certificate that identifies the Client.

The OpenSecureChannel request shall be signed with the private key for this Certificate.

The ApplicationInstanceCertificate type is defined in 7.3.

If the securityPolicyUri is None, the Server shall ignore the ApplicationInstanceCertificate.

requestType

Enum

SecurityToken RequestType

The type of SecurityToken request:

An enumeration that shall be one of the following:

ISSUEcreates a new SecurityToken for a new SecureChannel.

RENEW creates a new SecurityToken for an existing SecureChannel.

secureChannelId

BaseDataType

The identifier for the SecureChannel that the new token should belong to. This parameter shall be null when creating a new SecureChannel.

The concrete security protocol definition in OPC 10000-6 chooses the concrete DataType.

securityMode

Enum

MessageSecurityMode

The type of security to apply to the messages.

The type MessageSecurityMode type is defined in 7.20.

A SecureChannel may need to be created even if the securityMode is NONE. The exact behaviour depends on the mapping used and is described in the OPC 10000-6.

securityPolicyUri

String

The URI for SecurityPolicy to use when securing messages sent over the SecureChannel.

The set of known URIs and the SecurityPolicies associated with them are defined in OPC 10000-7.

clientNonce

ByteString

A random number that shall not be used in any other request. A new clientNonce shall be generated for each time a SecureChannel is renewed.

This parameter shall have a length equal to the SecureChannelNonceLength defined for the SecurityPolicy in OPC 10000-7. The SecurityPolicy is identified by the securityPolicyUri.

requestedLifetime

Duration

The requested lifetime, in milliseconds, for the new SecurityToken. It specifies when the Client expects to renew the SecureChannel by calling the OpenSecureChannel Service again. If a SecureChannel is not renewed, then all Messages sent using the current SecurityTokens shall be rejected by the receiver.

Several cryptanalytic attacks become easier as more material encrypted with a specific key is available. By limiting the amount of data processed using a particular key, those attacks are made more difficult. Therefore the volume of data exchanged between Client and Server shall be limited by establishing a new SecurityToken after the lifetime.

The setting of the requested lifetime depends on the expected number of exchanged messages and their size in the lifetime. A higher volume of data requires shorter lifetime.

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader type definition).

securityToken

ChannelSecurityToken

Describes the new SecurityToken issued by the Server. This structure is defined in-line with the following indented items.

channelId

BaseDataType

A unique identifier for the SecureChannel. This is the identifier that shall be supplied whenever the SecureChannel is renewed.

The concrete security protocol definition in OPC 10000-6 chooses the concrete DataType.

tokenId

ByteString

A unique identifier for a single SecurityToken within the channel. This is the identifier that shall be passed with each Message secured with the SecurityToken.

createdAt

UtcTime

The time when the SecurityToken was created.

revisedLifetime

Duration

The lifetime of the SecurityToken in milliseconds. The UTC expiration time for the token may be calculated by adding the lifetime to the createdAt time.

The revised lifetime shall be used by the Client to renew a SecureChannel before it expires even if the MessageSecurityMode is NONE.

serverNonce

ByteString

A random number that shall not be used in any other request. A new serverNonce shall be generated for each time a SecureChannel is renewed.

This parameter shall have a length equal to the SecureChannelNonceLength defined for the SecurityPolicy in OPC 10000-7. The SecurityPolicy is identified by the securityPolicyUri.

Table 12 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 12 – OpenSecureChannel Service Result Codes

Symbolic Id

Description

Bad_SecurityChecksFailed

See Table 182 for the description of this result code.

Bad_CertificateTimeInvalid

See Table 182 for the description of this result code.

Bad_CertificateIssuerTimeInvalid

See Table 182 for the description of this result code.

Bad_CertificateHostNameInvalid

See Table 182 for the description of this result code.

Bad_CertificateUriInvalid

See Table 182 for the description of this result code.

Bad_CertificateUseNotAllowed

See Table 182 for the description of this result code.

Bad_CertificateIssuerUseNotAllowed

See Table 182 for the description of this result code.

Bad_CertificateUntrusted

See Table 182 for the description of this result code.

Bad_CertificateRevocationUnknown

See Table 182 for the description of this result code.

Bad_CertificateIssuerRevocationUnknown

See Table 182 for the description of this result code.

Bad_CertificateRevoked

See Table 182 for the description of this result code.

Bad_CertificateIssuerRevoked

See Table 182 for the description of this result code.

Bad_RequestTypeInvalid

The SecurityToken request type is not valid.

Bad_SecurityModeRejected

The security mode does not meet the requirements set by the server.

Bad_SecurityPolicyRejected

The security policy does not meet the requirements set by the Server.

Bad_SecureChannelIdInvalid

See Table 182 for the description of this result code.

Bad_NonceInvalid

See Table 182 for the description of this result code.

A Server shall check the minimum length of the Client nonce and return this status if the length is below 32 bytes. A check for duplicated nonce can only be done in OpenSecureChannel calls with the request type RENEW.

This Service is used to terminate a SecureChannel.

The request Messages shall be signed with the appropriate key associated with the current token for the SecureChannel.

Table 13 defines the parameters for the Service.

Specific protocol mappings defined in OPC 10000-6 may choose to omit the response.

Table 13 – CloseSecureChannel Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters. The authenticationToken is always null.

The type RequestHeader is defined in 7.33.

secureChannelId

BaseDataType

The identifier for the SecureChannel to close.

The concrete security protocol definition in OPC 10000-6 chooses the concrete DataType.

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader definition).

Table 14 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 14 – CloseSecureChannel Service Result Codes

Symbolic Id

Description

Bad_SecureChannelIdInvalid

See Table 182 for the description of this result code.

This Service Set defines Services for an application layer connection establishment in the context of a Session.

This Service is used by an OPC UA Client to create a Session and the Server returns two values which uniquely identify the Session. The first value is the sessionId which is used to identify the Session in the audit logs and in the Server’s AddressSpace. The second is the authenticationToken which is used to associate an incoming request with a Session.

Before calling this Service, the Client shall create a SecureChannel with the OpenSecureChannel Service to ensure the Integrity of all Messages exchanged during a Session. This SecureChannel has a unique identifier which the Server shall associate with the authenticationToken. The Server may accept requests with the authenticationToken only if they are associated with the same SecureChannel that was used to create the Session. The Client may associate a new SecureChannel with the Session by calling ActivateSession. For the N Sessions supported by a Server, the Server shall support N+1 SecureChannels. A Server may support multiple Sessions for one SecureChannel.

The SecureChannel is always managed by the Communication Stack which means it shall provide APIs which the Server can use to find out information about the SecureChannel used for any given request. The Communication Stack shall, at a minimum, provide the SecurityPolicy and SecurityMode used by the SecureChannel. It shall also provide a SecureChannelId which uniquely identifies the SecureChannel or the Client Certificate used to establish the SecureChannel. The Server uses one of these to identify the SecureChannel used to send a request. Clause 7.36 describes how to create the authenticationToken for different types of Communication Stack.

Depending upon on the SecurityPolicy and the SecurityMode of the SecureChannel, the exchange of ApplicationInstanceCertificates and Nonces may be optional and the signatures may be empty. See OPC 10000-7 for the definition of SecurityPolicies and the handling of these parameters.

The Server returns its EndpointDescriptions in the response. Clients use this information to determine whether the list of EndpointDescriptions returned from the DiscoveryEndpoint matches the Endpoints that the Server has. If there is a difference then the Client shall close the Session and report an error. The Server returns all EndpointDescriptions for the serverUri specified by the Client in the request. The Client only verifies EndpointDescriptions with a transportProfileUri that matches the profileUri specified in the original GetEndpoints request. A Client may skip this check if the EndpointDescriptions were provided by a trusted source such as the Administrator.

The Session created with this Service shall not be used until the Client calls the ActivateSession Service and proves possession of its Application Instance Certificate and any user identity token that it provided.

A Server application should limit the number of Sessions. To protect against misbehaving Clients and denial of service attacks, the Server shall close the oldest Session that is not activated before reaching the maximum number of supported Sessions.

The SoftwareCertificates parameter in the Server response is deprecated to reduce the message size for OPC UA Applications with limited resources. The SoftwareCertificates are provided in the Server’s AddressSpace as defined in OPC 10000-5. A SoftwareCertificate identifies the capabilities of the Server and also contains the list of OPC UA Profiles supported by the Server. OPC UA Profiles are defined in OPC 10000-7.

Additional Certificates issued by other organizations may be included to identify additional Server capabilities. Examples of these Profiles include support for specific information models and support for access to specific types of devices.

When a Session is created, the Server adds an entry for the Client in its SessionDiagnosticsArray Variable. See OPC 10000-5 for a description of this Variable.

Sessions are created to be independent of the underlying communications connection. Therefore, if a communications connection fails, the Session is not immediately affected. When the communication connection fails, the Client should try to create a new communication connection and call ActivateSession again. See 6.7 for more details.

Sessions are terminated by the Server automatically if the Client fails to issue a Service request on the Session within the timeout period negotiated by the Server in the CreateSession Service response. This protects the Server against Client failures and against situations where a failed underlying connection cannot be re-established. Clients shall be prepared to submit requests in a timely manner to prevent the Session from closing automatically. Clients may explicitly terminate Sessions using the CloseSession Service.

When a Session is terminated, all outstanding requests on the Session are aborted and Bad_SessionClosed StatusCodes are returned to the Client. In addition, the Server deletes the entry for the Client from its SessionDiagnosticsArray Variable and notifies any other Clients who were subscribed to this entry.

If a Client invokes the CloseSession Service then all Subscriptions associated with the Session are also deleted if the deleteSubscriptions flag is set to TRUE. If a Server terminates a Session for any other reason, Subscriptions associated with the Session, are not deleted. Each Subscription has its own lifetime to protect against data loss in the case of a Session termination. In these cases, the Subscription can be reassigned to another Client before its lifetime expires.

Some Servers, such as aggregating Servers, also act as Clients to other Servers. These Servers typically support more than one system user, acting as their agent to the Servers that they represent. Security for these Servers is supported at two levels.

First, each OPC UA Service request contains a string parameter that is used to carry an audit record id. A Client, or any Server operating as a Client, such as an aggregating Server, can create a local audit log entry for a request that it submits. This parameter allows the Client to pass the identifier for this entry with the request. If the Server also maintains an audit log, then it can include this id in the audit log entry that it writes. When the log is examined and the entry is found, the examiner will be able to relate it directly to the audit log entry created by the Client. This capability allows for traceability across audit logs within a system. See OPC 10000-2 for additional information on auditing. A Server that maintains an audit log shall provide the information in the audit log entries via event Messages defined in this document. The Server may choose to only provide the Audit information via event Messages. The Audit EventType is defined in OPC 10000-3.

Second, these aggregating Servers may open independent Sessions to the underlying Servers for each Client that accesses data from them. Figure 14 illustrates this concept.

image017.png

Figure 14 – Multiplexing users on a Session

Table 15 defines the parameters for the Service.

Table 15 – CreateSession Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters. The authenticationToken is always null.

The type RequestHeader is defined in 7.33.

clientDescription

Application Description

Information that describes the Client application.

The type ApplicationDescription is defined in 7.2.

serverUri

String

This value is only specified if the EndpointDescription has a gatewayServerUri.

This value is the applicationUri from the EndpointDescription which is the applicationUri for the underlying Server. The type EndpointDescription is defined in 7.14.

endpointUrl

String

The network address that the Client used to access the Session Endpoint.

The HostName portion of the URL should be one of the HostNames for the application that are specified in the Server’s ApplicationInstanceCertificate (see 7.3). The Server shall raise an AuditUrlMismatchEventType event if the URL does not match the Server’s HostNames. AuditUrlMismatchEventType event type is defined in OPC 10000-5.

The Server uses this information for diagnostics and to determine the set of EndpointDescriptions to return in the response.

sessionName

String

Human readable string that identifies the Session. The Server makes this name and the sessionId visible in its AddressSpace for diagnostic purposes. The Client should provide a name that is unique for the instance of the Client.

If this parameter is null or empty the Server shall assign a value.

clientNonce

ByteString

A random number that should never be used in any other request. This number shall have a minimum length of 32 bytes. Profiles may increase the required length. The Server shall use this value to prove possession of its Application Instance Certificate in the response.

clientCertificate

ApplicationInstance

Certificate

The Application Instance Certificate issued to the Client.

The ApplicationInstanceCertificate type is defined in 7.3.

If the securityPolicyUri is None, the Server shall ignore the ApplicationInstanceCertificate.

A Client shall prove possession by using the private key to sign the Nonce provided by the Server in the response. For SecureChannels that use the Application Instance Certificate the Server shall verify that this Certificate is the same as the one it used to create the SecureChannel.

Requested

SessionTimeout

Duration

Requested maximum number of milliseconds that a Session should remain open without activity. If the Client fails to issue a Service request within this interval, then the Server shall automatically terminate the Client Session.

maxResponse

MessageSize

UInt32

The maximum size, in bytes, for the body of any response message.

The Server should return a Bad_ResponseTooLarge service fault if a response message exceeds this limit.

The value zero indicates that this parameter is not used.

The transport protocols defined in OPC 10000-6 may imply minimum message sizes.

More information on the use of this parameter is provided in 5.3.

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader type).

sessionId

NodeId

A unique NodeId assigned by the Server to the Session. This identifier is used to access the diagnostics information for the Session in the Server AddressSpace. It is also used in the audit logs and any events that report information related to the Session. The Session diagnostic information is described in OPC 10000-5. Audit logs and their related events are described in 6.5.

authentication

Token

Session

AuthenticationToken

A unique identifier assigned by the Server to the Session. This identifier shall be passed in the RequestHeader of each request and is used with the SecureChannelId to determine whether a Client has access to the Session. This identifier shall not be reused in a way that the Client or the Server has a chance of confusing them with a previous or existing Session.

The SessionAuthenticationToken type is described in 7.36.

revisedSessionTimeout

Duration

Actual maximum number of milliseconds that a Session shall remain open without activity. The Server should attempt to honour the Client request for this parameter, but may negotiate this value up or down to meet its own constraints.

serverNonce

ByteString

A random number that should never be used in any other request.

This number shall have a minimum length of 32 bytes.

The Client shall use this value to prove possession of its Application Instance Certificate in the ActivateSession request.

This value may also be used to prove possession of the userIdentityToken it specified in the ActivateSession request.

serverCertificate

ApplicationInstance

Certificate

The Application Instance Certificate issued to the Server.

A Server shall prove possession by using the private key to sign the Nonce provided by the Client in the request. For SecureChannels that use the Application Instance Certificate the Client shall verify that this Certificate is the same as the one it used to create the SecureChannel.

The ApplicationInstanceCertificate type is defined in 7.3.

If the securityPolicyUri is None and none of the UserTokenPolicies requires encryption, the Client shall ignore the ApplicationInstanceCertificate.

serverEndpoints []

EndpointDescription

List of Endpoints that the Server supports.

The Server shall return a set of EndpointDescriptions available for the serverUri specified in the request. All Endpoints are returned if the serverUri is null or empty. The EndpointDescription type is defined in 7.14. The Client shall verify this list with the list from a DiscoveryEndpoint if it used a DiscoveryEndpoint to fetch the EndpointDescriptions.

It is recommended that Servers only include the server.applicationUri, endpointUrl, securityMode, securityPolicyUri, userIdentityTokens, transportProfileUri and securityLevel with all other parameters set to null or empty. Only the recommended parameters shall be verified by the Client.

serverSoftware

Certificates []

SignedSoftware Certificate

This parameter is no longer used and the array shall be empty.

The SoftwareCertificates are provided in the Server AddressSpace as defined in OPC 10000-5.

serverSignature

SignatureData

This is a signature generated with the private key associated with the serverCertificate. This parameter is calculated by appending the clientNonce to the clientCertificate and signing the resulting sequence of bytes.

If the clientCertificate contains a chain, the signature calculation shall be done only with the leaf Certificate. For backward compatibility a Client shall check the signature with the full chain if the check with the leaf Certificate fails.

The SignatureAlgorithm shall be the AsymmetricSignatureAlgorithm specified in the SecurityPolicy for the Endpoint.

The SignatureData type is defined in 7.37.

maxRequest

MessageSize

UInt32

The maximum size, in bytes, for the body of any request message.

The Client Communication Stack should return a Bad_RequestTooLarge error to the application if a request message exceeds this limit.

The value zero indicates that this parameter is not used.

See OPC 10000-6 for protocol specific minimum or default values.

5.3 provides more information on the use of this parameter.

Table 16 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 16 – CreateSession Service Result Codes

Symbolic Id

Description

Bad_SecureChannelIdInvalid

See Table 182 for the description of this result code.

Bad_NonceInvalid

See Table 182 for the description of this result code.

A Server shall check the minimum length of the Client nonce and return this status if the length is below 32 bytes. A check for a duplicated nonce is optional and requires access to the nonce used to create the secure channel.

Bad_SecurityChecksFailed

See Table 182 for the description of this result code.

Bad_CertificateTimeInvalid

See Table 182 for the description of this result code.

Bad_CertificateIssuerTimeInvalid

See Table 182 for the description of this result code.

Bad_CertificateHostNameInvalid

See Table 182 for the description of this result code.

Bad_CertificateUriInvalid

See Table 182 for the description of this result code.

Bad_CertificateUseNotAllowed

See Table 182 for the description of this result code.

Bad_CertificateIssuerUseNotAllowed

See Table 182 for the description of this result code.

Bad_CertificateUntrusted

See Table 182 for the description of this result code.

Bad_CertificateRevocationUnknown

See Table 182 for the description of this result code.

Bad_CertificateIssuerRevocationUnknown

See Table 182 for the description of this result code.

Bad_CertificateRevoked

See Table 182 for the description of this result code.

Bad_CertificateIssuerRevoked

See Table 182 for the description of this result code.

Bad_TooManySessions

The Server has reached its maximum number of Sessions.

Bad_ServerUriInvalid

See Table 182 for the description of this result code.

Bad_SecurityPolicyRejected

See Table 182 for the description of this result code.

This Service is used by the Client to specify the identity of the user associated with the Session. This Service request shall be issued by the Client before it issues any Service request other than CloseSession after CreateSession. Failure to do so shall cause the Server to close the Session.

Whenever the Client calls this Service the Client shall prove that it is the same application that called the CreateSession Service. The Client does this by creating a signature with the private key associated with the clientCertificate specified in the CreateSession request. This signature is created by appending the last serverNonce provided by the Server to the serverCertificate and calculating the signature of the resulting sequence of bytes.

Once used, a serverNonce cannot be used again. For that reason, the Server returns a new serverNonce each time the ActivateSession Service is called.

When the ActivateSession Service is called for the first time then the Server shall reject the request if the SecureChannel is not same as the one associated with the CreateSession request. Subsequent calls to ActivateSession may be associated with different SecureChannels. If this is the case then the Server shall verify that the Certificate the Client used to create the new SecureChannel is the same as the Certificate used to create the original SecureChannel. In addition, the Server shall verify that the Client supplied a UserIdentityToken that is identical to the token currently associated with the Session. Once the Server accepts the new SecureChannel it shall reject requests sent via the old SecureChannel.

The ActivateSession Service is used to associate a user identity with a Session. When a Client provides a user identity then it shall provide proof that it is authorized to use that user identity. The exact mechanism used to provide this proof depends on the type of the UserIdentityToken. If the token is a UserNameIdentityToken then the proof is the password that is included in the token. If the token is an X509IdentityToken then the proof is a signature generated with private key associated with the Certificate. The data to sign is created by appending the last serverNonce to the serverCertificate specified in the CreateSession response. If a token includes a secret then it should be encrypted using the public key from the serverCertificate.

Servers shall take proper measures to protect against attacks on user identity tokens. Such an attack is assumed if repeated connection attempts with invalid user identity tokens happen. One option is to lock out an OPC UA Client for a period of time if the user identity token validation fails several times. The OPC UA Client is either detected by IP address for unsecured connections or by the ApplicationInstanceUri for secured connections. Another option is delaying the Service response when the validation of a user identity fails. This delay time could be increased with repeated failures. Sporadic failures shall not delay connections with valid tokens.

Clients can change the identity of a user associated with a Session by calling the ActivateSession Service. The Server validates the signatures provided with the request and then validates the new user identity. If no errors occur the Server replaces the user identity for the Session. Changing the user identity for a Session may cause discontinuities in active Subscriptions because the Server may need to tear down connections to an underlying system and re-establish them using the new credentials. A Server shall re-evaluate the permissions of all MonitoredItems in Subscriptions assigned to the Session after a user identity change.

When a Client supplies a list of locale ids in the request, each locale id is required to contain the language component. It may optionally contain the <country/region> component. When the Server returns a LocalizedText in the context of the Session, it also may return both the language and the country/region or just the language as its default locale id.

When a Server returns a string to the Client, it first determines if there are available translations for it. If there are, then the Server returns the string whose locale id exactly matches the locale id with the highest priority in the Client-supplied list.

If there are no exact matches, then the Server ignores the <country/region> component of the locale id, and returns the string whose <language> component matches the <language> component of the locale id with the highest priority in the Client supplied list.

If there still are no matches, then the Server returns the string that it has along with the locale id.

A Gateway Server is expected to impersonate the user provided by the Client when it connects to the underlying Server. This means it shall re-calculate the signatures on the UserIdentityToken using the nonce provided by the underlying Server. The Gateway Server shall use its own user credentials if the UserIdentityToken provided by the Client does not support impersonation.

Table 17 defines the parameters for the Service.

Table 17 – ActivateSession Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters. The type RequestHeader is defined in 7.33.

clientSignature

SignatureData

This is a signature generated with the private key associated with the clientCertificate. This parameter is calculated by appending the serverNonce to the serverCertificate and signing the resulting sequence of bytes.

If the serverCertificate contains a chain, the signature calculation shall be done only with the leaf Certificate. For backward compatibility a Server shall check the signature with the full chain if the check with the leaf Certificate fails.

The SignatureAlgorithm shall be the AsymmetricSignatureAlgorithm specified in the SecurityPolicy for the Endpoint.

The SignatureData type is defined in 7.37.

clientSoftwareCertificates []

SignedSoftware‌Certificate

Reserved for future use.

The SignedSoftwareCertificate type is defined in 7.38.

localeIds []

LocaleId

List of locale ids in priority order for localized strings. The first LocaleId in the list has the highest priority. If the Server returns a localized string to the Client, the Server shall return the translation with the highest priority that it can. If it does not have a translation for any of the locales identified in this list, then it shall return the string value that it has and include the locale id with the string. See OPC 10000-3 for more detail on locale ids. If the Client fails to specify at least one locale id, the Server shall use any that it has.

This parameter only needs to be specified during the first call to ActivateSession during a single application Session. If it is null or empty the Server shall keep using the current localeIds for the Session.

userIdentityToken

Extensible Parameter

UserIdentityToken

The credentials of the user associated with the Client application. The Server uses these credentials to determine whether the Client should be allowed to activate a Session and what resources the Client has access to during this Session.

The UserIdentityToken is an extensible parameter type defined in 7.41.

The EndpointDescription specifies what UserIdentityTokens the Server shall accept.

Null or empty user token shall always be interpreted as anonymous.

userTokenSignature

SignatureData

If the Client specified a user identity token that supports digital signatures, then it shall create a signature and pass it as this parameter. Otherwise the parameter is null or empty.

The SignatureAlgorithm depends on the identity token type.

The SignatureData type is defined in 7.37.

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader definition).

serverNonce

ByteString

A random number that should never be used in any other request.

This number shall have a minimum length of 32 bytes.

The Client shall use this value to prove possession of its Application Instance Certificate in the next call to ActivateSession request.

results []

StatusCode

List of validation results for the SoftwareCertificates (see 7.39 for StatusCode definition).

diagnosticInfos []

DiagnosticInfo

List of diagnostic information associated with SoftwareCertificate validation errors (see 7.12 for DiagnosticInfo definition). 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 request.

Table 18 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 18 – ActivateSession Service Result Codes

Symbolic Id

Description

Bad_IdentityTokenInvalid

See Table 182 for the description of this result code.

Bad_IdentityTokenRejected

See Table 182 for the description of this result code.

Bad_UserAccessDenied

See Table 182 for the description of this result code.

Bad_ApplicationSignatureInvalid

The signature provided by the Client application is missing or invalid.

Bad_UserSignatureInvalid

The user token signature is missing or invalid.

Bad_NoValidCertificates

The Client did not provide at least one Software Certificate that is valid and meets the profile requirements for the Server.

Bad_IdentityChangeNotSupported

The Server does not support changing the user identity assigned to the session.

Bad_SecurityPolicyRejected

See Table 182 for the description of this result code.

Good_PasswordChangeRequired

The log-on for the user succeeded but the user is required to change the password.

The activated Session has limited rights and is mainly available to change the password.

The detailed definitions for UserManagement, restrictions for Sessions and the Method ChangePassword used to set a new password are defined in OPC 10000-18. This result code is only used by Servers that support the Method ChangePassword.

This Service is used to terminate a Session. The Server takes the following actions when it receives a CloseSession request:

  1. It stops accepting requests for the Session. All subsequent requests received for the Session are discarded.
  2. It returns negative responses with the StatusCode Bad_SessionClosed to all requests that are currently outstanding to provide for the timely return of the CloseSession response. Clients are urged to wait for all outstanding requests to complete before submitting the CloseSession request.
  3. It removes the entry for the Client in its SessionDiagnosticsArray Variable.

When the CloseSession Service is called before the Session is successfully activated, the Server shall reject the request if the SecureChannel is not the same as the one associated with the CreateSession request.

Table 19 defines the parameters for the Service.

Table 19 – CloseSession Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

deleteSubscriptions

Boolean

If the value is TRUE, the Server deletes all Subscriptions associated with the Session. If the value is FALSE, the Server keeps the Subscriptions associated with the Session until they timeout based on their own lifetime.

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader definition).

Table 20 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 20 – CloseSession Service Result Codes

Symbolic Id

Description

Bad_SessionIdInvalid

See Table 182 for the description of this result code.

This Service is used to cancel outstanding Service requests. Successfully cancelled service requests shall respond with Bad_RequestCancelledByClient.

Table 21 defines the parameters for the Service.

Table 21 – Cancel Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

requestHandle

IntegerId

The requestHandle assigned to one or more requests that should be cancelled. All outstanding requests with the matching requestHandle shall be cancelled.

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader definition).

cancelCount

UInt32

Number of cancelled requests.

Common StatusCodes are defined in Table 182.

This Service Set defines Services to add and delete AddressSpace Nodes and References between them. All added Nodes continue to exist in the AddressSpace even if the Client that created them disconnects from the Server.

Calls to NodeManagement Services may result in changes to the AddressSpace in addition to the requested change. The actual behaviour is Server specific.

This Service is used to add one or more Nodes into the AddressSpace hierarchy. Using this Service, each Node is added as the TargetNode of a HierarchicalReference to ensure that the AddressSpace is fully connected and that the Node is added as a child within the AddressSpace hierarchy (see OPC 10000-3).

When a Server creates an instance of a TypeDefinitionNode it shall create the same hierarchy of Nodes beneath the new Object or Variable depending on the ModellingRule of each InstanceDeclaration. All Nodes with a ModellingRule of Mandatory shall be created or an existing Node shall be referenced that conforms to the InstanceDeclaration. The creation of Nodes with other ModellingRules is Server specific.

Table 22 defines the parameters for the Service.

Table 22 – AddNodes Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

nodesToAdd []

AddNodesItem

List of Nodes to add. All Nodes are added as a Reference to an existing Node using a hierarchical ReferenceType. This structure is defined in-line with the following indented items.

parentNodeId

Expanded NodeId

ExpandedNodeId of the parent Node for the Reference. The ExpandedNodeId type is defined in 7.16.

referenceTypeId

NodeId

NodeId of the hierarchical ReferenceType to use for the Reference from the parent Node to the new Node.

requestedNewNodeId

Expanded NodeId

Client requested expanded NodeId of the Node to add. The serverIndex in the expanded NodeId shall be 0.

If the Server cannot use this NodeId, it rejects this Node and returns the appropriate error code.

If the Client does not want to request a NodeId, then it sets the value of this parameter to the null expanded NodeId.

If the Node to add is a ReferenceType Node, its NodeId should be a numeric id. See OPC 10000-3 for a description of ReferenceType NodeIds.

browseName

QualifiedName

The browse name of the Node to add.

nodeClass

NodeClass

NodeClass of the Node to add.

nodeAttributes

Extensible Parameter

NodeAttributes

The Attributes that are specific to the NodeClass. The NodeAttributes parameter type is an extensible parameter type specified in 7.24.

A Client is allowed to omit values for some or all Attributes. If an Attribute value is null, the Server shall use the default values from the TypeDefinitionNode. If a TypeDefinitionNode was not provided the Server shall choose a suitable default value.

The Server may still add an optional Attribute to the Node with an appropriate default value even if the Client does not specify a value.

typeDefinition

Expanded NodeId

NodeId of the TypeDefinitionNode for the Node to add. This parameter shall be null for all NodeClasses other than Object and Variable in which case it shall be provided.

Response

responseHeader

Response Header

Common response parameters (see 7.34 for ResponseHeader definition).

results []

AddNodesResult

List of results for the Nodes to add. The size and order of the list matches the size and order of the nodesToAdd request parameter. This structure is defined in-line with the following indented items.

statusCode

StatusCode

StatusCode for the Node to add (see 7.39 for StatusCode definition).

addedNodeId

NodeId

Server assigned NodeId of the added Node. Null NodeId if the operation failed.

diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the Nodes to add (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the nodesToAdd 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 request.

Table 23 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 23 – AddNodes Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Table 24 defines values for the operation level statusCode parameter that are specific to this Service. Common StatusCodes are defined in Table 183.

Table 24 – AddNodes Operation Level Result Codes

Symbolic Id

Description

Bad_ParentNodeIdInvalid

The parent node id does not to refer to a valid node.

Bad_ReferenceTypeIdInvalid

See Table 183 for the description of this result code.

Bad_ReferenceNotAllowed

The reference could not be created because it violates constraints imposed by the data model.

Bad_NodeIdRejected

The requested node id was rejected either because it was invalid or because the Server does not allow node ids to be specified by the Client.

Bad_NodeIdExists

The requested node id is already used by another node.

Bad_NodeClassInvalid

See Table 183 for the description of this result code.

Bad_BrowseNameInvalid

See Table 183 for the description of this result code.

Bad_BrowseNameDuplicated

The browse name is not unique among nodes that share the same relationship with the parent.

Bad_NodeAttributesInvalid

The node Attributes are not valid for the node class.

Bad_TypeDefinitionInvalid

See Table 183 for the description of this result code.

Bad_UserAccessDenied

See Table 182 for the description of this result code.

This Service is used to add one or more References to one or more Nodes. The NodeClass is an input parameter that is used to validate that the Reference to be added matches the NodeClass of the TargetNode. This parameter is not validated if the Reference refers to a TargetNode in a remote Server.

In certain cases, adding new References to the AddressSpace shall require that the Server add new Server ids to the Server’s ServerArray Variable. For this reason, remote Servers are identified by their URI and not by their ServerArray index. This allows the Server to add the remote Server URIs to its ServerArray.

Table 25 defines the parameters for the Service.

Table 25 – AddReferences Service Parameters

Name

Type

Description

Request

requestHeader

Request Header

Common request parameters (see 7.33 for RequestHeader definition).

referencesToAdd []

AddReferences Item

List of Reference instances to add to the SourceNode. The targetNodeClass of each Reference in the list shall match the NodeClass of the TargetNode. This structure is defined in-line with the following indented items.

sourceNodeId

NodeId

NodeId of the Node to which the Reference is to be added. The source Node shall always exist in the Server to add the Reference. The isForward parameter can be set to FALSE if the target Node is on the local Server and the source Node on the remote Server.

referenceTypeId

NodeId

NodeId of the ReferenceType that defines the Reference.

isForward

Boolean

If the value is TRUE, the Server creates a forward Reference. If the value is FALSE, the Server creates an inverse Reference.

targetServerUri

String

URI of the remote Server. If this parameter is not null or empty, it overrides the serverIndex in the targetNodeId.

targetNodeId

Expanded NodeId

Expanded NodeId of the TargetNode. The ExpandedNodeId type is defined in 7.16.

targetNodeClass

NodeClass

NodeClass of the TargetNode. The Client shall specify this since the TargetNode might not be accessible directly by the Server.

Response

responseHeader

Response Header

Common response parameters (see 7.34 for ResponseHeader definition).

results []

StatusCode

List of StatusCodes for the References to add (see 7.39 for StatusCode definition). The size and order of the list matches the size and order of the referencesToAdd request parameter.

diagnosticInfos []

Diagnostic Info

List of diagnostic information for the References to add (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the referencesToAdd 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 request.

Table 26 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 26 – AddReferences Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Table 27 defines values for the results parameter that are specific to this Service. Common StatusCodes are defined in Table 183.

Table 27 – AddReferences Operation Level Result Codes

Symbolic Id

Description

Bad_SourceNodeIdInvalid

See Table 183 for the description of this result code.

Bad_ReferenceTypeIdInvalid

See Table 183 for the description of this result code.

Bad_ServerUriInvalid

See Table 182 for the description of this result code.

Bad_TargetNodeIdInvalid

See Table 183 for the description of this result code.

Bad_NodeClassInvalid

See Table 183 for the description of this result code.

Bad_ReferenceNotAllowed

The reference could not be created because it violates constraints imposed by the data model on this Server.

Bad_ReferenceLocalOnly

The reference type is not valid for a reference to a remote Server.

Bad_UserAccessDenied

See Table 182 for the description of this result code.

Bad_DuplicateReferenceNotAllowed

The reference type between the nodes is already defined.

Bad_InvalidSelfReference

The Server does not allow this type of self reference on this node.

This Service is used to delete one or more Nodes from the AddressSpace.

When any of the Nodes deleted by an invocation of this Service is the TargetNode of a Reference, then those References are left unresolved based on the deleteTargetReferences parameter.

Servers may delete additional Nodes and References like child Nodes that exist based on a TypeDefinition. The behaviour is Server specific.

When any of the Nodes deleted by an invocation of this Service is being monitored, then a Notification containing the status code Bad_NodeIdUnknown is sent to the monitoring Client indicating that the Node has been deleted.

Table 28 defines the parameters for the Service.

Table 28 – DeleteNodes Service Parameters

Name

Type

Description

Request

requestHeader

Request Header

Common request parameters (see 7.33 for RequestHeader definition).

nodesToDelete []

DeleteNodes Item

List of Nodes to delete. This structure is defined in-line with the following indented items.

nodeId

NodeId

NodeId of the Node to delete.

deleteTargetReferences

Boolean

A Boolean parameter with the following values:

TRUEdelete References in TargetNodes that Reference the Node to delete.

FALSEdelete only the References for which the Node to delete is the source.

The Server cannot guarantee that it is able to delete all References from TargetNodes if this parameter is TRUE.

Response

responseHeader

Response Header

Common response parameters (see 7.34 for ResponseHeader definition).

results []

StatusCode

List of StatusCodes for the Nodes to delete (see 7.39 for StatusCode definition). The size and order of the list matches the size and order of the list of the nodesToDelete request parameter.

diagnosticInfos []

Diagnostic Info

List of diagnostic information for the Nodes to delete (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the nodesToDelete 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 request.

Table 29 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 29 – DeleteNodes Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Table 30 defines values for the results parameter that are specific to this Service. Common StatusCodes are defined in Table 183.

Table 30 – DeleteNodes Operation Level Result Codes

Symbolic Id

Description

Bad_NodeIdInvalid

See Table 183 for the description of this result code.

Bad_NodeIdUnknown

See Table 183 for the description of this result code.

Bad_UserAccessDenied

See Table 182 for the description of this result code.

Bad_NoDeleteRights

See Table 183 for the description of this result code.

Uncertain_ReferenceNotDeleted

The Server was not able to delete all target references.

This Service is used to delete one or more References of a Node.

When any of the References deleted by an invocation of this Service are contained in a View, then the ViewVersion Property is updated if this Property is supported.

Table 31 defines the parameters for the Service.

Table 31 – DeleteReferences Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

referencesToDelete []

DeleteReferences Item

List of References to delete. This structure is defined in-line with the following indented items.

sourceNodeId

NodeId

NodeId of the Node that contains the Reference to delete.

referenceTypeId

NodeId

NodeId of the ReferenceType that defines the Reference to delete.

isForward

Boolean

If the value is TRUE, the Server deletes a forward Reference. If the value is FALSE, the Server deletes an inverse Reference.

targetNodeId

ExpandedNodeId

NodeId of the TargetNode of the Reference.

If the Server index indicates that the TargetNode is a remote Node, then the nodeId shall contain the absolute namespace URI. If the TargetNode is a local Node the nodeId shall contain the namespace index.

deleteBidirectional

Boolean

A Boolean parameter with the following values:

TRUEdelete the specified Reference and the opposite Reference from the TargetNode. If the TargetNode is located in a remote Server, the Server is permitted to delete the specified Reference only.

FALSEdelete only the specified Reference.

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader definition).

results []

StatusCode

List of StatusCodes for the References to delete (see 7.39 for StatusCode definition). The size and order of the list matches the size and order of the referencesToDelete request parameter.

diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the References to delete (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the referencesToDelete 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 request.

Table 32 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 32 – DeleteReferences Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Table 33 defines values for the results parameter that are specific to this Service. Common StatusCodes are defined in Table 183.

Table 33 – DeleteReferences Operation Level Result Codes

Symbolic Id

Description

Bad_SourceNodeIdInvalid

See Table 183 for the description of this result code.

Bad_ReferenceTypeIdInvalid

See Table 183 for the description of this result code.

Bad_ServerIndexInvalid

The Server index is not valid.

Bad_TargetNodeIdInvalid

See Table 183 for the description of this result code.

Bad_UserAccessDenied

See Table 182 for the description of this result code.

Bad_NoDeleteRights

See Table 183 for the description of this result code.

Clients use the browse Services of the View Service Set to navigate through the AddressSpace or through a View which is a subset of the AddressSpace.

A View is a subset of the AddressSpace created by the Server. Future versions of this document may also define services to create Client-defined Views. See OPC 10000-5 for a description of the organization of views in the AddressSpace.

This Service is used to discover the References of a specified Node. The browse can be further limited by the use of a View. This Browse Service also supports a primitive filtering capability.

In some cases it may take longer than the Client timeout hint to process all nodes to browse. In this case the Server may return zero results with a continuation point for the affected nodes before the timeout expires.

Table 34 defines the parameters for the Service.

Table 34 – Browse Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

View

ViewDescription

Description of the View to browse (see 7.45 for ViewDescription definition). An empty ViewDescription value indicates the entire AddressSpace. Use of the empty ViewDescription value causes all References of the nodesToBrowse to be returned. Use of any other View causes only the References of the nodesToBrowse that are defined for that View to be returned.

requestedMax

ReferencesPerNode

Counter

Indicates the maximum number of references to return for each starting Node specified in the request. The value 0 indicates that the Client is imposing no limitation (see 7.8 for Counter definition).

nodesToBrowse []

BrowseDescription

A list of nodes to Browse. This structure is defined in-line with the following indented items.

nodeId

NodeId

NodeId of the Node to be browsed. If a view is provided, it shall include this Node.

browseDirection

Enum

BrowseDirection

An enumeration that specifies the direction of References to follow. The enumeration is defined in 7.5.

The returned References do indicate the direction the Server followed in the isForward parameter of the ReferenceDescription.

Symmetric References are always considered to be in forward direction therefore the isForward flag is always set to TRUE and symmetric References are not returned if browseDirection is set to INVERSE.

referenceTypeId

NodeId

Specifies the NodeId of the ReferenceType to follow. Only instances of this ReferenceType or its subtypes are returned.

If not specified then all References are returned and includeSubtypes is ignored.

includeSubtypes

Boolean

Indicates whether subtypes of the ReferenceType should be included in the browse. If TRUE, then instances of referenceTypeId and all of its subtypes are returned.

nodeClassMask

UInt32

Specifies the NodeClasses of the TargetNodes. Only TargetNodes with the selected NodeClasses are returned. The NodeClasses are assigned the following bits:

Bit

NodeClass

0

Object

1

Variable

2

Method

3

ObjectType

4

VariableType

5

ReferenceType

6

DataType

7

View

If set to zero, then all NodeClasses are returned.

If the NodeClass is unknown for a remote Node, the nodeClassMask is ignored.

resultMask

UInt32

Specifies the fields in the ReferenceDescription structure that should be returned. The fields are assigned the following bits:

Bit

Result

0

ReferenceType

1

IsForward

2

NodeClass

3

BrowseName

4

DisplayName

5

TypeDefinition

The ReferenceDescription type is defined in 7.30.

Response

responseHeader

Response Header

Common response parameters (see 7.34 for ResponseHeader definition).

results []

BrowseResult

A list of BrowseResults. The size and order of the list matches the size and order of the nodesToBrowse specified in the request.

The BrowseResult type is defined in 7.6.

diagnosticInfos []

Diagnostic Info

List of diagnostic information for the results (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the results response 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 request.

Table 35 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 35 – Browse Service Result Codes

Symbolic Id

Description

Bad_ViewIdUnknown

See Table 182 for the description of this result code.

Bad_ViewTimestampInvalid

See Table 182 for the description of this result code.

Bad_ViewParameterMismatchInvalid

See Table 182 for the description of this result code.

Bad_ViewVersionInvalid

See Table 182 for the description of this result code.

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Table 36 defines values for the results parameter that are specific to this Service. Common StatusCodes are defined in Table 183.

Table 36 – Browse Operation Level Result Codes

Symbolic Id

Description

Bad_NodeIdInvalid

See Table 183 for the description of this result code.

Bad_NodeIdUnknown

See Table 183 for the description of this result code.

Bad_ReferenceTypeIdInvalid

See Table 183 for the description of this result code.

Bad_BrowseDirectionInvalid

See Table 183 for the description of this result code.

Bad_NodeNotInView

See Table 183 for the description of this result code.

Bad_NoContinuationPoints

See Table 183 for the description of this result code.

Uncertain_NotAllNodesAvailable

Browse results may be incomplete because of the unavailability of a subsystem.

This Service is used to request the next set of Browse or BrowseNext response information that is too large to be sent in a single response. “Too large” in this context means that the Server is not able to return a larger response or that the number of results to return exceeds the maximum number of results to return that was specified by the Client in the original Browse request. The BrowseNext shall be submitted on the same Session that was used to submit the Browse or BrowseNext that is being continued.

Table 37 defines the parameters for the Service.

Table 37 – BrowseNext Service Parameters

Name

Type

Description

Request

requestHeader

Request Header

Common request parameters (see 7.33 for RequestHeader definition).

releaseContinuationPoints

Boolean

A Boolean parameter with the following values:

TRUEpassed continuationPoints shall be reset to free resources in the Server. The continuation points are released and the results and diagnosticInfos arrays are empty.

FALSEpassed continuationPoints shall be used to get the next set of browse information.

A Client shall always use the continuation point returned by a Browse or BrowseNext response to free the resources for the continuation point in the Server. If the Client does not want to get the next set of browse information, BrowseNext shall be called with this parameter set to TRUE.

continuationPoints []

Continuation Point

A list of Server-defined opaque values that represent continuation points. The value for a continuation point was returned to the Client in a previous Browse or BrowseNext response. These values are used to identify the previously processed Browse or BrowseNext request that is being continued and the point in the result set from which the browse response is to continue.

Clients may mix continuation points from different Browse or BrowseNext responses.

The ContinuationPoint type is described in 7.9.

Response

responseHeader

Response Header

Common response parameters (see 7.34 for ResponseHeader definition).

results []

BrowseResult

A list of references that met the criteria specified in the original Browse request.

The size and order of this list matches the size and order of the continuationPoints request parameter.

The BrowseResult type is defined in 7.6.

diagnosticInfos []

Diagnostic Info

List of diagnostic information for the results (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the results response 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 request.

Table 38 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 38 – BrowseNext Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Table 39 defines values for the results parameter that are specific to this Service. Common StatusCodes are defined in Table 183.

Table 39 – BrowseNext Operation Level Result Codes

Symbolic Id

Description

Bad_NodeIdInvalid

See Table 183 for the description of this result code.

Bad_NodeIdUnknown

See Table 183 for the description of this result code.

Bad_ReferenceTypeIdInvalid

See Table 183 for the description of this result code.

Bad_BrowseDirectionInvalid

See Table 183 for the description of this result code.

Bad_NodeNotInView

See Table 183 for the description of this result code.

Bad_ContinuationPointInvalid

See Table 183 for the description of this result code.

This Service is used to request that the Server translates one or more browse paths to NodeIds. Each browse path is constructed of a starting Node and a RelativePath. The specified starting Node identifies the Node from which the RelativePath is based. The RelativePath contains a sequence of ReferenceTypes and BrowseNames.

One purpose of this Service is to allow programming against type definitions. Since BrowseNames shall be unique in the context of type definitions, a Client may create a browse path that is valid for a type definition and use this path on instances of the type. For example, an ObjectType “Boiler” may have a “HeatSensor” Variable as InstanceDeclaration. A graphical element programmed against the “Boiler” may need to display the Value of the “HeatSensor”. If the graphical element would be called on “Boiler1”, an instance of “Boiler”, it would need to call this Service specifying the NodeId of “Boiler1” as starting Node and the BrowseName of the “HeatSensor” as browse path. The Service would return the NodeId of the “HeatSensor” of “Boiler1” and the graphical element could subscribe to its Value Attribute.

If a Node has multiple targets with the same BrowseName, the Server shall return a list of NodeIds. However, since one of the main purposes of this Service is to support programming against type definitions, the NodeId of the Node based on the type definition of the starting Node is returned as the first NodeId in the list.

Table 40 defines the parameters for the Service.

Table 40 – TranslateBrowsePathsToNodeIds Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

browsePaths []

BrowsePath

List of browse paths for which NodeIds are being requested. This structure is defined in-line with the following indented items.

startingNode

NodeId

NodeId of the starting Node for the browse path.

relativePath

RelativePath

The path to follow from the startingNode.

The last element in the relativePath shall always have a targetName specified. This further restricts the definition of the RelativePath type. The Server shall return Bad_BrowseNameInvalid if the targetName is missing.

The RelativePath structure is defined in 7.31.

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader definition).

results []

BrowsePathResult

List of results for the list of browse paths. The size and order of the list matches the size and order of the browsePaths request parameter. This structure is defined in-line with the following indented items.

statusCode

StatusCode

StatusCode for the browse path (see 7.39 for StatusCode definition).

targets []

BrowsePathTarget

List of targets for the relativePath from the startingNode. This structure is defined in-line with the following indented items.

A Server may encounter a Reference to a Node in another Server which it cannot follow while it is processing the RelativePath. If this happens the Server returns the NodeId of the external Node and sets the remainingPathIndex parameter to indicate which RelativePath elements still need to be processed. To complete the operation the Client shall connect to the other Server and call this service again using the target as the startingNode and the unprocessed elements as the relativePath.

targetId

ExpandedNodeId

The identifier for a target of the RelativePath.

remainingPathIndex

Index

The index of the first unprocessed element in the RelativePath.

This value shall be equal to the maximum value of Index data type if all elements were processed (see 7.18 for Index definition).

diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the list of browse paths (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the browsePaths 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 request.

Table 41 defines the Service results specific to this Service. Common StatusCodes are defined in 7.39.

Table 41 – TranslateBrowsePathsToNodeIds Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Table 42 defines values for the operation level statusCode parameters that are specific to this Service. Common StatusCodes are defined in Table 183.

Table 42 – TranslateBrowsePathsToNodeIds Operation Level Result Codes

Symbolic Id

Description

Bad_NodeIdInvalid

See Table 183 for the description of this result code.

Bad_NodeIdUnknown

See Table 183 for the description of this result code.

Bad_NothingToDo

See Table 182 for the description of this result code.

This code indicates that the relativePath contained an empty list.

Bad_BrowseNameInvalid

See Table 183 for the description of this result code.

This code indicates that a TargetName was missing in a RelativePath.

Uncertain_ReferenceOutOfServer

The path element has targets which are in another Server.

Bad_TooManyMatches

The requested operation has too many matches to return.

Users should use queries for large result sets. Servers should allow at least 10 matches before returning this error code.

Bad_QueryTooComplex

The requested operation requires too many resources in the Server.

Bad_NoMatch

The requested relativePath cannot be resolved to a target to return.

A Server often has no direct access to the information that it manages. Variables or services might be in underlying systems where additional effort is required to establish a connection to these systems. The RegisterNodes Service can be used by Clients to register the Nodes that they know they will access repeatedly (e.g. Write, Call). It allows Servers to set up anything needed so that the access operations will be more efficient. Clients can expect performance improvements when using registered NodeIds, but the optimization measures are vendor-specific. For Variable Nodes Servers shall concentrate their optimization efforts on the Value Attribute.

Registered NodeIds are only guaranteed to be valid within the current Session. Clients shall unregister unneeded Ids immediately to free up resources.

RegisterNodes does not validate the NodeIds from the request. Servers will simply copy unknown NodeIds in the response. Structural NodeId errors (size violations, invalid id types) will cause the complete Service to fail.

For the purpose of Auditing, Servers shall not use the registered NodeIds but only the canonical NodeIds which is the value of the NodeId Attribute.

Table 43 defines the parameters for the Service.

Table 43 – RegisterNodes Service Parameters

Name

Type

Description

Request

requestHeader

Request Header

Common request parameters (see 7.33 for RequestHeader definition).

nodesToRegister []

NodeId

List of NodeIds to register that the Client has retrieved through browsing, querying or in some other manner.

Response

responseHeader

Response Header

Common response parameters (see 7.34 for ResponseHeader definition).

registeredNodeIds []

NodeId

A list of NodeIds which the Client shall use for subsequent access operations. The size and order of this list matches the size and order of the nodesToRegister request parameter.

The Server may return the NodeId from the request or a new (an alias) NodeId. It is recommended that the Server return a numeric NodeIds for aliasing.

In case no optimization is supported for a Node, the Server shall return the NodeId from the request.

Table 44 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 44 – RegisterNodes Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Bad_NodeIdInvalid

See Table 183 for the description of this result code.

Servers shall completely reject the RegisterNodes request if any of the NodeIds in the nodesToRegister parameter are structurally invalid.

This Service is used to unregister NodeIds that have been obtained via the RegisterNodes service.

UnregisterNodes does not validate the NodeIds from the request. Servers shall simply unregister NodeIds that are known as registered NodeIds. Any NodeIds that are in the list, but are not registered NodeIds are simply ignored.

Table 50 defines the parameters for the Service.

Table 45 – UnregisterNodes Service Parameters

Name

Type

Description

Request

requestHeader

Request Header

Common request parameters (see 7.33 for RequestHeader definition).

nodesToUnregister []

NodeId

A list of NodeIds that have been obtained via the RegisterNodes service.

Response

responseHeader

Response Header

Common response parameters (see 7.34 for ResponseHeader definition).

Table 51 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 46 – UnregisterNodes Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

This Service Set is used to issue a Query to a Server. OPC UA Query is generic in that it provides an underlying storage mechanism independent Query capability that can be used to access a wide variety of OPC UA data stores and information management systems. OPC UA Query permits a Client to access data maintained by a Server without any knowledge of the logical schema used for internal storage of the data. Knowledge of the AddressSpace is sufficient.

An OPC UA Application is expected to use the OPC UA Query Services as part of an initialization process or an occasional information synchronization step. For example, OPC UA Query would be used for bulk data access of a persistent store to initialise an analysis application with the current state of a system configuration. A Query may also be used to initialise or populate data for a report.

A Query defines what instances of one or more TypeDefinitionNodes in the AddressSpace should supply a set of Attributes. Results returned by a Server are in the form of an array of QueryDataSets. The selected Attribute values in each QueryDataSet come from the definition of the selected TypeDefinitionNodes or related TypeDefinitionNodes and appear in results in the same order as the Attributes that were passed into the Query. Query also supports Node filtering on the basis of Attribute values, as well as relationships between TypeDefinitionNodes.

See Annex B for example queries.

A View is a subset of the AddressSpace available in the Server. See OPC 10000-5 for a description of the organization of Views in the AddressSpace.

For any existing View, a Query may be used to return a subset of data from the View. When an application issues a Query against a View, only data defined by the View is returned. Data not included in the View but included in the original AddressSpace is not returned.

The Query Services supports access to current and historical data. The Service supports a Client querying a past version of the AddressSpace. Clients may specify a ViewVersion or a Timestamp in a Query to access past versions of the AddressSpace. OPC UA Query is complementary to Historical Access in that the former is used to Query an AddressSpace that existed at a time and the latter is used to Query for the value of Attributes over time. In this way, a Query can be used to retrieve a portion of a past AddressSpace so that Attribute value history may be accessed using Historical Access even if the Node is no longer in the current AddressSpace.

Servers that support Query are expected to be able to access the AddressSpace that is associated with the local Server and any Views that are available on the local Server. If a View or the AddressSpace also references a remote Server, query may be able to access the AddressSpace of the remote Server, but it is not required. If a Server does access a remote Server the access shall be accomplished using the user identity of the Client as described in 5.5.1.

This Service is used to issue a Query request to the Server. The complexity of the Query can range from very simple to highly sophisticated. The Query can simply request data from instances of a TypeDefinitionNode or TypeDefinitionNode subject to restrictions specified by the filter. On the other hand, the Query can request data from instances of related Node types by specifying a RelativePath from an originating TypeDefinitionNode. In the filter, a separate set of paths can be constructed for limiting the instances that supply data. A filtering path can include multiple RelatedTo operators to define a multi-hop path between source instances and target instances. For example, one could filter on students that attend a particular school, but return information about students and their families. In this case, the student school relationship is traversed for filtering, but the student family relationship is traversed to select data. For a complete description of ContentFilter see 7.7, also see Clause B.1 for simple examples and Clause B.2 for more complex examples of content filter and queries.

The Client provides an array of NodeTypeDescription which specify the NodeId of a TypeDefinitionNode and selects what Attributes are to be returned in the response. A Client can also provide a set of RelativePaths through the type system starting from an originating TypeDefinitionNode. Using these paths, the Client selects a set of Attributes from Nodes that are related to instances of the originating TypeDefinitionNode. Additionally, the Client can request the Server return instances of subtypes of TypeDefinitionNodes. If a selected Attribute does not exist in a TypeDefinitionNode but does exist in a subtype, it is assumed to have a null value in the TypeDefinitionNode in question. Therefore, this does not constitute an error condition and a null value is returned for the Attribute.

The Client can use the filter parameter to limit the result set by restricting Attributes and Properties to certain values. Another way the Client can use a filter to limit the result set is by specifying how instances should be related, using RelatedTo operators. In this case, if an instance at the top of the RelatedTo path cannot be followed to the bottom of the path via specified hops, no QueryDataSets are returned for the starting instance or any of the intermediate instances.

When querying for related instances in the RelativePath, the Client can optionally ask for References. A Reference is requested via a RelativePath that only includes a ReferenceType. If all References are desired than the root ReferenceType is listed. These References are returned as part of the QueryDataSets.

Query Services allow a special handling of the targetName field in the RelativePath. In several Query use cases a type NodeId is necessary in the path instead of a QualifiedName. Therefore the Client is allowed to specify a NodeId in the QualifiedName. This is done by setting the namespaceIndex of the targetName to zero and the name part of the targetName to the XML representation of the NodeId. The XML representation is defined in OPC 10000-6. When matching instances are returned as the target node, the target node shall be an instance of the specified type or subtype of the specified type.

Table 47 defines the request parameters and Table 48 the response parameters for the QueryFirst Service.

Table 47 – QueryFirst Request Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

View

ViewDescription

Specifies a View and temporal context to a Server (see 7.45 for ViewDescription definition).

nodeTypes []

NodeTypeDescription

This is the Node type description. This structure is defined in-line with the following indented items.

typeDefinitionNode

ExpandedNodeId

NodeId of the originating TypeDefinitionNode of the instances for which data is to be returned.

includeSubTypes

Boolean

A flag that indicates whether the Server should include instances of subtypes of the TypeDefinitionNode in the list of instances of the Node type.

dataToReturn []

QueryDataDescription

Specifies an Attribute or Reference from the originating typeDefinitionNode along a given relativePath for which to return data. This structure is defined in-line with the following indented items.

relativePath

RelativePath

Browse path relative to the originating Node that identifies the Node which contains the data that is being requested, where the originating Node is an instance Node of the type defined by the type definition Node. The instance Nodes are further limited by the filter provided as part of this call. For a definition of relativePath see 7.31.

This relative path could end on a Reference, in which case the ReferenceDescription of the Reference would be returned as its value.

The targetName field of the relativePath may contain a type NodeId. This is done by setting the namespaceIndex of the targetName to zero and the name part of the targetName to the XML representation of the NodeId. The XML representation is defined in OPC 10000-6.

When matching instances are returned as the target node, the target node shall be an instance of the specified type or subtype of the specified type.

attributeId

IntegerId

Id of the Attribute. This shall be a valid Attribute Id. The IntegerId is defined in 7.19. The IntegerId for Attributes are defined in OPC 10000-6. If the RelativePath ended in a Reference then this parameter is 0 and ignored by the Server.

indexRange

NumericRange

This parameter is used to identify a single element of a structure or an array, or a single range of indexes for arrays. If a range of elements are specified, the values are returned as a composite. The first element is identified by index 0 (zero). The NumericRange type is defined in 7.27.

This parameter is null or empty if the specified Attribute is not an array or a structure. However, if the specified Attribute is an array or a structure, and this parameter is null or empty, then all elements are to be included in the range.

Filter

ContentFilter

Resulting Nodes shall be limited to the Nodes matching the criteria defined by the filter. ContentFilter is discussed in 7.7. If an empty filter is provided then the entire AddressSpace shall be examined and all Nodes that contain a matching requested Attribute or Reference are returned.

maxDataSetsToReturn

Counter

The number of QueryDataSets that the Client wants the Server to return in the response and on each subsequent continuation call response. The Server is allowed to further limit the response, but shall not exceed this limit.

A value of 0 indicates that the Client is imposing no limitation.

maxReferencesToReturn

Counter

The number of References that the Client wants the Server to return in the response for each QueryDataSet and on each subsequent continuation call response. The Server is allowed to further limit the response, but shall not exceed this limit.

A value of 0 indicates that the Client is imposing no limitation.

For example a result where 4 Nodes are being returned, but each has 100 References, if this limit were set to 50 then only the first 50 References for each Node would be returned on the initial call and a continuation point would be set indicating additional data.

Table 48 – QueryFirst Response Parameters

Name

Type

Description

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader definition).

queryDataSets []

QueryDataSet

The array of QueryDataSets. This array is empty if no Nodes or References met the nodeTypes criteria. In this case the continuationPoint parameter shall be empty.

The QueryDataSet type is defined in 7.28.

continuationPoint

ContinuationPoint

Server-defined opaque value that identifies the continuation point.

The continuation point is used only when the Query results are too large to be returned in a single response. “Too large” in this context means that the Server is not able to return a larger response or that the number of QueryDataSets to return exceeds the maximum number of QueryDataSets to return that was specified by the Client in the request.

The continuation point is used in the QueryNext Service. When not used, the value of this parameter is null or empty. If a continuation point is returned, the Client shall call QueryNext to get the next set of QueryDataSets or to free the resources for the continuation point in the Server.

A continuation point shall remain active until the Client passes the continuation point to QueryNext or the session is closed. If the maximum continuation points have been reached the oldest continuation point shall be reset.

The ContinuationPoint type is described in 7.9.

parsingResults[]

ParsingResult

List of parsing results for QueryFirst. The size and order of the list matches the size and order of the NodeTypes request parameter. This structure is defined in-line with the following indented items.

This list is populated with any status codes that are related to the processing of the node types that are part of the query. The array can be empty if no errors where encountered. If any node type encountered an error all node types shall have an associated status code.

statusCode

StatusCode

Parsing result for the requested NodeTypeDescription.

dataStatusCodes []

StatusCode

List of results for dataToReturn. The size and order of the list matches the size and order of the dataToReturn request parameter. The array can be empty if no errors where encountered.

dataDiagnosticInfos []

DiagnosticInfo

List of diagnostic information dataToReturn (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the dataToReturn 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 query request.

diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the requested NodeTypeDescription. 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 query request.

filterResult

ContentFilter

Result

A structure that contains any errors associated with the filter.

This structure shall be empty if no errors occurred.

The ContentFilterResult type is defined in 7.7.2.

If the Query is invalid or cannot be processed, then QueryDataSets are not returned and only a Service result, filterResult, parsingResults and optional DiagnosticInfo is returned. Table 49 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 49 – QueryFirst Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Bad_ContentFilterInvalid

See Table 183 for the description of this result code.

Bad_ViewIdUnknown

See Table 182 for the description of this result code.

Bad_ViewTimestampInvalid

See Table 182 for the description of this result code.

Bad_ViewParameterMismatchInvalid

See Table 182 for the description of this result code.

Bad_ViewVersionInvalid

See Table 182 for the description of this result code.

Bad_InvalidFilter

The provided filter is invalid, see the filterResult for specific errors

Bad_NodelistError

The NodeTypes provided contain an error, see the parsingResults for specific errors

Bad_InvalidView

The provided ViewDescription is not a valid ViewDescription.

Good_ResultsMayBeIncomplete

The Server should have followed a reference to a node in a remote Server but did not. The result set may be incomplete.

Table 50 defines values for the parsingResults statusCode parameter that are specific to this Service. Common StatusCodes are defined in Table 183.

Table 50 – QueryFirst Operation Level Result Codes

Symbolic Id

Description

Bad_NodeIdInvalid

See Table 183 for the description of this result code.

Bad_NodeIdUnknown

See Table 183 for the description of this result code.

Bad_NotTypeDefinition

The provided NodeId was not a type definition NodeId.

Bad_AttributeIdInvalid

See Table 183 for the description of this result code.

Bad_IndexRangeInvalid

See Table 183 for the description of this result code.

This Service is used to request the next set of QueryFirst or QueryNext response information that is too large to be sent in a single response. “Too large” in this context means that the Server is not able to return a larger response or that the number of QueryDataSets to return exceeds the maximum number of QueryDataSets to return that was specified by the Client in the original request. The QueryNext shall be submitted on the same session that was used to submit the QueryFirst or QueryNext that is being continued.

Table 51 defines the parameters for the Service.

Table 51 – QueryNext Service Parameters

Name

Type

Description

Request

requestHeader

Request Header

Common request parameters (see 7.33 for RequestHeader definition).

releaseContinuationPoint

Boolean

A Boolean parameter with the following values:

TRUEpassed continuationPoint shall be reset to free resources for the continuation point in the Server.

FALSEpassed continuationPoint shall be used to get the next set of QueryDataSets.

A Client shall always use the continuation point returned by a QueryFirst or QueryNext response to free the resources for the continuation point in the Server. If the Client does not want to get the next set of Query information, QueryNext shall be called with this parameter set to TRUE.

If the parameter is set to TRUE all array parameters in the response shall contain empty arrays.

continuationPoint

ContinuationPoint

Server defined opaque value that represents the continuation point. The value of the continuation point was returned to the Client in a previous QueryFirst or QueryNext response. This value is used to identify the previously processed QueryFirst or QueryNext request that is being continued, and the point in the result set from which the browse response is to continue.

The ContinuationPoint type is described in 7.9.

Response

responseHeader

Response Header

Common response parameters (see 7.34 for ResponseHeader definition).

queryDataSets []

QueryDataSet

The array of QueryDataSets.

The QueryDataSet type is defined in 7.28.

revisedContinuationPoint

ContinuationPoint

Server-defined opaque value that represents the continuation point. It is used only if the information to be returned is too large to be contained in a single response. When not used or when releaseContinuationPoint is set, the value of this parameter is null or empty.

The ContinuationPoint type is described in 7.9.

Table 52 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 52 – QueryNext Service Result Codes

Symbolic Id

Description

Bad_ContinuationPointInvalid

See Table 183 for the description of this result code.

This Service Set provides Services to access Attributes that are part of Nodes.

This Service is used to read one or more Attributes of one or more Nodes. For constructed Attribute values whose elements are indexed, such as an array, this Service allows Clients to read the entire set of indexed values as a composite, to read individual elements or to read ranges of elements of the composite.

The maxAge parameter is used to direct the Server to access the value from the underlying data source, such as a device, if its copy of the data is older than that which the maxAge specifies. If the Server cannot meet the requested maximum age, it returns its “best effort” value rather than rejecting the request.

Table 53 defines the parameters for the Service.

Table 53 – Read Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

maxAge

Duration

Maximum age of the value to be read in milliseconds. The age of the value is based on the difference between the ServerTimestamp and the time when the Server starts processing the request. For example if the Client specifies a maxAge of 500 milliseconds and it takes 100 milliseconds until the Server starts processing the request, the age of the returned value could be 600 milliseconds prior to the time it was requested.

If the Server has one or more values of an Attribute that are within the maximum age, it can return any one of the values or it can read a new value from the data source. The number of values of an Attribute that a Server has depends on the number of MonitoredItems that are defined for the Attribute. In any case, the Client can make no assumption about which copy of the data will be returned.

If the Server does not have a value that is within the maximum age, it shall attempt to read a new value from the data source.

If the Server cannot meet the requested maxAge, it returns its “best effort” value rather than rejecting the request. This may occur when the time it takes the Server to process and return the new data value after it has been accessed is greater than the specified maximum age.

If maxAge is set to 0, the Server shall attempt to read a new value from the data source.

If maxAge is set to the max Int32 value or greater, the Server shall attempt to get a cached value.

Negative values are invalid for maxAge.

timestampsTo

Return

Enum

TimestampsTo Return

An enumeration that specifies the Timestamps to be returned for each requested Variable Value Attribute. The TimestampsToReturn enumeration is defined in 7.40.

nodesToRead []

ReadValueId

List of Nodes and their Attributes to read. For each entry in this list, a StatusCode is returned, and if it indicates success, the Attribute Value is also returned. The ReadValueId parameter type is defined in 7.29.

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader definition).

results []

DataValue

List of Attribute values (see 7.11 for DataValue definition). The size and order of this list matches the size and order of the nodesToRead request parameter. There is one entry in this list for each Node contained in the nodesToRead parameter.

diagnosticInfos []

DiagnosticInfo

List of diagnostic information (see 7.12 for DiagnosticInfo definition). The size and order of this list matches the size and order of the nodesToRead request parameter. There is one entry in this list for each Node contained in the nodesToRead 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 request.

Table 54 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 54 – Read Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Bad_MaxAgeInvalid

The max age parameter is invalid.

Bad_TimestampsToReturnInvalid

See Table 182 for the description of this result code.

Table 55 defines values for the operation level statusCode contained in the DataValue structure of each results element. Common StatusCodes are defined in Table 183.

Table 55 – Read Operation Level Result Codes

Symbolic Id

Description

Bad_NodeIdInvalid

See Table 183 for the description of this result code.

Bad_NodeIdUnknown

See Table 183 for the description of this result code.

Bad_AttributeIdInvalid

See Table 183 for the description of this result code.

Bad_IndexRangeInvalid

See Table 183 for the description of this result code.

Bad_IndexRangeNoData

See Table 183 for the description of this result code.

Bad_DataEncodingInvalid

See Table 183 for the description of this result code.

Bad_DataEncodingUnsupported

See Table 183 for the description of this result code.

Bad_NotReadable

See Table 183 for the description of this result code.

Bad_UserAccessDenied

See Table 182 for the description of this result code.

Bad_SecurityModeInsufficient

See Table 183 for the description of this result code.

This Service is used to read historical values or Events of one or more Nodes. For constructed Attribute values whose elements are indexed, such as an array, this Service allows Clients to read the entire set of indexed values as a composite, to read individual elements or to read ranges of elements of the composite. Servers may make historical values available to Clients using this Service, although the historical values themselves are not visible in the AddressSpace.

The AccessLevel Attribute defined in OPC 10000-3 indicates a Node’s support for historical values. Several request parameters indicate how the Server is to access values from the underlying history data source. The EventNotifier Attribute defined in OPC 10000-3 indicates a Node’s support for historical Events.

The continuationPoint parameter in the HistoryRead is used to mark a point from which to continue the read if not all values could be returned in one response. The value is opaque for the Client and is only used to maintain the state information for the Server to continue from. A Server may use the timestamp of the last returned data item if the timestamp is unique. This can reduce the need in the Server to store state information for the continuation point.

In some cases it may take longer than the Client timeout hint to read the data for all nodes to read. Then the Server may return zero results with a continuation point for the affected nodes before the timeout expires. That allows the Server to resume the data acquisition on the next Client read call.

For additional details on reading historical data and historical Events see OPC 10000-11.

Table 56 defines the parameters for the Service.

Table 56 – HistoryRead Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

historyReadDetails

Extensible Parameter

HistoryReadDetails

The details define the types of history reads that can be performed. The HistoryReadDetails parameter type is an extensible parameter type formally defined in OPC 10000-11. The ExtensibleParameter type is defined in 7.17.

timestampsToReturn

Enum

TimestampsTo Return

An enumeration that specifies the timestamps to be returned for each requested Variable Value Attribute. The TimestampsToReturn enumeration is defined in 7.40.

Specifying a TimestampsToReturn of NEITHER is not valid. A Server shall return a Bad_TimestampsToReturnInvalid StatusCode in this case.

OPC 10000-11 defines exceptions where this parameter shall be ignored.

releaseContinuation

Points

Boolean

A Boolean parameter with the following values:

TRUEpassed continuationPoints shall be reset to free resources in the Server.

FALSEpassed continuationPoints shall be used to get the next set of historical information.

A Client shall always use the continuation point returned by a HistoryRead response to free the resources for the continuation point in the Server. If the Client does not want to get the next set of historical information, HistoryRead shall be called with this parameter set to TRUE.

nodesToRead []

HistoryReadValueId

This parameter contains the list of items upon which the historical retrieval is to be performed. This structure is defined in-line with the following indented items.

nodeId

NodeId

If the HistoryReadDetails is RAW, PROCESSED, MODIFIED or ATTIME:

The nodeId of the Nodes whose historical values are to be read. The value returned shall always include a timestamp.

If the HistoryReadDetails is EVENTS:

The NodeId of the Node whose Event history is to be read.

If the Node does not support the requested access for historical values or historical Events the appropriate error response for the given Node shall be generated.

indexRange

NumericRange

This parameter is used to identify a single element of an array, or a single range of indexes for arrays. If a range of elements is specified, the values are returned as a composite. The first element is identified by index 0 (zero). The NumericRange type is defined in 7.27.

This parameter is null or empty if the value is not an array. However, if the value is an array, and this parameter is null or empty, then all elements are to be included in the range.

dataEncoding

QualifiedName

A QualifiedName that specifies the data encoding to be returned for the Value to be read (see 7.29 for definition how to specify the data encoding).

This parameter only applies if the DataType of the Variable is a subtype of Structure. It is an error to specify this parameter if the DataType of the Variable is not a subtype of Structure.

The parameter is ignored when reading history of Events.

continuationPoint

ContinuationPoint

For each NodesToRead item this parameter specifies a continuation point returned from a previous HistoryRead call, allowing the Client to continue that read from the last value received.

The HistoryRead is used to select an ordered sequence of historical values or events. A continuation point marks a point in that ordered sequence, such that the Server returns the subset of the sequence that follows that point.

A null or empty value indicates that this parameter is not used.

See 7.9 for a general description of continuation points.

This continuation point is described in more detail in OPC 10000-11.

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader type).

results []

HistoryReadResult

List of read results. The size and order of the list matches the size and order of the nodesToRead request parameter. This structure is defined in-line with the following indented items.

statusCode

StatusCode

StatusCode for the NodesToRead item (see 7.39 for StatusCode definition).

continuationPoint

ContinuationPoint

This parameter is used only if the number of values to be returned is too large to be returned in a single response or if the timeout provided as hint by the Client is close to expiring and not all nodes have been processed.

When this parameter is not used, its value is null or empty.

Servers shall support at least one continuation point per Session. Servers specify a max history continuation points per Session in the Server capabilities Object defined in OPC 10000-5. A continuation point shall remain active until the Client passes the continuation point to HistoryRead or the Session is closed. If the max continuation points have been reached the oldest continuation point shall be reset.

historyData

Extensible Parameter

HistoryData

The history data returned for the Node.

The HistoryData parameter type is an extensible parameter type formally defined in OPC 10000-11. It specifies the types of history data that can be returned. The ExtensibleParameter base type is defined in 7.17.

diagnosticInfos []

Diagnostic Info

List of diagnostic information. The size and order of the list matches the size and order of the nodesToRead request parameter. There is one entry in this list for each Node contained in the nodesToRead 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 request.

Table 57 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 57 – HistoryRead Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Bad_TimestampsToReturnInvalid

See Table 182 for the description of this result code.

Bad_HistoryOperationInvalid

See Table 183 for the description of this result code.

Bad_HistoryOperationUnsupported

See Table 183 for the description of this result code.

The requested history operation is not supported by the Server.

Table 58 defines values for the operation level statusCode parameter that are specific to this Service. Common StatusCodes are defined in Table 183. History access specific StatusCodes are defined in OPC 10000-11.

Table 58 – HistoryRead Operation Level Result Codes

Symbolic Id

Description

Bad_NodeIdInvalid

See Table 183 for the description of this result code.

Bad_NodeIdUnknown

See Table 183 for the description of this result code.

Bad_DataEncodingInvalid

See Table 183 for the description of this result code.

Bad_DataEncodingUnsupported

See Table 183 for the description of this result code.

Bad_UserAccessDenied

See Table 182 for the description of this result code.

Bad_ContinuationPointInvalid

See Table 182 for the description of this result code.

Bad_IndexRangeInvalid

See Table 183 for the description of this result code.

Bad_IndexRangeNoData

See Table 183 for the description of this result code.

Bad_HistoryOperationUnsupported

See Table 183 for the description of this result code.

The requested history operation is not supported for the requested node.

Bad_NoContinuationPoints

See Table 183 for the description of this result code.

See 7.9 for the rules to apply this status code.

This Service is used to write values to one or more Attributes of one or more Nodes. For constructed Attribute values whose elements are indexed, such as an array, this Service allows Clients to write the entire set of indexed values as a composite, to write individual elements or to write ranges of elements of the composite.

The values are written to the data source, such as a device, and the Service does not return until it writes the values or determines that the value cannot be written. In certain cases, the Server will successfully write to an intermediate system or Server, and will not know if the data source was updated properly. In these cases, the Server should report a success code that indicates that the write was not verified. In the cases where the Server is able to verify that it has successfully written to the data source, it reports an unconditional success.

The order the operations are processed in the Server is not defined and depends on the different data sources and the internal Server logic. If an Attribute and Node combination is contained in more than one operation, the order of the processing is undefined. If a Client requires sequential processing the Client needs separate Service calls.

It is possible that the Server may successfully write some Attributes, but not others. Rollback is the responsibility of the Client.

If a Server allows writing of Attributes with the DataType LocalizedText, the Client can add or overwrite the text for a locale by writing the text with the associated LocaleId. Writing a null String for the text for a locale shall delete the String for that locale. Writing a null String for the locale and a non-null String for the text is setting the text for an invariant locale. Writing a null String for the text and a null String for the locale shall delete the entries for all locales. If a Client attempts to write a locale that is either syntactically invalid or not supported, the Server returns Bad_LocaleNotSupported. The Write behaviour for Value Attributes with a LocalizedText DataType is Server specific but it is recommended to follow the same rules.

Table 59 defines the parameters for the Service.

Table 59 – Write Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

nodesToWrite []

WriteValue

List of Nodes and their Attributes to write. This structure is defined in-line with the following indented items.

nodeId

NodeId

NodeId of the Node that contains the Attributes.

attributeId

IntegerId

Id of the Attribute. This shall be a valid Attribute id. The IntegerId is defined in 7.19. The IntegerIds for the Attributes are defined in OPC 10000-6.

indexRange

NumericRange

This parameter is used to identify a single element of an array, or a single range of indexes for arrays. The array in this context includes String and ByteString. The first element is identified by index 0 (zero). The NumericRange type is defined in 7.27.

This parameter is not used if the specified Attribute is not an array. However, if the specified Attribute is an array and this parameter is not used, then all elements are to be included in the range. The parameter is null or empty if not used.

A Server shall return a Bad_WriteNotSupported error if an indexRange is provided and writing of indexRange is not possible for the Node.

value

DataValue

The Node’s Attribute value (see 7.11 for DataValue definition).

If the indexRange parameter is specified then the Value shall be an array even if only one element is being written.

If the SourceTimestamp or the ServerTimestamp is specified, the Server shall use these values. The Server returns a Bad_WriteNotSupported error if it does not support writing of timestamps.

A Server shall return a Bad_TypeMismatch error if the data type of the written value is not the same type or subtype of the Attribute’s DataType. Based on the DataType hierarchy, subtypes of the Attribute DataType shall be accepted by the Server. Servers may reject subtypes defined in newer specification versions than supported by the Server with Bad_TypeMismatch. For the Value Attribute the DataType is defined through the DataType Attribute. A ByteString is structurally the same as a one dimensional array of Byte. A Server shall accept a ByteString if an array of Byte is expected.

The Server returns a Bad_DataEncodingUnsupported error if it does not support the provided data encoding.

Simple DataTypes (see OPC 10000-3) use the same representation on the wire as their super types and therefore writing a value of a simple DataType cannot be distinguished from writing a value of its super type. The Server shall assume that by receiving the correct wire representation for a simple DataType the correct type was chosen. Servers are allowed to impose additional data validations on the value independent of the encoding (e.g. having an image in GIF format in a ByteString). In this case the Server shall return a Bad_TypeMismatch error if the validation fails.

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader definition).

results []

StatusCode

List of results for the Nodes to write (see 7.39 for StatusCode definition). The size and order of the list matches the size and order of the nodesToWrite request parameter. There is one entry in this list for each Node contained in the nodesToWrite parameter.

diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the Nodes to write (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the nodesToWrite 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 request.

Table 60 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 60 – Write Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Table 61 defines values for the results parameter that are specific to this Service. Common StatusCodes are defined in Table 183.

Table 61 – Write Operation Level Result Codes

Symbolic Id

Description

Good_CompletesAsynchronously

See Table 182 for the description of this result code.

The value was successfully written to an intermediate system but the Server does not know if the data source was updated properly.

Bad_NodeIdInvalid

See Table 183 for the description of this result code.

Bad_NodeIdUnknown

See Table 183 for the description of this result code.

Bad_AttributeIdInvalid

See Table 183 for the description of this result code.

Bad_IndexRangeInvalid

See Table 183 for the description of this result code.

It is also used if writing of IndexRange is supported in general for a Node but the passed IndexRange cannot be written by the Server.

Bad_IndexRangeNoData

See Table 183 for the description of this result code.

Bad_IndexRangeDataMismatch

The data to be written does not match the IndexRange.

Bad_WriteNotSupported

The requested write operation is not supported.

If a Client attempts to write any value, status code, timestamp combination and the Server does not support the requested combination (which could be a single quantity such as just timestamp); than the Server shall not perform any write on this Node and shall return this StatusCode for this Node. It is also used if writing of IndexRanges is not supported for a Node.

Bad_NotWritable

See Table 183 for the description of this result code.

Bad_UserAccessDenied

See Table 182 for the description of this result code.

The current user does not have permission to write the attribute.

Bad_OutOfRange

See Table 183 for the description of this result code.

If a Client attempts to write a value outside the valid range like a value not contained in the enumeration data type of the Node, the Server shall return this StatusCode for this Node.

This result code can be returned for any value that has the right DataType but does not comply with the restrictions defined by the Server implementation e.g. if a written String contains unsupported characters.

Bad_TypeMismatch

See Table 183 for the description of this result code.

Bad_DataEncodingUnsupported

See Table 183 for the description of this result code.

Bad_NoCommunication

See Table 183 for the description of this result code.

Bad_LocaleNotSupported

The locale in the requested write operation is not supported.

This Service is used to update historical values or Events of one or more Nodes. Several request parameters indicate how the Server is to update the historical value or Event. Valid actions are Insert, Replace or Delete.

Table 62 defines the parameters for the Service.

Table 62 – HistoryUpdate Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

historyUpdateDetails []

Extensible Parameter

HistoryUpdate

Details

The details defined for this update. The HistoryUpdateDetails parameter type is an extensible parameter type formally defined in OPC 10000-11. It specifies the types of history updates that can be performed. The ExtensibleParameter type is defined in 7.17.

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader definition).

results []

HistoryUpdate Result

List of update results for the history update details. The size and order of the list matches the size and order of the details element of the historyUpdateDetails parameter specified in the request. This structure is defined in-line with the following indented items.

statusCode

StatusCode

StatusCode for the update of the Node (see 7.39 for StatusCode definition).

operationResults []

StatusCode

List of StatusCodes for the operations to be performed on a Node. The size and order of the list matches the size and order of any list defined by the details element being reported by this result entry.

diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the operations to be performed on a Node (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of any list defined by the details element being reported by this results entry. 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 request.

diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the history update details. The size and order of the list matches the size and order of the details element of the historyUpdateDetails parameter specified in the request. 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 request.

Table 63 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 63 – HistoryUpdate Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Table 64 defines values for the statusCode and operationResults parameters that are specific to this Service. Common StatusCodes are defined in Table 183. History access specific StatusCodes are defined in OPC 10000-11.

Table 64 – HistoryUpdate Operation Level Result Codes

Symbolic Id

Description

Bad_NotWritable

See Table 183 for the description of this result code.

Bad_HistoryOperationInvalid

See Table 183 for the description of this result code.

Bad_HistoryOperationUnsupported

See Table 183 for the description of this result code.

Bad_UserAccessDenied

See Table 182 for the description of this result code.

The current user does not have permission to update the history.

Methods represent the function calls of Objects. They are defined in OPC 10000-3. Methods are invoked and return only after completion (successful or unsuccessful). Execution times for Methods may vary, depending on the function that they perform.

The Method Service Set defines the means to invoke Methods. A Method shall be a component of an Object. Discovery is provided through the Browse and Query Services. Clients discover the Methods supported by a Server by browsing for the owning Objects References that identify their supported Methods.

Because Methods may control some aspect of plant operations, Method invocation may depend on environmental or other conditions. This may be especially true when attempting to re-invoke a Method immediately after it has completed execution. Conditions that are required to invoke the Method might not yet have returned to the state that permits the Method to start again.

This Service is used to call (invoke) a list of Methods.

This Service provides for passing input and output arguments to/from a Method. These arguments are defined by Properties of the Method.

If the Method is invoked in the context of a Session and the Session is terminated, the results of the Method’s execution cannot be returned to the Client and are discarded. This is independent of the task actually performed at the Server.

The order the operations are processed in the Server is not defined and depends on the different tasks and the internal Server logic. If a Method is contained in more than one operation, the order of the processing is undefined. If a Client requires sequential processing the Client needs separate Service calls.

Table 65 defines the parameters for the Service.

Table 65 – Call Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

methodsToCall []

CallMethodRequest

List of Methods to call. This structure is defined in-line with the following indented items.

objectId

NodeId

The NodeId shall be that of the Object or ObjectType on which the Method is invoked.

In case of an ObjectType the ObjectType or a super type of the ObjectType shall be the source of a HasComponent Reference (or subtype of HasComponent Reference) to the Method specified in methodId.

In case of an Object the Object or the ObjectType of the Object or a super type of that ObjectType shall be the source of a HasComponent Reference (or subtype of HasComponent Reference) to the Method specified in methodId.

See OPC 10000-3 for a description of Objects and their Methods.

methodId

NodeId

NodeId of the Method to invoke.

If the objectId is the NodeId of an Object, it is allowed to use the NodeId of a Method that is the target of a HasComponent Reference from the ObjectType of the Object.

inputArguments []

BaseDataType

List of input argument values. An empty list indicates that there are no input arguments. The size and order of this list matches the size and order of the input arguments defined by the input InputArguments Property of the Method.

The name, a description and the data type of each argument are defined by the Argument structure in each element of the method’s InputArguments Property.

Fewer arguments than the total number of input arguments defined may be passed by the Client when optional input arguments are defined. A Method may define input arguments as optional by including HasOptionalInputArgumentDescription references to argument metadata. The InputArguments Property and the HasOptionalInputArgumentDescription ReferenceType are defined in OPC 10000-3.

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader definition).

results []

CallMethodResult

Result for the Method calls. This structure is defined in-line with the following indented items.

statusCode

StatusCode

StatusCode of the Method executed in the Server. This StatusCode is set to the Bad_InvalidArgument StatusCode if at least one input argument broke a constraint (e.g. wrong data type, value out of range).

This StatusCode is set to a bad StatusCode if the Method execution failed in the Server, e.g. based on an exception.

If the Method execution fails but the outputArguments provide additional information like an application specific error code, the Method should return a StatusCode with Severity Uncertain.

inputArgumentResults []

StatusCode

List of StatusCodes corresponding to the inputArguments.

This list is empty unless the operation level result is Bad_InvalidArgument.

If this list is populated, it has the same length as the inputArguments list.

inputArgumentDiagnosticInfos []

DiagnosticInfo

List of diagnostic information corresponding to the inputArguments. 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 request.

outputArguments []

BaseDataType

List of output argument values. An empty list indicates that there are no output arguments. The size and order of this list matches the size and order of the output arguments defined by the OutputArguments Property of the Method.

The name, a description and the data type of each argument are defined by the Argument structure in each element of the methods OutputArguments Property.

The list shall be empty if the statusCode Severity is Bad.

diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the statusCode of the results. 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 request.

Table 66 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 66 – Call Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Table 67 defines values for the statusCode parameter and Table 68 defines values for the inputArgumentResults parameter that are specific to this Service. Common StatusCodes are defined in Table 183.

Server vendors or OPC UA companion specifications may reuse existing StatusCodes for application specific error information. This is valid as long as the canonical description of the StatusCode does not have a different meaning than the application specific description. To eliminate any vagueness, the Server should include the application specific description in the DiagnosticInfo.

Good StatusCodes with sub-status shall not be used as statusCode since many programming language bindings would cause such codes to throw an exception.

Table 67 – Call Operation Level Result Codes

Symbolic Id

Description

Bad_NodeIdInvalid

See Table 183 for the description of this result code.

Used to indicate that the specified objectId is not an Object or ObjectType.

Bad_NodeIdUnknown

See Table 183 for the description of this result code.

Used to indicate that the specified objectId refers to a node that does not exist in the Server address space.

Bad_NotExecutable

The executable Attribute does not allow the execution of the Method.

Bad_ArgumentsMissing

The Client did not specify all of the non-optional input arguments for the Method.

Bad_TooManyArguments

The Client specified more input arguments than defined for the Method.

Bad_InvalidArgument

See Table 182 for the description of this result code.

Used to indicate in the operation level results that one or more of the input arguments are invalid. The inputArgumentResults contain the specific status code for each invalid argument.

Bad_UserAccessDenied

See Table 182 for the description of this result code.

Bad_SecurityModeInsufficient

See Table 183 for the description of this result code.

Bad_MethodInvalid

The method id does not refer to a Method for the specified Object.

Bad_NoCommunication

See Table 183 for the description of this result code.

Uncertain

The Method execution fails but the outputArguments provide additional information like an application specific error code.

Table 68 – Call Input Argument Result Codes

Symbolic Id

Description

Bad_OutOfRange

See Table 183 for the description of this result code.

Used to indicate that an input argument is outside the acceptable range.

Bad_TypeMismatch

See Table 183 for the description of this result code.

Used to indicate that an input argument does not have the correct data type.

A ByteString is structurally the same as a one dimensional array of Byte. A Server shall accept a ByteString if an array of Byte is expected.

Bad_DecodingError

See Table 182 for the description of this result code.

Used to indicate that an input argument with a Structure DataType cannot be decoded.

Clients define MonitoredItems to subscribe to data and Events. Each MonitoredItem identifies the item to be monitored and the Subscription to use to send Notifications. The item to be monitored may be any Node Attribute.

Notifications are data structures that describe the occurrence of data changes and Events. They are packaged into NotificationMessages for transfer to the Client. The Subscription periodically sends NotificationMessages at a user-specified publishing interval, and the cycle during which these messages are sent is called a publishing cycle.

Four primary parameters are defined for MonitoredItems that tell the Server how the item is to be sampled, evaluated and reported. These parameters are the sampling interval, the monitoring mode, the filter and the queue parameter. Figure 15 illustrates these concepts.

image018.png

Figure 15 – MonitoredItem model

Attributes, other than the Value Attribute, are only monitored for a change in value. The filter is not used for these Attributes. Any change in value for these Attributes causes a Notification to be generated.

The Value Attribute is used when monitoring Variables. Variable values are monitored for a change in value or a change in their status. The filters defined in this document (see 7.22.2) and in OPC 10000-8 are used to determine if the value change is large enough to cause a Notification to be generated for the Variable.

Objects and views can be used to monitor Events. Events are only available from Nodes where the SubscribeToEvents bit of the EventNotifier Attribute is set. The filter defined in this document (see 7.22.3) is used to determine if an Event received from the Node is sent to the Client. The filter also allows selecting fields of the EventType that will be contained in the Event such as EventId, EventType, SourceNode, Time and Description.

OPC 10000-3 describes the Event model and the base EventTypes.

The Properties of the base EventTypes and the representation of the base EventTypes in the AddressSpace are specified in OPC 10000-5.

Each MonitoredItem created by the Client is assigned a sampling interval that is either inherited from the publishing interval of the Subscription or that is defined specifically to override that rate. A negative number indicates that the default sampling interval defined by the publishing interval of the Subscription is requested. The sampling interval indicates the fastest rate at which the Server should sample its underlying source for data changes.

A Client shall define a sampling interval of 0 if it subscribes for Events.

The assigned sampling interval defines a “best effort” cyclic rate that the Server uses to sample the item from its source. “Best effort” in this context means that the Server does its best to sample at this rate. Sampling at rates faster than this rate is acceptable, but not necessary to meet the needs of the Client. How the Server deals with the sampling rate and how often it actually polls its data source internally is a Server implementation detail. However, the time between values returned to the Client shall be greater or equal to the sampling interval.

The Client may also specify 0 for the sampling interval, which indicates that the Server should use the fastest practical rate. It is expected that Servers will support only a limited set of sampling intervals to optimize their operation. If the exact interval requested by the Client is not supported by the Server, then the Server assigns to the MonitoredItem the most appropriate interval as determined by the Server. It returns this assigned interval to the Client. The ServerCapabilities Object defined in OPC 10000-5 identifies the minimum sampling interval supported by the Server. The optional MinimumSamplingInterval Attribute defined in OPC 10000-3 identifies the minimum sampling interval supported for a Variable. If a Server uses a fixed set of sampling intervals, the intervals can be exposed using the SamplingIntervalDiagnosticsArray in the ServerDiagnostics Object defined in OPC 10000-5.

The Server may support data that is collected based on a sampling model or generated based on an exception-based model. The fastest supported sampling interval may be equal to 0, which indicates that the data item is exception-based rather than being sampled at some period. An exception-based model means that the underlying system does not require sampling and reports data changes.

The Client may use the revised sampling interval values as a hint for setting the publishing interval as well as the keep-alive count of a Subscription. If, for example, the smallest revised sampling interval of the MonitoredItems is 5 seconds, then the time before a keep-alive is sent should be longer than 5 seconds.

Note that, in many cases, the OPC UA Server provides access to a decoupled system and therefore has no knowledge of the data update logic. In this case, even though the OPC UA Server samples at the negotiated rate, the data might be updated by the underlying system at a much slower rate. In this case, changes can only be detected at this slower rate.

If the behaviour by which the underlying system updates the item is known, it will be available via the MinimumSamplingInterval Attribute defined in OPC 10000-3. If the Server specifies a value for the MinimumSamplingInterval Attribute it shall always return a revisedSamplingInterval that is equal or higher than the MinimumSamplingInterval if the Client subscribes to the Value Attribute.

Clients should also be aware that the sampling by the OPC UA Server and the update cycle of the underlying system are usually not synchronized. This can cause additional delays in change detection, as illustrated in Figure 16.

image019.png

Figure 16 – Typical delay in change detection

The monitoring mode parameter is used to enable and disable the sampling of a MonitoredItem, and also to provide for independently enabling and disabling the reporting of Notifications. This capability allows a MonitoredItem to be configured to sample, sample and report, or neither. Disabling sampling does not change the values of any of the other MonitoredItem parameter, such as its sampling interval.

When a MonitoredItem is enabled (i.e. when the MonitoringMode is changed from DISABLED to SAMPLING or REPORTING) or it is created in the enabled state, the Server shall report the first sample as soon as possible and the time of this sample becomes the starting point for the next sampling interval.

Each time a MonitoredItem is sampled, the Server evaluates the sample using the filter defined for the MonitoredItem. The filter parameter defines the criteria that the Server uses to determine if a Notification should be generated for the sample. The type of filter is dependent on the type of the item that is being monitored. For example, the DataChangeFilter and the AggregateFilter are used when monitoring Variable Values and the EventFilter is used when monitoring Events. Sampling and evaluation, including the use of filters, are described in this document. Additional filters may be defined in other parts of OPC 10000.

If the sample passes the filter criteria, a Notification is generated and queued for transfer by the Subscription. The size of the queue is defined when the MonitoredItem is created. When the queue is full and a new Notification is received, the Server either discards the oldest Notification and queues the new one, or it replaces the last value added to the queue with the new one. The MonitoredItem is configured for one of these discard policies when the MonitoredItem is created. If a Notification is discarded for a DataValue and the size of the queue is larger than one, then the Overflow bit (flag) in the InfoBits portion of the DataValue statusCode is set. If discardOldest is TRUE, the oldest value gets deleted from the queue and the next value in the queue gets the flag set. If discardOldest is FALSE, the last value added to the queue gets replaced with the new value. The new value gets the flag set to indicate the lost values in the next NotificationMessage. Figure 17 illustrates the queue overflow handling.

image020.png

Figure 17 – Queue overflow handling

If the queue size is one, the queue becomes a buffer that always contains the newest Notification. In this case, if the sampling interval of the MonitoredItem is faster than the publishing interval of the Subscription, the MonitoredItem will be over sampling and the Client will always receive the most up-to-date value. The discard policy is ignored if the queue size is one.

On the other hand, the Client may want to subscribe to a continuous stream of Notifications without any gaps, but does not want them reported at the sampling interval. In this case, the MonitoredItem would be created with a queue size large enough to hold all Notifications generated between two consecutive publishing cycles. Then, at each publishing cycle, the Subscription would send all Notifications queued for the MonitoredItem to the Client. The Server shall return Notifications for any particular item in the same order they are in the queue.

The Server may be sampling at a faster rate than the sampling interval to support other Clients; the Client should only expect values at the negotiated sampling interval. The Server may deliver fewer values than dictated by the sampling interval, based on the filter and implementation constraints. If a DataChangeFilter is configured for a MonitoredItem, it is always applied to the newest value in the queue compared to the current sample.

If, for example, the AbsoluteDeadband in the DataChangeFilter is “10”, the queue could consist of values in the following order:

  • 100
  • 111
  • 100
  • 89
  • 100

Queuing of data may result in unexpected behaviour when using a Deadband filter and the number of encountered changes is larger than the number of values that can be maintained. The new first value in the queue may not exceed the Deadband limit of the previous value sent to the Client.

The queue size is the maximum value supported by the Server when monitoring Events. In this case, the Server is responsible for the Event buffer. If Events are lost, an Event of the type EventQueueOverflowEventType is placed in the queue. This Event is generated when the first Event is discarded on a MonitoredItem subscribing for Events. It is put into the Queue of the MonitoredItem in addition to the size of the Queue defined for this MonitoredItem without discarding any other Event. If discardOldest is set to TRUE it is put at the beginning of the queue and is never discarded, otherwise at the end. An aggregating Server shall not pass on such an Event. It shall be handled like other connection error scenarios using the SystemStatusChangeEventType with the ServerState COMMUNICATION_FAULT.

For any fatal error during event processing like out of memory situations, the Server should queue an SystemStatusChangeEventType event with the ServerState COMMUNICATION_FAULT and the source set to the Server Object. If there are no resources available at the time the error happens, the Server should flag an error internally until there are resources to further process Events for the MonitoredItem.

The MonitoredItems Service allows the addition of items that are reported only when some other item (the triggering item) triggers. This is done by creating links between the triggered items and the items to report. The monitoring mode of the items to report is set to sampling-only so that it will sample and queue Notifications without reporting them. Figure 18 illustrates this concept.

image021.png

Figure 18 – Triggering model

The triggering mechanism is a useful feature that allows Clients to reduce the data volume on the wire by configuring some items to sample frequently but only report when some other Event happens.

The following triggering behaviours are specified.

  1. If the monitoring mode of the triggering item is SAMPLING, then it is not reported when the triggering item triggers the items to report.
  2. If the monitoring mode of the triggering item is REPORTING, then it is reported when the triggering item triggers the items to report.
  3. If the monitoring mode of the triggering item is DISABLED, then the triggering item does not trigger the items to report.
  4. If the monitoring mode of the item to report is SAMPLING, then it is reported when the triggering item triggers the items to report.
  5. If the monitoring mode of the item to report is REPORTING, this effectively causes the triggering item to be ignored. All notifications of the items to report are sent after the publishing interval expires.
  6. If the monitoring mode of the item to report is DISABLED, then there will be no sampling of the item to report and therefore no notifications to report.
  7. The first trigger shall occur when the first notification is queued for the triggering item after the creation of the link.

Clients create and delete triggering links between a triggering item and a set of items to report. If the MonitoredItem that represents an item to report is deleted before its associated triggering link is deleted, the triggering link is also deleted, but the triggering item is otherwise unaffected.

Deletion of a MonitoredItem should not be confused with the removal of the Attribute that it monitors. If the Node that contains the Attribute being monitored is deleted, the MonitoredItem generates a Notification with a StatusCode Bad_NodeIdUnknown that indicates the deletion, but the MonitoredItem is not deleted.

This Service is used to create and add one or more MonitoredItems to a Subscription. A MonitoredItem is deleted automatically by the Server when the Subscription is deleted. Deleting a MonitoredItem causes its entire set of triggered item links to be deleted, but has no effect on the MonitoredItems referenced by the triggered items.

Calling the CreateMonitoredItems Service repetitively to add a small number of MonitoredItems each time may adversely affect the performance of the Server. Instead, Clients should add a complete set of MonitoredItems to a Subscription whenever possible.

When a MonitoredItem is added, the Server performs initialization processing for it. The initialization processing is defined by the Notification type of the item being monitored. Notification types are specified in this document and in the Access Type Specification parts of OPC 10000, such as OPC 10000-8. See OPC 10000-1 for a description of the Access Type Parts. Clients may receive Notifications for added MonitoredItems before the CreateMonitoredItems Response is received. Clients set the ClientHandle for the MonitoredItem in the CreateMonitoredItems Request and are therefore able to process the Notifications received before the CreateMonitoredItems Response is received.

When a user adds a monitored item that the user is denied read access to, the add operation for the item shall succeed and the bad status Bad_NotReadable or Bad_UserAccessDenied shall be returned in the Publish response. This is the same behaviour for the case where the access rights are changed after the call to CreateMonitoredItems. If the access rights change to read rights, the Server shall start sending data for the MonitoredItem. The same procedure shall be applied for an IndexRange that does not deliver data for the current value but could deliver data in the future. Servers should return all other errors as CreateMonitoredItems results but all possible errors are allowed to be returned in the Publish response.

Monitored Nodes can be removed from the AddressSpace after the creation of a MonitoredItem. This does not affect the validity of the MonitoredItem but a Bad_NodeIdUnknown shall be returned in the Publish response. It is possible that the MonitoredItem becomes valid again if the Node is added again to the AddressSpace and the MonitoredItem still exists.

If a NodeId is known to be valid by a Server but the corresponding Node Attributes are currently not available, the Server may allow the creation of a MonitoredItem and return an appropriate Bad StatusCode in the Publish response.

The return diagnostic info setting in the request header of the CreateMonitoredItems or the last ModifyMonitoredItems Service is applied to the Monitored Items and is used as the diagnostic information settings when sending Notifications in the Publish response.

Illegal request values for parameters that can be revised do not generate errors. Instead the Server will choose default values and indicate them in the corresponding revised parameter.

It is strongly recommended by OPC UA that a Client reuses a Subscription after a short network interruption by activating the existing Session on a new SecureChannel as described in 6.7. If a Client called CreateMonitoredItems during the network interruption and the call succeeded in the Server but did not return to the Client, then the Client does not know if the call succeeded. The Client may receive data changes for these monitored items but is not able to remove them since it does not know the Server handle for each monitored item. There is also no way for the Client to detect if the create succeeded. To delete and recreate the Subscription is also not an option since there may be several monitored items operating normally that should not be interrupted. To resolve this situation, the Server Object provides a Method GetMonitoredItems that returns the list of Server and client handles for the monitored items in a Subscription. This Method is defined in OPC 10000-5. The Server shall verify that the Method is called within the Session context of the Session that owns the Subscription.

Table 69 defines the parameters for the Service.

Table 69 – CreateMonitoredItems Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

subscriptionId

IntegerId

The Server-assigned identifier for the Subscription that will report Notifications for this MonitoredItem (see 7.19 for IntegerId definition).

timestampsToReturn

Enum

Timestamps ToReturn

An enumeration that specifies the timestamp Attributes to be transmitted for each MonitoredItem. The TimestampsToReturn enumeration is defined in 7.40.

When monitoring Events, this applies only to Event fields that are of type DataValue.

itemsToCreate []

MonitoredItem CreateRequest

A list of MonitoredItems to be created and assigned to the specified Subscription. This structure is defined in-line with the following indented items.

itemToMonitor

ReadValueId

Identifies an item in the AddressSpace to monitor. To monitor for Events, the attributeId element of the ReadValueId structure is the id of the EventNotifier Attribute. The ReadValueId type is defined in 7.29.

monitoringMode

Enum

MonitoringMode

The monitoring mode to be set for the MonitoredItem. The MonitoringMode enumeration is defined in 7.23.

requestedParameters

Monitoring Parameters

The requested monitoring parameters. Servers negotiate the values of these parameters based on the Subscription and the capabilities of the Server. The MonitoringParameters type is defined in 7.21.

Response

responseHeader

Response Header

Common response parameters (see 7.34 for ResponseHeader definition).

results []

MonitoredItem CreateResult

List of results for the MonitoredItems to create. The size and order of the list matches the size and order of the itemsToCreate request parameter. This structure is defined in-line with the following indented items.

statusCode

StatusCode

StatusCode for the MonitoredItem to create (see 7.39 for StatusCode definition).

monitoredItemId

IntegerId

Server-assigned id for the MonitoredItem (see 7.19 for IntegerId definition). This id is unique within the Subscription, but might not be unique within the Server or Session. This parameter is present only if the statusCode indicates that the MonitoredItem was successfully created.

revisedSampling Interval

Duration

The actual sampling interval that the Server will use.

This value is based on a number of factors, including capabilities of the underlying system. The Server shall always return a revisedSamplingInterval that is equal or higher than the requested samplingInterval. If the requested samplingInterval is higher than the maximum sampling interval supported by the Server, the maximum sampling interval is returned.

revisedQueueSize

Counter

The actual queue size that the Server will use.

filterResult

Extensible Parameter

MonitoringFilterResult

Contains any revised parameter values or error results associated with the MonitoringFilter specified in requestedParameters. This parameter may be null if no errors occurred. The MonitoringFilterResult parameter type is an extensible parameter type specified in 7.22.

diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the MonitoredItems to create (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the itemsToCreate 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 request.

Table 70 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 70 – CreateMonitoredItems Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Bad_TimestampsToReturnInvalid

See Table 182 for the description of this result code.

Bad_SubscriptionIdInvalid

See Table 182 for the description of this result code.

Table 71 defines values for the operation level statusCode parameter that are specific to this Service. Common StatusCodes are defined in Table 183.

Table 71 – CreateMonitoredItems Operation Level Result Codes

Symbolic Id

Description

Bad_MonitoringModeInvalid

See Table 183 for the description of this result code.

Bad_NodeIdInvalid

See Table 183 for the description of this result code.

Bad_NodeIdUnknown

See Table 183 for the description of this result code.

Bad_AttributeIdInvalid

See Table 183 for the description of this result code.

Bad_IndexRangeInvalid

See Table 183 for the description of this result code.

Bad_IndexRangeNoData

See Table 183 for the description of this result code.

If the ArrayDimensions have a fixed length that cannot change and no data exists within the range of indexes specified, Bad_IndexRangeNoData is returned in CreateMonitoredItems. Otherwise if the length of the array is dynamic, the Server shall return this status in a Publish response for the MonitoredItem if no data exists within the range.

Bad_DataEncodingInvalid

See Table 183 for the description of this result code.

Bad_DataEncodingUnsupported

See Table 183 for the description of this result code.

Bad_MonitoredItemFilterInvalid

See Table 183 for the description of this result code.

Bad_MonitoredItemFilterUnsupported

See Table 183 for the description of this result code.

Bad_FilterNotAllowed

See Table 183 for the description of this result code.

Bad_TooManyMonitoredItems

The Server has reached its maximum number of monitored items.

This Service is used to modify MonitoredItems of a Subscription. Changes to the MonitoredItem settings shall be applied immediately by the Server. They take effect as soon as practical but not later than twice the new revisedSamplingInterval.

The return diagnostic info setting in the request header of the CreateMonitoredItems or the last ModifyMonitoredItems Service is applied to the Monitored Items and is used as the diagnostic information settings when sending Notifications in the Publish response.

Illegal request values for parameters that can be revised do not generate errors. Instead the Server will choose default values and indicate them in the corresponding revised parameter.

Table 72 defines the parameters for the Service.

Table 72 – ModifyMonitoredItems Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

subscriptionId

IntegerId

The Server-assigned identifier for the Subscription used to qualify the monitoredItemId (see 7.19 for IntegerId definition).

timestampsToReturn

Enum

Timestamps ToReturn

An enumeration that specifies the timestamp Attributes to be transmitted for each MonitoredItem to be modified. The TimestampsToReturn enumeration is defined in 7.40. When monitoring Events, this applies only to Event fields that are of type DataValue.

itemsToModify []

MonitoredItemModifyRequest

The list of MonitoredItems to modify. This structure is defined in-line with the following indented items.

monitoredItemId

IntegerId

Server-assigned id for the MonitoredItem.

requestedParameters

Monitoring Parameters

The requested values for the monitoring parameters. The MonitoringParameters type is defined in 7.21.

If the number of notifications in the queue exceeds the new queue size, the notifications exceeding the size shall be discarded following the configured discard policy.

Response

responseHeader

Response Header

Common response parameters (see 7.34 for ResponseHeader definition).

results []

MonitoredItemModifyResult

List of results for the MonitoredItems to modify. The size and order of the list matches the size and order of the itemsToModify request parameter. This structure is defined in-line with the following indented items.

statusCode

StatusCode

StatusCode for the MonitoredItem to be modified (see 7.39 for StatusCode definition).

revisedSampling

Interval

Duration

The actual sampling interval that the Server will use. The Server returns the value it will actually use for the sampling interval. This value is based on a number of factors, including capabilities of the underlying system.

The Server shall always return a revisedSamplingInterval that is equal or higher than the requested samplingInterval. If the requested samplingInterval is higher than the maximum sampling interval supported by the Server, the maximum sampling interval is returned.

revisedQueueSize

Counter

The actual queue size that the Server will use.

filterResult

Extensible Parameter

MonitoringFilter Result

Contains any revised parameter values or error results associated with the MonitoringFilter specified in the request. This parameter may be null if no errors occurred. The MonitoringFilterResult parameter type is an extensible parameter type specified in 7.22.

diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the MonitoredItems to modify (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the itemsToModify 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 request.

Table 73 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 73 – ModifyMonitoredItems Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Bad_TimestampsToReturnInvalid

See Table 182 for the description of this result code.

Bad_SubscriptionIdInvalid

See Table 182 for the description of this result code.

Table 74 defines values for the operation level statusCode parameter that are specific to this Service. Common StatusCodes are defined in Table 183.

Table 74 – ModifyMonitoredItems Operation Level Result Codes

Symbolic Id

Description

Bad_MonitoredItemIdInvalid

See Table 183 for the description of this result code.

Bad_MonitoredItemFilterInvalid

See Table 183 for the description of this result code.

Bad_MonitoredItemFilterUnsupported

See Table 183 for the description of this result code.

Bad_FilterNotAllowed

See Table 182 for the description of this result code.

This Service is used to set the monitoring mode for one or more MonitoredItems of a Subscription. Setting the mode to DISABLED causes all queued Notifications to be deleted.

Table 75 defines the parameters for the Service.

Table 75 – SetMonitoringMode Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

subscriptionId

IntegerId

The Server-assigned identifier for the Subscription used to qualify the monitoredItemIds (see 7.19 for IntegerId definition).

monitoringMode

Enum

MonitoringMode

The monitoring mode to be set for the MonitoredItems. The MonitoringMode enumeration is defined in 7.23.

monitoredItemIds []

IntegerId

List of Server-assigned ids for the MonitoredItems.

Response

responseHeader

Response Header

Common response parameters (see 7.34 for ResponseHeader definition).

results []

StatusCode

List of StatusCodes for the MonitoredItems to enable/disable (see 7.39 for StatusCode definition). The size and order of the list matches the size and order of the monitoredItemIds request parameter.

diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the MonitoredItems to enable/disable (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the monitoredItemIds 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 request.

Table 76 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 76 – SetMonitoringMode Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Bad_SubscriptionIdInvalid

See Table 182 for the description of this result code.

Bad_MonitoringModeInvalid

See Table 183 for the description of this result code.

Table 77 defines values for the operation level results parameter that are specific to this Service. Common StatusCodes are defined in Table 183.

Table 77 – SetMonitoringMode Operation Level Result Codes

Symbolic Id

Description

Bad_MonitoredItemIdInvalid

See Table 183 for the description of this result code.

This Service is used to create and delete triggering links for a triggering item. The triggering item and the items to report shall belong to the same Subscription.

Each triggering link links a triggering item to an item to report. Each link is represented by the MonitoredItem id for the item to report. An error code is returned if this id is invalid.

See 5.12.1.6 for a description of the triggering model.

Table 78 defines the parameters for the Service.

Table 78 – SetTriggering Service Parameters

Name

Type

Description

Request

requestHeader

Request Header

Common request parameters (see 7.33 for RequestHeader definition).

subscriptionId

IntegerId

The Server-assigned identifier for the Subscription that contains the triggering item and the items to report (see 7.19 for IntegerId definition).

triggeringItemId

IntegerId

Server-assigned id for the MonitoredItem used as the triggering item.

linksToAdd []

IntegerId

The list of Server-assigned ids of the items to report that are to be added as triggering links. The list of linksToRemove is processed before the linksToAdd.

linksToRemove []

IntegerId

The list of Server-assigned ids of the items to report for the triggering links to be deleted. The list of linksToRemove is processed before the linksToAdd.

Response

responseHeader

Response Header

Common response parameters (see 7.34 for ResponseHeader definition).

addResults []

StatusCode

List of StatusCodes for the items to add (see 7.39 for StatusCode definition). The size and order of the list matches the size and order of the linksToAdd parameter specified in the request.

addDiagnosticInfos []

Diagnostic Info

List of diagnostic information for the links to add (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the linksToAdd 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 request.

removeResults []

StatusCode

List of StatusCodes for the items to delete. The size and order of the list matches the size and order of the linksToRemove parameter specified in the request.

removeDiagnosticInfos []

Diagnostic Info

List of diagnostic information for the links to delete. The size and order of the list matches the size and order of the linksToRemove 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 request.

Table 79 defines the Service results specific to this Service. Common StatusCodes are defined in 7.39.

Table 79 – SetTriggering Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Bad_SubscriptionIdInvalid

See Table 182 for the description of this result code.

Bad_MonitoredItemIdInvalid

See Table 183 for the description of this result code.

Table 80 defines values for the results parameters that are specific to this Service. Common StatusCodes are defined in Table 183.

Table 80 – SetTriggering Operation Level Result Codes

Symbolic Id

Description

Bad_MonitoredItemIdInvalid

See Table 183 for the description of this result code.

This Service is used to remove one or more MonitoredItems of a Subscription. When a MonitoredItem is deleted, its triggered item links are also deleted.

Successful removal of a MonitoredItem, however, might not remove Notifications for the MonitoredItem that are in the process of being sent by the Subscription. Therefore, Clients may receive Notifications for the MonitoredItem after they have received a positive response that the MonitoredItem has been deleted.

Table 81 defines the parameters for the Service.

Table 81 – DeleteMonitoredItems Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

subscriptionId

IntegerId

The Server-assigned identifier for the Subscription that contains the MonitoredItems to be deleted (see 7.19 for IntegerId definition).

monitoredItemIds []

IntegerId

List of Server-assigned ids for the MonitoredItems to be deleted.

Response

responseHeader

Response Header

Common response parameters (see 7.34 for ResponseHeader definition).

results []

StatusCode

List of StatusCodes for the MonitoredItems to delete (see 7.39 for StatusCode definition). The size and order of the list matches the size and order of the monitoredItemIds request parameter.

diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the MonitoredItems to delete (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the monitoredItemIds 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 request.

Table 82 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 82 – DeleteMonitoredItems Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Bad_SubscriptionIdInvalid

See Table 182 for the description of this result code.

Table 83 defines values for the results parameter that are specific to this Service. Common StatusCodes are defined in Table 183.

Table 83 – DeleteMonitoredItems Operation Level Result Codes

Symbolic Id

Description

Bad_MonitoredItemIdInvalid

See Table 183 for the description of this result code.

Subscriptions are used to report Notifications to the Client. Their general behaviour is summarized below. Their precise behaviour is described in 5.13.1.2.

  1. Subscriptions have a set of MonitoredItems assigned to them by the Client. MonitoredItems generate Notifications that are to be reported to the Client by the Subscription (see 5.12.1 for a description of MonitoredItems).
  2. Subscriptions have a publishing interval. The publishing interval of a Subscription defines the cyclic rate at which the Subscription executes. Each time it executes, it attempts to send a NotificationMessage to the Client. NotificationMessages contain Notifications that have not yet been reported to Client.
  3. NotificationMessages are sent to the Client in response to Publish requests. Publish requests are normally queued to the Session as they are received, and one is de-queued and processed by a Subscription related to this Session for each publishing cycle, if there are Notifications to report. When there are not, the Publish request is not de-queued from the Session, and the Server waits until the next cycle and checks again for Notifications.
  4. At the beginning of a cycle, if there are Notifications to send but there are no Publish requests queued, the Server enters a wait state for a Publish request to be received. When one is received, it is processed immediately without waiting for the next publishing cycle.
  5. NotificationMessages are uniquely identified by sequence numbers that enable Clients to detect missed Messages. The publishing interval also defines the default sampling interval for its MonitoredItems.
  6. Subscriptions have a keep-alive counter that counts the number of consecutive publishing cycles in which there have been no Notifications to report to the Client. When the maximum keep-alive count is reached, a Publish request is de-queued and used to return a keep-alive Message. This keep-alive Message informs the Client that the Subscription is still active. Each keep-alive Message is a response to a Publish request in which the notificationMessage parameter does not contain any Notifications and that contains the sequence number of the next NotificationMessage that is to be sent. In the clauses that follow, the term NotificationMessage refers to a response to a Publish request in which the notificationMessage parameter actually contains one or more Notifications, as opposed to a keep-alive Message in which this parameter contains no Notifications. The maximum keep-alive count is set by the Client during Subscription creation and may be subsequently modified using the ModifySubscription Service. Similar to Notification processing described in (c) above, if there are no Publish requests queued, the Server waits for the next one to be received and sends the keep-alive immediately without waiting for the next publishing cycle.
  7. Publishing by a Subscription may be enabled or disabled by the Client when created, or subsequently using the SetPublishingMode Service. Disabling causes the Subscription to cease sending NotificationMessages to the Client. However, the Subscription continues to execute cyclically and continues to send keep-alive Messages to the Client.
  8. Subscriptions have a lifetime counter that counts the number of consecutive publishing cycles in which there have been no Publish requests available to send a Publish response for the Subscription. Any Service call that uses the SubscriptionId or the processing of a Publish response resets the lifetime counter of this Subscription. When this counter reaches the value calculated for the lifetime of a Subscription, the Subscription is closed. Closing the Subscription causes its MonitoredItems to be deleted. In addition the Server shall issue a StatusChangeNotification notificationMessage with the status code Bad_Timeout. The StatusChangeNotification notificationMessage type is defined in 7.25.4.
  9. Sessions maintain a retransmission queue of sent NotificationMessages. NotificationMessages are retained in this queue until they are acknowledged. The Session maintains a retransmission queue size of at least two times the number of Publish requests per Session the Server supports. A Profile in OPC 10000-7 may make the retransmission queue support optional. The minimum number of Publish requests per Session the Server shall support is defined in OPC 10000-7. Clients are required to acknowledge NotificationMessages as they are received if the Publish response parameter availableSequenceNumbers is not an empty array. An empty array in availableSequenceNumbers indicates that the Server does not support a retransmission queue and acknowledgement of NotificationMessages. In the case of a retransmission queue overflow, the oldest sent NotificationMessage gets deleted. If a Subscription is transferred to another Session, the queued NotificationMessages for this Subscription are moved from the old to the new Session.

The sequence number is an unsigned 32-bit integer that is incremented by one for each NotificationMessage sent. The value 0 is never used for the sequence number. The first NotificationMessage sent on a Subscription has a sequence number of 1. If the sequence number rolls over, it rolls over to 1.

When a Subscription is created, the first Message is sent at the end of the first publishing cycle to inform the Client that the Subscription is operational. A NotificationMessage is sent if there are Notifications ready to be reported. If there are none, a keep-alive Message is sent instead that contains a sequence number of 1, indicating that the first NotificationMessage has not yet been sent. This is the only time a keep-alive Message is sent without waiting for the maximum keep-alive count to be reached, as specified in (f) above.

A Client shall be prepared for receiving Publish responses for a Subscription more frequently than the corresponding publishing interval. One example is the situation where the number of available notifications exceeds the Subscription setting maxNotificationsPerPublish. A Client is always able to control the timing of the Publish responses by not queueing Publish requests. If a Client does not queue Publish requests in the Server, the Server can only send a Publish response if it receives a new Publish request. This would increase latency for delivery of notifications but allows a Client to throttle the number of received Publish responses in high load situations.

The value of the sequence number is never reset during the lifetime of a Subscription. Therefore, the same sequence number shall not be reused on a Subscription until over four billion NotificationMessages have been sent. At a continuous rate of one thousand NotificationMessages per second on a given Subscription, it would take roughly fifty days for the same sequence number to be reused. This allows Clients to safely treat sequence numbers as unique.

Sequence numbers are also used by Clients to acknowledge the receipt of NotificationMessages. Publish requests allow the Client to acknowledge all Notifications up to a specific sequence number and to acknowledge the sequence number of the last NotificationMessage received. One or more gaps may exist in between. Acknowledgements allow the Server to delete NotificationMessages from its retransmission queue. If the retransmission queue contains outdated sequence numbers related to the sequence number acknowledged by the Client, the Server may delete these older NotificationMessage from the retransmission queue. The outdated sequence numbers are calculated with the following formular.

outdated < acknowledged sequence number – (2 x max retransmission queue size)

Clients may ask for retransmission of selected NotificationMessages using the Republish Service. This Service returns the requested Message.

Subscriptions are designed to work independent of the actual communication connection between OPC UA Client and Server and independent of a Session. Short communication interruptions can be handled without losing data or events. To make sure that longer communication interruptions or planned disconnects can be handled without losing data or events, an OPC UA Server may support durable Subscriptions. If this feature is supported, the Server accepts a high Subscription RequestedLifetimeCount and large MonitoredItem QueueSize parameter settings. Subclause 6.8 describes how durable Subscriptions can be created and used.

The state table formally describes the operation of the Subscription. The following model of operations is described by this state table. This description applies when publishing is enabled or disabled for the Subscription.

After creation of the Subscription, the Server starts the publishing timer and restarts it whenever it expires. If the timer expires the number of times defined for the Subscription lifetime without having received a Subscription Service request from the Client, the Subscription assumes that the Client is no longer present, and terminates.

Clients send Publish requests to Servers to receive Notifications. Publish requests are not directed to any one Subscription and, therefore, may be used by any Subscription. Each contains acknowledgements for one or more Subscriptions. These acknowledgements are processed when the Publish request is received. The Server then queues the request in a queue shared by all Subscriptions, except in the following cases.

  1. The previous Publish response indicated that there were still more Notifications ready to be transferred and there were no more Publish requests queued to transfer them.
  2. The publishing timer of a Subscription expired and there were either Notifications to be sent or a keep-alive Message to be sent.

In these cases, the newly received Publish request is processed immediately by the first Subscription to encounter either case (a) or case (b).

Each time the publishing timer expires, it is immediately reset. If there are Notifications or a keep-alive Message to be sent, it de-queues and processes a Publish request. When a Subscription processes a Publish request, it accesses the queues of its MonitoredItems and de-queues its Notifications, if any. It returns these Notifications in the response, setting the moreNotifications flag if it was not able to return all available Notifications in the response.

If there were Notifications or a keep-alive Message to be sent but there were no Publish requests queued, the Subscription assumes that the Publish request is late and waits for the next Publish request to be received, as described in case (b).

If the Subscription is disabled when the publishing timer expires or if there are no Notifications available, it enters the keep-alive state and sets the keep-alive counter to its maximum value as defined for the Subscription.

While in the keep-alive state, it checks for Notifications each time the publishing timer expires. If one or more Notifications have been generated, a Publish request is de-queued and a NotificationMessage is returned in the response. However, if the publishing timer expires without a Notification becoming available, a Publish request is de-queued and a keep-alive Message is returned in the response. The Subscription then returns to the normal state of waiting for the publishing timer to expire again. If, in either of these cases, there are no Publish requests queued, the Subscription waits for the next Publish request to be received, as described in case (b).

The Subscription states are defined in Table 84.

Table 84 – Subscription States

State

Description

CLOSED

The Subscription has not yet been created or has terminated.

CREATING

The Subscription is being created.

NORMAL

The Subscription is cyclically checking for Notifications from its MonitoredItems. The keep-alive counter is not used in this state.

LATE

The publishing timer has expired and there are Notifications available or a keep-alive Message is ready to be sent, but there are no Publish requests queued. When in this state, the next Publish request is processed when it is received. The keep-alive counter is not used in this state.

KEEPALIVE

The Subscription is cyclically checking for Notifications from its MonitoredItems or for the keep-alive counter to count down to 0 from its maximum.

The state table is described in Table 85. The following rules and conventions apply.

  1. Events represent the receipt of Service requests and the occurrence internal Events, such as timer expirations.
  2. Service requests Events may be accompanied by conditions that test Service parameter values. Parameter names begin with a lower case letter.
  3. Internal Events may be accompanied by conditions that test state Variable values. State Variables are defined in 5.13.1.3. They begin with an upper case letter.
  4. Service request and internal Events may be accompanied by conditions represented by functions whose return value is tested. Functions are identified by “()” after their name. They are described in 5.13.1.4.
  5. When an Event is received, the first transition for the current state is located and the transitions are searched sequentially for the first transition that meets the Event or conditions criteria. If none are found, the Event is ignored.
  6. Actions are described by functions and state Variable manipulations.
  7. The LifetimeTimerExpires Event is triggered when its corresponding counter reaches zero.

Table 85 – Subscription State Table

#

Current State

Event/Conditions

Action

Next State

1

CLOSED

Receive CreateSubscription Request

CreateSubscription()

CREATING

2

CREATING

CreateSubscription fails

ReturnNegativeResponse()

CLOSED

3

CREATING

CreateSubscription succeeds

InitializeSubscription()

MessageSent = FALSE

ReturnResponse()

NORMAL

4

NORMAL

Receive Publish Request

&&

(

PublishingEnabled == FALSE

||

(PublishingEnabled == TRUE

&& MoreNotifications == FALSE)

)

DeleteAckedNotificationMsgs()

EnqueuePublishingReq()

NORMAL

5

NORMAL

Receive Publish Request

&& PublishingEnabled == TRUE

&& MoreNotifications == TRUE

ResetLifetimeCounter()

DeleteAckedNotificationMsgs()

ReturnNotifications()

MessageSent = TRUE

NORMAL

6

NORMAL

PublishingTimer Expires

&& PublishingReqQueued == TRUE

&& PublishingEnabled == TRUE

&& NotificationsAvailable == TRUE

ResetLifetimeCounter()

StartPublishingTimer()

DequeuePublishReq()

ReturnNotifications()

MessageSent = TRUE

NORMAL

7

NORMAL

PublishingTimer Expires

&& PublishingReqQueued == TRUE

&& MessageSent == FALSE

&&

(

PublishingEnabled == FALSE

||

(PublishingEnabled == TRUE

&& NotificationsAvailable == FALSE)

)

ResetLifetimeCounter()

StartPublishingTimer()

DequeuePublishReq()

ReturnKeepAlive()

MessageSent = TRUE

NORMAL

8

NORMAL

PublishingTimer Expires

&& PublishingReqQueued == FALSE

&&

(

MessageSent == FALSE

||

(PublishingEnabled == TRUE

&& NotificationsAvailable == TRUE)

)

StartPublishingTimer()

LATE

9

NORMAL

PublishingTimer Expires

&& MessageSent == TRUE

&&

(

PublishingEnabled == FALSE

||

(PublishingEnabled == TRUE

&& NotificationsAvailable == FALSE)

)

StartPublishingTimer()

ResetKeepAliveCounter()

KeepAliveCounter--

KEEPALIVE

10

LATE

Receive Publish Request

&& PublishingEnabled == TRUE

&& (NotificationsAvailable == TRUE

|| MoreNotifications == TRUE)

ResetLifetimeCounter()

DeleteAckedNotificationMsgs()

ReturnNotifications()

MessageSent = TRUE

NORMAL

11

LATE

Receive Publish Request

&&

(

PublishingEnabled == FALSE

||

(PublishingEnabled == TRUE

&& NotificationsAvailable == FALSE

&& MoreNotifications == FALSE)

)

ResetLifetimeCounter()

DeleteAckedNotificationMsgs()

ReturnKeepAlive()

MessageSent = TRUE

KEEPALIVE

12

LATE

PublishingTimer Expires

StartPublishingTimer()

LATE

13

KEEPALIVE

Receive Publish Request

DeleteAckedNotificationMsgs()

EnqueuePublishingReq()

KEEPALIVE

14

KEEPALIVE

PublishingTimer Expires

&& PublishingEnabled == TRUE

&& NotificationsAvailable == TRUE

&& PublishingReqQueued == TRUE

ResetLifetimeCounter()

StartPublishingTimer()

DequeuePublishReq()

ReturnNotifications()

MessageSent = TRUE

NORMAL

15

KEEPALIVE

PublishingTimer Expires

&& PublishingReqQueued == TRUE

&& KeepAliveCounter <= 1

&&

(

PublishingEnabled == FALSE

||

(PublishingEnabled == TRUE

&& NotificationsAvailable == FALSE

)

StartPublishingTimer()

DequeuePublishReq()

ReturnKeepAlive()

ResetKeepAliveCounter()

KEEPALIVE

16

KEEPALIVE

PublishingTimer Expires

&& KeepAliveCounter > 1

&&

(

PublishingEnabled == FALSE

||

(PublishingEnabled == TRUE

&& NotificationsAvailable == FALSE)

)

StartPublishingTimer()

KeepAliveCounter--

KEEPALIVE

17

KEEPALIVE

PublishingTimer Expires

&& PublishingReqQueued == FALSE

&&

(

KeepAliveCounter == 1

||

(KeepAliveCounter > 1

&& PublishingEnabled == TRUE

&& NotificationsAvailable == TRUE)

)

StartPublishingTimer()

LATE

18

NORMAL

|| LATE

|| KEEPALIVE

Receive ModifySubscription Request

ResetLifetimeCounter()

UpdateSubscriptionParams()

ReturnResponse()

SAME

19

NORMAL

|| LATE

|| KEEPALIVE

Receive SetPublishingMode Request

ResetLifetimeCounter()

SetPublishingEnabled()

MoreNotifications = FALSE

ReturnResponse()

SAME

20

NORMAL

|| LATE

|| KEEPALIVE

Receive Republish Request

&& RequestedMessageFound == TRUE

ResetLifetimeCounter()

ReturnResponse()

SAME

21

NORMAL

|| LATE

|| KEEPALIVE

Receive Republish Request

&& RequestedMessageFound == FALSE

ResetLifetimeCounter()

ReturnNegativeResponse()

SAME

22

NORMAL

|| LATE

|| KEEPALIVE

Receive TransferSubscriptions Request

&& SessionChanged() == FALSE

ResetLifetimeCounter()

ReturnNegativeResponse ()

SAME

23

NORMAL

|| LATE

|| KEEPALIVE

Receive TransferSubscriptions Request

&& SessionChanged() == TRUE

&& ClientValidated() ==TRUE

SetSession()

ResetLifetimeCounter()

ReturnResponse()

IssueStatusChangeNotification()

SAME

24

NORMAL

|| LATE

|| KEEPALIVE

Receive TransferSubscriptions Request

&& SessionChanged() == TRUE

&& ClientValidated() == FALSE

ReturnNegativeResponse()

SAME

25

NORMAL

|| LATE

|| KEEPALIVE

Receive DeleteSubscriptions Request

&& SubscriptionAssignedToClient ==TRUE

DeleteMonitoredItems()

DeleteClientPublReqQueue()

CLOSED

26

NORMAL

|| LATE

|| KEEPALIVE

Receive DeleteSubscriptions Request

&& SubscriptionAssignedToClient ==FALSE

ResetLifetimeCounter()

ReturnNegativeResponse()

SAME

27

NORMAL

|| LATE

|| KEEPALIVE

LifetimeCounter == 1

The LifetimeCounter is decremented if PublishingTimer expires and PublishingReqQueued == FALSE

The LifetimeCounter is reset if PublishingReqQueued == TRUE.

DeleteMonitoredItems()

IssueStatusChangeNotification()

CLOSED

The state variables are defined alphabetically in Table 86.

Table 86 – State variables and parameters

State Variable

Description

MoreNotifications

A boolean value that is set to TRUE only by the CreateNotificationMsg() when there were too many Notifications for a single NotificationMessage.

LatePublishRequest

A boolean value that is set to TRUE to reflect that, the last time the publishing timer expired, there were no Publish requests queued.

LifetimeCounter

A value that contains the number of consecutive publishing timer expirations without Client activity before the Subscription is terminated.

MessageSent

A boolean value that is set to TRUE to mean that either a NotificationMessage or a keep-alive Message has been sent on the Subscription. It is a flag that is used to ensure that either a NotificationMessage or a keep-alive Message is sent out the first time the publishing timer expires.

NotificationsAvailable

A boolean value that is set to TRUE only when there is at least one MonitoredItem that is in the reporting mode and that has a Notification queued or there is at least one item to report whose triggering item has triggered and that has a Notification queued. The transition of this state Variable from FALSE to TRUE creates the “New Notification Queued” Event in the state table.

PublishingEnabled

The parameter that requests publishing to be enabled or disabled.

PublishingReqQueued

A boolean value that is set to TRUE only when there is a Publish request Message queued to the Subscription.

RequestedMessageFound

A boolean value that is set to TRUE only when the Message requested to be retransmitted was found in the retransmission queue.

SeqNum

The value that records the value of the sequence number used in NotificationMessages.

SubscriptionAssignedToClient

A boolean value that is set to TRUE only when the Subscription requested to be deleted is assigned to the Client that issued the request. A Subscription is assigned to the Client that created it. That assignment can only be changed through successful completion of the TransferSubscriptions Service.

The action functions are defined alphabetically in Table 87.

Table 87 – Functions

Function

Description

ClientValidated()

A boolean function that returns TRUE only when the Client that is submitting a TransferSubscriptions request is operating on behalf of the same user and supports the same Profiles as the Client of the previous Session.

CreateNotificationMsg()

Increment the SeqNum and create a NotificationMessage from the MonitoredItems assigned to the Subscription.

Save the newly-created NotificationMessage in the retransmission queue.

If all available Notifications can be sent in the Publish response, the MoreNotifications state Variable is set to FALSE. Otherwise, it is set to TRUE.

CreateSubscription()

Attempt to create the Subscription.

DeleteAckedNotificationMsgs()

Delete the NotificationMessages from the retransmission queue that were acknowledged by the request.

DeleteClientPublReqQueue()

Clear the Publish request queue for the Client that is sending the DeleteSubscriptions request, if there are no more Subscriptions assigned to that Client.

DeleteMonitoredItems()

Delete all MonitoredItems assigned to the Subscription.

DequeuePublishReq()

De-queue a publishing request in first-in first-out order.

Validate if the publish request is still valid by checking the timeoutHint in the RequestHeader.

If the request timed out, send a Bad_Timeout service result for the request and de-queue another publish request.

ResetLifetimeCounter()

EnqueuePublishingReq()

Enqueue the publishing request.

InitializeSubscription()

ResetLifetimeCounter()

MoreNotifications = FALSE

PublishRateChange = FALSE

PublishingEnabled = value of publishingEnabled parameter in the CreateSubscription request

PublishingReqQueued = FALSE

SeqNum = 0

SetSession()

StartPublishingTimer()

IssueStatusChangeNotification()

Issue a StatusChangeNotification notificationMessage with a status code for the status change of the Subscription. The StatusChangeNotification notificationMessage type is defined in 7.25.4. Bad_Timeout status code is used if the lifetime expires and Good_SubscriptionTransferred is used if the Subscriptions was transferred to another Session.

ResetKeepAliveCounter()

Reset the keep-alive counter to the maximum keep-alive count of the Subscription. The maximum keep-alive count is set by the Client when the Subscription is created and may be modified using the ModifySubscription Service.

ResetLifetimeCounter()

Reset the LifetimeCounter Variable to the value specified for the lifetime of a Subscription in the CreateSubscription Service (5.13.2).

ReturnKeepAlive()

Create an empty NotificationMessage with the current SeqNum value.

ReturnResponse()

ReturnNegativeResponse()

Return a Service response indicating the appropriate Service level error. No parameters are returned other than the responseHeader that contains the Service level StatusCode.

ReturnNotifications()

CreateNotificationMsg()

ReturnResponse()

If (MoreNotifications == TRUE) && (PublishingReqQueued == TRUE)

{

DequeuePublishReq()

Loop through this function again

}

ReturnResponse()

Return the appropriate response, setting the appropriate parameter values and StatusCodes defined for the Service.

SessionChanged()

A boolean function that returns TRUE only when the Session used to send a TransferSubscriptions request is different from the Client Session currently associated with the Subscription.

SetPublishingEnabled ()

Set the PublishingEnabled state Variable to the value of the publishingEnabled parameter received in the request.

SetSession

Set the Session information for the Subscription to match the Session on which the TransferSubscriptions request was issued.

StartPublishingTimer()

Start or restart the publishing timer and decrement the LifetimeCounter Variable.

UpdateSubscriptionParams()

Negotiate and update the Subscription parameters. If the new keep-alive interval is less than the current value of the keep-alive counter, perform ResetKeepAliveCounter() and ResetLifetimeCounter().

This Service is used to create a Subscription. Subscriptions monitor a set of MonitoredItems for Notifications and return them to the Client in response to Publish requests.

Illegal request values for parameters that can be revised do not generate errors. Instead the Server will choose default values and indicate them in the corresponding revised parameter.

Table 88 defines the parameters for the Service.

Table 88 – CreateSubscription Service Parameters

Name

Type

Description

Request

requestHeader

Request Header

Common request parameters (see 7.33 for RequestHeader definition).

requestedPublishing

Interval

Duration

This interval defines the cyclic rate that the Subscription is being requested to return Notifications to the Client. This interval is expressed in milliseconds. This interval is represented by the publishing timer in the Subscription state table (see 5.13.1.2).

The negotiated value for this parameter returned in the response is used as the default sampling interval for MonitoredItems assigned to this Subscription.

If the requested value is 0 or negative, the Server shall revise with the fastest supported publishing interval.

requestedLifetimeCount

Counter

Requested lifetime count (see 7.8 for Counter definition). The lifetime count shall be a minimum of three times the keep keep-alive count.

When the publishing timer has expired this number of times without a Publish request being available to send a NotificationMessage, then the Subscription shall be deleted by the Server.

requestedMaxKeepAlive

Count

Counter

Requested maximum keep-alive count (see 7.8 for Counter definition). When the publishing timer has expired this number of times without requiring any NotificationMessage to be sent, the Subscription sends a keep-alive Message to the Client.

The negotiated value for this parameter is returned in the response.

If the requested value is 0, the Server shall revise with the smallest supported keep-alive count.

maxNotificationsPerPublish

Counter

The maximum number of notifications that the Client wishes to receive in a single Publish response. A value of zero indicates that there is no limit.

The number of notifications per Publish is the sum of monitoredItems in the DataChangeNotification and events in the EventNotificationList.

publishingEnabled

Boolean

A Boolean parameter with the following values:

TRUEpublishing is enabled for the Subscription.

FALSEpublishing is disabled for the Subscription.

The value of this parameter does not affect the value of the monitoring mode Attribute of MonitoredItems.

priority

Byte

Indicates the relative priority of the Subscription. When more than one Subscription needs to send a Publish response, the Server should de-queue a Publish request to the Subscription with the highest priority number. For Subscriptions with equal priority the Server should de-queue Publish requests in a round-robin fashion.

A Client that does not require special priority settings should set this value to zero.

Response

responseHeader

Response Header

Common response parameters (see 7.34 for ResponseHeader definition).

subscriptionId

IntegerId

The Server-assigned identifier for the Subscription (see 7.19 for IntegerId definition). This identifier shall be unique for the entire Server, not just for the Session, in order to allow the Subscription to be transferred to another Session using the TransferSubscriptions service.

After Server start-up the generation of subscriptionIds should start from a random IntegerId or continue from the point before the restart.

revisedPublishingInterval

Duration

The actual publishing interval that the Server will use, expressed in milliseconds. The Server should attempt to honour the Client request for this parameter, but may negotiate this value up or down to meet its own constraints.

revisedLifetimeCount

Counter

The lifetime of the Subscription shall be a minimum of three times the keep-alive interval negotiated by the Server.

revisedMaxKeepAliveCount

Counter

The actual maximum keep-alive count (see 7.8 for Counter definition). The Server should attempt to honour the Client request for this parameter, but may negotiate this value up or down to meet its own constraints.

Table 89 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 89 – CreateSubscription Service Result Codes

Symbolic Id

Description

Bad_TooManySubscriptions

The Server has reached its maximum number of Subscriptions.

This Service is used to modify a Subscription.

Illegal request values for parameters that can be revised do not generate errors. Instead the Server will choose default values and indicate them in the corresponding revised parameter.

Changes to the Subscription settings shall be applied immediately by the Server. They take effect as soon as practical but not later than twice the new revisedPublishingInterval.

Table 90 defines the parameters for the Service.

Table 90 – ModifySubscription Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

subscriptionId

IntegerId

The Server-assigned identifier for the Subscription (see 7.19 for IntegerId definition).

requestedPublishingInterval

Duration

This interval defines the cyclic rate at which the Subscription is being requested to return Notifications to the Client. This interval is expressed in milliseconds. This interval is represented by the publishing timer in the Subscription state table (see 5.13.1.2).

The negotiated value for this parameter returned in the response is used as the default sampling interval for MonitoredItems assigned to this Subscription.

If the requested value is 0 or negative, the Server shall revise with the fastest supported publishing interval.

requestedLifetimeCount

Counter

Requested lifetime count (see 7.8 for Counter definition). The lifetime count shall be a minimum of three times the keep-alive count.

When the publishing timer has expired this number of times without a Publish request being available to send a NotificationMessage, then the Subscription shall be deleted by the Server.

requestedMaxKeepAliveCount

Counter

Requested maximum keep-alive count (see 7.8 for Counter definition). When the publishing timer has expired this number of times without requiring any NotificationMessage to be sent, the Subscription sends a keep-alive Message to the Client.

The negotiated value for this parameter is returned in the response.

If the requested value is 0, the Server shall revise with the smallest supported keep-alive count.

maxNotificationsPerPublish

Counter

The maximum number of notifications that the Client wishes to receive in a single Publish response. A value of zero indicates that there is no limit.

priority

Byte

Indicates the relative priority of the Subscription. When more than one Subscription needs to send Notifications, the Server should de-queue a Publish request to the Subscription with the highest priority number. For Subscriptions with equal priority the Server should de-queue Publish requests in a round-robin fashion.

A Client that does not require special priority settings should set this value to zero.

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader definition).

revisedPublishingInterval

Duration

The actual publishing interval that the Server will use, expressed in milliseconds. The Server should attempt to honour the Client request for this parameter, but may negotiate this value up or down to meet its own constraints.

revisedLifetimeCount

Counter

The lifetime of the Subscription shall be a minimum of three times the keep-alive interval negotiated by the Server.

revisedMaxKeepAliveCount

Counter

The actual maximum keep-alive count (see 7.8 for Counter definition). The Server should attempt to honour the Client request for this parameter, but may negotiate this value up or down to meet its own constraints.

Table 91 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 91 – ModifySubscription Service Result Codes

Symbolic Id

Description

Bad_SubscriptionIdInvalid

See Table 182 for the description of this result code.

This Service is used to enable sending of Notifications on one or more Subscriptions.

Table 92 defines the parameters for the Service.

Table 92 – SetPublishingMode Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

publishingEnabled

Boolean

A Boolean parameter with the following values:

TRUEpublishing of NotificationMessages is enabled for the Subscription.

FALSEpublishing of NotificationMessages is disabled for the Subscription.

The value of this parameter does not affect the value of the monitoring mode Attribute of MonitoredItems. Setting this value to FALSE does not discontinue the sending of keep-alive Messages.

subscriptionIds []

IntegerId

List of Server-assigned identifiers for the Subscriptions to enable or disable (see 7.19 for IntegerId definition).

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader definition).

results []

StatusCode

List of StatusCodes for the Subscriptions to enable/disable (see 7.39 for StatusCode definition). The size and order of the list matches the size and order of the subscriptionIds request parameter.

diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the Subscriptions to enable/disable (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the subscriptionIds 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 request.

Table 93 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 93 – SetPublishingMode Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Table 94 defines values for the results parameter that are specific to this Service. Common StatusCodes are defined in Table 183.

Table 94 – SetPublishingMode Operation Level Result Codes

Symbolic Id

Description

Bad_SubscriptionIdInvalid

See Table 182 for the description of this result code.

This Service is used for two purposes. First, it is used to acknowledge the receipt of NotificationMessages for one or more Subscriptions. Second, it is used to request the Server to return a NotificationMessage or a keep-alive Message. Since Publish requests are not directed to a specific Subscription, they may be used by any Subscription. 5.13.1.2 describes the use of the Publish Service.

Client strategies for issuing Publish requests may vary depending on the networking delays between the Client and the Server. In many cases, the Client may wish to issue a Publish request immediately after creating a Subscription, and thereafter, immediately after receiving a Publish response.

In other cases, especially in high latency networks, the Client may wish to pipeline Publish requests to ensure cyclic reporting from the Server. Pipelining involves sending more than one Publish request for each Subscription before receiving a response. For example, if the network introduces a delay between the Client and the Server of 5 seconds and the publishing interval for a Subscription is one second, then the Client shall issue Publish requests every second instead of waiting for a response to be received before sending the next request.

A Server should limit the number of active Publish requests to avoid an infinite number since it is expected that the Publish requests are queued in the Server. But a Server shall accept more queued Publish requests than created Subscriptions. It is expected that a Server supports several Publish requests per Subscription. When a Server receives a new Publish request that exceeds its limit it shall de-queue the oldest Publish request and return a response with the result set to Bad_TooManyPublishRequests. If a Client receives this Service result for a Publish request it shall not issue another Publish request before one of its outstanding Publish requests is returned from the Server.

Clients can limit the size of Publish responses with the maxNotificationsPerPublish parameter passed to the CreateSubscription Service. However, this could still result in a message that is too large for the Client or Server to process. In this situation, the Client will find that either the SecureChannel goes into a fault state and needs to be re-established or the Publish response returns an error and calling the Republish Service also returns an error. If either situation occurs then the Client will shall adjust its message processing limits or the parameters for the Subscription and/or MonitoredItems.

The return diagnostic info setting in the request header of the CreateMonitoredItems or the last ModifyMonitoredItems Service is applied to the Monitored Items and is used as the diagnostic information settings when sending Notifications in the Publish response.

Table 95 defines the parameters for the Service.

Table 95 – Publish Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

subscription

Acknowledgements []

Subscription Acknowledgement

The list of acknowledgements for one or more Subscriptions. This list may contain multiple acknowledgements for the same Subscription (multiple entries with the same subscriptionId). This structure is defined in-line with the following indented items.

subscriptionId

IntegerId

The Server assigned identifier for a Subscription (see 7.19 for IntegerId definition).

sequenceNumber

Counter

The sequence number being acknowledged (see 7.8 for Counter definition). The Server may delete the Message with this sequence number from its retransmission queue.

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader definition).

subscriptionId

IntegerId

The Server-assigned identifier for the Subscription for which Notifications are being returned (see 7.19 for IntegerId definition). The value 0 is used to indicate that there were no Subscriptions defined for which a response could be sent.

availableSequence

Numbers []

Counter

A list of sequence number ranges that identify unacknowledged NotificationMessages that are available for retransmission from the Subscription’s retransmission queue including the sequence number of this response if it is not a keep-alive Message. This list is prepared after processing the acknowledgements in the request (see 7.8 for Counter definition).

The list shall be empty if the Server does not support the retransmission queue. If the list is empty, the Client should not acknowledge sequence numbers.

This information is for diagnostic purpose and Clients should log differences to the expected sequence numbers.

moreNotifications

Boolean

A Boolean parameter with the following values:

TRUEthe number of Notifications that were ready to be sent could not be sent in a single response.

FALSEall Notifications that were ready are included in the response.

notificationMessage

Notification Message

The NotificationMessage that contains the list of Notifications. The NotificationMessage parameter type is specified in 7.26.

results []

StatusCode

List of results for the acknowledgements (see 7.39 for StatusCode definition). The size and order of the list matches the size and order of the subscriptionAcknowledgements request parameter.

diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the acknowledgements (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the subscriptionAcknowledgements 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 request.

Table 96 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 96 – Publish Service Result Codes

Symbolic Id

Description

Bad_TooManyPublishRequests

The Server has reached the maximum number of queued Publish requests.

Bad_NoSubscription

There is no Subscription available for this session.

Table 97 defines values for the results parameter that are specific to this Service. Common StatusCodes are defined in Table 183.

Table 97 – Publish Operation Level Result Codes

Symbolic Id

Description

Bad_SubscriptionIdInvalid

See Table 182 for the description of this result code.

Bad_SequenceNumberUnknown

The sequence number is unknown to the Server.

Good_RetransmissionQueueNotSupported

The Server does not support retransmission queue and acknowledgement of sequence numbers is not available.

This Service requests the Subscription to republish a NotificationMessage from its retransmission queue. If the Server does not have the requested Message in its retransmission queue, it returns an error response.

See 5.13.1.2 for the detail description of the behaviour of this Service.

See 6.7 for a description of the issues and strategies regarding reconnect handling and Republish.

Table 98 defines the parameters for the Service.

Table 98 – Republish Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

subscriptionId

IntegerId

The Server assigned identifier for the Subscription to be republished (see 7.19 for IntegerId definition).

retransmitSequence

Number

Counter

The sequence number of a specific NotificationMessage to be republished (see 7.8 for Counter definition).

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader definition).

notificationMessage

Notification Message

The requested NotificationMessage. The NotificationMessage parameter type is specified in 7.26.

Table 99 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 99 – Republish Service Result Codes

Symbolic Id

Description

Bad_SubscriptionIdInvalid

See Table 182 for the description of this result code.

Bad_MessageNotAvailable

The requested message is no longer available.

This Service is used to transfer a Subscription and its MonitoredItems from one Session to another. For example, a Client may need to reopen a Session and then transfer its Subscriptions to that Session. It may also be used by one Client to take over a Subscription from another Client by transferring the Subscription to its Session.

The authenticationToken contained in the request header identifies the Session to which the Subscription and MonitoredItems shall be transferred. The Server shall validate that the Client of that Session is operating on behalf of the same user. If the Client uses an ANONYMOUS user token, the Server shall validate if the ApplicationUri is the same for the old and the new Session and the MessageSecurityMode is SIGN or SIGNANDENCRYPT. If the Server transfers the Subscription, it returns the sequence numbers of the NotificationMessages that are available for retransmission. The Client should acknowledge all Messages in this list for which it will not request retransmission.

If the Server transfers the Subscription to the new Session, the Server shall issue a StatusChangeNotification notificationMessage with the status code Good_SubscriptionTransferred to the old Session. The StatusChangeNotification notificationMessage type is defined in 7.25.4.

Table 100 defines the parameters for the Service.

Table 100 – TransferSubscriptions Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

subscriptionIds []

IntegerId

List of identifiers for the Subscriptions to be transferred to the new Client (see 7.19 for IntegerId definition). These identifiers are transferred from the primary Client to a backup Client via external mechanisms.

sendInitialValues

Boolean

A Boolean parameter with the following values:

TRUEthe first Publish response(s) after the TransferSubscriptions call shall contain the current value for each data MonitoredItem in the Subscription where the Monitoring Mode is set to Reporting.If a value is queued for a data MonitoredItem, the next value in the queue is sent in the Publish response. If no value is queued for a data MonitoredItem, the last value sent is repeated in the Publish response.

FALSEthe first Publish response after the TransferSubscriptions call shall contain only the value changes since the last Publish response was sent.

This parameter only applies to MonitoredItems used for monitoring Attribute changes.

The data should be sent in the next regular PublishingInterval.

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader definition).

results []

TransferResult

List of results for the Subscriptions to transfer. The size and order of the list matches the size and order of the subscriptionIds request parameter. This structure is defined in-line with the following indented items.

statusCode

StatusCode

StatusCode for each Subscription to be transferred (see 7.39 for StatusCode definition).

availableSequence

Numbers []

Counter

A list of sequence number ranges that identify NotificationMessages that are in the Subscription’s retransmission queue. This parameter is null or empty if the transfer of the Subscription failed. The Counter type is defined in 7.8.

diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the Subscriptions to transfer (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the subscriptionIds 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 request.

Table 101 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 101 – TransferSubscriptions Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Bad_InsufficientClientProfile

The Client of the current Session does not support one or more Profiles that are necessary for the Subscription.

Table 102 defines values for the operation level statusCode parameter that are specific to this Service. Common StatusCodes are defined in Table 183.

Table 102 – TransferSubscriptions Operation Level Result Codes

Symbolic Id

Description

Bad_SubscriptionIdInvalid

See Table 182 for the description of this result code.

Bad_UserAccessDenied

See Table 182 for the description of this result code.

The Client of the current Session is not operating on behalf of the same user as the Session that owns the Subscription.

This Service is invoked to delete one or more Subscriptions that belong to the Client's Session.

Successful completion of this Service causes all MonitoredItems that use the Subscription to be deleted. If this is the last Subscription for the Session, then all Publish requests still queued for that Session are de-queued and shall be returned with Bad_NoSubscription.

Subscriptions that were transferred to another Session shall be deleted by the Client that owns the Session.

Table 103 defines the parameters for the Service.

Table 103 – DeleteSubscriptions Service Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33 for RequestHeader definition).

subscriptionIds []

IntegerId

The Server-assigned identifier for the Subscription (see 7.19 for IntegerId definition).

Response

responseHeader

ResponseHeader

Common response parameters (see 7.34 for ResponseHeader definition).

results []

StatusCode

List of StatusCodes for the Subscriptions to delete (see 7.39 for StatusCode definition). The size and order of the list matches the size and order of the subscriptionIds request parameter.

diagnosticInfos []

DiagnosticInfo

List of diagnostic information for the Subscriptions to delete (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the subscriptionIds 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 request.

Table 104 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.

Table 104 – DeleteSubscriptions Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182 for the description of this result code.

Bad_TooManyOperations

See Table 182 for the description of this result code.

Table 105 defines values for the results parameter that are specific to this Service. Common StatusCodes are defined in Table 183.

Table 105 – DeleteSubscriptions Operation Level Result Codes

Symbolic Id

Description

Bad_SubscriptionIdInvalid

See Table 182 for the description of this result code.