Workbook - Building PI System Assets V2012e - Student

Building PI System Assets
and Analytics with PI AF

Version 2012e
OSIsoft, LLC
777 Davis St., Suite 250
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web: http://www.osisoft.com
OSIsoft Australia Perth, Australia
OSIsoft Europe GmbH Frankfurt, Germany
OSIsoft Asia Pte Ltd. Singapore
OSIsoft Canada ULC Montreal & Calgary, Canada
OSIsoft, LLC Representative Office Shanghai, Peoples Republic of China
OSIsoft Japan KK Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V. Mexico City, Mexico
OSIsoft do Brasil Sistemas Ltda. Sao Paulo, Brazil
OSIsoft France EURL Paris, France
Copyright: 1992-2012 OSIsoft, LLC. All rights reserved.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means,
mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC.
OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, PI Asset Framework (PI AF),
IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual
Logger, PI Event Frames, PI ProfileView, PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports
and RtWebParts are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their
respective owners.
U.S. GOVERNMENT RIGHTS
Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement
and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC.
Published: 25-May-2012
Page ii
How to Use this Workbook

Each Main Heading describes a
high-level valuable learning topic.
Your objectives are skills you can

expect to learn in this segment.
New concepts are presented as level

2 headings.
Throughout the class you will be

presented with questions and
challenges to help you learn.
The majority of your time will be

spent learning new skills via handson exercises, either in small groups
or on your own.
Icons help you identify themes, like

exercises, tools, tips, or
documentation references.
Learning workbooks and other material used in class can be downloaded from
http://learning.osisoft.com/. User manuals and other documentation can be downloaded from
http://techsupport.osisoft.com/ (login with an OSIsoft technical support account is required).
Page iii
Table of Contents
1.
2.
3.
4.
5.
6.
7.
Page iv
PI System Basics ..................................................................................................... 1

1.1
What is a PI System? ..................................................................................... 1
1.2
Tags and Assets The Basic Building Blocks of the PI System .............. 3
1.3
Time and the PI System ................................................................................. 7
PI System Explorer ................................................................................................11

2.1
PI System Explorer Components ...............................................................11
2.2
Connecting to a PI System ..........................................................................13
2.3
Finding Data .................................................................................................17
A Walkthrough of PI AF ........................................................................................23
3.1
Key Features of the PI AF System .............................................................25
3.2
Directed Activity Velocity Terminals .......................................................26
3.3
PI ProcessBook Element Relative Display ................................................38
Modeling and Organizing the Assets ..................................................................41

4.1
Starting to Build a PI AF Structure .............................................................41
4.2
Styles of Approach for Designing Assets .................................................41
4.3
Organizing PI AF Elements in Hierarchies ................................................42
4.4
Solo/Group Exercise Organizing the Tanks for Velocity Terminals ....44
4.5
Where are my Assets? (Part 1) ...................................................................47
Visualizing the Assets Data ..................................................................................48

5.1
Leveraging the PI AF Structure in Visualization Tools ............................48
5.2
PI Coresight Related Assets ....................................................................48
5.3
PI DataLink Element Relative Reports ....................................................50
Adding Analytics to the Assets ............................................................................53

6.1
Identify the Best Solution to Perform a Calculation .................................53
6.2
PI Performance Equations ..........................................................................53
6.3
PI Totalizer Subsystem ................................................................................60
6.4
PI Advanced Computing Engine (PI ACE) .................................................63
6.5
Selecting the Right Calculation Tool .........................................................75
Taking Full Advantage of PI AF Functionalities .................................................77

7.1
PI AF Object Security ..................................................................................77
7.2
PI AF Versioning ..........................................................................................81
7.3
PI AF Advanced Template Design ..............................................................85
7.4
Using the Import / Export Feature in PI System Explorer ........................92
8.
7.5
Solo / Group Exercise Speedys Pizza and Advanced Template Design93
7.6
Group Discussion Where are my Assets? (Part 2) / PI AF System

Project Management ....................................................................................96
Communicating Important Events .......................................................................97

8.1
Introducing PI Notifications ........................................................................97
8.2
Group Discussion Frequency of Alerts ..................................................98
8.3
Directed Activity Installing PI Notifications (Optional) .........................99
8.4
Directed Activity PI Notifications State Groups and States (Global

Configuration) ............................................................................................101
8.5
Directed Activity Triggering the Alerts ..................................................102
8.6
Directed Activity PI Notifications Templates .......................................106
8.7
Formatting the Information to Deliver .....................................................107
8.8
Delivering the Events ................................................................................111
8.9
Adding Contacts ........................................................................................114
8.10 Subscribing Contacts to Notifications ....................................................119

8.11 MyPI and PI Notifications in PI System Visualization Tools ..................120
8.12 Solo / Group Exercise Speedys Pizza Notifications ...........................122
8.13 Acknowledging Notifications....................................................................123
8.14 Group Questions Checking on our Notifications ................................125
9.
Custom Plug-Ins ..................................................................................................126
10.
Final Exercise Modeling a Wind Farm in PI AF .............................................127
11.
Exercises Solution...............................................................................................129
11.1 PI Performance Equations Exercise Solution (Section 6.2.2.1) ............129
11.2 PI Totalizer Exercise Solution (Section 6.3.2) .........................................130
11.3 Speedys Pizza Solution (Section 7.4) .....................................................134
12.
Software Versions Used in this Document .......................................................140
13.
Revision History ..................................................................................................141
Page v
PI System Basics
1. PI System Basics
1.1 What is a PI System?
Objectives
1.1.1
Define the components of a PI System

Draw a diagram of the architecture of a PI System
The PI System Described
The PI System collects, stores, and manages data from your plant or process. You connect
your data sources to one or more PI Interface nodes. The Interface Nodes get the data from
your data sources and send it to the PI Server. Users get data from the PI Server and display it
with client tools.
These are generally the parts involved in a PI System:
PI Server
PI System User
Data PI Interface
Buffer
Source
Table
Lookup DR
PI AF
Relational
Database
Data is collected from the source by the PI Interface program hosted by the acquisition node.
The data is sent to the PI Server (asset data can be contained in the PI AF server). It is read
from the PI/AF Servers by the client tools, like PI ProcessBook.
Page 1
Building PI System Assets and Analytics with PI AF
1.1.2
Architecture of a Typical PI System
Sometimes the architecture can be very simple. Some customers have as few as one or two
interfaces feeding data to a PI Server. Everyone reads that PI Server for their data.
In many cases there are many PI Servers in an organization, aggregating data from lower
levels.
Page 2
PI System Basics
1.2 Tags and Assets The Basic Building Blocks of the PI System
Objectives
Define a PI AF Asset and its components the element and the attributes
Define the four attribute types: Static (None), PI Point, Formula, and Table Lookup
Define a PI Server Tag and the attributes Tag Name, Descriptor, and Point Source.
Define the different data types that can be stored in PI Server Tags
Tags
1.2.1
Assets
What is an Asset?
The PI Asset Framework (AF) Server is a part of the PI System. It contains asset or
metadata that is usually organized according to the assets containing the tags being
monitored. Assets can be helpful to users of the PI System who do not know or are not
familiar with tags. Using assets they can find the data they need without understanding the
technical details of each piece of equipment. Assets are also helpful in finding all of the tags
associated with a specific piece of equipment.
Page 3
1.2.2
Directed Activity Assets Defined

You are invited to watch what the instructor is doing or perform the same
steps at the same time to explore the different concepts presented in this
chapter or section.
Problem Description
Identify the type of data that can be aggregated in a PI AF database.
There are four types of data (Attributes) that can be added by default, list them here:
Type of Data
Page 4
Data Reference
PI System Basics
1.2.3
What is a PI Server Tag?
It is a unique storage point for data in the PI Data Archive. It is simply a single point of
measurement. It has been the traditional unit in the PI Server.
1.2.4
So What Types of Data Can the PI Server Store? (point types)
The answer is pretty much everything. Below are the valid data types:
Across
1.
Discrete value (On/Off, Red/Black/Green)
2.
Floating Point number, 32 bits (single precision)
3.
Integer value, 16 bits (0 to 32767, acc: 1/32767)
Down
2.
Floating Point number, 64 bits (double precision)
4.
Text value up to 976 characters
5.
Scaled Floating Point number, 16 bits (1/32767 times range)
6.
Any Time/Date in the range 1-Jan-1970 to 1-Jan-2038
7.
Integer value, 32 bits (-2147450880 to 2147483647)
8.
Binary large object up to 976 bytes
Page 5
1.2.5
Directed Activity Data Types

chapter or section.
Problem Description
Identify the type of data that might be associated with each of the following:
Example: A temperature sensor:
_Float__
A switch position:
_______________________________________
A Batch ID:
_______________________________________
Operator comments:
_______________________________________
The results of a calculation:
_______________________________________
Memory available on a server: _______________________________________

Current phase of the reaction:
_______________________________________
Current product count:
_______________________________________
1.2.6
Some Basic Point Attributes and Why they are Important to you
Each PI tag has a set of attributes that define it. There are some common tag attributes that
are often used in client tools. Most of these attributes are used for display or informational
purposes.
Tag Name
Unique name of the PI point used to search for tags. Most tags are built using a local naming
convention. Sometimes knowing the naming convention can be helpful in searching for tags.
For example, try to determine what the following tag may refer to:
M03_E1P1_MOTDRV1202_RUNSTAT
________________________________________________________
Descriptor
This is the human-friendly description of the PI Tag. It is often used as a search criteria in
place of the tag name when the tag name is not intuitive. Very often the tag name is some sort
of abbreviation convention and the descriptor is used to capture the full name.
PointSource
All tags are related to their interfaces that collect the data by an attribute called PointSource.
This means that in many cases you can find all of the tags associated with a particular device
by searching for all tags of a certain PointSource. This assumes that the user knows the point
sources in use and that will not be true in most situations.
Page 6
PI System Basics
1.3 Time and the PI System

Objectives
Define the time abbreviations in the PI System.

Define the time expressions in the PI System.
Explain how the PI System handles times zones and DST.
You can use a special syntax, called PI System time, to specify inputs for timestamps and
time intervals. The PI System time uses specific abbreviations, which you combine to create
time expressions.
1.3.1
PI System Time Abbreviations
When specifying a PI System time, you can use specific abbreviations that represent relative
time units and reference times.
Time-unit abbreviations
Abbreviation
Time unit
second
minute
hour
day
week
mo
month
year
To specify time units, you can specify the abbreviation, the full time unit, or the plural
version of the time unit, such as s, second, or seconds. You must include a valid value with
any time unit. If specifying seconds, minutes, or hours, you can specify a fractional value.
You cannot specify fractional values for other time units.
Reference-time abbreviations
Abbreviation
Full
Reference time
N/A
Current time.
today
yesterday
sun
sunday
00:00:00 (midnight) on the most recent Sunday
mon
monday
00:00:00 (midnight) on the most recent Monday
tue
tuesday
00:00:00 (midnight) on the most recent Tuesday
wed
wednesday
thu
thursday
fri
friday
sat
saturday
00:00:00 (midnight) of the current day

00:00:00 (midnight) of the previous day
00:00:00 (midnight) on the most recent Wednesday

00:00:00 (midnight) on the most recent Thursday
00:00:00 (midnight) on the most recent Friday
00:00:00 (midnight) on the most recent Saturday
Page 7
1.3.2
Abbreviation
Full
Reference time
YYYY
N/A
00:00:00 (midnight) on the current day and month in

year YYYY
M-D or M/D
N/A
00:00:00 (midnight) on the Dth day of month M in the

current year
DD
N/A
00:00:00 (midnight) on the DDth day of the current

month
PI System Time Expressions
The previous PI System time abbreviations will be used in PI System time expressions. They
can include a reference time and a time offset, indicated by a direction (either + or -) and a
time unit with a value. PI System time expressions can be:
A reference time only, such as "y"

A time offset only, such as "+3h"
A reference time with a time offset, such as "y+3h".
Reference times, time offsets and their combination are here detailed.
Reference Times
A reference time can be a fixed time, such as "24-aug-2012 09:50:00", or a valid PI System
reference-time abbreviation, such as "t".
A fixed time always represents the same time, regardless of the field or the current time.
Input
Meaning
23-Aug-12 15:00:00
3:00 PM on August 23rd, 2012
25-Apr-13
Midnight (00:00:00) on April 25th, 2013
A reference-time abbreviation represents a time relative to the current time.

Input
Meaning
Current time (now)
3-1 or 3/1
00:00:00 (midnight) on March 1 of the current year
2011
00:00:00 (midnight) on the current month and day in the

year 2011
25
00:00:00 (midnight) on the 25th of the current month
00:00:00 on the current date (today)
00:00:00 on the previous date (yesterday)
tue
00:00:00 on the most recent Tuesday
Time offsets
Entered alone in a time field, time offsets specify a time relative to an implied reference time.
The implied reference time depends on the type of field used where the expression is entered:
Page 8
PI System Basics
Type of
Field
Time
Offset
Start time
-1d
1 day before the current clock time (*-1d)
End time
+6h
6 hours after the start time (Start time +6h)
End time
-30m
30 minutes before the start time (Start time -30m)
Timestamp
-15s
15 seconds before the current clock time (*-15s)
Implied Meaning
Reference Times with a Time Offset

Only one time offset can be included in an expression. Including multiple offsets can lead to
unpredictable results. For example, the following time expressions are not valid:
*+1d+4h
t-1d+12h
When included with a fixed time or a reference-time abbreviation, a time offset adds or
subtracts from the specified time.
1.3.3
Input
Meaning
*-1h
One hour ago
t+8h
08:00:00 (8:00 a.m.) today
y-8h
16:00:00 (4:00 p.m.) the day before today (yesterday)
mon+14.5h
14:30:00 (2:30 p.m.) last Monday
sat-1m
23:59:00 (11:59 p.m.) last Friday
1-jan-11-1d
00:00:00 (12:00 a.m.) 31 December 2010
How does the PI System Adjust for Timezones and DST?
The short answer is: we dont!

When we collect data we convert it to UTC (Universal Coordinated Time), or what used to be
called Greenwich Mean Time (GMT). This means that each day has exactly 24 hours. Any
adjustments for time, such as timezone or Daylight Saving Time (DST), are made by the local
machine clock of the user looking at the data.
So once a year the day will look like it has 23 hours and another 25, but the PI Server never
knows anything other than 24-hour days.
Also, because the clients and PI Server know what timezone they are in, the data can be
viewed with respect to the Server Time or the Client Time. This is determined by a setting
in the client tool.
Page 9
1.3.4
Directed Activity PI System Time

chapter or section.
Problem Description
Determine the "real" dates and times indicated by the PI System times in the table below:
Abbreviation
Answer
* - 30m
T-1d
y+8h
12 8:
Tuesday 2d
Express the following times in valid PI System time abbreviations:

Abbreviation
Answer
Today at 6:30 AM
Monday at 5:45 AM
15 minutes ago
You would like to build a report to show the data for the previous day, what would you use as
start time and as end time?
Page 10
PI System Explorer
2. PI System Explorer
The PI System Explorer, or sometimes referenced as PSE, is the configuration and
management tool for PI AF, PI Notifications and PI Event Frames.
PI System Explorer can be installed on a machine by running the PI AF Client installation kit.
It is also installed as part of the PI ProcessBook version 3.1+ install kit. The client part of the
PI Notifications installation kit will add extra sections to PI System Explorer (MyPI,
Notifications and Contacts), to configure notifications.
2.1 PI System Explorer Components

PI System Explorer consists of these major components:
Page 11
Navigator Panel
PI System objects are grouped into sections displayed in the Navigator Panel. Groups
appearing by default include Elements, Event Frames, Library, and Unit of Measure. When
the PI Notifications feature is installed, MyPI, Notifications, and Contacts also appear in the
Navigator.
Menu Bar / Toolbar
Use these options for such tasks as opening/creating a database, searching for elements or
contacts, applying and checking in changes, setting view options, and so forth. Menus and the
Toolbar are context sensitive and will change and present different options depending on
what section is selected from the Navigator Panel.
Browser
Use the Browser to select the objects you want to work on and display in the Viewer panel.
The Browser displays the PI System objects that have been added to the PI AF database, such
as elements, templates, notifications, etc. Depending on the section selected from the
Navigator Panel, the following will be available from the Browser:
Elements: Elements represent either physical or logical entities in your process.

They can be organized in several hierarchies. An element can be created from a
template, or not. When based on a template, the element derives its initial definition
from it. Later modifications to the template would propagate to its derived elements.
Event Frames: An event frame is any event, defined by a start time, an end time and
a context, containing supporting data. It can be a downtime event, incident event,
material transfer event, equipment maintenance event, batch processing step, or
safety incident, and so forth. A transfer is an event frame that marks movement of
material in discrete quantities.
Library: This is a collection of application or domain information that can be
imported into a PI System. Types of objects that appear in the Library include
Categories, Element Templates, Enumeration Sets, Reference Types, and Tables.
Units of Measure (UOM): The UOM database provides automatic handling of
simple conversions between units of measure for attributes of the same UOM class.
A UOM class is defined by the fundamental dimensions of its measurement.
Examples of UOM classes are Mass, Volume, and Density. The UOM database ships
preloaded with numerous standard unit-of-measure classes and conversion factors.
You can extend these classes by adding new units of measure, as well as new
measurement classes. The implementation of UOM is based on the International
System of Units (SI).
Viewer
This is the primary work area. Create and edit elements, attributes, templates, tables, contacts,
notifications and so forth in the Viewer panel. When configuring attributes through the
Viewer, a configuration panel can also be shown to help modify their configuration.
Palette
The Palette displays templates, data references and contacts that can be associated with
objects being defining in the Viewer. Often the Palette is hidden to optimize screen real
estate.
Page 12
PI System Explorer
Status Bar
Check the status bar after clicking an item in the Browser to see its status. For example, last
modification time, if the object is checked out or if a notification is currently loading.
2.2 Connecting to a PI System

Objectives
2.2.1
Describe the different ways to connect to a PI System.

Connect to a PI AF Server and to a PI Server
Examine your connected credentials.
Create a new connection to a PI Server.
What do we connect to?
During this class, the PI System data will be retrieved mainly using the PI System Explorer.
A connection to PI AF will be needed to access all the metadata related to your assets while a
connection to the PI Server will be required to access the process data from the PI Server
tags.
2.2.2
Connecting to a PI AF Server
To connect to the PI AF Server simply open PI System Explorer (PSE). The default PI AF
Server was set during installation, so you will be connected automatically to it. If a default PI
AF database has already been defined, PSE will connect automatically to it as well. If no
default PI AF database has been defined, a window will pop up and you will be invited to
create a new AF database.
It is possible to see which PI AF server the user is connected to by selecting the
button on the toolbar. The Select Database dialog box will show the current server name in
the top drop-down "AF Server" list.
Page 13
To connect to a different available PI AF server, simply select it from the drop-down AF

Server menu and click on the Connect button.
2.2.3
Directed Activity Examining Credentials when connecting to the PI AF Server

In this part of the class you will perform a learning activity to explore the different
concepts presented in this chapter or section. You may be invited to watch what the
instructor is doing or perform the same steps at the same time. You may play a game
or hold a quiz. Your instructor will have directions.
Problem Description
You may follow along as your instructor shows you how to validate connections to PI
Server(s) and PI AF server(s).
Approach
Open the PI System Explorer and connect to an AF database
Start > Programs > PI System >
To find out the credentials being used for connecting to the PI AF Server, go to File >
Connections
Page 14
PI System Explorer
2.2.4
Connecting to a PI Server
Open the PI SDK Utility:

Start > Programs > PI System >
From the PI-SDK > Connections section, the PI Servers configured on the local machine are
displayed. To validate a connection to a PI Server, simply check the checkbox next to its
name or IP address. The connection information will then be shown if the connection attempt
is a success.
Note: The first time a PI System application is installed a default PI Server is selected. This is why, even
if you have never configured a PI Server at least one will appear in your Connections window.
The user that was used to authenticate on the PI Server will be shown in the status bar and the
connection information section on the right.
Note: The PI SDK Utility is a particularly useful tool to troubleshoot permission issues.
Most user guides have a section describing connection to the PI Server.

Please consult the user guide of your application for more details.
Page 15
2.2.5
Directed Activity Adding New Connections

In this part of the class you will perform a learning activity to explore the
different concepts presented in this chapter or section. You may be invited
to watch what the instructor is doing or perform the same steps at the
same time. You may play a game or hold a quiz. Your instructor will have
directions.
Problem Description
A new site part of your company just had a PI System deployed and you want to be able to
visualize data from their new PI Server and PI AF database.
Your Instructor will give you the credentials to use:
PI Server machine name:
_______________________________________
PI AF server machine name:
_______________________________________
Credentials (optional):
_______________________________________
Approach
Using the PI System Explorer (2012+) application, it is possible to test and add connections
to PI Servers and PI AF servers. This is done through the Servers window accessible from
the File > Connections menu item.
Add a new connection to the PI Server (
specified above.
) and PI AF (
Validate the new connections by selecting the server and clicking on the
Page 16
)
button.
PI System Explorer
Notes: A prompt to enter credentials might be shown when connecting to a PI AF server.

