OSIsoft Release Notes

PI Web API 2017 R2 Version 1.10.0

© 2017 OSIsoft, LLC. All rights reserved
Table of Contents

Overview ................................................................................................................... 1
Fixes and Enhancements ........................................................................................ 1
Fixes .................................................................................................................... 1
Enhancements..................................................................................................... 2
Known Issues ........................................................................................................... 4
Setup ......................................................................................................................... 6
Operating Systems .............................................................................................. 6
Server Platforms .................................................................................................. 6
Distribution Kit Files ............................................................................................. 6
Installation and Upgrade ..................................................................................... 6
Uninstalling PI Web API ...................................................................................... 7
Improve PI Web API Performance ...................................................................... 7
Security Information and Guidance ....................................................................... 8
OSIsoft’s Commitment ........................................................................................ 8
Vulnerability Communication ............................................................................... 8
Vulnerability Scoring ............................................................................................ 8
Overview of New Vulnerabilities Found or Fixed ................................................ 8
Documentation Overview ........................................................................................ 8
Technical Support and Resources ......................................................................10
 Overview
The PI Web API is a RESTful service in the Developer Technologies suite, designed to
provide cross-platform web and mobile programmatic interfaces to the PI System. The PI
Web API presently contains basic functionality needed to retrieve and manipulate time series
data from the PI Data Archive, Asset and Event Frame data from the PI Asset Framework,
and to index and search on objects within the PI System.
The PI Web API belongs to the OSIsoft PI Developer Technologies family of products, which
is designed to support the implementation of custom applications on top of the PI System, as
well as the integration of PI System data with other applications and business systems such as
Microsoft Office or SQL Server, Enterprise Resource Planning systems (ERPs), reporting and
analytics platforms, web portals, geospatial and maintenance systems, just to name a few. The
PI Developer Technologies cover a wide range of use cases in various environments,
programming languages, operating systems and infrastructures.

Fixes and Enhancements

Fixes

This section lists items that were resolved or added in this release of PI Web API.
Work Item Description
11553 Admin Utility: Handle whitespace in custom
service accounts
142263 Core Services: Search by attribute will now
handle query tokens which contain control
characters when using the “IN” search operator
144561 Admin Utility: Handles removing trailing
whitespace from usernames
144916 Core Services: PI Web API service running as a
service account will not cause requests from
other service accounts to fail
145902 Core Services: EventFrame SearchByAttribute
can now handle enumeration values with
spaces
146133 Core Services: Batch sub-request header
names are treated case-insensitive
159218 Core Services: GZip encoding is correctly
applied with multiple Accept-Encoding header
values
159672 Core Services: Batch requests with certain
types –
AFAnalysis,
AFAnalysisRule,
AFElement,
AFElementTemplate,

OSIsoft Release Notes Template Version 2.7 Page 1

 AFEventFrame,
AFTimeRule
- produces correct content body
163838 Core Services: Interpolated endpoint returns
resulting values in time-descending order when
end time is earlier than start time
166634 Core Services: Response sent when PI Web
API exhausts retrying requests that throw
exceptions during internal processes
167104 Core Services: Deadlock during AF SDK refresh
resolved
168584 Core Services: Swagger specification for
CreateSearchByAttribute actions correctly
exposes request body parameter
177073 Core Services: Batch requests with no-cache
header returns response
179494 Core Services: Batch Request Containing
Multiple Exclusive Operations will not hang

This section lists items that were resolved in this release of PI Web API Indexed Search.
Work Item Description
142694 Limit the number of queries generated during
matchedfields calculations.
144579 Fixed matchedfields calculation for elements
with a large number of attributes.
160670 Elements with only ReadData permission are
now searchable.
167326 Incremental crawl now picks up changes for
elements based from derived templates

Enhancements

PI Web API 2017 R2 introduces the following enhancements:

 Performance optimizations
o Reduced RPC calls when restoring PIPoints
o Improved search efficiency
o Streamsets results unordered unless requested
o Reduced time to restore multiple WebIDs
o Opt-out of first page of results when POSTing SearchByAttribute
 Verbose logging option in administration utility
 Scalability improvements
 WebID 2.0. See the Features section of the PI Web API User Guide, or the WebID 2.0

