OPC UA Adapters

Contents

Introduction
Configuration
OPC UA Adapter Properties
Input Ports
Output Ports
Data Conversion
Typechecking and Error Handling
Suspend and Resume Behavior
OPC UA Adapter Sample

Note

The OPC UA adapters are provided for Microsoft Windows systems only.

Introduction

The Streaming® Adapter for OPC UA allows Streaming to interact with data from an OPC UA (Open Platform Communications Unified Architecture) server. The adapters in this set include:

  • The OPC UA Control adapter, which is used to control the connection with the OPC UA server (connection, disconnection, server status, and so on)

  • The OPC UA Reader adapter, which is used to retrieve values from OPC UA Variable nodes

  • The OPC UA Writer adapter, which is used to write values to OPC UA Variable nodes

  • The OPC UA Subscriber adapter, which is used to subscribe to Variable nodes and get continuous updates when the nodes' values change

  • The OPC UA Browser adapter, which is used to traverse the OPC UA server's node hierarchy and retrieve metadata for these nodes

  • The OPC UA Historical Data Reader, which is used to retrieve historical data values from OPC UA data nodes

Placing an OPC UA Adapter on the Canvas

The OPC UA adapters are members of the Java Operators group in the Palette view in StreamBase Studio. Select the operator from the Insert an Operator or Adapter dialog, following these steps:

  1. Open the Insert an Operator or Adapter dialog with one of the following methods:

    1. Drag the Adapters, Java Operators token from the Operators and Adapters drawer of the Palette view to the canvas.

    2. Click on the canvas where you want to place the operator, then invoke the keyboard shortcut O V.

    3. From the top-level menu, invoke Insert>Operator>Java.

  2. In the search field, enter OPC to narrow the list of adapters.

  3. Select the OPC UA adapter of interest and click OK.

Prerequisites

In order run correctly, the adapters require that the Microsoft .NET Framework 4.8 or higher be installed on the machine.

How the Adapters Work

All adapters have one input stream to receive commands. The schema for this command stream varies depending on the adapter type; each schema is described in a section below.

All adapters have an output stream to communicate status events (such as when an error occurs during the execution of a command). The schema for this stream is identical for all OPC UA adapter types and is described in a section below.

With the exception of the Control adapter, all adapters also have a second output port to emit the results of running commands. For example, the Reader adapter uses this port to emit the value(s) it reads from the server.

Configuration

The different OPC UA operators share a connection to the same server, provided they are configured to do so. Each operator lists the servers available in the a combo box (see OPC UA Adapter Properties). The list's values are specified in a dedicated section of the application's adapter configuration file. Here is an example of such a section, containing all supported settings (long lines wrap to the next, for clarity): 

