PI Connector for OPC UA 2.0.

User Guide
OSIsoft, LLC
1600 Alvarado Street
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web: http://www.osisoft.com

PI Connector for OPC UA 2.0.1 User Guide

© 2015 - 2019 by OSIsoft, LLC. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or
by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission
of OSIsoft, LLC.
OSIsoft, the OSIsoft logo and logotype, Managed PI, OSIsoft Advanced Services, OSIsoft Cloud Services,
OSIsoft Connected Services, PI ACE, PI Advanced Computing Engine, PI AF SDK, PI API,
PI Asset Framework, PI Audit Viewer, PI Builder, PI Cloud Connect, PI Connectors, PI Data Archive,
PI DataLink, PI DataLink Server, PI Developers Club, PI Integrator for Business Analytics, PI Interfaces,
PI JDBC Driver, PI Manual Logger, PI Notifications, PI ODBC Driver, PI OLEDB Enterprise,
PI OLEDB Provider, PI OPC DA Server, PI OPC HDA Server, PI ProcessBook, PI SDK, PI Server, PI Square,
PI System, PI System Access, PI Vision, PI Visualization Suite, PI Web API, PI WebParts, PI Web Services,
RLINK, and RtReports are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein
are the property of their respective owners.
U.S. GOVERNMENT RIGHTS
Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC
license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12-212, FAR
52.227-19, or their successors, as applicable. OSIsoft, LLC.
Version: 2.0.1
Published: 18 December 2019
Contents

Introduction to PI Connector for OPC UA 2.0................................................................ 1

Operational overview...................................................................................................................................... 2
Connection to the OPC UA servers.................................................................................................................. 2
Browse or discover the OPC UA address space................................................................................................ 2
OPC UA objects and entities selection............................................................................................................. 3
Tag naming..................................................................................................................................................... 3
PI points, PI AF elements, and attributes......................................................................................................... 3
OPC UA static and dynamic variables and their mapping to PI points and PI AF elements............................3
Naming conventions................................................................................................................................... 4
Compression configuration..........................................................................................................................5
Units of Measure (UOM) and PI AF.............................................................................................................. 5
Conversion of non-ASCII characters for tag names...................................................................................... 6
Modes of operation......................................................................................................................................... 6
Generic mode..............................................................................................................................................6
ISA95 mode.................................................................................................................................................6
PCS 7 mode................................................................................................................................................. 7
TagsOnly mode........................................................................................................................................... 9
Mapping of PI points data types to OPC UA types..........................................................................................11
Data collection.............................................................................................................................................. 12
Historical data collection............................................................................................................................... 12
AF structure for OPC UA hierarchy................................................................................................................ 12

Prepare for connector installation............................................................................. 15

Software and hardware requirements for connectors.................................................................................... 15
Upgrade to version 2.x...................................................................................................................................16
Connector security.........................................................................................................................................17
Sensitive data security ...............................................................................................................................17
Security best practices for PI Connector for OPC UA.................................................................................. 17
Firewall configuration................................................................................................................................ 18
Create the Windows account for the connector......................................................................................... 19
Identify the administration port number........................................................................................................20
Identify administration group users............................................................................................................... 20

Install the connector................................................................................................. 23

Configure silent installation for connectors................................................................................................... 24
Change connector installation settings.......................................................................................................... 25
Uninstall the connector................................................................................................................................. 25
Uninstall the connector in silent mode.......................................................................................................26
Troubleshoot installation...............................................................................................................................26

Connector configuration........................................................................................... 27
Open the administration website of the connector........................................................................................ 27
Register the connector...................................................................................................................................27
Open PI Data Collection Manager..................................................................................................................28
Add a data source..........................................................................................................................................28
Data source configuration settings............................................................................................................ 29
Advanced configuration.............................................................................................................................30
Failover / Redundancy................................................................................................................................ 31

PI Connector for OPC UA 2.0.1 User Guide iii

Contents

OPC UA Communication Timeouts............................................................................................................ 33

OPC UA Historical Data..............................................................................................................................33
OPC UA Subscription Parameters.............................................................................................................. 34
Transformational Rules.............................................................................................................................. 35
Modify data sources...................................................................................................................................36
Discover data source contents................................................................................................................... 37
Select data.....................................................................................................................................................37
Start and stop data collection........................................................................................................................ 37
Verify data collection..................................................................................................................................... 37
PI Connector Relays................................................................................................................................... 38
Message logs............................................................................................................................................. 38

Technical support and other resources....................................................................... 39

iv PI Connector for OPC UA 2.0.1 User Guide

Introduction to PI Connector for OPC UA 2.0
PI Connector for OPC UA copies contextual and time-series data from OPC (Open Platform
Communications) UA (Unified Architecture) servers to OSIsoft PI Data Archive and PI Asset
Framework servers. Static OPC UA variables are mapped to PI Asset Framework elements and
attributes, and dynamic variables are converted to PI points. Before starting, users have an
option to browse the whole OPC UA address space and select manually, or by using a formula,
what they want to have replicated to PI.
PI AF templates, elements, their attributes, and PI points are created automatically based on
the information obtained from browsing the OPC UA address space. Data from OPC UA
variables is read through subscriptions (unsolicited reads). This version of the connector
supports the Data Access (DA) and the Historical Access (HA) parts of the OPC UA specification.
The following figure illustrates the initial setup of the connector architecture, and the
components involved in version 2.0. Users are advised to read the "PI Connector
Administration user guide" in Live Library (https://livelibrary.osisoft.com) to understand the
role of PI Data Collection Manager and PI Connector Relay in the 2.0 architecture. The second
step is the actual installation and configuration of PI Data Collection Manager, PI Connector
Relay, and PI Connector for OPC UA. Once these components are installed and configured, PI
Connector for OPC UA is registered to PI Data Collection Manager.
From PI Data Collection Manager, users register PI connectors, select data sources, add OSIsoft
Message Format (OMF) applications, and route data through PI Connector Relays to specific
destinations within the PI AF database. Users can view and monitor data flow in real-time on
the PI Data Collection Manager dashboard. The dashboard also provides functionality to
modify data sources, start and stop connectors, revoke OMF application data ingress, and re-
route data flow to alternative destinations.
See Connector configuration for further details.

PI Connector for OPC UA 2.0.1 User Guide 1

Introduction to PI Connector for OPC UA 2.0

PI Connector for OPC UA data flow

Operational overview
Once configured, the connector performs the following tasks:

• Creates PI AF templates, elements, attributes, and PI points

• Collects data from OPC UA variables through subscriptions
• Reads history from those OPC UA dynamic variables that have historical data

Connection to the OPC UA servers

The X.509-type client and server certificates are exchanged and verified and the connection to
the referenced OPC UA server established. The binary TCP/IP protocol on the specified host
and port is used. The endpoint can have for instance the following syntax:
opc.tcp://OPCServerHost:Port/OpcUa/SimulationServer

Browse or discover the OPC UA address space

PI Data Collection Manager provides the user with an option to initiate discovery by browsing
the OPC UA address space. This discovery procedure must be performed at least once.
Users have the option to specify a set of "Root NodeIDs".
Explicitly naming those hierarchy sub-sections (Root NodeIDs) allows for an initial
constraining of the number of objects the discovery calls bring back. The OPC UA objects that
are discovered are displayed in a hierarchical fashion for further selection.

2 PI Connector for OPC UA 2.0.1 User Guide

 Introduction to PI Connector for OPC UA 2.0

To initiate the discovery in PI Data Collection Manager, navigate to the Data tab on the right
side pane of the Connectors page and click Discover Data Source Contents. To select from the
discovered objects, navigate to the data selection page through the Select Data button.

