Building PI System Assets and Analytics

with AF
PI Server 2018 SP3 Patch 3
(Workbook 2021)
Building PI System Assets and Analytics with PI AF

Page ii
 PI System Basics

Table of Contents

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

1.1 What is a PI System? ..................................................................................... 1
1.2 The Basic Building Blocks in the PI System ............................................... 6
1.3 Time and the PI System ...............................................................................10

2. Introducing Asset Framework ..............................................................................15

2.1 PI AF Server ..................................................................................................15
2.2 PI System Explorer Components ...............................................................17
2.3 Connecting to a PI System ..........................................................................20
2.4 Finding Data .................................................................................................23

3. A Walkthrough of AF .............................................................................................26
3.1 What does Asset Framework (AF) do for me? ..........................................26
3.2 Introducing Elements and Attributes .........................................................28

4. Modeling and Organizing the Assets ..................................................................54

4.1 Asset Hierarchy Design Strategies ............................................................54
4.2 Organizing AF Elements in Hierarchies ....................................................57
4.3 Using the Import and Export Feature in PSE ............................................65

5. Visualizing Data .....................................................................................................67

5.1 Visualizing AF Data in PI Vision .................................................................67
5.2 PI ProcessBook displays in PI Vision ........................................................74
5.3 PI Datalink .....................................................................................................75

6. Adding Analytics to the Assets ............................................................................88

6.1 AF Calculation Options Overview ..............................................................89
6.2 Formula Data Reference ..............................................................................91
6.3 Value Retrieval Modes .................................................................................91
6.4 Case Study: PI Big Tires Co. .......................................................................99
6.5 PI Analysis Service, Expression Analysis ...............................................101
6.6 The Rollup Analysis ...................................................................................122
6.7 Visualizing Calculation Results in PI Vision ...........................................129

7. Tracking Important Events .................................................................................131

7.1 Tracking Production Downtime Periods .................................................132
7.2 Consuming Event Frames .........................................................................153
7.3 Tracking Critical Tank Level Periods .......................................................167

Page iii
Building PI System Assets and Analytics with PI AF

8. Using Event Frames to capture Production Batches ......................................174

8.1 Case Study: Wonderland Chemicals .......................................................174
8.2 Batch Production and ISA S88 standard .................................................177
8.3 Event Frames in PI Vision .........................................................................179

9. Taking Full Advantage of AF Functionalities ...................................................184

9.1 AF Object Security .....................................................................................184
9.2 Attribute Properties ...................................................................................197
9.3 Substitution Parameters ...........................................................................201
9.4 More about Attribute Data Reference Types ...........................................207
9.5 Advanced Element Template Design .......................................................215

10. Communicating Important Events .....................................................................220

10.1 Introducing Notifications ..........................................................................220
10.2 Delivering the Events ................................................................................222
10.3 Configuring Notifications ..........................................................................227
10.4 Formatting the Information to Deliver .....................................................234
10.5 Acknowledging Notifications ....................................................................239
10.6 Adding Contacts ........................................................................................245
10.7 Delivering Notifications via a Web Service .............................................256

11. AF Best Practices ................................................................................................261

12. Final Exercise: Modeling a Wind Farm in AF ....................................................263

12.1 TxLake Windfarm: Modeling your assets ................................................263

13. Training Cloud Environments (TCE) ..................................................................271

14. Resources ............................................................................................................272

14.1 OSIsoft Learning Options .........................................................................272
14.2 OSIsoft Community ...................................................................................273
14.3 Tech Support ..............................................................................................274
14.4 Further Questions ......................................................................................275

15. Software Versions Used in this Document .......................................................276

16. Appendix A: Substitution Parameters ...............................................................277

17. Revision History ..................................................................................................279

Page iv
 PI System Basics

1. PI System Basics

1.1 What is a PI System?

Objectives
• Define the components of a PI System.
• Draw a diagram of the architecture of a PI System.

1.1.1 The PI System described

The PI System collects, stores, and manages data from your plant or process. Your
data sources connect to one or more PI Interface nodes. The PI Interface nodes
collect data from your data sources and store into the PI Data Archive.
Asset Framework (AF) organizes and enhances the data. Users consume the data
by the use of a tool of the PI Visualization Suite (PVS) such as PI Vision.

The following is a diagram of the components of a simple PI System:

Page 1
Building PI System Assets and Analytics with PI AF

1.1.2 PI System Components

In a more detail, the following components constitute the PI Server:

Data Archive
The PI Data Archive is a component of the PI
Server that provides efficient storage and archiving
of time series data enabling high performance data
retrieval by client software.

Note: Traditionally, the PI Data Archive was referred to as the

"PI Server”.

Asset Framework
PI Asset Framework (PI AF) is a single repository
for asset-centric models, hierarchies, objects, and
equipment. It integrates, contextualizes, refines,
references, and further analyzes data from multiple
sources, including one or more PI Data Archives
and non-PI sources such as external relational
databases.
Asset Analytics
A feature of PI Asset Framework (PI AF) used to
create and manage analyses. Analyses read values
of PI AF attributes, perform calculations, and write
results to other attributes or create event frames.
Event Frames
Event Frames help to capture, track, compare, or
analyze important process or business events and
their related data for a repeatable period of time.
Event frames represent occurrences in your process
that you want to know about, such as asset
downtime, process excursions, equipment startup or
shutdown, environmental excursions, product
tracking batches, product runs, or operator shifts.
Notifications
The PI System can send notifications to users or
systems when key events occur. You set conditions
that define these events and specify notifications for
them, including recipients and actions to take, such
as what to do when a recipient is unavailable. In
operation, the PI System detects the events you
specified and automatically generates and sends
out notifications for them.

Page 2
 PI System Basics

1.1.3 Machine Friendly and Human Friendly Side in the PI System

Machine Friendly Side:

• PI Interfaces and Connectors
• PI Data Archive
• PI Tag

PI Interfaces and Connectors

PI Interfaces collect data from external data sources, providing real-time, fault-
tolerant data to the PI System.
PI Connectors are similar to PI Interfaces. They collect data from sensors and control
systems. Different to interfaces, they also automatically create a PI Asset Framework
(AF) model for your asset. (In that regard, also belong to the human friendly side)

PI Tag
A unique storage point for data in the PI System. It is simply a single point of
measurement. A point represents a single named stream of data coming from an
instrument, device or sensor (-> time-series data).

Note: A PI tag is the same as a PI Point.

Page 3
Building PI System Assets and Analytics with PI AF

Human Friendly Side:

• PI Asset Framework
• Assets and Attributes
• Visualization Tools

Assets

In AF, the equipment and processes that you want to monitor

are called assets. An asset represents a logical or physical
component of a process. Example assets include company
locations, sites, and pieces of equipment.
Assets are configured in AF as elements. The AF representation
of all your assets and processes together is called an asset
model, which is a hierarchical structure.

Attributes

An attribute represents a unique property associated with an asset.

Attributes can hold simple values representing fixed information such as the
manufacturer of a pump. Attributes can also reference a PI point, a formula, a value
from a relational database or internal AF table, and other information.

Page 4
 PI System Basics

1.1.4 Architecture of a Typical PI System

Sometimes the architecture can be very simple. Some customers have as few as
one or two PI Interfaces feeding data to a Data Archive from which the data can be
consumed by various applications. The following is an example of a fully developed
PI System, which includes most of the widely used OSIsoft products.

In the diagram above, two PI Data Archive computers are shown to represent a PI
Data Archive collective. A collective is a configuration of multiple servers that act
as a logical PI Data Archive server in your PI System to provide high availability
(HA), disaster recovery, load distribution, and increased scalability. A collective
consists of one primary server and one or more secondary servers.
For information on high availability options for PI Asset Framework refer to KB
article: KB00634 - High Availability (HA) options for PI Asset Framework (PI AF)

Note: In computer security, a demilitarized zone, named after the military usage of the term and
normally abbreviated to DMZ; also known as a Data Management Zone or Demarcation Zone or
Perimeter Network, is a physical or logical subnetwork that contains and exposes an
organization's external services to a larger, untrusted network, usually the Internet. The purpose
of a DMZ is to add an additional layer of security to an organization's Local Area Network (LAN);
an external attacker only has access to equipment in the DMZ, rather than the whole of the
network. [Reference: http://en.wikipedia.org]

Page 5
Building PI System Assets and Analytics with PI AF

1.2 The Basic Building Blocks in the PI System

1.2.1 Point Properties

Data Archive points have a set of properties that define them (these properties are
called attributes of the tag). Some common properties are defined in the following
paragraphs.

Point Name
This is the unique name used to create points for storage in the Data Archive.
Examples: P294H.FI.PV, M03_E1P1_MOTDRV1202_RUNSTAT

Descriptor
This is the human-friendly description of the Data Archive point. The descriptor is
often a search criterion since the point name is not always intuitive. Often the point
name is some sort of abbreviated convention and the descriptor captures the “full
name.”

Point source
Points can be related to their interfaces that collect the data by a point attribute
called pointsource. Grouping by point source allows all of points associated with a
particular device to be identified by searching for all points of a certain point source.
This assumes that the user knows the point sources in use and that will not be true in
some situations.

Point type
This is the attribute that specifies the data type for the values that a point stores. The
possible point types are:
int16, int32, float16, float32, float64, digital, string, BLOB, timestamp

Page 6
 PI System Basics

1.2.2 Attribute Data Reference Types

Attributes represent a unique property associated with an asset. The Data Reference
Type of an attribute defines from where to get the data for the attribute. The following
Data Reference Types exist:
• PI Point
• PI Point Array
• Formula
• Table Lookup
• String Builder
• URI Builder

Note: <none> means there is a static value for this attribute.

Data Reference Types (Setting Examples)

Page 7
Building PI System Assets and Analytics with PI AF

1.2.3 Solo or Group Activity – Assets Defined: Data Reference Types

This solo or group activity 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.

Problem Description
Identify the type of attribute data references in the AF Server.

Questions
Identify the corresponding Data Reference Type of the following attributes:

1. Nominal Power: There is a list with the nominal pressures for all the pumps
in the pump room and information can be read out of that list.

_____________________________

2. Flow Rate: receives actual measurements from the data source. There is a
related tag in the PI Data Archive.

_____________________________

Page 8
 PI System Basics

3. Pump Location: Specifies the location of the pump. The location

corresponds to the name of the parent element.

_____________________________

4. Electrical Current: maximum amperage of a pump. The electrical current of

a pump is calculated from the nominal power of the pump and the voltage
(220 V).

_____________________________

5. Manufacturer: brand of the pump. This information never changes.

_____________________________

6. AdHoc Pressure trend: link to PI Vision with parameters to specify the

element and the attribute and the start and end time for the trend.

_____________________________

Page 9
Building PI System Assets and Analytics with PI AF

1.3 Time and the PI System

Objectives
• Define the time abbreviations in the PI System.
• Define the time expressions in the PI System.
• Introduction to Future Data.
• Explain how the PI System handles times zones and daylight savings time
(DST).

You can use a special syntax, called PI System time, when specifying 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
time units and reference times.

Abbreviation Time-unit
s second
m minute
h hour
d day
w week
mo month
y 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.

Abbreviation Full Reference-time

* Current time.
t (or T) today 00:00:00 (midnight) of the current day
y (or Y) yesterday 00:00:00 (midnight) of the previous day

Page 10
 PI System Basics

Abbreviation Full Reference-time

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 00:00:00 (midnight) on the most recent Wednesday
thu Thursday 00:00:00 (midnight) on the most recent Thursday
fri Friday 00:00:00 (midnight) on the most recent Friday
sat Saturday 00:00:00 (midnight) on the most recent Saturday

1.3.2 PI System Time Expressions

The PI System time expressions 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 might include:
• Only a reference time, such as “y”
• Only a time offset, such as “+3h”
• A reference-time with a time offset, such as “y+3h”
A reference-time can be a fixed time, such as “24-aug-2012 09:50:00”, or a valid
reference-time abbreviation, such as “t”.
You can only include one time offset in an expression. Including multiple offsets can
lead to unpredictable results. For example, the following time expressions are not
valid:

1.3.3 Timestamp Specification

To specify inputs for timestamps, you can enter time expressions that contain:
Fixed times
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 p.m. on August 23, 2012
25-sep-12 00:00:00 (midnight) on September 25, 2012

Page 11
Building PI System Assets and Analytics with PI AF

Reference-time Abbreviations
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
t 00:00:00 on the current date (today)
y 00:00:00 on the previous date (yesterday)
tue 00:00:00 on the most recent Tuesday

Reference-time Abbreviations or Fixed Times with a Time Offset

When included with a fixed time or a reference-time abbreviation, a time offset adds
or subtracts from the specified time.
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 yesterday
mon+14.5h 14:30:00 (2:30 p.m.) most recent Monday
sat-1m 23:59:00 (11:59 p.m.) last Friday

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 field where you enter the
expression:
• For a start time, the reference-time is the current clock time.
• For an end time, the reference-time is the start time.
• For a single time stamp, the reference-time is the current clock time.

Time field Input Meaning

Start time -1d One day before the current clock time (24
hours before the current clock time)
End time +6h Six hours after the start time
End time -30m 30 minutes before the start time
Time stamp -15s 15 seconds before the current clock time

Page 12
 PI System Basics

1.3.4 Future Data

Future data is data associated with a future time stamp. Data Archive 2015 allows
storage and retrieval of data with time stamps beyond current time, allowing you to
store data within a time range of January, 1970 through January, 2038. With Data
Archive 2015 you can capture and analyze data with future time stamps, and use PI
visualization tools to graphically create possible forecasts or predictions for your
business.
Just as with historical data, to specify inputs for timestamps, you can enter time
expressions previous discussed fixed time, reference times, and reference-time
abbreviations or fixed times with a time offset. The difference being the timestamp
will be in the future. Some example expressions are:

Input Meaning
*+1h An hour from now
t+3d Three days from today at midnight
Y+1y A year from yesterday

1.3.5 How Does the PI System Adjust for Time Zones and DST?

The short answer is: we do not!

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. The local machine clock of the user looking at the data makes any
adjustments for time, such as time zone or DST.
If your region observes DST, 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.
In addition, because the clients and PI Server know what time zone 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 13
Building PI System Assets and Analytics with PI AF

1.3.6 Solo or Group Activity – PI System Times

This solo or group activity 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.

Problem Description
Determine the “real” dates and times indicated by the PI System times in the table
below:
(assume now: Tuesday, 20-May-2014 10:12:23 AM)

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
12 hours ago
The first day this
month
Tomorrow at 7:00 AM
2 hours from now

Page 14
 Introducing Asset Framework

2. Introducing Asset Framework

2.1 PI AF Server

2.1.1 AF Server Installation and Software Requirements

In a production environment, the AF Server component is typically installed on a

dedicated Windows server machine.
For the database management the AF Server is using a Microsoft SQL Server,
which has to be defined during the AF server installation. The default name of the
SQL database used for AF is PIFD.
The client program for AF is PI System Explorer (PSE), which is used to configure
and maintain the asset structure.
AF Server is compatible with several SQL Server versions (SQL Server 2008 or
later; for a complete list refer to AF Server software requirements). The PI AF server
works with 32-bit or 64-bit SQL Server versions.
Several SQL Server editions are supported: Express, Standard, Business
Intelligence, Enterprise, Datacenter. The Express version is free of charge, but has
several limitations. Depending on your AF asset structure size and the AF functions
you are using (such as audit trail functionality), the Express version may not be
sufficient. Refer to related OSIsoft Hardware System Sizing recommendations.
The SQL Server can reside on the same machine as the AF Server or on another
machine. It is possible to use an existing SQL Server that is also used for other
applications.
SQL Server Requirements for PI AF High Availability
To take advantage of the PI AF High Availability (HA Collective) feature, the primary
collective member must run SQL Server Standard Edition, SQL Server Business
Intelligence, SQL Server Enterprise Edition, or SQL Server Datacenter Edition. SQL
Server does not need to reside on the same machine as PI AF Server.
SQL Server Requirements for PI AF Audit Trail Functionality
The PI AF Audit Trail feature requires SQL Server Enterprise edition for supported
SQL Server versions of SQL Server 2014 and earlier.
The PI AF Audit Trail feature is also supported in:
• SQL Server 2016 (Windows Update or Microsoft KB 3164398 required)
• SQL Server 2016 SP1 Enterprise or Standard Editions
• SQL Server 2017 Enterprise or Standard Editions (Windows Version Only)
For complete information about the system requirements for the AF Server, refer to
the AF Server software requirements.

Page 15
Building PI System Assets and Analytics with PI AF

2.1.2 Asset Framework Key Features

Asset Framework provides an additional data layer in the PI System. It is based on

an asset model of your plant that is defined by the customer. The model consists of
elements and attributes.
The model organizes and structures the data according to
objects that customers are most familiar with, such as
physical objects in their processes like reactors,
transformers and meters.
Since the AF asset model can span PI Data Archives, it
allows customers to organize and search for PI System
information across multiple PI Data Archives.

The basis for the asset model is an Element, which contains Attributes that can
reference PI System data, design data or data from other systems:

AF Event frames allow users to associate or bookmark events, which occur over a
time span with those assets.
Asset Analytics provides real time calculation engine that allows users to configure,
schedule and run calculations written using Performance Equation syntax acting on
their AF attributes. Calculation results can be stored as time series data in PI Points
or create event frames, notifications can automatically be sent out for them if
needed.
Client applications including but not limited to, PI Vision, PI DataLink, PI
ProcessBook and PI Integrators can utilize the asset models to provide context
driven displays, reports and analyses.

Page 16
 Introducing Asset Framework

2.2 PI System Explorer Components

2.2.1 Directed Activity – Familiarize with the PI System Explorer Components

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.
Your instructor will have directions.

Problem Description
You may follow along as your instructor shows and explains the PI System Explorer
components and their general use.

Approach

Click on the PI System Explorer icon in the task bar to start the program.

Note: the very first start of PI System Explorer can take some time. In the beginning, no dialog
box is displayed. Subsequent starts will be much faster.

Page 17
Building PI System Assets and Analytics with PI AF

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 and Management.

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 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 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 created from scratch. When based on a template,
the element derives its initial attribute configurations from the template. Later
modifications to the template will propagate to all elements based on said
template.

• Event Frames: An event frame is any event, defined by a start time, an end
time, and a context. Event frames also have attributes containing supporting
data. Event Frames can represent downtime events, process and
environmental excursions, material transfer events, equipment maintenance
events, batch processing steps, safety incidents, and any other events
important to your organization. A transfer is a special type of event frame that
marks the movement of material in discrete quantities.

• Library: This is a collection of objects that can be re-used throughout the AF

hierarchy. 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 comes 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).

• Management: This section provides a summary of all analyses and

notification rules configured on the current AF database. It allows you to
perform administrative tasks like starting, stopping and backfilling.

Page 18
 Introducing Asset Framework

Viewer
This is the primary work area. Use it to create and edit elements, attributes,
templates, tables, contacts, notifications, analyses, and so forth. When configuring
attributes through the Viewer, the Configuration Panel comes into view allowing you
to make configuration changes.

Configuration Panel
The configuration panel is used to configure properties associated with attributes.
These properties include categories, attribute references, units, data types, and
values for static attributes.

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.

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.

Page 19
Building PI System Assets and Analytics with PI AF

2.3 Connecting to a PI System

Objectives
• Describe the different ways we can connect to a PI System.
• Connect to an AF Server.
• Examine your connected credentials.
• Connect to a Data Archive.
• Create a new connection to a Data Archive.

2.3.1 What Do We Connect for Data?

During this class, the PI System data will be retrieved mainly using PSE. A
connection to an AF Server will be needed to access all the metadata related to your
assets while a connection to the Data Archive will be required to access the process
data from the Data Archive points.

2.3.2 Connecting to a AF Server

To connect to the AF Server simply open PSE. The default AF Server was set during
installation, so you will be automatically connected to it. If a default AF database has
already been defined, PSE will automatically connect to it as well. If no default 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 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.

To connect to a different available AF server, simply select it from the drop-down AF

Server menu and click on the Connect button.

Page 20
 Introducing Asset Framework

2.3.3 Directed Activity – Examining Credentials When Connecting to the 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.
Your instructor will have directions.

Problem Description
You may follow along as your instructor shows you how to validate connections to
Data Archives and AF servers.

Approach

Click on the PI System Explorer icon in the task bar to start the program.
To find out the credentials being used for connecting to the AF Server, go to File >
Connections…

Page 21
Building PI System Assets and Analytics with PI AF

2.3.4 Directed Activity – Connecting to a Data Archive

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.
Your instructor will have directions.

You can validate your connection to the Data Archive via PSE. Notice AF Server icon
( ) is different than Data Archive server icon ( ).
The PI SDK utility provides you with more features to configure and diagnose
connections to the Data Archive.
Open the PI SDK Utility (PI System > PISDKUtility (64-bit)). From the PI-SDK >
Connections section, the Data Archive servers configured on the local machine are
displayed. To validate a connection to a Data Archive, simply check the checkbox
next to its name or IP address. If connection succeeds, connection information will
be shown.

The user that was used to authenticate on the Data Archive 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.

Page 22
 Introducing Asset Framework

2.4 Finding Data

Objectives
• Demonstrate the ability to find element data within the Asset Framework (AF)
hierarchy.
• Demonstrate the ability to search for points from within PI System Explorer
(PSE).
• Examine point attributes.

2.4.1 Directed Activity – Finding Elements and Attributes

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.
Your instructor will have directions.

PI System Explorer has two element search options: a quick search and an advanced search
with multiple search criteria.

Activity Objectives
• Perform a quick element search based on a name pattern
• Perform an element search with multiple search criteria.
• Perform an attribute search.

Approach
Quick Element Search
1. Open the PI Big Tires Co. AF database in PSE, select Elements in the
Navigator.
2. Explore the element hierarchy: it contains 3 locations (Houston, Montreal and
Philadelphia (“Philly”)) with four presses in each location.
3. Enter HOU into the quick search and click on Enter.

4. Enter HOU*Press into the quick search and click on Enter.

Page 23
Building PI System Assets and Analytics with PI AF

Note: The search is shown with a little asterisk . When you select Save from the
context menu, the search will be available the next time you log into PI System Explorer.
When you select Rename from the context menu, the search will be renamed and
saved.

Advanced Element Search (multiple search criteria)

5. From the PSE menu, select Search – Element Search…
6. (optional) If criteria were cached from the last search, click the blue “x” in the
search line on the top to reset.
7. Enter criteria to search for the presses in Montreal (Element Search Root=
Montreal, template= Press), click on Search to get the results.
8. Enter *1 in name field to specify another criteria, click on Search to get the
results.

Note: All Descendants specifies whether the search returns elements from the selected
levels and all levels below. The option should be set to true in most cases. The Name
field can make use of the wildcard characters (* and ?).

9. Reset the criteria. When you specify a template (e.g. Press) you can add a
criteria for an attribute value. Search for all presses with Press Status =
“Running”.

Attribute Search
10. From the PSE menu, select Search – Attribute Search…
11. Select PI Big Tires Co. AF database.
12. Enter Press Status into the attribute name field. Make sure the Search Sub-
Elements option is selected. Click Search. Result: the Press Status attributes
for all 12 presses are listed. Click on OK.

Page 24
 Introducing Asset Framework

2.4.2 Directed Activity – Finding Points within PSE

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.
Your instructor will have directions.

A Tag Search window is available from PSE in order to find the appropriate point to map to a PI
Point Element Attribute. This tag search window is accessible from the Search – Tag Search…
menu item.

Activity Objectives
• Understand the search capabilities and options of PSE Tag Search.

Approach
1. From the PSE menu, select Search – Tag Search…
2. (optional) If criteria were cached from the last search, click the blue “x” in the
search line on the top to reset.
3. Search for tags matching the name pattern CD*158
4. Search for tags matching the name pattern CD?158. What is the difference to
the previous search results?
5. By default, this window allows searching using a point name mask. If you
click on the control to display extra search features, you will get more options
to further refine the search using additional common point attributes like the
descriptor.

Enter criteria to search for all tags with point source=R and name= sinus*.

Page 25
Building PI System Assets and Analytics with PI AF

3. A Walkthrough of AF

3.1 What does Asset Framework (AF) do for me?

The PI Data Archive is focuses on a points database and is extremely good at

storing vast amounts of data collected by interfaces. It allows easy and
performant retrieval of time-series data. The PI Data Archive architecture is
scalable, maintainable and highly available.

The Asset Framework (AF) supplements the architecture by

providing a Meta-data structure for all data in the organization
(“Data Directory”). Asset Framework (AF) has a rich set of
features and functions to organize and enhance the data in the PI
Data Archive. Because it offers user-friendly access to the data it
is the preferred way for users to interact with their PI system data.

What are the benefits of Asset Framework?

Easy way to navigate throughout the system

The hierarchical asset structure gives a convenient way for navigation that can also
be used by people, who are not familiar with the technical details of how the data is
retrieved from the data source.

Unify data from disparate source systems

PI Point attributes get their data from PI Data Archives. AF is not limited to one PI
Data Archive. Attributes can refer to multiple PI Data Archive Servers (either
standalone or collective)
The origin of data can also be a relational database. While some attributes of an
element representing a reactor are time-series data coming from PI tags (such as the
temperature), data for some other attributes can be from an external database (such
as the physical characteristics or inventory data).
All attributes are listed side by side giving the user a comprehensive insight into all
the relevant data of the asset.

Page 26
 A Walkthrough of AF

Supports different Units of Measure

PI Asset Framework (PI AF) attributes are associated with specific Units of
Measure. AF is preloaded with numerous standard unit-of-measure classes and
conversion factors based on the International System of Units (SI). It also
supports user defined classes and Units of Measure. For example, the source
unit for a temperature sensor attribute in a reactor in the USA can be
associated with degrees Fahrenheit, the corresponding attribute for a reactor in
Italy can be associated with degrees Celsius. When working with the data
(doing calculations or displaying the data) this is properly taken into account.

Standardization with Templates

At many sites there are no rigorous naming standards for the points. 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:

Element templates in AF provide the basis for standardization. When applied for
elements that represent the same type equipment, all elements have the same set of
attributes with a consistent, user friendly naming. The attributes have same unit of
measurement, same data type, the same description, etc. This allows a harmonized,
consistent representation of your system.
Another benefit of using templates is the quick creation of many elements of the
same type.

Powerful Calculation Options (Asset Analytics)

Users can configure, schedule and run calculations written using PI Performance
Equation (PE) syntax acting on their PI Asset Framework (PI AF) attributes. PE
expressions, Rollup calculations and generation of PI Event Frames based on trigger
conditions are all supported analysis types. In addition, analysis templates enable
users to manage their analyses in a standardized and consistent manner. Typical
applications are Key Performance Indicator (KPI) calculations and condition based
maintenance (CBM).

Page 27
Building PI System Assets and Analytics with PI AF

3.2 Introducing Elements and Attributes

3.2.1 Directed Activity – Velocity Terminals

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. Your instructor will have
directions.

Activity Objectives
• Create an 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 an AF table.
• Create an AF element template from an element.
• Extend the template with new attributes and see how these affect the original
element.
• Create an AF enumeration set and use it for data validation in a template.
• Create an element from a template.
• Move AF Elements under a parent element.
• Create more elements with the PI Builder Excel add-in.

Problem Description
You are working for Velocity Terminals, a chemical company producing various
chemicals. The company has a number of storage tanks located in different countries
that they would like to monitor. You have been tasked with creating an asset model
for these tanks in AF.

Approach
Follow the instructor as he or she performs steps to create various AF objects that
will lead to the creation of a single PI ProcessBook display to monitor all of Velocity
Terminals’ tanks.
You will have opportunities to work on your own later on in the course. For now
follow and listen closely to the information in this initial exploration of AF.

Page 28
 A Walkthrough of AF

3.2.2 Directed Activity – Creating and Selecting AF Databases

Open PSE from the start menu and, if necessary, connect to the AF server PISRV01.
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.
To create a new database, right-click anywhere in the list of databases and choose
New Database or click on the New Database button on the toolbar.
To select the existing database for entering the Velocity Terminals structure, select
AF Startup and click the OK button or double-click on it to open the database.

About Databases

PISRV01 setup for training has many AF databases, which are specific for class exercises. In
practice, it may be better to build fewer, larger databases. That is because references in 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.

The Configuration database

As an administrator, it is possible to view a database 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 29
Building PI System Assets and Analytics with PI AF

3.2.3 Directed Activity – Creating AF Elements

Make sure the Elements section is selected from the Navigator Panel and create a
new element called Tank01.
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 AF. It is an organizational feature that can be thought
of like a folder. It has relationships with other elements and has searchable characteristics. An
elements has no Data Reference and does not have a value. Elements are generally organized
hierarchically, though this is not required.

