Guide to Substitution Syntax for Data

References in PI AF and PI Event

Frames

Version 2

October 2015
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 Introduction

Table of Contents
Introduction ............................................................................................... 4
Purpose ..................................................................................................................... 4
PI Point Data Reference ........................................................................... 4
Tag Name .................................................................................................................. 4
Mapping Using Substitution Strings ................................................................................................. 4
Mapping in Using a Table .............................................................................................................. 12
Using PI Builder ............................................................................................................................. 14

Formula Data Reference ......................................................................... 16

General Syntax ........................................................................................................ 16
Legend for Figures (18 through 24) ......................................................................... 16
Referencing Attributes in the Same Element ................................................................................. 17
Referencing Attributes in the Other Elements................................................................................ 17

Table Lookup Data Reference ................................................................ 20

Substitution Syntax .................................................................................................. 20
String Builder Data Reference (PI AF 2.6 or later) ................................ 24
PI Event Frames ...................................................................................... 28
Data from Elements ................................................................................................. 28
PI Point Data Reference ................................................................................................................ 28
String Builder Data Reference ....................................................................................................... 30
Formula Data Reference ................................................................................................................ 35
Data from other Event Frames ................................................................................. 36
String Builder Data Reference ....................................................................................................... 36
Formula Data Reference ................................................................................................................ 39

OSIsoft, LLC. 2 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 Introduction

Revision History

Version Date Comments Author

Version 1 1/7/2015 Original draft Ales Soudek

Updated for AF 2015 (AF 2.7)

Version 2 9/29/2015 - String Builder use in Event Frames Ales Soudek
- Additional syntax for Table Lookup

OSIsoft, LLC. 3 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 Introduction

Introduction
Purpose
The substitution parameters in PI Analysis Framework (PI AF) and PI Event Frames (PI EF) are
very powerful for creating a PI AF structure that can leverage the power of the templates and is
more maintainable. Since I could not find a user-focused document, which shows practical
examples of the substitution syntax and examples for the different Data References in PI AF, I
decided to compile one. This document also covers the special syntax used for PI EF.
This document discusses the following:
 PI Point
 Formula
 Table Lookup
 String Builder
 Event Frames

PI Point Data Reference

The PI Data Reference in PI AF requires the user to enter either a Tag name or an Attribute
reference that has a PI Data Reference defined. Details of these approaches are below.

Tag Name
If the site has adhered to a tag naming convention, then a substitution string can be set up in
the Attribute of the Element Template. This is the best scenario and least amount of work to
maintain and rollout (see Mapping Using Substitution Strings Section below). Unfortunately,
in most cases this is not possible since either there are too many different naming conventions
or there are no naming conventions at all. (See Mapping Using a Table and Using AF
Builder Sections below)
It is up to the reader to decide which approach they prefer and best fits their situation.

Mapping Using Substitution Strings

The syntax is as follows:
 Strings enclosed between % and % will substitute the name of the entity. So
%Element% returns the name of the Element containing this Attribute, %Attribute%
returns the name of the Attribute. More possible substitution entities are found in the
PI AF help file under PI data reference or some selected examples are shown in Table
1 below.
 | symbol means the string following is an Attribute, if the Attribute is at the same level
as the current Attribute, you do not need the | symbol. For use in the Tag Name this
would be combined with the use of the @ symbol. See the below.

OSIsoft, LLC. 4 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Point Data
Reference

 @ symbol means return the value of the Attribute. For example, %@.|PITagName%
means replace with the value of the child Attribute called PITagName.
 ..\ symbol means go to the parent of the current Element. For example, %..\Element%
means replace with the name of the parent Element.

Examples:
The following shows examples of using the substitution syntax for PI tag naming:
 Default setting
 Getting value of another Attribute
 Using Element hierarchy
 Substituting Server name

Syntax Examples
Default Setting
%Element%.%Attribute%

Example:
Figure 1 shows the default setting when creating a PI Point Data Reference. The
substitution string is %Element%.%Attribute% . The substitution will use the name of the
current Element and the name of the current Attribute. In this example, Element name is
P-101 and the Attribute name is Temperature. The resulting PI tag name is P-
101.Temperature, see Figure 2.

