2021 - Detailed Changes (PI Web API OMF Services)

New Concept: OMF version 1.2

PI Web API 2021 introduces partial support for version 1.2 of the OMF specification. A client can indicate that OMF v1.2 should be used by setting the omfversion request header to the value 1.2. OMF v1.2 builds upon OMF v1.1, and introduces many new features. For more information about OMF v1.2, consult the OMF v1.2 Specification.

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

• The TYPE message enum property.
  • Although ENUM TYPEs are fully supported, there are some PI System limitations. See the ENUM TYPE section for more information.
• The TYPE property isQuality property.
• The TYPE property reftypeid property.
  • Currently, only ENUM TYPE reference types can be used.
• The TYPE property maximum and minimum properties.
• The CONTAINER message dataSource property.
• The CONTAINER message propertyOverrides property. The following property overrides are supported:
  • minimum
  • maximum
  • uom
• The __link type's property property.
  • Currently, the property property is only support for static-to-dynamic links.

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

• The TYPE message extrapolation property.
• The TYPE message baseTypeId property.
• The TYPE property interpolation property.
• Non-ENUM TYPE messages that omit the classification property.
• The CONTAINER message extrapolation property.
• The CONTAINER message metadata and tags properties.
  • These properties already existed in OMF v1.1, but the PI Web API silently ignored them. The PI Web API will now include a warning indicating support for these properties is not yet implemented.
• The following CONTAINER message propertyOverrides properties are not yet supported:
  • name
  • description
  • interpolation
• The DATA message properties property.
• Type-to-type LINK messages.

New Concept: ENUM TYPEs

OMF version 1.2 introduces ENUM types. An ENUM type is used to restrict a property's values to a known set of legal values. To specify that a TYPE property uses an ENUM, use the new reftypeid property instead of type and format. When an ENUM type is created, the PI Web API will always create an AF Enumeration Set to represent the ENUM, and may create a DA Digital Set if the ENUM is eligible. An ENUM type is eligible for a DA Digital Set if it meets the following criteria:

• The ENUM must be of format int16 or int32.
• The ENUM must start at zero.
• The ENUM must increment monotonically in steps of one.

An ENUM TYPE AF Enumeration Set is of the following schema:

• The Enumeration Set's name must be the ENUM's ID.
• The Enumeration Set's description must be a set of key-value pairs. Keys are case-sensitive. Keys must be unique. Values containing the characters ,, ", \, =, or leading/trailing whitespace must be enclosed in double-quotes ("). Values enclosed in double-quotes must escape the characters \ and " with a leading backslash (\). The following keys are required:
  • OmfSchemaVersion - The schema version being used. The value must be 0.
  • OmfTypeName - The ENUM's name.
  • OmfTypeVersion - The ENUM's version.
  • OmfTypeDescription - The ENUM's description.
  • OmfEnumType - The ENUM's type.
  • OmfEnumFormat - The ENUM's format.
  • OmfEnumNullable - Indicates whether the ENUM is nullable. When the ENUM is nullable, NULLABLE; otherwise, NOTNULLABLE.
• The Enumeration Set's values must be of the following schema:
  • The Enumeration Value's value must be set according to the ENUM's type and format as follows:

    Type	Format	Value
    integer	int64	The value is not used by PI Web API.
    integer	int32	The value must be the numerical value of the ENUM value.
    integer	int16 (Default)	The value must be the numerical value of the ENUM value.
    integer	uint64	The value is not used by PI Web API.
    integer	uint32	The value is not used by PI Web API.
    integer	uint16	The value must be the numerical value of the ENUM value.

  • The Enumeration Value's name must be the ENUM value's name.
  • The Enumeration Value's description must be a set of key-value pairs. The following keys are required:
    • OmfEnumValue - The numerical value of the ENUM value.
      • AF Enumeration Value values must be int32; this would make valid OMF ENUMs using formats like int64 unable to be represented in AF. As a workaround, the PI Web API stores the numerical value in the description.

An ENUM TYPE Digital Set is of the following schema:

• The Digital Set name must be the ENUM's ID.
  • ex. If your ENUM has an ID of My.Example.Enum, the name of the Digital Set must be My.Example.Enum.
• The Digital State values must be of the following schema:
  • The name must be the ENUM value's name. This field is case-insensitive.
    • The Data Archive deduplicates Digital State names case-insensitively. This means once a Digital State named like FOO exists, an attempt to create a new Digital State foo will succeed, but subsequent reads will return the name of the previously-created FOO. As a workaround, the PI Web API treats Digital State names case-insensitively.
  • The numerical value must be the ENUM value's numerical value.