name = "OPC-UA.conf"
type = "com.tibco.ep.streambase.configuration.adapter"
version = "1.0.0"
configuration = {

// An adapter group type defines a collection of EventFlow adapter configurations,
// indexed by adapter type.
  AdapterGroup = {

// A collection of EventFlow adapter configurations, indexed by adapter type. This object
// is required and must contain at least one configuration.
    adapters = {

// The root section for an EventFlow adapter configuration.
      opc-ua = {

// Section list. This array is optional and has no default value.
        sections = [ 

// A configuration for an EventFlow adapter named section.
          {

// Section name. The value does not have to be unique; that is, you can have
// multiple sections with the same name in the same array of sections. This property
// is required.
            name = "endpoint-definition"

// Section for setting adapter properties. All values must be strings. This object
// is optional and has no default value.
              settings = {
                id = "TestEndpoint"
                            
// The discovery server to which to connect
// Note that this value may be enciphered using the epadmin encrypt secret command
                  discovery-uri = "opc.tcp://milo.digitalpetri.com:62541/milo"
                            
// 0 to not re-attempt connection when the attempt fails, -1 to continuously re-attempt
                  num-reconnection-retries = "5"
                  reconnection-retry-interval-ms = "10000"
                            
// Set to true to select the endpoint with the highest security level (a valid X509
// certificate will need to be provided below), false to use the lowest security
// (typically public anonymous access).
                  use-maximum-security = "false"
                            
// IMPORTANT!
// 
// "application-certificate-store-path" must point to a valid store in all cases.
// 
// "application-certificate-subject-name" and "application-certificate-thumbprint"
// must point to a valid X509 certificate if "use-maximum-security" above is set to true.
// Of course "application-certificate-store-path" can be adjusted to help locate this certificate.
                  application-certificate-store-path = "LocalMachine\\My"
                  application-certificate-subject-name = "CN=UA Client Test, DC=MYMACHINE"
                  application-certificate-thumbprint = "a306b24b05b28e7b3e2c4d23925c453e719a0b55"
                            
// Credentials to be used (if any) with the above certificate when
// connecting to the OPC UA server. You may leave these values empty
// to attempt access to public (or uncredentialed) servers/endpoints.
// 
// Note that "username" and "password" values may be enciphered using the epadmin encrypt secret command
                  username = ""
                  password = ""
                            
// Modify these as needed
                  application-uri = "urn:localhost:TIBCO:MyApp"
                  product-uri = "http://tibco.com"
                  trusted-issuer-certificate-store-path = "LocalMachine\\Trusted UA Applications"
                  trusted-peer-certificate-store-path = "LocalMachine\\Trusted UA Applications"
                  rejected-certificate-store-path = "LocalMachine\\Rejected UA Certificates"
                  auto-accept-untrusted-certificates = "false"
                  reject-sha1-certificates = "false"
                  min-certificate-key-size = "1024"
                  add-application-certificates-to-trusted-store = "false"
                  send-certificate-chain = "true"
            }
          }
        ]
      }
    }
  }
}

A best practice is to define your endpoints in this file before placing operator instances on the canvas, so that the lists are already available in the Properties view and the operators can be configured right away.

OPC UA Adapter Properties

This section describes the properties you can set for the adapters, using the various tabs of the Properties view in StreamBase Studio.

In following section tables, the Property column shows each property name as found in the one or more adapter properties tabs of the Properties view for this adapter.

Use the StreamSQL names of the adapter's properties when using this adapter in a StreamSQL program with the APPLY JAVA statement.

OPC UA General Tab

Name: Use this required field to specify or change the name of this instance of this component. The name must be unique within the current EventFlow module. The name can contain alphanumeric characters, underscores, and escaped special characters. Special characters can be escaped as described in Identifier Naming Rules. The first character must be alphabetic or an underscore.

Operator: A read-only field that shows the formal name of the operator.

Class name: Shows the fully qualified class name that implements the functionality of this operator. If you need to reference this class name elsewhere in your application, you can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.

Start options: This field provides a link to the Cluster Aware tab, where you configure the conditions under which this operator starts.

Enable Error Output Port: Select this checkbox to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports to learn about Error Ports.

Description: Optionally, enter text to briefly describe the purpose and function of the component. In the EventFlow Editor canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

OPC UA Operator Properties

The OPC UA adapters have the following properties, with the exceptions noted for some properties only on particular adapters:

Property Data Type Default Description
OPC-UA Configuration button —

Provides an Edit button. Click this to open a configuration file named OPC-UA.conf file in the current project. If the file does not exist, it is created in the project's src/main/configuations folder.

OPC Server Definition combo box Cleared

REQUIRED. Specifies the ID of the OPC UA server to which to connect, as defined in the adapter configuration file.
Connect on Startup check box Cleared CONTROL ADAPTER ONLY. Attempt to connect to the server when the application starts.
Log Level drop-down list INFO Controls the level of verbosity the adapter uses to send notifications to the console. This setting can be higher than the containing application's log level. If set lower, the system log level will be used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE.

Cluster Aware Tab

Use the settings in this tab to enable this operator or adapter for runtime start and stop conditions in a multi-node cluster. During initial development of the fragment that contains this operator or adapter, and for maximum compatibility with releases before 10.5.0, leave the Cluster start policy control in its default setting, Start with module.

