OSIsoft PI

.NET AGENT

Overview

The OSIsoft PI connector enables Seeq to access data from the PI Data Archive. This connector does not retrieve data from OSIsoft PI Asset Framework (AF), which can be connected via the OSIsoft Asset Framework (AF) connector.

Prerequisites

The following prerequisites need to be installed and configured on the Seeq Remote Agent machine prior to connecting the PI server(s) to Seeq.

PI System Management Tools

The PI System Management Tools (PISMT) need to be installed on the Seeq Remote Agent machine.

PISMT Installation

Download the PISMT (PISMT_2018_SP2_.exe or later). Follow the instructions in the OSIsoft support portal (A login to OSIsoft support is required).
Double-click the PISMT_2018_SP2_.exe file to start the installation and follow the installation wizard.
1. The wizard will show you the path for files extraction,
2. and the supporting software that is already installed and will be installed in your system.
3. Then, it will ask for the name of the default server. Enter the IP or FQDN of the default Data server. If you need to connect to more than one PI server, you can add connections later (see Configuring additional PI servers)
4. There is an option to change the Installation Directories if needed.
5. A Service Status confirmation dialog pops up:
6. Finally, a confirmation that the installation is complete should appear.

Connecting to PI server(s)

A default data server name is requested during the installation of the PISMT. However, the installer does not check for connectivity to that server. The instructions below allow you to check for connectivity from the Seeq Remote Agent machine to the default server, as well as to add more connections if more than one PI server needs to be connected to Seeq. Once this default server is configured correctly, Seeq will automatically connect to this default server upon startup and index its tags. If more than one server needs to be connected, the connections need to be enabled for the first time in the OSIsoft PI Connector.json file. Step-by-step instructions on how to properly configured your PI servers for Seeq are described below.

Configuring the default server

Open the PISDKUtility software (In Windows desktop: Start > PI System > PISDKUtility)
Navigate to PI SDK > Connections on the left panel.
You should see at least one connection in the central panel for the default server set up during installation. By selecting this connection (but NOT ticking the checkbox) you can adjust the connectivity properties in the right panel (e.g. Network Node, Port Number, or Default User Name)
Tick the checkbox of the connection to test connectivity to the PI server. If the connection is successful you should see a message at the bottom of the window

Configuring additional PI servers

If Seeq needs to connect to other servers (besides the default PI server), then you will have to add those connections in the PI SDK Utility.

In the same PI SDK Utility, go to the Connections tab in the main menu and click on Add Server…
Enter the IP or FQDN for the PI server you want to connect to. Uncheck the Confirm checkbox and hit OK.
Tick the checkbox of the connection to test connectivity to the PI server. If the connection is successful you should see a message at the bottom of the window.
If you have more PI servers to add just repeat steps 1-3.

Connectivity Recommendations

It is recommended that you create an ActiveDirectory domain account that has read-only access to PI (read/write if setting up exporting to PI Data Archive) and the tags that you wish to appear in Seeq. You can run the Seeq Remote Agent as a Windows Service using those credentials, which will dictate the way that Seeq logs in to PI.

There are two ways to authenticate this connector with the PI Server: PI Trust or Windows Integrated Security. For those familiar with PI System administration, this connector's authentication is set just as a PI interface security would be set. Seeq recommends using a PI Trust. While it is possible to use PI WINS, this also results in all Seeq processes running under that user.

OSIsoft PI Trust

PI Trusts are a convenient and Seeq-recommended way to authenticate services that connect to PI. Trusts use various computer network and process name properties to identify "the trust" and assign a PI Identity to the connection. Below is a sample trust, as configured with PI System Management Tools (we removed part of the IP Address for privacy). There is no additional configuration required on the Seeq Server for PI Trusts.

Windows Integrated Security

To authenticate to a PI Server using Windows Integrated Security, identify the domain account that has appropriate access then follow this article to run the Seeq Remote Agent under that account.

PI Collective Member Priority

