Configure PI WebAPI for Vision Library+

This guide explains how to setup and configure PI WebAPI for the use with PI Vision and Vision Library+.

1) Install PI Web API

First, we need an instance of PI Web API. You can either install PI Web API on the PI Vision machine itself, or on another machine.

1a) Configure PI Web API Authentication

Open PI System Explorer and navigate to the AF Database "Configuration", Select "OSIsoft", "PI Web API", "<Your Web API Name>" and "System Configuration". 

Click the Attribute "Authentication Methods" and change it to "Kerberos" and "Basic", in that order:

 

 

 

1b) (optional) Configure PI Web API  CORS

If you install PI Web API on a different machine, configure CORS (Cross Origin Resource Sharing) correctly in the AF Database "Configuration". Select "OSIsoft", "PI Web API", "<Your Web API Name>" and "System Configuration".

Set the following Attributes:

CorsExposedHeaders: "Allow, Content-Enconding, Content-Length,Date,Location"

CorsHeaders: "*"

CorsMethods: "GET,OPTIONS,POST, PUT, PATCH"

CorsOrigins: Comma separated list of your PI Vision server urls (no spaces between urls), e.g. "https://pivisionserver1.com,https://pivisionserver2.com" 

Note: if your PI Vision server is behind a network load balancer, also enter the NLB alias as well as all the server names (e.g.https://NLB-Alias, https://PrimaryHostname, https://SecondaryHostname)

CorsSupportsCredentials: True

DisableWrites: False

EnableCSRFDefense: False

XFrameOptions: <empty>

DebugMode: True

Example WebAPI Configuration that supports CORS:

 

 

Detailed instructions on how to configure CORS can be found here.

If you are having issues with CORS, read these tips on how to configure the CorsOrigins Attribute correctly.

• Check the Origin header in the request,and make sure the value matches with the header specified in the CorsOrigins attribute.
• Make sure the origin is in correct URL format (e.g., "my-internal-site" is not a valid URL).
• Do not include a space between the comma-separated list of origins.
• Do not include a forward slash at the end of the origins URL.
• Example configuration: http://my-internal-site.internal,http://my-internal-site2.internal:8080

To test the PI Web API, open up your browser and go to https://<yourserver>/piwebapi. After that, you should see the following output:

If you receive a dialog prompting you for your login credentials, kerberos delegation was not properly set up. Please go back to step 1.

If you receive a SSL certificate error, go back to the PI Web API Configuration Admin Utility and select a valid SSL certificate.

 

2) Configure Delegation and Permissions

To be able to read and write data via the PI Web API from within PI Vision, you need to have kerberos delegation enabled, so the PI Web API User or Machine can delegate the current user to the PI Server. You can either

Run the PI Web API Using the default service Account (NT SERVICE\piwebapi) and enable trusted delegation for this machine

or

(RECOMMENDED) Run the PI Web API using a domain account (preferably the same as PI Vision) and make sure that:

• The user account is trusted for delegation in Active Directory.

• The user account has Service Principal Names registered for:

  • HTTP/hostname

  • HTTP/fully.qualified.hostname 

• the user account is not marked “sensitive and cannot be delegated” in Active Directory.

Also make sure to have the Buffer Subsystem either disabled or running as the same user as above. 

 

3) Set PI Web API Url in Symbol config

On the PI Vision machine, go to C:\Program Files\PIPC\Scripts\app\edit\symbols\ext and edit the "config.js" file. If you have installed PI Web API on a different machine, enter the url to the PI Web API here. Otherwise, you can leave it the way it is.

4) Test Web API Connection

Drag the any of the symbols from "Symbol Collection Plus" onto the Display.

Then right click it and select "Configure".

In the configuration Pane, scroll down to "PI Web API" and click "Test".

If everything comes back green, the configuration was successful and the symbols will now work properly.

 

Frequently Encountered Problems

I configured everything correctly, but I get the error message "An exception has occured".

 

If you see this error message, head to the "Configuration" AF Database, find your PI Web API Instance in "OSIsoft" > "PI Web API" and set the Attribute "Debug Mode" to "True". If the attribute does not exist, create a new Attribute with that name and set it's DataType to "Boolean".

Then head back to section 4) of this guide and click the "Test" button again or try your symbol, you should then see an appropriate error message.

If you don't know how to fix that error, feel free to contact us at contact@software-athlete.com

 

Requests to the service fail with the response "It may be that the impersonated client user account cannot be delegated to the remote server."

 See section 2) for Configuring Kerberos Delegation.

 

Requests fail with the message "Failed to restore a path <Path\\To\\Attribute> to AFObject with Identity of 'Attribute'

This is mostly a User authentication issue. See section 1a) on how to configure the Authentication Methods properly.

Manual Inputs are not written onto the PI Tag even though no error is displayed when saving.

See if you have the Buffer Subsystem enabled on your PI Web API Server. You can either disable it entirely (recommended) or change the service user to the same as the PI Web API user.

 The symbols show the following error message:

 

This error message indicates an issue with the CORS configuration. Open the developer console and check for CORS errors. Go back to section 1b and configure CORS correctly.