Cluster awareness is an advanced topic that requires an understanding of StreamBase Runtime architecture features, including clusters, quorums, availability zones, and partitions. See Cluster Awareness Tab Settings on the Using Cluster Awareness page for instructions on configuring this tab.

Concurrency Tab

Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.

Caution

Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.

Input Ports

The adapters have a single input port which is used to receive commands. The schema for this port is different for each adapter. The schemas are described in this section.

OPC UA Control Adapter Input Port

This port is used to connect or disconnect from the configured server, and to get the current connection status. Results will be issued on the adapter's Status output port.

Field Name Field Type Description
command string REQUIRED. The command to execute. One of connect, disconnect, getconnectionstatus.

OPC UA Browser Adapter Input Port

The Browser adapter allows your application to traverse the data hierarchy of the OPC UA server. Using this port you can retrieve the metadata of one or more nodes (by specifying them by Node ID in the NodeList field). This metadata includes the node's class (Object, Variable, and so on), its access levels and a list of the nodes it references.

Field Name Field Type Description
NodeList list<string> REQUIRED. Contains a list of one or more nodes for which to retrieve metadata and node references. Each string is expected to represent the valid node id of an OPC UA node of any type. If an entry is left null, the root node of the server will be queried.

OPC UA Reader Adapter Input Port

This port instructs the adapter to retrieve the current value of the specified OPC UA nodes. These nodes are expected to be of class Variable (since they are the only nodes that can contain a value).

Field Name Field Type Description
NodeList list<string> REQUIRED. Contains a list of one or more Variable nodes for which to retrieve the value. Each string is expected to represent the valid node id of an OPC UA node of type Variable.
MaxAge long If set, specifies the maximum age of a value (in milliseconds) beyond which the server should attempt to read a fresh value from the data source. A null value (or a value of 0) for this field means the server will attempt to read a fresh value for each specified node.

OPC UA Writer Adapter Input Port

Using this port you can change the current value of one or more OPC UA nodes of class Variable.

Each value is specified as a string, and will be automatically parsed and converted to the correct type (Int8, DateTime, LocalizedText and so forth) based on the target node's data type information. See this conversion table for more information on the supported types.

Field Name Field Type Description
NodeList list<tuple> A list of tuples, each tuple describing one Variable node to update along with the value(s) with which to update it.
^ NodeID string The ID of the node to update.
Value string If this node represents a scalar value, this field is expected to contain the new value with which to update the node (if the value is set to null, the node's value will similarly set to null). If this node represents an array of values, this field is expected to be left null.
ValueArray list<string> If this node represents an array of values, this field is expected to contain the list of the values with which to update the node's array (and may be left null to set the node's value to null). If this node represents a scalar value, this field is expected to be null.

OPC UA Subscriber Adapter Input Port

This port is used to start (and stop) monitoring one or more Variable nodes for changes in their value. Periodical updates are issued by the adapter for each of these subscriptions until the subscription is removed via an Unsubscribe command to this port. Multiple subscriptions may be active at the same time.

Each Subscribe command sent to this port results in a single subscription being created, which monitors updates to all the specified nodes. Upon successful creation of a subscription, a status tuple will be emitted to the adapter's Status port to indicate success and more importantly to report the new subscription's ID, which must be specified in an eventual Unsubscribe command to cancel this subscription.

Field Name Field Type Description
Action string REQUIRED. One of Subscribe, Unsubscribe.
NodeList list<string> REQUIRED. Contains a list of one or more Variable nodes to which to subscribe. Each string is expected to represent the valid node id of an OPC UA node of type Variable.
SubscriptionID string UNSUBSCRIBE ACTION ONLY. Identifies which subscription to which to unsubscribe. This ID is reported by the Subscribe action's Status output port when subscribing. This setting is ignored during Subscribe actions.
PollingInterval int SUBSCRIBE ACTIONS ONLY. Specifies the number of milliseconds between updates from the subscription. A null value, a negative value or a value of 0 for this field means the server will employ the shortest supported update interval.

OPC UA Historical Data Reader Adapter Input Port

