Skip to main content
Skip table of contents

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

PISMT Installation

  1. Download the PISMT (PISMT_2018_SP2_.exe or later). Follow the instructions in the OSIsoft support portal (A login to OSIsoft support is required).

  2. 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

Configuring the default server

  1. Open the PISDKUtility software (In Windows desktop: Start > PI System > PISDKUtility)

  2. Navigate to PI SDK > Connections on the left panel.

  3. 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)

  4. 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

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.

  1. In the same PI SDK Utility, go to the Connections tab in the main menu and click on Add Server…

  2. Enter the IP or FQDN for the PI server you want to connect to. Uncheck the Confirm checkbox and hit OK.

  3. 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.

  4. 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

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

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

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.

  1. Bring up PI SDK Utility on that machine and click File > Connections,

  2. Click on the collective in the list and go to the Connection menu and then Member Setup…

  3. 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.

  1. 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).

  2. 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.

  3. 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 Configurable Options

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 options that are unique to the OSIsoft PI Connection.

image-20240906-234822.png

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

OSIsoft PI Connections Configuration

OSIsoft PI Configuration Options

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.

Configurable behavior for multivalued samples

Additional Configuration > Configurable behavior for multivalued samples

Seeq’s behavior when it encounters a Multivalued Sample in PI can be configured in the “Additional configuration” section of the Configuration modal. To change this, the Property Name and Value must be added as a new field at the top level of the Additional configuration’s JSON. Please note that this should only be configured on the advice of Seeq Support.

Property Name

Default Value

Data Type

Description

MultivaluedSamplesBehavior

Keep Last

String

Whether the system should keep only the last value (option Keep Last) or should stagger the values (option Stagger) when the data source returns multiple values at a given timestamp.

Indexing additional PI Point attributes

Additional Configuration > 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

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:

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,

  1. PIWorld identity will not be sent to Seeq

  2. 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

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.

Encoding of strings

String-valued samples appear incorrectly in Seeq

Because PI stores strings as raw bits without an attached encoding, in rare cases a PI interface may write values to PI that are not parsed correctly by the AF Client of the machine hosting the Seeq Remote Agent. For example, you may see the string ƒnƒ“ƒo�[ƒK�[ when you expect to see ハンバーガー. This is because the string was written to PI in the Shift JIS encoding, but the remote agent host has its system locale set to English (United States) or similar, so that the bits of the string are decoded with Windows-1252 or similar instead of the proper Shift JIS. To correct this, you must change the system locale to the appropriate locale to interpret the bits of the PI Point value correctly. The setting is found in the Region window of the Settings or Control Panel. You must switch to the Administrative tab and and choose “Change system locale…”, as shown here:

image-20240910-143941.png

After selecting the correct locale, you must also uncheck the checkbox for “Beta: Use Unicode UTF-8 for worldwide language support”:

image-20240910-144105.png

Finally, after making the change, you must reboot the remote agent host machine. Upon restarting, the strings will be correct for newly-queried data - if an item has cache enabled, you may need to clear cached values to cause Seeq to make requests to the PI server for previously-queried data instead of using the Seeq cache.

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.