OPC UA objects and entities selection

Upon successful completion of a discovery, the selection page provides the option to manually
select those OPC UA objects and entities that will be replicated in PI AF and PI Data Archive.
There are two options:
• Marking the discovered OPC UA entities manually
• Specify a selection rule
PI Data Collection Manager implements a logic that allows for building queries graphically. The
query building principle is intended to be intuitive. Use Run Selection Query to experiment
with applying a simple rule on the discovered results, and then verifying what was selected.
Run Selection Query returns only those objects that pass the criteria defined in the rule.
For more information about the data selection, see the "Select data" in Live Library (https://
livelibrary.osisoft.com) section in the PI Connector Administration user guide.

Tag naming
PI Data Collection Manager provides the capability to specify how tags are named, either
automatically or custom, once data has been selected.
For information on how to configure automatic or custom tag naming, refer to the "Configure
tag-naming" in Live Library (https://livelibrary.osisoft.com) section in the PI Connector
Administration user guide.

PI points, PI AF elements, and attributes

PI Connector for OPC UA implements a few significant design changes. Some of them were
already mentioned - the introduction of the PI Data Collection Manager and PI Connector Relay.
The concept of operational modes is yet another important modification. In version 2, you have
the option to operate the connector in four modes - Generic, ISA95, PCS7, and TagsOnly.
Refer to Modes of operation for details on the individual modes.
In all modes but TagsOnly, the connector tries to create the closest replica of the discovered
OPC UA objects in PI System. In cases when it is not possible, such as replicating child OPC UA
variables to child attributes in PI AF, the connector will continue running without creating the
objects.

OPC UA static and dynamic variables and their mapping to PI points and PI AF
elements
OPC UA variables, which have the HasTypeDefinition reference set to PropertyType are
treated as static variables. They are replicated as static attributes on a PI AF element.

PI Connector for OPC UA 2.0.1 User Guide 3

Introduction to PI Connector for OPC UA 2.0

Those OPC UA variables that do not have their reference set to PropertyType are treated as
dynamic variables and are replicated to PI points.
The following screenshot provides an example of the static variable PropertyType referenced
to a server named Auditing:

Example of a static variable reference

Naming conventions
The following naming conventions are applied:
• PI AF element and attribute names are taken from the corresponding OPC UA object's
property DisplayName.
• PI points are named according to the OPC UA variable's property NodeId.
The naming convention that PI Connector for OPC UA applies to PI points complies with the
following pattern:
RegisteredConnectorName.DataSourceName.NodeIdNamespaceIndex.NodeIdIdentif
ier
The delimiter is dot '.'
For example, an OPC UA dynamic variable with a NodeId: ns=5;s=Counter1 created by a
connector which was registered as OPC UA1 produces this PI point name:
OPC UA1.DataSource1.5.Counter1
You have the option to modify the described naming convention for PI point names in two
places:
• Applying a formula that can be entered as the SourceId Pattern found under the
Transformational Rules category of the Advanced Configuration. More additional
information, see Transformational Rules.
• Explicitly re-name the default PI point names on the Tag Naming Worksheet configuration
page of the PI Data Collection Manager.
Moreover, PI points are created with their Eng Units attribute set to the value of an OPC UA
property called EngineeringUnits, their Zero and Span attributes adjusted to the OPC UA
property EURange, and their Descriptor set to the value of the OPC UA property named
Descriptor.
Note:
The referenced OPC UA properties are optional; that means that if they are not specified,
PI points are created with the corresponding attributes having the default values.

4 PI Connector for OPC UA 2.0.1 User Guide

 Introduction to PI Connector for OPC UA 2.0

