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.

CODE

{
      "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.

`ServerDiscoveryEnabled`	true	Boolean	This field gives Seeq admins fine grained control over server discovery. By default, the configuration is set to `true` and changed to `false` after the first round of servers are discovered. If you want the connector to find newly added servers, then temporarily re-enable server discovery by setting this configuration variable to `true` and reverting the change once the new servers have been added to the configuration.
`RestartAgentAfterErrorTimeout`			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 `[-10733] PINET: RPC Resolver is Off-line` and `[-10734] PINET: Broken Connection`. If one of these exceptions is thrown, the connector will attempt to disconnect from and reconnect to the AF server. In some cases, it has been found that the errors will persist even after disconnecting and reconnecting; therefore this timeout causes an agent to restart, which sometimes resolves the issue when disconnecting and reconnecting does not.
`ApplicationIdentity`		String	Rarely needed; used in calls to SetApplicationIdentity.

OSIsoft Asset Framework (AF) Additional Configuration

Property Name	Default Value	Data Type	Description
`IgnoreHiddenAttributes`	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.
`IgnoreExcludedAttributes`	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.
`NestChildAttributes`	false	Boolean	In AF, it is possible to set an Attribute to be the parent of another Attribute. If `NestChildAttributes` is true, the associated child Signal or Scalar will be set as a child item of the parent Attribute’s Signal or Scalar in Seeq; if false, such Attributes will be set as child items of the Asset associated to the Attribute’s AF Element, with a name like `<ElementName>/<ParentAttributeName>/<AttributeName>`, i.e., the AF Path from the parent Element to the Attribute, with forward slashes substituted for the pipe (`\|`) symbols.
`SyncElementReferences`	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.
`AFServerID`		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.
`Username`		String	Usually you will use a service account to run the agent, so this field will be left `null`. However, in case the account running the agent does not have authorization to connect to the AF server, a Windows username can be used in this field instead. The domain may be included, but note that the backslash between domain name and username must be escaped, e.g. `"domain\\username"`
`Password`		String/Secrets File	As noted for `Username`, this should usually be left `null` so that the agent connects to AF using a service account. If this is not possible, the next best option is to use a secrets file; in rare cases, the password for a Windows account may be entered directly in the configuration; note, however, that this is visible in plain text in the Administration console.
`IncrementalIndexingFrequency`		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 `Nu` or `N u`, where `N` is a number and `u` is one of `d`, `h`, `m`, or `s` depending on whether a number of days, hours, minutes or seconds is being specified.
`IncrementalIndexingMaxChangedPerDatabase`	`10000`	Integer	There is a limitation of the `AFDatabase.FindChangedItems` method that requires all changed items since a certain timestamp to be returned in one response all at once, rather than with pagination. Therefore to limit the memory consumption of the agent, this parameter limits the number of changes that can be indexed in a single incremental index. (Full indexes will always sync all items in the AF database.) If you regularly make large changes to your AF databases, you may need to set this value higher, taking into consideration the memory demands on the agent this will entail.
`Databases`	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 `Name`, `ID`, and `Enabled`. Only the Default AF database is enabled by default. In PI System Explorer, if you click on Database in the toolbar below the menu bar, the Default Database can be identified by a small check in the top-right corner of the database icon: Only enabled databases will be indexed.
`Additional Properties`	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 `AdditionalPropertiesDefinition`
`ReinitializeOnFullIndex`	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.)
`SyncOrphanedElements`	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 `SyncOrphanedElements` to `true` in the connector configuration for the AF server in question. A better alternative may be to enable the OSIsoft AF Maintenance Job for the AF server, which cleans up orphaned and deleted Elements.
`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.

AdditionalPropertiesDefinition Configuration

Property Name	Default Value	Data Type	Description
`SeeqPropertyName`	`Zero`	String	The name as you would like it to appear in the Item Properties for the Signal in Seeq
`PIAttributeName`	`Zero`	String	The name of the PI Point attribute, e.g., `compmin`, `creator`, `location2`, `recno`

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.