A new connection to a PI Server can also be added from the Connections > Add Server menu item part
of the PISDKUtility > PI-SDK > Connections section.
2.3 Finding Data

Objectives
2.3.1
Demonstrate the ability to search for Elements in PI System Explorer

Demonstrate the ability to search for Attributes in PI System Explorer
Demonstrate the ability to search for PI Server tags in PI System Explorer
Finding Elements and Attributes
Most PI System applications will give the option of searching for Elements or Element
Attributes. Elements are the assets themselves while element attributes reflect tags value or
other associated data. When drilling down to an element, it is possible to inspect its Attributes
for their current value or any other key information.
Searching for Elements
In order to search for PI AF Elements, it is possible to use the top-right search box in PI
System Explorer, visible after selecting the Elements section of the Navigator Panel:
An advanced search can also be performed to retrieve Elements by selecting the Edit >
Advanced Search menu item from the Navigator Panel Elements section:
Page 17
Note: The Search Sub-Elements option should be checked in most cases. In order to perform a search,
fill in the Search Root and Name is fields. The Name is field can make use of the wildcard characters (*
and ?). Alternatively search for elements by simply selecting an Element Template from the Template is
drop-down list.
Make sure the search is being performed on the correct AF Server and Database before clicking the
Search button.
Searching for Attributes
In order to find specific PI AF Attributes and inspect their values, the Attribute Search
window can be used. This window is available from the Edit > Attribute Search menu
item.
In the majority of cases, you will be looking at data contained in elements, just as you would
have looked at tag data.
Page 18
PI System Explorer
Note: The advantage to using elements and attributes over tags is that you can clearly see what other data
is associated with an asset something you cannot determine using tags.
2.3.2
Finding Tags within PI System Explorer
A Tag Search window is available from PI System Explorer in order to find the appropriate
tag to map to a PI Point Element Attribute. This tag search window is accessible from the
Edit > Tag Search menu item or from the search button (
) from the Settings of a PI
Point Data Reference attribute.
Page 19
By default, this window allows searching using a tag name mask. Upon expanding the mask
section, it is possible to further refine the search using additional common tag attributes like
the Descriptor for example, by adding the Description criteria.
Wildcard Characters
Wildcards can be used to create the masks for each tag attribute criteria. More than one can
be used in a single mask and can be placed at the beginning, at the end or anywhere in the
mask.
Use the star "*" to replace any number of characters:
cd*158
CDEP158, CDM158, CDT158
Use the question mark "?" to replace exactly one character like in this example:
Page 20
cd?158
CDM158, CDT158
cd??158
CDEP158
PI System Explorer
2.3.3
Exercise Finding Data

The following questions are intended to reinforce key information presented in this
chapter or section.
Objectives
Use the PI System Explorer searching tools to discover data in the PI System.
Problem Description
You need to familiarize yourself with the principles of searching for data using the PI System
Explorer.
Note: You must use the OSIsoft Enterprises PI AF database (Training Sample) for this exercise. If this
is not available, your instructor will give you alternate details for the exercise below.
Approach
Answer the following questions using the PI System Explorer connected to the OSIsoft
Enterprises PI AF database (your instructor will give you appropriate details):
What is the current head pressure for YUL Pump 009?
______________________
Where is YUL Pump 009 located?
______________________
Note: Hovering over an Element will display its full path in the hierarchy, its location.
How many flow meters exist in Montreal?
______________________
How many flow meters seem to be working at the moment?
______________________
How many tags start with the character sequence "ba"?
______________________
Page 21
2.3.4
Finding Tags with the Common Tag Search Window (Optional)
Tag search is one of the most common functions that users will perform. The common Tag
Search window, available from PI ProcessBook for example, allows three types of search:
Basic, Advanced and Alias.
The Basic and Advanced search allow a user to filter the PI Server tags according to their tag
attributes value by using masks.
Basic search allows searching using common criteria through a defined menu.
Advanced search allows searching using a SQL like syntax.
Note: Alias search uses the PI Module Database (MDB). The PI MDB is no longer used as the main asset
structure for most applications beginning with PI Server 2010. Users should use the PI System Explorer
to find asset data.
Most of the tag searches will be filtered using one of the following two tag attributes or both
at the same time:
Tag Mask
This can also be called Tag Name. If your organization has a convenient naming convention
or you are very familiar with the tags in your plant, then your job of searching will be easier.
However, most people do not have that luxury. Most of us have to use some other criteria.
Descriptor
Descriptor is not a required tag attribute, but it is the one that many people use to find their
tags. For example, a temperature tag might be TC365674A.pv but the descriptor might be
read as Reactor 65 Operating Temp. The downside to searching by Descriptor is that it is
comparing text strings, and so can be fairly intensive on your computer processes.
Note: Some applications like PI Coresight or PI WebParts will use different tag search windows.
However, they will all give the same results given the same search criteria.
Page 22
A Walkthrough of PI AF
3. A Walkthrough of PI AF
An asset can be defined as being a
valuable item that is owned
(thefreedictionary.com). It represents
company locations, sites or equipment, for
example. Those are components everyone
in the company can easily relate to.
PI Asset Framework, or simply PI AF, is a
database of user-configured Process
Object Models called Elements, which
represent the logical components, the
assets, of a process.
These elements form an easily browsable data directory for PI System clients. It gives a
context to PI System data and transforms it into information.
Many sites have PI System data based on instrumentation. Often the configuration
information in the instrumentation is intended for functionality, not quality of information.
There may not have been rigorous tag naming standards. There may be missing descriptions
and/or engineering units. The PI System is often used to integrate information from different
sources and these sources may not have been configured consistently. The PI Server tags are
often built directly from these sources.
Nowadays, many companies want to compare performance of equipment, procedures, and

crews from multiple sites. They want a collaborative work environment between a fleet of
sites which may have a common process. However, their instrumentation systems often have
been installed on different control/automation systems, by different engineering systems,
using different units of measure or using different languages.
Page 23
What the PI Asset Framework (PI AF) can offer is normalization and context: the ability to
compare similar equipment and correct the inconsistencies and diversity of instrumentation
data and configuration. This allows organizations to see the comparability in processes from
dissimilar instrumentation and control systems and allows a more intuitive, organized access
to process data.
A PI System that thinks more like you do.
Page 24
3.1 Key Features of the PI AF System

Scalability
Up to 10 million assets with references to up to a hundred PI Server tags across

multiple PI Servers.
Hosted in 32-bit or 64-bit Microsoft operating systems.
Compatible with Microsoft SQL Server Express and up to Microsoft SQL Server
farms with mirroring.
Usability
Flexible hierarchy and powerful search and indexing support for finding data.
Integrated easy-to-use calculations and lookup tools.
Powerful templates support discipline and maintenance for relationships and

calculations.
Integrated to our visualization tools (PI Coresight, PI DataLink, PI ProcessBook

and PI WebParts).
Microsoft integrated and validated Windows security.
Extensibility
Supported by PI Notifications alerting and event filtering application.
Supported by PI OLEDB Enterprise and PI Web Services query capabilities with