Figure 1

OSIsoft, LLC. 5 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Point Data
Reference

Figure 2

Getting a value from another Attribute

%@<Attribute Name>|<Child Attribute Name>%

Example:
You can also use the substitution parameters to get the value of a particular Attribute. The
example below, in Figure 3, shows the syntax for getting a value from a child Attribute in
the same Element. The substitution string is %@Flowrate|PI Tag% . This means take
the value of the child Attribute PI Tag of the Attribute Flowrate. Figure 4 shows the
resulting substitution.
The value of the child Attribute PI Tag of the Attribute Flowrate is P-101.Operation,
therefore this is the name of the PI Tag that gets substituted.

Figure 3

OSIsoft, LLC. 6 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Point Data
Reference

Figure 4
An alternate syntax to achieve the same result as above is to use following %@.|PI Tag%
for the Attribute Flowrate. The . means current object, which is the Attribute, and the |
symbol means Attribute. So since the current object is an Attribute, the syntax says
replace with the value of the child Attribute PI Tag of the current Attribute, in the example
above, Figure 4, this would be the FlowRate.

Using Element hierarchy

%@..\..\|<Attribute Name>%.%@..\|<Attribute Name>%

Example:
This example shows how to use values of Attributes from the Parent Element in the
naming of the PI Tag. Figure 5 shows the substitution string syntax. In this example, the
substitution string is %@..\|country%.%@..\|city%.%@..\|entity%.%@asset
id%.NetVolume
Taking the first part of the string, %@..\|country% , the @ symbol means take the value
of, the ..\ symbol means go up one level in the Element hierarchy, the | symbol means
Attribute, and country is the name of the Attribute. The parent Element is Brasil 2 (see
Figures 6 and 7), which has an Attribute named country, whose value is Brasil, therefore
the substitution string %@..\|country% is substituted with Brasil. Similarly for the
%@..\|city% and %@..\|entity% substitution strings. The final part of the substitution
string %@asset id%.NetVolume use the value of the Attribute asset id in the current
Element and append the .NetVolume string. The final substitution result is shown in
Figure 6, which is
Brasil.Porto Alegre.MPC Branch LP Terminal.1-7.NetVolume

OSIsoft, LLC. 7 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Point Data
Reference

Figure 5

Figure 6

Figure 7

OSIsoft, LLC. 8 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Point Data
Reference

Substituting Server name

%Server%

Example:
When configuring the PI Point Data Reference the default setting for the PI Server name is
%Server%. This will be substituted by the current PI Archive Server name.
Note: The problem with this approach is that if the AF database is exported and then
imported to a new system with a new PI Archive Server, the old PI Archive Server name
will still be in the PI Point Data Reference settings of the Attributes. So one of my maxims
- never use default settings, always change them explicitly, because you never know when
they might cause you headaches.
If you encounter this situation, the following approaches will place the correct PI Archive
Server name when you move the PI AF to a new system:
 Method 1 - Import all the Elements into an Excel Worksheet using PI Builder. In the
settings, make sure to select the DataReference and ConfigString options. Do a
global replace on the old server name with the new server name. Then export the
Elements to the PI AF database. (See PI Builder User Manual). You will need the
following settings in PI Builder, see Figure 8 below.

Figure 8

 Method 2 - If the PI AF database has already been moved to the new server.
Import all the Elements into an Excel Worksheet using PI Builder as above but
excluding the DataReference and ConfigString options. Then using PI Builder delete
the Elements in the AF database (Note – only do this if all the Elements have an
Element Template, and you have not modified any values in the Element Attributes
outside of the Element Templates). Then recreate the Elements using PI Builder.
You will need the following settings in PI Builder, see Figure 9 below.

OSIsoft, LLC. 9 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Point Data
Reference

Figure 9

 Method 3 - Set up an Element and Attribute that will contain name of the PI Archive
