PI Web API 2023 release notes

PI Web API 2023

1.18.0.572

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 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 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 in this release of the PI Web API.

Enhancements

PI Web API 2023 introduces the following enhancements:

• Bearer authentication is reworked and improved.

  • PI Web API can use access tokens to authenticate the user’s identity. In this release, AVEVA Identity Manager (AIM) server is the only supported identity provider.

  • PI Web API also supports Open ID Connect (OIDC) Authorization Code Flow.

  • PI Web API’s OIDC well-known endpoint is now reworked to retrieve the discovery document from AIM.

• Allow PI Web API administrators to remove a cache instance.

• Indexed Search feature is removed from PI Web API.

Known Issues

This section lists problems and/or enhancements that have been deferred until a future release:

Additional Notes

The following endpoints cannot utilize Bearer authentication in PI Web API because Windows Security is required:

• PUT system/configuration/{key}

• DELETE system/configuration/{key}

• GET system/metrics/requests

• GET system/metrics/environment

• GET system/cacheinstances

• DELETE system/cacheinstance

• GET system/status

• GET analysiscategories/{webId}/security

• GET analyses/{webId}/security

• GET analysistemplates/{webId}/security

• GET assetdatabases/{webId}/security

• GET assetservers/{webId}/security

• GET assetservers/{webId}/security

• GET attributecategories/{webId}/security

• GET elementcategories/{webId}/security

• GET elements/{webId}/security

• GET elementtemplates/{webId}/security

• GET enumerationsets/{webId}/security

• GET eventframes/{webId}/security

• GET notificationcontacttemplates/{webId}/security

• GET notificationrules/{webId}/security

• GET notificationruletemplates/{webId}/security

• GET securityidentities/{webId}/security

• GET securitymappings/{webId}/security

• GET tablecategories/{webId}/security

• GET tables/{webId}/security

System Requirements

Operating Systems

This release is supported on the following operating systems:

• Windows Server 2022

• Windows Server 2019

• Windows Server 2016

Windows 11 (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.

Note: Earlier versions of Windows and non-x64 versions of Windows are not supported.

Server Platforms

Core:

• PI Data Archive 2018 SP3 Patch 3 (3.4.440.477) or later is recommended.

• PI AF Server 2018 SP3 Patch 3 (2.10.9.593) is recommended.

OMF:

• PI Data Archive 2018 SP3 Patch 3 (3.4.440.477) or later is recommended.

• PI AF Server 2018 SP3 Patch 3 (2.10.9.593) is recommended.

Not all features, bug fixes, and performance enhancements may be available with older PI Data Archive or PIAF Servers.

To use the new OIDC/Bearer authentication in PI Web API, PI Data Archive 2023 and PI AF Server 2023 are required and must have OIDC authentication enabled.

Distribution Kit Files

The installer is released as a self-extracting distribution kit that contains:

• Installation files for PI AF Client 2023 (x64), which includes the AF Client installer, and installers for its prerequisites:

  • Microsoft Visual C++ 2022 Redistributable (x86 and x64)

  • PI Network Subsystem 3.5.500.88

  • PI Buffer Subsystem 4.9.0.37

• The PI Web API Windows Installer Database (MSI) file signed by OSIsoft

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.

3. If you plan to enable OIDC/Bearer (Claims-based) authentication, verify that your domain account are in the aaAdministrators group on the AIM server.

Please reference the latest AF server and DA server documents on TLS and certificates requirements for Claims-based authentication.

Installation and Upgrades

The PI Web API installer has a graphical user interface, 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.

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 Web API User Guide.

The PI Web API installer supports silent installations. Please refer to the PI Web API User 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

• AIM registration secret files

The above items may be removed manually if desired.

Security information and guidance

We are committed to releasing secure products. This section is intended to provide relevant security-related information to guide your installation or upgrade decision.

We proactively disclose aggregate information about the number and severity of security vulnerabilities addressed in each release. The tables below provide an overview of security issues addressed and their relative severity based on standard scoring.

There are no security vulnerabilities in this release.

Vulnerability Mitigations in PI Web API v1.18.0 Release

The following vulnerabilities were identified in PI Web API v1.18.0 Release