Asset Framework Data Reference Plugin

The Asset Framework Data Reference Plugin has been deprecated and will no longer be available in Seeq versions released on or after July 2025.
To export Seeq data to the PI historian, refer to Exporting Signals and Conditions to PI.

Introduction

The Seeq AF Data Reference plugin is a licensed component and its use must be enabled by the Seeq Server license file. Contact your Seeq customer success manager to ensure that your license file allows its use.

When accessing Seeq data and calculations from AF, the Data Reference queries Seeq to get the values. (Data is not copied into the PI archive. If you wish to do that, take a look at Export Signals and Conditions to Historian.) Attributes must be configured within PI System Explorer with the details of the signals to be accessed in Seeq. Whenever AF requires data from that attribute, the Data Reference makes the appropriate calls to Seeq to return the data. Attributes generated this way can be displayed in any visualization software that supports AF, such as PI Vision or ProcessBook. Signals and calculated signals are converted to PI-compatible time series. Seeq Conditions are exported as a time series of zeros and ones, where zero represents the absence of a condition and one represents its presence.

Security Considerations

For Seeq SaaS:

Due to security requirements, there is no way to use TLS 1.0 or 1.1 with Seeq SaaS. Therefore any PI Vision servers or other AF clients using the data reference must ensure TLS 1.2 or higher is used. This can be achieved by editing the registry and restarting the application. For PI Vision, this means navigating to the site in IIS and restarting the site via Restart or Stop, then Start, in the right-click context menu. Details of setting registry keys to control security protocols can be found in Microsoft article: https://docs.microsoft.com/en-us/windows-server/security/tls/tls-registry-settings . It is important that TLS 1.0 and TLS 1.1 be explicitly disabled for the client role. After performing the registry edits, the keys for TLS 1.0, 1.1, and 1.2 should appear as shown below. Note that the Enabled DWORD should have its value set to 1 for TLS 1.2 and 0 for TLS 1.0 and 1.1.

For non-SaaS:

the configuration parameter Network/Http/DeprecatedTLS/Enabled must be overridden to true to enable the Data Reference to connect to Seeq from PI Vision. This will allow connections via TLS 1.0 and 1.1, which the nginx proxy does not allow by default. The setting must be changed via the Seeq Command Prompt on the Seeq Server host using the command

seeq config set Network/Http/DeprecatedTLS/Enabled true

Additionally, the Seeq Server must be restarted after this configuration change is made.

If you can only see data from Attributes using the Data Reference when logged into the PI Vision host, or if non-AF-Admin users cannot see the data in PI Vision at all, you may need to add a setting in IIS Manager on the PI Vision host. To add the setting in IIS Manager, navigate to the PI Vision site, then open Application Settings, right click in the table, and choose Add… as shown below. The setting name should be CustomDataReferenceSecurity, and its value should be set to System.

Setting up the Data Reference

The Seeq AF Data Reference is written as an AF plugin, using the OSIsoft AF extensibility interfaces.

There are three ways of installing and managing the Seeq AF Data Reference plugin.

You must perform these instructions for each AF Server that you wish to use the Seeq AF Data Reference plugin with.

Installing via the Seeq AF Connector

The preferred method of installation and management is to allow the OSIsoft AF Connector to handle installation and upgrade.

The Windows account that is used for the Seeq Server Windows Service must have read/write permissions on the top-level “Server” object within the OSIsoft AF Server in order to install and manage plugins.

If running more than one Seeq server (for example, when a development/production pair is in use), please note that the data reference will be registered upon indexing for any AF server for which the RegisterSeeqDataReference configuration parameter is set to true. This could lead to the data reference’s version changing to a version that is incompatible with the server for which it is configured.

As a Seeq Admin, navigate to the Datasources tab on the Administration page.
Locate the AF connector to which you would like to add the AF data reference.\
Set the RegisterSeeqDataReference to true

The AF Connector will attempt to register the Seeq AF Data Reference with that AF Server when you save the JSON file. This method will also ensure that any new version of the Seeq AF Data Reference is installed when Seeq is upgraded.

Troubleshooting

