ASSET FRAMEWORK: BASICS

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.
Contents
A Walkthrough of AF .................................................................................................................. 4
What does Asset Framework (AF) do for me? ........................................................................ 4
Introduction to AF Key Features ................................................................................................. 6
PI System Explorer (PSE) Navigation ..................................................................................... 7
Keyboard Shortcuts (optional) ................................................................................................ 9
Connecting and Verifying Data Archive and AF Servers ....................................................... 11
Searching and Filtering with PSE ............................................................................................. 13
Finding Data Demonstration ................................................................................................. 13
Searching and Filters............................................................................................................ 17
Finding Points through PI System Explorer .......................................................................... 21
Create an Element using the Palette functionality ................................................................. 24
Hiding Check In and Check Out Dialogs (optional) ............................................................... 29
Creating Databases, Hierarchies, Templates and more ........................................................... 31
Asset Hierarchy Design Strategies ....................................................................................... 31
Create an AF Database, Element and Attributes .................................................................. 33
Create an AF Table .............................................................................................................. 37
Create an AF Enumeration Set ............................................................................................. 39
Unit of Measures Overview................................................................................................... 41
Details on Reference Types ..................................................................................................... 44
Attribute Data Reference Types............................................................................................ 44
Formula Data Reference ...................................................................................................... 45
Substitution Parameters in an Attribute Template ................................................................. 48
Creating a Template from an Element .................................................................................. 50
String Builder Data Reference .............................................................................................. 52
Adding to the Hierarchy............................................................................................................ 53
Add attributes to the template ............................................................................................... 53
Creating an Element from a Template .................................................................................. 57
Adding Layers to the Hierarchy ............................................................................................ 59
Bulk edits of the AF Hierarchy .............................................................................................. 63
Attribute Traits ...................................................................................................................... 68
Use of Categories ................................................................................................................. 70
Discover Tag Creation .......................................................................................................... 74
Visualizing Velocity Terminal Data with PI Vision ................................................................. 76
Summary Lesson: Best Practices - Written ............................................................................. 83
A Walkthrough of AF

What does Asset Framework (AF) do for me?

The PI Data Archive 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|Page
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|Page
Introduction to AF Key Features
Asset Framework provides an additional data layer in the PI System. It is based on an asset
model of your plant that you define for your company. The model consists of elements and
attributes.
You can model your plant by organizing and structuring the data
according to how you work with your company data. Examples
include organizing by physical location or by physical objects in their
processes like reactors, transformers and meters.
Since the AF asset model can span PI Data Archives, it allows you
to organize and search for PI System information across multiple PI
Data Archives.

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

6|Page
PI System Explorer (PSE) Navigation

In this section, we'll be discussing the basics of PI system explorer, or PSE as it is frequently
referred to for short.

PI system explorer is the main tool for configuring and managing PI asset frameworks, PI
notifications and PI event frames.

We'll start by opening PI System Explorer by going to all programs, PI System folder and look
for this icon .

Now as PSE starts up, you'll notice that the screen is divided into several different sections. So
we'll go over each of these, starting in the bottom left, we have what is known as the navigator
panel.

Here you'll see that there are several different objects that you might want to work on within
PSE. In this course, our primary focus will be on the Elements and Library options.

In the elements section which is where your hierarchy resides, this can be a physical or logical
representation of your process.
The library is a collection of objects that can be used throughout your AF hierarchy. This
includes templates, enumerations sets, tables, etc.

7|Page
Although not modified in this course, but it should be acknowledged due to its importance is the
Unit of Measure. This database provides automatic handling of simple conversions between
units of measures for attributes of the same UoM class. A UoM class is defined by the
fundamental dimension of its measurement. Some examples of UoM classes are Mass,
Temperature Volume, and Density.

You may have noticed as we selected different sections on the navigator pane, available
options were changing above it – this section is known as the browser. With Elements selected,
your hierarchy is visible, if the Library is selected, options to work on building templates, tables,
enumerations sets are brought into view.

To the right of the browser area, we have the viewer, which is your primary work area. From this
pane, we can build templates, add attributes, configure tables, etc.

The final section we can display is called the palette. By default, this pane is hidden to optimize
screen visibility/workspace. To make the pallet visible, go to the view menu, select palette, and
show palette. From the palette area, we have several options available. For now, we will
mention the tag search. We can perform a tag search allowing us to quickly drag and drop
already defined data into the attribute area to make new attributes on a template.

Another option to increase viewing space is to minimize the configuration window.

If we explore the menu options, we can see one item labelled ‘Go’. This menu option gives
keyboard short cuts to traverse the navigator pane.

The last thing to mention is the status bar. It's at the base of the PI System Explorer window.
This will tell you the status of a selected element. For example, from the Library, I have selected
the PressTemplate. You can identify when it was last modified and by whom from the status bar.

To review, we went over the major components of PI System Explorer.

The components being the status bar, menu bar, and navigator panel for selecting groups of
objects to work on. The browser for selecting individual objects. The viewer for configuring
objects. And finally, the palette where we have quick access to templates and tags for drag and
drop editing.

8|Page
Keyboard Shortcuts (optional)
For those that like keyboard shortcuts, these navigation tips may be of interest to you.
It is a lot faster to use the keyboard shortcuts to move between the ribbons as well as to perform
other tasks in PSE. While there are many keyboard shortcuts, the most important will be those that
switch options in the Navigator Panel. This is because you will need to switch views frequently.
Navigate to the Library in the Navigator Pane using the keyboard. Then navigate back to the
Elements.

Step by step:
1. Press the Ctrl+3 key combination to navigate to the Library view. To navigate back to the
Elements view press the Ctrl+1 key combination. The Ctrl+<number> key combinations to
navigate to different views are (all these are found under the ‘Go’ drop down menu):

The table below shows other very useful keyboard shortcuts.

Key Combination Action