OSIsoft Release Notes Page 2

 Topic in the on-line help.
 Expose Reason Code of an AFAttributeTrait
 Allow use of Batch Requests in Read-Only mode
 Mixed security authentication methods in Google Chrome
 Expose Data Server point count license limits
 AF Query based search for Event Frames, Attributes, Elements, and Analyses
 Expose AFAttribute link to enumeration values for TypeQualifier fields of
AFEnumerationSet type
 Sync Time for Interpolated Queries
 Support up to 500 simultaneous unique users
 Support Reason Code “AFAttributeTrait”
 Support for custom headers
 Support for sending periodic empty messages to a Channel if there are no data updates

PI Web API Indexed Search Plug-in introduces the following enhancements:

 Full support of Federal Information Processing Standards (FIPS)
 Support WebID 2.0 (type “Full” only)
 Optimized document load time when specific fields are selected in search query

OSIsoft Release Notes Page 3

 Known Issues
This section lists problems and enhancements that have been deferred until a future release.

Work Item Description

N/A Channel service doesn’t work on Windows Server 2008 R2 or earlier platform.
This is a known issue since .NET implementation of Web Sockets is only
available on Windows 8 or Windows Server 2012 and above. No work item is
assigned to address this issue. OSIsoft recommends upgrading to Windows
Server 2012 R2 or 2016.
N/A Security settings of “Basic” or “Anonymous” prevent crawler execution. There
is a known issue with any security setting other than “Kerberos” creating
problems with the PI Web API Indexed Search crawler from executing.
Workaround is to use “Kerberos” security settings. No work item is assigned to
address this issue.
N/A In a Remote Desktop Session to a Windows Server 2016 machine, the PI
Web API Admin Utility can become unresponsive upon enumerating available
SSL certificates. As a workaround, cause the Remote Desktop Session to lose
focus (such as clicking outside the Remote Desktop Connection window), and
then restore focus to the PI Web API Admin Utility.
182056 Multiple users with the same identity performing event frame searches for
which the target event frames share referenced elements may receive a
“WebException” error response with the message “collection modified;
enumeration operation may not execute”. Data in the PI System are
unaffected. The workaround is to re-execute the search.
179169 When a large Batch request with a deep dependency level is sent, the client
may receive a “WebException” error response with the message “Insufficient
stack to continue executing the program safely. This can happen from having
too many functions on the call stack or function on the stack using too much
stack space.”
26947 PI AF server and database security is not factored into element level security.
When security is calculated, only element security is considered. This is only a
problem if a user is given explicit “DENY-READ” on a PI AF server or
database but has “ALLOW-READ” on an AF element, or if the user is an
Administrator but has no explicit read privileges on an AF element.
42700 Numerous PI Mappings may prevent access controls from being respected. If
several hundred PI Mappings exist for a single PI System, the Indexed Search
service may not be able to calculate the correct access controls. A
straightforward workaround is to map to an Active Directory group rather than
to individual accounts.
53055 Identity mapping changes on a PI System triggers a full crawl of all the
databases on that PI System. If a security mapping on a PI System changes, a
full crawl is triggered on all the databases on that PI System. This behavior
may be disabled by adding a registry entry:
In the InstallationConfig.json file located inside the installation folder, set the
property “AutoCrawlRebuild” value to false.
91225 Error stating, "When getting match info for AF attribute: Index was outside the
bounds of the array" seen when querying in PI Web API Indexed Search and
search index is in finalizing step. Workaround is to resubmit query after index
is finalized.

OSIsoft Release Notes Page 4

 182144 Finalizing phases do not display properly on the PI Web API Indexed Search
Service Administration database page on secondary instance (if using Shared
Index CTP).

OSIsoft Release Notes Page 5

 Setup

Operating Systems