The AF Connector will log the installation/upgrade activity for the Seeq AF Data Reference to the net-link.log file where the AF Connector is running. (See the Viewing Logs section in Datasource troubleshooting for more information on accessing logs.) If there is an error, the following text will appear in the logs:

CODE

Exception encountered registering/unregistering Seeq Data Reference

Installing from the Seeq Command Prompt

If it is not acceptable to run Seeq with the appropriate permissions to register the plugin, the Seeq AF Data Reference can be installed from the Seeq Command Prompt. This should be performed on the machine where the AF Connector runs. This is a one-off installation and will need to be repeated when Seeq Server is upgraded.

You must be logged into the machine as a user with the appropriate permissions, and run the Seeq Command Prompt from the start menu.

You can also right click the Seeq Command Prompt and choose “Run As” to launch the command prompt as the appropriate user.

Execute the following command to perform the installation:

CODE

seeq afdr install

You can uninstall the plugin if necessary with this command:

CODE

seeq afdr uninstall

The above commands will install the Seeq AF Data Reference on the default AF Server. A non-default AF Server may be specified by adding the --pi-system flag (abbreviated to -p):

RESTRUCTUREDTEXT

seeq afdr install -p myAFserver

Manual installation

Should the above methods not be suitable, a manual installation is provided as a fallback. This uses the OSIsoft-supplied regplugin64 utility.

Copy the files from C:\Program Files\Seeq Server\net-link\image\x64\af-data-reference into a folder on the AF Server.
Start a Windows command prompt in that folder with an account that has permission to register a plugin.
Locate the RegPlugIn64.exe executable. (It will normally be found in C:\Program Files\PIPC\AF.)

Execute the command:

CODE

"C:\Program Files\PIPC\AF\RegPlugIn64.exe" /f Seeq.Link.DataReference.AF.dll /owner:Seeq.Link.DataReference.AF.dll Seeq.SDK.dll RestSharp.dll Newtonsoft.Json.dll

If you are installing a new version please remove the old version with the following command before installing the new plugins (step 4).

CODE

"C:\Program Files\PIPC\AF\RegPlugIn64.exe" /u /f Seeq.Link.DataReference.AF.dll Seeq.SDK.dll RestSharp.dll Newtonsoft.Json.dll

After installation

AF applications load plugins on start-up, so they need to be restarted after the installation of the Seeq Data-reference, or after a newer version is installed. Pi-vision and AF Analytics run as services. These services need to be restarted.

For PI Vision, you must restart the associated Internet Information Server (IIS) service.

For AF Analytics, restart the AF Analysis Service:

If plugin verification is enabled on the AF Server at the RequireSignedTrustedProvider level then afdiag /TrustedProviderAdd:"Seeq Corporation" (case sensitive) will need to be executed on the AF server or Failed to load 'Seeq' PlugIn: Attempting to load an assembly with an invalid signature. will be seen when attempting to load data via the plugin.

Configuring the Data Reference

Once the Seeq AF Data Reference has been installed, AF Attributes can be configured using PI System Explorer to access Signals, Calculations, and Conditions from Seeq. The AF Data Reference will appear in the list of available Data References, as shown below:

Once the type of Data Reference is chosen it may be configured. Before any access to Seeq data is possible the Data Reference must have the name, port number, and login details of the Seeq Server configured. This is a one-time activity. The configuration data is stored in the AF Configuration Database and is shared by all Seeq-based AF Attributes on the System. This initial configuration of the Seeq Server details must be carried out by a user with the permissions to write to the AF Configuration Database.

The main configuration dialog box is shown below. It is displayed when a user clicks the "Settings..." button after the "Seeq" Data Reference has been selected in PI System Explorer.

The Seeq Server settings can be configured from "Configure server" on the "Configure" menu as shown below

The server setting form is shown below:

The protocol used to access Seeq (HTTP or HTTPS), the Server Name and the port number should be configured first. Once this is done clicking "Test Server Connection" will attempt to access the server. If it is successful, it will mark the test button with a green tick and enable the rest of the configuration. A failure to connect is marked with a red cross.

The authorization method can then be selected with the "User Directory" dropdown and an appropriate user name and password entered.

Clicking the "Test Seeq Login" will confirm whether this is valid. Again, the results of the test are shown with a tick or a cross.