flexible SQL and XML standards.
Published AFSDK (PI AF) and ANSDK (PI Notifications) with training and support
on OSIsoft vCampus.
Customers and partners can create custom calculations (data references) and filtered
data recipients (delivery channels) with Microsoft Visual Studio (C# or VB).
Reliability
PI AF configured for High Availability (HA) assures the PI AF directory and

information is always available.
Compatible with our proven PI Server HA technology.
Worldwide quality technical support.
Disciplined store for your enterprises process knowledge offering versioning,

backup, detailed integrated security and record locking collaboration.
PI Asset Framework (PI AF) is not a special purpose add-on to the PI Server. It represents the
best way to access all PI System data for users and applications. It is a core component of the
PI System today and will become the core component of the PI System of tomorrow.
Page 25
3.2 Directed Activity Velocity Terminals

directions.
Activity Objectives
Create a PI AF element with attributes using PI Point, Table Lookup, and Formula
data references.
Define the value types and units of measure for attributes in the element and in the
element template.
Create and populate a new PI AF table.
Create a PI AF element template from an element.
Extend the template with new attributes and see how these affect the original
element.
Create a PI AF enumeration set and use it for data validation in a template.
Create an element from a template.
Create more elements with the PI AF Builder add-in.
Problem Description
You are working for Velocity Terminals, a chemical company producing various chemicals.
As part of the assets, the company has some storage tanks located in different countries. You
are looking for a way to monitor the tanks activity using the PI System.
Approach
Follow the instructor as he performs steps to create various PI AF objects that will lead to the
creation of a single PI ProcessBook display to monitor all of Velocity Terminals tanks.
You will later be working on your own. For now, follow and listen closely to the information
in this initial exploration of the PI Asset Framework.
Page 26
3.2.1
Creating PI AF Databases
Open PI System Explorer (PSE) from the start menu and, if necessary, connect to the PI
System (PI AF server) that your instructor indicates.
If you are in an OSIsoft training room, use the existing Training AF database (may be
another name; must be the one where the <PI Server Name> ModuleDB element resides) to
create the Velocity Terminals structure.
If you are sharing a common PI AF server with other students, create a new PI AF Database
in PI System Explorer named Velocity Terminals_<FirstInitial+LastName>.
If PSE opens normally, choose File > Database. If PSE does not open and a pop-up appears,
click on the Select option to get to the Select Database window, as shown below. Right-click
anywhere in the list of databases and choose New Database or click on the New Database
button on the toolbar. Name the database as specified above (ex.: Velocity Terminals_JDoe).
Make sure the database is selected in the list of available databases and click the OK button
or double-click on it to open your database.
About Databases
For convenience, each participant will have a separate database. In practice, it may be better to build
fewer, larger databases. That is because references in PI AF only work within the same database; it is not
possible to compare elements and values across databases. Companies may find it better to organize their
database at the business unit level and not the plant level. Just remember: The database is a universe in
PI AF, and thus it cannot think something exists outside of it.
The Configuration database
As an administrator, it is possible to view another database available by default. That database is called
Configuration. Do not use this database to organize your assets as it is only shown to administrators, and
used to store configuration data for PI System software.
Page 27
3.2.2
Creating PI AF Elements
Make sure the Elements section is selected from the Navigator Panel and create a new
element called Tank01 (this mean the Tank01 element will not be created under the <PI
Server Name> ModuleDB element).
From the Browser, right-click on
and select New Element or click the
button from the toolbar and select <None> as the element template.
Under the General tab from the Viewer, change the name of the element to Tank01.
About Elements
The element is the basic building block of PI AF. It is an organizing feature, and can be thought of like a
folder. It has relationships with other elements and has search characteristics, but it doesnt hold dynamic
or static values. Elements are generally organized hierarchically, though this is not required.
Elements represent physical or logical entities in your process: equipment, lines, products, systems,
organizations, sites, and even events like batches or transfers. They can be based on a template or created
without one, although later sections will emphasize the fact that templates are highly recommended.
Elements in a PI AF database must be uniquely named to their path. An element named Transformer
can exist under an element named System A while another element named Transformer can exist
under System B. However, two elements named Transformer could not coexist under the same
element System A. If it is possible, there is some sense in uniquely naming all elements regardless of
their position in the hierarchy.
The name of an element can contain any character except control characters or any of the following ( ; ?
` ' " \ | {} [] ).
3.2.3
Creating PI AF Attributes
From the Viewer, select the Attributes tab and then right-click on the white space to select
New Attribute to define attributes or click the
button from the toolbar.
Three (3) attributes will be created for Tank01. Start configuring the attributes using the table
below:
Page 28
Attribute Name
Default UOM
Value Type
Value
Capacity
US gal (Volume)
Double
20,000
Level
% (Ratio)
Double
N/A
Volume
m3 (Volume)
Double
N/A
About Attributes
Attributes must also be uniquely named along their path within the element they belong to. Attributes can
have a configured constant value or can get a value dynamically from a Data Reference.
Attributes will generally be assigned units of measured (UOM). These UOM are organized into
convertible/comparable classes. The Default UOM configuration field defines the default unit of measure
to use to display the attributes values. This default unit of measure does not need to be the same as the
instrumentation. Later sections will show how this can be used and configured using data references.
The Value Type field for the attributes defines the format the value itself will have. The various types will
be familiar to those with programming experience. In general, value type Double can be used for most
analog/numeric values and value type String for everything else. Other types may also be useful in certain
circumstances. For example, a value type of Boolean allows either a 0 or a 1, which is represented as
False (0) or True (1).
Configuration Item attributes (identified by this icon ) are the ones defining the element or asset. An
example would be an attribute storing the serial number of a pump; changing the attributes value would
mean the pump would have been replaced by a new one. Checking the
check box for
an attribute indicates that a change in value will result in a revision change to the element. A
configuration item attribute is intended to be configured by a user or administrator of the PI System
database and not be set programmatically or by a data reference, it should thus be cleared for attributes
with values that will change with the process.
With the Attributes tab selected, select the Level attribute and change its data reference to PI
Point and then click on the Settings button.
Select the correct PI Server at the top and enter BA:LEVEL.1 (or use the tag search (
and click the OK button.
))
Select the Volume attribute and from the Configuration Panel, select the Formula data
reference. Clicking on the Settings button will bring up the Formula Configuration window.
Page 29
Note: When configuring a Formula data reference, it is required to explicitly set the units of measure
(UOM) when units conversion are necessary. Units of measure can be explicitly set for the parameters as
well as for the result. Do this from the parameters configuration section by choosing the appropriate
UOM from the Unit of Measure drop down. Do this also in the Result section at the bottom left.
Use the formula data reference to calculate the volume using the level (%) and the capacity
(US gal). Use the new button ( ) to add Parameters to use in the formula. Expand the list of
functions from the Equations section ( ) to pick the operators/functions to use in the
formula. Make sure to explicitly set the units of measure for the Capacity, the Level and the
Volume from the Formula Configuration window.
Press the
button on the toolbar and then the
the menu: File > Check In to save these changes.
button or select it from
About Saving Modifications

The PI AF Server uses a sandbox concept for modifications. It holds the changes until they are published
to the end users. When
is pressed, the changes made in your active session are published as
the single public version that others can now see.
Until you check in, other users will not be able to edit a checked out object. The checked out icon will be
shown (
). As for the user currently editing an object in PI AF, the object icon will signify some
changes were made to the object, that are not yet published (
). The Undo all changes to the
Database button ( ) next to the check in button will reset your sandbox changes and set your sandbox
back to the database state as it was before you started working.
Page 30
3.2.4
Creating PI AF Tables
Create a new PI AF table and name this table Material Properties. Building the table is similar
to building a table in other programs which have simple table building
capabilities.
In the PI System Explorer, first navigate to the Library section from the
Navigator Panel. Right-click on the Tables item to select New Table, or
click on the
Under the General tab, change the name of the table to Material
Properties.
Select the Define Table tab and add two (2) rows by right-clicking in the
blank area to select Insert or by selecting the starburst Insert a row button (
right-hand side. Define the table as follows:
) on the
Column Name
Value Type
Unit Of Measure
MaterialID
String
<None>
Density
Double
kg/m3 (Density)
Under the Table tab, enter the following fictional chemicals:

MaterialID
Density
AQ4500
2100 kg/m3
HC1500
3422 kg/m3
WX1200
8943 kg/m3
About Tables
Tables are held in the PI AF database to provide contextual information through the Table Lookup data
reference. Tables can provide information about the equipment or process entities or they can be used to
store tag names or other configuration information to be used in PI AF.
Tables can be created internally (like in this exercise), imported from an external relational or tabular data
source, or linked dynamically to an external relational data source. In this way, Tables can look up
information in a maintenance, production planning, or equipment database and expose it in PI AF for use
by the PI client applications.
3.2.5
Creating PI AF Enumeration Sets
From the Navigator Panel, select the Library section. Right-click on the Enumeration Sets
item to create a New Enumeration Set, or click the
button from the
toolbar and name the new set MaterialID. Enter the material IDs from the table below as the
names of that set:
Page 31
Value
Name
AQ4500
HC1500
WX1200
to save newly created objects to the PI AF database.

About Enumeration Sets
An enumeration set is an ordinal list of sequential integer values which are mapped to name. It allows PI
AF attributes to refer to a common term instead of a number. This is analogous to the PI Server digital
state sets used by Digital tags. It is not needed to rebuild the digital state sets or maintain them in PI AF.
Enumeration sets are just a meaningful way to display information, perform data validation and maintain
data consistency across the AF structure.
3.2.6
Creating PI AF Element Templates
Select Tank01 from the Elements section in the Navigator Panel and right-click on it to
select Convert > Convert to Template (note this does not delete or change the element, but
does set it to a new template).
Locate your new element template from the Library > Templates > Element Templates
section and change its name to Tank. Under the Attribute Templates tab, add three (3) new
attribute templates by clicking the
Attribute Name
Default UOM
Value Type
Data Reference
Density
kg/L (Density class)
Double
Table Lookup
Mass
kg (Mass class)
Double
Formula
Product
<None>
Enumeration Sets >

MaterialID
<None>
Configure the Table Lookup data reference for the Density attribute using the following:
Table
Result Column
Where
Material Properties
Density
MaterialID = @Product
Configure the Formula data reference for the Mass attribute using the following:
Parameters
Page 32
Equations
Variable
Attribute
Unit of Measure
Density
kg/L
Volume
D*V
the changes. Go back to the Elements section, select the Tank01 element and
look at its attributes. Pick any material for the Product attribute enumeration list and then
click on
. Note the value of the Density attribute.
Note: Elements should always be created from a template, even if at the moment of creation only one
asset would make use of that template. This ensures consistency in the creation and management of PI AF
elements.
However, for elements that would act only as organizing assets (folders) and that have no attributes, a
template is not required.
3.2.7
Creating New Elements from Templates
Create a new element called Tank02 based on the Tank element

template and assign to its attributes the values found in the table
below.
Attribute Name
Data Reference
Value
Capacity
<None>
30,000
Level
PI Point
SINUSOID
Product
<None>
HC1500
(Tank01 should have AQ4500)
Commit these changes to the PI AF database (
).
The Power of Templates

The term template suggests a cookie-cutter way to create new objects with consistency. PI AF element
templates do this and more for elements. They ensure similar equipment stay alike in PI AF.
When changes (in default values, attribute definition, or structure) are made to the template, the elements
created using that template are automatically updated.
However, if changes were made at the elements attribute level, a change to the attribute template will not
replace the modifications made by the user. That is, if you uniquely set values or configuration strings in
the data references of unique elements attributes, they will not be overwritten by a modification of those
Page 33
attributes default values at the element template level. Attributes derived from a template have a Reset to
Template option on their right-click menu to remove any unique value or configuration string definition
for this attribute and reset it to the default values established at the template level.
This allows to create, but also to maintain many elements with the template, knowing that changes are
applied to all appropriate related elements.
Templates also allow the AF database to grow into an analysis tool when ready to do so. It is possible to
add calculations and analytics into the template at any time since that information will be propagated to
all of the elements automatically. It is not necessary to have the complete analysis at the time of template
creation.
In this example we created a template from an existing element, but it is possible to go directly to the
Library to create a new template by right-clicking Element Templates and selecting New Template or by
clicking the
PI AF Templates have an
check box under the General tab. Checking this box allows
for additional attributes to be created at the element level, outside of the element template. Obviously, this
will no longer guarantee all elements have the same set of attributes.
Templates may be the most powerful and unique feature in PI Asset Framework. Very few applications
would not benefit of the use of templates when building PI AF elements.
3.2.8
Moving Elements under a Parent Element
Elements can be moved under other elements (then called Parent Elements) in order to
represent a logical hierarchy to be used by your applications.
Tip
When dragging and dropping elements under a parent, make sure that
parent element was first saved to the database (check-in)! If the
parent element was not checked in before moving another element under
it (child element), the move operation might cause the child element to
be deleted as PI AF doesnt know the parent element yet exist.
Create a new element not based on any template that will be named Montreal. Check-in the
changes.
Select both tanks using the mouse and drag and drop them while holding the Shift key on
the keyboard in order to move those elements under the Montreal element so they become
child elements of that location.
Select the Parent-Child Reference Type for each tank element. The different reference
types will be discussed in the next chapter.
Moving Elements Around
You can move elements around in the Viewer using the mouse and keyboard. This will result in creating
an element reference, or making a copy of the element or simply moving it.
Page 34
If you simply drag an element under a parent element, with no key pressed, a link or Element Reference
will be created, and the element will now exist in two places in the hierarchy. In this case, the element
icon has a link designator (
), like in the case of a file shortcut.
If you drag the element under a parent element while pressing the Ctrl key, a copy of the original element
will be created under that parent element. The original and the copied elements will not be linked.
If you drag the element under a parent while pressing the Shift key, the element will be moved under that
parent element.
3.2.9
Creating PI AF Objects in Bulk Using the PI AF Builder Add-in
PI AF Builder is an add-in to Microsoft Excel 2007 and later allowing rapid creation and
edition of AF objects in bulk.
Open Microsoft Excel, and select the PI AF Builder ribbon menu. Click on the AF
Database button and connect to your AF Server and personal database.
Import the tank elements from PI AF. To do this, select Elements > Find Elements from the
PI AF Builder ribbon menu, then select the Tank Farm as the root and/or the Tank Template
to search and find both tanks (make sure to check the Search Sub-Elements check box).
Select only to import the Template configuration of the element.
Page 35
Next, use the Transposed Attributes button part of the same window to import the
configuration and value of the Capacity, Level and Product attributes only.
Once you click OK, the objects imported from PI AF on the spreadsheet should look like the
following:
Note: In the screenshot above, there is an equal sign (=) in front of the Level attribute value (attributes in
column headers are prefixed by the pipe ( | ) character) in the form of =\\Server\Tag. Nothing must be
put in front of a static value attribute like the Capacity (value of 20000). The equal sign indicates a
configuration string for the attribute instead of a static value. Because the equal character is also used by
Excel for formulas, a single quote/apostrophe ( ' ) is inserted before it.
Also note the x in the Selected(x) column A that indicates if PI AF Builder needs to process this row or
not and apply those modifications to the element or attribute(s).
Use Excel functionalities (find-replace, Ctrl+H) to create records for two (2) additional tanks
(Tank03 and Tank04). Make sure the PI Server name is correct for the Level attribute
definition as well as the Product name matches one of the valid material from the Material
Properties PI AF table.
Page 36
Name
|Capacity
|Level
|Product
Tank03
10000
=\\PI Server\SINUSOIDU
HC1500
Tank04
10000
=\\PI Server\CDEP158
WX1200
Note: In this example we used the Transposed Attributes option of the PI AF Builder. Not making use
of this feature will result in each element and attribute to be imported in a different row instead of having
one row to represent each element along with its attributes. In the case where imported elements are tied
to the same template, the Transposed Attributes method is far superior.
The records are now ready to be exported to PI AF to create those two additional tanks using
the Export button from the ribbon menu ( ).
Confirm your work by going to PI System Explorer > Elements and pressing the
button or the F5 key on the keyboard.
Note: To rename an element, simply right-click on it in PI System Explorer > Elements and select
Rename. This can also be achieved by using the NewName column with the PI AF Builder in Excel.
Because PI AF keeps relationships using the elements GUID, elements can be renamed without breaking
relationships between elements or elements and their attributes or their templates. GUIDs are also used in
the relationships of elements in data references as well.
3.2.10 PI AF Units of Measure (UOM)

The units of measure feature (UOM) allows automatic unit conversions in client applications.
For example, suppose an AF attribute has a UOM of meters. A PI ProcessBook user who is
viewing that attribute value can choose to view the value in different units, such as feet. PI
AF automatically converts the data from meters to feet.
The Units of Measure (UOM) are available to all PI AF databases in the server. In other
words, the UOM defined in one PI AF database maybe used in any other PI AF database.
From PI System Explorer > Unit of Measure section, new classes can be
created to represent additional units of measure not present in PI AF by
default. In order to create a new unit of measure, either add it to an
existing unit-of-measure class or first create a new class.
Create a new UOM class by selecting the

button from the
toolbar or right-click in the Class listing and select New Unit-of-Measure
Class. Populate the fields as follow:
Name
Canonical UOM
Canonical UOM Abbreviation
Page 37
Data
byte
byte
Select the Data UOM class from the left side and create new units of measure using the
button from the top toolbar. Populate the fields as follow:
Press the
Name
Abbreviation
Reference UOM
Method
kilobyte
KB
byte
Type = Simple, Factor = 1024
megabyte
MB
kilobyte
gigabyte
GB
megabyte
button to save the new units of measure.
Note: From any database of this PI AF system, it will now be possible to make use of the new Data units
of measure class.
3.3 PI ProcessBook Element Relative Display

Open PI ProcessBook and use the File > New menu to create a *.PDI (standalone display
document) named Tank Monitoring.
From the View menu, select Element Relative Display and note the panel which appears on
the left. There is a PI System Explorer icon ( ), select it and select your AF Server-AF
System-Database from the resulting Element Search dialog. Make sure to check the Search
Sub-Elements check box and then click the Search button and select the four (4) tanks. The
tanks will be added as Elements of Interest.
Select from the menus Tools > Build and then Draw > Symbol Library. Now, from the
drawing area of the screen, add a new symbol from the symbol library by dragging out a
square of approximately 1 inch on the screen, as shown below.
Page 38
This brings up the Symbol Library window where a tank symbol will be selected and added
to the screen from the Tanks category.
Make sure you are still in Build mode (else click again on the hammer ( ) icon) and add a
Bar next to the tank to represent its level by selecting Draw > Bar and then dragging out a
bar shape on the screen. From the Define Bar window that shows up, open the pull/down flyout menu next to the Tag Search button and select Element Relative.
The selected tank should appear with its attributes. Select Level and use the down arrow to
push it into the Selected Attributes list, then click
OK.
Add a dynamic value by selecting Draw > Value
and clicking just below the tank symbol on the
drawing area. Still using the Element Relative
option, select the Level attribute again.
Add a trend by selecting Draw > Trend and
dragging out a rectangle the size of the trend
wanted. Still using the Element Relative option,
select the Mass attribute to be shown on that
trend.
Add another Value symbol above the tank, but
this time select to Add Element Name by
clicking this button at the bottom of the Select
Attributes window (refer to the picture on the
right).
Page 39
(Optional) Add two other value symbols to display the Capacity and the Volume attributes.
Switching to Run mode from Tools > Run, select a different tank from the left panel to
confirm the PI ProcessBook display is now element relative, meaning the information shown
depends on which tank is selected on the side pane. Leveraging the PI AF structure and
templates allows creation of reusable PI ProcessBook displays to represent similar
equipment.
Note the Mass attribute shown on the trend symbol has a history displayed, even though the
attribute was created couple moments ago. The values are not actually stored in the PI Server,
but historical values can still be displayed as they are calculated on demand.
PI AF has the power to transform PI Server data into information.
Page 40
Modeling and Organizing the Assets
4. Modeling and Organizing the Assets

4.1 Starting to Build a PI AF Structure
In a PI AF database, assets can be organized or structured into hierarchies. According to its
definition, a hierarchy is a system of persons or things arranged in a graded order
(thefreedictionary.com). Logical hierarchies of assets or people are common in companies
from any industry. It is used to know the place/location of each entity in the company. Since
the PI AF system is probably not the only enterprise system in your company, other systems
in place might already make use of assets hierarchies (maintenance system, etc.).
Those systems will often have an option to export the hierarchy information into a flat file
(.csv, .txt, .xml, etc.). The content of this file can then be opened in Microsoft Excel and be
used as a starting point to build the hierarchy in PI AF using the PI AF Builder add-in.
Note: The whole company does not need to be modeled in PI AF before being able to get value out of it.
In fact, the PI AF structure build-up is often project-driven. This means a small structure containing your
pumps might be built for it to be used in PI ProcessBook displays. As there will be more and more
applications making use of PI AF, the structure will eventually grow to include more and more of your
assets.
However, it is still a good thing to define the various hierarchy levels that will be represented in the PI AF
structure (divisions, locations, production lines, process, etc.) before gradually adding the assets to that
hierarchy.
4.2 Styles of Approach for Designing Assets

There are several styles for designing assets in PI AF.
Note: Even if the following approaches will end up giving a complete model, there will always be more
information to add in the future. That is fine and is in fact a relief, since it means the PI AF model does
not need to be perfect and complete the first time.
4.2.1
Bottom-up
Since often a PI Server is already in place, one approach is to group all tags by asset, and then
attempt to group the assets by similar PI Server tags. These similar object groups become
PI AF Element Templates, and the objects become PI AF Elements. Any foreign data thats
available is imported. Then, analytics that may seem useful are added, and finally consumers.
The bottom-up approach has the advantage of being a clear, reality-based path to follow. The
PI Server tags are known and analytics can be added on top of them.
However, a clear disadvantage is this approach lacks vision. This approach does not
guarantee the result to be useful.
Page 41
4.2.2
Top-down
Another approach is to start by asking theoretical questions: What is trying to be achieved?

What do the consumers need from PI AF? What are the business requirements? What
analytics will be desirable? What sort of foreign data might be useful?
After answering these questions, the Element Templates and Elements can be sketched, and
organized in a hierarchy. Then, AF Attributes are added for the desired data points, even if
the source for the data is not known yet. The first step is simply to add the placeholders for
that data, i.e. unconfigured attributes. If these attributes are confirmed to be the ones needed,
then the analytics can be added, the PI Server tags mapped, and the model fully implemented.
This top-down approach has the advantage of allowing to plan for the usefulness of the PI
AF model. Confidence that the model will be well-designed and reusable is assured. This
advantage cannot be understated and, usually, outweighs all of the following disadvantages.
However, one disadvantage is that the design can drift away from reality and be incredibly
hard to implement, yet have little benefit over an easier alternative, which is hard to tell
beforehand. Another disadvantage is that, implicitly, much of the available raw data that isnt
necessary will be ignored from the model.
4.2.3
Design top-down, then work bottom-up
The preferred approach will be a compromise: begin top-down, identifying goals and trying
to identify a good design for everything, but quickly move to a mix of this theory and
bottom-up experimentation. If a piece of data looks useful, add it to the model, because its
rarely a mistake to do so.
This planned approach combines the advantages of top-down and bottom-up: assurance that
the model will be useful, yet a good grounding in reality and completeness during
construction. The steps of this approach are:
Define what the assets are.

Design the element templates and inheritance tree.
Add attribute templates.
Configure the attributes to point to foreign data or PI Server tags, all with good units
of measure.
Add calculations/analytics.
Test the model using consumers (sample reports, notifications, displays, etc.)
4.3 Organizing PI AF Elements in Hierarchies

Once a hierarchical structure has been built in PI AF and the assets have been defined, it is
possible to organize the assets underneath that structure. Depending on the type of hierarchy
that was created, the equipment will be organized by geographical locations, by enterprise
divisions, by type of equipment, etc. However, having one kind of asset organization does not
imply another type cannot also be used in the same PI AF database.
PI AF has this ability to let the system manager organize his assets in multiple different ways.
It is then possible to have different views on the same information, but without duplicating
that information. This can be done using Element References ( ).
Page 42
4.3.1
Creating Children Elements
Elements can be structured to be children (i.e. hierarchically subordinate to another) of other

elements, called parents. In PI System Explorer, right-clicking on an element, and selecting
New > New Child Element will create a children element. A template must be chosen, or left
to none, and the hierarchical relationship must be selected:
The default Parent-Child relationship is usually used.

4.3.2
Selecting the Appropriate Reference Type
By default, three (3) reference types exist in PI AF between a parent and a child element.
Parent-Child
With a Parent-Child reference, the child, like in real life, can have multiple parents. The child
element can thus be part of multiple hierarchies. This reference type is best suited for assets
belonging to multiple views of the same information. For example, Pump01 can be organized
according to its location, Site ABC, or according to its equipment type, a pump.
The child element will only be deleted when its last parent is deleted. Furthermore, ParentChild element references can exist on their own: deleting the "master" ( ) Pump01 element
does not delete the other Parent-Child element references.
Weak Reference
A Weak Reference is qualified as having a "weak" reference strength. On the opposite,
Parent-Child and Composition are considered "strong" references. Think of the weak element
reference as a Parent-Child element reference, in that it allows Pump01 to be organized into
different views, except that a weak referenced element cant exist on its own.
The child element will be deleted as soon as no more "strong" reference exist. This can be
useful if you want one view of your assets to be a "master" view. For example, the master
Page 43
view would be the one by site and would contain the elements as Parent-Child, while other
views, like the Pumps one, would reference the elements using a Weak Reference. Deleting
the element in the "master" view would remove it from all other structures automatically.
Composition
The Composition relationship binds two elements together so that whenever one is changed
or calculated, the other is too. Deleting the parent element deletes the child as well. For
example, a valve attached to a tank may be represented as a separate element in PI AF, but is
really a part of the tank asset and cannot exist outside of it. Removing the tank from a site
removes the valve as well. Typically, an element having a Composition relationship with its
parent would not be referenced elsewhere by itself.
4.4 Solo/Group Exercise Organizing the Tanks for Velocity Terminals

This is a solo or group activity that is designed to maximize learning in a specific
topic area. Your instructor will have instructions, and will coach you if you need
assistance during the activity.
Exercise Objectives
Review the PI AF Builder and build some additional elements.

Create parent elements to build a hierarchy.
Organize the elements into hierarchies with drag & drop.
Problem Description
Now that part of your equipment (4 tanks) were defined and organized under their location
(Montreal, Canada), you now want to model and organize the tanks for the other locations of
your company called Velocity Terminals:
Montreal, Canada
Tokyo, Japan
Sydney, Australia
You also want the ability to view the companys tanks according to the division they are part
of, receiving or distribution. After searching on the enterprise portal, you end up finding the
following documents.
Page 44
Page 45
Approach
Model the extra tanks in PI AF using the VelocityTerminals_Tags&Assets.xlsx worksheet.
Note the PI Server tags in Sheet1 (Tags Ex 4.6) (your instructor may ask you to build these
tags and walk you through building them using the PI Tag Configurator add-in to Microsoft
Excel).
Note: The PI Tag Configurator Excel add-in is used as an Import (from the PI Server) and Export (to the
PI Server) tool to mainly create or edit PI Server tags. It can be added by going to File > Options > Addins > Excel Add-ins and then browsing for its location: %PIHOME%\SMT\PITagCnf.xla (where
%PIHOME% is usually C:\Program Files (x86)\PIPC).
Copy the tag names and prefix them with '=\\<PIServerName>\ to obtain the following under
the |Level column of Sheet3 (Assets):
'=\\TRAINING01\TANK05LI.PV (note the apostrophe before the equal sign)
Use PI AF Builder Export function to create the new elements in your PI AF database.
Using PI System Explorer create new elements, not based on any template, to model the
locations and divisions. Use the drag and drop techniques discussed previously to organize
the tanks in their appropriate hierarchies.
Note: Make use of Element References. Use Parent-Child references under the locations and Weak
references under the divisions.
Page 46
4.5 Where are my Assets? (Part 1)

The following questions are intended to reinforce key information, or to discover a
new insight. Your instructor may choose to have you try to answer the questions on
your own or have the group answer them together out loud.
Questions
Based on this experience with PI AF and your experiences with your process information
and/or PI Server in your work life, perhaps a few questions are suggested:
1.
Where would I find the assets, equipment, logical process units to form into elements in my facility?
2.
How many (estimate) assets would I likely need to get started using PI AF? How many templates
would be required to reflect the commonalities?
Page 47
5. Visualizing the Assets Data

5.1 Leveraging the PI AF Structure in Visualization Tools
The PI System has many visualization tools, each one having a different purpose. Part of this
section, four (4) visualization or client tools will be looked at:
1.
2.
3.
4.
PI Coresight: Modern and intuitive Web visualization tool allowing ad hoc analysis through rapid
screen creation.
PI DataLink: Microsoft Excel add-in allowing importation of PI System data on a spreadsheet for
integration with Excel features and production of reports and/or analysis.
PI ProcessBook: Process representation tool allowing monitoring through trends, values or charts
displaying real-time and/or historical data.
PI WebParts: Set of interactive Web Parts for Microsoft SharePoint allowing enterprise-wide
sharing of PI System real-time information.
Through each one of those tools, PI System data can be retrieved. Data organized in PI AF
can thus be easily found and used to create displays, screens or reports. If those documents
are applicable to a specific asset, because of the templatized nature of PI AF elements,
these documents will also be applicable to all similar assets. Similar assets are the ones
coming from the same element template.
In the next sections the concept of Element Relative displays, screens or reports will be
introduced to demonstrate how the PI AF structure can be leveraged by the various PI System
visualization tools.
5.2 PI Coresight Related Assets

PI Coresight makes use of an efficient search engine to let you browse through the
organizations AF structure to rapidly find the information you are interested in. As you begin
looking and analyzing some data, PI Coresight will find related information that might also
be of interest to you.
Page 48
Visualizing the Assets Data
The Related Assets feature gives you the list of asset coming from the same element
template as the one(s) you are currently looking at.
5.2.1
Directed Activity PI Coresight Related Assets

Activity Objectives
Have an overview of PI Coresight functionalities.

Witness an asset swap performed on a PI Coresight screen.
Approach
If a PI Coresight server is accessible, watch and follow the instructor as he creates a new PI
Coresight display to analyze Tank01 data and later make use of the Related Assets feature to
reuse the same screen for the other tanks part of the PI AF system.
If a PI Coresight server is not accessible, watch the main screen as the basic concepts of PI
Coresight, as well as the Related Assets feature, are explained in a short video
(http://www.youtube.com/watch?v=bUOW1yVBLnk)
Note: The http://coresighttraining.osisoft.com Web site can be used to demonstrate PI Coresight. You can
connect using pischool\Student01 with password student.
Page 49
5.3 PI DataLink Element Relative Reports

5.3.1
PI DataLink 2013 New Possibilities
With PI DataLink 2013+, it is possible to create reports that will leverage the PI AF model,
allowing for reports to be reusable across similar assets. This version moves away from PI
AFs predecessor, the PI Module Database, to fully embrace the power of the Asset
Framework. PI DataLink 2013+ also benefits from the new integrated search engine,
allowing to search for tags and assets all at once.
5.3.2
Building Drop-down Lists of PI AF Elements
Using this search window, it is possible to automatically generate drop-down lists in Excel to
allow this report to be applicable to multiple similar assets. In order to achieve this, the
following steps are needed:
1.
2.
3.
Select the cell where you want to have the ability to choose an asset from a drop-down list.
From the PI DATALINK ribbon, click on the Search button.
Use the tools to navigate to a top-level element, parent to all the elements you would like to add to
the selection list (the top-level element can be of a higher level than the direct parents to include all
required assets, for example we could navigate to the Locations element within our Velocity
Terminals structure).
Page 50
Visualizing the Assets Data
4.
5.
6.
7.
In the search bar, type in a mask for an attribute that is common to all assets you want populated in
the list (for example Level or Vol*).
Set the Root path length to the Maximum using the slider.
Select Drop-down list for the Insert root paths in option.
Select all results from the result window and click OK.
5.3.3
Solo / Group Exercise Building a Generic PI DataLink Report

Exercise Objectives
Experiment PI DataLink and its Asset Relative feature.

Follow the steps needed to create a report applicable to similar assets.
Problem Description
You have a PI ProcessBook display to monitor the current status of your tanks. However,
every day you need to produce a small report to present the hourly averages for the level and
Page 51
mass present in your tanks for the previous day. Microsoft Excel and the PI DataLink add-in
seem the logical tools to use since all of your tanks are already modeled in PI AF.
Approach
Use Microsoft Excel and PI DataLink to create a one-page report showing the hourly
averages for the Level and Mass attributes for your Velocity Terminals tanks. Make sure to
use a drop-down list to make this report reusable for all tanks.
Hint: To calculate hourly averages, the Calculated Data function should be used. To get the
proper results, the following parameters of that function should be used:
Page 52
Rooth path (\\<PIAFServer>\<Database>\<ParentElement>\...\TankXX)

Data item (Level or Mass)
Start time (PI System time expression to indicate the start of the day yesterday)
End time (expression for the end of the day yesterday)
Time interval (we want hourly averages)
Calculation (we want averages)
Adding Analytics to the Assets
6. Adding Analytics to the Assets

Once the process data is part of the PI AF structure, it might be interesting to include values
that are not coming from the process, nor from other databases. Data like summary
calculations, KPIs and results of other analysis could be useful to have in the PI AF database.
This section discusses the various options that exist and how to select the right one to use.
6.1 Identify the Best Solution to Perform a Calculation

There are many ways of transforming simple process data into decision making information
using the PI System. Such tools are often referred to as being analytics or calculation tools
because the values they produce are the results of calculations, simple or complex. Here is a
list of the main calculation tools that exist in the PI System:
Formula data reference (PI AF)

PI Point data reference and the Values retrieval methods (PI AF)
PI Calculation datasets (PI ProcessBook)
Calculated Data function and PI Expressions (PI DataLink)
Performance Equations (PE) tags (PI Server)
Totalizer tags (PI Server)
PI Advanced Computing Engine (PI ACE) tags
Before taking a closer look at some of the tools available, it is important to understand the
differences of each one with regards to the others in order to know what tool to use in what
circumstance. Here is a list of questions that will make those differences more obvious and
will allow identifying which solution to take to perform a specific calculation:
Who is the audience for the results?

What load will the calculation place on the PI Server?
Do I need to keep the history for the calculation?
Will the calculation be applied to multiple assets?
Note: Given the variety of possible calculation methods, the most difficult part of setting up a calculation
in the PI System is determining which choice is best. Too often people may choose a familiar method
over what would be the best and most effective method.
The next sections detail the characteristics of each calculation tools which will make the
previous questions more relevant.
6.2 PI Performance Equations

6.2.1
Performance Equation Syntax
The Performance Equation (PE) syntax is an algebraic syntax used to perform calculations
and filter data in multiple client and server products from the PI System suite. These include:
Page 53
PI Server through a Performance Equation (PE) tag.

PI ProcessBook through a PI Calculation dataset.
PI DataLink through use of Filter Expressions or PI Expressions.
PI Notifications through use of a Performance Equation Trigger Condition.
This syntax has three (3) rules when it comes to writing expressions:
1.
PI Server tag names and time stamps are written enclosed in apostrophes ('):
For example: 'CDT158', '*-1h', '03-Feb-2013 13:38', 'Sinusoid', etc.
2. Text strings or digital states are written enclosed in double quotes ("):
For example: "This is a comment.", "OFF", "Active", etc.
3. Mathematical operators and PE functions are written has is.
For example: +, -, *, ^, TagAvg(), FindGT(), etc.
A reference document can be opened to view all the available Performance Equation
predefined functions, how they work, as well as examples on how to use them. This can be
found on any computer with PI System products installed at the following location:
%PIHOME%\Help\PEReference.chm
6.2.2
Directed Activity Checking out the PEReference.chm Help File

instructor is doing or perform the same steps at the same time. You may play a
game or hold a quiz. Your instructor will have directions.
Activity Objectives
Learn where to find and how to use the PEReference.chm reference file
Explore the functions of the Performance Equation syntax.
Approach
Locate this useful help file and open it:
On 32-bit machines, it is usually located at:
C:\Program Files\PIPC\Help\PEReference.chm
On 64-bit machines, it is usually located at:

C:\Program Files (x86)\PIPC\Help\PERference.chm
With the instructor, examine the highlights of this syntax and its available functions.
Note: The functions each have examples at the bottom that can be copied and pasted to notepad or to
other PI System products directly.
Page 54
6.2.3
Solo / Group Exercise Applying Performance Equation Syntax

This is a solo or group activity that is designed to maximize learning in a
specific topic area. Your instructor will have instructions, and will coach
you if you need assistance during the activity.
Exercise Objectives
Learn to apply the Performance Equation syntax to different calculation and filtering
problems using the PEReference.chm as a reference.
Problem Description and Approach

You may want to construct your equations in Notepad or another editor rather than in the
space below so you can cut and paste from the help file also well be using these formulas
to build PI tags in just a minute.
Problem
Get a ten-minutes rolling
average of the CDT158 tag.
Get the time-weighted total
for the CDT158 tag over the
last hour, but only if at least
80% of the values used in
the calculation are
considered good.
Your solution
Hints
TagAvg()
TagTot()
How much time (in % of a

day), was the tag Sinusoid
between 30 and 70, for the
whole day yesterday?
TimeGT()
TimeGE()
The amount of time
returned is in
seconds.
Display Overload when

the tag ba:level.1 is greater
than 90 , Normal when
between 10 and 90, and
Empty when lower than
10.
If.. then else
Page 55
6.2.4
PI Performance Equation Scheduler
The PI Performance Equation Scheduler is a PI Server based calculation engine which

resembles a standard PI Interface. It is installed as a system service with all PI Servers you
can identify it as System Service. The executable is PIPESched.exe in the PI\Bin directory on
the PI Server. As with many PI Interfaces the PI PE Scheduler is configured with a startup
script PIPESCHED.bat which is never run, but rather read when the system service starts.
This file can be readily configurable using the PI-ICU interface configuration utility which is
installed with the PI Server. However changes to the file are only recognized when the PI PE
Scheduler system service is restarted (which you can do from the Computer Management
Services console, from the PI System Management tools services console, or from within the
PI-ICU).
The PI PE Scheduler reads the calculations from the tag configurations from PI Performance
Equation Tags with the Point Source of C and writes the results into the PI snapshot and
archive of those tags.
Note: C is the default point source for Performance Equations, but can be changed during set-up.
Page 56
6.2.5
Directed Activity Configuring the pipesched.bat file with PI ICU

Activity Objectives
Introduce the PI PE Scheduler.

Configure an additional scan class for scheduling calculations.
Restart the PI PE Scheduler service.
Approach
Open PI-ICU (Interface Configuration Utility) from the Start menu.
From the Interface menu, select New Interface Instance from a bat file or the open folder
icon, navigate to PI\Bin\PIPESchd.bat and select it. (There may be a pause while the PI
Server registers the interface.)
At the bottom of the PI-ICU General section, note the list of scan classes (and offsets). By
default, new PI Systems have 1 minute, 2 minutes, and 30 seconds scan classes established.
Add two new scan classes to the list:
A one hour scan class with zero offset

A ten seconds scan class with zero offset
(01:00:00,00:00:00)
(00:00:10,00:00:00)
Once completed, save your work and restart the interface service (use the PI ICU top-toolbar
buttons to do so).
Page 57
Solo / Group Exercise Building PI PE tags from your PI PE Expressions
6.2.6

Exercise Objectives
Apply PI Performance Equation Syntax to the PI PE Scheduler

Build PI PE tags in the PI Server
Problem Description and Approach

Open PI System Management Tools (PI SMT) from the Start menu.
Select the PI Server you have or that your instructor indicates by clicking on the box in the
upper left corner
Select Points and then Performance Equations from the navigation menu in the lower left..
Configure four new PI Performance Equations from your for PI PE formulas if your
instructor requests it - before each tag name, substitute your student number or initials to
identify these tags as yours. All tags are Point Source C and PointType of Float32.
Tag Name
Problem
Scheduling
_CDT158.10mAverage
Get a ten-minutes rolling average of the

CDT158 tag.
Event based: every time

CDT158 receives a new value.
_CDT158.1hTotal
Get the time-weighted total for the

CDT158 tag over the last hour, but only if
at least 80% of the values used in the
calculation are considered good.
Every hour, on the hour.
_SINUSOID.%30-70
How much time (in % of a day), was the

tag Sinusoid between 30 and 70, for the
whole day yesterday?
Event based: every time

Sinusoid receives a new value.
_Ba:Level_Status
Display Overload when the tag

ba:level.1 is greater than 90 , Normal
when between 10 and 90, and Empty
when lower than 10.
Every 10 seconds on the top of

the minute
You can verify your newly created tags are receiving values by adding them to a Trend
symbol in PI ProcessBook. Remember some tags you created might not update frequently.
Page 58
6.2.7
Limitations of the PI Performance Equations Scheduler
Although the PI Performance Equation syntax is flexible and readily understood, the
scheduler has many limitations:
The scheduler must parse the entire calculation string and identify the PI Server
tags every time it calculates. This is a serious performance disadvantage when
compared to compiled calculation options.
There is no persistent memory for PI Performance Equation calculations. They

cannot carry calculation values from one calculation event to the next. They must
indeed reassemble all of the values from the archive every time, which is a clear
performance/efficiency disadvantage.
In the PI Performance Equation syntax, the tags are specified explicitly by their
name. This means if the source tag is renamed at one point, the calculation will
break.
The syntax for the calculation is stored and entered on one single line/string of
text. Because tag names are explicit these formulas can many hundreds of characters,
especially when If-Then-Else statements are employed. This makes documenting,
verifying, and modifying calculations difficult.
The calculations are performed independently on different members of a PI

Servers Collective (HA). Although they should be materially the same, they may not
be identical due to differences in the server clocks.
Calculations cannot be easily re-used against different tag sets as there is no context
for these calculations. The formula must be rebuilt every time it is used against
similar assets or tag assets, using the PI Tag Configurator Excel add-in.
It isnt possible to introduce a new calculation frequency (scan class) without

reconfiguring the pipeschd.bat start-up parameters file and restarting the calculations.
PI Performance Equations can only read a value from and write a value to the PI
Server they are running on.
Calculations cannot be scheduled on multiple triggers. Only one tag can be used
to trigger event based calculations, even if multiple tags are used as inputs into the
formula.
Although the PI Performance Equation Scheduler service seems to be based on an

interface, OSIsoft does not support running more than one scheduler against a PI
Server. This means PE calculations capacity is not scalable by moving it to another
computer or having more than one scheduler on multiple machines.
All of these limitations are resolved in PI ACE, which is a calculation option covered later in
the course.
6.2.8
PI Recalculator Subsystem
The Recalculator is an interface like service which signs up for updates to the archive events
of all Performance Equation tags in order that it can recalculate PI Performance Equation
(Point Source C) tags if there are changes to the input tags in the archive. In operation, for
many customers who have significant performance equations, this has been a serious server
performance drain. Therefore we do not start the recalculator by default on system startup.
Page 59
Note: The PI PE Recalculator as described above, can be problematic if generally applied and can be
challenging to configure efficiently.
The Recalculator Interface can only recalculate if values already exist in the PI Server archive files.
6.3 PI Totalizer Subsystem

The PI Totalizer is a powerful and flexible post-processor engine that you can use to create
totalizations and other simple calculations from a single PI tags stream of snapshot value.
The totalizer can aggregate totals, averages, ranges, and standard deviations or identify
minimums or maximums. It can also be used to calculate the amount of time that a condition
is true and it can count events. The calculations can be filtered using simple Performance
Equation syntax. The results of the aggregations are stored into a different PI tag the
totalizer tag which uses a unique Point Class the totalizer point class which has attributes
used only by the totalizer engine. There is a wizard in the PI System Management tools to
help you build these tags and configure them properly.
6.3.1
Limitations of the PI Totalizer / Comparison to PI Performance Equation Tags
Of course the biggest limitation of the PI Totalizer compared with the PI

Performance Equation Scheduler or PI ACE scheduler is that it can only perform a
limited number of aggregation functions on a single tag.
The PI Totalizer uses PI snapshot data, before it may be filtered by data compression
for its source data. Therefore when compared to a Performance Equation calculation
with similar function, it may see a richer set of data and therefore be marginally more
accurate than a Performance Equation tag which uses compressed archive data.
However, this should not be significant if tags have well configured compression
algorithm parameters.
Page 60
The PI Totalizer does not have to interpret strings as the PI PE Scheduler does and it
has persistent memory to hold the running summary totals therefore it is a great
deal more efficient than the PI PE Scheduler when applied to similar problems.
Note that for many function types, including StdDev, Maximum, Minimum, Median
and Range, if TotalCloseModes of NSampleMoving or TimeMoving are selected, the
totalizer must maintain tables of all of the value during the period. This can be very
memory intensive and affect performance.
The PI Totalizer holds the source tag by its tag number, not its name, so tag
renaming will not break it. Changes to tag names used in the Performance Equation
syntax filters (Filter the source data with the following expression:) will break the
totalizer.
As with Performance Equations, the calculations are performed independently

from the same configurations on different members of PI HA collectives. Although
they should be materially the same, they may not be identical due to differences in
the server clocks.
Calculations cannot be easily re-used against different source tags. The

configuration must be rebuilt every time it needs to be used against similar tags set.
Like the PI PE Scheduler, the Totalizer can never read a value from another PI
Server except the one it is running on and cannot write to another PI Server.
You can only run one PI Totalizer Subsystem per PI Server and you cannot run it on
another computer, so you cannot increase the PI Totalizer calculation capacity by
moving it to another computer or having more than one scheduler.
Note: Since Totalizers are based on snapshot data that may not be stored in the archives, there is no
recalculator for the PI Totalizer. If the totalizer misses calculation periods, it has no way to restore those
calculations.
Page 61
6.3.2
Directed Activity Build Commonly Used PI Totalizer Tags (optional)

Activity Objectives
Learn how to build Totalizers with the PI SMT 3 plug-in Totalizer Editor
Build three types of useful totalizations often used by PI customers
Problem Description
Wed like to build three Totalizers:
1. A shift average for the CDT158 tag (shifts are twelve hours, starting at 6AM and
6PM).
2. The total number of gallons used per batch (where the flow rate tag is CDEP158 in
GPM and a batch starts when tag BA:Active.1 turns to Active and ends when it
turns back to Inactive).
3. A moving average on the CDEP158 tag, to smooth this volatile data flow (where the
moving average will include 5 values).
Approach
Well use the PI SMT > Points > Totalizer plugin editor.
Your instructor may ask you to precede the tag names with your student number or initials to
identify them as yours:
For the first totalizer, _CDT158.ShiftAverage, select a time-weighted average with natural
sampling and write the final result After a time period elapses. The first shift starts at 6
hours after midnight and lasts 12 hours long. The final result will be written at the end of the
12 hours, but should also be Stamped one second after start.
For the second totalizer, _CDEP158.BatchTotal, select a time-weighted total with natural
sampling and make the totalizer close whenever the batch active tag BA:Active.1 goes to
Inactive. Post interim results as new values come in (ramp). The result will be a total in
gallons, from a flow meter with readings in gallons per minute (GPM).
About Totals and the Conversion Factor:
Since the units of measure defined in the PI Server (the EngUnits attribute of each tag) are simply text,
the PI Server needs to make an assumption whenever calculating a total, the area under the curve. Indeed,
a totalization result greatly depends on the units of time of the EngUnits attribute. In fact, 1 m/s is much
faster than 1 m/h, proving the point that the units of measure are crucial in a totalization.
Hence, in order to be able to calculate a result, the PI Server will always make the assumption that the tag
units of measure are units per day, for example gal/day or ft/day. If these are not truly the units of
Page 62
measure, a conversion factor will need to be applied, that is a conversion between 1 day and the real units
of time: 24 for hours, 1,440 for minutes and 86,400 for seconds.
This should need to be applied only when Totals are requested, because this is the only calculation where
the units of measure of the result are not the same as the source tag units. For example, a total on a tag
with units of ft/h will be a result without the units of time, in ft. However, the result of an average on the
same tag will be in ft/h, thus no need for a conversion.
For the third totalizer, _CDEP158.MovingAverage, select a time-weighted moving average
that will close every time five (5) source tag values are read.
The PI Totalizer Subsystem should pick up the new tags and begin to process them
immediately. The results of the newly created calculations can be examine by using the PI
SMT > Data > Current Values plug-in, searching for tags with PointSource of T. If
Configure or Pt Created is the current value, the totalizer tag may simply not had enough
time or enough values to give a result yet. Their values can be checked at a later time.
Open the Totalizer help from within PI System Management Tools or

open the PI Server Application User Guide to the chapter on Totalizers to
review the options available for building a totalizer.
6.4 PI Advanced Computing Engine (PI ACE)

PI ACE (Advanced Calculation Engine) is a set of calculation tools that allows an end user to
easily develop a fully compiled DLL (dynamic link library) using Microsofts world leading
programming environment, Visual Studio in the Visual Basic language. This DLL is then
implemented to a flexible, high-performing triggering and scheduling real-time calculator
which can read PI Server data with precision, calculate on triggers of events in the PI Server
or on the clock and then write data back to PI Server tags.
6.4.1
PI ACE Components
PI ACE is composed of three (3) software components:

PI ACE Wizard
It is an add-in to Microsoft Visual Studio. There is no point in installing the PI ACE Wizard
where there is no copy of Visual Studio present. The Wizard is a code generator and rapid
application development engine which generates objects based on your input and output tag
selections, and provides an easy menu-driven way to create, edit, debug, register, and
schedule PI ACE calculations.
PI ACE Scheduler
This is the system service which runs on a dedicated or shared server and evaluates the
triggers, queues the calculations, performs the calculations, and writes the results.
Page 63
PI ACE Manager
It is a system management tool for PI ACE which can run on any PI System client which has
privileges to edit the module database of the designated PI ACE host PI Server. It can be used
to start, stop, register and reconfigure the schedule of PI ACE calculations.
Though PI ACE can read and write from any PI Server it has privilege to, the scheduler is
managed by the PI Module Database (OSIsofts pre-PI AF legacy context database) in a
particular PI Server, which could be considered its home PI Server (and it must be the
default PI SDK selected server for the computer that PI ACE is running on).
In general, the PI ACE Wizard is used to develop PI ACE DLLs. These must be stored on the
same computer in the correct directory path on the PI ACE Scheduler. When the calculations
in that DLL are scheduled, the scheduler will calculate them and based on triggers in the
activity of PI tags or on a clock schedule it will perform calculations and post any appropriate
results.
PI ACE supports a sophisticated triggering and scheduling system, such that if calculations
do not happen precisely when they are triggered, the snapshot values in PI are stored in a
queue and when the calculation happens some time later, the results are posted back at the
triggered time. This allows PI ACE to handle many calculations and still accurately use the
correct data and post them back to the correct time, even if the scheduler is temporarily busy
or the data is changing.
Installation notes
When installing it is important to realize that not all components should be installed on every
computer. The PI ACE Wizard is only useful where there is a copy of Microsoft Visual
Studio installed. The PI ACE Scheduler is not intended for client/end-user computers and can
cause problems if it is scheduled and started without being configured. The PI ACE Manager
can be installed anywhere where a PI Server manager feels it is important to manage a PI
ACE Scheduler. The Installation allows you to choose the components you want to install.
Choose carefully.
Page 64
Further the PI ACE installation still includes the legacy PI ACE version 1 scheduler and
wizard which support (pre .Net) VB6 calculations. As no new installation could use these
options there is no reason to install them unless rather dated, legacy PI ACE v1 calculations
are still in use and copy of Microsofts VB6 is still available to maintain them.
There are numerous installation options and architectures which may be appropriate for
different applications for PI ACE. Many customers run it on a dedicated server, some
customers run it on a server which also runs a PI Server and/or PI AF. Although your
instructor may be willing to explore brief questions concerning architecture that material is
covered in other classes and documentation.
6.4.2
PI ACE Features
PI ACE Scheduler: PI ACE implements a terrific, queued scheduling and
triggering engine. It includes a method for automatic or manual recalculation.
PI ACE Objects: The PI ACE Wizard converts the PI Server tags indicated in the PI
Module Database aliases into sophisticated PI ACE Objects with easy-to-use
methods and properties which make object oriented programming with the PI Server
data easy. PI ACE calculations are built in Microsoft Visual Studio and make use of
intellisense. PI ACE thus becomes a rapid development tool.
Performance: The compiled PI ACE *.dll files are much higher performing for
every kind of calculation than Performance Equation tags. Even with these
performance advantages, it is also possible to spread the calculation load across
multiple PI ACE scheduler engines running on separate machines.
Flexibility: PI ACE supports the rich VB.NET language so it is possible to use
external databases (with ADO.net) and third-party DLLs, including those written
in C# or other languages. PI ACE Calculations can write results to another data
source, or read from another data source than the PI Server. PI ACE also offers
sophisticated debugging, logging, and performance diagnostics.
Contextualization: PI ACE allows for the creation of one calculation that can then be
applied to many similar tag sets through the PI Module Database aliases.
High Availability: PI ACE is not only compatible with the PI Server HA
architecture, but also has the ability to support redundant/failed over PI ACE
engines, which assure the calculations will always be executed and their results
available.
Limitations of PI ACE
Although many associate VB with easy-to-design forms, PI ACE does not support
a user interface. It only runs in the background and does not support any end-user
interactivity at run-time.
PI ACE is still pretty much tied to PI AF precursor: the PI Module Database (MDB).
It is not yet adapted for use with PI AF directly. There are ways they can work
together, but this requires significant understanding of both PI ACE and PI AF
(including the AFSDK).
Page 65
6.4.3
Directed Activity Preparing for the Exercises

Activity Objectives
Know what PI Advanced Computing Engine (PI ACE) components are required.
Differentiate the PI Tag Configurator and the Module Database Builder add-ins for
Microsoft Excel.
Problem Description
In order to be able to complete the PI ACE exercises successfully, a set of PI Server tags and
a Module Database structure need to be created on your designated PI Server. The PI ACE
application will also need to be installed if not already available.
Approach for local PI Servers
1.
(optional) If your instructor indicates that PI ACE needs to be installed, first check to see that the
appropriate PI Server is the default PI Server. To do this, open the Start menu > All Programs > PI
System > PISDKUtility > Connections > Options, and make sure the default PI Server is the right
one (usually your local PI Server).
2. (optional) To complete the PI ACE installation, run the PI ACE installation kit from the provided
directory. Install ONLY the following components:
ACE Manager
ACE 2.x Scheduler
ACE Wizard for VB.NET 2005, 2008, and 2010+
3. Open the C:\Class\Exercises\02_PI ACE\PIACE_Tags.xlsx Excel worksheet.
4. While on the Tags worksheet, select the Add-ins ribbon and click on PI-SMT > Export Tags to
create the necessary tags for the PI ACE exercises on your designated PI Server.
(Optional) Approach for a shared PI Server
1.
(optional) If your instructor indicates that PI ACE needs to be installed, first check to see that the
appropriate PI Server is the default PI Server. To do this, open the Start menu > All Programs > PI
System > PISDKUtility > Connections > Options, and make sure the default PI Server is the right
one (usually your local PI Server).
2. (optional) To complete the PI ACE installation, run the PI ACE installation kit from the provided
directory. Install ONLY the following components:
ACE Manager
ACE 2.x Scheduler
ACE Wizard for VB.NET 2005, 2008, and 2010+
3. Open the C:\Class\Exercises\02_PI ACE\On-site Option\PIACE_Tags&Modules.xlsx Excel
worksheet and select the Tags tab.
4. Select the entire Tags worksheet by pressing Ctrl+A and Find-Replace by pressing Ctrl+H. Find
ZZ and after Replace with <your unique student number or initials>. Repeat the same for the
MDB worksheet.
Page 66
5.
6.
While on the Tags worksheet, select the Add-ins ribbon and click on PI-SMT > Export Tags to
create the necessary tags for this exercise on your designated PI Server.
From the MDB worksheet, select the entire sheet once more and use the Find-Replace option to
replace all occurrences of TRAIN01 with the name of your default/designated PI Server. Then, select
the Add-ins ribbon and click on PI-SMT > Module Database Builder > Export Items to build an
MDB structure on the PI Server.
6.4.4
Directed Activity Simple PI ACE Calculation

Activity Objectives
Enumerate the steps involved in creating a PI ACE calculation.

Create a simple PI ACE calculation.
Problem Description
Flows measured by flow meters CDT158 and SINUSOID are merged together in the plant
before reaching Tank01. You would like to know the total flow coming into Tank01 in realtime, anytime one of the two flow meters tag receive a reading in the PI Server (this cant be
done using a PI Performance Equation tag, since it allows for only up to one trigger tag).
Both flow meters have the same units of measure, m/h.
Approach
The PI Server tag TANK01FI.ACE will be used to store the total flow fed to Tank01.
Use the PI ACE Wizard (from Microsoft Visual Studio 2005+ > Tools > PIACEWizard) to
create a new calculation to calculate that total flow as being the sum of tag CDT158 and
SINUSOID.
1.
Create the new calculation from Tools > PIACEWizard > New.
Page 67
2.
Configure the inputs and outputs PI Server tags to use in the calculation.
3.
Write the calculation logic that will be executed by the PI ACE Scheduler.
Public Overrides Sub ACECalculations()

TANK01FI_ACE.Value = CDT158.Value + SINUSOID.Value
End Sub
Note: The Visual Basic environment does not allow certain characters to be used to name variables,
unlike tags within the PI Server. At the top of the PI ACE code is a comment block that shows how PI
ACE has adapted the tag names into PIACEPOINT object names. In this case TANK01FI.ACE was
renamed to TANK01FI_ACE within the code (the actual tag name was not changed).
4.
Test the calculation using the PI ACE Wizard.
Page 68
5.
Register the calculation using the PI ACE Wizard so it executes anytime CDT158 or SINUSOID
receive a new value on the PI Server.
Page 69
6.4.5
The PI Module Database (MDB) Contextualization before PI AF
Before PI AF was released in 2008, PI Servers included a similar but much simpler tool
called the PI Module Database (MDB). The PI Module Database is still part of the PI Server
and is a single root hierarchical database of objects called modules (simpler versions of
elements) which have only two types of things that PI AF would call attributes: the Alias (a
pointer to a PI Server tag, similar to the PI Point data reference) and the Property (which
would accept various kinds of entered values, similar to an attribute without a selected data
reference (<None>)).
The concept of templates is unknown to the PI Module Database. However, building modules
by copying existing ones (using the Module Database Builder add-in for Excel, the precursor
to the PI AF Builder) ends up giving similar results as the resulting modules offer an
interchangeable indirect reference to PI Server tags (aliases) and static context information
(properties); which is very valuable to PI ACE. OSIsoft PI Batch implementations also still
take advantage of the PI Module Database.
Although the PI Module Database is not nearly as powerful as PI AF, PI ACE still benefits
from using the MDB.
In 2010, OSIsoft released PI Server 2010 which hosted the PI AF Link synchronization tool,
synchronizing the legacy PI Module Database and PI AF. The synchronization is automatic
and provides replication of the PI Module Database structure under a root PI AF element in a
specific PI AF database. This allows for the orderly retirement of the PI Module Database.
Through PI AF Link, MDB Aliases are built as simple PI Point data reference attributes while Properties
become attributes with simply no data reference (<None>). The Formula and Table Lookup data
reference attributes are not compatible with the MDB and as such are labeled Not supported. With the
Page 70
limitations of the PI Module Database in mind, PI AF elements can still be built under this single root,
using element templates. They will result in usable MDB modules for applications still based on them.
Page 71
6.4.6
Directed Activity Using the Velocity Terminals PI AF Structure in the MDB

Activity Objectives
Witness the MDB to AF synchronization and understand its limitations.
Approach
In order to prepare for a later PI ACE exercise, accomplish the following:
1.
From the Library section of the navigator panel in PI System Explorer, edit the Tank element
template by adding an additional attribute (check-in the changes once completed).
Attribute
Name
Volume ACE
Default
UOM
m3 (Volume)
Value
Type
Double
Value
Data Reference
PI Point (Enable Tag

Creation, leave the
default configuration)
2.
Holding down the Ctrl key, drag and drop the Velocity Terminals structure under the <PI Server
Name> ModuleDB PI AF element. By doing this step, the Velocity Terminals database that was
built in chapters 3 and 4 will be copied to the PI Module Database. Check-in the changes.
3.
Confirm the structure is available in the PI Module Database by opening PI SMT > Operation >
Module Database. It is possible to also confirm the MDB to AF synchronization works well by
selecting the Operation > MDB to AF Synchronization plug-in.
Page 72
6.4.7
Solo / Group Exercise Contextualizing PI ACE Calculations

Exercise Objectives
Distinguish the tasks the PI ACE Wizard, PI ACE Scheduler and PI ACE Manager
can perform.
Identify the advantage of using asset context to scale out calculations to multiple
similar assets.
Problem Description
The volume of each tank needs to be analyzed over the past two (2) years by the engineers.
Data for a total of ten (10) tanks is currently available, but that number should go higher in
the next few months.
What calculation tool should we use in order to calculate the Volume for our tanks?
Approach
1.
Configure a new PI ACE calculation to calculate the Volume for Tank01:

Executable: Tanks
Class Module: Volume
Context:
\\TRAININGXX\Velocity Terminals\Locations\Montreal\Tank01 (or similar)
Input_Aliases: Level (using the Alias Search)
Output_Aliases: Volume ACE (using the Alias Search)
2. Write the calculation in the VB.NET environment:
Add a reference (Project > Add Reference > .NET) to the OSIsoft.PISDK.
At the top of the code (with the Imports OSIsoft.PI.ACE statement that is already there)
add the following:
Imports PISDK
Imports OSIsoft.PI.ACE.PIACEBIFunctions
The code should look like the below logic. Notice the Capacity needs to be retrieved from the
Properties of Tank01 has it couldnt be added as an Input to the calculation:
Page 73

Public Overrides Sub ACECalculations()
Dim pimTank As PIModule
Dim dblCapacity As Double
pimTank = GetPIModuleFromPath(Context)
dblCapacity = pimTank.PIProperties("Capacity").Value
Volume_ACE.Value = (Level.Value / 100) * dblCapacity
End sub
Note: The above code declares an object of type PIModule and a simple analog variable. It assigns the
currently running PI Server module to the object by using the PI ACE assigned string variable Context
(which at run-time gives the currently assigned PI Server module path). This is used to extract the value
of the capacity property from the module, to use it in the volume calculation.
3.
Debug, Test and Register the calculation using the PI ACE Wizard (a 10 seconds with 0 offset
scheduling can be chosen).
4.
In PI ACE Manager, open the tree view for Tanks > Volume > Context to select:
\\PIServerName\Velocity Terminals\Locations\Montreal\Tank01
Note: The executable, module and context icons should be green. If everything is grey, it is likely the PI
ACE Scheduler service is not running. You can start it from Run ( +r ) > services.msc applet.
5.
6.
Apply the calculations to all ten (10) tanks:

Right-click the Tank01 context and select Apply Schedule To.
Select Velocity Terminals (a parent module for all tanks) and click Close.
The resulting list should show the other tanks which have matching aliases and properties. Select
the tanks under the Locations hierarchy and click Apply. After a few minutes the volume for all
ten (10) tanks should start historize in the PI Server tags.
(optional) Using the PI ACE Manager, right-click on the Tanks executable and recalculate the
volume results for the past day (from *-1d to *, with no interval).
Page 74
6.5 Selecting the Right Calculation Tool

This section emphasize the fact that each calculation tool in the PI System has its purpose. As
it was detailed in previous sections, each tool has a series of advantages and limitations that
will make it the ideal one in certain specific circumstances.
6.5.1
PI System Analytics Decision Tree
Page 75
6.5.2
Group Discussion Which Calculation Should I use?

Questions
The PI AF Formula data reference, PI Performance Equation Scheduler Tags, PI Totalizer Tags, and PI
ACE are all options for calculated data in tags. They have marked differences and some similarities.
1. What if I need history (calculation results before now)? What are the merits of each tool?
2.
What if I need to apply the same calculation to many unique but similar things?
3.
What if my calculation is complex and executed often? Which are the most efficient options?
4.
What if I need to modify the calculations often? Which choices will work best for that?
5.
Any other thoughts on PI System calculation options?
Page 76
Taking Full Advantage of PI AF Functionalities
7. Taking Full Advantage of PI AF Functionalities

7.1 PI AF Object Security
Security in PI AF is tightly bound to windows security. AF
objects (Elements, Tables, Enumerations Sets, etc.) and
their effective permissions are based on the Windows user
identity. Each AF object has a set of access control
information associated with it. Known as a security
descriptor, this information controls the type of access
granted to a set of Windows users and groups.
Note: It is preferable to assign permissions to groups
instead of users. Because it is inefficient to maintain user
accounts directly, it is recommended that the assignment of
permissions on a user-by-user basis be the exception.
7.1.1
PI AF Permissions Type
The security permissions that you can specify for AF

objects are described in the following table. The available
security permissions depends on the type of object you are setting permissions for.
Permission
Definition
Read
The ability to read or see the object. Without this permission, it is not
possible to obtain the object or search for it.
Write
The ability to create and modify an object. If users do not have Write
permission on the PI AF database, then they cant modify any object
within the database, regardless of the specific permission on that
object.
Read Data
The ability to read data reference values from Attributes of Elements.
Write Data
The ability to write values to an Element's Attribute.
Subscribe
The ability to subscribe and unsubscribe Notifications to oneself.
SubscribeOthers
The ability to subscribe and unsubscribe others to a Notification.
Delete
The ability to delete an object.
Execute
The ability to run analysis cases.
Admin
The ability to modify the security settings, or owner, of an object.
Setting permissions can be done for individual PI AF objects or for collections of objects.
When you create new objects, except for child elements, the collection security is used as the
default security. When you create a child element, the security descriptor of the parent
element becomes its default security.
Page 77
7.1.2
PI AF Securable Object Collections
The following chart shows the available securable collections of AF objects in an AF Server
(PI System). Boxes are collections available at the PI AF server level while collections
represented by locks are available at the PI AF database level.
PI System
(AF Server)
Contacts
Databases
Database
Notification Contact
Templates
Analyses
Enumeration Sets
Analysis Templates
Notifications
Categories
Reference Types
Elements
Tables
Element Templates
Transfers
Note: The write permission on a PI AF database is enforced automatically on every other object in the
database. This allows for a simpler mechanism for disabling Write permission without having to recompute security descriptors for all objects within the database.
7.1.3
Accessing and Modifying PI AF Security
To modify permissions on collections belonging to a PI AF server, open up File > Database,

then click on the ellipsis button () next to the System drop-down list. Select the server of
interest in the Systems dialog box and then right-click to expand the Security menu.
Page 78
To modify permissions on collections belonging to a PI AF database, right-click on the

Database in the Select Database dialog box and select Security. Alternately, you can access a
collections security directly from the Library upper level location (database name) in the PI
System Explorer browser.
The PI AF Unit of Measure (UOM) database is shared across all PI AF databases.

Permissions cant be set individually per UOM classes. Permissions can only be set for the
Page 79
entire UOM database. Clicking the lock ( ) from the top toolbar gives access to the
Permissions for the Unit of Measure database.
When modifying the security for a collection, you can replace the security descriptor for all
previously created members of the collection. Right-click on the collection item and then
select security. From the Permissions Dialog, click the Advanced button and select the
Replace all child object permissions. This can also be used to modify the security
descriptor for a specific hierarchy of elements.
7.1.4
Directed Activity PI AF Objects Security

directions.
Page 80
Problem Description
In most OSIsoft classrooms, the group Students is included in the local administrators
group on all computers and that gives all StudentXX domain accounts administrative
privilege on all computers and PI AF Databases. Find your PI AF Database that contains your
tanks and alerts. Add your student account and give it all privileges on this database. Remove
the local Administrators group privilege.
What effect did this have? Can other students now edit your database? How is this privilege
reflected in elements and other objects inside of the database? (try running PI System
Explorer as another studentXX by right-clicking on PI System Explorer while holding the
Shift key, and then clicking on Run as different user).
7.2 PI AF Versioning
PI AF has the ability to save different versions of elements. If desired, you can set the
effective date of each checked in/saved version. When an AF Element has versions this is
indicated by a small clock icon presented with the PI AF element icon in the browser. If you
right click this element, there is a Show History option which will allow you to select the
versions and view the details of their configuration.
This can be used in two ways.
7.2.1
Benchmark Versioning
Although PI AF databases are normally backed up as a whole in a maintenance procedure,

you may want to benchmark individual elements so that you can see the older versions.
Note that the earliest date you can set as the effective date is midnight on January 1st of 1970
(the beginning of time for PI Servers and PI Systems). To keep benchmark versions where
the most recent version is always used, each time you check in, set your effective dates
incrementing one hour from this seminal time (i.e. 1-1-70 00:01:00, 1-1-70 00:02:00, 1-1-70
00:03:00, etc..).
7.2.2
Recognition of changing configurations in versioning effective dates
A more sophisticated implementation recognizes that the configuration, structure, even the
relationships between elements appropriately changes over the life of a process. To
implement this versioning, when you make changes and check in, apply the effective date for
this version to begin applying to. From the effective date until the current time, or another
version with a subsequent effective time, this version will be seen and used by PI AF.
Query Date PI System Explorer
The query date in PI System Explorer is set very simply by the Query Date toolbar button.
The default date points to the last version in time (not the current time), so if you have future
versions, you will see the latest or most future version in PI System Explorer unless you
change the Query Date.
Query Date PI ProcessBook & PI WebParts
The query date for PI AF in PI ProcessBook and PI WebParts are automatically set to
dynamically to the time of evaluation of the display, even within a trend.
Page 81
7.2.3
Directed Activity Element Versioning

Objectives
Use the versioning capabilities to create different versions of a PI AF element.

Demonstrate the changes in versions by showing the history and setting the query
date in PI System Explorer.
Examine the impact on a PI ProcessBook trend.
Problem Description
Over the past weeks, Tank02 has been inspected and rust at the base of the tank has become
an important matter. In order to prevent leakages, the tank has finally been replaced yesterday
by a brand new one. This new tank has a higher capacity bringing the capacity of Tank02
from 30,000 US Gal to 45,000 US Gal.
We want to save this change in configuration for the Capacity from 30,000 to 45,000, and
want that change to be effective starting yesterday at midnight (00:00:00). We then want to
confirm the change is recorded by looking at the data before and after within PI System
Explorer and PI ProcessBook.
Approach
1.
2.
Select the Tank02 element and look at its attributes.

Select the Capacity attribute and change its value to 45,000. Note that once a new value is inputted
for the Capacity, the change needs to be checked in to become effective as the attribute is marked as
being a Configuration Item.
Note: The Capacity attribute uses a <None> data reference (static value). When the value of a static
attribute is changed, the change will be automatically effective, without the need to check in.
HOWEVER, a check in will be required if the attribute is marked as a Configuration Item.
3.
4.
While holding down the Shift key on your keyboard, click the
button.
The Check In window shows up and notice now the possibility to create a new version, setting up an
effective date and including a comment. Check the Create New Version check box and set the
proper effective date for the new Capacity value.
Page 82
5.
After clicking Check In, notice the clock icon ( ) on the Tank02 element in the browser meaning
more than one version of the element now exist.
About Element Versioning

To create a new version for an Element, do like the above steps, or simply right-click an element and
select Create Version. Alternatively select an element, select its Version tab and click the New Version
button.
When multiple versions of the same element exist, it is possible to see and compare those versions from
various locations in PI System Explorer. To check the effective dates of each version, select the versioned
element, select its Version tab and switch versions by clicking on the Previous Version and Next
Version buttons. To see the effective date of each version and also have the ability to compare versions to
see what was modified between two versions, simply right-click the versioned element and select Show
History, or select the element, select its Version tab and click on the Show History button.
6.
From PI System Explorer, verify that the before and after values are recorded by displaying the
Show History window. Holding down the Ctrl key on your keyboard, select both versions effective
dates on the left to confirm what changed between both versions.
Page 83
7.
To see the values before and after the change in the PI System Explorer Viewer, the Query Date
will need to be modified to a time where the new version was not yet effective. Use the File > Query
Date or the top toolbar
button to navigate in time and confirm you can see the 30,000
value for the Capacity of Tank02.
Note: When using the Query Date in PI System Explorer, you can always go back to the original setting
to show the current values for all attributes. Do this by clicking the drop-down arrow next to the Query
Date top toolbar button, and then selecting Set to Latest.
8.
9.
To see the values before and after in PI ProcessBook, create a Trend to show the Mass and the
Capacity attributes of Tank02 over the past 48 hours. Do you see the change in the values at the
expected time?
(Optional) What happens in the Browser section of PI System Explorer if you select the Version tab
for Tank10 and you set an Obsolete Date of yesterday at midnight? How can you make Tank10
reappear?
Page 84
7.3 PI AF Advanced Template Design

7.3.1
Template Inheritance and Base Template
A powerful feature of the Element Template is the ability to set a Base Template. A base
template effectively includes all the base element templates attributes in the newly created
element template. When an element is created from an element template that includes a base
template, the element contains all attributes from both element templates.
A Base Template is best used when you are modeling elements that have a set of attributes in
common with a few attributes that differ. For example, if you have a set of tanks, some with
two valves and some with one valve, you can create an Element Template for the one-valve
models and use that as the Base Template for the two-valve models. Set the base template of
an element template in the General tab alternatively, you can set the base template at creation
time by right-clicking the base template and select New Derived Template.
To view the template inheritance tree from the PI System Explorer Library, simply organized
the templates by inheritance.
7.3.2
Substitution Parameters in an Attribute Template
Substitution parameters can be used when creating Element Template Attributes. The
%Element% expression is an example of a substitution parameter that would translate to the
attributes element name. For example, imagine the Element Tank01 with a Level attribute
Page 85
coming from the Tank template. The Level attribute is configured at the template level to
show the value of the following PI Server tag \\PIServer\%Element%LI.PV. When Tank01
is created, its Level attribute would try to look for the following PI Server tag:
\\PIServer\Tank01LI.PV, thus substituting %Element% by the name of the element: Tank01.
Notice the default configuration for a PI Point Data Reference attribute template. If not
configured, it will automatically configure the tag name as being
\\%Server%\%Element%.%Attribute%, meaning a tag named like the element name, dot, the
attribute name, and within the default PI Server configured for the client will try to be found
(ex.: \\TRAINING01\Tank01.Level).
Substitution parameters can also be useful as part of the WHERE clause of a Table Lookup
Data Reference.
Page 86
7.3.3
Defining the Substitution Parameters
The substitution parameters are listed in the following table. The ones in bold are the
commonly used Name substitution parameters.
Parameter
Will be replaced by this objects name:
%System%
The name of the PI System in which the attribute resides.
%Server%
The name of the default PI Server of the AF Database in which the

attribute resides.
%Database%
The name of the AF Database in which the attribute resides.
%Element%
The name of the AF Element in which the attribute resides.
%ElementId%
The element ID that holds this data reference.
%\Element%
The name of the root AF Element in which the attribute resides.
%..\Element%
The name of the owning element of the element in which the attribute
resides. To retrieve further ancestors, use the '..\' notations, such as
%..\..\Element%.
%Attribute%
The name of the attribute that holds this data reference.
%..|Attribute%
The name of the owning attribute in which the attribute resides. To

retrieve further ancestors, use the '..|' notations, such as %..|..|Attribute%.
%AttributeId%
The attribute ID that holds this data reference.
%Model%
The name of the model if it can be obtained from the context.
%Analysis%
The name of the analysis if it can be obtained from the context.
%StartTime%
The local start time if it can be obtained from the time context.
%UtcStartTime%
The coordinated universal (UTC) start time if it can be obtained from the
time context.
%EndTime%
The local end time if it can be obtained from the time context.
%UtcEndTime%
The coordinated universal (UTC) end time if it can be obtained from the
time context.
%Time%
The local time if it can be obtained from the time context.
%UtcTime%
The coordinated universal (UTC) time if it can be obtained from the time
context.
%<Environment
Variable>%
The matching System Environment Variables value. For example

%COMPUTERNAME% is replaced with the name of the computer on
which the Data Reference is executing.
%Description%
The description of the attribute that holds this data reference.
%ElementDescription%
The description of the element in which the attribute resides.
Not only can substitution parameters be replaced by the name of a PI AF object like an
attribute, but it can also be replaced by the value of that attribute.
Page 87
Imagine the Velocity Terminals example again. Imagine the tag names are always built the
same way following this tag naming convention:
LLEEEEEEMM.TT
Where
LL
Code of the location (ex.: Montreal is 15)
EEEEEE
Equipment name (ex.: TANK01)
MM
Measurement type (ex.: LI for level indicator)
TT
Type of data (ex.: PV for process value)
This could lead us to easily determine that the level of Tank01 would have its level tag named
15TANK01LI.PV. With that in mind, substitution parameters would make it possible to
configure the Level attribute at the template level in such a way that any newly created tank
in the PI AF hierarchy would automatically see its Level attribute mapped to the correct PI
Server tag. The idea here is to have all the required information somewhere in the structure so
the attribute can reconstruct the tag name depending on where it is in the hierarchy. A
solution to the above tag naming convention would simply be to add an ID attribute under the
city name element.
Then, the Level attribute could be built using the following configuration string:
\\%Server%\%@..\|SiteID%%Element%LI.PV
Page 88
7.3.4
Reading a Substitution Parameter
The above %@..\|SiteID% substitution parameter can be read as: Give me the value of the
parent-elements SiteID attribute. Each symbol in the previous substitution parameter mean
something different. In order to better understand what each symbol mean, refer to the
following table, giving the definition as well as examples.
Symbol
Examples
Consider the expression as a

substitution parameter.
%Element%, %Attribute%
Navigate a level down.
%@.\<ChildElement>|<Attribute>%
..
Navigate a level up.
%..\..\Element%, %..|Attribute%
References an element.
%..\Element%
References an attribute.
%..|Attribute%, %@|<Attribute>%
References the value of the

object instead of its name.
%@..\..\|<Attribute>%
%[]%
7.3.5
Definition
Solo / Group Exercise Using Substitution Parameters in a Template Attribute

Exercise Objectives
Assemble substitution parameters to automatically map PI Server tags to PI AF

attributes.
Problem Description
Velocity Terminals will buy other facilities in the next few months where multiple tanks are
present. They are going to implement the same tag naming convention at those new locations
and will want to save time when adding those extra assets to the actual PI AF hierarchy.
They want to use the substitution parameters to speed up the asset addition/configuration
process in PI AF. To demonstrate that this is feasible, you are asked to convert the Level
template attribute of the Tank element template so that it uses substitution parameters to
automatically find the correct PI Server tag.
Looking again on the Velocity Terminals portal, you find the below table in a spreadsheet:
ID
15
Location
Montreal, Canada
Page 89
ID
Location
23
Sydney, Australia
44
Tokyo, Japan
Approach
1.
2.
3.
Create an attribute under each city Element to display its ID (hints: you may want to use a Table
along with an Element Template and a Table Lookup Attribute Template).
Modify the Level attributes configuration string for the Tank template, using substitution
parameters so that the tag names are automatically built according to the expected tag naming
convention.
Validate the new configuration string by selecting a tank (between Tank05 and Tank10), and rightclicking its Level attribute to select the Reset to Template option.
Note: Because the Tank template was created from the Tank01 element, the Level attribute of Tank01
will be changed by the above exercise. In order to correct the situation, simply edit the Level attribute of
Tank01 so it points to the BA:LEVEL.1 tag.
7.3.6
Value Retrieval Methods
The value retrieval methods of the PI Point Data Reference allows an attribute to retrieve a
value based on a relative time instead of the current value, or aggregate values such as
averages, totals, minimums, etc.
By Time Retrieve a value other than the current one
Page 90
Specify a relative time to be used with the By Time retrieval option in the Relative Time
field. Specify the time expression as a PI System Time format (ex.: -2h or T+6h). Refer to
section 1.3.2 for more details on the time expressions. Select in the By Time list box, the
value to return with regards to this relative time. This list box basically indicates whether to
pick a real value in the PI Server archive or to interpolate a value at the relative time
specified.
By Time Range Retrieve the result of an aggregation

The PI Point Data Reference can be used to retrieve and display summary calculations over a
time range. In order to use this feature, the By Time option should be set to Time Range
Override (if not, the time range parameters will be ignored and the By Time retrieval method
will be used instead). Then set the Relative Time field and select the desired summary
calculation from the By Time Range list box.
Remember average calculations using PI System tools will calculate time-weighted averages
by default, which makes sense when analyzing time-series data where the time between two
consecutive events is not always the same (due to exception and compression).
Also notice that when using the Total as the summary calculation type, an extra drop-down
appears to specify the time units of the rate tag or attribute over which the calculation is
performed. That is required since the PI Server always assumes a rate tag to be in units/day.
Selecting the right time units is thus essential to retrieve a valid result.
Note: A substitution parameter could be used for the Relative Time field. For example, an
enumeration set attribute called Time Offset could contain the following (*-30m, *-1h, *-2h, *-1d). This
Page 91
would then allow a user or an application to quickly change the summary calculation time range by
selecting the desired value from the enumeration set.
For more information see "Configuring a PI Point Data Reference: Basic

Steps" in the PI System Explorer 2012 User Guide, version 2012, p. 81.
7.4 Using the Import / Export Feature in PI System Explorer

From PI System Explorer, it is possible to use an Import/Export feature to export the
configuration of any element to an XML file. Using the Import functionality, it is then
possible to import back this PI AF object into another PI AF database. This can also be used
to back up a PI AF structure before performing potential destructive actions.
It is possible to export almost any PI AF object by simply right-clicking that object and
selecting the
option. To export the whole PI AF hierarchy along with all the
necessary information to rebuild it completely, simply use the File > Export to File option.
In order to be able to rebuild the structure as is, it is required to check the Include All
Referenced Objects, so that Templates, Tables, UOMs, etc. are also exported to the .xml
file.
Page 92
7.5 Solo / Group Exercise Speedys Pizza and Advanced Template Design
Exercise Objectives
Design Templates for PI AF which use template inheritance.

Implement elements from these templates which use PI Point Data
and Formula Data References.
Problem Description
You are installing a PI Server and PI AF for Speedys Pizza and you are
currently focusing on Speedys delivery fleet.
(A file to create the tags required for the exercise Speedys Pizza is located at
C:\Class\Exercises\03_Speedy's Pizza\SpeedysPizza_Tags.xlsx or the location specified by
your instructor).
Speedys Pizza has eight (8) delivery vehicles:
ID
Model
License Plate Number
SP1
PizzaStar
CA HYK427
SP2
PizzaStar
CA HRZ648
SP3
PizzaStar
CA HBB139
SP4
JCar SuperVan
CA HAR990
SP5
JCar SuperVan
CA HEED21
SP6
JCar SuperVan
CA HQB932
SP7
StoreRunner
CA HOT263
SP8
StoreRunner
CA HEE563
All of Speedys vehicles have been instrumented for a few things:

Measurement
Tripmeter
(miles since last fill up)
Gas Tank Level
Speed
Time Counter
(time since vehicle left the store)
Units
PI Server Tag
Mile
SP?.Trip
Percentage
SP?.GasLvl
Mile per Hour
SP?.Speed
Minute
SP?.Timer
Page 93
The first three of these measurements are sent back to the store with real-time updates via
radio. The time counter for each vehicle is maintained at the store.
Each type of delivery vehicle can also send other information over the radio link:
The PizzaStar vans have a gas tank capacity of 20 US gallons and also capture:
Measurement
Units
PI Server Tag
Warming Oven Temperature
Degree Fahrenheit
SP?.OvenT
Engine Temperature
Degree Fahrenheit
SP?.EngT
Percentage
SP?.OilLvl
Oil Level
The JCar Supervans have a gas tank capacity of 30 US gallons and capture additional data:
Measurement
Units
PI Server Tag
RPM
SP?.MtrRPM
Degree Fahrenheit
SP?.EngT
Oil Level
Percentage
SP?.OilLvl
GPS Longitude
Seconds (")
SP?.GPSLong
GPS Latitude
Seconds (")
SP?.GPSLat
Motor RPM
Engine Temperature
The two StoreRunner vehicles have a smaller gas tank capacity of 15 US gallons and also
have:
Measurement
Units
PI Server Tag
GPS Longitude
Seconds (")
SP?.GPSLong
GPS Latitude
Seconds (")
SP?.GPSLat
The GPS readings are in Seconds (") (from the Plane Angle UOM Class, where there is a
relation between degree, minutes and seconds). The degrees and minutes are assumed.
Speedys Pizza wants the Fuel Efficiency in miles per gallon (MPG) (double) for every
delivery vehicle.
Your task is to build the templates, elements and configure the attributes required to support
Speedys Pizza vehicle monitoring system.
Approach
Page 94
Vehicles information is also present in the C:\Class\Exercises\03_Speedy's

Pizza\SpeedysPizza_Vehicles.xlsx file.
Optimize the use of PI AF template inheritance so that those attributes common to
multiple vehicles are part of the same template.
For the Fuel Efficiency calculation, you actually need the inverse of the remaining
fuel (the fuel consumed since the fill-up when the tripmeter was reset):
Tripmeter / ((100 - Level) * Capacity), right?
(Optional) Also produce the Range calculation in miles for each vehicle (fuel
efficiency * remaining fuel).
(Optional) Display the Fuel Efficiency in liters per hundred kilometers (L/100 km).
In order to convert from MPG, the Formula option will need to be used when
specifying the conversion.
(Optional) Categorize the attributes by grouping them in categories and display them
in those groups by checking the
checkbox in the upper right
corner of the attributes Configuration Panel.
About Attribute Categories

Categories can be used to group PI AF objects like elements, attributes or tables together to facilitate the
administration of those objects. To add an attribute to a category, simply select one or more category from
the Categories field of the attributes Configuration Panel, or alternatively write the category name. If that
category does not exist yet, a prompt will be shown to ask if this category should be created.
For special calculation features, like the custom Rollup data reference (that will be introduced during the
final exercise), categories will play an essential role as they will allow for aggregations to be calculated.
Page 95
7.6 Group Discussion Where are my Assets? (Part 2) / PI AF System

Project Management
Questions
1.
Generally, there are two approaches to implementing PI AF:

a) Start with the PI Server tags, organize them into assets, and discover the commonalities around
the assets and develop templates from there.
b) Start by developing the templates you know you will need, and assign the appropriate PI Server
tags to the template PI Point data references configuration strings.
Which approach seems more appropriate for your implementation of PI AF?
2.
Which application of PI AF do you think will be most useful for your process: a database of assets,
or databases of contextual data which can add value for this process?
3.
Some processes (like data centers or wind turbine farms) can be described with only a handful of
templates because they have a great many of just a few types of components, while others (like
power plants or oil refineries) have many unique things and very complex relationships and could
require hundreds of templates. Others are somewhere in between. Where on this spectrum would
your process fall? Although implementing PI AF is considerably more challenging for more
complex processes, can you see where it could provide more value? If you have very few repeated
components, can you still see benefit in using templates? For instance, might templates be useful
when implementing PI AF across a fleet of sister plants?
4.
Do you think you have to have the whole system, the entire plant or the entire fleet described by PI
AF to get value from it?
5.
PI AF implementation projects that are done entirely by process engineers will often do many things
the hard way because they are missing the data wrangling and system knowledge that I.T.
professionals bring to the effort. On the other hand, if I.T. departments attempt to implement PI AF
without the critical input of subject matter experts, they will likely produce something shallow
without as much value because most I.T. departments do not understand the process well enough to
make valuable templates. Do you think your PI AF implementation project can benefit from I.T. and
process engineers working together?
Page 96
Communicating Important Events
8. Communicating Important Events

8.1 Introducing PI Notifications
PI Notifications is an event filter and alerting application based on the PI System (PI AF) that
provides the ability to communicate important events to people as well as applications or
systems.
As the PI Notifications service is based on PI AF, it can provide alerts on data from multiple
PI Servers and other data sources. Every PI Notifications server has however one PI Server
which holds its history (called the history PI Server). It keeps a record of all notification
instances/events, when they started and ended and the end user responses to them
(acknowledgements and comments). PI Notifications configurations are stored in its
corresponding PI System Database (AF Server).
Very often in work, the measure of success is done on how many things are produced. For PI
Notifications, the more alerts are produced, very often the less successful the use of PI
Notifications becomes. If too many alerts are provided to a recipient, he probably wont be
able to give each one of them the appropriate attention or response. This will make the
implementation useless as all of the alerts will become noise to the recipients. Most PI
Notifications implementations analyze billions of new values per day and produce less than a
dozen events per day.
Hence, it is crucial to carefully filter the notifications rules so as to produce only appropriate
alerts. This suggests the creation of all notifications rules should be done as a two-step
process:
1.
2.
Create the notification (rule).

After some time passes, evaluate the triggering frequency of the rule.
Page 97
If the frequency seems appropriate, finalize the configuration by specifying recipients.

If it is producing too many alerts, re-evaluate the trigger conditions and wait another interval
before qualifying the notification again.
This is how well learn about PI Notifications. First well look at triggering and filtering and
later, well look at content, subscriptions, delivery channels and recipient response.
8.2 Group Discussion Frequency of Alerts

Questions
1.
Lets say you have a teenage driver and you could have the family car send you e-mail or text alerts
whenever they were driving it. What kind of alerts would you like to get?
2.
Lets say you have a company with six hundred (600) delivery vehicles. Would you still want to be
aware of the same alerts?
3.
What if you had six thousand (6,000) delivery vehicles? Would this have an impact?
4.
If we start making notifications, sometimes getting an alert per week can seem reasonable. But what
if you start building more notifications and eventually have 600 alerts a week. Is it still reasonable?
Even if each rule seems individually reasonable?
5.
Thinking of your process, what would make good alerts? Grade/product batch changes? Noncompliance (governmental) events? SQC / SPC out of control violations? Equipment or subsystem or
system or unit failures? Is the e-mail inbox a good place for the sort of alerts that occur regularly in
the control room?
Page 98
8.3 Directed Activity Installing PI Notifications (Optional)

Activity Objectives
Note: Although almost all classroom settings will have PI AF servers and clients already installed, not all
will have PI Notifications installations. Follow your instructors guidance if you are required to install PI
Notifications to continue.
The instructor will identify which components will need to be installed on each students
computer (if not already installed):
PI Notifications Client alone.

PI Notifications Client + Service.
PI Notifications Client + Service + Acknowledgment Webpage
Identify the appropriate History PI Server for the installation. Notifications history will be
stored in seven (7) tags per notification on that PI Server (counts as one (1) tag in the license
as of PI Server 2010 SP1+).
Install the required PI Notifications software on the participants computer:
PI AF
History PI Server
SMTP Server
From Email
Page 99
The installer contains the following features:

8.3.1
PI Notifications Client
This feature includes add-ins to PI System Explorer. Within this host, you configure,
subscribe to or unsubscribe from, and view the archived or active events of notification rules.
The client also enables you to receive new events through PI Notifications Desktop Alert.
The PI Notifications client will require (and install if needed) the PI AF Client. Note that
even if the class is using a shared PI Notifications Server if the PI Notifications Client is not
installed the necessary components will not appear under PI System Explorer.
8.3.2
PI Notifications Service
This feature runs a service instance to evaluate notification rules in real time, send out
notification messages, process acknowledgment requests and escalations, and record the
history in the history PI Server. In practice - the server is generally installed on a server class
computer, which may be shared with the PI AF server or may be a dedicated server. The PI
Notification Service is associated with a given PI System (AF Server) and has a specified
history PI Server to record its history though it can trigger and read data from any PI Server
which the PI System recognizes.
8.3.3
PI Notifications Acknowledgment Web Page
This page provides a link which is embedded in the email message; a subscriber can click
directly on this link to acknowledge a notification message or to comment on a notification
instance. The PI Notifications Acknowledgement Page requires Microsoft IIS 5.0 or greater
and ASP.NET 2.0 installed on the same machine. For Microsoft IIS 7.0, the IIS metabase and
IIS 6 configuration compatibility option must be enabled.
Note: During installation (or subsequently in the Notifications settings menu) you will be requested to
submit an SMTP server and an optional backup SMTP server. This is generally a corporate sponsored
mail server that will be used to receive and forward the e-mail based alerts from PI Notifications. Note
that although any Internet Information Service that comes with any Microsoft server operation system kit
can install an SMTP mail server, it is rarely received well by Information Technology policies and
management to start such a rogue mail server for a specific purpose such as this. In general it is always
good practice to identify the management of your established mail servers and coordinate the application
of PI Notifications with them. Installation of an SMTP server is not required for the class.
Note: By default the PI Notifications installation does not start its Windows service. Navigate to the
Windows Services applet to start the PI Notifications Scheduler service for the first time.
Page 100
8.4 Directed Activity PI Notifications State Groups and States (Global

Configuration)
Activity Objectives
Create a New State Group and States.

Review Global Configuration Settings.
Notification States are reason codes that provide priority and a classification of the
essential type of alert. These can be grouped into state groups for organization. Examples for
groups include Operational Alerts, Compliance alerts, Quality Alerts, System Alerts, and
Environmental Alerts. Examples for States include tank overflow/spill alert, six minute noncompliance alert, critical equipment failure, etc.
State Groups and States
Like Units of Measure, State Groups and States cross all databases on a given PI System. For
this reason all students in a class cannot build the same State Groups and States. As before, if
you are on a shared server, watch your instructor build this group and states. If you have a
dedicated PI AF Server and PI Notifications, build these as described below.
1.
2.
3.
4.
5.
Select Notifications from the Lower Left Navigation Panel.

Select Tools from the Menu, then select Notification Settings, then select State Group Configuration
(this will not appear unless Notifications are selected in the navigation panel).
Click on the New State Group Button/Tab and it will pop up a State Group enter Tank Alerts.
Click on the New State Tab and enter a new alert Overflow, leave the priority as Normal and select
Tank Alerts as the Group.
Enter another new State Empty and assign it to the Tank Alerts group as well.
This should be visible to all users of any database on the PI System.

Global Configuration
Under the Global Configuration tab you may specify the PI Server for History storage (aka.
History PI Server), a PI WebParts server (optional) so that instant trends can be included in
the Notifications content and messages. The Acknowledgment Web Page path can be entered
here if it was not entered during the installation. There are other options that are explained in
the documentation.
Page 101
8.5 Directed Activity Triggering the Alerts

Activity Objectives
Create a new notification on an existing PI AF element.

Apply triggering options.
Apply filtering options.
Approach
Well configure a Notification for our tanks. This notification will trigger whenever Tank01
is over 95% full and contains HC1500. Tanks regularly reach high levels, but HC1500 is
caustic and if it spills, well have an environmental reporting mess on our hands, so we want
to know if it is almost full. Other chemicals are not considered dangerous.
Follow the instructor during this section, well have the opportunity to work independently a
bit later:
1.
2.
Open PI System Explorer and display the Velocity Terminals structure.

With Notifications selected in the navigation pane, select New > Notification.
Overview tab
3.
Name the notification Tank Overflow.
Trigger tab
4.
5.
6.
7.
8.
Click the upper Select Target button and select the Tank01 element.
Under Conditions, select New Condition > And Conditions, since we need two conditions to be true
to send a notification.
From the And Conditions window, select New Condition > Comparison.
For the input, click the search icon and select the Level under attributes.
This is an overflow alert, so select > for the operator.
Note: We could enter the value here and specify the limit over which to send the alert, but it will be left
blank for now as the value will be entered in the template.
9.
Leave the Value field unpopulated and click OK. PI System Explorer will confirm whether you
want to do this; select Yes.
In the Library (Navigation Panel) under Element templates, locate your tank template.
Select the attributes tab and right-click on the Level attribute. From this select New Child
Attribute Template.
This should create a hierarchical child attribute under Level. Call this Overflow Limit set the
value type to double and the default UOM to % (Ratio). Then enter a default value of 95 and save
Page 102
the modifications.
10. Return to Notifications and select the Tank Overflow notification. Under the trigger tab, double-click
on the comparison condition to edit it.
11. Instead of a value, select Attribute for the Compare to section, and then use the search button to find
the new Overflow Limit attribute.
12. The next option is a Deadband limit (think of it as a reset limit). Lets set this to five (5).
About the Deadband Option
The deadband prevents the level from exceeding the limit and then sending the alert every time it crosses
and recrosses the limit, even though we essentially do not have a new event; the value is just still high. In
order to generate a new event, the value must go below the deadband to close the first event and reset the
notification, then if it crosses the limit again that will be a new event. This is a very important way to
filter events.
In our tanks example, the deadband is set to 5, so if the value drops below 90, the first event will be
closed. If a deadband is not set then every time the level crosses the limit it will close and re-open a new
alert event.
13. We wanted our alert only to be sent if there is an overflow condition when the tank contains product
HC1500. Thus select New Condition > Comparison, still from within the And Conditions window.
14. Select the Product attribute as the Input and the In operator and then enter HC1500 as the Compare
to value. The In operator is required here since the Product attribute is configured as an
Enumeration Set.
15. The deadband condition does not apply in this case. Click OK.
16. The next option is a Time True filter. This option is also an important filter because it prevents
alerts from being sent on momentary anomalies or spikes. It asks that a condition be true for a
given amount of time before it generates an alert. Set this to 3 seconds.
Page 103
About the Time True Option

To prevent false alarms, use Time True to specify the length of time the condition must be true to trigger
the notification rule. The Time True Option defines how the notification Time Rule affects the meaning
of the Time True value:
The Clock option for Time True causes an alert to be sent as soon as the condition has been true for the
specified time, independent of the Time Rule setting. Thus, the Time True value represents the exact time
that the condition must be true to trigger the notification.
The Natural option for Time True causes an alert to be sent only after the condition is re-evaluated as
specified by the Time Rule setting. In this case, the Time True value represents the minimum time that the
condition must be true to trigger the notification rule. If the condition is evaluated on a PI Point data
reference, for example, it will wait for the next PI value on that tag to arrive at the snapshot and if it is
still true and the time true time has passed then the condition will contribute to the trigger.
Note that while the Time True filter can be very useful in eliminating false alerts, it necessarily introduces
latency. The alert cannot be sent until the specified time elapses. If the Natural option is selected this
can take longer as the trigger waits on another value from the triggering source (often a PI tag).
17. The next option sets the State Group and State for this condition. Select Tank Alerts and Overflow.
Leave the Priority as Normal.
18. At the bottom of the Trigger tab panel there are several more filtering options. The first is the Time
Rule. Lets leave this set for Natural.
About the Time Rule Setting
The time rule establishes how often the trigger will be evaluated. If this option is Natural the trigger will
be evaluated whenever there is any change to any of its input values (even if those input values are
attributes calculated from other attributes). This is usually how Notifications are triggered if they are
based attributes on PI Point data references.
The Periodic time rule allows you to set how often the trigger is evaluated. You can set this in seconds,
minutes or hours, or set it to evaluate daily or monthly (even selecting which days and which months).
This option is handy when the triggering input is not based on PI (i.e. a piece of equipment going in or out
of service which is connected to a Table Lookup data reference to a table linked to a view of the
maintenance system), or when PI Notifications is being used for reporting to send periodic status
updates.
19. The next option is Notify only on change in status and it is usually selected. This is an important
filter as well. Lets leave this option selected.
Page 104
About the Notify only on change in status Option

Normally PI AF triggers when (using our current example) the level exceeds the limit, but does not
trigger on subsequent high values unless the value dips below the limit or deadband / reset value or the
event is closed by some other condition (like the Product changing). If you uncheck this option a
Notification alert will be sent for every trigger that meets the conditions. This can generate quite a few
alerts. A case where this might be appropriate would be if triggering on six minute Continuous Emissions
Monitoring data, where you are required to report every value which exceeds the limit. In this case, even
if the last value was in excess of the limit, you still have to report the next. This can be accomplished by
unchecking the Notify only on change in status box. Note, however, that in this example we are using
six minute data, so there will be a limit to how many alerts can be generated).
20. At the very bottom, there are two more filtering/triggering options: Resend Interval and Non
Repetition Interval. Lets set both of these for 10 minutes.
About the Resend and Non Repetition Intervals
The Resend Interval is related to the Notify only on change in status box. If the conditions to trigger
the Notification are still true after the resend interval has elapsed, and the notification has not been
acknowledged, another alert will be sent, even if the Notify only on change box has been checked. This
generates more alerts, and would generally only be used for important alerts that should not be ignored if
they persist.
The Non Repetition Interval filters out all alerts that would otherwise be triggered within the specified
period of time since the initial alert. In other words, this tells the Notification: no matter what, dont
trigger another alert more often than .
When determining what interval to use, remember 10 minutes still means a possibility of 144 alerts per
day!).
Both of these are absolute time clocks; there is no natural setting to make sure another event has been
received. The Resend Interval can be seen as a maximum time between two e-mails while the Non
Repetition Interval can be seen as a minimum time between two consecutive e-mails.
21. Finally we have our triggers and filters configured. Check in your work and then click on the Tank
Overflow alert. Note the green triangle ( ) start button on the notifications bar above it. Click this
button to start your notification (if the button is grey, verify whether your PI Notifications
Scheduler service is running).
22. Restart the PI Notifications Scheduler service from Start > Administrative Tools > Services. This is
only required when the first notification is started on the PI AF system, in order to make sure all the
PI Notifications components are connecting to the PI Server successfully.
Page 105
23. Go back to the Elements and take a look at Tank01. Select HC1500 as the product and write a value
greater than 95 for the Level (in order to be able to write values from PI System Explorer, open the
Settings for the Level attribute and uncheck the Read Only checkbox at the bottom).
24. Go back to your notification configuration and verify it was triggered by looking on its History tab.
The configuration of the Content and the Subscriptions tabs will be covered later.
8.6 Directed Activity PI Notifications Templates

Activity Objectives
Convert our Notification into a template.

Apply this Notification template to other elements which have the same element
template.
Set the Notification template rules for generating Notifications when new elements
are created.
Learn about Notification browser options.
Approach
Since we have more than one tank, we should create overflow notifications for all of them. PI
Notification templates apply the same great template functionality of elements templates and
allow the creation of many PI Notifications very efficiently and rapidly.
1.
2.
3.
4.
Open the Velocity Terminals database.

Select the Tank Overflow notification and from the right-click context menu, select Convert to
Notification Template.
Locate the Tank Overflow Template in the Library, under Notification Templates. Look under the
Trigger tab and notice the target is the Tank template, the template of Tank01.
Under the Overview tab, select to Automatically create a notification for each element from the
Creation and Startup Options section.
About Notification Templates

Every notification is tied to an Element Template (through the template designated in the Target field,
under the Trigger tab). As such, a notification template will have the option to automatically create a
notification for each element, which means a notification rule will be created for each new element that is
created from the target element template. Notifications for existing elements must be created manually.
These options can be very convenient, just be careful as this may result in many new notification alerts.
5.
6.
Check in your work and then right-click on the Tank Overflow notification template to select New >
New Notification. This window now shows existing elements from the target element template.
Select only those elements with no existing Tank Overflow notification by selecting the top option
Page 106
7.
8.
9.
Select > Elements Without Existing Notification. Make sure only the tanks under the nonreplicated hierarchy are checked (the MDB to AF synchronization structure may show up additional
tanks in the list).
Click OK to create the missing notifications for the other tanks and return to the Notifications section
to confirm the notifications creation.
To see which tank a notification applies to, simply display the target element name like in the below
picture:
Go to Elements in the navigation panel. Create a new child element (Tank11) under the Tokyo site
based on the Tank template, just to confirm that a Tank Overflow notification was automatically
created.
8.7 Formatting the Information to Deliver

As part of the PI Notifications software, a complete formatting tool is available to define
what information to provide to people, applications and systems, as well as how to provide
that information via an email. As with the majority of the PI System Explorer objects, the use
of templates is possible and desired. These templates are called Formatting Templates and
once created they may be used by any notification and, if necessary, customized.
8.7.1
Directed Activity Message Formatting Templates

Activity Objectives
Prepare two (2) message formatting templates for email and text message delivery.
Approach
1.
2.
3.
4.
From PI System Explorer, navigate to Notifications > Tools > Notifications Settings, then select
the Delivery Formats tab.
Right-click the existing Global Default Email format and select Duplicate. Rename the new format
as Default Email with Table.
Right-click the existing Global Default Email format and select Duplicate. Rename the new format
as Default Text Message.
Select the Default Email with Table format and modify the formatting so that a table will be
available to organize the information related to the notification.
Page 107
About Formatting Messages

The Delivery Formats tab from the notification settings as well as the Message tab from within a
notification have a Content section on the right side to add extra content to the message. From that
Content pane, simply drag and drop, or double-click on the desired content to add it to the message.
Only generic content can be added within the Delivery Formats section. Specific content can be added
when configuring the Message tab of a specific notification or a notification template.
5.
Select the Default Text Message format. Remove everything from the Body section of the message,
to keep a single-line message that will mention the notification name, the target elements name and
leave a space to enter the trigger value.
Page 108
6.
Click OK to make those formats available.
8.7.2
Directed Activity Configuring the Tank Overflow Notification Messages

Activity Objectives
Compose notification messages from message format templates.
Approach
We want to prepare two (2) message formats to send to our recipients. The first message
format is meant for email delivery and should include a table to display the critical
information. The second message format will be used to send a text message.
1.
From the PI System Explorer Library section of the navigator panel, select Templates >
Notification Templates > Tank Overflow, and then select the Message tab.
Tank Overflow Email with Table

2.
Right-click on the Default Email with Table message format template and select Duplicate.
Page 109
3.
Rename the duplicated format Tank Overflow Email with Table.

Add the appropriate information in the table part of the message Body by drag and dropping or
double-clicking on the information from the Content right-side pane. The second row of the table
should include the Level information (Content > Trigger Input > Level) while the third row could
include the Volume information (Content > Target Attribute (Tank) > Volume).
About Adding Additional Content to a Message

To add additional content, click the Add button at the top of the Content pane to add an attribute value,
file or Web links, or even files as attachments to the email sent to the recipient. These files or links or
extra attributes value should help the recipient taking the necessary decision after receiving that
notification.
4.
(Optional) Using the Content pane on the right, add a File from your computer and then drag and
drop it on the Attachments section, located between the Subject and the Body message sections.
Tank Overflow Text Message

5.
Right-click on the Default Text Message message format template and select Duplicate. Rename
the duplicated format Tank Overflow Text Message.
Page 110
6.
Add the Trigger Input > Level > Value and Units within the brackets of the Subject section.
7.
Check In the changes.
8.8 Delivering the Events

PI Notifications Delivery Channels provide for the mechanism by which alerts are delivered
to subscribers. With the standard installation of PI Notifications, three (3) delivery channels
are available: Email, OCS - Office Communications Server (aka Lync) and Web Service.
The top-level configuration of those delivery channels for the PI Notifications server is done
via the PI System Explorer. From the Notifications section of the navigator panel, access the
configuration settings by selecting Tools > Notification Settings > Delivery Channels.
There, the Email and the OCS delivery channels can be configured by right-clicking and
selecting Settings.
8.8.1
Email
The settings for the Email delivery channel allow to configure the primary and backup SMTP
server to relay the emails as well as the From email address for the alerts. The IT department
should indicate which servers and ports to use for the primary and backup SMTP servers. As
for the Sender Email, this address is not validated and can thus be set to any address desired
(i.e.: PINotifications@domain.com). In most cases, the Allow contacts to set sender email
should not be enabled.
Once the email delivery channel is setup, most email addresses should be provided by Active
Directory (AD). If the AD doesnt include all email addresses needed, it will be possible to
create additional emails within the Contacts section of PI System Explorer, as it will be seen
in section 8.9 Adding Contacts.
Page 111
8.8.2
OCS Office Communications Server (aka Lync)
The Microsoft Office Communications Server (OCS) delivery channel provides delivery of
messages to the Microsoft Office Communicator service, now known as Microsoft Lync.
This delivery channel provides for integrated email and instant messaging alerts to clients.
For the companies that use Microsoft Lync, this can be a powerful way to connect people to
the process.
The delivery channel consists of two (2) components: the PI Notifications OCS Delivery
Channel and the PI Notifications OCS Relay Service. The first is a plug-in that comes with
PI Notifications and thus installed on the PI Notifications server, while the second is a
separate installation kit that needs to be installed on the Microsoft Lync server. It acts as an
intermediary between the OCS delivery channel and the Lync server.
To configure the OCS delivery channel, select the Notifications section from the navigator
panel and select Tools > Notification Settings > Delivery Channels. Right-click the OCS
delivery channel and select Settings to enter the FQDN (Fully Qualified Domain Name) of
the Microsoft Lync / OCS server. Again, IT personnel should be able to provide all the
required information.
For more information see the OCS section in the PI Notifications 2012
User Guide.
The OCS or Lync contact addresses are also usually retrieved from the Active Directory.
Again, it will be possible to explicitly add those addresses from PI System Explorer, by
creating what is called a new Delivery Endpoint of type OCS.
The OCS Delivery Channel consumes presence information from OCS to decide whether to
try to send an instant message. The selected presences specify the levels of presence for
which this delivery endpoint should receive message. When a notification is triggered, a
message is only sent if the presence of the subscriber is online or one of the checked
presences.
Page 112
The OCS delivery channel will not be further discussed in this class as it will not be
configured nor used in the exercises.
8.8.3
Web Service
The Web Service delivery channel allows PI Notifications to contact and provide information
to a Web Service by calling one of its Methods. To use this delivery channel, a Web service
must thus be available on a Web server that the PI Notifications Scheduler service is able to
reach.
About Web Services
A Web service is a method of communication between two electronic devices over the Web. In most
cases, it is a service hosted on a Web server that provides methods to its clients. Those methods will
usually wait for incoming information from one end, then crunch the data, to finally return the data to the
same client or pass that information to another one.
There are many Web services commercially available, and many development environments
offer templates and other tools to develop custom Web services. Just to have an idea of a
Web service, the http://www.webservicex.net/ website offers samples like a Global Weather
werbservice. Access this Global Weather Web service and try to retrieve weather conditions
for the local classroom nearby city.
http://www.webservicex.net/globalweather.asmx
Page 113
The above is the standard look of a Web service. Notice the two (2) available methods:
GetCitiesByCountry and GetWeather. Keep in mind Web services are usually not accessed
by people, but rather accessed by applications to retrieve or transfer information, meaning
this user interface is rarely looked at.
Unlike the other two default delivery channels, the Web service is not configurable from the
Notifications section. The only configuration necessary to send information to a Web Service
via PI Notifications will be done when creating a new Delivery Endpoint of type
WebService from the Contacts section of the navigator panel in PI System Explorer. That
will be seen in a later section.
8.9 Adding Contacts

The Contacts section of the navigator panel of PI System Explorer allows the definition of
contacts. The contacts will be receiving the notification message once it is triggered. This
section defines the various types of contact objects that can be created and used by PI
Notifications.
8.9.1
PI Notifications and Active Directory
PI Notifications normally gets the contacts and their addresses (email, OCS, etc.) from the
configured domain Active Directory (AD) database. This prevents from having to do the
tedious task of entering all of the potential subscribers and their contact information to start
using PI Notifications.
This AD access is configurable from the Contacts navigator panel section, and then from the
Tools > Active Directory Properties menu item. If the PI Notifications service runs on a
domain machine, it should automatically find the Active Directory server through DHCP and
configure itself. If configuration is necessary, it is possible to use this window to specify the
FQDN of the Active Directory / DNS server and the domain identity PI Notifications should
use to retrieve the contacts.
Page 114
8.9.2
Searching for Contacts
Because the Active Directory database are often very large, contacts information is only
available from search results. To search for contacts, click the
button under the
Contacts section or use the search field. The star (*) can be used as a wildcard for that search.
OSIsoft classrooms computers should return all student AD users by performing a search for
stu*.
By default, only AD users will be returned from a search. AD groups can also be returned and
subscribed to a PI Notifications by modifying the Notification Settings > Global
Configuration > Show Active Directory Groups from False to True.
Page 115
8.9.3
Directed Activity Adding Contact Information

Activity Objectives
Create a new contact for PI Notifications.

Link a custom email address to an existing contact.
Problem Description
For those who dont have entries in Active Directory or if you dont have access to your
Active Directory (which is worth pursuing), you can enter custom contacts one at a time. This
may be appropriate for vendors or other contacts not in your company who you may still
want to send notifications to. Custom contacts (like UOM and PI Notifications States) are
available to all PI AF databases.
Approach
Adding a custom contact in PI System Explorer:
1.
2.
3.
To create a custom contact, select Contacts from the navigator panel.

Select New > New Contact from the toolbar.
Enter the contact Name and Email address information and check in your changes.
Note: E-mail accounts are available for the students to use on Outlook.com. These accounts are the
following:
PIStudent01@outlook.com (password: student01)
PIStudent20@outlook.com (password: student20)

Note that the password for PIStudent10@outlook.com is password10.
Adding a custom email contact information to an existing contact:
4.
5.
6.
7.
8.
Search for an existing contact using the

.
Right-click on the contact name and select New Delivery Endpoint.
Give it a name of <Contact Name> - SMS to follow the same naming convention.
Select Email as the delivery channel.
Enter an email address for your mobile phone in order to be able to receive text messages via PI
Notifications
(visit http://en.wikipedia.org/wiki/List_of_SMS_gateways for a list of all SMS gateways).
9. Uncheck the Use HTML for Format check box and check in your work.
10. Optionally click on the Test button at the bottom to send a test SMS to your phone.
Page 116
8.9.4
PI Notifications Groups
A Group is an unordered collection of delivery endpoints which includes Active Directory

recipients. If a notification is configured to send a message to a PI Notifications Group, the
message is sent to all members of the group simultaneously.
Try this out:
Create a new group called Active Students that will regroup all StudentXX users currently in
use in the class. Create the group by right-clicking the Groups folder and selecting New
Group. Use the Contacts pane on the right to search for contacts and drag and drop them on
the Viewer section to add them to the group.
8.9.5
PI Notifications Escalation Teams
An escalation team is a delayed delivery group which receives alerts on a notification only if
a specified time period called the Escalation period has elapsed, and the acknowledgement
requirement is not satisfied. Acknowledgments will be discussed in a later section, but it is
the ability to inform the PI Notifications server that the alert was acknowledged by a contact.
When a notification alert is sent to initial subscribers a timer is started, and if the
acknowledgment requirement is not satisfied by the time the escalation teams timer is up, the
escalation team will be sent alerts which will be labeled as escalation alerts.
Building escalation teams is very similar to building groups and so they can be included in
the subscribers area of a notification. Keep in mind that if an escalation team is added to a
notification that does not require acknowledgements, they will never receive alerts.
Try this out:
Create a new escalation team called Students Escalation by right-clicking the Escalation
Teams folder and selecting New Escalation Team. Add your StudentXX user as well as your
neighbor StudentXX contact and select a 5 minutes Escalation period.
8.9.6
PI Notifications Delivery Endpoints
A delivery endpoint is simply any subscriber to a notification, like everything that was
defined in the present section. However, one type was not mentioned and is here defined.
This delivery endpoint is the Web Service. As part of the classroom installation, a Web
Service for testing should be installed and available.
Webservice example: The Work Order Generator (Optional)
This is a custom Web service designed to act as an automatic work order generator. Imagine a
notification that would trigger whenever a piece of equipment needs maintenance. Via the
Webservice, the notification would pass all necessary information to the maintenance system
so a work order can be generated. For the purpose of this training, a SQL Server database
called WorkOrderGenerator will act as the maintenance system. This database is hosted on
your local SQL Server instance.
The Web service itself should be available at the following URL:
http://localhost/WorkOrderGenerator2013/Service1.asmx
Page 117
Validating the Web Service Functionality (Optional)

The NewWorkOrder method allows a user or an application to create a new work order
entry in the SQL Server database by passing the following information: equipment name,
failure type and action to take. From the Web page of the Web service, click the
NewWorkOrder method and enter something for the EquipmentName, FailureType and
ActionToTake fields, then click the Invoke button. If the following shows up, then work
order was successfully generated. Again, remember Web services are not meant for user
interaction.
Page 118
<?xml version=1.0 encoding=UTF-8?>

<int xmlns=http://localhost/>1</int>
You may go ahead and query the WorkOrderGenerator SQL server database to confirm that
the new work order was successfully created in the system.
Try this out (Optional):
Create a new delivery endpoint called Work Order Generator by right-clicking the
Delivery Endpoints folder and selecting New Delivery Endpoint.
Select WebService as the delivery channel, enter the Web service URL as defined above,
click the Get Web Services button, and select the NewWorkOrder as the default method to
use. Check In the changes.
This section can be used to optionally test the Web service, but the mapping to the correct
information will be done when configuring the notifications Subscriptions tab.
8.10 Subscribing Contacts to Notifications

To subscribe contacts, endpoints or groups to existing notifications, simply navigate to the
Subscriptions tab of the Notification or Notification Template and use the Add icon or the
right-side Contacts panel to drag and drop contacts, endpoints or groups as subscribers.
8.10.1 Solo / Group Exercise Adding Subscribers to the Tank Overflow Notifications
Exercise Objectives
Set up different types of subscribers to a notification.

Demonstrate PI Notifications can provide PI System information to people and
systems.
Problem Description
You would like to be alerted of a Tank Overflow on any of Velocity Terminals tanks. You
would like to receive an email as well as a brief text message whenever that is the case.
Furthermore, a work order should be created in the maintenance system of the company
(WorkOrderGenerator databse) whenever there is a Tank Overflow.
Approach
1. Navigate to the Tank Overflow notification template from the Library navigator
panel section and select the Subscriptions tab.
2. Add your StudentXX Email and SMS contacts, selecting the appropriate Delivery
Format for each one.
Page 119
3. (Optional) Add the Work Order Generator Web service delivery endpoint, and
then configure the bottom part of the viewer to specify the values to use for the three
(3) Web service methods parameters, by double-clicking on the parameters name.
a. For the EquipementName, select the Target.
b. For the FailureType, select the Name.
c. For the ActionToTake, enter custom text: Check if maintenance is
required.
4. Check In the changes.

5. Trigger the notification for Tank01 and validate all three (3) subscribers successfully
receive the notification. The History tab can be used to verify successful delivery.
(Optional) Check the Microsoft Access database to confirm a new entry was added
following an active notification.
8.11 MyPI and PI Notifications in PI System Visualization Tools

By using the MyPI navigator panel section of PI System Explorer, you will be able to review
the active and historical notifications of all notifications you are subscribed to.
Similar views of this information can be retrieved from PI ProcessBook and PI DataLink.
There is also a desktop applications called PI Desktop Alert that adds pop-up notifications to
the Windows task bar when alerts are triggered. This application is available from Start > PI
System > PI Desktop Alert. The above functionalities are only available on a machine where
the PI Notifications Client component was installed.
Page 120
PI ProcessBooks Notifications task pane allows to search for active/recent/historical

notifications as well as to display the trigger conditions history for further analysis.
Tip
There is a known issue with PI Notifications 2012 and the Notifications

add-in to PI ProcessBook. Refer to the following article for a
workaround:
KB Article # KB00690 PI Notifications Add-in does not appear under
"View" menu in PI ProcessBook with PI Notifications 2012
PI DataLinks Notification Search add-in allows to retrieve a report of the notifications that
were triggered during that last month for example. It dumps the history information of your
subscribed notifications on the spreadsheet to allow for reporting on that data.
Note: If a contact is not subscribed to a notification, the only way he can visualize the notifications
history is by looking under the History tab of the notification in PI System Explorer.
Page 121
8.12 Solo / Group Exercise Speedys Pizza Notifications

Exercise Objectives
Create new notification templates from the Library.

Review triggering and filtering options.
Apply a notification template to existing elements.
Problem Description
Speedys Pizza wants to have three (3) things set with alerts which will be later configured to
be sent to the manager on duty (your Student number).
Speedys Pizza management wants to be alerted under the following circumstances.
Since they have a Delivery in 15 minutes or its free! policy, they want to be aware
of any vehicle that left the restaurant for more than 30 minutes (the time counter
will reset when the vehicle is back at the restaurant, so 15 minutes maximum to
deliver and then get back).
They want to be aware of any speeding vehicle. They feel no one should go over 40
mph.
If any vehicles gas tank has less than 10% gas left, they need to be aware so they
can make sure they have enough to refuel.
Approach
In order to build a notification template so that it can be applied to all types of vehicles, the
target element template must be one common to all vehicles. That also means the attributes
used in the notifications triggering condition must also be part of that element template
(Timer, Speed and Gas Tank Level).
Build the notification templates, one per condition, and then apply them to all vehicles in the
fleet.
Page 122
8.13 Acknowledging Notifications

When an implementation of PI Notifications is mature and the filters and triggers have been
successfully validated, it may be desired to implement procedures to assure that important
and rarely triggered notifications are read and acted on. This is exactly what the
acknowledgment feature of PI Notifications is for.
8.13.1 Configuring Acknowledgments
Acknowledgments are optional, but can be required for specific notifications. This is visible
under the Subscriptions tab of a notification:
It can be set by right-clicking the above line and selecting the Options item, or by clicking its
button (
) from the toolbar. If the option is set to Auto, then the notification does not
require someone to acknowledge the alert as it will be done automatically.
Number of required acknowledgments cant be bigger than the number of subscribers to a

notification. This number can also be pre-configured at the Group, Escalation Team or
Notification Template level. Although this can be useful flexibility wise, it may be best to
always set it at the same place, which is usually at the notification template level.
If at least one acknowledgment is required, the PI Notifications Scheduler will not only track
the start and end time of the notification event, but also the time at which the required number
of subscribers acknowledge the alert. In this way the subscribers performance in responding
to the alert is recorded.
8.13.2 Ways of Acknowledging
After the PI Notifications Acknowledgment Webpage component of the installation kit is
deployed on a Web server, the Web page address will be populated under the Notification
Settings > Global Configuration > Acknowledgment Web Page. This address will usually
look like the following:
http://<WebServer>/PI Notifications Acknowledgment/Acknowledgment.aspx
The Hyperlink to that URL can be included in emails sent to recipients by adding one of the
acknowledgment hyperlinks to the Body of the email message. It is already present in the
global default email format, but can be retrieved from the right-side Content pane.
Page 123
The Acknowledge With Comment hyperlink is usually a better choice to add since it allows
the user to enter a comment if needed. That Web page must be accessible from the users
computer when reading the notification email. The Web server must also have access to the
Active Directory and the PI Notifications server. If subscribers need the ability to
acknowledge from outside the domain firewall (on the Internet), then the Web server will
have to be visible externally.
Subscribers can also acknowledge a notification through the PI ProcessBook or PI DataLink
notification add-ins, or via the PI Desktop Alerts or MyPI tools.
Administrators can acknowledge a notification via its History tab, by right-clicking the alert.
Note: A notification that has ended before it is acknowledged is not acknowledgeable anymore and the
notification is considered expired. Comments can however be entered for an alert at any time, even if the
notification has expired or if it never required an acknowledgment.
8.13.3 Solo / Group Exercise Validating the Acknowledgment Process (Optional)

Exercise Objectives
Compare the various tools available to acknowledge a notification instance.
Problem Description
Tank02 has the highest capacity of all Velocity Terminals tanks. If a Tank Overflow alert
would occur for this tank, one acknowledgment should be required.
Page 124
Approach
1.
2.
3.
4.
5.
From the Notifications > Notification Settings > Global Configuration section of PI System
Explorer, copy the Acknowledgment Web Page URL and paste it in Internet Explorer to see if you
can successfully access the page (it will display an error, but if the OSIsoft logo shows up, the page
is available).
Configure the Tank Overflow (Tank02) notification to make sure it will contain the
acknowledgment Web page with comment hyperlink in the email Body, and make sure to increase
the required amount of acknowledgment to 1.
Check In the changes and trigger the notification to send out the email.
Validate the acknowledgment process by clicking the hyperlink in the email.
Confirm the acknowledgment was successful by looking under the History tab of the Tank Overflow
(Tank02) notification. Also try to acknowledge using other tools like the Notification PI
ProcessBook add-in to compare both methods.
8.14 Group Questions Checking on our Notifications

Questions
1.
Did any of the created notifications generate any alerts? Where can we check?
2.
If this were an actual implementation, would this be an appropriate level of alerting?
Page 125
9. Custom Plug-Ins
Through the OSIsoft developers community, called the OSIsoft vCampus
(http://vcampus.osisoft.com/), it is possible to develop and find additional Data References
other than the four (4) default ones. An example of a custom data reference is the Rollup one
that will be introduced as an optional step in the Final Exercise to this class.
The same is true with Delivery Channels for the PI Notifications software. Apart from the
three (3) default Email, OCS and Web Service delivery channels, custom ones can be
developed. Those custom delivery channels can allow PI System information to be distributed
to other specific applications or systems. Custom delivery channels are already available
through again the OSIsoft vCampus community, such as the XML delivery channel for
example.
Page 126
Final Exercise Modeling a Wind Farm in PI AF
10. Final Exercise Modeling a Wind Farm in PI AF

This is a solo or group activity that is designed to maximize learning
in a specific topic area. Your instructor will have instructions, and
will coach you if you need assistance during the activity.
Exercise Objectives
Design a complete PI AF database.

Choose the optimum tools to perform the requested tasks.
Understanding the difference between importing PI AF tables and linking Microsoft
SQL Server tables.
Explore the PI AF attribute categories.
(Optional) Examine the Rollup custom data reference.
Problem Description
You have 215 Wind Powered Turbine units in your wind farm and you have PI Server tags
built for them. The engineers have interesting data in various spreadsheets. You also have
maintenance data in a Microsoft SQL Server. Youd like to integrate all that data into PI AF
using a common template.
PI Server Name
MS SQL Server Name (\Instance)
MS SQL Database Name
Approach
We will create an asset database primarily using the tool PI AF Builder. Much of the work
will be accomplished within Microsoft Excel.
There is a spreadsheet pre-configured for you to use in this exercise:
TxLakeWindFarm_WPUs.xlsx
The PI Server tags to use may need to be created using the TxLakeWindFarm_Tags.xlsx
spreadsheet and the PI Tag Configurator add-in to Microsoft Excel.
1.
2.
3.
4.
5.
6.
Create a PI AF database to represent the wind farm (please use a unique name within the class if the
same PI AF server is shared amongst the group).
There should be a top-level element under which you will create all the wind turbines.
Open the TxLakeWindFarm_WPUs.xlsx spreadsheet to see how many turbines this wind farm has
and then use a blank spreadsheet to create the PI AF elements using the PI AF Builder. The wind
turbines are to be called WPU_TxLKE001, etc. and based on the same template.
Validate that the wind turbines were created by opening PI System Explorer.
Create and configure the necessary attributes to fully model the data available in the
TxLakeWindFarm_WPUs.xlsx and TxLakeWindFarm_WPUModels.xlsx workbooks, both
located in the C:\Class\Exercises\04_TxLake Wind Farm folder.
Create and configure the necessary attributes to fully model the data available in the PI Server.
Page 127
Hint: Because the tag naming convention includes the wind turbine name, it is possible to use
substitution parameters in the template to populate the PI Point data references.
7.
8.
Add an attribute to show the energy generation (MWh) from the instantaneous GenWatts tag (kW).
This is a running total over the last hour on the instantaneous generation attribute (.GenWatts tag),
which can be seen as a rate tag in kW/hour.
Add an attribute to show the WPU effectiveness or yield (%) with the following formula:
Power / Rated Power * 100
9.
Create a PI AF table linked to the wind farm maintenance system (Microsoft SQL Server database:
WindFarmMaint)
Use the Microsoft OLE DB Provider for SQL Server driver.
Enter the Microsoft SQL Server instance name you noted at the beginning of this exercise.
Use Windows authentication.
Enter the Microsoft SQL Database name you noted at the beginning of this exercise
Link to the TxLakeMaint table (SELECT * FROM TxLakeMaint).
10. Create and configure the necessary attributes to fully model the data available from the Microsoft
SQL Server relational database.
11. Create Attribute Categories to organize the attributes in logical groupings.
About Attribute Categories
Categories can be used for various PI AF objects, such as the attributes. Attribute Categories are used to
group attributes together so it is easier to look, search or perform aggregations on the attributes of a PI AF
model. Categories are not extensively used in client applications like PI ProcessBook or PI DataLink.
However, for specific tools like the below explained Rollup data reference, the use of categories is
essential.
12. Complete the PI ProcessBook display TxLakeWindFarm_WPUStatus.pdi and make it Element
Relative to monitor the wind turbines of the TxLake Wind Farm.
13. (Optional) Install the Rollup custom data reference and use it to calculate the Total Energy
Generated for the whole wind farm (MWh). The Rollup custom data reference is available from the
C:\Class\Extras\PIAFRollupDataReference\.
About Custom Data References and the Rollup Data Reference
Four data references are built-in by default in PI AF. However, it is possible to develop your own custom
data references to interact with your applications and systems or generate different calculation results.
These can be developed by subscribing to the OSIsoft vCampus community (http://vcampus.osisoft.com)
At a top-level element (like the wind farm element), an attribute, using the Rollup custom data reference,
can be created to aggregate multiple attributes from children elements. The aggregation can be an
average, a minimum, a maximum or a sum. The attributes used in the aggregation must belong to the
same attribute category. The Rollup data reference is available on OSIsoft vCampus only and is not an
officially supported data reference.
Page 128
Exercises Solution
11. Exercises Solution

11.1 PI Performance Equations Exercise Solution (Section 6.2.3)
Problem
Solution
Hints
Add the tag SINUSOID

to the tag SINUSOIDU.
'SINUSOID' + 'SINUSOIDU'
Tags are wrapped in single

quotes/apostrophes ('TagName')
Get a 10 min rolling

average of the CDT158
tag.
TagAvg('CDT158', '*-10m', '*')
The TagAvg() function gives the

average of a tag over a given time
period.
Get the time-weighted

total for the CDT158 tag
over the last hour, but
only if the values of the
tag are good at least
80% of the time.
IF PCTGood('CDT158', '*-1h',
'*')>=80
THEN TagTot('CDT158', '*-1h', '*')
ELSE NoOutput()
If... Then... Else statements can

be used in the PE syntax.
The PCTGood() function gives
the percentage of good values
for a tag.
The TagTot() function gives the
time-weighted total of a tag over a
given time period.
or
TagTot('CDT158', '*-1h', '*', 80)
For the past day, how
much time (in % of a
day), was the tag
Sinusoid between 30 and
70?
TimeGT('SINUSOID', 'y', 't', 30) TimeGE('SINUSOID', 'y', 't', 70) /

86400 * 100
The TimeGT() function returns

the number of seconds a tag was
greater than a given value over a
given time range (TimeGE() is
greater or equal).
Display Overload when

the tag ba:level.1 is
greater than 90 ,
Normal when between
10 and 90, and Empty
when lower than 10.
if 'ba:level.1' >90 then "Overload"

else if 'ba:level.1' < 10 then "Empty"
else "Normal"
If... Then... Else require the

ELSE clause to be present.
Page 129
11.2 PI Totalizer Exercise Solution (Section Error! Reference source not found.)
Step-by-Step Solution
1.
2.
Open the PI System Management Tools, connect to the PI Server and select Points > Totalizers.
Create a new Totalizer tag, naming it _CDT158.ShiftAverage, and selecting a Block-Time
Weighted-Average and other values for its attributes as specified below:
3.
4.
Under the Sampling tab, select Natural sampling.

Under the Results tab, configure the totalizer to write the final result every 12 hours starting 6 hours
after midnight (6AM) as well as writing it one second after the start of the shift:
Page 130
Exercises Solution
5.
6.
Save your work by clicking on the floppy disk icon often as the configuration is sometimes lost if a
new tab is selected and the save button wasnt clicked.
Create a new Totalizer tag, naming it _CDEP158.BatchTotal, and selecting a Block-Time
Weighted-Total and other values for its attributes as specified below:
7.
8.
Under the Sampling tab, select Natural sampling.

Under the Results tab, configure the totalizer to write the final result based on a trigger event, which
is when the batch stops being active, so when 'BA:Active.1'="Active" is not true anymore (equals
zero). Also write interim results at source time (ramp):
9.
Under the Options tab, modify the Conversion Factor to 1440 to take into account the conversion
between minutes (GPM) and the PI Server assumption of units per day:
Page 131
10. Make sure to save your work to create the totalizer tag by using the top toolbar floppy-disk save
button.
11. Create a new Totalizer tag, naming it _CDEP158.MovingAverage, and selecting a Moving-Time
Weighted-Average and other values for its attributes as specified below:
12. Under the Sampling tab, select Natural sampling.

13. Under the Results tab, configure the totalizer to write the final result after 5 source events are read.
Also write the final result at source time (ramp):
Page 132
Exercises Solution
The PI Totalizer Subsystem should pick up the new tags and begin to process them
immediately. The results of the newly created calculations can be examine by using the PI
SMT > Data > Current Values plug-in, searching for tags with PointSource of T. If
Configure or Pt Created is the current value, the totalizer tag may simply not had enough
time or enough values to give a result yet. Their values can be checked at a later time.
Page 133
11.3 Speedys Pizza Solution (Section 7.4)

Step-by-Step Solution
1.
2.
Create tags required for the exercise from the file SpeedysPizzaTags.xlsx located in C:\Class (or the
location specified by your instructor).
Create the Base Template. From within PSE, select Library > Templates > Element Templates >
New Template.
3.
Name the template Vehicle.
4.
Select the Attribute Template tab.
Page 134
Exercises Solution
5.
In the white space, right-click, then select New Attribute Template or select the New Attribute
Template button in the menu.
Or
6.
Create the attributes standard to all the vehicles (Tripmeter, Gas Tank Level, Speed, and Time
Counter).
7.
Create derived templates for each individual van model.
8.
For Example, for model PizzaStar, the template is derived from the base template.
Page 135
9.
Add attribute templates to the template for the model.
10. Complete derived templates for each delivery van type. After checking in and refreshing the Browse
window, the individual models should appear under the base template.
11. Create individual elements for the 8 vehicles currently owned/operated by Speedy Pizza. Name them
according to the initial table with vehicle listing.
Page 136
Exercises Solution
12. Verify all the expected fields are present in the individual elements representing the appropriate
model. Vehicle SP1 is shown below for reference:
13. Verify all attributes are being updated based on the PI Points. For example, Engine Temperature is
based on %Element%.EngT but the tag should be listed as SP1.EngT or the appropriate Element ID
in place of %Element%
Page 137
14. Add the Fuel Efficiency calculation to the base template. As given in the hint, the Fuel Efficiency
can be calculated using the tank level, trip meter and tank capacity.
15. After adding this to the base template, check in the template, then verify the elements have the fuel
efficiency attribute added.
Page 138
Exercises Solution
Page 139
12. Software Versions Used in this Document

The list below describes the software versions used in this version of the course.
Software
PI ACE
PI AF Server
PI AF Client (PI System Explorer, PI AF Builder)
Version
2010 R2 SP1
2012
2012 SP1
PI DataLink
2013
PI Notifications
2012
PI ProcessBook
2012 SP1
PI Server
2012 + patch
PI SMT
2012 SP1
Microsoft Excel (32-bit)

Microsoft SQL Server (64-bit)
Microsoft Visual Studio
Page 140
2013
2012 Express
2010
Revision History
13. Revision History

Revision
Reviewer
Description
2010
Martin Bryant
Initial version of the Building PI System Assets and

Analytics with PI AF class workbook.
2012
Linda Payne
Revision to include comments from instructors after

few classes delivery.
2012b
Louis-Philippe Pag-Morin
Revision to include new features of the 2012 suite of

products.
2012c
Louis-Philippe Pag-Morin
Revision to integrate the Analytics and Notifications

sections with the Velocity Terminals and Speedys
Pizza structures. Addition of the PI DataLink 2013
exercise. Other additions and minor corrections.
2012e
Alejandro Molano
Revision of PowerPoint Slides and minor corrections

in the workbook
Page 141

Workbook - Building PI System Assets V2012e - Student

Загружено:

Сведения о документе

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Workbook - Building PI System Assets V2012e - Student

Загружено:

Авторское право:

Доступные форматы

Building PI System Assets

and Analytics with PI AF

Copyright: 1992-2012 OSIsoft, LLC. All rights reserved.

How to Use this Workbook

Your objectives are skills you can

New concepts are presented as level

Throughout the class you will be

The majority of your time will be

Icons help you identify themes, like

PI System Basics ..................................................................................................... 1

What is a PI System? ..................................................................................... 1

Time and the PI System ................................................................................. 7

PI System Explorer ................................................................................................11

PI System Explorer Components ...............................................................11

Connecting to a PI System ..........................................................................13

Finding Data .................................................................................................17

Key Features of the PI AF System .............................................................25

Directed Activity Velocity Terminals .......................................................26

PI ProcessBook Element Relative Display ................................................38

Modeling and Organizing the Assets ..................................................................41

Starting to Build a PI AF Structure .............................................................41

Styles of Approach for Designing Assets .................................................41

Organizing PI AF Elements in Hierarchies ................................................42

Solo/Group Exercise Organizing the Tanks for Velocity Terminals ....44

Where are my Assets? (Part 1) ...................................................................47

Visualizing the Assets Data ..................................................................................48

Leveraging the PI AF Structure in Visualization Tools ............................48

PI Coresight Related Assets ....................................................................48

PI DataLink Element Relative Reports ....................................................50

Adding Analytics to the Assets ............................................................................53

Identify the Best Solution to Perform a Calculation .................................53

PI Performance Equations ..........................................................................53

PI Totalizer Subsystem ................................................................................60

PI Advanced Computing Engine (PI ACE) .................................................63

Selecting the Right Calculation Tool .........................................................75

Taking Full Advantage of PI AF Functionalities .................................................77

PI AF Object Security ..................................................................................77

PI AF Advanced Template Design ..............................................................85

Using the Import / Export Feature in PI System Explorer ........................92

Solo / Group Exercise Speedys Pizza and Advanced Template Design93

Group Discussion Where are my Assets? (Part 2) / PI AF System

Communicating Important Events .......................................................................97

Introducing PI Notifications ........................................................................97

Group Discussion Frequency of Alerts ..................................................98

Directed Activity Installing PI Notifications (Optional) .........................99

Directed Activity PI Notifications State Groups and States (Global

Directed Activity Triggering the Alerts ..................................................102

Directed Activity PI Notifications Templates .......................................106

Formatting the Information to Deliver .....................................................107

Delivering the Events ................................................................................111

Adding Contacts ........................................................................................114

8.10 Subscribing Contacts to Notifications ....................................................119

Custom Plug-Ins ..................................................................................................126

Final Exercise Modeling a Wind Farm in PI AF .............................................127

Software Versions Used in this Document .......................................................140

Revision History ..................................................................................................141

Define the components of a PI System

Building PI System Assets and Analytics with PI AF

Architecture of a Typical PI System

Building PI System Assets and Analytics with PI AF

Directed Activity Assets Defined

What is a PI Server Tag?

So What Types of Data Can the PI Server Store? (point types)