Server (Also remember to convert this Element to a Template. Another one of my
maxims – every Element should be associated with a Template). This is my preferred
approach. The PI Point Data References in the Attributes are then set up with a different
substitution string to the default %Server%. (Remember my maxim from above – never
use default settings. See the example below). Then to change the server name in all
the PI Point Data References simply change the name in this Attribute with the
appropriate PI Archive Server name. Note: this only works for AF 2.6 and later. The
example in Figure 10 shows the Element named PI Server with an Attribute called
Name which is of a string value type. The value of the Name Attribute is the name of
the PI Archive Server.

Figure 10
The syntax for the substitution string in the PI Point Data Reference, shown in Figure 11,
is %@\PI Server|Name% . The @ symbol means take the value of, the \PI Server
means from top of the Element hierarchy use the Element named PI Server, the |Name
means use the Attribute called Name.

OSIsoft, LLC. 10 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Point Data
Reference

Figure 11
Table of useful substitution parameters for naming PI tags:

Substitution Parameter Description

%Attribute% Replaced with the name of the current Attribute

%..|Attribute% Replaced with the name of the parent Attribute of

the current Attribute containing the PI Point Data
Reference

%Element% Replaced with the name of the current Element

%..\Element% Replaced with the name of the parent Element of

the current Element

%Description% Replaced with the description of the current

Attribute

%ParentAttributeDescription% Replaced with the description of the parent

Attribute of the current Attribute containing the PI
Point Data Reference

%ElementDescription% Replaced with the description of the current

Element

%ParentElementDescription% Replaced with the description of the parent

Element of the current Element

%Server% Replaced with the current default PI Server

OSIsoft, LLC. 11 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Point Data
Reference

Mapping in Using a Table

This approach requires the creation of an Attribute/PI tag naming mapping table in PI AF
and then using two Attributes for each value – one to lookup the name of the PI tag from
this table and the second one to use the value of the first Attribute in a substitution string
for the PI Point Data Reference. The benefit of this approach is that this can be
templatized and all the tag naming is managed in a table that is part of the AF database.
The table can be created externally and then imported or linked to PI AF.
There are a couple of negatives to consider with this approach.
1. The Tables in PI AF are not recommended to have more than about 10,000 rows.
Performance may be adversely affected as a Table grows bigger.
2. The user needs to maintain the mappings in the Table(s)

Syntax Examples
%@.|<Attribute Name>%