This port instructs the adapter to retrieve the historical values for the specified OPC UA nodes. These nodes are expected to be of class Variable (since they are the only nodes that can contain a value).

Field Name Field Type Description
NodeList list<string> REQUIRED. Contains a list of one or more Variable nodes for which to retrieve historical values. Each string is expected to represent the valid node id of an OPC UA node of type Variable.
ReadType string The kind of historical query to execute. One of Raw (default), Modified, ReadAtTimes, Processed.
StartTime timestamp The beginning of the period to read.
EndTime timestamp The end of the period to read.
NumValuesPerNode int The maximum number of values to return per node.
ReturnBounds boolean Whether to include the bounding values.
RequestedTimes list<timestamp> For reads of ReadType ReadAtTimes, this is expected to contain the list of timestamps for which to read a value.
UseSimpleBounds boolean For reads of ReadType ReadAtTimes, indicates whether to use simple bounding values (true) or interpolated bounding values (false).
ProcessingIntervalInMS int For reads of ReadType Processed, specifies the interval of time (in milliseconds) between returned aggregate values.
AggregateType string For reads of ReadType Processed, specifies the NodeID of each aggregate operation(s) to perform. Note that the available aggregate functions vary from server to server. This list is typically described in the ServerCapabilities (i=2268) node hierarchy.
UseServerCapabilitiesDefaults boolean For reads of ReadType Processed, indicates whether to use default aggregate configuration settings
TreatUncertainAsBad boolean For reads of ReadType Processed, indicates whether values of uncertain quality should be treated as bad during aggregation.
PercentDataBad int For reads of ReadType Processed, indicates the minimum percentage of bad data values for the results to be considered bad.
PercentDataGood int For reads of ReadType Processed, indicates the minimum percentage of good data values for the results to be considered good.
UseSlopedExtrapolation boolean For reads of ReadType Processed, whether to use sloped extrapolation (true) or stepped interpolation (false) when no boundary value exists.

Output Ports

Every adapter (except the Control adapter) has an output port to emit tuples resulting from running queries. In addition, every adapter has an output port to receive status events.

Status Output Port (Common to all OPC UA operators)

The status port emits tuples that describe the status of processing each input tuple. The schema of the output tuple is as follows:

Field Name Field Type Description
Status string Describes this event (Connected, Disconnected, Success, Error, and so on).
Time timestamp The time at which this status tuple was generated.
Info list<tuple> Contains any additional information pertaining to this event. Each tuple has two fields, Name and Value to describe one informational entry.

OPC UA Browser Adapter Results Output Port

The Browser adapter allows your application to traverse the data hierarchy of the OPC UA server. Using this port emits tuples describing the metadata of one or more nodes. This metadata includes the node's class (Object, Variable, and so on), its access levels and a list of the nodes it references.

Field Name Field Type Description
Nodes list<tuple> The list of all the nodes retrieved, in the order in which they were requested in the input tuple's NodeList field.
^ NodeID string The OPC UA ID of the browsed node.
NodeClass string The class of this node (Object, Variable, and so on).
DisplayName string The display name of the node.
BrowseName string The browse name of the node.
Description string The description the browsed node.
AccessLevel string  
UserAccessLevel string  
WriteMask string  
UserWriteMask string  
MinimumSamplingInterval int The minimum interval at which the value of this node can be polled.
ErrorCode int Error code (used when there is a problem reading this node).
ErrorMessage string Error message (used when there is a problem reading this node).
References list<tuple> The list of child nodes referenced by this node.
^ ReferenceType string The type of reference represented by this entry.
NodeID string The ID of the referenced (target) node.
NodeClass string The type of the target node (Object, Variable, and so on).
DisplayName string The display name of the target node.
BrowseName string The browse name of the target node.
Input tuple The command tuple sent to the input port that triggered this result.

OPC UA Reader Adapter Results Output Port

The Reader adapter allows your application to query the current value attribute of one or more Variable nodes on the OPC UA server. See this conversion table for a list of supported types.