If you are utilizing a PI Collective with multiple PI Servers as members, it is important to set the collective member priority appropriately in the PI SDK Utility that is installed on the same machine as the Seeq Remote Agent.

Bring up PI SDK Utility on that machine and click File > Connections,
Click on the collective in the list and go to the Connection menu and then Member Setup…
You'll see the list of servers in the collective and you can set the Priority field. 1 is the highest priority, 2 is the next highest, and so on. Use -1 if you never want this machine to connect to a particular server.

Replication of tag security from PI

Seeq supports replicating tag security into Seeq’s integrated security model. Detailed information can be found in here.

Configuration

The configuration of the Seeq OSIsoft PI connector is automatically discovered by Seeq once you have configured the PI server connections in the PI SDK Utility (see Prerequisites). Follow these steps to make sure the configuration discovery process is completed successfully.

Restart the Seeq remote agent
In the machine where the remote agent is installed, open the Seeq Command Prompt (from Windows desktop: Start > Seeq Server> Seeq Command Prompt) and run the command seeq restart (Note that this will restart the remote agent and users will temporarily lose connectivity to any datasources handled by this agent).
Enable all PI connections
Restarting the Seeq remote agent allows Seeq to discover all established PI server connections on the machine and make entries in the OSIsoft PI Connector.json for each connection. However, only the default PI server connection will be enabled in this file. Any additional PI server connections will have disabled entries. To enable these PI connections:

Navigate to the Seeq data folder (typically C:\ProgramData\Seeq) and open the file configuration\link\OSIsoft PI Connector.json with a text editor such as Notepad or Notepad++. When Seeq Server first starts, it looks for all established PI server connections on the machine and makes disabled entries in this file. These entries look similar to this example:
CODE
```
{
  "Version": "Seeq.Link.Connector.PI.Config.PIConnectorConfigV3",
  "Connections": [
    {
      "Name": "52.27.42.233",
      "Id": "a2d1d1e3-9ed1-452e-8fb5-fac4e3049cf1",
      "Enabled": false,
      ...
    },
    {
      "Name": "ec2-54-42-148-162.us-west-2.compute.amazonaws.com",
      "Id": "c29fb683-86c9-4a74-b0af-95b6b9f528fb",
      "Enabled": true,
      ...
    }
  ]
}
```
Change the Enabled field to true and save the file.
Verify all PI servers are connected to Seeq
Open the Seeq UI in a browser. Navigate to the Datasources tab on the Administration page and verify that one datasource for each connected PI server has been added and indexed correctly.

OSIsoft PI Additional Configuration

Selecting Configure for a connected OSIsoft PI datasource in the Datasources tab of the Seeq Administration page displays a modal with several configuration options. This section covers specifically the Additional configuration options.

Below is an example of the configuration in the Additional configuration box of the modal that is displayed when selecting Configure for a connected OSIsoft PI datasource.

Additional configuration template

CODE

{
    "IncrementalIndexingFrequency": "1h",
    "PIServerID": "c29fb683-86c9-4a74-b0af-95b6b9f528fb",
    "Username": null,
    "Password": null,
    "AdditionalProperties": null,
    "SecuritySynchronization": {
        "IdentityMappingsDatasourceClass": "Windows Auth",
        "IdentityMappingsStopRegex": "^(BUILTIN\\\\.*)$",
        "Identities": false,
        "PointSecurity": false,
        "IdentityMappingsDatasourceId": null,
        "PIWorldMapping": null
    },
    "Export": {
        "Enabled": false,
        "MinimumLatency": "15m",
        "DirectiveRefreshFrequency": "15m",
        "AutoCreate": false,
        "AutoUpdate": false,
        "RequireApproval": true,
        "NewOrChanged": [],
        "PointSourceDefault": null,
        "PointSourceMatcher": null,
        "BufferOption": "DoNotBuffer"
    }
}

The following tables provide a description of all the properties in the Additional Configuration

OSIsoft PI Connections Configuration