Elements represent physical or logical entities in your process, this can be: equipment, lines,
products, systems, organizations or sites. 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 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” can
not coexist under the same element “System A”. It is recommended that unique names are
considered for 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 ( ; ? ` ‘ “ \ | {} [] ).

Page 30
 A Walkthrough of AF

3.2.4 Directed Activity – Creating 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.
As with elements, 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.

Value Type
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).

Display Digits
The Display Digits field (new in AF 2018) can be used to control the number of
digits you want to see for the attribute: zero or positive numbers indicate the number
of digits to display to the right of the decimal point. A negative number indicates the
number of significant digits to display. In this case, the absolute value of Display
Digits is the number of significant digits.

Note: With AF Server version before 2018 there was no option to set Display Digits. Function
was same if Display Digits would have been set to -5.

Example (Value= 23.45)

Display Digits Format

3 23.450
2 23.45
1 23.5
0 23
-1 2E+001
-2 23
-4 23.45
-5 (default) 23.45

Page 31
Building PI System Assets and Analytics with PI AF

Start configuring the first three attributes for Tank01 per the table below:

Attribute Default Value Display Data

Name UOM Type Value Digits Reference
Capacity US gal (Volume) Double 20,000 -5 <None>
Level % (Ratio) Double N/A 2 PI Point
Volume m3 (Volume) Double N/A 3 Formula

In the Value column for Level and Volume there will be errors, which we will fix by
completing the configuration in the next steps.

Units of Measures for Attributes

Attributes will generally be assigned units of measures (UOM). These UOM are organized into
comparable classes. The Default UOM configuration field defines the default unit of measure to
use to display the attribute’s 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.

Note: Always assign a unit of measurement! Do not leave this undefined. This will avoid
misinterpretation of the measurement in all subsequent operations.

• To enter an UOM, select the UOM from the corresponding UOM Class (here:
UOM class= Ratio, UOM= percent). Alternatively, enter the first characters
(such as per), then select from the list of matching UOMs.

Page 32
 A Walkthrough of AF

Level Attribute
• With the Attributes tab selected, select the Level attribute and then click on
the Settings button.

• Check the correct Data Archive Server is selected (PISRV01) for Data Server
at the top.

• Enter TANK01LI.PV (or use the tag search ( )). Change the Source Units
from “<Default> (%)” to “%”. Click on OK.

Note1: Make sure you always assign a unit of measure (UOM) rather than just keeping
the default. This prevents that the PI Point value is misinterpreted in case the Default
UOM of the attribute is changed later in time.

Note2: Display Digits will be updated according to the setting in the selected tag
(TANK01LI.PV). Reset to 2.

• The current value of TANK01LI.PV will be displayed in the Value column for
the Level attribute.

Page 33
Building PI System Assets and Analytics with PI AF

Add a new unit of measure (“ratio”)

To get the value for the Volume, we have to correlate the whole capacity with the
actual filling level. But instead of using the percentage value in a multiplication (which
is in the range of 0 … 100) we will rather use the ratio value for the multiplication (in
range of 0 … 1).
The conversion between the percent value and the ratio value can be accomplished
by using dedicated units of measure. There is already a UOM class for ratio, which
has percent in it. Let us add the unit of measure for the ratio:
With Unit of Measure selected in PI System Explorer Navigator, navigate to the UOM
class Ratio. Add a new unit of measure named ratio:

Note: A ratio of 0.5 means 50%, a ratio of 1 means 100%.

Volume Attribute

1. Return to the Tank element template (Library -> Elements), and select the
Volume attribute.
2. Click on Settings… to bring up the Formula Configuration window.
3. A Formula is entered by an equation using parameters. Parameters are
defined by a character from the alphabet Use the new button ( ) to add the
parameters to use in the formula. Assign C for Capacity (set the unit of
measure to m3), assign L for the Level (set the unit of measure to ratio).

Page 34
 A Walkthrough of AF

Note: double-check your proper UOM assignments by comparing your settings under
Parameters with the screenshot below.

4. Calculate the volume by multiplying the Level (with a ratio value) and the
capacity (with a value in cubic meter). For the equation, either manually type
in C*L
or
click the new button for the equation ( ) and expand the list of functions
from the equations section ( ) to pick variables, operators, functions,
substitution parameters to be used in the formula

5. Set UOM for results to m3. Click on OK. Check In ( ) your changes.

Note: It is recommended that you always assign the units explicitly! If you leave units
selector at <default> then no unit conversion takes place. If the default UOM of an
attribute is changed later on, then no corresponding conversion will happen and results
will not be correct!

Page 35
Building PI System Assets and Analytics with PI AF

About Checking In

The 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 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.

Note: it is not required to check in every time you make a change. There are even
reasons not to do all the time: if you have analytics running and you check in, then the
analytics will restart for all elements affected by the check in!

6. Click on Refresh to update values for all attributes. The following table will
help you to evaluate whether the calculation is correct.

Tank01 Level Volume (US Gallon) Volume (m3)

0% 0 US Gallon 0 m3
20 % 4,000 US Gallon ca. 15 m3
40 % 8,000 US Gallon ca. 30 m3
60 % 12,000 US Gallon ca. 45 m3
80 % 16,000 US Gallon ca. 60 m3
100 % 20,000 US Gallon ca. 75 m3

7. To explore the Display Digits setting, change Capacity from 20,000 ->
200,000. Once you have entered the modified value, the value will be shown
as 2E+05 US Gal. This is because the value cannot be displayed with just
five digits (Display Digits = -5), and the display is switched to scientific format.
2E+05 has to be interpreted as 2.0 * 10 ^ 5 (= 200,000). Change Capacity
back to 20,000.

2E+05 = 2.0 * 10 ^ 5 = 200,000

To familiarize with scientific format, open Windows Calculator and switch to Scientific
View. Enter 200,000 and change to scientific display (F-E button).

Page 36
 A Walkthrough of AF

3.2.5 Directed Activity - Creating AF Tables

About Tables

Tables are held in the 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 AF.

Tables can be created internally (“Internal Table”, like in this exercise), imported from an
external data source (“Imported Table”), or linked to an external relational data source
(“Linked Table”, refer to exercise Linking Tables from SQL Server). In this way, Tables can
expose information in maintenance, production planning, or equipment databases for use by PI
client applications.

Building the table is similar to building a table in other programs that have simple
table building capabilities.
In the PSE, first navigate to the Library section from the Navigator
Panel. Right-click on the Tables item to select New Table, or click on
the button from the toolbar.
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 ( ) on the right-hand
side. Define the table as follows:
Column Name Value Type Unit Of
Measure
MaterialID String <None>
Density Double kg/m3 (Density)

Under the Table tab, enter the following fictitious chemicals:

MaterialID Density
AQ4500 2100 kg/m3
HC1500 3422 kg/m3
WX1200|Old Recipe 8943 kg/m3
WX1200|New Recipe 9213 kg/m3

Page 37
Building PI System Assets and Analytics with PI AF

3.2.6 Directed Activity - Creating AF Enumeration Sets

About Enumeration Sets

An enumeration set is an ordinal list of sequential integer values, which are mapped to names. It
allows AF attributes to refer to a common term instead of a number. This is analogous to the
Data Archive digital state sets used by Digital points. It is not needed to rebuild the digital state
sets or maintain them in AF. Enumeration sets are just a meaningful way to display information,
perform data validation and maintain data consistency across the AF structure.

Hierarchical enumeration values (new in AF 2017 R2):

Enumeration values can be nested in hierarchy. The hierarchy can have as many levels as
needed. In our case, WX1200 is produced with different recipes, which result in different
physical characteristics and so in different density values. In a different level below the WX1200
value we can distinguish between the old and new recipe.

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:

Value Name
0 AQ4500
1 HC1500
2 WX1200

To distinguish WX1200 produced with either the old or new recipe, we will add two
child values in a level below WX1200:
Value Name
3 WX1200|Old Recipe
4 WX1200|New Recipe

Check In to save newly created objects to the AF database.

Page 38
 A Walkthrough of AF

3.2.7 Directed Activity - Creating 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). When converting you have to decide,
how the PI Point Data Reference for the Level attribute should be set. Select
Substituted, which will set the PI point name according to a naming pattern rule.
The default naming rule is %Element%.%Attribute%.%ID%.
Under Suggested Point Name, enter %Element%LI.PV and click Apply.

If you create elements for another tank based on the template, the substitution
parameters in the point reference (enclosed with %) for the Level attribute will be
replaced according to the name of the new element:

Naming Pattern: %Element%LI.PV

Element Name PI Point Name
Tank02 Tank02LI.PV
Tank03 Tank03LI.PV
Tank04 Tank04LI.PV
etc.

Substitution parameters will be explained later.

Locate your new element template under Library > Templates > Element Templates
section and change the element template name to Tank. Check In.

Page 39
Building PI System Assets and Analytics with PI AF

Under the Attribute Templates tab of the Tank template, add five (5) new attribute
templates by clicking the button from the toolbar.
Attribute Name Default UOM Value Type Data Reference Display
Digits
Enumeration (*)
Product <None> <None>
Sets > MaterialID
Density kg/L (Density) Double Table Lookup -5
Mass kg (Mass) Double Formula -6
Pressure bar (Pressure) Double PI Point 2
Tank Name <None> String String Builder (*)

Note: though the display digits are not applied for non-numerical values, the default value for
Display Digits (-5) will be displayed, Do not change the value.

Product Attribute
Enable the Configuration Item Property. Set the default to HC1500.

Density Attribute
Configure the Table Lookup data reference for the Density attribute using the
following:

Table Result Column Where

Material Density MaterialID = @Product
Properties

Page 40
 A Walkthrough of AF

Mass Attribute
Configure the Formula data reference for the Mass attribute using the following:

Parameters Equations
Variable Attribute Unit of Measure
D Density kg/L D*V
V Volume L

Pressure Attribute
The tags for the pressure sensors have the following tag names:

Element Name PI Point Name

Tank01 Tank01.Pressure
Tank02 Tank02.Pressure
etc.

Using the substitution parameters %Element%.%Attribute% for the tag name

means that for every element that is based on the Tank element template, the PI
point name will be set to the name of the element (e.g. Tank01) plus the name of the
attribute (Pressure). Substitution parameters will be explained later.
The value from the tag is the pressure measured in PSI. Since Velocity Terminals
has sites globally, we would like to show the pressure in bar. (Attribute, Default
UOM: bar; PI Point Settings, Source Unit:PSI).

Page 41
Building PI System Assets and Analytics with PI AF

Tank Name Attribute

To configure the String Builder data reference for the Tank name attribute:
Select String Builder from the Data Reference dropdown selection and click on the
Settings…
Click on the Add New String button, click on to get further selection options,
then select “%Element%” from Substitution Parameters:

Check In the changes.

Go back to the Elements section, select the Tank01 element and look at its
attributes.
Pick material HC1500 for the Product attribute enumeration list and then click on
.
Note the value of the Density attribute. Check the correct tank name.

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 AF elements.

However, for elements that would act only as organizing assets (folders) and that have no
attributes, a template is not required.

Page 42
 A Walkthrough of AF

3.2.8 Directed Activity - 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 Value
Capacity 30,000
Product AQ4500
Commit these changes to the AF database ( ).

The Power of Templates

The term template suggests a cookie-cutter way to create new objects with consistency. AF
element templates do this and more for elements. They ensure similar equipment stay alike in
AF.

When changes (in default values, attribute definition, or structure) are made to the template, the
elements created using that template are automatically updated.

Note: If changes were made at the element’s 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 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 button from the toolbar.

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 AF. Very few applications would not
benefit of the use of templates when building AF elements.

Page 43
Building PI System Assets and Analytics with PI AF

3.2.9 Directed Activity - 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
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.

Dragging an element
Action
while pressing the…

Copies the original element under another parent

Ctrl Key
element. The original and the copy will not be linked.

Shift Key Moves the element.

Creates an Element Reference. The element will now

exist in two places in the hierarchy. In this case, the
No key
element icon has a “link” designator ( ), like in the
case of a file shortcut.

Problem Description
You would like to establish an AF element hierarchy, where
Montreal is the top level element, and the two tanks are child
elements in a level below.

Approach
1. Create a new element not based on any template named Montreal. Check-in
the changes.
2. Select a tank with the mouse and drag and drop it while holding the Shift key
on the keyboard in order to move the element under the Montreal element so
it becomes child element of that location.
Select the Parent-Child Reference Type for each tank element. The different
reference types will be discussed in the next chapter
3. Repeat for the second tank. Check-in the changes.

Tip 1: When the element move does not result in the intended operation (this can happen when
you release the Shift key too early) click on the “Undo all changes to the Database” button ( ).

Tip 2: As an alternative to dragging and holding the Shift key, right click the element, copy it to
the new location and then delete the original.

Page 44
 A Walkthrough of AF

3.2.10 Directed Activity - Creating AF Objects in Bulk Using the PI Builder Add-in

PI Builder is an add-in to Microsoft Excel 2007 and later allowing rapid creation and
edition of AF objects and PI points in bulk.
Open Microsoft Excel, and select the PI Builder ribbon menu.
In the Connections section, select the Asset Server (AF Server: PISRV01) and the
AF database (AF Startup).
To connect to your AF database click on Database.

Import the tank elements from AF. To do this, select Elements > Find Elements from
the PI Builder ribbon menu, then select the Tank Template to search and find both
tanks.
Make sure to search child elements.

Select to import the Template configuration of the element.

Page 45
Building PI System Assets and Analytics with PI AF

Select capacity and product attributes to import their configuration and values.

Once you click OK, the objects imported from AF on the spreadsheet should look like
the following:

Use Excel functionalities to create two additional lines for Tank03 and Tank04.

Page 46
 A Walkthrough of AF

Verify the Product name matches one of the valid material from the Material
Properties AF table.

Name |Capacity |Product

Tank03 10000 HC1500
Tank04 10000 WX1200|Old Recipe

The records are now ready to be exported to AF; which will create two new tanks.
Click on the Publish button from the ribbon menu ( ). For the Edit Mode, select
Create Only.

Confirm your work by going to PSE > 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. Or use the NewName column in the PI Builder in Excel.

Because 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.

But in PI Vision and in PI Datalink definitions are based on element name and require an update
when element has been renamed.

Page 47
Building PI System Assets and Analytics with PI AF

3.2.11 Attribute Traits

Attribute traits hold characteristic information for their parent attribute. These can be
limits, forecast values, geolocation information, reason codes, asset health, and
analysis start triggers. They can either be defined as a fixed value or in combination
with a Data Reference such as e.g. PI Point or Table Lookup. Attribute traits are child
attributes.
Limit attribute traits: limits typically represent the expected range of a process
variable. Following limit traits are defined:
• Minimum and Maximum (very lowest/highest possible value)
• LoLo and HiHi (very low/high value for an abnormal situation, typically
initiates an alarm)
• Lo and Hi (low/high value that needs attention, typically initiates a warning)
• Target (aimed-for value such as setpoint)
Forecast attribute traits: forecasts contain predicted values, which allow to
compare actual value with the parent attribute. It typically comes from a future PI
point.
Location attribute traits: use location attributes to define longitude, latitude, and
altitude information for an asset. You can use this information to identify the location
of the asset on a map. Used by Integrator for ArcGIS.
Reason attribute traits: use reason attribute traits on event frames and transfers to
enable users to select a reason code for excursions, downtime, and other events.
The reason attribute trait must be an enumeration set that is previously defined, or a
system enumeration set delivered with PI AF.
Analysis start-trigger traits: When users configure analytics to generate event
frames, they can optionally elect to store the name of the start trigger in the value of
an attribute (string) and mark that attribute with the analysis start trigger trait. This
enables clients like PI Vision to indicate the start trigger that created that particular
event frame.
Health attribute traits: use health attribute traits on elements and models to enable
users to set a numeric health score and a health status (for example, healthy, out of
service, in maintenance, warning, or error). The HealthStatus attribute trait uses
values from the Health Status enumeration set, which is delivered with PI AF.
Administrators can modify the Health Status enumeration set as required.

Page 48
 A Walkthrough of AF

3.2.12 Directed Activity – Adding value limits for the tank level

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.
Your instructor will have directions.

Problem Description
You would like to use attribute traits to maintain limits for the normal operation of the
tanks. For all tanks the limits are the same.

Approach
1. In the PSE Navigator, select Library and open the Tank element template.
2. Select Limits… from the context menu of the Level attribute:

3. Set the limit traits as follows and click on OK.

Page 49
Building PI System Assets and Analytics with PI AF

3.2.13 Units of Measure (UOM)

The units of measure (UOM) feature allows automatic unit conversions for data
values. AF considers the technical unit for a measurement and allow to display it with
a different unit.
For example, suppose AF attributes of a tank represents the diameter and the height
and have a UOM of meters. AF considers the selected unit of measure. This
provides the option to show the diameter and height in other units than in meters,
e.g. to show it in inches. Another consideration is in attributes with a formula. It is
possible to calculate the tank volume in liters based on the physical dimensions
provided in meters. AF does the automatic conversion for you.
The relations between UOMs are defined with simple or formula conversion
methods.
There is one repository with all units of measurement
(UOMs), which is shared by all AF Databases. In other
words, the UOMs defined for one AF database maybe
used in any other AF database.
Unit of Measurements are organized in UOM classes.
UOM classes represent measurable properties, such as
temperature, length, time, and mass. To facilitate region
specific use of UOMs, the UOMs are associated with a
UOM group, which can either be Metric or US Customary
(additional UOM groups can be defined).

Click on Unit of Measure in the PSE Navigator to edit UOMs, UOM classes and UOM
groups.

Page 50
 A Walkthrough of AF

3.2.14 Directed Activity – Exploring how UOMs are organized and how they are used

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.
Your instructor will have directions.

Activity Objectives
• Understand the organization for UOMs, the UOM classes and the UOM
groups and their relationships.
• Apply unit of measures for a calculation of liquid in a container

Problem Description

A container at your plant has a shape of a

cylinder. The diameter is 1 m, the height of
the liquid inside (PI point: sinusoid) varies
and is measured in number of centimeters
(range 0 … 100 cm). Use a formula to
calculate the reactor volume in liters. Apply
units of measures properly.

• 1 meter (m) = 10 decimeter (dm) = 100 centimeter (cm)

• The volume of a body in liter is calculated from dimensions in decimeter
(1 liter = 1dm x 1dm x 1dm).

Page 51
Building PI System Assets and Analytics with PI AF

Units of Measure, UOM classes and UOM groups

1. Navigate to Unit of Measure and from the list of UOM classes, locate the
UOM class for Length and display its properties. What is the canonical UOM?
2. From the list of UOMs for Length, open the Properties for centimeter. What is
the conversion between meter and centimeter? What is the corresponding
unit for the US Customary UOM group?

Note: Per default, attributes are displayed in the PI System Explorer with the unit of measure in
which they were defined. With Tools > Options you can change that the attribute is displayed
with a unit from the selected UOM group.

3. Add new UOM for decimeter (1 decimeter = 0.1 meter), click on OK and
Check In.

4. Locate the UOM class for Area and display its properties. Note that the base
units is Length ^ 2. Locate the UOM class for Volume and display its
properties. Note that the base units is Length ^ 3.
5. Use the Conversion Calculator at the right hand side and convert 1 m3 (cubic
meter) into liters.
6. (bonus) Use the Search UOMs control at the top right
and search for units starting with sec. What is the
difference between the two units you get?
7. (bonus) How many kW has the motor of your car? Convert into horsepower.

Page 52
 A Walkthrough of AF

Container Element with attributes for Diameter, Fill Level and Liquid Volume
1. Select the Demo AF database, select Elements in the Navigator.
2. Locate the Container01 element (below UOM Demo).
3. Add an attribute for the Diameter, set the default UOM to meter (from UOM
class Length), Value Type= Double, and set value to 1
4. Add an attribute for the Fill Level, set the default UOM to meter (from UOM
class Length), Value Type= Double.

Set Data Reference to PI Point. Click on Settings to define tag name

SINUSOID, and under Unit of Measure set the Source Units to cm.
Values for SINUSOID are in range 0 … 100, in which range will the values for
Fill Level attribute be? Answer: 0 m ….. ________ m
5. Add an attribute for the Liquid Volume, set the default UOM to liter (from
UOM class Volume), Value Type= Double.

Remember that you get the proper value in liters, when you multiply the
values in decimeters. Set data Reference to Formula and define it as follows:

Hint: you get pi() from the Functions drop-down

6. Select Tools > Options and set Display UOM Group = US Customary. Click
Refresh to display UOMs from the US Customary group. Revert the setting
back to <None>.
7. (bonus) Remove the Read Only flag for the Fill level attribute and enter
maximum fill level of 1m. What is the Liquid Volume? Confirm result by using
the Windows calculator.

Page 53
Building PI System Assets and Analytics with PI AF

4. Modeling and Organizing the Assets

4.1 Asset Hierarchy Design Strategies

In a 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. They are used to convey the place/location of each
entity in the company. Since the AF system is probably not the only enterprise
system in your company, other systems in place might already make use of asset
hierarchies (maintenance systems, 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 AF using the PI Builder
add-in.

Note: The whole company does not need to be modeled in AF for you to be able to get value
out of it. In fact, the AF structure build-up is often project-driven. This means to begin with, a
small structure containing your pumps might be built for use in PI ProcessBook displays. As
more and more applications start making use of AF, the structure will continuously grow to
include more and more of your assets.

That being said, it is still a good idea to define the various hierarchy levels that will be
represented in the AF structure (divisions, locations, production lines, process, etc.) before
gradually adding the assets to that hierarchy.

There are several styles for designing asset models in AF.

Even if the following approaches will result in a complete asset 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 AF model does not need to be perfect and complete the first time.

4.1.1 Bottom-up

Often a Data Archive is already in place so one approach is to group the assets by
similar Data Archive points. These “similar object” groups become AF element
templates, and the “objects” become AF elements. Any foreign data that is available
is imported. Next, analytics that may seem useful are added, and finally consumers
such as PI ProcessBook displays or PI Datalink reports.
The bottom-up approach has the advantage of being a clear, reality-based path to
follow. The Data Archive points are known and analytics can be added on top of
them.

Page 54
 Modeling and Organizing the Assets

However, a clear disadvantage is that this approach lacks vision. This approach
does not guarantee the result to be useful since the asset model was not built with a
particular goal in mind.

4.1.2 Top-down

Another approach is to start by asking theoretical questions:

✓ What is the goal of the asset model?
✓ What do the consumers need from 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. Next, AF attributes can be added for the
desired data points, even if the source for the data is not known yet. The first stage is
simply to add the placeholders for that data, i.e. non-configured attributes. If these
attributes are confirmed to be the ones needed, then the analytics can be added, the
Data Archive tags can be mapped, and the model can be fully implemented.
This top-down approach has the advantage of planning for the usefulness of the 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. One disadvantage is that the design can drift away from reality and
be incredibly hard to implement while having little benefit over an easier alternative,
which is hard to tell beforehand. Another inherent disadvantage is that much of the
available raw data that is not “necessary” will be ignored from the model.

4.1.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, then 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 it is 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 the assets.
• Design the element templates and inheritance tree.
• Add attribute templates.
• Configure the attributes to point to foreign data or Data Archive points, all with
proper units of measure.
• Add calculations/analytics.
• Test the model using consumers (sample reports, displays, etc.).

Page 55
Building PI System Assets and Analytics with PI AF

4.1.4 Group Discussion – Asset Hierarchy Design Strategies

The group discussion allows to share student experiences and opinions on

which design strategy to select in their case. The instructor will moderate
the discussion.

Page 56
 Modeling and Organizing the Assets

4.2 Organizing AF Elements in Hierarchies

Avoid same names for different devices
If you have multiple devices in different environments, do not assign the same name
to them, as this can cause confusion. The following structure is possible but not
recommended:

To avoid this situation, either assign unique names (such as Tank1, Tank2 in
Montreal and Tank3 and Tank4 in Houston) or make the names unique by adding a
location code:

Different Views for the assets

Once a hierarchical structure has been built in 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 AF database.
AF has this ability to let the system manager organize their assets in multiple
different ways. It is then possible to have different “views” of the same information
but without duplicating that information. This can be done using Element References
( ).

Page 57
Building PI System Assets and Analytics with PI AF

4.2.1 Directed Activity – Familiarize with multiple asset views

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.
Your instructor will have directions.

Activity Objectives
• Understand how to organize assets in different views in order to
accommodate different AF user groups in the company.

Problem Description
In the Demo AF database there is a branch for Asset
Views. The main view is organized according to the
geographical location of the devices, a second view is
maintained based on the equipment types, and in a
further view is a general inventory list. You would like to
locate the first boiler in Frankfurt in all the views.

Approach
Open the Demo database in AF. Expand both the Locations, the Equipment and the
Inventory branch and locate the first boiler in Frankfurt in all the views. Explore that
the same information is represented in two locations of the asset tree.

Page 58
 Modeling and Organizing the Assets

1. Select the Demo database in AF. Select Elements in the Navigator and
explore the Asset Views branch. Locate FRA Boiler1 in all the three views.
2. Open the General tab for the FRA Boiler1 element.
Click on the Parents link:
The three positions in the element tree are listed by their corresponding
paths. The icon for the element itself has a little checkmark in the top right
corner ( ).

3. Select the element under Locations - Frankfurt and enter an element

description. Check-In the change. Then select one of the element references
in the other views and verify the modified description in there.

Page 59
Building PI System Assets and Analytics with PI AF

4.2.2 Element Reference Types

Whenever you create a new element or element reference in the asset tree, you are
asked to define the reference type related to its parent element.
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
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.

Parent-Child
With a Parent-Child reference, the child can have multiple parents. The child element
can thus be part of multiple hierarchies.

Parent-Child is the default for a new child element creation. When you use that reference type
substitution parameters in the element attributes are resolved according to the hierarchy the
element is in.

Weak Reference
A Weak element reference is like a Parent-Child element reference, but a weak
referenced element cannot exist on its own.

Weak is applied for element references when you have a main view (e.g. master view organized
according to geographical location) and you create additional views for your assets (e.g.
organized according to business function). Different to a parent-child reference the element
reference in an additional view will not exist on its own when removed in the master view.

Page 60
 Modeling and Organizing the Assets

4.2.3 Directed Activity – Understanding Reference Types (optional)

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.
Your instructor will have directions.

Activity Objectives
• Understand the use of different reference types in context with what happens
when you delete an element.

Approach
Open the Demo database in AF. Expand the Reference Types Demo. Explore the
reference types between the elements in the structure below.

Composition
The HeatExchanger01 in Production Line B has a valve that is an integral part of the
exchanger that can not exist on its own. Therefore, the relation between the valve
and the exchange is Composition.
1. Select Heat Exchanger01 and click the Child Elements tab on the right.
Check the Reference Type option:

2. Select Heat Exchanger01 and select Delete… from the element context
menu. Select Delete option to delete the object and all references to it.

Page 61
Building PI System Assets and Analytics with PI AF

3. Check-In and Refresh. Result: the valve element and all the valve element
references disappear (this is independent from whether the valve element
reference has a strong or weak reference to the parent element)

Weak Reference
Pump01 is located as a child under Production Line A - Pumps. This is the main
view for Pump01. An element reference for Pump01 is below the Secondary View
element, which is an additional view. For this view, the reference Type between
Secondary View and Pump01 element reference is Weak Reference.
1. Select Pumps and click the Child Elements tab on the right. The child
element Pump01 has a Parent-Child reference with its parent.
2. Select Secondary View and click the Child Elements tab on the right. The
Pump01 element reference has a Weak Reference with its parent.
3. Select Pumps and select Delete… from the element context menu. Select
Delete option to delete the object and all references to it. Check-In and
Refresh. Result: the element reference for Pump01 below Secondary View
disappears, because by deleting Pumps and Pump01 you have deleted the
last strong parent.

Typically you will be using Weak References for element references as you usually have one
main, primary view and further views are additional, secondary ones. However, the next part of
the exercise is to explore the use of Parent-Child with element references.

Parent-Child
Pump02 is located as a child under Production Line A - SiteABC. However, this is
not considered as the only view for this pump, because an element reference for
Pump02 is also below the Strong Families element, which is another view that is
considered with the same importance Reference Type between Strong Families
and Pump02 element reference is Parent-Child.
1. Select Site ABC and click the Child Elements tab on the right. The child
element Pump02 has a Parent-Child reference with its parent.
2. Select Strong Families and click the Child Elements tab on the right. The
Pump02 element reference has a Parent-Child reference with its parent.
3. Select Site ABC and select Delete… from the element context menu. Select
Delete option to delete the object and all references to it. Check-In and
Refresh. Result: the element reference for Pump02 is promoted to an
element. It changes from an element reference icon to an element icon.
(Sometimes the PSE does not show that properly even after a Refresh.
Switch to another database and back to the Demo database for a complete
refresh.)

Page 62
 Modeling and Organizing the Assets

4.2.4 Solo or Group Activity – Organizing the Tanks for Velocity Terminals

This solo or group exercise 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
• Build additional elements with PI Builder.
• Create parent elements to build a hierarchy.
• Organize the elements into hierarchies with drag & drop.

Problem Description
Now that four (4) of your tanks are defined and organized under their site (Montreal,
Canada), you now want to model and organize the tanks for other sites in your
company, Velocity Terminals. The sites are:
• Montreal, Canada
• Tokyo, Japan
• Sydney, Australia
You also want the ability to view the company’s tanks as part of a separate hierarchy
containing the receiving and distribution divisions. After searching on the enterprise
portal, you find the following documents:

Page 63
Building PI System Assets and Analytics with PI AF

Approach
Model the extra tanks in AF using the VelocityTerminals_Assets.xlsx worksheet
located in the Class folder.
1. To create the elements for the tanks Sydney and Tokyo, open the
spreadsheet. Use PI Builder Publish ( ) function to create the new elements
in your AF database.
2. Using PSE, create new elements, not based on any template, to model the
locations and divisions.
3. Use the drag and drop techniques discussed previously to move the tanks
into their appropriate hierarchies (Shift Key = Move Element).
4. To create the element references under the Divisions, drag the tank elements
into the corresponding element under Divisions (No key pressed = Create
Element Reference).

Note: Make use of Element References. Use Parent-Child references under the locations and
Weak references under the divisions.

Page 64
 Modeling and Organizing the Assets

4.3 Using the Import and Export Feature in PSE

From PSE, it is possible to use an Import and Export feature to export an entire AF
database or just a AF object to an XML file. With the Import functionality, it is
possible to import this AF object into another AF database. This can also be used to
back up a AF structure before performing potential destructive actions.
It is possible to export almost any AF object by simply right clicking that object and
selecting the option. To export the whole 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 65
Building PI System Assets and Analytics with PI AF

4.3.1 Directed Activity – Export and Import a Database

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.
Your instructor will have directions.

Activity Objectives
• Learn how to export an XML file from an AF Database and import into another
AF Database.

Problem Description
The AF structure for Velocity Terminals has been created in an AF database
dedicated to training and checkout. We would like to release it to production in a
different AF database. To do that, we will export contents of the AF Startup
database and import it into another AF database called Velocity Terminals.
Approach
• With AF Startup database opened, select File > Export to File from PSE
menu.
• Click on the icon and change settings to save the XML file as
C:\Class\Exercises\01_Velocity Terminals\My Velocity Terminals.xml. Click
on Save button (Note: this will not actually create the XML file!)

• Check the Include All Referenced Objects option. Click on OK.

• (optional) Use the editor and inspect the .XML file: locate units of measures,
the Tanks templates, the table, the elements created for the VT Tanks etc.

• Click on the button and select the Velocity Terminals database.

• Select File > Import from File from PSE menu and select the file that was
saved recently.

• Verify that objects in production database have been created successfully.

Page 66
 Visualizing Data

5. Visualizing Data

5.1 Visualizing AF Data in PI Vision

PI Vision is a modern and intuitive web-based visualization tool allowing ad hoc
analysis through rapid display creation. PI Vision allows you to:
• Search for PI data on desktop or mobile platforms.
• Visualize PI data as symbols, such as trends, tables, values, and gauges.
• Configure multi-state symbols to create visual alarms for critical process
states.
• Design, format and save displays for easy retrieval and further analysis.
• Analyze and compare process events.
• Monitor process data in displays.
• Share displays with other members of a group or anyone with access to PI
Vision.
• View PI ProcessBook displays.

Note: Before version 2017 the previous name for PI Vision was PI Coresight.

PI Vision homepage:

PI Vision makes use of an efficient search engine to let you browse through the
organization’s AF structure and rapidly find the information you are interested in. As
you begin looking at and analyzing some data, PI Vision will find related information
that might also be of interest to you.
If you have added a new database in AF and would like to access with PI Vision, you
have to update the list of allowed AF Databases in PI Vision:

Page 67
Building PI System Assets and Analytics with PI AF

Open the PI Vision Administration Page, then select AF Servers tab in the
Configuration section. You may have to expand the structure under the AF Server
name to see available databases. To add an AF database, select the checkbox next
to the AF database name and click on Save.

5.1.1 Directed Activity – Visualizing Velocity Terminal Data in a PI Vision Display

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.
Your instructor will have directions.

Activity Objectives
• Create a PI Vision display with tank data (AF database: Velocity Terminals)
• Incorporate objects with current data (trend, table, value object, gauge)
• Incorporate a picture
• Asset swap in PI Vision displays

Problem Description
Your manager has asked to visualize the tank data in a PI Vision display (name:
Velocity Terminals Tank) in the following way:

The display is setup for one of the tanks and should allow to swap between all tanks
at Velocity Terminals.

Page 68
 Visualizing Data

Approach

1. Click on the desktop link to open PI Vision. The link is http://pisrv01/PIVision.

There is also a bookmark for PI Vision under the favorites.
The homepage provides an overview with thumbnails of the displays, which
have been prepared for the training.

2. To create a new display, click on the link

Note: you are in Modify Display operation: the operation icon background is orange and the
canvas border is orange. To switch to Monitor Operation (you can do that in any non-empty
display) click on the operation icon, the canvas border will disappear and the operation icon
background switches to blue . You can toggle back and forth between the two operation
modes.

3. The search pane displays search paths for elements in the AF databases and
for tags in Data Archive.

4. Expand the asset structure to navigate to the Tank01. Select AF database

Velocity Terminals and penetrate to Locations > Montreal > Tank01. Select
Tank01 to get the attributes for that tank.

Page 69
Building PI System Assets and Analytics with PI AF

5. Select Level attribute and drag it to the display canvas on the left hand side.

6. Click on the > of the Level attribute to expand the structure and display the
traits. Drag Hi, HiHi, Lo, LoLo and Target into the trend. Select Format Trend
from the right mouse button menu.

Under Values Scales, Scale Type click on the icon for Single Scale .

For Scale Range click on the icon for Database Limits .

Click into the canvas to close the Format Trend settings.
Click on the time selector at the bottom and switch time display range to one
hour.

Page 70
 Visualizing Data

7. Click on Image icon and drag a rectangle in the display canvas. Under
the Choose File... selection navigate to VT Tank.jpg under
C:\Class\Exercises\01_Velocity Terminals

8. From the object list, select the Value object . Drag Tank Name to the top
of the tank picture.

9. From the right mouse button menu of the Value object, select Format Value.
Under Visibility, uncheck Label, Units and timestamp. Change Value color to
black.

10. Accordingly, position a value object for the Product attribute in the right
bottom corner

Page 71
Building PI System Assets and Analytics with PI AF

11. From the object list, select the Vertical Gauge object . Drag Level to the
center of the tank picture. Use Format Gauge to change the appearance.

12. From the right mouse button of the gauge object, select Add Multi-State.
Change the colors as following:

Bad data: magenta

HiHi – Maximum: blue
Hi – HiHi: light blue
Lo – Hi: light green
LoLo – Lo: orange
Minimum – LoLo: red

13. From the object list, select the Table object . From the attributes list,
select Capacity, Density, Product and Volume (keep Ctrl-key pressed). Then
drag them above the trend. You get a table with a header row and four rows
for the four attributes you had selected.

Page 72
 Visualizing Data

Select Table Columns… from the right mouse button menu and uncheck
Description, Trend, Minimum and Maximum.

14. Click on the Save icon on top right corner. Save display as Velocity
Terminals Tank in the Home folder.

15. Use the Asset selector to switch to another tank, Tank02.

16. Use the time control at the bottom to change the display ranges. Use the left
arrow to step through past time periods.
17. Position the cursor in the bottom area of the trend and drag it to switch the
time range.

18. To revert to the last hour from now, click on the Now button, then select the
1h from the time range selector.
19. Note: after you have made a modification in a display, the display name will
have an asterisk at its end to indicate there have been changes.

To save your changes, click on the Save icon . To save the modified
display under another name select Save As from the dropdown next to the
Save button and save under another name.
20. Add a symbol from the library to your display. The library is opened by

clicking the symbol on the left hand side: .

Page 73
Building PI System Assets and Analytics with PI AF

5.2 PI ProcessBook displays in PI Vision

PI Processbook has been the primary OSIsoft product for visualizing data from the PI
System for over 25 years. PI Vision, that allows to open displays in a browser
application, has become the first choice offering for visualization.

5.2.1 Directed Activity – Show a PI Processbook Display in PI Vision

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.
Your instructor will have directions.

Displays created with PI Processbook, can be viewed in PI Vision. They will be listed
in PI Vision, after they have been copied to a designated PI Vision Import folder. PI
Vision in the AF class training setup has some examples.

Step-by-Step Procedure
1. Open PI Vision in Web Browser.
2. Select Processbook Import folder.
3. Click on one of the displays.

4. Use the time controls on the bottom to navigate the modify time range.
5. Click on a trend to maximize the trend. Click into the trend to set a time
cursor.

Page 74
 Visualizing Data

5.3 PI Datalink
PI Datalink is a Microsoft Excel add-in that allows you to import data from your PI
System into a spreadsheet. Combined with the computational, graphic, and
formatting capabilities of Microsoft Excel, PI Datalink offers powerful tools for
gathering, monitoring, analyzing, and reporting PI System data.

5.3.1 PI Datalink Support for AF

With PI Datalink 2013+, it is possible to create reports that will leverage the AF
model, allowing reports to be reusable across similar assets. PI Datalink 2013+
benefits from the new integrated search engine, allowing searches for tags and
assets all at once.
PI Datalink 2014 introduces support for Event Frames, which will be discussed later
in the class.

Page 75
Building PI System Assets and Analytics with PI AF

5.3.2 Directed Activity – PI Datalink Basics: Access Sampled Tag data

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.
Your instructor will have directions.

This exercise is a brief introduction into PI Datalink. It familiarizes with recommended steps to
create a spreadsheet with dynamic data from the PI system.

Activity Objectives
• Use the Sampled Data function to get interpolated data for a tag in specified
time intervals.
• Understand how to reference spreadsheet cells to specify parameters for
Datalink functions.

Problem Description
You would have a report with interpolated tag values from tag TANK01LI.PV. The list
should cover the last 4 hours and list values in 15 minute intervals.

Approach
1. Open AF Class Datalink Exercises spreadsheet located in the
c:\class\exercises\01_Velocity Terminals folder.
2. Select the PI DataLink ribbon. Explore the different groups of PI Datalink
functions (see also the list on the next page). Which is the function that you
have to use?

_______________________________________________________

Page 76
 Visualizing Data

Group Function Name Function Example

Retrieve the current or What is the current outside air

Current Value most recent value of a temperature?
data item
Single
Value
Retrieve a data item What has been the tank level
Archive Value value for a specified this morning at 8:00 AM?
point in time

Retrieve data item What are the values stored in

Compressed
values for a specified the archive for the pressure
Data
time range sensor for yesterday?

Retrieve evenly-spaced, What is the generated Wind

interpolated data item turbine power, listed for every
Sampled Data
Multiple values for a specified full hour on the last Sunday?
Value time range

Retrieve interpolated What are the CO2 level values

data item values that for the tank at those times
Timed Data match with an array yesterday when there is value
specified of time stamps in the archive for the pressure
sensor?

Retrieve calculated data What are the hourly averages

item values. The for the reactor’s internal
calculation performs an temperature for yesterday?
Calculated Data
aggregation over a time
period (like minimum,
maximum, average etc.)
Calculation
Time Filtered Calculate the amount of How long has the motor been in
time over which a the “Running” state yesterday?
performance equation
evaluates as true for a
specified time range.

Page 77
Building PI System Assets and Analytics with PI AF

3. Select the Spreadsheet tab named Tags.

4. Enter the tag name TANK01LI.PV into cell B1.
5. Put the cursor in cell D1. This is where we want to have the result from the
Datalink function.

Note: before selecting a PI Datalink function, select the cell in the spreadsheet where
the result from the Datalink function should be output! This should be a free area in your
spreadsheet, so that existing contents is not overwritten!

6. Select Sampled Data function from Multiple Value group. Result: you get the
Sampled Data parameter window on the right hand side. Put the cursor into
Data Item(s) to select this parameter.

Note: click on the upper half of the icon. If you select the lower half, you select the
function along with pre-defined parameters.

7. With Data Item(s) selected, click cell B1 to reference the tag TANK01LI.PV.
Result: the parameter is set to ‘Tags’!$B$1
8. Put the cursor into Start time to select the parameter, then click cell B2.
9. Put the cursor into End time to select the parameter, then click cell B3.
10. Put the cursor into Time interval to select the parameter, then click cell B4.
11. Check Show time stamps.

Page 78
 Visualizing Data

12. Click on OK button. Result: data is returned into cell area D1 … E17.

Note: if you click Apply instead of OK, the Sampled Data parameter window is not
closed.

Page 79
Building PI System Assets and Analytics with PI AF

5.3.3 Directed Activity – PI Datalink Basics: report with data from AF

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.
Your instructor will have directions.

This exercise repeats the previous exercise, but instead of referring to a tag, an attribute in AF
(with PI Point Data Reference) is referenced.

Activity Objectives
• Understand how to specify an AF attribute in PI Datalink functions.

Problem Description
The report from the previous exercise should be built by referring to the Level
attribute of Tank01 in AF.

Approach
There are two ways to do that:
• refer to the Level attribute with the full AF path in one parameter for the
Datalink function
• refer to the Level attribute with the path and the attribute name in two
parameters

Page 80
 Visualizing Data

Full AF Path
1. Select the Spreadsheet tab named Attributes (1).
2. Put the cursor into cell B1, then click on the lower part of the Search icon and
select In a row. Result the Datalink Search window appears. You can either
search for tags or for information in AF. Select the AF Server PISRV01.
Result: PISRV01 is shown in the search path above.
3. Click on Velocity Terminals database, then penetrate further on to elements
Velocity Terminals – Locations – Montreal.
4. Enter Level into the search field and click on the magnifier glass at the right
side. Result: four Level attributes are listed, one from each of the four tanks in
Montreal, Tank01 … Tank04.
5. Drag the slider for Data item length to the left position, which is Full Path.
6. Select the line for Tank01 is the list above, then click on OK. Result: the full
path appears in cell B1:
\\PISRV01\Velocity Terminals\Velocity Terminals\Locations\Montreal\Tank01|Level

Note: the | character separates the path from the attribute name.

7. Put the cursor in cell D1. This is where we want to have the result from the
Datalink function. Select Sampled Data function from Multiple Value group.
Result: you get the Sampled Data parameter window on the right hand side.
Put the cursor into Data Item(s) to select this parameter.
8. With Data Item(s) selected, click cell B1 to reference the cell with the full
path.
9. Set parameters for Start time, End time and Time interval and check Show
time stamps.

10. Click on OK button. Result: data is returned into cell area D1 … E17.

Page 81
Building PI System Assets and Analytics with PI AF

Path and Item (attribute name) in two parameters

1. Select the Spreadsheet tab named Attributes (2).
2. Put the cursor into cell B1, then click on the lower part of the Search icon and
select In a row. Result the Datalink Search window appears.
3. Run the same search as in the previous exercise (it is probably still preset)
and get the same four Level attributes listed as before.
4. Drag the slider for Data item length to the right position, which is Name Only.
5. Select the line for Tank01 is the list above, and select Insert root paths in:
Column or Row. Click on OK. Result: the path appears in cell B1, the attribute
name appears in cell B2.
6. Put the cursor in cell D1. This is where we want to have the result from the
Datalink function.
7. Select Sampled Data function from Multiple Value group. Result: you get the
Sampled Data parameter window on the right hand side. Put the cursor into
Root path to select this parameter.
8. With Root path selected, click cell B1. Result: the parameter is set to
‘Attributes (2)’!$B$1
9. Set parameters for Start time, End time and Time interval and check Show
time stamps.

10. Click on OK button. Result: data is returned into cell area D1 … E17.

Page 82
 Visualizing Data

5.3.4 Directed Activity – PI Datalink: switch asset context in a report with data from AF

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.
Your instructor will have directions.

PI Datalink search window allows the possibility to generate drop-down lists in Excel to allow a
report to be applicable to multiple similar assets. This exercise repeats the previous exercise,
but shows how to create a cell with a drop-down selection to switch the asset context.

Activity Objectives
• Create a Datalink report that can be switched between different assets.

Problem Description
The report from the previous exercise, which gives values for the Level attribute of a
tank, should be enhanced to allow the switch between the twelve tanks.

Approach

1. Select the Spreadsheet tab named Attributes (3).

2. Put the cursor into cell B1, then click on the lower part of the Search icon and
select In a column. Result the Datalink Search window appears.
3. Expand the search for tanks in all locations. You can do that by click on
Locations in the search above. Enter Level into the search field and click on
the magnifier glass at the right side. Result: ten Level attributes are listed,
one from each of the ten tanks, Tank01 … Tank10.
4. Drag the slider for Data item length to the right position, which is Name Only.
5. Select the all lines in the list above (you can click on the checkbox in the
header line for that), and select Insert root paths in: Drop-down list. Click on
OK. Result: the path appears in cell B1, the attribute name appears in cell B2.
6. If you click cell B1 you get a drop-down selector icon for one for your ten
tanks.
7. Put the cursor in cell D1. This is where we want to have the result from the
Datalink function.
8. Select Sampled Data function from Multiple Value group. Result: you get the
Sampled Data parameter window on the right hand side. Put the cursor into
Root path to select this parameter.

Page 83
Building PI System Assets and Analytics with PI AF

9. With Root path selected, click cell B1. Result: the parameter is set to
‘Attributes (2)’!$B$1
10. Put the cursor into Data Item(s) to select this parameter. With Data Item(s)
selected, click cell B2.
11. Set parameters for Start time, End time and Time interval and check Show
time stamps.
12. Check Show time stamps.

13. Click on OK button. Result: data is returned into cell area D1 … E17.
14. If you switch the tank selection in cell B1, the report will retrieve data for the
selected tank.

Page 84
 Visualizing Data

5.3.5 Solo or group activity – Tank Level Report

This solo or group exercise 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 exercise.

Objectives
• Exercise the searching in PI Datalink.
• Get familiar with PI Datalink function to retrieve archive data.

Problem Description
The production supervisor needs an Excel report displaying the change in the level
of tank in Montreal between 8:00 AM and 9:00 AM today.
Approach
Select the Spreadsheet tab named LevelReport.
Use the Archive Value function to retrieve the level at 8:00 AM and at 9:00 AM today.
Once you have the level in two columns, you can calculate the difference using
Excel. Watch and follow along while the instructor creates this PI Datalink report.
Use Excel conditional formatting (Excel Home tab, Styles group) to highlight a
negative change.

Page 85
Building PI System Assets and Analytics with PI AF

5.3.6 Solo or group activity – Building an Element Relative PI Datalink Report

This solo or group exercise 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 exercise.

Objectives
• Experiment with PI Datalink’s Asset Relative feature.
• Follow the steps needed to create a report applicable to similar assets.

Problem Description
Create a small report that has the hourly averages for the level and mass present in
one of the Velocity Terminals tanks for the previous day. The report should have the
data for one tank, but should allow switching to another tank.

Approach
Select the Spreadsheet tab named Tank Analysis Report.
Which Datalink function allows to aggregate data such as getting the average over a
period of time?

_______________________________________________________

Page 86
 Visualizing Data

Hint: Cell C8 and F8 were prepared to show spark lines. Here is how the spark line
has been added for the Level data:
− Select the cells with the data (just select the values, not the timestamps)
− From the Excel Insert ribbon, select Sparkline
− Select the output cell (C8)

(Accordingly for the Mass spark line)

Page 87
Building PI System Assets and Analytics with PI AF

6. Adding Analytics to the Assets

PI Asset Framework provides several options to enhance the data with calculations
that are carried out on top of the values in the PI Data Archive. These calculations
transform raw process data into decision making information that is provided by the
PI System.

AF Calculation Option Examples

Get interpolated value for a PI Point from a

particular point in time (e.g. from 2 hours
Value Retrieval Methods
ago), get aggregated data for a PI point for a
(defined in PI Point data Reference)
defined time period (e.g. maximum from the
last 24 hours)

Ad-hoc calculation (add volumes from two

Formula Data Reference
tanks)

Expression: perform all kind of simple and

complex calculations such as summaries,
consumptions, metric data, KPIs etc.
Rollup: aggregate/summarize data over
Asset Analytics several levels in the asset hierarchy (e.g.
(Expression, Rollup, Event Frame maximum temperature for all reactors, overall
Generation, SQC) production in all production lines)
EF Generation: monitor process for special
conditions and capture in event frames (e.g.
downtimes, process excursions)
SQC: online statistical calculations

For a decision on what calculation options to use, consider the following aspects:
• What load will the calculation place on the PI System?
• Do I need to keep the history for the calculation?
• Will the calculation be applied to multiple assets?
• How complex is the calculation?
For related information refer to the Comparison table at the end of the next chapter.
Beside options in AF, there are further options in the PI System: Performance
Equations (PE) points and Totalizer tags (tag-based analytics in PI Data Archive
(*)),Calculated Data function and PI Expressions (PI Datalink), PI Calculation
datasets (PI Processbook) and PI Advanced Computing Engine (PI ACE).

(*) Note: Rather than using tag-based analytics in PI Data Archive, OSIsoft strongly
recommends that users upgrade to asset analytics that support event frames, formula data
references, and other newer features of PI Asset Framework.

Page 88
 Adding Analytics to the Assets

6.1 AF Calculation Options Overview

This section is an overview of calculation options in the PI System, all options are
explained individually in more detail later.

Value Retrieval Methods

• Configurable option within the PI Point Data Reference
• By default the current value of a tag is displayed
• By Time: get data from another point in time
(e.g. value from 2 hours ago)
• By Time Range: get aggregated data
(e.g. maximum value from last 15 minutes, total amount of material based on
the inflow)

Formula Data Reference

• Ad-hoc calculation, no history saved
• Calculation is defined in one or multiple equations
• Equation syntax based on variables,
operators (+, *, …) and functions (sin, cos, abs, sqrt,…)
• Examples: volume based on capacity and level, value of your stock based on
amount of goods and current prize

Page 89
Building PI System Assets and Analytics with PI AF

Asset Analytics (Analyses)

• Analysis Types: Expression, Rollup, Event Frame Generation, SQC

Expression Analyses:
• Calculation defined based on attributes, variables, operators and functions
• Functions include Performance Equation (PE) functions
(e.g. FindEq, TimeGE, TagMax, Tag Avg,…)
• Results stored in attributes (Analysis Data Reference, PI Point Data
Reference)

Note: This is for a first orientation. Expression Analyses as well as the other analysis types will
be explained in more detail later on.

Comparison
To help you with the selection for the best calculation option, use the following table.

Value Formula Data Expression Expression

Retrieval Reference Analysis Analysis
Methods (Output to non PI (Output to PI
Point Attribute) Point Attribute)

Creation Method Configuration Expression Expression Expression

Functions No Limited PE PE

Historization No No No Yes

Recalculation/ No No No Yes
Backfilling

Calculation Load Server Client Client Server

Time Awareness Relative No Yes Yes

Page 90
 Adding Analytics to the Assets

6.2 Formula Data Reference

Formula Data References allows the creation of simple custom calculations.
Calculations can be in the form of a single formula or a sequence of calculations.
The calculations are executed on demand, and the results are not archived
anywhere. The functions available are limited and they are not time-weighted.

We have used formula in previous chapter of the class when setting up the Velocity
Terminals tanks. It was used to have an additional attribute with an ad-hoc
calculation for the tank volume based on the capacity and the percentage of the
level.

6.3 Value Retrieval Modes

By default, the PI Point Data Reference retrieves the current value of a particular
point. The value retrieval methods of the PI Point Data Reference can be configured
so that the value will be either
• the value of a point at a specific time (By Time retrieval mode)
• the result of a calculation on the point’s value over a time range, e.g. an
average (By Time Range retrieval mode).

For detailed information refer to chapters "Configure value retrieval

by time" and "Configure value retrieval by time range" in the PI
Asset Framework and PI System Explorer section of the PI Server
documentation.

Page 91
Building PI System Assets and Analytics with PI AF

By Time - Retrieving a value other than the current one.

By Time mode options are After, At or Before, At or After,

Automatic, Before, Exact Time and Interpolated. To get a
value other than the current value these options are used in
context with the Relative Time field. Relative time
expressions have to be in the PI System Time format (see
examples below).

By Time Relative Meaning

Time

At or After -15m Returns the recorded value from 15 minutes before the current
time. If no value exists at that time, the next recorded value is
returned.

After -2h Returns the first recorded value after the point in time that is two
hours ago. If a value exists exactly at that time, it is not returned.

Exact -2h Returns the recorded value from two hours before the current
time. If no value exists at that time, “No Data”-error is returned.

Interpolated T+6h Returns an interpolated time for 6:00:00 of the current day.

Note: Do not choose the Not Supported, Time Range, and Time Range Override options for By
Time. These options are for attribute values based on time range calculations (see below)

Page 92
 Adding Analytics to the Assets

By Time Range – Retrieving the result of an aggregation.

By Time Range options are:

Average (time-weighted), Count, Delta, Maximum, Minimum, Population Standard
Deviation, Standard Deviation, Start Time, End Time, Total.
In case of Total, an extra drop-down appears to specify the time units of the rate
point or attribute over which the calculation is performed. That is required since the
Data Archive always assumes a rate point to be in units/day. Selecting the right time
units is thus essential to retrieve a correct result.
The options in the By Time field for a By Time Range retrieval are Not Supported,
Time Range and Time Range Override. Depending on what time context the client
application is providing the behavior is in the following table.

By Time Meaning
Setting

Not Supported If client application sends a time range, it is considered for the
calculation. If client application sends point in time (and not a time
range), an error is returned.

Time Range If client application sends a time range, it is considered for the
calculation. If client application sends point in time (and not a time
range), the time range specified under Relative Time is used.

Time Range The time range specified under Relative Time is used in any
Override case.

Page 93
Building PI System Assets and Analytics with PI AF

6.3.1 Directed Activity – Understanding Value Retrieval Modes for Times Ranges
(optional)

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.
Your instructor will have directions.

Activity Objectives
• Distinguish retrieval modes for time periods: Not Supported, Time Range and
Time Range Override

Problem Description
• You are measuring a temperature and would like to get minimum and
maximum for the last hour as well as for the time period applied in your PI
Vision trend.

Approach
Open the Demo database and select the Value Retrieval Demo element.
1. Display the elements attributes and get their function.

Attribute Name Value

Temperature Actual Value from now

Temperature.Min. Temperature Minimum for a time period: The time range

TimeRangeNotSupported is taken from the client (here: PSE). Because the PSE
does not supply a time range, a corresponding error (The
attribute requires a time range…) is displayed.

Temperature.Min. Temperature Minimum for a time period: If the time range

TimeRange.1HR is supplied by client (here: PSE), it is used. Because the
PSE does not supply a time range, the specified range is
used (1hr).

Temperature.Min. Temperature Minimum for one hour time period

TimeRangeOverride.1HR

(according to the three minimum attributes, there are three corresponding maximum
attributes)

2. (optional) From PSE Tools > Options > Time Context set a time range for
PSE of e.g. last five minutes. Discuss the value attribute changes. Reset the
time context back (Query Date Time= Latest Available)

Page 94
 Adding Analytics to the Assets

Click on the desktop link to open PI Vision and select the Retrieval Modes Demo
display.

1. Display the elements attributes and get their function. Set time period selector

to 1h:

Attribute Name Value

Temperature Actual Value from now

Temperature.Min. Temperature Minimum for a time period: The time range

TimeRangeNotSupported is taken from the client (here: PI Vision). PI Vision time
range is one hour. This means the Temperature
Minimum is for a hour time period.

Temperature.Min. Temperature Minimum for a time period: If the time range

TimeRange.1HR is supplied by client (here: PI Vision), it is used. PI Vision
time range is one hour. This means the Temperature
Minimum is for a hour time period.

Temperature.Min. Temperature Minimum for one hour time period

TimeRangeOverride.1HR

(according to the three minimum attributes, there are three corresponding maximum
attributes)

2. Set the time period selector to 8 hours.

Attribute Name Value

Temperature Actual Value from now

Temperature.Min. Temperature Minimum for a time period: The time range

TimeRangeNotSupported is taken from the client (here: PI Vision). PI Vision time
range is eight hours. This means the Temperature
Minimum is for an eight hour time period.

Temperature.Min. Temperature Minimum for a time period: If the time range

TimeRange.1HR is supplied by client (here: PI Vision), it is used. PI Vision
time range is eight hours. This means the Temperature
Minimum is for an eight hour time period.

Temperature.Min. Temperature Minimum for one hour time period

TimeRangeOverride.1HR

Page 95
Building PI System Assets and Analytics with PI AF

3. Set the start time to y+22h, set the end time to t. This is the time period of the
two hours before midnight today.
(yesterday 22:00:00 – today 00:00:00).

Attribute Name Value

Temperature Value from today midnight (today 00:00:00)

Temperature.Min. Temperature Minimum for a time period: The time range

TimeRangeNotSupported is taken from the client (here: PI Vision). PI Vision time
range is two hours. This means the Temperature
Minimum is for the two hour time period before midnight
today.

Temperature.Min. Temperature Minimum for a time period: If the time range

TimeRange.1HR is supplied by client (here: PI Vision), it is used. PI Vision
time range is two hours. This means the Temperature
Minimum is for the two hour time period before midnight
today.

Temperature.Min. Temperature Minimum is for the one hour time period

TimeRangeOverride.1HR before midnight today (yesterday 23:00:00 – today
00:00:00)

Page 96
 Adding Analytics to the Assets

6.3.2 Directed Activity – Apply Value Retrieval Modes for Tank Level Attribute

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.
Your instructor will have directions.

Activity Objectives
• Use the Value Retrieval mode to get the value of a tag from two hours ago
and its average for the last two hours.

Problem Description
• In addition to the actual material content level in the tanks, the operational
personnel would like to see what the level has been 2 hours ago and what
the average level has been for the last 2 hours.

Approach
Open the Tank template in the Library of the Velocity Terminals database.
Select Attribute templates tab.
For the value from two hours ago:
1. Select the line with the Level attribute and select New Child Attribute
Template from the right-mouse button context menu.
2. Attribute Name = Level.2HoursAgo
Default UOM = percent
DisplayDigits=2
Data Reference = PI Point
3. PI Point Settings:

Page 97
Building PI System Assets and Analytics with PI AF

For the average value of the last two hours:

1. Select the line with the Level attribute and select New Child Attribute
Template from the right-mouse button context menu.
2. Attribute Name = Level.2HoursAverage
Default UOM = percent
DisplayDigits=2
Data Reference = PI Point
3. PI Point Settings:

Verify the results:

1. Open one of the Velocity Terminals tanks (look at Tank03 because Level for
Tank01 and Tank02 changes too often).
2. Select the lines with the Level attribute and the two recently created child
attributes and select Trend from the right-mouse button context menu.

3. Set Start Time= *-8h and End Time= * and click on Refresh button.

Page 98
 Adding Analytics to the Assets

6.4 Case Study: PI Big Tires Co.

Before we will learn how to use expression analyses let us familiarize ourselves with
the tire production process, which is simulated in the TCE environment.

6.4.1 Directed Activity – Understand the production process at PI Big Tires Co.

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.
Your instructor will have directions.

Activity Objectives
• Understand the simulation of a tire production process.

How the Tire Curing Press work:

Raw tires are loaded individually into a Tire Curing Press. Once the tire is loaded, the
press is closed and temperature and pressure is applied to cook and mold the tire.
After the cooking time has elapsed, the press is opened and the tire is unloaded into
a cooling unit where fans blow air until the tire reaches a specific temperature.
Internal and Mold Temperatures and Pressure are attributes categorized under
“Process Variables”, their values are simulated in the TCE environment.
The system also tracks non-operational periods of the presses. The reason for a
downtime (e.g. a press setup, a maintenance or no operator at the press) is also
captured in a PIPoint attribute, Press Status. Under normal operation of the press
the Press Status is “Running”. In the TCE environment, downtime periods are
simulated on a random basis.
The Lid Position indicates whether the press is open or closed.
Attributes in the “Production” category provide information about the current days
production: Tires Produced is the number of tires produced today (i.e. since
midnight), Scrap Tires is the number of tires produced today, which cannot be sold,
Reference Type defines what kind of tire is currently in production.

The tire curing presses are an essential part of the production process and currently
there is a lack of key performance metrics; we will use Expression Analysis to extract
this information from the process data from the presses.

Page 99
Building PI System Assets and Analytics with PI AF

Familiarize with the attributes of the tire presses:

1. Open the PI Big Tires Co. AF database in PSE, select Elements in the
Navigator.
2. Explore the element hierarchy: it contains 3 locations (Houston, Montreal and
Philadelphia (“Philly”)) with four presses in each location. Select one of the
presses. Select attributes tab. Enable grouping by category.

3. Use the trend to display the Tires Produced for the past 48 hours. Identify
the reset to zero at midnight.
4. Identify the attribute template and open it (select Library in the Navigator).
5. Explore the enumeration sets used for Press Status and for Lid Position.

Page 100
 Adding Analytics to the Assets

6.5 PI Analysis Service, Expression Analysis

Asset analytics is a new feature of PI Analysis Service released with AF 2014 (2.6).
Asset Analytics allows you to create and manage analyses on top of your AF assets.
An analysis is a scheduled calculation that gets input values from attributes in any
level of your AF hierarchy and outputs its results to other AF attributes.
Asset analytics features three types of analysis:
• Expressions: Wide range of functions to create powerful analyses.
Expressions use the Performance Equation syntax.
• Rollup: Aggregation calculations for a group of selected attributes.
• Event Frame Generation: Specify conditions to trigger the start and the end of
an event.
• SQC: Uses Statistical Quality Control (SQC) methods to monitor that attribute
values lie within pre-determined boundaries.

Asset analytics provides the following capabilities:

• Historization: When the output attribute is mapped to a PI Point, the
calculation results are archived in the Data Archive.
• Backfilling/Recalculation:
Backfilling: Run the analysis over an earlier time period to backfill data for the
PI Points mapped to its outputs. Example: a new analysis to calculate daily
overall consumptions is created on April 1st. With Backfilling the overall
consumptions are calculated for a past period such as e.g. January - March
and stored in the archive of the output tag.
Recalculation: In case the values for the inputs of a calculation have changed
the recalculation feature allows to update the calculation results accordingly.
• Security: It is possible to configure and manage permissions to limit access to
analyses and analysis templates.
• Preview and Test: Calculation results can be previewed before putting the
analyses into production.
• Calculation Dependencies: The result of a calculation can be used as an
input to another calculation.
• Scheduling options: Calculations can be configured to be executed according
to a schedule or they can be event based.
Every analysis is associated with an element and can be created directly on that
element by selecting the Analyses tab; however, it is recommended that analyses
be associated with an element template. In order to do this, select the corresponding
Element Template and then use the Analysis Templates tab (see figure below).

Page 101
Building PI System Assets and Analytics with PI AF

Analyses can be managed (e.g. start, stop, backfill) directly at the element level
under the Analyses tab, or by using the Management plug-in from the navigator
panel. See below a screenshot presenting a short description of the different
components of the Management plug-in.

Page 102
Adding Analytics to the Assets

Page 103
Building PI System Assets and Analytics with PI AF

6.5.1 The Expression Analysis

The expression analysis allows you to create and schedule calculations using the
Performance Equation (PE) syntax and a broad gallery of functions. Before
discussing expression analysis in detail, it is essential to review the syntax for
expression analysis (also referred as Performance Equation (PE) syntax).

6.5.2 Syntax for Expression Analysis (PE Syntax)

The syntax for expression analysis is an algebraic syntax used to perform

calculations and filter data in multiple client and server products from the PI System
suite. Besides PI Analysis Service, the following products use this syntax:
• Data Archive through a PE points.
• PI ProcessBook through a PI Calculation dataset.
• PI Datalink through use of Filter Expressions or PI Expressions.
• Notifications through use of a PI PE Trigger Condition.

This syntax has three (3) rules when it comes to writing expressions:
1. AF Attributes or Data Archive tag names and time stamps are written enclosed
in single quotes (‘):
For example: ‘Pressure’, ‘CDT158’, ‘*-1h’, ‘03-Feb-2013 13:38’
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 as is.
For example: +, -, *, ^, TagTot(), FindGT(), etc.
2+3*4 and 2+(3*4): result for both is 14
The expression functions reference guide is available under the PSE help menu.

More examples:
if ('cdt158'+2*'sinusoid')> 100 then "good" else "bad"
if ('Temperature’+0.1*'Temperature|Offset')>50 then "hot" else "cold"

Page 104
 Adding Analytics to the Assets

6.5.3 Directed Activity – Checking Out the Expression Functions Reference

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. Your instructor will have directions.

Activity Objectives
• Learn where to find information about analysis expression functions.
• Explore the functions of the Expression Analysis syntax.

Approach
Information about analysis expression functions can be found at:
Analyses tab (Elements and Element Templates): Select the Demo AF Database and locate
the Analysis Demo element. Select the Analyses tab. Expression Functions are listed at the
right hand side. Use the drop-down for segregation according to functionality.

PI System Explorer Help: Asset Analytics > Expression functions reference

With the instructor, examine the highlights of Expression Analysis syntax and its
available functions.
• What function would you use to calculate the time-weighted average of an
attribute over the last 8 hours? ______________________.
• You want to find the total time that an attribute was greater than 100.What
function would you use? ___________________________.

Note: Each function presented in the reference guide features examples that can be copied
over to notepad or to other PI System products directly.

Page 105
Building PI System Assets and Analytics with PI AF

6.5.4 Solo or Group Activity – Applying Expression Analysis Syntax

This solo or group activity 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 Expression Analysis Syntax to different calculation and
filtering problems.

Problem Description and Approach

You may want to construct your equations in Notepad or another text editor rather
than in the space below so you can cut and paste from the help file.

Problem Your solution… Hints

Get a ten-minute “rolling”
average of the SensorX TagAvg()
attribute
Find the maximum for the
SensorY attribute over
the last 24 hours, but only TagMax()
if at least 80% of the
values used in the
calculation are considered
“good”.
The amount of time the TimeEQ()
Mode attribute was The amount of
“Manual” during the past time returned is in
four days. seconds.
Display “Overload” when
the SensorX attribute is
greater or equal than 90 ,
“Normal” when between
If... then… else
10 and 90 (excluding the
boundary values), and
“Empty” when lower or
equal than 10.

Try to do this exercise on your own before referring to the solution

on the following page.

Page 106
 Adding Analytics to the Assets

Familiarize with the function entry (optional)

1. Open the Demo database and select the Analysis Demo element.
2. Select the Analyses tab

3. Click on the New Analysis icon.

4. Enter the expressions in the Expression tab.

5. The analysis is not needed any more, so you can click on Check-out to undo
the entry.

Page 107
Building PI System Assets and Analytics with PI AF

6.5.5 Directed Activity - Overall Equipment Effectiveness (OEE) Metrics

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. Your instructor will have
directions.

Activity Objectives
• Create and configure an expression analysis.
• Create an analysis template.
• Backfill an analysis.
• Manage an analysis via the Analyses plugin.

Problem Description
Management would like to track the productivity of the tire curing presses by using
Overall Equipment Effectiveness (OEE). In short, OEE, developed in the mid 1990’s,
enables the monitoring of plant floor productivity and improvement of the efficiency of
a manufacturing process. OEE is composed of three different metrics: Availability,
Performance and Quality.

Metric Description Formula

Percentage of time that an equipment is Operating Time / Planned Production
Availability
up and running Time
Performance Actual yield to the target yield Total pieces / Target
Percentage of good units that are Good pieces / Total Pieces
Quality
produced
OEE Availability*Performance*Quality

Approach
The metrics represent a ratio, which can be in the range 0 … 1. We could also
represent this as a percentage in the range 0 … 100. We will use units for ratio and
percentage to convert the figures accordingly. Example:
When a press is only available half of the time, the Availability Score has a ratio of
0.5, which corresponds to 50%.
Each press has a status attribute. A press is considered to be operating whenever it
is in the running status; any other status indicates that the press is out of order.
The time basis for the OEE metrics calculation should be the current day, which means
beginning at midnight until the current time.

Page 108
 Adding Analytics to the Assets

Adding an Analysis Template

As indicated previously, it is recommended to configure the analyses directly at the
template level. So let’s open the press element template and click on the Analysis
Templates tab. In this window (see figure below) you will be able to set up analyses
that will be automatically created when a new instance of the corresponding element
is added to the AF structure.
First, enter a name and a meaningful description for the analysis (e.g OEE Metrics),
and then select the expression analysis type using the radio buttons.

Note: We have selected to enable the analysis right-away when it is created from the template.
Uncheck the option if you are not confident that your analysis does the right calculation. The
analyses can be started at a later time for the related elements.

Page 109
Building PI System Assets and Analytics with PI AF

Entering an Expression
The next step is to enter the expression, which is the equation that will be executed.
An expression can be written in a single row or multiple rows. Asset analytics allows
you to assign the result of a row to a variable; this variable can be used later in
another row.

Tip: Take advantage of the variables to simplify complicated expressions; testing and
debugging will be much easier since you will be able to evaluate smaller expressions one at a
time.

Let us use the first row to calculate the OEE availability. Start by giving a name to the
variable, for example Availability. The pane on the right lists descriptions of all
available functions that you can use to build your equation.
How can we get the time the press was running today?
___________________________________________________.

In what way will the time be returned?

___________________________________________________.

Let us assume the press should run all time. How can we get the number of seconds
until now since midnight?
___________________________________________________.

The ratio between these two times will be in range 0…1.

To assign the appropriate engineering unit, use the function Convert.

Note: The Convert function converts a value from its current unit of measure (UOM) to a
specified UOM. For a value with no UOM, assign the specified UOM.

Example:
Convert ('Outside Air Temperature', "degC")

Page 110
 Adding Analytics to the Assets

So the complete expression is:

Convert(TimeEq('Press Status','t','*',"Running")/DaySec('*'),"ratio")

Here are some tips concerning entry of expressions:

• Tip1: Auto completion (aka. IntelliSense) is available to assist you with the
syntax.

• Tip2: If you enter something that is syntactically incorrect, a curly underline

will occur:

• Tip3: If you click on Functions in the right hand side, the pane will list all
available functions. The drop-down on the top allow to filter function groups
(e.g. Date and Time). Select a function and click on the green Plus icon to
add it into the expression (you don’t have to type it)

• Tip4: You can add comments to explain what you are doing. Comments start
with two forward slashes (//). To start a new line use Shift-Enter.

Page 111
Building PI System Assets and Analytics with PI AF

• Tip5: If you click on Attributes in the right hand side, the pane will list all
available attributes. The upper part allows to navigate in the asset tree.
Select an attribute and click on either one of the green Plus icons to add it
into the expression (you don’t have to type it)

Insert Relative:

The attribute is inserted without the path in the element tree:

This refers to the attribute in its actual element context.

Insert Absolute:

The attribute is inserted along with the absolute element path. This refers to
the attribute in the specified element path.

You can pick attributes from other elements by navigating in the asset tree
shown above. An example for use of an absolute path is when the attribute
has a general meaning, e.g. the outside air temperature at a location:
'\Houston|OutsideAirTemperature'

Page 112
 Adding Analytics to the Assets

Mapping the output to an attribute

The output of an expression can be mapped to either an existing or a new attribute. In
order to map it to an existing attribute click to Map and select the corresponding
attribute. We will be mapping the result of the availability calculation to a new attribute,
so select New Attribute Template, which will open the Attribute Template Properties
window. Set the name to OEE Availability.

Switch to the Attributes Templates tab and select the OEE Availability attribute. Set
Default UOM to percent. Assign a new attribute category OEE Metrics. Under
Settings, you can now select a PI Point as an output. If an appropriate PI Point does
not exist, you can enable automatic point creation; simply check the Tag Creation
checkbox under Settings.

Tip: In case the output attribute’s data reference is a point, calculation results will be stored in
the Data Archive; therefore you will be able to trend them in PI Vision or PI ProcessBook.
Moreover, points also provide improved performance for AF.

Note: When automatic tag creation is enabled, you can use substitution parameters to name the
points. %Element%.%Attribute%.%ID% is the default for asset analytics output points.
Substitution parameters will be presented later in the class.

Page 113
Building PI System Assets and Analytics with PI AF

Scheduling an expression
Now that the calculation has been written, it is time to schedule it. Two scheduling
options are available: periodic and event-triggered.
• Event-triggered scheduling is event driven: the calculation is executed
whenever one or multiple input attributes receive a new value. You get to
choose which input attributes trigger the calculation.
• Periodic scheduling is clock-based and in the configuration window, you can
specify a period and an offset. Let us schedule the OEE calculations to be
executed every minute (00h 01m 00s).

Page 114
 Adding Analytics to the Assets

Testing an expression
Now that the calculation has been written and the scheduling is defined, it is time to
test it. The Evaluate button executes the expressions against values at evaluation (i.e.
now) and against values at Last Trigger (in our case when the current minute has
started). This will help you determine whether the results makes sense. Since we are
working from a template, you will have to click on Example Element before you can
test the expression.

Another great way to validate your expression is to run it against archived values; we
call this feature “preview results”. Right click the analysis name and select Preview
Results (see screenshot below).

Tip: You can export the results table to a spreadsheet or you can copy selected rows from the
results table into other applications.

Page 115
Building PI System Assets and Analytics with PI AF

Checking in an Expression
To the left of the analysis name the following icon is showing . This indicates that
the analysis has been modified and it needs to be checked-in for the changes to take
effect. Go ahead and click on .
Upon Check In, the Analysis Service will create the points for the output attribute and
start the analyses for all presses.
If you go to the Elements plugin and navigate to one of the presses you will notice
under the Attributes tab that the analysis’ output attribute (OEE Availability) is referring
to a tag that has been created based on the settings in the template. In case the
attribute value is “Pt Created” click on the Refresh button (after the full minute has
elapsed) so you get a calculated value.

Tip: By right clicking the parent element (i.e. Montreal) and selecting Create or
Update Data Reference, PI Points for all presses will be created; so you do not
have to do it one by one.

Managing Analyses (Start, Stop, Backfill)

The Analyses tab allows you to manage the analysis. You can even create new
analyses for a particular element, however, as we said before, we recommend using
analysis templates.
Analyses should start-up automatically unless there is an error with the configuration.
You can use the play ( ) and stop ( ) buttons to either start or stop an analysis.
Below a screenshot of the management analysis pane.

Page 116
 Adding Analytics to the Assets

An analysis can be in one of several states. The icon to the left of the analysis name
indicates its status. See the table below for the meaning of each icon.

Icon Meaning

New analysis

Starting or stopping

Running

Disabled

Error

Unknown Status

Since the analysis has been started, the OEE Availability attribute should now be
showing results. You may have to wait for a few minutes or refresh the screen to see
updates.

Page 117
Building PI System Assets and Analytics with PI AF

6.5.6 Directed Activity – OEE Metrics – Performance and Quality

This solo or group exercise 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 exercise.

Exercise Objectives
• Create and schedule an expression analysis.

Problem Description
Create analyses to calculate the remaining two OEE metrics: performance and
quality. After doing this you will be able to compute the OEE score.

Approach
Using the analysis template you just created (OEE Metrics), add two more expressions
to calculate the quality and performance metrics.

Quality
The quality is calculated as net production of good items / gross production count. The
total number of tires produced on the day (this includes the scrap tires) is tracked
under Tires Produced, the daily bad quality items are tracked under the Scrap Tires
attribute.
Expression:
___________________________________________________________________.

Performance
Performance is calculated as the net production count / expected production count.
The daily production count is tracked via the AF Attribute Tires Produced; the
production target is expressed in tires/hour under the AF attribute Production Target.
Hint: Since the production target is expressed in tires/hour, you will have to find the
expected production count by multiplying the Production Target by the number of
hours elapsed during the current day.
Useful functions: hour(‘*’) and minute(‘*’)
Expression:
___________________________________________________________________.

Page 118
 Adding Analytics to the Assets

OEE Score
Calculated as the product of Availability*Performance*Quality. Expression:
___________________________________________________________________.

Tip: Every variable of an expression can be mapped to an output attribute.

6.5.7 Backfilling/Recalculation

An analysis writes new data to its output attributes starting from the moment it is
created. It is however also possible to calculate the data for past periods of time.
There are two related options for that, which control how existing data should be
handled.
Example: you create a new analysis on March, 1st 2017 to calculate the heat energy
consumption, which is added from various sources. The designated output attribute
with the total consumption will have values for the time from that date onwards. To
get values for January and February 2017 as well you can use the backfill feature.

The two options are:

1. Leave existing data and fill gaps: existing data is retained and only
missing data is back filled.
2. Permanently delete existing data and recalculate: existing data will be
deleted before the new data are backfilled.
Notes:
• The option for existing data handling is new with AF 2016 R2. In previous AF
versions data were never deleted. This had to be carried out manually before
the backfill.
• Backfilling/recalculation requires that the output attributes have been mapped
to PI Points.
• Backfilled data is added into the archive files. With PI Data Archive versions
before 2012 an upfront intervention could be required to make backfilling to
work properly (e.g. PI archives reprocessing)
• For an event-frame-generation analysis, data is automatically deleted and
recalculated (which is the only mode allowed). Be aware that annotations on
those event frames will be lost.

Page 119
Building PI System Assets and Analytics with PI AF

6.5.8 Directed Activity - Backfilling OEE Metrics

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. Your instructor will have
directions.

Activity Objectives
• Learn how to backfill a calculation.
• Get familiar with the Analyses plug-in and perform some administration tasks.

Problem Description
Management is very happy seeing real-time updates for the OEE score so they want
more details. They have asked you to trend the OEE score for the last 24 hours for
all presses belonging to the Houston site where they recently acquired innovative
technology.
Approach
First, make sure that the OEE Metrics analyses are running and showing no errors.
In order to do this, you can take advantage of the
Management plugin under the Navigator pane.

To backfill an analysis, one option is to browse to the corresponding element and

then right click the desired analysis and select Backfill/Recalculate.

Page 120
 Adding Analytics to the Assets

However, since we want to backfill an analysis belonging to multiple elements, it

would take too many clicks to complete this task element by element. The Analyses
plug-in offers the possibility to perform backfills in bulk. All you need to do is select
the analyses, click on Queue backfilling for selected analyses under the Operations
pane. Next, enter the start time and end time then hit Queue.

Page 121
Building PI System Assets and Analytics with PI AF

6.5.9 Improving analyses for robustness and readability

We have seen how to write an analysis to calculate OEE KPIs. There are some
options to make the calculations more robust and improve readability (for example,
at midnight DaySec(‘*’) will be zero and when you divide by that there will be an
error). The following screenshot provides an example how to avoid divisions by zero
and how to distribute the calculation into more steps to achieve that.

The following knowledge article provides more related information :

KB01520 - Asset Analytics Tips and Tricks

https://customers.osisoft.com/s/knowledgearticle?knowledgeArticleUrl=KB01520

6.6 The Rollup Analysis

The rollup analysis allows you to perform aggregations or summary calculations
based on attributes associated with an element. The power of rollup analyses lies in
their ability to perform aggregations on an element’s children.
As an example, you might need to calculate the total energy consumption for a group
of motors in a paper mill. To do this, you create a rollup analysis on the parent
element (the paper mill) that sums the energy consumption attributes from its child
elements the motors.
When designing and building a AF hierarchy, the use of categories is going to pay off
when you start using the rollup analysis type. This is because when configuring a
rollup analysis, the attributes to be included in the calculation are selected by name
or category.

Page 122
 Adding Analytics to the Assets

6.6.1 Directed Activity – Comparing Sites using Rollups

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. Your instructor will have directions.

Activity Objectives
• Configure and test a roll-up calculation.

Problem Description
Management of our fictitious tire company would like to start comparing the
performance of the tire presses across all sites in the organization; the first metric
they would like you to develop is the total production of good tires.

Approach
Each press has an attribute for the current day’s total production and another one for
the current day’s scrap tires; however, no attribute holds the count of good tires
produced, so you will have to come up with one.
Let us start by creating the Good tires production counter attribute. Since you do not
want to archive the results of this intermediate calculation, you can use an AF
Formula Data Reference.
Under the Press template, add the new attribute and calculate the difference
between the Tired produced (represents the total production) and the Scrap tires.
Assign the new attribute to the Production attribute category.

Page 123
Building PI System Assets and Analytics with PI AF

Creating a roll-up analysis

Now it is time to shift focus to the parent elements, the sites. Select the Houston
element and go to the Analyses tab, give a meaningful name to your analysis and
select the Rollup analysis type.

A list of all available attributes is displayed on the right pane. It is now necessary to
select from that list the ones that will participate in the rollup calculation. You can
narrow down your search by filtering by element category or template. You can then
type-in the attribute name or category. The matching results will show a checkmark (
).

Note: A rollup identifies input attributes each time it is executed, hence it automatically includes
any new attributes that meets the selection criteria. You do not need to update the rollup
configuration when you create a new element.

Page 124
 Adding Analytics to the Assets

Selecting the roll up function

Now that you have selected the attributes for the rollup, it is time to specify the
function or type of summary calculation the rollup analysis will run. There are six
available summary functions:
• Sum
• Average
• Minimum
• Maximum
• Count
• Median
Since we want to calculate the total number to tires produced on a particular site, the
summary function to select is Sum.

Tip: You can select multiple functions in a rollup calculation, each one mapped to a specific
output attribute.

Mapping the output to an attribute

Once the function is selected, you can map the output to an attribute. In case the
output attribute does not exist yet, you will be prompted to create a new one. Let us
create a new output attribute and name it Total Good Production.

Switch to the Attributes tab and assign Tires for the default UOM of the Total Good
Production attribute.

Page 125
Building PI System Assets and Analytics with PI AF

Scheduling the roll-up calculation

Finally, it is time to schedule the calculation. The same two scheduling options
presented for the expression analysis type are available for rollups: event-triggered
and periodic. For this exercise, it makes sense to update the result every time a new
good tire is produced, hence, select event-triggered scheduling.

Tip: Before starting the analysis it is a good idea to click on the evaluate button to preview the
result. Furthermore, you can right-click on the analysis name and select Preview Results; this
will show you a trend with the result of the calculation had it run for a previous period of time.
These two actions will help you validate your rollup calculation.

The calculation is ready to be started! Check-In your changes.

Note: Be patient, it will take a moment to start the analysis and to create the PI point for the
rollup result! If the PI point of the Total Good Production attribute is not created use Create or
Update PI Point function from the attributes right-mouse button context menu.

Check the status of the calculation for any errors and validate that the output
attribute is updating.

Page 126
 Adding Analytics to the Assets

6.6.2 Group Question – One Site, Multiple Sites

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.

Objectives
• Convert an analysis to an analysis template.

Questions
The rollup calculation has been deployed to the Houston site only. What feature of AF
can you use to deploy it to the remaining sites? ____________________
What steps would you take to achieve this?

1. ____________________________________________________________.

Note1: In the Convert Attribute to Template dialog box, enable the Include Tag
Creation checkbox. This is needed because no tags have yet been created to store the
results of the Analysis.

Note2: set the PI Point naming pattern for Total Good Production attribute to follow the
default pattern, which is %Element%.%Attribute%.%ID%

2. ____________________________________________________________.

Bonus Question
How to display the three (3) Total Good Production Counters in one list?
____________________________________________________________.

Page 127
Building PI System Assets and Analytics with PI AF

6.6.3 Solo or Group Activity – Perform an advanced attribute search (optional)

This solo or group activity 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
• You have recently created attributes in several places of your asset hierarchy
that contain the string “Good”. Use the attribute search to get all their values
in one list.

Approach
1. From the PSE menu, select Search – Attribute Search…
2. Enter *Good* into the attribute name field. Make sure the Search Sub-
Elements option is selected. Click Search. Result: attributes containing string
“Good” are returned. Click on OK.

3. Click on the name of the Search to populate the Search Results at the right
hand side.

Page 128
 Adding Analytics to the Assets

6.7 Visualizing Calculation Results in PI Vision

6.7.1 Directed Activity – Visualize OEE Metric calculation results

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.
Your instructor will have directions.

Activity Objectives
• Duplicate an existing PI Vision display for the tire presses
• Visualize the OEE Metric calculation results.

Approach
Save the existing PI Vision display for PI Big Tire Presses under another name.
Add Good Tire Production Counter into the existing trend.
Add a trend for the OEE Metrics

Duplicate a PI Vision Display

1. From the PI Vision overview page, open the Big Tires Press display.
2. Click the dropdown link in the upper right corner to open the Save As menu.

3. Enter Big Tires Press Training as display name and click on Save.

Note: If you have added a database in AF and would like to access with PI Vision, you have to
update the list of allowed AF Databases in PI Vision. For more information see Visualizing AF
Data in PI Vision above).

Add data into a trend

1. Switch to Modify Display operation:

Page 129
Building PI System Assets and Analytics with PI AF

2. In the Assets pane, navigate to HOU.Press.01

3. From the Attributes pane, drag the Good Tires attributes into the trend with
the Tires Produced counter.
4. Configure the trend to have just a single scale.

Add a trend for OEE Metrics

1. Verify that trend has been selected in the symbol gallery.

2. From the Attributes list, select the OEE Metric category and drag it into the
display canvas.

Page 130
 Tracking Important Events

7. Tracking Important Events

Events are important process or business time periods that represent something
happening that affects your operations. In the PI System, events are known as event
frames. Thanks to Event Frames, you can analyze your PI data in the context of
these events rather than by continuous time periods. Instead of searching by time,
Event Frames enables users to easily search the PI System for the events they are
trying to analyze or report on.
With Event Frames, the PI System helps you capture, store, find, compare and
analyze the important events and their related data.
Event Frames represent occurrences in your process that you want to know about,
for example:

• Downtime tracking • Environmental monitoring

excursions

• Process excursions • Product tracking batches

• Equipment startups and • Operator shifts

shut downs

The following table presents some of the features and advantages of Event Frames:

✓ Reference multiple elements within the

same event.
✓ Support multiple overlapping events on a
Flexibility
AF element.
✓ Capture any event; a “batch” is just one
type of capturable event.

✓ Search by time range, type of event or

event frame attribute.
Powerful search ✓ Most common search attributes can be
configures as indexed attributes to speed
up end-user searches

Scalability ✓ Event Frames are extremely scalable.

A Event Frame is defined by three characteristics:

1. Name.
2. Start time and end time: defines the event’s time range.
3. Context: event attributes and related assets.

Page 131
Building PI System Assets and Analytics with PI AF

7.1 Tracking Production Downtime Periods

7.1.1 Directed Activity - Downtime Tracking

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. Your instructor will have
directions.

Activity Objectives
• Create an event frame template.
• Configure an event frame trigger.

Problem Description
PI Big Tires Co. has been falling behind their production schedule because, for
various reasons, the tires presses are frequently down. To improve the situation they
want to use Event Frames in AF to track the downtime periods for all their presses in
Houston, Montreal and Philadelphia.

The Maintenance engineer has asked you to trace the root cause for every
downtime. The curing press can be in one of five states, which have different
criticality.

They want to have a record of the investigations performed by the maintenance

team. Therefore it should be possible to acknowledge and save individual comments
for each Downtime Event Frame.

Page 132
 Tracking Important Events

Approach
1. For the first press in Houston, inspect the history of the Press Status value
and create one event frame manually. Set the name, the Start and End Time,
and the element reference. Define an event frame attribute to track the Press
Status value at the beginning of the downtime (i.e. the reason code of the
problem).
2. Create a corresponding event frame template (convert the event frame
created in the previous step into a template).
3. Define a naming pattern for new event frames from that event frame
template.
4. Add an analysis for the first press in Houston that monitors the Press Status.
Distinguish the different Press Status values and associate them with
corresponding severities.
5. Use an Output Expression to get and store the event frame duration to ease
future analysis of the event frame data with Excel Power Pivot.
6. Preview the analysis to assess whether the triggers were set correctly.
7. Start the analysis.
8. Backfill the analysis for the time since midnight today.
9. Include the analysis into the press template to apply the analysis to all
presses.
10. Backfill the analyses for all presses for the time since midnight today.

The instructor will show these steps and ask you to follow along in directed activities.

Page 133
Building PI System Assets and Analytics with PI AF

7.1.2 Directed Activity - Manual Event Frame Generation

To begin with, we will create a single event frame manually to have an example of
what we would like to capture for the period of a press downtime.
To begin with, let us identify a downtime period for the first press in Houston,
HOU.Press.01, based on the Press Status values.
1. Select Elements from the navigator panel and select Attributes tab for
HOU.Press.01.
2. Select the line for Press Status. Select Time Series Data… from the right-
mouse button context menu and display the values for the last two hours.
3. Identify a period, when there was a downtime. It starts with a value that is
different from Running and ends with a value of Running again. In our case
below, the press was not running after 1:22:05 PM because of Planned
Maintenance, and was not running again before 1:35:05 PM because of
another Maintenance.

Fill in the information for your case in the table below and close the window.

Example above: Your case:

Start Time 13:22:05

End Time 13:35:05

Time in seconds 780

Reason Planned Maintenance

for the downtime

Page 134
 Tracking Important Events

4. Select Event Frames from the navigator panel and click on the
button. Select <none> for Event Frame Template.
5. For name, enter Downtime Sample Period for HOU.Press.01. Enter Start
and End Times in hh:mm:ss. As you do not specify a date, PSE will assume it
is for today.

6. On the Referenced Elements tab, select the blue Add Element Reference
link, click on the button in the Single section.
7. In the Element Browser navigate to Houston -> HOU.Press.01 and click on
OK.

Page 135
Building PI System Assets and Analytics with PI AF

Event Frame Attribute for the Downtime Reason Code

8. Let us track the reason, why the press had a downtime. It is the value of the
Press Status attribute at the start of the problem.
On the Attributes tab, click on the blue New Attribute link. For the attribute
name, enter Reason Code. For value type, select Press Status from
enumeration sets. For Data Reference select PI Point. Click on Settings.
9. The dropdown offers the attributes of HOU.Press.01, select
.\Elements[.]|Press Status. For By Time Range select Start Time. Click on
OK.

You will get the Press Status value for the beginning of the event frame
period as it has been recorded before.
Note: If the value type was reset, switch it back to Press Status.

Event Frame Attributes

The generic format for attributes of event frames is .\Elements[.]|Attribute.

The attribute reference starts with .\Elements[.]| to indicate the primary element of the
event frame's Elements collection. .\ is the current reference, [.] is the default object of
the collection. The pipe character (|) is used to separate the element from the attribute
name.

Page 136
 Tracking Important Events

Create a new Event Frame template based on our manually created event
frame.
Now, that we have defined what we would like to record for press downtimes, let us
make a template out of it.
1. Check In your changes
2. Select the event frame you created, and from the right mouse button menu,
select Convert > Convert To Template.

3. For the Reason Code, keep

.\Elements[.]|Press Status;TimeRangeMethod=StartTime
Click on OK.

4. Check In your changes

Page 137
Building PI System Assets and Analytics with PI AF

7.1.3 Directed Activity - Finalize the event frame template

Let us have a look at the event frame template that has been created and adjust and
finalize it.
1. Select Library from the navigator panel and expand the structure Templates >
Event Frame Templates and select Downtime Sample Period for
HOU.Press.01Template. Rename to Press Downtime.
2. The Naming Pattern field enables you to dynamically build the name of the
event frames produced from the template so that each event frame will have
a unique, identifiable name. Use the arrow on the right ( ) for a list of
available substitution parameters. The most common ones are presented in
the following table:

%ELEMENT% Referenced element. Asset

where the event happened.

%..\ELEMENT% Name of the parent element of

the referenced element. To
retrieve further ancestors, use the
..\ notation, such as
%..\..\Element%.

%TEMPLATE% Name of the event frame

template.

%STARTTIME:yyyy-
MM-dd Event start time and format.
HH:mm:ss.fff%

3. What naming pattern should we set so the downtime events are called
something like the following?

DownTime HOU.Press.01 (Houston) 2015-12-24 23:22:21

_________________________________________________________

Note: In case the Naming Pattern field is not set, event frames created with asset analytics
will be named NameOfTheAnalysis – Starttime (i.e. Press Downtime – 20140725 11:20:00).

4. To track, whether the event frames was read by an operator, enable the Can
be Acknowledged option ( ).

Page 138
 Tracking Important Events

5. Open the Attribute Templates tab. The Reason Code attribute we have
defined before is listed here.
6. Add an Event Duration attribute (default UOM: second, value type: Int32,
data reference: Formula) to get the duration in number of seconds. We can
use the substitution parameter %Duration% in the formula as simply as
follows:

7. Producing one tire takes approximately 5 minutes (= 300 seconds). Based on

the duration of the press downtime the number of tires can be calculated that
could have been produced in case the press would have been running.

Add a Production Loss attribute (default UOM: tires, value type: Double,
data reference: Formula) and enter a calculation to get the number of tires
with a division by 300:

Page 139
Building PI System Assets and Analytics with PI AF

8. Check in the changes.

Page 140
 Tracking Important Events

7.1.4 Directed Activity - Creating an EF Generation Analysis

Let us create an EF generation analysis to track the downtime events in our curing
presses. Create it directly under Houston’s press1. Once we validate that this is
working fine we will convert the analysis into a template for deployment to all the
presses in our company.
Event frame analyses are configured in a similar way to expressions and rollup
analyses. Browse to Houston’s press1 and under the Analyses tab select Event
Frame Generation. Give a meaningful name and description to your analysis.
An event frame analysis is based on an event frame template, go ahead and select
the template from the dropdown list.

Tip: Before you create an EF generation analysis, be sure an event frame template is available
for it.

Page 141
Building PI System Assets and Analytics with PI AF

Triggering Conditions (Start Trigger Only)

It is time to enter the conditions that will trigger the start and end event: StartTrigger
and EndTrigger. These conditions are entered as expressions using the PE syntax
presented earlier.
When a single condition triggers both the start and the end of an event frame, only
the StartTrigger expression is needed. When the expression evaluates to TRUE the
event frame is started, and when it evaluates to FALSE the event frame is closed.
For example a tank’s level rising above a threshold might start an overflow event, the
event would end when level is below the threshold.

Triggering Conditions (Start and End Trigger)

You can specify an EndTrigger expression when the start and end conditions are
different:

In the case with Start and End Triggers, the end of the event is dependent on the
End Trigger condition only. So after the event has started, the event ends when the
End Trigger becomes true, independent from whether the Start Trigger is True or
False.

Page 142
 Tracking Important Events

Tip: If using start and end triggers, make sure the expressions never evaluate to TRUE at the
same time since this may lead to event frames with zero second durations. Try to configure your
event frames to use only a StartTrigger expression.

For example, if the temperature rises in your reactor the foam level rises accordingly.
When the temperature drops again, the foam level drops as well, but with some
delay in time.
You would like to capture the time, when temperature is too high until foam level is
back to normal:

Page 143
Building PI System Assets and Analytics with PI AF

Defining Triggering Condition for the Press Downtime

Since AF 2016 it is possible to define several start trigger conditions and associate
them with different event frame severities. This meets our requirement to have event
frames with different severity based on the reason why the press was down. Let us
look at the first situation, when the press stopped running because of a Planned
maintenance or a Press set-up.
The expression to start the event in that case is:
_________________________________________________________.
Assign an Information severity level.

To enter start and end triggers, click on blue Add… link and select
corresponding option from the dropdown.

Enter the start and end trigger expressions and assign the severity levels as follows:

Tip: Use the StartTrigger True for option to require the start trigger remain true for a set time
interval before creating the event frame. This is useful for attributes with continuous, non-
stepped data to prevent spikes in the input data from generating unwanted event frames.

Page 144
 Tracking Important Events

Scheduling an Event Frame Analysis

The last thing to do is to schedule the event frame analysis. As with expressions and
rollups, two scheduling options are available: Event-Trigger and Periodic. For this
exercise, schedule it as Event-Triggered.

7.1.5 Directed Activity - Previewing analysis results and starting the analysis

You can now use the Preview Results feature to validate whether the events that
would be generated are as expected. Select the Downtime analysis in the list of
analyses. From the right mouse context menu, select Preview Results.

If the results are OK, click on changes. Result: the analysis will start
running:

7.1.6 Directed Activity - Backfilling Event Frame analysis

The analysis we have created will monitor the Press Status from now on. However,
with the Backfill function of analysis, it is possible to also backfill past periods in time!
This means that the archived values for Press Status will be examined and event
frames with dates in the past will be created accordingly.
To backfill the time since midnight:
1. Select the Downtime analysis in the list of analyses. From the right mouse
context menu, select Backfill/Recalculate.

Page 145
Building PI System Assets and Analytics with PI AF

2. For Start Time, enter a t (=today midnight), for End Time enter a * (=now).
Click on Start button. The Backfilling column will show the progress of the
backfill activity.

3. After backfilling is completed, switch to the General tab and click on the blue
Event Frames link. You will get a list with all event frames linked with that
element.
4. (optional) Verification: what is the start time of the first event frame?
5. (optional) Scroll through the list and locate the manually created event frame.
There will be a further corresponding event frame with same start and end
time that was created by the analysis. Select the manually created event
frame and select Delete… from the right mouse button context menu. This
event frame is not required any more.

Page 146
 Tracking Important Events

7.1.7 Directed Activity - Converting an Analysis into a Template

It is very common that customers create and test an analysis directly on an element
(e.g. Houston’s Press01) before adding it to a template (e.g. Press template).
Analyses can be added to a template so you do not need to configure them once
again at the template level. Just right click the analysis and select Convert to
Template as seen in the figure below. Then check-in.

Note: Convert to Template does not create an element template; it just adds an analysis to an
already existing one.

Note: The analysis will be added to all assets created from the element template. Analyses will
be started automatically after the Check-in.

Page 147
Building PI System Assets and Analytics with PI AF

7.1.8 Directed Activity - Backfilling Event Frames

This solo or group exercise 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 exercise.

Exercise Objectives
• Define and save a search that returns the downtime analyses for all presses.
• Backfill the analyses in bulk.
• Understand the backfill options.

Problem Description
Downtime events are now being tracked in real time for all presses in our company.
Management does not want to wait for new events to start analyzing the causes of
production loss; they want you to create the event frames for all presses since today
midnight.

Approach

Use the Management plugin in the Navigator Panel

to backfill multiple event frames.
Initially, all analyses in that AF database will be listed.

To work with a specific set of analyses (all the downtime analyses for all presses),
you can define and save a search that will filter just those analyses:

1. Click on the green sign to add a new search:

2. For the search name, enter Press Downtime Analyses and select Template
under the Add Criteria dropdown.
3. From the Template dropdown, select Press Template\Downtime and click on
OK. Result: the list of analyses on the right hand side lists twelve analyses
(four from each location).

Page 148
 Tracking Important Events

To perform a backfill for all Presses:

1. Click on the checkbox on top of the list to select all presses.

2. Click on blue Queue backfilling or recalculation for 12 selected analyses link.

Acknowledge that existing event frames in the time range will be deleted,
then click on Queue button.

Note with regard to the required acknowledgement: For an event-frame-generation analysis

(different to the backfill case in context with non event-frame-generation analyses), data is
automatically deleted and recalculated. This is the only mode allowed. Be aware that
annotations on those event frames will be lost.

Page 149
Building PI System Assets and Analytics with PI AF

Automatic Recalculation: (AF 2017 R2 and later)

In case you expect that data from your inputs will be late-arriving or be out-of-order, you can
request automatic recalculation for an analysis. The Management list allows to set this option for
multiple analyses within one command. To set the option on an individual analysis base, use
Advanced Options on the Analyses tab of an element or an element template.

Page 150
 Tracking Important Events

7.1.9 Solo or Group Exercise – Defining an output expression for an event frame
analysis (optional)

This solo or group exercise 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 exercise.

Exercise Objectives
• Explore the option to output the result of an expression in an event frame
attribute at the time when an event frame is closed.

Problem Description
When the downtime event is closed, we want to set a downtime log entry, which
provides the information, whether it was a minor issue (when duration was less than
10 minutes) or whether it had a critical production impact.

Approach
1. Add a string attribute to the event frame template for press downtimes
2. Define an expression with a string result depending on the event duration
3. Store the expression output in an event frame attribute

There are different ways to get the event duration in an expressions. The following
KB summarizes the options:
How can I store the duration of an Event Frame in an Event Frame attribute?
https://customers.osisoft.com/s/knowledgearticle?knowledgeArticleUrl=EventFramed
urationinEventFrameattributeAsset-Analytics

In this exercise we will use the EventFrame function (new in AF

2017 R2). The function allows to get event frame properties
such as the start and end time or the duration of an event
frame.
The get the event frame duration the parameter for the
EventFrame function is “Duration”.

Page 151
Building PI System Assets and Analytics with PI AF

Step-by-Step Instructions
1. Add a string attribute Downtime Log Entry into the Press Downtime event
frame template:

2. Open the Downtime analysis in the Press element template.

3. Click on blue Add… link on top of the triggers section and select Output
Expression option from the dropdown.
4. For the expression, enter
IF EventFrame("Duration") > 600
then "* critical production impact *"
else "minor issue"

Note: To start a new line, insert Shift-Enter.

5. Click on the blue Map link at the right hand side, and select the Downtime
Log Entry attribute.

Page 152
 Tracking Important Events

7.2 Consuming Event Frames

Event Frames are stored in the AF Server. Visualization clients, such as PI Vision
and PI Datalink access the AF Server to retrieve the events and their related data
providing you with powerful tools to analyze important events.

Note: PI ProcessBook, PI BatchView, and PI Manual Logger do not support event frame
visualization.

7.2.1 Event Frames in PSE

In this section, we will be exploring how to consume event frames in PI System

Explorer (PSE). As an administrator, you can use PSE to search for events and
analyze them. The results are presented in a practical table format that features a
Gantt chart and columns for the attributes. Moreover, this is a quick way of verifying
the creation of event frames.
In order to access event frames in PSE, click on the Event Frames plugin under the
navigator panel.

Note: Unlike elements, it is not possible to browse events. You actually have to search for them.

The following screenshot presents the main features of the Event Frames plugin:

Page 153
Building PI System Assets and Analytics with PI AF

Event Frame Search Results

Event frames are listed with their information such as the event frame name, a Gantt
diagram, the event duration, the severity, and the start and end time:

Displaying the Event Frame attributes

By default, the event attributes are not displayed in the result window.
By right-clicking and selecting Column Visibility, you will be able to choose the
attributes you want to display.

Tip: To change the column visibility you can also click on the Settings icon in the header
row of the search results.

Page 154
 Tracking Important Events

Column Column EF Row Meaning

(Meaning) (Header Icon) Information

Is Template Hover with the mouse over this column

to get the event frame template.

<empty> Event frame is not based on an event

frame template.

Is Locked Captured Values: values for the event

frame attributes are saved in AF (see
note below).

<empty> Values for the event frame attributes are

not saved in AF (see note below).

Is Annotated Event Frame is annotated. Hover with

the mouse over the icon to get the
annotation(s).
Use EF right mouse button menu option
Annotate… to enter new annotations.

<empty> Event Frame is not annotated.

Use EF right mouse button menu option
Annotate… to enter new annotations.

Is Not Event Frame can be acknowledged.

Acknowledged Use EF right mouse button menu option
Acknowledge… to acknowledge the EF.

Event Frame is acknowledged.

Hover with the mouse over the icon to
get acknowledgement info (by whom?,
when?).

<empty> Event Frame cannot be acknowledged.

Whether an event frame can be
acknowledged is defined in the
corresponding event frame template
(General tab)

Note: You capture values to save the values for event frame attributes in a table in
the PI AF database. This can improve performance since PI AF does not execute
any data references. If you add new attributes to event frames with captured values,
you should recapture those values to ensure that values are also captured for the
new attributes.

Page 155
Building PI System Assets and Analytics with PI AF

7.2.2 Directed Activity - Event Frame Searches, Acknowledgement and Annotation

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.
Your instructor will have directions.

Exercise Objectives
• Familiarize yourself with the event frame search in PSE.
• Acknowledge and annotate event frames.

Problem Description
You want to get the details for any downtimes after 10PM yesterday triggered by a
“No Operator” root cause so you can annotate the events, and acknowledge them.

Approach
Use the Event Frame Search window to perform the following:
1. Select New Search from the right mouse button menu of the Event Frame
search root.
2. Enter following criteria: start time: y+22h, event frame template: Press
Downtime, element name: Hou*, Reason Code= No Operator ( you have to
use Add Criteria to enter that)

Hint: you can enter the criteria one by one and click on Search every time. If you enter
more criteria, then you get less event frames that match your criteria. Click on OK when
the returned event frames meet the desired scope.

3. Rename your narrowed down search: Downtime Events No Operator after

10PM yesterday

Background: Once performed, your searches and their criteria are saved. Use Rename
from the context menu of a search to assign a descriptive name for the search. To
further refine an existing search, while keeping the existing search saved, select New
Search from the context menu of the search and then modify the new one.

4. Add columns for the Reason Code and the Event Duration attributes. Verify
the Reason Code is No Operator in every case.
5. Select the first event frame and add annotation: “Bob was busy with
representative from press manufacturer.”
6. Select all event frames that started before midnight and acknowledge them in
one action.

Page 156
 Tracking Important Events

7.2.3 Solo or Group Exercise –Event Frame Searches

This solo or group exercise 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 exercise.

Exercise Objectives
• Perform medium to advanced event frames searches.

Problem Description
Perform the following event frame searches in PSE:
4. Find all downtime events for Montreal’s press2 for the last 12 hours.
5. Add columns to show the Production Lost and Reason code.
6. Narrow down your search to find events that lasted more than 10 minutes.
7. Narrow down your search to find downtime events caused by Press set-up.

Approach
Use the Event Frame Search window to perform your searches. Make sure to add
the necessary search criteria.

Page 157
Building PI System Assets and Analytics with PI AF

7.2.4 Event Frame Reports in Excel with PI Datalink

Explore versus Compare Events functions

You can use PI Datalink (2014 or later) to import event frames from AF into Excel
and then create reports for viewing and analyzing those events. Pivot tables and
pivot charts are great Excel features for summarizing the data and getting better
insight into event frames
Under the PI Datalink ribbon in Excel you will find two functions (buttons) to import
event frame data into Excel: The Explore Events function and the Compare Events
function.
The Explore Events function returns one event per row, which is useful to analyze
events sharing the same EF template.

Here: maximum temperature of event frame named Batch 1222 has been highlighted
above in yellow (89.56).

In case an event frame has child events, it is possible to also list child elements in
further lines below the parent event. In the example below, there are nine child event
frames (Material Add 1, Agitate, ,…):

Page 158
 Tracking Important Events

Here: the maximum temperature of child event frames Material Add 1 and Agitate
have been highlighted in green (12.45 and 13.08).

The second function, Compare Events, allows you to compare hierarchical events,
in other words, events with child events. The compare events function shows
attributes from both the parent event and the child event(s). In the following example
maximum temperature for the complete production batch as well as for the first child
event frames Material Add 1 and Agitate is returned:

Page 159
Building PI System Assets and Analytics with PI AF

7.2.5 Directed Activity - Creating Event Frame Reports with PI Datalink

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.
Your instructor will have directions.

Activity Objectives
• Learn how to import event frame data into excel.

Problem
Management wants to answer the following questions about the downtime events:
• What is the most offending cause of downtimes?
• How much production are we losing because of downtime events?
The best way to find an answer to these questions is by creating an Excel report
which imports the event frames into an Excel spreadsheet. Excel offers some useful
business intelligence tools that will help us aggregate the data so management can
make decisions.

Approach
We will be using PI Datalink to import the event frame information and then use
Excel PowerPivot and PowerChart to analyze the downtime events.

Building the DownTime Analysis Report

For this exercise, you will be using a template: Press DownTime Analysis.xlsx,
located in the class\exercises folder. The template contains two sheets; we will be
importing the event frames data into the Raw Data sheet, which will be read from the
Report sheet via a pivot table and a pivot chart.
Since we want to analyze the downtime events which are all based on
the same EF template, we will be taking advantage of the Explore
function in PI Datalink. Go to the Raw Data sheet, set the cursor into
cell A2 and click on the Explore function in the PI Datalink ribbon

Page 160
 Tracking Important Events

Configuring the Explore Events Function

The Explore Events pane will show up.

This pane offers several fields for you
to refine your event frames search.
Moreover, it features a results preview
section.
For the Search start and Search end
fields point to the corresponding cells
on the Report sheet (see figure).
Keep * for event name and element
name.

Note: It is expected you will not get

Event Frames that are not yet finished.
To exclude Event Frames that are not
finished, click on More Search Options
and select entirely in range under the
search mode.

Select the seven columns to display; you can as well set the column order. The
columns are actually the event frame attributes. The following columns are needed
for the analysis:

Make sure you selected Event Duration attribute (gives you the number of seconds),
and not Duration (would give you the time in a format hh:mm:ss, such as e.g.
0:06:30).
Hit OK to display all event frame information in the Raw Data sheet.

Page 161
Building PI System Assets and Analytics with PI AF

Just by looking at this spreadsheet, it is very difficult to identify the most offending
downtime cause or the production lost. By using an Excel tool, Pivot tables, we will
be able to automatically extract, organize, and summarize the event frame data.
PivotTables, and their graphical companions, Pivot Charts, are very versatile and
easy to create. No formulas needed!

Page 162
 Tracking Important Events

7.2.6 Directed Activity – Using Pivot Charts to summarize Event Frames (optional)

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.
Your instructor will have directions.

Activity Objectives
• Use Excel Pivot Chart functionalities to summarize event frame information.

Creating a PivotChart and a PivotTable

Go to the Report sheet, select the Insert ribbon and select the PivotCharts option to
create a PivotTable and a PivotChart.

As input for the PivotTable select the cell range in

the Raw Data sheet where the ExploreEvents
function has returned the data (including the
header line).
Then choose to place the PivotTable and
PivotChart in the Report sheet.
Tip: if you want to correct the source area later in
time, select all cells of your PivotTable (or choose
the Analyse ribbon), then from the Analyse
Ribbon, select Change Data Source.

Page 163
Building PI System Assets and Analytics with PI AF

The PivotChart field list should now be shown in your Excel worksheet and a range
of the worksheet should be designated where the pivot table will be located, as
shown below.

Select the PivotTable, and review the PivotTable Field list. These fields come from
the column names of the Raw Data sheet.
To perform a downtime analysis for our Event Frames based on the corresponding
reason code, select the Reason Code line and drag into the Values area. The
applied Aggregation for the reason codes is COUNT, because these are non-
numeric values. Select the Reason Code line again and drag into the Rows area:

Page 164
 Tracking Important Events

Select the Production Loss line and drag into the Values area. The aggregation
applied for these numeric values is SUM. Your PIVOT table is extended by another
row, which summarizes corresponding production losses, based on the reason
codes:

Tip1: if the PivotTable Fields pane was closed and you want to have it available again, select a
cell of your PivotTable. From the right-mouse button menu, select Show Field List.

Tip2: to change the aggregation that is applied to your data, select the dropdown icon on the
field, and choose Value Field Settings… to select another aggregation type.

Let us enhance our Pivot table for analysis depending on individual press
selections.
Which column of our data represents a press ?

Select a cell in the Pivot table, and select the Analyze ribbon from the Pivot
Table tools. Click on insert slicer, select primary element and click on OK.

Page 165
Building PI System Assets and Analytics with PI AF

The slicer for the primary element is added. It allows selecting any combination of
one or more presses for our analysis. Check various combinations (use Shift- and
Ctrl-key for selections in the slicer):
• all presses
• PHI. Press01 only
• all “Number 01”- presses (i.e. HOU.Press.01, MTL.Press.01 and PHI.
Press01)
• all presses in Houston

The PivotTable and the PivotChart will update to show you what reason code is
causing most of the downtime events. In the screenshot above, it is clear that during
the observed period of time, planned maintenance has caused most of the
production losses for the Houston Presses.

Page 166
 Tracking Important Events

7.3 Tracking Critical Tank Level Periods

The limit traits, which we have defined for the level in the tanks at Velocity Terminals
represent the following critical operation conditions:

Limit Trait Value Condition

Low If a tank becomes almost empty, the coating inside can

LoLo 15%
Limit corrode and the coating needs a repair treatment.

High If the tank is almost full, there is a risk that the material
HiHi 90%
Limit spills and causes environmental damage, which is critical.

The process control team at Velocity Terminals is concerned about such situations
and are asking to monitor the process data to have a list with those periods of time,
when the one or other condition applies.

7.3.1 Directed Activity – Monitoring Tank Levels

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.
Your instructor will have directions.

Activity Objectives
• Build an analysis to monitor the tank levels and create event frames
whenever the level is outside the limits (too low or too high)

Problem Description
We will monitor whether the levels of the tanks at Velocity Terminals are outside the
target operational limits (either too low or too high).
The event frame names should allow an easy identification which tank was
concerned and when the problem has started. For every period it should be possible
to identify whether the low or the high limit was violated and what the pressure has
been when the violation occurred.

Approach
We will create an analysis under the Tank Element Template to create event-frames,
whenever level is outside the limits.

Page 167
Building PI System Assets and Analytics with PI AF

Event Frame Template

1. Open Velocity Terminals database in PSE, select Library in the Navigator and
select New Template under Event Frame Templates.
2. For the name enter Tank Level Excursion
3. For the description enter Tank Level Outside Operational Targets
4. For the naming pattern enter

%TEMPLATE% for %ELEMENT% (%STARTTIME:yyyy-MM-dd HH:mm%)

Once an event frame is created, what will the event frame names look like?

____________________________________________________________

5. We will use the event frames later on in context with Notifications, therefore
check the option for Can Be Acknowledged
6. Click on OK.

Page 168
 Tracking Important Events

Event Frame Attribute Templates

7. Select Attributes Templates tab. Select New Attribute Template.
8. Add attributes for Level, Pressure, Product and Level Excursion

Attribute UOM Data Value Settings… DisplayDigits

Name Reference Type

Level percent PI Point Double .\Elements[.]|%Attribute%; 2

TimeRangeMethod=StartTime

Pressure PSI PI Point Double .\Elements[.]|%Attribute%; 2

TimeRangeMethod=StartTime

Product <none> String String .\Elements[.]|%Attribute%; NA

Builder

Level <none> <none> String NA

Excursion

Tip1: Once you have entered the Level attribute you can use the Copy and Paste function to
create another PI Point attribute which you can use to edit to create the one for Presssure

Tip2: You can enter the setting for the Product attribute manually. Alternatively, select an
attribute value from the menu and edit accordingly. Make sure the setting matches exactly to the
above information.

The Level Excursion attribute will be used to indicate, whether either the
high or the low limit was violated. Setting the value for this attribute will be
defined later on when configuring the analysis for the corresponding event
frames generation.
9. Check In.

Page 169
Building PI System Assets and Analytics with PI AF

Analysis for Event Frame Generation when limits are violated

10. Select Tank from Element Templates
11. Select Analysis Templates tab and click on the blue link to Create a New
Analysis Template.
12. For the name enter Limit Monitoring
13. Select analysis type Event Frame Generation
14. For the example element select one of the tanks (e.g. Tank01).
15. For the Event Frame template, select Tank Level Excursion:

16. Rename Start Trigger 1 to Too High. Enter expression:

'Level'>'Level|HiHi'

Set severity to Critical.

17. Add a new Start Trigger, set the name to Too Low. Enter expression:
'Level'<'Level|LoLo'

Set severity to Major.

18. Whenever the level changes, we want to check whether any of the limit was
violated. Therefore set Event-Triggered for Scheduling.

Note: The scheduling defines how often the triggers will be evaluated. If this option is Event-
Triggered the triggers will be evaluated whenever there is a change for the attributes in the
Trigger Expressions. This is usually how Analytics are executed if attributes are PI Point data
references. Use Periodic in case the attribute is of another data reference (e.g. Table Lookup).

Page 170
 Tracking Important Events

19. Click on Advanced Event Frame Settings...Check Save Start Trigger name to
event frame attribute. Click on Map Attribute and select Level Excursion
attribute. Click on OK.

Note: Ignore the Warning

“The selected attribute template will be converted to a Configuration Item and any
existing configuration of the attribute template will be lost.”

20. Check In.

Page 171
Building PI System Assets and Analytics with PI AF

Simulate the level is above the limit

Note: The simulation for the level of Tank01 cycles the value every 10 minute with a violation of
the low and high limit. You can either wait some time, so that the required value change occurs
automatically, or you can force it with a manual entry. Note that a manual entry may be replaced
by a new value from the interface too early to start the event frame

21. Select Elements – Velocity Terminals - Locations - Montreal - Tank01

22. Select Level Attribute – Settings
23. Uncheck Read-Only.
24. Select Product Attribute and change to HC1500 (we need that for later).
25. Check In.
26. Enter 98 into the Value for the Level attribute

Verify generation of event frames when limits are violated

27. Select Elements in Navigator Panel, navigate to Tank01 and select the
element.
28. Click on the blue Event Frames link on the General tab.

Tip: You should have an event frame for Tank01. If there is no event frame, the reason might
be, that the tank was actually already outside the limits. Re-enter a value.

Page 172
 Tracking Important Events

29. Click on the Wheel icon in the header line of the results.
Click on Select Attributes. Click on icon to add all four (4) attributes from
the Tank Level Excursion event frame template. Click on OK. The list will be
extended by the four selected attributes. Click on OK.

Page 173
Building PI System Assets and Analytics with PI AF

8. Using Event Frames to capture Production Batches

A typical application of the PI System is in plants that run batch productions. Event
frames in Asset Framework can be used to capture and document the batch
production. To familiarize with a batch environment, such a production is simulated
for a fictitious company called Wonderland Chemicals. This includes the simulation
of values received from a batch execution system (BES) as well as corresponding
sensor data of the production equipment.
An Event Frame Generator Interface is monitoring the simulated batch data and is
automatically creating corresponding event frames.

Note: Capturing batch production in event frames in Asset Framework is the current
recommended methodology. It is successor technology for capturing the batch information in
the PI Batch Database (BDB). Accordingly, the Event Frame Generator Interface is the
corresponding successor for the PI Batch Generator Interface (PIBaGen) that was used before.

8.1 Case Study: Wonderland Chemicals

Prior to exploring event frames with multiple levels let us familiarize ourselves with
the batch production process, which is simulated in the TCE environment.

8.1.1 Directed Activity – Batch production process at Wonderland Chemicals

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.
Your instructor will have directions.

Activity Objectives
• Understand the simulation of the batch production process at Wonderland
Chemicals (WLC).

Page 174
 Using Event Frames to capture Production Batches

From the PI Vision overview page, open the Wonderland Chemicals display.

The production at Wonderland Chemicals consists of two production lines (L1 and
L2), which have the same structure. Material from a raw material container is
supplied into the Mixer 1 and then into Mixer 2, where it is mixed two times. Then the
material is supplied into the Heater for a final treatment. The heater has two heating
coil elements, which are turned on in sequence.
The complete process cycle in a production line, which covers the mixing (2x) as well
as the heating, is the overall batch, the activities in the mixer units and in the heater
unit are unit batches. Every batch and every unit batch is associated with an ID, e.g.
ID for the execution from yesterday is B1234, ID for the execution today is B1235,
etc.
The unit batch in the heater unit consists of three phases, depending on the heating
coil operation.

Mixer1, Mixer2 and the Heater are units, where the unit batches are performed.

Page 175
Building PI System Assets and Analytics with PI AF

Every mixer has several sensors, that measure temperature, pH value and rotation
speed of the mixer.
Attributes of the first Mixer in Line 1 (L1 Mixer 1):

The units (Mixer1, Mixer2 and Heater) have associated tags, which have information
whether a unit batch is currently active or not and what the unit batch ID is. An Event
Frames Generator Interface is monitoring these tags and creates corresponding
event frames. The following is an example of event frames that were created by that
interface. The event frames have multiple levels: top level is the batch, level below is
the unit batch, and the lowest level is the heater phase (Heating unit only):

To search for the tags of the first mixer, from the PSE menu, select Search – Tag
Search…and search for the tags where name starts with L1Mixer1:

Note: The values for all these tags are simulated to mimic the batch production.

Page 176
 Using Event Frames to capture Production Batches

8.2 Batch Production and ISA S88 standard

In a plant where production is performed in batches (repetitive cycles), event frames
can be used to capture the production batches in AF Event Frames.
A batch process could be seen in a pharma company where batches of a particular
medicine are produced in a reactor. Every batch consists of several steps such as
e.g.: filling components into a reactor, mixing the components, heating up to initiate a
chemical process, emptying the resultant liquid from the reactor and finally bottling.
There is a defined process of steps (called the “recipe”) that happens repeatedly
through time.

Let us assume every step takes 10 minutes and the batch is executed every full
hour. Then the schedule will look like following:
Start Time End Time
REACTOR BATCH 1234 06:00 06:50
Filling 06:00 06:10
Mixing 06:10 06:20
Heating 06:20 06:30
Xfer Out 06:30 06:40
Bottling 06:40 06:50

REACTOR BATCH 1235 07:00 07:50

Filling 07:00 07:10
Mixing 07:10 07:20
Heating 07:20 07:30
etc.

Page 177
Building PI System Assets and Analytics with PI AF

ISA (International Society of Automation) has published the ISA-S88.01 standard

under the name “Batch Control : Models and Terminology” to provide an industry
standard for naming or referring to stages in batch processes. Its original version
was adopted by the IEC in 1997 as IEC 61512-1. The standard provides better
communication between vendors and buyers of process control systems.
The S88 Procedural Control Model describes how the batch process should be
carried out. In the model you will find that the procedure has three subordinates, unit
procedures, operations and phases. The procedure describes all the equipment-
oriented actions which in an ordered sequence will carry out the batch.

The following table shows, how these levels can be captured in different levels of
event frames:

ISA 88 PI Event Frame Level PIEFGen Event Frame Templates

Procedure 1 Procedure
Unit Procedure 2 UnitProcedure
Operation 3 Operation
Phase 4 Phase
5 PhaseState
6 PhaseStep

Page 178
 Using Event Frames to capture Production Batches

8.3 Event Frames in PI Vision

PI Vision discovers events related to assets on the display and it lists them in a
dedicated Events tab. The time range and duration of the display determine for which
period of time the events are listed. In case any event frames exist in that period, the
icon for the event frames has a little blue dot on the top left edge. Click on the event
frame icon to switch to the event frame list:

The contents of the event frame list can be adjusted by selecting Edit Search
Criteria. By default all event frames for assets on the display are listed where the
start and/or the stop time is inside the display time range.

Page 179
Building PI System Assets and Analytics with PI AF

If you select one of the event frames and click the right mouse button, you have
three options:

Apply Time Range:

Applies time range of the
selected event to all symbols
on the display.

Event Details:
Opens a dedicated screen to
analyze, acknowledge and
annotate events

Compare Similar Events

By Name / By Type:
Opens another Browser tab to
compare process data across
multiple events on a single
“overlay” trend.

By Name When comparing events by name, the Event Comparison screen

displays up to 11 events with the same name, Event Frame
template, and referenced asset.

By Type When comparing events by type, the Event Comparison screen

displays up to 11 events based on the same Event Frame
template and same referenced asset.

When you change the time range for your display, the events list will be refreshed
automatically. Uncheck button for Automatically refresh the list to avoid searches
whenever you make a change for the time range of the display.

Page 180
 Using Event Frames to capture Production Batches

8.3.1 Directed Activity – Visualizing Events Using PI Vision

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.
Your instructor will have directions.

Activity Objectives
• Explore the batch events for the units in production line 1 (L1 Mixer 1, L1
Mixer 2 and L1 Heater 1)
• Switch the display time range to cover the time period of a selected event
frame.
• Explore the details of a selected event frame and display all attribute values
and a trend of the PI Point attributes.

Step-by-Step Procedure
1. From the PI Vision overview page, open the Wonderland Chemicals display.
2. Click on the event frames icon at the left to get a list with event frames.

3. Event frames for unit batches of three (3) units are listed:
a. L1 Mixer 1
b. L1 Mixer 2
c. L1 Heater 1, the unit batch event frames have child event frames for
the phases of the heating process

Note: to narrow down the search results click on Edit Search Criteria (e.g. set
Asset name= L1 Mixer 1, note there is a space in front and after Mixer!). Make
sure the option Automatically refresh the list is enabled.

4. Select an event from Mixer 1 and select Apply Time Range from the right
mouse button menu. Result: the display time range is set to the time range of
the event:

Click on the Revert button to revert the display time period. Select
another event and repeat the step.

Page 181
Building PI System Assets and Analytics with PI AF

5. Select one of the events and select Event Details from the right mouse button
menu.
6. Explore related attributes for the L1 Mixer 1. Get maximum for the mixer
speed.

Note: click on a trend icon in front of an attribute below to enable/disable the line
in the trend above.

7. Click on the Back control to return to the Wonderland Chemicals display.

Page 182
 Using Event Frames to capture Production Batches

8.3.2 Directed Activity - Comparing Similar Events Using PI Vision

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.
Your instructor will have directions.

Activity Objectives
• Compare the event frame PI Point attributes of several trends in one common
trend chart (“Overlay trend”)

Step-by-Step Procedure
1. To display only unit batches from the Heater unit click on Edit Search Criteria
and change from Assets on Display to the specific name L1 Heater and click
on Apply. Option Automatically refresh the list must be enabled!
2. Select Compare Similar Events By Type from the right mouse button menu.
The Event Comparison display is shown. Every line in the trend corresponds
to one particular event frame. Process data for the unit batch executions can
be compared between multiple executions of the batch.

3. Select an event frame (either in list on top left or in Gantt chart on bottom
right) to highlight it. Select an event frame and select Hide Event from the
right mouse button menu to remove the trend line from the trend chart.
4. To display the event frame levels below, click on the plus sign in the event
frame Gantt Chart on the right bottom side.
5. (optional) Save the display.

Page 183
Building PI System Assets and Analytics with PI AF

9. Taking Full Advantage of AF Functionalities

9.1 AF Object Security

Beginning with AF version 2.7, a security model similar to Data Archive security was
implemented. This model relies on Windows integrated security for authentication,
but provides its own authorization to AF objects using AF Identities and Mappings.

In AF version 2.6 and before, permissions in AF were set based on Windows user and groups.

9.1.1 AF Identities and Mappings

An AF identity represents a set of access permissions on the AF server.

Each AF mapping points from a Windows user or group to an AF identity.
Built-In AF Identities are Administrators, Engineers and World
According to the specific security requirements, AF identities are created on the AF
Server, and the permissions for the AF server resources (such as an element
collection or objects) are granted for these AF Identities.

With AF Mappings, Windows users and groups are mapped to the AF Identities:

Note: It is preferable to define the AF Mappings for Active Directory (AD) groups instead of
individual windows users. Since it is inefficient to maintain individual user accounts directly, it is
recommended that the mapping on a user basis be the exception.

Members of the Windows groups that are mapped to an AF identity are automatically
granted the access permissions for that AF identity.
For example, the Active Directory (AD) group Engineering Team is mapped to
Engineers, so all the members in that AD group have read/write permission for the
Elements collection.

Page 184
 Taking Full Advantage of AF Functionalities

In case of multiple identities user is granted permissions based on all AF Identities to

which he or she is mapped. In example below, Bob has all permissions from PI AF
Identity 1 and PI AF Identity 2.

Built-in AF Identities:

AF Identity Description

Administrators By default, this identity has all access permissions to every collection and
object on the AF server, including all databases. It cannot be modified or
deleted.
It is recommended that access to this identity is restricted to only a few
users.

Engineers This identity has the same privileges as Administrators, with the
exception of the Admin (a) permission. This identity is also not allowed to
delete AF databases.
It is recommended that this identity be restricted to those users who are
defining the asset database. Additional identities should be created to
narrow the scope of access within AF.

World This identity has read access permissions to every collection and object
on the AF server. More information see below.

Page 185
Building PI System Assets and Analytics with PI AF

World Identity:
By default, World identity is mapped to the Windows Everyone users group:

By default, World Identity has Read permissions on all items. World identity cannot
be modified or deleted. However, Mappings for World can be removed and
Permissions for World can be removed.

9.1.2 AF access rights

Access permissions can be granted for all AF Objects. Examples:

Page 186
 Taking Full Advantage of AF Functionalities

The following table describes the access permissions you can assign to AF identities
for all objects in the AF hierarchy.

Access right Abbreviation Definition

Read r Enables a user to view the object.
w Enables a user to create and modify an object. The
exception is that event frames and transfers also
require Write Data permission on the element template
from which they are created.
Write
Additionally, if users do not have Write permission on
the AF database, they cannot modify any object within
the database, regardless of the specific permission on
that object.
Enables a user to read and write to the associated
Read/Write
object.
rd Enables a user to read element’s attribute values (non-
Read Data
configuration items).
wd Enables a user to modify element’s attribute values
(non-configuration items). Additionally, this permission
Write Data
controls whether a user can create or modify event
frames.
s Enables a user to subscribe and unsubscribe to a
Subscribe
notification.
so Enables a user to subscribe and unsubscribe other
SubscribeOthers
users to a notification.
Delete d Enables a user to delete an object.
x Enables a user to perform most actions on an analysis
case.
Only used in Pimsoft SigmafineTM data reconciliations.
Execute
The PI Analysis Service does not use this permission.
The Write permission is required to modify, run, and
stop asset analyses.
a Enables a user to modify the security settings, or
owner, of an object. Also allows to force an Undo
Admin
Check Out on an object that is checked out to another
user, as well as to lock and unlock an event frame..

Setting permissions can be done for individual 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 187
Building PI System Assets and Analytics with PI AF

9.1.3 AF Security Hierarchy

The following chart shows the structure of the AF objects in a AF Server. Each
securable AF object (element, event frame, and notification, and so on) throughout
the hierarchy has an associated security descriptor that contains the access
permissions information for that object.
All AF objects of the same type belong to a collection. For example, every AF
element in a database belongs to the Elements collection for that database. Each
collection also has an associated security descriptor that contains access permission
information.

Page 188
 Taking Full Advantage of AF Functionalities

9.1.4 AF Server Security

Setting the security for a AF server

To open Security Configuration window for AF Server: On the toolbar, click the
Database button. In the Select Database window, click the Edit Security button.

Alternatively, click the AF Server Properties button to open the AF Server

Properties window, then click the blue Security link below the Aliases field. The
Security Configuration window displays the defined access rights and allows to
change them.

Page 189
Building PI System Assets and Analytics with PI AF

The Items to configure list for the AF Server contains the following items:
AF Server
Contacts Collection
Notification Contact Templates Collection
Identities Collection
Mappings Collection
Databases Collection (entire AF hierarchy)
Analyses Collection (entire AF hierarchy)
Analysis Templates Collection (entire AF hierarchy)
Categories (entire AF hierarchy)
Elements Collection (entire AF hierarchy)
Element Templates Collection (entire AF hierarchy)
…
The Security Configuration allows adding, removing or changing the permissions for
AF Identities.
• You can uncheck/check items to control the scope of the changes you are
going to apply.
• You can modify permissions for one of the AF identities that is listed, or add
or remove identities, as needed.
• The child permissions option defines the handling concerning permission
inheritance.

Setting the security for an AF database

To open Security Configuration window for
an AF database:
On the toolbar, click the Database button.
In the Select Database window, right-click
a database in the Databases list and
select Security.

Page 190
 Taking Full Advantage of AF Functionalities

In the Items to Configure list of the Security Configuration window, the selected
database and every collection is checked.

The Items to configure list for the AF Database contains the following items:
AF Database
Analyses Collection
Analysis Templates Collection
Categories
Elements Collection
Element Templates Collection
…
The Security Configuration allows adding, removing or changing the permissions for AF
Identities. You can uncheck/check items to control the scope of the changes you are going to
apply. You can modify permissions for one of the AF identities that is listed, or add or remove
identities, as needed. The child permissions option defines the handling concerning permission
inheritance.

Setting the security for an AF collection

You can configure access permissions to collections (Elements collection, Event Frame
collection, Templates collection...) at several points in the AF hierarchy. You can set them at the
server level or at the database level. If set at the server level, the permissions assigned to
identities on the server are also assigned to the same identities in every database.

Page 191
Building PI System Assets and Analytics with PI AF

AF Object Security
You can set specific access permissions for an identity that differ from the default settings
inherited from elsewhere in the AF hierarchy on any object (or object group) and collection in a
database.

Page 192
 Taking Full Advantage of AF Functionalities

Permissions inheritance
When you change the access permissions for an element, the following applies for
access permissions of child elements:

Reference Type Behavior

Composition Access permissions for child and parent are always the
same.

Weak Access permissions are never inherited.

Parent – Child When access permissions are set on a parent, the Child Permission
settings in the Security Configuration window depend on option
used

Option Description

Do not modify child Prevents access permissions that have been set for the
permissions current object or collection from being replicated to child
collections and objects in the AF hierarchy.
Default for AF server 2.5 and earlier
Update child permissions for For each selected item on the Items to Configure list in the
modified identities Security Configuration window, replicates the access
permissions for all child collections and objects for each
identity on the Identities list whose access permissions have
been modified.
Default for AF server 2.6 and later.
Replace child permissions for For each selected item on the Items to Configure list in the
all Security Configuration window, replaces all child permissions
identities for every identity on the Identities list with the parent access
permissions.
Hint: Before you apply this option, review access permission
settings for all items on the Items to Configure list to avoid
unintentionally overwriting custom permissions that may have
been applied elsewhere in the collection hierarchy!

Page 193
Building PI System Assets and Analytics with PI AF

UOM Database security

The AF Unit of Measure (UOM) database is shared across all AF databases. You cannot set
permissions for individual UOMs or UOM classes. Permissions can only be set for the entire
UOM database.
To open UOM Security Configuration window:
In the Navigator pane, select Unit of Measure.
On the toolbar, click the UOM Security button.

Security Tips

Administrator privileges at the server level, provides access to every object

regardless of their security settings.

If you want to edit an element, you need write permissions on the Elements
collection and on the particular element.

Library objects, such as templates, enumeration sets, UOMs and reference

types always have read permission regardless of their security settings

Deny settings override any granted allow permissions

Page 194
 Taking Full Advantage of AF Functionalities

9.1.5 Directed Activity - AF Objects Security

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. Your instructor will have directions.

Exercise Objectives
• Create AF Identity and use it for a mapping to a Windows user account.
• Assign Permissions for an AF database and for AF elements.

Problem Description
Sheila, the new intern ([email protected]) has been hired at Velocity
Terminals. To prevent unauthorized read access and unintended changes, the
engineering supervisor has to change the security for the AF database:
Because of confidentiality, only designated Windows users should be able to read
the data for Velocity Terminals. Beside Administrators and Engineers, just the intern
should be able to read the data.
Sheila should not be able to see tanks in Sydney or Tokyo. Of course, if the intern
browses to the Distribution or Receiving divisions he should only see the tanks
belonging to Montreal.
She will be doing some research on Tank01; hence, she should be able to edit this
tank’s data and configuration.

Note: In order to avoid negative impact on the Velocity Terminals production database, perform
the steps on the AF Startup AF database!

Approach

1. Click on the AF Server Properties button ( ) to open the AF Server

Properties window. Identities and Mappings tabs: Add a new Interns AF
Identity and map the student04 account to it.

2. Click on the Database button ( ), select Security for AF Startup

database:
• To remove the permissions for the World Identity:
Select World identity, then click on button.

• To add Read and Read Data permissions for the Interns Identity:
Click on button, select the Interns identity.
Uncheck Allow All, then enable Read and Read Data
Select Update child permissions-Option and click on button.

Page 195
Building PI System Assets and Analytics with PI AF

3. For the Tank01 element in Montreal…

• To add Read/Write and Read/Write Data permissions for the Interns
Identity:

Select Security… from Tank01 element.

Select the Interns identity.
Enable Read/Wríte and Read/Write Data
• Select Do not Modify Child Permission-Option, click on button.

1. For the Tokyo and the Sydney element…

• Remove all permissions for the Interns Identity:

Select Security… from Sydney element

Select the Interns identity.
Click on button
Select Update child permissions-Option and click on button.
(accordingly for Tokyo).

Verification
1. Maximize PI System Explorer (PSE).

2. Open a second PI System Explorer (PSE) instance for connection with the
intern’s account:

With Shift key pressed, right-click the System Explorer icon in the Windows
taskbar and select Run as a different user. Supply student04 credentials.
(optional, for improved distinction) If needed, resize the window and bring it in
front of the first PSE window.

3. On second PSE: click the Database button ( ). In Select database

window, click on the button next to the AF Server name.

4. The current connection is with pischool\student04. Note the effective identity

permissions for pischool\student04 are (Interns | World)

5. Click on OK. Select the AF Startup database and verify the permissions on
the tanks. Attempt to change descriptors for Tank01 and Tank02.

Page 196
 Taking Full Advantage of AF Functionalities

9.2 Attribute Properties

When attributes are created, there are four associated properties (configuration item,
excluded, hidden, indexed). You have the option to set those properties for each
element attribute. In case of an element derived from a template, the properties of
the attributes cannot be changed any more except for the Exclude property:

Configuration Item You assign the Configuration Item property to an attribute with a
constant value that represents inherent properties of an asset (e.g.
a device serial number). In PI System Explorer, configuration
attributes are marked with a pencil icon ( ).
When you change the attribute value of a configuration item PI
System Explorer automatically checks out the attribute. To commit
the change you need to .

Indexed Indexed attributes are attributes that are optimized for fast search
results and fast value retrieval. You can only index attributes
whose values are stored in the AF database. This means that you
cannot index attributes that get their values from PI point data
references or from linked table references.

Excluded In situations where not all attributes in an element template apply,

(new in AF Server attributes that are not applicable can be excluded.
2015) Example: only some of the tanks have a second container
coating. Set the attribute for the material of the second coating to
Excluded property for the tanks with a single coating.

Hidden The Hidden property is useful if an attribute is being used to hold

(new in AF Server an intermediate result, such as a table lookup result that can then
2015) be retrieved by a PI point data reference, or is being used solely to
populate a tag name in a substitution parameter.

Page 197
Building PI System Assets and Analytics with PI AF

9.2.1 Directed Activity - Use of attribute properties

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.
Your instructor will have directions.

Activity Objectives
• Assign properties for attributes for specific use cases.

Problem Description
The Capacity attribute for a tank is considered as a constant that represent an
inherent property for the tanks at Velocity Terminals. The value will always be the
same except for a change of the equipment itself. Capacity changes should require a
Check-Out and Check-In sequence in AF.
Only the first tank in every location of Velocity Terminals (Montreal, Sydney, Tokyo)
has a dedicated night shift operator. Add attributes with the operator names, which
should only exist for tanks Tank01, Tank05 and Tank08.
The tag name convention for process values at Velocity Terminals is the abbreviation
“.PV” at the end of the tag name. The abbreviation should be defined in an AF
attribute, but the attribute should not appear in PI Visualization Tools or in PI System
Explorer Searches.

Page 198
 Taking Full Advantage of AF Functionalities

Approach
Open the Velocity Terminals database in AF and navigate to the Tank template in
the Library. (Do not use the AF Startup database any more.)

Select the Capacity

attribute and
enable the
Configuration Item
property

Add a Night Shift

Operator attribute
with Value Type
String and Default
Value Bob.

Add a PVCode
attribute with Value
Type String, enable
the Hidden property
and enter the Default
Value PV.

Check-In the new attributes.

Switch to elements and select Tank01. Change the Capacity from 20,000 to 22,000.
Notice, that the Tank01 element has been checked out. It is marked accordingly in
the Asset tree . If you select the element PI System Explorer status line
displays details of the checked out element:

Click on Undo Checkout button in the toolbar to revert to the initial setting.

Page 199
Building PI System Assets and Analytics with PI AF

Notice that the PVCode attribute is marked as hidden . Perform an attribute

search (search > Attribute Search) for all attributes in Montreal that start with P*.
PVCode is not returned.
Perform an attribute search for the Night Shift Operator attributes under Locations.
Select the lines for tanks without a Night Shift Operator (Tank02, Tank03, Tank04,
Tank06, Tank07, Tank09, Tank10):

Select Properties and set Excluded. Click on OK. The change applies to all the
selected attributes. Change the names for the first tanks in Tokyo (Akane) and
Sydney (Alex):

Click on Check-In. Then click on Refresh. Now the search returns only the non-
excluded attributes for Tank01, Tank05 and Tank08.
Select the tank elements individually and observe what is displayed for the Night
Shift Operator.
Under Tools > Options select the General tab and uncheck the Show Excluded
Attributes option. Click OK. Select the tanks individually again and observe what is
displayed now for the Night Shift Operator.

Page 200
 Taking Full Advantage of AF Functionalities

9.3 Substitution Parameters

9.3.1 Substitution Parameters in an Attribute Template

Substitution parameters are variables that you place in attribute templates for PI
point data references. AF resolves a substitution parameter when elements are
created. As an example, the substitution parameter %Element% would resolve to the
attribute’s element name.
For example, in a truck template, the tag for the speed attribute is configured as
%Element%.%Attribute%.PV. Once Truck1 is created from this template, AF would
try to find a tag named Truck1.Speed.PV.

The default setting for a PI Point Data Reference attribute template:

\\%Server%\%Element%.%Attribute%.

Note: the Pressure attribute in the tank template has this default setting.

Substitution parameters can also be applied in Table Lookup and String Builder Data
References.

Page 201
Building PI System Assets and Analytics with PI AF

9.3.2 Substitution Parameters

AF supports numerous substitution parameters. The following table lists the ones
most commonly used, for a comprehensive list see Appendix A.

Parameter Name Substitution

%Attribute% Name of the attribute that holds this data reference.

%Description% Description of the attribute that holds this data reference.

Name of the element in which the attribute resides. For

%Element% event frames, this refers to the name of the primary-
referenced element.

Name of the parent element of the element in which the

%..\Element% attribute resides. To retrieve further ancestors, use the ..\
notation, such as %..\..\Element%.

Name of the default Data Archive for the computer on which

you create the attribute. The default Data Archive for the
computer on which PSE is running.
%Server% Note: The %Server% parameter does not resolve to the
computer on which the AF database resides. The
%Server% parameter can resolve to a different Data
Archive depending on the default in AF Client.

The following table lists the substitution parameters that are useful for event frames
naming patterns.

Parameter Name Substitution

%EventFrame% Name of the event frame in which the attribute resides.

Name of the parent event frame of the event frame in which

%..\EventFrame% the attribute resides. To retrieve further ancestors, use the
..\ notation such as %..\..\EventFrame%.

%StartTime%,
Local start or end time, if obtainable from the time context.
%EndTime%

%UtcStartTime%, Coordinated universal (UTC) start or end time if it can be

%UtcEndTime% obtained from the time context.

Page 202
 Taking Full Advantage of AF Functionalities

A substitution parameters can not only resolve to the name of a AF object (like
%Attribute% for an attribute), but also to the value of an attribute. ‘@’ is used for that.

Symbol Description Examples

Attribute value at same level as

References the value of the object attribute: %@Attribute%
@
instead of its name. Attribute value at parent attribute
level %@..|Attribute%

For more information refer to the Appendix A in this document and

to the Guide to Substitution Syntax in AF-EF Data References.
The Guide can be obtained from PI Square at
https://pisquare.osisoft.com/thread/11188.

Page 203
Building PI System Assets and Analytics with PI AF

9.3.3 Directed Activity – Child attribute with the tag name definition

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.
Your instructor will have directions.

Objectives
• Configure a child attribute for a PI Point attribute that contains the tag name.
• Change the child attribute with the tag name to define an individual tag name
when no standard naming rule applies.

Problem Description
The pressure sensors in Sydney have been replaced and the sensors got new tag
names. The Pressure attribute should be modified to allow that individual tag names
can be maintained instead of a standard naming pattern.
The tags for the pressure sensors have the following tag names:

Tank Name Location PI Point Name

Tank01 Montreal Tank01.Pressure
Tank02 Montreal Tank02.Pressure
Tank03 Montreal Tank03.Pressure
Tank04 Montreal Tank04.Pressure
Tank05 Tokyo Tank05.Pressure
Tank06 Tokyo Tank06.Pressure
Tank07 Tokyo Tank07.Pressure
Tank08 Sydney Sydney.Tank08.Pressure.PV
Tank09 Sydney Sydney.Tank09.Pressure.PV
Tank10 Sydney Sydney.Tank10.Pressure

Approach
The request can be addressed by adding a child attribute that contains the tag name:

Page 204
 Taking Full Advantage of AF Functionalities

Step-by-Step Procedure
1. In the Tank element template, select the line with the Pressure attribute and
from the context menu, select New Child Attribute Template.
2. For the child attribute, set the name to tagname and select value type: String.
3. Select the Pressure attribute, click on Settings…, and change the Change
the tag name for the Pressure attribute to %@.|tagname%

4. Check In.
5. We will use PI Builder to define the values for the tagname child-attributes of
the Pressure attributes. Open Excel to access PI Builder. Make sure the
correct AF Server and database is selected under PI Builder Connections.
Select Elements -> Find Elements to get all elements based on the Tank
element template. Click on OK.

Page 205
Building PI System Assets and Analytics with PI AF

6. For the column selection, reset first by clicking Clear All, then enable
Pressure|tagname under Attribute columns - From Template ‘Tank’. Click on
OK. Result: the requested information is returned in the Excel spreadsheet,
the column for |Pressure|tagname is empty.

7. Enter the tag names into the cells of the |Pressure|tagname column

8. Click on Publish (with Edit Only-option).

9. Switch to PI System Explorer, click on Refresh and verify the Pressure
sensors are all set properly. Use the Attribute Search to find the attributes for
all the ten (10) tanks and confirm the PI Point Setting is correct.

Page 206
 Taking Full Advantage of AF Functionalities

9.4 More about Attribute Data Reference Types

In this chapter we will have a closer look on the following Data Reference (DR)
types:
• Table Lookup
• String Builder

9.4.1 Directed Activity – Table Lookup: Linking a Table from SQL 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. Your instructor will have
directions.

Exercise Objectives
• Link data from a SQL Server table with a table in AF.

You can use PI AF tables to access data that is external to the PI System. Such data
might be contained in Microsoft Excel, Access, or SQL Server, or other OLE DB/ODBC
data sources. You can either import the table or link to it after you have defined the
table structure.
PI AF tables with imported data are called imported tables. Imported tables are
read/write tables. They are limited in size but are more secure than linked tables.
Imported tables are sometimes called internal tables because, unlike linked tables, the
table data is managed in PI AF. After the initial import, there is no further relationship
between the foreign table and the PI AF table. You can edit the data directly in PI AF.
Linked tables are sometimes called external tables, because the source data is not
stored in the PI AF database. You cannot edit an external table from PI AF. Linked
tables require additional security configuration because you need to configure how PI
AF connects to the external data source.

Note: Microsoft does not support or recommend server side automation of office products.
Therefore avoid linking Excel tables to AF tables. For more refer to the KB

OSIsoft does not recommend using Excel files for linked tables
https://customers.osisoft.com/s/knowledgearticle?knowledgeArticleUrl=000034586

Page 207
Building PI System Assets and Analytics with PI AF

Problem Description
Velocity Terminals has facilities all around the world and maintains a list of site IDs in
an SQL Server table. The information should also be available in AF, the site ID
should be available as an attribute for every site that has tanks.:

Explore the table in SQL Server Management Studio

Let us have a look at the SiteTable table in the VelocityTerminals database in SQL
Server. To access a table in SQL Server, the SQL Server Management Studio
(SSMS) can be used.
1. Click on the SSMS icon in the Windows task bar. Click on Connect.

2. Expand the Explorer structure PISRV01 - Databases - VelocityTerminals -

dbo.SitesTable. Right click the table and Select Top 1000 Rows.
3. Locate the lines for Montreal, Sydney and Tokyo.
Site SiteID
Montreal 15
Sydney 23
Tokyo 44

Page 208
 Taking Full Advantage of AF Functionalities

AF Linked Table
1. Select the Library section in the Navigator Panel. Right-click Tables and
create a new table in AF, assign the name SitesTable.
2. Under Table Properties, select Link. In the dropdown for Connection, select
<Build>.
3. Use the Microsoft OLE DB Provider for SQL Server driver. Click Next >>.
4. Enter the Microsoft SQL Server instance name, PISRV01.
5. Use Windows NT Integrated security.
6. From the dropdown, select the VelocityTerminals Microsoft SQL Database.

7. Verify that when you click on Test Connection the test will succeed. Click on
OK.
8. For the query, enter SELECT * FROM SitesTable. Click on OK.

9. Click on the Table tab and verify the contents of the table. Check In.

Page 209
Building PI System Assets and Analytics with PI AF

Add SiteID attribute in Site element template

1. Under the Element section in the Navigator Panel, locate and select the
Montreal element.
2. Right click the element and select Convert to Template.
3. Under the Library section in the Navigator Panel, locate MontrealTemplate
and rename the template to Site.
4. Switch to Attributes Template tab. Add SiteID attribute, value type= Int16,
data reference= Table Lookup. Click on Settings.
5. Enter the table lookup criteria:
Table: SitesTable, result column: SiteID, query: Site = ‘%Element%’.
Click on OK.

6. Switch to Elements section in the Navigator Panel, locate and select the
Montreal element, verify the SiteID Attribute is 15. Check In.
7. Change element template for Sydney and Tokyo to Site, verify correct SiteID.
Check In.

Page 210
 Taking Full Advantage of AF Functionalities

9.4.2 Solo or Group Exercise – Use Substitution Parameters in a Template Attribute

This solo or group exercise 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 exercise..

Exercise Objectives
• Assemble substitution parameters to automatically map Data Archive tags to
AF attributes.

Problem Description
Velocity Terminals has a special naming convention for their temperature sensors.
Example for the temperature sensor in Tank01 located in Montreal (SiteID= 15):
15Tank01TS.PV
SiteIDEquipmentNameMeasurementType.DataType
Where
SiteID = ID for the location (ex.: Montreal is 15)
Equipment Name = Equipment name (ex.: TANK01)
MeasurementType = Measurement type (ex.: TS for temperature sensor)
Data Type = Type of data (ex.: PV for process value)

They want to use the substitution parameters to speed up the creation of additional
assets in AF. To demonstrate that this is feasible, you are asked to add a new
temperature attribute template to the Tank’s template so that it uses substitution
parameters to automatically find the correct PI tag.

Approach
1. Add a temperature attribute to the tank template. Use substitution parameters so that the
tag names are automatically built according to the tag naming convention mentioned above.
2. Validate the new configuration string by browsing the tanks.

Try to do this exercise on your own before referring to the solution on the
following page.

Page 211
Building PI System Assets and Analytics with PI AF

Step-By-Step Procedure
1. Add a Temperature attribute to the Tank template with following settings.

Page 212
 Taking Full Advantage of AF Functionalities

9.4.3 The String Builder Data Reference

The String Builder data reference allows you to use substitution parameters and
functions to manipulate values and output a string.
Below some cases where the String Builder data reference is useful:
✓ Concatenate strings (Element Name + Attribute Name + Value).
✓ Format dates and numbers.
✓ Build paths to elements and attributes.
✓ Parse comments from operators stored in PI tags.
✓ Display element information as an attribute.

Note: Since this data reference supports substitution parameters, when used in a template,
value substitutions takes place at run time.

String Builder allows you to manipulate strings located anywhere in your hierarchy by
using the Related Attribute Values contextual menu (see figure below).

Page 213
Building PI System Assets and Analytics with PI AF

9.4.4 Directed Activity - Using the String Builder Data Reference

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. Your instructor will have
directions.

Create a new attribute with information in a string like the following:

Tank01 is located in Montreal, level is at 99.8%

Approach
1. From the Navigator Panel, select the Library section. Open the Tank element
template.
2. Add the Tank Level Information attribute, value type= String, Data
Reference= String Builder.
3. Use the String Builder Data Reference dialog box to construct the string

Note 1: to display the level value in the requested format (one digit after the decimal
point), use the Format (real,format) function in String Builder. Format follows
Performance Equation (PE) style syntax, e.g.: "%3.1f". The number before the decimal
indicates the minimum total number of characters to output, pre-padding with blanks, the
number after the decimal indicates the number of digits to display after the decimal point.

Note 2: You can construct an expression on a single line, using semicolons to separate
its terms. But you can also place each term on its own line, which eliminates the
semicolons and makes the expression structure more apparent (see above).

4. Switch to one of the tank elements and verify the attribute string as desired. If
required, correct the String Builder definition.
5. Click on Check-In

Page 214
 Taking Full Advantage of AF Functionalities

9.5 Advanced Element Template Design

9.5.1 Template Inheritance and Base Template

A powerful feature of the element template is the ability to set a base template. Once
a base template is created, it can be used to create a number of derived templates.
When an element is created from a derived template, the element contains all
attributes from both the base template and the derived template.

• An element created from the Tank element template has three attributes:
Diameter, Height and Fill Level.

• An element created from the Mixing Tank element template has five
attributes: Diameter, Height, Fill Level, Mixer Speed and Mixer Blade Size

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.

Page 215
Building PI System Assets and Analytics with PI AF

To view the template inheritance tree from the PSE Library, simply organized the
templates by inheritance.

Page 216
 Taking Full Advantage of AF Functionalities

9.5.2 Directed Activity - Working with derived element templates

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.
Your instructor will have directions.

Activity Objectives
• Create a derived template for a special tank that has an additional sensor for
CO2 measurement
• Use a derived template to accommodate a different PI Point reference for the
Level attribute in a special tank.

Two modifications were done on Tank10, which means that the tank deviates from the normal
ones on the following details:

• There is an additional sensor for CO2 measurement. The tag name is:
Tank10CO2.PV

• The name for the Level sensor is different now. Instead of Tank10LI.PV the
name is
Tank10LEVEL.PV

This means the name does not follow the normal name pattern
%Element%LI.PV. Instead the name pattern has to be %Element%Level.PV
(or: %Element%%Attribute%.PV).

Approach
Create an element template for a Special Tank that has an additional sensor and a
different naming pattern for the Level attribute.

1. Open the Tank template in the Library of the Velocity Terminals database.
2. From the Tank template context menu and select New Derived Template

3. Rename the new element template to Special Tank.

Page 217
Building PI System Assets and Analytics with PI AF

Additional Attribute for CO2 (PI Point: Tank10CO2.PV)

4. On the Attributes Templates tab, add a new attribute template CO2:

Default UOM = percent (Ratio)

Value Type= Double
DisplayDigits=2
Data Reference = PI Point

5. Click on Settings… to enter the PI Point name. Use substitution

parameters to define a standard naming pattern based on the element
and the attribute name. Make use of the PVCode attribute string.
What do you write?

___________________________________________________

6. Change the Source Unit from <Default> (%) to %.

7. In the Navigator, switch to Elements. Select Tank10 and change the

template from Tank to Special Tank.

8. Verify the Tank10 has the CO2 attribute, the value is from PI Point
Tank10CO2.PV.

Attribute Override for Level (PI Point: Tank10LEVEL.PV)

9. On the Attributes Templates tab, add a new attribute template Level :

Default UOM = percent (Ratio)

Value Type= Double
DisplayDigits=2
Data Reference = PI Point

10. Click on Settings… to enter the PI Point name. Use substitution

parameters to define the different naming pattern based on the element
and the attribute name. Make use of the PVCode attribute string.

Page 218
 Taking Full Advantage of AF Functionalities

What do you write?

___________________________________________________

11. Change the Source Unit from <Default> (%) to %. Click OK.
12. To define the limits, select the Level attribute and click on Limits…in the
context menu. Set the limits in the same way as for the normal tank:

13. In the Navigator, switch to Elements. Select Tank10 and verify the PI
Point for the Level attribute of Tank10 is Tank10Level.PV
14. Check-In your changes.

Show element templates based on inheritance

15. Open the Element Templates in the Library of the Velocity Terminals.
From the context menu, select Arrange By > Arrange By Template
Inheritance. Result: Special Tank is shown below Tank.

Page 219
Building PI System Assets and Analytics with PI AF

10. Communicating Important Events

Notifications, which is a feature in Asset Framework, allows alerts to users in real

time about conditions in their system that need specific attention. Corresponding
actions can be taken to be pro-active or to resolve the problem of the current
situation. The information is either sent via email or is passed onto a Web Service.
The recipients for the notifications (“subscribers”) have the option to acknowledge
notifications. In case a situation, that requires action, is not acknowledged in time,
notifications can be sent out again.
Examples for the use of notifications are:
• Temperature is outside the normal range
• Equipment is shutdown
• Runtime counters have elapsed indicating a maintenance is required
• Amount of supply material is below a critical minimum level

Note: Notifications have been revised in the AF 2016 R2 version. In previous versions, there
was a different concept for the Notifications, which is now referred to as “Legacy Notifications”.
When upgrading the PI System to 2016 R2, existing legacy notifications can be migrated to the
new concept using a dedicated migration tool.

10.1 Introducing Notifications

With AF 2016 R2, notifications are triggered when new Event Frames are generated
in AF. Conditions for the trigger are defined in notification rules.
The event frames generation may be related to different sources. It can be
performed by asset analytics, by an Event Frame Generator (EFGen) interface, by a
custom AF SDK application or a manual creation.

Page 220
 Communicating Important Events

10.1.1 Notification Components

PI Notifications Service
The PI Notifications Service processes event frames defined in the Asset Framework
(AF) in real-time and sends out email and web service notifications. The service is
installed from the AF Server 2016 R2 Install Kit.

Notification Rule tab (PI System Explorer)

Notification Rules can be defined for individual elements or be created as a template.
The User Interface for configuring notification rules in PI System Explorer is in a
dedicated tab on elements and element templates:

Note: There is no entry for Notifications in the PI System Explorer Navigator (bottom left corner)
any more.

The definition includes the trigger criteria, adding subscribers to the notification rule,
and formatting the message to suit the needs of your organization.

Page 221
Building PI System Assets and Analytics with PI AF

Management Plug-In (PI System Explorer)

• Allows management of analyses and notification rules on the AF Server.

10.2 Delivering the Events

Notifications Delivery Channels provide for the mechanism by which alerts are
delivered to subscribers. With the standard installation of Notifications, the following
delivery channels are available:
• Email

Email delivery channel supports sending emails with notification alerts via an
SMTP Mail Server.

• Web Service

Web service channel supports providing information to a web service by

calling one of its methods.

Note: Legacy Notifications in earlier AF versions also supported OCS and Custom delivery
channels. These are not supported with the new Notifications in AF 2016 R2.

Page 222
 Communicating Important Events

10.2.1 Email Delivery Channel

The settings for the Email delivery channel allow you 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.:
[email protected]). In most cases, the Allow contacts to set sender email
should not be enabled.

Note: In the Training Cloud Environment (TCE) use [email protected].

Once the email delivery channel is setup, most email addresses should be provided
by Active Directory (AD). If the AD does not include all email addresses needed, it
will be possible to create additional emails within the Contacts section of PSE.

Page 223
Building PI System Assets and Analytics with PI AF

10.2.2 Directed Activity - Email Delivery Configuration and Checkout

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.
Your instructor will have directions.

Activity Objectives
• Understand the required settings for the email delivery.

Approach
1. From PSE, select Contacts in the Navigator and navigate to Tools > Delivery
Channel Plugins, then from the Email Delivery Channel Plug-In context menu
select the Settings.

2. In case of the Training Cloud Environment (TCE), the mail server is installed
on PISRV01.

Note: The mail server on PISRV01 is configured just for some user accounts in the pischool.int
domain.

Page 224
 Communicating Important Events

3. Click on the Test… button to send a test email to [email protected].

4. Start Microsoft Office Outlook and verify reception of the test email.

Note: If you start Outlook the first time, you will be prompted to enter the password for
student01, student02 and student03. Enter the password (enter same password for all the three
accounts), select the option to save the password and click on OK.

Page 225
Building PI System Assets and Analytics with PI AF

10.2.3 Web Service Delivery Channel

The web service delivery channel allows 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.

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.
Example: A custom Web Service could process the received information and
generate corresponding work orders in a customer Maintenance System:

Page 226
 Communicating Important Events

10.3 Configuring Notifications

Configuring a notification rule includes specifying the trigger criteria, adding
subscribers to the notification rule, and formatting the message to suit the needs of
your organization.
1. Select element or element template on which Notification Rule will be
created
2. Create a new Notification Rule:
a. Define the notification trigger conditions
b. Add the subscribers
c. Format the Notification message
3. Test the Notification

Note: If you have created a notification rule for an individual element, you can extend the scope
to the corresponding element template by using the Convert to Template function.

Page 227
Building PI System Assets and Analytics with PI AF

10.3.1 Trigger Conditions

The Notification Rules define the criteria that identify, which event frame generation
will initiate a new notification.
There are two possible trigger criteria modes for the Notification Rules:
• Analysis
• Event Frame Search

Use the Analysis mode to trigger a notification rule on event frames generated by a
particular analysis.

Use Event Frame Search mode to trigger a notification rule based on event frame
name, template and category. In the Event Frame Search mode, you can select a
configured event frame template, from the drop-down list, and then configure the
name and category for the event frames that will trigger your notifications. The name
may contain wildcard characters that are supported by event frame search.

For both the modes, you can add additional trigger criteria using event frame
attribute values. Criteria can be any specified for any attribute in the event frame
template that is specified in the notification rule trigger criteria. For example, if your
event frame template defines an event like "downtime" but you only want an email
about "unplanned" downtime, you can configure an attribute value condition where a
"reason code" attribute on the "downtime" event frame template has a value
indicating "unplanned" downtime.

Page 228
 Communicating Important Events

Note: Very often at work, the measure of success is made on how many things are produced.
For Notifications, the more alerts that are produced, very often the less successful the use of
Notifications becomes. If too many alerts are provided to a recipient, she/he probably won’t 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.

Page 229
Building PI System Assets and Analytics with PI AF

10.3.2 Directed Activity - Configuring a notification rule

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.
Your instructor will have directions.

Activity Objectives
• Create a notification rule (associate with the event frame analysis).
• Define notification trigger conditions.
• Add a subscriber who will receive the notification.
• Checkout email reception.

Problem Description
We are monitoring the tank levels at Velocity Terminals. The operational personnel
has asked to receive notification emails whenever tank levels are outside the target
operational levels (either too low or too high). But the notification is required only for
the tanks containing HC1500 because inappropriate quantities for that product is
causing issues.
The emails alerting about the limit violation should include the values of the level as
well as the value of the pressure, because this information is needed to assess the
condition of the liquid in the tank.

Page 230
 Communicating Important Events

Step-by-Step Procedure
1. Select Tank from Element Templates. Select Analysis Templates tab, select
the Limit Monitoring Analysis.
2. Click on the blue link to create a new notification rule template

3. On Notification Rule Templates tab change the name to

Critical Level Notification
4. In the Trigger section, select the blue View/Edit Trigger link.

5. Select the link to add attribute criteria

6. Add Product Equal HC1500. Click on OK.

7. In the Subscriptions section, select the blue View/Edit Subscriptions link.

8. Expand student01 so that the email occurs and drag it into the Subscriptions
section. Click OK. Check In.

9. Start Outlook for student01.

10. Change the value for the Level attribute of Tank01 to 99 and verify that you
receive an email.

Note: give the system some time to send out the email. It can even take up one to two
minutes before the email arrives.

Page 231
Building PI System Assets and Analytics with PI AF

10.3.3 Trigger Criteria Options

When the Trigger Criteria are defined, following options can be set:

Resend Interval
The time interval after which PI Notifications Service will send additional alerts until
the event frame matching the notification rule is acknowledged or closed.

Page 232
 Communicating Important Events

Non-Repetition Interval
The time interval during which PI Notifications Service will not send similar alerts
associated with the same notification rule.

Event Frame Can be acknowledged

Option to enable event frame to be acknowledged; the event frame template is also
modified accordingly. This option is automatically selected if the event frame
template has been configured for acknowledgement

Severity Option
This option applies only to event frame generation analyses. If you have configured
multiple start triggers for your analysis, you may choose to be notified in these ways:
• When the current trigger severity is higher than any trigger severity
encountered so far.
• When the current trigger severity is higher than the previous trigger severity.
• Every time a trigger condition is true, regardless of its relative severity to
other previous triggers.

Page 233
Building PI System Assets and Analytics with PI AF

10.4 Formatting the Information to Deliver

The Notifications software includes a complete formatting tool, which enables you to
define the formatting, and information that is included in email alerts.
Global Default Formats
The system provides one global format that is used as the default format. You can
edit or rename the global format, but cannot delete it. Additional formats can be
added. To access global default formats, navigate to Tools -> Global Formats .

Custom Delivery Formats

To edit or add specific Custom delivery formats for a particular Notification Rule,
select the blue Message Formats link. The formats can be distinguished by their
corresponding icons:

Page 234
 Communicating Important Events

10.4.1 Directed Activity - Message Formatting of a Default Notification Email

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.
Your instructor will have directions.

Activity Objectives
• Prepare a message-formatting template for email message delivery.

Approach
1. From PSE, navigate to Tools > Global Format.
2. Select the line with Global Default Email (color changes to light blue), and
click on the Duplicate icon above. Rename the new format as “Default
Email with Table”.

About Formatting Messages

The Formats window has 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 Global Formats section.
Specific content can be added when configuring the Message tab for a specific notification rule
or a notification rule template.

Page 235
Building PI System Assets and Analytics with PI AF

3. 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.
(See figure below)

To add a table, use the controls highlighted in the screenshot above. When
you add the Hyperlink, select the option to send the link as text:

We will be able to use the link and open a related display in PI Vision. When
sending an email to someone outside the organization with no access to PI
Vision use the option to send a screenshot.

Note: the mail server used in the Training Cloud Environment (TCE) for this class does
not support to include screenshots in the email!

4. To perform a test send click on the button.

For the Email address, enter [email protected]:

5. Click OK.

Page 236
 Communicating Important Events

10.4.2 Directed Activity - Message Formatting of a Tank Level Excursion Notification

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.
Your instructor will have directions.

Activity Objectives
• Compose notification messages from message format templates.

Approach
We want to define a particular format for the emails alerting about limit violations to
send to our recipients. The message format includes a table with the values of the
level and the pressure. The message should also provide a link into PI Vision
allowing an acknowledgement as well as a display for the time after the limit was
violated.
1. Select Tank from Library -> Element Templates, open the Notification Rule
Templates tab.

Tank Level Excursion – Email with Table

2. Click on the blue Manage Formats link in the Subscriptions section. Select
the line with Default Email with Table (color changes to light blue) and click
on the Duplicate icon above. Rename the duplicated format as Tank
Level Excursion - Email with Table.

Page 237
Building PI System Assets and Analytics with PI AF

3. Add the appropriate information to the table by dragging and dropping or

double-clicking on the information from the Content pane on the right hand
side. The second row of the table should include the Level information while
the third row should include the Pressure information. If completed, click on
OK.

4. In the Subscriptions section on the Notification Rule tab Click on the blue
View/Edit Subscriptions link.
5. In the line for student01 select Tank Level Excursion - Email with Table in
the Configuration column. Click on OK. Check In.
6. Verify with Outlook whether the new notification emails have the new
requested format.

Page 238
 Communicating Important Events

10.5 Acknowledging Notifications

Acknowledgements of Notifications can be used to confirm that important
notifications are read and acted on.

Note: A pre-requisite for the Acknowledgement feature is that the Can be Acknowledged setting
in the event frame template has been checked.

Ways of Acknowledging
Acknowledgment can be performed in two ways:
• Display the event in PI System Explorer (Event Frame Search Result). Select
the context menu function Acknowledge…

When acknowledged, the red exclamation mark changes into an .

When you hover with the mouse over the OK you get information about who
and when the acknowledgement was made.

• Open the corresponding Event details display in PI Vision. Click on the

Acknowledgement link for the event frame.
To display the corresponding event details, either follow the Event Details link
in the notification email or use the event search options in PI Vision.

Page 239
Building PI System Assets and Analytics with PI AF

10.5.1 Directed Activity – Commenting and Acknowledging Events

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.
Your instructor will have directions.

Tank01 in Montreal is critical for the whole operation at that site. If the material level in that tank
is not proper, it is the duty of student01 to add a comment on the problem and to acknowledge
the notification to document that action has been taken.

Activity Objectives
• Read the information in the latest notification email for Tank01 and open the
event details in PI Vision
• Enter a comment on the current level status and acknowledge the alert.

Approach
6. In Outlook, open the latest notification email for Tank01.
(If the email is quite new there is a high chance that the level has not yet
returned to normal level since it started to violate the limit.)
7. Click on the blue Events Details Hyperlink link. Details page for the event will
be displayed in PI Vision.

Page 240
 Communicating Important Events

8. If the level is still outside the limits, the event is still ongoing. In that case, the
end time is displayed as In Progress. In case you continue to observe the
display for some time, the time span covered in the trend will increase until
the level returned to normal (PI Vision update rate is 15 seconds).

9. Add and remove trend lines by selecting and unselecting them in the list
below the trend.

10. Add a text into the comment field and click on the Add button to enter.

Page 241
Building PI System Assets and Analytics with PI AF

11. Click on the Acknowledge button to acknowledge the event. Information

about the notifications being sent, the comment and the acknowledgement
are shown in PI Vision.

Page 242
 Communicating Important Events

10.5.2 Directed Activity - Validating the Acknowledgment Process

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.
Your instructor will have directions.

Exercise Objectives
• Compare the commenting and acknowledgment of notification alerts in PI
Vision and PI System Explorer.

Approach
1. Open the PI System Explorer and select Event Frames in the Navigator.
2. Select New Search… from Event Frame Searches context menu
3. Set Search to: Starting After
4. Set Search Start to: *-30m
5. Set Template to: Tank Level Excursion. Click on Search.

Page 243
Building PI System Assets and Analytics with PI AF

6. Click on the Wheel icon in the header line of the results.

Click on Select Attributes. Click on icon to add all four (4) attributes. Click
on OK. The list will be extended by the four selected attributes. Click on OK.

7. Rename default Search name to Tank Level Excursions Last 30 Minutes

8. Verify whether the event frames with Product= HC1500 have an annotation
icon. If you hover over the Annotation icon it displays Notification sent to 1
subscriber(s).

9. Verify that comment and acknowledgement information from the previous

exercise is displayed in PI System Explorer.
10. To acknowledge alerts in PI System Explorer, select one or several lines of
the event frame list. From the context menu, select Acknowledge… The icon
in the acknowledgement column changes from Unacknowledged to
Acknowledged .

Page 244
 Communicating Important Events

10.6 Adding Contacts

The Contacts section of the navigator panel of PSE allows for the definition of
contacts. The contacts will be receiving the notification messages once they are
triggered. This section defines the various types of contact objects that can be
created and used by Notifications.

10.6.1 Active Directory (AD) access for contacts

Notifications normally gets the contacts and their addresses from the configured
domain AD database. This prevents the administrator from having to do the tedious
task of entering all of the potential subscribers and their contact information in order
to start using Notifications.
Each AF server provides the option to specify the domain and contact sub-folder, as
well as the account needed to access Active Directory and retrieve contact names.
By default, the account under which the AF server application service is running is
used for Active Directory access. The AD access is configurable in the AF Server
Properties dialog box (with Contacts being selected in the Navigator, go to Tools >
Active Directory Properties).

By default, the AF server is installed using a virtual account,

NT SERVICE\AFService. However, the AF server service account can be changed.
If the AF server service account does not have the necessary permission to read the
Active Directory, no contact names will be retrieved in the Contacts list. If your Active
Directory security is configured to allow the AF server service account to read the
Active Directory, this is the simplest option.
In the Active Directory Domain Name text box, enter the full DNS name of the Active
Directory domain from which the contact names will be retrieved for the PI
Notifications Service Contacts.
In the Active Directory Contact Sub-Folder text box, enter the path to the folder
containing the list of contacts for this domain. In larger Active Directory domains,
contacts may be organized within sub-folders. The use of sub-folders can allow for
faster retrieval of a list of Active Directory contacts.

Page 245
Building PI System Assets and Analytics with PI AF

10.6.2 Searching for Contacts

Because the AD 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. In case of the Training Cloud Environment (TCE) a search for student*
will return all the student AD users (student01, student02, student03, student04).

Page 246
 Communicating Important Events

10.6.3 Directed Activity – Adding Contact Information

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. Your instructor will have directions.

Activity Objectives
• Create a new contact for Notifications.

Problem Description
For those who do not have entries in AD 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 want to receive notifications. Custom contacts are available to all AF
databases.

Approach
Adding a custom contact in PSE:
1. To create a custom contact, select Contacts from the navigator panel.
2. Select New > New Contact from the toolbar and enter your name for the
contact Name.
3. Right click the contact for you and select New Delivery Endpoint
4. Enter a delivery endpoint name (e.g. <your name> at Work). From the
Delivery Channel dropdown, select Email.
Fill in your work email address and check in your changes.

5. (optional) Enter a second delivery endpoint for the home email address.

Note: in the Training Cloud Environment (TCE) there are only some email addresses in the
pischool.int AD you can actually use for sending emails to. Refer to the corresponding
information in the Exercise section at the end of the book.

Page 247
Building PI System Assets and Analytics with PI AF

10.6.4 Notifications Groups

A Notifications Group is an unordered collection of delivery endpoints, which includes

Active Directory recipients. If a notification is configured to send a message to a
Notifications Group, the message is sent to all members of the group simultaneously.

10.6.5 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 Notifications server that
the alert was acknowledged by a contact.
A notification alert is sent to the first contact on the list. If the notification is not
acknowledged within a specified time, then notification messages are sent
sequentially to the remaining members of the escalation team until the notification
instance is acknowledged.
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.

10.6.6 Subscribing Contacts to Notifications

To maintain subscribers of a notification, navigate to the Notification Rules tab for a

selected element or a selected element template, and then click View/Edit
Subscriptions in the Subscriptions pane.
To add contacts, endpoints or groups to existing notifications, drag and drop them
into the Subscriptions list. To remove, select a line with a subscription and click on
the Unsubscribe icon on the top.

10.6.7 Dynamic Email Delivery Endpoints (since AF 2017 R2)

You can configure an email delivery endpoint as a value of an attribute. This

provides an additional flexibility in situations where notification emails can be sent to
different recipients without making changes to the notification rule template.

Page 248
 Communicating Important Events

10.6.8 Directed Activity - Using Dynamic Email Delivery Endpoints (optional)

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.
Your instructor will have directions.

Exercise Objectives
• Create an analysis to define an email address depending on current time.
• Switch email recipient for notification emails

Problem Description
To balance the workload for the people responsible to handle tank level excursions,
the notification emails should be sent to different email addresses depending on the
actual clock time according to the following rules:

Note: The above rule is likely not a typical real situation, but has rather been selected to allow a
convenient check-out during the class training.

Page 249
Building PI System Assets and Analytics with PI AF

Approach

Create an Analysis to set the email address according to the time

1. Open the PI System Explorer and navigate to the Tank element template.
Create a new expression analysis, Email Address Setting.
When you map the output, select the option to save output history. Set the
value type to string. For scheduling, select period of 30 minutes, no offset.

Page 250
 Communicating Important Events

Tips:
• '..\|SiteID' refers to the attribute SiteID in the parent element of
the tank (which is the site)
• To start a new line, use Shift-Enter.
• Do not use blanks in the Variable names.
• To check the analysis, select an example element and run Preview
Results.
• To get initial value for the Notification Email Address (is calculated
only every 30 minutes), switch to management tab and perform a
Backfill for the last hour.

Page 251
Building PI System Assets and Analytics with PI AF

Create a dynamic endpoint that refers to the Notification Email Address

attribute and create a related subscription.

1. Select Library in the Navigator and open the Notification Rule Templates for
the Tank element template.
2. Click on the blue View/Edit Subscriptions link
3. Expand Dynamic Endpoints in the Contacts section, click on the blue Create
a new dynamic endpoint… link and select Notification Email Address from
the dropdown of the attribute list. For the Endpoint Name, enter Dynamic
Notification Email Address. Click the Create button.

Note: the Warning

“Value must be a valid email address at delivery time.”
can be ignored.

4. Select the line with the existing subscription and click on the Unsubscribe
icon on the top.
5. Expand Dynamic Endpoints in the Contacts section and drag Dynamic
Notification Email Address to the Subscriptions list. Click on the dropdown
icon in the Configuration column and select Tank Level Excursion - Email
with Table.
6. Click on OK to exit the View/Edit Subscriptions dialog box.
7. Check in the changes.
8. Verify whether email delivery is performed as intended. (requires you keep
system running for a while).

Page 252
 Communicating Important Events

10.6.9 Directed Activity –Sending Notification Alerts in Escalation Sequence (optional)

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.
Your instructor will have directions.

Exercise Objectives
• Assign several contacts to an escalation team
• Understand and apply options for an escalation team.
• Explore the sequence of notifications for an escalation team.

Problem Description
You want to change the strategy, which people in the organization are informed in
case of a level limit violation. In order to avoid a confusion during the period when
you change the strategy, you want to suspend the notification emails during the time,
when you reconfigure the system.
Two people from the operational personnel, the tank operator and the safety
engineer) can handle the situation when the tank level has exceeded a limit. The
tank operator should be informed first. In case he does not take action within 5
minutes, the safety engineer should be informed as well. Do not send email to
student01 anymore.
Use the following email addresses:
Tank Operator: [email protected]
Safety Engineer: [email protected]

Note, that if you are executing this exercise in a local language environment, email addresses
for local language accounts corresponding to student02 and student03 are not supported.

Approach
1. Open the PI System Explorer and select Management in the Navigator.
Choose Notification Rules type.

Page 253
Building PI System Assets and Analytics with PI AF

Note: The status displayed here is based on the notification rule configuration only. The status
does not give information on whether the notification is running or in error.

2. Enable the check box in the header line to select all notifications for the ten
(10) tanks, then click Disable selected notification rules.

Tip: By selecting any combination of lines with rules, you can start or stop the selected rules.

3. Select Contacts in the Navigator.

4. Create a new escalation team called Tank Personnel Escalation Team by
right clicking the Escalation Teams folder and selecting New Escalation
Team.
5. In the right-hand side Contacts window, select Contacts > New Search…
Search for the contacts with Name= student*
6. Expand student02 and drag the email address (student02 - Email) into the
escalation list area (is empty in the beginning). Repeat the same for
student03. Select a 5 minutes Escalation period. Do not repeat the escalation
sequence, if the alert was not acknowledged.

7. Select Library in the Navigator and open the Notification Rule Templates for
the Tank element template.
8. Click on the blue View/Edit Subscriptions link
9. Expand Escalation Teams in the Contacts section and drag Tank Personnel
Escalation Team to the Subscriptions list. Click on the dropdown icon of the
team name to expand the team members. Select Tank Level Excursion -
Email with Table for both.
10. Select the line(s) with the other subscriptions and click on the Unsubscribe
icon on the top.
11. Click on OK to exit the View/Edit Subscriptions dialog box.
12. Check in the changes.
13. Select Management in the Navigator. Start the notifications in the same way
as they were stopped before.

Page 254
 Communicating Important Events

Question for different Escalation Option Settings

Assume you have set to repeat the escalation three (3) times, in case it was not
acknowledged. How many emails will be sent out, if no action is taken by the
operators and the violation is there for more than an hour? When will the last email
be sent?
Answers: _____ emails will be sent, the last email is sent ______ minutes after the
problem started.

Explore the escalation sequences (optional)

After some runtime (> 30 minutes), several new level limit violations will have
happened for Tank01 and Tank02.

Note: The simulation of the tank levels repeats the same pattern all over again. The cycle times
depend on the tanks. Tank01: 10 minutes, Tank02: 30 minutes, Tank03…Tank10: > some
hours.

1. Select Event Frames in the Navigator.

2. We have created an event frame search with the name Tank Level
Excursions Last 30 Minutes in an earlier activity.
Use this search to list the recent event frames (if still displayed from previous
activities, click on the Refresh button in PI System Explorer Toolbar).
3. Select a completed event frame (End Time not empty) for a Low Limit
Violation of Tank02. Select Annotate… from the context menu. The
Annotations lists the email sequence.

Hint: Click on the Wheel icon to show a column with Description information to get more
details on the email that was sent.

4. Select a completed event frame for Tank01. Can you describe why no
escalation was sent?

Page 255
Building PI System Assets and Analytics with PI AF

10.7 Delivering Notifications via a Web Service

10.7.1 Web Service

The web service delivery channel allows 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.

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 web service.
The configuration necessary to send information to a web service via Notifications
will be done when creating a new Delivery Endpoint of type WebService from the
Contacts section of the navigator panel in PSE.

10.7.2 Web Service example: The Work Order Generator

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 web service, the notification would pass all necessary
information to the maintenance system so a work order can be generated. For 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:85/WorkOrderGenerator2013/Service1.asmx

Page 256
 Communicating Important Events

10.7.3 Directed activity – Validating the Web Service Functionality (optional)

This solo or group activity 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
• Understand the functionality of the sample Web Service for a Work Order
Generator

Approach
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.
<?xml version=”1.0” encoding=”UTF-8”?>
<int xmlns=”http://localhost/”>1</int>
You can go ahead and query the WorkOrderGenerator SQL server database to
confirm that the new work order was successfully created in the system.

1. Open the Internet Explorer and got to:

http://localhost:85/WorkOrderGenerator2013/service1.asmx
(There is also a link for that under the favorites)
2. Click on New Work Order. Enter the parameters:
a. For the EquipmentName, enter Reactor1
b. For the FailureType, enter Pressure Too High
c. For the ActionToTake, enter Check Pressure Relief Valve
3. Click on Invoke. Record the Work Order Number that is returned.
4. Re-open the page (click on the favorites link again) and select
GetEquipmentNameFromWorkOrder. Enter the work order number from the
last step and submit.
5. Open SQL Server Management Studio and connect to PISRV01.
6. Expand
Databases > WorkOrderGenerator > Tables > dbo.WorkOrderGen table.
7. From the right-mouse button context menu, execute Select Top 1000 Rows.
8. Locate the last entry to verify whether the new work order entry has been
added.

Page 257
Building PI System Assets and Analytics with PI AF

10.7.4 Directed activity – Creating a WebService delivery endpoint (optional)

This solo or group activity 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
• Familiarize with the creation of a Web Service delivery point for the Work
Order Generator.

Approach
To add a custom delivery endpoint in PSE:
1. Select Contacts from the navigator panel.
2. Select New Delivery Endpoint from the right-click context menu of the
Delivery Endpoints folder. Enter the name Work Order and a description and
select Web service delivery channel. Check-In.
3. Enter the web service address
http://localhost:85/WorkOrderGenerator2013/service1.asmx
and click on Get Web Services
4. Select NewWorkOrder from the drop-down options under Web method.

5. Check in.

Page 258
 Communicating Important Events

10.7.5 Directed activity – Creating an automatic Work Order (optional)

This solo or group activity 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
• Set up different types of subscribers to a notification.
• Demonstrate how Notifications can provide PI System information to a work
order system.

Problem Description
In addition to alerting people by sending emails, you would like to create new entries
in the work order database for the critical tank level events.

Approach
To add a subscription for another delivery endpoint in PSE:
1. Select Library from the navigator panel and navigate to the Tank element
template. Open the Notification Rule Templates tab.
2. Click on the blue View/Edit Subscriptions link in the Subscriptions section.
3. Expand Delivery Endpoints in the Contacts section and drag Work Order to
the Subscriptions list. You are informed that you have to configure the Web
Service:
4. Click on the spanner icon and use drag and drop to set for the three (3) web
service methods’ parameters:
a. For the EquipmentName, set Tank name:Value At Start Time
(from Element Template Attributes: Tank)
b. For the FailureType, enter Event Frame:Name
(from Event Frame Properties)
c. For the ActionToTake, enter Level Excursion:Value At Start Time
(from Event Frame Attributes: Tank level Excursion)

Page 259
Building PI System Assets and Analytics with PI AF

5. Click on OK.
6. Check In the changes.

To verify the work order entries:

After some runtime, several new level limit violations will have happened for Tank01
and Tank02 (there are ca. 4 violations for Tank01 and ca. 2 violations for Tank02 in
30 minutes).
1. Select Event Frames in the Navigator.
2. List the event frames for the Search named Tank Level Excursions Last 30
Minutes (if still displayed from previous activities, click on the Refresh button
in PI System Explorer Toolbar)
3. Select a new event frame. Select Annotate… from the context menu. The
Annotations lists that notification has been sent to two (2) subscribers.

4. Open SQL Server Management Studio and connect to PISRV01 and access
the dbo.WorkOrderGen table contents again. Verify whether new work order
entry/entries have been added.

Note: the work order database accepts event frame names with a maximum of 50 characters. If
names are too long, no entry is made is made in the table

Page 260
 AF Best Practices

11. AF Best Practices

The following recommendations provide some guidelines on how to best setup your
AF asset structure based on experience from existing AF installations.
Be aware that in real life you cannot follow all these recommendations!

• All elements should be based on a template

Even if the template has no attributes in the beginning
Easier maintenance

• All elements at the same level should be of the same type

Enterprise at the first level, Site the second level, Area the third, etc.
Easier use of relative references from child-elements

• Do not only consider Bottom-Up approach

Try to achieve a well-designed structure, plan for the usefulness of the
AF model

• Categories for elements attributes and analyses

Organizes large numbers of attributes/elements
A fast way to search for elements and attributes

• Always set the unit of measure explicitly

PI Point attributes: set source unit for the tag
Formulas: set units for all variables and the result
Analyses: use the Convert() function
Avoid defaults

• Use inherited templates

Allows Flexibility but keeps the standardization

Page 261
Building PI System Assets and Analytics with PI AF

• Build Different Views specific for your users

Use element references

• Use Enumerations
Limit the choices that
can be entered in attributes

• Use Hierarchies of Attributes

Group details or aggregations on a different level

• Use all Data References

Many options with Table Lookup and for String Builder

• Keep relational data in relational database

Link AF Tables to results and views
Use Cache and Parameters

Page 262
 Final Exercise: Modeling a Wind Farm in AF

12. Final Exercise: Modeling a Wind Farm in AF

12.1 TxLake Windfarm: Modeling your assets

12.1.1 Directed Activity – Understanding the windfarm simulation

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.
Your instructor will have directions.

Activity Objectives
• Explore the PI points that simulate the windfarm operation
• Explore the information provided in Excel spreadsheet and in SQL Database
table
• Copy information from the Excel spreadsheet in to an AF table.

Problem Description
50 Wind Powered Turbine units (WPUs) are in the TxLake wind farm, process data is
captured in PI Data Archive Server tags. Work on creating the AF structure has
already started (AF database TxLake Windfarm). The company wants to have all
turbines represented in the AF database.
• An element for the first turbine, WPU_TxLKE001, is already created. It has
an PI Point attribute for the current generated Power (kW)
• A corresponding element template, Wind Turbine, is already created.
• An AF table WPUs Identification has detail information (such as the turbine
Model, Array Position, etc.) for all 50 turbines.

• Information about the turbine models is stored in an Excel spreadsheet.

• Information about turbine maintenance is stored in an SQL table.

Approach
In this step you will familiarize with the existing PI Points and the AF structure and
copy information from the excel spreadsheet into an AF table.

Page 263
Building PI System Assets and Analytics with PI AF

AF Database TxLake Windfarm

1. Open the TXLake Windfarm AF database in PSE, select Elements in the
Navigator. The database is in an initial, incomplete state.
2. Explore data for the 50 wind turbines in AF table WPUs Identification.
3. Explore the WPUs Identification table. Where is the information stored?
What is the type of table?
_____________________________________________

PI Points
4. Select Search > Tag Search from PSE menu. Search for tags with name
pattern WPU_TXLKE001* to get the points from the first wind turbine. Result:
six tags are listed and all tags have recent values. Record the engineering
units for later reference.

Tag Name AF Attribute Name (suggested) Unit

WPU_TXLKE001.GenWatts Power
WPU_TXLKE001.RotorRPM Rotor Speed
WPU_TXLKE001.WindDir Wind Direction
WPU_TXLKE001.WindSpd Wind Speed
WPU_TXLKE001.YawMotorAmps Yaw Motor Amperage
WPU_TXLKE001.YawPos Yaw Position

Search for the tags from another wind turbine.

Page 264
 Final Exercise: Modeling a Wind Farm in AF

Wind Turbine Model Information (available in Excel Spreadsheet)

5. Data for wind turbine models can be found in file:
C:\Class\Exercises\04_TxLake Wind FarmTxLake\WindFarm_WPUModels.xlsx.

To get this information into an internal AF table we will create the table structure
manually, then copy and paste the contents from spreadsheet into the AF table

6. Select Library in the Navigator, create a new table, name: WPU Models
Specifications
7. Select the Define Table tab and define table structure as follows:

8. Copy (Ctrl-C) the cells in the Excel spreadsheet with data (exclude the header line),
select a line in the AF table and paste (Ctrl-V) the contents.

Installation and Maintenance Dates (available in SQL Server table)

9. Open SQL Server Management Studio 2014, connect to SQL Server PISRV01.
10. Expand Databases, expand WindFarmMaint.
11. From context menu of the dbo.TxLakeMaint table, Select Top 100 Rows. There is a
row for every turbine. Locate the columns with installation date and last maintenance
date. In the next activity, we will link information from that table into AF.

Page 265
Building PI System Assets and Analytics with PI AF

12.1.2 Solo or Group exercise: Modeling a Wind Farm in AF

This solo or group exercise 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 exercise.

Activity Objectives
• Complete the design of the TxLake Windfarm AF database
• Implement formulas and analyses to provide information that is requested by
operation personnel
• Understand the difference between importing data from Excel spreadsheets
and linking Microsoft SQL Server tables
• Explore the AF attribute categories.

Approach
In this self-paced exercise you will complete information for all the 50 turbines in the
AF database with the data from the corresponding PI Points and the information from
the AF tables and from tables in SQL Server.

Page 266
 Final Exercise: Modeling a Wind Farm in AF

Explore the contents of the TxLake Windfarm database

1. Select the TxLake Windfarm AF database. It will be used to represent the
wind farm.
2. A top-level element and a child attribute for the first wind turbine is already
implemented:

What is the name of the element template that is used for the turbine
element? ____________________________

Complete the contents of the TxLake Windfarm database

3. Configure the necessary attributes to model the data available in the two
tables, WPUs Identification and WPU Models Specifications.
4. Create and configure the necessary attribute templates to model the real-time
data coming in the Data Archive tags (TxLakeWindFarm_Tags.xlsx).

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.

5. Use PI Builder to create the AF elements for the remaining 49 turbines. The
wind turbines are to be called WPU_TxLKE001, WPU_TxLKE002, etc. and
are all based on the same template.
6. Validate that the wind turbines were created by opening PSE.

Page 267
Building PI System Assets and Analytics with PI AF

Importing SQL Server data

7. Create a new AF table linked to the wind farm maintenance system (Microsoft
SQL Server database: WindFarmMaint)
Under Table Properties, select Link. In the dropdown
for Connection, select <Build>
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).

8. Create and configure the necessary attribute templates to model the data available from
the Microsoft SQL Server relational database.
9. Create attribute categories to organize the attributes into logical groupings.

About Attribute Categories

Categories can be used for various 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 AF model. Categories are not extensively used in
client applications like PI ProcessBook or PI Datalink. However, certain analytics, like
the roll-up calculation, take advantage of this feature.

Page 268
 Final Exercise: Modeling a Wind Farm in AF

Adding Analytics
10. Add an attribute to show the last hour’s average generated power (kW). This is a running
average over the last hour on the instantaneous generation attribute (.GenWatts tag).
There is no need to archive the result of this calculation.
11. Add an attribute to show the WPU effectiveness or yield (%) with the following formula.
The results of this calculation should be historized. The calculation should be executed
every minute. Backfill 1 hour worth of data for the first 10 wind turbines.
Power / Rated Power * 100
12. Calculate the Total Power Generated for the whole wind farm in MegaWatts by using a
rollup analysis.

Tracking important Events

13. Lake Wind Farm’s engineers would like to keep track of high-speed winds; knowing the
duration of wind gusts (speeds faster than 90 mph) is essential for performance analysis.
Furthermore, engineers need to know what the average rotor speed and the maximum
power generated are during a wind gust. Backfill the events for the last hour for all wind
turbines.

Visualizing the data (PI Vision)

14. Open the Windfarm Overview display. Verify that the list of turbines is expanded by the
new turbines you have created. Add a radial gauge object to display the total farm
energy.

Note: the default for the number of returned assets under the asset search criteria is 16.
It has been changed to 50 to accommodate all turbines.

Page 269
Building PI System Assets and Analytics with PI AF

15. Click on a turbine in the list to open the Wind Turbine Detail display. Add objects to the
display to show information from the attributes you have added.

Page 270
 Training Cloud Environments (TCE)

13. Training Cloud Environments (TCE)

There is a dedicated setup in the cloud with Microsoft Azure virtual machines, which
is prepared to perform the exercises of this class. The setup consists of the following
two machines: PIDC.PISCHOOL.INT (domain controller) and
PISRV01.PISCHOOL.INT (application server). The training is carried out on
PISRV01.
The Windows domain accounts available for this training are: student01, student02,
student03, and student04. For localized environments, the following accounts have
to be used:
German: de-student01, de-student02,de-student03, de-student04
Spanish: es-student01, es-student02,es-student03, es-student04
French: fr-student01, fr-student02,fr-student03, fr-student04
Japanese: ja-student01, ja-student02,ja-student03, ja-student04
Korean: ko-student01, ko-student02,ko-student03, ko-student04
Portuguese: pt-student01, pt-student02,pt-student03, pt-student04
Russian: ru-student01, ru-student02,ru-student03, ru-student04
Chinese: zh-student01, zh-student02,zh-student03, zh-student04
The Mail Server is configured to support the following student accounts:
[email protected], [email protected], [email protected] and
[email protected].

Page 271
Building PI System Assets and Analytics with PI AF

14. Resources

14.1 OSIsoft Learning Options

The OSIsoft Learning site is located at https://learning.osisoft.com.

14.1.1 Instructor Led Training

Instructor led training at our public training site - Our classic offering - Learn about
the PI System at OSIsoft Training Centers with classes in several languages and
growing!

Instructor led training at your site - Our personalized offering - Learn with customized
curriculum and get coaching at your site, at your time, with your data!

14.1.2 OnLine Training

Small Private Online Courses - Our latest offering - Learn about the PI System from
your own office or home, on your own schedule, with your own data! For more
information go to https://pisquare.osisoft.com/community/Master-PI

Page 272
 Resources

On Demand Learning: YouTube Channel - Learning Anywhere, Everywhere - Learn

about the PI system by watching any of our 1000+ free videos on You Tube! Playlist
for various topics are available to help guide you through your training topic.

Training Cloud Environments (TCE): The Training Cloud Environments give you
access to a working PI System on the Cloud. They are hosted on Microsoft Azure
virtual machines. These environments are usually associated with one of our online
courses and they are meant to help you work on the course material hands on. Each
of the Training Cloud Environments has a different number of virtual machines and
their duration will be different based on the online course they are associated with.

14.1.3 Asset-Based PI Example Kits

Asset Based PI Example Kits help you learn how to apply Asset Framework
concepts to common, industry-specific business objectives. The kits are not intended
to provide complete solutions for their example applications, and examples may be
missing key requirements for a production environment.
They can be obtained from the OSIsoft Learning site at:
https://learning.osisoft.com/asset-based-af-example-kits

14.2 OSIsoft Community

PI Square is OSIsoft’s Community. Here you can make connections with
• other OSIsoft employees and customers
• PI Dev Club to assist in your development projects

Page 273
Building PI System Assets and Analytics with PI AF

14.3 Tech Support

We recommend visiting the Tech Support site, http://techsupport.osisoft.com.

From here you have many options.

• You can download anything your company is licensed for using the Download
center.
• You can view OSIsoft’ s Roadmap to get information about the most current
releases and predicated release dates and features for new version or
products.
• You can login and view your support calls, both currently open and previously
closed.
• You can also search through our Knowledge Base to try and troubleshoot any
issues you may be having on your own.
The phone number and email address for OSIsoft Technical Support:
• Phone: (01) 510 297-5828 US or search
https://techsupport.osisoft.com/Contact-Us/ for your local contact number.
• E-Mail: [email protected]
• Before you contact Tech Support, collect
o the name of the product and the version number..
o Determine the PI version and build numbers using the Operation >
Version option in SMT.
o Get computer platform (CPU type, operating system, and version
number) as follows:

Page 274
 Resources

▪ On Windows, right-click on My Computer icon and select

Properties tab.
▪ On UNIX, type uname -a
o Note the time that the difficulty started, and be prepared to report the
contents of the message log at that time. The message log is found in
the Operation > Message Log Viewer option in SMT.
o You will likely also need the PIPC log covering the applicable time
range. This log is located in \\pipc\dat.

14.4 Further Questions

For questions about Licensing, if you are in the US, you can find your salesman
listed at http://www.osisoft.com > Contact Us > US Sales. If you are outside the US
you can find your salesman listed at http://www.osisoft.com > Contact Us >
International Sales.
For questions about existing Support Issues, you should call technical support at 510
297-5828 or visit http://techsupport.osisoft.com > My Support > My Calls.
For questions about unresolved training issues, contact your instructor or email
[email protected].
For all other questions, please contact our Customer Service group via email at
[email protected].

Page 275
Building PI System Assets and Analytics with PI AF

15. Software Versions Used in this Document

The list below describes the software versions used in this version of the course.

Software Version
Windows Server 2016
Data Archive Server 2018 SP3 Patch 3 (3.4.440.477) (*)
PI System Management Tools 2018 SP3 Patch 1 (3.6.3.365) (*)
AF Server 2018 SP3 Patch 3 (2.10.9.593) (*)
PI System Explorer 2018 SP3 Patch 3 (2.10.9.593) (*)
PI Analysis Service 2018 SP3 Patch 3 (2.10.6.195) (*)
PI Notifications Service 2018 SP3 Patch 3 (2.10.9.593) (*)
Event Frames Generator Interface 4.0.40.3609
PI Vision 2020 Patch 1 (3.5.1.0)
PI Datalink 2019 (5.5.0.0)
PI ProcessBook 2015 R2 SP2 (3.6.2.271)
Microsoft Office (64-bit) 2016
Microsoft SQL Server (64-bit) 2014 SP3 (12.0.6024.0) (*)
(*) this was upgraded in 2021 version of the class

Page 276
 Appendix A: Substitution Parameters

16. Appendix A: Substitution Parameters

Name Substitution Parameters

Parameter Substitution

%Attribute% The name of the attribute that holds this data reference.

Name of the root attribute or attribute template that holds this

%|Attribute%
data reference.

%..|Attribute% The name of the parent attribute that holds this data reference.

%Database% The name of the AF Database in which the attribute resides.

%Element% The name of the AF Element in which the attribute resides.

The name of the root AF Element in which the attribute

%\Element%
resides.

The name of the parent element of the element in which the

%..\Element% attribute resides. To retrieve further ancestors, use the ‘..\’
notations, such as %..\..\Element%.

The name of the default PI Data Archive of the AF Database in

which the attribute resides. It first resolves to the current PI AF
database's default PI Data Archive if one is specified;
%Server% otherwise, it resolves to the PI AF Server's default PI Data
Archive if one is specified. If one is not specified there, it
resolves to the local default PI Data Archive.

Name of the PI AF server or collective where the attribute

%System%
resides.

Description Substitution Parameters

Parameter Substitution

%Description% The description of the attribute that holds this data reference.

%ElementDescription
The description of the element in which the attribute resides.
%

Page 277
Building PI System Assets and Analytics with PI AF

Time Substitution Parameters

Parameter Substitution

Time span between the start time and end time, if it can be
obtained from the time context. In open event frames, obtains
the time span from start time to the current time. The time span
%Duration% uses a different format from other time substitution parameters.
For details on the format refer to "List of PI AF substitution
parameters" in the PI Asset Framework and PI System
Explorer section of the PI Server documentation.

%EndTime% Local end time if it can be obtained from the time context.

%StartTime% Local start time if it can be obtained from the time context.

%Time% The local time if it can be obtained from the time context.

Symbols used in Substitution Parameters

Symbol Description Examples

Considers the expression as a %Element%

%....%
substitution parameter. %Attribute%

Current element or attribute. Use .\

to navigate down from current
. %.\ChildElement|Attribute%
element. Use .| to navigate to child
attributes of the current attribute.

%..\..\Element%
.. Navigates a level up
%..|Attribute%

Separates components of a path,

\ %..\Element%
except attributes.

| Separates attributes in a path. %..|Attribute%

Attribute value at same level as

References the value of the object attribute: %@Attribute%
@
instead of its name. Attribute value at parent attribute
level %@..|Attribute%

For more information refer to chapter "Substitution parameters in

data references" in the PI Asset Framework and PI System Explorer
section of the PI Server documentation.

Page 278
 Revision History

17. Revision History

Revision Reviewer Description

2010 Martin Bryant Initial version of the Building PI System Assets
and Analytics with 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
2014 Alejandro Molano AF 2.6 Update, added Asset-Based analytics
chapter, Event Frames chapter and EF
visualization using PI Coresight and PI Datalink.
2015 Linda Payne, Gerhard Replaced Pizza Delivery Vehicles by Mining
Polenz Trucks Application, updated for Azure-based
learning setup
2015a Linda Payne, Gerhard Updated for PI Server 2015
Polenz Revised chapter AF Object SecurityTerm, added
chapter for Future Data
2015b Gerhard Polenz Revised exercise 6.2.3 (PIVOT table), Changed
chapter 9.6 (Future data now created by AF
Analysis),
added chapter 12.6. How to import data from
Excel
2016a Gerhard Polenz 2016 Software Upgrade.
Coresight related parts rewritten, EF-related
exercises revised, attribute traits, attribute
properties, multiple Asset views, ACE optional
2016b Gerhard Polenz 2016 R2 Software Upgrade.
Complete re-write of the Notification section
2016c Gerhard Polenz new TCE VM security, new student passwords
2017 R2 Gerhard Polenz 2017 R2 Software Upgrade, Coresight->PIVision
2018 Gerhard Polenz TCE based on Windows 2016 Server (PISRV01),
added DisplayDigits, removed PE, Totalizer and
ACE chapters
2018A, Gerhard Polenz Minor corrections
2018A2
2018A3 Gerhard Polenz Comments for virtual classroom environment
2021 Gerhard Polenz Added Wonderland Chemicals for batch event
frames

Page 279