Each returned entry will be a string representation of the value, along with its data type and some additional metadata. Using this information the application can then parse the string into the desired type (Int32, Double, Timestamp, and so on) as required.

If a given node's value is an array rather than a scalar, the ValueArray (of type list<string>) field will be used instead of the Value field. Note that only arrays of rank 1 are supported.

If an error occurs when reading a node specified in the input tuple's NodeList field, the StatusCode field will provide an error code.

Note

Many OPC UA servers use case-sensitive node IDs.

Field Name Field Type Description
Values list<tuple> The list of all the values retrieved, in the order in which they were requested in the input tuple's NodeList field.
^ NodeID string The OPC UA ID of the Variable node containing this value.
Value string The value if the data type of this Variable node's VALUE attribute is non-null and a scalar, or null if the attribute is null or if its rank is 1 or more (that is, if it represents an array of values).
ValueArray list<string> If the value's rank is 1 (that is, the data type is an simple array of scalars) this field will contain the array while the Value field will be set to null. If the value is a scalar, this field will be set to null. Arrays of rank greater than 1 are not supported.
ValueRank int -1 if the value is a scalar type, 1 if it's an array of scalars. The rank may also be greater than 1 in the case of multi-dimensional arrays, but such arrays are not supported so the actual Value and ValueArray fields will not be set in those cases.
DataType string The data type of the value, or in the case of an array, the data type of the array's elements. See this conversion table for supported data types and their expected conversion to Streaming types.
SourceTimestamp Timestamp The source timestamp associated with this value.
ServerTimestamp Timestamp The server timestamp associated with this value.
StatusCode string Indicates whether the read operation was successful and the value is valid (Good) or some error value to indicate there was a problem.
Input tuple The command tuple sent to the input port that triggered this result.

OPC UA Writer Adapter Results Output Port

The Writer adapter allows your application to set or update the value attribute of one or more Variable nodes on the OPC UA server. See this conversion table for a list of supported types.

The output on this port informs on the result of the write operation for each specified node (Good in the case of success, or some other value related to the reason for failure).

Field Name Field Type Description
WriteStatus list<tuple> The list of the result of writing each entry, in the order in which they were requested in the input tuple's NodeList field.
^ NodeID string The OPC UA ID of the Variable node to which the write operation was attempted.
StatusCode string Indicates whether the write operation was successful (Good) or some error value to indicate there was a problem.
Input tuple The command tuple sent to the input port that triggered this result.

OPC UA Subscriber Adapter Results Output Port

The Subscriber adapter allows your application to monitor the current value attribute of one or more Variable nodes on the OPC UA server (see this conversion table for a list of supported types). Once a subscription is active, tuples will be emitted periodically to report on the monitored nodes' values.

Each returned entry in the tuple will be a string representation of the value, along with its data type and some additional metadata. Using this information the application can then parse the string into the desired type (Int32, Double, Timestamp, and so on) as required.

If a given node's value is an array rather than a scalar, the ValueArray (of type list<string>) field will be used instead of the Value field. Note that only arrays of rank 1 are supported.

If an error occurs when reading a node specified in the input tuple's NodeList field, the StatusCode field will provide an error code.

Note

Many OPC UA servers use case-sensitive node IDs.

Field Name Field Type Description
SubscriptionID long The ID of this subscription, as assigned by the server. Use this value in the SubscriptionID field of Unsubscribe commands to cancel this subscription and stop monitoring the associated nodes.
Values list<tuple> The list of all the values retrieved, in the order in which they were requested in the input tuple's NodeList field.
^ NodeID string The OPC UA ID of the Variable node containing this value.
Value string The value if the data type of this Variable node's VALUE attribute is non-null and a scalar, or null if the attribute is null or if its rank is 1 or more (that is, if it represents an array of values).
ValueArray list<string> If the value's rank is 1 (that is, the data type is an array of simple scalars) this field will contain the array while the Value field will be set to null. If the value is a scalar, this field will be set to null. Arrays of rank greater than 1 are not supported.
ValueRank int -1 if the value is a scalar type, 1 if it is an array of scalars. The rank may also be greater than 1 in the case of multi-dimensional arrays, but such arrays are not supported so the actual Value and ValueArray fields will not be set in those cases.
DataType string The data type of the value, or in the case of an array, the data type of the array's elements. See this conversion table for supported data types and their expected conversion to Streaming types.
SourceTimestamp Timestamp The source timestamp associated with this value.
ServerTimestamp Timestamp The server timestamp associated with this value.
StatusCode string Indicates whether the read operation was successful and the value is valid (Good) or some error value to indicate there was a problem.