New Concept: Quality Mappings

The OMF version 1.2 specification introduces the isQuality property to TYPE properties; however, the specification does not define how an OMF server implementation utilizes this field. PI Web API 2021 includes a quality mapping feature that allows an application to write quality information to the Data Archive. This quality mapping mechanism is not part of the OMF specification - it is a PI Web API specific feature.

A quality mapping can be associated with a DYNAMIC TYPE that has a property marked as isQuality. To associate a quality mapping with a DYNAMIC TYPE, include a metadatum with key DataQualitySchema and value of the quality mapping's ID. When a DYNAMIC DATA value is received, the value associated with the quality property will be compared to the quality mapping. The comparison can be either a direct value mapping (ex. "A value of '5' means 'GOOD', a value of '12' means 'QUESTIONABLE'"), or a set of flags (ex. "A value is 'BAD' if at least one of these bits is set"). The type of comparison is defined at the quality mapping level - it cannot mix value comparisons and flag comparisons.

Creating custom quality mappings is discouraged. As a PI Web API specific feature, quality mapping behavior may change between future product or OMF versions, making maintaining custom quality mappings difficult. For more information on custom quality mappings, please contact your technical support representative.

Quality mappings are stored as an AF Enumeration Set on the OMF AF Asset Database according to the following rules:

• The Enumeration Set name must have the prefix __qualitymap., followed by your quality map's ID. This is needed for the PI Web API to recognize your Enumeration Set as a quality map.
  • ex. If you sent the metadata value Foo, your Enumeration Set name should be __qualitymap.Foo.
• The Enumeration Set description must be a set of key-value pairs. Keys are case-sensitive. Keys must be unique.
  • The following keys are required:
    • Type - The OMF property type that the values of this quality mapping are defined in.
    • Format - The OMF property format that the values of this quality mapping are defined in.
    • IsNullable - Indicates whether a value of null should be treated as Good. If true, null will be treated as Good; otherwise, null will be treated as having the quality associated with the lowest numerical value in the quality map.
    • IsFlags - Indicates whether the values contained by this quality mapping should be treated as literal values, or as masks. If true, incoming values will be masked against the values defined by the quality mapping, and the worst quality for which all bits in the flag were set will be returned. An incoming value of zero will be treated as Good unless the quality mapping includes an explicit value of 0. If false, if an incoming value is contained by the quality map, the associated quality will be used; otherwise, Good will be used.
  • The following keys are optional:
    • Source - A human-readable indicator describing the source of the quality mapping.
    • Name - A human-readable name associated with this quality mapping.
    • Mask - When present, incoming values will be masked by this value. This value must be of the Type and Format used by the quality mapping.
• The Enumeration Values must be of the following form:
  • The value does not matter.
  • The name must be a valid value according to the enumeration's description's Type and Format keys. Values must be unique. This is the value that incoming DATA values will be compared against.
    • The quality mapping value is stored in the Enumeration Value's name, rather than the Enumeration Value's value, because AF Enumeration Set values must be within the range of int32. This means some OMF property formats, like int64, would not be able to be represented if the Enumeration Value's value was used.
  • The description must be a set of key-value pairs. Keys are case-sensitive. Keys must be unique. The following keys are optional:
    • Quality - The quality associated with this value. If not specified, a quality of Good is assumed. The value must be one of the following:
      • Good
      • Questionable
      • Bad
    • SystemStateCode - A manual system state code to use when storing quality data. This value is only allowed if Quality is set to Bad. The specified value must be defined by the AFSDK's AFSystemStateCode enumeration.
    • Comment - A human-readable comment associated with this value.

New Feature: Improved Per-User OMF Cache Control

PI Web API uses a per-user cache to improve request performance. Developers that have used PI Web API Core Services may already be familiar with this mechanism: When a user makes a request to the PI Web API, if they have recently used a PI System resource, the cached version will be used. This can greatly improve client application performance and reduces load on the PI System. However, some applications may need to bypass the PI Web API's per-user cache (ex. they cannot tolerate stale data). Applications that need to bypass the PI Web API's per-user cache do so by including the Cache-Control: no-cache header on their request. Note that if a client application requests cache refreshes too often, it can severely impact PI System performance. Clients must use this feature with caution.

