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

New Concept: Simple Types

PI Web API OMF Services 2019 SP1 introduces the simple type concept. A simple type is a dynamic type that has a single value property. Simple types are not part of the OMF specification: they are specific to the PI Web API. When discussing types, the term complex types is used to describe dynamic types with more than one value property.

Using a simple type changes how some resources are represented in your PI AF or PI Data Archive:

[{
    "id": "simple-dynamic-type1",
    "version": "1.0.0.0",
    "type": "object",
    "classification": "dynamic",
    "properties": {
        "time": {
            "type": "string",
            "format": "date-time",
            "isindex": true
        },
        "attribute1": {
            "type": "string",
            "name": "Attribute One"
        }
    }
}]

[{
    "id": " complex-dynamic-type1",
    "version": "1.0.0.0",
    "type": "object",
    "classification": "dynamic",
    "properties": {
        "time": {
            "type": "string",
            "format": "date-time",
            "isindex": true
        },
        "attribute1": {
            "type": "string"
            "name": "Attribute One"
        },
        "attribute2": {
            "type": "string"
            "name": "Attribute Two"
        }
    }
}]

[{
    "id": "simple-container1",
    "name": "Simple Container",
    "typeid": "simple-dynamic-type1"
}]

[{
    "id": "complex-container1",
    "name": "Complex Container",
    "typeid": "complex-dynamic-type1"
}]

simple-container1.attribute1

complex-container1.attribute1
complex-container1.attribute2

simple-container1

complex-container1.attribute1
complex-container1.attribute2

Simple Container.Attribute One

Complex Container.Attribute One
Complex Container.Attribute Two

Simple Container

Complex Container.Attribute One
Complex Container.Attribute Two

New Concept: UPDATE Action

PI Web API 2019 SP1 introduces limited UPDATE action support. UPDATE is supported for DATA messages. UPDATE is not yet implemented for TYPE or CONTAINER messages.

When an UPDATE message is received, it will be treated as an insert-or-replace operation. If the specified resource already exists, it will be replaced. If the specified resource does not exist, it will be created.

New Concept: Migrations

PI Web API 2019 SP1 introduces limited OMF migration support. This migration support allows somes resource types created using prior versions of PI Web API OMF Services — as well as non-OMF resources — to be re-purposed for use with the current version of PI Web API OMF Services. When a migration occurs, the resource will be modified for use with the PI Web API — sometimes destructively.

When a CREATE LINK DATA message is received, AF Attribute migration may occur. If a link between a static instance and a container already exists, AF Attributes belonging to that link may be renamed: for example, from Simple Container.Attribute One to Simple Container.

When a CREATE CONTAINER message is received, PI Point migration may occur. If a PI Point exists with the name PI Web API was going to use, it will be re-purposed for use with PI Web API OMF Services.

When migrating a PI Point, the way it was created affects how it will be migrated for use with PI Web API OMF Services 2019 SP1. PI Points are grouped in the following manner for migration:

• PI Points created by OMF (PI Web API 2019 and 2019 SP1) contain valid Point Source and Extended Descriptor attributes.
• PI Points that were not created by OMF have an Extended Descriptor attribute that the PI Web API cannot parse.

For PI Points created using OMF (PI Web API 2019), PI Points belonging to containers using a simple type will be renamed: for example, from simple-container-id.attribute1 to simple-container-id.

For any migrated PI Point — regardless of how it was created — some PI Point attributes will be overwritten:

• The OmfSchemaVersion=1 key-value pair will be added to the PI Point Extended Descriptor attribute.
• The PI Point Point Type will be changed according to the type being used by the container. The Data Archive controls whether the point type conversion is possible.
• The container description will be stored in the PI Point Descriptor attribute. If the container does not have a description, the PI Point Descriptor attribute will be blank. This will overwrite an existing Descriptor attribute value.

Schema Changes

Types

• No changes

Containers

• PI Point naming conventions have changed. Previously, all OMF PI Points were named like ContainerId.PropertyIndex. Now, PI Points using simple types will be named like ContainerId. The naming convention for PI Points using complex types has not been changed.
• The container description will be stored in the PI Point Descriptor attribute of all PI Points belonging to that container.
• The PI Point Extended Descriptor attribute now includes an additional key-value pair with the key OmfSchemaVersion. The value of this pair indicates which version of the PI Web API OMF Services was used to create the PI Point. A value 1 indicates that the PI Point was created using PI Web API OMF Services 2019 SP1. If this key-value pair is not present in a PI Point's Extended Descriptor attribute, it is assumed that the PI Point was created using PI Web API OMF Services 2019 (the first release of the plugin.)

Data

• AF Attribute naming conventions have changed. Previously, creating a static-to-dynamic link resulted in AF Attributes named like ContainerName.PropertyName. Now, static-to-dynamic links for a container using a simple type will result in AF Attributes named like ContainerName. The naming convention for AF Attributes using complex types has not been changed.