Changelog

Items listed in bold are considered potentially breaking changes from the previous released version. Potentially breaking changes include:

• Changes to the structure of returned objects
  • Addition/removal of properties or links
  • Changes to the structure of composed types (e.g. collections)
• Status code changes
• Changes to default parameter values

We make a special effort not to remove properties or links, change the structure of composed types, change the class of status codes (e.g. 200 class to 400 class), or change default parameter values.

Clients should be prepared to handle changes to status codes within the same class, especially the 400 and 500 classes, and to handle the addition of properties and links to response objects.

PI Web API 2023

New Features:

• 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.

• Allow PI Web API Administrators to remove a cache instance via the Remove Cache Instance.

• PI Web API's OIDC well-known endpoint is now reworked to retrieve the discovery document from AIM (Aveva Identity Manager)

Data model changes:

• Change the property name from 'User' to 'UserName' on objects of cache instance
• Change the property name from 'Sid' to 'UserId' on objects of cache instance
• Expose 'IsWindowsIdentity' property on objects of cache instance

PI Web API 2021 SP3

New Features:

• PI Point queries are exposed via the Get Points By Search endpoint.
  • The query syntax follows the AFSDK Point Query syntax.
  • This endpoint utilizes the underlying AFSDK PI Point search.

Bug Fixes:

• Fixed an issue with incorrect child event frames being returned with ambiguous search root.

PI Web API 2021 SP2

New Features:

• The Admin Utility GUI now allows the certificate validation check to be bypassed.
  • Previously, the Admin Utility GUI only allowed a certificate to be selected if it used the SHA-2 signing algorithm and was trusted by the local machine. To use an untrusted certificate, the system administrator had to use the Admin Utility's command-line interface.
  • Now, a system administrator can optionally choose to disable the check when using the Admin Utility GUI, and can select any certificate that has a private key.
  • Note that bypassing the certificate validation check allows a system administrator to select an insecure certificate. When bypassing the validation check, system administrators should only use certificates they know to be secure.
• Ad-hoc stream set requests that include duplicate Web IDs will now succeed.
  • Previously, an ad-hoc stream set request that included duplicate Web IDs could fail. Now, the operation will deduplicate when retrieving resources.
  • Note that deduplicating Web IDs may cause the number of results to not match the number of supplied Web IDs. When sending duplicate Web IDs, client applications should be careful to index into the results using the Web ID rather than an offset.

Bug Fixes:

• Fixed a race condition where a successful request could incorrectly report a failure due to a disposed user identity.

PI Web API 2021 SP1

New Features:

• The 'EnableBuiltInHelp' configuration setting has been added.
  • When set to true, the PI Web API's built-in help system will be enabled.
  • When set to false, the PI Web API's built-in help system will be disabled. Attempts to access the built-in help system will be redirected to the equivalent public AVEVA documentation webpage.
  • This setting is false by default.

Other Changes:

• The CreateSearchByAttribute and ExecuteSearchByAttribute endpoints return more information about what caused the request to fail.
  • Previously, when a request using these endpoints failed due to a malformed query parameter or request content, the returned error did not describe why the query parameter or request content was malformed. Now, an additional error message describes why the query parameter or request content was malformed.
  • Because the human-readable error message has changed, this is considered a breaking change. If your application does not programmatically parse the returned error messages, this is not a breaking change.

PI Web API 2021

New Features:

• Added the Performance Metrics Controller
  • Performance Metrics allows system administrators to view PI Web API usage, system load, and aggregate request performance.
  • For more information, see the Performance Metrics topic.
• Allow Point Source filtering when listing a Data Server's PI Points.

Bug Fixes:

• Channels now emit data source communication errors to clients.
  • For more information see the Error Handling section in Channels topic
• The PI Web API built-in help system now loads correctly when OMF is the only installed plugin.
• Request IDs are now preserved across the PI Web API's Admin, Analytic, and Debug Event Logs.
• Invalid configuration options now cause error events to be logged to the Admin Event Log. Previously, informational events would be logged.
• Users' permission settings no longer affect access to the Known Servers Table.

Other Changes:

• InstanceConfiguration endpoint has been renamed to ActiveConfiguration
  • ActiveConfiguration now shows all configuration settings, even those that have not yet been configured. If a setting has not been configured, the default value is shown.
  • The InstanceConfiguration endpoint is still available, but will return the same results as the ActiveConfiguration endpoint.
• Unrecognized AF and DA servers are no longer automatically added by default.
  • Previously, if a request tried to access an AF or DA server that was not recognized by the PI Web API server, the PI Web API would connect to the server and automatically add it to the set of known servers.
  • To re-enable automatically adding unrecognized servers, enable the 'AllowUnrecognizedAssetServers' and 'AllowUnrecognizedDataArchives' settings.
  • For more information, consult the PI Web API manual.
• The 'BearerEnableJwt' configuration setting has been removed. The authentication flow controlled by this setting has been removed.
• The default values of the 'BearerValidIssuer' and 'BearerValidAudiences' settings have changed.
  • Previously, these settings had a default value of null. These settings now have default values that are intentionally invalid, to prevent accidental misconfiguration.
  • Existing PI Web API configurations may require changes after upgrading due to these new default values. For more information, consult the PI Web API manual.
• 'AuthenticationMethods' configuration values are now case-insensitive.

PI Web API 2019 SP1

Other Changes:

• Added Content Security Policy to defend against Cross Site Scripting
  • The default Content Security Policy can be overridden using the Custom Headers feature to specify a reporting URI. For details, consult the PI Web API manual.
• Security & Bug Fixes

PI Web API 2019

New features:

• Open Message Format (OMF) Services
  • OMF v1.1 data ingress through PI Web API endpoint now supported over HTTPS when Open Message Format Services are installed
    • Support for create and delete actions
    • update actions are not implemented
    • For more information, see the OMF Endpoint Notes topic
      • This link is only available if the OMF plugin has been installed by your system administrator
• Stream Updates has been made part of the Core Services feature, and has graduated from Community Technology Preview (CTP). For more information, see the Stream Updates topic

Other Changes:

• Security & Bug Fixes

PI Web API 2018 SP1

New features:

• Notifications
  • Read for child NotificationContactTemplates
  • Read for NotificationPlugIn
  • Read, create, update, and delete for SecurityEntries on NotificationRules, NotificationRuleTemplates and NotificationContactTemplates
  • Create, update and delete for NotificationRules, NotificationRulesTemplates, NotificationContactTemplates and NotificationRuleSubscribers
  • GetByPath endpoints for NotificationContactTemplates, NotificationRules, and NotificationRuleTemplates
  • Search endpoint for NotificationContactTemplates