Caution:
OPC UA servers support more characters than do PI point, PI AF element, and attribute
names. In order to mitigate this discrepancy, PI Connector for OPC UA replaces the
unsupported characters with an underscore. The following characters are replaced: * ' ? ;
{}[]|\`"
The following screenshot illustrates the definition and property values referenced to an Analog
Item named FloatAnalogItem.

Property values example

Compression configuration
When the connector creates a PI point, the point's Compressing attribute is set to Off (or 0).
The other compression attributes (CompDev, CompDevPercent, CompMin, and CompMax) are
set to the server default values.
To specify compression attributes for individual points, use the Point Builder tool in PI System
Management Tools (PI SMT). For more information, see the PI Server topic "Point Builder" in
Live Library (https://livelibrary.osisoft.com).
To specify compression attributes for many points, edit the points in bulk using PI Builder. For
more information, see the PI Server topic "PI Builder" in Live Library (https://
livelibrary.osisoft.com).
For more information about compression attributes, see the PI Server topic "CompDev,
CompDevPercent, CompMax, and CompMin" in Live Library (https://livelibrary.osisoft.com).

Units of Measure (UOM) and PI AF

The connector can detect a value's unit of measure (UOM). The unit's representation in PI AF
depend on the unit representation in the data source. The connector attempts to map the unit
from the data source into a standard unit abbreviation. The PI AF UOM feature enables
automatic unit conversion in client applications.
The UOM field value of the data reference configuration string is a standard unit abbreviation as
defined by the International System of Units or a UOM defined in PI AF. When the unit
representation by the data source is non-standard or not a recognized PI AF UOM, the PI Data
Reference configuration string UOM field is not added to the data reference.
If PI AF does not recognize a unit or the connector cannot map the unit into a standard unit,
you can create a unit of measure in the PI AF UOM database. For more information, see the PI
Server topic "Units of measure in PI AF" in Live Library (https://livelibrary.osisoft.com).

PI Connector for OPC UA 2.0.1 User Guide 5

Introduction to PI Connector for OPC UA 2.0

Conversion of non-ASCII characters for tag names

If the data source contains non-ASCII characters that are used to create new tags in PI Data
Archive, the non-ASCII characters in tag names will be converted to their Unicode hex
representation if necessary. This is because PI Data Archive only directly supports ASCII
characters. For example, a character such as "Π" will be converted to "U+03A0" in a PI Data
Archive tag name. This can be decoded using a Unicode conversion application or online tool.
For more information on which characters are valid in tag names for PI Data Archive, see the
OSIsoft Knowledge Base Article, Can non-English characters be used in tag names, modules
names, module database alias names, and properties names (https://customers.osisoft.com/s/
knowledgearticle?knowledgeArticleUrl=KB00043).

Modes of operation
The four mode options available for PI Connector for OPC UA 2.0 are detailed in the following
sections.

Generic mode
This is the default mode and the closest one to how the PI Connector for OPC UA version 1.x
worked. The most significant difference is that the filtering is no longer based on OPC UA object
types. Users have the option to filter manually, or by using a formula to select the actual OPC
UA objects. Hence the filter file, known from version 1.x of this connector, is no longer needed

ISA95 mode
The connector, when instructed to run in the ISA95 mode, makes a few assumptions about
where to search for templates. The following explains the principle:

ISA95 templates

In the ISA95 mode, every OPC UA object that the connector replicates to PI AF is checked if it
has the DefinedByEquipmentClass reference. If it does, the DisplayName of this reference is
used as the template name for the resulting PI AF element. If there are more
DefinedByEquipmentClass references (as in the screenshot above), the DisplayNames of all
of them are concatenated and the PI AF template name is formed from them. If an object does
not have such references, the connector falls back and checks the HasTypeDefinition

6 PI Connector for OPC UA 2.0.1 User Guide

 Introduction to PI Connector for OPC UA 2.0

reference deriving the PI AF template from that. That means that the logic for generating
template names (for the objects without the DefinedByEquipmentClass reference) is exactly
the same as in the Generic mode.

PCS 7 mode
The PCS 7 mode was included to enable users to run this connector also with Simatic OpenPCS
7 UA servers, for which they previously needed a separate connector - the PI Connector for
Siemens Simatic PCS 7. The main differences compared to the Generic mode are how the PI
AF structure is built, and how the static and dynamic variables are recognized.

The PI AF hierarchy is built by parsing the DisplayName of static variables

The OPC UA server for OpenPCS 7 organizes its underlying entities as a flat list of objects called
process groups. From within the process group names the connector takes a notion of a
hierarchy (delimited strings) and builds the PI AF structure. For example, if a DisplayName of
a static variable is FIC_Feed/PID.BatchID the resulting hierarchy will (among others)
contain the PI AF elements called FIC_Feed and PID.

The rule for recognizing which variable is static and which is dynamic
The OpenPCS 7 variables are divided into two groups: static (constants) and dynamic (real-
time values). Static variables are converted to PI AF attributes and dynamic variables become
PI points. The connector decides if an OpenPCS 7 variable is static or dynamic according to the
following rule:
Static variables are all variables which have a hash '#' character in their DisplayName. For
example: FIC_Feed/PID.BatchID#Op_Level
Variables that do NOT have the '#' character in their DisplayName are treated as dynamic. For
example: FIC_Feed/PID.BatchID
Note:
An exception to this rule is when the ' #Value' pattern is found within the variable name,
such variable is then considered dynamic. For example: Units/Drain/2U303_9/
V3.Permit#Value.

The PI AF templates are derived from the value of a particular OpenPCS 7 variable
The AF templates are taken from the value of the following OpenPCS 7 variable: #blocktype.
See chapter PI structure for OpenPCS 7 data where you can find screenshots showing how the
PI AF hierarchy is built.
Note:
In this version of the connector the Alarms and Conditions (A&C), which are supported in
the PI Connector for Siemens Simatic PCS 7, are NOT implemented!

PI AF structure for OpenPCS 7 data

In the figure below there is an example of an OpenPCS 7 followed by a screenshot showing the
result in PI AF.

PI Connector for OPC UA 2.0.1 User Guide 7

Introduction to PI Connector for OPC UA 2.0

OpenPCS 7 example

In PI AF, the connector replicates the OpenPCS 7 process groups to PI AF elements and the
OpenPCS 7 variables to static and dynamic PI AF attributes. The SIMATIC S7 Protocol Suite
object was considered an entry to the OpenPCS 7 hierarchy.

OpenPCS 7 PI AF hierarchy

Here is an example of individual element names in the PI AF hierarchy:

Pcs7Demo\Distillation\FIC_Feed\PID
These were derived from the individual element names, as in:

8 PI Connector for OPC UA 2.0.1 User Guide

 Introduction to PI Connector for OPC UA 2.0

• Pcs7Demo: The Data source name, specified in the connector's configuration page.
• Distillation: The value of the OpenPCS 7 variable #areaname.
• FIC_Feed\PID: The OpenPCS 7 process group.

TagsOnly mode
In this mode, users have the option to reference a .csv file with a list of NodeIds and several
other optional columns. Only those OPC UA variables, which have their NodeIds listed in the
file, will be subscribed for changes and will consequently forward events to the PI System. This
mode is fundamentally different from all the modes described previously where the connector
initially browses the whole OPC UA address space and users have the option to select objects
that they are interested in. The TagsOnly mode is thus very explicit and along with listing the
NodeIds allows for providing a couple of additional input parameters on a per-NodeId basis.
Note:
In this mode, no PI AF hierarchy is created; nevertheless, the discovery of the OPC UA
server address space (Discover Data Source Contents button in PI Data Collection
Manager) must be initiated. The referenced list of explicit NodeIds, however, makes sure
the discovery process will be efficient.

NodeID parameters

Parameter Required/ Definition and syntax

Optional
NodeId Required The OPC UA variable's NodeId in the following
format:
ns=NamespaceIndex;IdentiferType=identif
ier
SamplingInterval Optional A time in milliseconds, which defines the fastest
rate at which a given OPC UA variable will be
accessed. If not specified the value is taken from
the corresponding input under:
Advanced Configuration -> OPC UA Subscription
Parameters

QueueSize Optional The requested size of the MonitoredItem queue.

If not specified the value is taken from the
corresponding input under:
Advanced Configuration -> OPC UA Subscription
Parameters

PI Connector for OPC UA 2.0.1 User Guide 9

Introduction to PI Connector for OPC UA 2.0

Parameter Required/ Definition and syntax

Optional
MonitoringMode Optional Determines if an OPC UA variable will be active or
inactive. The corresponding OPC UA variable will
be included in a subscription, but it won't produce
OPC UA value event notifications if the
MonitoringMode for the variable is disabled.
MonitoringMode may be set to:
• Disabled: a given variable is subscribed, but
told to not send any OPC UA value event
notifications
• Reporting: a given variable is subscribed and
allowed to send out OPC UA value event
notifications
The default is Reporting.

DataChangeTrigger Optional The type of change that triggers an OPC UA value

event notification:
• Status: the status of a value that triggers the
OPC UA value event notification
• StatusValue: the value itself, or the status
that triggers the OPC UA value event
notification
• StatusValueTimestamp: the (source)
timestamp, or a value, or the status that
triggers an OPC UA value event notification
The default is StatusValue.

Deadband Optional The dead-band. Additional input is specified in the

DeadBandType column. Default is 0.
DeadbandType Optional The DeadbandType can be Absolute, None, or
Percent. The value event is triggered if the
Abs(last value - new value) > DeadBand.
The dead-band type=Percent is only valid for
variables having the EURange defined. The
Percent mode triggers an OPC UA value event
notification of change only if a change is more
than the specified percentage of the value range.
The default is None.

In the .csv file, the only mandatory column is NodeId. The simplest example of this file is
therefore as follows:
NodeId
ns=5;s=Counter1
If a file with the above content is referenced to the connector, it will only replicate data from
the variable having the listed NodeId.
Note:
The order of all optional columns is not important. Any optional column can even be
omitted and the default will be considered.

10 PI Connector for OPC UA 2.0.1 User Guide

 Introduction to PI Connector for OPC UA 2.0

Note:
The TagsOnly mode is also different when compared with the same mode implemented
in PI Connector for OPC UA version 1.x. The main difference is that the CustomStreamId
column is not considered. The reason for it is that users have the option to rename PI
points through the tag naming feature provided with PI Data Collection Manager.

Mapping of PI points data types to OPC UA types

OPC UA data type PI point data type
Boolean Int32
Boolean Digital
HasTypeDefinition: TwoStateDiscreteType Digital Set: OPC UA.TwoState.Id

Byte Int32
DateTime DateTime
Double Float64
Enumeration Int32
ExpandedNodeId String
Float Float32
GUID String
Int16 Int32
Int32 Int32
Int64 Float64
Integer Float64
LocalizedText String
NodeId String
Number Float64
QualifiedName String
SByte Int32
StatusCode Float64
String String
UInt16 Int32
UInt32 Digital
HasTypeDefinition: MultiStateDiscreteType Digital Set: OPC UA.MultiState.Id

UInt64 Float64
UInteger Float64
Uint32 Float64
Variant Based on its actual data type

PI Connector for OPC UA 2.0.1 User Guide 11

Introduction to PI Connector for OPC UA 2.0

Data collection
The connector collects data from OPC UA variables, which are discovered by clicking Discover
Data Source Content in PI Data Collection Manager. The individual snapshots of dynamic and
static variables are received as unsolicited OPC UA subscription notifications.

Historical data collection

Provided the connected OPC UA server implements historical data (HA), the connector
performs automatic history recovery for those OPC UA variables, which have HistoryRead
specified in the access level attribute. History recovery is always done at startup, from the time
when the connector has been recently stopped. During runtime, the history recovery is
automatically triggered when the OPC UA server disconnection was detected.

AF structure for OPC UA hierarchy

Because every OPC UA server implements its own information model, the resulting PI AF
structure will always be different. The rules for building and mapping the OPC UA objects to PI
entities have been described in the Mapping of PI points data types to OPC UA types section.
The following figures provide an example.
OPC UA address space:

Example address space

The corresponding PI AF structure the connector has built:

12 PI Connector for OPC UA 2.0.1 User Guide

 Introduction to PI Connector for OPC UA 2.0

Corresponding PI AF structure

PI Connector for OPC UA 2.0.1 User Guide 13

Introduction to PI Connector for OPC UA 2.0

14 PI Connector for OPC UA 2.0.1 User Guide

Prepare for connector installation
Before installing the connector, complete the following tasks.

Procedure
1. Verify the host meets the software requirements for the connector.
For more information, see Software and hardware requirements for connectors.
2. If you are upgrading from version 1.x, review Upgrade to version 2.x.
3. If the data source has additional requirements for installation, complete those tasks.
4. Configure security for the connector and your network.
For more information, see Connector security.
5. Identify the administration port number.
6. Identify administration group users.

Software and hardware requirements for connectors

Software requirements
The following software is required on the host where the connector is installed:
• Microsoft Windows
◦ 64-bit system
◦ Server class: Windows Server 2012 or later
◦ Client class: Windows 8.1, 10 or later
• Web browser: An HTML5-compliant web browser for access to the administration website
of the connector and PI Data Collection Manager. The following browser is supported in
desktop mode only:
◦ Google Chrome version 44 or later
The following software is also required, but can be installed on other hosts:
• PI System
◦ PI Data Archive version 3.4.380 or later
◦ PI AF Server 2015 (version 2.7.0) or later
• PI Connector Relay version 2.5 or later
• PI Data Collection Manager version 2.5 or later

Hardware requirements
The following hardware is required or recommended:

PI Connector for OPC UA 2.0.1 User Guide 15

Prepare for connector installation

• RAM: 4 GB minimum, 8 GB or more recommended

• Hard drive space: 25 GB or more
• Processor: Dual-core minimum, quad-core or greater recommended

Upgrade to version 2.x

If you are upgrading your connector, follow the installation procedure as described in Install
the connector paying special attention to the following:
Note:
This version of the connector does NOT support a direct upgrade from version 1.x.
If you have a version 1.x of PI Connector for OPC UA installed on your computer and you want
to install version 2.x on the same machine, follow these steps:
1. Copy these two files from the existing installation of the PI Connector for OPC UA ver 1.x to a
safe location:
%PIHOME64%\Connectors\OpcUa\Configuration\Datasource.config.json
and
%PIHOME64%\Connectors\OpcUa\Configuration\PIServers.config.json
2. Manually uninstall version 1.x.
3. Rename the PI AF database that stores the elements and templates created by version 1.x.
The new version will recreate the PI AF structures during the very first start-up.
4. Install and start configuring the new connector.
Note:
The two .json files referenced above contain the Data Source Names and PI Server
destinations, which you may want to preserve.
5. During the configuration, leave markers for Create root element and Prefix points checked;
see "Specify destination settings" in Live Library (https://livelibrary.osisoft.com) in the PI
Connector Administration user guide for additional information.
6. Naming your registered connector "OPC UA" allows you to reuse your existing PI point
names so that the new PI AF structure will look the same as that which was created with
version 1.x. The name you entered will appear as the RegisteredConnectorName part of
the PI point name mentioned in chapter Naming conventions.
Note:
If you chose some other name than OPC UA while registering the connector to PI Data
Collection Manager, then this registered name will be used as the root element in PI
AF, and the connector will create a new set of PI points prefixed with it.
The new features in version 2.x include manual or rule-based selection of the actual OPC UA
objects and variables, and the option of renaming PI points before they get created. Version 2.x
supersedes the filtering based on OPC UA types that was used in version 1.x. Version 2.x does
not offer an automated procedure of translating the filter file used in version 1.x to the new
selection scenario.

16 PI Connector for OPC UA 2.0.1 User Guide

 Prepare for connector installation

Connector security
The following topics describe security procedures to ensure the integrity of your data;
however, some data source protocols are inherently insecure. OSIsoft recommends you review
the security standards for your data source to determine the appropriate security measures
necessary to secure your system.

Sensitive data security

Passwords
Passwords may be used by connectors to access data sources. These passwords are located in
the data source configuration files on the connector and PI Data Collection Manager hosts.

• On the connector host, the data source configuration file Datasource.config.json is

stored in the %PIHOME64%\Connectors\ConnectorName\Configuration folder.
• On the PI Data Collection Manager host, the data source configuration information is stored
in the NodeMap.config.json file in the %PIHOME64%\Data Collection Manager
\DataCollectionManager\Configuration folder.
Note:
The Microsoft Data Protection API (DPAPI) is used to perform encryption for connectors
that encrypt confidential information such as passwords.

Cryptographic keys
Connectors create two X.509 certificates at installation time for each connector application
(connector, PI Connector Relay, and PI Data Collection Manager). The first X.509 certificate is
used to secure an HTTPS connection used for application administration. The second X.509
certificate is used to secure AMQPS communication. The private keys for these certificates are
stored in the Windows Certificate Store.

Security best practices for PI Connector for OPC UA

Adhere to the following security guidelines:

• The OPC UA username, specified in PI Data Collection Manager, must have the Browse and
Read privileges, so that the connector can successfully replicate the underlying OPC UA
variables and objects to the PI System.
• The Windows account under which the Connector service runs has no relevance.
• Because the OPC UA endpoint contains the TCP port number, firewalls can be used for
enabling the communication on the given port number.
Note:
OSIsoft strongly recommends to use the highest available security profile. Employing the
[NONE:NONE:BINARY] profile is not recommended for anything else than testing
purposes.
Additional sources of information:

PI Connector for OPC UA 2.0.1 User Guide 17

Prepare for connector installation

• Vendor manuals for the OPC UA server

• OPC UA specifications from the OPC Foundation website:
◦ Part 2: Security Model (https://opcfoundation.org/developer-tools/specifications-
unified-architecture/part-2-security-model)
◦ Part 13: Aggregates (https://opcfoundation.org/developer-tools/specifications-unified-
architecture/part-13-aggregates)

Firewall configuration
You must properly configure firewalls to support the connector.

Remote administration
The connector process hosts a web service for connector administration. To access the
connector administration pages from a remote host, all firewalls between the remote host
(running a compatible browser) and the connector host must allow the browser to open a
connection to the administration port that is assigned to the connector during installation. For
example, if Windows firewall is enabled on the connector host, Windows firewall needs to
allow incoming connections to the connector administration port from remote hosts that are
permitted to administer the connector.
Access to the connector's web page can be restricted to the local host alone. The firewall for
listening on that port does not have to be open to remote machines. For administering the
connector using PI Data Collection Manager, no listening ports on the connector are required.
This is a more secure way to administer the connector remotely. This is possible because the
connector initiates the connection to PI Data Collection Manager. The connection is required
for users to perform administrative tasks, such as configuring which relay to send data and
data selection.

PI Connector to PI Data Collection Manager security

Communication between the connector and PI Data Collection Manager occurs using Advanced
Message Queuing Protocol (AMQP) over TCP on port 5672. This port is not configurable. The
channel communication is secured by self-signed certificates that are created during
installation. These same certificates are also used for authentication. If any firewalls are in the
network route from the connector to PI Data Collection Manager, all firewalls must be
configured to permit the connector to open connections to TCP port 5672 on the PI Data
Collection Manager host.
Note:
The firewalls can be physical network devices or the Windows firewall on the PI Data
Collection Manager or connector hosts.
When a registration request is submitted from a connector to PI Data Collection Manager, the
connector initiates a security handshake outbound to the PI Data Collection Manager
administration port. (The administration port is selected during installation of PI Data
Collection Manager; the default port is 5460.) During the security handshake, the connector
and PI Data Collection Manager exchange certificates to use for authenticating and encrypting
communication. The security handshake will complete and communication between the
connector and PI Data Collection Manager will occur only if the administrator approves the
registration request in PI Data Collection Manager. Once the request is approved, the connector

18 PI Connector for OPC UA 2.0.1 User Guide

 Prepare for connector installation

can be administered using PI Data Collection Manager. Communication between the connector
and PI Data Collection Manager will now occur exclusively using AMQP over port 5672.
Note:
The administration port (default 5460) on PI Data Collection Manager must remain open
to the connector machine during the security handshake. After the security handshake is
complete, the PI Data Collection Manager administration port can be closed to the
connector. However, the 5672 communication port (AMQP), outbound from the
connector to PI Data Collection Manager, must remain open between the connector and
PI Data Collection Manager to allow them to communicate with each other.

PI Connector to PI Connector Relay security

Communication between a connector and PI Connector Relay occurs using Advanced Message
Queuing Protocol (AMQP) over TCP on port 5671. This port is not configurable. The channel is
secured by self-signed certificates that are created during installation. The same certificates are
also used for authentication. If any firewalls are in the network route from the connector to the
relay, all firewalls must be configured to permit the connector to open connection to TCP port
5671 on the relay host.
Note:
The firewalls can be physical network devices or the Windows firewall on relay or
connector hosts.
When configuring data flow from connector to relay, PI Data Collection Manager initiates a
security handshake between the connector and the relay. During the security handshake, the
connector and relay exchange certificates for authenticating and encrypting that allow data
communication. PI Data Collection Manager exchanges a certificate between the connector and
the relay, then the relay returns the certificate. Secure data communication between the
connector and relay will then occur using AMQP over port 5671.

Create the Windows account for the connector

You must create a Windows account to host the connector. There are two types of accounts:
• Windows domain accounts are the more secure option for hosting the connector. In a
domain environment, a domain controller performs authentication for centralized control.
• Windows workgroups are the less secure option for hosting the connector. In a workgroup
environment, all computers are peers and authentication is performed locally.

Before you start

Determine whether the connector host is part of a Windows domain or workgroup. Computer
domain information can be found in the Control Panel system information, in the Computer
name, domain, and workgroup settings area.

Procedure
• Create either a dedicated domain account, or local account for the connector.
Note:
The account should not be a member of the host's local administrators group.

◦ If the computer is part of a domain, create a dedicated domain account for the connector.

PI Connector for OPC UA 2.0.1 User Guide 19

Prepare for connector installation

You must have domain administrator privileges to create domain accounts.

◦ If the computer is part of a workgroup, create a local account for the connector.
You must have local administrator privileges to create local accounts.

Identify the administration port number

The connector service uses a TCP port to host the administration web service. If you intend to
access the web service from a remote host, all firewalls between the remote host and connector
host must permit a browser on the remote host to open a connection to the web service. For
example, if Windows firewall is enabled on the connector host, configure Windows firewall to
allow access to the configured web service port from approved remote hosts.
Determine an unused TCP port for the web service before installing the connector software.
You are prompted to enter this port number during installation.

Procedure
1. Open a command prompt and enter: netstat -a -n -p TCP | find "LISTENING"
The tool displays only TCP ports that are currently in use.

2. View the last set of numbers in the second column to determine ports that are in use.
For example, the preceding figure shows that ports 80, 135, 445, and so on are in use. The
default port 5460 is available, or you can choose another unused port. Since default and
other well-known ports can be the targets of cyber attacks, choosing a non-default port can
provide an additional defense.

Identify administration group users

To configure and administer the connector, users must belong to the local Windows PI
Connector Administrators group on the computer where the connector is installed.

20 PI Connector for OPC UA 2.0.1 User Guide

 Prepare for connector installation

Procedure
1. Identify all local or domain users that require administrative privileges for the connector.
2. Use Windows tools to add and remove appropriate users.
During installation, you are prompted to add these users. After installation, you can use
Windows administration tools to add or remove users from the PI Connector
Administrators group at any time.
Note:
When selecting users for the PI Connector Administrators group, be aware that
users in this group can locally or remotely stop and start connectors and modify
configurations.

PI Connector for OPC UA 2.0.1 User Guide 21

Prepare for connector installation

22 PI Connector for OPC UA 2.0.1 User Guide

Install the connector
Before you start
Ensure all connector-specific installation requirements are met in order to successfully install
the connector. See Prepare for connector installation.
If you are upgrading from version 1.x, see Upgrade to version 2.x for important information
before installing the connector.
Note:
You must be logged in to a Windows account with administrator privileges.

Procedure
1. Start the connector installation kit.
2. Set the extraction path for the installation files and click OK.
The connector setup wizard opens.
3. Install and configure all required software using the installation wizard.
The setup program installs the prerequisite software and opens the connector installation
wizard to guide you through connector configuration choices.
4. Configure the following items:
◦ Administration port number for hosting the administration web service.
◦ Windows service account information. The installation wizard automatically adds the
connector service account to the PI Connector Administrators group.
◦ Optional: Alternate file path for buffer and other local files.
5. Click Install.
6. Add all local or domain users that require administrative privileges to the PI Connector
Administrators group, and then click Next. Users must belong to this group to configure and
perform administrative tasks for the connector.
7. Click Finish to exit the installer.
If connector installation is not successful, see Troubleshoot installation.

After you finish

Note:
Catalog files are separate downloadable files, and are used for application whitelisting. If
you use whitelisting, install the catalog files associated with your OSIsoft products to
ensure that those products function as intended. Windows catalog files that have been
digitally signed by OSIsoft can be used as a digital signature for 3rd party and other
unsigned components installed by OSIsoft setup kits. This facilitates a trusted way to
verify these components and may be used for whitelisting purposes. For information on
how to use catalog files for whitelisting, refer to the OSIsoft Knowledge Base article:
Whitelisting PI applications based on catalog files (https://customers.osisoft.com/s/
knowledgearticle?knowledgeArticleUrl=KB01975).

PI Connector for OPC UA 2.0.1 User Guide 23

Install the connector

Configure silent installation for connectors

You can install this software with the Windows silent installation feature. Sometimes called an
unattended installation, silent installation requires no user interaction during the setup
process. System administrators with an automated software distribution application can use
silent installation to deploy software automatically to large numbers of corporate computers.
Modify the silent.ini file to configure silent installation. Configuring the silent.ini file
determines items that you would have selected during a normal installation with the connector
installation wizard.

Before you start

See Prepare for connector installation.

Procedure
1. Prepare the silent installation file path and identify the status of supporting software.
a. Run the connector setup kit self-extracting executable file.
The self-extracting window opens. You will only complete the step to extract the
installation files, not actually proceed to install the connector or prerequisites.
b. Enter an extraction path and click OK. The installation files are extracted and the setup
program opens.
c. Cancel the installation.
2. Go to the extraction folder, and open the silent.ini file in a text editor.
3. Modify the COMMANDLINE section for the module for the connector.
See the silent.ini file included in the setup kit for more details about each of the
configurable settings:

◦ Required: SERVICE_ACCOUNT. Set this property to the domain and name of the Windows
account for the connector service.
◦ Required: SERVICE_ACCOUNT_PASSWORD. Set this property to the password for the
Windows account for the connector service.
Note:
The password in the silent.ini file is visible to any user who has read access to
the file. Protect all copies of the file with an access control list that allows read
access to only a white list of users who know the password and denies read access
to all other users. Preferably, remove the file immediately after installation. If long-
term retention is necessary, keep the file on removable media that is stored offline
in a physically secure location.
◦ Optional: USERPORT
◦ Optional: ALTERNATEFILEPATH
4. To run the silent installation, open a command prompt window, change the working
directory to the extraction path, and enter setup.exe -f silent.ini.

24 PI Connector for OPC UA 2.0.1 User Guide

 Install the connector

Change connector installation settings

Caution:
Before changing installation settings, backup or save configuration so that those settings
can be referenced later if necessary.
The following installation settings can be changed from the connector installation wizard
accessed from the Windows Control Panel. Change installation settings for the connector when:

• Reinstalling the connector software

• Replacing missing files from the installation
• Changing the administration port number
• Changing the location of the buffer and data files
• Changing the Windows account for the connector service
Note:
To remove users from the PI Connector Administrators Group, modify the Windows User
Accounts configuration through the Windows Control Panel.

Procedure
1. Open Programs and Features as an administrator from the Windows Control Panel.
2. Select the connector program, and then click Change.
Note:
Changing installation settings stops the connector service.
The connector installation wizard opens.
3. Click Next.
The installation and change options are shown.
4. Click Change to modify the settings.
5. Change installation configurations using the wizard.

Uninstall the connector

You can uninstall the connector with Control Panel or with the .msi file that setup kit
extracted.
Caution:
Before uninstalling the connector, backup or save configuration so that those settings can
be referenced if reinstalling later. Uninstalling the connector will remove all configuration
files in the directory.

Procedure
• Uninstall the connector with one of the following methods:

PI Connector for OPC UA 2.0.1 User Guide 25

Install the connector

◦ From the Windows Control Panel, open Programs and Features, then select the
connector and click Uninstall.
◦ In the extraction folder created by the setup kit, right-click the ConnectorName.msi file
and then click Uninstall.
Note:
The version of the ConnectorName.msi file must be the same as the installed
connector.

Uninstall the connector in silent mode

Use silent mode to uninstall the connector from the command line.

Before you start

Note:
The original ConnectorName.msi file or a copy of the same version must be used for
silent uninstall.

Procedure
1. Open a command prompt window.
2. Change the working directory to the folder containing the ConnectorName.msi file.
3. Enter msiexec -x ConnectorName.msi -qn.

Troubleshoot installation
If installation of the connector is not successful, you can troubleshoot installation problems by
viewing the connector setup log for detailed information.

Procedure
• Locate the connector setup log in %PIHOME%\dat. The connector setup log file is named
SetupConnectorName.log where ConnectorName is the product name of the connector.

26 PI Connector for OPC UA 2.0.1 User Guide

Connector configuration
You can access the administration website of the connector to register PI Data Collection
Manager.

Open the administration website of the connector

Configure and perform configuration tasks for the connector from the administration website
of your PI connector using a supported browser.
See Software and hardware requirements for connectors.

Before you start

The connector service must be running. From the Windows menu, run services.msc to open
the Services window, and then locate and start the connector service.
To access the administration website of the connector from remote computers, configure
Windows firewalls and any other firewalls in the network to permit remote access to the
service port.

Procedure
1. On the computer where the connector is installed, from the Windows menu, click All
Programs > PI System > PI Connector for connector_name Administration .
Note:
If you are using a remote computer, enter the following URL into the browser's
address bar, using the connector's IP or hostname and port:
https://IP_or_hostname:port/ui

2. If your browser does not recognize the security certificate, allow your browser to access the
site.
3. Log in using the account credentials using domain\user_name format.
The account that you log in with must belong to the local Windows PI Connector
Administrators security group.
The administration website of the connector opens to the Overview page.

Register the connector

You must register the connector from the administration website of the connector. Later, an
administrator authorizes the connector using PI Data Collection Manager.

Procedure
1. In the administration website of the connector, click Set Up Connector.
2. Enter the following settings:
◦ Registration Server Address: The address and port number of the PI Data Collection
Manager administration web service, in the format:

PI Connector for OPC UA 2.0.1 User Guide 27

Connector configuration

https://IP_or_hostname:port
The PI Data Collection Manager administrator can provide this address.
◦ Registration Server User Name and Registration Server Password: The user name (in the
format domain\user_name) and password for a user who belongs to the PI Trusted
Installers Windows group on the PI Data Collection Manager host.
◦ Description: A description of the connector. This field is optional.
3. Click Request Registration.
The connector is authorized for data flow using PI Data Collection Manager, which is often
installed on a separate host. A separate user, such as a PI System administrator, typically
authorizes the connector. For more information about PI Data Collection Manager, see the
"PI Connector Administration user guide" in Live Library (https://livelibrary.osisoft.com).

Open PI Data Collection Manager

As described in Introduction to PI Connector for OPC UA, PI Data Collection Manager enables
users to configure and manage multiple PI connectors, OMF applications, and PI Connector
Relay to multiple PI Systems.

Procedure
1. On the computer where the connector is installed, from the Windows menu, click All
Programs > PI System > PI Connector for connector_name Administration .
Note:
If you are using a remote computer, enter the following URL into the browser's
address bar, using the connector's IP or hostname and port:
https://IP_or_hostname:port/ui

2. If your browser does not recognize the security certificate, allow your browser to access the
site.
3. Log in using the account credentials using domain\user_name format.
The account that you log in with must belong to the local Windows PI Connector
Administrators security group.
The administration website of the connector opens to the Overview page.
4. Authorize the connector. For information on how to authorize the connector, see the topic
"Authorize a connector" in Live Library (https://livelibrary.osisoft.com) in the PI Connector
Administration user guide.
5. Click Save.

Add a data source

Add a data source and configure it for data collection using PI Data Collection Manager. For
details, see the "Data collection configuration" in Live Library (https://livelibrary.osisoft.com)
section of the PI Connector Administration user guide.

28 PI Connector for OPC UA 2.0.1 User Guide

 Connector configuration

Procedure
1. Under Connectors, click the status box for the configured connector.
2. In the Details pane, select the Data tab and click Add Data Source.
3. Populate the parameters described in the following sections:
◦ Data source configuration
◦ Advanced configuration
◦ Failover / Redundancy
◦ OPC UA Communication Timeouts
◦ OPC UA Historical Data
◦ OPC UA Subscription Parameters
◦ Transformational Rules
4. Click Save.

Data source configuration settings

Field Description
Name Data source name
Required
Data source description Description of the data source configuration.
Optional
Mapping Type One of the following must be selected: Generic, TagsOnly,
PCS7, ISA95.
Required
Discovery or Server Endpoint URL The endpoint URL of the OPC UA or Discovery server. The URL
format is for example:
Required
opc.tcp://OPCServerHost:Port/OpcUa/
SimulationServer
To discover the endpoints click on Discover Available
Endpoints and then pick the desired endpoint.

User Name User name for accessing the OPC UA server. Default is empty
string.
Optional
Password Password for accessing the OPC UA server. Default is empty
string.
Optional

PI Connector for OPC UA 2.0.1 User Guide 29

Connector configuration

Field Description
Root NodeIds List of comma separated NodeIds of those objects from where
the connector will browse the OPC UA server address space.
Optional
This option allows selecting only subsets of the OPC UA address
space by explicitly listing one or more NodeIds which will be
included into the initial browse. For example:
ns=5;s=85/0:Simulation
In effect, only this node and all its underlying descendants will
be considered.
Default is empty list, which means the whole address space will
be browsed.
Note:
An exception to it is the case when the PCS 7 mode is
selected, then the following string is pre-populated in the
Root NodeId's input:
ns=1;s=f|[ProjectName]::SIMATIC S7 Protocol
Suite
The [ProjectName] shall be replaced with an existing
project name listed under the OpenPCS7 object in the PCS
7 hierarchy. At least one such Root NodeId must be
included.

Advanced configuration
Advanced configuration settings are defined in the following table:
Setting Definition
Incoming Timestamps Specifies whether the incoming timestamps are
taken from the source, from the OPC UA server, or
[ Source ]
from the connector.
PI Store Mode Specifies whether the connector INSERTs or
UPDATEs values. If a PI point already has a value at
[ Update ]
a timestamp, the UPDATE mode modifies it. If not,
the INSERT option creates a new value.
Preferred Locale Specifies the text localization to be used.
[ English - United States ]

Max Browse References to Return Specifies the maximum number of returned

references per node in a Browse() call.
[ 100 ]

Browse Block Size Specifies the maximum number of nodes in a

Browse() call.
[ 1 ]

Read Block Size Specifies the maximum number of nodes in a

Read() call.
[ 1000 ]

[ ] Allow Insecure Credentials Marking this means that passwords can be sent
over insecure connections.

30 PI Connector for OPC UA 2.0.1 User Guide

 Connector configuration

Setting
[x] Take DNS Name and Port from Discovery URL
[ ] Enable Property Subscription
[ ] Enable OPC UA Model Changes
Definition
Marking this causes the connector to use the DNS
name and port from the discovery URL to connect
to an OPC UA server.
Marking this means that the connector will create
subscriptions to those OPC UA objects (their
properties) that are mapped to static PI AF
attributes.
Marking this means that the connector receives
notifications when any new OPC UA object is
added to the address space, as well as when an
object is updated.Consequently, and depending
upon the DCM settings for the 'Future changes to
the data source structure' option, the connector
replicates them to PI and/or PI AF.
Note:
Your OPC UA server must implement the
GeneralChangeModelEventType so that
the connector can react onto these
notifications.

[ ] Override the Reconnection Logic
When the communication link to an OPC UA server
is disconnected, the default reconnection logic
(implemented in the third party component the
connector uses) is activated. In certain scenarios,
however, this logic might not deliver the desired
results. Marking this causes the connector to
initiate its own reconnection logic.
Note:
Consult with OSISoft technical support about
your use scenario before activating this
option.

Failover / Redundancy
Note:
PI Connector for OPC UA 2.0 does NOT support connector level failover.
To enable server redundancy support, your server must support it. Using a third party OPC UA
client, you can find it out by taking a look at the value of the RedundancySupport property,
which must be set to something else than None. This screenshot provides an example of a
server which does not support the redundant scenario.

PI Connector for OPC UA 2.0.1 User Guide 31

Connector configuration

Server redundancy support options

Provided your server runs in a redundant scenario, enable it explicitly on the connector by
marking and populating the entries described in the following table.
Setting Description
[ ] Enable OPC UA Server Redundancy Marking this tells the connector that an OPC UA
server supports and runs in a redundant scenario.
Note:
When marked, the Endpoint URL of a backup
server becomes a mandatory field.

[ ] Backup OPC UA Server Endpoint URL Specifies the Endpoint URL of a backup server.

32 PI Connector for OPC UA 2.0.1 User Guide

 Connector configuration

Setting Description
Failover Transition Delay Specifies the failover transition delay.
[ 60 ] Note:
The connector will fail back to a redundant
OPC UA server provided the indicator
(ServiceLevel) of a current server is
within the interval <2-200> and the specified
time expired.

OPC UA Communication Timeouts

The following table details the settings for communication timeouts:
Settings
Browse [s] [ 60 ]
Connection [s] [ 20 ]
Create Monitored Item [s] [ 60 ]
GetEndpoints [s] [ 20 ]
History Read [s] [ 60 ]
Read [s] [ 20 ]
Session Reconnect Create Subscription
Delay [s] [ 5 ]
Session Reconnect [s] [ 30 ]
Session Reconnect Delay [s] [ 30 ]
Session Request [s] [ 120 ]
Session Watchdog [s] [ 10 ]
Session Watchdog Cycle Time [s] [ 5 ]
Subscription [s] [ 30 ]
Subscription Lifetime [s] [ 600 ]
Subscription Max Keep alive Time [s] [ 10 ]
Description
Timeout of the Browse() call.
Connection timeout.
Timeout of the CreateMonitoredItems() call.
Timeout of the GetEndpoints() call.
Timeout of the Read history() (data) call.
Timeout of the Read() call (data and metadata).
Timeout between successful reconnection and
consequent CreateSubscription() call.
Timeout of the session reconnection.
Maximum time between the reconnect attempts.
Timeout of CreateSession() call.
Maximum time that the watchdog waits for a
response from the server before starting the
reconnection process.
The time between cycles of the watchdog, which
checks the status of the connection with server.
Timeout of CreateSubscription() call.
Server subscription idle time.
Maximum keep alive interval.

OPC UA Historical Data

The following table provides settings and definitions for historical data options:

PI Connector for OPC UA 2.0.1 User Guide 33

Connector configuration
Settings
[x] Enable History Recovery
Read Block Size [10]
Number of Values per Node [ 0 ]
[x] Include variables having historical data only
Historical Data Scan Period [s] [ 60 ]
OPC UA Subscription Parameters
The following table details the settings for subscription parameters options:
Settings
Max Monitored Items per call [ 100 ]
Max Monitored Items per Subscription
[ 1000000 ]
Max Notifications per Publish [ 0 ]
Publishing Interval [ms] [ 1000 ]
Sampling Interval [ms] [ 250 ]
Queue Size [ 4 ]
34 PI Connector for OPC UA 2.0.1 User Guide
Definitions
Marking this initiates the history recovery every
time connector communication to an OPC UA
server is broken and then re-established, and
every time the connector is stopped and restarted.
The history recovery is implemented for those OPC
UA dynamic variables that have a history to
recover.
Specifies the maximum number of variables in the
history Read() call.
Specifies the maximum number of returned events
per variable in the history Read() call.
0 means the server returns the maximum number
of values per node.
Marking this causes the connector to scan those
OPC UA variables that store only historical data;
that is, variables without current values.
Note:
When marked, the Historical Data Scan
Period is used for polling.
Specifies the scan period used for polling variables
with historical data.
Definitions
Specifies the maximum number of variables in a
CreateMonitoredItems() call.
Specifies the maximum number of variables in a
subscription.
Specifies the maximum number of events returned
in a publish response. 0 means the server will send
its maximum number of events.
Specifies how often an OPC UA client (the
connector) requests new data.
Specifies how often an OPC UA server polls its
underlying system for data. The data is then moved
to the MonitoredItem queue. There is a queue for
each variable.
Specifies the size of the OPC UA MonitoredItem
queue. 0 means the server returns the default
queue size for the event notifications. 1 means the
server returns the minimum queue size for the
event notifications.

Transformational Rules
The following table provides detail on settings for transformational rule options:
Settings
SourceId Pattern
[ datasource.ns.identifier ]
Object Separator
[]
Connector configuration
Definitions
This pattern defines a new unique identifier for an OPC UA variable that
is used as a PI Point name. The SourceId Pattern defines a
combination of the following keywords that are dynamically populated
on runtime:
• datasource will be replaced by the name of the data source defined in
the connector
• ns will be replaced by the NameSpaceIndex part of a NodeId of an
OPC UA variable
• identifier will be replaced by the Identifier part of a NodeId of an
OPC UA variable
• path will be replaced by the path to the variable from an OPC UA
hierarchy
Example 1:
Defined SourceId Pattern: datasource.ns.identifier
Data source: TestDS
NodeId: ns=5;s=Boiler1Temperature
Result (PI point name): TestDS.5.Boiler1Temperature
Example 2:
Defined SourceId Pattern: datasource.path
Data source: TestDS
OPC UA hierarchy path: Boilers\Boiler1 Variable DisplayName:
Temperature
Result (PI point name): TestDS.Boilers.Boiler1.Temperature
Note:
When, as in the Example 2, the SourceId Pattern contains just
the path keyword, the resulting PI point name will not contain the
variable NodeId at all. This is useful in cases when the NodeId is
numeric, GUID or even ByteString.
Some OPC UA servers express the hierarchical structure of their
underlying systems in a string form. This delimited string is usually
placed in the DisplayName attribute of an OPC UA variable. If this is
true, the Variable Separator allows for parsing the DisplayName and
building a PI AF hierarchy. When left empty, no parsing of the
DisplayName occurs and the PI AF hierarchy is built out of the OPC UA
hierarchy.
Example:
DisplayName: Factory|Boilers|Boiler1.Temperature
Object Separator: |
Result (AF hierarchy): Factory\Boilers\Boiler1
PI Connector for OPC UA 2.0.1 User Guide 35
Connector configuration

Settings Definitions
Variable Separator Variable Separator is used to identify a variable name in a DisplayName
string.
[]
Note:
See the description of the Object separator.
Example:
DisplayName:
Factory|Boilers|Boiler1.Temperature
Variable Separator: .
Result (AF attribute name): Temperature

[x] Create Area Asset in Marking this enables the creation of a PCS 7 Area asset in PI AF.
AF
Note:
Marking this enables the creation of a PCS 7 Area asset in PI AF.

[x] Create Data Source
Asset in AF
[ ] Enable Deep Browse
[ ] Enable Expanded
NodeId
Marking this enables the creation of a top-most asset in PI AF . It will be
named the same as the Data source name.
Marking this enables creation of a PI AF asset for an OPC UA variable,
provided this variable has a child variable. The default behavior is - the
child OPC UA variable is ignored.
Marking this enables 'Expanded NodeId' instead of 'NodeId'.
Note:
This setting mostly applies to OPC UA wrappers put on top of OPC
DA servers. OSIsoft recommends consulting with OSIsoft technical
support about your use scenario before activating this marker.

[ ] Ignore Some OPC UA servers send this status right after start-up, which causes
Bad_WaitingForInitialDa out of order data in PI. Marking this instructs the connector to ignore
ta Status this status event.
[ ] Enumeration as Marking this maps the OPC UA Enumeration data type and applies it to
Integer an Int32 PI point. The default is - the connector maps the OPC UA
Enumeration data type to a Digital PI point.
[ ] MultiState as Marking this maps the OPC UA MultiState and TwoState types and
Integer applies them to an Int32 PI point. The default is - the connector maps
the OPC UA Enumeration data type to a Digital PI point.
[ ] Variant as String Marking this converts the OPC UA Variant type to a String PI point.
Otherwise, the resulting PI point type reflects the mapping described in
the table in the Introduction chapter of this manual.

Modify data sources

Use PI Data Collection Manager to modify data sources.

36 PI Connector for OPC UA 2.0.1 User Guide

 Connector configuration

Procedure
1. In the Data Sources section, click the data source status box.
2. In the Data Source Details pane, click Edit.
3. Edit the data source settings and click Save.

Discover data source contents

Perform the steps below to automatically discover available data source contents for the
connector. After the discover data source contents process completes, an administrator can
select available assets and value streams using PI Data Collection Manager.

Procedure
1. Under Connectors, click the status box for the configured data source.
2. In the right pane under the Data tab, click Data Source Contents.

Select data
After data discovery is finished, you can specify which of the discovered assets and
measurements to collect and store in the PI System.
For more information about data selection, see the "Select data" in Live Library (https://
livelibrary.osisoft.com) section in the PI Connector Administration user guide.

Start and stop data collection

Once the connector is configured, you can start or stop data collection from PI Data Collection
Manager.

Procedure
1. From the Connectors section, navigate to the Configuration tab.
2. Next to the Edit Settings button, there is a button with three vertical dots. It contains the
options to start and stop the connector.

Verify data collection

For each PI Data Archive server, use PI System Explorer to confirm that the connector is
collecting data.

Before you start

Verify the following items to ensure data collection.

1. Verify the connector service is started.

PI Connector for OPC UA 2.0.1 User Guide 37

Connector configuration

a. From the Windows Start menu, run the services.msc command.

b. In the Services window, verify the connector service status is Started.
2. Verify the connector is running.
a. Open PI Data Collection Manager.
b. In the Overview pane, verify that the Connector Status box shows the status Running
with a green check mark ( ).
c. Click the Connector Status box and verify the available button is Stop Connector.
3. Verify the data source is connected. Under Data Sources, verify that each data source shows
the status Running with a green check mark ( ).

Procedure
1. Open PI System Explorer and click Database.
2. In the Select Database window, select the PI AF database that is configured to receive the
data.
3. Double-click Elements.
4. Navigate to the PI AF element of interest.
5. Click the Attributes tab. The PI AF attributes that are PI data references should have proper
time stamps under the Time Stamp column.

PI Connector Relays
All PI Connector Relay hosts that are configured with the connector are listed in the Relays
column of PI Data Collection Manager.
For information on PI Connector Relay, see the topic "Add a PI Connector Relay" in Live Library
(https://livelibrary.osisoft.com) in the PI Connector Administration user guide.

Message logs
For information on Message logs, see the topic "Message logs" in Live Library (https://
livelibrary.osisoft.com) in the PI Connector Administration user guide.

38 PI Connector for OPC UA 2.0.1 User Guide

Technical support and other resources
For technical assistance, contact OSIsoft Technical Support at +1 510-297-5828 or through the
OSIsoft Customer Portal Contact Us page (https://customers.osisoft.com/s/contactus). The
Contact Us page offers additional contact options for customers outside of the United States.
When you contact OSIsoft Technical Support, be prepared to provide this information:
• Product name, version, and build numbers
• Details about your computer platform (CPU type, operating system, and version number)
• Time that the difficulty started
• Log files at that time
• Details of any environment changes prior to the start of the issue
• Summary of the issue, including any relevant log files during the time the issue occurred
To ask questions of others who use OSIsoft software, join the OSIsoft user community,
PI Square (https://pisquare.osisoft.com). Members of the community can request advice and
share ideas about the PI System. The PI Developers Club space within PI Square offers
resources to help you with the programming and integration of OSIsoft products.

PI Connector for OPC UA 2.0.1 User Guide 39

Technical support and other resources

40 PI Connector for OPC UA 2.0.1 User Guide