OSIsoft Asset Framework (AF)
.NET AGENT
Overview
The OSIsoft Asset Framework (AF) connector enables Seeq to access data from OSIsoft Asset Framework.
Prerequisites
Authentication
Seeq requires read access to data sources. When an AF Attribute is backed by a PI Point, Seeq will use Asset Framework's Data Reference infrastructure to query for the data directly from the appropriate PI Server or PI Collective. As such, it is important that you use Windows integrated security or configure an appropriate PI Trust that will allow this connection.
Connectivity to the AF Server supports two methods of authentication:
Run the Seeq Server and Seeq connectors under a service account with access to the data sources (recommended). This approach is the most secure and is generally known as "WINS" (Windows Integrated Security).
Supply a user name and password to use for authentication in the Additional Configuration section of your datasource or the equivalent OSIsoft AF Connector.json file. If this method is chosen, it is recommended that you use a "service" account with minimum privileges.
Installation
Seeq requires the OSIsoft AF SDK version 2.5 - 3.
First, make sure you can reach your AF Server using OSIsoft's PI System Explorer running on the Seeq Server machine (or the Remote Agent machine if applicable).
Run PI System explorer on the Seeq Server. Then select File > Connections.
In the dialog, you can see your Asset Servers and PI Servers. Add the Asset Server if you don't see it.
Start Seeq after the initial installation.
Open Windows Explorer and navigate to C:\ProgramData\Seeq\data\configuration\link. (Note, if you have moved the data folder, it will be in a different location.)
Using Notepad or any text editor open OSIsoft AF Connector.json.
When Seeq Server starts, the AF Connector identifies the AF Servers to which you have connected with via PI System Explorer, and the servers are added as entries in the file. They are not enabled by default.
If you do not see your server, you'll need to use the PI System Explorer to connect to the desired PI AF Server first. It should get added to the file within a few minutes, or you can restart the server to have it happen immediately.
Edit the Enabled property to true.
Leave the Username and Password set to null if you are authenticating with Windows Integrated Security (in which case, the user account that Seeq Server is running under determines the authentication) or using a PI Trust.
If you are not running under a service account, add a valid user name and password using an external secret file. It is recommended that you use an account dedicated to the Seeq connection with read-only access to PI AF and limited rights on the machine hosting the AF Server.
A domain service account user is recommended; if a domain user is used, you need to have two backslashes (“\”) separating the domain from the user name.
For example:SeeqDomain\\SeeqUser1
The AFServerID field can be changed independently of the Id field, which is useful if you have separate "test" and "production" AF servers and want to switch between them without causing duplication in Seeq. Note that the Element and Attribute IDs in the two servers must be identical (for identical elements/attributes) in order for this strategy to work, which means you would have used AF's import/export facilities appropriately.
Seeq automatically picks up changes to this file when it is saved.
The Seeq PI AF connector uses the supplied username and password to connect to the AF Server. The default AF Database will be indexed by Seeq, and you should be able to see your AF Server from within Seeq Workbench.
Configuration
This is an example configuration template that is displayed in the Additional Configuration box that appears when you click Configure for an existing datasource (or if a new datasource is being created, in the Create new datasource connection modal that appears after clicking Add Datasource) on the Datasources administration page.
{
"IgnoreHiddenAttributes": false,
"IgnoreExcludedAttributes": false,
"NestChildAttributes": false,
"SyncElementReferences": false,
"AFServerID": "f8beab08-6a87-4495-8315-400c849f27b3",
"Username": null,
"Password": null,
"IncrementalIndexingMaxChangedPerDatabase": 10000,
"Databases": [],
"Additional Properties": [
{
"SeeqPropertyName": "Zero",
"PIAttributeName": "Zero"
},
{
"SeeqPropertyName": "Span",
"PIAttributeName": "Span"
}
]
}
Connector Configuration
Connector configuration parameters are not accessible from the Administration console. They may be changed through the API Reference, but this is not straightforward. If possible, when changes are needed to these parameters, make the changes in the JSON config file on the agent host.
| true | Boolean | This field gives Seeq admins fine grained control over server discovery. By default, the configuration is set to |
| Occasionally the error returned by a request to AF indicates a state that has been found not to allow recovery without disconnecting from the AF server and reconnecting. These include | ||
| String | Rarely needed; used in calls to SetApplicationIdentity. |
OSIsoft Asset Framework (AF) Additional Configuration
Property Name | Default Value | Data Type | Description |
---|---|---|---|
| false | Boolean | Causes Hidden AF Attributes to be excluded from indexing. These are indicated by the hidden icon in the icons column in PI System Explorer: See PI System Explorer User Guide for more details. |
| false | Boolean | Causes Excluded AF Attributes to be excluded from Seeq’s indexing, so that no Signal or Scalar is created in Seeq for the Attribute. These Attributes are indicated by the icon next to the Attribute name in PI System Explorer, if Show Excluded Attributes is enabled. See PI System Explorer User Guide for more details. |
| false | Boolean | In AF, it is possible to set an Attribute to be the parent of another Attribute. If |
| false | Boolean | If true, AF Reference Elements and their Attributes will be synced as distinct items in Seeq. If false, Reference Elements and their Attributes will not be synced. |
| String | The ID of the AF Server. In PI System Explorer, this is found by choosing File > Connections…, then choosing Properties from the right-click context menu for the AF server of interest. | |
| String | Usually you will use a service account to run the agent, so this field will be left | |
| String/Secrets File | As noted for | |
| String | Time between the end of one incremental index and the start of the next, assuming no full index is in progress. Should be of the form | |
|
| Integer | There is a limitation of the |
| An empty List | List | This list is populated by the agent automatically upon establishing a connection to the AF server. Each entry in the list will have fields for Only enabled databases will be indexed. |
| null | An AdditionalPropertiesDefinition | For AF Attributes that use the PI Point Data Reference, this property may be used to add PI Point attributes that aren’t included in the Signal’s Item Properties by default. Properties already indexed for PI Point Attributes are exdesc, pointsource, instrumenttag, excmax, compressing, compmax, displaydigits, descriptor, pointtype, and engunits. See below for fields of |
| false | Boolean | This is an option if a full index does not pick up changes that are nevertheless checked in to the AF Server; it should not be needed except under rare circumstances. It has the effect of restarting the agent, which affects other connections. “Request Index” in the datasources administration UI will have no effect for the connection if this setting is enabled; to induce a reindex manually, instead select “Manage” for the connection and set the Next indexing at to a date in the past.(Note that this will affect the timing of future indexes based on the schedule, so the best choice is the date of the previous index.) |
| false | Boolean | In some cases, a combination of AF security and the privileges of the service account running the Seeq agent can cause an AF Element or its parent to be inaccessible, but its Name and Unique ID in AF are still available to the connector during indexing. Exposing these Elements as Assets clutters the list of child items for the AF Database Asset and can be a security concern in some cases. The assets for these Elements can be restored by setting |
|
| String | Whether the system should keep only the last value (option |
AdditionalPropertiesDefinition Configuration
Property Name | Default Value | Data Type | Description |
---|---|---|---|
|
| String | The name as you would like it to appear in the Item Properties for the Signal in Seeq |
|
| String | The name of the PI Point attribute, e.g., |
Known Issues
There are no known issues for the OSIsoft Asset Framework (AF) connector. Please report any issues you find to our support portal.
Troubleshooting
If you are running into issues with connecting to or access data from OSIsoft Asset Framework (AF), view our guide for troubleshooting datasource issues.
Performance considerations
Performance on PI 2017
PI 2017 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 2018.
Seeq recommends upgrading your PI server to PI 2018 if you are using an affected version. One known mitigation is using a Remote Agent to connect Seeq to PI, which can help by reducing the latency between Seeq's agent and the PI server.
Maximum Interpolation for non-PIPoint Attributes
AF Attributes that are not just PI Point references can have poor performance on small requests if the data density is high relative to the Maximum Interpolation. Depending on workloads, it may be a good idea to apply Connector Property Transforms to reduce the Maximum Interpolation from the default 40h
to a smaller value if the sample rate is high for a non-PIPoint Attribute. For example, if the sample rate for an AF Attribute with a Formula Data Reference is 30 samples/minute, you might set the Maximum Interpolation for the Attribute to 1min
.
View our guide on optimizing datasource performance for general guidance.
Constant AF Attributes and Seeq Scalars
By default, Seeq indexes AF Attributes that have a Data Reference as Signals and Attributes that have no Data Reference as Scalars. However, in some cases Attributes defined via Table Lookup, String Builder, or other Data References have no time dependence.
AF Attributes that are marked as Configuration Items are indexed as Scalars, because they are “presumed to be constant” in AF. This is the best way to indicate to Seeq that an Attribute has no time dependence.