PI Web API 2021 improves application control over the PI Web API per-user cache. In previous versions, the OMF cache could not be cleared by the user; applications either needed to wait for the cache to automatically referesh, or had to restart the PI Web API service. OMF applications can now trigger a refresh of the PI Web API per-user cache using the same Cache-Control: no-cache header. Note that this header is not part of the OMF specification - the per-user cache is a PI Web API specific feature intended to improve application performance.

Expanded Feature: UPDATE Action

PI Web API 2021 expands support for the UPDATE action. Previously, the UPDATE action was supported only for DATA messages. Now, the UPDATE action can be used for both CONTAINER and DATA messages. UPDATE is not yet implemented for TYPE messages.

The PI Web API's UPDATE CONTAINER feature can update any CONTAINER field, including typeId. When changing an existing CONTAINER's type, the new TYPE must not add or remove any value properties. This is a PI Web API specific restriction - it is not part of the OMF specification. This restriction exists so that an existing CONTAINER does not change from a simple type to a complex type (or vice versa), which could trigger unintentional PI Point renaming.

Breaking Change: PI Point Schema Version 2

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 introduces a new PI Point schema version: schema version 2. Schema version 2 introduces greater control over PI Points created using OMF, and supports new OMF features such as property minimum and maximum.

PI Points will automatically be upgraded to schema version 2 when a CREATE CONTAINER or UPDATE CONTAINER message is received. PI Points are upgraded to schema version 2 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. PI Vision symbol axes scaling changing based on the PI Point Span and Zero); 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 2 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	Set according to the Point Type and property type and format. The Point Type table takes precedence over the property type and format. Unless otherwise noted, the Step will be set to 0. Point Type Step Value String 1 Timestamp 1 Blob 1 Digital Unsupported Type Format Step Value array Unsupported boolean 1 integer int64 If this PI Point is using reftypeid, 1 If this PI Point is not using reftypeid, 0 integer int32 (Default - non-ENUM) 0 integer int16 (Default - ENUM) 0 integer uint64 If this PI Point is using reftypeid, 1 If this PI Point is not using reftypeid, 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.

Breaking Change: Parameter Names

When the PI Web API service has been configured for debug mode, PI Web API OMF Services may include additional information when an event is returned as part of the response payload. These pieces of additional information are called parameters. These parameters are meant to be used by developers when debugging OMF client applications, and are not intended for programmatic use.

Several existing parameter names have been changed as part of this release. These new names were chosen to improve readability of the returned event information.

Old Name	New Name
AttributeName	Attribute.Name
ContainerId	Container.Id
ContainerName	Container.Name
ElementName	Element.Name
ElementPath	Element.Path
PIPointDescriptor	PIPoint.Descriptor
PIPointEngineeringUnits	PIPoint.EngineeringUnits
PIPointExtendedDescriptor	PIPoint.ExtendedDescriptor
PIPointPointSource	PIPoint.PointSource
PIPointPointType	PIPoint.PointType
PropertyNullable	Property.IsNullable
TypeId	Type.Id
TypeVersion	Type.Version
TypePropertyFormat	Property.Format
TypePropertyIndex	Property
TypePropertyName	Property.Name
TypePropertyType	Property.Type
TypePropertyUom	Property.Uom

Breaking Change: Property Nullability Rules

OMF v1.2 introduces the concept of "implicitly nullable" property types/formats. An implicitly nullable property is a property which may receive a value of null even if the declared type does not include "null". An erratum for the OMF v1.1 specification has been published to include the same rule. The following property types/formats are now implicitly nullable:

• Properties of type array
• Properties of type object
• Properties of type string, except when format is Date-Time
  • This does not include isIndex or isName properties, which are not allowed to be null.

The following are expected changes in behavior as a result of this change:

• STATIC DATA messages that include null for implicitly nullable properties will no longer be rejected
• DYNAMIC DATA messages that include null for implicitly nullable properties will no longer be rejected
• The default value for non-Date-Time string properties has been changed to null. In previous versions of PI Web API OMF Services, the default value for a non-Date-Time string property that was not explicitly marked as nullable was "" (an empty string).
  • When omitting a value for a non-Date-Time string property in a CREATE or UPDATE DATA message, the recorded value will now be null. In Data Archive, this results in a "No Data" digital state being recorded.

Breaking Change: Events

• Operations that previously returned TypeMismatch now return TypeConflictsWithExisting.

Non-Breaking Change: OMF v1.2 TYPE Version Demoted to Metadata