CTRL+A Selects all objects in the Viewer.
CTRL+C Copies the selected object to the clipboard.
CTRL+ALT+C Copies the path of the selected object to the clipboard.
CTRL+V Pastes the object on the clipboard to the Viewer.
CTRL+X Cuts (deletes) the selected object and copies it to the clipboard.
DELETE Deletes the selected object.
SHIFT+DELETE Same as CTRL+X
INSERT Adds a new object to the Viewer or Browser.
HOME Selects the first row in the Viewer, for example, the first row in a
table of attributes.

END Selects the last row in the Viewer.

9|Page
Key Combination Action
CTRL+HOME Selects the first cell of the current page in the Viewer.
CTRL+END Selects the last cell of the current page in the Viewer.
ALT+HOME Selects the first page of objects in the Viewer.
ALT+END Selects the last page of objects in the Viewer.
CTRL+PAGE UP Selects the previous page of objects in the Viewer.
CTRL+PAGE DOWN Selects the next page of objects in the Viewer.
CTRL+ENTER If the Viewer contains multiple pages of objects, displays the
Select Page Number window.
ALT+ENTER In the Browser, displays the properties of the selected object.
SPACE Presses the currently selected button.
or
ENTER
Left, Right, Up, and Down Navigate objects in the Viewer or Browser.
Arrows
F2 Edits the selected object on the Viewer. For complex objects,
displays the edit window for the object.
F4 Displays the choices in the selected list box. For layered lists,
or displays the complete hierarchy of choices.
ALT+Up Arrow
or
ALT+Down Arrow

F1 Brings up the Help Menu

10 | P a g e
Connecting and Verifying Data Archive and AF Servers

In this section we will review connecting to an AF Database.

To work in PI System Explorer, a connection needs to be made to a PI System.
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.

From the left-hand corner of PSE, you see the word Database, from here, you can connect to
the correct AF Database (providing multiple databases exist). As we click on Database, in our
case, multiple databases display on the screen.

The database named Configuration is a database that should not be modified. It is used
internally.
Throughout this course, we will be using the Big Tire Co. databases unless otherwise directed.

Although, we are using AF to organize our company process data in a readable format, the data
actually exists in the Data Archive.
From PSE, the PI Server and AF Servers must be identified so the tool can connect to the
database created for your company’s data. During installation of the PI System, the connections
are built, however, it is good to know how to verify the connection.

From the File menu option, under Connections, a list of servers can be found. The name, user
logged in and type of server can be found in the connection window.

You can validate your connection to the Data Archive via PSE. Notice AF Server icon ( ) is
different than Data Archive server icon ( ).

11 | P a g e
The connection information is not only important for connecting PSE to the correct database,
this information is critical in locating the data (or storing the data) being collected within your
facility.

An alternate means of validating your connection to the Data Archive is via the PI SDK utility.

From the program menu, select PI System → PISDKUtility. The default view opens with
Connections selected. (From the PI-SDK > Connections section, the Data Archive servers
configured on the local machine are displayed.) To validate a connection to a Data Archive,
simply check the checkbox next to its name or IP address. If connection succeeds, connection
information will be shown.

The user that was used to authenticate on the Data Archive will be shown in the status bar and
the connection information section on the right.

Note: The PI SDK Utility is a particularly useful tool to troubleshoot permission issues.

12 | P a g e
Searching and Filtering with PSE

Finding Data Demonstration

In this section, we will demonstrate some options to search for information.

• Perform a quick element search based on a name pattern

• Perform an element search with multiple search criteria.
• Perform an attribute search.
Let’s start with the Quick Element Search:

Approach
Quick Element Search
1. Open the PI Big Tires Co. AF database from PSE, verify Elements is selected in the
Navigator.
2. Explore the element hierarchy: it contains 3 locations (Houston, Montreal and
Philadelphia (“Philly”)) with four presses in each location. (Slight pause as locations are
being opened)
3. Above the viewer pane, there is a Search box in the upper right-hand corner. Enter HOU
into the quick search and press Enter. The results of the search will appear in the
browser screen under the ‘Element Searches’ option and in the viewer pane.

(Pause as 5 results should appear on the screen)

4. Now let’s try a different search. Enter HOU*Press into the quick search and click on
Enter.
(Pause as 4 results should appear on the screen)

Note: one has been eliminated due to the additional criteria added to the search and an
additional quick search will display under the Element Searches option.

13 | P a g e
 Note: The searches created display a little asterisk next to the searches name. If
you created a search to be used periodically, you can save it by right clicking on the
Element Search name, then select Save. From the same context menu, you can
rename the search.

If you do not save the search, it will not be available the next time you open PI System
Explorer.

Advanced Element Search (multiple search criteria)

5. From the PSE menu, select Search – Element Search…
6. (optional) If criteria was cached from the last search, click the blue “x” in the search line
on the top to reset.
7. Enter criteria to search for the presses in Montreal.
a. Select the ellipse (…) towards of the ‘Element Search Root’ entry box.
b. A screen appears, from here you can select the item of interest. We will select
‘Montreal’. Click OK.
c. In the template field, we can add PressTemplate. This will become more
important as additional templates are created.
d. The search criteria should have the Element Search Root= Montreal and the
template= PressTemplate.
e. Click on Search to get the results – the search field is in the upper right hand
corner of the screen.
Pause – as all 4 presses appear upon select search.
8. Let’s add an additional piece of information into the search. Enter *1 in name field to
specify another criteria, click on Search to get the results.
Pause – as only 1 press from Montreal appears.

14 | P a g e
 In the above two searches, we had ‘All Descendants’ set to False.

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

9. Let’s reset the criteria by clicking the reset button in the lower right hand corner.
10. Now, set ‘All Descendants’ to True and enter *1 into the Name field.
Pause – 3 records are found throughout the hierarchy.

11. Reset the criteria again. When you specify a template (e.g. PressTemplate) you can add
additional criteria. Click Add Criteria, select Attribute Value.

12. To select the attribute of interest, select the ellipse field next to the word Attributes.
Select Other Attributes, then the attribute of interest, for now, Press Status.

13. Press Status is based on an enumeration set, so a drop down box has the potential
values for the attribute. Set the value to “Running”.
14. Press Search. Currently there are 12 elements with the attribute Press Status. Odds are
some but not all Presses will be running.

