Jerome Lefebvre

General guidance when updating a manual data entry custom symbol for PI Vision 2020

Blog Post created by Jerome Lefebvre on Oct 23, 2020

PI Vision Extensibility (mainly custom symbols) is a regular feature of PI Vision since PI Vision 2019 and one of the most commonly implemented custom symbols is for manual data entry. Typically this will use PI Web API as the go-between the browsers and the PI Server.

 

Below are a few notes to help you how to migrate your symbol to PI Vision 2020. While manual data entry is not on the current PI Vision roadmap, please continue to show your interest by voting below if you believe this should be offered as a standard symbol in PI Vision https://feedback.osisoft.com/forums/320517-pi-vision/suggestions/13698603-manually-enter-data-for-attribute-tag

 

There have been a few samples of manual data entry posted to PI Square over the years and reimplemented many times a customer sites. Thus I will be *not* be updating those symbols, simply give some general guidance on updating a symbol you may already be using.

 

There are a few changes to PI Vision 2020 that can impact an implementation of manual data entry custom symbol using PI Web API.

As this is dealing with custom code this list cannot be exhaustive and you may be impacted by some or more of these issues.

 

# PI Web API is no longer part of the PI Vision install kit

Upgrading PI Vision 2020 will let you know that PI Web API is no longer used as part of PI Vision, but it will remain installed.

If you are doing a new installation of PI Vision 2020, you may need to install PI Web API separately if it is not already available. PI Web API is now a component of the PI Server, thus you will be able to download it from the customer portal.

**Warning: while usage of PI Web API within a PI Vision custom symbol is allowed, usage of PI Web API core services outside of PI Vision still requires a PSA license**

 

# Security

PI Vision 2020 has brought in tighter security requirements to prevent certain types of attacks. The PI Vision extensibility documentation has been updated to reflect these changes for how to configure your PI Vision 2020 server:  https://github.com/osisoft/OSI-Samples-PI-System/blob/master/PI-Vision-Extensibility/docs/PI%20Vision%20Extensibility%20Guide.md#content-security-policy . This not only impacts using PI Web API but also embedding an external dashboard like Power BI into PI Vision 2020 via a custom symbol.

 

# Creating a path that can be used in PI Web API

To access a resource in PI Web API, you can search for it (https://techsupport.osisoft.com/Documentation/PI-Web-API/help/topics/search-query-syntax.html), use a method like GetByPath (https://techsupport.osisoft.com/Documentation/PI-Web-API/help/controllers/attribute/actions/getbypath.html) or create a WebID (https://pisquare.osisoft.com/videos/2430-using-pi-webid-20-in-pi-web-api)

 

These techniques can be impacted if you are using

scope.symbol.DataSources

as part of your query. This is due to the fact the included paths have been made more robust to changes in the AF structure.

 

This can be resolved by instead using the label property in the newData object, this label will be periodically made available to your onDataUpdate method https://github.com/osisoft/OSI-Samples-PI-System/blob/master/PI-Vision-Extensibility/docs/PI%20Vision%20Extensibility%20Guide.md#data-shapes

 

The changes to DataSources are not fully yet documented, so for now, the most straightforward way is to remove them is to simply split the string using the two question marks as delimiters.

 

I did post an alternative way to deal with them using PV.Utils, but PV.Utils not documented and probably falls outside of the extensibility framework. To understand what is supported please see:  OSI-Samples-PI-System/PI Vision Extensibility Guide.md at master · osisoft/OSI-Samples-PI-System · GitHub

To see a method which may fail outside the regular guidelines, you may also refer to this:

https://pisquare.osisoft.com/people/jlefebvre/blog/2020/10/20/dealing-with-paths-in-pi-vision-2020-extensibility

 

# Accessing the PI Web API Base URL

As PI Web API was removed from PI Vision, PI Vision no longer keeps track of if or where a PI Web API instance is installed.

 

Changes to accessing PI Web API host base URL from PI Vision are documented here: https://customers.osisoft.com/s/knowledgearticle?knowledgeArticleUrl=000031645

This change will require that the host base URL be made available via a configuration or hardcoded in the symbol directly.

 

I hope these tips will help you with upgrading your symbol for PI Vision 2020!

Outcomes