The preferred, supported deployment platforms are Windows Server 2016 or Windows
Server 2012 R2.
Windows Server 2008 R2 and Windows Server 2012 (Full Desktop Installation only) may
also be used; however, use of Windows Server 2008 R2 or Windows Server 2012 is
discouraged, as planned enhancements to PI Web API will require functionality that is only
available in later versions of Windows.
Microsoft’s client operating systems, Windows 10 (64-bit only) may be used in a limited
capacity for development and testing purposes only. Please make sure that two entries
“RegisteredOwner” and “RegisteredOrganization” exist under the registry key
“HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Windows
NT\CurrentVersion”. If not, add those two entries with empty string values.
Earlier versions of Windows and non-x64 versions of Windows are not supported.

Server Platforms

 PI Data Archive 3.4.380 (released in 2009) or later. PI Data Archive 2012

(v3.4.390) or later is recommended.
 PI Asset Framework 2017 R2 (v2.9.5) or later.
Not all features, bug fixes and performance enhancements may be available with older PI
Data Archive or PI AF servers.

Distribution Kit Files

PI Web API is installed via the PI AF Services distribution kit. See PI AF 2017 R2 (v2.9.5)
Release Notes for details on Distribution Kit Files.

Installation and Upgrade

Before You Install

1. Verify that the system you plan to use is running a supported operating system.
2. Verify that you can run the installer as an Administrator.

Installation and Upgrades

PI Web API is installed via the PI AF Services Integrated Install kit, which allows you to
perform an installation or upgrade of PI Web API. At the end of an installation or upgrade,
the PI Web API Admin Utility is automatically launched. You need to go through all the
steps in the PI Web API Admin Utility to complete the installation or upgrade. Detailed
information and a walk-through of installation is available in the PI AF Services Installation
and Upgrade Guide.

OSIsoft Release Notes Page 6

 The PI Web API installer supports silent installations. Please refer to the PI AF Services
Installation and Upgrade Guide for detailed information.

Uninstalling PI Web API

Remove the product using Uninstall a program in the Windows Control Panel, or
alternatively, re-run the Installation Kit and follow the prompts to remove the product.
Uninstalling the product will not remove:
 Any SSL certificates that were created during the installation process
 The binding of the selected SSL certificate to the port used by PI Web
API in the Windows HTTP service’s configuration
 The URL reservation for PI Web API in the Windows Kernel routing table
 The locally stored indexes for Indexed Search functionality
The above items may be removed manually if desired.

Improve PI Web API Performance

On servers with multiple processors, you can improve performance and achieve higher
throughput in PI Web API by setting .NET common language runtime to Server garbage
collection.

Procedure
1. From the PI Web API installation folder, open the PI Web API configuration file,
OSIsoft.REST.Host.exe.config. Typically, the PI Web API installation folder is
C:\Program Files\PIPC\WebAPI.
2. Edit the runtime element to include the child element gcServer with the enabled attribute
set to true, as shown in the following example.
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<runtime>
<gcServer enabled="true"/>
<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
…
3. Restart the PI Web API service:
a. Open the Services administrative tool in Windows.
b. From the Services list, right-click PI Web API, and click Restart.

OSIsoft Release Notes Page 7

 Security Information and Guidance

OSIsoft’s Commitment

Because the PI System often serves as a barrier protecting control systems and mission-
critical infrastructure assets, OSIsoft is committed to (1) delivering a high-quality product
and (2) communicating clearly what security issues have been addressed. This release of
PI Web API is the highest-quality and most secure version of the PI Web API released to
date. OSIsoft’s commitment to improving the PI System is ongoing, and each future
version should raise the quality and security bar even further.

Vulnerability Communication

The practice of publicly disclosing internally discovered vulnerabilities is consistent

with the Common Industrial Control System Vulnerability Disclosure Framework
developed by the Industrial Control Systems Joint Working Group (ICSJWG). Despite
the increased risk posed by greater transparency, OSIsoft is sharing this information to
help you make an informed decision about when to upgrade to ensure your PI System
has the best available protection.
For more information, refer to OSIsoft’s Ethical Disclosure policy:
https://techsupport.osisoft.com/Troubleshooting/Ethical-Disclosure-Policy.