15 | P a g e
 Attribute Search
15. From the PSE menu, select Search – Attribute Search…
16. Verify the PI Big Tires Co. AF database is selected
17. Enter Press Status into the attribute name field. Click Search. Result: The Press Status
attributes for all 12 presses are listed. Click on OK.

16 | P a g e
Searching and Filters

As your AF hierarchy grows, it is important to be able to find the Elements you need. In the
following exercise, we will discuss searching, then filtering the search results.

Approach: Create a search view named Tanks that contains all the Storage Tanks for our
creatively named Production Area

Step by step:
Before creating the search and filters, the database needs to be changed.
a. Verify current database, so far, the Big Tire Co. database has been used.

b. Press Database, then highlight the OSI Production Facility database, press OK.

c. If you are not in the Elements, go to Elements in the Navigation pane or press the
Ctrl+1 key combination
d. Press the F3 key to bring up the Element Search window or from the menu, select
Search then Element Search.
i. Enter Production Area for the Element Search Root OR click … to select the
root from the hierarchy.
ii. Select True for All Descendants
iii. Select Generic TankTemplate for the Template

iv. Press Search to preview the results.

v. Click the OK button.

17 | P a g e
e. You can rename the search results in two ways.

Option 1: Right click the Element Search Results 1 in the Browser pane and select
Rename. Type in Tanks and press the Enter key.

Option 2: Click on the Element Search Results 1 and the press the F2 key, type in
Tanks and press the Enter key.

f. Additional filtering can be done from the Viewer pane.

18 | P a g e
Viewing Additional Columns in Searches

a. All the Tanks are listed in the Viewing pane.

i. To view every Internal Temperature of Tanks we first need to add an Attribute
to the header to make it visible.
ii. An Attribute named InternalTemperature has been configured in the
PressTemplate.
iii. Right click on the gray area of the header and select Column Visibility>Select
Attributes.

b. In the Select Attributes dialog select the row with the name Internal Temperature and
click the button. Then click the OK button.

19 | P a g e
 c. Now in the Viewer, we are able to see all the internal temperatures associated with all
the tanks using the Generic Tank Template.

Note: For large databases/hierarchies, the rows displays can be controlled by the ‘Maximum
Query Size’ located in Tools>Options menu.

20 | P a g e
Finding Points through PI System Explorer
Activity Objectives
• Review the search capabilities and options of PSE Tag Search.

Approach
1. Verify Elements is selected in the Navigation Pane. The menu varies with navigation
item selected.
2. From the PSE menu, select Search – Tag Search…
3. (optional) If criteria were cached from the last search, click the blue “x” in the search line
on the top to reset.
4. Search for tags matching the name pattern CD*158

3 items display with this search.

5. Search for tags matching the name pattern CD?158. What is the difference to the
previous search results?
2 items display with this search.
Note: an * can represent 1 or more characters; whereas the ? represents a single
character.
6. Reset the search, by pressing the ‘Reset’ button to clear previously entered information.
7. By default, the Tag Search window defaults to searching against the point name mask. If
you click on the control to display extra search features, you will get more options to
further refine the search using additional common point attributes like the descriptor.

21 | P a g e
This option is convenient in instances where a common point source is used in setting
up interfaces or specific groupings of data.

For example, enter point source=R to search for all tags with this criterion. In our PI
Server configuration, the R in point source indicates all tags associated with the Random
interface.

22 | P a g e
If you are working on setting up your hierarchy, it may be more convenient to bring up
the Tag Search in the Palette view. The same functionality exists, but it is viewed in a
fixed pane.

23 | P a g e
Create an Element using the Palette functionality
Work with the Palette using the OSI Production Facility database.

Verify the database is set to the OSI Production Facility.

Display the Tag Search functionality within the Palette.

When you start building an Element it can be hard to find tags and fill out all attribute fields.
Thankfully, the Tag Search Palette process is streamlined. We will create a new Element
called Extruder containing all relevant PI Points.
Step by step:
Step 1. Navigate to the Elements view.
Step 2. Open up Production Line1 location. Right Click on Production Line1 and
select New Child Element.

Step 3. Choose <None> for the Element Template and click OK.

24 | P a g e
Step 4. Name the non-templated Element Extruder. You can press F2 to rename quickly
or right click on the new element.

25 | P a g e
 OR

Step 5. Navigate to the Attributes tab.

Step 6. If you have not already opened the Palette, in the Menu bar click on View and
then select Palette>Tag Search. (you can also use short cut key combination of
Ctrl+Shift+8)

26 | P a g e
 Step 7. Search for *EX* to find the appropriate PI Tags associated with the extruder. The * is
either a single or multicharacter wild card.

Step 8. As we are currently under Production Line1, Add the tags *PL1.EX1* for
External Temperature, Flow Rate, Internal Temperature and Pressure by
clicking and dragging each tag in the Viewer area. Notice how the description,
point type, and UOM match the PI tag definition.

Note: The tags can be added individually or all together – by selecting each with the control key
selected.

Note: The units of the PI Tag must exist in the UOM database before dragging tags from the
palette.

Step 9. Close the Palette window to allow more space to configure the attributes.

27 | P a g e
 Step 10. Once added we can change the individual Attribute names. The names can be
updated through the configuration screen, select Name or by double clicking the
individuals name in the viewer screen.

Step 11. Rename the four attributes as per the following:

Step 12. Check-In your changes, by selecting Check In or press the Ctrl+S key
combination to Check In your changes.

Note: We have not discussed the Check-Ins and their need to save changes to the database.

Whenever you make a change to an object, including whenever you create a new object, PI
System Explorer checks that object out from the database. You need to save these changes in
the database, although you can apply a change to a selected object by clicking in the toolbar
and then check in your changes later.

Live Library link to Check-in database changes: PI Server 2018 (osisoft.com)

28 | P a g e
Hiding Check In and Check Out Dialogs (optional)

When performing a Check In, it is timesaving to avoid the Check In dialog.

