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

Expanded Feature: OMF version 1.2

PI Web API 2021 SP1 extends the partial support for version 1.2 of the OMF specification introduced in PI Web API 2021.

Support for the following OMF v1.2 features has been added:

• The TYPE message extrapolation property.
• The TYPE property interpolation property.
• The CONTAINER message extrapolation property.
• The following CONTAINER message propertyOverrides properties:
  • interpolation
• Partial support for the DATA message properties property.
  • Currently, the PI Web API only supports the properties property in combination with a typeid. The typeid cannot be omitted. When used, any additional properties added via the properties keyword will extend the specified TYPE.

The following OMF v1.2 features are not yet supported by the PI Web API:

• The TYPE message baseTypeId property.
• Non-ENUM TYPE messages that omit the classification property.
• The CONTAINER message metadata and tags properties.
• The following CONTAINER message propertyOverrides properties:
  • name
  • description
• Type-to-type LINK messages.

New Concept: Interpolation and Extrapolation Modes

PI Web API 2021 SP1 introduces support for the interpolation and extrapolation keywords in version 1.2 of the OMF specification. These keywords are used to control how data queries against the backend store should behave. The interpolation mode is used by the PI Web API to control the PI Point Step attribute value. The extrapolation mode is stored by the PI Web API, but is not used by the PI System.

For information on how the Step attribute value is calculated, see the section titled "PI Point Schema Version 3".

New Concept: Non-TYPE-Derived Properties

PI Web API 2021 SP1 introduces support for the DATA message properties keyword added in OMF version 1.2. The properties keyword allows a DATA message to define additional properties that will be used when storing a value. These properties support all the same features as a property defined as part of a TYPE, including the reftypeid, minimum, and maximum keywords. When the properties keyword appears alongside a typeid, any additional properties must be additive to the specified TYPE, and they must not overlap.

The PI Web API currently requires that a typeid be specified when using the properties keyword, even though the OMF specification does not make this requirement. This is because the PI Web API retrieves STATIC DATA instances by performing attribute value searches, and the backing AF Server may not support attribute value searches without specifying an AF Element Template. The PI Web API also requires that any additional properties are non-system properties: they must not have the isName, isIndex, or isQuality keywords set to true.

Breaking Change: Interpolation Mode

The interpolation keyword is used by the PI Web API to control the PI Point Step attribute value. In earlier PI Web API versions, a default interpolation mode was always used. Under certain conditions, the interpolation mode would be written to the PI Point extended descriptor; however, because interpolation mode was only used internally, these conditions could not be met when using the PI Web API. With the release of PI Web API 2021 SP1, the interpolation mode can now be controlled by the client OMF application. Interpolation modes in the extended descriptor of PI Points using earlier schema versions will now be ignored for migration purposes.

If your application does not directly read the interpolation mode from PI Point extended descriptors, you are not affected by this change. This covers applications that only use OMF. If your application does read the interpolation mode, your application must be updated to use PI Point schema version 3.

Breaking Change: PI Point Schema Version 3

As part of PI Web API 2019 SP1's resource migration support, the concept of schema versions was introduced. Schema versions describe the structure of PI System resources that are created or interacted with by the PI Web API; schema versions are not part of the OMF specification. PI Web API 2021 SP1 introduces a new PI Point schema version: schema version 3. Schema version 3 introduces greater control over PI Points created using OMF, and supports new OMF features such as interpolation and extrapolation.

PI Points will automatically be upgraded to schema version 3 when a CREATE CONTAINER or UPDATE CONTAINER message is received. PI Points are upgraded to schema version 3 regardless of the version of OMF being used. OMF client application behavior is not impacted; no changes are required. PI System applications may experience changes in behavior (ex. value queries returning different results due to the PI Point Step attribute); for this reason, this change is considered a breaking change.

Each PI Point maps to a value property on the TYPE used by a CONTAINER. PI Point attributes are mapped using schema version 3 as follows:

PI Point Attribute	OMF Mapping
Name (AKA Tag)	If the CONTAINER type is simple (has one value property), of the form quot;{container.Id}". If the CONTAINER type is complex (has more than one value property), of the form quot;{container.Id}.{property.Index}". For more details on simple and complex types, see the PI Web API OMF Services 2019 SP1 detailed changes topic.
Descriptor	The CONTAINER's description. If the CONTAINER does not have a description, this attribute is not set.
Point Source	If the CONTAINER specifies a dataSource, the specified dataSource. If the CONTAINER does not specify a dataSource, the default value PIWebAPI_OMF.
Point Type	If the property is not using reftypeid, derived from the property's type and format according to the table below. If the property is using reftypeid, if the referenced ENUM corresponds to a Digital Set, Digital. Otherwise, derived from the ENUM's type and format according to the table below. Type Format PI Point Type Notes array Unsupported boolean Int16 integer int64 If this PI Point is using reftypeid, String If this PI Point is not using reftypeid, Float64 The Data Archive does not have a numerical data type large enough to store an int64 without precision loss. integer int32 (Default - non-ENUM) Int32 integer int16 (Default - ENUM) Int32 The Data Archive has special behavior for Int16 PI Points. For consistency, the PI Web API instead uses Int32. integer uint64 If this PI Point is using reftypeid, String If this PI Point is not using reftypeid, Float64 The Data Archive does not have a numerical data type large enough to store a uint64 without precision loss. integer uint32 Float64 The Data Archive does not have a native unsigned integer data type. However, a Float64 can store a uint32 without precision loss. integer uint16 Int32 The Data Archive does not have a native unsigned integer data type. However, an Int32 can store a uint16 without precision loss. number float64 Float64 number float32 (Default) Float32 number float16 Float16 Although the Data Archive supports Float16, because the Asset Framework server does not, properties of type float16 cannot be created. object dictionary Unsupported string String string date-time Timestamp
Digital Set Name	If the property is using reftypeid and the specified ENUM is eligible for a Digital Set, the Digital Set with the name matching the ENUM's ID. If the property is using reftypeid and the specified ENUM is not eligible for a Digital Set, this attribute is not set. If the property is not using reftypeid, this attribute is not set.
Eng Units	In order of precedence, If the CONTAINER contains a property override for this property that specifies a uom, the specified uom. If the property specifies a uom, the property's uom. This attribute is not set.
Zero	In order of precedence, If the CONTAINER contains a property override for this property that specifies a minimum, the specified minimum. If the property specifies a minimum, the property's minimum. The Classic PI Point Class' default zero.
Span	In order of precedence, If the CONTAINER contains a property override for this property that specifies a maximum, a value derived from the specified maximum. If the property specifies a maximum, a value derived from the property's maximum. The Classic PI Point Class' default span.
Step	In order of precedence, If the CONTAINER contains a property override for this property that specifies an interpolation, a value derived from the specified interpolation. If the property specifies an interpolation, a value derived from the property's interpolation. A default value derived according to the property's type and format. The interpolation modes defined by the OMF specification are mapped to Step values as: Interpolation Mode Step Value Notes Continuous 0 StepwiseContinuousLeading 0 The Data Archive doesn't natively support this interpolation mode. Because a Step of 1 would misleadingly cause interpolated values to behave as stepwise following, the PI Web API treats this interpolation mode as continuous. Discrete 1 The Data Archive doesn't natively support this interpolation mode. The PI Web API treats this interpolation mode as stepwise following because it is the most similar natively supported mode. StepwiseContinuousFollowing 1 The following PI Point Types do not support interpolation. If a PI Point is using any of these types, the interpolation and property type and format are ignored. Point Type Step Value String 1 Timestamp 1 Blob 1 Digital 1 The following property type and format combinations do not support interpolation, and will override any specified interpolation: Type Format Step Value array Unsupported boolean 1 object dictionary Unsupported string 1 string date-time 1 If no interpolation is specified, if reftypeid is being used, the default Step value is 1. Otherwise, the default Step value will be: Type Format Step Value array Unsupported boolean 1 integer int64 0 integer int32 (Default - non-ENUM) 0 integer int16 (Default - ENUM) 0 integer uint64 0 integer uint32 0 integer uint16 0 number float64 0 number float32 (Default) 0 number float16 0 object dictionary Unsupported string 1 string date-time 1
Extended Descriptor	The extended descriptor is reserved for internal PI Web API use.

Non-Breaking Change: Event Names

Some existing events have been renamed for readability.

Old Name	New Name
ElementContainsUnrecognizedOmfAttribute	ElementContainsUnknownExtensionAttribute
SpecifiedOverrideIsNotValidForProperty	SpecifiedOverridesAreNotValidForProperty
TypeDoesNotHavePropertyWithSpecifiedIndex	PropertyWithSpecifiedIndexNotFound

Informational: Migrating from Prior PI Web API Versions

AF Attributes Created Via LINK Messages

If a minimum or maximum override is added to a CONTAINER while the PI Web API is being upgraded from 2021 to 2021 SP1, existing AF Attributes created via LINK messages may incorrectly have the minimum and maximum added as child attributes, rather than emit a mismatch event.

Schema Changes

Types

• The interpolation field will appear as a child AF Attribute Template.
• The extrapolation field will appear as an extended property of the AF Element Template.

Containers

• PI Point Step attribute now contains a value derived from OmfPropertyInterpolationMode.
• PI Point Extended Descriptor attribute changes:
  • The value associated with the OmfSchemaVersion key has been changed to to 3.
  • The OmfPropertyInterpolation key may now be present. When present, it indicates the interpolation mode this property is expected to use. When not present, it indicates no explicit interpolation mode was specified. Allowed values are:
    • Continuous - Indicates that the property is using the continuous interpolation mode.
    • Discrete - Indicates that the property is using the discrete interpolation mode.
    • StepwiseContinuousLeading - Indicates that the property is using the stepwisecontinuousleading interpolation mode.
    • StepwiseContinuousFollowing - Indicates that the property is using the stepwisecontinuousfollowing interpolation mode.
  • The OmfContainerExtrapolationMode key may now be present. When present, it indicates the extrapolation mode this property is expected to use. When not present, it indicates no explicit extrapolation mode was specified. Allowed values are:
    • All - Indicates that the property is using the all extrapolation mode.
    • None - Indicates that the property is using the none extrapolation mode.
    • Forward - Indicates that the property is using the forward extrapolation mode.
    • Backward - Indicates that the property is using the backward extrapolation mode.
• When reading a PI Point using schema version 2, the PI Web API will ignore the OmfPropertyInterpolation key if it is present.

Data

• Non-TYPE-derived properties will appear as AF Attributes.
  • If a non-TYPE-derived property has a minimum, maximum, or interpolation, it will be stored as child AF Attributes in the same manner as a TYPE-derived property.
• When creating a LINK where a target PI Point has an Engineering Units attribute whose value does not correspond to an AF UOM, an AF Attribute will be created without a UOM.