Example:
The example below can be set up in different ways, but the general syntax is the same.
Steps (the naming for Attributes and Elements in the steps relate to the example in
the Figures below
1. In the Template, create an Attribute, Power Draw and a child Attribute TagName, and set
the Date Reference to PI Point for the parent Attribute. The setting for the tag name is
%@.|TagName%
The syntax meaning of the above substitution string is as follows. Substitute the value of
what is between the % and % symbols. The @ means use the value in the Attribute
named Power Draw|TagName, where the Power Draw is the parent Attribute and
TagName is the child Attribute. See Figure 12.
2. Set the Data Reference for the child TagName to Table Lookup. The setting for the
config string is
ParentName = '%..\..\..\..\Element%' AND ElementName = '%Element%' AND
AttributeName = '%..|Attribute%'
The syntax meaning of the above string is as follows. Compare the ParentName column
to the Element name 4 levels up the hierarchy, and the ElementName column with the
Element containing the Attribute Power Draw, and the AttributeName column with the
parent Attribute name (in this case Power Draw which is the parent Attribute of the
TagName child-Attribute). See Figure 13.
3. Figure 14 shows the table details to support this structure
4. Figure 15 shows the resulting Element hierarchy and substitution results for the
Attribute

OSIsoft, LLC. 12 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Point Data
Reference

Figure 12

Figure 13

Figure 14

OSIsoft, LLC. 13 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Point Data
Reference

Figure 15

Using PI Builder
This approach is identical to the one in the Section above, Mapping Using a Table, with
the exception that the child Attribute does not have a Data Reference. The values for the
child Attribute are populated using Excel and the PI Builder. The advantage of this is that
you can populate the names of the PI tags in Excel and you will not break the Element
inheritance from the Template. If you were to enter the PI tag names directly into the
Element Attribute PI Point Data Reference, then the inheritance from the Template is
broken. Another one of my maxims – never break Template inheritance if you can help it.
It will make any changes to configuration much easier later.

Syntax Examples

Example:

This example uses a Meter Template and a parent Attribute Flow which has a child
Attribute TagName to illustrate the use of the PI Builder to set the child Attribute TagName
values for all the meter Elements. In PI Builder, select the Find Elements in the menu,
select the Meter Template, and then select only the check boxes shown in Figure 16. This
will provide a simple list of all meter Elements and only the child Attribute Flow|TagName
for entering the PI tag names.

OSIsoft, LLC. 14 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Point Data
Reference

Figure 16

The result will be as shown in Figure 17. Then enter the PI tag names in the highlighted

area and click Publish button in the ribbon.

Figure 17

OSIsoft, LLC. 15 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 Formula Data
Reference

Formula Data Reference

The Formula Data Reference gives the user the ability to create calculations based on other
Attributes in the same AF Database. These calculations are performed on demand only when a
PI AF client tool asks for the value of the Attribute, which has this Data Reference.

There are two possible situations:

 Referencing Attributes in the same Element
 Referencing Attributes in other Elements

General Syntax
The syntax for the Formula settings is:
A={Description};[A] where {Description} would be the string that is shown in the Figures below
under the Description column.
So for example, in Figure 18 below an Attribute named Inherits from C has the Description |C
(about half way down the Figure), then the settings string for the Formula would be
A=|C;[A]

Legend for Figures (18 through 24)

The screen captures in the Figures show three columns: Name, Value, and Description.
Name
Attribute name, indicating whether it is a value or inherited using the Formula from another
Attribute. There are also three templates; Base Template, A Template, and B Template.
The Attributes are categorized according to which template they are defined in. In Figure
18, the Element is created from the B Template, which inherits from the A Template, which
in turn inherits from the Base Template.
Value
This is the value that is returned by the Formula or a manually input value.
Description
If this is a number, then this Attribute does not contain the Formula Data Reference and the
value is manually input (it could be also coming from another data reference). The syntax
for the Settings string for the Formula Data Reference is described in the General Syntax
section above.

OSIsoft, LLC. 16 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 Formula Data
Reference

Referencing Attributes in the Same Element

Syntax Examples

Figure 18

Referencing Attributes in the Other Elements

Syntax Examples
This example uses the Elements named and configured as shown in Figure 19.

OSIsoft, LLC. 17 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 Formula Data
Reference

Figure 19

Figure 20

Figure 21

Figure 22

OSIsoft, LLC. 18 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 Formula Data
Reference

Figure 23

Figure 24

OSIsoft, LLC. 19 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 Table Lookup Data
Reference

Table Lookup Data Reference

The Table Lookup Data Reference gives the user the ability to create views of data from
external databases for use in the PI AF Database. Typically, these would be things like
equipment specifications, material properties, etc. The values in these PI AF Tables can then
be retrieved from an Element Attribute using a SQL Select statement. The syntax is as follows:
SELECT <Table Field Name1> FROM <Table Name> WHERE <Table Field Name2> = %Element%
AND <Table Field Name3> = %Attribute%
The SQL statement can also use the OR and ORDER BY clauses.

Substitution Syntax
Example:
This example shows how to use the look up to return the value of the PITag field in the PI
AF Table Table1 by comparing the value of an Attribute PlantCode of a grand-parent
Element in the hierarchy to the AttributeValue field value in the Table. The Element
GrandParent1 has an Attribute PlantCode (Figure 25). The child Element Element1 has
the Table Lookup data reference. The Select statement is
SELECT PITag FROM Table1 WHERE ElementName = '%Element%' AND AttributeValue =
@[..\..\|PlantCode]

There are two substitutions in the Select statement above: %Element% and
@[..\..\|PlantCode], the explanation of these is below.
ElementName = %Element%
Means the name of the Element is substituted into the comparison (%Element%) and then
compared to the value in the ElementName field in the PI AF Table Table1, see Figure
27.
AttributeValue =@[..\..\|PlantCode]
The @ sign means get the value of an Attribute not the name of it. In this Data Reference
the Attribute name to locate must be enclosed inside [ ]. (If the Attribute PlantCode
existed in the same Element, then you do not need to use the [ ] symbols, and all you
would write is @|PlantCode). The ..\..\ signifies go up two levels of Elements in the
hierarchy, so in this example starting at the Element1 go two levels up to Element
GrandParent1. Then the last part of the syntax is |PlantCode , the | signifies that the text
following is an Attribute name, in this case PlantCode. In this case, the value is DEF as
shown in Figure 26.

OSIsoft, LLC. 20 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 Table Lookup Data
Reference

Figure 25

Figure 26

Figure 27

OSIsoft, LLC. 21 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 Table Lookup Data
Reference

Other useful substitution parameters:

Syntax Meaning
%Element% Returns the name of the Element of
the current Attribute
%\Element% Returns the name of the root Element
from the hierarchy of the Element of
the current Attribute
%..\Element% Returns the name of the parent
Element of the Element of the current
Attribute
%ElementDescription% Returns the description of the Element
of the current Attribute
%Attribute% Returns the name of the Attribute
%..|Atribute% Returns the name of the parent
Attribute of the current Attribute
%System% Returns the name of the PI AF Server
%Database% Returns the name of the PI AF
database

Example:
This example shows a judicious naming of the Attributes in the Element Template and the
column names of the Table so that the query can be made very generic. In this example
the Table has three columns; Name, Value, and Value1. The Attributes in the Element
Template are named Value and Value1. Then the same query is used in both Attributes
with the syntax as follows.
Select [%Attribute%] From <Table Name> Where ‘%Attribute%’ = ‘Attribute%’

Figure 28

OSIsoft, LLC. 22 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 Table Lookup Data
Reference

Figure 29

OSIsoft, LLC. 23 of 40
 A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 String Builder Data
Reference (PI AF
2.6 or later)

String Builder Data Reference (PI AF 2.6 or later)

Its purpose is to allow the user to combine strings together, get values from Attributes that are
strings or numeric, and use substitution parameters to get things like the Element name. This
can be very useful for obtaining system parameters like the PI system name or values from
parent Elements.

Benefits:
 This is useful for getting a string or a numeric value type from other Element Attributes, where
the Attributes do not need to have a PI Point Data Reference.
 Create a string by concatenating multiple values from referenced Element Attributes and other
text.
 Can get the name of the Element (and its parent Elements). This is a useful technique for
making reporting using SQL statements easier and more efficient. I recommend using this
approach.
Limitations:
 Does not perform Unit of Measure conversions
 Does not perform any calculations, but there are some basic formatting and string manipulation
functions

Syntax Examples

Return the name of Element

“%Element%”

Example:
Returns the name of the Element of the current Attribute.

Figure 30

OSIsoft, LLC. 24 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 String Builder Data
Reference (PI AF
2.6 or later)

Returning a value from an Element Attribute

|<Attribute Name>

Example:
Returns the value of Attribute DVCode in the same Element.

Figure 31

Returning a value from a parent Element Attribute

..\|<Attribute Name>

Example:
Returning the value of Attribute PlantCode that belongs to the parent Element.

Figure 32

OSIsoft, LLC. 25 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 String Builder Data
Reference (PI AF
2.6 or later)

Figure 33

Concatenating values and strings

“The parent element %..\Element% parent code value “;..\|<Attribute Name>

Example:
Ccreating a string by concatenating the name of the parent Element and the value of the
Attribute PlantCode of the parent Element. The ; is the concatenation symbol.

Figure 34

Other useful substitution parameters:

Syntax Meaning
%Element% Returns the name of the Element of
the current Attribute
%\Element% Returns the name of the root Element
from the hierarchy of the Element of
the current Attribute
%..\Element% Returns the name of the parent
Element of the Element of the current
Attribute

OSIsoft, LLC. 26 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 String Builder Data
Reference (PI AF
2.6 or later)

%ElementPath% Returns the path from the top level

Element to the referenced Element,
e.g. Asset1\Asset2\Asset3
%ElementDescription% Returns the description of the Element
of the current Attribute
%Attribute% Returns the name of the Attribute
%..|Atribute% Returns the name of the parent
Attribute of the current Attribute
%Description% Returns the description of the current
Attribute
%System% Returns the name of the PI AF Server
%Database% Returns the name of the PI AF
database

OSIsoft, LLC. 27 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Event Frames

PI Event Frames
Event Frames can have Attributes that get data from other Event Frames, when the Event
Frames are associated with each other as parent/child. The Attributes can also get data from
the referenced Elements.

Data from Elements

There are three ways of getting data from a referenced Element: PI Point, String Builder, and
Formula Data References. Benefits and limitations of each as well as examples of the syntax
are described in the sections below.

PI Point Data Reference

Benefits:
 This is useful for getting data at different aggregations from the referenced Element’s
Attribute. (Like maximum, minimum, average, etc.)
 Will perform Unit of Measure conversions. The Attributes in the Element and the Event
Frame must be of the same class.
 Passes time context
Limitations:
 The Attribute in the Element must be a PI Point Data Reference.

Syntax Examples
An Event Frame returning a value from referenced Element
.\Elements[.]|<Attribute Name>

Example:
Event Frame returning the maximum value of the Element Unit1 for the Attribute Power
Used.

Figure 35

OSIsoft, LLC. 28 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Event Frames

Figure 36

Use the syntax in the above example when there is only one referenced Element. It is
possible and desirable in some situations to have more than one referenced Element for
an Event Frame. In such cases, different search criteria need to be used to get data from
the desired Element. The most useful criteria are:
 Index (1 based)
 Name (can use wild cards)
 Template (cannot use wild cards, must be explicit)
 Category (cannot use wild cards, must be explicit)

Example syntax for more than one referenced Element:

Syntax Meaning
.\Elements[@Index = 3]|Attr1 Get the value Attribute Attr1 from the
3rd referenced Element
.\Elements[@Name = Pump*]|Attr1 Get the value Attribute Attr1 from the
first referenced Element whose name
starts with Pump
.\Elements[@Template = Process Units]|Attr1 Get the value Attribute Attr1 from the
first referenced Element whose
Template is Process Units
.\Elements[@Category = Rotating Equip]|Attr1 Get the value Attribute Attr1 from the
first referenced Element whose
Category is Rotating Equip
.\Elements[@Category=Rotating Get the value Attribute Attr1 from the
Equip][@Name = Pump*]|Attr1 first referenced Element whose
Category is Rotating Equip and name
starts with Pump

Note: - You can combine several search criteria together in one call as shown by the last
row in the table above.

An Event Frame returning a value from referenced Element’s child Element

.\Elements[.]\[@Name=P-1*|<Attribute Name>

OSIsoft, LLC. 29 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Event Frames

Note: - The syntax above is using the Name as the search criteria for the child Element
starting with P-1, but you can also use the Index, Template, and Category.

Example:
Event Frame returning the maximum value of the Unit1 child Element whose name starts
with P-1 for the Attribute Pressure. The Event Frame has Unit1 as the referenced
Element.

Figure 37

Figure 38

String Builder Data Reference

Benefits:
 This is useful for getting a string or a numeric value type from the referenced Element’s
Attribute, where the referenced Element’s Attribute does not need to have a PI Point
Data Reference.
 Create a string by concatenating multiple values from referenced Element Attributes and
other text.
 Passes time context – the end time of the Event Frame

OSIsoft, LLC. 30 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Event Frames

 Can get the name of the referenced Element (and its parent Elements). This is a useful
technique for making reporting using SQL statements easier and more efficient. I
recommend using this approach.
Limitations:
 Does not perform Unit of Measure conversions
 Does not perform any aggregation or calculations

Syntax Examples
An Event Frame returning the name of a referenced Element
“%Element%”

Example:
Event Frame returning the name of the referenced Element.

Figure 39

An Event Frame returning a value from a referenced Element

\”%Element%”|<Attribute Name> (AF 2.6 or earlier)

Example:
Event Frame returning the value of Attribute Mass from the referenced Element.

Figure 40

\Elements[.]|<Attribute Name> (AF 2.7 or later)

OSIsoft, LLC. 31 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Event Frames

Example:
Event Frame returning the value of Attribute Mass from the referenced Element.

Figure 41

An Event Frame returning a value from a referenced Element where the

Event Frame Attribute has the same name as the Attribute in the
referenced Element
\”%Element%”|%Attribute% (AF 2.6 or earlier)

Example:
Event Frame returning the value of Attribute Volume from the referenced Element. The
Attribute in the Event Frame is also name Volume.

Figure 42

Figure 43

OSIsoft, LLC. 32 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Event Frames

\Elements[.]|%Attribute% (AF 2.7 or later)

Example:
Event Frame returning the value of Attribute Mass from the referenced Element.

Figure 44

An Event Frame returning a value and a name from a referenced Element

and creating a concatenated string
“The element named %Element% has a mass of “;\”%Element%”|<Attribute Name>
(AF 2.6 or earlier)

“The element named %Element% has a mass of “;.\Elements[.]|<Attribute Name>

(AF 2.7 or later)

Example:
Event Frame creating a string by concatenating the name and description of the
referenced Element and the value of the Attribute Mass of the referenced Element. The ;
is the concatenation symbol.

Figure 45

Other useful substitution parameters:

Syntax Meaning
%ElementPath% Returns the path from the top level
Element to the referenced Element,
e.g. Asset1\Asset2\Asset3

OSIsoft, LLC. 33 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Event Frames

%ElementDescription% Returns the description of the

referenced Element
%..\Element% Returns the name of the referenced
Element parent Element. If there is no
parent Element a blank is returned.
%StartTime% Returns the start time of the Event
Frame
%EndTime% Returns the end time of the Event
Frame
%System% Returns the name of the PI AF Server
%Database% Returns the name of the PI AF
database

An Event Frame returning a value from referenced Element’s child Element

.\Elements[.]\[@Name=A*|<Attribute Name>

Note: - The syntax above is using the Name as the search criteria for the child Element
starting with the letter A, but you can also use the Index, Template, and Category.

Example:
Event Frame returning the value of the Attribute Mass from the child Element Asset1 of
the referenced Element Asset2.

Figure 46

OSIsoft, LLC. 34 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Event Frames

Figure 47

Formula Data Reference

Benefits:
 This is useful for getting a numeric value type from the referenced Element’s Attribute,
where the referenced Element’s Attribute does not need to have a PI Point Data
Reference.
 Passes time context – the end time of the Event Frame
Limitations:
 Only works for numeric values

Syntax Examples
An Event Frame returning a value from a referenced Element
A=.\Elements[.]|<Attribute>;[A]

Example:
Event Frame returning the value of Attribute Ratio from the referenced Element.

Figure 48

Use the syntax in the above example when there is only one referenced Element. It is
possible and desirable in some situations to have more than one referenced Element for
an Event Frame. In such cases, different search criteria need to be used to get data from
the desired Element. The most useful criteria are:

OSIsoft, LLC. 35 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Event Frames

 Index (1 based)
 Name (can use wild cards)
 Template (cannot use wild cards, must be explicit)
 Category (cannot use wild cards, must be explicit)

Example syntax for more than one referenced Element:

Syntax Meaning
A=.\Elements[@Index = 3]|Attr1 Get the value Attribute Attr1 from the
3rd referenced Element
A=.\Elements[@Name = Pump*]|Attr1 Get the value Attribute Attr1 from the
first referenced Element whose name
starts with Pump
A=.\Elements[@Template = Process Get the value Attribute Attr1 from the
Units]|Attr1 first referenced Element whose
Template is Process Units
A=.\Elements[@Category = Rotating Get the value Attribute Attr1 from the
Equip]|Attr1 first referenced Element whose
Category is Rotating Equip
A=.\Elements[@Category=Rotating Get the value Attribute Attr1 from the
Equip][@Name = Pump*]|Attr1 first referenced Element whose
Category is Rotating Equip and name
starts with Pump

Note: - You can combine several search criteria together in one call as shown by the last
row in the table above.

Data from other Event Frames

There are two ways of getting data from child Event Frame: String Builder, and Formula
Data References. You can only get data from Event Frames that are in a parent-child
relationship. Benefits and limitations of each as well as examples of the syntax are
described in the sections below.

String Builder Data Reference

Benefits:
 This is useful for getting a string or a numeric value type from the referenced Element’s
Attribute, where the referenced Element’s Attribute does not need to have a PI Point
Data Reference.
 Create a string by concatenating multiple values from referenced Element Attributes and
other text.
 Passes time context – the end time of the Event Frame

OSIsoft, LLC. 36 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Event Frames

 Can get the name of the referenced Element (and its parent Elements). This is a useful
technique for making reporting using SQL statements easier and more efficient. I
recommend using this approach.
Limitations:
 Does not perform Unit of Measure conversions
 Does not perform any aggregation or calculations

Syntax Examples

A child Event Frame returning a parent Event Frame name

"%..\EventFrame%"

Example:
Event Frame returning the name of the parent Event Frame.

Figure 49

Other useful substitution parameters:

Syntax Meaning
%Template% Returns the name of the Event Frame
Template
%EventFrame% Returns the name of the Event Frame
%..\EventFrame% Returns the name of the parent Event
Frame of the current Event Frame. If
there is no parent Event Frame a blank
is returned.
%EventFrameDescription% Returns the Event Frame description
%StartTime% Returns the start time of the Event
Frame
%EndTime% Returns the end time of the Event
Frame
%System% Returns the name of the PI AF Server
%Database% Returns the name of the PI AF
database

OSIsoft, LLC. 37 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Event Frames

A child Event Frame reading a parent Event Frame value

..\|<Attribute>

Example:
Event Frame returning the value of Attribute Limit from the parent Event Frame.

Figure 50

Figure 51

A parent Event Frame reading a child Event Frame Attribute value

.\EventFrames[@Template=<ChildEFName>]|<Attribute>

Note: - The syntax above is using the Template as the search criteria for the child
Element, but you can also use the Index, Name, and Category.
Note: - You must name the child Event Frame to prevent getting an error message.

Example:
Event Frame returning the value of Attribute Area from the child Event Frame whose
Template is ChildEvent.

OSIsoft, LLC. 38 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Event Frames

Figure 52

Formula Data Reference

Benefits:
 This is useful for getting a numeric value type from the child Event Frame’s Attribute,
where the child Event Frame’s Attribute does not need to have a PI Point Data
Reference.
 Passes time context – the end time of the Event Frame
Limitations:
 Only works for numeric values

Syntax Examples

A child Event Frame reading a parent Event Frame Attribute value

A=..\|<Attribute>;[A]

Example:
Event Frame returning the value of Attribute Rate from the parent Event Frame.

Figure 53

OSIsoft, LLC. 39 of 40
A Guide to Substitution Syntax for Data References in PI AF and PI Event Frames – Version 1 PI Event Frames

Figure 54

Note: - In this example the value in the attributes for the parent and child Event Frames
are not the same. The reason is that in the parent Event Frame the attribute is configured
to get the End Time value from the referenced Element's Rate Attribute, and the End
Times for the parent and child Event Frames are different. Hence, the End time of the
Event Frame is passed to the call for the data.

A parent Event Frame reading a child Event Frame Attribute value

.\EventFrames[@Template=<ChildEFName>]|<Attribute>

Note: - The syntax above is using the Template as the search criteria for the child
Element, but you can also use the Index, Name, and Category.
Note: - You must name the child Event Frame to prevent getting an error message.

Example:
Event Frame returning the value of Attribute Value from the child Event Frame.

Figure 55

OSIsoft, LLC. 40 of 40