To hide the dialog, you can enable ‘Only show database Check-In dialog when Shift key is down’
in PSE.
Part 1: Create a new element and check it in without the dialog popping up.
(Database: OSIsoft Plant)

Step by step:
a. If you are not in the Elements view press the Ctrl+1 key combination or Select
Elements from the Navigator Pane
b. In the menu, navigate to Tools>Options…
c. In the Options dialog check the Check Box Only show database Check-In dialog
when Shift key is down

d. Click the Apply, then OK

e. Right click the Elements ( ) in the Browser pane and select New Element
(choose element template <None>). Alternately, you can also select Elements
( ) and press the Insert (Ins) key.
f. Note, a new Element exists named Element1 with a check next to the New Element

g. Press the Ctrl+S key combination. The changes are now checked in. (Another option
is File → Check In)
h. Verification of Check-in can be seen, by the disappearance of the check mark next to
the newly created element.

29 | P a g e
Part 2: Create a new element and check it in, but have the Check In dialog appear first.

Step by step:

a. Right click the Elements ( ) in the Browser pane and select New Element
(choose element template <None>). Alternately, you can also select Elements
( ) and press the Insert (Ins) key.
b. While holding the Shift key down, click in the Toolbar. A new screen
appears for verifying check-in.

Note that you cannot use the Ctrl+S key combination while holding down the Shift
key.

c. Click the Check In button in the dialog.

d. Reset Check-In functionality if you prefer seeing the dialog.

30 | P a g e
Creating Databases, Hierarchies, Templates and more

Asset Hierarchy Design Strategies

In an AF database, assets can be organized or structured into hierarchies. According to its
definition a hierarchy is “a system of persons or things arranged in a graded order”
(thefreedictionary.com). Logical hierarchies of assets or people are common in companies from
any industry. They are used to convey the place/location of each entity in the company. Since
the AF system is probably not the only enterprise system in your company, other systems in
place might already make use of asset hierarchies (maintenance systems, etc.).
Those systems will often have an option to export the hierarchy information into a flat file
(.csv, .txt, .xml, etc.). The content of this file can then be opened in Microsoft Excel and be used
as a starting point to build the hierarchy in AF using the PI Builder add-in.

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

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

There are several styles for designing asset models in AF.

Even if the following approaches will result in a complete asset model, there will always be
more information to add in the future. That is fine and is in fact a relief, since it means the AF
model does not need to be perfect and complete the first time.

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

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

32 | P a g e
Create an AF Database, Element and Attributes
In previous lessons, connections to the servers and database, search functionality and how to
create an element from the palette have been covered.

In this exercise, a new database is being created to start a new element. Attributes will be
added to the element with different data reference types.

Create a database:
You are working for Velocity Terminals, a chemical company producing various chemicals. The
company has a number of storage tanks located in different countries that they would like to
monitor. You have been tasked with creating an asset model for these tanks in AF.
Open PSE and 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.
Enter the name AF Startup into the Name field of the Database Properties window
A description can be added as the usage of the database – in this case, Velocity Terminals test
database.
Select OK to complete database creation.

Now that we have a clean database, let’s create your first element:
Make sure the Elements section is selected from the Navigator Panel and create a new element
called Tank01.

From the Browser, right-click on and select New Element or click the
button from the toolbar and select <None> as the element template.
Under the General tab from the Viewer, change the default name of the element to Tank01.

Notice the small check mark next to the newly created Tank01 element. The check mark
indicates, changes are being made to the database and have not be ‘saved’.

33 | P a g e
Create AF Attributes

From the Viewer, select the Attributes tab and then right-click on the white space to select New
Attribute to define attributes or click the button from the toolbar.
As with elements, attributes must also be uniquely named along their path within the element
they belong to. Attributes can have a configured constant value or can get a value dynamically
from a Data Reference.

Let’s create a static capacity value for the Tank.

Rename Attribute1, to Capacity, by double clicking Attribute1 in the viewer pane or navigating to
the Name field in the configuration pane.

Set the Unit of Measure to US Gallons (it will be under the Volume class). Setting the UoM is
important to prevent misinterpretation of the measurement. The Unit of measure will be
displayed with the attributes value.

Set the Value type as a Double with a default value of 20,000.

Since the Capacity attribute is a static value, the Data Reference is <None>.
Let’s go a little deeper in setting up two more attributes, each will use another form of data
reference.

Attribute Default Value Display Data

Name UOM Type Value Digits Reference
Level % (Ratio) Double N/A 2 PI Point
Volume m3 (Volume) Double N/A 3 Formula

Another method of creating a new attribute is to right click in the viewing pane, then select New
Attribute.
Start entering the Level attribute information. Default UoM as %, Value Type Double, and
Display Digits 2. After setting the Data Reference to PI Point, select the Settings button.

34 | P a g e
A search window will display – verify the Data Server is PISRV01, then either enter
Tank01LI.PV in the field next to the Tag Name OR select the tag search (magnifying glass) and
enter a portion of the tag name (for example, tank01*). (The tag search may need to be reset to
remove any cached information.) After selecting the tag name, select OK.

The current value of TANK01LI.PV will display in the Value column.

Let’s add one more attribute to the Tank01 element.
Add the Volume attribute. Enter the Unit of measure as m3 located under the Volume class.
Another means of setting the Unit of Measure is to type the abbreviation into the field.
For this attribute, we are going to use a Formula Data Reference. Press the Settings button to
finish the configuration.

• Use the new button ( ) to add parameters to use in the formula.

Volume Attribute
• Select the Volume attribute.

• Click on Settings… to bring up the Formula Configuration window.

• Use the formula data reference to calculate the volume using the level (%) and the
capacity (m3).

• Use the new button ( ) to add parameters to use in the formula.

Two previously created attributes are being used in this formula. Capacity and Level to
calculate the volume.

• Click the New Button, then expand the list of functions from the equations section ( ) to
pick the operators/functions to use in the formula.

35 | P a g e
 • For completion, select Check In to save the changes in the database.

Units of Measures in Formulas