Once valid details have been entered clicking "Save" will store these details to the AF Configuration Database. These details will then be used by all Seeq AF Attributes configured on the AF server.

All users that will use Seeq Data Reference need to have Read and Read Data permissions to ONLY the Seeq element in the AF Configuration database.

Selecting Seeq Signals and Conditions

Once the connection details have been configured, the Seeq data for the attribute can be selected from the "Seeq Series Search" dialog. The search dialog box works in the same manner as the Seeq data search in the Seeq application. By default, all series and conditions containing the search string are listed. Wildcards and regular expressions are also supported.
The name and type of each Seeq signal/condition, which is accessible to the configured user are listed. As it is possible that the same name may occur multiple times in different Analyses, the name of the analysis and the owning users are also listed, to help disambiguate the names.

The "search for" checkboxes can be used to configure the type of data searched for.
Pressing OK will configure the attribute to display data from the selected entry.

Advanced Settings

Clicking the advanced setting tab, allows the user to configure several other options.
Changes made on this menu only affect the attribute being configured.

PI Trend Format

Setting this option will make trended data appear as it would in PI Tools, with the latest sample extrapolated to "now". As shown below.

The normal Seeq style of trending makes no assumptions about the value of the tag after the latest sample. So, the trend finishes at the last sample.

Unfortunately, this makes Pi tools display a current value of "No Data"
Pi format trending may be set as the default for all attributes, on the configure/option menu.

Additionally, it can be set or cleared for each attribute independently using the advanced setting tab.

Remove changeable data

Seeq is not a Historian, and in some cases it will re-calculate values when the requests are made. An example of this is a Daily average. It will be calculated for the current day from the start of the day until the current time. The result is that the value can change throughout the day.
This can cause problems for AF analytics, which assumes that data values, at a given timestamp, do not change. AF analytic attempts to maintain a cache of data, by constantly asking for new values. These values can then be used in calculations minutes or hours later - but which time they may have changed.
This flag removes any values which may change from the data stream sent AF analytics.

Minimum time between current value requests to Seeq

As mentioned above, AF analytics will constantly ask for new data. This setting limits how often this can happen. Seeq needs to perform calculations to find if new data is available and although these calculations general only take only a few milli-second these times can add up when many request are being made.
By limiting the frequency of the calculations, the load on both Seeq and AF analytics is greatly reduced, at the cost of increasing the time before a change in Seeq is reflected in the corresponding AF attribute.
The default is 10 seconds.

Asset Swapping

The Seeq AF Reference supports allows the Seeq "asset swapping" feature and can be used to implement "element relative" displays in PI tools.
This is achieved in two ways:

Asset swapping when adding an Attribute

When Asset swapping in used in a Seeq workbook, the Seeq Data-Reference has no way of keeping track of which assets are currently in use. In fact, it is common for users to duplicate worksheets and swap them to monitor difference assets in the same workbook. This leads to many different uses of the asset formula in the same workbook.
The Seeq Data-Reference searches by formula name and will always fine the original "un-swapped" version of the formula. To allow the Data-Reference user to take advantage of asset swapping, the user is given the opportunity to perform "asset-swapping" when the attribute is defined in Pi System Explorer.
If an asset-based formula is detected an extra dialog box is displayed.

This displays the asset which the formula uses and allows it to be "swapped" by typing in a replacement asset path. The "Replace Selected Asset" button is enabled when a valid Seeq path has been entered. Once this button is pressed, the asset swap is performed. Should the swap fail the user is informed and allowed to enter an alternative path. To cancel out completely without configuring the attribute press the "X" in the upper right-hand corner.

Asset swapping using Attribute templates

This method assumes that the Seeq AF connector is in use so that each level in the AF hierarchy will correspond to a level in the Seeq asset hierarchy.
If a template attribute is being added, the data reference will check if the data in Seeq is dependent on any asset-relative inputs. If it is, a second dialog form will appear.

This form lists the asset dependences of the Seeq item and allows the user to select one asset to be replaced with the Seeq asset which corresponds to the position of the attribute in the AF hierarchy.
The default assumes that the asset to be used corresponds to the position of the element where the template is instantiated. The data reference understands AF style Substitution parameters (%Element% etc.). The "advanced" button makes the textbox writable, which will then allow the asset path to be typed manually (including Substitution parameters as needed). This allows relative asset paths to be used
When the element is instantiated the substitution, strings are resolved in the context of the element being created and The asset-swapping is then performed the first time the attribute is used to fetch data.