• Stream Sets GetJoined Endpoint
  • Endpoint for StreamSets that returns a set of recorded values (x-axis) with another set of data for any number of streams (Y, Y', Y''... axis) that are interpolated based on the points returned for the x-axis
• Stream Updates (CTP)
  • Metadata changes from AF Servers are handled
  • Selected fields are honored
  • Responses now include PreviousEventAction information
  • Error messages are shown for markers that are no longer valid

Data model changes:

• Expose 'Paths' and 'DataReference' properties on objects of attribute
• Expose 'Paths' property on objects of element

Other changes:

• The version of Web ID returned by PI Web API can be configured
  • PI Web API instances that run 2018 SP1 can now work together with older versions behind a load balancer since they can be configured to return the same version of Web ID
• Removed OpenAPI/Swagger specification endpoint
• Bug fixes

PI Web API 2018

New features:

• Read for notification contact templates, notification rules, notification rule subscribers and notification rule templates
• Read, create, update and delete for annotation attachments on event frames
• Retrieve relative paths of an element
• Retrieve full inheritance branch of an element template
• Allow reading annotations of a stream using the "associations" parameter
• Allow showing all child attribute templates of an element template
• Add parameter support for tables
• Filter attributes by trait and trait category
• Support health traits
• Incrementally receive updates from streams with Stream Updates (CTP)

Data model changes:

• Expose 'ServerTime' property on objects of asset server, data server and system
• Expose 'DisplayDigits', 'Span' and 'Zero' properties on objects of attribute and point
• Expose 'DefaultUnitsNameAbbreviation' property on objects of attribute and attribute template

Other changes:

• Add 'PreflightMaxAge' configuration setting

PI Web API 2017 R2 SP1

Bug fixes; no significant behavior changes.

PI Web API 2017 R2

New features:

• Web ID 2.0
• AFSearch based Element search
• AFSearch based Event Frame search
• AFSearch based Attribute search
• AFSearch based Analysis search
• AFSearch based Analysis Template search
• Retrieve the list of all available actions
• Add Sync Time parameters to all "Interpolated" endpoints
• Allow opting out of getting the search results for "CreateSearchByAttribute" endpoints
• Batch and "CreateSearchByAttribute" endpoints work in Read-only mode
• Channels support heartbeat of empty data frames

Data model changes:

• Expose 'WebException' property on all PI Web API service responses. Any response containing a 'WebException' indicates that PI Web API encountered an unhandled error during the transfer of the response stream. These errors only occur after PI Web API has sent the client a successful HTTP status code. Responses will not contain a 'WebException' if no error occurred. The 'WebException' property will be present at the top level of all response objects, except during responses from the Stream and Stream Set controller responses, in which case each stream value may present with an 'Errors' field (see 'Errors' below). For more information see the Error Handling topic.

• Expose 'Errors' property on time series data responses from the Stream and Stream Set controller. Any time series value containing an 'Errors' property indicates PI Web API encountered an handled error during the transfer of the response stream. Values will not contain a 'Errors' property if no error occurred. Each object in the list of 'Errors' contains which field name caused an error during this time, as well as the exception message. Unlike 'WebException', which is a single property found at the top level of the response object, an 'Errors' property may be present on each stream value. If a stream value contains an 'Errors' property, then its value will be 'null'. For more information see the Error Handling topic.

Other changes:

• Previously, the Stream controller would return an HTTP error response if any of the time series data values to be returned contained an AFSDK exception for its value. This has been changed. A full time series data payload will now be returned, and any values that contain an AFSDK exception as a value will have a value of 'null'. The exception will now be included in the 'Errors' property.

• The "/value", "/recordedattime", and "/end" actions on the Stream Controller will now verify if the value to be returned contains an AFSDK or PI Web API exception. These endpoints now return an error HTTP Status Code if any error occurs.

PI Web API 2017

New features:

• Support of claims-based authentication using ADFS, Azure AD, and PingFederate
• Search for event frames by 'Severity', 'IsAcknowledged', and 'CanBeAcknowledged' properties
• Retrieve recorded values at multiple timestamps for a stream or stream set
• Expose PI Web API 'Status' on System
• Protection against Cross-Site Request Forgery attacks
• Swagger specification
• Improved point attribute filtering
• New summary type: 'TotalWithUOM'

Data model changes:

• Expose AFSecurity in EventFrames
• Expose 'TimeZone' and 'ConvertToLocalTime' properties of tables
• Expose Product Title of PI Web API versions
• Hide Point link on AFAttributes with invalid PI Point data references.

Other changes:

• Add 'EnableCSRFDefense' and 'XFrameOptions' configuration settings
• Merge Channel controller to the core services

PI Web API 2016 R2

New features:

• Read, create, update and delete for security identities
• Read, create, update and delete for security mappings
• Read, create, update and delete for security entries
• Read, create, update and delete for annotations on event frames
• Manage attribute traits
• Allow to add an existing element as a child to another element
• Allow to provide time zone information as query parameter for stream and streamset resources
• Support Gzip compression for inbound data

Data model changes:

• Expose 'IsAnnotated' and 'IsLocked' properties on objects of event frame
• Expose 'Descriptor', 'DigitalSet', 'EngUnits' and 'Step' properties on objects of point
• Expose 'TraitName' property on objects of attribute
• Expose 'TraitName' property on objects of attribute template

PI Web API 2016 SP1

New features:

• Read, create, update and delete for analyses
• Read, create, update and delete for analysis categories
• Read, create, update and delete for analysis templates
• Read, create, update and delete for analysis rules
• Read, create, update and delete for time rules
• Read analysis rule plug-ins
• Read time rule plug-ins

PI Web API 2016

New features:

• Search element attributes matching various filters
• Search event frame attributes matching various filters
• Retrieve security rights of a user for an AF securable resource
• Retrieve multiple attributes by web id or path
• Retrieve multiple points by web id or path
• Retrieve (optionally) the attribute templates from the ancestors of the current element template
• White list selection of response fields
• A new type of batch sub-request: request template
• Add two web id aliases: "S00" for the local (PI Web API host) asset server and "S0D" for the default asset server

Data model changes:

• Expose 'ExtendedProperties' property on objects of element template, element, event frame, asset database and asset server
• Expose 'IsManualDataEntry' property on objects of attribute
• Expose 'InstanceType' property on objects of element template
• Expose 'NamingPattern' property on objects of element template
• Expose 'DefaultValue' property on objects of attribute template
• Expose 'HasChildren' property on objects of attribute template, attribute, element and event frame
• Expose 'BaseTemplate' property on objects of element template
• Expose 'Acknowledgement' property on objects of event frame
• Expose 'Severity' property on objects of event frame
• Add 'Categories' link on objects of attribute template and element template
• Add 'Path' property for the stream in StreamSet responses

Other changes:

• Add 'CorsExposedHeaders' configuration setting
• Merge Batch controller to the core services

PI Web API 2015 R3

New features:

• Search elements or event frames by attribute value
• CreateConfig for all attributes of elements or event frames
• Create, read, update, and delete for event frames' referenced elements
• Allow any HTTP method request as HTTP POST
• Get a single recorded value at a given time for Streams or StreamSets
• Get interpolated values at times for Streams or StreamSets
• Global request content length limit
• Batch (CTP)
• Channel (CTP)

Data model changes:

• Exposed property 'RefElementWebIds' on event frame objects
• Integrate AFJson library

Other behavior changes:

• None

PI Web API 2015 R2

New features:

• Bulk writes of time-series data (single and multiple value)
• Ad-hoc bulk reads and writes of time-series data
• Future PI points
• End-of-stream values for streams and stream sets
• Filtering of hidden and excluded attributes
• Event frame value capture

Data model changes:

• Exposed properties 'IsExcluded' and 'IsHidden' on attribute and attribute template objects
• Exposed property 'Future' on point objects
• Exposed property 'IsConnected' on Asset and Data Server objects
• Exposed property 'AreValuesCaptured' on event frame objects

Other behavior changes:

• None

PI Web API 2015

New features:

• Create, update, and delete for databases
• Create, update, and delete for event frames
• Create, read, update, and delete for enumeration sets and digital states
• Create, read, updated, and delete for element categories and attribute categories
• Create, read, update, and delete for tables and table categories
• Create, read, update, and delete for units and unit classes
• Create, update, and delete for points
• Read and update for point attributes
• Bulk retrieval of time-series data:
  • Current values
  • Recorded values
  • Interpolated values
  • Plot values
  • Summary values
• AF calculations
• Summary value filtering (streams and stream sets)
• Additional event frame search modes

Data model changes:

• Exposed properties 'Type' and 'TypeQualifier' on attribute and attribute template objects
• Exposed property 'Step' on attribute objects
• Exposed link 'Point' on attributes with point data references
• Exposed link 'DefaultAttribute' on event frames with a default attribute
• Exposed link 'Categories' on event frames

Other behavior changes:

• The default stream value update option changed from 'NoReplace' to 'Replace'.
• To accommodate filtering, stream summary value retrieval may now return error values as part of a successful (200) response. An error value may take the form of a string or an object with a single property, 'Errors', whose value is an array of error strings.

PI Web API 2014 R2 Update 1

Bug fixes; no significant behavior changes.

PI Web API 2014 R2

New features:

• Resources for indexed search

Data model changes:

• None

Other behavior changes:

• None

PI Web API 2014

• Create, read, update, and delete for elements
• Create, read, update, and delete for attributes
• Retrieval of time-series data:
  • Value at a timestamp, or current value
  • Recorded values
  • Interpolated values
  • Plot values
  • Summary values
• Single-value writes of time-series data
• Read for event frames
• Read for Asset Servers and databases
• Read for Data Servers and points