PI AF Templates
Recommended Practices
Version 2.1
Published May 2017
Table of Contents
Executive Summary ................................................................................................. 1
Introduction .............................................................................................................. 4
Purpose ............................................................................................................... 4
Document Scope ..................................................................................................... 5
References .......................................................................................................... 5
Version History .................................................................................................... 7
Templates ................................................................................................................. 7
Template Security ............................................................................................... 8
Template Relationships ....................................................................................... 9
Template, Element, and Attribute Classification ................................................12
Standards for Naming ....................................................................................... 13
Element Categories ........................................................................................... 13
Attribute Categories ........................................................................................... 14
Child Attributes .................................................................................................. 15
Attributes and AF Data References ..................................................................... 15
Using Substitution Parameters .......................................................................... 16
PI Point Data Reference .................................................................................... 17
Table Lookup Data Reference .......................................................................... 20
Custom Data References .................................................................................. 20
Best Practices for Working with PI AF Administrator Tools .............................21
PI System Explorer ............................................................................................ 21
PI Builder ........................................................................................................... 21
PI AF XML Import/Export .................................................................................. 22
Custom Code utilizing the PI AF SDK ............................................................... 23
Combined Administrator Tool Strategy for PI AF Deployment ..........................23
Building PI AF Hierarchies.................................................................................... 24
Standards for Element Hierarchy Structures .....................................................24
Start with Placeholder Templates and Elements ..............................................25
Build Multiple Hierarchies .................................................................................. 26
Working with existing Elements........................................................................... 27
Creating a New Template from an Existing Element ........................................28
Changing to an Existing Template .................................................................... 28
Extending Elements .......................................................................................... 28
Resetting to Templates ..................................................................................... 28
PI Asset-Based Analytic Templates ..................................................................... 29
PI Event Frame Templates .................................................................................... 29
Notification Templates .......................................................................................... 29
About OSIsoft, LLC ................................................................................................ 30
LIST OF FIGURES
Figure 1 Demonstration of adopted security policies from parent element ............................... 8
Figure 2 Replacing child object permissions for an element hierarchy ..................................... 9
Figure 3 A set of derived element templates representing various types of meters ................. 10
Figure 4 A representation of a street light using reference templates ...................................... 11
Figure 5 A meter existing in two hierarchies with parent-child and weak references ............. 12
Figure 6 Attributes separated by category in PI System Explorer ........................................... 15
Figure 7 Configuring PI tag creation in the PI point data reference ........................................ 17
Figure 8 An element representing a PI Server ......................................................................... 18
Figure 9 PI Point data reference tag configuration by substitution parameters ....................... 18
Figure 10 PI Point data reference tag configuration by table lookup data reference ............... 19
Figure 11 Using placeholder element templates to plan for future development .................... 26
Figure 12 A simple AF database featuring multiple element hierarchies ................................ 27
Executive Summary
This paper describes the current best practices for building the PI AF structures for an
Enterprise PI AF deployment. This document includes best practices for, but is not
limited to:
•
The use of PI AF templates
•
Classifying templates, elements, and attributes templates and analysis
templates
•
Using attributes and PI AF data references
•
Working with PI AF administrator tools
•
Using and building PI AF hierarchies
•
Working with existing PI AF elements
•
Working with Event Frames
Summaries of the key best practices outlined in this paper are:
•
With the implementation PI Analysis Services within PI AF, PI Analytics
should be the first choice for PI System calculations and writing the results to
the PI Data Archive. PI ACE and PI Performance Equations should only be
used if PI Analytics cannot solve the specified use case.
•
When configuring PI Analysis Templates, results should be configured to
write the analytical results to PI Tags.
•
Templates should be used for the creation of all elements, event frames, and
notifications in order to save implementation effort, decrease maintenance,
standardize data, enable easier searching and reporting, and improve
performance and scalability.
•
Derived templates should be used to push common attributes into a higher
level template in order to save implementation effort and enable cross-asset
reporting.
•
It is a best practice to set security at the top levels of the PI AF security
model, as all PI AF objects created from that point forward will inherit the
security of the parent.
•
All PI AF objects, including templates of all types, elements, notifications, and
attributes, should follow a standard naming convention whenever possible,
either from an industry standard or an internal standard. This will help users
locate data, simplify reporting and analytics, and help streamline data
exchanges with 3rd parties.
•
Element categories should be used to separate elements into groups to make
it easier for users to locate data in PI System clients and improve the ability of
reporting and analytics tools to locate relevant data.
Page 1
•
Data attributes should be primarily at the top level, with child attributes used
primarily for configuration items and parameters of the parent attribute. This
will streamline the user experience and ensure that attributes are available in
all PI AF clients.
•
Data attributes should be separated into at least a few categories to enhance
reporting and searching.
•
If PI tags have not been created, it is a best practice to use PI AF to define
the PI tag configuration and create the tags. This applies to normal PI tags as
well as calculation PI tags such as PI Performance Equation tags and PI
Totalizer tags. This will reduce user error in tag creation as well as enforcing
tag naming and configuration standards.
•
When using PI Point data references, the PI tag names in the references
should be auto configured based on the template and other configuration
attributes. Automating PI tag name generation will streamline element
creation and result in less maintenance in the long run in most cases.
•
Once elements containing PI Point data references have been created, it is a
best practice to lock in the PI tag referenced by the PI Point data references
by using the “Create or Update Data References” function. This will reduce
round trips between PI AF clients and the PI System servers resulting in
better performance.
•
In addition to PI data references, other data references should be auto
configuring where possible, including formula, table lookup, and custom data
references.
•
Formula data references are evaluated client-side when they are accessed
and are not historized, so it is a best practice to use them primarily for simple
calculations that will evaluate quickly when a user loads the element. They
should be kept to one level if possible, i.e. not based on the results of other
formula data references, as this can cause slow performance. When formula
data references perform too slowly, it is a best practice to move them to use
PI Analysis Services and historized the results. Other options could include PI
ACE to a historized analysis. Using a PI Performance Equations PI Tag is still
an option, but using a PI Analytic for calculation and historization is the
recommend design approach.
•
Use PI Analysis Services and historized results for calculations and Event
Frame Triggering. Currently PI Analysis Service cannot overwrite historized
archive results, PI ACE or PI Performance Equations would be required to
update the historized data. For use cases where historized results may
require recalculation, the OSIsoft Center of Excellence should be consulted
directly.
•
Table lookup data references are primarily intended for configuration items
and smaller real-time data sets. Linking an AF table to a large external
database and using table lookup data references against it can cause slow
performance. It is a best practice to keep table lookup data references
against configuration items and smaller real-time data sets (10,000 rows or
less).
Page 2
•
If the external data that needs to be linked or imported to a PI AF table
cannot be reduced to less than 10,000 rows by the query, it is recommended
to consider bringing the data into the PI Server with the PI-RDBMS interface.
•
Custom data references are very useful and powerful, but because they are
evaluated client side they can cause performance problems. They should
always be carefully planned and extensively tested for performance.
•
There are a number of administrator tools available to work with PI AF,
including PI System Explorer, PI Builder in Excel, PI AF XML Import/Export,
and the PI AF SDK. The best practice approach to working with PI AF is to
use a combination of tools, typically starting with PI System Explorer for initial
work and testing and moving to PI Builder for bulk operations. In cases where
large-scale automation is possible, XML Import/Export and the PI AF SDK
can be used.
•
When there is an industry standard governing the relationship between
elements, best practice states that at least one hierarchy should be built to
meet the standard. This will enable the usage of industry reporting standards
and interoperability.
•
When starting to build hierarchies as part of building out the elements
structure of the PI AF implementation, it is a best practice to focus on high
value areas of the hierarchy first while using “placeholder” elements to leave
room for future work in the hierarchy.
•
Building multiple hierarchies using weak references is a best practice when
there are multiple use cases that each derives value from different
hierarchies.
If PI AF elements need to be synchronized back to the PI MDB for purposes like PI
ACE, it is best practice to consider the limitations of the PI MDB in terms of functionality
and scalability. It may be necessary to create special PI AF hierarchies to synchronize
which contain only the relevant elements, or in cases where elements have many
attributes it may be necessary to make smaller duplicates of those elements that
contain only the attributes necessary for calculations. For PI AF element
synchronization limitations, refer to the PI Asset Framework Installation and Upgrade
Guide, the PI Server 2010 MDB to AF Transition Guide, KB00692 - Limitations with
MDB to PI AF Synchronization and PI Server 2010 Configuring PI Server Security,
Chapter 7,MDB to AF Security Synchronization Considerations.
Page 3
Introduction
Purpose
PI AF provides a powerful framework for an asset context around real-time PI System
data. It allows users to work in terms of assets rather than simply data streams. The
assets in PI AF can represent a wide variety of real or virtual objects across any
industry.
As the PI System becomes more focused on assets over time, the value of a PI AF
implementation is becoming ever more apparent. PI AF is already directly valuable in
many common areas of the PI System, including:
•
•
•
PI Clients
o
PI Vision
o
PI ProcessBook
o
PI WebParts
o
Notifications
o
PI DataLink
o
PI Manual Logger
Data access
o
PI OLEDB Enterprise
o
PI JDBC
o
PI Web Services
o
PI AF SDK
Analytics
o
PI AF Formula Data Reference
o
PI Analysis Services
Within these products, PI AF not only provides value in terms of locating data but also
often improves the fundamental way the product is used.
However, implementing PI AF can be a daunting task to PI System Administrators that
are not used to the underlying technology and/or the idea of an asset centric PI System.
Building the contents of an enterprise PI AF implementation may require business
knowledge that PI administrators have only part of and therefore should always be a
team effort with PI administrators and business users working together.
This paper describes the current best practices for building the contents of an
Enterprise PI AF deployment. These best practices include, but are not limited to:
•
Defining recommendations for the use of PI AF templates
•
Defining recommendations for the naming and categorizing of PI AF templates and
elements
•
Defining attributes and PI AF data references
Page 4
•
Defining strategies for working with PI AF using administrator tools
•
Defining recommendations for the use of PI AF hierarchies
•
Options for working with existing PI AF elements and when they should be used
Document Scope
This document describes the current best practices for using PI AF templates to build
out an enterprise PI AF deployment. The scope of this document is limited to the best
practice methods and does not include much information on how to implement these
methods. For more detailed how-to information, see the relevant product user manuals
or other sources.
This document focuses on building the contents of the PI AF database or databases,
rather than the architecture they reside within. The topic of the PI AF architecture is
covered in the Center of Excellence best practices document “PI AF Deployment
Architectures”. The topic of how to synchronize multiple PI AF databases is covered in
the Center of Excellence best practices document “PI AF Synchronization”.
The scope of this document is also limited to general information that applies across all
industries. For information or documents specific to your industry, consult with your
Enterprise Project Manager and Center of Excellence Engineers. Additional industry
specific resources may be available that cover some of the topics in this document in
more detail.
For certain extreme use cases such as AMI or Smart Metering implementations, some
of the best practices covered in this document may not apply. In these extreme use
cases, the OSIsoft Center of Excellence should be consulted directly. Use cases
involving Sigmafine are also not covered in this document, as the Sigmafine application
is now owned by Pimsoft, Inc. For best practices in the Sigmafine application see the
Sigmafine documentation.
This document assumes the use of the following versions:
•
PI AF 2014 R2 or later
•
PI Server 2010 R3 or later
Future versions of this best practice document may include additional topics.
References
Reference
Source
PI System Explorer 2014 User Guide: A complete user
guide to PI System Explorer configuration tool of PI
AF. The documentation is also included within the
AF.chm help file installed into the PIPC\Help directory.
[LINK TO
DOCUMENT]
Page 5
Reference
Source
PI AF 2014 Installation and Upgrade Guide: A guide for
installing and updating Asset Framework application
service, PI SQL database, and PI AF client. The
documentation is also included within the AF.chm
help file installed into the PIPC\Help directory.
[LINK TO
DOCUMENT]
PI Live Library
Using event frames to capture process events
[LINK TO PI Live
Library]
PI Live Library
[LINK TO PI Live
Library]
Analytics and Notifications
OSIsoft.Learning Channel
OSIsoft: Create/edit Element Templates. v2010
[LINK TO YouTube
Video]
OSIsoft.Learning Channel
[LINK TO YouTube
Video]
OSIsoft: Create/edit element template attributes. v2010
OSIsoft.Learning Channel
OSIsoft: Use substitution parameters in a template
attribute, Part 1. v2010
OSIsoft.Learning Channel
OSIsoft: Use substitution parameters in a template
attribute, Part 2. v2010
OSIsoft.Learning Channel
OSIsoft: Create/edit Notifications Templates, Part 1.
v1.1
OSIsoft.Learning Channel
OSIsoft: Create/edit Notifications Templates, Part 2.
v1.1
OSIsoft.Learning Channel
OSIsoft: How to Setup Expression Analyses with PI AF
[PI AF 2014- v2.6.0.5843]
OSIsoft.Learning Channel
OSIsoft: How to Create PI EF Events, EF Attributes,
and EF Templates (PI EFGen v3.0.0.x)
OSIsoft.Learning Channel
[LINK TO YouTube
Video]
[LINK TO YouTube
Video]
[LINK TO YouTube
Video]
[LINK TO YouTube
Video]
[LINK TO YouTube
Video]
[LINK TO YouTube
Video]
[LINK TO YouTube
Video]
Page 6
Reference
Source
OSIsoft: How to Setup an Event Frame Template with
PI AF [PI AF 2014- v2.6.0.5843]
OSIsoft.Learning Channel
OSIsoft: How to Setup Event Frames Generation
Analyses with PI AF [PI AF 2014- v2.6.0.5843]
OSIsoft.Learning Channel
OSIsoft: Configure EF Events within the PIEFGen
Tutorial (PI EFGen v3.0.0.x)
[LINK TO YouTube
Video]
[LINK TO YouTube
Video]
Version History
Version
Date
Author(s)
Description
1.0
July 23, 2012
David Black, CoE,
dblack@osisoft.com
First Approved
Version
Ales Soudek, CoE,
asoudek@osisoft.com
Brian Palmer, CoE,
bpalmer@osisoft.com
Ramanj Pamidi, CoE,
rpamidi@osisoft.com
2.0
January, 2015
Alicia Coppock
Updates
Jon Croonenberghs
William Lum Kwan
2.1
May 2017
Jon Croonenberghs
Updates
Templates
PI AF templates allow the structure and contents of an element, including attributes and
analytics, Event Frames and Notifications to be defined before the PI AF object is
created. Multiple elements, notifications, or event frames can then be created from their
respective templates. Changes to the template are also reflected in all the objects
created from that template. PI notifications is currently a separate PI AF component
which can use templates like PI AF Elements.
Well-executed template design is the indispensable foundation of every PI AF
deployment. Utilizing templates for the creation of all elements, notifications, and event
Page 7
frames is a best practice for many reasons. Building with templates reduces effort and
enforces consistency in the creation of PI AF objects, including the functionality of
automating data reference configuration. Templates also make it much easier to make
changes to multiple objects at a later point after creation because changes made to a
template will also affect all objects created from that template.
PI AF templates provide benefits after they are used to create PI AF objects as well.
Utilizing templates for the creation of PI AF objects improves the performance of PI AF
and allows higher scalability. Templates also help when it comes to searching for
assets and building reports in an asset-based fashion. Elements, notifications, and
event frames can be found by searching for the template they were created from.
The PI System is changing to support an asset relative approach to data, and this is
reflected in many PI System clients. Asset relative functionality allows a “one to many”
approach to creating displays, reports, and analytics. It accomplishes this by allowing PI
System users to target their displays, reports, and analytics against a particular
template instead of a particular element, so it can be used with any element created
from that template or even related derived templates. Asset relative functionality is
currently present in PI DataLink, PI ProcessBook, PI Vision, and PI WebParts. It is also
planned for many other products such as PI Manual Logger. This client-side
functionality also makes utilizing templates a best practice because much of the assetbased functionality in PI System clients is built around the idea of templates.
Template Security
Security on a PI AF template controls which users can modify the template. It is
important to note that objects created from templates do not inherit the security of the
template, in other words security on a template is not “templatized security”. Instead,
the created objects adopts the security from the parent collection. For example in
Figure 1 below, TestFormulaTemplate when added Colorado\Bailey adopted the
security permissions from Bailey.
Figure 1 Demonstration of adopted security policies from parent element
Refer to PI System Explorer User GuideFor PI Asset Framework 2.6.1 included with PI
Server 2014 R2, PI Live Library PI AF security overview and KB00841 - An overview of
PI AF security.
It is a best practice to tighten the security within defined PI AF Asset models according
to the organization’s standards. Additional users can then be added to the PI AF
Model’s permissions if necessary. This will ensure that templates are only modified by
the correct users. Figure 2 below highlights updating security for the Element ‘Colorado’
Page 8
and using the advanced setting selecting Replace all child object permission entries for
this object check box for updating model security for all children.
Figure 2 Replacing child object permissions for an element hierarchy
Template Relationships
PI AF enables users to create relationships between templates. There are two types of
relationships, Derived Templates and Referenced Templates. Derived templates inherit
the attributes of the parent template and by extension other templates up through the
tree of derived templates. Referenced templates allow users to define common
relationships between elements at the template level. Both template relationships are
explained below in more detail.
Template Inheritance can be implemented via Derived Templates. Inheritance allows
multiple child templates to be derived from a single parent template, gaining the
attributes defined in the parent in addition to any attributes defined at the level of the
derived template. One important limitation to note is that PI AF templates can only have
one parent template; multiple parent inheritance is not currently supported.
This allows attributes that are shared across assets to be pushed into a higher level
template. Clients and reporting tools can use the higher level templates as their target,
enabling cross-asset reporting at a very generic level. For example, if a company
wanted to build an enterprise-wide energy usage monitoring system, they could build a
generic attribute into a top level template that represents the energy consumption for all
assets. Lower level templates representing the various assets could then override this
attribute to point to the correct PI tag representing the energy consumption of the asset.
An enterprise-wide energy usage report could then be created by targeting the generic
top level template’s energy consumption attribute.
Page 9
Figure 3 A set of derived element templates representing various types of meters
Using at least a few levels of derived templates is a best practice because it:
•
Shares effort in template creation across multiple templates and assets
•
Enables reporting on attributes shared across assets of different types
•
Can enforce standards across disparate types of assets
The exact number of levels of derived templates that should be used, and the amount
of detail they should be used to separate assets into, depends on the implementation
and as such there is no specific best practice for how many should be used. Some
common levels used in derived templates include:
•
A generic asset level that includes attributes shared across all assets within an
enterprise organization, such as a serial number
Page 10
•
An asset type level defining attributes for all assets of a type, such as turbines
with an RPM attribute
•
A type subset level that defines specific subsets of a generic type, for example
gas turbines and steam turbines
•
A manufacturer level with attributes that override the more generic templates to
automate PI tag name generation
•
A generation or revision level, overriding the attributes that change between
generations of an asset type
Referenced Templates
Referenced templates allow users to define the relationship between PI AF elements at
the template level, so that the relationship guides users in element creation later. This
can be used to reflect real world relationships, for example a street light is clamped to a
pole. Referenced templates can also be used to represent more conceptual
relationships, such as the relationships between the organization, a site, and a plant
within that site.
Figure 4 A representation of a street light using reference templates
All elements are related by default generic reference types. Defining reference types
using referenced templates is not required, but it can be helpful in certain use cases.
There are three default generic reference types, “Composition”, “Parent-Child”, and
“Weak”. They correspond to the three reference strengths available for reference types
created by referenced templates, which are “Composition”, “Strong”, and “Weak”
respectively.
Taking the time to implement specific relationship types through referenced templates is
only a best practice when many users will be creating elements from templates
manually in PI System Explorer, and need guidance during the creation process.
Otherwise, it is sufficient to utilize the default relationships.
Reference Types
There are three reference types used to define relationships between elements:
Page 11
•
Composition: The child element is a part of the parent element and does not exist
without it, deleting the parent element will also delete the child element
(represented by the default “Composition” reference type)
•
Strong: The child element has multiple parents, and will not be deleted even if a
parent element is deleted as long as it has other existing parents (represented by
the default “Parent-Child” reference type)
•
Weak: The elements are related, but the relationship does not define the lifetime
of the child element (represented by the default “Weak” reference type)
When creating elements, it is a best practice to use the parent-child reference type (or a
strong custom reference type) when first creating the element, then use the weak
reference type (or a weak custom reference type) when creating further hierarchies.
Using weak references allows users to reference elements in other hierarchies without
actually creating copies of those elements, so they have little performance impact.
For example, in Figure 5 below, “SmartMeter-ABC123XDF” exists in the “Electric-Utility”
element hierarchy. The “Sub-Station” hierarchy only contains a link to the meter
element using a weak reference. Multiple hierarchy solutions have many uses; typically
they are used to present different views of assets to end users. In the example below, a
corporate user might only be concerned with meters sorted by sector, while a user
focused on distribution transformers might only need to see the meters underneath a
particular transformer.
Figure 5 A meter existing in two hierarchies with parent-child and weak references
Template, Element, and Attribute Classification
To make the best use of PI AF, it is important for users to be able to easily locate the
data that is relevant to their use case. This means that the elements representing
particular assets must be easy to find, and the attribute that contains the data the user
requires must be easy to locate within the element. There are a number of best
practices for achieving this goal, including:
•
Standards for naming of elements and attributes
•
Use of element categories to group elements
•
Use of attribute categories to group attributes within an element and across elements
•
Use of child attributes to hide configuration attributes from users
Page 12
Standards for Naming
The naming of PI AF elements and attributes is an important consideration when
building a PI AF implementation. It is a best practice to model the contents of PI AF on
industry wide standards when such a standard exists and is possible to implement.
Even when an industry standard is not available, a companywide internal standard for
naming conventions of PI AF elements and attributes should be adopted. Some of the
common industry standards that include or reference naming conventions that are
relevant to PI AF include CIM (Common Interface Model), the MultiSpeak Specification,
and ANSI/ISA S95.
This helps in interoperability, exchange of data between applications, and ease of use
across sites for users. If the PI tags are also named according to an industry standard
or internal standard, naming the elements and attributes according to the standard can
make it easier to automatically configure those elements and attributes. Query tools
such as PI OLEDB Enterprise can take advantage of naming conventions by building
generic SQL queries at the PI AF template level rather than individual elements and
attributes.
Following a naming standard can be particularly advantageous for customers who
already have the PI System deployed across multiple sites, especially if those sites
acquired the PI System individually or were acquired from other organizations. In
situations like this, even if the PI tags are named differently across sites, PI AF can be
used to present the data to the users in a consistent fashion across all sites by following
a naming standard within PI AF. This will abstract the actual PI tag names away from
users, and get them thinking about how to use the data rather than how to find it.
Element Categories
Element categories allow users to group elements in categories, independent of their
position in PI AF hierarchies. These groups of elements can be used while browsing or
searching in PI AF client tools, as a dimension when building a Business Intelligence
cube, and as an input to analytics.
However, element categories are one dimensional compared to hierarchies; in other
words, an element can belong to any number of categories, but all elements choose
from the same list of element categories. There is no functionality to separate element
categories into groups within PI AF. Because of this, best practice is to use hierarchies
for more complicated groupings of elements while utilizing categories for simple onedimensional separation. An example of a best practice use of categories would be
adding categories for regions, sites, and plants to enable searching by categories
instead of having to search by a certain hierarchy level.
One situation where categories can be useful is when the geographic hierarchy for an
organization cannot be normalized, in other words the same level of the hierarchy does
not always represent the same type of element. In this situation, all elements
representing sites could be put into a “Sites” category, and searches could be
performed against this category instead of a complicated search involving multiple
hierarchy levels.
One thing to note is that adding element categories to elements created from templates
requires the use of the “Allow Extensions” option on the template. Adding extra
Page 13
categories to elements is the safest use of “Allow Extensions” and utilizing it is a best
practice when extra categories are necessary at the element level.
Attribute Categories
Attributes can be categorized into custom categories just like elements. This can be
useful for making elements easy to use when they have large numbers of attributes.
Typical uses of attribute categories include:
•
Separating real-time data from static meta-data
•
Separating calculated values from raw values (Figure 6)
•
Separating summary values such as averages, minimums, maximums, etc. from raw
values
•
Separating attributes into subsystems within an element
•
Separating configuration values from the attributes they help to configure
Support for attribute categories in PI System clients varies. A few places in clients they
are useful include:
•
Querying groups of attributes through OLEDB or JDBC
•
Administering element templates and elements in PI System Explorer
•
PI ProcessBook AF attribute search
•
Use Rollup Analysis which supports inputs based on categories.
•
As an input to custom data references
Other PI clients provide varying levels of support for PI AF attribute categories. It is best
practice to divide attributes on element templates and elements into at least a few
categories. Whether effort is spent on further dividing the PI AF attributes depends on
the use cases for PI AF.
Page 14
Figure 6 Attributes separated by category in PI System Explorer
Child Attributes
PI AF attributes can also be created as children of other PI AF attributes in their own
hierarchy. This functionality can be used for many different purposes, including:
•
Separating attributes into subsystems, types, etc.
•
Hiding attributes not normally needed by users from their initial browsing or searches
•
Hiding attributes specifically used for configuration of other attributes from users
•
Grouping calculation parameters with the calculation they are inputs for
Using too many levels of child attributes can complicate queries and user interaction
with the PI AF database. For most users it is best practice to keep the attributes
referencing data at the top level and utilize the child attribute functionality for
configuration parameters or calculation inputs that users do not need to work with. It is
typically a better practice to separate attributes with categories rather than creating
artificial hierarchies with child attributes.
Attributes and AF Data References
Although elements are the structure of PI AF, the attributes that make up the contents
of the elements are where much of the real work is done. PI AF attributes contain or
reference most of the data on an asset, and AF data references enable the majority of
that data.
Page 15
Be aware that chaining data references can cause slow client-side performance. For
example, a formula Data Reference (DR) attribute getting data from a number of Table
DR attributes from different elements, each with a query containing PIPoint DR attribute
parameters. It is best practice to minimize this type of configuration.
Without data references, attributes can still be useful for static values, such as model
number or type. They can even use the enumeration data type to be selectable from a
dropdown. However, these will only account for a small percentage of attributes per
element.
The following AF data references are available by default:
•
PI Point Data Reference
•
PI Point Array Data Reference
* Currently only custom applications using the PI
AF SDK can consume PI Point Array Data References
•
Formula Data Reference
•
Table Lookup Data Reference
Custom data references can also be written for integrating complex data sources and
calculated references. With the release of PI Analysis Services the need to utilize
custom data references in PI AF for most cases should utilize PI Asset-based Analytics.
Refer to Implementing custom AF 2.x Data References in OSIsoft PI Square for how to
build and used custom data references using Microsoft Visual Studio.
By combining the OSIsoft provided data references with custom data references if
needed, users can use PI AF to locate almost any data about an asset. There are best
practices that are relevant to each type of data reference, which will be discussed in the
following sections for each specific data reference.
Using Substitution Parameters
Substitution parameters allow PI AF administrators to define placeholders in the
configuration of an attribute within a template that will be replaced automatically when
an element is created. They can be used for both static attributes and in the
configuration of data references. Using substitution parameters in attributes makes the
templates more manageable and scalable because effort is saved when the element is
created because it becomes partially or fully self-configuring. A list of substitution
parameters can be found in the PI System Explorer User Guide.
Utilizing substitution parameters whenever possible is a best practice because it
reduces the amount of work required to create PI AF elements. Although it requires
more effort to set up at the template level, the amount of work saved at element
creation time typically far outweighs the time spent in setting up the substation
parameters because of the “one to many” nature of templates.
It is also a best practice to build templates such that elements require as little
configuration as possible by using substitution parameters. The best option, if possible,
is to auto configure the attributes of elements by the name of the element. If the
attributes cannot be auto configured based on the name of the element alone, the next
best option is to build a few configuration attributes into the template that are configured
by the user, for example make, model, and serial number.
Page 16
PI Point Data Reference
The PI Point data reference is the main data reference that will be used within PI AF. It
supports both direct data calls to the PI tags using the usual PI System time retrieval
methods as well as summary calculations. There are a number of best practices for
utilizing PI Point data references effectively.
The first consideration is whether the PI tags that will be referenced by the PI Point data
references exist or still need to be created. If they must be created, PI AF can be used
to drive the PI tag creation (Figure 5). All of the PI tag configuration parameters can be
built into the attribute inside the template. It is a best practice to use PI AF to build PI
tags when they do not exist using the PI AF PI Point data reference as it will partially
automate tag creation, reducing errors in tag creation and enforcing standards in
naming and PI tag configuration. The PI tag creation can even be extended to the
creation and modification of calculation PI tags such as PI Performance Equation tags
and PI Totalizer tags, allowing them to be created and modified in an asset-based
fashion.
Figure 7 Configuring PI tag creation in the PI point data reference
Page 17
When configuring the PI Point data references, avoid use of “%Server%” substitution
parameter for the PI Server selection in Enterprise deployments with multiple PI
Servers because it is evaluated to the default PI Server for a particular PI AF client.
Instead, it is best practice to directly configure the PI Server name where the data is
located, usually by a configuration attribute representing which PI Server contains the
PI tag, either in each asset or in an element representing the PI Server somewhere.
Figure 8 below shows an example of this.
Figure 8 An element representing a PI Server
When configuring the PI tag for the PI Point data reference, it is best practice to make
the tag string configure itself as much as possible. If the corporation has a very well
defined PI tag naming convention across all sites, then using the system variables is
the best approach. For example, the substitution string might be
“%..\Element%.%Element%.%Attribute%.PV”. In Figure 9 below, this evaluates to
“Process Unit 1.Pump B.Flow.PV”.
Figure 9 PI Point data reference tag configuration by substitution parameters
However, if the corporation does not have a well-defined PI tag naming convention a
more sophisticated approach is needed. One method to accomplish this is to use a
mapping AF Table to map the PI tags to the appropriate attributes, have a configuration
child attribute that does a table lookup to retrieve the PI tag name, and then map the
value of this attribute to the attribute with the PI data reference. Figure 9 shows an
example where the “Power Consumption” attribute has a child attribute named “PITag”.
The string in the “Power Consumption” attribute’s settings is then “%@.|PITag%”,
referencing the child attribute containing the tag name.
Page 18
Figure 10 PI Point data reference tag configuration by table lookup data reference
Configuration of the unit of measure for the PI tag referenced is optional, and if left at
the default option will use the unit of measure of the attribute instead. However, it is a
best practice to explicitly set the unit of measure the source PI tag is measured in. If the
unit of measure of the attribute is changed for display reasons in the future, it will
display incorrectly if the PI Point data reference unit of measure is left at the default. If it
is explicitly set, PI AF will perform the unit of measure conversion to the new display
unit.
The PI Point data reference also allows you to select the time retrieval for the PI tag
data. The default option is “Automatic”, but it is a best practice to explicitly set the
retrieval mode to what is desired for the PI tag data access to ensure that users see
exactly what they request when retrieving data. Typical uses would be “At or before” or
“Interpolated”, depending on the type of data being retrieved.
The PI Point data reference can also be used for simple summary calculations over a
time range including count, average, range, etc. When using summary calculations, it is
a best practice to indicate in the attribute name that a summary calculation is being
used so users do not confuse the attribute with a raw data retrieval attribute. They can
also be separated from raw values conveniently using categories or child attributes.
Once the elements with PI Point data reference attributes have been created, the link to
the PI tag can be “locked in” so that PI AF clients no longer have to make an extra
round trip to evaluate the PI tag name from substitution parameters and lookup the
resulting tag name in the PI Server. Locking in the PI tag reference will save the server
name and point ID of the PI tag, resulting in fewer round trips during data access and
faster data access. The PI tag is locked in by using the “Create or Update Data
Reference” options in the various PI AF administrator clients:
1. PI System Explorer: Right click on the attribute or containing element and select
“Create or Update Data Reference” or “Create or Update PI Point”.
2. PI System Explorer Import: During Import, select the “Create or Update PI Points”
option.
3. PI Builder for Excel: Enable the “Create or Update PI Points” setting.
4. AFImport.exe (XML Import): Use the /CreateUpdatePIPoints (/P) option.
Page 19
Once the PI tag is locked in, it will not change based on the substitution parameters
changing without using the “Reset to Template” functionality. It is a best practice to lock
in the PI tag reference after element creation unless there is a business case for rapidly
changing tag references, which is extremely rare.
Table Lookup Data Reference
The Table Lookup data reference allows users to perform queries against PI AF tables
using a simple SQL query language. The result of these queries then becomes the
value of an attribute returned to the PI AF client. Like all PI AF data references, they are
evaluated client-side at the time of data retrieval.
The key best practice for the Table Lookup data reference is to utilize it for configuration
data and smaller sets of real-time data such as lab data. It is not intended for largescale data access against large tables containing large amounts of data. Performance
will vary depending on the implementation, but typically “large” tables are those
containing more than 10,000 rows.
In the case of external tables that need to be imported or linked into PI AF tables, it is a
best practice to limit the scale of the PI AF table to 10,000 rows or less by targeting the
query against the external table used for the import or link specifically at the required
data. For example, if an external table contains 200,000 rows, but each row represents
a timestamp and PI AF users will only need the values for a certain recent period of
time, design the query to retrieve the latest 10,000 or less rows. Calling parameterized
stored procedures to the external datasource can improve performance when using
table lookup references.
In solutions where large amounts of real-time data need to be accessed and the data
set required cannot be brought to under 10,000 rows by the query to build the PI AF
table, customers should consider implementing a custom PI AF data reference using
direct access to the external database source through methods such as OLEDB or
JDBC instead of a linked PI AF table and a table lookup data reference. Customers
could also consider utilizing the PI-RDBMS interface to make the data available in the
PI Server, and then utilize PI Point data references within PI AF.
Custom Data References
In addition to the data references provided with PI AF by default, new data references
can be written in .NET. These references are installed on the server and then are
automatically distributed to the PI AF clients.
Although best practices for the development of custom data references are beyond the
scope of this document, their use can be powerful where the default data references
are not sufficient. The key factor to consider when utilizing custom data references is
that PI AF data references are evaluated only when a client accesses them. They are
not historized in any way beyond simple caching. With custom data references, it is
important to consider how long they will take to evaluate, and consider that when
deciding how many custom data references to build into an element. Too many custom
data references can significantly increase the response time when loading an element.
For more information on building custom data references, consult the sample custom
data references and related white papers on OSIsoft PI Square. With the release of PI
Page 20
Analysis Services the need to utilize custom data references in PI AF for most cases
should utilize PI Asset-based Analytics. Refer to Implementing custom AF 2.x Data
References in OSIsoft PI Square for how to build and used custom data references
using Microsoft Visual Studio.
Best Practices for Working with PI AF Administrator Tools
There are a number of administrator tools available for working with PI AF, including:
•
PI System Explorer
•
PI Builder
•
XML Import / Export
•
Custom coding with AF SDK
Each tool is strong in certain areas, with some overlap between the tools available. The
best practice approach utilizes a combination of these tools to provide a comprehensive
environment for working with PI AF.
PI System Explorer
PI System Explorer, commonly referred to as PSE, is the primary administrator tool for
PI AF. It provides a graphical view of the contents of PI AF and allows users to create
and modify anything within PI AF. In terms of usage, it is a Windows application
requiring installation on the user’s system.
Pros
•
Access to full PI AF feature set
•
Graphical user interface
•
Supports common Windows application functions such as copy and paste
•
Can be used to view results of actions easily as it is also a PI AF client tool
•
Can open two copies of PI System Explorer and connect to different PI AF
databases or PI Systems, and copy PI AF objects between them
Cons
•
New user interface for users to learn, access to full feature set can be intimidating to
new users
•
Laborious when configuring a large number of PI AF objects due to point and click
nature
PI Builder
PI Builder is a plug-in for Microsoft Excel that allows the manipulation of PI AF objects
by importing and exporting to and from PI AF databases. PI Builder v 2.6.2.6558 or later
now includes the PI Tag building capabilities. It is based on the ribbon style of Excel
menus, and as such requires Excel 2007 or later. Although it provides graphical
Page 21
functions for users through ribbons, the data in PI Builder is displayed in a tabular
format and is harder to interpret visually than the PI System Explorer graphical display.
Pros
•
Supports most of the PI AF feature set for element templates, elements, event frame
templates, and event frames
•
Supports bulk operations on PI AF objects
•
Tabular format of data makes bulk operations very efficient
•
Security settings can be changed in bulk
•
Transposed attributes from templates function makes creating elements in bulk for a
single template type extremely fast and simple
•
PI AF structure can be maintained in a document management system as a revision
tool for changes to templates or other PI AF objects
•
Good overview of all the attributes and properties of the template
•
Can be used to build and configure PI Tags
Cons
•
Cannot build Notification templates
•
Requires Excel 2007 or later
•
All data must be entered manually, no built-in pull down menus for enumeration sets,
units of measure, data references, etc.
•
Tabular nature of interface makes it more difficult to visualize changes compared to
PI System Explorer
PI AF XML Import/Export
The PI AF XML Import allows users to export to or import from a PI AF XML file format.
It can be used to modify existing PI AF objects or create new objects. There are two
utilities for importing and exporting XML files: a command line utility which can be
scripted, and a menu function within PI System Explorer. A common usage of PI AF’s
XML Import/Export functionality is moving PI AF objects from one PI AF database to
another, for example test to production.
Pros
•
Easily scriptable using standard Windows functionality without any custom code
•
Can be created from other XML formats using XSLT process
•
Can create PI AF databases
•
Efficient for bulk operations
Cons
•
XML Format is not easily created or modified by users, typically needs to be created
from an existing PI AF database and modified
Page 22
•
Does not support renaming objects unless GUID’s are used, which are not shared
across PI AF databases (rename will create new object with the new name and leave
the old object)
•
Other tools must be used to view the results of actions, does not provide much PI AF
client functionality
Custom Code using the PI AF SDK
The PI AF SDK supports the full feature set of PI AF and can be used to create or
modify any type of PI AF object. It is a .NET SDK that can be used in customer custom
applications, including web services.
One possible use of the PI AF SDK for creating PI AF objects would be to create a
custom application that would be user friendly to end users by appearing as part of an
application they already work with, allowing them to build PI AF objects without needing
to learn PI System Explorer or PI Builder. Another example use is to build web services
that are called from business systems to create PI AF objects.
Pros
•
Access to full PI AF feature set
•
Can create any PI AF object such as databases, element templates, elements, etc.
•
Can set security on any PI AF object
•
Efficient for bulk operations
•
.NET SDK that can be used in a wide variety of Windows application types, from
console to web services
•
.NET SDK that is easy to learn quickly for programmers with .NET experience
Cons
•
Must have a programming environment
•
Must have users with development experience
•
Must add code to take advantage of new features in new PI AF releases
•
Must program all the features that are already available in the other tools
Combined Administrator Tool Strategy for PI AF Deployment
Although each tool for working with PI AF objects has advantages and disadvantages, it
is best practice to use a combination of the tools in order to complete a PI AF
implementation. Typically work should start with template creation in PI System
Explorer, as it provides the easiest view of PI AF due to the graphical nature of the tool.
Once a base template has been established, it can be used as a guide for creating
other templates in PI Builder for Excel by importing the original template.
If there are many templates to be built, and what the templates should contain is
already defined in an external database, a custom application written using the AF SDK
or a script utilizing PI AF XML Import/Export may be worthwhile in the long run to create
additional templates.
Page 23
Much like creating templates, the best strategy to use for creating elements utilizes
several of the available tools in a combined fashion. When first creating elements,
especially while in the end stage of developing the templates, PI System Explorer is the
best choice for a tool due to the ability to immediately see the results of changes for
testing purposes. The basics of the PI AF hierarchies should also be created in PI
System Explorer since it is easier to visualize the hierarchy. After the hierarchies are
created, the actual elements can be created in bulk in a tool better suited for bulk
creation such as PI Builder in Excel or a custom application.
Building PI AF Hierarchies
Once the PI AF template design and implementation is at least partially complete, users
will begin to implement the actual PI AF elements. As these elements will be built into
hierarchies, it requires some planning on how to build the hierarchy or hierarchies.
There are several key best practices related to building PI AF hierarchies:
1. Follow Standards for Element Hierarchy Structure
2. Start with Placeholder Templates and Elements
3. Build Multiple Hierarchies
4. Host more than one PI AF Database within PI AF to segregate solutions, provide a
sandbox for solution development and process system owners to model their
systems. Developed PI AF hierarchies and solutions can imported to enterprise PI
AF Databases as needed.
Standards for Element Hierarchy Structures
Using a logical hierarchical structure for PI AF elements is an important consideration
when building a PI AF implementation. Best practice is that PI AF should be modeled
based on industry wide standards when such a standard exists and it is possible to
implement. Even when an industry standard is not available, a companywide internal
standard for hierarchical conventions of PI AF elements should be adopted. Some of
the common industry standards that include or reference hierarchical conventions that
are relevant to PI AF include CIM (Common Interface Model), the MultiSpeak
Specification, and ANSI/ISA S95.
If an enterprise master data system for assets exists, such as SAP or Maximo, it can
also be used as a source of one or more hierarchies within PI AF. Using an existing
source for one or more hierarchies within PI AF will help with maintenance, and
enhance familiarity for users.
Adopting a standard helps navigation, interoperability, exchange of data between
applications, and ease of use across sites for users. If the structures of PI AF
hierarchies are laid out according to an industry standard or internal standard, then it
can make it easier to automatically configure the elements and attributes associated
with the structure.
Following a hierarchy structure standard can be particularly advantageous for
customers who already have the PI System deployed across multiple sites, especially if
those sites acquired the PI System individually or were acquired from other
Page 24
organizations. In situations like this, PI AF can be used to present the data to the users
in a consistent navigation fashion across all sites by following a standard within PI AF.
Start with Placeholder Templates and Elements
Starting from scratch to create a PI AF database that covers an entire enterprise-level
company can be a daunting task. One danger is that the creators of the PI AF database
can get so caught up in creating a perfect database that the value return can be greatly
delayed. However, a large part of the effort in creating the PI AF database level is at the
attribute level, both in creating the templates and in instantiating the templates to create
elements.
One option for obtaining value quickly from a PI AF implementation is to create the
element templates and elements necessary for your pilot project immediately, but using
placeholder elements for other parts of the PI AF database. These placeholder
elements can be simply named and have the correct placement in the AF element
template hierarchy of derived templates, but be mostly empty or un-populated in terms
of attributes. The elements created from these templates provide value for several
reasons:
•
They provide an accurate hierarchy for searching or browsing for the fully-realized
templates
•
They already exist in the hierarchy and when fully populated with attributes, will not
require any hierarchy changes or break any existing applications or user patterns
•
They assist in planning the scope of work required to fully realize the PI AF database
Page 25
Figure 11 Using placeholder element templates to plan for future development
As an example, see Figure 11 above. The full regional hierarchy is created in terms of
depth, shown by the region, site, plant, and an asset at the plant. The Tank_421
element representing an asset is fully created with a full set of attributes supported. The
element representing the Horseshoe site, however, contains only a note stating that it is
a placeholder element. Tank_421 can still be found when searching by region, site, or
plant. The contents of the plant element, such as roll-up calculations or overall utilities
usage, can be filled in at a later time.
Build Multiple Hierarchies
One concern that many PI System users implementing a new PI AF architecture have is
the hierarchy chosen for the solution. Although the hierarchy is very useful and an
important part of a well realized PI AF deployment, it is important to remember that the
PI AF database is not limited to a single hierarchy. Through the use of references, new
hierarchies can be created that are better suited to different projects than the original
hierarchy.
Page 26
Figure 12 A simple AF database featuring multiple element hierarchies
Figure 12 above shows a simple database for an electric utility containing two distinct
hierarchies for different purposes. The “Meters” hierarchy is a simple list of all the
meters in a flat structure, useful for easily locating and working with a meter by serial
number or name. Although flat hierarchies are sometimes necessary, especially for
Advanced metering infrastructure (AMI) customers, a flat hierarchy can have serious
performance implications – especially with a large number of elements. The “Feeder
Circuits” hierarchy contains the feeder circuits used by the utility, with references to
each meter powered by that feeder circuit as child elements. The “Feeder Circuits”
hierarchy could be used for rollup calculations or reports by feeder circuit rather than by
meter.
Due to the use of symbolic links within the AF Database for referenced elements, there
is little cost to creating additional hierarchies. Utilizing multiple hierarchies can provide
PI System users the ability to utilize the PI AF database effectively with a solution
custom-tailored to their needs for displays and reports.
Working with existing Elements
Once elements have been created, whether from templates or individually, there are
still a few further options for working with them. New templates can be created from
existing elements, or changed to reflect an existing template. Elements can be
extended by adding extra attributes, or reset back to the defaults for the template.
Page 27
Creating a New Template from an Existing Element
An existing element can be used to create an element template with the “Convert to
Template” functionality of PI AF, which can then be used to create other elements.
Since it is a best practice for all elements to be created from templates, this can be
useful if users of the system prefer to work in a “hands-on” fashion while creating
elements, immediately seeing the results of their changes rather than having to take an
extra step to create an element from a template they are working with. The template
may still need some work to automate tag mapping for PI Data references and other
details, but it involves less effort than starting from nothing.
Changing to an Existing Template
Elements can also be changed to reflect an existing template, whether they were
created from a template or not. When doing so, it is important to note any changes to
the element that will be erased by converting to a template, such as attributes that are
not included in the template.
The most valuable use of this functionality is when changes to the element template
hierarchy are made after elements have already been created. For example, originally a
PI AF deployment uses only a standardized “Turbine” template, and elements are
created from that template. Later the decision is made that there is value in created
derived templates to represent certain manufacturers of turbines. The turbines from that
manufacturer can then be changed to reflect the new manufacturer-specific template
without deleting and recreating them.
Extending Elements
In some cases, the template may not reflect everything an element created from that
template needs to have as an attribute or element category. If the “Allow Extensions”
option is turned on in the definition of the template, additional attributes can be created
and the element can be added to additional categories. This can be very useful if you
have many assets that do not conform to the same templates, but can be a challenge in
terms of future management of the PI AF implementation. Changes to the template can
overwrite changes made when extending the template. Changes to the extensions must
be made to each element instead of the template.
If possible, it is a better practice to create more detailed templates rather than extending
existing templates. It is only best practice to use extensions if it is not viable to create
more templates.
Resetting to Templates
When elements created from templates have been altered after creation, they can still
be reset back to the template. If changes are made to data references that are defined
in the template but have been altered in the element, resetting to the template will force
the element to use the data reference definitions from the template. However, care
should be taken that changes are not unintentionally undone.
Page 28
The “Reset to Template” function is also the best way to force an element that has had
its PI Point data references locked into a certain PI tag reference to reevaluate the
substitution parameters used to configure the data reference.
PI Asset-Based Analytic Templates
Refer to PI System Explorer 2016 R2 User Guide - Asset-Based Analytics for PI Server
for detail discussions for using PI Analysis Services.
•
Use Asset-Based Analytics to replace PI Performance Equation Tags unless Analytic
output PI Tag would require recalculation.
PI Event Frame Templates
Refer to PI System Explorer 2016 R2 User Guide - Asset-Based Analytics and Using
event frames to capture process events for PI Server for detail discussions for using PI
Analysis Services.
•
For hierarchical arrangement of Event Frames the PI Event Frames Generator
should be used.
Notification Templates
Refer to the Notifications User Guide for discussions about Notification Templates.
•
Use Notification Templates where a notification solution will be using an asset
Element Template for multiple assets. Monitoring multiple like assets using a
Notification Template and associated Element Template will enable a scalable
Notification solution.
Page 29
About OSIsoft, LLC
OSIsoft, a global leader in operational intelligence, delivers an open enterprise
infrastructure to connect sensor-based data, operations, and people to enable real-time
and actionable insights. As the maker of the PI System, OSIsoft empowers companies
across a range of industries in activities such as exploration, extraction, production,
generation, process and discrete manufacturing, distribution, and services to leverage
streaming data to optimize and enrich their businesses. For over thirty years, OSIsoft
customers have embraced the PI System to deliver process, quality, energy, regulatory
compliance, safety, security, and asset health improvements across their operations.
Founded in 1980, OSIsoft is a privately-held company, headquartered in San Leandro,
California, U.S.A., with offices around the world. For more information visit
www.osisoft.com.
Page 30