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
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.
The wizard will show you the path for files extraction,
and the supporting software that is already installed and will be installed in your system.
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)
There is an option to change the Installation Directories if needed.
A Service Status confirmation dialog pops up:
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
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
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
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.
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:
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 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.
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:
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.
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:
After selecting the correct locale, you must also uncheck the checkbox for “Beta: Use Unicode UTF-8 for worldwide language support”:
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.