Data Pipe

The AF Data Reference now incorporates a "data pipe". This is a mechanism which ensures that all changes in the signal occurring between calls to the data reference are returned to the caller.
This prevents data loss if the signal changes more frequently than the data reference is called. Applications such as AF Analytics will call the data- reference frequently to examine the "event-pipe" and this causes an API call to Seeq. In the case of AF analytics this can be multiple times per second.
In order to prevent excessive load on the Seeq, server it is possible to limit the frequency of API calls from the data reference.

This is done by using the "Minimum time between current value requests to Seeq" option described above

Using the Seeq Data-Reference with OSIsoft tools

Once the attribute is configured it can be used in any tool which supports AF. Notes on individual applications are given below.

PI Vision

Attributes configured using the Seeq Data-Reference can be used in the same manner as other AF attributes.
See Asset Swapping above, for detail on element relative displays
See PI Trend Format above for details on controlling the formatting of trends
Attributes which are not based on PI tags tend to be slow to update in PI Vision (around one update per minute). This can be overcome by writing the data to a Pi tag, using AF analytics as detailed below.

Datalink (PI Excel Add-In)

Data can be return from Seeq to excel as "interpolated" or "compressed"
The Seeq data reference supports the optional "RecordedValues" data method to allow greater control of values returned at the boundaries of the time-range. This allows the PI "inside", "outside" and "interpolated" interpolation methods in DataLink to be supported.

Known Issues

Seeq conditions are exported as a time series of zeros and ones, where zero represents the absence of a condition and one represents it presence. If the Condition has over-lapping capsules they are merged.
The Seeq Data-Reference has not been tested with PI Web Parts.
If an AF structure containing Seeq Data References is imported into Seeq using the AF connector, it will be somewhat inefficient: Seeq asks AF for the data, and AF calls straight back into Seeq, and Seeq may need to call back into PI for the raw data for the calculation. It will work, but it is less efficient than just using the Seeq calculation directly in Seeq.

Version Compatibility when multiple Seeq servers are in use

If multiple Seeq servers exist in the network (e.g., a dev/prod setup), and both have RegisterAFDataReference set to true in their OSIsoft AF Connector configurations, there can be a version mismatch of the data reference in AF clients. In most cases, this can be resolved by the following process:

Re-register the reference by triggering an index with RegisterAFDataReference set to true for the desired Seeq server.
Stop all AF clients on the machine where the data reference is failing to load (just close PI System Explorer if this is where the issue is).
Delete the folders for any Seeq server versions in the C:\ProgramData\OSIsoft\AF\PlugIns folder, e.g., 53.3.0, 54.0.0. These folders will have a subfolder named 4.0 that will contain a file named Seeq.Link.DataReference.AF.dll as well as a few others.
Restart any AF clients. If the issue is in PI System Explorer, you should just need to reopen it.
Navigate to the Attribute that uses the data reference. When you do so, a folder named with the version number of the Seeq server should appear in the C:\ProgramData\OSIsoft\AF\PlugIns folder again. At this point, the issue should be resolved; if not, contact Seeq support

PI Vision Server using old version of Data Reference

PI Vision’s application pool loads the Seeq AF Data Reference into memory to serve requests, which can keep old versions of the files needed by the Data Reference from being deleted. To solve this, one can use the steps in https://seeq.atlassian.net/wiki/spaces/KB/pages/933725050/Seeq+AF+Data+Reference#Version-Compatibility-when-multiple-Seeq-servers-are-in-use . For step 2, just stop the PIVisionServiceAppPool in the Internet Information Services (IIS) Manager on the host for the PI Vision site:

It should then be possible to manually delete old versions of the data reference files in C:\ProgramData\OSIsoft\AF\PlugIns before restarting the PIVisionServiceAppPool . Note that the Data Reference files will not reappear in the PlugIns folder until an Attribute using the Data Reference is loaded from a PI Vision display, unless another client (e.g., PI System Explorer) is used from the PI Vision host first.