You can perform unit conversions by setting the units of measure (UOM). Units of measure can
be explicitly set for the parameters as well as for the result. Do this from the parameters
configuration section by choosing the appropriate UOM from the Unit of Measure drop down.
Do this also in the Result section at the bottom left.

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

36 | P a g e
Create an AF Table
Building the table is similar to building a table in other programs that have simple table building
capabilities.
Tables are held in the AF database to provide contextual information through the Table Lookup
data reference. Tables can provide information about the equipment or process entities or they
can be used to store tag names or other configuration information to be used in AF.

In the PSE, first verify the AF Start up database is selected.

Then navigate to the Library section from the Navigator Panel.

Right-click on the Tables item to select New Table, or click on the

button from the toolbar or from the link in the viewer.

Under the General tab, change the name of the table to “Material Properties”.

Select the Define Table tab and add two (2) rows by right-clicking in the blank area to select
Insert or by selecting the starburst “Insert a row” button ( ) on the right-hand side. Define the
table as follows:
Column Name Value Type Unit Of
Measure
MaterialID String <None>
Density Double kg/m3 (Density)

37 | P a g e
Under the Table tab, enter the following fictitious chemicals:

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

After completing the information in the table, select Check-In to save the information to the
database, then press OK to exit the Table Properties window.

Now, a plus (+) sign appears next to tables, indicating a table exists.

Tables can be created internally (like in this exercise), imported from an external relational or
tabular data source, or linked dynamically to an external relational data source. In this way,
Tables can expose information in maintenance, production planning, or equipment databases
for use by PI client applications. For further information on tables and other advanced AF topics
with ‘Asset Framework: Beyond the Basics’ or with LiveLibrary.

38 | P a g e
Create an AF Enumeration Set

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

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

An enumeration set is a table that correlates numbers with strings. Enumeration sets allow
attributes to be trended based on their numeric string equivalent. Enumeration sets are
analogous to digital state sets used in the Data Archive.
Be sure you are in the AF Startup Database.
From the Navigator Panel, select the Library section.
Right-click on the Enumeration Sets item to create a New Enumeration Set, or click the
button from the toolbar or from the New Enumeration Set link in the
viewer.

Update the name to MaterialID.

Enter the material IDs from the table below as the names of that set:
Value Name
0 AQ4500
1 HC1500
2 WX1200

In the last lesson, a table was created with an Old and New Recipe associated with material id
WX1200.
To distinguish WX1200 produced with either the old or new recipe, we will add two child values
in a level below WX1200:

39 | P a g e
 Value Name
3 WX1200|Old Recipe
4 WX1200|New Recipe

Select the name value associated with WX1200 and right click to create a new Child
Enumeration Set.
Enter the value of Old Recipe or New Recipe. The above information will be displayed in the
enumeration set table.

Repeat creating a Child Enumeration Value for the New Recipe.

Check-In changes to save them to the database.

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

Unit of Measure classes can be modified or the database can be expanded or added to based
on your specific requirements.

In this course, we are restricting our usage to assigning unit of measures to measurements and
exploring Unit of Measures.

Explore the Unit of Measure class Length:

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

Scroll down for the answers…..

41 | P a g e
Canonical UOM – will have the same value of the unit and will have a check mark by the name.

Answers:
1. Meter
2. 1 cm = 0.01 meter; either yard or foot (ft)

42 | P a g e
For future reference, creating new and editing existing UOMs can be made in the database.
Click on Unit of Measure in the PSE Navigator to edit UOMs, UOM classes and UOM groups.

Creating New Editing existing

43 | P a g e
Details on Reference Types

Attribute Data Reference Types

Attributes represent a unique property associated with an asset. The Data Reference Type of an
attribute defines from where to get the data for the attribute. The following Data Reference
Types exist:

• PI Point
• PI Point Array
• Formula
• Table Lookup
• String Builder
• URI Builder

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

Data Reference Types Examples:

44 | P a g e
Formula Data Reference
Formula data reference allows you to perform simple calculations that are evaluated on-the-fly
by the client application (e.g. PI Vision, PI DataLink). Performance issues can arise in case of
long dependency chains (i.e. when a Formula needs to wait for its input values coming from a
chain of other Formulas). The best solution is to move the calculation to Asset Analytics
(discussed in Asset Analytics: Basics course) and use PI Points to store the calculation results.

Earlier, we created a Formula Data References to determine the Volume of a tank based on the
static value of the tank’s capacity and the current level of the tank.

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

Below is the calculation we created earlier in our Tank01 Element.

We can add an additional calculation to the formula to discard values below a specific level (to
potentially take in the deviation error into account).

Verify the database is AF Startup in PSE.

Navigate to Elements in the Navigator Panel, then select the Tank01 element.
Select the Attributes tab in the viewer pane and select the Volume attribute.
Select Settings… from the configuration pane, to add an additional formula to the configuration.

As stated, if the result is less than a specific value, we want a 0 to display due to measurement
tolerance values.

45 | P a g e
In order to use the result of Volume in another formula and eliminate getting a circular reference
error, the initial equation needs to be modified.
• Double click the equation (or Highlight) the original equation to edit the formula.

• Place the cursor at the beginning of the equation and enter M=, so the full equation is
now M=C*L/100

• Now, select New in the Equation section of the Formula Configuration window.

The following equation can be typed into the field or the formula can be input through the use
of the menu structure:

IF M<5 THEN 0 ELSE M

46 | P a g e
To verify your formula is working, select Evaluate while the formula is highlighted.

Accept the formula changes by clicking OK. Then Check In your changes.

47 | P a g e
Substitution Parameters in an Attribute Template
Substitution parameters are variables that be placed 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.

48 | P a g e
Defining the Substitution Parameters
AF supports numerous substitution parameters, which can be used in attribute templates. The
following table lists the ones most commonly used.

Parameter Name Substitution

%Attribute% Name of the attribute that holds this data reference.

%Description% Description of the attribute that holds this data reference.

Name of the element in which the attribute resides. For event

%Element%
frames, this refers to the name of the primary-referenced element.