OPC UA Historical Data ReaderAdapter Results Output Port

The result of historical data queries sent to the adapter are emitted on this port.

Field Name Field Type Description
Nodes list<tuple> The list of all the nodes retrieved, in the order in which they were requested in the input tuple's NodeList field.
^ NodeID string The OPC UA ID of the queried node.
StatusCode string Indicates whether the overall query of this node was successful and the return values are valid (Good) or some error value to indicate there was a problem.
Values list<tuple> The list of values retrieved for this node.
^ Value string The value if the data type of this Variable node's VALUE attribute is non-null and a scalar, or null if the attribute is null or if its rank is 1 or more (that is, if it represents an array of values).
ValueArray list<string> If the value's rank is 1 (that is, the data type is an array of simple scalars) this field will contain the array while the Value field will be set to null. If the value is a scalar, this field will be set to null. Arrays of rank greater than 1 are not supported.
DataType string The data type of the value, or in the case of an array, the data type of the array's elements. See this conversion table for supported data types and their expected conversion to Streaming types.
ValueRank int -1 if the value is a scalar type, 1 if it is an array of scalars. The rank may also be greater than 1 in the case of multi-dimensional arrays, but such arrays are not supported so the actual Value and ValueArray fields will not be set in those cases.
StatusCode string Indicates whether the read operation was successful and the value is valid (Good) or some error value to indicate there was a problem.
SourceTimestamp timestamp The source timestamp associated with this value.
ServerTimestamp timestamp The server timestamp associated with this value.
ModificationInfos list<tuple> For reads of ReadType Modified, this contains the list of modifications (if any) made to each value.
^ ModificationTime timestamp The time at which the modification was made.
UpdateType string The type of modification made (one of Insert, Replace, Update, Delete).
UserName string The identity of the author of this modification.
Input tuple The command tuple sent to the input port that triggered this result.

Data Conversion

Because different nodes may contain values of different types, the various OPC UA operators represent each value as a string, but also provide metadata such as data type and array rank to inform on their actual representation in the OPC server. Using this information the Streaming application can parse the string values into more representative types, for example to add the value of two nodes that are of type Double in the server.

The following table lists the various OPC UA data types, and the Streaming types into which the values can be parsed.

OPC UA Type Streaming Type into which the string representation can be parsed
Boolean boolean
Byte, SByte, Int16, Int32, UInt16 int
Int64, UInt64 long
ByteString blob
Float, Double double
DateTime timestamp
Guid, LocalizedText, NodeId, QualifiedName, StatusCode, String, XmlElement string
Single-dimensional array (array of rank 1) A list<string> where each element can be parsed according to the type of the scalar contained in the OPC array
Variant If the Variant represents one of the above types, it will be unwrapped into one of the above types
DataValue, DiagnosticInfo, ExpandedNodeId, ExtensionObject Not supported.
Multi-dimensional array (array of rank 2 or greater) Not supported.

Typechecking and Error Handling

Typechecking fails if the input schema does not contain all the required fields, or if a valid OPC Server Definition hasn't been specified.

Suspend and Resume Behavior

Upon suspension, the OPC UA adapters finish processing the current tuple, outputs the result tuple(s), then pauses waiting for input.

Upon resumption, the OPC UA adapters continue processing with the next input tuple.

In either case, any database connection is not modified.

OPC UA Adapter Sample

The Streaming installation includes a sample demonstrating the use of this operator. To load the sample in Studio, select File>Import Samples and Community Content and look under the IoT section for an entry called OPC UA Adapters.

Back to Top ^