Marcos Vainer Loeff

Announcing the PI Web API Data Reference

Blog Post created by Marcos Vainer Loeff Employee on Jun 26, 2018

Introduction

 

A few years ago, we've announced the public PI Web API endpoint in order to:

 

  • Provide developers access to a PI System who may not be able to access PI otherwise
  • Create code samples against the public endpoint and to host them under OSIsoft organization on GitHub
  • Offer developers a playground to exercise with PI Web API
  • Create a streamlined way to offer datasets in a PI System

 

Although we were able to achieve the goals above, I felt that visualizing the data only through PI Web API is a challenge since common tools like PI System Explorer and PI Vision are not available to work with PI data stored on a remote PI Web API endpoint. Given this scenario, I've developed the PI Web API Data Reference which allows local attributes to access data from remote attributes through PI Web API endpoints. As a result, now I can see PI data from the public PI Web API endpoint within the PI System Explorer.

 

This custom data reference (CDR) was developed on top of the PI Web API client library for .NET Framework and PI AF SDK. The basic idea is to make HTTP requests against PI Web API and convert the responses into PI AF SDK objects which PSE will be able to process.

 

Requirements

 

  • PI Web API 2017 R2+ installed within your domain using Kerberos or Basic Authentication. If you are using an older version, some methods might not work.
  • PI AF 2017 R2+
  • .NET Framework 4.6.2

 

GitHub repository

Please visit the GitHub repository for this project where you can find its source code, download the CDR under the GitHub release section and read about the new features added. There are two folders: src and dist. The src folder has the source code package. If you compile the VS Solution in the Release mode, the binaries will be created on the dist folder.  Due to the settings of the .gitgnore file, this folder is empty.

 

Video to get started:

 

 

 

 

Installation

  • Copy all files from the dist folder to %PIHOME%\PIWebApiDR
  • Register the CDR using the following command (you can also run register_plugin.bat):

 

"%pihome%\AF\regplugin" "OSIsoft.PIDevClub.PIWebApiDR.dll" "OSIsoft.PIDevClub.PIWebApiClient.dll" "Newtonsoft.Json.dll" /own:OSIsoft.PIDevClub.PIWebApiDR.dll /PISystem:PISYSTEMNAME 

 

 

Uninstallation

  • Unregister the CDR using the following command (you can also run unregister_plugin.bat):

 

"%pihome%\AF\regplugin" -u "OSIsoft.PIDevClub.PIWebApiDR.dll" /PISystem:PISYSTEMNAME 

 

  • Delete all files from the %PIHOME%\PIWebApiDR folder.

 

ConfigString and ConfigStringEditor

 

The config string of this CDR has the following structure:RemoteDatabaseId={RemoteDatabaseId};WebId={WebId}

  • RemoteDatabaseId is the ID of the RemoteDatabase which is an AF Element with many attributes with the configuration to connect to a remote PI Web API.
  • WebId is the Web ID 2.0 of the remote AF Attribute.

 

The ConfigStringEditor (the window that is opened when you click on the "Settings..." button on PI System Explorer generally used to edit the attribute config string) does not allow the user to change the ConfigString of the attribute. It is used only to visualize the information. Please use the Remote Database Manager to delete and create databases mapping remote ones.

 

 

 

The remote databases are stored under the "OSIsoft Technology" root element of the Configuration AF database.

 

 

 

Remote Database Manager

The Remote Database Manager should be used to manage the remote database on the system as well as to create local AF databases mapped to remote AF databases through PI Web API. Below you can find a screenshot of this application that comes with the PI Web API Data Reference.

 

 

Visualizing PI data from remote AF databases locally in PSE

On the screenshot below, you can see a PI System Explorer accessing data from the "Universities Mapped" database. This database was created by the Remote Database Manager, mapping the "Universities" AF database from the public PI Web API.

 

 

Visualizing PI data from remote AF databases in PI Vision 3

 

This custom data reference works with PI Vision 3 as long as the following procedure is followed:

  1. On the PI Vision 3 machine, edit the file C:\ProgramData\OSIsoft\Coresight\PIDS_Settings.config  by adding the following key:   <add key="AFDRSetting:PI Web API" value="DisableInputs"/>
  2. Edit the PI Vision 3 web config (C:\Program Files\PIPC\PIVision) by making sure the file attribute of pidsSetting node is defined as:  <pidsSettings file="C:\ProgramData\OSIsoft\Coresight\PIDS_Settings.config" />
  3. Save and restart IIS

 

The procedure above will make sure that PI Vision will read data using the default PI AF SDK methods.

 

Features of the CDR in PI AF SDK

 

When writing our UnitTests, we have create a sample AF database with attributes using the PI Point DR and then created mapped AF database with PI Web API DR using the Remote Database Manager. Each test will get data from the PI Point DR and PI Web API DR and compare the results to make sure they are the same. Below you can find the features implemented on the PI Web API data reference:

  • Asynchronous
  • DataPipe (please refer to PIWebApiEventSource.cs)
  • InterpolatedValue
  • InterpolatedValues
  • InterpolatedValuesAtTimes
  • PlotValues
  • RecordedValue
  • RecordedValues
  • RecordedValuesAtTimes
  • Summary
  • Summaries
  • Bulk calls

 

If you use AFDataPIpes with Attributes with PI Web API Data Reference, the CDR will use PI Web API Channels to get new real-time values under the hood.

 

Troubleshooting

If you are having issues make sure:

  • .NET Framework 4.6.2 is installed on the computer registering the plugin.
  • Run the Remote Database Manager with administrative privileges.
  • Unblock the files after extracting them from the compressed file.

 

 

Disclaimer

 

In case you are using Basic authentication, the username and password will be stored in fixed attributes. Although the password will be encoded, it won't be safe. Every user with read access to the Configuration database will be able to get the password of the remote PI Web API endpoint. For Kerberos authentication, the credentials won't be stored on the AF database.

 

This is not an official product. As described, there are security risks involved. Use it carefully.

 

Conclusion

I hope that the PI Community will benefit a lot from using the library as another tool to share data. Please test yourself and let me know if it works fine. I plan to record a video with some tips to use this great feature.

Outcomes