Name of the parent element of the element in which the attribute

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

Name of the default Data Archive for the computer on which you
create the attribute. The default Data Archive for the computer on
which PSE is running.
%Server% Note: The %Server% parameter does not resolve to the computer
on which the AF database resides. The %Server% parameter can
resolve to a different Data Archive depending on the default in
AF Client.

LiveLibrary Link to substitution parameters in data references.

49 | P a g e
Creating a Template from an Element
So far, in our Velocity Terminal database, an element and attribute have been created. Now we
are moving to one of the advantages of AF – templates.
Verify you have PSE open and the database set to AF Startup.
Select Tank01 from the Browser (verify the Elements section in the Navigator Panel is
selected) and right-click on it to select Convert > Convert to Template (note this does not
delete or change the element, but does set it to a new template).
When converting you have to decide, how the PI Point Data Reference for the Level attribute
should be set. Select Substituted, which will set the PI point name according to a naming
pattern rule.
The default naming rule is %Element%.%Attribute%.%ID%.
Under Suggested Point Name, enter %Element%LI.PV and click Apply. Be sure to deselect
‘Include Tag Creation’.

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

Naming Pattern: %Element%LI.PV

Element Name PI Point Name

Tank02 Tank02LI.PV
Tank03 Tank03LI.PV
Tank04 Tank04LI.PV
etc.

]
Substitution parameters were discussed in the previous lesson.
Substitution parameters can be confusing at times, so we will briefly review their usage in this
template and attribute.

50 | P a g e
In this case, the level tags were previously created with a defined nomenclature: Element Name
including tank number, followed by LI.PV where LI = Level Indicator and PV denotes process
variable. In later lesson, as we create additional Elements with the template, the advantage of
templates and substitution parameters will become apparent.
Check-In the changes.

Let’s verify the template has been created (the check-in screen already verified it, but….)
Navigate to Library → Element Templates → The Tank Template should be visible in the
browser.

51 | P a g e
String Builder Data Reference

The String Builder data reference allows you to use substitution parameters and functions to
manipulate values and output a string.
Below some cases where the String Builder data reference is useful:
✓
Concatenate strings (Element Name + Attribute Name + Value).
✓
Format dates and numbers.
✓
Build paths to elements and attributes.
✓
Parse comments from operators stored in PI tags.
✓
Display element information as an attribute.

Note: Since this data reference supports substitution parameters, when used in a template,
value substitutions takes place at run time.

String Builder allows you to manipulate strings located anywhere in your hierarchy by using the
Related Attribute Values contextual menu (see figure below).

52 | P a g e
Adding to the Hierarchy

Add attributes to the template

Locate your new element template from the Library > Templates > Element Templates
section and change its name to “Tank”.

Under the Attribute Templates tab of the Tank template, add four (4) new attribute templates
by clicking the button from the toolbar.

Attribute Name Default UOM Value Type Data Reference Display

Digits
Enumeration (*)
Product <None> <None>
Sets > MaterialID
kg/L (Density -5
Density Double Table Lookup
class)
Mass kg (Mass class) Double Formula -6
Tank Name <None> String String Builder (*)

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

Product Attribute
When you create the Product attribute, enable the Configuration Item Property.

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

Table Result Column Where

Material Density MaterialID = @Product
Properties

53 | P a g e
After entering the Where clause information, select either ‘Add And’ or ‘And Or’ to complete the
WHERE Clause.
Select OK
Mass Attribute
Configure the Formula data reference for the Mass attribute using the following:

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

Note we are converting the Volume from US gallons to L in this calculation.

Select OK.

54 | P a g e
Tank Name attribute

This attribute will use String Builder as the Data Reference. To configure the attribute for Tank
name.

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

Select OK
the changes.

Now to examine one advantage of using templates.

Go back to the Elements section, select the Tank01 element and look at its attributes.
Pick material “HC1500” in the Value field for the Product attribute enumeration list.

and then click on .

Note the value of the Density attribute. Check the correct tank name.

55 | P a g e
Note: Elements should always be created from a template, even if at the moment of
creation only one asset would make use of that template. This ensures consistency in
the creation and management of AF elements.

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

56 | P a g e
Creating an Element from a Template

In the last lesson, a template was created for tanks.

In this exercise, we will create a new element based on the Tank template.
A new element can be created from either the Library or Element Navigation Path.
From Library:

Navigate from Templates → Element Templates → Right click on Tank → select New
→ Then New Element

From Elements:
Right click on Elements → select New Element

Upon selecting New Element, choose the Tank Element Template

A new element is created in the hierarchy. Note it has the same characteristics as Tank01.
Navigate to the General tab of the new element.
Rename the Element to Tank02.

Update the attributes as indicated below for Tank02. Remember the capacity is a static value
and Product is selected from an Enumeration Set.

Attribute Name Value

Capacity 30,000
Product AQ4500

Check-In the changes and select Refresh.

All attributes should have values after the refresh. (Note values will not exactly match the
screenshot below.)

57 | P a g e
58 | P a g e
Adding Layers to the Hierarchy

Our assignment was to create an AF hierarchy representative of our process which includes the
location of the storage tank.
You are working for Velocity Terminals, a chemical company producing various chemicals. The
company has a number of storage tanks located in different countries that they would like to
monitor. You have been tasked with creating an asset model for these tanks in AF.
Elements can be moved under other elements (then called Parent Elements) in order to
represent a logical hierarchy to be used by your applications
You can move elements around in the Viewer using the mouse and keyboard. This will result in
creating an element reference, or making a copy of the element or simply moving it.

Dragging an element while

Action
pressing the…

Copies the original element under another parent element.

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

Shift Key Moves the element.

Creates an Element Reference. The element will now exist in

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

In retrospect, you realize Tank01 and Tank02 are located in Montreal, Canada. The hierarchy
needs to be updated to indicate the location of the tanks.

From the Elements Browser, right click on Elements → select New Element with <None> for
Element Template → press OK.

59 | P a g e
Navigate to the General tab and rename the element to Montreal. Check in the changes.

