2021 SP2 - Detailed Changes (PI Web API OMF Services)

New Feature: Accept-Verbosity header

PI Web API 2021 SP2 adds support for the Accept-Verbosity header when included on an OMF request. When the PI Web API processes an OMF request, the returned response may include information related to the request, such as any warnings or errors that occurred during processing. Previously, the PI Web API server could be configured to include additional information to assist with debugging client applications, and clients had no control over what information was included in the response. Now, by including the Accept-Verbosity header, a client application can indicate that it would like to receive additional information in the response regardless of the server-side configuration.

Note: The Accept-Verbosity header indicates that the client is prepared to receive this additional information. The additional information may include values supplied by the client, PI System internal state, or other information determined at runtime. This information is not included in responses by default due to the security risk it can pose to insecure clients. If a client includes the Accept-Verbosity header but does not handle the response securely (ex. by escaping returned strings before presenting them to the user, by preventing deserialization of the response from requesting external resources, etc.), the client may be exposed to reflected XSS attacks, information disclosure attacks, and other vulnerabilities. The safest way to avoid such attacks is to not include the Accept-Verbosity header on requests. However, if the design of your application requires this information, be aware of the risks and ensure the returned information is handled correctly.

The Accept-Verbosity header can be used with the following values:

Header Value	Additional Details Returned	Description
parameters	Parameters associated with log events	Events may include parameters that help contextualize the event. For example, if an event says a TYPE was not found, it may include a parameter indicating the ID of the missing TYPE.
exceptions	Exception information associated with a log event	Events may arise as a result of an exception occurring during processing. If an event has such an exception associated with it, it will include information about the exception that occurred. For example, if an AF or DA operation failed due to a runtime exception, the exception information may help diagnose the underlying cause of the failure.
inner-events	Inner log events contained within a parent log event	Events may include inner events that help contextualize the event. For example, if an event indicates a conflict with an existing PI Point, the inner events may contain information describing the reason the conflict occurred.
verbose	Behaves the same as specifying both parameters and inner-events.

Multiple Accept-Verbosity headers and/or values can be sent within the same request. For example, a client could indicate that the response should include event parameters and exceptions in either of the following ways:

Accept-Verbosity header specified multiple times:

Accept-Verbosity: parameters
Accept-Verbosity: exceptions

Accept-Verbosity header specified once, with multiple values:

Accept-Verbosity: parameters, exceptions

Breaking Change: 'InnerEvents' and 'OmfIncludeInnerEvents' configuration option

When the PI Web API receives an OMF request, it will respond with a series of events that occurred during processing. These events can include various types of information, such as errors, warnings, or informational messages. These events may themselves be composed of inner child events that give greater context to the parent event. Previously, these inner events would only be included in a PI Web API OMF response when the PI Web API had been configured to run in Debug Mode. This meant that inner events were not available in production environments. PI Web API 2021 SP2 introduces a new configuration setting, OmfIncludeInnerEvents, which can be used to enable or disable inner events in production environments.

By default, OmfIncludeInnerEvents is set to true, and inner events will be returned. For backwards compatibility, returning inner events can be disabled by setting the OmfIncludeInnerEvents option to false. For more instructions on runtime configuration, see the PI Web API Admin Guide.