OSIsoft PI Additional configuration

Property Name	Default Value	Data Type	Description
`IncrementalIndexingFrequency`	`1h`	String	The maximum time taken for new or changed tags from the PI Data Archive to be synced to Seeq.
`PIServerID`	null	String	PI Server ID which is automatically discovered by Seeq. This field can be changed independently of the Id field, which is useful if you have separate "test" and "production" PI Servers and want to switch between them without causing duplication in Seeq. Note that the Point IDs (an integer number, observable in the System section of the PI Server Management Tools' Point Builder section) in the two servers must be identical (for identical tags) in order for this strategy to work. Otherwise duplication and other hazards will ensue.
`UserName`	null	String	NOT RECOMMENDED: This is the username of a user that has access to the database.
`UserPassword`	null	String/SecretFile	NOT RECOMMENDED: This is the password of a user that has access to the database. If used, it is recommended to leverage a Secrets File to store this information.

Indexing additional PI Point attributes

To index additional PI Point attributes for display in the Seeq Workbench "Item Properties" panel, you can specify which attributes to index in the AdditionalProperties field of the Additional configuration.

Property Name	Default Value	Data Type	Description
`AdditionalProperties`	null	Array[PIPointAttributeDefinition]	Index additional PI Point attributes for display in the "Item Properties" panel within Seeq Workbench.

PIPointAttributeDefinition

Property Name	Default Value	Data Type	Description
`SeeqPropertyName`	null	String	User-defined name that will show up in the "Item Properties" panel
`PIAttributeName`	null	String	Name of the PI Point attribute in PI

Putting it all together, the AdditionalProperties field should look similar to this:

CODE

"AdditionalProperties": [
    {
      "SeeqPropertyName": "Zero",
      "PIAttributeName": "Zero"
    },
    {
      "SeeqPropertyName": "Span",
      "PIAttributeName": "Span"
    }
]

After indexing has finished, you will see these properties in the "Item Properties" panel after clicking on a signal's information.

SecuritySynchronization Configuration

Seeq supports replicating tag security into Seeq’s integrated security model. Detailed information for these fields can be found in here

Property Name	Default Value	Data Type	Description
`IdentityMappingsDatasourceClass`	`Windows Auth`	String	The class of the datasource that provides Active Directory groups. Possible values: Windows Auth, LDAP, OAuth 2.0. OAuth 2.0 is supported only when the folowing conditions are all true: the identity provider is Azure, IdentitySynchronizationType is set to AZURE (default) in the configuration file the Azure groups have an attribute named `onPremisesSecurityIdentifier` set to the SID of the group in the on prem AD (this is usually true if the Azure identities are joined with the onPrem Identities from AD - see https://docs.microsoft.com/en-us/azure/active-directory-domain-services/synchronization for more information).
`IdentityMappingsStopRegex`	`^(BUILTIN\\\\.*)$`	String	Regex used to prevent some PI identity mappings from being sent to Seeq. If for example we don't want BUILTIN users / groups and the user / groups starting with word ”AMAZONA” to be sent, the regex will be set to *^(BUILTIN\\\\.\|AMAZONA.)$*
`Identities`	false	Boolean	Whether the PI Identities will be synchronized with Seeq. When true, PI Identities and optionally (see IdentityMappingsDatasourceId key below) mappings with Active Directory groups are synchronized to Seeq before the incremental or full update of signals starts.
`PointSecurity`	false	Boolean	Whether the security strings for PI Points are sent to Seeq during full or incremental indexing of signals. When true, datasecurity and pointsecurity for PIPoints will be sent to Seeq. Note: The fields "Security String" and "Source Security String" may also be transformed using Property Transforms. This makes sense for installations where PI Identities are not synchronized to Seeq and PI Point security will be defined using existing Seeq user groups.
`IdentityMappingsDatasourceId`	null	String	When provided, it must be the ID of the LDAP / "Windows Auth" / "OAuth 2.0" datasource that provides the Active Directory groups that PI Identities are mapped with. The ID may be taken from `LDAP Connector.json` , `Windows Auth Connector.json` or from `OAuth 2.0 Connector.json` from the attribute named Id. When null, PI Connector will not send / manage the mappings of PI Identities with AD groups. This may be useful in configurations where Active Directory is not used and Seeq users will be added to the PI groups manually in Seeq. Please note that this is not the usual configuration. When IdentityMappingsDatasourceClass and IdentityMappingsDatasourceId are provided, the corresponding authentication connector has to be configured to synchronize the relevant groups into Seeq. See Group Synchronization using Windows Authentication Connector or LDAP (Active Directory) Authentication Connector or OpenID Connect
`PIWorldMapping`	null	String	Used when PIWorld PI Identity is not wanted as a group in Seeq and it is intended to use Auth/Seeq/Everyone group (or any other group) instead. Usual value: "Auth/Seeq/Everyone". When not null, PIWorld identity will not be sent to Seeq In PI Point security strings, piworld identity will be replaced with the string specified here

Export Configuration

Export Configuration (see Exporting Signals and Conditions to a Historian )

The Seeq OSIsoft PI connector can export signals or conditions from Seeq and write its values to the OSIsoft PI Data Archive. Detailed information for configuring the following fields can be found in Exporting Signals and Conditions to a Historian

Property Name	Default Value	Data Type	Description
`Enabled`	false	Boolean	If true, enables the datasource export subsystem for this connection.
`MinimumLatency`	`15m`	String	Enforces a global minimum latency for all export directives associated to the connection for which it has been specified.
`DirectiveRefreshFrequency`	`15m`	String	Specifies how quickly new/changed export directives are discovered. It does not affect the rate at which data is exported.
`AutoCreate`	false	Boolean	If true, Seeq will automatically create the signal in the destination system.
`AutoUpdate`	false	Boolean	If true, Seeq will automatically update an already-created signal in the destination system if its metadata in Seeq has changed.
`RequireApproval`	true	Boolean	If true, the `AutoCreate` and `AutoUpdate` features will only take action for signals that have an `Approved` value of `true`
`NewOrChanged`	empty array	Array[Map]	New or changed directives that are automatically discovered are added to this field.
`PointSourceDefault`	null	String	If null, Seeq will use the string “Seeq” for any PI Points created via the auto-create mechanism. If a string is provided, this will be the Point Source used for auto-created PI Points or suggested in the export configuration
`PointSourceMatcher`	null	String	JSON-escaped regular expression that will match all `Point Source` values of PI Points for which export directives are configured. Only set if you need to allow the Point Source to differ from the default.
`BufferOption`	`DoNotBuffer`	String	Buffering option for write operations. Valid values: DoNotBuffer, BufferIfPossible, Buffer. Consult the BufferOption specification for more details.

Known Issues

There are no known issues for the OSIsoft PI connector. Please report any issues you find to our support portal.

Troubleshooting

These are the known possible configuration issues and their solution.

Only one PI server appears in the Seeq Datasources tab

Make sure you follow the steps in the Configuration section above. Most likely, the connection entries in the OSIsoft PI Connector.json have not been enabled.

PI Security in Seeq

All users are seeing all the tags even if PIWorld is disabled

This can happen if PIWorldMapping is enabled (is set to Auth/Seeq/Everyone) and PIWorld is disabled in PI. Even if PIWorld is disabled the security string still contains PIWorld. If PIWorld is mapped to Everyone in Seeq then Everyone will be able to see all the tags.

If you are running into other issues with connecting to or accessing data from OSIsoft PI, view our guide for troubleshooting datasource issues.

Performance considerations

PI Server 2017 R2 has a known issue that can severely restrict network throughput, especially when there is significant latency between Seeq and the PI server. This issue is fixed in PI Server 2018.

Seeq recommends upgrading your PI server to PI 2018 if you are using an affected version. Additionally, view our guide on optimizing datasource performance for general guidance.