Select a tank with the mouse and drag and drop it while holding the Shift key on the keyboard
in order to move the element under the Montreal element so it becomes child element of that
location.

Select the Parent-Child Reference Type for each tank element.

After moving Tank01:

60 | P a g e
Repeat for the second tank. Check-in the changes.

Now that the location is part of the hierarchy, we would like to create a new attribute called Tank
Level Information on the Tank Template with information in a string like the following:
Tank01 is located in Montreal, level is at 99.8%

Approach
1. From the Navigator Panel, select the Library section. Open the Tank Template under
Templates → Element templates.
2. Add the Tank Level Information attribute, value type= String, Data Reference= String
Builder.
3. Use the String Builder Data Reference dialog box to construct the string:

61 | P a g e
 One option to create the requested string:

Note 1: to display the level value in the requested format (one digit after the decimal
point), use the Format (real,format) function in String Builder. Format follows
Performance Equation (PE) style syntax, e.g.: "%3.1f". The number before the decimal
indicates the minimum total number of characters to output, pre-padding with blanks, the
number after the decimal indicates the number of digits to display after the decimal point.

Note 2: You can construct an expression on a single line, using semicolons to separate
its terms. But you can also place each term on its own line, which eliminates the
semicolons and makes the expression structure more apparent (see above).

4. Click on Check-In

5. Navigate to Elements in the Navigator Pane, select Tank01 in the Browser, and select
the Attributes tab. Verify the attribute string for the Tank Level Information is as expected.
If required, correct the String Builder definition. (Be careful with the use of single and
double quotes.)

62 | P a g e
Bulk edits of the AF Hierarchy
PI Builder is an add-in to Microsoft Excel allowing rapid creation and edition of AF objects and
PI points in bulk.
Open Microsoft Excel, to a blank worksheet and select the PI Builder ribbon menu. (An
activation message will appear – X out of the wizard. We have a license but due to the transient
nature of the virtual environments the license is not validated.)
In the Connections section, select the Asset Server (AF Server: PISRV01) and the AF database
(AF Startup).

It maybe necessary to select AF Startup as your Database. To connect to your AF database

click on the dropdown next to the database name.

Now that two tanks have been created for Montreal, we can use those as a base for creating
additional Elements.

Import the tank elements from AF. To do this, select Elements > Find Elements from the PI
Builder ribbon menu, then select the Tank Template to search and find both tanks. (Note: It
maybe necessary to clear the search by clicking the Reset button in the bottom right hand
corner.)

63 | P a g e
Make sure to search child elements (verify ‘All Descendants’=True).

Highlight both Tanks for importing into PI Builder.

Select OK.

64 | P a g e
Select ‘Clear All’. Some columns remain selected as they are required.

65 | P a g e
Under Element, select to import the Template configuration of the element. This is important to
bring all components of the ‘Tank’ template to the individual elements being created.

Then Navigate to the Attribute Columns. From Template ‘Tank’ select Product and Capacity.
All attributes will be copied from the template during the creation of the new elements. Product
and Capacity are static values associated with individual tanks. By adding them to the
spreadsheet, an update can be made to these attributes at the time of creation.

Click OK

66 | P a g e
Modify the Tank 01 and Tank 02 records to Tank03 and Tank 04 respectively.

Verify the Product name matches one of the valid materials from the Material Properties AF
table as shown in the table below. Update the capacity for each tank as shown below.

Name |Capacity |Product

Tank03 10000 HC1500
Tank04 10000 WX1200|Old Recipe

The records are now ready to be exported to AF; which will create two new tanks.
Click on the “Publish” button from the ribbon menu ( ). A dialog for Publishing options will
display – by default the ‘Edit Mode’ is selected. Update it to either ‘Create Only’ or ‘Create and
Edit’. In this case, my preference is to select ‘Create Only’ as I know these should not exist in
this database.

Confirm your work by going to PSE > Elements and pressing the button or the F5 key
on the keyboard.

Let’s verify the product and capacity fields are correct and the data is being updated for Tank03
and Tank04.

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

Putting it into practice:

Add value limits for the attribute level on the Tank Template Attribute.

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

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

68 | P a g e
3. Set the limit traits as follows and click on OK.

69 | P a g e
Use of Categories

About Attribute Categories

Categories can be used to group AF objects like elements, attributes, or tables together to
facilitate the administration of those objects. To add an attribute to a category, simply select one
or more categories from the Categories field of the attribute’s Configuration Panel, or
alternatively write the category name. If that category does not exist yet, a prompt will be shown
to ask if this category should be created.

In this exercise, Attribute categories will be explored.

Open PSE > Change database to OSIsoft Plant.
In the Navigator Pane > select Library.
Open Templates > Element Templates > Generic Tank Template.
Open the Attribute Template tab.

Above the configuration panel, there is a Group By selection. The attributes can be grouped by
Category or Template. In this example, if we select Template, all attributes remain together. As
you develop more involved templates, a derived template could be used and grouping by
templates will allow easy visibility of the template origins.
In this exercise our focus it to group by category.

Upon selecting category, the attributes are grouped into several categories for potentially easier
viewing/editing. In this view, product properties, tank properties and process variables are
grouped together.
Now, move back to the AF Startup Database we are creating for our Velocity Terminal plant. We
are going to add some attribute categories.
Navigate to Library > Templates > Element Templates > Tank.
Select Category to group attributes.
Currently, there are no categories for grouping attributes into any categories.
Categories can be created from Library > Categories > Attribute Categories
Using this method, we will create 3 of the 4 attribute categories we need to group our attributes.

70 | P a g e
Three additional categories to be added are Material Properties, Product Properties, and Tank
Information.
Now we will use another method of creating a category.
Navigate to Library > Templates > Element Templates > Tank > Attribute Templates tab.

Select Level from the attributes, then from the configuration panel, select the browse button on
the right end of categories.

71 | P a g e
Select New Category.

Enter Process Variable as the name of the new Category.

