OSIsoft Asset Framework (AF)

.NET AGENT

Item Type Support

SIGNALS SCALARS ASSETS

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:

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

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

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.
RemapAttributes	false	Boolean	Determines whether Seeq will attempt to update existing Seeq Signals and Scalars indexed from AF when the Element Template, Element Reference, or other metadata changes in a way that modifies the AF Element or Attribute ID but not the AF Path. See RemapAttributes Considerations section for important caveats and considerations.

AdditionalPropertiesDefinition Configuration

RemapAttributes Considerations

As noted above in the table of configuration parameters, the RemapAttributes feature has the power to preserve Seeq Signals and Scalars under circumstances where changes that are transparent to AF users would otherwise cause the associated Seeq items to be archived. This section aims to explain how such changes arise, their effects on Seeq Signals and Scalars, and how RemapAttributes helps to alleviate the Seeq item archiving and replacement that occurs when certain changes are made in AF.

Unique IDs and Element update workflows in AF

Every entity in AF has associated to it a Unique ID, which is used by AF clients and the AF server to identify the entity even when its Name or other aspects change. In PI System Explorer, one can toggle whether the Unique ID of Elements and Attributes are shown in PI System Explorer by right-clicking on the footer of the window and clicking the “Show Unique ID” text that pops up:

When this setting is checked, the Unique ID of any entity in AF will be shown when selected - Elements, Attributes, Event Frames, or even Library entities like Element Templates or Enumeration Sets. This feature can be used to observe whether Element or Attribute IDs are changed whenever making changes in AF, even if the path of the entity is unchanged and may appear otherwise unchanged to a user.

There are some common workflows in AF that cause Element or Attribute Unique IDs to change. One of these is to create a new Element Template and then deploy it throughout the Element tree. This may be accomplished via the Change Template… workflow:

Similarly, one can use the Change Reference Type… workflow to change an Element Reference to an Element (so making the original Element an Element Reference) by checking the Primary Parent checkbox in the Change Reference Type… form. These are both examples of changes one can make in AF that cause Attribute IDs to be modified; however, from a user’s perspective in PI System Explorer or PI Vision, the Attribute appears to be the same.

Why It Matters in Seeq

When RemapAttributes is false (and on earlier versions of Seeq that don’t support the parameter), changes that modify the Element or Attribute ID will cause the associated Seeq Signal or Scalar to become archived and replaced with a new Signal or Scalar, even if the AF Path of the Attribute hasn’t changed. This causes the Seeq users then to have to update their Analyses and calculated items to use the new versions of the Signals and Scalars. For these users, nothing appears to have really changed about these items in Seeq or their precursors in AF, since the path through the Seeq Asset tree and through the AF Element tree is identical to what it was before the Signal or Scalar was archived.

The reason such changes in AF sometimes cause archiving and replacement of Seeq items is that Seeq constructs an identifier called the Data ID using the Element and Attribute Unique IDs instead of the AF Path - thus, changes to the Element or Attribute ID cause Seeq to consider there to be a new item. Seeq combines the Element Unique ID and the Attribute Unique ID as <ElementUniqueID>/<AttributeUniqueID>, e.g., 8b945b00-1524-11e8-945b-025ed0f19b59/9b98a02c-0342-504c-0642-7fdcc7148eb1. The Data ID can be seen in the Advanced section of the Item Properties:

In case of an Attribute synced as a Scalar, the suffix -Scalar is appended to the Data ID, since Seeq items, once created, cannot change Type, and it’s possible that an Attribute may be synced as a Scalar during one index and as a Signal the next, or vice versa. Additionally, since Element Reference Attributes have the same Element and Attribute Unique IDs as those associated to the primary Element, a REF: prefix is used for Assets, Signals, and Scalars synced from Element References and Element Reference Attributes.

How RemapAttributes Can Help

When RemapAttributes is set to true, an additional suffix is added to the Seeq Data ID, which contains the AF Path of the Attribute. For example, 8b945b00-1524-11e8-945b-025ed0f19b59/9b98a02c-0342-504c-0642-7fdcc7148eb1 may become 8b945b00-1524-11e8-945b-025ed0f19b59/9b98a02c-0342-504c-0642-7fdcc7148eb1 [\\ServerAF\Example-AF-Dev\Location F2|Hours]. This allows the connector to incorporate the path into the unique identification of the AF Attribute so that the connector can attempt during indexing to update the Data ID of an existing Seeq Signal or Scalar instead of archiving the current Signal or Scalar and replacing it. This works under the condition that the AF Path is unchanged but the Element or Attribute ID has been updated. It also remains the case that if an AF Attribute’s parent Element ID and its Attribute ID are unchanged but its name or its path changes (due to renames of Elements or Attributes in the path), the associated Signal or Scalar will be preserved across indexes.

It is important to note that this is a best effort and will not work in all circumstances. For example, suppose a Template is duplicated via the New > New Template workflow:

If an Attribute Template is then renamed on a duplicated Template, say Temperature becomes Temperature 1, the AF Path of the Attribute would thus be different, as would the Attribute ID. In this case, the Seeq Temperature Signal or Scalar would be archived and its replacement Signal or Scalar Temperature 1 would take its place. That said, if the Template is then changed again without renaming Temperature 1, the new Signal or Scalar would survive across indexing despite the resulting change in the Attribute ID, since its AF Path would be unaltered.

Another scenario of concern is when the RemapAttributes setting is toggled from false to true or vice versa. While changing the setting from true to false will cause the first index after the change to update the Data IDs of the Signals and Scalars to remove the AF Path suffix, this will not apply to any items that have been archived since the setting was toggled to true. Those Signals and Scalars will not have the AF Path removed from their Data IDs, so if the archived items are later restored while RemapAttributes is still false, new items will be created in their place, since these new items will not have the AF Path appended to their Data IDs and therefore will not be unarchived. In such a scenario, if there are Analyses or calculated items that reference the archived items that have Data IDs containing the AF Path suffix, these will continue to reference the archived items until a user updates the references. This scenario is expected to be rare; if it occurs, a datasource swap may also be used to update the affected Analyses and any workbook-scoped calculated items.

There may be other edge cases where, due to changes in AF, an existing Signal or Scalar is archived unexpectedly and replaced with a new Signal or Scalar. If this occurs, please file a support ticket and reference the RemapAttributes configuration parameter in the description.

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. Alternatively, one can add a category SeeqScalar to AF and apply it to the Attribute to be indexed as a Scalar.

Regardless of the method used, a successful index is necessary to cause a Scalar to be indexed for the Attribute. If there was a Signal synced for the Attribute previously, this Signal will be archived.