Vulnerability Scoring

OSIsoft has selected the Common Vulnerability Scoring System (CVSS) to quantify
the severity of security vulnerabilities for disclosure. To calculate the CVSS scores,
OSIsoft uses the National Vulnerability Database (NVD) calculator maintained by the
National Institute of Standards and Technology (NIST). OSIsoft uses High, Medium
and Low categories to aggregate the CVSS Base scores. This removes some of the
opinion related errors of CVSS scoring. As noted in the CVSS specification, Base
score range from 0 for the lowest severity to 10 for the highest severity.

Overview of New Vulnerabilities Found or Fixed

For this release of the PI Web API, (1) security vulnerability has been identified and fixed.
Based on the CVSS scoring system this issue has been categorized as a Medium (4.0 –
6.9). This issue was self-identified as part of OSIsoft’s Security Development Lifecycle
(SDL) process. This medium-level security issue mitigates the possibility of a Cross-site
Scripting (XSS) attack.

Documentation Overview
These release notes comprise a part of the following documentation set that supports PI Web
API:

OSIsoft Release Notes Page 8

 PI Web API 2017 R2 Programmer Reference: This reference is included in the product. It
is an online API reference meant for developers who wish to program against the services
provided in the product. It is accessible as HTML from the link
https://servername/piwebapi/help, where servername is the hostname of the
server on which this product has been installed.
PI Web API 2017 R2 User Guide: This user guide provides information relevant to the
configuration, settings, and administration of the product, and contains steps and helpful
information for resolving problems with the product.
PI Square and PI Developers Club: The OSIsoft PI Square Community website has free
resources to help you with the programming and integration of OSIsoft products. Additional
benefits are available on a paid subscription basis to members of PI Developers Club.
Additional information about the PI Developer Platform, PI Data Archive, PI Asset
Framework, and other topics of interest can be found in respective books available on the
OSIsoft Technical Support and Resources Web site.

OSIsoft Release Notes Page 9

 Technical Support and Resources
For technical assistance, contact OSIsoft Technical Support at +1 510-297-5828 or
techsupport@osisoft.com. The OSIsoft Technical Support website offers additional contact
options for customers outside of the United States.
When you contact OSIsoft Technical Support, be prepared to provide this information:
 Product name, version, and build numbers
 Computer platform (CPU type, operating system, and version number)
 Time that the difficulty started
 Log files at that time
 Details of any environment changes prior to the start of the issue
 Summary of the issue, including any relevant log files during the time the issue occurred

The PI Square community has resources to help you with your technical questions. PI
Developers Club program offers specific services to developers and system integrators.

OSIsoft Release Notes Page 10

 OSIsoft, LLC
1600 Alvarado Street
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web: http://www.osisoft.com

PI Web API
© 2013-2017 by OSIsoft, LLC. All rights reserved.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or
by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission
of OSIsoft, LLC.

OSIsoft, the OSIsoft logo and logotype, Managed PI, OSIsoft Advanced Services, OSIsoft Cloud Services, OSIsoft Connected
Services, PI ACE, PI Advanced Computing Engine, PI AF SDK, PI API, PI Asset Framework, PI Audit Viewer, PI Builder, PI
Cloud Connect, PI Connectors, PI Data Archive, PI DataLink, PI DataLink Server, PI Developers Club, PI Integrator for
Business Analytics, PI Interfaces, PI JDBC Driver, PI Manual Logger, PI Notifications, PI ODBC, PI OLEDB Enterprise, PI OLEDB
Provider, PI OPC DA Server, PI OPC HDA Server, PI ProcessBook, PI SDK, PI Server, PI Square, PI System, PI System Access, PI
Vision, PI Visualization Suite, PI Web API, PI WebParts, PI Web Services, RLINK and RtReports are all trademarks of OSIsoft,
LLC.

All other trademarks or trade names used herein are the property of their respective owners.

U.S. GOVERNMENT RIGHTS

Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement
and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC.
Version: 1.10.0
Published: 12/20/2017

OSIsoft Release Notes Page 11