72 | P a g e
Once all categories are created, begin updating the remaining attributes configuration with the
appropriate categories.
Attribute Category
Capacity Tank Information
Density Product Properties
Level Process Variables (already completed – but can be verified)
Mass Product Properties
Product Tank Information
Tank Level Information Tank Information
Tank Name Tank Information
Volume Tank Information
After updating all the attributes with the appropriate category. Group the attributes by category.
Be sure to check-in your changes.

73 | P a g e
Discover Tag Creation

Objectives
• Create a new attribute in a template
• Use AF attributes substitution parameters.
• Demonstrate automatic tag creation.

Problem Description
A new pressure transducer has been installed on every tank at Velocity Terminals. You have to
add a pressure attribute to the tanks in your AF structure; however, the PI points have not been
created.
Velocity Terminals would like you to use a meaningful naming convention for the PI tags created
as part of this project; they would like the tags to be named something like:
Tank01.Pressure.PV
Since our company has sites globally, it is better to use International units for pressure (Bar)

Approach
Add a new attribute to the Tank template, name it Pressure, Categorize it to Process Variable
and use Bar as the default UOM.
Select PI Point as the Data Reference, and click on Settings to configure it.
Data Server defaults to %Server%.
Under Tag Name, in order to match the naming convention they want,
enter %Element%.%Attribute%.PV which results in TankXX.Pressure.PV.
In the future, as Velocity Terminal builds out additional sites, it might be necessary to include
the site/location which is represented as %..\Element%-%Element%.%Attribute%.PV results in
Montreal-TankXX.Pressure.PV

Since the tags have not been created, check Tag Creation.

Tip: You could configure the tag settings (PointSource, InstrumentTag,Location codes, etc.)
from the Tag Creation Settings dialog window or import the settings of a working tag by
selecting the ellipsis (…).

74 | P a g e
Check-In the Tank Template with the Pressure attribute added.

Navigate to Elements → Elements → Montreal → Tank01 → Attributes.

What value is shown for the Pressure attribute?

“PI Point Not Found”

Now, let’s create the PI point, by right clicking on Montreal → select Create or Update Data
Reference. A window will indicate when the PI Point creation is complete, close the window.

Refresh the display.

Now, what is the value shown for the Pressure attribute for any of the Tanks?
All should show Pt Created.

Note: In this example, we took the default settings associated with PI Point creation. By default,
there is no configuration associating the PI Point to any interface for data.

75 | P a g e
Visualizing Velocity Terminal Data with PI Vision
Activity Objectives
• Create a PI Vision display with tank data (AF database: Velocity Terminals)
• Incorporate objects with current data (trend, value object, gauge)
• Incorporate a tank from the Graphic Library
• Asset swap in PI Vision displays

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

(or http://pisrv01.pischool.int/PIVision)

Note: The first time PI Vision is started can take a few minutes.
The homepage provides an overview with thumbnails of the displays, which have been
prepared for the training.

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

3. The search pane displays search paths for elements in the AF databases and for tags in
Data Archive.
4. Expand the asset structure to navigate to the Tank01. Select AF database AF Startup
and navigate to Montreal > Tank01. Select Tank01 to get the attributes for that tank.

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

76 | P a g e
6. From within the Trend, right click to select Configure Trend. A menu will appear on the
right-hand side of the screen. From the menu, various options exist to format the trend,
values, default time range, and trace options.

7. Click on the time selector at the bottom and switch time display range to one hour.

77 | P a g e
8. Click on the Graphic Library icon . Navigate to Tanks then select a tank and drag it
to the display.

78 | P a g e
9. Navigate back to Assets , select the Value object . Drag Tank Name (from the
attribute list) to the top of the tank picture.

79 | P a g e
10. From the right mouse button menu of the Value object, select Format Value.

Uncheck Label, Units and timestamp. Change Value color to black and font size to 36.

11. Now position a value object for the Product attribute in the right bottom corner. Format in
the same manner as the Tank name with the exception of font size of 18.

80 | P a g e
12. From the object list, select the Vertical Gauge object . Drag Level to the center of the
tank picture. Use Format Gauge (by right clicking on the gauge) to change the
appearance by removing the label and value.

13. Click on the Save icon on top right corner. Save display as Velocity Terminals Tank.

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

81 | P a g e
15. Use the time control at the bottom to change the display ranges. Use the left arrow to
step through past time periods.

16. Another means of changing the time range is from within the trend. Switch to Read Only
by deselecting the Edit Mode . Now, position the cursor in the bottom area of the
trend and drag ( ) the cursor back and forth to switch the time range.

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

To save your changes, click on the Save icon . To save the modified display under
another name select Save As from the dropdown next to the Save button and save
under another name.

19. To view Saved displays, navigate Home by selecting . If the display was
saved, it should be present in the list.

82 | P a g e
Summary Lesson: Best Practices - Written
The following recommendations provide some guidelines on how to best setup your AF asset
structure based on experience from existing AF installations.
Be aware that in real life you cannot follow all these recommendations!

• All elements should be based on a template

Even if the template has no attributes in the beginning
Easier maintenance

• All elements at the same level should be of the same type

Enterprise at the first level, Site the second level, Area the third, etc.
Easier use of relative references from child-elements

• Do not only consider Bottom-Up approach

Try to achieve a well-designed structure, plan for the usefulness of the
AF model

• Categories for elements attributes and analyses

Organizes large numbers of attributes/elements
A fast way to search for elements and attributes

• Always set the unit of measure explicitly

PI Point attributes: set source unit for the tag
Formulas: set units for all variables and the result
Analyses: use the Convert() function
Avoid defaults

• Use inherited templates (covered in Asset

Framework: Beyond the Basics)
Allows Flexibility but keeps the standardization

83 | P a g e
• Build Different Views specific for your users
(covered in Asset Framework: Beyond the
Basics)
Use element references

• Use Enumerations
Limit the choices that
can be entered in attributes

• Use Hierarchies of Attributes

Group details or aggregations on a different level

• Use all Data References

Many options with Table Lookup and for String Builder

• Keep relational data in relational database

Link AF Tables to results and views
Use Cache and Parameters

84 | P a g e