PI System Basics

Operational IntelligenceCopyright
Copyright & Trademark
© Copyright 1995-2020
OSIsoft, LLC
1600 Alvarado Street
San Leandro, CA 94577

© 2020 by OSIsoft, LLC. All rights reserved.

All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means,
mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC.
OSIsoft, the OSIsoft logo and logotype, Managed PI, OSIsoft Advanced Services, OSIsoft Cloud Services, OSIsoft Connected Services, PI ACE, PI
Advanced Computing Engine, PI AF SDK, PI API, PI Asset Framework, PI Audit Viewer, PI Builder, PI Cloud Connect, PI Connectors, PI Data
Archive, PI DataLink, PI DataLink Server, PI Developers Club, PI Integrator for Business Analytics, PI Interfaces, PI JDBC Driver, PI Manual
Logger, PI Notifications, PI ODBC Driver, PI OLEDB Enterprise, PI OLEDB Provider, PI OPC DA Server, PI OPC HDA Server, PI ProcessBook, PI
SDK, PI Server, PI Square, PI System, PI System Access, PI Vision, PI Visualization Suite, PI Web API, PI WebParts, PI Web Services, RLINK and
RtReports are all trademarks of OSIsoft, LLC.

All other trademarks or trade names used herein are the property of their respective owners.

U.S. GOVERNMENT RIGHTS

Use, duplication or disclosure by the US Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and/or as
provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12-212, FAR 52.227-19, or their successors, as applicable.

Published: September 20, 2021

Table of Contents

Contents
Table of Contents .......................................................................................................................................... 3
1 PI System Components .............................................................................................................................. 5
What is a PI System? ................................................................................................................................. 5
The PI System ........................................................................................................................................ 5
Architecture of a PI System ................................................................................................................... 6
Building Blocks of the PI System ............................................................................................................... 8
What is an AF Attribute? ....................................................................................................................... 8
What is a PI Point? ................................................................................................................................ 9
PI Cloud and PI Edge ............................................................................................................................... 10
What is OSIsoft Cloud Services (OCS)?................................................................................................ 10
How is the data collected? .................................................................................................................. 10
What is Edge Data Store (EDS)? .......................................................................................................... 11
Collecting Data ........................................................................................................................................ 12
PI Interfaces ........................................................................................................................................ 12
PI Connectors ...................................................................................................................................... 12
PI Adapters .......................................................................................................................................... 12
2 PI Time...................................................................................................................................................... 14
PI Time Expressions................................................................................................................................. 14
Fixed Time Syntax ............................................................................................................................... 15
Reference Time Syntax ....................................................................................................................... 15
Time Offset Syntax .............................................................................................................................. 17
Rules to Remember................................................................................................................................. 18
Exercise – PI Time................................................................................................................................ 19
3 Applying Concepts.................................................................................................................................... 20
PI Vision - Browser based displays .......................................................................................................... 20
Drill Down Through the Assets in Your Plant ...................................................................................... 21
Explore PI Points, AF Attributes, and Related Assets in PI Vision ........................................................... 23
Directed Activity – Up close and personal with PI System Data through PI Vision ............................ 23
 Viewing Events in PI Vision ..................................................................................................................... 25
Tracking Important Events with PI ...................................................................................................... 25
Retrieving and Visualising Event Frames ............................................................................................ 26
Advantages of Event Frames............................................................................................................... 26
Directed Activity – Process Downtime ................................................................................................ 27
4 HOW OSIsoft Supports YOU ..................................................................................................................... 28
Learning Platform @ learning.osisoft.com ............................................................................................. 28
OSIsoft Learning YouTube Channel @ youtube.com/OSIsoftLearning................................................... 30
Exercise – Search the OSIsoft Learning Channel ................................................................................. 30
Directed Exercise – Find a playlist on YouTube .................................................................................. 31
myOsisoft.com and the Customer Portal @ customers.osisoft.com...................................................... 32
PI Square – The online PI System Community @ pisquare.osisoft.com ................................................. 33
Exercise – Navigating PI Square .......................................................................................................... 33
1 PI SYSTEM COMPONENTS

What is a PI System?
Learning Outcomes
After completing this topic you should be able to:
 Define the components of a PI System.
 Draw a diagram of the architecture of a PI System.

The PI System

The PI System was originally developed by OSIsoft to collect Plant Information from PLC, DCS
and SCADA systems. The PI System collects, stores, and manages time stamped data. This
data may have timestamps in the past, current or future.
Components of a PI System are:
 Computers with a PI Interface, PI Connector or PI Adapter collect data (known as
points or tags) from a data source. These interface nodes get data from your data
sources and send it to the Data Archive. This data may be collected from a variety of
places, such as:
o the plant, weather stations,
o IT networks,
o location data for trucks,
o Telemetry from monitoring systems.
 Data is stored in the Data Archive in such a way as to make user retrieval as efficient as
possible. The data is accessible to users in different ways: directly or via tools providing
context.
 Accessing the data in context is provided by linking the data points to assets defined in
an Asset Framework (AF) system.
 To visualize the data collected and stored, users use tools in the Visualization Suite:
o PI Vision (browser-based graphs and symbols),
o PI Datalink (a Windows based Excel add in),
o PI ProcessBook (a Windows based application for graphical displays).
 PI Integrators are used to prepare and send the data from the PI System to other
systems for example to be used in data science or Business Intelligence (BI)
applications.
This diagram shows the 3 main categories and components of a typical PI System:

Architecture of a PI System
The architecture varies from simple to complex; some customers have only a single interface
sending data to a single Data Archive. There are many more combinations and configurations of
the PI software components, so make sure to ask your PI System administrator about how your
infrastructure is laid out.
Here is a conceptual diagram as an example:

 Quick Check
Having completed this topic, are you able to:
 Define the components of a PI System?
 Draw a diagram of the architecture of a PI System?

If you answered NO to any of these questions, ask your instructor for assistance.
Building Blocks of the PI System
LEARNING OUTCOMES
 Define the terms of Asset Framework (AF) and its components: elements and attributes.
 Define AF attribute types: static (none), PI Point, point array, formula, string builder,
table lookup and Analysis.

What is an AF Element/Asset?
In Asset Framework, company locations, sites, processes
and each piece of equipment is represented by an
Element. Company Assets may be defined with an AF
Element. The AF encourages organization of assets into a
structure that makes it easier to find information.
A self-explanatory element structure for assets goes a long
way to help users find the data they are seeking. With well-
defined elements showing context for the assets, data can
be located without the user needing to understand the
technical details of each piece of equipment. The AF
element structure assists in promoting a hierarchical and
logical organization of assets.

What is an AF Attribute?

Attributes represent a single property associated with an

asset element. Attributes hold values that can represent:
 static information, such as the diameter of a tank
 a PI point stored in the Data Archive, such as the
current temperature of the tank contents
 formulas
 values linked to tables in relational databases
 values held in internal AF tables
 values derived from AF analytics

PI Vision Screenshot: Drilling down through

Assets in an AF Database titled “Windfarm”

Note: All relevant data about an asset is grouped together with AF Attributes on AF Elements.
This allows users to build displays and reports that maintain a complete view of the company’s
assets.
What is a PI Point?

A PI Point (sometimes referred to as a tag) is a unique storage point for data in the Data
Archive. It is a single point of measurement and has a value with a timestamp, such as a
temperature of 31.2 oC on 2019-Dec-24 23:59.
Point name
Points stored in the Data Archive each have a unique name. It is
a common practice to name the PI Points based on Control
Systems point names. Since the point is the name that identifies
the point to users, a consistent point-naming convention should
be used that is meaningful to people in your organization.
Knowing the naming convention can be helpful in searching for
points.
Try to determine what the following point may refer to:
M03_E1P1_MOTDRV1202_RUNSTAT
It refers to - Machine3 Enclosure 1 Panel 1 Motor Drive 1202
Run Status.
PI Vision Screenshot:
Searching for PI Points Is this intuitive? Probably not, unless you have spent time
memorizing the equipment’s naming conventions.
Most of the time, the PI Points themselves are not going to be easy enough for users to work
with; therefore, OSIsoft recommends developing your Asset Framework hierarchy to leverage
the very “human friendly” nature of AF Attributes on AF Assets. Building an intuitive AF structure
will make end users’ work much easier to accomplish.
PI Cloud and PI Edge
Now that we got an overview of an on-premises PI Server, or PI Core, which is helping our
customers with their data needs for decades, we will also have a look into the more recent cloud
and edge portions of the PI System.

What is OSIsoft Cloud Services (OCS)?

OCS is a cloud-native, secure data platform built on Microsoft Azure and fully operated by
OSIsoft (SaaS/PaaS). You can use OCS to collect, manage, enhance, and share historical,
real-time, and forecasted operations data.

OCS complements on-premises PI Servers and can also collect data directly from edge data
sources. The cloud platform enables you to easily define, visualize, query, and shape datasets,
whether for data science purposes or for use with popular reporting applications, such as
Microsoft Power BI.

OCS gives you the ability to share operations data both internally and with trusted partners or
vendors. IT and BI groups can now use formatted and contextualized Operational Technology
(OT) data across cloud providers (such as Azure, AWS, and Google’s Cloud Platform) and with
other enterprise applications. Operations data within OCS is formatted so that it’s shaped and
ready for advanced analytics.

How is the data collected?

OCS provides a variety of methods to collect data into the system. You can ingress data from
an external application or from PI Server directly to OCS using any of the following methods:
  The PI to OCS Agent transfers PI time-series data from an on-premises PI Server into
OCS. PI to OCS maps PI Data Archive PI points to Sequential Data Store (SDS) types
and streams.
 OSIsoft Message Format (OMF) is a platform-independent format for passing JSON
messages to OCS using an HTTP client. Use OMF to achieve a high-throughput data
feed into OCS. OMF is used to send data from the Edge Data Store (EDS) and from PI
Adapters.
 Developer-friendly REST APIs provide programmatic access to read and write
sequential data into OCS.

What is Edge Data Store (EDS)?

Edge Data Store (EDS) is a lightweight data collection and storage application designed to
capture data at the edge of networks for historical storage and analysis. EDS augments the
PI System and OCS by collecting and storing data in situations where deploying a full system is
impractical. It can collect data that is beyond the reach of automation systems, in unreliable
network conditions, and in environments too rough for traditional computers. Edge Data
Store can run almost anywhere you can install a sensor, such as beam pumps, mining trucks,
wind mills, etc.

The data is collected via PI Adapters which are taking up the task of PI Interfaces and PI
Connectors for edge systems.
Collecting Data
OSIsoft offers three families of data communications software designed to send the data from
various data sources to the PI System. Within each family there are dedicated types which can
communicate with the different data sources. For the most common data sources there is a
product available from each of the three classes.

PI Interfaces

PI interfaces is the oldest and therefore biggest family of data communications software within
the PI System. There are hundreds of different PI interfaces to connect to a large variety of data
sources.

PI interfaces typically run on a dedicated system, called an interface node, which connects both
to the data source and to PI Data Archive. Interface nodes can run multiple interfaces and
connect to multiple PI Data Archive servers. Management and configuration are usually done
from an application installed on the interface node called Interface Configuration Utility (PI ICU).

PI Connectors

PI connectors represent a technology a generation beyond OSIsoft's earlier interface products,

simplifying systems administration through the automation of key functions. With minimal
configuration requirements managed through an HTML-5 compliant web-based dashboard, PI
connectors automate many aspects of setting up an effective PI System, including:

Collection of data types

PI connectors automatically discover data on a data source when they are first connected. PI
connectors collect time-series data and metadata. Time-series data is saved to PI points in PI
Data Archive, whereas metadata such as elements, attributes, and related Event Frames are
saved in AF Server.

Creation of PI points

PI connectors automatically create the PI points, elements, and attributes needed to store the
data that has been selected for collection. Data streams are then auto-configured on the PI
Server. A reference model is built in AF, which serves as a mirror image of the data source. This
is a convenient starting point for integration with a more comprehensive AF model. New data
streams added to the data source are automatically collected by PI connector, which monitors
the source continuously. Automation of this process is particularly useful when dealing with
large numbers of tags.

PI Adapters

PI Adapters gather operations data with total security, fast performance, and no-code
manageability—regardless of device, communication protocol, language, data frequency,
delivery speed, or format. PI Adapters can be installed quickly and are optimized for real-time
time-series data. Adapters are supported on Windows and Linux devices.

Adapters perform the following actions:

 Collect data from assets in remote locations over a variety of popular protocols, a
process known as Data ingress. Each PI Adapter available supports a specific
communication protocol.
 Convert ingressed data to the OSIsoft Message Format (OMF).
 Send converted data to a supported data archive, a process known as Data egress.
Supported data archives include:
o PI Server
o OSIsoft Cloud Services (OCS)
o Edge Data Store (EDS)
o Any combination of the three
2 PI TIME
LEARNING OUTCOMES

 Understand PI time expressions

 Explain the differences between fixed and reference times
 Use time offsets
 Understand the effect of DST on the retrieval of PI point data.

When searching for data in PI you will use a timestamp since most PI data is time series data
and this data has a timestamp associated with it. We can use a special syntax, called PI time, to
specify inputs for timestamps and time intervals in the PI client applications, for example PI
Vision. PI time uses specific abbreviations and rules in building valid time expressions.

PI Time Expressions
In PI there are two ways to specify time:

Fixed Time: An expression that signifies a specific date and time. Used when you want to
save a view of your PI System data for a specific time in history.
Example: A user is creating a report that analyses an equipment failure event which
occurred on the 25th of July 2013 at 11 am, so 25-Jul-2013 11:00:00 AM
Reference Time: An expression that signifies a date and time relative to the current date
and time. Used when you want to create a dynamic view of your data, which can be used to
view data in real-time, or re-used on a periodic basis to create periodic reports.
Example: A user creates a report that summarizes weekly production totals. By using
relative time expressions, the user will be able to re-use this report every week, so define a
start date of “Monday” meaning start the report from last Monday.

Both Fixed Time and Reference Time can be used with Time Offsets; Time Offsets can be used
alone.
Fixed Time Syntax

A fixed time expression is an expression which includes a date, and optionally a time.
When the time component is omitted, Midnight is assumed. And midnight occurs at the
beginning of the day, not the end.

Expression Meaning
5-jan-92 12:34 12:34 p.m. on January 5, 1992
25-sep-12 00:00:00 (midnight) on September 25,
2012

The PI System interprets many different formats for fixed time. In the event of an ambiguous
input, the Windows Region and Language settings of the computer where the PI Visualization
Tool is installed take precedence.

Note the following:

Region and Language
Expression Meaning
Format
00:00:00 (midnight) on
1/5/2015 English (United States)
January 5th 2015
00:00:00 (midnight) on
1/5/2015 Rest of the world
May 1st 2015

Reference Time Syntax

A reference-time abbreviation represents a time relative to the current time.

Abbreviation Meaning Reference time

Now Current time
*
t today 00:00:00 (midnight) of the current day
y yesterday 00:00:00 (midnight) of the previous day
fri friday 00:00:00 (midnight) on the most recent Friday
may may 00:00:00 (midnight) on the current day in May
of the current year
apr-15 april-15 00:00:00 (midnight) on the 15th day of April in
the current year
 Abbreviation Meaning Reference time
YYYY Year 00:00:00 (midnight) on the current day and
month in year YYYY
M-D or M/D USA 00:00:00 (midnight) on the Dth day of month M
Or in the current year
D-M, D/M The world
15 00:00:00 (midnight) on the 15th day of the
current month

Use the first three letters as an abbreviation for any day of the week and any month of the year.
For example:
Expression Meaning
thu 00:00:00 (midnight) on the most recent Thursday
MAR 00:00:00 (midnight) on the current day in March of the
current year

Time Offset
When specifying PI time use specific abbreviations that represent time units. These are used in
constructing Time Offsets as in the table.

Abbreviation Time Unit

s second
m minute
h hour
d day
mo month
y year
w week

Specify the abbreviation, the full time unit or the plural version of the time unit, such as s,
second, or seconds. Time offset is any of the time units with a valid value and a + or – sign
included, e.g. +8h.
Time offsets can be used alone in a time field or come with a fixed time or reference-time
abbreviation.
Time Offset Syntax

Reference Time or Fixed Time and Offset Expression

When included with a reference-time abbreviation or with a fixed time, a time offset adds or
subtracts from the specified time (indicated by either + or -) and a time unit with a value
Expression 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.) last Monday
sat-1m 23:59:00 (11:59 p.m.) last Friday
1-jan-20 – 1d Midnight 31 December 2019

Time Offsets Used Alone

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 Expression 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
Rules to Remember
Rule 1: You can only include a single time offset in an expression. Including multiple
offsets can lead to unpredictable results. For example, the following time expressions
are not valid:
*+1d+4h
t-1d+12h
Rule 2: To define a time offset you must include a valid value with any time unit. Only for
seconds, minutes, or hours, you can specify a fractional value. You cannot specify
fractional values for other time units.

Rule 3: A fixed timestamp consists of the fields of Year, Month, Day and Time (hours,
minutes and seconds). If any of these fields are not specified in the PI time expression,
the following values will be assumed by default:

 If Time is not specified, then the default value would be Midnight.

 If Day is not specified, then the default value would be Current Day.
 If Month is not specified, then the default value would be Current Month.
 If Year is not specified, then the default value would be Current Year.
Exercise – PI Time

Problem Description
Part 1 – Determine the “real” dates and times indicated by the PI Times in the table below:
Timestamp Input Meaning
* - 30m
y + 8h
T
Thu
Tuesday – 2d
18
y-2y

Part 2 – Express the following times in valid PI time expression:

Timestamp Input Meaning
Today at 6:00 AM
Monday at 6:30 am
12 hours ago
The first day this month
The end of the week (Friday morning)
7:00 am yesterday
15 minutes ago
First of March
25th of September 2014

Part 3 – List at least 4 ways you can “PI Abbreviate” 8 am today.

 Quick Check
Having completed this topic, are you able to:
 Understand PI time expressions?
 Explain the differences between fixed and reference times?
 Use time offsets?

If you answered NO to any of these questions, ask your instructor for assistance.
3 APPLYING CONCEPTS
LEARNING OUTCOMES

 Look at live data using PI Vision

 Build a basic display in PI Vision

Now that you understand the terminology and concepts associated with the PI System, it’s time
to start driving value from our client tools. Let’s demonstrate some of the concepts we discussed
and create a display of live data in PI Vision.

PI Vision - Browser based displays

PI Vision is a web browser-based application that lets you retrieve, monitor, and analyze
process information.

PI Vision allows users to:

 Search for and visualize time-series and other PI System data.
 Save displays for later use and further analysis.
 Reuse displays for multiple assets.
 Share displays with other members of a group or anyone with access to PI Vision.

PI Vision is supported by most modern browsers on a wide variety of computers, including

tablets and phones running iOS or Android operating systems.

Learning Outcomes:
 Create a PI Vision display.
 Use PI Vision symbols
 Demo future data
 Explain the search mechanism.
 Explain how to change the time range of a display.

To start using PI Vision, navigate to the PI Vision application server set up by your
administrator. In a default installation, the address is: https://webServer/PIVision where
webServer is the name of the PI Vision web server, for example https://pisrv01/pivision.
Drill Down Through the Assets in Your Plant

Ok, you need to quickly and easily get insight into the operational data stored in your PI System.
The 1st page displayed on the web server is the PI Vision homepage. Here you are able to view
the thumbnails of ‘All Displays’ that you can access; displays that you create as well as those
displays your colleagues create and share with others.

In this section the focus is on working with the native PI Vision displays. Below is a typical home
page for PI Vision.

To create a new display, click on and then start exploring the hierarchy of
the OSIsoft Plant, which is already set up as an AF database for you.

You can click on the arrow to the right of

‘OSIsoft Plant’ to start inspecting.
Drill through your AF Asset hierarchy
by clicking on the black arrows to find
assets in the plant. Notice the
hierarchy of assets displayed on the
left.

Once you click on an asset of interest,

say Storage Tank1, the Attributes list
populates below the Assets’ list…

Click a symbol, then drag and drop an

asset or attribute to the display area to
create a display. You are then able to
add other attributes or assets to this
symbol.

Change the start time Change duration of display Change the end time

Shift backward in time Set the display to end now

Explore PI Points, AF Attributes, and Related Assets in PI Vision

Directed Activity – Up close and personal with PI System Data through PI Vision

Objectives
 Create components of a PI Vision display

Problem Description
You want to see the following critical measurements of Mixing Tank1 from your home computer!

Measurement Display Symbol

Pressure Radial Gauge

Mixing Tank1

Level
Trend
Level_Forecast
External Temperature Value

Product
Table
Density

Approach
Step 1 : Open your web browser to the PI Vision homepage
Step 2 : Create a new display with
Step 3 : Drill down through the hierarchy in AF Server PISRV1 and database OSIsoft Plant to
determine the assets and their attributes.
Step 4 : Drill down to Mixing Tank1. Select the Radial Gauge icon and drag the Pressure
attribute to the display area to create the radial gauge.
Step 5 : Select the Trend icon and drag the Level and Level_Forecast to create a trend.
Right click and choose Format Trend, change the colours of the trend cursors.
Step 6 : Change the end time of the display to ten minutes in the future from now. Change
the start time of the display to the start of the work week (Monday at 8 am).
Step 7 : Select the value icon and drag the External Temperature to create the value.
Step 8 : Select the table icon and drag the Product and Density to the display area.
Step 9 : Change the start time of the display to start yesterday at 8 in the morning.
Step 10 : For fun - Add the Installation Date to the table; then remove it via the Configure
Table… pop up.
Alternative Approach (PI Points ONLY)

Objectives
 Create the same PI Vision display using only PI Points (not with AF Attributes)

Problem Description
Your company has not set up an Asset Framework hierarchy (yet!). Create the same display
you made before, but only use PI Points instead of the AF attributes. Thankfully, your colleague
has identified the PI Points that you need to use in the dashboard and has filled in the below
table for you:

Measurement PI Point Display Symbol

Pressure VPSD.OSIsoftPlant.PL1.MXTK1.Pressure Radial

Gauge
Mixing Tank1

Level VPSD.OSIsoftPlant.PL1.MXTK1.Level
Trend
Level_Forecast VPSD.OSIsoftPlant.PL1.MXTK1.Level_Forecast
External VPSD.OSIsoftPlant.PL1.MXTK1.External Value
Temperature Temperature
Product BCS1717
Table
Density 4321 g/L

Approach
Step 1 : Open your web browser to the PI Vision homepage
Step 2 : Create a new display with
Step 3 : Find the PI Points by drilling into the Data Archive and search
for the names listed in the table above.
Step 4 : Select the Display Symbol, then drag and drop the PI Point onto your display.
Step 5 : Repeat steps 3 and 4 for all measurements/symbols required.
Step 6 : Product and Density are not from PI Points. Use text fields for these items.

Discussion Questions:
1. How likely is it that you will know (or be given) every PI Point name you need to work with?
2. Your boss sees your great work and says that MixingTank2 should have the same display,
how do you build out another display for the second mixing tank?
3. Next week, you know that the products in your mixing tanks will change. How would you
get this new information onto your display without the use of Asset Framework?
Viewing Events in PI Vision
Learning outcomes
 Understanding Event frames

Tracking Important Events with PI

Events are important process or business time periods representing something happening that
impacts your operations. Capturing important events, and collecting relevant data concerning
those events can help analyse why they occurred. You may monitor events to identify
possible causes or potential points of failure such as:
 Asset downtime  Operator shifts
 Process excursions  Product tracking batches
 Equipment start-ups and  Environmental monitoring
shutdowns excursions
In the PI System, such events are known as Event Frames. With Event Frames, you can
capture, store, find, compare and analyse events and their related data. With Event Frames you
are able to analyse PI data in the context of the events rather than in continuous time periods.
Instead of searching by time, Event Frames lets users easily search the PI System for the
specific events they are interested in.
An Event Frame is defined by three characteristics:
1. Name: each event frame name must be unique and often includes a time stamp
2. Start time and End time: defines the event’s time range
3. Context: one or more event attributes and referenced AF elements
There are two categories of events that would fit an event frame profile:
“Good” events: Events that you want to track as a normal part of business such as product
tracking, shifts, asset stops and starts, and so on.
“Bad” events: Events that are unexpected and need to be analysed, such as unexpected
shutdowns or excursions. These are events that you want to track and report.
The following questions may help identify events or conditions that should be tracked:
Q1. What are all the times that event X occurred on this type of asset?
Q2. Do I want to associate data from different points over a given time?
Q3. What is the associated data for a particular time period when a problem occurred, or may
occur in the future?
Q4. What are the critical process events of which someone needs to be notified?
Retrieving and Visualising Event Frames

Just as elements allow you to collect and store data about assets, event frames allow you to
collect and store data about events. Use asset analytics to track your events using event
frames. PI Datalink and PI Vision are client tools that support event frame visualization, along
with PI System Explorer.
Following is an explanation of the tools:
PI DataLink: Import event frames from AF into Excel and then create reports for viewing
and analysing those events. Pivot tables and pivot charts are Excel features that can be
used to summarize the data and get a better insight into event frames.
PI Vision: Event frames related to assets on a display are discoverable by PI Vision.
The time range and duration of the display determine which events are shown in the
events list. You can compare similar events to each other using Gantt charts and trend
overlays.
PI System Explorer: An administrative utility mainly for working with Asset Framework.
It allows for an easy interface to search for events and analyse 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.

Advantages of Event Frames

Features of Event Frames are:

Features Advantage of the feature

 Reference multiple elements within the same event.

 Support multiple overlapping events on an AF
Flexibility element.
 Capture any event; a "batch" is one type of event that
may be captured.

 Search by time range, type of event or event frame

Easy search
attribute.

Scalability  Event Frames are extremely scalable

Directed Activity – Process Downtime

Objectives
 Find an asset’s related events.
 Use PI Vision to analyse important events.

Problem Description
Build a display in PI Vision to analyse the out of control events.

Approach
Step 1 : Open the Tank Details Solution display.

Step 2 : Click on the Events button to find all related events to Mixing Tank1
Step 3 : Select the most recent closed event for Mixing Tank1. Note what the Reason Code
of this event is. ______________
Step 4 : Right-click on the name of the most recent Downtime event, select Event Details to
see the end values of the Attributes. What was the Flow Rate when the Event
Frame ended? ___________
Step 5 : Based on the list of the values of the data items find the temperature difference
related to the most recent downtime event. ________________
Step 6 : Right-click on the name of the most recent downtime event again, select Compare
Similar Events by Type. Which event was the longest? What time did it start?
______________
Step 7 : Pin a reference event and change the search criteria to include all tanks.

 Quick Check
If you don’t understand:
 Retrieving Events
 Finding Related Events
 Comparing Events
 ‘Pinning’ Events

then please seek help from your instructor.

4 HOW OSISOFT SUPPORTS YOU
LEARNING OUTCOMES

 Demo the OSIsoft Learning Platform

 Explore the OSIsoft Learning YouTube Channel
 Introduce PI Square and the Customer Portal

Learning Platform @ learning.osisoft.com

The best place to learn more about the PI System is through the OSIsoft Learning platform. We
have curated our online courses, instructor-led training, and hands-on labs in an easy to browse
website, so you can keep learning about the PI System long after PI World concludes.
The platform is separated into learning paths, and for beginners, we suggest the User path.
Online Courses
Take a few minutes to click into the different learning paths and see the types of online courses
offered for:
 Users – who need to see the data in real time, or build reports with PI System data;
 Administrators – who keep the data flowing and support end users. These courses dive
into the backend components of the PI System;
 Developers – who write code to interact with the PI System programmatically;
 Power Users – who are adept with the basics of the PI System and can boost their
organization’s efforts through building an enhanced Asset Framework structure.
Our online courses cover a wide range of topics and are on-demand. When you sign up for an
online course, you will immediately gain access to the course material for 30 days along with a
Training Cloud Environment for you to practice the concepts discussed in the course.
You can also purchase a Training Cloud Environment separately from the courses if you want a
place to explore the PI System outside of your company’s production environment; however, we
recommend using your own development system whenever possible to create meaningful
results with your company’s data as you learn from our online materials.

Classroom Courses
If you prefer a classroom setting, you will want to check out our instructor-led Classroom
Courses. We have a number of training centers around the world for you to visit, so pick a
location that is convenient for you (or combine some PI education with a vacation)!
To browse the available training centers and courses, follow these steps:
1. Click on “All Content”
2. Use the filter on the left to select “Classroom” under “Content Type”
3. Expand the “Location” category to browse our training centers
4. View the available courses offered at your selected location
a. Some training locations offer course taught in languages other than English, feel
free to use the “Language” filter to further refine your course options.
5. Click on the course that matches your interest and follow through registration

If you want to view the course calendar, you can click on the calendar icon
in the All Content page.
OSIsoft Learning YouTube Channel @ youtube.com/OSIsoftLearning
Visit our YouTube Channel to Learn about the PI System by watching any of our 1000+ free
videos on You Tube!
Playlists for various topics are available to help guide you through your training topic of choice
from start to finish.

Exercise – Search the OSIsoft Learning Channel

Objectives
 Find a video on the OSIsoft YouTube Learning Channel to learn about a topic not
covered in the Visualizing PI System Data Course
 Demo accessibility features and playback settings in YouTube
Problem Description
You want to learn how to navigate a PI Vision display and make use of Ad-Hoc trending
functionality.
Approach
Step 1 : Use a web browser to navigate to YouTube.com
Step 2 : Search for the OSIsoft Learning Channel
Step 3 : Run a search to find a video about migrating PI ProcessBook displays to PI Vision,
sample search: “PI Vision” or “ad hoc trending” or search for any other topic of
interest to you.
Step 4 : A video covering the utility is “PI ProcessBook to PI Vision Migration Utility”
Step 5 : Turn on the Subtitles by clicking on the button
Step 6 : Change the quality of the video by clicking on the Settings icon
Step 7 : While in Settings, choose Subtitles and notice
that you can have Google auto-translate to the
language of you choice AND you can submit
subtitles in other languages for the OSIsoft
YouTube team to review
Step 8 : To get notified when OSIsoft releases new
videos, make sure to and click on
the bell icon for updates
Directed Exercise – Find a playlist on YouTube

Objectives
 Search the OSIsoft YouTube Learning Channel for a playlist that interests you
 Use the playlist links to share structured content with your colleagues
Problem Description
You want to learn as much about a product as possible, or you want to audit an online course
for free.
Approach
Step 1 : Use a web browser to navigate to YouTube.com
Step 2 : Search for the OSIsoft Learning Channel.
Step 3 : Identify several playlists on the channel’s “Home” tab.
Step 4 : Click on the PI Vision Playlist.
Note the playlist sidebar on the right side of
the page. Now you can click into several
related videos.

Step 5 : Share the URL for the video with a colleague by selecting the entire URL on your
page. If you use the share button on the video, it does not share the entire playlist.
Step 6 : Go back to the OSIsoft Learning channel homepage by clicking on the channel icon
below the video player.
Step 7 : Scroll down until you see the section titled “Audit our Online Courses” and click on
the title.
Step 8 : Take note of all the free online course videos that you can view and share after PI
World with your team!

Follow up: What are 2 ways you can find playlists on the OSIsoft Learning YouTube Channel?
myOsisoft.com and the Customer Portal @ customers.osisoft.com
The myOSIsoft.com website has a lot of tutorials on how to do support related activities as well
as quick links to take you to commonly used support pages:
Login to Customer Portal Customer Portal How To's Partner EcoSphere
See Your Downloads How to Get an OSIsoft OSIsoft Partner Portal Login
Customer Portal Login
Create a New Case OSIsoft Partner Portal
How to Create a New Case How To's
View your Cases
How to Download Products Partner Access to Customer
Use the Enhanced Search
Portal
How to Search for Articles
See your Upcoming Services
OSIsoft Partner Marketplace
How to Manage Users
Manage Your Team
Partner Accreditation

And from the Customer Portal, you can:

 Download any PI product your company is licensed for using.
 View the PI System Roadmap to get information about the most current releases and
what new features and products are on the horizon.
 Login and view your open and previously closed Support Cases or create a new one.
 Search through our Knowledge Base to try and troubleshoot any issues you may be
having by referring to the rich collection of available KB Articles.

Here are the general phone number and email address for the OSIsoft Technical Support:
Phone: +1 510 297-5828
E-mail: techsupport@osisoft.com

Support may be provided in languages other than English in certain centres based on
availability of attendants. If you select a local language option, we will make best efforts to
connect you with an available Technical Support Engineer with that language skill. If no local
language techsupport engineer is available to assist you, you will be routed to the first available
attendant.
Before you contact Technical Support, it is helpful to have certain information readily available.
OSIsoft technical support engineers will ask:
 name of the product
 version number
 the time that the difficulty started
 the computer platform (CPU type, operating system, and version number)
PI Square – The online PI System Community @ pisquare.osisoft.com
PI Square is OSIsoft’s community where you can get Technical Support for your questions,
access the PI Developers Club (PI DevClub) for your coding projects, and connect to PI
Systems users worldwide to get more value out of your PI System.
The PI Square community has places you go to collaborate, called Spaces. These spaces are
generally named for a specific topic or purpose. Each space can contain multiple types of
content, including discussions, documents, blog posts, polls, and more. Currently, PI Square
has the following four spaces:
 All Things PI - A general forum where OSIsoft Technical Support will keep watch to help
answer questions and contribute to discussions. Use the product-specific spaces like PI
Server or PI Visualization to find relevant content for whatever your needs may be.
 PI Developers Club - Here we have tools and support for developers to create applications
for the PI System.
 Learn PI - Our hub for students to interact and learn from each other while they pursue
certificates in our on-demand online courses.
 PI Square Groups – Join a group that speaks to your specific industry’s needs and learn
from others in your field of their recommended best practices for projects on your horizon.

Exercise – Navigating PI Square

Objectives
 Create a PI Square SSO Account and find answers about Visualization topics
 Discover the online course forums
Approach – Part 1
Step 1 : Using a web browser, navigate to the PI Square website:
https://pisquare.osisoft.com
Step 2 : Log in to the PI Square community
a. If you don’t have an OSIsoft SSO account, create one now. You’ll use the same
account for PI Square, the OSIsoft Learning platform, and the Customer Portal.
Step 3 : Search for a post for each of the topics:
a. Future Data in PI DataLink | URL Parameters in PI Vision
Step 4 : Read through past posts, comment, or ask your own question.
Approach – Part 2
Step 5 : Navigate to the “Learn PI” space either by clicking on Spaces>Learn PI in the page
header, or by clicking on “Online Courses” from the homepage.
Step 6 : Click on “Visualizing PI System Data with PI Vision” under the “User” learning path.
Step 7 : Explore the questions posed and the answers given by the community for our on-
demand Online Courses.
© Copyright 2020
OSIsoft, LLC
PI Vision: Basics

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved.

AVEVA, the AVEVA logos and AVEVA product names are trademarks or registered trademarks of aveva group plc or its subsidiaries
in the United Kingdom and other countries. Other brands and products names are the trademarks of their respective companies.

AVEVA Group plc

High Cross, Madingley Road
Cambridge CB3 0HB, UK
Tel +44 (0)1223 556655
Fax +44 (0)1223 556666

aveva.com
Page 2 of 84
 Page 3 of 84

Table of Contents

Contents
Table of Contents .................................................................................................................................................................... 3
Introduction ............................................................................................................................................................................ 5
Objectives................................................................................................................................................................................ 5
Your PI System ........................................................................................................................................................................ 5
Approach ................................................................................................................................................................................. 6
PI Vision Introduction.............................................................................................................................................................. 7
PI Vision Home Page....................................................................................................................................................... 7
PI Vision Display Modes ................................................................................................................................................. 7
Asset Pane & Events Pane .............................................................................................................................................. 7
Challenge 1: Create an Overview Display ............................................................................................................................... 9
1.1: Prepare the Display .................................................................................................................................................... 10
1.2: Add PI Data................................................................................................................................................................. 12
1.3: Configure Multi-Stating.............................................................................................................................................. 15
Challenge 2: Create a Well Pad Drill-in Display ..................................................................................................................... 18
2.1: Prepare the Display .................................................................................................................................................... 19
2.2: Add PI Data for the Well Pad ..................................................................................................................................... 20
2.3: Add PI Data for the Well Pad’s Wells ......................................................................................................................... 22
2.4: Create a Collection ..................................................................................................................................................... 24
Challenge 3: Modify an Existing Oil Well Display .................................................................................................................. 25
3.1: Find and Copy the Migrated PI ProcessBook Display ................................................................................................ 26
3.2: Modernize Gauge Symbol and Update XY Plot .......................................................................................................... 27
3.3: Introduce Downtime Event Tracking ......................................................................................................................... 28
Challenge 4: Explore new options to work with symbols in PI Vision .................................................................................. 33
4.1: Create a display with multiple time ranges ............................................................................................................... 34
4.2: Explore the new configuration options for trends. ................................................................................................... 36
4.3: Hide Status Message .................................................................................................................................................. 39
4.4: Create a Bar Chart Symbol ......................................................................................................................................... 41
Challenge 5: Calculations ...................................................................................................................................................... 47
5.1: Add Minimum and Maximum values from an existing Calculation ........................................................................... 49
5.2: Edit a Calculation ....................................................................................................................................................... 51
5.4: Create and Use an Asset-based Calculation .............................................................................................................. 53
 Page 4 of 84

(Optional) Challenge 6: Link displays together ..................................................................................................................... 55

6.1: Update the North Dakota Overview Display.............................................................................................................. 56
6.2: Update the Well Pad Detail Display ........................................................................................................................... 57
6.3: Update the Oil Well Detail Display ............................................................................................................................. 58
6.4: Experiment with URL Parameters .............................................................................................................................. 60
(Optional) Challenge 7: Collection Search Criteria................................................................................................................ 61
7.1: Filter Collection Assets with Asset Attribute Criteria................................................................................................. 62
(Optional) Challenge 8: Ad Hoc Analysis ............................................................................................................................... 64
8.1: Explore the Ad Hoc Workspace.................................................................................................................................. 65
8.2: Add Data from Multiple Sources to Ad Hoc Workspace ............................................................................................ 66
8.3: Export Ad Hoc Workspaces ........................................................................................................................................ 68
(Optional) Challenge 9: Compare Downtime Events ............................................................................................................ 69
9.1: Compare Events from the Event Details View ........................................................................................................... 70
(Optional) Challenge 10: Manage PI Vision Displays and User settings ............................................................................... 72
Role-Based User Access ................................................................................................................................................ 72
Display Folders ............................................................................................................................................................. 72
10.1: Finding and Categorizing Displays............................................................................................................................ 73
10.2: Controlling Access to a Display ................................................................................................................................ 74
10.3: Organizing Displays with Folders ............................................................................................................................. 75
Appendix ............................................................................................................................................................................... 77
Interacting with Data Symbols ..................................................................................................................................... 77
References ............................................................................................................................................................................ 83
 Page 5 of 84

Introduction
In this session we will use the latest features of the PI Vision 2019 in order to build extensive, rich, and
informative displays. We will be heavily leveraging PI Asset Framework throughout this lab in order to
showcase the incredible strengths and abilities of the latest release of PI Vision. We will investigate
new PI Vision features by building five main displays and by covering the basic display management
and administration tasks.

Objectives
The following goals will be accomplished upon finishing the lab:
• Understand how to search for important Events, PI Tags, and AF Elements and Attributes
using the PI Vision Search Pane
• Familiarization with all key features available in PI Vision 2019, especially the new Ad Hoc
Trending and PI ProcessBook Display Migration
• Understand the importance and use of each of the eight main symbols. Understand how
they can be used to work together in order to display data quickly, easily, and efficiently
• Utilize templates in AF to create one display that may be reused with many different assets
• Be able to perform simple PI Vision Administrator tasks

Your PI System
This lab uses a simplified PI system including the PI Data Archive, PI Asset Framework, and PI Vision all
bundled together on one production server. Each student will have their own client machine to access
PI Vision remotely. Each client machine is deployed using a Microsoft Azure environment so we will
connect to them using Remote Desktop.

The servers of importance are:

• PISRV01
o PI Data Archive 2018 SP3
o PI AF Server 2018 SP3
o PI AF Client 2018 SP3
o PI Vision 2020
o We will not have direct access to this machine
• PICLIENT01
o Server to make client connections to PI Vision
o Shortcut to open PI Vision is available on Desktop
o PI ProcessBook 2015 (will not be used in this lab)
o PI ProcessBook to PI Vision 2020 Migration Utility (will not be used in this lab)
 Page 6 of 84

Approach
TechCon Labs, LLC has had the PI System for years but has just recently starting using PI Vision. So far,
they have only used PI Vision as a tool to view Imported PI ProcessBook Diplays.

You have been hired as a consultant by TechCon Labs, LLC to help them get the most value out of their
PI System and visualize their data accordingly. TechCon Labs, LLC needs a quick and efficient way to
monitor their 60 Wells, 27 Well Pads, and eight Production Areas. They estimate that you’ll need to
create around 100 displays, and they have allotted two full weeks for the job.

As an expert on PI Vision you will help TechCon Labs, LLC build displays that showcase important
events and data within the company. With your in-depth knowledge of PI Vision as well as your
comprehensive understanding of element and attribute templates within AF, you know that you’ll
only need to create 5 displays and that it should take just under three hours to complete.
 Page 7 of 84

PI Vision Introduction
TechCon Labs, LLC would like a quick PI Vision introduction before you build all of their displays. Once
all of the content is created, they want to make sure that everyone has a general idea of how to
navigate PI Vision and create simple ad-hoc displays.

PI Vision Home Page

The home page is the starting point for PI Vision navigation. From here you can create displays as
well as browse through your own and public displays:

PI Vision Display Modes

There are two separate modes within PI Vision. You can only build and edit displays while in Design
Mode. Look for the ruler and pencil icon in the top right corner of the toolbar. When in Design
Mode this icon, as well as the border of the display, will be highlighted in orange:

Monitor Mode:

Design Mode:

Asset Pane & Events Pane

The Asset Pane is used to find AF Elements and Assets as well as PI Points. AF Attributes can be
found in the Attributes section. If the particular asset you are working with has related events they
will be populated in the Events Pane:
 Page 8 of 84

Note:

In this lab we will be working with the Oil Well Production AF Database on the PISRV01 AF Server.
The Assets viewable in the PI Vision Search Pane are AF Elements created with PI System Explorer.
The AF Structure has been built prior to beginning work on the PI Vision displays, which is
recommended in order to take advantage of PI Vision’s most powerful features.

Each element can have its own set of permissions, which is also enforced within PI Vision.
 Page 9 of 84

Challenge 1: Create an Overview Display

TechCon Labs has identified production within the state of North Dakota as a strategic area to monitor
in the next several months. The TechCon Labs management team has requested a dashboard from
which they can see any under-performing Well Pads or Oil Wells within the state at a single glance. If
management is impressed by the resulting dashboard, they plan to approve additional project
resources to continue the project.

Below, the team has provided an illustration of what they would like this overview display to look like:
 Page 10 of 84

1.1: Prepare the Display

1. On the PI Vision Homepage, click the New Display button at the top right-hand side of the
screen.
2. Right-click anywhere on the background of the display and select Format Display… to open
up the configuration pane.
3. Open the Background drop-down color selector and choose the white background:

4. Click the Image button on the toolbar:

5. Click and drag to outline most of the display area, and then click Choose File:

6. Select the file C:\Class Files\north_dakota.gif from the file explorer. If you do not see the
image in this folder, please let your instructor know.
7. Click on the Save button in the top right of the browser window:
 Page 11 of 84

8. Select the Display Folder for your user account:

9. Save the display with the name North Dakota Overview followed by your student number.
For example: North Dakota Overview_Student##.
10. Click the Design button (ruler and pencil) to place the display back into Design Mode:

Note:

The workbook does not explicitly call for the display to be saved again until it is completely
finished.
However, it is a good idea to make incremental saves after every couple steps to make sure no
work is ever lost. This can be done at any time by clicking the Save button again.

11. Click the Text button on the toolbar:

12. Click on the upper right area of the state image and type “North Dakota Production” in the
Format Text field of Configuration Pane.
13. In the same Configuration Pane, set the Font Size to 28.
 Page 12 of 84

1.2: Add PI Data

1. In the Asset Pane to the left of the display workspace, find the Oil Well Production database
and click on the rightmost “>” to drill down into the database. On the first level of the
database, find and click on the North Dakota element. If the Asset Pane is collapsed, click
on the Assets icon to expand it (see Asset Pane & Events Pane section for a refresher).

2. Verify the Trend symbol type is highlighted, and click and drag the Avg Production Rate
attribute on the display to fill the area below the text symbol that reads “North Dakota
Production”.
3. Right-click on the symbol and select Format Trend.
4. Change the Background from very light grey to white

5. Resize the trend to only occupy a narrow band below the display title in the top right corner
of the North Dakota outline:
 Page 13 of 84

6. Drill down into the North Dakota and Crosby elements in the Asset Pane to find Well08 and
click on it.
7. Below the Asset Pane under Attributes, find the Location, City attribute:

8. Select the Asset Comparison Table symbol and then click and drag the Location, City
attribute onto the bottom right area of the North Dakota state outline on the display:

9. Right-click on the table symbol and select Configure Table…:

10. Under Additional Attributes, select Production Rate and click the upwards pointing arrow to
add an additional attribute column:

11. Repeat the previous step (10) for the Total Downtime and Weather attributes to add a
fourth and fifth attribute column to the table.
12. In the Style section of the configuration pane, select the middle option to use a light color
scheme

13. Resize the symbol area and the table columns so that no text is cut off either in the column
headers or in the data cells.
14. In the configuration pane, highlight the Production Rate column and click the Show Units
checkbox:
 Page 14 of 84

15. Repeat the previous step (14) to show units for the Total Downtime attribute column as
well.
16. Right click on the Asset Comparison Table symbol and select Add Dynamic Search Criteria…

17. Modify the Search Root to include all of North Dakota and click the checkbox to Return All
Descendants. Then, click Refresh:

18. Resize the symbol again so that all rows are shown and there are no scroll bars.

Note:

The icons in the Weather column can be clicked to open a link containing weather information
for the appropriate city. Behind the scenes, this is an AF Attribute that contains a URL as its
value.
 Page 15 of 84

1.3: Configure Multi-Stating

1. Right-click on the Asset Comparison Table symbol and select Add Multi-State…:

2. In the Configuration Pane, select Production Rate and select Enable Multi-State:

Note:

You may notice this checkbox is grayed-out in some of the other columns. This is because
attributes must contain numeric values or be configured with digital states to be eligible for Multi-
Stating.

3. Modify the State colors so low values are shown in red and high values in green with a color
gradient in between:
 Page 16 of 84

4. On the left-hand side of the display, open the Graphic Library locate the Plant Facilities
section. Select the Oil Well graphic:

5. Draw the Oil Well graphic next to Dickinson on the map:

6. Right-click on the graphic and select Configure Multi-State…

7. Drill down into the North Dakota element in the Asset Pane and highlight Dickinson.
8. Click and drag the Avg Production Rate attribute under the Multi-State Attribute header in
the rightmost configuration pane.
9. Repeat step 3 to modify the State colors so low values show in red and high values in green.
10. Select the Oil Rig graphic on the display and click Copy on the toolbar

11. Click Paste four times

Note:

The keyboard shortcuts Ctrl + C and Ctrl + V may also be used to copy and paste, respectively.

12. Click and drag the four new Oil Well graphics so there is one next to each production area
13. Repeat steps 6-9 to replace the Multi-state Attribute with the Avg Production Rate for the
corresponding production area (Crosby|Avg Production Rate, Kenmare|Avg Production
Rate, etc).
 Page 17 of 84

Note:

Be sure to replace the Multi-State data item rather than removing the existing item (using the
trashcan graphic) and adding the new one. If the item is removed, the Multi-State colors will need
to be re-configured each time.

14. Open the Asset drop-down menu on the top of the display and then click the configure
button

15. Under Configure Context Switching in the configuration pane, select Do not show:

Note:

Since this is an overview display, we are hiding the context switching menu. This display is
designed to always show the same data items. We will later be creating other displays that are
meant to have a swappable asset context, and therefore will have the menu enabled.

16. In the top right corner, click the Save button:

 Page 18 of 84

Challenge 2: Create a Well Pad Drill-in Display

The TechCon Labs management team has taken a look at the North Dakota dashboard and they think
this PI Vision project has potential. However, they would also like to have a more detailed dashboard
for each well pad.

Below, the team has provided an illustration of what they would like these well pad displays to look
like:

Since there are five different production areas and each one has a variable number of oil rigs, the
executive team has allotted a week to build a specialized display for each area. However, because you
are familiar with the latest collection and asset-relative functionality in PI Vision, you believe you can
satisfy the design requirements with a single display.
 Page 19 of 84

2.1: Prepare the Display

1. On the PI Vision home page, click the New Display button at the top right-hand side of the
screen

Note:

At any time, you may return to the PI Vision home page by clicking on the PI Vision logo in the top
left of the page. But please remember to save the display you are currently working on as any
unsaved changes will be lost.

2. Right-click anywhere on the background of the display and select Format Display to open up
the configuration pane.
3. Change the display Background color from the default dark gray to white:

4. Highlight the Text button on the toolbar and then click on the top middle area of the display
and type “Well Pad Detail” under the Format Text header in the configuration pane.
5. In the same Configuration Pane, set the Font Size to 26.
6. Click on the Save button in the top right of the browser window.
7. If it is not already selected, click on the Display Folder for your user account

8. Save the display with the name Well Pad Detail followed by your student number. For
example: Well Pad Detail_Student##.
 Page 20 of 84

2.2: Add PI Data for the Well Pad

1. Click the Design button to place the display back into Design Mode

2. Drill down into the North Dakota element under the Oil Well Production database in the
Asset Pane and find the Crosby element:

3. Select the Value symbol type at the top of the search pane:

4. Click on the Well Pad Name attribute and drag it onto the display below the “Well Pad
Detail” text symbol.
5. Right-click on the value symbol and select Format Value…

6. Expand the Visibility section of the configuration pane and deselect Label, Units, and
Timestamp. We only want to display the name of this well pad:

7. With the Value symbol still highlighted, click on the Production Area Name attribute and
drag it onto the display below the “Well Pad Detail” text symbol and to the right of the well
pad name.
8. Right-click on the value symbol and select Format Value…
9. Repeat step 6 to remove the Label, Units, and Timestamp from the Production Area Name.
10. Select both Value symbols by holding the Ctrl key and clicking on each in turn.
11. Right-click on either of the symbols and select Format Symbols…:

12. In the Configuration Pane, set the Font Size of both symbols to 20.
 Page 21 of 84

13. With both value symbols still selected, click the Align Top option in the Arrange dropdown
menu on the toolbar. This will adjust the vertical positions of all currently selected symbols
to align to the top of the topmost symbol in the selected group:

14. From the Shape dropdown menu on the toolbar, select the Rectangle:

15. With the rectangle shape selected, click and drag on the display to draw a rectangle around
the two existing Value symbols.
16. In the Arrange dropdown menu, select Send to Back to move the rectangle underneath the
two Value symbols:

17. Expand the Shape dropdown menu on the toolbar and select the Line.
18. While holding down Shift, trace a line to divide the rectangle into two sections containing
one value symbol each:

Note:

Holding down Shift while drawing will cause the Line shape to “snap” to the closest 45° angle.
 Page 22 of 84

2.3: Add PI Data for the Well Pad’s Wells

1. Drill down into the North Dakota and Crosby elements under the Oil Well Production
database in the Asset Pane and find the Well08 element:

2. Verify the Value symbol is still selected:

3. Find the Well Name attribute and drag it onto the display.
4. Right-click and Format [this] Value… to deselect the Label, Units, and Timestamp options
underneath the Visibility section of the configuration pane (see 2.2, steps 5-6 for a
refresher).
5. Copy this symbol and Paste it two times.
6. Find the Status Message attribute underneath Well08 in the Asset Pane. Drag it onto the
second Well08 Value symbol. The second Value symbol should now read the status message
rather than the well name:

7. Find the Avg 30d Downtime attribute underneath Well08 in the Asset Pane and drag it onto
the third Well08 Value symbol:

8. Right-click on the third value symbol and select Format Value.

9. In the Visibility section, check the boxes for Units and Label. Using the drop-down menu,
select the second label instance (where it only includes the name of the attribute and not
the name of the element):

10. Copy the Avg 30d Downtime Value symbol and Paste it one time.
 Page 23 of 84

11. Click and drag the fourth value symbols so there is no overlap

12. Find the Production Rate attribute and drag it onto the newly created fourth Value symbol.
13. Click and drag a selection box around the value symbols to select all four simultaneously.
14. From the Arrange dropdown menu, select Align Left. This will horizontally adjust the
position of all currently selected symbols to align with the leftmost symbol in the selected
group.
15. With all four of the symbols still selected, right-click any one of the symbols and select the
Group Symbols option:

16. Right-click on any of the four symbols again and select Format Symbols…

17. Set the Font Size to 14

18. On the left-hand side of the display, open the Graphic Library, find the Plant Facilities
section, and select the Oil Well graphic from Challenge 1 (page 21).
19. Draw the Oil Well graphic right next to the four values symbols that were most recently
added
 Page 24 of 84

2.4: Create a Collection

1. Select all of the Value symbols created in the previous section including the Oil Well graphic,
right-click on any one of those items, and select the Convert to Collection… context option:

2. Resize the collection area so that all Oil Wells can be show in a horizontal row

3. Open the Asset drop-down menu on the top of the display and then click the configure
button

4. Toggle the Context Switching option to use Show search results and verify that the North
Dakota element is set as the Search Root.
5. Open the Asset Dropdown menu and click Williston to change the display context

6. Save the display.

 Page 25 of 84

Challenge 3: Modify an Existing Oil Well Display

The TechCon Labs management team is again satisfied with your work and would like to take this a
step further. This time they have requested a dashboard for each oil well within North Dakota. There
is an existing PI ProcessBook display that served this purpose before and should be used as a model.
In addition to the items on that display, the dashboard must also include a way to view and classify
recent downtime events for the oil rig.

Management was surprised by the quick turnaround on the last stage of the project, but they still
figure so many displays will take at least a week to build. With your experience building the previous
two displays, you are confident that only a single display is needed here. To make matters easier, a
colleague of yours has already migrated the PI ProcessBook display into PI Vision. But they forgot to
transfer ownership of the display to you before they left for vacation! As a result, you’ll need to find
this migrated display and create a copy that you can adapt for downtime event analysis.

With your additions to the original display, the management team expects this display to look
something like the following:
 Page 26 of 84

3.1: Find and Copy the Migrated PI ProcessBook Display

1. Click on the PI Vision icon in the top-left of the browser window to return to the display
homepage.
2. Navigate to the Home folder at the top of the display folder navigation tree:

3. Find and open the display named Oil Well Detail located here.
4. In the top-left corner of the display, you should see the words “read-only” next to the
display name. No changes may be made to this copy of the display. Instead, an editable
copy must be made:

5. In the top-right corner of the display, click the dropdown next to the Save button and select
Save As:

6. Name the display something like Oil Well Detail_Student## and save it to your display
folder:

7. You are now the owner of an editable copy of this display. To further show this, you should
now see your saved display under My Displays:
 Page 27 of 84

3.2: Modernize Gauge Symbol and Update XY Plot

1. Click on the Design button in the top right corner of the window to switch to Design Mode

2. Right-click on the Vertical Gauge and select Switch Symbol to Radial Gauge

3. In the Visibility section, use the Label dropdown menu and select to show only the attribute
name:

4. Right-click on the XY Plot and select Configure XY Plot…

5. In the General section of the Configuration Pane, enable Engineering Units

 Page 28 of 84

3.3: Introduce Downtime Event Tracking

1. Open the Events Pane beneath the Asset Pane on the left-hand side PI Vision:

2. Click Edit Search Criteria:

Note:

By default, the Events Pane returns events active at any point between start and end time of the
display and related to any assets currently on the display.

3. Select Custom Time Range from the Time Range dropdown list, specify “*-2mo” (two
months ago) as the Start Time, and click Apply to save the changes:
 Page 29 of 84

4. Click Create Events Table and drag the resulting symbol beneath the Production Rate vs
Power Consumption trend:

5. In the Configuration Pane, deselect the columns Asset and Acknowledgement, and select
the columns Duration and Reason.
6. In the Style section of the Configuration Pane, Select the Light color scheme:

7. In the Edit Search Criteria section of the Configuration Pane, add an Event Name search
filter for “*Downtime*” and then click Apply:

8. Resize the Events Table symbol outline and columns so that no nothing is cut off or wraps to
the next line:

9. Place the Events Table symbol at the bottom of the display and adjust the position of other
symbols if desired.
 Page 30 of 84

Note:

If needed, the Zoom Out button is located in the bottom right of the display.

10. Right click on an Event in the table and select Apply Time Range to set the display Start Time
and End Time to match the downtime event:

11. Click the Pencil graphic in the Reason column for the same Event in the table, and then
expend the Reason hierarchy to select a Pump Breakdown as the reason for the downtime:

Note:

Setting the Reason Code in PI Vision saves the information on the underlying event. Going forward,
anyone that views this particular event will see an explanation of what caused the downtime.
 Page 31 of 84

12. Next, we will configure the asset list to limit the switch asset function to wells in North
Dakota. Open the Asset drop-down menu on the top of the display and then click the
configure button

13. Toggle the Context Switching to Show search results

14. Adjust the search root to “North Dakota” and enable Return All Descendants

15. In the Asset Type dropdown menu, select Well

16. Open the Asset dropdown menu and click Well02 to change the display context. The list now
only includes wells in the North Dakota region.
 Page 32 of 84

17. Since we cannot tell from the well name to which well pad they belong it would be nice to
have this information shown in the asset list. To show the path, open up the configuration
again and select Show asset paths.

18. The list will now show the path.

19. Save the display.

 Page 33 of 84

Challenge 4: Explore new options to work with symbols in PI Vision

You heard about some of the new options the most recent PI Vision versions have to offer and want
to try them out. In the past, the TechCon Labs management team has asked for displays showing
trends with different time ranges. Now it is possible to do this. You want to create a demo display to
show this and other new possibilities to the management.

You want to demonstrate the following features:

- You would like to display the Production Rate of Well08 in a trend covering the time range of
the display and at the same time see the data for the last 24 hours and for the current work
week in two separate trends on the same display.
- Set a descriptive plot title for each of the trends.
- Change the legend label to display the asset name instead of the attribute name.
- Place the scale labels outside of the plot area.
- Use data markers on a trend line.
- Change the grid style to use lines.
- Configure a status message to show up only when the status is different from Running.
- Create a Bar Chart symbol to see the Power Consumption of all wells and configure this for
context switching for the display.

The complete demo display should look something like the following:
 Page 34 of 84

4.1: Create a display with multiple time ranges

1. Create a new display.
2. Make sure the trend symbol is selected, then search for Well08 and drag the Production
Rate attribute on to the display area.
3. Drag Production Rate on the display two more times to create additional trends or copy and
paste the first trend.
4. Arrange the trends in one row on the display.

Tipp:

To arrange the trends on the display, you can use the new Snap to Grid function or select

the three trends and use the functions in the Arrange menu.

5. Right click the second trend and select the Configure Trend option.
6. Open up Time Range and select Duration and Offset. Make the Duration 24 hour and offset
0. This will result in a trend with the same end time as the first trend but with a start time 24
hours previously.

7. For the third trend, select Use custom time range. Specify Monday (or Mon) as the start
and * as the End.
 Page 35 of 84

Note:

To learn more about the options for entering the Start and End times see PI time on OSIsoft
Documentation.

8. After these configurations the display should look similar to the one shown below.
 Page 36 of 84

4.2: Explore the new configuration options for trends.

1. Under Trend Options, set a descriptive Plot Title for each of the trends, for example Last 24
hour Production Rate for the trend in the middle and Work Week Production Rate for the
third trend. For each title, press enter to confirm before you move on to the next trend.

Tipp:

If you need to make configuration changes to a couple of assets you can leave the configuration
pane open and select the next asset to change.

2. Since the plot titles are stating that we are looking at the Production Rate we do not need to
have this again in the legend. Instead, we would like to see the Well name in the legend.
Under Trace Options, expand the drop-down menu for Legend Label and select Well08.
 Page 37 of 84

3. To have a clear view onto the data at the start time of each trend we want to display the
Scale Labels outside of the plot area. Under Value Scales, click on the Scale Labels symbol for
Outside plot area.

4. For the trend using the display time range, we would like to display data markers on the line
trace. Under Trend Options, click the Traces symbol for Data markers.

5. Since time range of the work week trend will vary, we want to use a different grid style to
make this more apparent. Under Trend Options, click on the Grid symbol for Lines.
 Page 38 of 84

6. After these configurations your display should look similar to the one shown below.
 Page 39 of 84

4.3: Hide Status Message

You have heard that PI Vision 2020 also introduced the option to hide symbols using the
Multi-State functionality. You want to make use of this for displaying the Status Message on
the display only when it is in any other State than Running.
1. Select the Value symbol and drag the attribute Status Message onto the display. Adjust the
size to make it clearly visible on the display. In the Format Value menu under Visibility
uncheck all but Value.

2. Right click on the symbol and select Add Multi-State. The color of the states should apply to
the Value only. Under Property, select Value from the drop-down menu.

3. Under States, click on Running and tick the check box for Hide.
 Page 40 of 84

4. The value Running is shown again in the original color as long as we are in Design mode.

5. Click on Modify Display to exit Design mode to see that the value is not shown any more
when the attribute is in the state Running.
 Page 41 of 84

4.4: Create a Bar Chart Symbol

Next, we want to create a Bar Chart symbol to get an overview of the current production rate of all
our wells. We will also configure this symbol for easy asset switching of the display.

1. Click the Design button (ruler and pencil) to place the display back into Design Mode.

2. Select the Bar Chart symbol and drag the attribute Production Rate onto the empty
right side of the display. You will get a Bar Chart displaying one bar for the currently selected
well.

3. To include all other wells, right click on the symbol and select Add Dynamic Search Criteria.
4. Delete the current Search Root “North Dakota\Crosby” and leave the field blank to search
from the root level down. Tick Return All Descendants.
5. By default the maximal number of results returned is limited. To see all wells, increase the
Number of Results to 100. Since there are so many bars, there is no space for labeling and
we only know by hovering over the individual bars which assets they belong to.
 Page 42 of 84

6. To get a more condensed chart showing only what is important, we will modify the search
criteria to only show badly performing assets. We will define this here as assets having a
current Production Rate of less than 600.

7. By resizing the symbol, we might be able to see asset names, but as shown below, the space
on the display might be too tight to display everything. We will go into further configuration
to fix this in the next steps.

8. Right click the symbol and select Format Bar Chart.

 Page 43 of 84

9. First, we will change the Orientation to better use the space on the display. Select
horizontal orientation and switch the grid style to bands.

10. Again you might need to adapt the size of the symbol to see the labels. In the picture below,
I have now been able to fit the labels in completely. But in fact there is a lot of information I
would not need here.
 Page 44 of 84

11. In the Visibility section, we can deselect Value. We want to keep the label, but we can make
it simpler. In the Style section we can select what is shown as Bar Label. Select Asset since
the Well name will be sufficient.

12. To still keep the information which attribute is being displayed, we can add a title.

13. Since we have limited the maximum of the Production Rate being displayed, it makes sense
to adapt the Scale Range accordingly. Open up the Scale Range section and choose Custom
limits. Set 600 as the Right limit.
 Page 45 of 84

14. For a better visual distinction between the performance levels, we can add multi-state
functionality to the symbol. Right click the symbol and select Add Multi-State or Bands. You
can change the limits and colors, for example as shown below.

15. As a last configuration step, we want to use the Bar Chart for swapping assets on the display.
Right click on the symbol and select Add Navigation Link. Select Change context of current
display and Use current asset as root.
 Page 46 of 84

16. Save the display as Vision Demo_<your initials> and exit the Design Mode to test the
functionality. When you click on one of the bars, the trends and the Status Message value
symbol will change the context to the asset selected.
 Page 47 of 84

Challenge 5: Calculations

Part 1: Tag-based Calculations

The team at the Crosby site is still using displays which are based on PI Tags. Originally those were
migrated PI ProcessBook displays containing PI Calculation data sets. Through the migration to PI
Vision displays the data sets became PI Vision Calculations. The team has asked you to perform some
modifications on the Crosby Power Consumption display.

- Make use of the existing PI Vision Calculations and add the minimum and maximum values to
the trends.
- Instead of the 1 hour Calc Interval you want to see the calculation results for each shift. Edit
the calculation to set the Calc Interval to 8 hours, enable the Sync Time and set it to 06:00:00
to match the shift schedule with 8 hour shifts starting at 6 am.

The result should look similar to the picture shown below.

 Page 48 of 84

Part 2: Asset-based Calculations

Your manager wants you to create a display showing the Casing Temperature and the Tubing
Temperature and the difference between the two together in a trend. No analysis exists to calculate
the difference and you do not have the rights to create one. Furthermore, this calculation would not
be used anywhere else so you do not want to bother the PI Admin with this and decide to use PI Vision
Calculations instead.

The result should look like this:

 Page 49 of 84

5.1: Add Minimum and Maximum values from an existing Calculation

1. Open the display Crosby Power Consumption. The display is set to read- only so you need to
save the changes under a different name. Click the Save button and select Save As to save a
copy of the display with the name Crosby Power Consumption_<your initials>.
2. Click Calculations on the left side of the screen. The list shows three calculations for the
Power Consumption of the three wells in Crosby. The tick mark shows that the calculation is
already used on the display.

3. We want to make use of the calculations by adding the Minimum and Maximum values to
the trends. Drag and drop the Minimum and Maximum from the Columns list to each of the
trends. Make sure to use the correct calculation for each well.
 Page 50 of 84

4. The result should look similar to the picture shown below.

 Page 51 of 84

5.2: Edit a Calculation

1. We want to edit the existing calculations to use the shifts as a calculation basis.
2. Select a calculation and click on the Edit symbol.

3. Under Advanced Options in the Calculation Editor set the Calc Interval to 8 hours. Click the
Enabled box for Sync Time and set the Sync Time to 06:00:00. Click Save.
 Page 52 of 84

4. Repeat this for all three calculations and save the display. The resulting trends should look
similar to the picture below.
 Page 53 of 84

5.4: Create and Use an Asset-based Calculation

1. Create a new display.
2. In the Assets Pane, search for Well08.
3. Create a value symbol showing the Well Name and a trend with the Casing Temperature
and the Tubing Temperature attributes.
4. Right click on the Value symbol and select Format Value. Under Visibility, deselect Label and
Timestamp.
5. Right click on the trend and select Configure Trend. Under Value Scales, select the symbol
for Single Scale.
6. Select the trend and click on the calculation

icon . In the calculation menu you will

see a number 2, next to the “+” symbol.
That means that PI Vision automatically
detected that the attributes in the trend
are meant to be in a calculation and added
them for us.
7. Click on the . Name the calculation “Temperature difference” and fill the description.
Change the expression to be “'Casing temperature' - 'Tubing temperature'”. Click on preview
and save the calculation. Check that this time the cube is selected because we are using an
asset instead of a PI Point.
 Page 54 of 84

8. Drag and drop the calculation to the trend.

9. Save the display with the name Temperature Differences_<your initials>.

 Page 55 of 84

(Optional) Challenge 6: Link displays together

At this point, the TechCon Labs management team is very pleased with the dashboards you have
created. But they are concerned that the navigation from one display to another by first returning to
the PI Vision home page is a bit cumbersome. They have requested that the overview and detail
displays be linked together, preferably in an intuitive way that benefits infrequent or inexperienced
users of PI Vision. For example, when a user wants to know more information about a specific well
pad or oil well, they should be able to just click on it.

As a side note, the director mentioned they feel that the borders of the current dashboards are too
cluttered with functional items such as the toolbar and other functional items. If all goes well with
the display linking, they would also like you to design a way to present these displays in a more focused
manner.

Fortunately, you are familiar with all the latest navigation and URL functionality in PI Vision and know
that this can be implemented on the existing dashboards fairly easily.
 Page 56 of 84

6.1: Update the North Dakota Overview Display

1. On the PI Vision Home page, open your North Dakota Overview display.
2. Click on the Design button on the far-right side of the toolbar to enter Design Mode.
3. Right-click on the Crosby Oil Well graphic and select Add Navigation Link…

4. Verify that Open hyperlink to another page is selected under the Action header:
5. In the Hyperlink section, click Search for displays… and find the Well Pad Detail display that
was created in Challenge 2:

6. In the Asset Pane, drill down into the Oil Well Production database to find the Crosby
element.
7. Click and drag the Crosby asset into the Asset Context field in the configuration pane.

Note:

This Asset Context field determines which asset will be selected when the linked display is opened.
In some scenarios this does not need to be explicitly set. For example: when using links within
Collections and Asset Comparison Tables, PI Vision is able to automatically determine the
appropriate asset.

8. Repeat steps 3-8 for the Kenmare, Williston, Stanley, and Dickinson Oil Well graphics using
the Kenmare, Williston, Stanley, and Dickinson assets from the Asset Pane.
 Page 57 of 84

6.2: Update the Well Pad Detail Display

1. Click on the ruler and pencil icon on the right side of the toolbar to switch to Monitor Mode.
2. Double-click on the Oil Well graphic next to Crosby to activate the newly added Navigation
Link and open the Well Pad Detail display.
3. Click on the ruler and pencil icon again to switch back to Design Mode.
4. Select the Text button on the toolbar and click on the top left corner of the display. Type
“Back to Overview Display” under Format Text on the configuration pane.

5. Set the Font Size to 12.

6. Click the Format Text header to open the configuration menu and select Add Navigation
Link:

7. Under the Hyperlink header search for and select the North Dakota Overview display.
8. Deselect the Set asset context option. The North Dakota Overview display is not currently
built to support context switching:

9. Right-click anywhere on the Oil Well collection and select Modify Collection:

10. Right-click on the Oil Well graphic and select Add Navigation Link…
11. Under the Hyperlink header, search for and select the Oil Well Detail display.
12. Save the display.
 Page 58 of 84

6.3: Update the Oil Well Detail Display

1. On the Well Pad Detail display, select the “Back to Overview Display” text symbol and copy
it using either the toolbar icon or the keyboard shortcut (Ctrl + C).
2. Click on the ruler and pencil icon on the right side of the toolbar to switch to Monitor Mode.
3. Double-click on an Oil Well graphic within the collection to activate the Navigation Link to
the Oil Well Detail display:

4. Click on the ruler and pencil icon again to switch back to Design Mode.
5. Paste the copied “Back to Overview Display” text symbol from earlier into the top left corner
of the display using either the toolbar icon or the keyboard shortcut (Ctrl + V).
6. Click on the ruler and pencil icon on the right side of the toolbar to switch to Monitor Mode.
7. Single-Click on the Text symbol to return to the North Dakota Overview display.

8. Right-click on the Asset Comparison Table symbol and select Add Navigation Link…

9. Under the Hyperlink header, search for and select the Oil Well Detail display.
10. Verify that Set start and end time and Set asset context are selected:

11. Save the display.

 Page 59 of 84

12. Click on the first well under the Asset column of the Asset Comparison Table:

13. Click on the ruler and pencil icon again to switch back to Design Mode.
14. Click the Text icon on the toolbar:

15. Create a Text symbol in the top left corner of the display that reads “Back to Well Pad
Display”.
16. Change the Font Size to 12.
17. Right-click on the Text symbol and select Add Navigation Link…
18. Under the Hyperlink header, search for and select the Well Pad Detail display.

19. Deselect the Set asset context checkbox. Only the Set start and end time option should be
selected:

It is expected that our link to the Well Pad Detail display from the Oil Well Detail display will not
update the city context of the display. This would be possible to do if we get a bit creative, but it is
outside the scope of this lab.

20. Save the display.

 Page 60 of 84

6.4: Experiment with URL Parameters

In the browser address bar, add the string ?mode=kiosk&hideToolbar&hideTimebar to the URL and
click refresh. The result should be a cleaner, more streamlined display view that hides elements
from the topbar, the toolbar, and the timebar:

Note:

Navigate through the three different displays while changing the asset and time context to verify all
the displays link functionality is working. Once you are finished, you will need to manually remove the
URL parameters from the URL in order to begin the next challenge.
 Page 61 of 84

(Optional) Challenge 7: Collection Search Criteria

The PI Vision dashboards have become heavily used within the team monitoring North Dakota
operations. Word has spread and there is interest from the executive management team in expanding
the use of PI Vision to cover all of North American production. Before that, however, they would like
to see something a bit different from any existing dashboard. On a single display, they would like to
see the lowest performing Oil Wells in all of North America.

The management team knows this sounds like a tricky request and has offered to bring in developers
in case a programmatic solution is needed. But your experience with PI Vision asset collections tells
you that this will not be necessary.

So that they have an idea of the final product, you have provided the team a sketch of what this
display will ultimately look like:
 Page 62 of 84

7.1: Filter Collection Assets with Asset Attribute Criteria

1. From the PI Vision home page open your Well Pad Detail display.
2. Click on the ruler and pencil icon again to switch to Design Mode.
3. Click on the Save Display drop-down menu and select Save As:

4. If it is not already selected, click on the display folder for your user account:

5. Name the display “Low Performing Wells” followed by your student number. For example:
Low Performing Wells_Student##.
6. Saving the display will have returned you to Monitor Mode, so click on the ruler and pencil
icon again to switch back to Design Mode.
7. Delete the Text symbol navigating to the North Dakota Overview display and the City &
State value symbols. When selected, an item on a display can be deleted by clicking the
trash bin icon in the toolbar, or by pressing the Backspace or Delete key on your keyboard:

8. Right-click on the Well Pad Detail text symbol and select Format Text:

9. Change the text to “Low Performing Wells”:

 Page 63 of 84

10. Right-click on the Oil Well collection and select Edit Collection Criteria…:

11. Remove the Search Root and select Return All Descendants:

12. Verify that the Asset Type is set to Well. Then set an Asset Attribute filter for a Production
Rate value of less than 600 MSCFD:

13. Save the changes to the display.

 Page 64 of 84

(Optional) Challenge 8: Ad Hoc Analysis

Another request has come in from some members of the engineering team. For the most part, they
are happy with the dashboards that have been created so far. But they would like to select a few
different items from the displays and do some additional analysis when they investigate specific
issues. If they identity something of interest, they would like to be able to share their findings with a
colleague.

Fortunately, you remember that PI Vision revamped its ad hoc display functionality with an enhanced
workspace. You gather the team members for a quick demo.
 Page 65 of 84

8.1: Explore the Ad Hoc Workspace

1. From the PI Vision home page open the Oil Well Detail display.
2. While holding the Ctrl key, click on the Trend and Radial Gauge symbols and then the New
Ad Hoc Trend button in the top right:

3. Toggle between the different Scale and Range settings in the top left:

4. Highlight traces by selecting rows in the Summary Table at the bottom of the window:

5. Toggle the visibility of the Power Consumption trace by clicking the checkbox and remove
the Bottom hole pressure trace by clicking the trash can graphic:

6. Set a custom scale by entering zero for the Production Rate trace’s scale Bottom

7. Close the Ad Hoc Workspace with the Hide button in the top right
 Page 66 of 84

8.2: Add Data from Multiple Sources to Ad Hoc Workspace

1. Click the Back to Overview Display link to open the North Dakota Overview display.
2. While holding the Ctrl key, click the Oil Rig graphics next to Williston and Stanley

3. Open the Ad Hoc Trend dropdown menu in the top left and then select Replace Ad Hoc
Trend:

4. In the top right, toggle off the Summary Table

5. Close the Ad Hoc Workspace by clicking the Hide button

6. Open the Asset Pane and drill down to the Hot Springs element under South Dakota in the
Oil Well Production database:
 Page 67 of 84

7. With Hot Springs is still selected, right-click the Avg Production Rate attribute in the bottom
part of the pane and click Add Selection to Ad Hoc Trend:

8. Click on Well63 in the Asset Comparison Table to open the Oil Well Detail display:

9. Right-click on the Production Rate trace in the trend legend and select Add Trace to Ad Hoc
Trend

10. Reopen the Ad Hoc Workspace by clicking the Ad Hoc Trend icon in the toolbar:

11. Click anywhere in the trend area to add trend cursors that display the exact value of each
trace at a specific moment in time:
 Page 68 of 84

8.3: Export Ad Hoc Workspaces

1. From within the Ad Hoc Workspace click the Share button and then the Copy button to load
the clipboard with a URL that will regenerate the existing workspace:

2. Open a new browser tab by clicking the plus icon on the top left, paste (Ctrl + V) the URL
from the clipboard, and hit the Enter key:

3. Close the new browser tab and return to the original tab with the Ad Hoc Workspace open
4. Click the Summary Table button to toggle the table back onto the Ad Hoc Workspace

5. Click on the Convert button to place the Ad Hoc Workspace contents into an Editor Display
that can be permanently saved and shared:

6. Click on the Save drop-down menu and select Save As

7. If it is not already selected, click on the display dolder for your user account:

8. Name the display “Production Anomaly Data” followed by your username. For example:
Production Anomaly Data_Student##.
9. Adjust any formatting as needed and save the changes.
 Page 69 of 84

(Optional) Challenge 9: Compare Downtime Events

A new type of request has come in from a member of the engineering team. They would like to
compare the time series data that occurred during two different times that oil wells were down.
Specifically, there were events on Well01 and Well16 that seemed very similar and the team would
like to take a closer look.

The engineering team has correctly noted that is not possible to overlay timeseries data on standard
PI Vision dashboards and has asked if there are any workarounds. Luckily, you just came across the
documentation of Event Comparison displays so you know how to do this.
 Page 70 of 84

9.1: Compare Events from the Event Details View

1. From the PI Vision home page, open the Oil Well Detail display.
2. Use the Asset drop-down menu to switch the display asset context to Well01:

3. Double-click on the most recent Downtime event in the Events Table symbol to open the
Event Details window:

Note:

Alternately it is possible to view the event details by right-clicking on an Event in the Events Pane.
Events will automatically populate this list if any of the assets on the display have active events within
the time range of the display. It is also possible to manually search for Events by modifying the Search
Criteria.

4. Open the Events Pane

5. Right-click on the Downtime Event and select Compare Similar Events by Type:

6. Right-click on the same Downtime event and select Pin Event

 Page 71 of 84

7. Click on Edit Search Criteria to open the search criteria:

8. Set the Event Name filter to “Well16*”, the Asset Name filter to “Any”, and then click Apply:

9. Click and drag the Casing pressure and Tubing pressure attributes onto the display.
10. Save the display as “Downtime Event Comparison” followed by your student number.
 Page 72 of 84

(Optional) Challenge 10: Manage PI Vision Displays and User settings

Now that you have seen how to create displays within PI Vision, you may wonder how to keep track
of and manage a large number of displays.

Role-Based User Access

PI Vision provides for two different user roles to facilitate system manageability. The two types are:

Publisher

• Designed for subject matter experts and content creators.

• May create and save new dashboards and analysis views.
• Equivalent to the traditional PI Vision User in previous versions.

Explorer

• Can use the full power of existing displays, including context and time manipulation
• Can create ad-hoc displays
• May not save any new displays or changes to existing displays

Users are assigned roles on an AF Identity basis. The PI Vision Admin site is used to manage these
settings.

Note:

For security and organizational purposes OSIsoft recommends separating users into Publishers and
Explorers. However, these designated access groups are not mandatory and the universal PI Vision
User role may still be used. Use the PI Vision Admin site to manage these settings.

Display Folders
Another thing to note is that PI Vision allows the use of display folders to organize displays and to
manage user access.

• Users can be set to have read permission to the displays contained within specific folders.
• As appropriate, users can also be given permission to edit the displays within a folder and/or add
new displays to folder.

PI Vision administrators can control access to these folders on an AF Identity basis from the PI Vision
home page.
 Page 73 of 84

10.1: Finding and Categorizing Displays

1. PI Vision allows you to add keywords to displays so that they can be organized into one or
more groups. To add a keyword to a display, select its gear icon from the PI Vision home
page:

This will bring up the display settings dialog that you can use to manage displays you have
created. You may add keywords here to help organize your displays. Simply type any text
you like into the Keyword box. To add multiple labels at a time, separate them with a
semicolon.
2. Once you have added a few labels, click Filter by Keywords on the homepage.

This will bring up a tag cloud of the keywords that have been created on this server. The
cloud is weighted so that labels that appear more in displays will be larger. Clicking a label
from within the cloud will filter the list of displays to only those which have the selected
label.
3. Another way to filter is by clicking the Related Displays button.

This shows all displays that contain any of the keywords associated with the selected display.
4. In addition to keywords, you can also mark a display as a favorite by clicking the star under a
display.

5. Using the navigation pane you can filter displays to see only Favorites, displays that were
created by you, or displays that you have recently viewed.
 Page 74 of 84

10.2: Controlling Access to a Display

1. When you create a display, it will initially be set to Private, denoted by the single person icon
on the PI Vision Home Page.

2. If you would like to share a display that you have created, click the gear graphic to open the
Display Settings menu and then check the boxes next to the groups with which you would
like to share your display.

After at least one group is selected, the display will change to Public, denoted by the three-
person icon on the home page.

3. Also available is the option to make the display Read-only, which will prevent other users
from making any modifications to the display.
4. The display owner is located below the display name. If needed, the display owner can be
changed by PI Vision administrators

5. You can also delete your display using the Delete display button
 Page 75 of 84

10.3: Organizing Displays with Folders

1. To move a display to a folder, first hover over the display and click the checkmark in the
bottom left corner to select it. Then, click the Move button and select a destination folder

2. On the bottom left section of the home page, you will see the Display Folders for which you
have permission. At the root level, the folder configuration buttons will be grayed out unless
you are a PI Vision administrator

3. When you select a Folder, you will see the displays within it to which you have permission

4. Since you have write permission within the Display Folder created for your user account, you
may add child folders. Click on the Student## Displays folder and then click on the new
folder graphic.
 Page 76 of 84

5. Since you have write permission at the parent level of this new child folder, you may manage
the permissions on the folder or delete.

If you delete a Display Folder, any subfolders will also be deleted. Any displays in the selected
folder or subfolders will be moved to Home, the root level above any display folders.
 Page 77 of 84

Appendix
Interacting with Data Symbols
In PI Vision, data is visualized with symbols. Below are the eight built-in symbols included with every
installation of PI Vision 2019:

Trend

When in Design Mode, right-click on the trend and select Format Trend in order to bring up the
design options for the trend

• Trend Options are used to change the Foreground and Background colors, choose between
single or multiple scales, and set the scale range

• Trace Options allows you to customize the color, weight, style, and scale range of individual
traces. You can also delete traces from this section
• The Use Default Settings button allows you to reset all trend options

In Monitor Mode, use the bottom third of the trend area to shift the time context of the trend

When in Monitor Mode you can add a cursor by simply clicking on the trend. A cursor automatically
populates on all trends within that display. Drag the cursor to change positions, and drag it off of the
trend in order to get rid of it.
 Page 78 of 84

In Monitor mode, click on the data item in order to highlight it on the trend

Value
The Value Symbol populates with the asset name, timestamp, UOM, and value:

Format the Value by right-clicking on the value and selecting Format Value. This allows you to
change the Fill, Text, and Value color as well as changing what attributes are displayed within the
Value symbol

Table
The table symbol displays multiple attributes or PI Points concisely in a table format

▪ Add data items to the table by dragging the data item onto the table
▪ Get rid of data items by clicking on the row of your choice and then clicking the delete
button

▪ If you select a data item in a table you can then drag that data item onto a trend in order see
historical values
▪ Dragging a data item off of a table onto a blank space in the display will create a separate
object for that data item while in display monitoring mode. The object type will depend on
which symbol is selected above the search pane.
▪ Right-click on the table and select ‘Table Columns’ to pick which columns to display
 Page 79 of 84

Vertical and Horizontal Gauges

The Vertical and Horizontal Gauges display a singleton in a bar format:

You can format the Bar, Fill, Outline, and Value color, Outline weight, and Visibility of the Vertical
Gauge by right-clicking on the gauge and selecting Format Gauge

Radial Gauge
The Radial Gauge symbol displays a singleton in a gauge format:

Right-click on the gauge and click Format Gauge to bring up the possible format options. Here it is
possible to change the stylings, visibility, and Scale start and end of the gauge

XY Plot
The XY plot displays a graph of plotted points that helps to show if a relationship exists between sets
of data

Right-clicking on the XY plot and selecting Format XY Plot allows for the customization of the Source
data, associated X and Y scales, as well as general styling of the XY plot
 Page 80 of 84

Asset Comparison Table

If the same attributes exist for multiple Elements, the Asset Comparison table allows us to display
them all in a single table:

Right-click on the Asset Comparison table and select Format Table in order to select which attributes
and assets to display in the table

Events table
The Events Table button is available in the Events Search Pane

It creates a dynamically updating table of current events

Right-click on the Events Table and click on Table Configuration to edit the Table Columns and
Dynamic Criteria that determine which events to show
 Page 81 of 84

(Context Option) Multi-Stating

Value symbols and all Gauge Symbols can be modified to become multi-state symbols

Right-click on the symbol and select Add Multi-State in order to configure the Multi-State symbol.
The trigger tag and states can be configured here

(Context Option) Navigation Links

Every symbol can be configured with a navigation link. Navigation links allow users to link from one
PI Vision display to another, from a PI Vision display to a separate website, or change the asset
context of the current display:

Navigation links are activated by clicking on those symbols configured to use them.

(Context Option) Collections

• Every symbol has the option to convert it to a collection
• A collection is a dynamically updating group of symbols that leverages Element templates in AF
 Page 82 of 84

(Context Option) Switch Symbol

• Each symbol has a menu option that allows a user to switch a symbol into a different type of
symbol
• This saves a user from having to recreate a symbol from scratch if they would like to change the
symbol type

Ad Hoc Trend Workspace

• Selecting any number of symbols and/or data items and then the Ad Hoc Trend button will open
a new window designed for Ad Hoc analysis
• Optionally view a table with statistics for all data items
• Toggle Trend options with single clicks without navigating a configuration menu
• Add multiple cursors to the trend
• Publish as a display and share with other users

Asset Dropdown
Opening the Asset dropdown menu gives a list of possible Assets to which the display context could
be switched

If the list of Assets is very long, it is possible to enter a filter:

By default, the menu will populate with similar Assets to the current context. If appropriate, click the
gear button to customize the Asset search criteria
 Page 83 of 84

References
Consult these resources for assistance with PI Vision that can be found in https://my.osisoft.com and
https://docs.osisoft.com/.
Register your interest for
AVEVA PI World 2022 in
San Francisco
November 14-17, 2022

https://engage.aveva.com/register-your-interest-sf-2022.html
PI Vision – Beyond the Basics

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved.

AVEVA, the AVEVA logos and AVEVA product names are trademarks or registered trademarks of aveva group plc or its subsidiaries
in the United Kingdom and other countries. Other brands and products names are the trademarks of their respective companies.

AVEVA Group plc

High Cross, Madingley Road
Cambridge CB3 0HB, UK
Tel +44 (0)1223 556655
Fax +44 (0)1223 556666

aveva.com
Page 2 of 45
 Page 4 of 45

Table of Contents

Contents
Table of Contents ..................................................................................................................................................4
Contents ............................................................................................................................................................4
Introduction ..........................................................................................................................................................5
Approach ...............................................................................................................................................................5
Scenario: Energy Management Solutions ..............................................................................................................6
Exercises ...............................................................................................................................................................7
Exercise 1: Creating a Turbine Information Display...........................................................................................7
Exercise 2: Turbine Events Display ....................................................................................................................9
Exercise 3: Linking the displays .......................................................................................................................11
Exercise 4: Ad Hoc Trending in PI Vision .........................................................................................................13
Exercise 5: PI Vision Advanced Calculations ....................................................................................................16
Exercise 6: XY Plot with Reference Curve ........................................................................................................17
Solution Guide .....................................................................................................................................................18
Solution for Exercise 1: Creating a Turbine Information Display ......................................................................18
Solution for Exercise 2: Turbine Events Display ...............................................................................................23
Solution for Exercise 3: Linking the displays.....................................................................................................28
Solution for Exercise 4: Ad Hoc Trending in PI Vision .......................................................................................33
Solution for Exercise 5: PI Vision Advanced Calculations .................................................................................34
Solution for Exercise 6: XY Plot with Reference Curve .....................................................................................38
PI Vision Security .................................................................................................................................................40
Share Displays and Edit Access........................................................................................................................40
Manage PI Vision Displays ...............................................................................................................................42
Editing PI Vision Displays .................................................................................................................................43
Reports............................................................................................................................................................44
 Page 5 of 45

Introduction
This course is designed for people who already have already used PI Vision. Students should already be familiar
with how to create displays in PI Vision and understand how PI Vision is able to leverage AF Templates.
Exercises can be solved using PI Vision and PI System Explorer. If you've not used PI Vision before that's okay.
Just try and follow the solution guide that's at the end of the workbook and is after each exercise.

Approach
Specific questions or scenarios will be presented to solve primarily using OSIsoft PI Vision as your visualization
and analysis tool. More advanced features of PI Vision will have a strong reliance on AF so you will also need
to use PI System Explorer (PSE). Each exercise can be completed with PI Vision and PSE.

The scenario for this course is that you've just been hired as a consultant for energy management solutions.
Your first client is a wind farm energy company, and you are tasked with creating some advanced PI Vision
displays that employees can use to monitor their turbines.
 Page 6 of 45

Scenario: Energy Management Solutions

You have just been hired as a consultant for Energy Management Solutions. Your first client is a Wind Farm
energy company, and you are tasking with creating some advanced PI Vision displays that employees can use
to monitor their turbines. Luckily the company has just completed a project building out an AF database that
has correctly templatized their AF Assets. Their AF structure features three main levels, Region, Farm, and
Turbine.

Red – Region
Blue – Farm
Green - Turbine

Within AF, the customer has configured Event Frames to monitor Turbine downtime. These Event Frames are
set to trigger whenever the turbine is in a status other than “Run”.

You know that this structure will make it possible for you to utilize template dependent features within PI
Vision which can save you time when building out displays.

Note: PI AF database used in these exercises is a slight modification of the Wind Farm Monitoring Asset Based
PI Example Kit available the learning website:

https://learning.osisoft.com/asset-based-af-example-kits
 Page 7 of 45

Exercises
Exercise 1: Creating a Turbine Information Display
Exercise Objectives:
• Create a display showing Turbine level information
• Utilize a multi-level collection to navigate through their AF database

Scenario:
Your first assignment is to create a Turbine Information Display. The client would like to have a display that
shows Power and Production information for each Turbine that is selected. The client has 22 turbines in total.
With your knowledge of PI Vision, you know if you make a display using attributes from the same template you
can use the Asset Drop Down box to make a reusable display that can be applied to all turbines. The client
informs you though that they do not want to have users using the Asset Drop Down box. They would like to
have an on-screen symbol that they can select to change the context of the display at various levels and only
be able to see Turbines in the selected Region and Farm.

Approach:

1. Use the shortcut on the desktop to launch PI Vision using Edge.

a. Alternatively, start Edge and navigate to https://pisrv01.pischool.int/pivision

2. Click New Display in PI Vision.

3. Create three collections, one for each level of the hierarchy that contain the asset name. There should
be one for Region Name, Farm Name, and Turbine Name.

Hint: On the OSIsoft Learning Channel there is a video called: PI Vision Alternative Context Switching
with Collections and Multiple Filters (https://www.youtube.com/watch?v=_QlyKSJyy9o&t=387s)
 Page 8 of 45

4. Configure the collection’s navigation link to change the root context of the current display

5. Create symbols in PI Vision that can be used to monitor Power and Production of the Turbines.
Specifically, the Active Power, Apparent Power, and Lifetime Production attributes will be useful.

6. Once finished, select the drop-down arrow on the right hand side of the Asset Drop Down box and click
the gear icon. Then in the Configure Context Switching pane on the right select the option for “Do not
show”.

7. Save the display as Windfarm Turbine Overview.

Questions:
What is the Hourly Lifetime Production for Turbine GE004 in Santaella?

What is the difference in Active Power and Apparent Power for Turbine RB009 in Finisterre?
 Page 9 of 45

Exercise 2: Turbine Events Display

Exercise Objectives:
• Use the Events Table to see recent Event Frames
• Analyze Event frames with the Details page

Scenario:

Your client loved your Turbine information display, but they would also like to see a display they can use to
better track their Event frames. Currently they are monitoring turbine downtime events and would like a
display to visualize that. They would like the display to contain all the most recent events from the selected
turbine.

Approach:

1. Create a new display in PI Vision.

2. Create symbols on the display showing the Turbine name and status.

a Only create the display using data from one turbine.

3. Add an Events Table show Event Frames for all assets on the display.

a Hint: This can be done by selecting the Events tab and using the Create Events Table button

4. While in run mode, single click the Event to open the Details display.

5. Save the display as Windfarm Turbine Detail.

 Page 10 of 45

Questions:
When was the last time turbine PH002 in Philadelphia had a downtime Event?

What was the approximate peak Lost Revenue Rate in that time range?

What was the approximate minimum Apparent Power for that time range?
 Page 11 of 45

Exercise 3: Linking the displays

Exercise Objectives:
• Use AF to dynamically build URLs to the Event Details display.
• Create an Asset Comparison table to display those URLs in PI Vision.

Scenario:
Again, your latest display was well received by the client. As you already know they do not like to have their
users go through the Asset Drop Down box to change the context of the display, so they are looking for an
alternate solution. What they would like to have is a way to navigate from the Information display to the
Events display and have that link provide the context for the Events display.

Approach:

1. Open PI System Explorer and select the Wind Farm Database

2. Navigate to Library and under Templates > Element Templates > Turbine

3. Modify the Details URL attribute so it will take you to the Turbine Events Display

Hint 1: The URI builder data reference may be of use here

Hint 2: URL parameters can be used to set the context of the display
https://docs.osisoft.com/bundle/pi-vision/page/url-parameters-reference.html
 Page 12 of 45

Hint 3: Substitution parameters can be used to quickly build out the path to the element.

i. %System% - Gets the name of the AF Server the attribute is on

ii. %Database% - Gets the name of the database the attribute is on

iii. %ElementPath% - Gets the path to the element the attribute is on

(not including server and database)

4. Create an Asset Comparison table in PI Vision and pull in the URL attributes

5. Modify the Details URL Yesterday attribute in AF to also change the time context of the display and add
those attributes to your Asset Comparison Table as well. For the time context use “y” as the start time
and “t” as the end time

Questions:
What does the time range of start time “y” and end time “t” correspond to?

Try to use another URL parameter in System Explorer.

Exercise 4: Ad Hoc Trending in PI Vision
Exercise Objective:
• Analyze an existing display using the Ad Hoc functionality of PI Vision

Scenario:
After seeing the advance displays you have been making your client has taken it upon themselves to make a
display of their own. They created a display called Wind Farm Overview but are having trouble analyzing the
display to answer specific questions about their operations.

Approach:
1. Open the display called Wind Farm Overview.

2. While in Run mode, hold the CTRL key and select the Wholesale Price attributes and Lost Power
attributes.

3. Click the Ad Hoc trend button:

4. Ensure the summary table is being shown:

What was the maximum Wholesale Price over the last 8 hours for both regions?

What was the Wholesale Price for the Northeast region yesterday at 1 PM?

13 | P a g e
5. Close the Ad Hoc display workspace and add the Total Revenue attributes which are shown in the
trend symbols to the Ad Hoc Trend workspace.

6. On the same display drill down to the Lost Revenue Rate attribute for PH001.

7. Right Click the attribute and select “Add Selection to Ad Hoc Trend.

8. Open your Ad Hoc display workspace and hide the trends for Wholesale Price and Lost Power for the
Scirocco region.

Note: In the solution video you will see a check box to show/hide traces as it is used in PI Vision 2019.
In PI Vision 2020 you can click the value field in the summary table to hide a trace.

Is there a correlation between the Lost Revenue Rate of PH001 and the entire Northeast region?

9. Beginning with PI Vision 2020 you can add Minimum, Maximum, and Average summary traces with
customizable intervals to the trend in the ad hoc workspace. Click on the Average for the Lost Revenue
Rate of PH001 in the summary table to get the Average value shown on the trend. The Average value
in the summary table gets highlighted in the color corresponding to the trend line.

10. Click the Summary Intervals drop-down menu.

14 | P a g e
11. Select the Step option with an interval of 1 hour.

15 | P a g e
Exercise 5: PI Vision Advanced Calculations
Exercise Objective:
• Create a PI Vision Calculation
• Understand the Advanced Options within the PI Vision Calculation

Scenario:

After seeing the Ad Hoc analysis performed in the previous exercise the client now has some
additional on-demand type analysis they would like you to perform. They would now like to see
what percentage of total Wholesale Price the Scirocco region comprises. Furthermore they
would like to see this percentage calculated each hour and plotted clearly on a trend.

Approach:

1. Open the Wind Farm Overview display.

2. Create a calculation to represent the percentage of Wholesale Price the Scirocco region
comprises and configure it to calculate on the hour.
a. Hint 1: The calculation will be as follows
i. 'Wholesale Price'/('Wholesale Price' + '\Northeast|Wholesale
Price')*100
3. Plot the calculation Value in a trend and enable data markers on the trend.

Questions:
What is the current percentage of Wholesale Price for the Scirocco region?

What was the percentage 4 hours ago?

16 | P a g e
 Page 17 of 45

Exercise 6: XY Plot with Reference Curve

Exercise Objective:
• Create an XY Plot in PI Vision.
• Add a Reference Curve to the XY Plot

Scenario:

The client has now informed you that they would be interested in visualizing the relationship
between Active Power and Apparent Power on each of their turbines in the Turbine Events
Display. On the customer’s side they have set up an AF Analysis that is calculating a value for their
Apparent Power.

Approach:

1. Open the Windfarm Turbine Detail Display and drill down to the Turbine currently on the
display.

2. Create an XY plot with Active Power on the X axis and Apparent Power on the Y axis.

3. For the Y axis column add the Calculated Apparent Power attribute.

4. Configure the second set of markers to serve as a reference curve.

Hint: https://customers.osisoft.com/s/knowledgearticle?knowledgeArticleUrl=KB01580
 Page 18 of 45

Solution Guide

Solution for Exercise 1: Creating a Turbine Information Display

1. Connect to PI Vision by clicking the PI Vision shortcut on the desktop.

2. Click the New Display button.

3. On the left hand tree select the Wind Farm database.

4. Drill down to the Northeast level in the Assets pane.

5. On the top symbol bar select the Value symbol.

6. From the Attributes pane select the Region Name attribute and drag it onto the display.
 Page 19 of 45

7. Format the Value symbol to only show the Value by right clicking the symbol and
selecting “Format Value…”

8. Increase the font size to make the symbol larger.

9. Once finished formatting click back in the display space.

10. Right click the symbol and select “Convert to Collection…”

11. Click back in the display to close the Configuration pane. Then select the collection and
click “Modify Collection”

12. Then right click on the Value symbol and select “Add Navigation Link”
 Page 20 of 45

13. Under the Action section select “Change context of current display” and “Use current
asset as root”

14. Click back onto the display and click the Exit Modify Mode button.

15. Ensure you are in build mode.

16. Format the collection so only one item is showing.

17. In the Assets pane drill down to the New York Element.

18. Confirm the Value symbol is still selected, find the Farm Name attribute, and drag it onto
the display.
 Page 21 of 45

19. Repeat steps 7-15 to format the symbol, create a collection, and configure the navigation
for the symbol.

20. Drill down to the NY001 Element

21. Confirm the Value symbol is still selected, find the Turbine Name attribute, and drag it
onto the display.

22. Repeat steps 7-15 to format the symbol, create a collection, and configure the navigation
for the symbol.

23. Add text symbols to the display and format the collections as desired. An example can be
seen below:

24. While still on turbine NY001 create another value symbol to show the Turbine Name.
This will not be made into a collection and can be used to show which turbine is selected.

25. Select the horizontal gauge symbol and find the Lifetime Production (Hourly) attribute.
Drag it onto the screen to create the symbol.

26. Select the trend symbol and select the Active Power and Apparent Power attributes.
Drag those onto the display to make a trend symbol.
 Page 22 of 45

27. Format the display as desired. An example display can be seen below:

28. Select the drop down arrow on the right hand side of the Asset Drop Down box and click
the gear icon.

29. In the Configure Context Switching pane on the right select the option for “Do not
show”.

30. Ensure your display is in run mode and select the collections to change the display.

31. Save the display and answer the exercise questions.

 Page 23 of 45

Solution for Exercise 2: Turbine Events Display

Example of a display that we will create in this exercise:

1. Connect to PI Vision by clicking the PI Vision shortcut on the desktop.

2. Click the New Display button.

3. Drill down to the Turbine NY001 in the Assets pane.

4. Select the Value symbol and drag over the Turbine Name.
5. Configure the symbol to just show the turbine name.
 Page 24 of 45

6. Add a value symbols for the Status.

7. On the left side of the screen select the Events icon to explore Event Frames.

8. Verify that Event Frames have populated in the Events Pane and select the “Create
Events Table” button. If no Events are present ensure the “Automatically refresh the list”
option is checked.

9. Right-click on the event table and select the Configure Table… option and use the arrow
button to move Event Type and Duration from Additional Attributes up to Current
Columns.

10. Use the arrow next to the asset name in the Attributes pane to see the list of asset
attributes. Drag and drop the attributes Lost Revenue Rate and Apparent Power on the
Events Table. The table will display the attribute values at the end time of the event
frame.

11. Save the display as Windfarm Turbine Detail.

12. Put the display in Monitor mode and click on an Event in the table. This will open the
details display and you can answer the exercise questions. If you need to change the
context of the display you can use the Asset drop down box.
 Page 25 of 45

Tipps to find the solution to the questions:

When was the last time turbine PH002 in Philadelphia had a downtime Event?
Scroll through the event table to find the newest event at the bottom of the table or use the arrow at the
Event Name or Start Time column header to have the column sorted in descending order.

Finding maximum and minimum values to answer the questions:

• What was the approximate peak Lost Revenue Rate in that time range?
• What was the approximate minimum Apparent Power for that time range?

Option 1: Right click on the latest Event Frame in the Events Table and select Open Popup Trend From
Row. In the Popup Trend, click on Show Summary Table in the upper left. The summary table will appear
below the trend and displays the minimum and maximum values for the attributes in the trend.
 Page 26 of 45

Option 2: Click on the latest Event Frame in the Events Table while in Monitor Mode or right click and
select Event Details. To bring the attributes onto the trend pane, click the line symbol to the left in the
Related Asset Attributes list for Lost Revenue Rate and Apparent Power.

At the top you can change the appearance of the lines. For example you can active Data Markers to easily
see where the archived values are. To find the maximum and minimum values for the attributes, you can
use a trend cursor by clicking on the trend at the timestamp of the minimum or maximum, respectively.
The trend cursor can be moved by holding down the mouse button if you have not hit the maximum or
minimum exactly. Still it might be difficult to find the exact spot and get a precise value. Multiple cursors
can be used simultaneously, simply click again on the trend.
 Page 27 of 45

In the example, I selected the peak at approximately 5 min as the maximum of the Lost Revenue Rate.
Looking more carefully, you will notice that the trend is actually going higher at the end of the time range.
The end time value is shown in the legend at the right.

Option 3:

Create a Table symbol on the Windfarm Turbine Detail display with the two attributes Lost Revenue Rate
and Apparent Power. Make sure to show the Minimum and Maximum columns. Right click on the event in
the Events Table and select Apply Time Range.
 Page 28 of 45

Solution for Exercise 3: Linking the displays

1. Open up PI System Explorer by clicking the PI System Explorer shortcut on the desktop.

2. Open up the Wind Farm database by clicking the Database icon near the top left.

3. Once in the database select the Library tab in the bottom left.

4. Expand the Templates section of the hierarchy and then expand the Element Templates
section.
 Page 29 of 45

5. Select the Turbine Template then select the Attribute Templates tab as that is where we
are going to configure the Details URL.

6. Select the Details URL attribute and change the Data Reference to URI Builder.

7. Click the “Settings…” button.

8. In the box copy and paste in the URL for the display you created in Exercise 2 and click
Continue.

9. For the Type select PI Vision.

 Page 30 of 45

10. Click the * icon to add a new key.

11. For the key select Asset and for the value type
\\%system%\%database%\%elementpath%

12. Click OK.

13. Select the Details URL Yesterday attribute.

14. Repeat steps 6-11 for the new attribute.

15. In addition to the Asset key, create a StartTime key and set its value to “y”

16. Create an EndTime key and set its value to “t” and click on OK. When finished making
changes be sure to Check In Changes in PSE.
 Page 31 of 45

The display that was created in exercise 1 will be expanded by an asset comparison table with
the URI Builder attributes created before. Example:

17. Return to PI Vision and open the Windfarm Turbine Overview display you created in
Exercise 1.
 Page 32 of 45

18. Create an Asset Comparison Table Symbol on the display that includes the following
attributes:
a. Status
b. Details URL
c. Details URL Yesterday

19. Save the display and test the links by using Run mode and clicking on them.

20. For question 2, you can modify the Details URL Yesterday attribute by adding a new key.
 Page 33 of 45

Solution for Exercise 4: Ad Hoc Trending in PI Vision

This Exercise was written to already provide step-by-step instructions.
 Page 34 of 45

Solution for Exercise 5: PI Vision Advanced Calculations

The Wind Farm Overview display that was used in Exercise 4 will be expanded to include an
additional trend of calculated data.

1. In PI Vision open the Wind Farm Overview Display if not already opened.

2. Place the display in Design mode.

3. Select the Calculation tab and select the value symbols for the Northeast and Scirocco

Wholesale Price attributes. Note that the parent element of the attribute that was

selected first is used as the root element. In the following we show the steps when the

Wholesale Price attribute of Scirocco is selected first. Click the ‘+’ to create a new

calculation.
 Page 35 of 45

4. Name the new calculation Scirocco Wholesale Price Percentage

5. The Expression box will show the following (with asset Scirocco selected as root):

'Wholesale Price' + '\Northeast|Wholesale Price'

6. Modify the Expression to the following:

'Wholesale Price'/('Wholesale Price' + '\Northeast|Wholesale Price')*100

7. Expand Advanced Options and change the Time Interval to Custom

8. Adjust the Calc Interval to 1 hour

 Page 36 of 45

9. Save the calculation.

10. Select the Trend symbol in the PI Vision symbol tray.

11. Drag the Value Column of the calculation onto the display space to make a new trend.

12. Right click the trend and hit Configure Trend.

13. Expand Trace Options and make a selection for the Marker setting
 Page 37 of 45

14. Place the display in Run mode and use your trend and trend cursors to answer the

exercise questions
 Page 38 of 45

Solution for Exercise 6: XY Plot with Reference Curve

The Windfarm Turbine Detail display that was created in exercise 3 will be expanded by an XY
plot. Example:

15. In PI Vision open the Turbine Events display you created in Exercise 2

16. Drill down in the Assets pane to whatever Turbine is currently shown on the display

17. Select the XY Plot symbol

18. In the Attributes pane select both the Active Power and Apparent Power attributes. You

can select multiple attributes in PI Vision by holding the Ctrl key. Drag those on to a blank

area in the display to make the XY plot

19. Right Click the XY Plot and select “Configure XY Plot…”

 Page 39 of 45

20. From the attributes pane find the Calculated Apparent

Power attribute and drag it to the Y-axis of the XY Plot

configuration

21. Under the Format section select the second row that

has the Calculated Apparent Power attribute

22. Click the check box for Connecting Line and uncheck the box for Markers

23. Now click back in the display space and save your display.
 Page 40 of 45

PI Vision Security
By default, any new display you create in PI Vision is private. Meaning that only you can view and
edit it. You can however share it with other users and even grant them access to edit and save
new versions. Let’s see how PI Vision 2020 streamlines the process of granting users read and
write access to displays.
Share Displays and Edit Access
The Display Settings window allows you to control a display's visibility and ownership. To access
the Display Settings window, browse to the Home page and click Edit display settings on the
display thumbnail that you want to edit. The options available on the Display Settings window
depend on your PI Vision user role.

Administrators have access to all Display Settings. Display Owners may only access some options.
The Keywords setting allows you to provide keywords separated by semi-colons. This makes it
easier for someone to search and find this display. Checking the Read-only box disables saving any
changes to the display by any user, including yourself. You must save the display under a different
name to make changes. If you are an administrator, you can change the owner for the selected
display. The display owner can make changes and save new versions of the original display. You
can remove displays by clicking on the delete button. You cannot undo this action so make sure
you are certain before you proceed.

Display Access

In this section you can assign read and write access to your display for selected AF identities. A PI
AF identity represents a set of access permissions for a group of users. This is setup by your PI
Administrator. You can use the identity group World to share your display with everyone in your
organization. You can specify the type of access that you want to grant to a display for an AF
Identity.

• Read access: users can see and open the display

• Write access: users can save changes to a display
 Page 41 of 45

Read access is granted by default to any AF identity added. To grant Write access you must check
the appropriate box. Click an identity under Unassigned AF Identities and then click Add Permissions
to grant that AF Identity access to the display.

Collaborate on Your Displays

Users can access the same display at the same time. If one of them modifies the contents of the
display, these changes will be automatically applied to the displays of the other users within 2
minutes. The user who made the changes would need to save the display and exit edit mode.

If another user attempts to also make changes to the display before it updates, an indication will
popup. This notifies them that the display has been changed. Their options are then to either save
their display as a new version or reload to update their display. This way users avoid change conflict
and are guaranteed to be looking at the same version of the display.

If you want to view the changes to a display before accepting them, you can open the display in a
new browser tab and then decide whether to keep the changes or not.
 Page 42 of 45

Manage PI Vision Displays

Manage Role-Based User Access Level
Your PI Vision Administrator can give users different level of access by assigning and managing
user roles on the PI Vision Administration website. PI Vision provides two access roles based on PI
AF identities:
• Publisher: users have full access to the application and can save displays.
• Explorer: users have access to the application but cannot save or share displays. An Explorer
can still export data from a display.
PI Vision Homepage
In the homepage of PI Vision, you can View and Search All Displays that you have access to, Filter
displays by Labels, or navigate logical groups to find displays. These groups are listed below:
• ALL DISPLAYS: lists all public and private displays
• FAVORITES: filters the thumbnails to show only favorites (starred displays)
• MY DISPLAYS: shows all displays that you have created.
• RECENT: PI Vision automatically remembers displays that you used within the last seven days.
• FOLDER HOME: shows the folders that your administrator has configured for you to access PI
ProcessBook displays. Below this option, the list of folders for accessing PI ProcessBook
displays will be listed. In the example shown in the screenshot below, this folder is named “PI
ProcessBook Displays”.

Organizing PI Vision Displays

PI Vision offers new options for organization of displays to provide a quicker way of finding
displays of interest.

• Search All Displays: Displays are searchable by name or owner.

• Favorites: You can mark displays as "favorites" by clicking the star icon. Favorites are a
user-specific property.
• Keywords: You can apply keywords to displays to categorize them. The keywords can be
viewed in a keyword cloud by selecting "Filter by Keywords." Within the keyword cloud,
 Page 43 of 45

the keywords are sorted alphabetically, and their size is determined by their relative
frequency. Keywords applied by one user are visible to the rest of the users.
• You can add a keyword by clicking the Display Settings icon and typing in the keyword in
the Keywords box. Once you start typing the keyword, the matching available keywords
become available in a list, as shown in the image below.

Editing PI Vision Displays

Some of the editing options are available from the PI Vision homepage and some from the PI
Vision display itself.

From the homepage, clicking on the Display Settings icon you will see the following options:

• Keyword: allows you to provide semi-colon separated keywords that someone may use
while searching for this display.
• Read-only access: click here to disable saving any changes to the display by any user,
including yourself. If you want to make changes to a display that is Read-only, open that
display and save it under a different name.
 Page 44 of 45

• Display Owner: change the owner for the selected display to a different user. This display
will appear in the selected user's Private displays if you do not grant access to any AF
Identities when you click Save. You can make anyone else in your organization the owner
of any display. (Only visible to the Administrators).
• Delete Display: If you no longer need a display and want to remove it, click Delete
display. Make sure you are certain before you delete a display. You cannot undo this
action.

Reports
PI Vision administrators can view or export five different reports about the usage of PI Vision. The
reports are available under the Reports tab on the PI Vision Administration site. In the virtual
environment you can access the PI Vision Administration site under the URL
https://pisrv01.pischool.int/pivision/admin.

Each of the report types is defined as follows.

• Detailed display content information - Provides a summary of the contents of displays

created during a specified time range. This can include information about data items,
symbols, display visibility, and display ownership.
• Display Access - Provides a count of total views and unique users that have accessed a
display in the specified time range.
• Users who have accessed PI Vision within a specific time range - Provides a count of users
who have opened PI Vision displays each month during the specified time range.
• List of all PI Vision users - Provides a count of displays owned by each PI Vision user.
• Get the count of Publishers and Explorers - Provides a count of Publisher and Explorer
licensed users that have accessed PI Vision in the specified time range.
 Register your interest for
AVEVA PI World 2022 in San
Francisco
November 14-17, 2022
https://engage.aveva.com/register-your-interest-sf-2022.html
PI DataLink: Basics
OSIsoft, LLC
1600 Alvarado Street
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Web: http://www.osisoft.com

© 2020 by OSIsoft, LLC. All rights reserved.

OSIsoft, the OSIsoft logo and logotype, Analytics, PI ProcessBook, PI DataLink, ProcessPoint, Asset
Framework (AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI
BatchView, PI Vision, PI Data Services, Event Frames, PI Manual Logger, PI ProfileView, PI
WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all
trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their
respective owners.

U.S. GOVERNMENT RIGHTS

Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft,
LLC license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR
52.227, as applicable. OSIsoft, LLC.

Published: October 13, 2021

2|Page
Table of Contents

Contents
Table of Contents .................................................................................................................................................................... 3
1. Introduction .................................................................................................................................................................... 5
Learning Objectives ................................................................................................................................................. 5
Prerequisites ........................................................................................................................................................... 5
Useful Resources ..................................................................................................................................................... 6
2. PI System Basics .............................................................................................................................................................. 7
Map of the PI System .............................................................................................................................................. 7
What are PI Assets, Attributes and Tags? ............................................................................................................... 8
2.2.1 What is a PI Point? .......................................................................................................................................... 8
2.2.2 Assets and Attributes ...................................................................................................................................... 9
Time in the PI System ............................................................................................................................................ 10
2.3.1 PI Time Expressions ....................................................................................................................................... 10
2.3.2 Fixed Time Syntax ......................................................................................................................................... 10
2.3.3 Referenced Time Syntax ............................................................................................................................... 11
2.3.4 Time offset .................................................................................................................................................... 12
2.3.5 Time offset syntax ......................................................................................................................................... 13
2.3.6 Some rules to remember .............................................................................................................................. 13
2.3.7 Future Data ................................................................................................................................................... 14
2.3.8 How does PI Adjust for Time Zones and DST? .............................................................................................. 14
Connect to the PI System ...................................................................................................................................... 15
3. PI DataLink Basics .......................................................................................................................................................... 17
Introduction .......................................................................................................................................................... 17
Mind map of PI DataLink ....................................................................................................................................... 18
Search for PI Tags and PI AF attributes ................................................................................................................. 18
Get instantaneous PI data with PI Current Value Function .................................................................................. 20
Get historical PI Data with PI Archive Value Function .......................................................................................... 21
Use Root Path References..................................................................................................................................... 21
Build KPI Reports ................................................................................................................................................... 22
4. Compressed, Sampled and Calculated Data ................................................................................................................. 24
Get Raw PI data with PI Compressed Data Function ............................................................................................ 24
 Get Custom Interval PI data with PI Sampled Data Function ............................................................................... 26
Functions returning Data ...................................................................................................................................... 27
4.3.1 Directed Activities – Single value queries ..................................................................................................... 27
4.3.2 Directed Activities - Multiple Value Queries ................................................................................................. 32
Interpolation and Retrieval Modes in PI DataLink ................................................................................................ 34
4.4.1 Interpolated Values ....................................................................................................................................... 34
4.4.2 Retrieval Modes ............................................................................................................................................ 35
Get Time-Summary Calculations with PI Calculated Data Function ..................................................................... 36
PI Calculated Data Function – hourly range of values .......................................................................................... 38
5. Using Time Filtered Data in a Preventative Maintenance Example.............................................................................. 41
Time Filtered Data................................................................................................................................................. 41
6. Filtered Data Using Custom Expressions....................................................................................................................... 46
Excel Conditional Formatting ................................................................................................................................ 47

4|Page
1. Introduction

In this course, you will learn how to use this tool to access your process data, create
meaningful reports, and use them to make key decisions about your plant
performance. PI DataLink is our add-in that allows users to access and deliver data to
and from Microsoft Excel and create easy-to-read reports.
This course is for beginning users of PI System data and is open to anyone who wishes
to learn more about PI DataLink. if you're a process engineer or a plant operator and
are interested in learning about the key features of PI DataLink, how to process data,
and create meaningful reports that your end users could use - then this course will be
useful for you.
This course was previously titled: Creating Basic Reports with PI DataLink

Learning Objectives
By the end of this course, you will be able to:
• Understand the PI System Basics
• Search for PI Tags and AF Attributes in PI DataLink
• Identify which PI DataLink function to use for your report
• Get current and historical PI data in PI DataLink
• Build reports with key KPIs
• Interpolate data with custom intervals
• Use calculated data
• Build reusable daily report

Prerequisites
Familiarity with MS Excel is helpful. No specific knowledge of the PI System software
is required.
Learners are encouraged to use their own software and data structures whenever
possible. This allows each learner to immediately leave the course with something
valuable to their enterprise. To complete the exercises and the final project, you need
to have the following software installed:
PI DataLink 2013 or later (connected to PI Data Archive and Asset Framework)
If you do not have access to a PI System you can use the included Training Cloud
Environment. Go to the Training Cloud Environment section at the end of the course
to learn more about it and deploy your cloud environments.

5|Page
 Useful Resources
• PI DataLink User Guide, available:
o via the F1 key or question mark on a PI DataLink task pane
o on LiveLibrary
o as a PDF download from the OSIsoft Customer Portal
• PI DataLink Playbook, which contains:
o Version history
o Common data gather steps for troubleshooting issues
o Architecture and data flow overview
o Links to articles addressing common issues, sorted by issue type
(installation, runtime, admin tasks, etc.)

6|Page
2. PI System Basics

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

Map of the PI System

The PI System collects, stores, and manages data from your plant or process. You
connect your data sources to one or more PI Interface nodes. The interface nodes get
the data from your data sources and send it to the Data Archive. Data is stored in the
Data Archive and is accessible in the assets defined in Asset Framework (AF). Data
can be accessed either directly from the Data Archive or from the AF Server using
tools in the PI Visualization Suite (PVS) such as PI ProcessBook. Because of the
usability advantages of AF, users are encouraged to consume data by accessing the
AF Server rather than directly accessing the Data Archive.
The following is a diagram of the components of a typical PI System:

Sometimes the architecture can be very simple. Some customers have as few as
one or two interfaces feeding data to a Data Archive, from which the data can be
read through various applications. The following is an example of a fully developed
PI System which includes most of the widely used OSIsoft products.
PI Server = Data Archive + PI Asset Framework (AF)
In some companies, there are many Data Archives used for aggregating data.

7|Page
 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]

What are PI Assets, Attributes and Tags?

Objectives
• Define the terms of PI Asset Framework (AF) Asset and its components:
elements and attributes.
• Define AF attribute types: static (none), PI Point, point array, formula, string
builder, table lookup and Analysis.

2.2.1 What is a PI Point?

PI Point (or PI Tag) is a unique storage point for data in the Data Archive. It is simply
a single point of measurement. It has been the traditional storage unit in the PI Server.
Data Archive points have a set of properties called point attributes that define the PI
points. Some of these properties are commonly used in client tools for display or
informational purposes and are briefly described in the following.
Point name

8|Page
 Unique name is required to create points for storage in the Data Archive. It is a
common practice to name the PI Points based on the Control Systems point names.
Since the point is the name that identifies the point to users, consistent point-naming
convention should be used that is meaningful to people in your organization. Knowing
the naming convention can be helpful in searching for points. For example, try to
determine what the following point may refer to:
Point name: M03_E1P1_MOTDRV1202_RUNSTAT
It refers to: Machine3 Enclosure 1 Panel 1 Motor Drive 1202 Run Status which is not
intuitive.
Some of the other common point attributes that are often used in client tools are
listed in the following table.

Attributes Description
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.”

EngUnits Engineering units (units of measure)

Zero and Span These define the minimum and maximum values and are used in a
number of places. Most obvious are the upper and lower boundaries
of object like the trend, bar graph, or multistate symbol.

Point source Allows grouping of PI points by their interfaces that collect data and is
occasionally used in point searching. It requires the knowledge of
data source, which is instruments that generate the data of interest
(e.g. DCS, PLC, or other sources).

2.2.2 Assets and Attributes

In AF, each piece of equipment or process or company locations and sites is

represented by an Element (Asset). It organizes all equipment into a structure that
makes it easy to find information. AF can be helpful to users of the Data Archive who
know the assets and processes but are not familiar with attribute nomenclature. With
assets, data can be located without understanding the technical details of each piece
of equipment as the assets are organized hierarchically and logically.
Attributes represent a unique property associated with an asset. Attributes can hold
simple values, representing fixed information, such as the diameter of a tank. An
attribute can reference a PI point, a formula, a value from a relational database, and
more. All relevant data about an asset is tied to the element representing that asset.
AF can automatically generate points as assets are created.

9|Page
 Time in the PI System
You can use a special syntax, called PI time, to specify inputs for timestamps and time
intervals in PI client applications, for example PI Vision. PI time uses specific
abbreviations and rules in building valid time expressions.

2.3.1 PI Time Expressions

There are two categories of time specification within the PI system:

• Fixed Time: An expression that signifies a specific date and time, which will never
change.
o When to use it: When you want to save a view of your PI System data for
a specific time in history.
o Example: A user is creating a report that analyzes an equipment failure
event which occurred on the 5th of January.
• Reference Time: An expression that signifies a date and time relative to the
current date and time.
o When to use it: When you want to create a dynamic view of your data,
which can be used to view data in real-time, or re-used on a periodic basis
to create periodic reports.
o Example: A user is creating a report that summarizes the weekly production
totals. By using relative time expressions, the user will be able to re-use
this report every week.
Both Fixed Time and Reference Time can be used with Time Offsets. Time Offsets
can also be used alone.

2.3.2 Fixed Time Syntax

A fixed time expression is an expression which includes a date, and optionally a time.
If the time is omitted, midnight is assumed.

10 | P a g e
 Expression 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

The PI System can interpret many different formats for fixed time. In the event of an
ambiguous input, the Windows Region and Language settings of the computer where
the PI Visualization Tool is installed take precedence. For example:

Expression Region and Language Format Meaning

1/5/2015 00:00:00
(midnight)
English (United States)
on January
5th 2015

1/5/2015 English (Canada) 00:00:00

(midnight)
on May 1st
2015

2.3.3 Referenced Time Syntax

A reference-time abbreviation represents a time relative to the current time.

Abbreviation Full Reference time

* Current time

t Today 00:00:00 (midnight) of the

current day

y Yesterday 00:00:00 (midnight) of the

previous day

fri Friday 00:00:00 (midnight) on the

most recent Friday

may May 00:00:00 (midnight) on the

current day in May of the
current year

apr-DD april-DD 00:00:00 (midnight) on the

DDth day of April in the
current year

11 | P a g e
 YYYY 00:00:00 (midnight) on the
current day and month in
year YYYY

M-D or M/D 00:00:00 (midnight) on the

Dth day of month M in the
current year

DD 00:00:00 (midnight) on the

DDth day of the current
month

Use the first three letters as an abbreviation for any day of the week and any month of
the year. For example:

Expression Meaning

thu 00:00:00 (midnight) on the most recent Thursday

2015 00:00:00 (midnight) current day and month in 2015

2.3.4 Time offset

When specifying PI time, you can use specific abbreviations, listed below, that
represent time units. These would be used in constructing Time Offsets.

Abbreviation Time Unit

s second

m minute

h hour

d day

mo month

y year

w week

You can specify the abbreviation, the full-time unit, or the plural version of the time unit, such as s, second,
or seconds. Time offset is any of the time units with a valid value and a + or – sign included, e.g., +8h.

Time offsets could be used alone in a time field or come with a fixed time or reference-time abbreviation.

12 | P a g e
2.3.5 Time offset syntax

Reference-Time or Fixed Time and Offset Expression

When included with a reference-time abbreviation or with a fixed time, a time offset
adds or subtracts from the specified time (indicated by either + or -) and a time unit
with a value.

Expression Meaning

*-1h One hour ago

t+8h 8:00 a.m. today

y-8h 4:00 p.m. the day before yesterday

mon+14.5h 2:30 p.m. last Monday

sat-1m 11:59 p.m. last Friday

1-jan-15-1d Midnight 31 December 2014

Time Offsets Used Alone

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 Expression 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

2.3.6 Some rules to remember

• Rule 1: You can only include a single time offset in an expression. Including
multiple offsets can lead to unpredictable results. For example, the following time
expressions are not valid:
o * + 1d +4h
o t – 1d + 12h
• Rule 2: To define a time offset you must include a valid value with any time unit.
Only for seconds, minutes, or hours, you can specify a fractional value. You
cannot specify fractional values for other time units.

13 | P a g e
 • Rule 3: A fixed timestamp consists of the fields of Year, Month, Day and Time
(hours, minutes and seconds). If any of these fields are not specified in the PI
time expression, the following values will be assumed by default:
o If Time is not specified, then the default value would be Midnight.
o If Day is not specified, then the default value would be Current Day.
o If Month is not specified, then the default value would be Current Month.
o If Year is not specified, then the default value would be Current Year.

2.3.7 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

* + An hour from now

1h

t + Three days from today at

3d midnight

Y + A year from yesterday

1y

2.3.8 How does PI Adjust for Time Zones and DST?

The short answer is it doesn’t!

When Data Archive collects data, it converts the time 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 Daylight-Saving Time (DST).
So once a year the day will look like it has 23 hours and another 25, but the Data
Archive never knows anything other than 24-hour days.
Also, because the clients and Data Archive know what time zone they are in, the data
can be viewed in either Server Time or Client Time. This is determined by a setting in
the client tool.

14 | P a g e
 Connect to the PI System
PI System Explorer is a way we work with a PI AF server. And it's a way we explore
what's on our PI System. Once we open it, there is a database button. And once we
open the databases, we can see what PI Systems we can connect to. So, when you
hit the drop down, these are the PI Systems that are available. Let’s say I'm interested
in SL3PIAF01. So, I'm going to click on that. And then below, I have a list of all the
different databases that are available. Each one of these PI Systems is like a realm of
data, it's where we stored a lot of data.
Now what if your PI System that you are interested in isn't on this list?

What you can do is you can add the PI System, so you can connect to a system that
you aren't connected to yet. And you do that by pressing the Browse “three dots” icon.
Once you are in here, you'll see a list of all the PI servers that you can connect to. So
right now, I'm already connected to SL3ITPIAF01. If I wanted to add it, all I need to do
is right click, add an AF server or you can just click add AF server. And then you are
brought to a window which asks what PI System do you want to connect to? So, you
just put in the name here, or copy and paste it. And then you press test the connection,
connect to the AF server. And if things were successful, you'll see all these fields will
get filled out. And you can say OK. And then it is there in your list of systems.

The checkmark means this is the default server. So, when I connect, this is the system
that I want to go look at first. Well, let’s say this is not the one I want to use. I want to
use the one I just added. So, I'm going to right click on it, and I can set it as the default
AF server. If you have multiple servers out there, you probably want to set one as the
default, which ever one you use, set as default. Say OK.
So, with PI DataLink, PI DataLink is the plug-in to Excel. So, it's just another tab on
top here. And the way I would connect to different servers is I'll go to settings. And
then connection manager. And I can right click and add an AF server. But I also have

15 | P a g e
the option of adding one of the classic connections, a PI data archive server. I can do
that as well. So, this list includes both of those -- PI Systems and PI servers.

And then in ProcessBook, file, and there are connections and PI Systems. If I select
PI Systems, I get the same dialogue box. Select the database, it's the same one that
I saw in PI System Explorer.

16 | P a g e
3. PI DataLink Basics

Introduction
PI DataLink from OSIsoft allows you to bring PI System data into Microsoft Excel and
since Excel is the world's tool of choice for numbers PI DataLink is a very common
tool for OSIsoft users. PI DataLink is an Excel add in. It has a separate install file that's
downloadable from OSIsoft.com and installed on top of Excel. Once installed PI
DataLink appears on the Microsoft Excel ribbon bar. The handful or so of DataLink
functions are available by clicking the ribbon buttons and are configured with easy-to-
use sidebar wizards. Many people use PI DataLink for either building reports or
analyzing their process.
Reporting: before they first use PI DataLink, we often find people copying or pasting
or importing raw data from text files and with PI DataLink that's completely unneeded.
Your sheets update with live data, and you can ask for more data anytime. At the end
of every day, you can open a reports spreadsheet and PI DataLink replaces
yesterday’s data with today's data and can then email it off. You can have a single
spreadsheet template for all your heat exchanger assets and all you need to do is
select the heat exchanger from this drop-down list and the spreadsheet calls the data
for that heat exchanger. It's all from a single spreadsheet and you save the time you
would otherwise spend collecting and formatting data from all over the plant.
Analysis: so, there are many native Microsoft Excel functions that are very powerful
for analyzing data, but they just aren't designed with time series data in mind and that's
the type of data that the PI system collects for me to process. So, for instance say you
have these sensor readings from the past twenty-four hours, if you want to see the
maximum sensor reading every hour and what time that reading happened PI DataLink
has a function for that and can quickly tell me. To do the same thing with the native
Microsoft Excel function you would need to divide the raw data by hour, run a different
maximum calculation for each hour and then cross reference with the raw data to find
the time that that maximum happened and well that's a lot of steps that PI DataLink
can do in one step. And what's more, if all you want to see are the maximum hourly
sensor readings, you don't even need all the raw sensor data on the sheet at all; you
can clear it away and now the spreadsheet files are much smaller and calculate much
faster without all that raw data
The bottom line is PI DataLink puts PI System data in Excel. As a bonus spreadsheets
run faster with smaller file sizes, and you have special functions for working with all
the time series process data.
If you are using PI DataLink 2013, the add-in should be activated automatically when
you run the install kit. If not, open Microsoft Excel. Then browse to the file section.
Then select options. Then select add-ins. Then at the bottom of the window, you can
then select the com section and press on go. In this section, you should find the PI
DataLink add-in.
If it's not there, you will normally find the file under the program file 32-bit folder. Then
PIPC and then Excel. We can now take a look at the connections of PI DataLink. In
this version, the connection manager will be found under the settings menu at the
bottom of the window. In it, you will be able to see which PI server, the blue one. And

17 | P a g e
which PI AF server, the orange one, you will have access to. If your server is not there,
to add it, simply right click in a blank section of the window and select add another
server, either PI AF server or PI server. All you would need to enter after that is simply
the name or the IP address of the machine hosting your server.

Mind map of PI DataLink

The functions found in PI DataLink are setup in three different sections. The single
value section, the multiple value, and the calculated value section.

In the single value, you will find the current value function and the archived value
function. The current value returns the latest value available that we also call snapshot
value for a specific data item of your system. As for the archive value function, you will
obtain a value of a tag or attribute for a specific moment in time
The multiple value section is composed of the compressed data function, the sample
data function, and the time data function. The compressed data will return all the
archived value of your PI system for a data item. The sample data works a little bit the
same way as the compressed data function. But this time, instead of getting all the
archive value, you will get the value that would follow a specific time interval.
Finally, the last function of this section is the time data function. This function will return
the value for a specified timestamp. The calculated data section is composed of two
different functions which would be the calculated data and the time filter function. The
first one will return a calculation such as the average, the minimum, the maximum or
the total over a specific period of time for a data item. The time filter function will return
the time spent respecting specific criteria for a data item.

Search for PI Tags and PI AF attributes

You can search for an attribute or group of attributes. You may want to locate a
particular attribute, for example, to configure a formula data reference or to assign it
as a value to another attribute. (To search for a specific attribute value, choose an
attribute value as search criteria for an element search.)

18 | P a g e
Procedure
1. In the navigator pane, click Elements.
2. Choose from the following actions
a. From the PI System Explorer menu, select Search > Attribute Search.
b. In the browser, right-click the Element Searches collection and select New
Attribute Search.
3. Set the Attribute Search window to find the desired attributes in the PI AF database:
a. Under Where, set the fields to restrict attributes retrieved:
i. Attribute name - Enter the name of the attribute to retrieve. You can
enter special characters to match part of a name.
ii. Attribute description - Enter a string (of up to 440 characters) that
retrieved attributes must match.
iii. Attribute category - Select the category that retrieved attributes must
match.
iv. Attribute value type- Select the type of value that the retrieved attributes
must store.
v. Maximum results - Enter the maximum number of matching attributes to
retrieve.
b. In the Element Criteria area, set the fields to restrict the elements searched for
matching attributes:
i. Search Root - Enter the element that you want to use as the root or base
level for the attribute search. Type the exact name or click Browse (…) to
open the Element Browser window, where you can view the element
hierarchy and select an element. You cannot include wildcard characters
in the entered name. If you do not specify an element, you set the main
level of the element hierarchy as the root. Depending on your PI AF
hierarchy, specifying an element in the Search Root field can improve
search performance. Select the Search Sub-Elements check box to
search the entered root and any sub-elements. Clear this check box to
search only the entered root.
ii. Name - Enter the name of the elements in which you want to search for
attributes. You can enter special characters to match part of a name.
iii. Description - Enter a string (of up to 440 characters) to retrieve only
those elements that match.
iv. Category - Select the category of the elements in which you want to
search for attributes.

19 | P a g e
 v. Template - Select the template of the elements in which you want to
search for attributes.
vi. Type - Select the type of the elements in which you want to search for
attributes.

If you specify values for multiple settings, the search returns only those attributes that
match all the specified settings.

4. Click Search to retrieve the matching attributes into the Search results table.
Alternatively, use the element tree under Search results to browse for attributes under
particular elements, and then select the attributes to add them to the Search results
table.
Remember that the attributes available by searching and the attributes available by
browsing the element hierarchy depend on the configuration properties of the attributes.
5. Select items in the search results list and click OK.
The results are displayed in the viewer and in the browser tree.

Get instantaneous PI data with PI Current Value Function

The Current Value function returns the most recent value of a historical PI point or PI
AF attribute. For a future PI point, the value returned depends on the time stamps of
recorded values relative to the current time:
• If all recorded values have time stamps before the current time, the function returns
the last recorded value.
• If recorded values have time stamps that straddle the current time, the function
returns an interpolated value.
• If all recorded values have time stamps after the current time, the function returns
no data.
What do we need to call for the current value of something in our PI System?
Root path – the common path to specified data items
Data item – one or more PI point names or PI AF attribute
names, for which the function returns values.
Output cell - where on the sheet we will put the actual
output
No time stamp - return only values
Time at left - the time stamp in the left column and the value
in the right column.
Time on top - return two rows: the time stamp in the top row
and the value in the bottom row.

20 | P a g e
 Get historical PI Data with PI Archive Value Function
If you select the Data item option, the Archive Value function returns the value of a PI
point or a PI AF attribute at a specified time stamp. This function supports bulk calls.
If you select the Expression option, the Archive Value function returns the computed
value of a performance equation at a specified time stamp.
Root path – the common path to specified data items
Data item – one or more PI point names or PI AF attribute
names, for which the function returns values.
Expression - One or more performance equations that the
function computes a value for.
Time stamp – the time stamp for which the function returns
values. Specify either a fixed time or a time expression
relative to the current time.
Retrieval mode – Available if you select the Data item option.
The method the function uses to determine returned values:
previous (returns the value that exactly matches or precedes
the specified time stamp), previous only (returns the value
that precedes the specified time stamp), interpolated (returns
the interpolated value at the specified time), auto (returns the
interpolated value at the specified time, or follows the
previous method, uses the previous method for data items
with step attributes), next (returns the value that exactly matches or follows the
specified time stamp), next only (returns the value that follows the specified time
stamp), exact time (returns only a value that exactly matches the time stamp, or
returns No events found if no value exists at that time stamp).
Output cell - where on the sheet we will put the actual output
No time stamp - return only values
Time at left - the time stamp in the left column and the value in the right column.
Time on top - return two rows: the time stamp in the top row and the value in the
bottom row.

Use Root Path References

The root path is the common path to specified data items. Valid entries include:
• PI Data Archive server name if the data item is a PI point.
• PI AF server and database if the data item is a PI AF attribute.
• Blank if the data item is a PI point on the default PI Data Archive server.
When you define a function, you specify the paths to data items with the Data item,
Expression, and Filter expression fields along with the optional Root path field. You
can specify:

21 | P a g e
• Fully qualified paths in the Data item, Expression, or Filter expression fields. A fully
qualified path begins with two backslashes (\\) and evaluates to either a PI point
or a PI AF attribute.
• Partial paths in the Data item, Expression, or Filter expression fields and the
common base path in the Root path field. PI point names or PI AF attribute names
are examples of partial paths. PI DataLink combines the common base path with
the partial path to set the full path that evaluates to either a PI point or PI AF
attribute.
PI DataLink requires a full path to find the data item. To find a PI point, PI DataLink
must know the PI Data Archive server to search and the point name. To find a PI AF
attribute, PI DataLink must know the PI AF server, the database, the element, and any
sub-elements or parent attributes. Use a pipe (|) to separate attributes from elements
or parent attributes.
You can leave the Root path field blank if the Data item, Expression, and Filter
expression fields contain a fully qualified path or a PI point on the default PI Data
Archive server.
If specified, the Root path field indicates the common path to the specified data items.

Type of data
Content of root-path field
item

PI Data Archive server that stores the point or a blank to indicate the default PI Data Archive server.
PI point Valid entries include:

• MyPIDataArchiveServer
• \\MyPIDataArchiveServer

PI AF server and database along with any elements, sub-elements, and parent attributes not specified
PI AF attribute in Data item. Valid entries include:

• \\MyPIAFServer\MyDatabase
• \\MyPIAFServer\MyDatabase\MyElement
• \\MyPIAFServer\MyDatabase\MyElement\MySubElement
• \\MyPIAFServer\MyDatabase\MyElement|MyParentAttribute
• \\MyPIAFServer\MyDatabase\MyElement|MyParentAttribute1|MyParentAttribute2

Note: The PI AF server and database must be in the same field. You cannot specify
the PI AF server in the Root path field and the database in the Data item field.

Build KPI Reports

So, let's start with a blank spreadsheet. The first thing you will need to do is to define
the different data that you will want to obtain the KPIs. The easiest way to obtain such
information within PI DataLink is to use the search functionality that you find just right
there. If you click on the icon, you will have two different options, the first one will be
search through the PI Server, for the PI Points you're interested, but the other problem
with that kind of search is that you need to know every single name of those points.
The second option, which is easier, is to browse through the error key of the PI AF

22 | P a g e
Database, in order to find elements that you are looking for. In that case, if you browse
into the wind field PI database, and select the wind field generation fleet and Black
Mesa Windfarm you will be able to search for a common KPI. Let's say, in the case
the monthly energy actual. This will be the first KPI we are interested in.

What you will be able to do after that is to separate the root path from the data item to
present the KPIs in the form of a table. In this case the root path selection represents
different windmills found in the farm, and the data item is the actual KPI value. Once
this is selected, you can either import it in column or row or in a drop-down list. For
this one let's just select a column or row options, and import. All you have to do is click
on OK. Once this is done, we can select the other KPIs we are interested in. So, you
can either search for them with the search functionality or if you know their name,
simply write it down like this into the Excel spreadsheet. Once this is done, you can do
the same thing but this time for daily KPIs. So, if you open the search panel, you will
be able to select the root path, but this time for the daily KPI. And this time you will
select the drop-down list. After that, all we need to do is add the different KPIs to the
table, and we're set as for the data icon.
Now that this is done, let's get the first value of the first KPI, in this case it will be the
monthly energy actual. In order to obtain the last value for this data item, we will be
using the current value function, the function that returns the latest value from a
specific data item of your PI Service. If we click on this function, a panel will open on
the right side of the screen. We can see that there are only three sections. The first
section, the root path is the value we obtained from the search function. In this case,
this value also represents the wind mill we are interested in. The second one, the data
item, is the actual KPI. And finally, the last one, is the output cell, is where you want
the value to be shown. We could simply directly enter the values in the corresponding
fields of the function, but it's a lot more practical to use the cell references. Cell
reference will give you the opportunity to change any parameters of the function
directly from your spreadsheet, making your reports a lot more dynamic.

23 | P a g e
4. Compressed, Sampled and Calculated Data

Get Raw PI data with PI Compressed Data Function

If you select the Time range option, the Compressed Data function returns all the values of a PI
point or PI AF attribute along with a count of values that occur during a specified time period.
If you select the Number of values option, the Compressed Data function returns a specific
number of point values or attribute values beginning at a certain time.
Note: Values stored in the archive of PI Data Archive undergo a compression algorithm that
removes all values that represent the same slope. Values stored in the PI Data Archive snapshot
have not undergone this compression algorithm. If you specify the current time in the time period
of the Compressed Data function, the function retrieves a snapshot value for that time. That
snapshot value might not be subsequently stored in the archive due to compression.

Root path - The common path to specified data items, including those
in expressions.
Data item(s) - One or more PI point names or PI AF attribute names, for
which the function returns values.
Start time - The start of the time period for which the function returns
values.
End time - The end of the time period for which the function returns
values.
Number of values - The number of values that the function returns,
beginning at Start time.
Backwards in time - Select this check box to return values recorded at
Start time and earlier. Available if you select the Number of values option
and enter a value in the Number of values field. If you enter a cell
reference in the Number of values field, this check box is disabled.
Filter expression - A Boolean performance equation that the function uses to filter values. When
the expression evaluates to false, the function excludes corresponding values.
Mark as filtered - Select this check box to insert the label “Filtered” in place of a value or block
of values that the function filtered from the output based on Filter expression.
Boundary type – The method that the function uses to determine which values to return near the
start time or end time:

• inside (default) - Returns values at start and end times, if they exist, or the nearest values
that occur within the range.
• Outside - Returns the nearest values that occur immediately outside the range.

24 | P a g e
 • Interpolated - Returns interpolated values at the start and end times.
• Auto - Returns interpolated values, but uses the inside method for data items with step
attributes.
Output cell - The worksheet cell where the function writes the resulting function array.
Hide count - Select this check box to hide the count of returned values and show only returned
values. Available if you select the Time range option.
Show time stamps - Select this check box to show the time stamp that corresponds to each
returned value. PI DataLink shows time stamps to the left of values displayed in a column or
above values displayed in a row.
Show value attributes - Select this check box to show the extended status bits associated with
returned values. PI DataLink shows value attributes in a column to the right of the values. Possible
status bits include:

• A - Annotated. Indicates the value has a comment.

• S - Substituted. Indicates the value has changed from its originally recorded value.
• Q - Questionable. Indicates that there is some reason to doubt the accuracy of the value.
Show annotations – Select this check box to show annotations associated with returned values.
Annotations contain notes or comments that describe a data value. PI DataLink shows
annotations in a column to the right of the value.
Column – Click this option to return values in a column.
Row - Click this option to return values in a row.
Note: If you specify a range of items in Data item(s) or a range of expressions in Expression(s),
PI DataLink automatically selects Column or Row to match the orientation of the specified range.

25 | P a g e
 Get Custom Interval PI data with PI Sampled Data Function
If you select the Data item option, the Sampled Data function returns evenly spaced,
interpolated values for a PI point or PI AF attribute over a regular interval.
If you select the Expression option, the Sampled Data function returns evenly spaced,
interpolated values of a performance equation over a regular interval.

Root path - The common path to specified data items, including those
in expressions.
Data item(s) - One or more PI point names or PI AF attribute names,
for which the function returns values.
Expression - One or more performance equations that the function
computes a value for.
Start time – The start of the time period for which the function returns
values.
End time – The end of the time period for which the function returns
values.
Time interval - The frequency that the function returns calculated
values during the time period. Enter a value and time unit. For
example, enter 15m (15 minutes) to return a value for every 15-minute
interval in the time period.
Filter expression - A Boolean performance equation that the function uses to filter values.
When the expression evaluates to false, the function excludes corresponding values.
Mark as filtered - Select this check box to insert the label Filtered in place of a value or block of
values that the function filtered from the output based on Filter expression.
Output cell - The worksheet cell where the function writes the resulting function array. If you
select a cell before you open the function task pane, PI DataLink inserts the selected cell into
the Output cell field.
Show time stamps – Select this check box to show the time stamp that corresponds to each
returned value. PI DataLink shows time stamps to the left of values displayed in a column or
above values displayed in a row.
Column – Click this option to return values in a column.
Row - Click this option to return values in a row.
Note: If you specify a range of items in Data item(s) or a range of expressions in Expression(s),
PI DataLink automatically selects Column or Row to match the orientation of the specified
range.

26 | P a g e
 Functions returning Data
With PI DataLink functions, you can query any Data Archive or AF server, apply
calculations to retrieved results and return values to worksheet cells. These functions
return results in function arrays, which you can recalculate to update values as
needed.

Query Category Function Name What it Returns

Single value Current Value The current or most recent value of a Data
Item

Archive Value Value of a Data Item at a specified time

stamp

Computed value of a performance

equation at a specified time stamp

Multiple value Compressed All the values of a Data Item for a

Data specified time period

A specific number of Data Item values

beginning at a certain time

Sampled Data Evenly spaced, interpolated values for a

Data Item over a regular interval

Evenly spaced, interpolated values of a

performance equation over a regular
interval.

Timed Data Actual or interpolated sample values for a

Data Item at specified time stamps

Values of a performance equation

computed at specified time stamps

Calculation Calculated Data One or more evenly spaced, calculated

values based on a Data Item’s values and
specified calculation preferences

One or more evenly spaced, calculated

values based on an evaluated
performance equation and specified
calculation preferences

Time Filtered The amount of time that a performance

equation evaluates to true during a
specified time period

4.3.1 Directed Activities – Single value queries

Learning Outcomes

• Retrieve a current value for a data item

• Retrieve an archived value for a data item

27 | P a g e
 • Describe the different retrieval modes
• Retrieve data item attributes

Directed Activity – Single Value Query

You are invited to perform the same steps at the same time to explore the
different concepts presented in this chapter or section. Use your own data
if you have access to such data.

Objectives
• Perform Single Value Queries in PI DataLink

Activity Description
We would like to prepare a report that shows the current value of External Temperature,
Pressure and Flow Rate of Mixing Tank2. You are also interested in knowing the value of these
measurements at 7 am yesterday.
Approach
Part 1 – Get Current Values
Step 1 : Open Excel and in cell A1 type Current Values as a heading.
Step 2 : Click on cell A2. Select Current Value function.
Step 3 : Click on the magnifying glass next to Data Item(s) box.
Step 4 : Search for the External Temperature of Mixing Tank2.
Step 5 : Select Time at Left and click OK.
Step 6 : Repeat these steps for Pressure and Flow Rate in cells A3 and A4, respectively.
Part 2 – Add Archive Values
Step 1 : In cell C1 type Archive Values as a heading.
Step 2 : Click on cell C2. Select Archive Value function.
Step 3 : Click on the magnifying glass next to Data Item(s) box.
Step 4 : Search for the External Temperature of Mixing Tank2.
Step 5 : Type Y+7h in the Time stamp box. What time stamp will be retrieved? ___________
Step 6 : Select Time at Left and click OK.
Step 7 : Repeat these steps for Pressure and Flow Rate in cells C3 and C4, respectively.

28 | P a g e
Part 3 – Do you think this is an efficient way to search for the data item every time a value is
retrieved?

Directed Activity – Single Value Query Using Cell Reference

You are invited to perform the same steps at the same time to explore the
different concepts presented in this chapter or section. Use your own data
if you have access to such data.

Objectives
• Perform Single Value Queries in PI DataLink

Activity Description
You would like to include the current value of External Temperature of Mixing Tank1 in your
daily report. You are also interested in the value of this tank’s Internal Temperature at 7 am
today.
Approach
Part 1 – Build a Template

Step 1 : Open Excel and click on cell A2. Click on Search.

Step 2 : Select the AF Database of OSIsoft Plant. Type Ext*Temp* in the search box and
click ‘Enter’. The External Temperature of all four tanks should show up on the
search results list.

Step 3 : Select the external temperature of Mixing Tank1 and click OK.
Step 4 : In cell B1 type Current Value. In cell D1 type Archive Value as headings.
Step 5 : In cell A4 type Timestamp, in B4 type t+4.5h. What time do you expect to see?
___________
Step 6 : Your report template will look similar to this:

29 | P a g e
Part 2 – Query PI Data
Step 1 : Select cell B2 (this will be your Output cell). Click on Current Value function.
Step 2 : Refer to cell A2 in the Data Item field and select Time at left. Click OK.
Step 3 : Select cell D2 (this will be your Output cell). Click on Archive Value function.
Step 4 : Refer to cell A2 in the Data Item field. In the Time stamp field refer to cell B4. Do
not change any of the other options. Select Time at left and click OK.

Exercise –Temperature at a Glance

This solo or group activity is designed to maximize learning in a specific

topic area. You can access the PI Square space of this course if you need
assistance during the activity. Use your own data if you have access to
suitable data.
Objectives
• Extract values and attributes from the PI System using the following functions:
• Current value
• Archive value

Activity Description
You would like to include the current value of the External Temperature of all Tanks in your
daily report. You are also interested in knowing the value of the tanks’ Internal Temperature at 7
am today.
Approach
Step 1 : Open the file PI_DataLink-Exercises.xlsx.
Step 2 : Save it as<your initials>_ PI_DataLink-Exercises.xlsx then work on sheet
Temperature at a Glance and fill in data into all of the fields.
Step 3 : Use the Current Value and Archive Value queries to fill in the template. We should
base our PI DataLink queries on cell references whenever possible.

Exercise – Activity Report

This solo or group activity is designed to maximize learning in a specific

topic area. Access the PI Square space of this course if you need
assistance during the activity. Use your own data if you have access to
such data.

30 | P a g e
Objective
• Extract values and attributes from the PI System using the following functions:
• Current value
• Archive value

Activity Description
Your manager needs a report they can open each afternoon to see the current values of KPI’s
for Mixing Tank2, which are:
• External Temperature
• Internal Temperature
• Level
• Flow Rate

Your manager needs to see the KPIs values at 9 AM this morning. Not trusting this new “PI
Thing” your manager wants to see archive values around 9 AM as well as be able to type in a
timestamp and see if there is an archive value at an exact time.
Approach
Step 1 : Open <your initials>_PI_DataLink-Exercises.xlsx then work on sheet Activity Report
and fill in data into all of the fields.
Step 2 : Use the Current Value and Archive Value queries to fill in a template.

 Quick Check

Can you:
• retrieve a current value?
• retrieve an archived value?
• describe the different retrieval modes?
• retrieve data item attributes?

If you answered NO to any of these questions, join the community on PI Square for assistance.

31 | P a g e
4.3.2 Directed Activities - Multiple Value Queries

Directed Activity – Archived, Sampled and Timed Data Functions

You are invited to perform the same steps at the same time to explore
the different concepts presented in this chapter or section.

Objectives
• Retrieve archive data with the different multiple value functions

Activity Description
You would like to analyse the archived values of the External Temperature of Mixing Tank1 in
your daily report for the first two hours of every day. You would also like to see this temperature
value every 10 minutes during these two hours.
You are also interested in doing a comparison between Mixing Tank1 and Mixing Tank2 at the
timestamps where there is a value archived for external temperature of Mixing Tank1.
Approach
Part 1 – Build a Template
Step 1 : In Excel, create a Template for your report by typing Data Item, Start Time, End
Time and Time Interval in cells A1, A3, A4 and B5, respectively.

Step 2 : Using Search, find the attribute External Temperature for Mixing Tank1 and Mixing
Tank2 and place them in cells B1 and B2, respectively.

Step 3 : Type the Start Time of T (in cell B3), End Time of T+2h (in cell B4) and time interval
of 10m (in cell B5).

Part 2 – Query PI Data

Step 1 : Obtain the compressed data for Mixing Tank1 External Temperature and list it in cell
C3.
Step 2 : Do the same for Mixing Tank2 in cell G3.
Step 3 : Obtain the sampled data for Mixing Tank1 External Temperature in cell E3.
Step 4 : Comparing the timestamps of the compressed data for the two mixing tanks you
notice they are not the same so the comparison can’t be accurately done. To have

32 | P a g e
 a better comparison, use Timed Data function and get the External Temperature of
Mixing Tank2 at the timestamps in Column C.

Exercise – Tank Analysis Report

This solo or group activity is designed to maximize learning in a specific topic

area. Ask the PI Square community if you need assistance during the
activity. Use your own data if you have access to suitable data.

Objective
• Extract values and attributes from the PI System using the following functions:
Compressed Data, Sampled Data.

Activity Description
Show the archived values of the Pressure of the two Mixing Tanks listed in your daily report for
the past 24 hours. When retrieving the raw archived data for this process variable, you prefer to
see one value each hour for the past 24 hrs.
You will use this report to do some analysis on this critical process variable of the mixing tanks.
Approach
Step 1 : Spend a few minutes and fill out the following table:

Data Item

Start Time

End Time

Time
Interval

Step 2 : Open <your initials>_PI_DataLink-Exercises.xlsx then work on sheet Tank Analysis

Report and fill in data for all of the fields.
Step 3 : We will use the Compressed Data and Sampled Data queries to fill in a template.
Bonus 1
Using Excel functions, modify your report such that you get one value at the top of each hour
for the past 24 hours.

33 | P a g e
 Bonus 2
The Excel Insert tab in the Sparklines section has several options to show lines and columns
as well as additional options to format the axes and colors.
To use this functionality, first select the cell where you want to place the Sparkline. Then choose
the Sparkline type. For Data Range, select the cells with the data (just select the values, not the
timestamps). Verify your output cell and choose OK. The result is a small trend of your data, with
an assumption of evenly spaced values over time.

 Quick Check
Can you:

• Retrieve compressed data for a point?

• Retrieve sampled data for a point?
• Retrieve timed data for a point?

If you answer NO to any question, ask the PI Square community for assistance.

Interpolation and Retrieval Modes in PI DataLink

4.4.1 Interpolated Values

Many PI DataLink functions can return interpolated values, useful for PI points associated with
time stamps. For example, you might request that the Archive Value function return an
interpolated value at a particular time stamp rather than the last recorded value that precedes the
time stamp. The interpolated value depends on the time stamps of the recorded values and
possibly on the type of PI point:
• For time stamps before the first recorded value, the function returns either Pt Created or No
Data.
• For time stamps between two recorded values, the function determines the value at the time
stamp using linear interpolation between the recorded values. For points that store discrete
values, such as digital state points or step points, the function returns the last recorded value
that precedes the time stamp.
• For time stamps after the last recorded value, the returned value depends on the point type:
o For historical PI points, the function returns the most recent value.
o For future PI points, the function returns No Data.

34 | P a g e
4.4.2 Retrieval Modes

When bringing the archive value to our report, we saw that a timestamp needs to be specified
and the archived value will be retrieved for that timestamp. There may or may not be a value
archived at the specified timestamp; how does PI DataLink decide just what data is retrieved?
You can decide the data retrieval behavior by selecting different options from the Retrieval Mode
drop down list. The default option is Auto. Different modes will retrieve the value differently, as
listed in the following table:
Retrieval Mode Data retrieval behavior
Auto (Default) Interpolates at the exact timestamp provided,
unless the data item is a step point, which would retrieve
the previous value.
Interpolated Always interpolates at the exact timestamp provided.

Previous, Next Retrieves the previous or next compressed event from the
timestamp specified. If a compressed event does exist at
the exact timestamp, it is retrieved.

Previous Only, Next Only Same as Previous, Next, except it will ignore any event at
the exact timestamp specified.

Exact Time Retrieves the value if and only if an archived value exists
at that exact timestamp (down to the second).

The graph and table below exemplify the different retrieval modes.

Retrieval Mode Timestamp Value

Interpolated 13:00:00 1.8
Previous 12:30:00 2.5
Next 13:30:00 1
Exact No events found No events found

35 | P a g e
The next graph shows the difference between Auto and Interpolated for a step point and
an analogue point.

Auto Interpolated
Step OFF (Rate point) 13:00:00 – 2 13:00:00 – 2
Step ON 12:30:00 – 2.8 12:30:00 – 2.8

Get Time-Summary Calculations with PI Calculated Data Function

If you select the Data item option, the Calculated Data function returns one or more evenly
spaced, calculated values based on PI point or PI AF attribute values and specified
calculation preferences. If you specify no filter expression and no time interval, the function
supports bulk calls.
If you select the Expression option, the Calculated Data function returns one or more evenly
spaced, calculated values based on an evaluated performance equation and specified
calculation preferences.

Root path - The common path to specified data items, including those in
expressions.
Data Item(s) - One or more PI point names or PI AF attribute names, for
which the function returns values.
Expression(s) - One or more performance equations that the function
computes a value for.
Start time – The start of the time period for which the function returns
values.
End time – The end of the time period for which the function returns
values.
Time interval - The frequency that the function returns calculated values
during the time period.

36 | P a g e
Filter expression - A Boolean performance equation that the function uses to filter values. When
the expression evaluates to false, the function excludes corresponding values.
Conversion factor - A factor that the function applies to returned values. Enter 1 if a conversion
factor is not needed. For time-weighted total calculations, specify a factor that converts recorded
rate values to the server default time unit (units per day).
For example, common conversion factors include:

• for values that store units/day

• 24 for values that store units/hour
• 1440 for values that store units/minute
• 86400 for values that store units/second
Calculation mode - The type of calculation that the function performs:

• total - Sums values during the interval.

• minimum - Finds the minimum value during the interval.
• maximum - Finds the maximum value during the interval.
• standard deviation - Computes the standard deviation of values during the interval.
• range - Computes the maximum value minus the minimum value during the interval.
• count - Counts the number of seconds in the interval if the Calculation basis field is set to
time weighted. Counts the number of values stored during the interval if the Calculation basis
field is set to event weighted.
• average (time-weighted) - Computes the time-weighted average of the recorded values
during the interval.
• average (event-weighted) - Computes the event-weighted average of the recorded values
during the interval.
Calculation basis - The calculation method:

• time-weighted - Default for all calculation modes except for event-weighted average. The
function weights each recorded value by the length of time that the value applies. The function
interpolates values at the interval boundaries.
• event-weighted - The function weights each recorded value equally. Select this option for
batch values. This method requires at least one recorded value in a time period (two recorded
values for standard deviation calculations).
If you enter an expression in the Expression(s) field and set the Expression sampling field to
interpolated, then the function interpolates values at the time interval boundaries when there are
no recorded values.
Expression sampling - The method that the function uses to determine when to evaluate an
expression:

• Compressed - The function evaluates the expression during the time period at time stamps
where PI points or PI AF attributes in the expression have stored values. If there are no stored
values, the function returns either no value or an interpolated value. For best results, select
interpolated rather than compressed during time periods with few stored values.

37 | P a g e
• Interpolated - The function evaluates the expression at evenly spaced sampling intervals,
determined by Expression sampling frequency.
Expression sampling frequency - The frequency that the function evaluates an expression.
Required if you set Expression sampling to interpolated.
Minimum percent good - The minimum percentage of good data required in each time interval
to calculate and return a value for that interval. The function returns the label “Insufficient good
data” for an interval that does not meet this percentage.
Output cell - The worksheet cell where the function writes the resulting function array.
Show start time – Select this check box to show the start time of the time interval used to
calculate the returned value.
Show end time – Select this check box to show the end time of the time interval used to calculate
the returned value.
Show min/max time – Select this check box to show the time stamp that corresponds to the
minimum or maximum value during the interval used to calculate the value.
Show percent good - Select this check box to show the percentage of time that good values
were returned during the array time period. Good values are recorded values that PI Data Archive
determined were valid, and not in an error state.
Column - Click this option to return values in a column.
Row - Click this option to return values in a row.
With calculated data you can very easily do all these calculations on the PI Server, so you don't
need to have your spreadsheet filled with lots of raw values that then you're doing calculations
with Excel calculations on. It can all be done on the PI Server, which is faster, you'll have a lighter
weight spreadsheet. You can do all sorts of powerful time range calculations; things that aren't
available to you in the standard Excel functions.

PI Calculated Data Function – hourly range of values

To see the hourly range of values from midnight today until the present time for the PI point
sinusoid, set the following inputs for the Calculated Data function:

Input Value
Data item(s) sinusoid
Start time T
End time *
Time interval 1h
Calculation mode range
Calculation basis time-weighted
Show start time selected
Show end time selected
Column selected

38 | P a g e
In this example, the function calculates the range for each one-hour interval. You can specify any
available calculation over any interval. The function returns the following array:

Exercise – Production Summaries

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.

Objective
• Extract calculated values using the Calculated Data function.

Activity Description
As the production manager, you want to create a report showing last week’s
production statistics. You want to display the following for the production from each
day of the past week:
• Total
• Average
• Maximum
You also want to do the same calculations for the entire week.

Approach
Step 1 : On the PI Server, the production is the sum of the productions from the two
production lines and is stored as an attribute named Production under the element
of Production Area. It is defined as the sum of the flows of the two Mixing Tanks in
litres per minute.
Step 2 : Spend a few minutes and fill out the following table:

39 | P a g e
 Root
Path

Data
item

Start
time:

End
time:

Time
interval:

UOM

Step 3 : You will use the template provided in sheet Production Summaries of the file <your
initials>_PI_DataLink-Exercises.xlsx. Use the values of your table in the provided
template.

Note:

When working with the weekly total, do not use the time interval. Only use it for the daily
total (hint).

Be sure to show the Start Time for the daily Calculations.

The percent good field is located to the right of an aggregate calculation, so use
with the Maximum.

 Quick Check
Can you:
• Obtain calculated values?
• Obtain filtered values?
• Understand Conversion factors?

If you answered NO to any of these questions, ask your instructor for assistance.

40 | P a g e
5. Using Time Filtered Data in a Preventative
Maintenance Example

Learning Outcomes
• Using the Time Filtered Function

Time Filtered Data

You have a Pump and would like to implement a Preventative Maintenance program.
Firstly, you need to determine the period that the pump was running. These total hours
can then be checked against the replacement period as indicated in the pump
manufacturer’s datasheet; every 10,000 hours, for example.
If you have a PI Point recording the status of the pump (when it is ON or OFF) you can
report your Preventative Maintenance program by using the Time Filtered function.
This function returns the amount of time that a performance equation evaluates to true
during a specified time period.
You need to specify the following fields for this function:
• Expression(s)
o Can specify 1 or more and it would follow the Performance Equation format. Data
items permitted in expressions are:
PI points
AF attributes that store data references to PI points
AF attributes that store constant values
• Start Time and End Time.
• Time Unit
o i.e. The pump was running for 5 seconds/minutes/hours/days

41 | P a g e
Directed Activity – Controller state

You are invited to watch what the instructor is doing or perform the same
steps at the same time to explore the different concepts presented in this
chapter or section.

Objectives
• Extract Time Filtered data in PI DataLink

Activity Description
We want to determine the amount of time a controller has been in the CASCADE state. The
controller is a digital point, named CDM158, and has five (5) discrete states. We are only
concerned with the CASCADE state at this time.

Approach
Step 4 : In Excel create a label for the output cell Time in Cascade mode (hours).
Step 5 : Choose an empty output cell.
a. Select the Time Filtered function.
Step 6 : Use the following values for different fields:
a. Expression(s): ‘CDM158’ = “CASCADE”
b. Start Time: T-3d
c. End Time: T
d. Time Units: Hours

42 | P a g e
Directed Activity – Mixing Tank Level Control

You are invited to watch what the instructor is doing or perform the same
steps at the same time to explore the different concepts presented in this
chapter or section.

Objectives
• Use an expression in the Time Filtered function

Activity Description
Mixing tank1 level going above 7 is an indication of malfunctioning of the pump. In our analysis
report, we want to find out for how many hours the pump was malfunctioning during yesterday.

Approach
Step 1 : In Excel create a report template similar to the screenshot at the end of the activity.
Step 2 : Select cell B1 and search for the Mixing Tank1 Level attribute.
Step 3 : Modify the expression and apply the PE syntax rules to ‘level’>7

Important Note: The first ‘ in an Excel cell is used to signify that the cell content is text and that
no Excel formulas should be interpreted. To include an expression in a cell, you need to put a ‘
at the beginning of the expression.

Step 4 : Complete the report template with these values:

a. Start Time: T
b. End Time: Y
c. Time Units: Hours
Step 5 : Select the Time Filtered function and use the output cell as B6.

43 | P a g e
Exercise – Condition based Inspection

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.

Objective
• Calculate the operating time with the Time Filtered function.

Activity Description
The pumps on our mixing and storage tanks need to be visually inspected every 4
months only if they have been running for over 2,000 hours. As the person in charge
of the Preventative Maintenance program, you want to know the operating time for
the pumps on the tanks.
A PI Point does not exist to determine if the pump is ON or OFF, but the pump only
runs when the tank Level is greater than 1.2. Find the amount of time the pumps on
each of the tanks have been running for the past 4 months and find out if any of the
pumps need to be inspected.

Approach
You will use the template provided in sheet Condition Based Inspection of the file
<your initials>_PI_DataLink-Exercises.xlsx. Get the total Operating Time of the
pumps associated with tanks.
Step 1 : Use Asset Filter Search to bring the list of Assets without any attribute.
a. Specify the appropriate Root Path and Element Template in the search dialogue
box and without selecting any attributes, click Ok.
Step 2 : Use Time Filtered function to calculate the number of hours each pump was
running.

44 | P a g e
 Quick Check
• Can you use the Time Filtered function?
If NO, then ask your instructor for assistance.

45 | P a g e
6. Filtered Data Using Custom Expressions

Learning Outcomes
• Using Filtered expressions

When using different PI DataLink functions, we noticed an optional field of

Filter Expression.

This option is available for the functions of:

• Compressed Data
• Sampled Data
• Calculated data
PI DataLink applies the filter expression to the raw data retrieved and only the values
that make the specified expression True, would be included. Therefore, for the two
functions of Compressed Data and Sampled Data, only the values that make the
specified filter expression True would be listed in the output cell. For the Calculated
Data function, only the raw values that make the filter expression True, would be
considered in the calculations. With the use of Filter Expression, an option of Mark
as filtered becomes available for the Compressed and Sampled Data functions; if
the Mark as filtered option is selected, a Filtered status is returned for each group
of values that does not satisfy the filter expression.
The Filter Expression is a performance equation and follows the formatting rules
discussed in the previous section.

Note: When using a cell reference for your Filter Expression, be sure that if the Filter Expression
begins with a timestamp or point name that you use two single quotes. The first single quote is
used in Excel to identify a text string, rather than a value, and will not be seen by the filter
expression. Another option is to enclose the entire filter expression in parenthesis, in which case
the extra single quote is not needed.

For more information see the “Expressions” section in the PI

DataLink User Guide.

46 | P a g e
Excel Conditional Formatting

This topic is not specific to PI DataLink, but the Conditional Formatting found in
Microsoft Excel can give your PI DataLink reports a great perspective. It is useful for
visually comparing values extracted from PI. Conditional Formatting is found in the
Home Ribbon in the Styles section. You can use this functionality to provide
highlighted maxima or minima, bar graph backgrounds, and many other visual cues
about the data being displayed.
To use this functionality, first highlight the group of cells you wish to format. Then
click on the Conditional Formatting button and choose a group and rule. For the
Highlight Cells Rules and Top/Bottom Rules, you will see a preview of the
formatting once you configure the appropriate limits. For Data Bars, Colour Scales
and Icon Sets, simply hover the mouse over each preconfigured option to preview
its effect on the cells you selected. Click the desired rule to select it.
If none of the preconfigured rules suit your needs, you can configure additional rules
using Conditional Formatting > New Rule. Multiple rules can be applied in
configurable order using Conditional Formatting > Manage Rules.

Note: The MS Excel TODAY() function returns the serial number of the current date. The serial
number is the date-time code used by Microsoft Excel for date and time calculations. Microsoft
Excel stores dates as whole number of days starting at 1900. Dates and times are values and
therefore can be added, subtracted, and included in other calculations.

Syntax: =TODAY()

Example: =(TODAY() - 10 + 16/24) is today minus 10 days at 4 PM

47 | P a g e
Directed Activity – Filtered Data Value Queries

You are invited to watch what the instructor is doing or perform the same
steps at the same time to explore the different concepts presented in this
chapter or section.

Objectives
• Apply a filter expression to the values retrieved using Compressed Data function

Activity Description
Retrieve data using the Compressed Data function and filter out all values below 150 because
they are irrelevant to our report.

Approach
Part 1
Step 3 : In Excel create a sheet with
o Data Item: CDT158
o Start Time: T
o End Time: T-1d
o Filter Expression: ‘‘CDT158’ > 150
Step 4 : Retrieve the Compressed Data and verify there are no values less than 150.
Step 5 : Values below 150 are unnecessary and we would not need to include them on our
report.
Part 2
Step 6 : On a new sheet, create a sheet with
o Tank: \\PISRV01\OSIsoft Plant\Production Area\Production Line1\Mixing Tank1
o Process Variable: External Temperature
o Start Time: T
o End Time: T-1d
o Filter Expression: ‘‘External Temperature’ > 200

Step 7 : Retrieve the Compressed Data and verify there are no values less than 200; the filter
expression removed them.

48 | P a g e
 Exercise – Production Level Report
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.

Objectives
• Use the Filter Expression option of the Sampled Data function to constrain the values
that are extracted.

Activity Description
As a quality control manager, you want to examine the level of product in Mixing
Tank1. Since this is an analogue point, it is better to perform a Sampled Data query
rather than a Compressed Data query.
You want to build a report for the level yesterday over 10-minute intervals. The
report filters out mean tank levels, which is defined as a level between 4 and 6.

Approach
Step 8 : Spend a few minutes and fill out the following table:

Root Path

Data Item

Start Time

End Time

Interval

Upper
Limit

Lower
Limit

Filter
Expression

Step 9 : You will use the template provided in sheet Production Level Report of the file <your
initials>_PI_DataLink-Exercises.xlsx.

49 | P a g e
 
Note: Are you familiar with the Excel function of CONCATENATE?



 Quick Check
Having completed this topic:

• Do you understand the use of Filtered Expressions?

If you answered NO, ask your instructor for assistance.

50 | P a g e
51 | P a g e
Building Asset Hierarchies with PI AF
OSIsoft, LLC
1600 Alvarado Street
San Leandro, CA 94577

All rights reserved. No part of this publication may be reproduced, stored in a retrieval
system, or transmitted, in any form or by any means, mechanical, photocopying,
recording, or otherwise, without the prior written permission of OSIsoft, LLC.

OSIsoft, the OSIsoft logo and logotype, Managed PI, OSIsoft Advanced Services,
OSIsoft Cloud Services, OSIsoft Connected Services, OSIsoft EDS, PI ACE, PI
Advanced Computing Engine, PI AF SDK, PI API, PI Asset Framework, PI Audit Viewer,
PI Builder, PI Cloud Connect, PI Connectors, PI Data Archive, PI DataLink, PI DataLink
Server, PI Developers Club, PI Integrator for Business Analytics, PI Interfaces, PI JDBC
Driver, PI Manual Logger, PI Notifications, PI ODBC Driver, PI OLEDB Enterprise, PI
OLEDB Provider, PI OPC DA Server, PI OPC HDA Server, PI ProcessBook, PI SDK, PI
Server, PI Square, PI System, PI System Access, PI Vision, PI Visualization Suite, PI
Web API, PI WebParts, PI Web Services, RLINK and RtReports are all trademarks of
OSIsoft, LLC.

All other trademarks or trade names used herein are the property of their respective
owners.

U.S. GOVERNMENT RIGHTS

Use, duplication or disclosure by the US Government is subject to restrictions set forth

in the OSIsoft, LLC license agreement and/or as provided in DFARS 227.7202, DFARS
252.227-7013, FAR 12-212, FAR 52.227-19, or their successors, as applicable.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form
or by any means, mechanical, photocopying, recording or otherwise, without the written permission of
OSIsoft, LLC.

2
Table of Contents
Lesson 1 - Introduction to Asset Framework (AF) ........................................................................................ 4
What does AF do for me? ......................................................................................................................... 4
AF Server Installation and Software Requirements .................................................................................. 6
Lesson 2 - PI System Explorer Basics ............................................................................................................. 8
Navigate in PI System Explorer (PSE) ........................................................................................................ 8
Connect to and Search a PI System......................................................................................................... 10
Connect to, Create and Share PI AF Databases ...................................................................................... 13
Lesson 3 – Introduction to AF Modeling ..................................................................................................... 16
Modeling Approaches in PI AF: Top-down Versus Bottom-up .............................................................. 16
Starting to Build an AF Structure ............................................................................................................ 16
Styles of Approach for Designing Assets ................................................................................................. 16
About AF Elements.................................................................................................................................. 19
About AF Attributes ................................................................................................................................ 19
Lesson 4 – Attribute Data References......................................................................................................... 24
Attribute Data Reference Types ............................................................................................................. 24
Use Alternative Value Retrieval Methods with PI Point Data Reference ............................................... 25
Lesson 5 – Create Templates in AF ............................................................................................................. 29
Introduction to and Advantages of AF Templates .................................................................................. 29
Use Substitution Parameters with Attribute Templates......................................................................... 30
Build Derived Templates in AF ................................................................................................................ 34
Lesson 6 – Build Tags in AF ......................................................................................................................... 36
Use Advanced Substitution Parameters with Attribute Templates ........................................................ 36
Lesson 7 – Organize Elements and Attributes ............................................................................................ 37
Move and Reference Elements in AF ...................................................................................................... 37
Lesson 8 - AF Security ................................................................................................................................. 39
AF Identities and Mappings .................................................................................................................... 39
AF Access Rights ...................................................................................................................................... 41
AF Server Security ................................................................................................................................... 43

3
Lesson 1 - Introduction to Asset Framework (AF)
What does 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.

4
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).

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

6
7
Lesson 2 - PI System Explorer Basics

Navigate in PI System Explorer (PSE)

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.

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.

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

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

Connect to and Search a PI System

Connecting to an 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.

10
To connect to a different available AF server, simply select it from the drop-down AF
Server menu and click on the Connect button.
Connecting to a Data Archive
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.

11
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.
PI Points in your Data Archive have a set of properties that define them (these
properties are called attributes of the tag). Below are some of the parameters you
can use to filter searches for PI Points in PI System Explorer.

Searching for PI Points in PSE: Basic PI Point Properties

PI Points in your Data Archive have a set of properties that define them (these
properties are called attributes of the tag). Below are some of the parameters you
can use to filter searches for PI Points in PI System Explorer.

12
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

Connect to, Create and Share PI 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.

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

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.

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

15
Lesson 3 – Introduction to AF Modeling

Modeling Approaches in PI AF: Top-down Versus Bottom-up

Starting to Build an AF Structure

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

Styles of Approach for Designing Assets

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.

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.

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

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.

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.
17
 • Add calculations/analytics.
• Test the model using consumers (sample reports, displays, etc.).

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

18
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
( ).
Create Elements and Attributes in AF

About AF 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 ( ; ? ` ‘ “ \ | {} [] ).

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.

About AF Attributes

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

19
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: If your AF Server version is before
2018, the functionality is identical to Display Digits = -5 (default) in the table below.

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

Units of Measure 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.

20
 • 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.

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.

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

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, (Data References will be
discussed in Lesson 4). Attribute traits are child attributes, which can be created by
right-clicking on an attribute and selecting New Child Attribute. Define the Attribute Trait
by using the Properties drop-down when the child attribute is selected.

Limit

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

Forecasts contain predicted values, which allow to compare actual value with the parent
attribute. It typically comes from a future PI point.

22
Location

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

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

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

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.

About Saving Modifications

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

23
Lesson 4 – Attribute Data References

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

24
Data Reference Type Examples

Use Alternative Value Retrieval Methods with PI Point Data Reference

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

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

26
 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)

By Time Range – Retrieving the result of an aggregation

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

27
 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)

28
Lesson 5 – Create Templates in AF

Introduction to and Advantages of AF Templates

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.

29
Use Substitution Parameters with Attribute Templates
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.

Notice the default configuration for a PI Point Data Reference attribute template:
\\%Server%\%Element%.%Attribute%.

Substitution parameters can also be applied in Table Lookup and String Builder Data
References.
30
Defining Substitution Parameters

The substitution parameters are listed in the following table. The ones in bold are the
commonly used “Name” substitution parameters.

Parameter Will be replaced by this object’s name:

The name of the owning element of the element in which

%..\Element% the attribute resides. To retrieve further ancestors, use the
‘..\’ notations, such as %..\..\Element%.

Name of the root attribute or attribute template that holds

%|Attribute%
this data reference.

The name of the owning attribute in which the attribute

%..|Attribute% resides. To retrieve further ancestors, use the ‘..|’
notations, such as %..|..|Attribute%.

The value of the attribute referenced. To retrieve further

%@Attribute% ancestors, use the ‘..|’ notations, such as
%@..|..|Attribute%.

The name of the root AF Element in which the attribute

%\Element%
resides.

The matching System Environment Variable’s value. For

%<Environment example %COMPUTERNAME% is replaced with the
Variable>% name of the computer on which the Data Reference is
executing.

The name of the analysis if it can be obtained from the

%Analysis%
context.

%Attribute% The name of the attribute that holds this data reference.

%AttributeId% The attribute ID that holds this data reference.

The name of the AF Database in which the attribute

%Database%
resides.

The description of the attribute that holds this data

%Description% reference.

31
%Element% The name of the AF Element in which the attribute resides.

The description of the element in which the attribute

%ElementDescription%
resides.

%ElementId% The element ID that holds this data reference.

The local end time if it can be obtained from the time

%EndTime%
context.

The name of the model if it can be obtained from the

%Model%
context.

The name of the default Data Archive of the AF Database

%Server% in which the attribute resides.

The local start time if it can be obtained from the time

%StartTime%
context.

%System% The name of the PI System in which the attribute resides.

%Time% The local time if it can be obtained from the time context.

The coordinated universal (UTC) end time if it can be

%UtcEndTime%
obtained from the time context.

The coordinated universal (UTC) start time if it can be

%UtcStartTime%
obtained from the time context.

The coordinated universal (UTC) time if it can be obtained

%UtcTime%
from the time context.

.\ The current reference

The default object of the parent collection. For example

.\Elements[.] |Temperature returns the temperature
[.]
attribute from the primary element of the current
reference’s Elements collection.

The search string in text (e.g. Tank*) matches the given

filter. Supported filters are: @Name, @Index, @Template,
[@filter=text]
@Category, @ReferenceType, @Description, @Type,
@UOM.

32
 [@Index=#] Returns the result at location # from the collection result.

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

Reading Substitution Parameters

In order to better understand configuration strings in substitution parameters, refer to

the following table:

Symbol Definition Examples

Consider the expression as a
%[…]%
substitution parameter.
. Navigate a level down.
.. Navigate a level up.
\ References an element.
| References an attribute.
References the value of the
@ %@..\..\|<Attribute>%
object instead of its name.
%Element%,
%Attribute%
%@.\<ChildElement>|<Attribute>%
%..\..\Element%, %..|Attribute%
%..\Element%
%..|Attribute%, %@|<Attribute>%

When referring attribute values there are differences between substitution parameters used in
PI Point Data References and the syntax in the String Builder. %@..\|SiteID% works in the PI
point reference but has to be ‘..\|SiteID’ instead for the String Builder.
33
Build Derived Templates in AF
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.

34
To view the template inheritance tree from the PSE Library, simply organized the
templates by inheritance.

35
Lesson 6 – Build Tags in AF

Use Advanced Substitution Parameters with Attribute Templates

Reading Substitution Parameters
In order to better understand configuration strings in substitution parameters, refer to
the following table:

Symbol Definition Examples

Consider the expression as a
%[…]%
substitution parameter.
. Navigate a level down.
.. Navigate a level up.
\ References an element.
| References an attribute.
References the value of the
@ %@..\..\|<Attribute>%
object instead of its name.
%Element%,
%Attribute%
%@.\<ChildElement>|<Attribute>%
%..\..\Element%, %..|Attribute%
%..\Element%
%..|Attribute%, %@|<Attribute>%

When referring attribute values there are differences between substitution parameters used in
PI Point Data References and the syntax in the String Builder. %@..\|SiteID% works in the PI
point reference but has to be ‘..\|SiteID’ instead for the String Builder.

36
Lesson 7 – Organize Elements and Attributes

Move and Reference Elements in AF

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 while pressing

Action
the...

Copies the original element under another

Ctrl Key parent 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
No Key this case, the element icon has a "link"
designation ( ), like in the case of a file
shortcut

Tip: When moving an object, be deliberate with the shift key, drag and drop manipulation. It is
safer to right click the element, copy it to the new location, and then delete the original.

Element Reference Types

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

37
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

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.

38
Lesson 8 - AF Security

AF Identities and Mappings

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 users and groups.

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

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

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

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

41
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.
42
AF Server Security
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.

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

44
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 a 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.

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

46
Setting the security for a 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.

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.

47
Permission 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
permissions
Update child permissions for
modified identities
Replace child permissions for
all
identities
Prevents access permissions that have been set for the
current object or collection from being replicated to child
collections and objects in the AF hierarchy.
Default for AF server 2.5 and earlier
For each selected item on the Items to Configure list in the
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.
For each selected item on the Items to Configure list in the
Security Configuration window, replaces all child permissions
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!

48
 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 for individual UOMs or UOM
classes. Permissions can only be set for the entire UOM database.
To open UOM Security Configuration window:
1. In the Navigator pane, select Unit of Measure.
2. 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 references
types always have read permission regardless of their security settings
• Deny settings override any granted allow permissions

49
Event Frames and Notifications

1
© 2021 OSIsoft, LLC. All rights reserved
OSIsoft, LLC
1600 Alvarado Street
San Leandro, CA 94577

All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or
transmitted, in any form or by any means, mechanical, photocopying, recording, or otherwise, without
the prior written permission of OSIsoft, LLC.

OSIsoft, the OSIsoft logo and logotype, Managed PI, OSIsoft Advanced Services, OSIsoft Cloud Services,
OSIsoft Connected Services, OSIsoft EDS, PI ACE, PI Advanced Computing Engine, PI AF SDK, PI API, PI
Asset Framework, PI Audit Viewer, PI Builder, PI Cloud Connect, PI Connectors, PI Data Archive, PI
DataLink, PI DataLink Server, PI Developers Club, PI Integrator for Business Analytics, PI Interfaces, PI
JDBC Driver, PI Manual Logger, PI Notifications, PI ODBC Driver, PI OLEDB Enterprise, PI OLEDB Provider,
PI OPC DA Server, PI OPC HDA Server, PI ProcessBook, PI SDK, PI Server, PI Square, PI System, PI System
Access, PI Vision, PI Visualization Suite, PI Web API, PI WebParts, PI Web Services, RLINK and RtReports
are all trademarks of OSIsoft, LLC.

All other trademarks or trade names used herein are the property of their respective owners.

U.S. GOVERNMENT RIGHTS

Use, duplication or disclosure by the US Government is subject to restrictions set forth in the OSIsoft,
LLC license agreement and/or as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12-212, FAR
52.227-19, or their successors, as applicable.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form
or by any means, mechanical, photocopying, recording or otherwise, without the written permission of
OSIsoft, LLC.

2
© 2021 OSIsoft, LLC. All rights reserved
Contents
- About this course .............................................................................................................................. 5
By the end of this course, you’ll… ......................................................................................................... 5
Audience ............................................................................................................................................... 5
This Course Includes... .......................................................................................................................... 5
Prerequisites ......................................................................................................................................... 5
Further information .............................................................................................................................. 6
- Lesson 1: Introduction ...................................................................................................................... 7
Learning outcomes................................................................................................................................ 7
Introduction .......................................................................................................................................... 7
Definitions ............................................................................................................................................. 9
Use Cases - Example............................................................................................................................ 10
Learn More.......................................................................................................................................... 11
- Lesson 2: Event Frames - Introduction ........................................................................................... 12
Learning outcomes.............................................................................................................................. 12
Introduction ........................................................................................................................................ 12
Generating Event Frames.................................................................................................................... 13
Retrieving Event Frames ..................................................................................................................... 14
PI Vision: Finding and Acknowledging Event Frames.......................................................................... 15
PI Vision: Manual entry of reason codes ............................................................................................ 17
PI System Explorer: Finding and Acknowledging Event Frames ......................................................... 19
Features of Event Frame Templates ................................................................................................... 20
Learn More.......................................................................................................................................... 21
- Lesson 3: Event Frames - Tasks ....................................................................................................... 22
Learning outcomes.............................................................................................................................. 22
Directed Activity - Manual Event Frame Generation .......................................................................... 22
Directed Activity - Finalize the event frame template ........................................................................ 27
Directed Activity - Backfilling Event Frames ....................................................................................... 29
Creating Event Frames with EFGen ..................................................................................................... 31
Migrating from PI Batch to Event Frames ........................................................................................... 33
Filter by Event Frames with the PI Integrator for Business Analytics ................................................. 34
- Lesson 4: Event Frame Analysis ...................................................................................................... 37
Learning outcomes.............................................................................................................................. 37

3
© 2021 OSIsoft, LLC. All rights reserved
 Directed Activity - Creating an EF Generation Analysis ...................................................................... 37
- Directed Activity - Previewing analysis results and starting the analysis ................................... 42
Directed Activity - Backfilling Event Frame analysis ........................................................................... 43
- Directed Activity - Converting an Analysis into a Template ........................................................ 45
Event Frame Reports in Excel with PI Datalink ................................................................................... 46
Directed Activity - Creating Event Frame Reports with PI Datalink .................................................... 48
- Lesson 5: Notifications .................................................................................................................... 51
Learning outcomes.............................................................................................................................. 51
Introduction ........................................................................................................................................ 51
Delivering Notifications – options and settings .................................................................................. 53
Trigger criteria for Notifications.......................................................................................................... 55
Dynamic endpoints ............................................................................................................................. 58
Notification groups and escalation teams .......................................................................................... 58
Installing the PI Notifications services ................................................................................................ 60
Account permissions for the PI Notification service ........................................................................... 62
Create a notification based on an Event Frame.................................................................................. 64
Troubleshooting the PI Notifications Service...................................................................................... 69
1. Configure logging for the PI Notifications Service ...................................................................... 69
2. Access Performance Counters .................................................................................................... 70
- Next Steps ................................................................................................................................... 71

4
© 2021 OSIsoft, LLC. All rights reserved
- About this course
Event Frames and Notifications are a powerful combination of features in Asset
Framework that help you capture, store, find, compare and analyze important
system events and their related data. With notifications, you can send alerts to
users in real time about conditions in the system that need specific attention.
Corresponding actions can then be taken to be pro-active or to resolve the problem
of the current situation.
We hope you enjoy the module and please don’t hesitate to get in touch with any
comments or feedback.

By the end of this course, you’ll…

• Describe the uses and functions of Event Frames and the PI Notifications
service.
• Understand the features and advantages of using Event Frame templates.
• Create Event Frames in multiple ways: via asset analytics, manually, and with
the Event Frame Generator.
• Interact with different PI System products that utilize Event Frames.
• Install and troubleshoot the PI Notifications service, and create a notification
based on an Event Frame.

Audience
This course is for experienced users of PI AF, but is open to anyone who wishes to
learn more about Event Frames and Notifications.
Level: Intermediate
Study time: 4 hours

This Course Includes...

• Videos, discussion opportunities and quizzes to help you learn the material
• A sharable certificate of completion

Prerequisites

• Familiarity with the content covered in the courses “PI System Basics” and
“Building Asset Hierarchies with PI AF” is advised.

5
© 2021 OSIsoft, LLC. All rights reserved
• You can access our YouTube content.
• PDF Reader or equivalent is required to access the workbook and presentation
provided.

Further information

1. Once you register for a course, you will have access to the course materials 24/7
on this website.
2. This is a self-paced course. Any questions or assistance needed about the
material can be asked in this course's space in the OSIsoft PI Square community
3. When you complete the examination at the end of the course, you will receive
a certificate of completion which can be shared and directly posted on LinkedIn.
4. For more information about our Online Courses please visit our FAQ page

You can audit the full video lecture content right now on the OSIsoft Learning
YouTube Channel

6
© 2021 OSIsoft, LLC. All rights reserved
- Lesson 1: Introduction
Learning outcomes
After completing this lesson, you will:
• Understand the basic components of the PI System.
• Be more familiar with the definitions of the terms Event Frames and
Notifications.
• Have reviewed Event Frame and Notification examples.

Introduction

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 Data Archive. Asset
Framework (AF) organizes and enhances the data and users then consume the data
using 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:

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

Data Archive
The 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 Data Archive was referred to as the "PI Server”.

7
© 2021 OSIsoft, LLC. All rights reserved
Asset Framework
Asset Framework (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 Data Archives
and non-PI sources such as external relational databases.
Asset Analytics
A feature of Asset Framework (AF) used to create and manage analyses. Analyses
read values of 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 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.

This course will examine Event Frames and Notifications.

8
© 2021 OSIsoft, LLC. All rights reserved
Definitions

Events are important process or business time periods that represent something
happening that affects operations. Capturing important events in your process and
collecting relevant data around those events can help analyze why they occurred.
In the PI System, events are known as Event Frames. With Event Frames, you can
capture, store, find, compare, and analyze the important events and their related
data. The power of Event Frames is that 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 enable users to easily search the PI System for the specific
events they are trying to analyze or report on.

Starting with PI Server 2016 R2, you can use the Asset Framework to configure
notifications to alert you for conditions that signal Event Frames of interest.
Notification messages may be customized to include information that is specifically
relevant to the event, and may be sent via email to individuals, groups, or to a web
service. Therefore, Notifications is the feature in the Asset Framework (AF) that you
use to create and manage notification rules. Notification rules are the mechanism
by which users are alerted for response in real time, for conditions that signal
events of interest. Furthermore, escalations are also configurable in the
notification system.

Notification rule triggers are based on event frames; the event frames may come
from different sources like analyses, the Event Frame Generator (EFGen) interface
or custom AF SDK applications. Relevant information for events is stored in event
9
© 2021 OSIsoft, LLC. All rights reserved
frames and compatible tools can retrieve such information. Information contained
in elements, event frame templates, and other places may also be added to the
notification content. Furthermore, event frame annotations contain historical
notification information and may also include attachments; all annotations may be
viewed using PI Vision or other client tools that support viewing annotations.

Use Cases - Example

You can monitor the following events to identify possible causes or potential points
of failure.

• Asset downtime
• Environmental monitoring excursions
• Process excursions
• Product tracking batches
• Equipment startups and shutdowns
• Operator shifts

Example in a wind power generation company

Take the example of a wind power generation company that has different types of
windmills across different locations and uses PI AF to organize their data. Their
asset framework structure is based off a base element template of type "windmill",
and has various child templates based off OEM, model, and megawatt ratings. The
wind operator may want to win favorable warranty contracts by showing that the
blades are operating safely. Alternatively, the operator may need to monitor
parameters such as oil-bearing pressure, maximum voltage, power-factor, or
performance of electronic and mechanical brakes in the minutes before process
trips occur. In all these cases, the PI System can be used to generate event frames
that capture relevant data and context needed to analyze the events.

Some event frames may need notifications to alert personnel or trigger other
systems; some examples include:
• 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
10
© 2021 OSIsoft, LLC. All rights reserved
Notification messages can include links and screenshots to pre-configured PI Vision
displays, and thereby provide visual representation of the event that triggered the
notification. See PI Vision or PI DataLink product documentation for details on
notifications feature support.

Learn More
• Event frames in PI AF (Live Library Article)
• [VIDEO] What are PI Event Frames?

11
© 2021 OSIsoft, LLC. All rights reserved
- Lesson 2: Event Frames - Introduction
Learning outcomes
After completing this lesson, you will:
• Be more familiar with Event Frames, especially in the processes of
generating, retrieving, and acknowledging them.
• Have understood the features and advantages of using Event Frame
templates.
• Have a clear idea of which PI System products support interacting with Event
Frames.

Introduction

An Event Frame is defined by three characteristics:

1. Name: each Event Frame name must be unique and often includes a
timestamp
2. Start time and End time: defines the event’s time range
3. Context: one or more event attributes and referenced AF elements

There are two categories of trackable events that would fit an Event Frame profile:

• Good events: Events that you want to track as a normal part of a business
such as product tracking, shifts, and so on.
• Bad events: Events that are unexpected and need to be analyzed and
perhaps fixed quickly if they ever occur such as unexpected shutdowns or
excursions. These are events that you want to track and report in aggregate,
over time.

You can use data to identify some baseline “average” event and then look for those
that are better than average (i.e., let’s figure out what we did well and try to repeat)
or worse than average (i.e., let’s see what went wrong and try to avoid it). So, in a
sense, these are events that aren't clearly good or bad but they are both captured
with the same type of event frames and analysis logic.

Some of the features and advantages of Event Frames are:

• Flexibility

12
© 2021 OSIsoft, LLC. All rights reserved
 o Reference multiple elements within the same event.
o Support multiple overlapping events on an AF element.
o Capture any event; a "batch" is just one type of capturable event.
• Powerful search
o Search by time range, type of event or Event Frame attribute.
• Scalability
o Event Frames are extremely scalable (whereas search performance
degrades with a large number of batches.). The upper limit for the
number of Event Frames an AF server can have before experiencing
significant performance issues is about a hundred million. More
information in this article.

This list of PI System products support interacting with Event Frames:

o Asset Analytics
o Notifications
o Dev Tech (AF SDK, PI Web API, JDBC Driver, etc.)
o EFGen
o PI Vision
o PI DataLink
o Data Archive (migrate batch data to Event Frames)

Generating Event Frames

Asking questions such as these can help identify events or conditions that must be
tracked. These will then be utilized in doing event analysis:
1. What are all the times that event X occurred on this type of asset?
2. Can I associate data from different points for a time-range, or for a single
point in time?
3. What is the associated data for a particular time period when a problem
occurred or may occur in the future?
4. What are the critical process events that someone needs to be notified on?
There are different ways to generate Event Frames:
- PI Interfaces for Batch Execution Systems:
o PI Batch Framework 3.x and later versions can create Event Frames within
a PI AF database or PI Batch objects within a PI Batch database. For more

13
© 2021 OSIsoft, LLC. All rights reserved
 information on creating Event Frames and using PI interfaces to populate
the PI AF database with events-based data, see:
▪ PI interfaces for batch and manufacturing execution systems
▪ PI Event Frames Interface Manager
- The Event Frame Generator:
o PI EFGen uses both PI SDK and AF SDK to create a hierarchy of events or
to convert a PI BaGen structure to an Event Frame generator structure.
Use PI System Explorer or PI Builder to create the Event Frame templates,
associated attributes and PI point references.
o For instructions on how to create Event Frames with PI EFGen, watch this
video.
- AF SDK:
o You can create your own custom applications using AF SDK and PI ACE to
create and monitor events.
- Asset Analytics:
o you can generate Event Frames directly from AF. Once Event Frames are
generated in AF, client tools such as PI DataLink and PI Vision could be
used in visualizing and analyzing them.
o For an example of creating Event Frames using asset analytics, see Create
Event Frames automatically to track inefficiency.
Although you can create Event Frames with several different OSIsoft products,
OSIsoft strongly recommends that you use asset analytics in most cases.
The data needed to trigger Event Frames and populate many of their attributes is
in PI Points. So, as long as you have history in the Data Archive, you can backfill your
EFs. That means you don’t have to set them up and wait for new events. You can
validate your logic against known occurrences and/or discover events from the
past that provide value now.

Retrieving 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 visualize and analyze important events. Here
is the list of the client applications that could be used in analyzing the generated
Event Frames:

14
© 2021 OSIsoft, LLC. All rights reserved
- PI Vision: Event Frames related to assets on a display are discovered by PI Vision.
The time range and assets on the display determine what events are shown in
the events list, but users may define their own custom searches as well. You can
compare similar events to each other using Gantt charts and trend overlays.
- PI System Explorer: 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.
- PI DataLink: Beginning with PI DataLink v2014, you can use PI DataLink 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

PI Vision: Finding and Acknowledging Event Frames

To view events, open the Events tab on the left side. Here you will find events
related to your process, the color to the left of each event indicates its severity. By
default, the time range of the display and the context of the symbols in the display
determine which events are shown in the Events list. To discover additional events,
modify the time range or choose Edit Search Criteria. When editing the search
criteria, there are a few filtering options to find the Event Frames you are looking
for, as shown.

15
© 2021 OSIsoft, LLC. All rights reserved
Select an event to find its Data Items (event
attributes) and its start and end time.

By right-clicking on an event, you can choose Event Details. This will create a trend
and table with information about the event, click an item to add it to the trend. On
the right, will also see the Actions and Comments associated with an event. If you
have access to do so, you can add a new comment to the Event Frame and
‘Acknowledge’ it. The access is controlled in PI System Explorer with the Annotate
permission.
Note: acknowledgement must be enabled on the event frame template. Refer to
this Live Library article on how to ”Set permissions to allow users to acknowledge
and annotate events”.

16
© 2021 OSIsoft, LLC. All rights reserved
The PI Notifications Service writes an annotation to Event Frames with information
about the number of subscribers the notification was sent to. From the
Subscriptions pane in PI System Explorer, you can configure the subscribers to be
alerted when a notification rule is triggered. A subscriber is an individual entity or
group of entities that can receive notification messages by subscribing to
notification rules.
More information on Subscriptions in notification rules can be found in the Live
Library.

PI Vision: Manual entry of reason codes

On the Event details page, the Reason pane lists available reasons and shows the
reason currently set for an event. You can clear the current reason or select and
apply a new reason. The reason attribute can be configured as an enumeration set
for an Event Frame template, which can be hierarchical in PI AF version 2017 R2
and later. For users to be able to select and edit reason codes on the Event details
page, the user must be mapped to an AF identity that has Write Data permission
on the Event Frame template.
1. Create an Enumeration Set containing the possible reason codes.
• In PI System Explorer, navigate to the Library tab. Right-click "Enumeration
Sets" and select "New Enumeration Set".
• Create a new row for each possible reason. Pipe symbols can be used to create
a hierarchical structure.

17
© 2021 OSIsoft, LLC. All rights reserved
 2. Assign the enumeration set to the Event Frame reason attribute.
• Under "Event Frame Templates", select the target Event Frame template.
• On the General tab of the Event Frame, select the Reason hyperlink.

• Under Value Type, browse to the Enumeration Set containing the Reason Codes.

• If selected successfully, the Attribute tab of the Event Frame will now contain
an attribute with a name and property of "Reason".

18
© 2021 OSIsoft, LLC. All rights reserved
 3. Set the Reason Code from the Event Table Symbol on a PI Vision display.
• Use the Event Search pane to find the desired Event Frame and then select
Create Events Table.
• Right-click on the Event Table symbol, select "Configure Table", and then check
the Reason box to add the column to the symbol.

• Click the pencil graphic under the Reason column

in the Events Table symbol, and then select the
appropriate Reason Code.

PI System
Explorer:
Finding and
Acknowledging Event Frames
In PI AF 2016 and later, you can require that an Event Frame be acknowledged. The
acknowledgment feature is used by notifications and PI AF client applications, such
as PI Vision.
- How to acknowledge an Event Frame
You acknowledge Event Frames in the Event Frames browser or in the General tab
of a selected Event Frame in the Event Frames viewer.
1. In the navigator, click Event Frames.
2. In the Event Frames browser, click an Event Frame Search collection. The
contents of the collection are displayed in the viewer.

19
© 2021 OSIsoft, LLC. All rights reserved
3. Optional. To group Event Frames by their acknowledged status, click the
column icon.
4. Choose from the following actions.
o Right-click an Event Frame in the viewer and click Acknowledge on the
context menu.
o Double-click an Event Frame in the viewer and, on the General tab, click
the Acknowledge link.
5. Click Yes in response to the “Are you sure you want to acknowledge
Event_Frame_Name?” prompt.
The following changes occur:
o In the Event Frame Search collection that is displayed in the viewer, the
Acknowledged ( ) column changes to OK status.
o On the General tab, the Acknowledged field is displayed with a time and
date stamp. The user ID of the user who made the acknowledgment is
displayed in the By field.

- How to find and read Event Frame annotations

You can search for Event Frames that have been annotated. You review annotation
status in the viewer for an Event Frame Searches collection, where an “Is
Annotated” column is displayed ( ).
To group Event Frames by their annotation status, you click the column icon.
Look in this article for information on Adding annotations to Event Frames.

Features of Event Frame Templates

Using Event Frame templates, you can define and standardize the related data (i.e.
Event Frame attributes) associated with different types of events. Event Frame
attributes provide additional context around the event that are useful for searches
and reports. For example, downtime events often have a reason code that users
want to search for or filter on during analysis of their downtime events.
You can also configure Event Frame attributes to reference process data in the
context of the event. For example, a temperature excursion event is likely to have
an attribute for the maximum temperature. You can configure Event Frames to
20
© 2021 OSIsoft, LLC. All rights reserved
record those values for you. Additionally, for each event type, you can configure an
index for the most-searched attributes: this enables faster and easier searches on
the PI AF server when you track several event types or millions of events.
When you create Event Frames dynamically with Event Frame templates, you
typically need to reference elements, attributes, templates, or other related
objects based on those Event Frame templates. Because each individual Event
Frame occurs in a slightly different context, you can use substitution parameters to
reference other PI AF objects dynamically, rather than static, absolute references.
For example, you can use a downtime Event Frame template for any number of
assets, such as a pump, motor, boiler, compressor, and so on.
Following on from our “Example of Event Frames in a wind power generation
company”, since all types of turbines share many identical attributes, you can
create just one Event Frame template and use it to monitor similar events across
the different assets. For example, you may be interested in the RPM attribute to
capture a speed-based event. Using the special notation .\Elements[.]|RPM in the
template, enables you to use the template on any windmill, and access the
attribute of the particular referenced element.
For information on how to set up Event Frame templates, watch this video.

Learn More
- For more information
o on viewing and acknowledging Event Frames using PI Vision, see the
PI Vision topic View event details and annotate events.
o on Event Frame templates, take a look at the articles on Live Library
- You may choose Batch or Event Frames depending on your process and business
needs. More information can be found in the Live Library.

21
© 2021 OSIsoft, LLC. All rights reserved
- Lesson 3: Event Frames - Tasks
Learning outcomes
After completing this lesson, you will:
• Have reviewed three different ways to create Event Frames: manually, via
Asset Analytics and with the Event Frame Generator.
• Have been introduced to the process of migrating Event Frames that were
made with PI PIBaGen (PI Batch Generator).
• Have explored exporting Event Frames with the PI Integrator for Business
Analytics.
• Be more familiar with exploring Event Frames in PI DataLink.

Directed Activity - Manual Event Frame Generation

Although you typically use event-frame-generation analyses or PI Event Frames
Generator (PI EFGen) to create event frames, you can create an event frame
manually. While not recommended as a practical or scalable way to generate
events in a production environment, manual creation is quite useful as a learning
exercise to reinforce understanding of event frame structure and configuration.
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.
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.

22
© 2021 OSIsoft, LLC. All rights reserved
 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

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.

23
© 2021 OSIsoft, LLC. All rights reserved
 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.

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

24
© 2021 OSIsoft, LLC. All rights reserved
 Time. Click on OK.

Note that the dropdown has all the reference element’s attributes
available in the proper reference syntax. The value returned will be
the Press Status at the start of the Event Frame.
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.

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. your changes
2. Select the event frame you created, and from the right mouse
button menu, select Convert > Convert To Template.

25
© 2021 OSIsoft, LLC. All rights reserved
 3. For the Reason Code, keep
.\Elements[.]|Press Status;TimeRangeMethod=StartTime
Click on OK.

4. your changes

26
© 2021 OSIsoft, LLC. All rights reserved
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%

%@Attribute% The value of the event frame’s

attribute template, represented by
the path.

More information on Naming Patterns is available in the Live Library.

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

27
© 2021 OSIsoft, LLC. All rights reserved
 Answer: Set the Naming Pattern as Downtime %ELEMENT%
(%..\ELEMENT%) %STARTTIME:yyyy-MM-dd HH:mm:ss% where
HH is 24-hour format.

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 option

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). The attribute value will be set by the analysis, which
we will create in the next step.
7. Producing one tire takes approximately 5 minutes. 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), set Data Reference to Formula. To get the amount of
production loss, divide the duration in seconds by 300:

8. Check in the changes.

28
© 2021 OSIsoft, LLC. All rights reserved
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:

29
© 2021 OSIsoft, LLC. All rights reserved
 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).
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 Backfill/Recalculate 12 selected analyses link.

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

30
© 2021 OSIsoft, LLC. All rights reserved
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.

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.

Creating Event Frames with EFGen

The PI Event Frames Generator (PI EFGen) generates events (event frames) in the
PI AF database based on values from trigger points in the PI Server. Using event
frame templates in PI AF, PI EFGen populates event frame attributes from point
data, handles complex hierarchical events like batches, and migrates existing PI
Batch Generator (PIBaGen) configurations to event frames so you can continue
using your current batch structure.

31
© 2021 OSIsoft, LLC. All rights reserved
The following are notable features of PI Event Frames Generator:
• Generate events - Easily configure event generation and automatically generate
your events from the trigger points that are already collecting data in the PI
Server. The screen shot below shows an example of downtime events being
created using PI EFGen:

• Handle multiple event types - Generate all your different event types, such as
downtime, excursions, batches, and other events, on the same asset with no
restrictions on overlapping events. Please note that we can have multiple EF
generation analyses using the same or different templates running and
generating EF in parallel.
• Standardize using event frame templates and populate event attributes -
Different event types have different attributes and information that are
important for analysis. Standardize your events using event frame templates
and use PIEFGen to automatically populate event’s attributes with data from PI
points.
• Generate complex event hierarchies like batches - This is the biggest advantage
of the EF Gen Interface. Create and relate complex events such as batch
processes, which have levels of events like procedures, unit procedures,
operations, and phases, while maintaining the parent/child relationships.
• Recover history and backfill events - if PIEFGen loses its connection to the PI
Server, your events are recovered upon reconnection, using built in history
recovery. You never lose events when you have the underlying PI System data.
Unlike the legacy PI Batch Generator (PIBaGen), you can recover events without
manually deleting records before recovery. PIEFGen enables you to define your
history recovery time window, then it recovers the events from previous time
periods automatically.

32
© 2021 OSIsoft, LLC. All rights reserved
• High availability and failover - if you have a primary and secondary PI Server
(HA PI Server Collective), PIEFGen can be configured to retrieve the trigger point
information from the secondary PI Server automatically upon failure. To ensure
continuous creation of events, you can run multiple instances of PIEFGen using
interface-level failover. Finally, if you have a high-availability PI AF server, your
events are stored redundantly, so the data is always available.
• Flexible deployment - Unlike PIBaGen, PIEFGen can be run anywhere in your PI
System architecture. OSIsoft recommends that you install it on your PI AF Server
or on a PI interface node.
• Easy migration from PI Batch Generator - Using the PIBaGen Converter tool,
existing PIBaGen configurations that write to PI Batch can easily be migrated to
PIEFGen to create the same events using event frames. After migrating, you can
enhance your configuration to take advantage of features like event frame
templates and attributes.
• Configuration tool - Event Frames Interface Manager enables you to configure
all event frame interfaces using a graphical user interface, rather than manually
editing text files.

For more information on “Preparing batch data sources and consumers for
migration” look at this article in the Live Library.

Migrating from PI Batch to Event Frames

Starting with PI Server 2015, you can migrate your PI Batch Database and PI Batch
Subsystem data to event frames. Because you will need different client applications
to manage batch data in event frames than you have been using with the Batch
Database, do not migrate to event frames until the solutions you need for event
frames are all in place. Also, once you start the migration, the Batch Database
becomes read only, and you will not be able to revert to it.
OSIsoft does not recommend that you run the PI Batch Database and use event
frames in parallel for the same batch data. OSIsoft envisions that you will migrate
all batch data at one time from the PI Batch Database. An exception is if you decide
to create event frames to support non-batch data (such as for monitoring
equipment downtime) at the same time as you create batches in the PI Batch
Database.
33
© 2021 OSIsoft, LLC. All rights reserved
Note:

- OSIsoft recommends that, unless you have non-critical migration requirements

or a very simple environment, you test the migration of your batch data to
event frames and the cutover to event frame data sources and consumers.

- Allow approximately 90 minutes per million event frames for the migration,
bearing in mind that this time will vary greatly depending on network,
hardware and other factors.

For more information on “Preparing batch data sources and consumers for
migration” look at this article in the Live Library.
PI interfaces for batch and manufacturing execution systems are scan-based
interfaces that populate the PI AF database (with event frames and assets) or the
PI Batch Database and PI Module Database (with batches, modules and properties)
based on events and data read from a data source. For more information, access
this article.
Filter by Event Frames with the PI Integrator for Business Analytics
PI Integrator for Business Analytics transforms PI System data into a decision-ready
format that can be consumed by business intelligence (BI) tools, such as Microsoft
Power BI, Tableau, and others. With BI tools, you can run retrospective analyses on
large sets of your real-time PI System data.
The following procedure shows how to create, modify, and apply an event view.
When you define an asset shape, you create a collection of matches that meet the
same criteria. When you apply an event frame filter to this view, you define an
event shape that creates a collection of matches for a set of event frames. PI
Integrator for Business Analytics then joins these two collections based on a
common asset to obtain the subset of data that matches both.
For example, assume you have a number of wells where a certain piece of
equipment is run one at a time at each well, and event frames are used to record
the data collected by this equipment. Each event frame has a different start and
end time and applies to a different well. You can use the event frame row filter to
include asset view data for the well only for the period that the equipment was
running on that well.

34
© 2021 OSIsoft, LLC. All rights reserved
Procedure
1. On the My Views page, select the view that you want to modify and click Modify
View. Then click Next to open the Modify View page. Note: If you are already on
the Modify View page, skip to the next step.
2. Use the Start Time and End Time fields to adjust the time range to include the
times when the event frames of interest were recorded. Note: If the start and
end times are outside the event frame time range, no event frames will be
found.
3. Click Edit Row Filters and choose Event Frame for the type of filter. PI Integrator
for Business Analytics now searches for event frames on your PI AF database for
this view and displays a subset of the ones it finds.

4. Click the icon to open the menu. Click the right-angle bracket (>) on one of
the filtering categories to open the related panel.

35
© 2021 OSIsoft, LLC. All rights reserved
 In the filtering fields, specify parameters to narrow down the event frames to
find the ones you are looking for. For example, enter a pattern-matching string
in the Event Name field or select a template in Event Template.

5. Click Apply Filters.

6. From the event frames found, drag an event frame to the center pane. The filter
now includes rows for which this event frame is active.
7. Optionally, you can broaden the row filter search criteria to include all event
frames with the same template or category. To do this, use the drop-down list
to change the search from Event Name to Event Template or Event Categories.

36
© 2021 OSIsoft, LLC. All rights reserved
8. Click the icon next to the event condition. PI Integrator for Business Analytics
fetches matching event frames and shows them in the preview pane at the
bottom of the window.
9. To align the event frames with the correct asset, drag the asset or attribute from
the Shape Tree onto the filter criteria. This step defines the relationship
between the two data sets (the event frame data set and the asset and
attributes data set). This is similar to the clause in a relational table join that
equates an attribute in one table (or dataset) to an attribute in the other table
(dataset). Here, we are equating the asset "owning" the event frame to the asset
from your Shape Tree. PI Integrator for Business Analytics updates the display
of matching event frames in the preview.
10. When you have finished defining the filter, click Save Event Frame Row Filter.
For more information on the “PI Integrator for Business Analytics” look at this
article in the Live Library.
- Lesson 4: Event Frame Analysis

Learning outcomes
After completing this lesson, you will:
• Have gone through the process of creating an EF Generation Analysis
• Know about converting an analysis into a template
• Have understood Event Frame reports in PI Datalink

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.

37
© 2021 OSIsoft, LLC. All rights reserved
Tip: Before you create an EF generation analysis, be sure an event frame template
is available for it.

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.

38
© 2021 OSIsoft, LLC. All rights reserved
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.

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.

39
© 2021 OSIsoft, LLC. All rights reserved
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:

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:
'Press Status'="Planned Maintenance" or 'Press Status'="Press set-up"

Assign an Information severity level.

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

40
© 2021 OSIsoft, LLC. All rights reserved
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.

Note: In the example above, the start triggers are all mutually exclusive. In other
cases, however, multiple start triggers can be true at the same time. This leads to
EF hierarchy generation. More information can be found in the Live Library.
Store the duration in the corresponding event frame attribute

Since AF 2017 R2 there is an EventFrame function,

which allows to get event frame properties such as the
event frame duration in an easy way.

To store the event frame duration in the Event Duration attribute of the event
frame:
1. To enter an output expression, click on blue Add… link on top of
the triggers section and select Output Expression option from the
dropdown.

41
© 2021 OSIsoft, LLC. All rights reserved
 2. For the expression, enter EventFrame("Duration")
3. Click on the blue Map link at the right hand side, and select the
Event Duration attribute.

An alternative way is to use a Formula Data Reference attribute configured to

return the value of %Duration%. If the Value Type of the Formula Data Reference
is set to "String" the value will have the format: hh:mm:ss. More information can
be found in this article.
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.

- 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:

42
© 2021 OSIsoft, LLC. All rights reserved
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.

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? The first event will be from some time past today
midnight, because we backfilled from today midnight onwards.
43
© 2021 OSIsoft, LLC. All rights reserved
 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.

44
© 2021 OSIsoft, LLC. All rights reserved
- 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.

45
© 2021 OSIsoft, LLC. All rights reserved
Event Frame Reports in Excel with PI Datalink
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, ,…):

46
© 2021 OSIsoft, LLC. All rights reserved
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:

47
© 2021 OSIsoft, LLC. All rights reserved
Directed Activity - Creating Event Frame Reports with PI Datalink
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.
Requirements
Before completing this activity, you must have already created the appropriate
Event Frame template and EF Generation analysis.
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, I’ll will be using a template: Press DownTime
Analysis.xlsx, located in the class\exercises folder. The template contains
two sheets; I’ll 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

48
© 2021 OSIsoft, LLC. All rights reserved
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).
49
© 2021 OSIsoft, LLC. All rights reserved
Hit OK to display all event frame information in the Raw Data sheet.

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!

50
© 2021 OSIsoft, LLC. All rights reserved
- Lesson 5: Notifications
Learning outcomes
After completing this lesson, you will:
• Have a better understanding of Notifications, delivery channels and trigger
criteria.
• Know how to configure dynamic endpoints and setup escalation teams.
• Installing the PI Notifications service.
• Creating a notification based on an Event Frame.
• Troubleshooting the PI Notification service with performance counters.

Introduction
Within PI System Explorer, you can configure and manage notification rules from
the Notification Rules tab (visible after you select an element), and from the
Management plug-in.
With AF 2016 R2, notifications are triggered when new Event Frames are generated
in Asset Framework. Conditions for the trigger are defined in notification rules.

There are three components to PI Notifications:

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.

51
© 2021 OSIsoft, LLC. All rights reserved
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:

The definition includes the trigger criteria, adding subscribers to the notification
rule, and formatting the message to suit the needs of your organization. The
recipients for the notifications (“subscribers”) have the option to acknowledge
notifications. For situations that require actions, lack of acknowledgement can be
used to trigger a resend of the notification or escalation to another subscriber.
Management Plug-In (PI System Explorer)
Allows management of analyses and notification rules on the AF Server for a
particular AF database. The Management Plug-In allows for bulk management of
Notification Rules e.g., enabling or disabling many notification rules at once.

52
© 2021 OSIsoft, LLC. All rights reserved
Delivering Notifications – options and settings
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 - supports sending emails with notification alerts via an SMTP Mail Server.
• Web Service - supports providing information to a web service by calling one of
its methods.
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. In most cases, the “Allow
contacts to set sender email” should not be enabled.
This article contains information on how to configure the email delivery channel to
be able to receive email notifications. This must be done once for each PI AF server.

53
© 2021 OSIsoft, LLC. All rights reserved
Once the email delivery channel is setup, most email addresses should be provided
by Active Directory (AD). AD Groups are supported as well.
AD access is configured separately from PSE > File > Server Properties > Configure
Active Directory Access for Contacts. Please see the ‘Configure Active Directory
access for contacts’ article for more details. If the AD does not include all email
addresses needed, it will be possible to create additional emails and groups within
the Contacts section of PI System Explorer.
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.
There are many web services commercially available, and many development
environments offer templates and other tools to develop custom Web services.
Notifications can use either SOAP or REST APIs to contact web services. Check out
the following links for additional documentation on configuration:
REST, SOAP.
Example: A custom Web Service could process the received information and
generate corresponding work orders in a customer Maintenance System:

54
© 2021 OSIsoft, LLC. All rights reserved
Trigger criteria for 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 the element or element template on which Notification Rule will be
created
2. Create a new Notification Rule:
a) Define the notification trigger conditions
b) Format the Notification message
c) Add the subscribers
3. Test the Notification

55
© 2021 OSIsoft, LLC. All rights reserved
When the Trigger Criteria are defined, the 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.

Non-Repetition Interval
The time interval during which PI Notifications Service will not send similar alerts
associated with the same notification rule.

56
© 2021 OSIsoft, LLC. All rights reserved
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.

57
© 2021 OSIsoft, LLC. All rights reserved
Dynamic endpoints
In PI 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. To configure a dynamic email delivery endpoint and add
an email subscriber to your notification rule, follow this procedure.
For a conventional email delivery endpoint configuration, see Configure an email
delivery endpoint.
Configure a dynamic email delivery endpoint
1. Navigate to the element that you want to receive the notifications from and
add an attribute with your email address as a value. The value of this attribute
must be a string. You can enter multiple email addresses delimited by comma.
2. Navigate to Notification Rules tab to configure and add an email delivery
endpoint as a subscriber to your notification rule.
a. Click View/Edit subscriptions in the Subscriptions pane of the
notification rule.
b. Click Create a new dynamic endpoint under Dynamic Endpoints.
c. Select an email attribute configured in step 1.
d. Click Create.
e. Drag and drop the configured contact from the Contacts to the
Subscriptions pane.
f. Click OK.
3. Go to Contacts plug-in to edit or delete a configured delivery endpoint. It will
be found in Delivery Endpoints folder.

Notification groups and escalation teams

You can set up an escalation structure to ensure that the right people are notified
with the right information, and in the right order.
In the PI System, an escalation team is an ordered collection of delivery endpoints.
When a notification is not acknowledged for a specified period of time, notification

58
© 2021 OSIsoft, LLC. All rights reserved
messages are sent sequentially to members of the escalation team. An escalation
team can contain other groups.
Create a group
1. Right-click the Groups folder and click New Group.
2. In the Name field, enter a unique name for the group.
3. Choose from the following actions:
a. Click and, in the Select a Contact window, locate a contact with a new
search, or select another group, an escalation team, or a delivery
endpoint, and click OK. Repeat as needed.
b. In the Contacts palette, locate a contact with a new search, or select
another group, an escalation team, or a delivery endpoint, and drag it
onto the viewer. Repeat as needed.
4. Set notification contact options for the group.
a. Right-click each subscriber delivery endpoint, click Options, and enter
notification contact options in the Retry interval and Maximum Retries
fields.
b. If escalation teams are included in a group, right-click each escalation
team, click Options, and enter notification contact options in the
Escalation period and select an If not acknowledged option.

Create an escalation team

1. Right-click the Escalation Teams folder and click New Escalation Team.
2. In the Name field, enter a unique name for the escalation team.
3. In Escalation period, specify how long you want an escalation to last.
4. In If not acknowledged, specify the action to be taken if the notification is not
acknowledged after being sent to all contacts in a team:
a. To stop the escalation process, select End escalation.
b. To repeat the escalation process for a specified number of times until
the notification closes or is acknowledged, select Repeat N times.
c. To repeat the escalation process indefinitely until the notification closes
or is acknowledged, select Repeat while active.
5. Choose from the following actions:
a. Click and, in the Select a Contact window, locate a contact with a new
search, or select another group, or a delivery endpoint, and click OK.
59
© 2021 OSIsoft, LLC. All rights reserved
 b. In the Contacts palette, locate a contact with a new search, or select
another group, or a delivery endpoint, and drag it onto the viewer.
6. Configure the sequence for the escalation chain.
a. Click a subscriber and click and to position as needed.
b. To remove a subscriber, click the subscriber to be removed and click .

Look at this Learning Library article for more information on:

• editing an existing contact,
• creating a custom contact that is not already in Active Directory,
• creating a delivery endpoint, such as a stand-alone email or a web service.

Installing the PI Notifications services

Use the PI Server install kit to install PI Notifications Service. This section provides
details specifically on installing the PI Notifications Service through the install kit.
Before you start:
• Ensure that the computer on which you are installing PI Notifications Service
meets all the system requirements. See System requirements for PI
Notifications Service.
• Install the PI AF server. A connection is required to PI AF Server to complete
the installation. OSIsoft recommends adding additional PI Server individual
features after PI AF server has been fully setup.
Process:
1. Go to the directory where you downloaded the PI Server install kit and double-
click the setup file to launch the installation. The Welcome window appears.
2. Click Next. The Feature Selection window appears.

60
© 2021 OSIsoft, LLC. All rights reserved
The PI Server install kit provides a simple and easy-to-use UI that provides
selectable Server Roles to choose from for your installation. These Server Roles
automatically select the PI components necessary to install a typical deployment
of the PI Server feature you select. Alternatively, you can click the Individual
Features tab to manually select and customize your installation of any PI Server
feature(s) to meet your deployment requirements.
3. In the Server Roles tab, select PI Notifications Service. A list of components to
be installed is displayed in the Summary panel.
4. Click Next - The AF Server window appears.
5. Enter the PI AF server name to associate with the PI Notifications Service.
6. Click Next to proceed with the setup. The Notifications window appears.
7. Specify the SMTP Server with port number, Backup SMTP Server with port
number and From Email Address to configure for PI Notifications Service.
8. Click on the Use TLS checkboxes to enable TLS encryption for the SMTP server
or backup SMTP server connection. Specify the PI Vision Server URL address to
integrate PI Notifications Service with PI Vision.
9. Click Next to proceed with the setup. The Service Accounts window appears.
10.Specify the service account for PI Notifications Service. Select the default
account NT SERVICE\PINotificationsService or specify a different service

61
© 2021 OSIsoft, LLC. All rights reserved
 account. If the AF Server is remote to the PI Notifications service, then you
must use a domain account or a Managed Service Account because the service
account credentials will be mapped to the Notifications identity on the AF
Server. If your computer is in a Workgroup the installation must be run silently
and additional steps might be necessary to guarantee that the PI Notifications
Service has access to AF Server. Since the PI Notifications Service also needs
read access to PI Points, a domain account or Managed Service Account may
also be desired for configuring Windows integrated security in the Data
Archive.
11.Click Next to proceed with the setup. The Summary window appears, listing
the selected features and version numbers scheduled for the installation.
12.Click Install. The Installation Progress window opens. The Complete window
opens when the installation is complete. Note: If you cancel the installation
before it is complete, the PI AF SQL database might have already been created
and you will need to remove the database manually.
13. Click Close.

To enable high availability for PI Notifications Service, you must install the service
in each node of a failover cluster. More information can be found in this article.

Account permissions for the PI Notification service

The account that PI Notifications Service uses requires read access to the PI point
database (PIPOINT) on each Data Archive server that the service accesses. The PI
Notifications Service account also requires specific permissions to PI AF objects and
local directories.
Configure Data Archive access for PI Notifications Service
1. Use PI SMT to grant the PI Notifications Service account read access to the
PIPOINT database on any Data Archive to which PI Notifications Service requires
access:
a) Create a new PI identity (Security > Identities, Users, & Groups).
b) Give the identity read access to the PIPOINT database (Security >
Database Security). For more information on access permissions for PI
points, see the PI SMT topic PI point access permissions article.

62
© 2021 OSIsoft, LLC. All rights reserved
 c) Create a mapping between the PI identity and the account that runs the
service (Security > Mappings and Trusts). If you are using the virtual
account, you will need to use the PI AF server machine's computer
account to create the mapping. See also the Microsoft article
Understanding Computer Accounts.
After you grant the PI Notifications Service account access to the PIPOINT database,
the service will, by default, have the necessary access to all points subsequently
created on that Data Archive server.
2. For any pre-existing points that you will use for notifications, make sure that the
PI Notifications Service account has the following access permissions:
PtSecurity (r)
DataSecurity (r)

You can use PI SMT or PI Builder to configure the point access for PI Notifications
Service.
PI AF object and local machine permissions for PI Notifications Service
The PI Notifications Service setup process using the PI Server install kit creates the
PI AF identity Notifications, maps the PI Notifications Service account to that
identity, and grants that identity the PI AF object permissions shown in the
following tables. The setup process also grants the PI Notifications Service account
permission to access the local machine directory.
• If an account has administration privileges on the PI AF server, then the account
has all security rights to all objects within the PI AF server, including all
databases. This is true whether the account is granted or denied specific rights
on individual objects.
• If you change the PI Notifications Service log on account after installation, you
must make sure the new user has permissions to access necessary AF objects.
The easiest way to do this is to add a mapping for the user to the Notifications
identity in the PI AF Server. The sections below describe the necessary
permissions in detail.
PI AF Object Permissions

63
© 2021 OSIsoft, LLC. All rights reserved
 PI AF server and children1 Read/Write, Read/Write Data
Event Frames Read/Write, Read/Write Data, Annotate

1
Children of PI AF server include but are not limited to database, elements, element
templates, notification rules, enumeration sets, contacts, and categories.
Local Machine Directory Permissions
%ProgramData%\OSIsoft\PINotifications Read, Write, Modify

Create a notification based on an Event Frame

If you have already configured analyses to detect anomalies in your PI AF asset
data, or you wish to configure such analyses, follow this procedure to configure
notification rules on configured analyses.
If you want to configure notification rules to trigger on event frames from sources
like event frame interfaces or custom applications, see Configure notification rules
for user-defined event frames.
Configure notification rules from analyses
1. Select the existing event frame generation analysis for which you want to
create a notification rule.

2. Click Create a new notification rule for the selected analysis. You see the
Notifications Rules tab highlighted, as well as the options to configure a
notification rule with the default name "Notification Rule".

64
© 2021 OSIsoft, LLC. All rights reserved
3. Edit the created notification rule.
a. Provide one or more of the specified criteria; some of your criteria may
be pre-selected from your analysis. The notification rule is triggered
when all criteria are satisfied. You should change the name of the
notification rule from the default, add a suitable description, and
select a suitable category.
b. Selecting a category aids in organizing and searching for your
notification rules.
4. Click View/Edit Trigger - The Trigger Criteria pane allows you to configure either
of these trigger criteria modes: Analysis or Event Frame Search. Make sure that
the Analysis criteria mode is selected.
5. Steps 5-7 are optional depending on your goals, the information provided here
is for your reference: Configure options in the Trigger Criteria pane.
a. You see the details of the selected analysis such as the event frame
template name, the start and end triggers, and so on.
b. You can configure a new analysis of type Event Frame Generation or
SQC. When you choose to create a new analysis with either the default
or a custom name, you see the same analysis creation window as from
the Analyses tab of PI System Explorer.
c. For more information, see Trigger criteria in notification rules.

65
© 2021 OSIsoft, LLC. All rights reserved
 6. Configure options in the Options pane.
a. Optional. Resend Interval. Select the time interval at which PI
Notifications Service will send additional alerts if the event frame
matching the notification rule is not acknowledged or closed. For more
information, see Resend Interval in notification rules.
b. Optional. Non-repetition Interval. Select the time interval for which PI
Notifications Service will not send similar alerts associated with the
same notification rule. For more information, see Non-Repetition
Interval in notification rules.
c. Event Frame Can Be Acknowledged. This option is automatically
selected if the event frame template has been configured for
acknowledgment.
d. Optional. Options based on multiple start triggers. If you have
configured multiple start triggers for your analysis, choose between
the options of being notified (a) when the current trigger severity is
higher than any trigger severity encountered so far, (b) when the
current trigger severity is higher than the previous trigger severity, or
(c) every time a trigger condition is true, regardless of its relative
severity to other previous triggers.
7. Optional. To configure the email format, click Manage Formats in the
Subscriptions pane. You see the Message and Content panes. By default, the
notifications feature uses the Global Default Email format for each
66
© 2021 OSIsoft, LLC. All rights reserved
 subscriber. For more information, see Delivery formats in notification rules.
Note: If the Content pane has a message indicating that your selected format
is "read-only", you must first add a new format before you can customize it.

8. Optional. To create a custom delivery email format, copy the default Global
Default Email format by clicking on the copy icon in the Message pane.
Alternatively, you can create a new delivery format by clicking the new
delivery format icon . The default format includes basic notification
information such as the notification rule name, trigger time and event frame
start time, as well as system information such as system and database
names. To add more information to your custom format, drag and drop
information from the Content pane to the Message pane. You can designate
your custom format as the default by clicking the Is Default box in the
Message pane.
a. Alternatively: To create a custom delivery email format, copy the
system-provided, default Global Default Email format by clicking on the
copy icon in the Message pane (for more details on global email
formats see Delivery formats in notification rules)
9. Click View/edit subscriptions in the Subscriptions pane. You can search for
contacts using Contacts Search in the Contacts pane. To add a subscriber,

67
© 2021 OSIsoft, LLC. All rights reserved
 drag and drop a specific contact from the Contacts pane to the Subscriptions
pane. Make sure to select your customized email format if you have created
one, or pick the Global Default Email format. For more information, see
Subscriptions in notification rules.

10.Optional. Configure escalation teams.

a. You can configure members of escalation teams from the Contacts
plug-in on PI System Explorer, as described in Manage contacts. The
escalation team contacts, or groups will be notified one by one at the
end of time segments specified in Escalation period. You can also
control the frequency of the escalation notification.
b. Note: Escalations are triggered on event frame templates that can be
acknowledged. Open the Library plug-in on PI System Explorer, select
your event frame template and verify that the Event Frame Can Be
Acknowledged check box is selected.
11.Check in the notification rule - When the event of interest occurs, an email
will be sent to the subscriber's mailbox. The email shows the event frame
that triggered the notification rule with customized details that you have
configured.
To manage your notification rules, use the Management plug-in on PI System
Explorer. See Management of notification rules.

68
© 2021 OSIsoft, LLC. All rights reserved
Troubleshooting the PI Notifications Service

1. Configure logging for the PI Notifications Service

Notifications message logs contain useful information to troubleshoot issues with

PI Notifications Service. Adjusting the severity level and verbosity of message logs
can assist with identifying issues more easily and better troubleshooting.
At the end of installation, the notifications folder (%PIHOME64%\Notifications or
<Drive name>:\Program Files\PIPC\Notifications) contains the:
• PINotifications.exe.config file for each process and
• the Notifications.UserNLog.config file for NLog configuration, a popular
logging tool for troubleshooting.
Caution: Increasing the debug level from the default can flood the logs and
decrease performance. Do not leave the debug level higher than the default for
longer than necessary.
%programdata%\OSIsoft\PINotifications\Logs is the default directory that the
logs are written to. More information on configuring logging can be found here.

69
© 2021 OSIsoft, LLC. All rights reserved
 2. Access Performance Counters

The PI Notifications Service has performance counters for monitoring the status of
notification rules.
To gather statistics around PI Notifications service, use Windows performance
counters. You can view and access available performance counters with the
Windows Performance Monitor.
1. On the Windows system hosting the service, click Control Panel > System and
Security > Administrative Tools. A list of administrative tools are listed.
2. Double-click Performance Monitor to open Windows Performance Monitor.
3. Expand Monitoring Tools and click on Performance Monitor in the navigation
panel on the left.
4. Click the button. The Add Counters window appears.
5. In the Available counters panel, expand PI Notifications Service. The list of PI
Notifications Service performance counters is here.

For a full list of the available counters explained, have a look at this article.

70
© 2021 OSIsoft, LLC. All rights reserved
- Next Steps
Thank you for taking this course!
Continue learning with our self-paced courses on the Asset Framework:
• Configuring Analytics with PI AF
o Learn how to create different types of asset analytics to gain more
insight into your data. Using Asset Framework (AF), we will explore a
range of analyses including expressions with multi-line calculations,
roll-ups for aggregate attributes, event frames to capture important
events in your process, and notifications to trigger alerts based on the
real-time changes in your asset.
• Asset Maintenance: Using a Layered Approach
o We walk through scenarios to illustrate the use of process data and
machine condition data and a layered approach to maintenance via
usage-based, condition-based and predictive maintenance. Data
sources include traditional plant instrumentation such as PLCs and
SCADA, the newer IoT devices, and from machine condition
monitoring such as vibration, oil analysis etc. In this lab will also
discuss predictive maintenance use cases that require advanced
analytics, including machine learning, such as APR (advanced pattern
recognition), anomaly detection, and others.
• Easy Wins to Improve your Asset Framework Experience
o Best practices and hands-on exercises on how to get started with Asset
Framework (AF) and Asset Analytics. The course will cover setting the
scope and modelling accordingly, dealing with asset variations and tag
naming conventions, integrating external data in AF, building well-
configured AF analyses and propagating changes between separate
environments (test-to-production or central-to-local systems).

71
© 2021 OSIsoft, LLC. All rights reserved
OSIsoft Self Paced Training Course

PI System Administration: Basics

OSIsoft, LLC
1600 Alvarado Street
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Web: http://www.osisoft.com

© 2020 by OSIsoft, LLC. All rights reserved.

OSIsoft, the OSIsoft logo and logotype, Analytics, PI ProcessBook, PI DataLink, ProcessPoint, Asset
Framework (AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI
BatchView, PI Vision, PI Data Services, Event Frames, PI Manual Logger, PI ProfileView, PI
WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all
trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their
respective owners.

U.S. GOVERNMENT RIGHTS

Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft,
LLC license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR
52.227, as applicable. OSIsoft, LLC.

Published: July 28, 2021

2|Page
 PI System Administration: Basics

Table of Contents
1. Introduction .......................................................................................................................................... 6
1.1 Overview of the Course ................................................................................................................ 6
1.2 PI System software........................................................................................................................ 7
2. [Optional] Preparing for a PI System .................................................................................................... 8
2.1 Background: What Preparation is Needed?.................................................................................. 8
2.2 Background: Hardware Sizing ....................................................................................................... 8
2.3 Background: Software Prerequisites........................................................................................... 11
2.4 Background: Service Accounts and Certificates .......................................................................... 11
2.4.1 Service Accounts ................................................................................................................. 11
2.4.2 Group Managed Service Accounts ...................................................................................... 12
2.4.3 Certificates .......................................................................................................................... 12
2.4.4 Service Principle Names ...................................................................................................... 13
2.5 Background: Firewall Port Requirements ................................................................................... 13
2.6 Background: PI Data Archive License File Activation .................................................................. 13
3. PI Server Installation ........................................................................................................................... 16
3.1 Hands-On: PI Server Installation ................................................................................................. 16
3.2 Hands-On: Post-Install - Backup.................................................................................................. 17
3.3 Hands-On: Post-Install - Security ................................................................................................ 17
3.4 Knowledge Check: Final Post-Install Tasks .................................................................................. 19
3.4.1 Exercise - Create a Mapping ............................................................................................... 20
4. PI Interface Installation ....................................................................................................................... 21
4.1 Background: How Does the PI System Connect to Data Sources? ............................................. 21
4.1.1 PI Interfaces ........................................................................................................................ 21
4.1.2 PI Connectors ...................................................................................................................... 22
4.1.3 PI Adapters .......................................................................................................................... 22
4.1.4 Custom Applications ........................................................................................................... 22
4.2 Hands-On: PI Interface Installation ............................................................................................. 23
4.3 Knowledge Check: Confirming Connectivity ............................................................................... 24
4.4 Hands-On: PI Interface Configuration ......................................................................................... 24
4.5 Knowledge Check: The PI Data Archive Message Log ................................................................. 34
4.5.1 Exercise - Explore the PI Data Archive Message Log........................................................... 34

3|Page
 4.6 Knowledge Check: Confirming Interface Operation ................................................................... 32
4.6.1 Part 1: Check that you are receiving data for all points belonging to the interface in the PI
Data Archive ........................................................................................................................................ 32
4.6.2 Part 2: Check that data is flowing through the buffer ........................................................ 32
4.7 Knowledge Check: The Bufferer, the Betterer ............................................................................ 26
5. PI Point Management ......................................................................................................................... 28
5.1 Hands-On: Creating Points for Interfaces ................................................................................... 28
5.2 Background: Explore PI Points and Interfaces ............................................................................ 29
5.3 Background: Compression and Exception .................................................................................. 29
5.4 Reference: The Interface User Manual ....................................................................................... 29
5.5 Knowledge Check: Creating Digital Points .................................................................................. 30
5.5.1 Introduction to Digital Points .............................................................................................. 30
5.5.2 Digital State Sets ................................................................................................................. 30
5.5.3 Exercise: Create a Digital State Set and Point ..................................................................... 31
5.6 Hands-On: Creating Points in Bulk .............................................................................................. 32
5.7 Knowledge Check: Creating More Points.................................................................................... 34
5.7.1 Exercise - Create Points for Pump Current ......................................................................... 37
5.7.2 Exercise Solution ................................................................................................................. 37
6. Improving Interface Reliability ............................................................................................................ 39
6.1 Background: Interface Redundancy ............................................................................................ 39
6.2 Knowledge Check: Preparing a Second PI Interface ................................................................... 39
6.2.1 Exercise: Configure an OPC Interface on PIINT02 ............................................................... 39
6.3 Hands-On: Configure UNIINT Failover ........................................................................................ 40
6.3.1 Part 1: Prepare the shared folder ....................................................................................... 40
6.3.2 Part 2: Configure failover on one interface ........................................................................ 40
6.3.3 Part 3: Fix security for UFO status tags ............................................................................... 41
6.4 Knowledge Check: Interface Health Points ................................................................................. 43
6.4.1 UniInt Health Points ............................................................................................................ 43
6.4.2 Exercise - Create UniInt health points for both of your Interface instances ...................... 44
7. Managing User Access ........................................................................................................................ 45
7.1 Hands-On: Data Archive Security ................................................................................................ 45
7.2 Background: What is Asset Framework? .................................................................................... 46
7.3 Hands-On: Asset Framework Security ........................................................................................ 47

4|Page
 PI System Administration: Basics

7.4 Knowledge Check: Contractor Access ......................................................................................... 49

7.4.1 Part 1: Prepare your Data Archive and Asset Framework .................................................. 49
7.4.2 Part 2: Satisfying a new management request ................................................................... 50
7.4.3 Part 3: Satisfying another management request ................................................................ 50
7.4.4 Part 4: Check if your changes worked ................................................................................. 50
8. Managing Data .................................................................................................................................... 51
8.1 Background: What are Archive Files? ......................................................................................... 51
8.2 Knowledge Check: PI Archives in Depth ..................................................................................... 51
8.2.1 Exercise: Move old archives to a different drive ................................................................ 52
9. Final Exam ........................................................................................................................................... 54

5|Page
1. Introduction

1.1 Overview of the Course

Before reading this section, please refer to the following course YouTube
video: https://youtu.be/yJgPct6gAtg
Video

This course will teach new PI System Administrators to install, configure, secure and manage the core
components of a PI System, including:

• PI Data Archive installation and configuration

• PI Interface installation and configuration

• PI Point creation and administration

• User access configuration

During the class we'll cover best-practise configuration only, but will link out to documentation covering
older practises and methods when necessary. No matter if you're about to administer a new PI System or
are maintain an established one, you'll get a lot out of this class.

Throughout this class we will assume you have already completed the free PI System Basics class. We will
not cover any background or content that has already been covered in this class.

The course consists of text-based lessons, and video lectures. You are encouraged to follow along with all
video lectures using your Learning Cloud Environment. It is intended that you follow the video lectures in-
order, as a lot of configuration depends on prior lessons. Text-based lessons contain background theory,
documentation and other useful information.

Lessons are categorized using the following key words:

• Hands-On: These lessons contain hands-on walkthroughs on configuring your virtual

environment. Skipping these videos is not recommended, you will find that you cannot complete
some later lessons without first completing the earlier ones.

• Knowledge check: Exercises to complete using your virtual environment, or quizzes to keep your
skills sharp. Lessons will assume you have completed prior knowledge checks. Some knowledge
checks ask you to change the configuration of your virtual environment and skipping them may
result in you being unable to complete later exercises.

• Background: Readings or videos containing useful background information to assist your

understanding. These lessons are optional as they do not contain specific information regarding
your virtual environment.

6|Page
 PI System Administration: Basics

• Reference: Documentation or downloads you may find useful when applying this class to your
own system. You are not expected to read through all references, and will not be examined on
any content within them, but they are included for your convenience.

In the next lesson we'll cover the Learning Cloud Environment used in class, and what we'll accomplish in
this class in detail.

1.2 PI System software

The VM (virtual machine) used for this course has the following PI System software installed:

Software Version

PI Data Archive 2018 SP3

PI Asset Framework (PI AF) server 2018 SP3

PI Asset Framework (PI AF) client (PI System Explorer) 2018 SP3

PI Analysis & PI Notifications Services 2018 SP3

PI Interface Configuration Utility 1.5.0.7

PI Interface for OPC DA (Read Only) 2.7.1.41

For details on PI System software, please see http://www.osisoft.com/pi-system/pi-capabilities/product-

list/

After reading this section, please refer to the following course YouTube
video: https://youtu.be/WYPOsLvogkQ
Video

7|Page
2. [Optional] Preparing for a PI System

You can consider this chapter optional. If you will never plan for or install a PI System from scratch, the
knowledge contained in this chapter is not strictly needed. If you will only ever maintain a PI System
already in place, you can skip to the next chapter.

2.1 Background: What Preparation is Needed?

During this section we will cover prerequisites for a PI System Core installation. Even if your job
description doesn't involve installing software in any way - preparing for and installing a system is the
best way to learn how it all fits together. Preparing for a new PI System Installation consists of four
parts:

1. Size up and Procure hardware

2. Install software prerequisites

3. Create service accounts and certificates

4. Obtain a PI Data Archive license file

Documentation for PI Server installation can be found on PI Live Library

Installation best practices are found in the PI Data Archive Install Field Service
✔ Best
Technical Standard. This document can be downloaded from the [Reference: PI
Practice
Data Archive Install Technical Standards] lesson online.

2.2 Background: Hardware Sizing

On OSIsoft’s Customer Portal MS Excel spreadsheet “Hardware and PI System Sizing Recommendation
Spreadsheet” can be found and downloaded (link). You can also find the spreadsheet attached to this
lesson.

This spreadsheet gives recommendations for the following hardware resources based on current or
anticipated load and data volume.

• Storage Capacity

• Disk Throughput (IOPS)

• CPU Count

• Memory (RAM)

• Network Bandwidth

8|Page
 PI System Administration: Basics

The amount of disk space required depends primarily on the number of PI points that the PI system will
collect. See below to calculate the necessary disk space.

PI Data Archive Space Requirement Notes

Component

PI Data Archive and PI 160 MB PI SDK includes the PI API.

Software Development
100 MB temporary disk
Kit (PI SDK)
space for installation

PI Data Archive 11 MB per 1000 points + 1 Located on the same computer as the
databases MB PI Server.

Message log files 10 MB Located on the same computer as PI

Server, in the pi\log directory.

PI Archive files 10 MB per 1000 points

PI event queue 5 MB per 1000 points OSIsoft recommends that you place
the event queue on a different
physical drive from the PI archive files.

Rollback backup Size of PI Data Archive The PI Archive setup program

(upgrade only) databases + primary performs a minimal backup during the
archive upgrade.

For PI Data Archive, PI AF server, and Microsoft SQL Server, one or more Microsoft Windows compatible
computers, with a 64-bit operating system is required.

For best performance and improved security, OSIsoft recommends that you install MS SQL Server on a
different computer from PI Server. If you plan to install MS SQL Server on the same node as the PI Data
Archive, the SQL Express Edition should be installed so that the MS SQL Server does not compete with
system resources of the PI Server. The MS SQL Express Edition is limited to using only a single physical
CPU and 1 GB of RAM.

It is recommended that the PI AF server and PI Data Archive server be installed on different computers if:

• PI AF server will use time-series data from multiple PI Servers

• PI AF server is configured for high availability (such as a load balanced PI AF server, PI AF servers
connected to a mirrored MS SQL Server, or PI AF servers connected to clustered MS SQL
Servers).

The number of required computers depends on the size and complexity of the PI System. The size of a PI
System depends on the number of PI points and the number of units (elements) of equipment (such as
mixers, tanks, or meters or whatever else you have added into the asset database).

A simple, small system will have the PI Data Archive, the PI AF Server and MS SQL Server (the free MS
SQL Server Express may be used) installed on the same hardware (or virtualised) server, as shown
below:

9|Page
For distributed systems with large workloads and point counts, and with multiple PI Servers or PI Data
Archive Server collectives that link to a central PI AF database, OSIsoft recommends that you install PI
Data Archive Server collectives with two PI AF Servers with a Network Load Balancer over them, and
Microsoft SQL Server on separate, redundant computers to achieve the best level of performance and
scalability. This type of system is depicted below:

10 | P a g e
 PI System Administration: Basics

2.3 Background: Software Prerequisites

There are two major prerequisites for a PI System:

• Microsoft Windows
• Microsoft SQL Server
• A Data Source for Time Series Data

Except for select interfaces and adapters, all PI System software is Microsoft Windows-based. Any server
where PI System software will be installed must have Microsoft Windows installed on it.

Microsoft SQL Server is required by both PI AF Server, and PI Vision. In this class we'll be focusing on PI
AF Server - PI Vision installation is not covered in this class. To see which versions of Microsoft SQL
Server are supported, see the SQL Server Requirements documentation.

Your time-series data source will be defined by your desired project outcome. Which pieces of
equipment or data sources do you want to expose to your users? How do they expose their data now?
These topics will be covered in depth during the upcoming lesson on PI Interface Installation and
Configuration. For now, this course will assume you'll be using an OPC DA Server as your data source, as
it is by far the most common. During the upcoming lesson on PI Interface installation and configuration,
we will study this depth and cover non-OPC Server data sources. For more information on OPC DA, see
the OPC Foundation's page on the topic.

2.4 Background: Service Accounts and Certificates

Your IT Department will need to configure domain objects prior to installing the PI System, in the form
of:

• Service accounts

• Certificates

• Service Principle Names

The information below should give you a better idea on what each of what to ask your IT department for
regarding each of these topics.

2.4.1 Service Accounts

You can think of a service account similarly to a user account in a domain. It is an account that has been
created for the purpose of running a specific service. Modern security best practises dictate that services
that require different levels of access to different objects should run under different accounts. The
permissions on these accounts should follow the principle of least privilege - each one should have the
minimum privileges to perform its function and nothing more.

During this class, we will be using service accounts for the following services, and configuring least-
privilege for each:

11 | P a g e
 • PI AF Server

• PI Analysis Service

• PI Interface for OPC DA

• PI Buffer Subsystem

In this class we build a very simple system, but in a more complex production system, you may also need
service accounts for:

• PI Notifications Service

• Any additional individual PI Interface instances

• PI Vision

• PI Web API

• PI Data Archive Network Manager

• PI Connectors, PI Connector Relay, PI Data Collection Manager

• Any PI Integrators

• Any additional standalone or legacy PI System services

2.4.2 Group Managed Service Accounts

In this class we will be using a special type of account for this job, called Group Managed Service
Accounts (gMSAs). Most of the steps we work through in this class also work with other account types,
and when there are configuration differences we'll make sure to mention them. We use gMSAs because
their passwords are automatically managed by the domain, and they align much better with what we're
trying to achieve than other account types. Once the initial setup is done, your job as an administrator is
much simpler as password changes and maintenance is automatically performed. You can read more
about using this type of account with PI System Services here and you can read about migrating to
gMSAs here (both links require a validated OSIsoft customer portal account).

2.4.3 Certificates

You will need SSL Certificates generated for:

• PI AF Server

• PI Vision Server

There are many ways to generate these certificates, and the process you use will be decided by your IT
department. You will need to ask your IT department for certificates for these two servers, generated by
an authority that is trusted by all users that are going to be using the PI System at your organisation. For
more information on these certificates, see the PI Vision documentation here.

12 | P a g e
 PI System Administration: Basics

During this course we won't be installing PI Vision, but we will be installing PI AF Server, so we will need
a certificate. We'll be using a certificate generated by our Domain's Certification Authority. The
certificate we're using in this class have similar function to certificates generated by your IT department
for use within your corporate domain, trusted by domain-joined computers and users. This is the most
common type of certificate used for PI System Services the field.

2.4.4 Service Principle Names

This section relates specifically to the PI Vision and PI Web API components of the PI System. SPNs are
used by Kerberos authentication to associate a service instance with a service logon account. If you'll be
installing PI Vision and/or PI Web API, you'll need your IT department to set up SPNs for these services
before users are able to connect to them. For more information start reading the PI Vision
documentation from the chapter on Kerberos Delegation here.

2.5 Background: Firewall Port Requirements

When connecting to any server with PI System software installed, the port for the service(s) installed on
the server must be open. This is a task for your IT department to complete before an installation
proceeds. All servers in your learning environment already have the required ports open.

A quick summary of inbound ports that must be open for each service:

Service/Product Port

Data Archive 5450

Asset Framework Server 5457, 5459

PI Notifications 5468

PI Analysis Service 5463

PI Vision 80, 443

A full list of knowledge base articles on this topic can be found here.

A simple way of checking if a port is open from one machine to another is to take advantage of the Test-
NetConnection PowerShell cmdlet. Running the following command will attempt a connection to
MACHINE on port 5450.

Test-NetConnection MACHINE -Port 5450

If you see an error, the port is blocked. If you don't see an error, the port is open.

2.6 Background: PI Data Archive License File Activation

A License File must be generated before the PI Data Archive server is installed. The OSIsoft Customer
Portal allows you to generate your site-specific PI Server license file. This license file controls which

13 | P a g e
applications can run on the PI Data Archive Server and displays running parameters, such as the point
count limit.

When the license file is generated, view the PI Server Manifest to verify the server details.

In order to generate license file, a Machine Signature File (MSF) is required. The PI Server install kit is
capable to generate the MSF by itself, you must copy the install kit to a local disk on the PI Data Archive
Server computer and then run the kit.
The kit will generate the MSF file to Documents folder of user running it.

i.e. C:\Users\<username>\Documents

If the PI Data Archive Server is on a virtual machine (VM), run the utility on the VM. If you generate the
MSF on the wrong computer (on your laptop, for example) then the license activation file will match the

14 | P a g e
 PI System Administration: Basics

laptop computer. If you install PI Data Archive Server on a different computer or VM, the server will not
run as expected. The license file must be present during the installation. It can be on a flash drive, CD, or
any media that can be read by PI Data Archive Server during installation. The setup program copies the
license file to the %PISERVER%\dat directory during installation; the original file will no longer be used.

For more information, see the PI Data Archive Installation and Upgrade documentation here.

15 | P a g e
3. PI Server Installation

3.1 Hands-On: PI Server Installation

This is a hands-on chapter. It is recommend that you watch the video for
this chapter and follow the steps using your own virtual environment:
https://youtu.be/TcJ2Nw_R1Lk. Below are the configuration steps
Video performed in the video.
In this section we cover PI Server Installation. Documentation referenced in this video can
be found here.
Below is a step-by-step walkthrough on changes that are made to our virtual environment
during this lesson:
Part 1: Data Archive Installation
1. Connect to PISRV01
2. Double click the PI Install Kits shortcut on the desktop
3. Right click → Run as Administrator on the PI Server install kit
4. Click Next
5. Select to install the PI Data Archive role
6. Change the three installation directories so they all point to D:\ instead of C:\,
keeping the rest of the installation paths the same as default
7. Click Next
8. Click the Ellipsis "..." button next to License directory
9. Select the file D:\PI Install Kits\Training License\pilicense.dat
10. Click OK
11. Change the Historical and Future Archive data directories to all point to E:\, keeping
the rest of the installation paths as default
12. Change the Event Queues directory to point to D:\, keeping the rest of the
installation path as default
13. Click Next
14. Click Install, and wait until it finishes.
Part 2: Asset Framework Installation
1. Connect to PISRV02
2. Double click the PI Install Kits shortcut on the desktop
3. Right click → Run as Administrator on the PI Server install kit
4. Click Next
5. Select to install the AF Server and PI Analysis Service roles

16 | P a g e
 PI System Administration: Basics

6. Click Next
7. Click Next on the SQL Server Connection page without making any changes
8. Click Select under the HTTPS section
9. Click OK
10. Click Next
11. Change the PI AF Application Service to run under PISCHOOL\SVC-PIAF$
12. Change the PI Analysis Service to run under PISCHOOL\SVC-PIANALYT$
13. Change the PI SQL DAS to run under PISCHOOL\SVC-PIRTQP$
14. Click Next
15. Click Install, and wait until it finishes.

3.2 Hands-On: Post-Install - Backup

This is a hands-on chapter. It is recommend that you watch the video for
this chapter and follow the steps using your own virtual environment:
https://youtu.be/3b7pLe22Nzs. Below are the configuration steps
Video performed in the video.
Below is a step-by-step walkthrough on changes that are made to our virtual environment
during this lesson:
1. Connect to PISRV01
2. Open a command prompt with the shortcut on the taskbar
3. Type the following commands

D:
cd %piserver%\adm
pibackup E:\PIBackup -install

4. Click the Windows Start button

5. type Task Scheduler and press the enter key on your keyboard
6. Click Task Scheduler Library
7. Right click on PI Server Backup and click Run
8. After a few minutes, ensure the backed up files are created at E:\PIBackup

3.3 Hands-On: Post-Install - Security

This is a hands-on chapter. It is recommend that you watch the video for
this chapter and follow the steps using your own virtual environment:
https://youtu.be/28OSQGrIPVk. Below are the configuration steps
Video performed in the video.

17 | P a g e
In this lesson we assume you will exclusively use the modern method to authenticate
services and users that connect to the PI Data Archive; PI Mappings. We switch off PI Trusts
completely as they're not being used by our system. If your organisation still uses legacy PI
Trusts for authentication, we recommend reading the documentation for configuring PI
Interface connections using PI Trusts to fully understand how these work. Even if your
organisation has existing trusts, we do not recommend creating any new trusts for new
interfaces or services in your system.
Below is a step-by-step walkthrough on changes that are made to our virtual environment
during this lesson:
Part 1: Create a Mapping for your administrator user
1. Connect to PISRV01
2. Through the Start menu, open PI System Management Tools
3. Navigate to Security → Mappings and Trusts
4. Click New Mapping in the top left corner
5. Enter the following
o Windows Account: PISCHOOL\student01
o PI Identity: piadmins
6. Click Create
7. Close and reopen PI System Management Tools
8. Navigate back to Security → Mappings and Trusts
9. Ensure the account name in the bottom left hand corner says
"PISCHOOL\student01 | piadmins, PIWorld". If it still says piadmin (without the s
on the end) go back and begin these steps again.
Part 2: Create an Identity and Mapping for the Analysis Service
1. Navigate to Security → Identities, Users and Groups inside PI System
Administration Tools on PISRV01
2. Click the New Identity button in the top left of the window
3. Type the name SVC-PIANALYT
4. Click Create
5. Navigate to Security → Database Security
6. Double click on PIPOINT
7. Click Add
8. Select SVC-PIANALYT
9. Click Add
10. Check the box next to Write
11. Click OK

18 | P a g e
 PI System Administration: Basics

12. Navigate to Security → Mappings & Trusts

13. Click New Mapping in the top left corner
14. Enter the following
o Windows Account: PISCHOOL\SVC-PIANALYT$
o PI Identity: SVC-PIANALYT
15. click Create
Part 3: Disable the Temporary Lookback Trust [Note: This step should only be done for new
PI Systems, or if you have already checked that you do not have any applications that require
the loopback trusts to be in place to function]
1. Navigate to Security → Mappings & Trusts inside PI System Administration Tools
on PISRV01
2. Click the Trusts tab at the top of the screen, just below the row of buttons
3. Double click the only trust in the list: !Proxy_127!
4. Check Trust is Disabled
5. Click OK
Part 4: Raise the Security Slider to Maximum [Note: This step should only be done for new PI
Systems, or if you have already checked that you do not have any applications that require
trusts to be in place to function]
1. Navigate to Security → Security Settings inside PI System Administration Tools on
PISRV01
2. Drag the Slider up to the top
3. Click Save
Part 5: Restart the Data Archive Services
1. On PISRV01, start a command prompt with the shortcut in the taskbar
2. run the following commands:
D:
cd %piserver%\adm
pisrvstop.bat
pisrvstart.bat

3.4 Knowledge Check: Final Post-Install Tasks

Great, so we've installed our server, let all the services in, and configured backups. Except...
we forgot one service. During installation of the AF server, we were asked for a service
account for the Real-Time Query Processing (RTQP) Engine Service to run under. The RTQP
service requires read access to the PI Data Archive. If we have a service that needs access to
the Data Archive - what do we need to create to let it in?

That's right - a mapping.

19 | P a g e
3.4.1 Exercise - Create a Mapping

Follow the steps below to create the mapping for our RTQP Engine service:

1. Connect to PISRV01
2. Open PI System Management Tools (SMT)
3. Use PI SMT to create an identity for the service, and a mapping for the account to the
new identity. During installation of the AF Server we specified PISCHOOL\SVC-PIRTQP as
the account to run the RTQP Engine Service.

20 | P a g e
 PI System Administration: Basics

4. PI Interface Installation

4.1 Background: How Does the PI System Connect to Data

Sources?
There are a number of software components that can be used to extract data from a data
source and store it in the Data Archive and/or the AF Server. If you have a data source that
you'd like to read from, the easiest way to find the appropriate software component is to
search our Interface List. The search on this page finds any of the below components that can
connect to your desired data source, and directs you to references where you can find out
more.

4.1.1 PI Interfaces

OSIsoft has over 450 different interfaces in it's library of software, and their reliability and
resiliency has made them an industry standard for decades. They do not automatically
synchronise data streams or asset hierarchies from a data source to a PI System. Configuration
and maintenance must be manually done by the administrator for the most part.
We will focus on interfaces in this class because:

• They are by far the most common method of connecting a PI System to a data source that
you will find in the wild
• They require far more maintenance and setup by PI System Administrators than other
connection technologies - if you are a PI System Administrator in the early 2020s in almost
any organisation that uses the PI System, you must be familiar with interface configuration
and maintenance

So even though they are the oldest technology we list on this page - and we recommend using
any of the more modern methods below where possible, we'll still focus on Interfaces in this
course.

21 | P a g e
4.1.2 PI Connectors

PI Connectors follow a much more modern design and architecture, and require considerably
less maintenance and management than interfaces. Their features most notably include
automatic point creation - normally a very time consuming task for PI System Administrators
that manage interfaces. If you can find a PI Connector that supports your data source using the
aforementioned interface list search, you should use it over an equivalent interface in almost
every case. The technologies may not completely overlap and you may need to reconsider your
architecture, but it will be a worthwhile exercise.
For example, you'd like to read from a data source that supports several different OPC
standards. The source is capable of being both an OPC UA and OPC DA server. Is this case you
would most likely be much better off using the PI Connector for OPC UA over the PI Interface
for OPC DA. Before making a choice between connection technologies, thoroughly read the
documentation for each.

4.1.3 PI Adapters

PI Adapters are a newer technology, designed for fast deployment on low-power equipment.
They are not managed through user interaction, but through programmatic service calls.
Configuring PI Adapters are beyond the scope of this course, but if you have a scenario where
there is highly distributed equipment and must extract that data using low-power consuming
devices that must be managed in bulk, you may want to look into PI Adapters. You can find out
more on PI Live Library under the "Edge" subheading.

4.1.4 Custom Applications

Many organizations develop their own applications to both read from and write to the PI
System using technologies such as PI AF SDK, PI Web API, or OMF. The use of these

22 | P a g e
 PI System Administration: Basics

technologies is beyond the scope of this course, but as a PI System Administrator, you should
know that programmatically accessing or writing to the Data Archive and Asset Framework
components is always an option if you can't find an out-of-the-box method of integrating
systems together.

4.2 Hands-On: PI Interface Installation

This is a hands-on chapter. It is recommend that you watch the video for
this chapter and follow the steps using your own virtual environment:
https://youtu.be/emNsxVcfHQE. Below are the configuration steps
Video performed in the video.
Below is a step-by-step walkthrough on changes that are made to our virtual environment
during this lesson:
Part 1: Install the PI Interface Configuration Utility
1. Connect to PIINT01
2. Open the PI Install Kits folder on the desktop
3. On the installer for PI ICU, right click → Run as Administrator
4. Click OK
5. Click OK
6. For the Default Data Server, input: PISRV01
7. Click Next
8. Change the installation directories to install to D: instead of C:. Keep the rest of the
paths the same as the default.
9. Click next, and continue through the rest of the installer
Part 2: Install the PI Interface for OPC DA (Read only)
1. On the installer for the OPC Interface, right click → Run as Administrator
2. Click OK
3. Click OK
4. Click Next
5. Continue through the rest of the installer until it is complete
Part 3: Install the PI API for Windows Integrated Security
1. On the installer for the PI API for Windows Integrated Security, right click → Run as
Administrator
2. Click OK
3. Click Install
4. Continue through the rest of the installer until it is complete

23 | P a g e
4.3 Knowledge Check: Confirming Connectivity

This step should have been done during prerequisites, but it's usually a good idea to make sure
the interface machine can connect to the correct port on the Data Archive machine before even
getting started installing. This way, if the port is blocked you can contact your IT department
and make sure the issue is resolved before you need to configure the system.

1. Open your connection to PIINT01

2. On PIINT01, open a Windows PowerShell console
3. Type and run the following command:

Test-NetConnection PISRV01 -Port 5450

This command will attempt to initiate a TCP connection on port 5450 to PISRV01, our Data
Archive. If successful, it means that we should be able to proceed with our configuration of our
interface. If the command gives an error, it means you need to talk to your IT department about
allowing a connection from your interface machine through to your PI Data Archive on port
5450.

4.4 Hands-On: PI Interface Configuration

This is a hands-on chapter. It is recommend that you watch the video for
this chapter and follow the steps using your own virtual environment:
https://youtu.be/7MyWwfbBVzI. Below are the configuration steps
Video performed in the video.
References in this Video:
• Find more information on the PI Interface for OPC DA here
• Find more information on the PI Buffer Subsystem here
• If configuring an interface instance to read from an OPC Server not on the same
machine as the instance, you must go through DCOM configuration, explained here.
NOTE: During this course we assume that the interface machine is a member of the same
Windows Domain as the PI Data Archive, and set up authentication with this in mind. If
policies within your organisation do not allow this, authentication can still be configured
with the use of Windows Credential Manager. Read more about this in the knowledge base
article here (requires a validated OSIsoft customer portal login account).
Below is a step-by-step walkthrough on changes that are made to our virtual environment
during this lesson:
Part 1: Create the Identity and Mapping for the interface connection on the PI Data Archive
1. Connect to PISRV01
2. Open PI System Management Tools through the Start menu
3. Navigate to Security → Identities, Users and Groups

24 | P a g e
 PI System Administration: Basics

4. Click New... in the top left corner

5. Type the name SVC-PIINT
6. Click Create
7. Navigate to Security → Mappings and Trusts
8. Click New... in the top left corner
9. Type the following details
o Windows Account: PISCHOOL\SVC-PIINT$
o PI Identity: SVC-PIINT
Part 2: Configure the Interface Instance
1. Connect to PIINT01
2. Open the PI Interface Configuration Utility (ICU) from the Start menu
3. Click the Interface menu at the top → New Windows Interface Instance from BAT
File...
4. Select the file D:\Program Files
(x86)\PIPC\Interfaces\OPCInt_ReadOnly\OPCInt_ReadOnly.bat_new
5. Select PISRV01 from the drop down menu
6. Click OK
7. Click the OPCInt menu in the side-bar down the left hand side
8. Click the List Available Servers button
9. Open the drop-down menu under OPC Server Name: and select
OPCSample.OpcDa20Server.1
10. Click Apply in the bottom right corner
11. Click the Service menu in the side-bar down the left hand side
12. Click the Create button
Part 3: Configure Buffering
1. On PIINT01, Inside the ICU, click the menu at the top of the window Tools →
Buffering
2. Click Yes
3. Click Continue with configuration
4. Check the box next to PISRV01
5. Click Next
6. Click Next, then click Yes
7. Change the Buffer location to D:\Buffer
8. Click Next

25 | P a g e
 9. Click Exit new installation wizard
Part 4: Configure Service Accounts
1. On PIINT01, open Computer Management with the shortcut in the taskbar
2. Navigate to System Tools → Local Users and Groups → Groups
3. Double Click on PI Buffering Administrators
4. Click Add
5. search for the account svc-piint and click Check Names, then OK
6. Click OK
7. Open the Windows Services applet with the shortcut in the taskbar
8. On the PI Buffer Subsystem service right click → Properties
9. Go to the Log On tab
10. Change it to run under This account and fill in PISCHOOL\SVC-PIINT$ as the name,
and leave the passwords blank
11. Click OK, and OK again until you are brought back to the services console
12. Repeat steps 8 through 11 for the PI-opcint_ReadOnly1 service, making it also run
under the PISCHOOL\SVC-PIINT$ account
13. Right click and restart the PI Buffer Subsystem service
14. Close all ICU and Buffer Manager windows
Part 5: Configure Dependencies and Start the Interface Instance
1. On PIINT01, open the ICU
2. Select opcint_ReadOnly1 -> PISRV01 from the large drop down select box at the top
of the window
3. Click the Service menu in the side-bar down the left hand side
4. Click Yes
5. Click the play ► button at the top of the window to start the interface

4.5 Knowledge Check: The Bufferer, the Betterer

We have configured an interface, configured buffering for it, and confirmed that everything is
working. But, there's another opportunity to configure buffering in our system.

The PI Analysis service, which we installed on PISRV02, also writes data to the PI Data Archive.
The Analysis service is in charge of watching the Asset Framework server for calculations and
analytics it should run, running the analytics, and writing the results to PI Points. Actual
configuration of these calculations is done in other training classes and we won't configure
them here, but it's our responsibility to make sure things work reliably once analytics start

26 | P a g e
 PI System Administration: Basics

running. Because the analysis service needs to write to PI Points, it also benefits from buffering
being configured. Follow the below steps to configure buffering for this service.

Note: When performing most actions in this course in a production environment, you should
not be logging directly into the server machines. This activity is on exception, however. You
must configure buffering while being logged in to the machine itself.

1. Connect to PISRV02
2. The Interface Configuration Utility isn't installed on this machine - but that's ok. We can
access the buffer manager from PI System Explorer (PSE) too. Open PSE by clicking Start
> PI System > PI System Explorer.
3. Select Tools > Buffering Manager
4. Click Yes to the question asking if you'd like to configure buffering
5. Click Continue with Configuration
6. Change the Buffer location to D:\Buffer
7. Click Next
8. Exit the Wizard

Now we've configured buffering, we need to make sure it connects to the PI Data
Archive using an account that can write to analysis points. In an earlier exercise, we
configured the SVC-PIANALYT group managed service account to have these privileges.

9. Open the Windows Services panel by clicking on the icon for it in the taskbar
10. Modify the PI Buffer Subsystem service so it logs in as the PISCHOOL\SVC-PIANALYT
account (hint: this account is a group-managed service account so you may need to do
special things with dollar signs and passwords. If you don't know what to do, the
configuration is very similar to the configuration we did in the interface buffering video,
but with a different account this time).
11. Create a service dependency for PI Analysis Service on PI Buffer Subsystem to ensure
that PI Buffer Subsystem starts first on machine start. To do this, run Windows
command prompt with the icon in the taskbar and execute the following command:

SC CONFIG PIAnalysisManager depend= pibufss

12. Open Computer Management from the Windows Start menu. Navigate to System Tools
→ Local Users and Groups → Groups
13. Double click on the PI Buffering Administrators group, and add the SVC-PIANALYT
account to the group
14. Use the Windows Services panel to restart the PI Buffer Subsystem service. It should
warn you that it will restart the PI Analysis service as well.
15. Close and reopen Buffering Manager. The status indicator should be green if you have
configured buffering correctly.

27 | P a g e
5. PI Point Management

5.1 Hands-On: Creating Points for Interfaces

This is a hands-on chapter. It is recommend that you watch the video for this
chapter and follow the steps using your own virtual environment:
https://youtu.be/n89Acel0Q40. Below are the configuration steps performed in
Video the video.

References for this video:

• In this video we cover creating our first point that will be loaded on our OPC
Interface instance. All point attribute configuration for the OPC Interface is detailed
here.
• When using other interfaces, check the documentation for appropriate PI Point
configuration. All interfaces have a similar point attribute configuration section in
their documentation.
Below is a step-by-step walkthrough on changes that are made to our virtual environment
during this lesson:
Part 1: Create a Point
1. Connect to PISRV01
2. Open PI System Management Tools (SMT) from the Start menu
3. Navigate to Points → Point Builder
4. Fill in the following attributes, on their corresponding tabs:
o General
▪ Name: pump1.bearingtemp
▪ Descriptor: Bearing Temperature of Pump 1
▪ Point Source: OPC
▪ Eng Units: degc
o Classic
▪ Location 1: 1
▪ Location 2: 0
▪ Location 3: 1
▪ Location 4: 1
▪ Location 5: 0
▪ Instrument Tag: Sample Process/Pump1/BearingTemp

28 | P a g e
 PI System Administration: Basics

o Security
▪ Data Security → Add... → SVC-PIINT → Check both the Read and
Write boxes
5. Click Save in the top left
6. Wait for at least 2 minutes
Part 2: Confirm the new tag is receiving new data
1. On PISRV01 inside SMT, navigate to Data → Current Values
2. Click the Tag Search in the top left corner
3. Enter a Point Source of opc
4. Click Search
5. Click Select All
6. Click OK
7. Click the play ► button at the top of the window to start updating values
8. Ensure your tag's value changes every few seconds

5.2 Background: Explore PI Points and Interfaces

This is a background chapter with video content only. It is recommend that you
watch the video for this chapter: https://youtu.be/Yleu86Y3SH4.
Video

5.3 Background: Compression and Exception

This is a background chapter with video content only. It is recommend that you
watch the video for this chapter: https://youtu.be/6-scv3oQ7Kk.
Video

Exception and Compression for points is controlled on a point-by-point basis. The Excdev,
Excmax, Compdev and Compmax explained in the video are in the "archive" tab on Point
Builder in PI System Management Tools. Go ahead and look at the settings on the points you
already have set up.
For more details on how Exception and Compression works, see the full details video.

5.4 Reference: The Interface User Manual

Every PI System component, including Interfaces, has a corresponding User manual.
Documentation for the most common interfaces and connectors can be found on OSIsoft Live
Library, under the "Interfaces and Connectors" subheading (you may need to click the "+ View

29 | P a g e
More" button below to see the whole list). In this class we're using the PI Interface for OPC DA,
who's documentation can be found here.
As a PI System Administrator, you'll become very familiar with the documentation for the
interfaces your organisation uses. The most common places you'll refer to are the sections for
PI Point Configuration. We recommend reading through some of this section now and growing
accustomed to it, now you know the basics of creating points in the PI Data Archive. Every
interface has a similar section, and most interfaces have different requirements when it comes
to point configuration - you'll need to read this section of the documentation each time you're
configuring a new interface type.

5.5 Knowledge Check: Creating Digital Points

5.5.1 Introduction to Digital Points

When creating a PI Point, you must specify a Point Type. So far we've only used the default float32 point
type, which allows a point to store single-precision floating-point numbers. The PI Data Archive also
allows you to store a few other types of data, most notably digital data.

5.5.2 Digital State Sets

PI Points of type Digital are used to store data values that have discrete states exemplified above.
Example of typical states are Open/Closed for a valve or On/Off for a switch. While the user is interested
in the actual state, PI Data Archive stores this information as an integer. This integer is then associated
with a Digital State Set; a grouping of these states. Whenever the value is requested, PI Data Archive

30 | P a g e
 PI System Administration: Basics

retrieves the integer value, does a lookup in the Digital State Set, and then presents the associated text
value.

Digital Sets are kept in a common table for all points of type Digital to access. The Digital State Set must
exist prior to the creation of the digital point. When defining a point use the DigitalSet attribute to store
the associated Digital Set name. The digital states are case preserving, but not case sensitive, so you can
refer to them with upper and lower case, but any display will show the configured upper or lower case.
There is a large default set called System that contains system error messages and other information. All
points, including non-digital points, can receive and archive a state from the System digital states set
(Shutdown, PtCreated, Over Range, Under Range, I/O Timeout, etc.).

Warning: Do not edit the SYSTEM set on your PI System!

5.5.3 Exercise: Create a Digital State Set and Point

One of the tags on our OPC Server is a digital tag. It has an itemID of Sample Process/Pump1/Status.
The tag sends through integers 0 through 4, and you've asked the operations team what these numbers
correspond with. You'd like your users to see the name of the state rather than just the number when
they're looking at the tag's value in the system.

State Name State Number

Off 0

Startup 1

Running 2

Warning 3

Error 5

We'd like to create a point to archive this controller’s mode of operation. However, in order to build the
point, you will first need a digital state set.

1. On PISRV01 open the PI SMT and navigate to Points → Digital States plug-in.

2. Create new Digital State Set called PumpStatus.

3. Fill the State Names according the table above.

4. Save it and restart PI SMT. We need to do this for the Point Builder to pick up the new state set.

5. Navigate to Points → Point Builder plug-in.

6. Create a new point with the following attributes:

o General Tab: Name: pump1.status; Description: Status of Pump 1; Point Source: OPC;
Point Type: Digital; Digital Set: PumpStatus

31 | P a g e
 o Classic Tab: Location 1: 1; Location 3: 1; Location 4: 1; Instrument Tag: Sample
Process/Pump1/Status

o Security Tab: Add the SVC-PIINT identity to Data Security, and give it Read/Write
permission

7. Save the configured PI Point.

8. Wait for the PI Interface to start collecting data for the new point.

9. Check the updates in Data → Current Values.

5.6 Knowledge Check: Confirming Interface Operation

You should now have a working interface. This exercise will guide you through some
checks to confirm its operation.

5.6.1 Part 1: Check that you are receiving data for all points belonging to the interface
in the PI Data Archive

You should now have a working interface. This exercise will guide you through some checks to
confirm its operation.

Part 1: Check that you are receiving data for all points belonging to the interface in the PI Data
Archive

1. Connect to PISRV01
2. Open PI System Management Tools (SMT)
3. Navigate to Data > Current Values
4. Search for all points that share a point source with your interface, and add them to the
list of tags in the Current Values plugin
5. Ensure all points have recent timestamps (note that the virtual environment is in UTC,
and may have a different timezone to your own), and click the Start Updating button.
You should see new values come through every now and again.

5.6.2 Part 2: Check that data is flowing through the buffer

Note: It is possible for an interface to be sending data to the PI Data archive without it travelling
through the buffer - but this is not what we want. Follow these steps to ensure that your data is
being properly buffered by the PI Buffer Subsystem before being sent on to the PI Data Archive

1. Connect to PIINT01
2. Open the PI Interface Configuration Utility (ICU)
3. Navigate to Tools > Buffering

32 | P a g e
 PI System Administration: Basics

4. Ensure that the X total events sent is greater than zero, and you are getting a non-zero
number of events per second. The number of total events sent should be increasing
over time.
5. Ensure that the X events in queue settles at around zero events. Every now and again it
may increase to a number greater than zero, then settle down again. You can use these
numbers to diagnose issues. If the X events in queue number is going up, it means that
the buffer is having trouble connecting to the PI Data Archive or does not have
adequate bandwidth to send all the data it needs to. If the X total events sent number
is not increasing, it means that the interfaces on this machine are not generating and/or
sending data through - this is most likely a problem with the interface configuration and
the interface message log should point you in the right direction.

5.7 Hands-On: Creating Points in Bulk

This is a hands-on chapter. It is recommend that you watch the video for this
chapter and follow the steps using your own virtual environment:
https://youtu.be/XJwH_WZgob0. Below are the configuration steps performed in
Video the video.
Note: When opening Excel for the first time, you may be asked if you want to install the PI
Builder Plugin. If you are, select Install. If you still do not see the PI Builder ribbon when you
open a new workbook, you can enable it by doing the following:
1. Click the File ribbon in the top left corner of the window
2. Click Options
3. Select the Add-Ins option in the left sidebar
4. Change the drop-down select menu, Manage: COM Add-ins
5. Click Go...
6. Check the box next to PIAFBuilder
7. Click OK
8. You should now see the PI Builder ribbon at the top of the window
During this exercise, we connect to PISRV01 and modify the spreadsheet "C:\Class
Documents\Exercise Files\tag export from DCS.xlsx". To skip the work done in this video and
go straight to the solution, you can do the following:
1. Connect to PISRV01
2. Open C:\Class Documents\Exercise Files\Solution\Pump Current Point Creation
Solution.xlsx
3. Select the PI Builder ribbon
4. Ensure the Data Server in the top left is PISRV01
5. Click the Publish button
6. Select Create and Edit in the select box

33 | P a g e
 7. Click OK
8. If you receive any errors about digital state sets, see the previous lesson Creating
Digital Points.
(In the video we specifically say NOT to use create and edit mode. This is specifically aimed
at those modifying production systems. In this case, because we're applying a solution, it
doesn't matter much and we do want to overwrite all current configuration)

5.8 Knowledge Check: The PI Data Archive Message Log

A very important part of troubleshooting and configuring a PI System is becoming familiar with
the message logs on both the PI Data Archive and your Interface machines.

5.8.1 Exercise - Explore the PI Data Archive Message Log

1. Connect to PISRV01
2. Open PI System Management Tools{ (SMT) and navigate to Operation > Message Log
3. Click the Retrieve Messages button in the top left. It is shaped like a magnifying glass. If
no messages are returned, you may need to modify the "End:" entry and search for
messages over a larger time range.

4. Scroll through the log, and modify the start and end times where needed. Try to find
messages similar to the following:

[Server] PISRV01 [ID] 7082 [Time] 10/16/2020 2:59:19 AM [Program] pinetmgr [Priority] 10
[ProcessOSUser] pinetmgr [ProcessID] 3252 [Severity] Debug
Successful login ID: 16. Address: . Name: SMTHost.exe. Identity List: piadmins | PIWorld. Environment
Username : PISCHOOL\student01. Method: Windows Login (SSPI,NTLM,HMAC-MD5,RSADSI RC4,128)

This message indicates that a successful connection was made from SMThost.exe (the
name for the PI System Management Tools application), by PISCHOOL\student01 (the
Windows account we are logged in with). This is the confirmation message that
appeared in the log just now when we opened up SMT and connected. Every connection
attempt is logged in the PI Server message log. This makes it an incredibly useful tool for

34 | P a g e
 PI System Administration: Basics

troubleshooting security problems. In the next few steps, we're going to create own
security problem and see what the log files look like throughout.

5. In SMT, navigate to Security > Mappings & Trusts.

6. Double click on the mapping for SVC-PIINT, check the box next to Mapping is disabled
and click ok.
7. On PIINT01, open the PI ICU and open a scrolling log with the View current PI Message
log continuously button. [Note: The Message log on an interface machine can also be
viewed and searched with an installed application called PI SDK Utility, available on the
Windows Start menu]
8. Open Windows Services, and restart the PI Buffer Subsystem service. Select Yes to the
prompt asking if you want to also restart your interface.
9. You should see an error message in your scrolling log similar to the following:

E 16-Oct-20 03:14:22 pibufss:pibufmgr<PISRV01> (2102)

>> Error connecting to server PISRV01:5450, [-10431] Authentication method is disabled by current
server policy
Attempt 1: [SSPI], [-10407] No Access - Secure Object, details: none
Attempt 2: [TRUST], [-10431] Authentication method is disabled by current server policy, details: none

This error indicates that the buffer attempted to connect to the Data Archive, but it was
not allowed in. A good rule of thumb is that if you see any error in a log with an error
code in the form 104XX - you should check your mappings and trusts, and make sure
that the account has the required privileges.

10. On PISRV01, in SMT, navigate back to the Message Logs and click Retrieve Messages.
Try to find some messages like the following:

[Server] PISRV01 [ID] 7138 [Time] 10/16/2020 3:20:22 AM [Program] pinetmgr [Priority] 10
[ProcessOSUser] pinetmgr [ProcessID] 3252 [Severity] Information
Unsuccessful login ID: 28. Address: 192.168.0.22. Name: pibufss(5348):remote. Credentials used:
PISCHOOL\SVC-PIINT$. Method: Windows Login (SSPI,Kerberos,HMAC-SHA1-96,Kerberos AES256-CTS-
HMAC-SHA1-96,256). Error: [-10433] No identity mapping for this request

[Server] PISRV01 [ID] 7138 [Time] 10/16/2020 3:20:22 AM [Program] pinetmgr [Priority] 10
[ProcessOSUser] pinetmgr [ProcessID] 3252 [Severity] Information
Unsuccessful login ID: 28. Address: 192.168.0.22. Name: pibufss(5348):remote. Credentials used:
PISCHOOL\SVC-PIINT$. Method: Trust. Error: [-10431] Authentication method is disabled by current
server policy

These messages indicate that the buffer attempted to authenticate to the data archive
using a Mapping, then a legacy Trust. Both have failed.

11. On PISRV01, in SMT, navigate back to Mappings & Trusts and re-enable your mapping.
Before clicking OK, change its PI Identity to piusers. This will make your interface be
given the piusers identity instead of the SVC-PIINT identity.

35 | P a g e
 12. On PIINT01, restart the PI Buffer Subsystem service
13. Check your scrolling log. You should see a lot of errors similar to the following:

E 16-Oct-20 03:29:14 pibufss:pibufmgr<PISRV01> (2111)

>> Error -10401 encountered while posting to point ID 28.
event time: 16-Oct-20 03:28:55.24400, value: 103.08, mode: precomp_arc.

This error indicates that the buffer service cannot write to this point because it doesn't
have permission to. By default the piusers identity doesn't have write access to tags,
only read access. Note the 10401 error code. If we got this error in a production system,
we'd go straight for the security tabs to check configuration to try to clear this error.

14. Check your PI Server message log again, and click Retrieve messages. You should see
this message:

[Server] PISRV01 [ID] 7082 [Time] 10/16/2020 3:28:54 AM [Program] pinetmgr [Priority] 10
[ProcessOSUser] pinetmgr [ProcessID] 3252 [Severity] Debug
Successful login ID: 34. Address: 192.168.0.22. Name: pibufss(944):remote. Identity List: piusers |
PIWorld. Environment Username : PISCHOOL\SVC-PIINT$. Method: Windows Login (SSPI,Kerberos,HMAC-
SHA1-96,Kerberos AES256-CTS-HMAC-SHA1-96,256)

Our buffer subsystem has connected with the identity "piusers". When troubleshooting,
we use both the logs on the Interface, and on the PI Data Archive to identify the
problem here. We see that the interface is connecting as the identity "piusers", and it is

36 | P a g e
 PI System Administration: Basics

having trouble writing to the interface's points. We can conclude that the "piusers"
identity doesn't have permission to write to the points.

15. On PISRV01, in SMT, navigate back to Mappings & Trusts and change the mapping's PI
Identity back to SVC-PIINT.
16. On PIINT01, restart the PI Buffer Subsystem service.
17. Check message logs on both the interface and the Data Archive. All errors should now
be cleared.

When going through the rest of this class, we recommend coming back to the PI Data Archive
message log and taking a look at the messages every now and then. When newly installed and
configured services connect, and when troubleshooting any issues you face, you'll find a wealth
of information in this log.

5.9 Knowledge Check: Creating More Points

Right after we created our points in bulk - one of your engineers called you and ask you to
also add another tag for pump input current. They've helpfully given you a DCS export for
the current tags for your pumps, but it's in a different format to the last one they gave you!

5.9.1 Exercise - Create Points for Pump Current

1. Connect to PISRV01
2. Open the Exercises folder on the desktop, and navigate to the spreadsheet called
"currenttags.csv".
3. Edit the file in Microsoft Excel so PI Builder can export the tags to the PI Data
Archive, then export them.
4. Use the Current Values plugin in PI SMT to ensure you're seeing new data come in
to the PI Data Archive for your new tags for pump current.

5.9.2 Exercise Solution

A solution spreadsheet can be found inside the Exercises folder on your virtual environment.
To skip this exercise and simply apply the solution, do the following:
1. Connect to PISRV01
2. Open C:\Class Documents\Exercise Files\Solution\Bulk Point Creation
Solution.xlsx
3. Select the PI Builder ribbon
4. Ensure the Data Server in the top left is PISRV01
5. Click the Publish button
6. Select Create

37 | P a g e
 7. Click OK

38 | P a g e
 PI System Administration: Basics

6. Improving Interface Reliability

6.1 Background: Interface Redundancy

This is a hands-on chapter. It is recommend that you watch the video for this
chapter and follow the steps using your own virtual environment:
https://youtu.be/atAFzUHx9jg. Below are the configuration steps performed in
Video the video.
References used in this video:
• For different failover scenarios and how the interface reacts, see this chapter in the
documentation.

6.2 Knowledge Check: Preparing a Second PI Interface

We're about to set up two interfaces to be a redundant pair. But before we do that - we have to
have a second interface machine, with exactly the same configuration as the first.

6.2.1 Exercise: Configure an OPC Interface on PIINT02

We'll need our PIINT02 configured in exactly the same way as our PIINT01. Follow the steps
below. You may need to refer to earlier lessons in this course if you don't remember the exact
steps. The "PI Interface Configuration" lesson earlier in the course covers steps 2 through 4 of
this exercise.

1. To save time, the PI Interface for OPC DA, the Interface Configuration Utility (ICU) and the PI API
for Windows Integrated Security are already installed on PIINT02 - there's no need to run the
installers, and no need to juggle while you wait for the install to complete. Open the ICU and
move to the next step.
2. Configure an OPC Interface Instance on PIINT02, using the same settings as on PIINT01. Do not
start the interface yet.
3. Configure Buffering on PIINT02.
4. Configure the interface instance and the PI Buffer Subsystem to run under the SVC-PIINT
account, and give the account appropriate permissions to run the buffer.
5. Connect to PIINT01 and turn off the interface with the stop button on the ICU.
6. Start the new interface instance on PIINT02. Ensure you are getting updated data by viewing the
interface's points in PI System Management Tools.

Once you have data flowing, you're ready for the next lesson.

39 | P a g e
6.3 Hands-On: Configure UNIINT Failover
This is a hands-on chapter. It is recommend that you watch the video for this
chapter and follow the steps using your own virtual environment:
https://youtu.be/hranir0BEM4. Below are the configuration steps performed in
Video the video.
Below is a step-by-step walkthrough on changes that are made to our virtual environment
during this lesson:

6.3.1 Part 1: Prepare the shared folder

1. Connect to PIINT02
2. Open Windows File Explorer using the shortcut on the taskbar
3. Navigate to D:
4. Right click in the white space and create a new folder called Interface Failover
5. On your new folder, Right click → Properties
6. Select the Sharing tab
7. Click Advanced Sharing
8. Check Share this folder
9. Click the Permissions button
10. Click the Add... button
11. Click the Object Types button
12. Check Service Accounts
13. Click OK
14. Enter the object name SVC-PIINT$ and click Check Names
15. Click OK
16. Check the Full Control → Allow checkbox
17. Click OK

6.3.2 Part 2: Configure failover on one interface

1. On PIINT02, Open the PI Interface Configuration Utility (ICU)

2. Select the interface instance opcint_ReadOnly1 -> PISRV01 from the Interface drop-
down select box
3. Select the UniInt → Failover menu on the left side of the window
4. Check the Enable UniInt Failover checkbox
5. Enter the following numbers:
o Failover ID# for this instance: 2

40 | P a g e
 PI System Administration: Basics

o Failover ID# of the other instance: 1

6. Click the Browse button next to Failover ID# of the other instance
7. Select PIINT01 → opcint_ReadOnly1
8. Click OK
9. Under UFO Type: select HOT
10. Right click on one of the tags in the table below and click Create UFO_State Digital
Set on Server PISRV01
11. Click OK
12. Right click on one of the tags in the table below and click Create all points (UFO
Phase 2)
13. Under Synchronization File Path: click the Browse button
14. In the address bar, enter \\PIINT02\Interface Failover
15. Click Open
16. Click Apply in the bottom right
17. Click OK
18. Restart the interface with the restart button at the top of the window

6.3.3 Part 3: Fix security for UFO status tags

1. On PISRV01, open a new blank workbook in Microsoft Excel

2. Select the PI Builder Ribbon
3. Ensure you have PISRV01 selected as the Data Server in the top left
4. Click PI Points → Find PI Points
5. Enter a search of *ufo* and click Search
6. Click OK
7. Click Clear All
8. Select the checkbox Security → datasecurity
9. Add the string " | SVC-PIINT: A(r,w)" to each row in the datasecurity column
10. Click Publish
11. Select Edit Only
12. Click OK

6.3.4 Part 4: Configure failover on the second interface

1. On PIINT01, open the ICU

41 | P a g e
 2. Select the interface instance opcint_ReadOnly1 -> PISRV01 from the Interface drop-
down select box
3. Select the UniInt → Failover menu on the left side of the window
4. Check the Enable UniInt Failover checkbox
5. Enter the following numbers: [NOTE: THESE ARE OPPOSITE TO THE NUMBERS IN
PART 2]
o Failover ID# for this instance: 1
o Failover ID# of the other instance: 2
6. Click the Browse button next to Failover ID# of the other instance
7. Select PIINT02 → opcint_ReadOnly1
8. Click OK
9. Under UFO Type: select HOT
10. Right click on one of the tags in the table below and click Create UFO_State Digital
Set on Server PISRV01
11. Click OK
12. Right click on one of the tags in the table below and click Create all points (UFO
Phase 2)
13. Under Synchronization File Path: click the Browse button
14. In the address bar, enter \\PIINT02\Interface Failover [NOTE: THIS IS THE SAME
LOCATION AS THAT CONFIGURED IN PART 2]
15. Click Open
16. Click Apply in the bottom right
17. Click OK
18. Restart the interface with the restart button at the top of the window

6.3.5 Part 5: Configure Disconnected Startup

1. On PIINT02, open the ICU

2. Select the UniInt → Disconnected Startup menu on the left side of the window
3. Check the box for Enable disconnected startup (with point caching)
4. Next to Cache Path: click Browse
5. Click OK
6. Click Apply
7. Start or restart the interface with the buttons at the top of the window
8. Repeat steps 1 through 7 with PIINT01

42 | P a g e
 PI System Administration: Basics

6.4 Knowledge Check: Interface Health Points

6.4.1 UniInt Health Points

UniInt Health Points are PI Points that collect information about the health of the interface.
They are created from the PI ICU, in the UniInt > Health Points section:

OSIsoft recommends that, at minimum, the following UniInt Health Points be created:
1. Heartbeat: This PI Point indicates whether or not the interface is running. The
heartbeat point is updated continuously unless the interface is shut down or in a
deadlock situation. As long as the interface is running, the value of the point cycles
incrementally from 1 to 15. The heartbeat point does not indicate whether the
interface is connected to or collecting data from a data source.
2. Device Status: This PI Point contains information about communication between
the interface and the data source. During normal operation, it contains the value
GOOD, indicating that the interface is communicating properly with the data source.
Otherwise, the point contains a string indicating status, formatted as follows:

43 | P a g e
 Status code | Description | Interface-specific text.

Example:
95 | Device(s) in error
This device status means that the PI Interface cannot communicate with the data
source.
3. IO Rate: This PI Point keeps a count of all point values (inputs, outputs, triggered
inputs) being sent to the Data Archive. If the value stops updating, the interface has
stopped collecting data.
4. Scan Class Scans Skipped: This PI Point counts, for a specific scan class, “skipped
scans”, i.e the number of scans that were not performed before the scan time
elapsed and the next scheduled scan was executed, for a defined reporting period (8
hours by default)

6.4.2 Exercise - Create UniInt health points for both of your Interface instances

1. On PIINT01, run PI ICU and browse to UniInt → Health Points

2. Right-click on the following Health Points and select Create:
o Heartbeat
o Device Status
o IORate
o Scan Class Scans Skipped.sc0
3. On PISRV01, using SMT, verify whether these Health Points are receiving data using
the Current Values plugin. If they are not receiving data, correct the problem, then
restart the interface. You may need to look in the interface message log for clues. If
you can't find and correct the problem, see "Health Points Solution.pdf" attached
to this lesson.
4. Repeat the above steps for the interface instance on PIINT02

44 | P a g e
 PI System Administration: Basics

7. Managing User Access

7.1 Hands-On: Data Archive Security

This is a hands-on chapter. It is recommend that you watch the video for this
chapter and follow the steps using your own virtual environment:
https://youtu.be/0oMVa5NgjQY. Below are the configuration steps performed in
Video the video.
References
• Full documentation on Data Archive security can be found here.
Below is a step-by-step walkthrough on changes that are made to our virtual environment
during this lesson:
Part 1: Configure security for PI Administrators
1. On PISRV01, open PI System Management Tools (SMT)
2. Navigate to Security → Mappings & Trusts
3. Click the New... button in the top left of the window
4. Enter Windows Account: PISCHOOL\PI Administrators
5. Enter PI Identity: piadmins
6. Click Create
Part 2: Configure security for PI Interfaces
1. On PISRV01, open SMT and navigate to Security → Identities, Users & Groups
2. Double click on SVC-PIINT
3. Change its name to PI Interfaces
4. Navigate to Security → Mappings & Trusts
5. Click the New... button in the top left of the window
6. Enter Windows Account: PISCHOOL\PI Interfaces
7. Enter PI Identity: PI Interfaces
8. Click Create
Part 3: Configure security for PI Users
1. On PISRV01, open SMT and navigate to Security → Identities, Users & Groups
2. Click the New... button in the top left of the window
3. Enter the Name: PI Users
4. Click Create
5. Navigate to Security → Mappings & Trusts

45 | P a g e
 6. Click the New... button in the top left of the window
7. Enter Windows Account: PISCHOOL\PI Users
8. Enter PI Identity: PI Users
9. Click Create
Part 4: Configure security for PI Point and Analysis Creators
1. On PISRV01, open SMT and navigate to Security → Identities, Users & Groups
2. Click the New... button in the top left of the window
3. Enter the Name: PI Point and Analysis Creators
4. Click Create
5. Navigate to Security → Mappings & Trusts
6. Click the New... button in the top left of the window
7. Enter Windows Account: PISCHOOL\PI Point and Analysis Creators
8. Enter PI Identity: PI Point and Analysis Creators
9. Navigate to Security → Database Security
10. Double click on PIPOINT
11. Click Add...
12. Select PI Point and Analysis Creators
13. Click Add
14. Click OK
15. Check the Write checkbox
16. Click OK
Part 5: Clean up unneeded identities
1. On PISRV01, open SMT and navigate to Security → Identities, Users & Groups
2. Right click → delete the following identities:
o PIEngineers
o PIOperators
o PISupervisors

7.2 Background: What is Asset Framework?

This is a background chapter with video content only. It is recommend that you
watch the video for this chapter: https://youtu.be/VWrxS48PpjY.
Video

46 | P a g e
 PI System Administration: Basics

This video provides some background if you are not familiar with Asset Framework. The next
lesson will go into how data flow works between Asset Framework and Data Archive, and
security on Asset Framework objects.

7.3 Hands-On: Asset Framework Security

This is a hands-on chapter. It is recommend that you watch the video for this
chapter and follow the steps using your own virtual environment:
https://youtu.be/oQHBhSzRI0E. Below are the configuration steps performed in
Video the video.
References
• Full documentation for Asset Framework security can be found here.
Note: This video assumes that all "Power Users" in your organisation belong to both the PI
Users and PI Power Users active directory groups. If this is not the case, some extra
configuration is needed to allow the Power Users to connect to the server at the top level.
For directions on these steps, see the next exercise.
Below is a step-by-step walkthrough on changes that are made to our virtual environment
during this lesson:

7.3.1 Part 1: Prepare Production and Development AF Databases

1. Connect to PISRV01
2. From the Windows Start Menu, open PI System Explorer
At this point, depending on what configuration you've done so far, you may be asked "There
are no PI AF Servers defined. Do you want to define one?" If you are, click Yes, then enter
PISRV02 as the host, and click OK.

If you get an error popup saying "Could not connect to net.tcp://pisrv01:5457...", this
indicates that your PISRV01 thinks that it has an AF server installed on it - which it doesn't.
To fix this and instead point at the AF server installed on PISRV02, click OK, wait for the
connection to time out, then click Select. Click the ... ellipsis next to the PISRV01 dropdown
menu, right click on PISRV01, select Properties, rename the Host to PISRV02, and click OK,
then OK, then Connect.
3. Click the Database button in the top left of the window
4. Right click on Database1 and rename it to Production (or if you don't have
Database1, click New Database and create a new one called Production)
5. Click the New Database button in the top left of the window
6. Name the new database Development
7. Click OK

47 | P a g e
7.3.2 Part 2: Configure security for PI Administrators

1. Connect to PISRV01, open PI System Explorer, and click the Database button in the
top left of the window
2. Click the small Show Properties button next to the greyed out Connect button
3. Select the Mappings tab
4. In the white space below the list of mappings Right Click → New Mapping
5. Type Account: PISCHOOL\PI Administrators
6. Select Identity: Administrators
7. Click OK
8. On the BUILTIN\Administrators mapping Right Click → Delete
9. Click OK

7.3.3 Part 3: Configure security for PI Users

1. Ensure you have the Mappings tab open in the PI AF Server Properties window
2. In the white space below the list of mappings Right Click → New Mapping
3. Type Account: PISCHOOL\PI Users
4. Select Identity: World
5. Click OK
6. On the Everyone mapping Right Click → Delete
7. Click OK

7.3.4 Part 4: Configure security for PI Power Users

1. Ensure you have the Identities tab open in the PI AF Server Properties window
2. In the white space below the list of identities Right Click → New Identity
3. Type Name: Power Users
4. Click the Mappings tab
5. Click Add...
6. Type Account: PISCHOOL\PI Power Users
7. Click OK
8. Click OK to leave the PI AF Server Properties window completely and return to the
Select Database window
9. On the Development database, Right Click → Security
10. Click Add...
11. Select Power Users

48 | P a g e
 PI System Administration: Basics

12. Click OK
13. Click OK to return to the Select Database window

7.4 Knowledge Check: Contractor Access

A common scenario that requires a more complex security setup is when you have a group
of contractors who need limited access to the system. where you may want to give
employees and contractors different access to the PI System. In this exercise you will
configure a model like this for your system, then test the configuration to make sure
contractors don't have access to data that they shouldn't be able to see. For a full step-by-
step solution to this exercise, see the attached "Contractor Security Solution.pdf" to the
online version of this lesson.

7.4.1 Part 1: Prepare your Data Archive and Asset Framework

• Create an identity for PI Contractors on both the Data Archive using System
Management Tools (SMT), and Contractors on the Asset Framework server using PI
System Explorer (PSE). For a step-by-step on how to do this, see the respective
lessons on Data Archive security and Asset Framework security.
• Create a mapping to the new identity for the group PI Contractors on both the Data
Archive and Asset Framework.
• On the Asset Framework Server, there is one extra configuration step that needs to
be completed to allow the contractors to connect to the server at the top level. Just
because a user has permission to see a database, it doesn't mean they're allowed to
connect to the server itself. The Contractors are not members of the PI Users active
directory group and will not be allowed in under the World identity we set up in the
previous lesson. Unlike the PI Data Archive, the World identity isn't given to all
authenticated connections automatically.
1. Connect to PISRV01, open PI System Explorer, and click the Database
button in the top left of the window
2. Click the Edit Security button at the top of the Select Database window.
This allows you to edit permissions to the server at the top level.
3. Click Add...
4. Select Contractors
5. Uncheck all Allow boxes except for Read and Read Data. This will modify all
permissions on the server, allowing contractors to connect and see all
objects. This is fine for now, don't worry - we're going to lock it down in the
next part of this exercise.
6. Click OK

49 | P a g e
7.4.2 Part 2: Satisfying a new management request

Management at our company has decided that the Status points for our pumps contain
confidential business information, It is important that our contractors cannot see these
points. In a previous exercise, we named these points with the convention PumpX.Status,
where X is the number of the pump.
• Configure the security on the Status tags so that the contractors cannot read their
data, or even see that they exist.

7.4.3 Part 3: Satisfying another management request

You've been asked to prepare a new database on Asset Framework, hosting data for Remote
Assets. The contractors have been hired to manage these assets, but as they are not
employees they are not permitted to see the Production or Development databases.
• Use PSE to create an additional database called Remote Assets, and allow your
contractors to view it, but not write to it.
• Configure the security for each of your other databases to block access to your
contractors completely.

7.4.4 Part 4: Check if your changes worked

1. Open extra copies of SMT and PSE as a contractor to check their access. To open
them as a contractor, follow these steps:
1. Right click on the application on your windows Taskbar
2. Hold the Shift key and right click on the name of the application
3. Select Run as different user
4. We'll run these applications as student04, who is in the domain group "PI
Contractors". For the credentials, enter:
▪ User: PISCHOOL\student04
▪ Password: *enter the password that was emailed to you after you
originally created your virtual machines
5. Test searching for any status tag using SMT, or opening any database apart
from the Contractor database in PSE
6. Test again using PISCHOOL\student02, who is a member of the PI Users
group. You should be able to connect to both the Data Archive and AF
Servers, but not make any changes.

50 | P a g e
 PI System Administration: Basics

8. Managing Data

8.1 Background: What are Archive Files?

This is a background chapter with video content only. It is recommend that you
watch the video for this chapter: https://youtu.be/zBN5m5JM2Es.
Video

This video was originally published in the playlist "Manage Archive Files & Check Archiving
Health". You can find the full playlist here.

8.2 Knowledge Check: PI Archives in Depth

In this lesson we'll take a look at the archives in our Data Archive. Take a look at the Archives
in your system by doing the following:
1. Connect to PISRV01 and open PI System Management Tools (SMT)
2. Navigate to Operation → Archives
You should see all archive files that are registered on your PI Data Archive. It's looking pretty
sad right now - you only have a single file. The archive's start time is about the time you
installed your Data Archive server, and the end time is "Current Time". Because the end
time is the "Current Time", we call this archive the Primary Archive - it is being written to
with data coming in live from your interface. You should also see a very small number in the
%Full column. When the archive gets almost full, a new archive is automatically created, and
we shift into it. When this happens, the end time of the previous archive is set to the time of
the shift. Let's simulate this now.
3. Right click in the white space underneath your archive and click Force shift
After waiting a few seconds, you now see two archive files:

One of them is your new primary archive. If data is written to the Data Archive server with a
timestamp within the old archive's time range, it is written to the old one. If data comes in
within the new time range, it is written to the new one.
A small warning - the action we performed - Force shift - isn't something you need to do
often. In fact, you should never perform a Force Shift if you suspect something is wrong
with your system. It hardly ever fixes any issues, and almost always causes more problems if
your system is already in trouble.
Before the PI Data Archive to write to an archive file, it must be registered. Windows won't
let us move an archive file while it's registered - if you try you'll get an error saying "This

51 | P a g e
action can't be completed because the file is open in PI Archive Subsystem". Let's say we'd
like to move an archive file from one drive to another. We'd need to unregister the archive,
move it with Windows File Manager, then register it again. This will only work if the PI
Archive Subsystem is allowed to access the folder we move it into.

8.2.1 Exercise: Move old archives to a different drive

It is common to have two (or more) devices or drives hosting your archive files. You may
want your recent archives on high performance storage, and your older archives on low
performance storage as they are accessed much less frequently. We'll set up an alternate
location to store archive files, then move an old archive into the folder. The new location
we'd like to host our older archives will be D:\PI\Archives. Usually this would be a
completely separate drive, one that doesn't have any other software installed on it - but
we're starting to run out of drives to use in our learning environment.
Part 1: Prepare the new archive folder
Before an archive can be registered, the PI Archive Subsystem service must have full control
permissions over that file location.
1. Open Windows File Explorer, and navigate to a new folder at the path D:\PI
2. Create a new folder called Archives
3. On your new Archives folder, Right Click → Properties
4. Go to the Security tab
5. Click Edit...
6. Click Add...
7. Click Locations...
8. Select PISRV01
9. Click OK
10. Enter the account name NT Service\piarchss
11. Click OK
12. Check the Full Control checkbox for Allow
13. Click OK
14. Click OK
Part 2: Move an old archive into the folder
1. Connect to PISRV01 and open PI System Management Tools (SMT)
2. Navigate to Operation → Archives
3. Take a note of the name of your old archive (the archive that does not have
"Current Time" as its End Time). You're going to move this file in a few steps, so try
to remember the last few numbers in its name. Once you think you can tell your two
archives apart, Right Click → Unregister Archive

52 | P a g e
 PI System Administration: Basics

4. Click Yes
5. Open Windows File Explorer
6. Navigate to E:\PI\arc
7. Select both the archive .arc file you unregistered, and its corresponding .arc.ann file.
The .ann file is an annotation file, and contains annotations to data contained in the
archive. whenever you move an archive file, you should always move both the
archive, and its annotations.
8. Move both files to the new D:\PI\Archives folder
9. Go back to SMT, and in the white space below your list of archives Right Click →
Register archive
10. Select the archive you moved to the D:\PI\Archives folder
11. Click Open
12. Your archive should appear back in the registry list, with the new path listed under
the Archive File column
If you're looking into automating this job, all of the above steps can be scripted with the
command line tool piartool. You can read about piartool here.

53 | P a g e
9. Final Exam

The final exam for this course is taken online. Please check the course listing online for more details.

54 | P a g e
Introduction to Developing with
the PI System

1
© 2020 OSIsoft, LLC. All rights reserved
OSIsoft, LLC
1600 Alvarado Street
San Leandro, CA 94577

All rights reserved. No part of this publication may be reproduced, stored in a

retrieval system, or transmitted, in any form or by any means, mechanical,
photocopying, recording, or otherwise, without the prior written permission of
OSIsoft, LLC.

OSIsoft, the OSIsoft logo and logotype, Managed PI, OSIsoft Advanced Services,
OSIsoft Cloud Services, OSIsoft Connected Services, OSIsoft EDS, PI ACE, PI
Advanced Computing Engine, PI AF SDK, PI API, PI Asset Framework, PI Audit
Viewer, PI Builder, PI Cloud Connect, PI Connectors, PI Data Archive, PI DataLink,
PI DataLink Server, PI Developers Club, PI Integrator for Business Analytics, PI
Interfaces, PI JDBC Driver, PI Manual Logger, PI Notifications, PI ODBC Driver, PI
OLEDB Enterprise, PI OLEDB Provider, PI OPC DA Server, PI OPC HDA Server, PI
ProcessBook, PI SDK, PI Server, PI Square, PI System, PI System Access, PI Vision,
PI Visualization Suite, PI Web API, PI WebParts, PI Web Services, RLINK and
RtReports are all trademarks of OSIsoft, LLC.

All other trademarks or trade names used herein are the property of their
respective owners.

U.S. GOVERNMENT RIGHTS

Use, duplication or disclosure by the US Government is subject to restrictions set

forth in the OSIsoft, LLC license agreement and/or as provided in DFARS 227.7202,
DFARS 252.227-7013, FAR 12-212, FAR 52.227-19, or their successors, as
applicable.

No part of this publication may be reproduced, stored in a retrieval system, or

transmitted, in any form or by any means, mechanical, photocopying, recording
or otherwise, without the written permission of OSIsoft, LLC.

2
© 2020 OSIsoft, LLC. All rights reserved
Contents
- About this course .............................................................................................................................. 5
About this course .................................................................................................................................. 5
By the end of this course you’ll… .......................................................................................................... 5
Audience ............................................................................................................................................... 5
This Course Includes... .......................................................................................................................... 5
Prerequisites ......................................................................................................................................... 6
Further information .............................................................................................................................. 6
- Lesson 1: Introduction to PI Developer Technologies ...................................................................... 7
Learning outcomes................................................................................................................................ 7
Introduction .......................................................................................................................................... 7
Quick comparison of Dev. Technologies ............................................................................................... 7
Detailed comparison of Developer Technologies ................................................................................. 8
Licensing................................................................................................................................................ 9
List of deprecated PI Developer Technologies...................................................................................... 9
OSIsoft Messaging Format .................................................................................................................. 10
Learn More.......................................................................................................................................... 11
- Lesson 2: AF SDK ............................................................................................................................. 12
Learning outcomes.............................................................................................................................. 12
Definition ............................................................................................................................................ 12
Installation and rationale .................................................................................................................... 12
Naming Conventions ........................................................................................................................... 13
Exercise - Search the AF SDK Reference ............................................................................................. 14
Learn More.......................................................................................................................................... 15
- Lesson 3: PI SQL Framework ........................................................................................................... 16
Learning outcomes.............................................................................................................................. 16
Introduction ........................................................................................................................................ 16
PI SQL Data Access Server (RTQP) ....................................................................................................... 17
Architecture ........................................................................................................................................ 18
PI SQL Client ........................................................................................................................................ 18
PI SQL Commander ............................................................................................................................. 19
Learn More.......................................................................................................................................... 19
- Lesson 4: PI Web API ....................................................................................................................... 20

3
© 2020 OSIsoft, LLC. All rights reserved
 Learning outcomes.............................................................................................................................. 20
Introduction ........................................................................................................................................ 20
PI Web API installation ........................................................................................................................ 21
Exercise - Explore PI Web API Reference ............................................................................................ 21
Using GitHub with PI ........................................................................................................................... 22
Learn More.......................................................................................................................................... 23
- Lesson 5: PI Integrators ................................................................................................................... 24
Learning outcomes.............................................................................................................................. 24
Introduction ........................................................................................................................................ 24
PI Integrator for Business Analytics .................................................................................................... 24
PI Integrator for Esri ArcGIS ................................................................................................................ 27
Learn More.......................................................................................................................................... 28
- Lesson 6: OCS and EDS .................................................................................................................... 30
Learning outcomes.............................................................................................................................. 30
OSIsoft Cloud Services (OCS)............................................................................................................... 30
Edge Data Store (EDS) ......................................................................................................................... 31
- Next Steps and FAQ ........................................................................................................................ 33
FAQ ...................................................................................................................................................... 33
Next steps ........................................................................................................................................... 33

4
© 2020 OSIsoft, LLC. All rights reserved
- About this course
About this course
Developer Technologies are designed to support the development of custom
applications on top of the PI System, as well as the integration of PI System data
with other applications and business systems. This course is designed for software
developers new to the PI System who desire programmatic access to it. You will
be introduced to various Developer Technologies that you can leverage in your
custom application to interact with the PI System. At the end of the lab, you will
walk away with knowledge of their basic capabilities and also know where to go if
you want to dive deeper into them.
We hope you enjoy the module and please don’t hesitate to get in touch with any
comments or feedback.

By the end of this course you’ll…

• Be able to make better decisions regarding the development of your
custom application
• Have become familiar with the different PI Developer technologies (AF SDK,
PI Web API, PI SQL Framework)
• Be able to describe the purpose of a PSA license and Application ID
• Have learnt more about PI Integrators, OSIsoft Cloud Services (OCS) and the
Edge Data Store (EDS)
• Be aware of available resources and how to access them

Audience
This course is designed for developers, systems integrators and systems architects
who are looking for an introduction on everything they need to develop solutions
on the PI System.
Level: Introductory
Study time: 2 hours

This Course Includes...

• Videos, discussion opportunities and quizzes to help you learn the material
• A sharable certificate of completion

5
© 2020 OSIsoft, LLC. All rights reserved
Prerequisites

• You can access our YouTube content.

• PDF Reader or equivalent is required to access the workbook and presentation
provided.

Further information

• Once you register for a course, you will have access to the course materials
24/7 on this website.
• This is a self-paced course. Any questions or assistance needed about the
material can be asked in this course's space in the OSIsoft PI Square
community
• When you complete the examination at the end of the course, you will receive
a certificate of completion which can be shared and directly posted on
LinkedIn.
• For more information about our Online Courses please visit our FAQ page

You can audit the full video lecture content right now on the OSIsoft Learning
YouTube Channel

6
© 2020 OSIsoft, LLC. All rights reserved
- Lesson 1: Introduction to PI Developer Technologies
Learning outcomes
After completing this lesson, you will:
• Be more familiar with the types of PI Developer Technologies and
understand the features and limitations of each.
• Be more knowledgeable on topics such as the PI System Access (PSA)
license and the OSIsoft message format.

Introduction
PI Developer Technologies are designed to support the development of custom
applications on top of the PI System, as well as the integration of PI System data
with other applications and business systems such as Microsoft Office or SQL
Server, Enterprise Resource Planning systems (ERPs), reporting and analytics
platforms, web portals, or geospatial and maintenance systems among other
things.
They cover a wide range of use cases in various environments, programming
languages, operating systems, and infrastructures. This course covers an
introduction to the different technologies in the family, including:
• AF SDK provides comprehensive, high performance, Windows based .NET
programmatic access to the PI System. Other technologies in the family might
use AF SDK calls internally.
• PI SQL Framework family of products exposes the data on a PI Server as if it were
on a relational database. Here, we will be focusing on PI SQL client and RTQP.
• PI Web API exposes a REST API, enabling operating system and device
independent programmatic access to the PI System.

Quick comparison of Dev. Technologies

In this section we provide a quick comparison of the advantages and limitations of
each of the Development Technologies.

• AF SDK
o Has the best performance of all PI Development Technologies.
o More methods and options available than any other Technology.

7
© 2020 OSIsoft, LLC. All rights reserved
 o Limited to Windows operating systems.
• PI SQL Framework
o Is compatible with other systems that use Structured Query Language
(SQL).
o Has limited methods and options available compared with AF SDK (for
example, setting security on assets and creating units of measure).
o Is limited to read-only PI AF access (but can create and write to tags on
your PI System).
• PI Web API
o Operating system and programming language agnostic.
o Limited methods and options available compared with AF SDK.
Detailed comparison of Developer Technologies

Name Type PI Data PI Asset Example Use

Archive? Framework?
PI AF SDK .NET based SDK RW RW Custom development
PI Web API RESTful web service RW RW Custom development, including mobile
and non-Windows REST clients
PI SQL Client Relational (SQL) – R* R SQL clients, Microsoft SQL Server Linked
(RTQP) OLEDB, JDBC, ODBC Server, Java clients on Windows and
Standards Linux
PI OLEDB Relational (SQL) – R* R SQL clients, Microsoft SQL Server Linked
Enterprise OLEDB Standard Server
PI OLEDB Relational (SQL) – RW - Same as PI OLEDB Enterprise
Provider OLEDB Standard
PI JDBC Driver Relational (SQL) – RW R Java clients on Windows and Linux
JDBC Standard
PI ODBC Driver Relational (SQL) – RW R ODBC clients on Windows
ODBC Standard
PI OPC DA OPC DA Standard RW - OPC clients on Windows
Server
PI OPC HDA OPC HDA Standard RW - OPC clients on Windows
Server

• R: Read access
• RW: Read and Write access
* through PI Point Data Reference Attributes

8
© 2020 OSIsoft, LLC. All rights reserved
You might also like to have a look at this presentation from the Developer Track at
the 2017 Users Conference in San Francisco: “How to Pick the Right PI Developer
Technology for Your Project”.

Licensing
PI Developer Technologies are freely available for download. However, this does
not mean that the PI Developer Technologies are license-free. You need a PI System
Access (PSA) license to deploy your applications. You might think of this as a run-
time license. The PSA runtime license enables end users to access PI System data,
including time series data in Data Archives and asset metadata in AF Servers, using
any of the PI Developer Technologies.
Therefore, PSA is a license required when deploying a non-OSIsoft software
program, application, or device that programmatically accesses data stored in the
PI Server or supporting servers. Programmatic access of PI System data is possible
through our Developer Technologies. Deprecated Developer Technologies may
require additional licensing.

• What are the terms of a PI System Access license? Please refer to the Usage and
Service Terms Content > Product Licensing > Product Usage Terms document
for the most up-to-date terms of the PSA license.
• Who should I contact regarding the PI System Access license? If you have
questions regarding licensing, contact your Customer Success Manager or
Account Manager.
For the latest information on the PI System Access license review this article on the
myOSIsoft customer portal.

List of deprecated PI Developer Technologies

PI SDK - The PI Software Development Kit (PI SDK) is a programming tool based on
Microsoft's Component Object Model (COM) used to access PI Servers. Data
Access Pack or PI System Access licenses are required to deploy custom PI SDK
applications.
PI API - The PI API Provides a common programmer interface to PI Data Archive
information, designed to span multiple hardware and software environments.

9
© 2020 OSIsoft, LLC. All rights reserved
Data Access Pack or PI System Access licenses are required to deploy custom PI
API applications.
PI Web Services - PI Web Services is a set of Simple Object Access Protocol (SOAP)
services that exposes time series data in the PI System. This product is
implemented using Microsoft Windows Communication Foundation (WCF). PI
System Access licenses are required to deploy custom PI Web Services
applications.
For a complete list, please visit the Developer Technologies website.

OSIsoft Messaging Format

PI Interfaces and PI Connectors can be used to access and read data from many
types of equipment and control systems. But what happens when you have a data
source for which no interface or connector exists? One solution is to write an
application that uses OMF to send the data to the PI System.
OMF enables you to send data into your PI System from sources that you would
not otherwise be able to send data from. Those sources could include different
platforms, different operating systems, and different devices - from server class
devices to headless devices running embedded operating systems. OMF allows
you to connect the pieces so that you have your data available, no matter where
it originated.
The OSIsoft Message Format (OMF) defines a set of message headers and bodies
that can be used to generate messages for ingestion into a compliant back-end
system. OMF can be used to develop data acquisition applications on platforms
and in languages for which there are no supported OSIsoft libraries.
OMF itself does not define or depend on any particular binary message protocol
(HTTP, AMQP, Kafka, etc.) It is instead based on an abstract message type, where
a message consists of a set of key / value pairs, called the headers, and a binary
payload, called the body. OMF messages can thus be constructed using any
message protocol that defines headers and bodies.
OMF messages fall into three categories:
• Type
• Container

10
© 2020 OSIsoft, LLC. All rights reserved
• Data

Within each category, three types of actions can be specified: Create, Update, and
Delete.
Each message bulks individual JSON objects into a JSON array. Within a given
array, all objects must be of the same message type: Type, Container, or Data.
To achieve optimal throughput, bulking and compression of messages is
recommended.
For more information:
• Live Library documentation – link
• OMF Docs - link
Learn More
• PI Developers club - link
o an online offering that provides resources for developing applications and
solutions on the PI System. PI DevClub can be considered the next version
of OSIsoft Virtual Campus and offers members-only and public features.
PI DevClub is the gateway to get support, latest updates, and access to
the developers’ community.
o The member benefits of the club are listed in this FAQ.
• PI Developer Technologies (tech support) - link

11
© 2020 OSIsoft, LLC. All rights reserved
- Lesson 2: AF SDK
Learning outcomes
After completing this lesson, you will:
• Be more familiar with AF SDK programmatic library.
• Know how to locate and search the AF SDK reference.
• Know how to locate and install the AF SDK.

Definition
If you need to develop your own application to interact with the PI System, you
have a few options. The whole family of PI Developer Technologies is at your
disposal. However, if you want to get the best performance out of your
application, the AF SDK has the greatest potential - assuming you are developing
and running the application in a Microsoft Windows environment.
The AF SDK is a Microsoft .NET based programmatic library that provides
structured access to the variety of data stored in the OSIsoft PI System. This data
includes:
• Assets and their properties and relationships
• Time Series data from the PI Data Archive and other sources
• Event frames that record and contextualize process events
The AF SDK provides a comprehensive, Windows based, programmatic interface
to the PI System. It provides an object-oriented approach to interact with AF
structures and data, as well as the PI Data Archive, directly. The AF SDK is
designed for easy access from Microsoft .NET languages like Visual Basic .NET, C#,
and Managed C++. The development machine and the machine that will
eventually run any applications developed with AF SDK must have at least
Microsoft .NET Framework 3.5 installed. However, for full use of all features we
recommend using the AF SDK .NET 4.5 assemblies, which would require .NET 4.5
to be installed on both the development machine, and any other machines that
will run your application.

Installation and rationale

Some reasons why you might choose to develop with the AF SDK:

12
© 2020 OSIsoft, LLC. All rights reserved
 • You can quickly build complex AF hierarchies. Many of our customers and
partners prefer to build AF hierarchies this way, rather than using the PI
Builder plugin to Microsoft Excel.
• You have the power to create rich and customized Windows client
applications. Client applications such as PI Datalink are developed using the
AF SDK and its predecessors.
• It is well suited to developing middleware applications sitting between the
PI System and other systems. AF SDK gives you flexibility on how you want
to integrate other systems with the PI System and allows you to do so in
the most resource efficient way possible. It is also possible to automate
element generation and/or synchronization between AF and other systems.
cra
In the myOSIsoft customer portal, use the Products page search box to search for
the PI Server Integrated Installation Kit. The installer includes components such as
PI AF Server, PI Notifications Service, PI Analysis Service, and PI AF Client (includes
AF SDK). For the most recent release, search in the Current Version tab; for all
versions 2018 and later, search in the All Versions tab.

For more information on downloading the Asset Framework (AF) Server and PI
System Explorer from the Customer Portal have a look at this article.

Naming Conventions
Every time you write an application using the AF SDK, you are going to have to
connect to an AF Server, or a Data Archive. The AF SDK is a little confusing when it
comes to naming, because we have kept a lot of discontinued old names of
products to preserve backwards compatibility. The Data Archive used to be called

13
© 2020 OSIsoft, LLC. All rights reserved
a PI Server, and the AF Server used to be called a PI System. OSIsoft now use the
words “PI Server” and “PI System” to describe groups of software; the PI Server
now refers to our group of server products, while PI System refers to all products
– clients, servers and development tools. For all intents and purposes:
Name in OSIsoft Name in Description
Documentation and AF SDK
Training
Data Archive PIServer A server application that stores high fidelity
time-series asset data.
AF Server PISystem A server application that indexes and
categorizes time-series, calculation, and
relational asset data.
PI Server - A collective term given to all OSIsoft non-
client server products and features. “The
Data Archive and PI AF Server, along with a
few others, make up the PI Server.”
PI System - A collective term given to all OSIsoft
products. “OSIsoft makes the PI System.”

Exercise - Search the AF SDK Reference

An important resource when developing with the AF SDK is the AF SDK Reference
on the PI Live Library. We will look at this reference and try to find some
important methods. The steps to follow are:
1. Navigate to livelibrary.osisoft.com
2. Scroll down the page to “</> Developer Technologies” and select “AF SDK
Reference”. It takes you to a different site, hosting the full reference
manual.
3. Search the manual for the following methods and write down what they
do.
o PISystem.Connect()

14
© 2020 OSIsoft, LLC. All rights reserved
 o AFAttribute.GetValue()

o AFAttribute.Data.UpdateValue ()

Learn More
• This webpage contains examples that demonstrate how to use the SDK.
• Take our online courses to learn more about AF SDK
o Developing Applications with PI AF SDK
▪ Discover how easy it is to develop powerful AF SDK based
applications; learn the basics of the programmatic access to
the PI System using AF SDK
o AF SDK Project Management Best Practices
▪ Get a taste of the AF SDK methodologies used by large global
companies to manage their large-scale complex PI landscapes
and get started on building a prototype application for
managing multiple remote AF databases (AF templates).

15
© 2020 OSIsoft, LLC. All rights reserved
- Lesson 3: PI SQL Framework
Learning outcomes
After completing this lesson, you will be:
• Be more familiar with PI SQL Framework.
• Able to describe PI SQL Client for RTQP and its features.
• Able to explain the purpose of PI SQL Data Access Server (PI SQL DAS).

Introduction
The PI SQL Framework is a category of PI System Access products that expose PI
asset structures and time series data as if the PI Server were a relational database.
That is, each exposes PI data (both real time and contextual) as tables available for
access via SQL queries. These technologies are typically used when integrating the
PI System with other systems that can import data in this format.
PI SQL Client for RTQP replaces the functionality of PI OLEDB Enterprise and is the
recommended tool for new development projects.
In this course we are highlighting only the recommended technology to use when
reading from the PI System using SQL technologies. If your organization is using an
older technology, see the following video explaining the history and landscape of
the PI SQL family of products, including all legacy products.
The only reason not to use RTQP are if you are not using AF or if you have an older
version of PI. If you are using AF and your system supports RTQP you should use it.
The tables below show some a comparison between the technologies.
Query Parsing Engine Pros Cons
PI SQL Data Access • Current path forward for PL SQL • Query Engine is on AF
Server (RTQP) • More performant query optimizer Server
• Denormalized/customizable • Read-only
schema • No Access to MDB or
• All endpoints decoupled from Batch data
query engine
• Simple/consistent Data Flow
• Transpose Queries
PI SQL Subsystem • Compatible with 2.x ODBC • Deprecated
• Query Engine not on client • Query Engine is on Pl
Data Archive
• Limited schema
16
© 2020 OSIsoft, LLC. All rights reserved
 PI OLEDB Provider • Read/write • No access to AF Server
• Direct access to Pl Data Archive data
• Access to MDB and PI Batches • OLEDB endpoint
• Simple schema coupled to query
• Backward compatible with PI SQL engine
Subsystem queries
PI OLEDB Enterprise • Access to AF Server data including • Succeeded by RTQP
Event Frames • Read-only
• Highly Normalized • Highly Normalized
• Transpose Queries • No Access to MDB or
Pl Batches
• Complex data flow
• OLEDB endpoint
coupled to query
engine

These Developer Technologies are particularly useful when the PI System has a role
to play in Reporting or Business Intelligence (BI) scenarios, where it must interact
with other products or systems that communicate using Structured Query
Language (SQL).
In order to decide which one to use, you’ll need to read the documentation of the
software or device that you’re using to read the data and see which standard it
supports. For example, you could import data into a Microsoft SQL Server database
with either ODBC or OLEDB as it supports these two standards, but you’d need to
use JDBC to import data into an Oracle database unless you’re using an additional
wrapper.

PI SQL Data Access Server (RTQP)

The RTQP Engine is a new query engine with improved performance and scalability.
The ER model is simplified, meaning that query complexity is reduced. It is a PI AF
Server component and can only be installed on PI AF Server.
It’s main features include:
• Exposes AF objects (Elements, Attributes, Event Frames) and associated data.
• Simplified schema to make writing queries easier.
• Custom schemas and functions.

17
© 2020 OSIsoft, LLC. All rights reserved
• Many performance improvements over OLEDB Enterprise, including streaming
of partially completed result sets.
• Time zone support.
• No AF SDK requirement on client machine.

Architecture
PI SQL Client OLEDB has been constructed to leverage PI SQL DAS (RTQP Engine) on
PI AF Server for query execution. Because PI SQL DAS (RTQP Engine) is installed on
the same server as PI AF Server, the client only requires a thin client that has no
local dependency on larger components such as a query engine and AF SDK.
PI SQL DAS (RTQP Engine) provides secure network communication through
Net.Tcp or HTTPS to the driver on the client side.

Install PI DAS (Data Access Server) for RTQP on the AF Machine through the PI
Server 2018 install kit and install PI SQL Client via the stand alone PI SQL Client
install kit on the desired client machine. This guide provides procedures for the
installation and configuration of PI SQL DAS (RTQP Engine) on Windows operating
systems. Users of this guide should be familiar with PI AF.

PI SQL Client
PI SQL Client is a set of lightweight providers that allow data access to the PI System
through a relational schema and belongs to the OSIsoft Developer Technologies
family of products. The PI SQL Data Access Server (RTQP Engine) is the server-side
component that processes incoming queries from PI SQL Client connections.
18
© 2020 OSIsoft, LLC. All rights reserved
Connections to the PI SQL Data Access Server (RTQP Engine) are made by client
software that make use of the PI SQL Client family of drivers. This includes PI SQL
Client OLEDB, PI SQL Client ODBC, and PI SQL Client JDBC.
The RTQP Engine via PI SQL Client became available in PI Server 2018 SP2 and is the
successor to PI OLEDB Enterprise. The functionality is very similar to PI OLEDB
Enterprise in that PI AF and the underlying tags can be queried using SQL
statements. The main benefits over PI OLEDB Enterprise are better performance,
simpler queries, and simplified software architecture.
PI SQL Commander
The PI SQL Client installation includes a test environment, which handles the OLE
connection process and allows the user to execute queries and perform other tasks.
This test environment is PI SQL Commander Lite.
PI SQL Commander is the user interface to assist with creating queries, transpose
functions, and views against PI AF using PI SQL Client. This user interface also
provides access to the legacy PI OLEDB Provider and PI OLEDB Enterprise providers.
PI SQL Commander Lite is an application to navigate a relational view of the PI
System using SQL Queries that are exposed by PI ODBC. This can be used to create,
edit, test, and save SQL queries of PI System data.
More information on the SQL commander is available in the Live Library.
Learn More
• Take our online courses to learn more about PI SQL Framework
o Exposing PI Data with the PI SQL Framework
▪ Learn the best way for your organization to integrate the PI
System into applications built for relational databases.
o Building PI SQL Queries for the Real-Time Query Processing Engine
▪ Create optimized PI SQL Client queries and transform existing
PI OLEDB Enterprise queries into PI SQL Client queries
• For information on Troubleshooting, User permissions, metadata and more,
have a look at this article in the Live Library.
• Older technologies exist and may still be useful in specific situations. See
this video for more information.

19
© 2020 OSIsoft, LLC. All rights reserved
- Lesson 4: PI Web API
Learning outcomes
After completing this lesson, you will:
• Be more familiar with the PI Web API interface to the PI System.
• Know how to locate and search the PI Web API reference.
• Know how to locate and install the PI Web API install kit.
• Understand how we are using GitHub at OSIsoft.

Introduction
In a world that is increasingly an “Internet of Things”, it is becoming more and
more important to integrate systems of different functions and standards with
each other. The PI Web API makes it easy to integrate the PI System with non-
Windows systems such as smartphones, UNIX servers or other network-
connected devices. It gives rich, cross-platform access to the PI System from any
application that can send and receive HTTPS. Adding a PI Web API Server to a PI
System will enable client access to the PI Server via a RESTful interface.
Under normal operation, a client makes HTTPS calls to the PI Web API Service.
The PI Web API Service gets the data needed from the PI Data Archive and AF
servers, and returns the data in the form of JSON to the requesting client.
A common task that you may need to perform when programming against the PI
System is to search for objects that match specific criteria. The PI Web API
provides 3 ways to execute search actions within the PI Web API:
1) Traditional endpoints with filters
2) Using the Search controller
3) Using Query methods that utilize the AFSearch classes in AF SDK
The AFSearch methods provide significant advantages over the other two search
types.
For example, searching via the Search controller is generally fast but requires
much more setup and configuration. Each AF database or PI Data Archive that is
going to be searched must be configured to be crawled by the PI Web API Search
Crawler, which creates index files for each server. This introduces more potential

20
© 2020 OSIsoft, LLC. All rights reserved
problems and administrative burden. For many applications, the AFSearch
endpoints are similarly performant and the more robust option.

PI Web API installation

PI Web API is available for installation through the standalone PI Web API install
kit.
In the myOSIsoft customer portal, use the Products page search box to search for
the PI Web API Installation Kit. For more information have a look at the article on
“How do I download PI Web API from the Customer Portal?”
There is also an article on Live Library on how to “Install PI Web API”.

Exercise - Explore PI Web API Reference

Open a web browser to the PI Live Library. Scroll down to “Developer
Technologies” and select “PI Web API Reference”. The Controllers section lists the
top-level endpoints provided by the service. Each controller's detail page provides
links to the methods exposed by the controller. Go through the following
questions:
1. Which PI Web API controller would you use for seeing the names and
properties of child elements of a given element in your AF database?

2. What does the “Stream” controller do?

21
© 2020 OSIsoft, LLC. All rights reserved
 3. You are designing an application that requires the results of time-
weighted averages of a few different data streams. You can get the
results of a summary calculation like this with PI Web API. Which
controller would you use?

4. Your application needs to be able to write back to an AF Attribute.

Which controller would you use to accomplish this?

Using GitHub with PI

GitHub is a version control web platform, widely used by the open-source
community, allowing like-minded users to borrow and contribute to other user
projects.
OSIsoft has a GitHub site with sample applications located on this page. The OSIsoft
samples are introductory, language-specific examples of programming against
OSIsoft technologies. They are intended as instructional samples only. This site has
examples that utilize PI Web API from various languages/frameworks. These
projects implement some basic functionality and are a good place to start if you are
curious what an application could look like in one of the provided languages.
This code is intended as a sample and not production level code and is provided
as-is. Any use of this code outside of the sample is not supported and at your own
risk. For more information, see our Ethical Disclosure Policy.

22
© 2020 OSIsoft, LLC. All rights reserved
Learn More
• PI Web API in Live Library
• Take our online courses to learn more: Using PI Web API from Beginner to
Advanced
o Learn how to retrieve and manipulate time series data, asset
information and event frames using PI Web API.
• [VIDEO] Getting cOMFortable with PI Web API
o With today’s computing power and the low cost of sensors, no data
should be out of the reach of your PI System. When dealing with
large amounts of critical data, it is important that our data ingress is
performant and reliable. This video goes over the best practices of
deploying an OMF application at the edge, using the PI Web API’s
OMF Data Ingress Services.

23
© 2020 OSIsoft, LLC. All rights reserved
- Lesson 5: PI Integrators
Learning outcomes
After completing this lesson, you will:
• Be more familiar with PI Integrators in general and have taken a deep dive
into our most popular options: PI Integrators for Business Analytics and Esri
ArcGIS.
• Have gained a high-level understanding of the PI Integrator Architecture
and Installation Process.
• Be aware of possible resource and documentation locations for further
study.

Introduction
PI Integrators provide decision-ready PI Data to external systems, offering
Information Technology/Operational Technology integration. PI Integrators are
user-configurable products that mitigate the need for extensive custom solutions.
In this lesson we will take a closer look at two of the most popular PI Integrators:
i) for Business Analytics and ii) for Esri ArcGIS.
Other PI Integrators include:
• PI Integrator for Microsoft Azure - presents PI System data, context, and
events perfectly suited for Advanced Analytics with Cortana Intelligence
and Power BI for reporting, visualization, and analytics.
• PI Integrator for SAP Hana - combines PI System data with SAP Hana so you
can combine and analyze your sensor-based, time series, data from the PI
Server with the high-performance analytics of SAP Hana.

PI Integrator for Business Analytics

PI Integrator for Business Analytics transforms PI System data into a decision-ready
format that can be consumed by business intelligence (BI) tools, such as Microsoft
Power BI, Tableau, Tibco Spotfire, and QlikView. With BI tools, you can run
retrospective analyses on large sets of your real-time PI System data. Such analyses
make operational behaviors and patterns visible, so you can identify dependencies
and correlations between different aspects of your operations.

24
© 2020 OSIsoft, LLC. All rights reserved
The PI Integrator for Business Analytics gathers AF attribute data, filters it based on
the criteria entered by the user in the Integrator's browser-based User Interface
(UI) and publishes the data to an external data store (e.g. Microsoft SQL Server,
Apache Hadoop). PI Integrator for Business Analytics is designed to help users
transform time series data from the PI System into a data set that is easily
consumed by Business Intelligence (BI) tools. PI Integrator for Business Analytics
works directly with PI AF (not the PI Data Archive) when creating the search criteria
for views. Therefore, a good AF structure is vital to using the PI Integrator.
Architecture and Components
PI Integrator for Business Analytics has three basic components. The user interacts
through the UI with each of these components:
• PI Integrator Framework - the master Windows Service for the PI Integrator
o Runs the Web UI - Self-hosted application server used to access the PI
Integrator
o Coordinates view scheduling and controls which Worker Node
publishes each view
• PI Integrator Worker Node(s) - Windows service that handles publication
jobs.
o Up to 5 worker nodes can be added to help distribute jobs (note that
each additional worker node adds RAM and CPU requirements).
• PI Integrator Sync - Windows Service that watches for changes to PI tag data
and AF objects, and for views that support this, automatically updates
supported targets with changed data. See Live Library for “How published
data gets updated” for information on which views support automatic
updates.

25
© 2020 OSIsoft, LLC. All rights reserved
Download and Installation
Have a look at this link for information on downloading PI Integrators from the
Customer Portal. There are three phases to PI Integrator installation.
o Phase 1: Prepare for installation
▪ This phase ensures that you have the appropriate access and
permissions to the components that interact with PI Integrator
for Business Analytics: PI AF server, PI Data Archive, and
Microsoft SQL Server. These prerequisites must be in place
before you run the installation kit for PI Integrator for Business
Analytics.
o Phase 2: Install PI Integrator for Business Analytics
▪ In this phase, you install PI Integrator for Business Analytics,
specifying the PI AF server and Microsoft SQL Server. New PI
Integrator databases are created on the Microsoft SQL Server
for PI Integrator for Business Analytics.
o Phase 3: Verify the installation
▪ This phase verifies that the PI Integrator for Business Analytics
services have started and are running.
For more details on the installation phases have a look at this Live Library article.

26
© 2020 OSIsoft, LLC. All rights reserved
For topics such as Licensing, Output Streams, Product Documentation, Releases
and Configuration please refer to this article.

PI Integrator for Esri ArcGIS

PI Integrator for Esri ArcGIS 2017 SP1 allows you to expose your PI System data in
a real-time geographical context using the Esri ArcGIS platform. It gathers AF
attribute data combined with geographical information (either from PI or by joining
to an existing Esri Feature Layer with geometry) about the corresponding assets
and publishes it to the Esri ArcGIS platform for use in maps and geospatial analyses.
The Integrator can serve real-time PI data streams to the Esri ArcGIS GeoEvent
server, which enables geospatial analysis, or real-time and (starting in the 2017
release) historical data directly to Esri platforms for customers to host and view GIS
content: ArcGIS Enterprise with Portal for ArcGIS (on-premises) or ArcGIS
Online (cloud).
The latest version features time-enabled mapping, allowing ArcGIS clients to access
and display historical PI System data. You can now view data stored at any time in
the PI System in addition to streaming current data. It also adds support for
Integrated Windows Authentication (IWA), one of the web-tier authentication
schemes in Esri’s Portal for ArcGIS.

Download and Installation

Have a look at this link for information on downloading PI Integrators from the
Customer Portal.
27
© 2020 OSIsoft, LLC. All rights reserved
The PI Integrator for Esri ArcGIS installation process comprises three phases. The
phases are:
• Phase 1: Prepare to install PI Integrator for Esri ArcGIS.
o Proper configuration is required when installing PI Integrator for Esri
ArcGIS. Ensure you have all of the system requirements in place before
installing.
• Phase 2: Install PI Integrator for Esri ArcGIS.
o You must install PI Integrator for Esri ArcGIS on a computer that has
access to a Microsoft SQL Server. PI Integrator for Esri ArcGIS may
authenticate with the SQL Server either using Windows
Authentication or legacy SQL Authentication. During installation, you
will have the opportunity to validate the connection and
authentication.
• Phase 3: Administrator configuration.
o While logged on as a system administrator, you must perform a few
configuration tasks before users can access the system.
For more details on the installation phases have a look at this Live Library article.
For topics such as GeoEvent-enabled Layers, Time-enabled Layers, Licensing and
Data security please refer to this article.

Learn More
• Live Library links:
o PI Integrator for Business Analytics
o PI Integrator for Esri ArcGIS
• PI Integrators Tech Support page
• BI Reporting with PI Integrator for Business Analytics - online course focused
on analyzing PI System data using Power BI and PI Integrator for Business
Analytics. We will build upon your existing application knowledge with
hands-on activities to help you transform data into information.
• Videos
o Insight: PI Integrators and OSIsoft Cloud Services for time-series Data
Science Enablement - OSIsoft continues to invest in technology for
better enabling data science and advanced analytics. For most

28
© 2020 OSIsoft, LLC. All rights reserved
 analytics projects, there is no magic “X marks the spot”, but there are
many possible paths to success.
o PI Integrator for Esri ArcGIS Architecture Map of Data Flow- High Level
- The PI Integrator for Esri ArcGIS is the OSIsoft product that enables
real-time geographic data visualization by connecting your PI System
with the Esri ArcGIS platform. This video explains the major pieces in
the data flow between these two systems by drawing a high-level
architecture map. Learn what feature services and layers are, the role
of the ArcGIS GeoEvent Processor in pushing real-time data to the
feature services, and how the PI Integrator for Esri ArcGIS connects the
GeoEvent Processor to the PI System data and can be used to create
the map layers.

29
© 2020 OSIsoft, LLC. All rights reserved
- Lesson 6: OCS and EDS
Learning outcomes
After completing this lesson, you will:
• Be more familiar with both OSIsoft Cloud Services and Edge Data store
• Know where to get more information to expand your understanding and
skills.

OSIsoft Cloud Services (OCS)

Introduction
Industrial digitalization and globalization are generating more data and new
opportunities to leverage data. Data that can be shared and used to power new
applications that deliver increased operational efficiency and support new business
models. At the same time the cloud offers a scalable, elastic, and centralized
environment to aggregate data for reporting, advanced analytics, and third-party
applications. OSIsoft's Cloud Services are designed to meet today's digital
transformation needs by connecting in real-time data from PI Systems, to people,
analytics and applications for enterprises and communities to realize the value of
their data.
What is it?
OCS is a cloud-native platform built for historical, real-time and future/forecasted
operational data. OCS complements existing on-premises PI systems and enables
users to easily define, visualize, query and shape data sets required for data
science.

More information

30
© 2020 OSIsoft, LLC. All rights reserved
 • https://www.osisoft.com/Solutions/OSIsoft-Cloud-Services/
• OSIsoft Cloud Services portal: cloud.osisoft.com
o This your gateway to learning about Cloud Services features. You will
find detailed API documentation as well as sample code to help you
interact programmatically with your data using the Cloud Services API.
o In the OCS portal you can:
▪ View OSIsoft Cloud Services API documentation
▪ Explore working code samples provided in multiple
programming languages
▪ View the OSIsoft Cloud Services service blog
• Enabling Enterprise-wide Data Science with OCS Dataviews
o In this course, you will gain hands-on experience with a new OSIsoft
software product, OSIsoft Cloud Services (OCS): analyze & visualize
data in OCS, add metadata & create Data Views in OCS, access OCS
data in a Jupyter Notebook via Python, filter & prepare data from OCS
for machine learning and more.
• OSIsoft Cloud Services (YouTube playlist)
• OCS for Developers (webinar)

Edge Data Store (EDS)

Introduction
EDS augments the PI System and OCS by collecting and storing data in situations
where deploying a full system is impractical. It can collect data that is beyond the
reach of automation systems, in unreliable network conditions, and in
environments too rough for traditional computers. Edge Data Store can run almost
anywhere you can install a sensor, such as beam pumps, mining trucks, windmills,
etc.
What is it?
EDS is a lightweight data collection and storage application designed to capture
data at the edge of networks for historical storage and analysis. It runs on small,
rugged devices or embedded in existing industrial hardware, and is designed to be
resilient and require minimal installation and administration.
EDS collects data using any of the following methods:

31
© 2020 OSIsoft, LLC. All rights reserved
• Built-in OPC UA connectivity
• Built-in Modbus TCP connectivity
• Custom application using OSIsoft Message Format (OMF)
• Custom application using REST API
Once collected, the data is stored locally in configurable data storage within EDS,
until it can be sent to permanent storage in a PI System or in OSIsoft Cloud Services
through periodic egress. The data can also be read from local storage by custom
applications using REST APIs.

More information
• Link to GitHub page (https://osisoft.github.io/Edge-Data-Store-Docs/V1/)
which includes: design, performance and security considerations , quick
start guides and configuration options.
• Blog post: Easy as PI: Edge Data Store
• Video: What is an Edge to Cloud IIoT Solution for Remote Asset Monitoring
using Smart Sensors?
o Listen to Mikhail Koloskov from IPCOS say why they chose EDS for
their edge analytics application for Oil & Gas. OSIsoft's Chris Felts
describes the history of EDS and how it is related to the PI System.
• Video: Edge Data Store - Applications delivered at the Edge
o In this presentation, we will cover what the Edge DS is and how we
envision customers will use it at the Edge of networks. We show you
how you can create local user applications directly from data stored
in Edge DS. Finally, we will show you how to use Edge DS to extend
applications from the Edge to the Enterprise or the Cloud.

32
© 2020 OSIsoft, LLC. All rights reserved
- Next Steps and FAQ
FAQ
• Should I use the Developer Technologies to send data to another PI System?
o We offer better solutions for that:
▪ PI System Connector
▪ PI to PI Interface
▪ Differences between PI to PI and the PI System Connector
• Should I use the Developer Technologies to send data to Esri ArcGIS, SAP
Hana or Business Analytics Tools?
o We offer better solutions for that:
▪ PI Integrators
• What is the “PI OPC DA/HDA Server?”
o This is an old product that has been replaced by two new products:
▪ PI OPC DA Server
▪ PI OPC HDA Server
• Do we have a “PI OPC UA Server?”
o Not yet: Feedback item is in User Voice
• What is the PI SQL Data Access Server (PI SQL DAS)?
o A component of the PI SQL Framework. There are three editions:
▪ PI SQL DAS (RTQP): Real Time Query Processing Engine for the PI SQL Client
▪ PI SQL DAS (OLEDB): Connects ODBC/JDBC Drivers to the OLEDB Providers
▪ PI SQL DAS (PI Integrator Framework): Used by the PI Integrators
• Is the PI SQL Framework a product?
o No. The PI SQL Framework is a group of products:
▪ PI SQL Client (OLEDB, ODBC, JDBC)
▪ PI OLEDB Provider
▪ PI ODBC Driver
▪ PI JDBC Driver

Next steps
Thank you for taking this introductory module on Developer Technologies. We
recommend you continue along the “Developer” learning path by following courses
appropriate to the developer technology you have chosen for your project.
Take our online courses to learn more:
• PI AF SDK

33
© 2020 OSIsoft, LLC. All rights reserved
 o Developing Applications with PI AF SDK - Discover how easy it is to
develop powerful AF SDK based applications; learn the basics of the
programmatic access to the PI System using AF SDK
o AF SDK Project Management Best Practices - Get a taste of the AF
SDK methodologies used by large global companies to manage their
large-scale complex PI landscapes and get started on building a
prototype application for managing multiple remote AF databases
(AF templates).
• PI SQL Framework
o Exposing PI Data with the PI SQL Framework - Learn the best way for
your organization to integrate the PI System into applications built
for relational databases.
o Building PI SQL Queries for the Real-Time Query Processing Engine -
Create optimized PI SQL Client queries and transform existing PI
OLEDB Enterprise queries into PI SQL Client queries
• PI Web API
o Using PI Web API from Beginner to Advance - Learn how to retrieve
and manipulate time series data, asset information and event frames
using PI Web API.
Alternatively, get familiar with basic Data Science concepts and techniques, by
going through the steps of a Data Science project example in our “Introduction to
Data Science for PI System Professionals” course.
You can find the complete list of courses for the “Developer” learning path here.

34
© 2020 OSIsoft, LLC. All rights reserved