In OMF versions 1.0 and 1.1, TYPE versions were a first-class feature. The original intention of TYPE versions was to allow client applications to maintain multiple versions of the same TYPE. However, in practice, this made interacting with TYPEs more burdensome - especially with the introduction of new features like reftypeid and TYPE-to-TYPE links as part of OMF v1.2. As a result, in OMF v1.2, TYPE versions have been demoted to metadata describing the TYPE, and are no longer required when referencing a TYPE.

When porting a client application from OMF v1.0 or v1.1 to OMF v1.2, if the client depends on the TYPE version exactly matching (ex. during STATIC DATA or LINK messages), the client will experience a breaking change where requests that previously failed will now succeed. Applications which do not use OMF v1.2 are not impacted.

Non-Breaking Change: Event Names

Some existing events have been renamed for readability.

Old Name	New Name
AFAttributeConflictsWithExpected	AFAttributeConflictsWithExisting
ContainerAlreadyExists	ContainerConflictsWithExisting
DuplicateType	TypeAlreadyExists
PIPointConflictsWithOverwrite	PIPointConflictsWithExisting
StaticDataDoesNotMatchExisting	StaticDataConflictsWithExisting
StaticInstanceWithSpecifiedIdAlreadyExists	StaticInstanceConflictsWithExisting
TypeAlreadyExists	TypeConflictsWithExisting

Schema Changes

Types

• array, object, and non-Date-Time string properties are now implicitly nullable. Omitting "null" when specifying a property of these types no longer prevents a value of null from being accepted for that property. This does not apply to any property with the isIndex or isName flag.
• The minimum and maximum property fields will appear as child AF Attribute Templates with the minimum/maximum limit property set.
• ENUM TYPEs have been introduced.

Containers

• PI Point Zero and Span attributes now contain values derived from the minimum/maximum of the associated TYPE property.
• PI Point Point Source attribute now contains the CONTAINER Data Source if one was supplied. If no Data Source was specified, the default Point Source PIWebAPI_OMF will be used.
• PI Points of type Digital may now be created. The PI Point Digital Set Name attribute will be set according to the OmfRefTypeId value when the OmfRefTypeQualifier value is Digital-Enum. If the OmfRefTypeQualifier value is Non-Digital-Enum, then the PI Point will be created using the type specified by the OmfPropertyType and OmfPropertyFormat keys.
• PI Point Step attribute now contains a value derived from OmfPropertyInterpolationMode. Because PI Web API does not yet support interpolation, this value is always the default mode associated with the property type and format.
• PI Point Extended Descriptor attribute changes:
  • The value associated with the OmfSchemaVersion key has been changed to to 2.
  • Backslashes are now escaped with a preceding backslash.
  • The OmfExplicitDataSource key may now be present. When present, it indicates whether an explicit CONTAINER Data Source was specified.
  • The OmfRefTypeId key may now be present. When present, it indicates the PI Point is using the reftypeid feature. When the OmfRefTypeId key is present, the OmfRefTypeQualifier key must also be present.
  • The OmfRefTypeQualifier key may now be present. When present, it indicates the qualifier of the reference type referred to by the property's reftypeid. This key must be present if the OmfRefTypeId is present. Allowed values are:
    • Digital-Enum - Indicates that the PI Point is expected to use a Digital Set. The expected Digital Set is specified by the OmfRefTypeId key.
    • Non-Digital-Enum - Indicates that the PI point is expected to use the type and format specified by the OmfPropertyType and OmfPropertyFormat keys.
  • A property format of date-time is now serialized as "Date-Time". In prior schema versions, a format of date-time was serialized as "DateTime" (note the missing hyphen).
  • The OmfPropertySimple key is now present in the PI Point's extended descriptor attribute. The value indicates whether this property is considered "simple". Previously, this value was inferred from the PI Point name. The representation of resources derived from a simple property may differ from non-simple properties (for example, PI Point names or AF Attribute names).
  • The OmfPropertyInterpolation key may now be present. When present, it indicates the interpolation mode this property is expected to use. When not present, the interpolation mode is inferred from the property type and format. 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.
  • The OmfPropertyMinimum and OmfPropertyMaximum keys may now be present. The values for these keys indicate whether a property has an explicit minimum or maximum. This is necessary because the Classic PI Point class defines default values for Span and Zero, and so the attribute values cannot be used to determine whether a minimum or maximum has been specified.

Data

• array, object, and non-Date-Time string properties are now implicitly nullable. Applications that consume OMF data can no longer rely on values of properties of these types to be non-null.
• The minimum and maximum property fields will appear as child AF Attributes with the minimum/maximum limit property set.