Please ensure Javascript is enabled for purposes of website accessibility
Powered by Zoomin Software. For more details please contactZoomin

PI Web API Reference

TABLE OF CONTENTS

Changelog

Save PDF
Save selected topicSave selected topic and subtopicsSave all topics
Share
Share to emailCopy topic URL

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 OMF Services 2023

New features:

Bug Fixes:

PI Web API OMF Services 2021 SP3

For more information, see the PI Web API OMF Services 2021 SP3 detailed changes topic.

New features:

  • Simplified Type delete

    • Only TypeID is required to delete a type - other fields will be ignored.

  • Simplified Container delete

    • Only Container and TypeID are required to delete a container - other fields will be ignored.

  • Simplified Static Data delete

    • Only TypeID and Values are required to delete static data - other fields will be ignored.

  • Case Insensitivity

    • Container ID's are now case insensitive.
    • Type ID's are now case insensitive.
    • Static Data indicies are now case insensitive.

Enhancements:

  • Container Create/Update will not overwrite Step point attribute of OMF PI Points when taking over existing PI Point.
  • Contianer Update will not overwrite DataSource point attribute of OMF PI Points when "datasource" field is not specified in OMF messages.
  • Warning is returned when the precision of a value may be lost in processing OMF Data messages.

Bug Fixes:

  • None.

PI Web API OMF Services 2021 SP2

For more information, see the PI Web API OMF Services 2021 SP2 detailed changes topic.

New features:

Enhancements:

  • The 'OmfIncludeInnerEvents' configuration option has been added. This setting controls whether responses populate the 'InnerEvents' field by default.
    • Previously, responses always included the 'InnerEvents' field, but it would only be populated when the 'DebugMode' configuration was enabled. Now, the 'InnerEvents' field will be populated based on this setting.
    • Available options are True and False.
    • The default setting is True.
    • For more information, see the PI Web API OMF Services 2021 SP2 detailed changes topic.
  • ContainerOverlapsWithAnotherContainer events will now return status code 409 (Conflict), instead of 500 (Internal Server Error).
  • Improved error handling when connecting to Asset Framework and Data Archive servers.
    • Previously, when an Asset Framework or Data Archive server was not found or could not be connected to, a 500 (Internal Server Error) would be returned.
    • Now, a 503 (Service Unavailable) will be returned.
  • Improved error handling when an operation fails due to a network interruption to Asset Framework or Data Archive.
    • Previously, when an operation failed due to a network interruption, a generic 500 (Internal Server Error) would be returned.
    • Now, in most cases, a 504 (Gateway Unavailable) will be returned. Some operations which can gracefully recover from a network interruption may return a more specific status code if data was lost as a result of the network interruption.
  • Some operations will return additional parameters indicating what type or container the event is related to.
    • Previously, the client needed to check the message index to determine which resource caused the failure. Now, the client can choose to rely on the event parameters if they are available and using the message index is too cumbersome.
      • Note that the set of parameters returned by an operation may change between OMF versions or releases of the PI Web API. When possible, the message index is still the preferred mechanism to determine which resource caused a failure.
  • The PointReferenceAttributesUpdated metric now reflects the number of AF Attributes updated when processing a link.
    • Previously, these attributes were rolled up under the PointReferenceAttributesCreated metric.

Bug Fixes:

  • update data operations that include link messages no longer incorrectly report mismatches when a link already exists.
    • Previously, the mismatch would prevent the link from being updated. Now, the link will be correctly updated.
  • Operations involving static-to-dynamic links where the target container includes an enumeration property will no longer incorrectly report PI Point mismatches.
    • Previously, a create data request that included a static-to-dynamic link where the target container included an enumeration property would succeed, but subsequent operations on the LINK (ex. re-submitted create operations, delete operations, etc.) would incorrectly report a PI Point mismatch. Now, the check is performed correctly, and subsequent operations will succeed (or fail with the correct error message).

PI Web API OMF Services 2021 SP1

For more information, see the PI Web API OMF Services 2021 SP1 detailed changes topic.

New features:

Enhancements:

Bug Fixes:

  • The interpolation mode of PI Points created using earlier versions of PI Web API is now ignored.
    • Full interpolation mode support is available as of this release. Previously, interpolation mode was an internal feature of PI Web API and could not be controlled.
    • For more information, see the PI Web API OMF Services 2021 SP1 detailed changes topic.
  • Container messages that include unsupported property overrides will now return accurate events.
    • Previously, when a container message included property overrides for a reference property, if a property override was not supported, the event would incorrectly identify which override was not supported. Now, the event parameters will correctly indicate which property overrides are not supported.
  • Minimum and maximum values derived from PI Point Span and Zero attributes are now clamped to the range of the specified property type and format.
    • Previously, if an OMF PI Point's Span and Zero attributes represented minimum or maximum values outside the range of the specified property type format, some operations that consume the PI Point could fail (such as creating a link). Now, the minimum and maximum values will be clamped to the allowed range, and the operation will not fail.
  • Links can be created when a PI Point has an Engineering Unit that does not correspond to an AF UOM.
    • Previously, if an OMF PI Point's Engineering Unit attribute did not correspond to an AF UOM, the link operation would fail. Now, the link will be created without an associated UOM.

PI Web API OMF Services 2021

For more information, see the PI Web API OMF Services 2021 detailed changes topic.

New features:

  • Partial support for version 1.2 of the OMF specification has been added.
    • OMF version 1.2 introduces many new features, including:
      • Enumeration types
      • Property minimum and maximum support
      • Overriding type-level information when processing containers
    • For more information, see the following resources:
  • The update action is now partially supported for the container resource type.
  • Improved PI Point migration support is now available.
  • Performance metrics for OMF are now available.

Enhancements:

  • Some event info parameter names have been changed for readability.
  • array, object, and non-Date-Time string properties are now implicitly nullable.
  • UpdateOperationCreatedNewResource has been replaced with more specific events.
    • Depending on the type of resource created, one of the following events will be returned:
      • ContainerCreated
      • LinkCreated
      • StaticInstanceCreated
  • Some events regarding resource collisions have been updated.
  • The 'OmfCreateMode' configuration option has been added. This setting indicates how to treat duplicate values when writing dynamic data to the Data Archive.
    • Available options are Replace, Insert, and NoReplace.
    • The default mode is Insert.
  • Existing digital PI Points can now be adopted by containers.
  • The per-user OMF cache can now be cleared using the Cache-Control: no-cache header.
  • Dynamic data for int32 properties will no longer return FeatureNotSupported for very large negative numbers.
    • Previously, these values were rejected because the Data Archive cannot faithfully store them. Now, the value will be coerced to the Over Range Digital State.

Bug Fixes:

  • Containers using a type that has no non-system properties will be rejected.
    • Previously, containers that used a type that had only system properties would be accepted, but no PI Points would be created. This meant container IDs could be incorrectly re-used.
  • StaticDataDoesNotMatchExisting events will now return status code 409 (Conflict), instead of 400 (Bad Request).
  • delete container messages that do not match the existing container will now return status code 409 (Conflict), instead of 200 (OK).
    • Previously, if a delete container message did not match the existing container, PI Points would not be deleted, but a 200 (OK) would still be returned. Although the underlying behavior has not changed, clients may need to be updated to account for the new status code.
  • Types containing properties which specify a UOM may now be deleted using either the UOM's full name, or its abbreviation.
  • A PI Point extended descriptor that ends in a comma will no longer cause requests to hang.
  • A delete type message that is rejected due to a mismatch between the message and the existing resource now includes information about the detected mismatch.
  • Static-to-dynamic links now set attribute UOMs.

PI Web API OMF Services 2019 SP1

For more information, see the PI Web API OMF Services 2019 SP1 detailed changes topic.

New features:

  • Limited support for the update action has been added.
    • update is now supported for data requests for the static, dynamic, and __link resource types.
    • For more information, see the OMF Endpoint Notes topic.
  • Naming conventions have been changed for some resource types.
  • Limited migration support has been added for some resource types.

Fixes and Enhancements:

  • ContainerNotFound and StaticInstanceNotFound events will now return status code 404 (Not Found), instead of 400 (Bad Request).
  • TypeDoesNotHavePropertyWithSpecifiedIndex has had its severity downgraded from Error to Info.
  • The string values "NaN", "Infinity", and "-Infinity" are now accepted for properties of type number.
  • Bug fixes

PI Web API OMF Services 2019

For more information, see the PI Web API OMF Services 2019 detailed changes topic.

New features:

  • 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.
In This Topic
TitleResults for “How to create a CRG?”Also Available in