PI System Explorer

User Guide

Part of AVEVATM PI Server 2023

© 2015-2023 by AVEVA Group Limited or its subsidiaries. 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 AVEVA
Group Limited. No liability is assumed with respect to the use of the information contained herein.
Although precaution has been taken in the preparation of this documentation, AVEVA assumes no responsibility
for errors or omissions. The information in this documentation is subject to change without notice and does not
represent a commitment on the part of AVEVA. The software described in this documentation is furnished under
a license agreement. This software may be used or copied only in accordance with the terms of such license
agreement. AVEVA, the AVEVA logo and logotype, OSIsoft, the OSIsoft logo and logotype, ArchestrA, Avantis,
Citect, DYNSIM, eDNA, EYESIM, InBatch, InduSoft, InStep, IntelaTrac, InTouch, Managed PI, OASyS, OSIsoft
Advanced Services, OSIsoft Cloud Services, OSIsoft Connected Services, OSIsoft EDS, PIPEPHASE, 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, PRiSM,
PRO/II, PROVISION, ROMeo, RLINK, RtReports, SIM4ME, SimCentral, SimSci, Skelta, SmartGlance, Spiral Software,
WindowMaker, WindowViewer, and Wonderware are trademarks of AVEVA and/or its subsidiaries. All other
brands may be trademarks of their respective owners.
U.S. GOVERNMENT RIGHTS
Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the license agreement
with AVEVA Group Limited or its subsidiaries and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR
12-212, FAR 52.227-19, or their successors, as applicable.
Publication date: Tuesday, May 9, 2023
Publication ID: 1221248
Contact Information
AVEVA Group Limited
High Cross
Madingley Road
Cambridge
CB3 0HB. UK
https://sw.aveva.com/
For information on how to contact sales and customer training, see https://sw.aveva.com/contact.
For information on how to contact technical support, see https://sw.aveva.com/support.
To access the AVEVA Knowledge and Support center, visit https://softwaresupport.aveva.com.
Contents

Chapter 1 Get started with PI System Explorer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

How assets are represented in PI AF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
PI System Explorer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Sign on with OpenID Connect (OIDC). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
PI System Explorer user interface components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Feature suggestions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
PI System Explorer browser and navigator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Customize the navigator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
PI System Explorer customization options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Show attribute values in source unit of measure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Change the unit of measure for displayed attribute values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Column display configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Select attributes to display as viewer columns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Select multiple objects in the viewer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Object duplication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Icons that indicate object states. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Check-in of database changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Delete PI AF objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Keyboard shortcuts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Change the language. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Valid characters in PI AF object names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
PI time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
PI time abbreviations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
PI time expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Time-stamp specification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Time-interval specification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Chapter 2 Server and database connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

PI AF server connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Connect to a PI AF server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Add a PI AF server to the connection list. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
PI AF server properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
View properties of the connected PI AF server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Manage identities in PI AF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Manage mappings in PI AF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Add a mapping to an identity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Map a role to a PI AF identity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
 View PI AF server object counts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
View RPC metrics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
View PI AF server connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Data Archive connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Connect to Data Archive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Data Archive connection problems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Configure clients to allow explicit login prompts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Review digital state sets on a Data Archive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Review differences between digital state sets and enumerations sets. . . . . . . . . . . . . . . . . . . . . . . . . . 53
Create enumeration sets from digital state sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Add PI Data Archive servers to connected server lists. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
View buffering status for connected Data Archive servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
PI AF database connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Create PI AF databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
View or edit properties of PI AF databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Connect to a database on a different PI AF server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Set the default database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
The structure of PI AF asset models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Rename databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Search for PI AF databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Refresh the list of databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Database deletion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
PI AF and Data Archive collective connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Manage connection preferences for PI System Explorer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Switch collective members. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Switch to a specific collective member. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Chapter 3 Database import and export. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Export a database to XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
XML export options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
All Referenced Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
File format for export and restore. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Restore databases from exported XML files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Export of library objects to another database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
PI AF saved libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Save databases as libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Load database libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Review properties of loaded libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
AFExport utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Guidelines for exporting collections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
AFExport utility parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Sample export paths. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
AFImport utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
AFImport utility parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Chapter 4 Retrieval of asset information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

 Asset browsing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Element browsing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Configure browser page size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Open additional browser windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Asset and asset data searches. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Quick search. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Search result paging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Maximum query sizes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Searches on a specified date. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Search for PI points. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Syntax for PI point searches. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Manage search results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Search for elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Configure search conditions for attribute values when a template is specified. . . . . . . . . . . . . . . . . . . 95
Configure search conditions for attribute values when no template is specified. . . . . . . . . . . . . . . . . . 96
Special characters in name searches. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Search for attributes on elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Search for event frames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Search for attributes on event frames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Search for transfers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Search for attributes on transfers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Trends in PI System Explorer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Create trends. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Version management for equipment and processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Create versions for elements or models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Create table versions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Compare two versions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Display of different object versions and obsolete objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Query Date and PI System Explorer time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Show specific dates and times. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Time context for attribute values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Set time context for displayed attribute values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
View time series data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Boundary type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Filter expression. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Weighting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Event horizon mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Restrictions on viewing time series data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Chapter 5 Organization of asset models in PI AF. . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

The structure of PI AF asset models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
The design of PI AF asset hierarchies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Element references in the asset hierarchy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Reference types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Parent-Child reference type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
 Composition reference type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Weak reference type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Create single element references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Create multiple element references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Locate other references to the same element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Change reference types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Creation of custom reference types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Create custom reference types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Categorization of objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Create new categories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Assign objects to categories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Chapter 6 Representation of assets in PI AF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Asset representation with templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Template strategy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Element templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Default attribute. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Base and derived templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Naming patterns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Create element templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Find template references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Define templates for other objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Child templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Create child template references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Asset representation with elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Create elements based on a template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Create elements not based on a template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Find where an element is used. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Deletion of elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Attribute-value reset to original properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Convert elements to element templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Change element templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Storage of application-specific information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Create extended properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Chapter 7 Association of data with PI AF assets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Attribute templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Attribute properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Configuration Item attribute property. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Excluded attribute property. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Hidden attribute property. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Indexed attribute property. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Manual Data Entry attribute property. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Attribute traits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Set limit attribute traits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
 Set forecast attribute traits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Set location attribute traits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Set reason attribute traits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Set health attribute traits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Control the display of attribute and attribute template values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Create attribute templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
PI AF data types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Define constant values for attribute templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Configure values for Basic data types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Configure values for Array data types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Configure Enumeration Set values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Configure values for Object data types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Add attribute extensions to template-based elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Enumeration sets in PI AF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Manage enumeration sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Renumber enumeration values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Chapter 8 Configuration of data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Attribute configuration strings in PI System Explorer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Configuration strings for PI point data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Data reference parameters that specify values to return. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Data reference parameters that specify PI point to create. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Path syntax for references to other attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Path syntax for Data Archive computers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Path syntax for PI AF databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Syntax for relative paths. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Examples of references to attributes of the same element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Examples of references to attributes of different elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Path syntax for dynamic objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Path syntax for collection types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Path syntax for filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Wildcard characters in Name filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Substitution parameters in data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Symbols used in substitution parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Name substitutions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
References to attribute values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
List of PI AF substitution parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Format strings for time substitution parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Find the default Data Archive server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
PI point data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Direct PI point references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Indirect PI point references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Create direct PI point data references from Tag Search results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Configure direct or indirect PI point data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
References to attribute values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Unit of measure considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Configuration of retrieval methods for attribute values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
 Relative time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Time retrieval options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Range retrieval options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Configure value retrieval by time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Configure value retrieval by time range. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Create ranges of configurable durations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Create default time ranges for element attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Configure dynamic time range calculations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Time ranges for event frames and transfers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
PI point value updates from a data reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Attribute-value updates from PI point data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Attribute indicators for updates of PI point data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Configure creation of PI points. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Edit PI point properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Preview substitution parameters in PI point data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
PI point array data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Create PI point array data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Formula data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Formula data reference operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Formula data reference functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Units of measure in formula data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Configure formula data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Define parameters for formula data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Define equations for formula data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
String Builder data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Attribute references in String Builder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Function implementation in String Builder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Create String Builder data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Table lookup data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Create PI AF tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Conversion settings for time zones. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Create table column definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Populate tables manually. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Data references from outside the PI System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Authentication for linked tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Create reusable table connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Access to Microsoft Access or Excel data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Access to SQL Server data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Remove control characters from imported AF tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Configure table lookup data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Select first row matching criteria. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Summarize all rows matching criteria. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Table provided time series data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
WHERE clause syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Parameters for linked table queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
URI Builder data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Create URI Builder data references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Chapter 9 Units of measure in PI AF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Case sensitivity of UOM abbreviations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Configuration of case-sensitive UOM abbreviations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Base classes and derived classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
UOM base classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Common UOM derived classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Create UOM classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Create units of measure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
UOM conversion calculation with a formula. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Calculate conversion values for a UOM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
UOM groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Manage UOM groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Origin of UOMs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Chapter 10 Security configuration in PI AF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

PI AF identities and mappings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Built-in PI AF identities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Security hierarchy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Security inheritance of PI AF objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Permission inheritance of element objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
PI AF access rights. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Deny permission option. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Security Configuration window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Permissions tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Effective access tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
View effective access by user. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
PI AF server security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Configure security for a PI AF server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
PI AF database security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Configure security for new PI AF databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Configure security for a single PI AF database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
PI AF collection security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Configure security for collections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
PI AF object security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Configure security for objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Configure security for analyses and analysis templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Configure security for the UOM database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Differences from Data Archive security model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

Chapter 11 Event frames in PI AF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Structure of event frames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Advantages of event frames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
 Examples of event frames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Event frames or batch?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Ways to create event frames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Visualization of event frames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Event frame templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Primary referenced element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Data references to attributes in the primary referenced element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Data references to attributes in other elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Create event frame templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Change event frame templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Create event frames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Create attributes on event frames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Value capture for event frames and transfers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Capture values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Lock event frames or transfers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Acknowledgment of event frames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Acknowledge event frames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Transfers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Create transfer templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Create transfers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Create transfer ports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Transfer Ports tab properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

Chapter 12 Annotations in PI AF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

Element annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Add annotations to elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Event frame annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Add annotations to event frames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Transfer annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Add annotations to transfers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Chapter 13 Asset analytics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

Introduction to analyses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Configure and manage analyses on an element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Analysis templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Updates of analyses and analysis templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Excluded attributes in analyses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Analysis scheduling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Output time stamps for analyses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Specify time stamp for analysis outputs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Trend charts in Preview Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Expressions for analyses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Expression specification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Expression simplification with refactoring. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
 Future data and analyses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Types of analyses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Expression analyses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Create an expression analysis template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Create an expression analysis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Rollup analyses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Rollup analysis functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Create a rollup analysis template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Create a rollup analysis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Event frame generation analyses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Implicit modes of event frame generation in asset analytics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Create an event frame generation analysis template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Create an event frame generation analysis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Start and end trigger conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Child event frame generation with multiple start triggers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
SQC analyses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Create an SQC analysis template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Create an SQC analysis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Sample analyses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Build an expression analysis to study efficiency deviation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Create a template for power rollup analyses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
Create event frames automatically to track inefficiency. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Management of analyses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Management window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Analyses tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
View analyses details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
Performance tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
View analytic performance data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Search for analyses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
PI Analysis Service management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
View performance data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Service Details tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
View analysis service statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
View or modify analysis service settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Analysis service configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Buffering PI point outputs for PI Analysis Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Backfilling and recalculation of analyses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Backfill or recalculate data for an analysis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Backfill or recalculate data for multiple analyses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Reconciliation of event frames during backfilling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Configure automatic recalculation of analyses and analyses templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
Enable or disable automatic recalculation for multiple analyses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
Open recalculation log folder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
Asset analytics expression functions by type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
Expression functions reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Abs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Acos. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
AND. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
ArrayLength. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Ascii. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Asin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Atn. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Atn2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Avg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
BadVal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
Bod. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Bom. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Bonm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
Ceiling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Char. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Compare. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Concat. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Contains. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Convert. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Cos. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Cosh. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Cot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Coth. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Cov. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Csc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
Csch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Curve. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Day. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
DaySec. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
DeltaValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
DigState. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
DigText. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
E. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
ELSE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
EventCount. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
EventFrame. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Exit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
Exp. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
FilterData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
FindEq. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
FindGE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
FindGT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
FindLE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
FindLT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
FindNE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
FirstValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Float. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Floor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
Frac. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
HasChanged. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
HasValueChanged. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
Hour. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
IF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
IN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
InStr. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Int. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
InterpolatedValues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
IsSet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
LastValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
LCase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
Left. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
Len. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
LinRegr. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
Log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
Log10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
Logbase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
LTrim. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
MapData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
Max. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
Median. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
Mid. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
Min. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
Minute. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
Mod. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Month. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
NextEvent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
NextVal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
Noon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
NoOutput. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
Normalrnd. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
NOT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
NumOfChanges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
OR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
ParseTime. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
PctGood. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
Pi. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
Poisson. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
Poly. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
Pow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
PrevEvent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
PrevVal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
PStDev. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Rand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
Range. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
Rate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
RecordedValues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
RecordedValuesByCount. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
Remainder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
Right. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Round. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Roundfrac. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
RTrim. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
Sec. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
Sech. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
Second. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
SecSinceChange. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
Sgn. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
Sin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
Sinh. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
Split. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
Sqr. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
StateNo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
SStDev. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
StDev. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
TagAvg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
TagBad. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
TagDesc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
TagEU. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
TagExDesc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
TagMax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
TagMean. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
TagMin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
TagName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
TagNum. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
TagSource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
TagSpan. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
TagTot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
TagType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
TagTypVal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
TagVal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
TagZero. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
Tan. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
Tanh. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
Text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
THEN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
TimeEq. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
TimeGE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
TimeGT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
TimeLE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
TimeLT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
TimeNE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
TimeStamp. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
Total. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
Trim. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
Year. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
Trunc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
UCase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
 Weekday. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
Yearday. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
Steam functions for analysis expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
Steam functions in asset and tag-based analytics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
Ranges for steam function inputs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
Considerations for steam functions that have pressure as an input. . . . . . . . . . . . . . . . . . . . . . . . . . . 504
Unit of measure conversion for steam functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
Steam property reference states. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
Steam functions reference (asset analytics). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
Steam_HPS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
Steam_HPT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
Steam_HPTL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Steam_HPX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Steam_HsatP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
Steam_HsatT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
Steam_PsatT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
Steam_SPH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
Steam_SPT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
Steam_SPTL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
Steam_SPX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
Steam_SsatP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
Steam_SsatT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
Steam_TPH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
Steam_TPS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
Steam_TsatP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
Steam_VPH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
Steam_VPS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514
Steam_VPT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514
Steam_VPTL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515
Steam_VPX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515
Steam_VsatP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
Steam_VsatT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
Steam_XPH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
Steam_XPS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517

Chapter 14 Notifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518

Introduction to notifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
Notifications and event frames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
Notifications history. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
Requirements for notifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
Client support for notifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
Notifications security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
Security for contacts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
Summary of permissions for contacts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
Edit security for existing contacts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
Security for notification rules and templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
 Summary of permissions for notification rules and templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
Edit security for a notification rule or template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
Configure authentication for SMTP server connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
Configure authentication for a web service connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
Create a notification rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
Create a notification rule template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
Trigger criteria in notification rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
Non-Repetition Interval in notification rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
Resend Interval in notification rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
Delivery formats in notification rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
Add a domain to the list of trusted sites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
Add a screenshot in notification email delivery format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
Subscriptions in notification rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
Customization of subscription content and delivery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
Configuration of notifications delivery endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
Configure an email delivery endpoint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
Update SMTP settings for the email delivery channel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
Configure a dynamic email delivery endpoint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
Configure a REST web service delivery endpoint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
Configure a SOAP web service delivery endpoint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
Contacts plug-in. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
Configure Active Directory access for contacts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
Manage contacts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
Options for the notifications email delivery channel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
Options for the notifications web service delivery channel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
Notification rules management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544
Management of notification rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544
Search for notification rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
Configuration of notification rules for analyses or event frames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
Configure notification rules from analyses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
Configure notification rules for user-defined event frames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
Configure escalations for notification rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
Changes from PI Notifications 2012. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
Migration from PI Notifications 2012. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554
Additional resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559

Chapter 15 Process models in PI AF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560

The scope of a PI AF model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
Guidelines for PI AF models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
Submodels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
Element types in models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
Create PI AF models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562
Edit PI AF models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562
Ports and connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563
 Create ports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563
Create connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563
Layers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564
Create layers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564

Chapter 16 PI AF utilities and plug-ins. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565

Launch PSE with command line options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
AFExplorer parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
PI AF Diagnostics utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566
Grant permissions for PI AF Diagnostics utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566
Run the AFDiag utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567
AFDiag utility parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568
Audit Trail implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573
AF Update Plug-in Configurations utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574
Set PI AF server utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
SetPISystem utility parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
Capture AF SDK event trace output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
AFGetTrace utility parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
Track PI AF changes with Audit Trail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580
Overview of Audit Trail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581
Review changes with the Audit Trail utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582
View installed plug-ins. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
Command-line plug-in registration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
RegPlugIn parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586
Create an XML registration file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588
Create an SQL registration script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
Register plug-ins with generated SQL scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
Plug-in provider management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590
Locate the names of trusted providers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590
AVEVA™ PI System Explorer User Guide
Chapter 1

Get started with PI System Explorer

With Asset Framework (PI AF), you can represent assets and processes as PI AF objects and structure them to
provide value to your business.
PI System Explorer (PSE) and PI Builder are the primary tools that you use to create and manage PI AF objects.
Both tools include support for the following features:
• Event frames
With event frames, you can capture important process events and collect relevant data around
them to help analyze why they occurred. See Event frames in PI AF for more information.
• Asset analytics
Integrated into PI System Explorer, you can use asset analytics to create calculations and set up
conditional statements involving asset values. See the "Asset analytics" topic in the Analytics and
Notifications publication for more information.
• Notifications
Integrated into PI System Explorer in PI AF 2016 R2, you can use notifications to create rules by
which users can be alerted in real time to anomalous conditions in the system. See the "Introduction
to notifications" topic in the Analytics and Notifications publication for more information.

How assets are represented in PI AF

PI Asset Framework (PI AF) enables you to build a representation of your equipment and processes that can give
you tremendous insight into your data. In PI AF, the equipment and processes that you want to monitor are
called assets. The PI AF representation of all your assets and processes together is called an asset model. The
asset model organizes all your equipment into a structure that makes it easy to find information.
In the PI AF asset model, each piece of equipment is represented by an element. The associated data for an
element is stored as attributes on the element. Attributes can hold simple values, representing fixed information,
such as the diameter of a tank. An attribute can alternatively reference a PI point, a formula, a value from a
relational database, a file, a photograph, and more. All relevant data about an asset is tied to the element
representing that asset.
For example, suppose you have a pump with three associated pieces of data: the pressure (read from a PI point),
the inlet temperature, and the outlet temperature. To model this in PI AF, you can create a PI AF element to
represent the pump and then create three attributes to represent the associated data.
The following illustration shows how the data might look in PI AF. Although all the values are PI point values, the
user never needs to know the names of the PI points. All the data is available directly on the element.
 Video
For information on assets and attributes, watch this video:

PI System Explorer
PI System Explorer provides a graphical user interface for creating, editing, and managing PI AF objects. Use PI
System Explorer to create and manage your asset framework, including PI AF databases, elements, and
templates.
Random and Ramp Soak interfaces removal
Starting with PI Server 2018 SP3, the Random and Ramp Soak interfaces are no longer installed by default with a
new PI Data Archive installation. Optionally, you can install them by using separate install kits: the PI Interface for
Ramp Soak Simulator Data and the PI Interface for Random Simulator Data. After installing these interfaces,
follow the instruction provided by the interface install kits to create default PI points and then receive simulated
data from these interfaces. For upgrades, previous versions of Random and Ramp Soak interfaces will remain and
the default PI Points will continue to retrieve simulated data.
Prior to PI Server 2018 SP3, the following default PI points are created automatically with the PI Data Archive
install kit:
• BA:ACTIVE.1
• BA:CONC.1
• BA:LEVEL.1BA:PHASE.1
• BA:PHASE.1
• BA:TEMP.1
• CDEP158
• CDM158
• CDT158
• SINUSOID
• SINUSOIDU
PI System Explorer versions
On computers with a 64-bit operating system, both a 32-bit and a 64-bit version of PI System Explorer are
available after a PI AF client installation. Beginning with PI AF 2017, the 32-bit version is labeled PI System
Explorer Legacy 32-bit, whereas the 64-bit version is labeled simply PI System Explorer.
The legacy 32-bit version is available should you need to continue to use the legacy version of Notifications (prior
to the 2016 R2 version) and its contact editor. This version of the contact editor is required to work with legacy
delivery channels. For more information on notifications, see the "Notifications" topic in the Analytics and
Notifications publication.
Support for FIPS
Beginning with PI AF 2017 R2, PI AF supports Windows environments that enforce the use of U.S. Federal
Information Processing Standards (FIPS) cryptographic algorithms. No additional configuration is required once
the local security policy System cryptography: Use FIPS compliant algorithms for encryption, hashing, and
signing has been enabled.
To be in compliance with FIPS, users who need to use passwords to link to external tables can only use PI AF
2017 R2 or later clients and servers. Furthermore, users cannot export data from a PI AF database that contains
table passwords created with a PI AF 2017 R2 or later client and import those passwords to PI AF clients on older
releases. For more information on linking to external table data references, see Data references from outside the
PI System.
Sign on with OpenID Connect (OIDC)
You can use claims-based authentication via Open ID Connect (OIDC) to sign on to PI System Explorer. OIDC uses
an Identity Management service to verify a user's identity and then grant access to AF client and Data Archive
resources via access tokens. The AVEVA Identity Manager is the provided identity service for PI Server 2023.
Once you have successfully signed on with OIDC, the same access token is used to authenticate and gain access
to other PI server resources. If a server does not use OIDC authentication, it defaults to Windows authentication.
When first opening PSE, the initially selected authentication mode is used for all default and implicit connections
made during that session. To switch the authentication mode used to connect to a specific PI Server resource,
you can use the Connect As command. See Connect to a PI AF server, Connect to Data Archive, and Connect to a
database on a different PI AF server.
If OIDC is not enabled on a resource, Windows authentication is the default authentication mode.
Prerequisite
You must have created and assigned a user account to an Identity Server role, set permissions, and created a
mapping.
Procedure
1. Open PI System Explorer.
The Authentication Mode dialog opens.

2. Select the Authentication down arrow, then select OpenID Connect Authentication.
Note: If you selected Windows authentication to log on, PI System Explorer opens.
3. Optional: Select Remember my Choice in the Authentication Mode dialog to preserve your preferred
authentication method, and bypass the dialog for future server connections.
4. Select OK.
The AVEVA Identity Manager browser window opens and then a second browser window opens and
prompts for your sign-on credentials.
5. Enter your OIDC credentials in the browser window, then click OK.
6. In the pop up message box, select Yes/Allow.
 The PI System Explorer window opens.
Note: User permissions are set up via role assignments in AVEVA Identity Manager.
7. Optional: To verify the authentication mode assigned to a user, select File, then select Connections.
The Servers dialog opens and lists server connections by user and authentication method: AIM (claims-
based) or Windows.

PI System Explorer user interface components

The following illustration shows the major components of the PI System Explorer.

1. Menu bar
2. Toolbar
3. Browser
4. Navigator
5. Status bar
 6. Palette
7. Viewer
Videos
For information on PI System Explorer browser and navigator, watch this video:
For information on PI System Explorer palette and viewer, watch this video:

Feature suggestions
Beginning with PI AF 2017, you can make suggestions on features you would like to see added to the AVEVA™ PI
System™. You can also review suggestions that other users have already submitted and vote for those you
approve of. You can select from the following categories for your suggestion:
• Analytics and Calculations
• Asset Framework
• Data Archive
• Event Frames
• General
• Help/Documentation/Videos
• Installation
• Notifications
• PI Builder
• Security
• System Management
To provide feedback, you select Help > Give Us Feedback and click Sign in. You can type your feedback into the
Enter your idea field, select an appropriate category, and provide additional details as needed.
PI System Customer Experience Improvement Program
The Customer Experience Feedback Option on the Help menu enables you to participate in the telemetry
program that collects anonymous usage data to improve the PI System and to prioritize new features. The
collected data does not include business data or logic, but can include information such as IP addresses, host
names, and names of PI System objects.
To participate in the telemetry program, you select Yes, I would like to participate (Recommended) and click OK.

PI System Explorer browser and navigator

The content of the PI System Explorer browser depends on which button is selected in the navigator. The default
available objects in the navigator are elements, event frames, library objects, units of measure, and contacts. The
management object is also displayed if the Management plug-in (which encompasses analyses and notification
rules) is installed.
 Note: If legacy notifications are installed on a PI AF client computer, MyPI and Notifications may also be
displayed in the navigator.
You can move very quickly between browser objects in PI System Explorer with the following keyboard shortcuts.
Notice also that different colors are displayed at the top of the browser and viewer to help distinguish between
selected browser objects:

Shortcut Browser

CTRL+1

CTRL+2

CTRL+3

CTRL+4

CTRL+7

CTRL+0

Customize the navigator

To increase the space available on your screen for objects in the browser, change the buttons in the navigator to
icons.
1. Right-click in the navigator and click Navigation Pane Options.
2. In the Navigation Pane Options window, clear the check box beside each component on the Display Full
Button list.
3. Click OK.
The rows of button labels are replaced by a single row of icons.

4. Move your cursor over an icon to display its label.

PI System Explorer customization options
You can customize many aspects of PI System Explorer to suit your needs with Tools > Options.
General tab
You use the General tab to control display options for several features. You can control:
• Keystroke to open Check-In and Undo-Checkout windows. For more information, see Check-in of database
changes.
• Title bar appearance.
• Page size for browser objects. For more information, see Configure browser page size.
• Number of queries returned in object searches. For more information, see Search result paging.
• Unit of measure appearance for attributes. For more information, see Show attribute values in source unit of
measure.
• Display of attribute values to the units of measure that are mapped to a selected UOM group. When no
UOM group is selected, attribute values are based on the default UOM defined in attribute templates or
their source unit of measure (if Use Source Unit-Of-Measure for attribute display is selected). For more
information, see UOM groups.
• Display of excluded attributes. For more information, see Excluded attribute property.
• Number of digits displayed for attribute values. For more information, see Control the display of attribute
and attribute template values.
Time Context tab
You use the Time Context tab to define the time or time range that PI System Explorer uses to display attribute
values. For more information, see Set time context for displayed attribute values.
Server Options tab
You use the Server Options tab to define how PI System Explorer should connect to a PI AF collective or Data
Archive collective. For more information, see Manage connection preferences for PI System Explorer.

Show attribute values in source unit of measure

For attributes that are defined by data references, you can have their values displayed in the units of measure
that are defined by the data reference, rather than in the default units of measure that are established in
attribute templates.
1. Select Tools > Options.
2. On the General tab, select Use Source Unit-Of-Measure for attribute display.
3. Click Apply.
4. Click OK to close the window.

Change the unit of measure for displayed attribute values

During your current session in PI System Explorer, you can change the unit of measure (UOM) that is displayed
for an attribute value from its default or mapped value.
 1. In the Attributes tab of the Elements or Event Frames viewer, right-click the value for an attribute and click
Change Display UOM.
2. In the Select Display UOM window, select a new UOM for the value from the Display UOMs list.
Note: The list contains all UOM values in a class. <Default> is displayed beside the default UOM. If you have
selected a UOM group in Tools > Options and the selected UOM group has a mapping for the attribute's
default UOM, <Mapped> is displayed beside the mapped UOM.
3. Click OK.

Column display configuration

Property columns
Whenever data columns are displayed in the viewer or a search results window, you can customize which
property columns you wish to view. At the far right of the window, you can click and select additional column
selections or clear default column selections.
Attribute columns
In viewer or search results windows for elements and event frames, you can also select attribute columns and
display them as columns alongside the default property columns. An attribute column is identified by the |
character.

Select attributes to display as viewer columns

For collections of Elements, Element Searches, Event Frames Searches, and Transfer Searches, you can select
attributes to display as columns in the viewer, in addition to default properties.
1. In the navigator pane, choose one of the following actions:
▪ To select attributes for Elements and Element Searches collections, click Elements.
▪ To select attributes for Event Frames Searches and Transfer Searches collections, click Event Frames.
2. In the browser, click the collection for which you want to select attributes.
3. At the far right of the viewer, click .
4. Click Select Attributes.
5. In the Select Attributes window, choose from the following options to select the attributes that you want
displayed in the viewer:
To ... Do this ...

Add attributes from a template a. Select the Add Attributes from Template
option.
b. Select a template from the list.
 To ... Do this ...

Add attributes from an element or event frame a. Select the Add Attributes from Element/
Event Frame option.
Note: You cannot add attributes from a Transfer
Searches collection b. Choose from the following actions:
To• search for an element or event
frame, click and enter criteria to
locate attributes in the Element
Search or Event Frame Search
window.
To• select an element or event frame
from the browser tree, click and
select from the Element Browser or
EventFrame Browser window.
c. Click OK.
Add other attributes a. In the Others field, enter attribute names
separated by a semicolon, or click
and enter criteria to locate attributes in
the Attribute Search window.
b. Click Add.
Selected attributes are displayed in alphabetical order in the left-hand Attributes or Attribute Templates list. For
added convenience, you can group them by category or template by selecting one of the Group by check boxes.
You can also filter them if necessary with further search criteria.
6. From the Attributes or Attribute Templates list, select the attributes you want to display in the viewer.
a. Use standard Windows selection keystrokes (such as SHIFT+<click> and CTRL+<click>) to select
contiguous and non-contiguous attributes in the list, as described in Select multiple objects in the
viewer.
b. Click to move selected items or to move all items to the right-hand Attributes list.
7. Optional. Adjust the order that attributes will be displayed in viewer columns:
To ... Do this ...

Move an attribute up the list Select an attribute below the top row and click .
Move an attribute down the list Select an attribute above the bottom row and click

Remove an attribute from the list Select an attribute and click .

Remove all selected attributes Click .
8. Optional. You can add additional attributes as required, for example from another template. Repeat steps 5
to 7.
 9. Click OK to complete the attribute selection.
The selected attributes are displayed as columns in the viewer.
10. Optional. You can control which selected attribute columns are displayed in the viewer:
To ... Do this ...

Remove an attribute column a. Click .

b. Click Attribute Columns.
c. Clear the attribute you want to remove.
Remove all attribute columns a. Click .
b. Clear Show Attribute Columns.

Select multiple objects in the viewer

In the viewer, use standard Windows mouse and keyboard combinations to select more than one object to
complete operations such as copying, deleting, exporting, checking items in and out, as well as changing
templates.
1. To select a group of contiguous objects in the viewer, click one object, move the cursor to the end of the
group, press SHIFT and click the last object in the group.
2. To select non-contiguous objects, press the CTRL key as you click each object in the viewer.
3. To select all objects in the viewer, press CTRL+A. To deselect individual objects in the selection, press CTRL
and click each object.
After selecting the objects, right-click and click the operation to perform on the context menu.

Object duplication
You can copy individual objects or multiple rows of objects and paste the information for those objects into a
spreadsheet in a tab-separated format.
The Copy option is available on context menus throughout PI AF. The Copy Path and Copy Cell options are
available where appropriate.
Note: When you drag and drop, the clipboard always contains the path information, which renders the data
compatible with other client applications, such as PI ProcessBook.
Copy
In any PI AF browser, use Copy on a context menu to place the full path of the selected object on the clipboard:
\\Kaboom\Chocolate Milk Tutorial\ChocolateMilkModel\MixFlow
In any viewer grid or list, use Copy to place the content of each displayed column in the selected row on the
clipboard. If you select multiple PI AF rows, Copy places multiple data rows separated by a new line. In attributes
lists, the copied data includes strings that correspond to the Configuration ( ), Quality ( ), Template ( ), and
Hidden ( ) column icons, in addition to other displayed columns:
 Name

Value

Path

Copy Path
The Copy Path option places the full path for each selected object on the clipboard. If multiple PI AF objects are
selected, Copy Path places multiple paths separated by a new line:
\\ABACUS-CURRENT\NuGreen\NuGreen\Houston\Cracking Process\Equipment\F-321|Model
\\ABACUS-CURRENT\NuGreen\NuGreen\Houston\Cracking Process\Equipment\F-321|Motor Amps
Copy Cell
In any viewer grid or list containing multiple columns, such as attributes, referenced elements, child event
frames, and so on, the Copy Cell option places the contents of the selected cell on the clipboard.

Icons that indicate object states

PI System Explorer uses the following (mini) icons superimposed over object icons, such as attributes ( ),
elements ( ),
event frames ( ), and servers ( ), to indicate the current state of those objects. Such icons can also be
combined to indicate multiple states: for example, uses the referenced and default icons to indicate the
primary referenced element in an event frame, whereas uses the connected and default icons to indicate the
default connected PI AF server.
Icon Object state

Is changed, but not yet applied.

Is checked out by you.

Is checked out by a different user.

Is available in multiple versions.

Is a reference to another object.

 Icon Object state

Is the default.

Is disconnected, such as a collective member.

Is connected, such as a PI AF server.

Is a search.

Is a template.

Is arranged by category.

Is unsaved, such as a search.

Is unsupported, such as a server version.

Check-in of database changes

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.
• Unsaved changes are indicated by a red check mark icon.
• Changes that have been applied, but not saved to the database are indicated by a dark red check mark
icon.

As you work, you can choose from these options to save your changes:
• Click File > Check In.
• On the toolbar, click Check In.
• In the browser, right-click an object and click Check In to save changes in the database for that object only.
The first two options allow you to save changes for all modified objects. The Check In window opens and displays
objects that have been modified. You can select them all in or select some to check in, and allow others to
remain checked out. Click Session to select objects modified only in the current session. You can still check in
objects modified in other sessions.
 Undo Check Out
If you decide not to save your changes, you can use the File > Undo Check Out option. In the Undo Check Out
window, you clear any items in the list you do want to check in, and click Undo Check Out.
Undo Check Out for all users
Occasionally, you may be unable to modify a PI AF object because the element is checked out to another user.
You see the following message types that inform you that an object is locked by a user:
• In notifications, when you attempt to stop, rename, delete, or otherwise change a notification, the error
message Notification 'Notification_name' with Unique ID 'ID' is locked by user Windows_account is displayed.
• In PI AF, when you attempt to work with an object, the error message AF Object Name 'Object_name' with
UniqueID 'ID' is locked by user Windows_account is displayed.
To undo the lock, a user who has the Admin permission on the object set to Allow can select Show All Users in
the Undo Check Out window, select All and then click Undo Check Out. For more information, see PI AF access
rights.
Videos
For information on the check in/check out mechanism of a PI AF object, watch this video:
For information on how to check in modifications to PI AF objects, watch this video:
For information on how to undo check out of PI AF objects, watch this video:

Delete PI AF objects
PI AF database objects are deleted from the PI System Explorer browser. You can delete any object that is
checked in or checked out, as well as delete references between elements, event frames and elements, and
event frames. For more information on references, see Element references in the asset hierarchy.
1. To delete a PI AF database object, click the Element, Event Frame or Library button in the navigator.
2. In the browser, navigate to the object you want to delete.
3. Right-click the object, then click Delete.
4. In the Delete window, you can delete objects that have references to other objects, as well as those that do
not.
• If the object has references to other objects...
To... Do this...

Delete an object and all the references pointing to it Click Delete this object and all references to it. Check
without immediately checking in the changes. in is required to complete this action.
Delete the currently selected reference only without Click Only delete this reference to the object. Check
immediately checking in the changes. in is required to complete this action.
Delete the object permanently from your PI asset Click Permanently delete; this action is irreversible.
model.
Caution: This option results in the immediate
deletion of the object and its references from the
database.
 Caution: If the object is an event frame, selecting any of the options in the Delete window results in the
immediate deletion of the event frame.
• If the object does not have references to other objects...
To... Do this...

Delete an object without immediately checking in the Click Delete this object. Check in is required to
changes. complete this action.
Delete the object permanently from your PI asset Click Permanently delete; this action is irreversible.
model.
Note: This option results in the immediate deletion of
the object from the database.

Tip: By default, PI AF automatically deletes analyses and notifications that reference a deleted element. You can
change this behavior by disabling the /EnablePropogationOfTargetDeletion parameter in the PI AF Diagnostics
utility. For more information, see Deletion of elements.
1. Click OK.
Note: If you did not permanently delete the object, remember to click the Check In button to apply and save
your changes to the database.

Keyboard shortcuts
PI System Explorer provides keyboard shortcuts for navigation and other tasks that require a mouse or other
pointing device.

Shortcut 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.
CTRL+HOME Selects the first cell of the current page in the viewer.
Shortcut Action

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 Arrows Navigate objects in the viewer or browser.
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, displays the complete hierarchy of
or
choices.
ALT+Up Arrow
or
ALT+Down Arrow
CTRL+1 Navigates to the Elements browser.
CTRL+2 Navigates to the Event Frames browser.
CTRL+3 Navigates to the Library browser.
CTRL+4 Navigates to the Unit of Measure browser.
CTRL+5 Navigates to the MyPI browser.
CTRL+6 Navigates to the Notifications browser.
CTRL+7 Navigates to the Contacts browser.
CTRL+0 Navigates to the Analyses browser.
Change the language
You can change the language for PI System Explorer on your computer if you have a Language Pack and the
desired language resources have been installed. The language setting is per user locale, so if others want to use
PI System Explorer on the same computer under a different login, they can use different language resources if
available.
1. Run the Language Pack and select the language resources you want to install, if they are not already
available.
2. Click View > Language Settings.
3. In the Language Settings Tool window, select the target language and click OK.
4. Quit and restart PI System Explorer.
PI System Explorer appears in the specified language.
Note: The language setting is account-specific, so users who log in under a different account see the language
specified for that account.

Valid characters in PI AF object names

PI AF has the following constraints on object names:
• Leading or trailing spaces are removed from names.
• Maximum name length is 259 characters.
• Blank names are not permitted.
You can use standard keyboard characters, with the following exceptions:

Object type Invalid characters

Other than contacts Control characters plus: * ? ; { } [ ] | \ ` ' "

Contacts Control characters plus: * ? ; [ ] | \ "

PI time
You can use a special syntax, called PI time, to specify inputs for time stamps and time intervals. PI time uses
specific abbreviations, which you combine to create time expressions.

PI time abbreviations
When specifying PI time, you can use specific abbreviations that represent time units and reference times.
Time-unit abbreviations

Abbreviation Full version Plural version Corresponding time unit

s second seconds Second

m minute minutes Minute
Abbreviation Full version Plural version Corresponding time unit

h hour hours Hour

d day days Day
mo month months Month
y year years Year
w week weeks Week
To specify time units, you can specify the abbreviation, the full version, or the plural version of the time unit,
such as s, second, or seconds. You must include a valid value with any time unit. If specifying seconds, minutes,
or hours, you can specify a fractional value, such as 1.25h. You cannot specify fractional values for other time
units.
Reference-time abbreviations

Abbreviation Full version Corresponding reference time

* Current time
t today 00:00:00 (midnight) of the current day
y yesterday 00:00:00 (midnight) of the previous day
The first three letters sunday 00:00:00 (midnight) on the most recent Sunday
of the day of the
week. For example:
sun

The first three letters june 00:00:00 (midnight) on the current day in June of the current
of the month. For year
example:
jun

dec DD december DD 00:00:00 (midnight) on the DDth day of December in the current
year
YYYY 00:00:00 (midnight) on the current day and month in year YYYY
M-D or M/D 00:00:00 (midnight) on the Dth day of month M in the current
year
DD 00:00:00 (midnight) on the DDth day of the current month

PI time expressions
PI time expressions can include fixed times, reference-time abbreviations, and time offsets. A time offset
indicates the offset direction (either + or -) and the offset amount (a time-unit abbreviation with a value).
For example, PI time expressions can have the following structure:
Structure Example

Fixed time only 24-aug-2012 09:50:00

Reference-time abbreviation only t

Time offset only +3h

Reference-time abbreviation with a time offset t+3h

Include at most one time offset in an expression; including multiple time offsets can lead to unpredictable
results.

Time-stamp specification
To specify inputs for time stamps, you can enter time expressions that contain:
• Fixed times
A fixed time always represents the same time, regardless of the current time.
Input Meaning

23-aug-12 15:00:00 3:00 p.m. on August 23, 2012

25-sep-12 00:00:00 (midnight) on September 25, 2012
• Reference-time abbreviations
A reference-time abbreviation represents a time relative to the current time.
Input Meaning

* Current time (now)

3-1 or 3/1 00:00:00 (midnight) on March 1 of the current year
2011 00:00:00 (midnight) on the current month and day in the year 2011
25 00:00:00 (midnight) on the 25th of the current month
t 00:00:00 (midnight) on the current date (today)
y 00:00:00 (midnight) on the previous date (yesterday)
tue 00:00:00 (midnight) on the most recent Tuesday
• Reference-time abbreviations with a time offset
When included with a reference-time abbreviation, a time offset adds or subtracts from the specified time.
Input Meaning

*-1h One hour ago

t+8h 08:00:00 (8:00 a.m.) today
y-8h 16:00:00 (4:00 p.m.) the day before yesterday
 Input Meaning

mon+14.5h 14:30:00 (2:30 p.m.) last Monday

sat-1m 23:59:00 (11:59 p.m.) last Friday
• Time offsets
Entered alone, time offsets specify a time relative to an implied reference time. The implied reference time
might be the current clock time or another time, depending on where you enter the expression.
Input Meaning

-1d One day before the current time

+6h Six hours after the current time

Time-interval specification
Time-interval inputs define intervals for collecting or calculating values during a time period. For example, you
might specify a 60-minute interval to compute an hourly average over a 12-hour period. To specify time-interval
inputs, enter a valid value and time unit:
• Positive values define intervals that begin at the earlier time in the period and that finish at or before the
later time in the period.
Start time 2:00:00

End time 3:15:00

Time interval 30m

Returned intervals 2:00:00 to 2:30:00

2:30:00 to 3:00:00
• Negative values define intervals that finish at the later time in the period and that begin at or after the
earlier time in the period.
Start time 2:00:00

End time 3:15:00

Time interval -30m

Returned intervals 2:15:00 to 2:45:00

2:45:00 to 3:15:00
Chapter 2

Server and database connections

After a PI AF Client installation, an administrator needs to configure a PI AF server for general use. Configuration
includes the following tasks:
• Connect to a PI AF server and set up a default.
• Set up PI AF identities.
• Map Windows user accounts to one or more PI AF identities.
• Select a default Data Archive, if one was not selected during PI AF Client installation.
• Create (or import) PI AF databases.
• Specify PI System Explorer connection preferences, if PI AF collectives are defined.
• Configure access permissions for identities to the PI AF Client server and databases. For more information,
see Security configuration in PI AF.
Video
For information on how to connect to and search an AVEVA™ PI System™, watch this video:

PI AF server connections
An administrator needs to select the PI AF servers to which to connect and establish the default. Additionally, an
administrator needs to set up PI AF identities and mappings to PI AF servers.

Connect to a PI AF server
Use the Servers window to review PI AF server connections, connect to different servers as needed, and change
the authentication mode used to connect to the PI AF server.
1. From the PI System Explorer menu bar, choose File > Connections.
In the Servers window, you see a list of known servers, identified by the following icons.
A disconnected PI AF server in the Known Server Table

A connected PI AF server

The default connected PI AF server

A Data Archive in the Known Server Table.

 The local default connected Data Archive

A disconnected Data Archive collective

A connected Data Archive collective

Note: The icon and a warning indicates that the PI AF client is connected to an unsupported version of Data
Archive, such as version 3.4.375 or 3.4.370. The PI AF client cannot connect to a Data Archive server that is
running software earlier than version 3.4.370.
1. To connect to a PI AF server, choose from the following actions:
To ... Do this ...

Connect to a different PI AF server Select a server in the list and click Connect.
Connect to a server as a different user (for example, a. Right-click a server in the list and click
from a shared computer) Connect As.
Ifi.OIDC is not enabled, the Connect to PI
AF servers window opens. Enter a
Windows user account name and
password.
Ifii.OIDC is enabled, the Authentication
Mode dialog opens. Select the
authentication mode you want to use
for the connection: OpenID Connect
or Windows.
b. Click OK.
Connect to a server that is not displayed on the Click Add Asset Server. For more information, see
Known Servers Table Add a PI AF server to the connection list.
Set a default PI AF server Right-click a connected PI AF server in the list and
click Set as local default Asset Server.
A icon appears next to the default server.
Connect to a collective a. Right-click a collective in the list.
b. Choose one of the following actions:
To• connect to the primary server in the
collective, click Connect to Primary.
To• connect to a specific collective
member, click Connect to Collective
Member, as described in Switch to a
specific collective member.
2. Click Close.
Add a PI AF server to the connection list
If the PI AF server you want to connect to is not currently displayed on the Known Servers Table, you can add it in
the PI AF Server Properties window.
1. In PI System Explorer, click File > Connections.
2. Click Add Asset Server.
3. In the PI AF Server Properties window, enter the PI AF server properties.
4. The Name field does not have to match the host name. After you connect to a PI AF server, you can change
the server name by clicking Rename and entering a new name.
Caution: Renaming the PI AF server impacts all clients.
5. The Account field is typically not needed in normal installations and should be left blank.
By default, PI AF clients such as PI System Explorer attempt to use a Service Principle Name (SPN) registered
by the PI AF server to establish a secure connection to the server. If an SPN cannot be created by the PI AF
server, a secure connection can be established via Microsoft NTLM if the server is running under a system
account, such as Network Service. In each case, the Account field is not needed and should be left blank.
If the PI AF server is run under a domain account, however, and an SPN is not successfully created by either
the PI AF server or an administrator, the domain account of the server must be specified so that the PI AF
client can securely identify the server.
6. The default Timeout value of 300 seconds is acceptable in most cases. If you experience timeout errors as
you work in PI System Explorer, increase the time in the Timeout box.
7. Optional. Aliases are alternate names for the PI AF server which users can use to look for the server. When
configured, PI AF server aliases are stored locally on the client only.
8. Optional. The Configure Active Directory link is for setting up the notifications contacts list. This is a PI AF
system administrator function.
9. Click Connect.
Note: If an error message opens saying that you cannot connect to the PI AF server, you need to enter the
domain account of the server in the Account field.
10. After a server if connected, you can click Security and set up security for the server. For more information,
see the PI System Explorer topic Security hierarchy.
11. Click OK.

PI AF server properties
You manage the configuration of the currently connected PI AF server in the PI AF Server Properties window.
The following tabs are available:
• General. For more information, see View properties of the connected PI AF server.
• Plug-Ins. For more information, see View installed plug-ins.
• Libraries. For more information, see Review properties of loaded libraries.
• Identities. For more information, see Manage identities in PI AF.
• Mappings. For more information, see Manage mappings in PI AF.
 • Counts. For more information, see View PI AF server object counts.
• RPC Metrics. For more information, see View RPC metrics.
• Connections. For more information, see View PI AF server connections.

View properties of the connected PI AF server

On the General tab of the PI AF Server Properties window, review and modify settings for the currently
connected PI AF server, such as:
• Server name, host name, and ID
• Default data server
• Server account
• Server version number
• Server port, timeout, and aliases
1. Click on the PI System Explorer toolbar, or click File > Server Properties.
2. On the General tab of the PI AF Server Properties window, review the server information and modify as
needed.
3. You can also choose from the following actions.
To … Do this …

Rename the PI AF server a. Click Rename.

b. In the New Name field of the New PI AF
Server Name window, replace the current
name with a new name.
c. Click OK.
Caution: Renaming the PI AF server impacts all PI AF
clients.

Change the default data server a. Click the arrow next to the Default Data
Server field.
b. Select the data server to be invoked when
you are using the %Server% substitution
parameter for templated attributes that
are tied to the PI point or PI point array
data references.
c. Click OK.
Note: To use the client's local default data server,
select <Inherit local default Data Server>.
 To … Do this …

Enter an alias a. Click .

b. In the New Name field of the New Alias
Name window, enter an alternate name
that users can use to look for the PI AF
server. Aliases are stored locally on the
client.
Configure Active Directory access for contacts See Configure Active Directory access for contacts.
View or modify security permissions of mapped user a. Click Security.
identities
b. In the Security Configuration window, review
the permissions for the listed identities
that have been configured for each server
component. You can add and remove
identities (as well as create new identities
and mappings) as needed. For more
information, see the PI System Explorer
topic Configure security for a PI AF server.
4. Click OK.

Manage identities in PI AF
Use the Identities tab to review identities that are currently assigned to the PI AF server. You can also add,
remove, and edit identities.
Note: Using permissions, you can restrict the identities and mappings visible on the Identities tab except for
three built-in identities: Administrators, Owner, and World. Those identities are always visible. You can also use
permissions to make identities editable or read only. For more information on granting permissions to PI AF
identities, see the PI System Explorer topic Security configuration in PI AF.

1. On the PI System Explorer toolbar, click .

2. In the PI AF Server Properties window, click the Identities tab.
3. Review the alphabetized list of identities. Click a column heading to change the sort order. Enabled identities
are indicated as True, whereas disabled identities are grayed out and indicated as False. The built-in
identities Administrator and World are read only.
4. You can choose from the following actions:
To ... Do this ...

Disable an identity a. Double-click an enabled identity on the list.

b. In the Identity Properties window, clear the
Identity is Enabled checkbox.
c. Click OK.
 To ... Do this ...

Enable an identity a. Double-click a disabled identity on the list.

b. In the Identity Properties window, select the
Identity is Enabled checkbox.
c. Click OK.
Create a new identity a. Right-click and select New Identity.
b. In the Identity Properties window, enter a
name and description for the identity.
c. Optional. Click the Mappings tab and click
Add. For more information, see Add a
mapping to an identity.
Manage security settings for identities a. Right-click a column title or below the list and
click Security.
b. In the Security Configuration window, you
can review or modify permissions for a
listed identity, as well as add or remove
identities as needed. For more
information, see the PI System Explorer
topic Configure security for a PI AF server.
Delete an identity a. Right-click an identity on the list and click
Delete.
b. In the Delete confirmation window, click Yes.
Rename an identity a. Right-click an identity on the list and click
Rename.
b. Enter a new identity name.
c. Right-click and click Check In to apply the
change.

Manage mappings in PI AF
Use the Mappings tab to review mappings that are currently set up on the PI AF server. You can also add,
remove, and edit mappings.
1. On the PI System Explorer toolbar, click .
2. In the PI AF Server Properties window, click the Mappings tab.
3. Review the alphabetized list of mappings. If necessary, scroll rightward to see mapped identities and
Windows accounts.
4. You can choose from the following actions:
 To ... Do this ...

Modify the properties of a mapping a. Double-click a mapping on the list.

b. In the Mapping Properties window, you can
edit the name and description as needed,
as well as select a different identity from
the Identity drop-down list.
c. Click OK.
Create a new mapping See Add a mapping to an identity and Map a role to a
PI AF identity.
Delete a mapping for an identity a. Right-click a mapping on the list and click
Delete.
b. In the Delete confirmation window, click Yes.
Note: If your user account is associated with
the mapping you are deleting, a warning
that you might be locked out is displayed.

Rename a mapping a. Right-click a mapping on the list and click

Rename.
b. Enter a new mapping name.
c. Right-click and click Check In to apply the
change.
Manage security settings for mappings a. Right-click a column title or below the list and
click Security.
b. In the Security Configuration window, you
can review or modify permissions for a
listed identity, as well as add or remove
identities as needed. For more
information, see the PI System Explorer
topic Configure security for a PI AF server.

Add a mapping to an identity

When you add a mapping for an identity, you need to specify the Windows account to be mapped and the name
of the mapping. See Map a role to a PI AF identity if you are using OpenID Connect (OIDC) and want to map a
role.
The security identifier (SID) for the account is generated automatically and cannot be changed while the
mapping is being created.
1. Open the Mapping Properties window.
2. Select the Windows option.
3. In the Account field, enter one of the following object types:
 • User
• Group
• Built-in security principal
• Service account
• Computer name
You can also click and enter search criteria in the Select User, Computer, Service Account, or Group
window to select the object type, location, and name. The available search locations are the local
computer hosting the connected PI AF server and active directory nodes that the user can access.
Note: You can also enter a SID directly in the Account field. When the entry is validated, a domain
identifier is prepended if the account is a domain account. If the account is a local account on the
AVEVA™ PI System™ host machine, the fully qualified domain name is prepended.
4. To validate your entry in the Account field, press Tab or click in another field.
The Account SID field displays the SID of the account, and the Name field defaults to displaying the account
name.
5. In the Name field, modify the default account name as needed.
Text you enter in the Description field is displayed in the PI AF Server Properties window. Use this field to
differentiate between mappings for any given identity (since in PI AF a single user can be mapped to multiple
identities).
6. If an identity has not been selected already, select the identity you wish to associate with the mapping from
the Identity drop-down list.
7. Click OK.
Map a role to a PI AF identity
You can create a mapping from a PI AF identity to an Identity provider (IdP) role. A role represents a group of
users with similar job functions and access permissions. Roles are stored and managed by the Identity provider
service. The AVEVA Identity Manager is the provided identity service for PI Server 2023.
A PI AF identity represents a set of access permissions on the AF server for a Windows user or group. Role
members that are mapped to a PI AF identity inherit the same access permissions as the PI AF identity, such as
access to an element collection or objects. See PI AF identities and mappings for more information.
Prerequisite
OIDC authentication must be enabled.
Procedure
1. Open PI System Explorer.
2. If this is the first time you are opening PI System Explorer, select the OIDC authentication option and sign in
with your OIDC credentials.
3. Select File, then select Connections.
The Servers dialog opens.
4. Select the Properties button.
The PI AF Server Properties dialog opens.
5. Select the Mappings tab.
6. Right-click in the dialog and select New Mapping.
The Security Mapping Properties dialog opens.
7. Select the OpenID Connect option.
Note: If the user has signed on with OIDC, the OpenID Connect option is selected by default.
8. Select the Role magnifying button.
The Select an OIDC Mapping dialog opens.
 9. Select the Roles or Client ID option to filter the list box by Identity provider roles or client ID names.
10. In the list box, select the role or client ID you want to map to the PI AF identity, then select OK.
Note: The roles listed in the Select a Role dialog depends on the identity provider. Roles are created and
configured on the identity server.
11. The role, role ID, and name are added to the Security Mapping Properties dialog.
12. In the Security Mapping Properties dialog, select the Identity down arrow, then select the PI AF identity you
want to map to the role.
13. Select OK.
The role is now mapped to the PI AF identity in PI System Explorer. Users assigned to the role inherit the
same access permissions to AF resources as the PI AF identity.

View PI AF server object counts

You can view object counts for the PI AF server to which you are currently connected, such as the number of
databases, elements, element templates, event frames, and so on.
1. In PI System Explorer, click File > Server Properties.
2. In the PI AF Server Properties window, click the Counts tab.
View RPC metrics
You can view remote procedure call (RPC) metrics for the current server connection. The RPC Metrics page
displays performance data about RPC calls by name, including the number of calls and call duration.
Note: Only users with administrator privileges can view the RPC Metrics page. Beginning with PI AF 2018 SP2,
only certain column headers on the RPC Metrics page are visible.

1. On the PI System Explorer toolbar, click .

2. In the PI AF Server Properties window, click the RPC Metrics tab.
3. You can view, sort, and copy data on the RPC Metrics page:
▪ To sort data by a particular column heading such as Calls or Total Duration, click the column heading.
▪ To copy one row of connection data, right-click the row and then click Copy.
▪ To copy all connection data, right-click the row, click Select All and then click Copy.
4. Review information about each call as needed. You can expand the width of the columns as needed.
5. The RPC Metrics page displays the following information:
Column Title Explanation

RPC Name The name of the client process executed by the server
Calls The number of total calls for the individual RPC since
the server was last started
Total Duration The total length of all the calls to the server from a
particular client
Per Call The average length of each call
Calls (Delta) A count of the number of calls since the list was last
displayed or refreshed
Duration (Delta) The total length of the calls to each RPC since the list
was last displayed or refreshed
Per Call (Delta) The average length of the calls to each RPC that
occurred since the list was last displayed or refreshed
Calls (Client) The number of calls to each RPC that was made by
the client retrieving the RPC metrics
Duration (Client) The length of the RPC call made by the client
retrieving the RPC metrics
Per Call (Client) The average length of the calls to each RPC that was
made by the client retrieving the RPC metrics
Retries The number of times the client process has been
attempted
Note: Use the Refresh button to update the RPC Metrics page with the latest RPC call data.
 View PI AF server connections
You can view, sort, and copy details about PI AF server connections on the Connections page.
Note: Only users with administrator privileges can view information on the Connections page.

1. On the PI System Explorer toolbar, click .

2. In the PI AF Server Properties window, click the Connections tab.
The Connections page opens.
3. You can view, sort, and copy data on the Connections page:
▪ To sort data by a particular column heading such as a start or end time, click the column heading.
▪ To copy one row of connection data, right-click the row and then click Copy.
▪ To copy all connection data, right-click the row, click Select All and then click Copy.
4. The Connections page displays the following information:
Column Title Explanation

Username The name of the user or service connected to the

server
Client Host The host's IPv6 address
Client Port The port that they're connecting from
Authentication Type of authentication protocol used to establish the
connection. There are three types of authentication:
• None: An anonymous connection that occurs
when a client first attempts a connection
• NLTM: A Windows connection
• Oauth 2.0: An OpenID Connect (OIDC) connection
Start Time Time connection began
End Time Time connection ended
Note: Use the Refresh button to update the Connections page with the most current information.
5. To move quickly through a defined number of records, click the Previous or Next button. To change paging
settings, see Search result paging.

Data Archive connections

You can set the default Data Archive, also called the default data server, at the PI AF server and PI AF database
level. Setting the default data server points PI System Explorer to the location of PI point data references. By
default, any database without a default data server set inherits the PI AF server's default data server.
 The %Server% substitution parameter resolves to the default data server. See Find the default Data Archive
server for more information. The following diagram shows the order that the default data server gets resolved
using the %Server% substitution parameter:

• 1. Current AF database
• 2. PI AF server
• 3. Local client machine
1. PI AF checks to see if the current PI AF database's default Data Archive is specified. If specified, PI AF looks
there for stored templated attributes that are tied to PI point or PI point array data references. See View or
edit properties of PI AF databases for more information.
2. If one is not specified for the current database, it resolves to the PI AF server's default Data Archive setting.
See View properties of the connected PI AF server for more information.
3. If none is specified at the PI system level, it resolves to the local default Data Archive.
You can view the default data server for the database and PI AF server using the following methods:
• Use the Database Properties window to view and set the default PI AF server for the database.
• Use the PI AF Servers Properties window to view and set the default Data Archive server for the system.
Note: If the default Data Archive is not specified on the PI AF server or PI AF database, it can resolve to a
different Data Archive for different client machines depending on their configuration.

Connect to Data Archive

Use the Servers window to review Data Archive known server connections, connect to different servers as
needed, and change the authentication mode used to connect if OpenID Connect (OIDC) is enabled.
1. Click File > Connections.
In the Servers window, a list of known servers is displayed in the Known Server Table (KST). Each of the
following icons indicate the type of server and its current connection:
A disconnected PI AF server in the Known Server Table

A connected PI AF server

The default connected PI AF server

A Data Archive in the Known Server Table

The default connected Data Archive
 A disconnected Data Archive collective

A connected Data Archive collective

Note: A warning icon ( ) beside a server indicates that Data Archive is running an unsupported version, such as
version 3.4.375 or 3.4.370. The PI AF client cannot connect to a Data Archive server that is running software
earlier than version 3.4.370.
1. To connect to a Data Archive, choose from the following actions:
To ... Do this ...

Connect to a different Data Archive Select a server in the list and click Connect.
Connect to a server as a different user (for example, a. Right-click a server in the list and click
from a shared computer) or change the Connect As.
authentication mode used to access the server
Ifi.OIDC is not enabled, the Connect to PI
Data Archive server window opens.
Enter a Windows user account name
and password.
Ifii.OIDC is enabled, the Authentication
Mode dialog opens. Select the
authentication mode you want to use
for the connection: OpenID Connect
or Windows.
b. Click OK.
Connect to a server that is not displayed on the Click Add Data Server. For more information, see Add
Known Servers Table PI Data Archive servers to connected server lists.
Set a local default Data Archive Right-click a server in the list and click Set as local
default Data Server. An icon appears next to the
local default data server.
2. Click Close.

Data Archive connection problems

Windows Authentication only uses identity mappings and does not utilize trusts defined with windows
credentials for authentication or any other trusts that may be configured. When connecting to Data Archive,
error messages might appear if there is no PI mapping configured and one of the following conditions exists:
• You are using a PI username and password to login to Data Archive.
• You are using the default user with a blank password to login to Data Archive.
These errors occur because PI AF 2012 and later has more stringent security settings than earlier versions of PI
AF. Clients that connect to Data Archive through PI AF 2012 and later are subject to the following behaviors:
• The default behavior for connections is to not prompt the user for an explicit login unless the Allow login
prompt setting is configured. This setting controls what happens when Data Archive authentication fails. If
the Allow login prompt setting is enabled, a window opens prompting the user for a username and
 password. If the setting is off, an error message is displayed. The setting is specific to each client computer.
For more information, see Configure clients to allow explicit login prompts.
• Default user connections are no longer supported.
To resolve error conditions, configure PI mappings for users connecting to Data Archive. For more information,
see the PI System Management Tools topic Identities, Users, and Groups.
PI Data Archive connection error messages
Error Message Connect Failure Conditions

Insufficient privilege to access Data Archive. Default User connections are enabled in PI SDK.
No Access - Secure Object
Default User connections to Data Archive are
currently enabled from this client but are not
supported from PI AF.
Insufficient privilege to access Data Archive. No Default User connections are the only authentication
supported authentication methods are enabled. method enabled in PI SDK.
No Access - Secure Object
Default User connections to Data Archive are
currently enabled from this client but are not
supported from PI AF.
Insufficient privilege to access Data Archive. Explicit logins setting was not set in registry.
No Access - Secure Object
The explicit login prompt is not configured on this
computer and therefore not allowed.

Configure clients to allow explicit login prompts

If all configured protocols fail, use the PI SDK Utility to allow a login prompt to be displayed.
1. Open PISDKUtility from the Windows Start menu.
2. Click Connections > Options.
3. In the Connection Options window, select the Allow login prompt (if all configured protocols fail) check box.
4. Click OK.
5. Click File > Exit PISDKUtility.

Review digital state sets on a Data Archive

You use the State Sets tab in the PI Data Archive Properties window to review the digital state sets on a specific
Data Archive and compare them to existing enumeration sets in the current PI AF database. You can also export
digital state sets from the Data Archive to create enumeration sets.
1. Click File > Connections.
2. In the Servers window, select a connected Data Archive.
3. Choose one of the following actions.
▪ Right-click and click Properties.
▪ In the taskbar, click Properties.
4. In the PI Data Archive Properties window, click the State Sets tab.
In addition to the digital state sets available on the selected Data Archive, the window displays matching
enumeration sets in the current PI AF database and how many differences exist between them.
5. Choose from the following actions.
To... Do this...

Review differences between a digital state set and its See Review differences between digital state sets and
equivalent enumeration set in the current database enumerations sets.
Export digital state sets on a Data Archive to the See Create enumeration sets from digital state sets.
current database
Refresh the list of digital state sets Right-click the grid and click Refresh.
6. To close the PI Data Archive Properties window, click OK.

Review differences between digital state sets and enumerations sets

On the State Sets tab in the PI Data Archive Properties window, review the differences between a digital state set
on a selected Data Archive and its equivalent enumeration set in the current PI AF database.
1. In the PI Data Archive Properties window, select a digital state set where the Conflicts column indicates that
a number of states are different.
A grid opens with a list of conflicts.
• If a Digital State Name and an Enumeration Value Name are different, both are displayed in boldface
text.
• If a digital state name does not exist in an enumeration set, the Enumeration Value Name is displayed in
boldface text and the Digital State Name is blank.
• If an enumeration value name does not exist in a digital state set, the Digital State Name is displayed in
boldface text and the Enumeration Value Name is blank.
• If a digital state value does not exist in a digital state set but does exist in the enumeration set, the Value
and the Enumeration Value Name are displayed in boldface text and the Digital State Name is blank.
2. Review other digital state set conflicts as needed.
3. Click OK.

Create enumeration sets from digital state sets

In PI System Explorer, select the AF database you wish to create the enumeration sets in.
You can export digital state sets from a Data Archive server into the current PI AF database to create
enumeration sets.
1. In PI System Explorer, click File > Connections.
 The Servers window opens.
2. In the Name column, select the Data Archive server that contains the digital state set, then click Properties.
The PI Data Archive Properties window opens.
3. In the PI Data Archive Properties window, select the State Sets tab, then choose from the following actions.
To... Do this...

Create one or more enumeration sets from digital a. Use standard Windows selection
state sets on the selected Data Archive keystrokes (such as SHIFT+<click> and
CTRL+<click>) to select contiguous and
non-contiguous digital state sets in the
list, where the Enumeration Set cell is
empty and the Conflicts column
displays EnumerationSet 'EnumName'
not found.
b. Right-click and select Create Enumeration
Set from State Set.
c. In the Create EnumerationSets window,
click Yes.
Create enumeration sets from all digital state sets a. Right-click and select Select All.
on the selected Data Archive
b. Right-click and select Create Enumeration
Set from State Set.
c. In the Create EnumerationSets window,
click Yes.
Enumeration sets that already exist are
ignored, but those that do not exist are
created.
4. Click OK.
5. To exit the Servers window, click Close.
6. Check in your changes.

Add PI Data Archive servers to connected server lists

If the Data Archive server you want to connect to is not currently displayed on the Known Servers Table, add it in
the PI Data Archive Properties window.
1. Click File > Connections.
2. In the Servers window , click Add Data Server.
3. In the PI Data Archive Properties window, enter properties as needed.
4. Optional. You can change the default name in the Name field:
a. Click Rename.
 b. In the New Name field in the New PI Data Archive Name window, enter a name for the new Data
Archive. The name does not need to match the host name.
c. Click OK.
5. Enter the host name in the Host field. You can enter:
▪ A fully qualified domain name.
▪ A server name.
▪ An IP address. An IPv6 address must be enclosed in brackets [ ].
6. Unless your particular application requires a different port, accept the default value in the Port field.
Note: You can modify the host name and port only when disconnected from the server.
7. The default values for the Connection Timeout and Data Timeout fields are acceptable in most cases. If you
experience connection timeouts when connecting to Data Archive from PI System Explorer, increase the time
in the Connection Timeout field. If you experience timeout errors while accessing Data Archive data,
increase the time in the Data Timeout field.
8. Optional. Enter an alias name in the Aliases field.
Aliases are alternate names that can be used for Data Archive. Data Archive aliases are stored locally on the
client only.
9. Click Connect to connect to Data Archive.
Note: The ID, Time Zone and Version fields are not editable. ID is the Data Archive ID, Time Zone is the local
time zone of the Data Archive and Version is the Data Archive version.
10. Click OK.

View buffering status for connected Data Archive servers

If PI Buffer Subsystem 4.3 or later is installed and running, you can view the buffer status of a connected Data
Archive server.
1. Click File > Connections.
In the Servers window, each Data Archive server for which a connection is configured displays a buffering
status in the Buffer Status column.
Note: PI Buffer Subsystem versions 3.4.380 and earlier display a status of Unknown.
2. To view more details and manage buffering for a specific Data Archive, click Buffering Manager to open the
Buffering Manager tool.
Note: You can also open Buffering Manager from the PI System Explorer Tools menu.

PI AF database connections
PI AF stores the asset framework objects (elements, templates, and so on) in PI AF databases. You can have
multiple databases in PI AF, although you can connect to only one at a time. You typically work with PI AF
databases in PI System Explorer or in PI Builder. When you start PI System Explorer for the first time, it connects
to the default PI AF database. If no databases are defined, PI System Explorer prompts you to create a new
database.
 Note: The Configuration database is used by PI AF clients, such as PI Web API, as they interact with PI AF. Do not
use this database for your own application data.
Videos
For information on how to create PI AF databases, watch this video:
For information on how to work with multiple PI AF databases, watch this video:
For information on the configuration database, watch this video:

Create PI AF databases
You can create an empty PI AF database with no pre-configured content, or you can load a library that has been
saved on a connected PI AF server.
1. Choose one of the following actions:
▪ Press Ctrl+O.
▪ On the PI System Explorer toolbar, click .
▪ Click File > Database.
2. From the Asset server drop-down list in the Select Database window, select a connected server on which you
have administrator access rights to create a database. Alternatively, click and select a server from the PI
AF Servers window.
3. Click New Database.
4. In the Database Properties window, enter a unique name in the Name field.
5. Optional. Enter a description in the Description field.
6. Choose from the following actions:
To ... Do this ...

Create a new database with no configured content Leave the Load Library field (if displayed) set to
<None>.
Create a database with configured objects from a Select a library from the Load Library drop-down list.
saved library For more information, see PI AF saved libraries.
Create extended properties See Storage of application-specific information.
Set up access permissions for the new database See Configure security for a single PI AF database.
7. Click OK.
The new database is added to the Database list in the Select Database window.

View or edit properties of PI AF databases

Use the Database Properties window to check how many objects exist in each collection type in a PI AF database,
set the default data server, and review or add extended properties and access permissions.
1. On the PI System Explorer toolbar, click .
2. In the Select Database window, right-click a database and click Properties.
3. In the Database Properties window, choose from the following actions:
To ... Do this ...

Review the number of objects in the database Click the Counts tab.
Review or modify the database name and description On the General tab, make changes as needed in the
Name and Description fields.
Review or modify extended properties a. On the General tab, click Extended
Properties.
b. In the Extended Properties window, make
changes as needed in the Name and
Value fields. To create a new property,
click New Extended Property. For more
information, see Create extended
properties.
Review or modify database security a. On the General tab, click Security.
b. In the Security Configuration window, make
changes as needed. For more
information, see Configure security for a
single PI AF database.
Review the properties of the connected server a. On the General tab, click .
b. In the PI AF Server Properties window, review
properties on the General tab, as
described in View properties of the
connected PI AF server.
Change the default data server a. Click the arrow next to the Default Data
Server field.
b. Select the data server to be invoked when
you are using the %Server% substitution
parameter for templated attributes that
are tied to the PI point or PI point array
data references.
c. Click OK.
Note: To use the PI AF Server's default data
server, select <Inherit from PI AF
Server>.
 To ... Do this ...

Load a saved library a. On the General tab, select a saved library

from the Load Library list. For more
information on saved libraries, see PI AF
saved libraries.
b. Click Apply.
4. Click OK.

Connect to a database on a different PI AF server

Use the PI AF Servers window to locate and connect to the PI AF server that contains the database you want to
work with. If OpenID Connect (OIDC) is enabled, you can also change the authentication mode used to connect
to the database.
1. In the Select Database window, click .
2. In the PI AF Servers window, review the list of servers. Note that the default database on each connected
server is also displayed.
3. Choose from the following actions.
To ... Do this ...

Select the server where the database is located Double-click on a connected ( ) server. The PI AF
Servers window closes and the selected server is
displayed in the Asset server field.
Check the properties of a server Select a server and click Properties.
Connect to a server Right-click a server that is not connected ( ) and
click Connect.
Connect to a server as a different user (for example, a. Right-click a server that is not connected and
from a shared computer) or change the click Connect As.
authentication mode used to access the server
Ifi.OIDC is not enabled, the Connect to PI
AF servers window opens. Enter a
Windows user account name and
password.
Ifii.OIDC is enabled, the Authentication
Mode dialog opens. Select the
authentication mode you want to use
for the connection: OpenID Connect
or Windows.
b. Click OK.
 To ... Do this ...

Review access permissions for a connected server a. Right-click a connected server and click
Security.
b. In the Security Configuration window, check
the settings for the listed identities, as
needed.
Note: If you have administrative privileges on the
server, you can also modify the security configuration.
See Configure security for new PI AF databases.

Set the default database

The default database is displayed when PI System Explorer opens for the first time. After the first time you run PI
System Explorer, it will display whatever database was open when you last closed PI System Explorer.
1. On the PI System Explorer toolbar, click .
2. In the Select Database window, right-click a database and click Set as Default Database.
A check mark icon ( ) is displayed over the database icon that is now the default.
3. Click OK.

The structure of PI AF asset models

PI AF objects are organized in a tree structure, similar to the file structure on a Windows computer. In Windows,
rather than having thousands of files on your desktop, you typically group files under folders. The same concept
applies to PI AF elements. Organizing elements into hierarchies makes navigation of the elements easier, and it
also provides insights into how the elements relate to one another.
When you create an asset model, you need to decide on a structure that makes it easy for users to find the
different assets. Consider who your users are and what they will be looking for. For example, maintenance
engineers might want to use PI System Explorer to find and record maintenance information. For this audience
you might want to group assets by equipment type.
For example, if you had three pump elements, you might create an element called Pumps and then place all the
pump elements beneath it. If you had two elements representing tanks, you might put them all under a Tanks
element.
Asset model organized by equipment type

On the other hand, if you have multiple plants in different locations, that same maintenance engineer might
want to see all the equipment located at his own plant. The following illustration shows the same elements
organized by plant.
 Asset model organized by location

You are not restricted to only one organizational strategy. You can use an element reference to include the same
asset in more than one place in the tree. For example, you could choose to organize by equipment type and by
plant as well. In the following illustration, the hierarchy includes the geographical tree and the equipment tree
side by side.
Mixed asset model

You could alternatively nest the equipment organization under the geographical organization.
Note: Limit the depth of your asset hierarchies to 10 levels or less to maintain the performance and
interpretability of your asset data.

Rename databases
You can change the name of a PI AF database as needed.
1. On the PI System Explorer toolbar, click .
2. In the Select Database window, right-click a database and click Rename.
3. Enter a valid name for the database. For rules on object names, see Valid characters in PI AF object names.
4. Click OK.

Search for PI AF databases

To locate a specific PI AF database on a selected PI AF server, use the Search feature.
1. On the PI System Explorer toolbar, click .
2. In the Select Database window, begin typing the name of a database in the Databases field.

The Search icon changes to the Searching icon . Results filter corresponding to how many letters you
type.
3. Select a database in the list and click OK.
The window closes, and you will be working in the selected database.
4. To return to the full list of available databases, press ESC.
 The window closes.

Refresh the list of databases

When other users add databases to the PI AF server, those databases might not be displayed until you refresh.
1. On the PI System Explorer toolbar, click .
2. In the Select Database window, right-click in the list of databases and click Refresh.

Database deletion
When you delete a database, all information contained within that database is removed. Before you delete a
database, therefore, ensure that you have selected the database that you want to delete.
Caution: You cannot undo a deletion. However, you can recover data by restoring your last SQL Server backup.

PI AF and Data Archive collective connections

An administrator needs to configure connection preferences if a PI AF collective or Data Archive collective is
being set up.

Manage connection preferences for PI System Explorer

Use the Server Options window to define how PI System Explorer should connect to a PI AF collective or Data
Archive collective, whether login prompts are allowed, and if you want servers to be added to the Known Servers
Table automatically.
1. In PI System Explorer, choose Tools > Options > Server Options.
2. In the PI AF Server Connection Settings in PI System Explorer section, define how PI System Explorer should
connect to the PI AF server:
 Setting Description

Connection preference Use this preference to influence the selection of a collective member
when a connection is made to a PI AF collective.
• Prefer Primary
PI System Explorer attempts to connect with the primary server
in the collective, and if it is not available, uses the individual
priority settings of the collective member to influence
selection of the server connection. This is the default
setting.
• Require Primary
PI System Explorer is required to connect with the primary
server in the collective. If the primary server is not
available, the connection fails.
• Any
PI System Explorer can connect with any available member of
the collective, and uses the individual priority settings of
the collective member to influence selection of the server
connection.
Server name resolution behavior Use this preference to inform PI System Explorer what action to
perform when it attempts to communicate with one or more PI AF
servers that are not in the Known Servers Table.
• Auto Add
Adds a server to the Known Servers Table automatically if the
computer name is valid and PI System Explorer can find the
server's computer name on the network.
• Auto Add If Resolvable
Adds a server to the Known Servers Table only when the server
name is successfully resolved by a DNS server.
• Do Not Auto Add
Makes no attempt to find a server if it cannot be found in the
existing collective.
Allow login prompt Select this option if you want a login prompt to appear when a
connection to the server fails because of a security exception.
3. In the PI Data Archive Connection Settings in PI System Explorer section, define how PI System Explorer
should connect to Data Archive:
 Setting Description

Connection preference This preference is used to influence the selection of a collective

member when a connection is made to a Data Archive collective.
• Prefer Primary
PI System Explorer attempts to connect with the primary server
in the collective, and if it is not available, uses the individual
priority settings of the collective member to influence
selection of the server connection. This is the default
setting.
• Require Primary
PI System Explorer is required to connect with the primary
server in the collective. If the primary server is not
available, the connection fails.
• Any
PI System Explorer can connect with any available member of
the collective, and uses the individual priority settings of
the collective member to influence selection of the server
connection.
Server name resolution behavior Use this preference to inform PI System Explorer what action to
perform when it attempts to communicate with one or more PI Data
Archive servers that are not in the Known Servers Table.
• Auto Add
Adds a server to the Known Servers Table automatically if the
computer name is valid and PI System Explorer can find the
server's computer name on the network.
• Auto Add If Resolvable
Adds a server to the Known Servers Table only when the server
name is successfully resolved by a DNS server.
• Do Not Auto Add
Makes no attempt to find a server if it cannot be found in the
existing collective.
4. In Protocols in the PI Data Archive Connection Settings section, set the authentication protocols and the
order in which they are used when connections are attempted to known servers.
PI System Explorer attempts to connect using the first protocol listed. If the first attempt fails, it continues
attempting to connect using the other protocol in the list (if selected). If attempts using all protocols fail and
Allow login prompt is selected, the PI Data Archive Login window is displayed.
a. To establish the order used when connecting to a server, use the arrows button to move protocols.
b. Select the Allow login prompt option if you want a login prompt to be displayed when a connection to
the server fails because of a security exception.
 5. Click OK.

Switch collective members

When you connect to a PI AF collective, PI AF automatically connects you to the collective member with the
highest priority (lowest number). You can switch the connection to the next member in the collective list. The
next member in the list is determined by members’ assigned priority.
1. In PI System Explorer, click File > Connections.
2. Right-click the collective and click Switch Collective Member.

Switch to a specific collective member

When you connect to a PI AF collective, you are automatically connected to the collective member with the
highest priority (lowest number). You can switch to a specific member of the collective.
1. In PI System Explorer, select File > Connections.
2. Right-click the collective and click Connect to Collective Member.
3. In the Choose Collective Member window, select the collective member from the Collective Member list to
which you want to connect.
4. Click OK.
You are now connected to the selected collective member.
Chapter 3

Database import and export

You can export a database from PI System Explorer in XML and then restore it from that XML file by importing it
back to PI AF.
To export the database without having to manage XML files, you export the database as a library, as described in
Save databases as libraries.
Videos
For information on how to import and export databases with PI System Explorer, watch this video:
For information on how to import and export databases with import and export utilities, watch this video:

Export a database to XML

This procedure archives PI AF databases into an XML file that you can later restore.
Note: You can also export PI AF objects from a command line utility. See AFExport utility.
1. Click File > Export to File.
2. In the Export to File window, select desired export options (XML export options).
3. Click OK.
PI System Explorer exports the current database into an XML file.

XML export options

The Export to File window contains the following export options.

Export option Result

Include All Referenced Objects Causes dependent references to be exported, as detailed in the All
Referenced Objects table. Use this option to facilitate moving objects
between different PI AF databases.
Include Security Settings Causes the security settings of individual objects to be exported. This
option increases the amount of time required for the export and
subsequent import operations. You must have Administrative privileges
to import objects that have the security setting specified.
 Export option Result

Flatten XML Exports hierarchical objects in a flat format. Exporting in a flat style can
make editing in some tools simpler. Hierarchical objects that will be
exported flat are attributes, attribute templates, elements, and event
frames.
Simplify Configuration Strings Removes Data Archive and tag identifiers from configuration strings for
PI point data references. Additionally, substitution parameters will be
resolved.
Note: This option slows the export process because it requires
evaluation of the saved configuration strings.

Include Default Values Includes the default values assigned to objects. Without this option, a
property that has not been changed from its default setting is not
included in the output. This saves considerable space and time when
you are exporting large amounts of data.
Include Unique IDs Includes the unique ID of each object in the export. By including this
option, you can rename existing items during an import to the same
database. Unless rename is required, it is more efficient to leave this
option turned off.
Library Objects Only Limits the database export to include only library objects (templates,
enumeration sets, reference types, tables, table connections,
categories, and UOM databases).
Include Event Frames, Transfers, Exports event frames, transfers, and cases.
and Cases

All Referenced Objects

The following table lists the objects that are exported when you select Include All Referenced Objects.

XML object type Included reference

AFAnalysis AFAnalysisCategories referenced

AFAnalysisTemplate in Template

AFElementTemplate in CaseTemplate

AFElement in Target

AFSecurityIdentities from SecurityAccessControl (if Include

Security Settings is also selected)
AFAnalysisTemplate AFAnalysisCategories referenced

AFElementTemplate in CaseTemplate

AFElement in Target

AFSecurityIdentities from SecurityAccessControl (if Include

Security Settings is also selected)
AFAttribute Referenced AFEnumerationSets in ValueTypeQualifier when not
from template
AFAttributeTemplate Referenced AFEnumerationSets in ValueTypeQualifier
AFCase AFElementCategories referenced

AFEnumerationSets referenced in attributes without templates

All child AFElements

All AFConnections (not just those added or removed)
AFContact AFSecurityIdentities from SecurityAccessControl (if Include
Security Settings is also selected)
AFDatabase UOMDatabase

AFContacts referenced

AFNotificationContactTemplates referenced

AFSecurityIdentities (if Include Security Settings is also selected)

AFElement and AFModel AFElementTemplate in Template

AFElementCategories referenced

AFEnumerationSets referenced in attributes without templates

AFReferenceTypes to referenced children

Same as above for all child elements

AFSecurityIdentities from SecurityAccessControl (if Include
Security Settings is also selected)
AFElementTemplate Base AFElementTemplates
AFElementTemplates referenced in
AFPort.AllowedElementTemplate

AFReferenceTypes that specifically reference this template

AFElementCategories referenced

AFEnumerationSets referenced in attribute templates

AFSecurityIdentities from SecurityAccessControl (if Include

Security Settings is also selected)
AFEnumerationSet AllReferences adds AFSecurityIdentities from
SecurityAccessControl (if Include Security Settings is also
selected)
AFEventFrame AFElementTemplate in Template

AFElementCategories referenced

AFEnumerationSets referenced in attributes without templates

AFReferenceType from parents

AFElements referenced including full hierarchy of their parent root

elements
Child event frames referenced
AFSecurityIdentities from SecurityAccessControl (if Include
Security Settings is also selected)
AFModelAnalysis AFAnalysisCategories referenced

AFElementTemplate in Template

AFElementTemplate in CaseTemplate

AFElement in Target

AFSecurityIdentities from SecurityAccessControl (if Include

Security Settings is also selected)
AFNotificationTemplate AFNotificationContacts

AFAnalysisTemplate

AFSecurityIdentities from SecurityAccessControl (if Include

Security Settings is also selected)
AFNotification AFNotificationTemplate in Template

AFNotificationContacts

AFAnalysis

AFSecurityIdentities from SecurityAccessControl (if Include

Security Settings is also selected)
AFNotificationContact AFNotificationContactTemplate

Child AFNoticationContacts
AFContact referenced

AFNotificationContactTemplate Child AFNotificationContactTemplates

AFContacts referenced

AFSecurityIdentities from SecurityAccessControl (if Include

Security Settings is also selected)
AFDeliveryFormat DeliveryChannel

AFNotificationRule AFNotificationRuleTemplate

AFNotificationContactTemplate (via Subscribers)

Child AFNoticationContacts
AFContact

AFDeliveryFormat

AFNotificationRuleSubscriber AFNotificationContactTemplate

Child AFNoticationContacts
AFContact

AFNotificationRuleTemplate AFNotificationContactTemplate (via Subscribers)

Child AFNoticationContacts
AFContact

AFDeliveryFormat

AFReferenceType AFReferenceTypeCategories referenced

AFElementTemplates from AllowedParentElementTemplate and

AllowedChildElementTemplate

AFSecurityIdentities from SecurityAccessControl (if Include

Security Settings is also selected)
AFSecurityIndentity AFSecurityIdentities from SecurityAccessControl (if Include
Security Settings is also selected)
 AFSecurityMapping AFSecurityIdentity mapped to

AFSecurityIdentities from SecurityAccessControl (if Include

Security Settings is also selected)
AFTable AFTableConnection

AFTableCategories referenced

AFSecurityIdentities from SecurityAccessControl (if Include

Security Settings is also selected)
AFTableConnection AFSecurityIdentities from SecurityAccessControl (if Include
Security Settings is also selected)
AFTransfer AFElementTemplate in Template

AFElementCategories referenced

AFEnumerationSets referenced in attributes without templates

AFElements referenced in Source and Destination including full

hierarchy of their parent root elements
UOMClass UOMClass for exported class and classes referenced by UOMs in
UOMClass. For example, when the Area class is exported, the Length
class is included because Length UOMs are referenced by many Area
UOMs.
Note: UOMClass export does not include security settings, which are
only exported with UOMDatabase.

UOMGroup (if any of the UOMs in the exported or referenced classes

have an assigned UOMGroup).
UOM for all UOMs belonging to the exported UOMClass.

UOMDatabase AFSecurityIdentities from SecurityAccessControl (if Include

Security Settings is also selected)
UOMGroup. Group mappings are defined under each UOM.

UOMClass

UOM

File format for export and restore

The Import/Export XML format is described in a schema file located in the PIPC\AF installation directory,
OSIsoft.AF.xsd.
Many of the AF Objects support an operation attribute in the XML that allows for deletion. Similarly, you can
execute the Auto Point Config option selectively on elements using this same technique.
 Example
...
<AFElement operation="delete"> <Name>ElementToDelete</Name> </AFElement>
...
Elements and Attributes can be imported using a flat list, in which the relative path of the element or attribute is
included in the name field. Example:
...
<AFElement> <Name>RootElement</Name> ... </AFElement>
<AFElement> <Name>RootElement\ChildElement1<\Name> ... </AFElement>
<AFElement> <Name>RootElement\ChildElement2<\Name> ... </AFElement>
...

Restore databases from exported XML files

You can restore a database that has been exported to XML by importing objects from the XML file.
You can also import PI AF objects with a command line utility. See AFImport utility.
Avoid the Allow Update option when importing objects with duplicate names, such as event frames, into an
empty PI AF database. Otherwise, problems can occur. However, you may then receive a message that objects,
such as units of measure, already exist on the PI AF server. The import does not attempt to make any changes to
existing objects, which means that if there are differences between objects' properties in the XML file and the
destination system, they are not resolved.
1. Click File > Import from File.
2. In the Import from File window, select the XML file that contains the data and select the appropriate options.
Import option Description

Allow Create Allows new objects to be created. If you want to

update existing items, clear this option to prevent
accidental creation of new objects.
Allow Update Allows existing objects to be updated. If you only
want to add new items, clear this option to prevent
existing objects from being accidentally overwritten.
Automatic Check In Allows the import operation to automatically check in
objects as the import proceeds. This reduces the
maximum memory requirements of the operation.
Use this option when you are importing a large
number of objects.
Import option Description

Create or Update PI Points Causes any attributes with a PI point configuration

specified in the XML file to be updated if they already
exist, or created if they do not exist. This option
invokes the appropriate Data Reference CreateConfig
option, which creates or updates PI points, as well as
resolving their substitution parameters and setting
server and point IDs. The performance of the import
operation is negatively affected when this option is
selected.
Note: PI points are not created unless the Tag
Creation check box is selected in the PI Point Data
Reference window.

Preserve Unique IDs Retains any unique IDs that exist in the source XML.
This option is only valid when the Allow Create and
Automatic Check In options are also selected. The
performance of the import operation is negatively
affected when this option is selected. There is no
guarantee that PI AF will preserve unique IDs of
attributes derived from templates because unique IDs
of such attributes are generated based on the
template's unique ID.
Note: Because PI AF servers maintain a cache of
rowids to ids, the import with Preserve Unique IDs
option affects load-balanced PI AF servers differently
from non-load balanced PI AF servers. In a non-load
balanced scenario, removed items will cause the
cache of rowids to ids to be updated. However, in a
load-balanced scenario, the non-connected server
will need to be restarted to have the cache updated
after items are removed, and before the import with
Preserve Unique IDs option is used to restore items
to the same system.

Disable New Analyses and Notifications When enabled (the default), any new analyses or
notifications that are created by the import are
disabled by the import, regardless of the value of the
Enabled property on the analysis or notification. The
Status settings in the XML for existing analyses and
notifications are ignored and they are not modified
when the option is selected.
Export of library objects to another database
You can export library objects (templates, formulas, UOM, and so on) from one database into another.

PI AF saved libraries
A PI AF saved library provides a collection of application- or domain-specific objects that you can import into a PI
AF database. Saved libraries typically include categories, element templates, enumeration sets, reference types,
tables, as well as the unit-of-measure database, which is always included. You also have the option to include
other objects, such as elements and notifications.
Note: Libraries are stored as XML files in the PI AF SQL Server database (PIFD), where they are easily accessible
to other users. By contrast, the Export to File option enables you to export an entire database of objects as an
XML file to your computer or network. The exported file can be imported to a different server altogether.

Save databases as libraries

You save database objects as a library when you wish to make those objects available for import to a different
database on the PI AF server.
1. Click File > Save as Library.
2. In the Save Database as Library window, enter a name in the Library Name field. The library name does not
need to be unique if you plan to overwrite an existing library.
3. Optional. Enter a description of the library content in the Description field.
4. To replace an existing library, select the Replace existing Library without prompting check box.
5. To include objects such as elements and notifications in the library, select the Include non-library objects
check box.
6. Click OK.

Load database libraries

You load a database library from a set of libraries that have been previously saved in the PI AF database.
1. Click .
2. In the Select Database window, select the database into which you want to load a library, and click OK.
3. Click File > Load Library.
4. In the Load Library into Database window, select a library from the list and click OK.
The objects in the loaded library populate the current database. To confirm how many objects are loaded, view
the Count tab in the Database Properties window, as described in View or edit properties of PI AF databases.

Review properties of loaded libraries

You view the properties of libraries that have been loaded on the PI AF server in the PI AF Server Properties
window. You can change a library name and description.
1. Click File > Server Properties.
2. In the PI AF Server Properties window, click the Libraries tab.
 The libraries that are currently installed are listed.
3. Right-click the library you want to review and click Properties.
4. Optional. In the Library Properties window, you can change the library name and description as needed.
5. Click OK.

AFExport utility
The AFExport utility is a command line application that you can use to archive PI AF databases into an XML
format that you can restore later. Use this utility to archive elements, templates, event frames, transfers, and
other objects from a PI AF database. You can also export collections of PI AF objects from the PI System Explorer.
See Export a database to XML.
The AFExport.exe utility is located in the \PIPC\AF folder.
To run the PI AF Export utility you open a command window and navigate to the PIPC\AF folder. Use the
following syntax: AFExport.exe and choose from the parameters listed in AFExport utility parameters. To display
all parameters, type: AFExport /?

Guidelines for exporting collections

You should follow these guidelines as you prepare to export a collection:
• Specify collections by their PI AF SDK property name, followed by "[ ]".
• Identify individual members of a collection by placing their name within the brackets.
• If no collection name is specified, the default child collection for that location in the path is assumed.
• The default child collection of a PI AF server is Databases.
• The default child collection of a database is Elements.
• The default child collection of an element is Elements.
• The default child collection of UOM database is UOM.
• A vertical bar (|) indicates an attributes or attribute templates collection.

AFExport utility parameters

The AFExport utility supports the following parameters.

Parameter Short form Description

Path Path to the object that you wish to export.

Typically of the form: \\afserver\database.
Additional details and examples follow this
Use '.' to export the default database. See
table.
Sample export paths.
/File:string /F Specify an output file. If not specified, then
the output is streamed to the console.
Parameter Short form Description

/StartTime:string /T Specify a start time to cause event frames,

transfers, and cases to be exported that
are between the start and end times
specified.
/EndTime:string /E Specify an end time when exporting event
frames, transfers, and cases.
/AllReferences[-] /A Export any referenced object from the
specified PI AF object. This parameter
cannot be used with the No References
parameter.
/NoReferences[-] /N Do not export any referenced objects,
including child objects. This parameter
cannot be used with the All References
parameter.
/DefaultValues[-] /D When this parameter is not specified, then
properties that are set to the default
values are not exported, resulting in a
substantially smaller export file. Importing
a file without default values over existing
objects may result in values not being
reset to their defaults.
/Library[-] /L Export only the library objects from a
database. Library objects include all
categories, templates, enumeration sets,
reference types, and tables.
/Security[-] /Y Export security information. Exporting
security information will increase both
export time and subsequent import times.
/SimplifiedConfigStrings[-] /Sc Export configuration strings for attribute
templates or attributes derived from
attribute templates without substituting
parameters and do not export UniqueIDs
or point identifiers in the configuration
strings.
/UniqueIDs[-] /U Export unique IDs of all objects. This allows
the renaming of objects when imported
back into the same database. This
parameter increases the size of the output
file and may increase the amount of time
required to import.
 Parameter Short form Description

/Silent[-] /S Silent mode. Prevents informational

messages from being displayed. If no
output file is specified, this option is
automatically chosen.
/Summary[-] /M Summary mode. Output only minimal
information on progress. This parameter is
not valid with the Silent mode or if no
output file is specified.
/User:string /user Use to specify a different Windows user
account to connect to the PI AF server.
/Password:string /pw If a user name is specified, specify the
network credentials password.
/Version /V Use to display version information. All
other parameters are ignored.
/Flat[-] /flat Export hierarchical object in a flat format.
Exporting in a flat style can make editing in
some tools simpler. Hierarchical objects
that will be exported flat are attributes,
attribute templates, elements, and event
frames.
/Paste[-] /Pa Paste operation behaves as a typical copy/
paste.
/?, /help Prints the contents of this table.
@file Use the specified file to provide additional
input arguments. The file should contain
one argument per line. Comment lines
start with the # character.

Sample export paths

The following table contains sample syntax to export different database components.

To export ... Use this syntax ...

The default database .

The database MyDatabase on the default PI AF server \\.\MyDatabase
The element MyElement in the database MyDatabase \\MyAFServer\MyDatabase\MyElement
on the PI AF server named MyAFServer
All element templates in the database MyDatabase \\.\MyDatabase\ElementTemplates[]
 Element template T1 in the database MyDatabase \\.\MyDatabase\ElementTemplates[T1]

All enumeration sets in the MyAFServer default \\MyAFServer\.\EnumerationSets[]

database
All attributes of MyChildElement in the MyAFServer \
default database \MyAFServer\MyElement\MyChildElement\Attrib
utes[]

The UOM database (UOMDatabase is case sensitive) \\.\UOMDatabase

All tables in the MyAFServer default database \\MyAFServer\.\Tables[]

AFImport utility
The AFImport utility is a command line application that you can use to restore PI AF objects into a database. You
can also use Import from File in PI System Explorer to restore database objects. See Restore databases from
exported XML files.
The AFImport.exe utility is located in the \PIPC\AF folder.
To run the AFImport utility, you open a command window and navigate to the PIPC\AF folder. Use the following
syntax: AFImport.exe and choose from the parameters listed in AFImport utility parameters. To display all
parameters, type:
AFImport /?
Syntax Example #1
To import database objects from an XML file into a PI AF database and create or update PI point configuration for
newly created elements, enter:
AFImport "\\AFServer\database" /File:"C:\Filename.xml" /P
Note: Using the /P (/CreateUpdatePIPoints) parameter may significantly impact import performance.
Syntax Example #2
To import database objects from an XML file into a PI AF database and disable the validation of configuration
string settings for data references and delivery channels, enter:
AFImport "\\AFServer\database" /File:"C:\Filename.xml" /D
Note: Use the /D (/DisableConfigStringValidation) parameter to improve the speed of an import operation. Keep
in mind that using this parameter bypasses looking up PI points, which corrects or adds server IDs and point IDs
to configuration strings.
Syntax Example #3
To import database objects from an XML file into a sub-element under a PI AF database, enter:
AFImport "\\AFServer\database\element" /File:"C:\Filename.xml"

AFImport utility parameters

The AFImport utility supports the following parameters.
Parameter Short form Description

Path Path to the object into which you want

to import. Typically of the form: \
\afserver\database. Use '.' to import
into the default database.
/File:string /F Specify an input file. If not specified, the
import operation reads from the
standard input.
/AutoCheckIn[-] /A Automatically check in changes during
an import operation. Default value: True
/Create[-] /C Allow import operation to create new
objects. Default value: True
/Update[-] /U Allow import operation to update
existing objects. Default value: True
/CreateCategories[-] /CC Create categories that do not exist but
are referenced by objects in the input.
Default value: True
/CreateUpdatePIPoints[-] /P Create or update PI point configuration
for newly created elements. This option
can significantly affect import
performance.
Parameter Short form Description

/PreserveUniqueIDs[-] /Pid Retain unique IDs that exist in the source

XML. This option is only valid when /
Create and /AutoCheckIn are also
specified. This option can significantly
affect import performance.
There is no guarantee that PI AF will
preserve unique IDs of attributes derived
from templates because unique IDs of
such attributes are generated based on
the template's unique ID.
Note: Because PI AF servers maintain a
cache of rowids to ids, the import with
Preserve Unique IDs option affects load-
balanced PI AF servers differently from
non-load balanced PI AF servers. In a
non-load balanced scenario, removed
items will cause the cache of rowids to
ids to be updated. However, in a load-
balanced scenario, the non-connected
server will need to be restarted to have
the cache updated after items are
removed, and before the import with
Preserve Unique IDs option is used to
restore items to the same system.

/DisableNewAnalysesNotifications[-] /DN New analyses and notifications are

created in a disabled state. Existing
analyses and notifications in the
destination database are not affected.
/DisableConfigStringValidation[-] /D Disable the validation of configuration
string settings for data references and
delivery channels, which can improve
the speed of the import operation.
However, this will bypass looking up PI
points, which corrects or adds server IDs
and point IDs to configuration strings.
/GenerateUniqueNames[-] /G Generate unique names for objects
when an object with the same name
already exists.
/Paste[-] /Pa Paste operation behaves as if this is a
copy/paste process. Depending on
where the data is imported, this affects
whether a new name is generated.
Parameter Short form Description

/ContinueOnError /CE Specify the behavior of the import

process when a recoverable error occurs.
The three options available are Yes, No,
and Prompt. The default value is Prompt,
unless running silently in which case the
default will be to cancel the import
process.
/Silent[-] /S Silent mode. Prevent informational
messages from being displayed.
/Summary[-] /M Summary mode. Output only minimal
information on progress.
/User:string /user Use to specify a different Windows user
account to connect to the PI AF server.
/Password:string /pw If a user name is specified, specify the
network credentials password.
/Version /V Display version information. All other
parameters are ignored.
@file Read response file for more options. The
response file contains one parameter per
line. Comment lines start with the #
character.
Chapter 4

Retrieval of asset information

PI System Explorer provides a variety of methods that you can use to locate and review the assets in your PI AF
database, including a browser, search windows, trends to verify formulas and calculations, and version
management. You can also review time series data for attributes that contain or reference such data.

Asset browsing
You use the PI System Explorer browser to display asset objects in the PI AF database. The browser displays the
following assets, depending on the asset type that you have selected in the navigator pane:
• Elements
Displays element assets and element searches in a tree format. You can control how many elements are
displayed per page.
• Event Frames
Displays event frame and transfer search collections. Because asset models can comprise thousands of event
frames or transfers, these objects are not displayed in a hierarchy in the browser. Instead, each has a search
collection in the browser. Recent searches are also listed under the search collection.
• Library
Displays object collections for Templates (for elements, event frames, models, and transfers), Enumeration
Sets, Reference Types, Tables, Table Connections, and Categories (for analyses, attributes, elements,
notification rules, reference types, and tables). To see all the objects of a particular type, you expand the
collection for that type.
• Unit of Measure
Displays all UOM classes in the Unit of Measure database. When you select a class, UOMs belonging to that
class are listed in both the viewer and the conversion calculator.
• Contacts
Displays a list of contact searches, escalation teams, groups, and stand-alone delivery endpoints for use with
notifications.

Element browsing
Elements are displayed as a tree in the browser. The structure of the element tree is different for each
organization. The asset model designer chooses structure that is relevant to the users in the organization. In the
following illustration elements are organized by plant location. If you were in charge of all the equipment for a
 particular plant, then such a model might make sense for you. A different model might be more useful for
someone with a different role.

The element tree can include different sub trees that provide different context for the same assets. This allows
users to find elements in the context that makes the most sense for the task at hand. For example, in addition to
the organization by plant location shown above, you might also have an organization by equipment
manufacturer, as shown in the following illustration.

The elements representing the pumps appear in both the Manufacturers and the Plant Location hierarchies. In
the Manufacturer hierarchy, the pump elements are not new separate elements, rather they are references to
the elements that already existed in the Plant Location tree. To indicate that they are element references, they
are represented by the referenced element icon .

Configure browser page size

The PI System Explorer browser is paged. This means that it displays a certain number of objects at a time. If
more objects exist, PI System Explorer displays them in another page. When this happens, you see
and in the browser.
By default, the maximum number of objects displayed in the browser is 1000. You can change that number.
1. In PI System Explorer, select Tools > Options.
2. On the General tab, type the maximum number of objects that can be displayed in the browser in the
Maximum Tree Branch Page Size field.
3. Click OK.
 Open additional browser windows
Occasionally, you may find it convenient to open additional browser windows. For example, you can have the
Unit of Measure database displayed in one browser instance while creating a new template in the Library
browser.
1. In the navigator pane, right-click the item you want to open in another window.
2. Select Open in New Window.
3. To move between windows, click the PI System Explorer icon in the Windows taskbar and select the
thumbnail of the window you want.

Asset and asset data searches

PI System Explorer provides a variety of options for finding assets, asset data, and PI points.
• Find data for a specific piece of equipment. For example: PI point data, calculation results, maintenance
information, and so on. For example, you can use PI System Explorer to find information about a specific tank
at a specific plant.
• Find all equipment with specified attribute values or value ranges. For example, get a list of all tanks with
temperature greater than 200 °F.

Quick search
You can use the quick search box at the right end of the PI System Explorer toolbar to find elements, event
frames, element templates, or UOM (unit of measure) types.
1. Make a selection in the navigator pane to set the context for quick search.
For example, select Event Frames to set quick search to search for event frames.
2. In the quick search box, select a search constraint from Actions , enter search criteria, and press Enter.
Search results are displayed in the viewer, as well as in the browser.
Note: Search results that are displayed in the browser remain there for easy access in the event you need them
again. You can right-click and delete them from the browser; they are also removed when you exit PI System
Explorer. You can right-click and save them to keep them until you delete them.

Search result paging

When you are searching large numbers of elements or event frames, you can use the Set Maximum Query Size
option to return quick search results back in manageable chunks. This is called paging. Change the Set Maximum
Query Size value to the number of objects you want to see in the search results at one time. If the search returns
a greater number of objects than the Set Maximum Query Size value specifies, the results are paged.
For example, if the Set Maximum Query Size value is 100,000 the PI AF server attempts to find 100,000 matching
objects before returning the results. You probably would not want to wait for the server to find that many
matches, nor would you want to see that many matches in a single page of search results. If you change Set
Maximum Query Size to 100, the PI AF server would send you the results after each 100 matches, and you
would see 100 objects at a time in the search results.
 Search result rules
• Only search results for elements, transfers, and event frames are paged.
• The Set Maximum Query Size setting applies only to quick searches of elements, transfers, or event frames.
If you are searching other objects, the search ignores the Set Maximum Query Size value.
• In search windows, the Results per Page value overrides the Set Maximum Query Size value.

Maximum query sizes

A system default controls the number of objects that can be returned by a search query. Users can override the
system default by specifying a different value in Element Search, Attribute Search, Event Frame Search, and
Transfer Search windows.
System default
You set the Maximum Query Size option in Tools > Options. This sets the default value for PI System Explorer.
Custom sizes
You can override the system default for a specific search by setting a custom value for Maximum results. For
event frames, you specify a custom value in the Results per Page field.

Searches on a specified date

You can conduct a search in PI System Explorer at a specified time and date, by entering that time setting for
Query Date. PI System Explorer also displays object versions for that date. See Query Date and PI System
Explorer time for information on what objects are affected by Query Date.
In addition, you can set a time or time range that applies only to displayed attribute values and leaves in place
the Query Date setting. To do this, establish a time context in the Set Time Context window, as described in Set
time context for displayed attribute values.

Search for PI points

Use the Tag Search window to retrieve PI points that match your search query criteria. In PI AF and PI Builder
2017 or later versions, you can create a search query based on both PI point attributes and PI point values.
Note: To create PI point data references directly from PI points retrieved from a PI point search, select View >
Palette > Tag Search. For more information, see Create direct PI point data references from Tag Search results.
1. In the navigator pane, click Elements.
2. Select Search > Tag Search.
3. In the Tag Search window, select the Data Archive computers on which you want to search.
To add or change Data Archive computers, choose from the following actions:
▪ Click next to the Server(s) field and click a Data Archive on the list.
▪ Click and double-click on the Data Archive you wish to add from the list in the PI Data Archives
window.
▪ To remove a selected Data Archive, select the server name in the Server(s) field, right-click and click
Delete.
 Servers are added in alphabetical order to the existing selection. You can add multiple selections from either
list.
4. You create a PI point search query in the text box next to the Search button. A search query comprises a filter
name, which can be a text string, a PI point attribute (defaults to tag) or a PI point value (for example, Value),
an operator (defaults to :=), and a query filter (defaults to *, or all PI points). For a full description of the
syntax of a PI point query, see Syntax for PI point searches.
Examples of attribute queries are:
• sin*
• tag:=sin*
• tag:<>sin* datatype:float
• step:0 AND pointsource:L
• tag:<>sin* AND PointType:Float64
Examples of value queries (which you can combine with attribute queries) are:
• Value:>1000
• tag:<>sin* AND Value:>10
• PointType:Int32 AND Value:>10
• PointSource:L AND Annotated:1 AND TimeStamp:t
• creationdate:>y-1d AND future:true AND timestamp:<*
By default, PI AF searches for point names that start with the query string (meaning that the Starts With
filter is already selected).
Note: Queries that contain a query filter name (such as name:*sine*), search tag attributes only. In
previous versions of PI AF, queries that contained a query filter name would search the descriptor
attribute as well as the specified query filter, unless the descriptor attribute was actually specified as part
of the query filter.
To build a search query, choose from the following actions.
To ... Do this ...

Clear previously selected criteria Click Reset.

All queries are cleared, as well as the Include
Description in Search filter.
Include point descriptions in a query a. Click .
b. Click Add Criteria or press ALT+C.
c. Select Include Description in Search and set
the value to True.
To ... Do this ...

Type a query directly in the search text box a. Type the first character of the query.
b. Select from the list of matching point
attributes and values, or continue typing
a point attribute or value manually.
c. Enter the criteria to be matched.
Include common PI point attributes in a query a. Click .
b. Enter criteria in any of the following fields:
Name
• (alias for tag attribute)
Point
• Source
Data
• Type (alias for pointtype attribute)
Point
• Class (alias for ptclassname
attribute)
c. To enter criteria for engineering units and
description, click Add Criteria or press
ALT+C. Then click Engineering Units
and/or Description.
Criteria are appended to the string in the
search text box, separated by a space.
Note: The search query returns only PI points that
match all criteria.
 To ... Do this ...

Include PI point values in a query a. Click .

b. Click Add Criteria or press ALT+C.
c. Click any of the following criteria:
Value
•
•
TimeStamp
IsGood
•
Annotated
•
Substituted
•
Questionable
•
a. Enter criteria in the fields you have selected,
as required. Note that you can select a
comparison operator for Value and
TimeStamp criteria.
Criteria are appended to the string in the
search query text box, separated by a
space.
Note: The search query returns only PI points that
match all criteria.

Clear an existing query, or remove a criterion from Click x.

the expanded search area
Use a previous query a. Click .
b. Click Recent Searches.
c. Select the existing query from the list.
Filter point names by contents, exact match, or a. Click .
ending
b. Click the appropriate filter:
Contains
•
Exact
• Match
Ends
• With
5. Click Search to retrieve the points that match into the results table.
6. Choose from the following actions.
To ... Do this ...

Review time series data Right-click a PI point and click Time Series Data. For
more information, see View time series data.
 To ... Do this ...

Create a trend Right-click a PI point and click Trend. For more

information, see Create trends.
Add a PI point to an existing trend Right-click a PI point and click Add to Trend.

Review current PI point values, time stamps, and Right-click a PI point and click Properties.
attributes
Create a PI point data reference For search results displayed in the palette only.
Drag a PI point onto the Attributes grid. For more
information, see Create direct PI point data
references from Tag Search results.
Change the columns in the results table Click and clear the columns that you want to
remove.
Add attribute columns to the results table a. Right-click a column heading and click Add
Column.
b. In the Select Point Attributes window, select
the point attributes to be added.
c. Click OK.
Restore original columns in the results table Right-click a column heading and click Restore
Original Columns.
7. Click OK.
The results are displayed in the viewer. Each search is temporarily listed in the browser with a Tag Search
Results label. To differentiate between searches, you can change a label by right-clicking and clicking
Rename.

Syntax for PI point searches

Refer to the following sections for details on the syntax for building PI point queries in PI AF and PI Builder. For
complete details on PI point query syntax, see “PIPoint Query Syntax Overview” in PI System Explorer Help > AF
SDK Reference > Overview, or go to the Tech Support page PI Point Query Syntax Overview.
Condition filters
To build a PI point query, enter one or more AND condition filters that you can also combine with an OR
condition as needed. Each AND condition contains one or more queries, separated by a space or AND. A query
consists of a query filter name, an operator, and the query filter. This enables you to specify multiple conditions
with a single query, as shown in the following example:
(tag:<>sin* AND PointType:Float64) OR (tag:="*Tank*" AND DataType:=Int32)
Note: You can only use parentheses between OR conditions.
You can only reference a filter name once per AND condition of the query string. For example, PointId:>5 AND
PointId:<10 generates an error, whereas PointType:=Int32 OR PointType:=Float32 is valid.
For maximum efficiency, build your query so that you eliminate most items from the retrieved results with your
first condition filters.
Query filter names
When querying based on PI point attributes, the query filter name is a PI point attribute name or alias. Common
aliases are:

Alias name Attribute name

Name Tag
DataType PointType
Description Descriptor
PointClass PtClassName
Starting in PI AF 2017, you can query based on values, in addition to querying PI points based on attribute.
However, you cannot use the OR condition to query a PI point value. For example, you would generate an error if
you were to enter the following queries:
• IsGood:false OR Annotated:true
• PointType:Float AND Value:>10 because PointType:Float is implicitly translated to
'PointType:=Float16 OR PointType:=Float32 OR PointType:=Float64'
• PointType:Int AND Value:>10 because PointType:Int is implicitly translated to 'PointType:=Int16
OR PointType:=Int32'
• sin* AND Value:>10 because sin* is implicitly translated to 'tag:=sin* OR Descriptor:=sin*' if the
default filter setting for Include Description in Search is selected. To be valid, you would need to clear the
Include Description in Search filter.
Wildcard characters
You can use the following special characters in a PI point query.

Special character Description Example

* Substitute any number of sin*

unspecified characters
Returns all PI points that have names starting with
"sin", for example, sinusoid and sinusoidu.
? Substitute a single unspecified CD?158
character
Returns all PI points that have names starting with
"CD", followed by any single character, followed by
"158" (for example, CD1158, CDA158, and so on).
Special character Description Example

: or := When searching for all PI points pointsource:R

with a specific attribute value
Returns all PI points that have the pointsource value
(other than name), separates the
R.
attribute and the value you are
searching for. "ba:temp.1"

Note When searching for a PI point ba\:temp.1

name that contains a colon, enclose Either of the above examples returns the PI point
the name in double quotation named ba:temp.1.
marks, or precede the colon with a
backslash.

'' Delimiters for search strings '*Owner Change*'

containing spaces or special
or or
characters
"" "*Owner Change*"
Returns all PI points that have names containing
Owner Change.
"ba:temp.?"
Returns all PI points that have names starting with
ba:temp. and ending with any single character.
Note: Results of the examples above assume you are using the default search option, which searches for PI point
names that start with your search string.
Operators
The following table lists the operators that you can use in an AND condition.

Operator Description Example

= The EQUALS operator. Tag:Tank* or Tag:=Tank*

<> The NOT EQUALS operator. PointType:<>Int32

< The LESS THAN operator. Descriptor:<M

<= The LESS THAN OR EQUAL operator. Tag:<=Tank

> The GREATER THAN operator. Tag:>Tank

>= The GREATER THAN OR EQUAL operator. Tag:>=Tank

In PI point value queries with a String data type, you cannot use the following operators: <, <=, >, or >=.
Furthermore, when boolean values are expected (as with Substituted, Questionable, Annotated, and IsGood
point value queries), you can only use the = and <> operators.
 Syntax restrictions
• You cannot query future point attributes, such as creationdate:>y-1d AND future:true, on Data Archive
servers older than 3.4.395.
• You cannot query security point attributes, such as PtSecurity and DataSecurity, on Data Archive servers
older than 3.4.380.

Manage search results

PI System Explorer displays all search results in the browser where you can save them in a searches collection for
reuse, rename them, or edit the criteria. All unsaved search results are indicated by an asterisk.
Note: All unsaved search results are deleted when you exit PI System Explorer.
1. Optional. To work from a list of search results in the viewer rather than in the browser, choose from the
following actions:
To ... Do this ...

Manage an element or attribute search a. In the navigator, click Elements.

b. In the browser, click the Element Searches
collection.
Manage an event frame search a. In the navigator, click Event Frames.
b. In the browser, click the Event Frame
Searches collection.
Manage a transfer search a. In the navigator, click Event Frames.
b. In the browser, click the Transfer Searches
collection.
2. Select a search and choose from the following actions:
To ... Do this ...

Save a search result Right-click an unsaved search result name and click
Save.
Rename a search result a. Right-click a search result name and click
Rename.
b. Type a new search result name.
Copy a search result Right-click the search result name and click Copy.
Edit criteria for a search result a. Right-click a search result name and click
Properties. (In the viewer, you can also
double-click a search result name.)
b. Modify search criteria as needed and click
OK.
 To ... Do this ...

Delete a search result a. Right-click a search result name and click

Delete.
b. Click Yes in the Delete confirmation window.
Rearrange event frame or transfer search results In the browser only:
a. Right-click an event frame or transfer search
result name and click Arrange By.
b. Select from the following options:
Arrange
• By Name
Arrange
• By End Time
Arrange
• By Start Time
Arrange
• By Category
Arrange
• By Template
Display the full path to elements or event frames In the viewer only:
a. Right-click on the column header (or below
the search results grid).
b. Click Show Full Paths.

Search for elements

Use the Element Search window to retrieve element data that matches your search criteria.
1. In the navigator pane, click Elements.
2. Choose from the following actions:
▪ From the PI System Explorer menu, select Search > Element Search.
▪ In the browser, right-click the Element Searches root node and select New Search.
3. Set the Element Search window to find the desired element or elements in the PI AF database.
Note: If you enter values for multiple criteria, the search returns only those elements that match all the
specified criteria.

4. From the Actions list, select the type of filter to apply: Contains, Exact Match, Starts With, or Ends With.
5. Choose from the following actions:
To ... Do this ...

Type one or more filter conditions directly into the Enter element criteria field • Use the : or := operator t
• Use special characters as
• Enclose strings that cont
To ... Do this ...
• Separate filter condition
Category:"Processing
Beginning with PI AF 2018 SP2, y
• "Name:’ElementName’
• "Description:’TestDe
Filter elements under Criteria Enter values in the following field
• Name
Enter the name of the element to retrieve, based on the filter type. You can enter special characters to
match part of a name. See Special characters in name searches.
• Element Search Root
Enter the element that you want to use as the root or base level for the element search. Type the exact
name or click to open the Element Browser window, where you can view the element hierarchy
and select an element. You cannot include wildcard characters in the entered name. If you do not
specify an element, you set the main level of the element hierarchy as the root.
Depending on your PI AF hierarchy, specifying an element in the Element Search Root field can improve
search performance.
• All Descendants
Select True to retrieve any sub-element in the hierarchy that matches the specified criteria. Select False
to retrieve only root-level elements that match the specified criteria.
• Template
Select the template that retrieved elements must be based on. After you select a template, you can add
criteria to find elements by attribute value.
• Category
Select the category that retrieved elements must match.
• Attribute Value
You can specify up to three conditions for an attribute value. For each condition, specify an attribute
name, operator, and attribute value, such as Temperature >= 98.
In•versions prior to PI AF 2018, only available when you specify a template. For more details, see
Configure search conditions for attribute values when a template is specified.
In•PI AF 2018 and later versions, you can specify attribute values without needing to specify a
template. For more details, see Configure search conditions for attribute values when no
template is specified.
• Description
Enter a string (of up to 440 characters) that retrieved elements must match.
• Element Type
 Select the type that retrieved elements must match.
• Is Annotated
(PI AF 2017 or later versions.) Set to True to retrieve only elements that have annotations. Set to False
to retrieve only elements that do not have annotations.
• Creation Date

(PI AF 2017 or later versions.) Select an operator and enter a date or a PI time abbreviation ( >= *-30d
is the default) to retrieve elements that were created in the specified period. You can also click to
select a date in the Date and Time Picker window. You can select Creation Date a second time and
filter the search for results between two values (< *+1d is the default).
• Modify Date

(PI AF 2017 or later versions.) Select an operator and enter a date or a PI time abbreviation ( >= *-30d
is the default) to retrieve elements that were modified in the specified period. You can also click
to select a date in the Date and Time Picker window. You can select Modify Date a second time and
filter the search for results between two values (< *+1d is the default).
Note: An element's modify date is updated whenever an annotation or child element is added, as well
as when a change to its configuration is checked into the database.
Most template changes, or any modification to an attribute value that is not a configuration item, will
not affect an element's modify date.
• Results per Page
Enter the maximum number of elements to show on a single page of the search results.
6. Optional. Specify how you want results to be displayed in the Results table.
To ... Do this ...

Group by template Select the Template check box.

Group by category Select the Category check box.

Change column selections a. Right-click the column heading in the Results table or the white space b
b. Click Column Visibility.
c. Select or clear column selections as needed.
Display attributes as columns a. Click and click Select Attributes.
b. In the Select Attributes window, use standard Windows keystrokes to hi
c. Click .
d. Click OK.
Display full paths of elements a. Right-click the column heading in the Results table or the white space b
b. Click Show Full Paths.
 To ... Do this ...

Conceal full paths of elements a. Right-click the column heading in the Results table or the white space b
b. Click Hide Full Paths.
7. Select any of the results you want to use and click OK.
The results are displayed in the viewer and in the browser tree. For more information on working with
search results, see Manage search results.
8. Select any of the results you want to use and click OK.
The results are displayed in the viewer and in the browser tree. For more information on working with
search results, see Manage search results.

Configure search conditions for attribute values when a template is specified

Before you configure search conditions, you should be aware of the following:
• Unindexed attributes can take a significant amount of time to evaluate, particularly if they are configured
with a data reference.
• You cannot search for attributes with Object or Array value types.
You can restrict your search based on the value of an attribute. After you specify a template (required in versions
prior to PI AF 2018), use the Attribute Value field to configure up to three conditions that the search must match
regarding an attribute value.

1. Click (Display attribute choices) and select an attribute from the list of possible attribute categories:
Option Description

Indexed attributes, including configuration attributes.

Configuration attributes that are not indexed.

Non-configuration attributes that are not indexed.

2. Click , and select a mathematical operator from the list.

▪ For attribute value types Single and Double, queries do not support the In operator.
▪ For attribute value types String, Boolean, and Int64, queries do not support the following operators:
• < (less than)
• > (greater than)
• <= (less than or equal to)
• >= (greater than or equal to)
3. Enter a value in the units specified by the default UOM in the attribute template.
Note: For indexed attributes that store String value types, the search only uses the first 40 characters of the
entered value.
 Configure search conditions for attribute values when no template is specified
Before you configure search conditions, you should be aware of the following:
• When no template is selected, all attributes are searched, including those used in templates.
• When no template is selected, wildcard characters should not be used in the Attribute Value field.
• Unindexed attributes can take a significant amount of time to evaluate, particularly if they are configured
with a data reference.
• You cannot search for attributes with Object or Array value types.
When using a PI AF 2018 or later client and connected to a PI AF 2018 or later server, you can restrict your search
based on the value of an attribute, without first having to specify a template. Use the Attribute Value field to
configure up to three conditions that the search must match regarding an attribute value.
1. From the Add Criteria list, select Attribute Value.
2. In Attribute Value, enter the name of the attribute to retrieve.

3. Click , and select a mathematical operator from the list.

4. Enter a value. If the value type is Enumeration Set or Guid, you also need to append as Enumeration_Set
or as Guid to the search query displayed in the Enter element criteria field.
For example, to search for assets with a Health Status attribute value of Error, you would enter the following
as the Attribute Value criteria:

To complete the search query, you would append the name of the Health Status enumeration set to the
string already displayed in the Enter element criteria field:
as 'Health Status'
The completed search query in the Enter element criteria field would look as follows:

Note: Keep in mind the following guidelines when appending to search queries:
• Append As String or As Numeric whenever the value type of an attribute does not match what the
query search value appears to be.
• For example, if the value type of an attribute were String and the search value were 55 (which looks like
a numeric), you would need to append As String to the query.
• Use uppercase and lowercase combinations when you append to search queries: As String, as
string, and as STRING are all equivalents.
• Use either ' or " to enclose enumeration sets and strings that contain space characters.

Special characters in name searches

When searching for objects by name, such as element names, event frame names, or attribute names (when
associated with a template), you can use special characters:
 Special character Purpose

* Substitute any number of unspecified characters.

? Substitute a single unspecified character.
[xyz] Specify a set of characters (x, y, or z) to match.
[!xyz] Specify a set of characters (x, y, or z) to preclude a match.
\ Ignore the subsequent special character and interpret as its actual
character.
[first-last] Specify a range of characters (from first to last) to match. For example,
a[a-c] matches aa, ab, or ac, but does not match ad or abc.

Search for attributes on elements

You can search for an attribute or group of attributes. You may want to locate a particular attribute, for example,
to configure a formula data reference or to assign it as a value to another attribute. (To search for a specific
attribute value, choose an attribute value as search criteria for an element search.)
1. In the navigator pane, click Elements.
2. Choose from the following actions:
▪ From the PI System Explorer menu, select Search > Attribute Search.
▪ In the browser, right-click the Element Searches collection and select New Attribute Search.
3. Set the Attribute Search window to find the desired attributes in the PI AF database:
a. Under Where, set the fields to restrict attributes retrieved:
• Attribute name
Enter the name of the attribute to retrieve. You can enter special characters to match part of a name.
See Special characters in name searches.
• Attribute description
Enter a string (of up to 440 characters) that retrieved attributes must match.
• Attribute category
Select the category that retrieved attributes must match.
• Attribute value type
Select the type of value that the retrieved attributes must store.
• Maximum results
Enter the maximum number of matching attributes to retrieve.
b. In the Element Criteria area, set the fields to restrict the elements searched for matching attributes:
• Search Root
 Enter the element that you want to use as the root or base level for the attribute search. Type the
exact name or click Browse to open the Element Browser window, where you can view the element
hierarchy and select an element. You cannot include wildcard characters in the entered name. If you
do not specify an element, you set the main level of the element hierarchy as the root. Depending
on your PI AF hierarchy, specifying an element in the Search Root field can improve search
performance.
Select the Search Sub-Elements check box to search the entered root and any sub-elements. Clear
this check box to search only the entered root.
• Name
Enter the name of the elements in which you want to search for attributes. You can enter special
characters to match part of a name. See Special characters in name searches.
• Description
Enter a string (of up to 440 characters) to retrieve only those elements that match.
• Category
Select the category of the elements in which you want to search for attributes.
• Template
Select the template of the elements in which you want to search for attributes.
• Type
Select the type of the elements in which you want to search for attributes.
If you specify values for multiple settings, the search returns only those attributes that match all the
specified settings.
4. Click Search to retrieve the matching attributes into the Search results table.
Alternatively, use the element tree under Search results to browse for attributes under particular elements,
and then select the attributes to add them to the Search results table.
Remember that the attributes available by searching and the attributes available by browsing the element
hierarchy depend on the configuration properties of the attributes.
5. Select items in the search results list and click OK.
The results are displayed in the viewer and in the browser tree. For more information on working with
search results, see Manage search results.

Search for event frames

Use the Event Frame Search window to retrieve event frame data that matches your search criteria.
1. In the navigator pane, click Event Frames.
2. Choose from the following actions:
▪ From the PI System Explorer menu, select Search > Event Frame Search.
▪ In the browser, right-click the Event Frame Searches collection and select New Search.
3. Set the Event Frame Search window to find the desired event frame or event frames in the PI AF database.
 Note: If you specify values for multiple criteria, the search returns only those event frames that match all the
specified criteria.
4. From the Actions list, select the type of filter to apply: Contains, Exact Match, Starts With, or Ends With.
5. Choose from the following actions:
To ...

Type one or more filter conditions directly into the Enter Event Frame Criteria field

Filter event frames under Criteria

• Search
Select the method you want to use to specify when the desired event frames occurred. The window
shows the appropriate fields for the selected method.
For example, select Active Between to specify a start time and end time, and find event frames active
any time during that period. Select Starting After to specify only a start time, and find event frames
that start after that time.
• In Progress
If available, select this check box to further restrict matching event frames to those that have not yet
finished.
• Search start
A PI time expression that specifies the start of the time period used to search for event frames.
• Search end
A PI time expression that specifies the end of the time period used to search for event frames.
Optional. From the list next to this field, select a defined time to automatically fill in the Search start and
Search end fields.
• All Descendants
Select this check box to search all levels of the event frame hierarchy below the specified root for
matching event frames.
• Name
Enter the name of the event frame to retrieve, based on the filter type. You can enter special characters
to match part of a name. See Special characters in name searches.
• Element Name
Enter a PI AF element that must be the parent of any retrieved event frames. You can enter special
characters to match part of a name. See Special characters in name searches.
• Category
Select the category that retrieved event frames must match.
• Results per Page
Enter the maximum number of event frames to show on a single page of the search results.
• Template
Select the template that retrieved event frames must be based on. After you select a template, you can
add criteria to find elements by attribute value.
• Analysis Name
Enter the name of the analysis that retrieved event frames were generated from. You can use wildcards
as needed.
• Attribute Value
You can specify up to three conditions for an attribute value. For each condition, specify an attribute
name, operator, and attribute value, such as Temperature >= 98.
In•versions prior to PI AF 2018, only available when you specify a template. For more details, see
Configure search conditions for attribute values when a template is specified.
In•PI AF 2018 and later versions, you can specify attribute values without needing to specify a
template. For more details, see Configure search conditions for attribute values when no
template is specified.
• Duration
Select an operator and enter a value, which can include a PI time abbreviation. For example, select >=
and enter 1d to retrieve events that last at least one day. You can select Duration a second time and
filter the search for results between two values. For example, select <= and enter 2d to retrieve
events that lasted between one and two days.
• Event Frame Search Root
Enter the event frame that you want to use as the root or base level for the event frame search. Type
the exact name or click Browse to open the Event Frame Browser window, where you can view the
event frame hierarchy and select an event frame. You cannot include wildcard characters in the
entered name. If you do not specify an event frame, you set the main level of the event frame
hierarchy as the root. Depending on the complexity of your PI AF hierarchy, specifying an event
frame in the Event Frame Search Root field can improve search performance.
• Can Be Acknowledged
(PI AF 2016 or later versions.) Set to True to retrieve event frames that can be acknowledged. The ability
to acknowledge event frames is determined in the template on which the event frame is based.
• Is Acknowledged
(PI AF 2016 or later versions.) Set to True to retrieve event frames that have been acknowledged. Set to
False to retrieve only event frames that have not been acknowledged.
 • Is Annotated
(PI AF 2016 or later versions.) Set to True to retrieve only event frames that have annotations. Set to
False to retrieve only event frames that do not have annotations.
• Severity
(PI AF 2016 or later versions.) Select an operator and select a severity setting from the list. For example,
select >= Minor to retrieve event frames that have at least a Minor severity setting. You can select
Severity a second time and filter the search for results between two severity settings. For example,
select <= Critical to retrieve event frames that have Minor, Major and Critical severity settings.
• Creation Date
(PI AF 2017 or later versions.) Select an operator and enter a date or a PI time abbreviation ( >= *-30d is
the default) to retrieve event frames that were created in the specified period. You can also click
to select a date in the Date and Time Picker window. You can select Creation Date a second time and
filter the search for results between two values (< *+1d is the default).
• Modify Date
(PI AF 2017 or later versions.) Select an operator and enter a date or a PI time abbreviation ( >= *-30d is
the default) to retrieve event frames that were modified in the specified period. You can also click
to select a date in the Date and Time Picker window. You can select Modify Date a second time and
filter the search for results between two values (< *+1d is the default).
Note: An event frame's modify date is updated whenever a capture value, an annotation, or a child
event frame is added, as well as when a change to its configuration is checked into the database.
Most template changes, or any modification to an attribute value that is not a configuration item,
will not affect an event frame's modify date.
6. Optional. Specify how you want results to be displayed in the Results table.
To ...

Group by template
Group by category
Change column selections

Display attributes as columns

Display full paths of event frames

 To ...

Conceal full paths of event frames

7. Click Search to retrieve the matching event frames into the Results table.
8. Click OK.
The results are displayed in the viewer and in the browser tree. For more information on working with
search results, see Manage search results.

Search for attributes on event frames

Use the Event Frame Attribute Search window to retrieve event frame attribute data that matches your search
criteria.
1. In the navigator pane, click Event Frames.
2. Choose from the following actions:
▪ From the PI System Explorer menu, select Search > Event Frame Attribute Search.
▪ In the browser, right-click the Event Frame Searches collection and select New Attribute Search.
3. Set the Event Frame Attribute Search window to find the desired attributes in the PI AF database:
Under Where, set the fields to restrict attributes retrieved:
a. Attribute name
Enter the name of the attribute to retrieve. You can enter special characters to match part of a name.
See Special characters in name searches.
b. Attribute description
Enter a string (of up to 440 characters) that retrieved attributes must match.
c. Attribute category
Select the category that retrieved attributes must match.
d. Attribute value type
Select the type of value that the retrieved attributes must store.
e. Maximum results
Enter the maximum number of matching attributes to retrieve.
4. In the Event Frame Criteria area, set the fields to restrict the search to matching attributes:
• Search
Choose criteria to find transfers that overlap the time period specified by Search start and Search end.
• Search start / Search end
Choose or enter start and end times for the search time period.
• Search Root
 Enter the event frame to use as the root or base level for the attribute search. Type the exact name or
click Browse to open the Event Frame Browser window, where you can view the hierarchy and select
an event frame. You cannot include wildcard characters in the entered name. If you do not specify an
event frame, the root is set to the main level of the hierarchy. Depending on the complexity of your PI AF
hierarchy, specifying search root can improve search performance.
Select the Search Sub-Event Frames check box to search the entered root and its children. Clear this
check box to search only the entered root.
• Name
Enter the name of the event frames you want to search for attributes. You can enter special characters to
match part of a name. See Special characters in name searches.
• Description
Enter a description string of up to 440 characters to retrieve only those elements that match.
• Duration
Enter minimum and maximum duration values to limit the attribute search to event frames whose
duration is within these limits.
• Category
Select the category of the event frames you want to search for attributes.
• Template
Select the template of the event frames you want to search for attributes.
If you specify values for multiple settings, the search returns only those attributes that match all the
specified settings.
5. Click Search to retrieve the matching attributes into the Search results table.
You can limit the results further to list only those attributes that match the text entered into the Search
results field.
6. Select items in the search results list and click OK.
The results are displayed in the viewer and in the browser tree. For more information on working with
search results, see Manage search results.

Search for transfers

Use the Transfer Search Criteria window to retrieve transfer data that matches your search criteria.
1. In the navigator pane, click Event Frames.
2. Choose from the following actions:
▪ From the PI System Explorer menu, select Search > Transfer Search.
▪ In the browser, right-click the Transfer Searches collection and select New Search.
3. Set the Transfer Search Criteria window to find the desired transfers in the PI AF database:
• Search
Choose criteria to find transfers that overlap the time period specified by Search start and Search end.
 • Search start / Search end
Choose or enter start and end times for the search time period.
• Name
Enter the name of the transfers you want to search for. You can enter special characters to match part of
a name. See Special characters in name searches.
• Description
Enter a description string of up to 440 characters to retrieve only those transfers that match.
• Source

Enter or click to open the Element Browser window, where you can view the element hierarchy and
select the source element for transfers you want to include in the search. Click the Any button to reset to
the default <Any>.
• Destination

Enter or click to open the Element Browser window, where you can view the element hierarchy and
select the destination element for transfers you want to include in the search. Click the Any button to
reset to the default <Any>.
• Template
Select the template of the transfers you want to search for.
• Maximum results
Enter the maximum number of matching transfers to retrieve.
If you specify values for multiple settings, the search returns only those transfers that match all the
specified settings.
4. Click Search to retrieve the matching transfers into the Search results table.
You can limit the results further to list only those transfers that match the text entered into the Search
results field.
5. Click OK.
The results are displayed in the viewer and in the browser tree. For more information on working with
search results, see Manage search results.

Search for attributes on transfers

Use the Transfer Attribute Search window to retrieve transfer attribute data that matches your search criteria.
1. In the navigator pane, click Event Frames.
2. Choose from the following actions:
▪ From the PI System Explorer menu, select Search > Transfer Attribute Search.
▪ In the browser, right-click the Transfer Searches collection and select New Attribute Search.
3. Set the Transfer Attribute Search window to find the desired attributes in the PI AF database:
a. Under Where, set the fields to restrict attributes retrieved:
 Attribute name
Enter the name of the attribute to retrieve. You can enter special characters to match part of a name. See
Special characters in name searches.
Attribute description
Enter a string (of up to 440 characters) that retrieved attributes must match.
Attribute category
Select the category that retrieved attributes must match.
Attribute value type
Select the type of value that the retrieved attributes must store.
Maximum results
Enter the maximum number of matching attributes to retrieve.
b. In the Transfer Criteria area, set the fields to restrict the attribute search to transfers matching the
specified criteria:
Search
Choose criteria to find transfers that overlap the time period specified by Search start and Search end.
Search start / Search end
Choose or enter start and end times for the search time period.
Name
Enter the name of the transfers you want to search for attributes. You can enter special characters to match
part of a name. See Special characters in name searches.
Description
Enter a description string of up to 440 characters to retrieve only those attributes that match.
Source
Enter or browse to and select the source element for transfers whose attributes you want to include in the
search.
Destination
Enter or browse to and select the destination element for transfers whose attributes you want to include in
the search.
Template
Select the template of the transfers you want to search for attributes.
Category
Select the category of the transfers you want to search for attributes.
If you specify values for multiple settings, the search returns only those attributes that match all the
specified settings.
4. Click Search to retrieve the matching attributes into the Search results table.
 You can limit the results further to list only those attributes that match the text entered into the Search
results field.
5. Click OK.
The results are displayed in the viewer and in the browser tree. For more information on working with
search results, see Manage search results.

Trends in PI System Explorer

While browsing elements in PI System Explorer, you can quickly create simple trends to verify the formulas,
calculations, and other measurements you are building within PI AF. For example, while you are designing a PI AF
formula, you might want to see what the results look like over the last several hours. Or, if you are creating PI
point attributes that involve summaries, it could be useful to see what those look like over recent hours.
You can add the PI AF attributes or PI points of interest to a trend; one way of adding them is to drag and drop
them onto the trend. You can then explore the data by adjusting the duration and the start and stop times of the
trend.
After you have created the trend, it remains available in the Trend window even when you are using other
features within PI System Explorer. You can add or remove traces to the trend at any point. You can also right-
click the trend cursor and select commands from a context menu.
You can also see a trend of an attribute when you view its time series data (by right-clicking an attribute and
clicking Time Series Data). The trend is automatically shown at the bottom of the Time Series Data window.

Create trends
OSIsoft recommends you use visualization tools, such as AVEVA PI Vision, PI ProcessBook, and PI WebParts, to
create and save trends that you plan to use more than once.
To verify formulas, calculations, and other measurements in PI AF, create a trend.
1. From the PI System Explorer menu, select View > Show Trend.
2. In the Trend window, choose from the following actions.
To ... Do this ...

Add an attribute to the trend a. Click Add Attributes.

b. In the Attribute Search window, specify
search parameters in the Attribute
Name, Attribute Category, and other
fields to find the attribute of interest.
c. Expand the element hierarchy in the Search
results area and select the attribute.
d. Click OK.
The Trend window displays a trend showing
how that attribute has varied over the
past hour (1 hour is the default duration).
Adjust the duration Specify times in the Start Time and End Time fields.
 To ... Do this ...

Add a PI point to the trend a. Click Add PI Points.

b. In the Tag Search window, search for the PI
point you want to see and select it in the
results.
c. Click OK.
The PI point is added to the trend.
Adjust which traces are visible on the trend Click Traces and clear the check box of attributes or
points you do not want to see.
3. Add any further PI AF attributes and PI points for which you want to view data.
The traces in the Trend window persist until you close the window.
You can drag attributes and PI points from other search results and drop them on the trend to add them.
Alternatively, you can right-click an attribute or point and click Add to Trend.

Version management for equipment and processes

When you need to make an equipment change, such as swapping out a broken pump for a similar pump, you can
continue to use the existing element to represent the new pump. However, to indicate that a change has
occurred, it is a good idea to create a new version of the element. That way you have a record of the change to
the equipment that the element represents.
Similarly, you might need to create versions of a table. For example, strapping tables of tanks are updated
periodically to match the changing physical characteristics of the tank. By versioning the table, you will be able to
use the table as it was configured at the time of the data collection.
PI System Explorer allows you to create multiple versions of elements, models, and tables.
You can also indicate an element, model, or table is not in service past a specific date by selecting that date as its
obsolete date.
Videos
For an overview of version management, watch this video:
For information on how to create versions of elements and tables, watch this video:

Create versions for elements or models

Whenever a new version is created, a check-in occurs on the element or model.
Create a new version when you need to keep track of changes to an asset.
1. In the navigator, click Elements.
2. in the Elements browser, choose from the following actions.
▪ Right-click the element or model you want to version and click Create Version.
 ▪ Click the element or model you want to version. In the viewer, select the Version tab and click New
Version.

3. In the Create Version window, enter an Effective Date for the version or click to select a date.
PI System Explorer creates a new version.
4. Optional. In the Comment field, enter information on the new version.
5. Click OK.
To indicate that more than one version exists, the icon in the browser changes to for an element or for
a model.

Create table versions

Whenever a new version is created, a check-in occurs on the table.
Create a new version when you need to keep track of changes to a table.
1. In the navigator, click Library.
2. In the Library browser, choose from the following actions.
▪ Right-click the table you want to version and click Create Version.
▪ Click the table you want to version. In the viewer, select the Version tab and click New Version.

3. In the Create Version window, enter an Effective Date for the version or click to select a date.
PI System Explorer creates a new version.
4. Optional. In the Comment field, enter information on the new version.
5. Click OK.
To indicate that more than one version of the table exists, the icon in the browser changes to .

Compare two versions

You can compare two versions of an element, model, or table that has more than one version.
1. Choose from the following actions.
To... Do this...

Compare table versions a. In the navigator, click Library.

b. In the Library browser, select a table that
displays the icon.
Compare element or model versions a. In the navigator, click Elements.
b. In the Elements browser, select an element
that displays the icon, or a model that
displays the icon.
2. In the viewer, select the Version tab and click Show History.
 3. In the Show History window, select two versions in the left panel from the list of all existing versions.
The right panel uses colored change bars to indicate the differences between the versions:
• Red means that the item was present in the older version and is not present in the newer version.
• Green means the item is present in the newer version but was not present in the older version.
• Yellow means that the item changed between the older and newer version.
4. To exit, click Close.

Display of different object versions and obsolete objects

By default, PI System Explorer shows the latest versions of elements, models, and tables (even if those versions
are in the future). It also excludes earlier versions and all objects that have an Obsolete date specified (even if
that date is in the future). As a result, when you specify an Obsolete date for an object and check it in, it
immediately disappears from PI System Explorer.
You can, however, find and view an obsolete object, or a particular version of an object, by setting Query Date to
a fixed time at which the object or version is current. To display an element that became effective January 1,
2010 and obsolete on January 1, 2011, for example, set Query Date to any time between those two dates.
Video
For information on how to display different versions, watch this video:

Query Date and PI System Explorer time

Query Date determines the time values PI System Explorer uses to:
• Find and display attribute values.
• Identify current versions of objects to display and include in search results.
At the default Query Date setting, Set to Latest, PI System Explorer finds and displays the most current data for
attribute values. You can override the Query Date to view values for a different time with Set Time Context. See
Set time context for displayed attribute values.
Set to Latest also causes PI System Explorer to use the latest versions of objects, even if those versions are in the
future, and excludes any object with an Obsolete date, even if that date is in the future.
You can change Query Date to specify a fixed date and time:
• The date and time picker lets you choose a specific date and time setting.
• The selections Set to Now and Set to Today each use the current time to establish a fixed date and time. For
example, if you choose Set to Now on Monday, then on Wednesday Query Date will still be set to Monday.
How Query Date affects PI System Explorer
 What is affected Query Date is Set to Latest Query Date is a fixed date and time

All PI System Explorer objects PI System Explorer uses the latest PI System Explorer uses versions of
versions, even if those versions are objects that are in effect at that
in the future; it excludes any object time.
with an obsolete date, even if that
date is in the future.
Element, model, and table versions PI System Explorer returns the PI System Explorer returns the
in search latest versions, even if those versions that are in effect at that
versions are in the future. time.
Relative times in searches PI System Explorer defines the PI System Explorer defines the
current time (*) as the time of the current time (*) as the time
search. specified by the Query Date.
PI data PI data is returned at its latest PI data returned is the value for the
snapshot value. timestamp specified by the Query
Date.

Show specific dates and times

When you set the query date to a specific date and time, it remains constant at that date and time until you
change it again.
1. On the PI System Explorer tool bar, click the Query Date button.
2. In the Date and Time Picker window, choose the date and time that you want. If you want to set the query
date to the current date and time, click the Set to Now button.
Note: When you choose Set to Now as the query date, you are setting the query date to a specific date and
time; this is a constant value. This is not the same as setting the query date to always be the current time.
For that, you should choose the Set to Latest option.
3. Click OK.
Video
For information on how to set a specific query date, watch this video:

Time context for attribute values

The time or time range that PI System Explorer uses to display attribute values is determined by values you set in
the Set Time Context window.
By default, PI System Explorer displays the latest values for attributes based on the current time. The Query Date
reflects PI System Explorer's time setting (see Query Date and PI System Explorer time). You can view attribute
values for a different time, however, by specifying a new time in the Set Time Context window.
The time and time range settings in the Set Time Context window apply only to displayed attribute values. Query
Date continues to apply to all other PI System Explorer objects.
 Set time context for displayed attribute values
You use Set Time Context to specify a different time or time range for displayed attribute values.
1. On the PI System Explorer toolbar, click .
Alternatively, click Tools > Options and select the Time Context tab.
2. In the Set Time Context window, select one of the following options.
Enter time values for an option directly, or click to select a date and time. You can also click to
construct a time expression, such as *-1d.
Option Description

Query Date Time Displays the current setting for Query Date (defaults
to Latest Available). You can specify a different
date time setting for Query Date, to enable PI System
Explorer to evaluate which versions of objects to
retrieve from the PI AF database.
Alternative Time Displays the time context for data retrieval after
applying the current Query Date setting. The default
is the current time (*), but you can enter a new time
context to use for displayed attribute values.
Time Range Enter Start and End times to specify a new time range
to use for displayed attributed values that require a
time range.
3. Optional. Click Set as Default to register the current settings as the default time context, or click Restore
Default to restore the time context for Query Date Time to Latest Available.
4. Click Apply to see your changes and OK to keep them. The revised time context settings are displayed in the
PI System Explorer title bar.

View time series data

PI System Explorer can display time series data for attributes that contain or reference such data. This allows you
to preview how your data reference configurations will work with your collected data in other PI client tools,
such as PI ProcessBook, AVEVA PI Vision, PI DataLink and PI WebParts.
Note: Some attribute configurations do not support this type of data. See Restrictions on viewing time series
data.
1. Right-click on the attribute in the viewer and click Time Series Data.
2. In the Time Series Data window, choose the tab representing the type of data you want to see:
• Archive
For PI points. Shows the archived values within the specified time. Settings include Boundary type and
Filter expression.
• Sampled
 Returns evenly-spaced, interpolated values over a regular interval. You can include a Filter expression.
• Plot
Retrieves values over the specified time range suitable for plotting over the specified number of
intervals. Typically, the intervals represent pixels and you would use this feature to represent the screen
width available for the plot.
• Summary
Displays summary Statistics for attribute values that support this feature. You can specify Weighting.
• Data Pipe
Enables you to monitor and display data changes within attributes. For attributes that support future
data, you can specify how the data pipe returns data with the Event horizon mode and Offset properties.
For historical tags, Event Horizon Mode has no effect.

Boundary type
Specify a boundary type to determine how the searches for data values are handled near the start and end times
of the value range:
• Inside (default)
Returns values at start and end times, if they exist, or the nearest values occurring within the range.
• Outside
Returns the closest values occurring immediately outside the range.
• Interpolated
Returns interpolated values at start and end times.

Filter expression
Add a filter expression to filter event values using a mathematical expression, eliminating data for which the
expression evaluates as false. For example, the simple filter expression:
‘.’ < 70
Note: Be sure to place filter expressions within two straight apostrophe symbols (Unicode character
'APOSTROPHE' (U+0027)).
would remove all values over 70 from the calculation. You can also use any valid PI performance equation in the
filter expression to build more complex expressions to remove atypical peaks in data values, for example.
Expression variables are limited to attributes or PI points which originate from a single Data Archive. Attributes
which resolve to a static value (no data reference configured), are also acceptable. See Indirect PI point
references for a complete description of possible reference syntax.
Attribute variable examples

Filter expression What it does

‘.’ Reference to the attribute being queried.

 Filter expression What it does

‘Level’ Reference to the attribute Level at the same

attribute hierarchy level in the element or event
frame.
‘..’ Reference to the parent attribute of the attribute
being queried. Only valid for nested child attributes.

‘.|HighLimit’ Reference to the child attribute HighLimit of the

attribute being queried.

‘|Temperature’ Reference to the Temperature attribute at the top

hierarchy level in the current element or event frame.

‘\\MyPIServer\sinusoid’ Absolute path to a PI point. It must be in the same

Data Archive as the current queried attribute.

‘\\myAFServer\myDatabase\myElement| Absolute path to a PI AF attribute.

myAttribute’

‘\myRootElement|myAttribute’ Database relative path to a PI AF attribute.

PI point variable examples

Filter expression What it does

‘.’ Reference to the PI point being queried.

‘sinusoid’ Reference to the PI point sinusoid in the same Data
Archive.
sinusoid

Statistics
The Summary tab provides the following statistics for attributes that support such statistics:
• Percent Good
Displays the percentage of time for which good values are returned over the total time range. Good values
are event values determined to be valid and not in an error state.
• Average
Computes the average of values during the interval.
• Minimum
Returns the minimum value during the interval.
• Maximum
 Returns the maximum value during the interval.
• Range
Computes the maximum value minus the minimum value during the interval.
• Standard deviation
Computes the standard deviation of values during the interval.
• Population standard deviation
Computes the population standard deviation of values during the interval.
• Count
Returns the number of values stored during the interval.

Weighting
The Summary tab allows you to select the Weighting for the statistical calculations:
• Time-weighted
Default. Weights each event value by the length of time over which it applies.
• Time-weighted continuous
Time-weights values, but does all interpolation between values as if the values represent continuous data,
(standard interpolation) regardless of whether the attribute is stepped.
• Time-weighted discrete
Time-weights values, but does all interpolation between values as if the values represent discrete, unrelated
values (stair step plot) regardless of the attribute is stepped.
• Event-weighted
Weights each event equally. This method requires at least one event in a time range (two events for standard
deviation calculations). By default, events at the boundary of the calculation are handled as follows:
• use events at both boundaries when there is only one calculation interval
• include events at start time in multiple intervals and the intervals are in ascending time order
• include events at the end time in multiple intervals and the intervals are in descending time order
• Event-weighted - Exclude Earliest Event
EventWeighted, except that the event at the start time (earliest time) of an interval is not used in that
interval.
• Event-weighted - Exclude Most Recent Event:
EventWeighted, except that the event at the end time (most recent time) of an interval is not used in that
interval.
• Event-weighted - Include Both Ends:
Events at both ends of the interval boundaries are included in the event-weighted calculation.
Event horizon mode
Event horizon mode controls when events for attributes that support future data are returned in the PI AF data
pipe. Possible values are described in the following table.
Value Description

End of Stream Events are returned as they are created, without

regard to the current time.
Time Offset Events are only returned after they cross the relative
time offset into the future from now.
For example, with a time offset of zero, future tag
data changes are not returned until their timestamp
is less than or equal to the current time.
Time Offset with Outside Event Events are only returned if they occur before the
relative time offset into the future, or they are the
next event that would cross this time horizon.
For example, with a time offset of one hour, future
tag data changes are not returned until their time
stamp is less than or equal to the current time plus
one hour, or they are the next known event after the
one hour time horizon. This mode is useful for
trending data into the future.

Restrictions on viewing time series data

PI point data reference configuration types
Although many configurations are possible with PI point data references, support differs for each data function.
PI point data references can be grouped into the following types for time method configurations:
• Simply configured PI point
All data functions are supported and there is no additional configuration. Time method is Automatic,
Interpolated, or AtOrBefore.
• Archive retrieval of specified PI point
Only functions in the interpolated values group (listed in the following table) are supported. Time method is
Before, Exact, AtOrAfter, or After.
• Relative time PI point
Simply configured PI point with relative time configured. Time method is Automatic, Interpolated, or
AtOrBefore.
• Time range only
Time method is not supported.
• Time range with relative time
Time method is TimeRange or TimeRangeOverride.
The following table details which data functions are supported by the PI point data reference configurations
listed above. These restrictions also apply to other client tools, such as PI DataLink, PI Vision, PI ProcessBook and
PI WebParts.

Data function Simply Archive Relative time Time range Time range
configured retrieval only with relative
time

InterpolatedValue

InterpolatedValues

InterpolatedValuesAtTimes

RecordedValue

RecordedValues

RecordedValuesAtTimes

RecordedValuesByCount

Async

PlotValues

Summary

Summaries

FilteredSummaries

UpdateValue

UpdateValues

Annotations

Filters

AFDataPipe

Non-PI point data reference configuration types

Non-PI point data references can be grouped into the following types for time method configurations:
• No data reference
Data reference is set to None.
• Calculation-based data reference with time-series inputs
Calculation-based data references with time-series inputs, such as Analysis, Formula, String Builder, Table
Lookup, and URI Builder support the base data functions. However, filtering and annotations functions are
not supported. Calculation-based data references use recorded values of their inputs to generate
 timestamps for their own recorded values. If calculation-based data references contain no time-series inputs,
they behave like the No-data-reference configuration type, except that they cannot be written to.
Note: Table Lookup data references that are configured with a time column, as described in Table provided
time series data, support the same data functions as the configuration type: Custom data reference
generating its own time-series data.
• Custom calculation-based data reference
Custom calculation-based data references are required to "opt-in" to gain access to base data functions.
• Custom data reference generating its own time-series data
Custom data references that generate their own time-series data require code to be implemented for each
data function call.
The following table details which data functions are supported by the non-PI point data reference
configurations listed above. These restrictions also apply to other client tools, such as PI DataLink, PI Vision,
PI ProcessBook and PI WebParts.
Data function No data Calculation- Custom Custom data
referenc based data calculation- reference with
e reference with based data its own time-
time-series reference series data
inputs

InterpolatedValue OptIn1 Code2

InterpolatedValues OptIn1 Code2
InterpolatedValuesAtTimes OptIn1 Code2
RecordedValue OptIn1 Code2
RecordedValues OptIn1 Code2
RecordedValuesAtTimes OptIn1 Code2
RecordedValuesByCount OptIn1 Code2
Async OptIn1 Code2
PlotValues OptIn1 Code2
Summary OptIn1 Code2
Summaries OptIn1 Code2
FilteredSummaries Code2
UpdateValue Code2
UpdateValues Code2
Annotations Code2
 Data function No data Calculation- Custom Custom data
referenc based data calculation- reference with
e reference with based data its own time-
time-series reference series data
inputs

Filters Code2
AFDataPipe OptIn1 Code2
1
Indicates that a custom data reference can be written with one method to declare which attributes it uses as inputs, and another
method that transforms inputs to outputs. With input support, the AF SDK uses these methods to emulate the others, using a time
series generated from input data.
2
Indicates that code is needed for each method, if the time series comes from the system of record that is being connected to.
Chapter 5

Organization of asset models in PI AF

The goal of your asset model organization is to make assets easy to find for your users. The main method of
organization is the element tree. PI AF elements are organized in a tree structure. Individual elements can be
organized and regrouped within the tree, without limitations. If you are just getting started with PI AF, then start
by creating the element hierarchy.
You can additionally organize through categories to speed up and simplify browsing and searching information.
Think of categories as labels that you can apply to PI AF objects. Each object can have multiple categories.
Note: You can also organize assets within a process. See Process models in PI AF.

The structure of PI AF asset models

PI AF objects are organized in a tree structure, similar to the file structure on a Windows computer. In Windows,
rather than having thousands of files on your desktop, you typically group files under folders. The same concept
applies to PI AF elements. Organizing elements into hierarchies makes navigation of the elements easier, and it
also provides insights into how the elements relate to one another.
When you create an asset model, you need to decide on a structure that makes it easy for users to find the
different assets. Consider who your users are and what they will be looking for. For example, maintenance
engineers might want to use PI System Explorer to find and record maintenance information. For this audience
you might want to group assets by equipment type.
For example, if you had three pump elements, you might create an element called Pumps and then place all the
pump elements beneath it. If you had two elements representing tanks, you might put them all under a Tanks
element.
Asset model organized by equipment type

On the other hand, if you have multiple plants in different locations, that same maintenance engineer might
want to see all the equipment located at his own plant. The following illustration shows the same elements
organized by plant.
Asset model organized by location
 You are not restricted to only one organizational strategy. You can use an element reference to include the same
asset in more than one place in the tree. For example, you could choose to organize by equipment type and by
plant as well. In the following illustration, the hierarchy includes the geographical tree and the equipment tree
side by side.
Mixed asset model

You could alternatively nest the equipment organization under the geographical organization.
Note: Limit the depth of your asset hierarchies to 10 levels or less to maintain the performance and
interpretability of your asset data.

The design of PI AF asset hierarchies

The goal is to create an asset (element) hierarchy that is going to make sense to the people who need to use it. If
you have different types of users, then you might need more than one tree structure.
If you are just getting started, do not try to do everything at once. Create a hierarchy for a subset of your assets.
For example, you might start by modeling all your tanks, or alternatively, your equipment in a single plant, or
your equipment from a particular manufacturer. Another approach would be to create a hierarchy for a
particular type of user.
Gather information:
• What assets will be included in the tree? In other words, what types of equipment do you want to model?
• Who is going to need to find assets in this tree? Maintenance engineers? Process control engineers?
Operators? For each type of user, what tasks will they need to perform?
• What assets are important to each user and what types of information will they need? Consider asking a few
representative users of each type about what data they need to access and how. This should inform your
organizational strategy.
Again, start small. You might start with one type of user. For example, suppose maintenance engineers need to
use the model. If you have several plants, each with a group of maintenance engineers responsible for the
equipment at that plant, then you should probably include a tree that organizes equipment by plant.
From there, you might ask some maintenance engineers how they would want to access the equipment
information. Perhaps they usually look for assets by equipment type but sometimes they need to search by
manufacturer. You could create parallel trees, one organized by equipment type and another by manufacturer.
 Each asset would then appear in each tree. Or you could organize the tree by equipment type and then use
categories to label each asset by manufacturer.
After you create the hierarchy for a type of user, you might have a few of them try it out for a period of time,
then take their feedback to improve the hierarchy. You can always change a hierarchy.
Note: When thinking about users, remember that the element hierarchy might also be exposed in certain PI
client applications. Consider the users of those applications as well. For example, AVEVA PI Vision exposes the
tree for users searching for related assets. In AVEVA PI Vision, related assets are elements built from the same
template.
Videos
For information on how to create elements, watch this video:
For information on how to build element hierarchies, watch this video:

Element references in the asset hierarchy

You can use element references to add the same element to your element hierarchy more than once, as
described in The structure of PI AF asset models, The structure of PI AF asset models. When you create a
reference to an existing element, you essentially create a placeholder in the hierarchy that points back to the
referenced element. This allows users to find the element in all the relevant contexts, but it does not create a
copy of the element. The exact behavior depends on the reference type.

Reference types
When you add an element reference to an element hierarchy the exact relationship between the referenced
element and the element to which you add it depends on the type of reference. PI AF provides three system-
defined reference types:
• Parent-Child
• Composition
• Weak Reference
You can also create your own custom reference types, as described in Creation of custom reference types and
Child templates.
Videos
For a 5-minute tutorial on how to use reference types, watch this video:
For more information on how to use reference types, watch these longer videos:
For information on how to build custom reference types, watch this video:
For the conclusion of the reference type example, watch this video:

Parent-Child reference type

The default reference type is parent-child. The reference type is strong since it allows the child element to have
many parents and exist as long as it has one or more strongly related parents. When the last parent element of
the child is deleted, the child itself is deleted. Use the parent-child reference type when you want the child
element to exist as long as it has a strong reference to at least one parent, but you do not want the child element
to be treated as a single unit with the parent element.
Effect of a deleted parent-child reference when that parent-child reference type exists elsewhere

Example
A meter belongs to a company and is attached to a building. You would use a parent-child reference between the
Company element and the child Meter element, and another parent-child reference between the Building
element and the child Meter element. If the reference between the Meter and the Building element is deleted,
the Meter element continues to exist because it has a parent-child reference to the Company element. However,
if the child Meter element is also deleted from the Company element, it no longer exists because all parent-child
references have been removed.

Composition reference type

A reference type with a reference strength of composition means that the child element is really a part of the
parent and does not exist without the parent. If you delete a parent element that has a child element that is
compositionally referenced, you delete the child element also.
Effect of a deleted parent element on elements with a composition reference type

Example
Use a composition reference when the two objects in the relationship are considered one item. For example, a
meter might be composed of two sensors, and so you would use a composition reference between the Meter
element and each of its two child Sensor elements. When you delete the Meter element, the child Sensor
elements are also automatically deleted.

Weak reference type

Use a weak reference between two elements when you want to create a relationship between two elements but
you do not want that relationship to control the lifetime of the child element. For example, you may want to
organize your meters into groups, but if all strong references to the meter are removed, then you want it to
automatically be removed from the grouping. In this case, you would use a weak reference between the group
parent element and the child meter element.
Effect of a deleted strong element on an element with a weak reference type
 Example
A child element with a weak reference is deleted as soon as no more strong references exist. You may find this
useful if you want one view of your assets to be the master view. For example, in the above illustration the
master view might be the Site ABC view and contain elements with strong parent-child reference types. Other
views, such as Pumps, reference elements with a weak reference type. If the strong Pump01 element in the
master Site ABC view is deleted, the weak-referenced Pump01 element in the Pumps view is deleted
automatically.

Create single element references

You create a single element reference to establish a hierarchical relationship between two elements.
1. In the Elements browser, click the element that you want to reference and drag it to the appropriate parent
element.
2. In the Choose Reference Type window, select the reference type.
If you are not sure what reference type you want, you probably want the default reference type, parent-
child. See Reference types for more information.
3. Click OK.
The referenced elements are displayed in the browser. The referenced element icon indicates that they
are references.
Video
For additional information on how to create an element reference type, watch this video:

Create multiple element references

You create multiple element references to establish a relationship between an element and other elements in
the hierarchy.
1. In the Elements browser, right-click an element and click New > Add Element Reference.
Note that you can also select an element and drag it to the parent.
2. In the Add Element(s) window, click the Find Multiple Elements button.
3. In the Element Search window, select search criteria to locate the desired elements and click the Search
button.
The search results field shows the results of your search.
4. Select the elements that you want to reference and click OK.
5. In the Add Elements window, select the reference type. If you are not sure what reference type you want,
you probably want the default reference type, parent-child. See Reference types for more information.
6. Click OK.
 The referenced elements are displayed in the browser. The referenced element icon indicates that they
are references.

Locate other references to the same element

A single element can be referenced in multiple places in a hierarchy. You can find all the elements in the
hierarchy that contain the element or a reference to the element.
1. Select the element in the Elements browser.
2. In the General tab, click the Parents link.
The element's parents are displayed in the Parents of Element window.
3. Click Close.

Change reference types

You can change the reference type of a child element and event frame that has at least one parent in the
hierarchy and is not at the root level of the hierarchy (where the reference type must be parent-child).
1. Choose from the following actions:
To ... Do this ...

Change a child element reference type a. In the navigator, select Elements.

b. In the browser, expand the Elements tree and
locate the child element with more than
one parent.
c. Right-click the child element and click
Convert > Change Reference Type.
Change a child event frame reference type a. In the navigator, select Event Frames.
b. In the browser, expand the Event Frames tree
and locate the child event frame with
more than one parent.
c. Right-click the child event frame and click
Convert > Change Reference Type.
2. In the Change Reference Type window, select a parent from the Parent list.
3. Select a new reference type from the New Reference Type list. Only valid reference types for the selected
parent are available.
4. To establish the selected parent as the primary parent (when the selected reference type is valid), select the
Primary Parent check box.
Note: To be valid, the selected reference type must be strong and no composition references can be defined
for the element or event frame.
5. Click OK.
 Creation of custom reference types
Custom reference types are easy to create. Each custom reference type must be based on one of the three pre-
defined reference types. Through the use of custom reference types, you can create rules that allow PI AF to
guide users when they create new elements. See Child templates for information on creating template
references.

Create custom reference types

Custom reference types are created in child templates. You can also create them to define your own hierarchy of
elements using a more specific relation. Custom reference types must be based on one of the pre-defined
reference types.
Note: You can create reference types more quickly in the Element Templates collection using referenced
templates, as described in Create child template references.
1. In the Library browser, right-click the Reference Types collection and select New Reference Type.
2. In the Name field, enter a name for the reference type.
3. In the Child Name and Parent Name fields, enter names for the child and parent.

4. Optional. In the Categories field, click and select one or more categories to which the reference type
belongs from the Categorize window. You can also enter one or more reference type categories directly,
separated by a semicolon.
5. In the Reference Strength field, select Strong, Weak, or Composition from the list. See Reference types for
definitions of reference type strengths.
6. In the Allowed Parent Element Template and Allowed Child Element Template fields, select a template to
which the reference type parent and child belong from the list.

Categorization of objects
PI System Explorer allows you to organize objects into categories. Categories are essentially object groups that
you define yourself. Their purpose is to help you find objects more easily. When you search for an object, you can
use the category as a filter to reduce the list of results. Define as many categories as you like. Objects can belong
to multiple categories.
For example, suppose you have a set of elements representing tanks. Half of the tanks are manufactured by
ACME company, and the other half are manufactured by EMCA company. To locate tanks by manufacturer, create
an ACME category and an EMCA category.
Each object type has its own categories. You cannot apply categories from one object type to an object of
another type. For example, you cannot apply an element category to a table. PI AF supports the following
category types:
• Analysis
• Attribute
• Element
• Notification Rule
• Reference Type
 • Table
Videos
For information on how to create categories, watch this video:
For information on how to assign categories, watch this video:
For information on how to group by category, watch this video:

Create new categories

Create categories for specific object types. Alternatively, use PI Builder to create multiple categories in an Excel
worksheet.
1. In the navigator, click Library.
2. In the Library browser, under Categories, right-click on the category object type and select New Category.
3. In the Object_Type Category Properties window, enter a name for the category in the Name field.
4. Optional. Enter a description of the category in the Description field.
5. Click OK.
6. Optional. Click the Security link if you wish to set up custom access permissions to the category beyond
those already established at the server, database, or collection level. For more information, see Configure
security for objects.

Assign objects to categories

Assign objects to the categories that you have created for each category type.
1. In the viewer, use standard Windows keystrokes to highlight contiguous (SHIFT+<click>) or non-contiguous
(CTRL+<click>) objects that you want to categorize.
2. Right-click and select Categorize.
3. In the Categorize window, select the category or categories to assign to the selected objects.
a. If the category you need is not listed, click the New Category button.
b. In the Attribute Categories Properties window, create the new category and click OK.
4. Click OK. The categories are applied and are displayed in the Categories field in the configuration panel for
each object.
a. If any selected objects are created from templates, you can modify the template or not add the category
to that particular object.

Choose one of the following options:

• Click Modify the template and add the category to modify all attributes derived from the template
with the category.
• Click Do not add the category to prevent the category from being assigned to the object.
b. To apply the option to other selected attributes that are derived from templates, select the Apply choice
to remaining templates check box.
c. Click OK.
Chapter 6

Representation of assets in PI AF

Each physical object that you include in your model is represented by a PI AF element. Physical objects are
typically pieces of equipment, such as pumps or tanks. To associate data with an element, you create attributes
on the element. Attributes can hold simple values representing fixed information, such as the diameter of a tank.
An attribute can alternatively reference a PI point, a formula, a value from an external relational database, and
more.
Templates
You can create each element individually, but it is recommended to base individual elements on an asset
template that represents the type of equipment. Element templates enable you to:
• Configure the template once; no need to individually configure each element based on the template.
• Update element structure across all elements belonging to the template.
• Maintain consistency in the asset model.
• Enable powerful features in PI AF client applications.

Asset representation with templates

PI AF allows you to base similar objects on a single template. Templates essentially define a set of base attributes
for all the objects that use that template. Create the template once and you can create as many elements based
on the template as needed. If you make a change to a template, the change is automatically reflected in all the
elements that use that template.
For example, suppose you have 100 pumps with the same three attributes. You can create a template for one
pump and then base all the other pumps on that one template. The attributes in the template are automatically
created for you in the pumps that are based on that template.

Now, suppose you need to make a change to the pump objects. You simply make the change in the template,
and PI AF automatically propagates the change to all the pump objects that are based on that template.
Templates are a powerful tool, not only for creating new objects, but for keeping existing objects consistent and
up to date.
 A further advantage is that visualization tools can provide special features for objects based on templates. For
example, suppose you build a trend for a pump based on a template. A visualization tool might let you swap or
add in any other pump that is based on the same template. Assets based on the same template are sometimes
called related assets.
Note: You can also create templates for event frames, transfers, models, and notifications.

Template strategy
In almost every case, it is best to base your elements on templates. You not only save time but also ensure that
you have consistent definition across all of the elements based on that template. Any changes that you make to
an element template are propagated to every element that is based on that template. A single template
modification can alter hundreds of elements. This allows you to make changes to your model in a single place;
you don't need to update every element.
You do not have to plan and create all your templates at once. A good approach is to start by modeling a single
type of asset. Create a template for the asset type. Decide what data, calculations, and other properties you
need to store for that type of asset. Each of these items requires an attribute template.
Base templates
Template usage can be very broad or very specific. A template can define a specific type of measurement device,
such as a brand-name instrument, or it can be a broad-use template specifying a particular role, such as a liquid
mass meter. Depending on how broadly you define the template, you might find that the list of attributes is
slightly different for different subsets of assets. In this situation, consider using a base template (for more
information, see Base and derived templates). The alternative is to use a different template for each asset
subset.
Extensions
You can also set up element templates to include attributes (as well as ports) that are not defined or maintained
by the template (for more information, see Extensions). You can add simple, asset-specific attributes without the
need to add them on all instances of the template.
Note: Categories, analyses and notifications are not affected by whether the Allow Extensions check box is
enabled.

Element templates
An element template is a model of an asset type that saves you time and promotes consistency. Element
templates make creating displays, notifications, calculations, and analytics much simpler because equipment of
the same type can share the same implementation. Typically, you create a base template that represents a type
of equipment, such as a tank or pump and assign common attributes to that asset. Then, you create one or more
derived templates based on the base template and assign additional attributes to each asset subset.
You can easily create elements based on a derived template because most of the element configuration is
defined in the template.
When you change an element template, those changes propagate to all elements derived from it.
Deleting an element template deletes any notification or analysis templates that target it.
Note that:
 • An element derived from a template gets its initial definition of categories from the template. An element's
attributes and ports are derived from its template.
• If the template allows extensions, then a derived element can contain ports and attributes that are not
defined in the template.
• Element templates can specify the allowed parent and child references (Parent Reference Types and Child
Reference Types) for an element created from the template. This restricts the allowed relationships between
elements in the hierarchy.
• An element cannot be derived directly from a Base Template Only template.
Video
For information on how to create element templates, watch this video:

Default attribute
The default attribute is an attribute that is most representative of the element. For example, if a user were to
reference a tank, perhaps Level would be the single best attribute to use. For an electrical meter, the best
attribute to use could be Voltage. The attribute must be at the top level of the attribute hierarchy of the element.
Notifications and asset analytics can take advantage of the default attribute to simplify some tasks. For example,
if you were to create a comparison between two electrical meters, and had not specified which attributes to
compare, the comparison would be performed using the Voltage attribute of the meters because you had made
Voltage the default attribute.

Base and derived templates

A base template is best used when you are modeling elements that share most attributes, but have a few
attributes that differ. A base template passes on all its attributes (as well as ports and analyses) to any derived
templates that are created from it. When you later create an element from such templates, that element
contains not only every attribute (as well as ports and analyses) from the base template, but also from the
derived template.
Base template only (BTO) templates
To ensure certain templates are not used directly to create objects, you can assign the Base Template Only (BTO)
property to a new template. Just like other base templates, a BTO template can be as broad or specific as needed
and then used to create a derived template. When an instance of an object is created, it is based on the derived
template, not the BTO template. Any modifications to a BTO template also alter its derived templates. The BTO
property can be assigned to element, model, transfer, and event frame templates.
Note: A checkmark next to the Base Template Only check box on the General page of the Template Properties
window indicates the template is a BTO template.
Base template example
Suppose you have a set of tanks, some with two valves and some with one valve: you can create an element
template for the one-valve models, and use that as the base template for the derived template that you create
for the two-valve models. When you create objects based on the two-valve model, they inherit all the attributes
from the one-valve model, as well as any additional attributes defined for the two-valve model.
 Derived templates
You define derived templates from a base template. You can designate a derived template after creating a base
template using the following method:
• Right-click a base template in the Library browser, then click New > New Derived Template.
• The new template is immediately added to the Library browser with the new name BaseTemplate_Derived1.
You can modify the definition, including the name, as described in Create element templates.
Override of base-template attribute values
Situations may exist where you need to use attribute template values in a derived template that suppress or
override attribute template values inherited from their base template. Consider the following situations:
• Different substitution patterns are needed for PI points on the same type of asset (such as trucks with a
common set of measurements, but truck manufacturer A uses a different PI point naming pattern than
manufacturer B).
• Some assets employ direct measurement for an attribute PI point, whereas others may need that attribute
value to be calculated. Similarly, an attribute value may be calculated for both types of assets, but the
calculation is slightly different between the two.
• Different default UOMs or categories are needed for the same attribute, based on a template.
• Not all attribute templates in a derived template are applicable (for example, some meters may only need
three of the five attributes in a generic base Meter template).
You override base template attribute values by creating an attribute template with exactly the same name in the
derived template. You can then modify properties as needed.
You can also prevent an attribute template that has been inherited from a base template from being visible to
users or a client application, such as AVEVA PI Vision, by creating an attribute template of the same name in the
derived template and selecting Excluded as its Properties setting. For more information, see Excluded attribute
property.
Template inheritance
By default, element templates are arranged by name in the Library browser. To determine the relationship that
exists between templates, you might prefer to arrange them by template inheritance instead. You can right-click
the Element Templates collection and click Arrange By > Arrange By Template Inheritance. Expand templates
with beside them to reveal derived templates.

Extensions
You can allow some attributes to be defined in the element itself, independent of the template. To do this you
configure the template to allow extensions. Attributes that are created as extensions do not change when the
template changes.
Note: If you have a template that allows extensions and you later change it to disallow extensions, no new
extended element attributes can be added to elements based on that template. However, all existing extended
element attributes remain.
Extensions permit flexibility in cases where assets are similar in many areas, but a number of small variations
exist. For example, suppose you build a template for a specific model of a car. All the cars of this model have the
same core set of features: four tires, a steering wheel, and so on. However, one car may have a spoiler while the
 other car may not. One might have air conditioning, while another does not. Extensions are intended to handle
this type of variation.
When extensions are enabled, you can base all the elements on a template, while adding additional information
to each element as required. However, if you have multiple elements that are very similar to the template
definition, but all require the same extra attributes, a base template might be a better approach than allowing
extensions.
Note: Categories, analyses and notifications are not affected by whether the Allow Extensions check box is
enabled.

Naming patterns
Naming pattern substitution parameters
When you define naming patterns for element, event frame, transfer, and model templates, you can use the
substitution parameters described in the following table. These naming pattern shortcuts are available in
addition to the substitution parameters that are listed in the Naming Pattern field when you click .

Parameter name Substitution

Description parameters
%DESCRIPTION:path% The object's description represented by the path to the object. If the
path is not specified, the description of the current object is used.
%\ELEMENTDESCRIPTION% The description of the object's root element, or the description of the
primary referenced element of the object's root event frame.
%..\ELEMENTDESCRIPTION% The description of the object's parent element, or the description of the
primary referenced element of the object's parent event frame. Use ..\
notation, such as %..\..\ELEMENTDESCRIPTION%, to retrieve further
ancestors.
%\EVENTFRAMEDESCRIPTION% The description of the object's root event frame.
%..\EVENTFRAMEDESCRIPTION% The description of the object's parent event frame. Use ..\ notation,
such as %..\..\EVENTFRAMEDESCRIPTION%, to retrieve further
ancestors.
ID parameters
%ANALYSISID% The ID of the object's analysis.
%ATTRIBUTEID% The ID of the object's attribute or attribute template.
%|ATTRIBUTEID% The ID of the object's root attribute or attribute template.
%..|ATTRIBUTEID% The ID of the object's parent attribute or attribute template. Use ..|
notation, such as %..|..|ATTRIBUTE%, to retrieve further ancestors.
%DATABASEID% The ID of the object's PI AF database.
%ELEMENTID% The ID of the object's element, or the ID of the primary referenced
element of the object's event frame.
Parameter name Substitution

%\ELEMENTID% The ID of the object's root element, or the ID of the primary referenced
element of the object's root event frame. Use ..\ notation, such as
%..\..\ELEMENTID%, to retrieve further ancestors.
%..\ELEMENTID% The ID of the object's parent element, or the ID of the primary
referenced element of the object's parent event frame.
%EVENTFRAMEID% The ID of the object's event frame.
%\EVENTFRAMEID% The ID of the object's root event frame.
%..\EVENTFRAMEID% The ID of the object's parent event frame. Use ..\ notation, such as
%..\..\EVENTFRAMEID%, to retrieve further ancestors.
%ID:path% The object's ID represented by the path to the object. If the path is not
specified, the ID of the current object is used.
%MODELID% The ID of the object's PI AF model.
%SYSTEMID% The ID of the object's PI AF server.
%TRANSFERID% The ID of the object's PI AF transfer.
Name parameters
%ANALYSIS% The name of the object's analysis.
%DATABASE% The name of the object's PI AF database.
%\ELEMENT% The name of the object's root element, or the name of the primary
referenced element of the object's root event frame.
%..\ELEMENT% The name of the object's parent element, or the name of the primary
referenced element of the object's parent event frame. Use ..\ notation,
such as %..\..\ELEMENT%, to retrieve further ancestors.
%\EVENTFRAME% The name of the object's root event frame.
%..\EVENTFRAME% The name of the object's parent event frame. Use ..\ notation, such as
%..\..\EVENTFRAME%, to retrieve further ancestors.
%NAME:path% The object's name represented by the path to the object. If the path is
not specified, null is returned since it references the name of the
current object.
%SYSTEM% The name of the object's PI AF server.
%\TEMPLATE% The name of the root template of the object's element or event frame.
%..\TEMPLATE% The name of the parent template of the object's element or event
frame. Use ..\ notation, such as %..\..\TEMPLATE%, to retrieve further
ancestors.
Path parameters
 Parameter name Substitution

%ELEMENTPATH% The path of the base element, the element of an attribute, or the
primary referenced element of an event frame.
%..\ELEMENTPATH% The path of the object's parent element, or the path of the primary
referenced element of the object's parent event frame. Use ..\ notation,
such as %..\..\ELEMENTPATH%, to retrieve further ancestors.
%EVENTFRAMEPATH% The path of the event frame or the element of an attribute of an event
frame.
%..\EVENTFRAMEPATH% The path of the object's parent event frame. Use ..\ notation, such as
%..\..\EVENTFRAMEPATH%, to retrieve further ancestors.
Time parameters
Note: You can specify a format string with all time substitutions. The format string is separated from the
substitution name by a colon. For example, %TIME:d% uses the short date pattern, whereas
%UTCTIME:yyyy/MM/dd HH:mm:ss.fff% specifies the format in full.

%ENDTIME:yyyy-MM-dd The current local end time of the object using the specified formatting.
HH:mm:ss.fff% If no formatting is specified, the default formatting is used. The
formatting uses standard format strings supported by the
DateTime.ToString method, as described in Format strings for time
substitution parameters.
%UTCENDTIME:yyyy-MM-dd The current Coordinated Universal Time (UTC) end time of the object
HH:mm:ss.fff% using the specified formatting. If no formatting is specified, the default
formatting is used. The formatting uses standard format strings
supported by the DateTime.ToString method, as described in Format
strings for time substitution parameters.

Create element templates

Create and configure an element template to ensure consistent definitions for elements in your asset structure.
1. In the Library browser, right-click the Element Templates collection and click New Template.
2. Adjust and assign settings on tabs to configure the element template. PI System Explorer provides defaults
for all required settings, but you can configure settings yourself. The settings include:
Option Description

Base Template You can base the template on an existing template. Select the base template
from the list. For more information on base templates, see Base and derived
templates.
Type You can base the template on an element type. Select the element type from the
list. For more information on element types, see Element types in models.
Option Description

Categories Optional. You can organize objects by grouping them into categories. To browse
available categories or to create a new category, click . See Categorization of
objects.
Default Attribute Optional. Select a default attribute from the drop-down list. See Default
attribute.
Naming Pattern Optional. You can enter a text string, or click to choose from the following
substitution parameters to define a naming pattern.
• %TIME:yyyy-MM-dd HH:mm:ss.fff%
The current local time of the object using the specified formatting. If no
formatting is specified, the default formatting is used. The formatting
uses standard format strings supported by the DateTime.ToString
method, as described in Format strings for time substitution
parameters.
• %UTCTIME:yyyy-MM-dd HH:mm:ss.fff%
The current Coordinated Universal Time (UTC) time of the object using
the specified formatting. If no formatting is specified, the default
formatting is used.
• %TEMPLATE%
The name of the object's template.
• %@Attribute%
The value of the object's attribute, represented by the path.
You can also use other naming pattern substitution parameters. For
example, if you want an element path included in the naming
pattern, enter %ELEMENTPATH% as a substitution parameter. For a
complete list of naming pattern substitution parameters, see
Naming patterns.
Each element derived from the template will have a unique, identifiable
name. To ensure that new elements created from the template have
an incremental number, enter * at the end of any pattern you enter
here.
If left blank, PI System Explorer uses the element template Name field
and adds an asterisk to add an incremental number as needed.
Some substitution parameters may not be applied when a derived
element is created. To ensure a derived element's name fully reflects
the naming pattern, right-click the element and click Reevaluate
Naming Pattern.
Note: The name generated by the naming pattern must be less than the
maximum name length of 260 characters.
 Option Description

Allow Extensions Select this checkbox to enable additional attributes (as well as ports) to be
defined for an element, beyond those defined in its template. See Extensions.
Note: Categories, analyses and notifications are not affected by whether the
Allow Extensions check box is enabled.

Base Template Only Select this checkbox to assign the Base Template Only (BTO) property to an
element template. Elements cannot be derived directly from BTO templates. For
more information, see Base and derived templates.
Extended Properties This link is an advanced feature. For more information, see Storage of
application-specific information.
Location Click this link if you wish to set up location attribute traits for the element.
However, you can also set them on an attribute if you prefer. Note that you can
only assign one set of location attributes per element. For more information, see
Attribute traits.
Security Click this link if you wish to set up custom access permissions to the element
template beyond those already established at the server and database level. For
more information, see Configure security for objects.
3. Use the Attribute Templates tab to create an attribute template for each property or data item for the
template. See Create attribute templates.
4. If you are creating a model, use the Ports tab to specify ports, which define end-points for connections
between elements within a model. See Process models in PI AF.
5. Optional. Use the Analysis Templates tab to create an analysis template for the element template. For more
information, choose from the following:
▪ To create an expression analysis template, see Create an expression analysis template.
▪ To create a roll up analysis template, see Create a rollup analysis template.
▪ To create an event frame generation analysis template, see Create an event frame generation analysis
template.
▪ To create an SQC analysis template, see Create an SQC analysis template.
6. Optional. Use the Notification Rule Templates tab to select or create a notification rule template for the
element template. For more information, see Create a notification rule template.
7. To save your work, press CTRL+S or click Check In.

Find template references

Locate where a template is used in PI System Explorer.
1. In the Library browser, choose from the following options:
▪ To locate an element template, expand Templates > Element Templates and select a template.
▪ To locate an event frame template, expand Templates > Event Frame Templates and select a template.
2. Choose from the following options:
To find ... Do this ...

Derived templates Click Derived Templates.

The Find Derived Templates for Element_Template
window displays all element templates that have the
selected element template as their base template.
The list also includes element templates that are
indirectly derived from the selected template,
through multiple templates.
Elements created from the template Click Elements.
The Find Elements for Element_Template window
displays all elements, models, transfers, and event
frames that have been created directly from the
selected element template.
Note: To display the full path to elements, right-click
on the column header (or below the search results
grid) and click Show Full Paths.

Elements derived from the template Click Derived Elements.

The Find Derived Elements for Element_Template
window displays all elements, models, transfers, and
event frames that have been created from the
selected element template, as well as from any
template that is derived from it.
Note: To display the full path to derived elements,
right-click on the column header (or below the search
results grid) and click Show Full Paths.

Referenced parent templates Click Referenced Parent Templates.

The Find Referenced Parent Templates for
Element_Template window displays element
templates that have specifically been linked to this
element template as a parent through a reference
type. The list of templates includes those that
indirectly have been linked through template
inheritance.
 To find ... Do this ...

Referenced child templates Click Referenced Child Templates.

The Find Referenced Child Templates for
Element_Template window displays element
templates that have specifically been linked to this
element template as a child through a reference type.
The list of templates includes those that indirectly
have been linked through template inheritance.
Event frames created from the template Click Event Frames.
The Find Event Frames for Event_Frame_Template
window displays all event frames that have been
created directly from the selected event frame
template.
Note: To display the full path to event frames, right-
click on the column header (or below the search
results grid) and click Show Full Paths.

Event frames derived from the template Click Derived Event Frames.
The Find Derived Event Frames for
Event_Frame_Template window displays all event
frames that have been created from the selected
template, as well as from any template that is derived
from it.
Note: To display the full path to derived event frames,
right-click on the column header (or below the search
results grid) and click Show Full Paths.

Define templates for other objects

In addition to element templates, you can create base templates for event frames, models, and transfers. After a
base template is designed, you can create derived templates from it and then assign additional attributes as
needed. You then create instances of the object by basing them on the derived template. To learn more, see
Base and derived templates.
1. In the navigator, click Library.
2. In the Library browser, open Templates to display the following object collections:
▪ Element Templates
▪ Event Frame Templates
▪ Model Templates
▪ Transfer Templates
3. Right-click an object collection and select New Template.
 The new template displays the following tabs:
• General
• Attribute Templates
• Ports (not available for event frame templates)
Note: To ensure certain templates are not used directly to create objects, you can assign the Base
Template Only (BTO) property to a new template. BTO templates can be used to create derived
templates. When an instance of an object is created, it is based on the derived template, not the BTO
template.
4. Fill in these tabs just as you would for an element template. See Create element templates.
5. To save your work, press CTRL-S or click Check In.

Child templates
In some cases, you might want to create a template that has one or more child templates. For example, suppose
you have a template representing a motor and you want a separate template for the shaft. You want the shaft
template to be a child of the motor template. You cannot directly create a child template in the same way that
you would create a child element. Instead, you create a new referenced template below the Motor template.

This also creates a new reference type in the Reference Types collection.

Now, suppose you create an element based on the Motor template. PI System Explorer does not automatically
create the child element, Shaft. However, when you manually create a child element on the motor element, the
Motor-Shaft reference type is added to the list of reference types and the Shaft template appears in the Element
Template list.

Create child template references

Create a child template reference when you need to establish parent-child relationships between two element
templates.
1. In the Library browser, right-click the template to which you want to add the child template reference and
click New > New Referenced Template.
2. In the Set Referenced Element Template Name window, type a name for the child template, and click OK.
This creates a child template in the Templates collection and a new reference type in the Reference Types
collection.
3. Optional. To define a reference type other than strong parent-child, select the Edit reference type check box.
 a. In the Reference Type Properties window, select the desired reference strength from the Reference
Strength list.
b. Click Check In.
c. Click OK to close the window.
4. Complete the element template definition, as described in Create element templates.

Asset representation with elements

In your asset model, elements represent physical objects, such as pumps or tanks. Each element has associated
attributes that store properties and data for that element. Typically, you base each element on a template. For
example, you would base each pump element on a pump template.

Create elements based on a template

Use the element templates that you have defined to create elements in your asset hierarchy.
1. In the Elements browser, right-click the collection of elements or an individual element and click New
Element.
2. In the Choose Element Template window, select an element template in the Element Template field.
3. In the Add child element using the reference type field, select a reference type from the list of available
types.
The available reference types depend on the selected element template and what reference types are
defined in the database. If you are not sure what reference type to use, select the default reference type,
parent-child.
4. Click OK.
Property tabs for the new element are displayed in the viewer. Because the element is based on a template,
most fields on the General tab are read-only (with gray or hash-pattern shading).
5. In the Name and Description fields, type a name and description for the element.
6. Optional. Perform the following actions as needed.
▪ Click the Extended Properties link to create properties for client applications such as PI ProcessBook and
PI WebParts. For more information, see Storage of application-specific information.
▪ Click the Location link to set up location attribute traits for the element. For more information, see Set
location attribute traits.
▪ Click the Annotations link to enter a note for the element. For more information, see Element
annotations.
▪ Click the Security link to set up custom access permissions for the element. For more information, see PI
AF object security.
7. Optional. Click the Attributes tab to review the attributes defined by the template. You cannot add new
attributes unless the template allows extensions.
8. Optional. Click the Notification Rules tab to review any notification rules defined by the template. You
cannot add new notification rules unless the template allows extensions.
 9. To save your work, press CTRL+S or click Check In.

Create elements not based on a template

Although you can create elements that are not based on a template, it is strongly recommended to base your
elements on templates to take advantage of powerful template-based features available in client applications.
You can use the Convert to Template feature, as described in Convert elements to element templates.
1. In the Elements browser, right-click the collection of elements or an individual element and click New
Element.
2. In the Choose Element Template window, select a reference type in the Add child element using the
reference type field.
The available reference types depend on the element template and what reference types are defined in the
database. If you are not sure what reference type to use, you probably want the default reference type,
parent-child.
3. In the Element Template field, click <None>.
4. Click OK.
Property tabs for the new element are displayed in the viewer.
• Use the General tab to perform the basic element configuration.
• The Child Elements tab is mainly used to view existing child elements on an existing element. You can
optionally create new child elements directly from this tab.
• Use the Attributes tab to create an attribute for each property or data item.
• Use the Ports tab only if you are modeling a process.
• Use the Analyses tab to select an analysis for the element.
• Use the Notification Rules tab to select a notification rule for the element.
• Use the Version tab to add version information for the element.
5. Optional. Perform the following actions as needed.
▪ Click the Extended Properties link to create properties for client applications such as PI ProcessBook and
PI WebParts. For more information, see Storage of application-specific information.
▪ Click the Annotations link to enter a note for the element. For more information, see Element
annotations.
▪ Click the Security link to set up custom access permissions for the element. For more information, see PI
AF object security.
6. To save your work, press CTRL-S or click Check In.

Find where an element is used

Use the Find links on the General tab for a selected element to locate where and how it is used in the asset
model.
1. Select an element in the Elements browser.
2. Choose from the following options:
 To find ... Do this ...

Parent elements Click the Parents link. The Parents of Element window
opens.
Child elements a. Click the Children link.
b. In the Element Search window, enter
element name text in the search field. To
refine your search, you can enter
additional criteria in the Criteria section.
c. Click Search.
Matching elements are displayed in the
Results section.
Event frames connected to the element Click the Event Frames link.
• If a match is found, the Find Event Frames for
Element displays a list of all event frames
that reference the element.
• If no match is found, a No Event Frames
Found message is displayed.

Deletion of elements
When you delete an element, PI AF automatically deletes the notifications and analyses that target that element.
If you wish to repurpose a notification attached to an element that you plan to remove, ensure you do so before
you remove the element.
Alternatively, you can change the default behavior so that PI AF does not automatically delete notifications and
analyses when you delete the targeted element.
You use the afdiag command line utility with the /EnablePropagationOfTargetDeletion parameter, as described
in AFDiag utility parameters:
afdiag /EnablePropagationOfTargetDeletion-
Be aware that disabling the setting can cause problems, such as:
• Notifications are left open (and remain active)
• New notifications are not created
• Expected emails are not sent

Attribute-value reset to original properties

When you have created elements based on templates in a test environment and later want to transfer your work
to a production environment, you can reset all attributes for an element to the original properties as defined by
a template. You can right-click an attribute for an element and click Reset to Template.
For example, suppose you configure a PI AF attribute to use the name of Data Archive as part of the attribute’s
configuration in a test environment. You might want this to reflect the new name for Data Archive when you
transfer your work to a production environment.
 Convert elements to element templates
You should create elements that are based on templates. If you created elements and attributes and did not
originally base them on a template, you can later convert them to a template.
1. In the navigator, click Elements.
2. In the Elements browser, locate the element that you want to convert to a template.
3. Right-click the element and click Convert > Convert to Template.
A template named ElementNameTemplate is created and displayed in the Template field on the General
tab.
4. Optional. To rename the template, click Library in the navigator.
a. In the Library browser, locate the new template in the Element Templates branch.
b. Right-click the template and click Rename.
c. Modify the default name as needed. The new name must be unique across all templates.

Change element templates

Exercise caution when you change an element template, since there can be unintended consequences. For
example, attributes could be deleted if they were defined by the old template and are not present in the new
template. Be sure that attributes with the same name in both the old and new template have the same data
type.
You can change the template on which an existing element is based, or add a template to an element that is not
currently based on a template.
1. In the navigator, click Elements.
2. In the Elements browser, right-click the element that you want to change and click Convert > Change
Template.
3. In the Choose Element Template window, select a template from the Element Template list.
• Optional. To display only templates in a specific category, select a category from the Templates of
category list.
4. Click OK.

Storage of application-specific information

Extended properties are properties that other applications define on PI AF objects. For example, PI WebParts
stores Icon and URL in a PI AF element's extended properties. Applications typically make use of the information
stored in the Extended Properties window programmatically with AF SDK.
An Extended Properties link is displayed on the General tab of many object types in PI System Explorer. This link
can be used to configure one or more additional properties for an object.
Note: Users do not need to use this advanced PI AF feature.
Create extended properties
In general, client applications such as PI WebParts and PI ProcessBook use the Extended Properties feature to
write properties, and users do not need to use this advanced feature.
1. Click the Extended Properties link.
2. In the Extended Properties window, choose from the following actions:
▪ To create the first extended property, click the New Extended Property link.
▪ To create an additional extended property, right-click in the Name column and select New Extended
Property.
3. In the Name field, delete the default text and enter the extended property name.
4. Click in the Value field and choose from the following options:
▪ Enter a string. To visualize the text you are entering, press F2 and type in the Text Visualizer window.
▪ Click and select from the list of Basic Types, Array Types, and Objects.
• If you choose an object such as Attribute or Element, click and locate the desired object.
• If you choose File, click and select Upload to locate the desired file.
5. Click Close.
Chapter 7

Association of data with PI AF assets

To associate data with an asset, you create attributes on the element that represents that asset.
Attributes can hold simple values that represent fixed information, such as the diameter of a tank. They can also
hold values from PI points, be derived from formulas, or hold data from outside the PI System through the use of
PI AF tables.
Enumeration sets
If you need an attribute to hold only predefined values, you can use an enumeration set. An enumeration set
maps an ordered set of user-defined constant values to a set of strings. You can use the strings to provide brief,
descriptive text to use within your PI AF model.
Videos
For information on how to create element attributes, watch this video:
For information on how to create child attributes, watch this video:

Attribute templates
Attribute templates are associated with element templates. Just as an element template represents a type of
asset, an attribute template represents a type of data configuration. When you create an instance of the element
template, that element contains an attribute for each attribute template. These attributes inherit all properties
configured on the attribute template.
Rather than create attributes on each element, create attribute templates in an element template. Whenever
you create elements based on that template, PI AF automatically creates the attributes for you. You still need to
give each attribute a value.
Modification of attribute descriptions created from attribute templates
Beginning with 2017 R2, you can modify the descriptions of attributes that are created from a template. You may
find this helpful when differentiating between attributes that use the same attribute template. For example, in a
series of pumps, each pump has a Flowrate attribute with a PI point data reference. The template description for
Flowrate is simply Pump flowrate. To make that description unique for each instance of the pump, you could use
PI Builder to load the descriptor attribute for each pump flowrate PI point and incorporate that value into each
Flowrate description, thereby customizing it.
To modify descriptions created from an attribute template, you must use a PI AF client and server that are
running PI AF 2017 R2 or later. Older clients that connect to a PI AF server running 2017 R2 or later continue to
see only the description from the attribute template.
 Note: Because extra memory is used to store descriptions for attributes that have been overridden, loading them
into client applications can take a little longer.
Video
For information on how to create attribute templates, watch this video:

Attribute properties
You need to set up the properties for each element attribute. After you assign properties in an attribute
template, users can only modify the Exclude property on individual attributes.

Configuration Item attribute property

You assign the Configuration Item property to an attribute that represents inherent properties of an asset. Any
attribute that has a constant value can be a configuration item. Because the attribute value of a configuration
item is presumed to be constant, PI System Explorer automatically checks out the attribute when you change the
attribute value. To commit the change, you need to check it in. In PI System Explorer, configuration attributes are
marked with a pencil icon ( ).
Attributes with values that change, such as PI point data references, or formula data references, should not be
configuration attributes. When you change the value of a non-configuration attribute, PI System Explorer does
not check out the attribute. For example, suppose you have an element representing a tank. The element has
the following attributes:
• manufacturer
• photo (file)
• serial number
• maximum temperature rating
• maximum volume
• temperature (PI point data reference)
• volume (PI point data reference)
The first five attributes would typically be configuration items, since these values will not change unless you
change the equipment. The last two attributes would not be configuration items, since the values change all
the time.

Excluded attribute property

You exclude an attribute in situations where not all attributes in an element template apply. For example,
suppose you have five attribute templates defined in an element template named Meter, which you use to
create elements representing several different types of meter in use at your facility. In some kinds of meter
(meterA), only three attributes from the Meter template are applicable, whereas in the remainder (meterB) all
five attributes apply. In meters of type A, you should select the Excluded property for the two attributes that are
inapplicable. For all practical purposes, those two attributes “seem” nonexistent to most PI AF client applications
since searches retrieve the digital state value No Result.
Note: An excluded attribute cannot be used to return elements and event frames that are referenced by an
excluded attribute value.
When the Excluded property is assigned in an attribute template, the property is indicated by beside the
attribute name if the Show Excluded Attributes option is enabled. Attributes that are derived from that template
appear on an element Attributes tab with in the Template column and Excluded in the Value column. You can
toggle the display of such attributes with the Hide Excluded Attributes and Show Excluded Attributes command
on the Attributes tab context menu. Note that when Show Excluded Attributes is enabled, users can change the
Excluded property setting for an attribute from the setting it is assigned in an attribute template. See Create
attribute templates for instructions on how to exclude an attribute.
Alternatively, you can clear the Show Excluded Attributes option in Tools > Options to hide excluded attributes
everywhere in PI System Explorer. When attributes are hidden, the Excluded attributes are hidden message is
displayed on the Attributes tab.

Hidden attribute property

A hidden attribute is one that cannot be retrieved in searches from PI AF client applications such as AVEVA PI
Vision. This property is useful if an attribute is being used to hold an intermediate result, such as a table lookup
result that can then be retrieved by a PI point data reference, or is being used solely to populate a PI point name
in a substitution parameter.
It can also be useful to set an attribute property to Hidden in a template when configuration has not been fully
completed in the element itself. For example, elements are being created from a template with a PI point data
reference, but because some instrumentation is missing, PI points do not yet exist for all the elements. By setting
the attributes for the missing instrumentation to Hidden, a PI AF client application is prevented from obtaining
an error result from a search.
When the Hidden property is assigned to an attribute in an attribute template, the property is indicated by in
the Hidden column beside the attribute name. The same icon is displayed next to the attribute name on the
Attributes tab when the template is assigned to an element.

Indexed attribute property

You index an attribute to optimize it for fast search results and fast value retrieval. Indexes only improve
performance for attributes whose values are stored in the PI AF database. This means that you do not gain any
benefit from indexing attributes that obtain their values from data references, as is the case with PI points and
linked tables. For event frames, however, when attribute values are captured they are written to the PI AF server
and as a result can benefit from indexing.
Note: Only the first 40 characters of indexed attributes with a String value type are used in searches.
When you index an attribute, both the attribute and the attribute value are returned more quickly in a search.
However, indexed attributes increase the table size in your PI AF database and they create some CPU load on the
SQL server. Indexed attributes are marked with the icon.
You typically index an attribute that you think users are likely to search for frequently. For example, if you know
that you want to locate assets by searching for a serial number, you should index the serial number attribute.

Manual Data Entry attribute property

You flag an attribute for manual data entry to enable client applications (such as AVEVA PI Vision and PI Manual
Logger) to guide users to enter data for that attribute. For example, in a future release of PI Manual Logger, this
property will identify tags in a tour that operators should collect manually, in contrast to tags that are collected
automatically via an interface or connector.
 To determine which attributes have this property, add a Manual Data Entry column to an attribute grid in the
Elements viewer, where attributes with this property display as True.

Attribute traits
Attribute traits identify commonly held characteristics or related behaviors of a parent attribute. PI AF supports
attribute traits for limit conditions, forecasted values, geolocation information, reason codes, asset health, and
analysis start triggers. Users and client applications like AVEVA PI Vision can then find, display, and analyze such
related attributes more effectively.
To set and access attribute traits, both the PI AF client and server need to be running PI AF 2016 or later.
Limit attribute traits
You use limit attribute traits to identify the expected range of a process variable or a measurement attribute.
Limit attribute traits are often set elsewhere (for example, on a control system), or represent inherent properties
of the parent attribute, such as temperature. A typical usage would be to set up conditions for an alarm. AVEVA
PI Vision, for example, uses most limit attributes as input when configuring multi-state behavior for a visual
alarm.
Limit attribute traits are child attributes of the measurement they describe and have the same value type and
UOM as the parent. The only exception is when the value of a limit attribute trait is obtained from a data
reference, in which case the source UOM of a defined data reference can be different. You can also only set limit
attribute traits for parent attributes that are numeric. Note that you can only assign a specific limit attribute trait
once to a parent attribute.
The following limit traits are defined:

Limit attribute trait Description

Minimum Indicates the very lowest possible measurement value or process output.
LoLo Indicates a very low measurement value or process output, typically an abnormal one
that initiates an alarm.
Lo Indicates a low measurement value or process output, typically one that initiates a
warning.
Target Indicates the aimed-for measurement value or process output.
Hi Indicates a high measurement value or process output, typically one that initiates a
warning.
HiHi Indicates a very high measurement value or process output, typically an abnormal one
that initiates an alarm.
Maximum Indicates the very highest possible measurement value or process output.
Video
For information on how to set limit attribute traits, watch this video:
Forecast attribute traits
In general, you use forecast attribute traits as predicted values to compare with the actual value of the parent
attribute. Typically, such attribute traits represent future PI points but that is not a requirement. Client
applications can very easily relate these attributes and trend them together.
Forecast attribute traits are child attributes of the attribute they describe and have the same value type and
UOM as the parent. The only exception is when the value of a forecast attribute trait is obtained from a data
reference, in which case the source UOM of a defined data reference can be different. You can also create
forecast attribute traits for parent attributes that are of any value type. Note that you can have multiple forecast
attribute traits defined for a parent attribute.
Location attribute traits
You 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.
You can create location attribute traits on an element, an event frame, a model, or on their child attributes.
However, you can create only one of each attribute trait per element, event frame, or model. The UOM for the
latitude and longitude attribute traits should be degree (the default) or at least an angle, whereas the altitude
attribute trait can be meter (the default) or another UOM in the Length class. The value type for all location
attribute traits must be numeric (double).
Reason attribute traits
You use reason attribute traits on event frames and transfers to enable users to select a reason code for
excursions, downtime, and other events. You can set a single reason attribute trait on an event frame or transfer
template or an event frame or transfer instance. The reason attribute trait must be an enumeration set that is
previously defined, or a system enumeration set delivered with PI AF.
Health attribute traits
You 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.
Analysis start-trigger attribute 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 AVEVA PI Vision to indicate the start trigger that created that particular event frame. For
more information, see Event frame generation analyses.

Set limit attribute traits

Set up to seven limit traits for an attribute template or an element attribute to enable users to define the
expected range of a process variable or a measurement.
1. Choose from the following actions:
 To set a limit trait for an ... Do this ...

Attribute template a. In the Library browser, select an element

template.
b. In the viewer, click the Attribute Templates
tab.
Element attribute a. In the Elements browser, select an element.
b. In the viewer, click the Attributes tab.
2. Select the attribute for which you want to set one or more limit traits.
3. Choose one of the following actions:
▪ Right-click and click Limits.
▪ At the bottom of the configuration area, click the Limits link.
4. In the Limits window, select the check box beside the limit trait you want to set.
5. In Attribute, choose one of the following actions:
▪ Leave the default attribute name as is.
▪ Replace the default attribute name with a revised name of your choice.
▪ If a child attribute already exists that you want to assign to the limit trait, select it from the drop-down
list.
Note: Limit attribute traits that have already been defined are displayed in bold typeface.
6. Choose from the following actions:
To set a ... Do this ...

Value for the limit trait In Value, enter a limit value.

Value for the limit trait from a data reference a. In Data Reference, select a data reference
type.
b. In Settings, click to configure the data
reference.
Note: The source UOM of a data reference
can be different from that of the parent
attribute.
c. Click OK to close the data reference window.
The result of the evaluated data reference is
displayed.
7. Repeat steps 4 to 6 to set values for other limit traits.
8. Click OK when your list of limit traits for the selected parent attribute is complete.
Set forecast attribute traits
Set one or more forecast traits for an attribute template or an element attribute to enable users and client
applications to compare predicted values with actual values and plot a trend.
1. Choose from the following actions:
To set a forecast trait for an ... Do this ...

Attribute template a. In the Library browser, select an element

template.
b. In the viewer, click the Attribute Templates
tab.
Element attribute a. In the Elements browser, select an element.
b. In the viewer, click the Attributes tab.
2. Select the attribute for which you want to set one or more forecast traits.
3. Choose one of the following actions:
▪ Right-click and click Forecasts.
▪ At the bottom of the configuration area, click the Forecasts link.
4. In the Forecasts window, click the New Forecast button or link.
5. In Attribute, choose one of the following actions:
▪ Leave the default attribute name as is.
▪ Replace the default attribute name with a revised name of your choice.
▪ If a child attribute already exists that you want to assign to the forecast trait, select it from the drop-
down list.
Note: Forecast attribute traits that have already been defined are displayed in bold typeface.
1. Choose from the following actions:
To set a ... Do this ...

Value for the forecast trait In Value, enter a forecast value.

Value from a data reference a. In Data Reference, select a data reference
type.
b. In Settings, click to configure the data
reference.
Note: The source UOM of a data reference
can be different from that of the parent
attribute.
c. Click OK to close the data reference window.
The result of the evaluated data reference is
displayed.
2. You can set as many forecasted values as necessary. Repeat steps 4 to 6.
3. Click OK when your list of forecast attributes for the selected parent attribute is complete.

Set location attribute traits

You can only set one set of location attribute traits per element, model, or event frame.
Set one or more location traits on an element or event frame template or on an element or event frame to
enable users to identify the location of an asset on a map. You can also set a location for a model.
1. Choose from the following actions:
To set a location trait on ... Do this ...

Element or model template a. In the Library browser, select an element or

model template.
b. Choose one of the following actions:
Right-click
• and click Location.
On
• the General tab, click the Location
link.
Event frame template a. In the Library browser, select an event frame
template.
b. Choose one of the following actions:
Right-click
• and click Location.
On
• the General tab, click the Location
link.
Element or model a. In the Elements browser, select an element
or model.
b. Choose one of the following actions:
Right-click
• and click Location.
On
• the General tab, click the Location
link.
Event frame a. In the Event Frames browser, select an event
frame.
b. Choose one of the following actions:
Right-click
• and click Location.
On
• the General tab, click the Location
link.
Note: You can also configure location traits as a child attribute template to an existing attribute template, or as a
child attribute to an existing attribute:
On a template, right-click an attribute template and click Location of Element/Event Frame/Model Template.
On an element, event frame, or model, right-click an attribute and click Location of Element/Event Frame/
Model.
1. In the Location window, select the check box beside the trait you want to apply, or select the check box in
the column header to select all traits.
2. In Attribute, choose one of the following actions:
▪ Leave the default attribute name as is. The default attribute name displays the path relative to the
element.
▪ Replace the default attribute name with a name of your choice. Ensure that the full path to the element
is retained.
▪ If a child attribute already exists that you want to assign to the location trait, select it from the list.
Note: Location attribute traits that have already been defined are displayed in bold typeface.
3. Choose from the following actions:
To set a ... Do this ...

Value for the location trait In Value, enter a location value.

Value from a data reference a. In Data Reference, select a data reference
type.
b. In Settings, click to configure the data
reference.
c. Click OK to close the data reference window.
The result of the evaluated data reference is
displayed.
4. Click OK when your list of location attributes for the selected element is complete.

Set reason attribute traits

You can only set one reason attribute trait per event frame or transfer.
Use reason attribute traits on event frames and transfers to enable users to select a reason code for excursions,
downtime, and other events.
1. To designate an attribute as a reason attribute trait for an event frame or transfer, choose from the following
actions:
To set a reason attribute trait for ... Do this ...

Event frame template a. In the Library browser, select an event frame

template.
b. Choose one of the following actions:
Right-click
• and click Reason.
On
• the General tab, click the Reason link.
To set a reason attribute trait for ... Do this ...

Transfer template a. In the Library browser, select a transfer

template.
b. Choose one of the following actions:
Right-click
• and click Reason.
On
• the General tab, click the Reason link.
Event frame a. In the Event Frames browser, select an event
frame.
b. Choose one of the following actions:
Right-click
• and click Reason.
On
• the General tab, click the Reason link.
Transfer a. In the Event Frames browser, select a
transfer.
b. Choose one of the following actions:
Right-click
• and click Reason.
On
• the General tab, click the Reason link.
Attribute template for an event frame template a. In the Library browser, select an event frame
template.
b. Click the Attribute Templates tab.
c. Choose one of the following actions:
Right-click
• an existing attribute template
and click Reason for Event Frame
Template.
Click
• New Attribute Template, right-click
and click Reason for Event Frame
Template.
Attribute template for a transfer template a. In the Library browser, select a transfer
template.
b. Click the Attribute Templates tab.
c. Choose one of the following actions:
Right-click
• an existing attribute template
and click Reason for Transfer
Template.
Click
• New Attribute Template, right-click
and click Reason for Transfer
Template.
 To set a reason attribute trait for ... Do this ...

Event frame or transfer attribute If the Allow Extensions check box has been selected
for an event frame or a transfer template, and no
attribute template has previously been designated as
a reason attribute trait, you can either create a new
attribute and establish it as the reason attribute trait,
or choose an existing attribute.
a. In the Event Frames or Transfer browser,
select an event frame or transfer.
b. Click the Attributes tab.
c. Choose one of the following actions:
Right-click
• an existing attribute and click
Reason for Event Frame or Reason
for Transfer.
Right-click
• below the attribute table and
click Reason for Event Frame or
Reason for Transfer.
2. In the Reason window, select the check box beside the Reason trait you want to apply.
3. In Attribute, choose one of the following actions:
▪ Leave the default attribute name as Reason.
▪ If an attribute already exists that you want to designate as the reason trait, select it from the list.
Note: Reason traits that have already been defined are displayed in bold typeface.
4. Choose from the following actions:
To set a ... Do this ...

Default value for the reason trait a. In Value Type, select Enumeration Value >
Enumeration Sets and select an
enumeration set to use for the reason
trait. The default is the built-in System
enumeration set.
b. In Default Value, select the default reason
trait value from the selected enumeration
set.
 To set a ... Do this ...

Default value from a data reference a. In Data Reference, select a data reference
type.
Note: The data reference must be to a digital states
tag. b. In Settings, click to configure the data
reference.
c. Click OK to close the data reference window.
The result of the evaluated data reference is
displayed.
5. Click OK when the assignment of a default reason trait for the selected event frame or transfer is complete.

Set health attribute traits

You can only set one set of health attribute traits per element or model.
Set health attribute traits for an element template or for an element to enable users to establish the health of an
asset. You can also set health attribute traits for a model template or model.
1. Choose from the following actions:
To set a health trait for ... Do this ...

Element or model template a. In the Library browser, select an element or

model template.
b. Choose one of the following actions:
Right-click
• and click Health.
On
• the General tab, click the Health link.
Element or model a. In the Elements browser, select an element
or model.
b. Choose one of the following actions:
Right-click
• and click Health.
On
• the General tab, click the Health link.
 To set a health trait for ... Do this ...

Attribute template a. In the Library browser, select an element or

model template.
b. In the viewer, click the Attribute Templates
tab.
c. Choose one of the following actions:
•
Right-click under the grid and click
Health of Element Template.
Click
• New Attribute Template and from
the Properties list, select Health >
HealthScore or Health >
HealthStatus. Then assign values, as
described in step 4.
Attribute a. In the Elements browser, select an element
or model.
b. In the viewer, click the Attributes tab.
c. Choose one of the following actions:
Right-click
• under the grid and click
Health of Element.
Click
• New Attribute and from the
Properties list, select Health >
HealthScore or Health >
HealthStatus. Then assign values, as
described in step 4.
Note: You can also configure health traits as a child attribute template to an existing attribute template, or as a
child attribute to an existing attribute by right-clicking and clicking Properties. From the Properties list, select
Health > HealthScore or Health > HealthStatus. Then assign values, as described in step 4.
2. In the Health window, select the check box beside the trait you want to apply, or select the check box in the
column header to select all traits.
3. In the Attribute column of the Health window, choose one of the following actions:
▪ Leave the default attribute name as is. The default attribute name displays the path relative to the
element.
▪ Replace the default attribute name with a name of your choice. Ensure that the full path to the element
is retained.
▪ If a child attribute already exists that you want to assign to the health trait, select it from the list.
Note: Health attribute traits that have already been defined are displayed in bold typeface.
4. Choose from the following actions:
 To set a ... Do this ...

Value for the HealthScore trait In Default Value (for a template) or Value (for an
element) , enter a numeric value.
Value for the HealthStatus trait In Default Value, select a Health Status enumeration
value:
• Healthy
• Out of Service
• In Maintenance
• Warning
• Error
• Other Health Status enumeration set values
added by an administrator
Value from a data reference a. In Data Reference, select a data reference
type.
b. In Settings, click to configure the data
reference.
c. Click OK to close the data reference window.
The result of the evaluated data reference is
displayed.
5. Click OK when your list of health attributes for the selected element (or model) is complete.

Control the display of attribute and attribute template values

Prior to PI AF 2018, PI System Explorer rendered numeric data types in displays with high levels of precision. For
example, the Single and Double data types have a precision of seven and fifteen respectively. Such high levels of
precision are not always useful in real-time situations, or for PI AF client products: for example, a temperature
gauge may only display a precision of three digits, so process engineers are unlikely to require a greater degree
of precision for mathematical calculations.
Beginning with PI AF 2018, the Use DisplayDigits for Attribute and Attribute Template values system option is
enabled and ensures that the default setting of the DisplayDigits property is used to display attribute values: -5,
or a total of five digits overall. This is the same default setting used for PI points on Data Archive.
When creating attribute templates, you can now control the number of digits you want to see for individual
attributes in the Display Digits field:
• You can enter a negative number up to -20 to indicate the total number of digits to display.
• You can enter a positive number up to 10 to indicate the number of digits after the decimal point to display,
including trailing zeros.
When you are editing an attribute value, the actual number is displayed rather than the truncated number
established by the Display Digits field.
 For attributes that are not based on a template, the precision of PI point data references is obtained from the PI
point itself.
Note: On upgrades, existing attributes configured with a PI Point data reference are not updated to obtain their
DisplayDigits value from the PI point: they are set to -5.

Create attribute templates

Use attribute templates to create a standard set of attributes that are associated with element, event frame,
model, and transfer templates.
1. In the Library browser, select a template.
2. To create a new attribute template, choose one of the following actions:
▪ On the toolbar, click New Attribute Template.
▪ Right-click the template in the browser and click New > New Attribute Template.
3. In the Name and Description fields, enter a unique name and a description for the attribute template.
Note: When you need to search for an attribute, you can search on up to 440 characters of a description.
4. Set the configuration fields, as needed.
Field Description

Properties Select one or more of the following properties, as

needed.
• Configuration Item
• Excluded
• Hidden
• Indexed
• Manual Data Entry
For more information on these properties,
see Attribute properties.
You can set up the current attribute template
to be a location attribute trait for a
parent object. Select one of:
• Location > Longitude
• Location > Latitude
• Location > Altitude
When the parent object is an event frame or
transfer, you can set up the current
attribute template to be a reason
attribute trait. For more information, see
Set reason attribute traits.
When the parent object is an element or
model, you can set up the current
attribute template to be an asset health
attribute trait. For more information, see
Set health attribute traits.
Note: When you configure a child attribute template,
you can also select limit and forecast attribute traits,
depending on the value type of the parent attribute
template. For more information, see Attribute traits.

Categories Click and select one or more previously defined

categories from the Categories window. You can also
create a new category. For more information, see
Categorization of objects.
 Field Description

Default UOM Select a UOM from the list. For more information on
UOMs, see Units of measure in PI AF.
Note: Although a user can change the UOM that is
displayed for an attribute in PI System Explorer, the
UOM that is defined in the template does not change.

5. Configure the type of value that the attribute holds.

▪ For attributes with constant values, set the attribute Value Type. Constant attribute values can be
numbers, strings, files, date-times, Boolean, URLs, arrays, and more. For more information, see Define
constant values for attribute templates.
Note: Do not set a default UOM for integer value types if searches by client applications, such as AVEVA
PI Vision, will be performed on the value or a UOM conversion is involved. For example, an integer value
type with a default UOM is not compatible with the UOM groups feature introduced in PI AF 2017 R2.
Use the Single or Double value type instead.
Note: While allowed, the Anything value type is not recommended. When the value type is unspecified,
many client applications may have difficulty working with that attribute. For example, PI OLEDB
Enterprise, PI ProcessBook, and AVEVA PI Vision would all have reduced capability with such attributes,
such as the inability to trend a value numerically. Furthermore, standard PI AF features such as
automatic UOM conversion, formulas, and analytics cannot function with attributes that have no value
type.
▪ For PI point values, PI point arrays, formulas, and table data (including data from relational databases),
click Settings to configure a data reference. For more information, see Configuration of data references.
6. Optional. Enter a default value for the attribute in the Default Value field.
7. Optional. When the Use DisplayDigits for Attribute and Attribute Template values system option is selected,
you can override the default DisplayDigits property value of -5 and specify the number of digits to display in
the Display Digits field. Only numeric values in the Value field are affected.
▪ Enter a negative number up to -20 to indicate the total number of digits to display.
▪ Enter a positive number up to 10 to indicate the number of digits after the decimal point to display,
including trailing zeros.
For more information, see Control the display of attribute and attribute template values and PI System
Explorer customization options.
8. To save your work, press CTRL-S or click Check In.
When you create an attribute based on the template, you need to set the value:
• For constant values, add the value to the attribute directly.
• For data references, you need to create the instance of the data reference. To do this, right-click on the
element in the browser and choose Create or Update Data Reference. For more information, see
Attribute-value updates from PI point data references.
 Note: The way you configure an attribute can sometimes restrict how the data can be viewed in client
applications, such as PI ProcessBook or AVEVA PI Vision. See Restrictions on viewing time series data
for more information.

PI AF data types
The following table contains definitions of the data types in use in .

Data type Data Archive Description Range

equivalent

Boolean None A data type that tracks true or True or False

false conditions
A Boolean attribute can be stored into a PI
point of type String and any of the Integer
tags, but Digital is the preferred
representation.
Byte None An 8-bit unsigned data type 0 to 255
These values can be represented in a larger PI
data type such as Int16. However, if Data
Archive contains data outside the byte range,
an error is returned when retrieved through
PI AF.
DateTime Timestamp Date and time stored • If stored in Data Archive: 1 Jan 1970 to 19
internally in 64 bits Jan 2038, with a precision of 15
microseconds
• If not stored in Data Archive: 1 Jan 0001
to 31 Dec 9999, with a precision of 100
nanoseconds
Double Float64 A 64-bit floating point number ±5.0e−324 to ±1.7e308, 15 digits of precision
GUID None A unique 128-bit data type 00000000-0000-0000-0000-000000000000 to
used for the global ffffffff-ffff-ffff-ffff-ffffffffffff
identification of objects
The above values can be represented as a
String PI data type.
Int16 Int16 A 16-bit signed integer -32,768 to 32,767
The PI AF Int16 data type is not equivalent to
the Data Archive Int16 data type. In Data
Archive, the Int16 data type only supports
positive integers.
Int32 Int32 A 32-bit signed integer -2,147,483,648 to 2,147,483,647
 Data type Data Archive Description Range
equivalent

Int64 None A 64-bit signed integer -9,223,372,036,854,775,808 to

9,223,372,036,854,775,807
There is no equivalent of an Int64 in Data
Archive. For non-numerical representations
(such as an ID number), a string may be used.
For numerical representations, Float64
provides some equivalence but will be subject
to rounding issues with very large (positive or
negative) numbers.
Single Float32 A 32-bit floating point number ±1.5e−45 to ±3.4e38, 7 digits of precision
String String A sequence of multiple Data Archive strings limited to 976 characters,
characters and are not unicode

Define constant values for attribute templates

You can assign constant values directly on an attribute template. Although you cannot set actual attribute values
in attribute templates, you can define default values.
1. In the viewer, use the Value Type field to select the data type of the attribute.
There are four groups of value types:
• Basic Types
A data type supported by PI AF, as described in PI AF data types.
• Array Types
An array contains any of the Basic types as elements.
• Enumeration Sets
An enumeration set is a list of user-defined constant values. You typically use an enumeration set to
define a list of predefined values for an attribute template. When you configure attributes based on that
template, you can select a value from the list. Use the Enumeration Sets option to select any of the
enumeration sets that have already been created in your PI AF database.
• Objects
An object can be another PI AF attribute, element, or an operating system file.
2. Click in the Default Value field.
The format of the Default Value field changes according to the Value Type.
3. Configure the value for the attribute, as described in the appropriate procedure for the attribute data type.

Configure values for Basic data types

After you have set Value Type to one of the Basic data types, you can define the attribute's value.
1. Click in the Default Value field.
The format of the field changes according to the value type. See PI AF data types.
2. Enter the attribute's value in the Default Value field.
PI System Explorer resolves the data you enter and when you check in your changes, it sends the resulting
value to PI AF. For example, for DateTime, it sends the resulting date and time.
Examples
If the value type is DateTime, you can type the time in any string format that is supported by PI AF (including PI
Time formats) or the .NET DateTime object. Some examples of valid entries:
*-5d
May 12, 2009
07 06 2010 10:00:00 AM
09 14 2008 14:00:00
To create an attribute with a link as a value, select the value type String and enter the URL as the attribute value.
Strings that are recognized as absolute URL paths will be displayed as a link. For example, strings starting with
http://, ftp://, file:// and www. are recognized as links, whereas strings starting with C:\, and abc.com are not. In
PI System Explorer, links appear underlined and have an associated tooltip.

Configure values for Array data types

After you have set Value Type to one of the Array data types, you can define the attribute's value.
1. Click in the Default Value field.

2. Click beside the Default Value field.

3. In the Array window, define your array.
The Default Value field is set to the appropriate format for the data type you selected for your array
elements. See PI AF data types.
4. Click OK.
PI System Explorer resolves the data you have entered and when you check in your changes, it sends the
resulting array values to PI AF.

Configure Enumeration Set values

When you select an enumeration set for the Value Type, you can pick the value for an attribute from that set's
predefined list of constant values. For more information on enumeration sets, see Enumeration sets in PI AF.
1. Click in the Default Value field.
The Default Value field becomes a drop-down with values from the selected enumeration set.
2. Select a value from the list of predefined constants.
When you check in your changes, PI System Explorer sends the resulting value to PI AF.

Configure values for Object data types

After you have set Value Type to one of the Object data types, you then define the attribute's value.
1. Click in the Default Value field.
 The action button beside the field changes according to the selected value type.
Value Type Action

<Anything> While allowed, the Anything value type is not recommended.

Note: When the value type is unspecified, many client applications may have
difficulty working with that attribute. For example, PI OLEDB Enterprise, PI
ProcessBook, and AVEVA PI Vision would all have reduced capability with such
attributes, such as the inability to trend a value numerically. Furthermore,
standard PI AF features such as automatic UOM conversion, Formulas, and
Analytics cannot function with attributes that have no value type.

Attribute Click to open the Attribute Search window. Enter search criteria, as described
in Search for attributes on elements.
Element Click to open the Element Browser window, where you can locate and select
an element.
File Click and select Upload. Locate and select a file in the Open window. For
acceptable types of attachment files, see /FileExtensions in AFDiag utility
parameters.
Caution: Before you upload a file, run an anti-virus check and ensure that the file
size does not exceed your storage space. Some file types can pose a security risk,
and a warning message will be displayed, asking if you are sure you want to
continue. The list of file types that PI System Explorer considers unsafe can
change. As a guideline, look at Microsoft's list of file types blocked by Outlook.

2. Click OK.
When you check in your changes, PI System Explorer sends the resulting value to PI AF.

Add attribute extensions to template-based elements

The Allow Extensions check box on the General tab for the element template upon which the attribute is based
must be checked.
In some situations, you might want to add another attribute to an existing element. If the element is based on a
template that allows extensions, you can define additional attributes in the element itself independently of the
template.
1. In the Elements browser, select the element to which an attribute will be added.
2. Choose from the following actions.
▪ In the toolbar, click New Attribute.
▪ Right-click the element in the browser and click New > New Attribute.
▪ Select the Attributes tab in the viewer, right-click and click New Attribute from the context menu.
3. In the Name and Description fields, enter a unique name and a description for the attribute template.
Note: When you need to search for an attribute, you can search on up to 440 characters of a description.
4. Configure the type of value that the attribute holds:
▪ For attributes with constant values, set the attribute Value Type. This setting determines what you can
enter in the Value field.
Constant attribute values can be numbers, strings, files, date-times, Boolean, URLs, arrays, and more.
Note: While allowed, the Anything value type is not recommended. When the value type is
unspecified, many client applications may have difficulty working with that attribute. For example, PI
OLEDB Enterprise, PI ProcessBook, and AVEVA PI Vision would all have reduced capability with such
attributes, such as the inability to trend a value numerically. Furthermore, standard PI AF features
such as automatic UOM conversion, formulas, and analytics cannot function with attributes that
have no value type.
Optional. Enter or modify the default value for the attribute in the Value field.
▪ For formulas, PI point values, PI point arrays, and table data (including data from relational databases)
click Settings to configure a data reference.
See Configuration of data references for information about configuring different types of data
reference.
5. Set other configuration fields, as needed.
Field Description

Properties Select one or more of the following properties, as

needed.
• Configuration Item
• Excluded
• Hidden
• Indexed
• Manual Data Entry
For more information, see Attribute
properties.
Categories Click and select one or more previously defined
categories from the Categories window. You can also
create a new category. For more information, see
Categorization of objects.
Default UOM Select a UOM from the drop-down list. For more
information, see Units of measure in PI AF.
Note: You can change the UOM that is displayed for
the attribute in PI System Explorer; however, the
UOM defined in the template is not changed.

6. To save your work, press CTRL-S or click Check In.

Enumeration sets in PI AF
You typically use enumeration sets to establish predefined values for attribute templates. When you configure
element attributes based on those templates, you can then have users select those values from pre-populated
lists rather than typing values manually. This helps ensure you have consistent nomenclature throughout your
database.
Hierarchical enumeration values
Beginning with PI AF 2017 R2, you can nest enumeration values in a hierarchy. This can be very helpful when you
create a predefined set of reason attribute traits. You can create as many levels as you need. Each level is
designated by the | character, which you can either enter manually or by right-clicking a row and clicking New
Child Enumeration Value.
Hierarchical enumeration set example
Suppose you have an enumeration set of pump manufacturers, with child enumeration values for pump types.
Within each pump type you could also create child enumeration values for different models.
Sample hierarchy of enumeration values
When you configure the Pump attribute template, you can simply select the Pump Manufacturer enumeration
set as the Value Type, and thereby enable users to select predefined pump types and model numbers.
Sample enumeration set in attribute template
 Sort order
Beginning with PI AF 2017 R2, wherever predefined values defined by enumeration sets are displayed, users can
select Sort By > Sort By Name to sort those values by name, or Sort By > Sort By Value to sort by enumeration
set value.
Video
For information on how to create enumeration sets, watch this video:

Manage enumeration sets

Beginning with PI AF 2018 SP2, you can export digital state sets from a Data Archive to create enumeration sets.
For more information, see Review digital state sets on a Data Archive.
You use enumeration sets in attribute templates whenever you want to be able to select from lists of predefined
values when you are defining element attributes. You also use enumeration sets to create reason attribute traits
for event frames and transfers.
1. In the navigator, click Library.
2. Choose from the following actions.
To ... Do this ...

Create a new enumeration set a. Choose one of the following actions.

On
• the toolbar, click New Enumeration
Set.
In•the browser, right-click the
Enumeration Sets collection and click
New Enumeration Set.
b. In the Name field, enter a unique name for
the enumeration set.
c. Optional. In the Description field, enter a
description for the enumeration set.
d. Optional. To use hexadecimal values, select
the Hexadecimal check box.
e. Optional. If you want to configure access
permissions for the new enumeration set
that are different from those inherited
from the Enumeration Sets collection,
click the Security link. For more
information, see Configure security for
objects.
To ... Do this ...

Create a new enumeration value a. Choose one of the following actions.

In•the browser, click an existing
enumeration set. In the viewer, right-
click in any Value field and click New
Enumeration Value.
In•the browser, right-click an existing
enumeration set and click New
Enumeration Value.
The value is a unique numeric value
associated with the enumeration and
provides a quicker, less memory-
intensive representation of an
enumeration's value.
b. In the Value field of the Enumeration Value
Properties window, either enter a unique
number manually, or click to increase
or lower the value.
c. In the Name field, enter a unique string that
describes the condition or state being
represented. This string is used as the
displayed value when an enumeration set
is selected as the value type for an
attribute.
d. Optional. In the Description field, enter a
description for the enumeration value.
To ... Do this ...

Create a new child enumeration value in a. In the browser, click an existing enumeration
Enumeration Value Properties window set.
b. In the viewer, right-click an existing value to
which you want to add a child
enumeration value, and click New Child
Enumeration Value.
c. In the Enumeration Value Properties window,
verify that the value selected in the
Parent field is correct. Otherwise, select a
different parent from the list.
d. In the Value field, either enter a unique
number manually, or click to increase
or lower the value.
e. In the Name field, enter a unique string that
describes the condition or state being
represented. This string is used as the
displayed value when an enumeration set
is selected as the value type for an
attribute.
f. Optional. In the Description field, enter a
description for the enumeration value.
Create a new child enumeration value manually a. In the browser, click an existing enumeration
set.
b. In the viewer, click an empty row and enter a
unique number manually in the Value
field.
c. In the Name field:
Enter
i. the original enumeration value for
which you want to create a child
value.
Enter
ii. a | character.
Enter
iii. a unique string that represents the
child enumeration value.
d. Optional. In the Description field, enter a
description for the child enumeration
value.
 To ... Do this ...

Rename an enumeration value a. In the browser, click an existing enumeration

set.
b. In the viewer, right-click the existing value
that you want to rename and click
Properties.
c. In the Name field of the Enumeration Value
Properties window, revise the name
string as needed but ensure it remains
unique. If the name is being used as a
parent enumeration value, note that the
name change will update the parent
portion of all child enumeration value
strings.
Renumber enumeration values See Renumber enumeration values.
Delete an enumeration value a. In the browser, click an existing enumeration
set.
b. In the viewer, right-click the existing value
that you want to delete and click Delete.
c. Click Yes in response to the Delete warning.
Note that you will invalidate objects
where the value is currently being used.
3. On the toolbar, click Check In.

Renumber enumeration values

You can renumber an enumeration set although you will invalidate objects where the value is currently being
used.
1. Right-click anywhere in a field and select Renumber Enumeration Values.
The Change Enumeration Value confirmation window explains that you will invalidate objects already using
the existing enumeration set.
2. To continue, click Yes.
3. In the Starting Values field of the Renumber window, click to increase or lower the value.
4. In the Increment by field, click to select an increment value.
If you select a row before renumbering, renumbering starts at the selected row, with this row getting the
starting value and each subsequent row getting the next value of increment. Only the selected row and
following rows are changed during a renumber action. If renumbering does not start at the topmost row, a
possibility of the generated values being identical to the values above the selected row exists. The following
error message is displayed:
Attempting to change the enumeration values would overlap previous enumeration values prior to the
selected row.
Chapter 8

Configuration of data references

You can configure an attribute or attribute template to obtain a value from a specified source. This configuration
is called a data reference. Attributes that include them are called data reference attributes. You create a data
reference for the following sources:
• PI point
Produces a value from a PI point, or the summary, or other operation on the point value, depending
on how you configure it.
• PI point array
Produces a single value from an array of PI points.
• Formula
Produces a value from a calculation result. The calculation itself can include attributes, as well as
other data reference attributes.
• String builder
Produces a string value from text-manipulation functions and substitution parameters.
• Table lookup
Produces a value from:
• Internal table
• Imported value from an external (non-PI) table
• Linked value in an external table
• URI builder
Produces a dynamic link for attributes from attribute values and substitution parameters. You can
use the attribute in a notification or in a client application, such as AVEVA PI Vision.

Attribute configuration strings in PI System Explorer

An attribute configuration string describes a data reference. The syntax of a configuration string depends on the
type of data reference.
The configuration string for String Builder data references can contain substitution parameters. For attribute
templates, any configuration string can contain substitution parameters. See List of PI AF substitution
parameters.
 In PI System Explorer, when you select an attribute with a data reference, the configuration string appears in the
text box below the Settings button. You edit configuration strings directly in the text box.
The following table contains examples of configuration strings for different types of data references:

Type of data reference Sample configuration string

Formula =Density;V=Volume;[D*V]

A=Attribute3;[A*3];UOM=cm

PI Point \\MyPIDataArchiveServer\sinusoid

\\192.168.0.255\ChocMilkMeter;TimeMethod=TimeRange;
RelativeTime=-1h;TimeRangeMethod=Total;ReadOnly=False

PI Point Array \\MyPIDataArchiveServer\Point.1|Point.2|Point.3

String Builder "%Attribute% value is";'Attribute1';

Table Lookup SELECT Density FROM [Material Specifications] WHERE MaterialID

URI Builder https://MyDataServer.int:443/Vision/#Displays/215915/Mine-Truck

Temp?Asset=\\%System%\%Database%\%Element%&StartTime=03%2F21%2F
09:26:00&EndTime=&Mode=kiosk

Configuration strings for PI point data references

The attribute configuration string for PI point data references must contain the path to the point. The string can
also contain parameters that specify the value that the data reference returns. If specified in an attribute
template, the string can contain parameters that specify the point to create. In the string, you separate the
parameters with semi-colons.
Examples
• Simple reference to a point on a Data Archive server called MyPIDataArchiveServer:
\\MyPIDataArchiveServer\sinusoid
• Configuration string referencing the same point, but with a time retrieval specification and specified units of
measure:
\\MyPIDataArchiveServer\sinusoid;TimeMethod=ExactTime;UOM=°C
• Configuration string referencing the same point, but returning a total of point values over a time range:
\\MyPIDataArchiveServer\sinusoid;TimeMethod=NotSupported;
TimeRangeMethod=Total;RateConversion=day
• Configuration string from an attribute template, using substitution parameters:
\\%Server%\%Element%.%Attribute%
• Same configuration string, but with tag creation enabled and point configuration specified:
 \\%Server%\%Element%.%Attribute%;ptclassname=classic;pointtype=Float32; engunits=m3/
s;location1=1;location2=30;location4=1;location5=1;pointsource=R

Data reference parameters that specify values to return

Configuration strings for PI point data references can include optional parameters that specify the value that the
data reference returns. The following table lists available parameters:

Parameter Syntax Example Default

TimeMethod TimeMethod=time_method TimeMethod=Automatic Automatic

where time_method is one
of:
• After
• AtOrAfter
• Before
• AtOrBefore
• Automatic
• ExactTime
• Interpolated
• NotSupported
• TimeRange
• TimeRangeOverride
RelativeTime RelativeTime=[*] +|- RelativeTime=-1h N/A
integertime_unit
where time_unit is one of:
• y
• M
• d
• h
• m
• s
Parameter Syntax Example Default

TimeRangeMetho TimeRangeMethod=method_ TimeRangeMethod=Total EndTime

d name
where method_name is one
of
• Average
• Count
• Delta
• EndTime
• Maximum
• Minimum
•
PopulationStandardDev
iation
• Range
• StandardDeviation
• StartTime
• Total
TimeRangeMinPe TimeRangeMinPercentGood 80
rcentGood1 = percentage
Parameter Syntax Example Default

CalculationBasis1 CalculationBasis= TimeWeighted

calculation_basis
where calculation_basis is
one of:
• EventWeighted
•
EventWeightedExcludeE
arliestEvent
•
EventWeightedExcludeM
ostRecentEvent
•
EventWeightedIncludeB
othEnds
• TimeWeighted
•
TimeWeightedContinuou
s
• TimeWeightedDiscrete

RateConversion2 RateConversion=uom RateConversion=minute day

where uom is a defined unit
of measure
UOM UOM=uom UOM=°C Attribute's Default UOM
where uom is a defined unit
of measure
ReadOnly ReadOnly=boolean ReadOnly=false true
where boolean is one of:
• true
• false
1 Used when specifying TimeRangeMethod.
2 Used only when TimeRangeMethod=Total.

Data reference parameters that specify PI point to create

In attribute templates that specify new PI points, configuration strings for PI point data references include
parameters that specify the type of point to create. Point creation parameters consist of a point attribute and
value. To specify a new PI point, attribute templates must include the pointtype attribute as a parameter; other
attributes are optional.
 • Create a PI point of type Float64 and use default settings for the rest of the point configuration:
\\%Server%\%Element%.%Attribute%;pointtype=Float64
• Create a PI point that sets the point attributes shown in the following table:
Point attribute Setting

ptclassname classic

pointtype Float32

pointsource R

location4 1

location5 2

span 200

zero 1100
\\%Server%\%Element%.%Attribute%;ptclassname=classic;pointtype=Float32;
location4=1;location5=2;pointsource=R;span=200;zero=1100

Path syntax for references to other attributes

To reference other attributes, you use paths that locate attributes on the server, database, and elements in
which they reside.
• Use an absolute path to specify the actual server, database, and element where an attribute is located. For
example:
\\MyPIDataArchive\MyAFDatabase\MyElement|Attribute1
• Use a relative path to identify an attribute based on its name and its place in the hierarchy of elements and
attributes. For example:
..\Element2|Attribute1
Components of a path
A path is comprised of parts, with each part representing an object or list of objects. Each part of the path is
typically separated as follows: by a single backslash (\), with the following exceptions:
• PI AF attributes and PI AF attribute templates are preceded by the pipe character (|).
• The Data Archive is preceded by two backslashes (\\).
You can specify a Data Archive and a database by name or by globally unique identifier (GUID). A GUID is a
unique 128-bit number produced by Windows to identify a particular component, application, file, or database
entry. GUIDs must be specified within curly brackets ({ and }). For example:
\\{5c64c379-c182-4f35-8d30-78d8c2f84502}\{5c64c379-c182-4f35-8d30-78d8c2f84503}
If you specify both the name and GUID, separate them with a semicolon (;). The first one specified takes
precedence in the search, so in the following example, the GUID takes precedence:
\\{5c64c379-c182-4f35-8d30-78d8c2f84502};MySystem\{5c64c379-
c182-4f35-8d30-78d8c2f84503};MyDatabase
Path syntax for Data Archive computers
To indicate a fully qualified path from the Data Archive, start the path with two backslashes (\\) followed by the
Data Archive.
To indicate the current system, start a relative path with two backslashes followed by a period (\\.). For example,
to reference a database called Database2 in the current system, type:
\\.\Database2
To specify a collection of PI Data Archives, use the following format:
\\PIDataArchives[MyPIDataArchiveName]

Path syntax for PI AF databases

The PI AF database follows the Data Archive specification.
You can start a relative path with a single backslash (\) to indicate the current database. For example, the
following paths reference objects in the current database:
\Element2
\Tables[MyTable]
Note: You can access non-database objects external to the PI System. You must identify the collection, as
demonstrated by the following example:
\\MySystem\Contacts[JSmith]

Syntax for relative paths

Use a double period (..) to indicate the parent object. The following example references Attribute1 of Element2
that is in the current database:
..\Element2|Attribute1
The single period (.) represents the current object. You can use it to create a relative path from the current
object.
• When the current object is a PI AF attribute, a single period followed by a backslash (.\) represents the
owning PI AF element. For example:
.\|Attribute1
• A single period followed by a vertical bar (.|) references a child PI AF attribute, for example:
.|Attribute1|Attribute2
• When the current object is a PI AF element, a relative path is created from the database, for example:
\Element1\Element2|Attribute1

Examples of references to attributes of the same element

To reference an attribute that belongs to the same element, you can:
• Identify the attribute relative to its top-level ancestor attribute.
• Identify the attribute relative to the current attribute (the attribute for which you are configuring the data
reference).
The following examples refer to the above illustration.

Type of reference To reference this attribute From this attribute

Parent attribute Level Average

Grandparent attribute Level Interval

Parent attribute Average Interval

Sibling attribute Average Minimum

Child attribute Average Level

Grandchild attribute Interval Level

Top level attribute Temperature Any attribute

Full path from top-level ancestor
To reference any attribute from another attribute belonging to the same element, you can specify that attribute's
entire path from the element. Start the path with the pipe symbol (|) and use the pipe symbol to separate
attribute levels.
In the above illustration, the top-level ancestor of the Interval attribute is Level. To reference the Interval
attribute from any other attribute of the same element, type:
|Level|Average|Interval
To reference any top-level attribute from any other attribute of the same element, type the pipe symbol followed
by the attribute name. For example, to reference the Level attribute from anywhere, type:
|Level
To reference the Temperature attribute from anywhere, type:
|Temperature
Sibling attributes
To specify a sibling, simply use the name of the sibling attribute. No other notation is usually required, but
because the PI Point data reference requires some attribute path characters to differentiate this reference from a
PI Point reference, use the full attribute path from the element.
In the illustration shown above, the Maximum and Minimum attributes are siblings. To reference the Maximum
attribute when configuring the Minimum attribute, you would type:
Maximum
Parent and grandparent attributes
You use two periods (..) to move up the attribute hierarchy. For example, to specify the parent attribute, you
would use:
..
You can use this notation to move up the attribute's ancestor elements. For example, to reference the
grandparent attribute, you would use:
..|..
In the illustration shown above, to reference the Level attribute from the Average attribute, type:
..
Because Level is the top-level parent attribute, you could type instead:
|Level
You cannot use this notation to reference the Temperature attribute from the Average attribute, because
Average is not a descendent of Temperature. Furthermore, you cannot use this notation to reference the
Average attribute from the Interval attribute, because Average is not at the top level of the attribute hierarchy.
To reference the Level attribute from the Interval attribute, type:
..|..
You cannot use this notation to reference the Maximum attribute from the Interval attribute, because the
Interval attribute is not a descendant of the Maximum attribute. In this case, you need to use a complete path:
|Level|Maximum
Similarly, to reference the Temperature attribute from the Interval attribute, use
|Temperature
Descendant attributes
To reference a child attribute, you use a period (.), which indicates "this attribute", followed by a path.
In the illustration shown above, to reference the Average attribute from the Level attribute, type:
.|Average
To reference the Interval attribute from the Level attribute, type:
.|Average|Interval
You cannot use this notation to reference the Interval attribute from the Temperature attribute, because the
Interval attribute is not a descendant of the Temperature attribute. In this case, you need to use a full path:
|Level|Average|Interval

Examples of references to attributes of different elements

You can reference attributes that belong to different elements in the following ways:
• Directly from the top of the element hierarchy in the database.
• Specify the parent element of the target attribute using a relative path.
Attributes relative to database
To reference an attribute based on a path relative to the root of the PI AF database, specify the entire element
and attributes path from the database. Start the path with a backslash (\), and use the backslash to separate
element levels. Precede the attribute with the pipe symbol (|). For example:
\Reactors\React1|pressure
This example assumes that the Reactors element is at the top level of the element hierarchy. You can always use
this notation to reference an attribute relative to the top level of elements in the database.
For example, suppose you have the element hierarchy shown in the following illustration:

Assume you want to reference an attribute called pressure, belonging to the NewTank element. You can type:
\Tanks\Tank1\NewTank|pressure
If you want to represent a child attribute of pressure called temp, the reference is:
\Tanks\Tank1\NewTank|pressure|temp
Attributes relative to containing element
You can reference attributes relative to the containing element of the attribute that you are configuring. Use
backslashes (\) to move down the element hierarchy and .. to move up the element hierarchy.
In the above illustration, each element (Tank1, Tank2, Tank3, and NewTank) has a pressure attribute:
These examples demonstrate the syntax to:
• Reference a sibling element:
To refer to the Tank2 attribute pressure from Tank1, type:
..\Tank2|pressure
• Reference a parent element:
To refer to the Tank1 attribute pressure from NewTank, type:
..\|pressure
• Reference a child element:
To refer to the NewTank attribute pressure from Tank1, type:
.\NewTank|pressure
Path syntax for dynamic objects
Paths to dynamic objects are also supported. To create a PI point array attribute with Sinusoid and Sinusoidu
values, for example:
PI Point Array.\\piserver2\sinusoid|sinusoidu
If a path is to a PI point, a dynamic attribute is created. To create an attribute with the data reference configured
to read values from the PI point Sinusoid, for example:
\\piserver2\sinusoid

Path syntax for collection types

Each parent object has a default collection type. For example, a Data Archive has a default collection of
databases, and a PI AF database has a default collection of elements.
Use a single period enclosed in square brackets ([.]) to represent the default object of the parent object. The
following example refers to Element1 of the default database in the current system:
\\.\Databases[.]\Element1

Path syntax for filters

A collection filter starts with the at sign (@) followed by the filter name. Supported filters are: @Category,
@Description, @Index, @Name, @ReferenceType, @Template, @Trait, @Type, and @UOM.
You must enclose the filter specification in square brackets ([ and ]).
You can also specify multiple filters; they are evaluated in the order specified. For example:
\\MySystem\MyDatabase\Elements[@Template=Tank][@Category=Tutorial]|
Attributes[@Category=Tutorial]
Category filter example
The following example returns the Volume attribute from all elements in the category, Tutorial, that belong to
the database called MyDatabase:
\\MySystem\Databases[MyDatabase]\Elements[@Category=Tutorial]|Volume
Type filter example
The following example returns the attributes of Element1 that are of Int32 type:
\Element1|Attributes[@Type=System.Int32]
Unit of measure filter example
The following example returns the attributes of Element1 that have meters as their unit of measure:
\Element1|Attributes[@UOM=meter]
Index filter example
Use the index filter [@Index=int] or [int] to specify the position of the matched object to return (the first item is
at index position 1). The index filter must be the last filter specified. The following example returns the third
database in the collection of PI AF databases in the current system:
\\Systems[MySystem]\Databases[@Index=3]
Beginning with PI AF 2017, you can use a negative number for an index from the end of the collection (for
example -1 indicates the last item, -2 indicates the penultimate item).
\Element#1\Elements[@Name=Tank*][@Index=-3]
The index filter name is optional if another filter is specified before the index filter. For example:
 \Element#1\Elements[@Name=Tank*][3]

Wildcard characters in Name filters

You can place a wildcard asterisk (*) character in the name of any object to match zero or more characters.
Note: To match a literal asterisk, use a preceding backslash ( \*).
Examples
\\MySystem\MyDatabase\[@Name=E*]
\\MySystem\MyDatabase\Elements[@Name=E*][@Index=3]

Substitution parameters in data references

Substitution parameters are variables that you place in attribute templates for data references such as PI point,
String Builder, and URI Builder. PI AF resolves the substitution parameters when it creates the data reference for
an attribute based on that template. For example, you can use substitution parameters:
• To configure a PI point data reference template to use names for tags based on element names built from
that template.
• To use the value of a different attribute in the configuration of a PI point property value.
Videos
For information on how to use substitution parameters in templates, watch this video:
For information on how to use substitution parameters as you create PI points, watch this video:

Symbols used in substitution parameters

Use the symbols in the following table to build a substitution parameter.

Symbol Description Examples

%…% Considers the expression as a %Element%

substitution parameter.
%Attribute%
. Current element or attribute. Use .\ %.\ChildElement|Attribute%
to navigate down from current
element. Use .| to navigate to child
attributes of the current attribute.
.. Navigates a level up. %..\..\Element%
%..|Attribute%
\ Separates components of a path, %..\Element%
except attributes.
| Separates attributes in a path. %..|Attribute%
 Symbol Description Examples

@ References the value of the object • Attribute value at same level as attribute:
instead of its name.
• %@Attribute%
Note: Only PI point data references • Attribute value at root level of same element:
use attribute value substitution
syntax. Other data references, such • %@|Attribute%
as formula, table lookup, and String • Attribute value at parent attribute level:
Builder have a simpler syntax for
referencing attribute values. • %@..|Attribute%
• Attribute value at parent element level:
• %@..\|Attribute%
• Attribute value of child attribute of same
element:
• %@.|Attribute%
• Attribute value of child element attribute:
• %@.\ChildElement\ChildOfChild|Attribute%
• Attribute value of primary element of event
frame:
• %@.\Elements[.]|Attribute%

Name substitutions
When you use a name substitution, PI AF performs a direct substitution of the substitution parameter for
whatever that particular parameter represents.
The table in List of PI AF substitution parameters lists the available substitution parameters and what they
represent. For example, %Element% is a substitution parameter that represents the element name. After you
create an element based on that template, you tell PI AF to create the data reference (Attribute-value updates
from PI point data references). When PI AF creates the reference, it substitutes the current element name
wherever the configuration says %Element%.
Suppose you have a data reference template that references the PI point name:
%Element%_TT
You create an element named Tank1 that is based on that template. The attribute data reference points to a PI
point named:
Tank1_TT

References to attribute values

When configuring a PI point data reference attribute, you can use substitution parameters to reference the value
of another attribute. You can use attribute value references to specify a value in the Relative Time field or in the
point attribute configuration for automatically-generated PI points. The syntax is:
%@AttributeName%
 where AttributeName is the name of the attribute. The @ indicates to substitute the value of the indicated
attribute, rather than its name. To reference an attribute that is not a sibling of the current attribute, use the
syntax described in Indirect PI point references to define the path to the desired attribute.
PI AF does not update the attribute value over time. When a substitution is used in the tag name, the value is
resolved only at the time the data reference is loaded. If a substitution parameter is used to define point
attributes, PI AF uses the value of the attribute at the exact time that you created or updated the data reference
(see Attribute-value updates from PI point data references for more information). This value is a constant. PI AF
does not evaluate that attribute value again, unless you update the data reference.
Note: The exception to this rule is a value substitution for the Relative Time, which is evaluated on every value
call to the PI point data reference (see Create ranges of configurable durations).

List of PI AF substitution parameters

PI AF interprets numerous types of substitution parameters. The following tables are grouped by type:
• Name
• Time
• ID
• Description
• Path
• Environment variable
Name substitution parameters
The following table lists the name substitution parameters that supports.

Parameter name Substitution

%@path% The value of the object's attribute or attribute template, represented by

the path.
%Analysis% Name of analysis, if obtainable from the context.
%Attribute% Name of the object's attribute or attribute template.
%|Attribute% Name of the root attribute or attribute template that holds this data
reference.
%..|Attribute% Name of the parent attribute or attribute template that holds this data
reference.
%Database% Name of the PI AF database in which the attribute resides.
%Destination% Name of the destination element for the transfer in which the attribute
resides.
%Element% Name of the element in which the attribute resides. For event frames,
this refers to the name of the primary-referenced element.
%\Element% Name of the root element in which the attribute resides.
Parameter name Substitution

%..\Element% Name of the parent element of the element in which the attribute
resides. To retrieve further ancestors, use the ..\ notation, such as
%..\..\Element%.
%EventFrame% Name of the event frame in which the attribute resides.
%\EventFrame% Name of the root event frame in which the attribute resides.
%..\EventFrame% Name of the parent event frame of the event frame in which the
attribute resides. To retrieve further ancestors, use the ..\ notation,
such as %..\..\EventFrame%.
%Model% Name of the model, if obtainable from the context.
%Name:path% Name of the object represented by the path to the object. If the path is
not specified, null is returned since the name of the current object is
being referenced.
%Server% Name of the default Data Archive. It first resolves to the current PI AF
database's default Data Archive if one is specified; otherwise, it resolves
to the PI AF server's default Data Archive if one is specified. If one is not
specified there, it resolves to the local default Data Archive.
Note: If the default Data Archive is not specified on the PI AF server or
PI AF database, it can resolve to a different Data Archive for different
client machines depending on their configuration.

%Source% Name of the source element for the transfer in which the attribute
resides.
%System% Name of the PI AF server or collective where the attribute resides.
%Template% Name of the template on which the element or event frame is based.
For example, if you created element Valve101 from a template called
Valve, then the substitute text would be Valve.
%\Template% Name of the root template on which the element or event frame is
based.
%..\Template% Name of the parent template on which the element or event frame is
based. To retrieve further ancestors, use the ..\ notation, such as
%..\..\Template%.
%Transfer% Name of the transfer in which the attribute resides.
Time substitution parameters
PI AF supports substitution parameters that specify a particular time and time zone, depending on the context.
Optionally, you can augment these supported parameters by including a format string that specifies the format
of the time string. See Format strings for time substitution parameters.
The following table lists the time substitution parameters that supports.
Parameter name Substitution

%Duration% Time span between the start time and end time, if it can be obtained
from the time context. In open event frames, obtains the time span
from start time to the current time. The time span uses a different
format from other time substitution parameters.
• You can use standard formats such as "c" (constant), "g" (general,
short), or "G" (general, long), for example: %Duration:c%. For more
information, see the MSDN article Standard TimeSpan Format
Strings.
• You can also use a custom time span format, as described in the
MSDN article Custom TimeSpan Format Strings.
Note that you need to define the symbols that separate days from
hours, and so on with a string literal. For example,
%Duration:d\.hh\:mm\:ss% defines a period (.) as the separator
between days and hours, and a colon (:) as the separator between
hours, minutes, and seconds.
%EndTime% Local end time, if obtainable from the time context. For event frame-
based objects that do not have an end time yet specified, the result is
an empty string.
%StartTime% Local start time, if obtainable from the time context.
%Time% Local time, if obtainable from the time context.
%UtcEndTime% Coordinated universal (UTC) end time, if it can be obtained from the
time context. For event frame-based objects that do not have an end
time yet specified, the result is an empty string.
%UtcStartTime% Coordinated universal (UTC) start time, if it can be obtained from the
time context.
%UtcTime% Coordinated universal (UTC) time, if it can be obtained from the time
context.
ID substitution parameters
The following table lists the ID substitution parameters that supports.

Parameter name Substitution

%AnalysisId% ID of the analysis with which the attribute is associated.

%AttributeId% ID of the attribute that holds this data reference.
%|AttributeId% ID of the root attribute or root attribute template in which the attribute
resides.
Parameter name Substitution

%..|AttributeId% ID of the parent attribute or parent attribute template in which the

attribute resides. Further ancestors can be retrieved by using the ..|
notation, such as %..|..|AttributeId%.
%DatabaseId% ID of the database in which the attribute resides.

%ElementId% ID of the element in which the attribute resides. For event frames, this
refers to the ID of the primary referenced element.
%\ElementId% ID of the root element in which the attribute resides. For event frames,
this refers to the ID of the primary referenced element of the root event
frame in which the attribute resides.
%..\ElementId% ID of the parent element in which the attribute resides. For event
frames, this refers to the ID of the primary referenced element of the
parent event frame in which the attribute resides. Further ancestors can
be retrieved by using the ..\ notation, such as %..\..\ElementId%.
%EventFrameId% ID of the event frame in which the attribute resides.

%\EventFrameId% ID of the root event frame in which the attribute resides.

%..\EventFrameId% ID of the parent event frame in which the attribute resides. Further
ancestors can be retrieved by using the ..\ notation, such as
%..\..\EventFrameId%.
%Id:path% ID of the object represented by the path to the object. If the path is not
specified, the ID of the current object is used. .
%ModelId% ID of the model in which the attribute resides.

%SystemId% ID of the PI AF server in which the attribute resides.

%TransferId% ID of the transfer in which the attribute resides.

Description substitution parameters

The following table lists the description substitution parameters that supports.

Parameter name Substitution

%Description:path% Description of the attribute represented by the path to the attribute.

If the path is not specified, the description of the current attribute is
used.
%|Description% Description of the root attribute or root attribute template in which
the attribute resides.
Parameter name Substitution

%..|Description% Description of the parent attribute or parent attribute template in

which the attribute resides. Further ancestors can be retrieved by
using the ..| notation, such as %..|..|Description%.
%ElementDescription% Description of the element in which the attribute resides. For event
frames, this refers to the description of the primary referenced
element of the event frame in which the attribute resides.
%\ElementDescription% Description of the root element where the attribute resides. For
event frames, this refers to the description of the primary referenced
element of the root event frame in which the attribute resides.
%..\ElementDescription% Description of the parent element in which the attribute resides. For
event frames, this refers to the description of the primary referenced
element of the parent event frame in which the attribute resides.
Further ancestors can be retrieved by using the ..\ notation, such as
%..\..\ElementDescription%.
%EventFrameDescription% Description of the event frame in which the attribute resides.

%\EventFrameDescription% Description of the root event frame in which the attribute resides.

%..\EventFrameDescription% Description of the parent event frame in which the attribute resides.
Further ancestors can be retrieved by using the ..\ notation, such as
%..\..\EventFrameDescription%.
Path substitution parameters
Path substitutions cannot generally be used to create references to other attributes, because they contain
backslash characters. The Path substitution parameters are most useful with String Builder data references when
you construct paths for output into strings. The path that is produced does not include the PI AF server or
database.
The following table lists the path substitution parameters that supports.

Parameter name Substitution

%ElementPath% Path of the base element, the element of an attribute, or the primary
referenced element of an event frame.
%..\ElementPath% Path of the parent element in which the attribute resides. For event
frames, this refers to the path of the primary referenced element of the
parent event frame in which the attribute resides. Further ancestors can
be retrieved by using the ..\ notation, such as %..\..\ElementPath%.
%EventFramePath% Path of the event frame, or the element of an attribute of an event
frame.
 Parameter name Substitution

%..\EventFramePath% Path of the parent event frame in which the attribute resides. Further
ancestors can be retrieved by using the ..\ notation, such as
%..\..\EventFramePath%.
Environment variable parameter
The following table lists the environment variable parameter that supports.

Parameter name Substitution

%Environment Variable% Value of the matching system-environment variable. For example,

%COMPUTERNAME% is replaced with the name of the computer on
which the data reference is executing.

Format strings for time substitution parameters

In time substitution parameters, you can include a format string that specifies the format of the time string.
Standard date and time format
Use any standard format string supported by the DateTime.ToString method, described in the MSDN article
Standard Date and Time Format Strings. In the specification of the time substitution parameter, separate the
substitution and the format string with a colon. For example, %TIME:d% specifies the local time in a short-date
pattern.
The following table provides an abbreviated description of DateTime format strings:

Format specifier Description Example

d Short date pattern 6/15/2009 (en-US)

15/06/2009 (fr-FR)
2009/06/15 (ja-JP)
D Long date pattern Monday, June 15, 2009 (en-US)
Montag, 15. Juni 2009 (de-DE)
f Full date/time pattern (short time) Monday, June 15, 2009 1:45 PM (en-US)
F Full date/time pattern (long time) Monday, June 15, 2009 1:45:30 PM (en-US)
g General date/time pattern (short time) 6/15/2009 1:45 PM (en-US)
15/06/2009 13:45 (es-ES)
2009/6/15 13:45 (zh-CN)
G General date/time pattern (long time) 6/15/2009 1:45:30 PM (en-US)
15/06/2009 13:45:30 (es-ES)
2009/6/15 13:45:30 (zh-CN)
 Format specifier Description Example

M, m Month/day pattern June 15 (en-US)

O, o Round-trip date/time pattern 2009-06-15T13:45:30.0000000-07:00
R, r RFC1123 pattern Mon, 15 Jun 2009 20:45:30 GMT
s Sortable date/time pattern 2009-06-15T13:45:30
t Short time pattern 1:45 PM (en-US)
T Long time pattern 1:45:30 PM (en-US)
u Universal sortable date/time pattern 2009-06-15 20:45:30Z
U Universal full date/time pattern Monday, June 15, 2009 8:45:30 PM (en-US)
Y, y Year month pattern June, 2009 (en-US)
Any other single Unknown specifier
character
Custom date and time format
You can also construct custom patterns in the date and time format string, using time specifiers described in the
MSDN article Custom Date and Time Format Strings. For example, %TIME:yyyy/MM/dd HH:mm:ss.ffffff%
produces output similar to 2015/03/31 09:28:03.843512.

Find the default Data Archive server

You can now specify the Data Archive, also referred to as the default data server, for the PI system and PI AF
database. By default, PI AF databases inherit the PI AF server's local default data server.
Note: The %Server% parameter defines the default Data Archive. It first resolves to the current PI AF database's
default Data Archive if one is specified; otherwise, it resolves to the PI AF server's default Data Archive. If one is
not specified there, it resolves to the local default Data Archive. If the default Data Archive is not specified on the
PI AF server or PI AF database, it can resolve to a different Data Archive configured for each one depending on
the different client machines' settings.
Choose from the following actions:

To … Do this …

View the default data server for the current database a. On the PI System Explorer toolbar, click
.
b. In the Select Database window, click
Database Properties.
c. Locate the Default Data Server field on the
General page to view the default data
server.
d. Click OK twice.
 To … Do this …

View the default data server settings for the system a. Click on the PI System Explorer toolbar, or
click File > Server Properties.
b. Locate the Default Data Server field on the
General page to see the default data
server for the PI system.
c. Click OK.
View the name of the default data server a. From the PI System Explorer menu bar,
choose File > Connections.
b. Locate the icon to identify the default
Data Archive data server.
c. Click Close.

PI point data references

A PI point data reference is a reference from a PI AF attribute to a PI point. The value of the data reference
attribute can be the same as the point value, or it can be the result of a calculation based on point values. You
can create a PI point data reference for:
• An element attribute or an element attribute template
• A transfer attribute or a transfer attribute template
• An event frame attribute or an event frame attribute template
A PI point data reference for an attribute template has additional features. When you create a PI point data
reference in an attribute template, you can:
• Automatically create tags referenced by attributes based on the template.
• Create a naming scheme for attributes based on the template so that attributes built from it have unique
names that conform to a consistent structure.
To reference the PI point, you use a direct or an indirect reference. There are two quick methods to create a
direct reference, whereas you need to use the PI Point Data Reference window to create a more complex direct
reference or an indirect reference.
Videos
For information on how to set up PI point data references, watch this video:
For information on UOMs in PI point data references, watch this video:

Direct PI point references

In the configuration string, a direct point reference uses two backslashes (\\) to reference a PI point on a Data
Archive. For example, the following configuration string references the sinusoid point on a Data Archive called
MyPIServer:
\\MyPIServer\sinusoid
 For attribute templates, you can also use substitution parameters in the reference. For example, the following
configuration string references the sinusoid point on the default Data Archive of the PI AF database for the
attribute:
\\%Server%\sinusoid
For more information on substitution parameters, see Substitution parameters in data references.

Indirect PI point references

You can configure a PI point data reference to point at another attribute. The referenced attribute must itself be
a PI point data reference. This is called an indirect reference to whatever PI point the target attribute references.
It makes sense to reference by attribute when you need multiple attributes that each use data from the same PI
point.
For example, suppose you have an attribute called Level that references a PI point registering a tank level. You
want three child attributes to hold the daily average, minimum, and maximum tank levels. If you configure the
three child attributes to reference the Level attribute, you can later change the Level attribute to reference a
different point and you do not have to reconfigure child attributes. Used in combination with templates, this
significantly reduces the amount of configuration required per element instance.

Relative paths
To reference another attribute, the configuration string uses a relative path. The relative path identifies a data
reference attribute based on its name and its place in the hierarchy of elements and attributes. For the PI point
data reference, the path must include an attribute path designation (| or ..) in the configuration string so that it
is distinguished from a PI point reference.
The following table shows typical configurations for indirect references:

Object Syntax Example

Top level attribute of |topLevelAttribute See "Full path from top-level ancestor" in
same element Examples of references to attributes of the
same element.
Parent attribute .. See "Parents and grandparent attributes"
in Examples of references to attributes of
the same element.
Child attribute .|childAttribute See "Descendant attributes" in Examples
of references to attributes of the same
element.
 Object Syntax Example

Sibling attribute ..|siblingAttribute See "Sibling attributes" in Examples of

(when not a top level references to attributes of the same
attribute) element.
From event frame to .\Elements[.]|Attribute See Data references to attributes in the
primary element primary referenced element.
From event frame to .\Elements[.]\..\|Attribute See "Examples that use relative paths" in
attribute of parent Data references to attributes in other
element elements.
From event frame to .\Elements[.]\ChildElementName| See "Examples that use relative paths" in
attribute of child Attribute Data references to attributes in other
element elements.
Database path \TopLevelElement|myAttribute See "Attributes relative to database" in
Examples of references to attributes of
different elements.
Full path \\myServer\myDatabase\myElement| See Path syntax for references to other
myAttribute attributes.

Create direct PI point data references from Tag Search results

You can drag a PI point from Tag Search results in the palette to set the name, description (if the PI point has a
descriptor), and type of a PI point data reference. If the engineering units property of the PI point matches an
existing unit of measure, including case, the Default UOM field is also set.
1. To configure a PI point data reference:
▪ In the Elements browser, select the desired element.
▪ In an element template, select the desired element template in the Library browser.
2. In the Attribute or Attribute Templates tab, select the attribute.
3. Select View > Palette > Tag Search, or press CTRL+SHIFT+8.
4. In the Tag Search window, create a search query to retrieve the PI points you want to use as data references.
For more information on searching for PI points, see Search for PI points and Syntax for PI point searches.
5. Do one of the following:
▪ To create a new attribute, drag a PI point from search results onto the Attributes grid. A new attribute
configured as a data reference based on the PI point is added to the grid.
▪ To configure an existing attribute, select the attribute in the viewer and drag a PI point from search
results to the attribute Settings field to configure the attribute as a data reference based on the PI point.
6. Click Check In to save the data reference.

Configure direct or indirect PI point data references

Use the PI Point Data Reference window to configure PI point data references on element attributes.
1. From the Attributes tab in the viewer, select an attribute.
2. In the attribute configuration section, select PI Point from the Data Reference list.
3. Click Settings.
Note: You can click in the Settings field and enter a tag name to create a direct PI point data reference in \
\serverName\tagname format. PI System Explorer retrieves the tag name from the default Data Archive. For
example, if you enter sinusoid, the PI point data reference displays \\yourDefaultDataArchive\sinusoid.
4. In the PI Point Data Reference window, choose from the following actions to create the data reference.
To ... Do this ...

Create a direct PI point data reference a. Leave the default server, or choose a
different Data Archive from the Data
server list.
Note: If the desired Data Archive does not
appear in the list, click and select a
Data Archive from the PI Data Archives
window.
b. In the Tag name field, type the point name,
or click to search for a point on the
selected Data Archive.
Tip: You can enter a substitution parameter
instead of the tag name. If you are
creating a reference in an attribute
template, you can use substitution
parameters in both the Data server and
Tag name fields. See List of PI AF
substitution parameters.

Create an indirect PI point data reference a. Choose the Attribute option.

b. Type a relative path to the attribute, or
choose one from the drop-down list of
attributes that have PI Point data
references.
To type in a path, use the syntax described in
Indirect PI point references. The attribute
that is referenced must also have a PI
point data reference.
5. Optional. Specify the units that the referenced PI point uses. See Unit of measure considerations.
Note: For time weighted totals on referenced PI Point data reference attributes, ensure that you select a
UOM from the Source Units list that matches the UOM of the source attribute. Even if the default source
units appear to match the UOM of the source attribute, do not select <Default> but instead select the
appropriate hardcoded UOM from the list.
 6. In the Value retrieval methods section, specify how the attribute gets its value. For example, the attribute
value could be the same as the point value, or it could be a result of a calculation on the point value. See
Configuration of retrieval methods for attribute values.
7. Use the Read Only check box to specify whether you want PI AF to write the attribute value back to the
source point. By default, PI AF does not write data to the referenced PI point (the Read Only check box is
checked). See PI point value updates from a data reference.

References to attribute values

When configuring a PI point data reference attribute, you can use substitution parameters to reference the value
of another attribute. You can use attribute value references to specify a value in the Relative Time field or in the
point attribute configuration for automatically-generated PI points. The syntax is:
%@AttributeName%
where AttributeName is the name of the attribute. The @ indicates to substitute the value of the indicated
attribute, rather than its name. To reference an attribute that is not a sibling of the current attribute, use the
syntax described in Indirect PI point references to define the path to the desired attribute.
PI AF does not update the attribute value over time. When a substitution is used in the tag name, the value is
resolved only at the time the data reference is loaded. If a substitution parameter is used to define point
attributes, PI AF uses the value of the attribute at the exact time that you created or updated the data reference
(see Attribute-value updates from PI point data references for more information). This value is a constant. PI AF
does not evaluate that attribute value again, unless you update the data reference.
Note: The exception to this rule is a value substitution for the Relative Time, which is evaluated on every value
call to the PI point data reference (see Create ranges of configurable durations).

Unit of measure considerations

When you define a PI point data reference you can optionally specify the units that the referenced PI point uses.
If possible, PI AF automatically changes the attribute type to a value type that is compatible with the specified
units.
However, if the attribute is defined by an attribute template, PI AF cannot change the type. Instead, PI AF
attempts to convert the value to the template’s value type. If PI AF cannot convert the value, it generates an
error.

Configuration of retrieval methods for attribute values

Client applications request attribute values for a specific time or for a time range. For example, in PI
ProcessBook, the display can optionally provide a time range context (a time range symbol, such as a trend, must
be present on the display to enable reception of a time range). You typically configure the data reference to
expect either a time or a time range. The attribute value will then be either:
• The value of the point at a specific time. See Configure value retrieval by time.
• The result of a calculation on the point's values over a time range. See Configure value retrieval by time
range. For example, the attribute value could be the average of the point values over an hour.
Videos
For information on how to retrieve aggregate values in PI point data references, watch this video:
For information on how to retrieve a single value in a PI point data reference, offset by a time period, watch this
video:

Relative time
Relative time expressions are some number of a number of days (d), hours (h), minutes (m), or seconds (s),
specified with either a leading plus sign (+) or a leading minus sign (-). The Relative time field in the PI Point Data
Reference window shifts the time context by the specified offset. For example, if a client requests an attribute
value at the current time where the relative time expression is -8h, PI AF returns data from eight hours before
the current time.
Fractional times are supported. For example, use -1.5d to indicate one and one-half days.
Relative time expressions can contain only one operator, either + or -. For example, the following is not
supported:
-1d+1h
The following are all valid relative times:
+1d
-24h
-3.25m
+24s

Time retrieval options

The following table describes the available options for the By Time value-retrieval method in the PI Point Data
Reference window.

Option Description

After Returns the first recorded value after the time requested by the client
application.
At or After Returns a recorded value at the time requested by the client application. If no
value exists at the specified time, returns the next recorded value.
At or Before Returns a recorded value at the time requested by the client application. If no
value exists at the specified time, returns the previous recorded value.
Automatic A continuous point (step attribute = 0) is treated as Interpolated, whereas a
discrete point (step attribute = 1) is treated as At or Before.
Before Returns the first recorded value before the time requested by the client
application.
Exact Time Returns a recorded value at the time requested by the client application. If no
recorded value exists at that time, an error is returned.
Interpolated Returns an interpolated value for the time requested by the client application.
Discrete points (step attribute = 1) carry the previous value forward.
Not Supported Used in time range calculations only. If the client application sends a time
instead of a time range, PI AF returns an error message as the attribute value.
Option Description

Time Range Used in time range calculations only. Creates a default time range to use if the
client application sends a time instead of a time range. If you choose this option,
you must type a PI relative time expression in the Relative Time field. See Create
default time ranges for element attributes for details.
Time Range Override Used in time range calculations only. Specifies a time range that always overrides
the time range supplied by the client application. You can specify:
• A fixed duration, as described in Create ranges of configurable durations.
• A dynamically calculated duration, as described in Configure dynamic time
range calculations.

Range retrieval options

The following table describes the available options for the By Time Range value-retrieval method in the PI Point
Data Reference window.

Option Description

Average Returns the average value over the time range.

Count Returns the event count over the time range, when Calculation Basis is set to
Event Weighted. Returns the sum of event time duration over the time range,
when Calculation Basis is set to any of the time weighted options.
Delta Returns the difference in value from the end of the time range to the start of the
time range.
End Time Returns the value at the end of the time range.
Maximum Returns the maximum value over the time range.
Note: The timestamp value displays the time that the maximum value occurred.

Minimum Returns the minimum value over the time range.

Note: The timestamp value displays the time that the minimum value occurred.

Population Standard Returns the population standard deviation over the time range.
Deviation
Range Returns the range of values over the time range (Maximum-Minimum)
Standard Deviation Returns the standard deviation over the time range.
Start Time Returns the value at the start time of the time range.
Total Returns a totalization over the time range.
Configure value retrieval by time
A client application request for an attribute value includes a time. Specify how to interpret that time to retrieve
values for the attribute.
1. Select an option from the By Time list. The default option is Automatic. For more information, see Time
retrieval options.
2. Optional. If an attribute is configured to return the value at a specific time, you can configure a time delay
from the time requested. This can be useful when you are creating dead-time delayed attributes.
In the Relative Time field, type the relative time of the delay. Use a PI relative time expression, as described
in Relative time.
Note: You can also use substitution parameters to read the relative time from the value of another attribute,
as described in References to attribute values, References to attribute values.
3. Select an option from the By Time Range list. The default option is End Time. For more information, see
Range retrieval options.
4. Click OK.

Configure value retrieval by time range

If you want the attribute value to be the result of a summary calculation over a time range, configure the value
retrieval by time range.
1. Select an option from the By Time list. The default option is Automatic. For more information, see Time
retrieval options.
2. Select an option from the By Time Range list. The default option is End Time. For more information, see
Range retrieval options.
3. If the Calculation Basis list is enabled, select one of the following options.
Note: If you select one of the time weighted options for a totalization, source units convert to a rate. Select a
unit of time from the list next to the Source Units field.
Option Description

Event Weighted Evaluates values with equal weighting for each event.
No interpolation is done. At least one event must be
within the time range to perform a successful
calculation. Two events are required for standard
deviation.
In handling events at the boundary of the calculation,
PI AF uses the following rules:
• Events at both boundaries are used when
there is only one calculation interval.
• Events at start time are included when
multiple intervals exist and the intervals
are in ascending time order.
• Events at the end time are included when
multiple intervals exist and the intervals
are in descending time order.
Event Weighted Exclude Most Recent Event Behaves the same as Event Weighted, except in the
handling of events at the boundary of summary
intervals in a multiple intervals calculation. Use this
option to prevent events at the intervals boundary
from being double count at both intervals. With this
option, events at the end time (most recent time) of
an interval are not used in that interval.
Event Weighted Exclude Earliest Event Similar to the Event Weighted Exclude Most Recent
Event option. Events at the start time (earliest time)
of an interval are not used in that interval.
Event Weighted Include Both Ends Events at both ends of the interval boundaries are
included in the event-weighted calculation.
Time Weighted Weights the values in the calculation by the time over
which they apply. Interpolation is based on the step
attribute of the point. Interpolated events are
generated at the boundaries if necessary.
Time Weighted Continuous Applies weighting as in Time Weighted, but does all
interpolation between values as if they represent
continuous data (standard interpolation), regardless
of the step attribute of the point.
Time Weighted Discrete Applies weighting as in Time Weighted but does
interpolation between values as if they represent
discrete, unrelated values (stair-step plot), regardless
of the step attribute of the point.
4. In the Min percent good field, enter a value between 0 and 100. This is a percentage representing the
minimal amount of time a value must be good before a summary value is returned. For time weighted
calculations, the percentage is based on time. For event weighted calculations, the percent is based on event
count.
5. Click OK.

Create ranges of configurable durations

To guarantee that time ranges are always of the same length, configure time range overrides.
1. From the By Time list, select Time Range Override.
2. In the Relative Time field, type a PI relative time expression, as described in Relative time.
PI AF creates a time range based on the end time supplied by the client application and the offset defined by
the relative time.
Note: You can use substitution parameters to read the relative time from the value of another attribute, as
described in References to attribute values, References to attribute values. If you do this, PI AF evaluates the
referenced attribute value at the time of each data request.
Example
To create a one-hour rolling average, you would use the following settings:
• From the By Time list, select Time Range Override.
• In the Relative Time box, type -1h.
• From the By Time Range list, select Average.
With this configuration, the data reference always computes a 1-hour average, even when the client application
specifies a different time range.

Create default time ranges for element attributes

You can create a default time range for element attributes. A default time range is a time range that PI AF uses
when a client application provides a specific time, rather than a time range.
Note: Event frame and transfer attributes treat time ranges differently, as described in Time ranges for event
frames and transfers.
1. In the PI Point Data Reference (or PI Point Array Data Reference) window, use the following value retrieval
settings:
a. From the By Time list, select Time Range.
b. In the Relative Time field, type a PI relative time expression, as described in Relative time.
Note: You can also use substitution parameters to read the relative time from the value of another
attribute, as described in References to attribute values, References to attribute values.
PI AF creates a time range based on the time specified by the client application and the offset defined by
the relative time.
Example
A totalization meter requires a time range in order to deliver a totalized value. If the client application sends a
specific time, you want to create a one-hour time range that ends in the specified time. To do that, you would
use these settings:
1. From the By Time list, select Time Range.
2. In the Relative Time field, type:
-1h
3. From the By Time Range list, select Total.
Note: For a 24-hour totalizer you would set a relative time of -24h or -1d.

Configure dynamic time range calculations

Use a PI AF attribute to calculate the time range based on variable factors. You can use the attribute value to
determine the time range dynamically. The attribute values must be valid PI relative times, as described in
Relative time.
1. Configure an attribute to generate the PI relative times. The attribute might reference an enumeration set
containing PI relative times, or it might construct PI relative times based on a calculation.
2. Configure the PI point data reference.
a. From the By Time list, select Time Range Override.
b. In the Relative Time field, type: %@AttributeName%
where AttributeName is the name of the attribute that generates the PI relative time values.
c. From the By Time Range list, select a calculation method.
With this configuration, the data reference uses the calculated relative time as a time offset that determines the
time range.
See Example variable end time to step through an example.
Example variable end time
This example creates a data reference with a variable end time.
1. Create an enumeration set, MyEnumSet, that contains these three values:
-30m
-1h
-2h
 Note: Values must be valid relative time expressions, as described in Relative time.
2. Create an attribute, called TimeRangeAttribute, that references the MyEnumSet enumeration set.
You specify the enumeration set when configuring the attribute. From the Value Type list, select
Enumeration Sets > MyEnumSet.
3. Create another attribute, called DataReferenceAttribute with a configured PI point data reference:
a. For the PI point, choose any point that has a numeric value.
In this example, we will use the sinusoid point on a Data Archive named PISRV1.
b. From the By Time list, select Time Range Override.
c. In the Relative Time box, type: %@TimeRangeAttribute%
d. From the By Time Range list, select Average.
The TimeRangeAttribute attribute lets you choose the time interval for the calculation.

Time ranges for event frames and transfers

Event frames and transfers, by their nature, have a time range associated with them. When a calling application
requests a value from an attribute, the value returned depends on the data reference and its configuration:
• When the calling application supplies no time context, PI AF calculates the attribute value using the time
range of the event frame or transfer. For example, if an attribute contains a PI point configured with a time
range summary option, the summary will be performed over the time range of the event frame or transfer.
• If an attribute contains a PI point configured with only the default time option, PI AF returns the value of the
point at the end time of the event frame.
 • When the calling application supplies a single timestamp, PI AF returns the value at the specified time, even
if the time is outside the time range of the event frame or transfer.
• If the calling application supplies a time range, PI AF uses the intersection of the supplied time range and the
time range of the event frame. If there is no intersection, a "No Data" event is returned.
• The shaded area in the following figure represents the intersection between an event frame time range and
a requested time range. For attributes that contain a PI point configured with a time range summary option,
the summary is performed over this intersection. If the attribute contains a PI point configured with only the
default time option, the value at the start time of the intersection is returned.
Intersection between event frame time range and requested time range

PI point value updates from a data reference

An attribute with a PI point data reference can write a value to a PI point. In the PI Point Data Reference
configuration window, the Read only check box determines whether the attribute can write data to the
referenced PI point. By default, the check box is selected (Read only = True), meaning that the PI AF attribute
cannot change the value of the PI point.
In rare cases, you might want to write the attribute value back to the point value. For example, if the attribute
value is the result of a calculation or analysis, you can update the PI point with the result of that analysis. In this
case, you would clear the Read only check box to allow the attribute to write its value to the point.
Note: Applications that use the AF SDK UpdateValue method, such as the PI Analysis Service, can write data to
the PI point regardless of whether the Read only check box is selected or not.

Attribute-value updates from PI point data references

When you create an attribute based on a template with a data reference, PI AF does not automatically create the
PI point data references associated with that element. To create the data references, you must right-click the
element in the Elements (or Event Frames) browser and click Create or Update Data Reference. PI AF replaces all
substitution parameters with the corresponding values at that moment, and creates and locks in the data
reference.
Data reference lock-in
When a data reference is locked in, changes to the attribute template no longer affect instances of the attribute.
Substitution parameters are also no longer evaluated. However, the following fields are exceptions:
• An attribute value reference is entered in the Relative Time field, as noted in References to attribute values,
References to attribute values.
• Any point attribute change made in the Tag Creation Settings window.
For example, if a point attribute change is made or a point attribute is defined by substitution parameters, the
data reference of derived attributes will still be affected whenever you right-click an element and click Create or
Update Data Reference.
Data reference reset
After an attribute value has been locked in, you can use the Reset to Template feature to reset an element to its
template's original properties, as described in Attribute-value reset to original properties.

Attribute indicators for updates of PI point data references

PI System Explorer employs distinctive visual indicators for attributes that support the Create or Update Data
Reference option. A visual indicator is also displayed when an attribute no longer appears to be configured
correctly, such as after a server or a tag name has been changed.
The following visual indicators for the Create or Update Data Reference option are available:

Icon Description Column

The attribute is associated with a template that contains point Configuration Item Indicator
creation rules. Use the Create or Update PI Point option to create
the tag configuration based on the template. Additionally, the column ( )
point name and ID is resolved.
Specifies if an attribute's data reference configuration differs from Configuration Item Indicator
what is stored in the specified data server. This can occur when a
point is renamed, when an attribute's data reference is tied to a PI column ( )
point without a value (floating) or when the underlying PI Data
Archive is replaced. Use the Create or Update PI Point option to
update the configuration.
The data reference has returned a system digital state rather than Quality Indicator column ( )
a typical value from the source. An example is when a PI point has
been created, but doesn't have any data.
The value returned from the data reference has a bad quality. An Quality Indicator column ( )
example is when a PI point has been created, but it does not yet
have any data.
 Icon Description Column

The attribute is a configuration item. See Configuration Item Configuration Item Indicator
attribute property for more information.
column ( )
Note: The Create or Update Data Reference option is not
applicable for configuration item attributes.

When you review element attributes on the Attributes tab, the first entry in the column at left of a data
reference attribute's name indicates whether you can run the Create or Update Data Reference option. You
initiate the Create or Update Data Reference option by right-clicking an element or an attribute and clicking
Create or Update PI Point.
The Create or Update Data Reference operation updates a PI point data reference with any changes that have
occurred to the PI point; substitution parameters are resolved, and server and point IDs are updated. If the PI
point does not yet exist, and the configuration contains a point creation option, it is created.
Attribute update example
When you see the indicator displayed for an attribute, you can update its configuration by right-clicking and
clicking Create or Update PI Point.
Note: The icon does not determine beforehand if any changes to the tag or its configuration will occur.
Attribute indicator with tooltip

As the tooltip shown above indicates, when you update the configuration, point name substitution rules are
resolved and the point ID is stored into the attribute's metadata. This results in faster subsequent initialization.

Note: You can use the Column List button to add columns to or remove columns from the Attributes window.

Configure creation of PI points

In an attribute template, you can configure a PI point data reference to create PI points.
1. In the Library browser, select an element template.
2. Click the Attribute Templates tab.
3. Add a new attribute template to the element template, as described in Create attribute templates.
 4. From the Data Reference list, select PI Point.
5. Click Settings.
6. In the Tag name field in the PI Point Data Reference window, set up the PI point names for the generated
points. Use substitution parameters to enable PI AF to build point names for the points it generates.
a. Click to select name substitution and related attribute values from a context menu. For more
information on name substitution values, see List of PI AF substitution parameters.
Note: If the attribute value substitution is a string that contains spaces, you must surround the entire
tag name in double quotes. Concatenate the entire string first, then substitute the value into the tag
name portion of the string with String Builder.
For example:
"\\%Server%\%Element%.%ID%.%@ConcatStringName%;pointtype=String"
b. Select the Tag Creation check box.
c. Click .
d. In the Tag Creation Settings window, specify a point class and point type in the Point Class and Point
Type fields. For more information on PI point classes and attributes, see Point classes and attributes.
e. Default attribute values are displayed for the selected point class. You can edit the default PI point
attributes, or you can click Import to import PI point attribute values from an existing point that you
locate in the Tag Search window.
7. To preview how the selected substitution parameters resolve, click the Select example instance link in the
Preview section.
8. In the Find Derived Elements for Element_Template window, select a sample element.
9. Click OK.
The ConfigString and Value fields display the resolution of the substitution parameters you selected, as well
as the tag creation settings.
10. To save your work, press CTRL-S or click Check In.
11. Create a new element based on your element template and click on the Attributes tab.
12. Right-click the PI point data reference attribute and click Create or Update Data Reference.
13. To save your work, press CTRL-S or click Check In.
All the points that the new elements reference are created. This only works because the elements were based on
a template and the attribute template for the data reference uses the Tag Creation option.
After the PI points are created, it might take some time before values are written into Data Archive by the
specified interface. Until then, the values are displayed as Pt. Created.

Edit PI point properties

Edit a PI point property when you need to provide more information on a PI point than default tag property
values. For example, it can be helpful to provide a descriptor for a PI point that is created as output from an
analysis.
1. In the Elements browser, locate the element that contains the PI point you want to edit.
 2. Click the Attributes tab and select the attribute with the PI Point data reference.
3. Click Settings.
4. In the PI Point Data Reference window, click .
5. In the PI Point Properties window, choose from the following actions:
To ... Do this ...

Edit a property value a. Click the Value field beside a property.

b. Enter a revised value.
Restore an edited value to Data Archive default a. Click the Value field beside an edited
property.
b. Click and select Restore default value.
6. Click OK.

Preview substitution parameters in PI point data references

Preview how substitution parameters resolve as you configure a PI point data reference in an attribute template.
1. In the Library browser, select an element template.
2. Click the Attribute Templates tab.
3. Add a new attribute template to the element template, as described in Create attribute templates.
4. From the Data Reference list, select PI Point.
5. Click Settings.
Default substitution values are displayed in the Tag name field.
6. Use substitution parameters to enable PI AF to build point names automatically for the points it generates.
Click to select name substitution and related attribute values from a context menu. For more information
on name substitution values, see List of PI AF substitution parameters.
7. To preview how the selected substitution parameters resolve, click the Select example instance link in the
Preview section.
8. In the Find Derived Elements for Element_Template window, select a sample element.
9. Click OK.
The ConfigString and Value fields display the resolution of the substitution parameters you selected, as well
as any tag creation settings and value retrieval methods (if selected).
10. Choose one of the following actions:
▪ To confirm the PI point data reference configuration, click OK.
▪ To change configuration settings, click Cancel and start over by clicking Settings.
PI point array data references
You use the PI point array data reference to link attributes of elements to arrays of PI points for either reading or
writing their values. Each tag name specified corresponds to a single entry in the array. Configure the PI point
array data reference as you would the PI point data reference, with the exception of the Tag Names field in the PI
Point Array Data Reference window.
Video
For information on how to set up PI point array data references, watch this video:

Create PI point array data references

Create a PI point array data reference to link attributes of elements to arrays of PI points for either reading or
writing their values.
1. To configure a PI point array data reference:
▪ In the Elements browser, select the desired element.
▪ In an element template, select the desired element template in the Library browser.
2. In the Attribute or Attribute Templates tab, select the attribute.
3. In the attribute configuration panel, choose PI Point Array from the Data Reference list.
4. Click the Settings button.
5. In the PI Point Data Array Reference window, leave the default server, or choose a different Data Archive
from the Data server list.

Note: If the desired Data Archive does not appear in the list, click and select a Data Archive from the PI
Data Archives window.
6. In the Tag name field, choose from the following actions:
▪ To enter PI points directly, enter point names separated by the pipe symbol (|). For example:
CDM158|CDT158|SINUSOID

▪ To search for PI points, click and enter search criteria in the Tag Search window. Select multiple PI
points on the selected Data Archive.
7. Optional. Specify the units that the referenced PI points use. See Unit of measure considerations.
8. In the Value retrieval methods section, specify how the attribute gets its value. For example, the attribute
value could be the same as the point values, or it could be a result of a calculation on the point values. See
Configuration of retrieval methods for attribute values.
9. Use the Read Only check box to specify whether you want PI AF to write the attribute value back to the
source points. By default, PI AF does not write data to the referenced PI points (the Read Only check box is
checked). See PI point value updates from a data reference.
Formula data references
You use formula data references to create custom calculations based on other element attributes. Calculations
can be a single formula or a sequence of calculations. Formula data references can have multiple input
attributes.
Videos
For information on how to create formula data references, watch this video:
For information on UOMs in formula data references, watch this video:

Formula data reference operators

You can use the following operators in formula data references (in order of precedence):
Operator Precedence

Parenthesis 9 (calculated first)

Unary Minus 8

^ 7

* / mod 6

+- 5

< > <= >= == <> 4

NOT 3

AND 2

OR 1 (calculated last)

You cannot use the assignment operator = at the beginning of any formula.
Note: Formula data reference syntax uses == (two equals signs) to indicate equality and = (single equals sign) for
assignment. Analytics (and performance equation) syntax uses = to indicate equality and := for assignment.
Compound operators
You can choose If-Then-Else, a compound operator with operands used as follows:
If expr0 Then expr1 Else expr2
where expr0, expr1, and expr2 are expressions. If expr0 is true, the value of expr1 is returned; otherwise, the
value of expr2 is returned.
 Formula example
This sample formula calculates the daily average cost of reagent per tonne processed, as shown in the Value field
for Grinding Media in the following mineral processing illustration:
A=.|Addition (Daily Total);B=.|Unit Cost;C=Tonnage (Past 24 Hours);[if C ==0 then
digstate("No Data") else A*B/C]
Sample formula data reference

Formula data reference functions

supports the following functions in a formula data reference. For information on analyses expression functions,
see .

Function Description

abs(X) Absolute value of X.

acos(X) Arc cosine of X.
asin(X) Arc sine of X.
atan(X) Arc tangent of X.
Function Description

badval(x) Returns 1 if the value has a bad status, has a floating point value of not a number
(NaN), or is not a numeric value, otherwise returns 0.
ceiling(X) Smallest integer not less than X.
cos(X) Cosine of X.
cosh(X) Hyperbolic cosine of X.
cot(X) Cotangent of X.
coth(X) Hyperbolic cotangent of X.
csc(X) Cosecant of X.
csch(X) Hyperbolic cosecant of X.
digstate() Returns a system digital state value.
• If successful, the system digital state is returned as a system enumeration
value. For PI AF Client versions older than 2.4, the value is returned as a PI
SDK digital state, because the system enumeration value set did not exist.
• If unsuccessful, the value is returned as a string.
In both cases, the AFValue.IsGood flag is set to false, and the attribute is
flagged in the Attributes Viewer with the icon.
e() Value of the natural logarithm base.
exp(X) Natural logarithm base e raised to power of X.
floor(X) Largest integer not greater than X.
ln(X) Natural logarithm of X.
log(X) Logarithm of X using base 10.
logbase(X,Y) Logarithm of X using base Y.
max(X,Y) Greater of X and Y.
min(X,Y) Lesser of X and Y.
normalrnd(X,Y) Random number that maps the normal distribution curve. X is the mean and Y is
the standard deviation.
pi() Value of pi.
poisson(X) Random number that maps the Poisson distribution. X is the mean.
pow(X,Y) X raised to the power of Y.
rand() Uniform random number. The values can be between 0 and less than 1.0
rand(X,Y) Uniform random number. The values can be between X-Y/2 and less than X+Y/2.
 Function Description

remainder(X,Y) Returns the remainder resulting from the division of X by Y.

round(X) X rounded to the nearest whole number.
roundfrac(X,Y) X rounded to the number of fractional digits specified by Y. Y is an integer
number.
sec(X) Secant of X.
sech(X) Hyperbolic secant of X.
sign(X) Returns 1 if X is greater than zero and -1 if X is less than zero.
sin(X) Sine of X.
sinh(X) Hyperbolic sine of X.
sqrt(X) Square root of X.
tan(X) Tangent of X.
tanh(X) Hyperbolic tangent of X.

Units of measure in formula data references

When working with formulas and units of measure, you need to configure the equation inputs and the output
with the correct UOM:
• For the attributes in the equation, use the UOM that the formula expects (NOT the units the attribute is
already in).
• For the calculation result, specify the UOM in which you want the result to appear. This must be consistent
with the UOMs for your inputs (attribute values).
Example of UOM in a formula data reference
Consider the following formula configuration for converting volume and density into mass:
V=Volume;UOM=L;D=Density;UOM=kg/L;[V*D];UOM=kg
The units of measure for the inputs and outputs are consistent: (L*kg/L = kg). This formula works on any input
attributes or output attributes, regardless of the attribute's unit of measure, as long as they have a unit of
measure of the correct class specified.

Configure formula data references

The formula data reference does not support strings or other non-numeric value types.
Create formula data references to perform custom calculations.
1. Choose one of the following actions.
▪ In the Elements browser, select the desired element.
▪ In an element template, select the desired element template in the Library browser.
2. In the Attribute or Attribute Templates tab, select the attribute.
 3. From the Data Reference drop-down list, choose Formula.
4. Click the Settings button to open the Formula Data Reference configuration window.

5. If your equation requires an attribute value, click to add it as a parameter (Define parameters for
formula data references).
6. Select the Default Values Allowed check box to enable PI AF to use attribute default values in the
calculation. Default values are specified on the attribute template. If you clear the check box, the calculation
fails when the data for one or more attributes is not available.

7. Click to begin defining the equation. For more information, see Define equations for formula data
references.
8. In the Unit of Measure field, specify the unit of measure the result of the formula or calculation sequence
will produce, as described in Units of measure in formula data references.
9. In the Minimum field, enter an appropriate value for the minimum returned value. If the calculated value is
less than this minimum, the data reference returns the minimum value you specify. If there is no minimum
value for this calculation, leave the Minimum box blank.
10. In the Maximum field, enter an appropriate value for the maximum returned value. If the calculated value is
greater than this maximum, the data reference returns the maximum value you specify. If there is no
maximum value for this calculation, leave the Maximum box blank.
Note: Select the Stepped check box for the value to be stepped when plotted.
11. Click Evaluate to test the data reference. The value returned by the calculation sequence appears in the
adjacent box. When the formula data reference is configured under a template attribute, the calculation uses
the default values for the template attributes. When the configuration is done under an element attribute
the actual data is used for the calculation.
12. Click OK.
13. Configure the rest of the attribute settings as you would for any other attribute.

Define parameters for formula data references

When equations require attribute values, add those attributes as parameters in the Formula Configuration
window.

1. Click next to the Parameters field.

Note: You can alternatively click in an empty row and enter a variable (a -z).
2. In the Parameter Configuration window, select a variable from the Variable menu.
The number of variables available is limited to 26 chars (from A to Z).
3. Select the attribute that the variable represents.
▪ Choose the attribute from the Attribute menu. All sibling attributes with supported value types are
listed.
 ▪ If the attribute that you want is not in the menu, choose Other. A new field called Attribute appears in
the window. Click to pick your attribute from the tree. Alternatively, type in the path to the attribute
of interest. Examples of some attribute paths are listed.
4. Select the desired unit of measure for the attribute. Note that this is not the UOM of the attribute but rather
the UOM that your formula requires from this input, as described in Units of measure in formula data
references.
For example, if your input attribute has a UOM of Celsius but your equation requires Fahrenheit, you would
select Fahrenheit in this field.

Define equations for formula data references

Define equations for use in formula data references.
1. To add a new formula row, click next to the Equations field.
You can also click in the text area and type in an equation.
2. Type an equation directly or build your equation from a list of available variables, operators, functions, and
substitution parameters. Click to choose from the following actions:
To ... Do this ...

Enter a variable Click Variables and click a letter on the alphabetized

list.
Enter an operator Click Operators and click an operator on the list. Valid
operators are listed in Formula data reference
operators.
Enter a function Click Functions and click a function on the list. Valid
functions are listed in Formula data reference
functions.
Enter a substitution parameter Click Substitution Parameters and click a time
substitution parameter. For elements and transfers,
only %Time% is available, but for event frames you
can select from %StartTime, %EndTime%,
%UtcTime%, %UtcStartTime%, %UtcEndTime%, and
%Duration%. For more information on these
parameters, see List of PI AF substitution parameters.
Numbers are converted to a double, time spans to a
duration in seconds, and timestamps to UTC seconds.

3. To add another row to the formula, click and continue the formula. Repeat as needed until you have
completed the formula.
4. To change the formula, choose from the following actions:
 To ... Do this ...

Remove the selected equation from the calculation Select the row you wish to remove and click .
sequence
Remove all equations from the calculation sequence Click .
Move an equation up or down in the calculation Select the row to be moved and click or .
sequence

String Builder data references

The String Builder data reference enables you to apply string manipulation functions, such as concatenation, to
an attribute's values, and output a reformatted string. This is useful when you need to obtain a string or numeric
value type from other element attributes. String Builder data references do not perform Unit of Measure
conversions or calculations. When you use the String Builder data reference in a template, value substitution
takes place at run time.
Expression syntax
Observe the following rules as you build an expression:
• You can construct an expression on a single line, using semicolons to separate its terms.
• You can also place each term on its own line, which eliminates the semicolons and makes the expression
structure more apparent.
• Enclose substitution parameters in double quotes so that their result is treated as a literal string.
• You can include any keyboard character in a double-quoted string, for example, dashes, backslashes, colons,
semicolons, and so on. To include the double-quote character in a string, type two consecutive double-quote
characters within the string, for example, """t""e""s""t""" produces "t"e"s"t".
• You can include single-quoted attribute paths to display the value of the referenced attribute in the result.
• You should avoid the use of unquoted strings because you may get haphazard results.

Attribute references in String Builder

To reference other attributes, you use the syntax in the following table.

Object Syntax

Sibling attribute siblingAttribute

Top level attribute of same element |topLevelAttribute
Parent attribute ..
Parent element attribute ..\|myAttribute
Child attribute .|childAttribute
 Object Syntax

From event frame to primary .\Elements[.]|myAttribute

element
Database relative path \TopLevelElement|myAttribute
Full path \\myServer\myDatabase\myElement|myAttribute
Examples
Suppose you want to retrieve the Environment PI point value from the Cracking Process parent element:

In the child element Equipment, you would use the syntax ..\|myAttribute and enter '..\|Environment' in the
String Builder Data Reference window:

A value similar to the following is displayed in the Value field: 43.3071403505214.

Function implementation in String Builder

In String Builder, you can use several text manipulation functions, as well as the Format function.
Text extraction and case manipulation
You can use functions to manipulate the case of a string and to extract certain sections.
The syntax for text manipulation functions in String Builder is described in the following table:

Left(string, length) Returns a string that contains the specified number of characters
(length) from the left of the input (string).
Example: Left("Temperature",4) returns Temp
Right(string, length) Returns a string that contains the specified number of characters
(length) from the right of the input (string).
Example: Right("GasTemp",4) returns Temp
Mid(string, start, [length]) length is optional. Returns a sub-string from the specified position
(start) of the input (string). When number of characters (length) is
included, returns the specified number of characters.
Example: Mid("GasPressure",4,8) returns Pressure
UCase(string) Converts string to uppercase.
Example: UCase("Temperature") returns TEMPERATURE
LCase(string) Converts string to lowercase.
Example: LCase("TEMPERATURE") returns temperature
Trim(string) Removes blanks on both sides of string.
Example: Trim(" Temperature ") returns Temperature
RTrim(string) Removes trailing blanks from string.
Example: RTrim(" Temperature ") returns " Temperature"
LTrim(string) Removes leading blanks from string.
Example: LTrim(" Temperature ") returns "Temperature "
Replace(string1, string2, string3) The function searches string1 for string2, then replaces string2 with
string3.
Example: Replace("Temperature","Temp","External Temp")
returns "External Temperature"
You can also nest text manipulation functions.
• For example, for an attribute named GasPressure, you can use the Mid function in combination with the
UCase function to return the following expression: GASPR
Mid(UCase("%Attribute%"), 1, 5);
• Alternatively, for the same attribute, you can use the Mid function in combination with the LCase function to
return the following expression: pressure
Mid(LCase("%Attribute%"), 4, 8);
Note: Beginning with PI AF 2018, you can nest functions in any position, not the first position only. For example,
Replace(Mid("abc",1,3),"b","2");
Replace("abc",Mid("abc",2,1),"2");
Replace("abc","b",Mid("123",2,1));
all return the expression: a2c
Format function
The Format function enables you to convert real numbers, integers, and time stamps to a string according to the
format and optional culture specification.
Note: Unlike other string functions, the syntax of Format(DateTime, ... ) follows C# syntax.
The syntax for Function implementation in String Builder is described in the following table:

Real numbers Format(real, format) Format follows Performance Equation (PE)

style syntax, such as "%0.3f", where the
Format (real, format, culture)
number before the decimal indicates the
minimum total number of characters to
output, pre-padding with blanks, and the
number after the decimal indicates the
number of digits to display after the
decimal point.
Culture is optionally specified using an
Internet Engineering Task Force (IETF)
language tag, such as "en", "en-US", "de",
which specifies the language and optional
culture and regions.
Integer numbers Format(integer, format) Format follows PE style syntax, such as
"%4d", where the number indicates the
Format(integer, format, culture)
minimum total number of characters to
output, pre-padding with blanks as
necessary.
Culture is optionally specified using an IETF
language tag, such as "en", "en-US", "de",
which specifies the language and optional
culture and regions.
Time stamps Format(datetime, format) Format follows C#
Format(datetime, format, culture) DateTime.ToString(format) syntax, and can
be either a pre-defined syntax, or a custom
syntax.
DateTime format uses invariant culture
settings. To display dates and times for a
specific culture, add an IETF language tag,
such as "fr-FR" and "fr-CA", as described in
the MSDN article Table of Language
Culture Names, Codes, and ISO Values
Method.
For more information on date and time
formats, see Format strings for time
substitution parameters.
Arrays Format(array, delimiter) Delimiter uses white space " " as the
default delimiter, unless another delimiter
Format(array, delimiter, format)
character is specified.
Format(array, delimiter, format, culture)
In addition, format and culture can
optionally be specified, using the same
syntax as real and integer numbers above.
For example, the following String Builder
data reference to an array (with values
11.12, 15.98, and 99.154) that specifies a
"-" delimiter, a "%3.3.f", and a "Fr-fr"
culture:
Format('..\|TestArray',"-","%3.3f","Fr-fr");
produces a value of 11,120-15,980-99,154.
New line NewLine() Ensures that a new line is displayed in the
output value. For example, when
a;Newline();b; is entered, the output
value is displayed as:
a
b
Numeric format example
Suppose you want to format the Environment PI point value that you have already retrieved from the Cracking
Process parent element. In the String Builder Data Reference window, you would select the row that contains the
string expression, click and select Functions > Format(Real, "%3.3f") to modify the expression:

The Value field changes from 43.3071403505214 to 43.307.

To change the cultural value from the US default to a Spanish culture format, you would select Functions >
Format(Real, "%3.3f", "en-US") and change the "en-US" string to "es":

The Value field changes from 43.307 to 43,307.

Note: Be sure the data type you specify matches the attribute data type. You would encounter errors, for
example, if you specify "%3.2f" for an integer type attribute value or "%3d" for a floating point attribute value.
 Date time format example
Suppose you want to retrieve and format the In Service Date value from the Condenser child element:

In the parent element Power and Steam Generation, you would create an attribute named Condenser Service
Date. Use the syntax .\childElement|Attribute, and enter '.\Condenser|In Service Date' in the String
Builder Data Reference window:

The In Service Date value is retrieved and displayed in the Value field: 2/25/2009 12:00:00 AM.
To change the format from the US default to Universal full date in German culture format, you would alter the
expression to read Format(.\Condenser|In Service Date,"U","de"). The Condenser Service Date attribute
value format is converted accordingly:

Create String Builder data references

When a String Builder data reference is used in a template, value substitution takes place at run time.
Create a String Builder data reference when you need to apply string manipulation functions, such as
concatenation, to an attribute value and output a reformatted string.
1. Choose one of the following actions:
▪ In the Elements browser, select the desired element.
▪ In the Event Frames browser, select the desired event frame.
▪ In an element template, select the desired element template in the Library browser.
2. In the Attribute or Attribute Templates tab, select the attribute.
3. In the attribute configuration panel, choose String Builder from the Data Reference list.
4. Click Settings.
5. In the String Builder Data Reference window, click .
6. In the highlighted row, press F2 or click and select from the following options:
Option Description

Literals A text string between double quotation marks:

"Sample"
Attribute Values A list of other attributes for the selected element or
element template. Note that attributes must appear
in single quotes.
Related Attribute Values A list of the following attribute references:
• '\\<Server>\<Database>\<Element>|
<Attribute>'
• '\\.\<Database>\<Element>|<Attribute>'
• '\<Root Element>|<Attribute>'
• '.\<Child Element>|<Attribute>'
• '..\|<Primary Parent Attribute>'
• '..\<Sibling Element>|<Attribute>'
You can also select Search to enter search
criteria in the Attribute Search window.
Substitution Parameters A list of 20 commonly used substitution parameters.
For more information, see List of PI AF substitution
parameters.
 Option Description

Functions A list of the following functions:

• Left(string, length)
• Right(string, length)
• Mid(string, length)
• Mid(string, start, length)
• UCase(string)
• LCase(string)
• Trim(string)
• RTrim(string)
• LTrim(string)
• Replace(string, string, string)
• Format(Real, "%3.3f")
• Format(Real "%3.3f", "en-US")
• Format(DateTime, "yyyy-MM-dd HH:mm:ss")
• Format(DateTime, "yyyy-MM-dd HH:mm:ss",
"en-US")
• Format(Array, Separator)
• NewLine()

7. Build your expression further. You can either type a semicolon (;) and continue in the same row, or click
to continue on another row. You can use the following icons to manipulate the expression:
To ... Do this ...

Append a new string Click .

Remove a string Select a row and click .
Remove all strings Click .
Move a string up a row Select a row below the top row and click .
Move a string down a row Select a row above the bottom row and click .
As you build the string expression, you can preview the result of the expression in the Value field.
8. When the string expression is complete, click OK.
Examples
• You can enter the following substitution parameters in a single row to concatenate a pathname string. For
example:
 "%Database%";"\";"%Element%";"|";"%Attribute%";
• This data reference would produce output similar to: DB26\WX12000|pressure.
• You can build an expression in separate rows to show the duration of an event. For example:
a. Click , press F2 and select Substitution Parameters > "%StartTime%".
b. Click and type the characters: " to "
c. Click , press F2 and select Substitution Parameters > "%EndTime%".
d. The Value field shows a date and time interval:

1.
For more examples, see Function implementation in String Builder.

Table lookup data references

You can configure an attribute to obtain its value from a PI AF table. You can define the PI AF table entirely in PI
AF, or you can link to or import from a data source outside the PI System (such as a Microsoft SQL table or a
Microsoft Excel worksheet).
Table lookup
The table lookup data reference is intended to be a simple table lookup. It uses Microsoft's .NET
System.Data.DataTable.Select method, and follows the filter expression rules of that method. Note that not all
its features are implemented in PI AF. For example, a table lookup data reference does not include functionality
such as column functions and parent/child relation referencing.
Note: The table lookup data reference is not optimized to treat data in an external table as a time series and
query for it. For optimal performance, such data should be stored in PI tags on a Data Archive.
 Table lookup methodology
You begin by creating a table profile in the Library browser, where you establish general settings for the time
zone and cache interval for refreshing data, as well as definitions of table columns and connections to data
sources outside the PI System if you are linking to or importing external data.
If you are linking to external data sources, consider creating reusable table connection profiles in the Library
browser, as described in Create reusable table connections.
Videos
For information on how to create internal tables for table lookup data references, watch this video:
For information on how to configure table lookup data references, watch this video:

Create PI AF tables
You create a table profile so that attributes can obtain their values from an internal or external table.
1. In the Library browser, right-click the Tables collection and click New Table.
2. In the General tab, enter a Name and Description for the table.
3. Optional. Assign one or more categories to the table. Enter table category names directly, separated by a
colon, or click and select them from the Categorize window.
4. Decide how DateTime values should be stored in the table. By setting the value for the table overall, you
need not specify it every time you create a table lookup data reference.
a. In the Time Zone field, select a time zone from the list.
b. Select or clear the Convert To Local check box. Choose from the following options:
▪ To convert DateTime values to the local time, select the Convert To Local check box.
▪ To display DateTime values in the time zone selected in the Time Zone field, clear the Convert To
Local check box.
Note: When a client application queries the table, the time zone in which DateTime values are
displayed depends on whether the Convert To Local check box is selected. PI System Explorer uses
this setting to determine the precise DateTimeMode to use in a Microsoft .NET data table, as
described in Conversion settings for time zones.
5. In the Cache Interval field, enter the amount of time until the table's cached data is automatically refreshed.
From the list, choose whether the value is in seconds, minutes, hours, or days. The default value is zero,
which indicates a manual refresh.
Note: Automatic refreshing is disabled if the table has changes that have not been saved to the server.
Note: With manual refreshes, you refresh table data by right-clicking the table in the Library browser and
clicking Refresh. Otherwise, table data that is being queried by client applications is refreshed only when the
application is restarted. For example, when PI System Explorer is opened or whenever the Microsoft Internet
Information Services (IIS) application pool recycles the client (the default is every 29 hours).
6. Check in your work.
Note: The Connection and Query fields are read-only. PI AF populates these fields when you link to or import
an external table.
Define and populate the table in one of three ways:
• Manually define and populate the table in PI System Explorer. First, create column definitions on the Define
Table tab, as described in Create table column definitions. Next, enter data on the Table tab, as described in
Populate tables manually.
• Import a table from outside the PI AF server. See Access to Microsoft Access or Excel data.
• Link to a table outside the PI AF server. See Access to Microsoft Access or Excel data.

Conversion settings for time zones

The precise time conversion calculation depends on:
• The value that you select in the Time Zone list. Times are prefixed with either Universal Coordinated Time
(UTC), Greenwich Mean Time (GMT), or Time Zone (TZ). The list also includes the None option.
• Whether you selected or cleared the Convert to Local check box.
• Whether this is an internal (either imported or defined in PI AF) or external (linked) table.
The following table explains how displayed times are determined for each possible combination. The exact
options in the Time Zone list are dependent on your operating system.

Time zone Convert to Internal/ Behavior

local external

None Internal Fields that contain DateTime data type are automatically
adjusted for time zone differences and return local times on
the client.
External Fields that contain DateTime data type are assumed to be in
the time zone of the PI AF server and are adjusted to the
client's local time.
None Internal Fields that contain DateTime data type are not translated.
Useful for storing date fields where translation is not desired,
such as birth date.
External Fields that contain DateTime data type are not translated.
Useful for storing date fields where translation is not desired,
such as birth date.
UTC or Internal Fields that contain DateTime data type are adjusted to local
times on the client.
GMT
External Fields that contain DateTime data type are externally stored
as UTC, but adjusted to local time on the client, represented
as UTC.
UTC or Internal Fields that contain DateTime data type are always
represented as UTC.
GMT
External Fields that contain DateTime data type are externally stored
as UTC, and left as UTC on the client.
 Time zone Convert to Internal/ Behavior
local external

TZ Internal Fields that contain DateTime data type are adjusted for time
zone differences and are local time on the client. This
combination is not normally needed except when external
data is being imported into PI System Explorer.
External Fields that contain DateTime data type are adjusted for time
zone differences, and are adjusted to local time on the client,
represented as UTC.
TZ Internal Fields that contain DateTime data type are left in the time
zone specified. A table lookup data reference adjusts as
appropriate; however, other applications may not.
External Fields that contain DateTime data type are left in the original
time zone specified, represented as UTC. A table lookup data
reference adjusts as appropriate; however, other applications
may not.

Create table column definitions

To create a table manually, begin by defining the columns in the table.
1. Once you have completed the overall table settings on the General tab, click the Define Table tab.
2. Determine the number of columns in the table and click once for each column to be defined.
3. Click the Name cell and replace the default label with the required column name.
4. Click the adjacent Value Type cell and select a data type from a list of Basic Types or Array Types. For a
description of data types, see PI AF data types.
Tip: If any value type is set to DateTime or String, leave the column time zone value set to None and select a
time zone value for the table overall in the Time Zone field on the General tab. That value supersedes time
zones set on specific table columns.
5. Optional. Click the Unit of Measure cell and choose one of the following actions:
▪ Start typing and select a unit of measure from the list of matching UOMs.
▪ Click and select from the full list of UOMs.
Tip: We recommend you set a unit of measure for a table column so you do not need to specify one each
time you select the column in a table lookup data reference.
6. Optional. For any column you assign a Byte Array value type, you can set Use Image to True. PI System
Explorer attempts to display the array as an image.
7. Repeat steps 3 to 6 for each column in the table.
8. To modify the table column definition, right-click a row in the grid and select an option. Alternatively, use the
following icons.
 To ... Do this ...

Insert a new column Click .

Move a column up a row Select a row below the top row and click .
Move a column down a row Select a row above the bottom row and click .
Remove a column Select a column and click .
When you have completed defining table columns, click the Table tab so you can enter row data for each column
manually.

Populate tables manually

Once you have completed table column definitions, enter row data for each column.
1. Click the Table tab. Based on the table columns that you created in the Define Table tab, enter the
appropriate information in rows for each column.
2. Choose from the following actions:
To ... Do this ...

Enter a new row Right-click in the table grid and click Insert or New.
Copy and paste rows from an Excel spreadsheet a. In the spreadsheet, copy the rows you want.
b. In the table grid, right-click a new row or a
range of rows and click Paste.
Replace data for specific cells a. Use standard Windows selection keystrokes
(such as SHIFT+<click> and CTRL+<click>)
to select contiguous and non-contiguous
cells in the table, as described in Select
multiple objects in the viewer.
b. Right-click and click Clear Cell(s).
c. Enter new data in the cleared cells.
Remove a row Right-click the row you want to remove and click
Delete.
3. To save your work, press CTRL+S or click Check In.

Data references from outside the PI System

You can also use PI AF tables to access data that is external to the PI System. Such data might be contained in
Microsoft Excel, Access, or SQL Server, or other OLE DB/ODBC data sources. You can either import the table or
link to it after you have defined the table structure, as described in Create PI AF tables and Create table column
definitions.
Imported tables
PI AF tables with imported data are called imported tables. Imported tables are read/write tables. They are
limited in size but are more secure than linked tables. Imported tables are sometimes called internal tables
because, unlike linked tables, the table data is managed in PI AF. After the initial import, there is no further
relationship between the foreign table and the PI AF table. You can edit the data directly in PI AF.
It is a good practice to limit your imported tables to 10,000 rows of data or less. Imported tables are not
designed for storing very large databases. If you need to access a lot of data in PI AF tables, link to external tables
instead, which do not present such storage limits. Alternatively, break the table into separate tables when
importing.
Linked tables
Linked tables are sometimes called external tables, because the source data is not stored in the PI AF database.
You cannot edit an external table from PI AF. Linked tables require additional security configuration because you
need to configure how PI AF connects to the external data source. You should set up a reusable table connection,
where you configure the type of authentication to access the external table.
Videos
For information on how to import data from external tables, watch this video:
For information on how to link to data in external tables, as well as SQL security, watch this video:

Authentication for linked tables

When a client application requests external data, the PI AF server queries the external data source and returns
the data to the client as a read-only PI AF table.
For externally linked tables, the OLE DB provider and the PI AF server should share the same bitness (32-bit or
64-bit). To configure an external table connection in PI System Explorer, for example, you would use a PI AF
server of the same bitness (typically, 64-bit).
When you configure the linked table, you must specify the credentials that the PI AF server uses to connect to
the database. The authentication options are:
• Impersonate Client
If the source database supports Windows authentication, use the Windows identity of the client that is
requesting the data. This is an impersonated connection. This is the most secure method of authentication
and should be used wherever possible.
• Supply Password
If the source database does not support Windows authentication, or if the database and PI AF server are on
different, non-trusted domains, specify a user name and password with the necessary access on the source
database. PI AF uses this hard-coded account to read the data in the external data source. For example,
MySQL database does not support Windows authentication, so you would use the user name and password
of an account on the MySQL database.
Note: You can enter a user ID and password as part of the connection string and save it with a PI AF table
connection, regardless of whether support for external PI AF tables for non-impersonated users has been
previously enabled (with the afdiag /DTImp command).
• No additional security context
 This option usually applies when you use Excel or other file-based data sources; otherwise every user needs
to be granted read access to the file on the server. With this option, the external table will be accessed using
the PI AF server's identity. In this case, you do not need to specify a username or password when configuring
the linked table, nor is Kerberos configuration required.
Caution: Take care to configure SQL security in such a way that the PI AF server's identity does not have
more privilege than necessary to retrieve the data. Only PI AF administrators are allowed to configure
external tables for security reasons. For that reason, ensure that the PI AF Administrators identity and the
Admin access right are assigned to only a limited set of users when this connection mode is enabled.
Restrictions on non-impersonated connections
Because there are security risks for linked tables that use non-impersonated connections, some PI AF server
system administrators restrict or prevent their use. Your system administrator might:
• Require administrative privileges on the PI AF server and write privileges on the PI AF table.
• Prevent creation of linked PI AF tables with non-impersonated connection.
• Prevent creation of any linked tables.
If you have problems with linked tables, consult your system administrator about the PI AF server external table
settings.
Risk of using non-impersonated connections
Depending on the configuration of the SQL Server, a user with PI AF administrator privileges could create attacks
on the SQL Server and take full control of the system if these following conditions exist:
• A PI AF table is configured to use the PI AF server identity for linking to an external database.
• Non-impersonated linked (external) tables are enabled on the PI AF server.
By default, non-impersonated linked tables are disabled on the PI AF server. In order for a user to execute an
attack, that user would need to enable non-impersonated external tables.
• The PI AF server account has administrative rights on a SQL Server.
By default, the PI AF server runs under a virtual account, NT SERVICE\AFService, and does not have
administrative rights to the locally-configured SQL Server or access to remote computer databases. Without
administrator rights to the remote database, the possibility for elevation of privilege attacks is limited.
Caution: For security reasons, do not grant the PI AF server administrative privileges on the computer or SQL
Server when running with non-impersonated queries.
Data access recommendations for linked tables
Observe the following guidelines for linked tables:
• If access to linked tables is not needed, disable it altogether.
• Do not grant the PI AF Application Service account administrative privileges on the PI AF server or SQL Server
when running with non-impersonated queries.
• You must have administrative privileges on the PI AF server to configure an external table that runs non-
impersonated queries.
Security settings for linked tables
You use the PI AF Diagnostics utility (afdiag located in the %PIHOME64%\AF folder) to enable or disable support
for external PI AF tables. Since the utility makes a direct connection with the associated SQL Server database, the
SQL Server sysadmin or db_AFadmin role is required.
Use the PI AF Diagnostics utility to adjust security settings for external tables.

Task Command Default Setting

Enable support for external PI AF tables afdiag /DT enabled

Disable support for external PI AF tables afdiag /DT-
Enable support for external PI AF tables for non- afdiag /DTImp disabled
impersonated users
Disable support for external PI AF tables for non- afdiag /DTImp-
impersonated users
Change security settings for a specific PI AF table In the Library browser, By default, table
right-click on the table and configuration requires
click Security. administrative privileges
on the PI AF server.
Change security settings for all tables In the Library browser, By default, table
right-click on Tables and configuration requires
click Security. administrative privileges
on the PI AF server.
Note: You do not have to enable support for external PI AF tables for non-impersonated users. You can include a
user ID and password as part of the connection string in a PI AF table connection and check it in, regardless of
whether support for external PI AF tables for non-impersonated users is enabled. The defined PI AF table
connection can be used within a PI AF table definition. This means that if a SQL Server Login has permission to
access the data referenced in the connection string, a PI AF table linked to that PI AF table connection can
retrieve the external data.

Create reusable table connections

Use the 64-bit PI System Explorer to configure connections to linked tables. It includes 64-bit OLE DB drivers,
which are required for the 64-bit PI AF Server.
Create an OLE DB connection and reuse it to configure linked tables from the same data source.
1. In the navigator, click Library.
2. Choose from the following actions:
▪ Select Table Connections and click New Table Connection on the toolbar.
▪ From the browser, right-click Table Connections and click New Table Connection.
Table connection properties are displayed in the viewer with a default name in the Name field.
3. Optional. Edit the default name and add a description for the table connection in the Description field.
 4. In the Connection field, you can either enter a connection string directly, or click Build to configure the
connection in the Data Link Properties window.
5. In the Provider tab of Data Link Properties, choose an OLE DB provider and follow onscreen instructions to
configure the connection.
6. Depending on the provider selected, you may need to specify the data source and location, server name,
user name, password, and/or database.
7. Click OK.
The connection string for the reusable table connection is displayed in the Connection field.
8. If prompted, enter a password and click OK.
9. In the viewer, select a Security option.
Some options may not be available.
▪ Impersonate Client (recommended)
▪ Supply Password
Note: You can use the Change Password button to change the SQL Server password required for the
table connection.
▪ No additional security context
See Authentication for linked tables for information on these options.
10. On the toolbar, click Check In to check in and save the table connection.

Access to Microsoft Access or Excel data

To access data from a Microsoft Access database or a Microsoft Excel workbook, you can link or import the data.
The data in a linked table is refreshed when the table is accessed and whenever the time since the last refresh
exceeds the table's Cache Interval setting.
Imported data is loaded into the PI AF table once. If you ever need to refresh the imported data in a table, you
can right-click the table in the Library browser and click Re-Import Table.
You can link to or import data from a Microsoft Access table or a Microsoft Excel workbook after you perform the
following steps:
• Specify the source database or workbook.
• Create a query that returns the desired data.
• Enter any login credentials required to access the database or workbook.
The exact instructions depend on your hardware configuration and what you are trying to do:

32-bit PI AF server Follow the instructions in Link or import data.

64-bit PI AF server • To import, follow the instructions in Link or import data.
• To link, follow the instructions in Link to data on a 64-bit PI AF
server.
Link or import data
These instructions describe how to import data on a 32-bit or 64-bit PI AF server and how to link to data from a
32-bit PI AF server only. To link to data from a 64-bit server, see Link to data on a 64-bit PI AF server.
1. In PI System Explorer, navigate to the PI AF table or create one as described in Create PI AF tables.
2. In the Library pane, expand the Tables node, and click the desired PI AF table.
The table details display in the right pane.
3. Click Link or Import.
The corresponding window opens.
4. Link only: If you are linking the table, enable the Impersonate Client option (not displayed for Import).
5. Click Build.
The Data Link Properties window opens.
6. On the Provider tab, select the provider according to the version of Microsoft Office that you are using and
click Next.
▪ Office 97-2003: select Microsoft Jet 4.0 OLE DB Provider.
▪ Office 2007 and higher: select Microsoft Office 12.0 Access Database Engine OLE DB Provider.
7. On the Connection tab, specify the following and click OK.
• Data Source
The location and file name of the database or workbook (such as C:\AFTestData.xls). If you are linking,
the path to the file must be relative to the PI AF server.
• User Name
Login credentials of a user that has been granted read access to the database or workbook.
Note: To store the password with the connection information, select the Allow Saving Password check
box. The password is stored as plain text (not encrypted).
8. On the Advanced tab, in the Access permissions list, select Share Deny None.
9. Excel only: On the All tab, select the Extended Properties value and click Edit Value.
The Edit Property Value window opens.
Enter the property value according to the version of Microsoft Excel that you are using, and then click OK.
• Excel 97-2003: Excel 8.0
• Excel 2007 and higher: Excel 12.0
10. To verify that the spreadsheet is accessible, return to the Connection tab and click Test Connection.
If the settings are valid, a Test connection succeeded message displays.
11. To dismiss the window and return to PI System Explorer, click OK.
12. To define the data to be returned from the spreadsheet, enter an SQL query in the Query field. To dismiss
the window, click OK.
• Microsoft Excel example: SELECT * FROM [Sheet1$]
 • Microsoft Access example: SELECT * FROM Table1
13. To review the resulting data, examine the Table tab. If the query is specified correctly, the tab contains a
table displaying the results.
14. To save your changes, right-click the table node and choose Check In.
Link to data on a 64-bit PI AF server
To link to data in an Access database or Excel workbook on a 64-bit PI AF server, you must use the 64-bit Access
Database Engine (ACE) data provider; there is no 64-bit Jet data provider.
1. In PI System Explorer, navigate to the PI AF table or create one as described in Create PI AF tables.
2. In the Library pane, expand the Tables node, and click the desired PI AF table.
The table details display in the right pane.
3. Click Link.
The corresponding window opens.
4. Enable the Impersonate Client option.
5. In the Connection field, enter a valid connection string for the Excel workbook or Access database, using the
Microsoft Office 12.0 Access Database Engine OLE DB Provider (must be installed on the PI AF server), as in
the following examples:
• Microsoft Excel example:
Provider=Microsoft.ACE.OLEDB.12.0;Data Source=c:\example.xlsx;Extended
Properties="Excel 12.0 Xml";
• Microsoft Access example:
Provider=Microsoft.ACE.OLEDB.12.0;Data Source=c:\example.accdb;Persist
Security Info=False;
6. To define the data to be returned from the spreadsheet, enter an SQL query in the Query field. To dismiss
the window, click OK.
• Microsoft Excel example: SELECT * FROM [Sheet1$]
• Microsoft Access example: SELECT * FROM Table1
7. To review the resulting data, examine the Table tab. If the query is specified correctly, the tab contains a
table displaying the results.
8. To save your changes, right-click the table node and choose Check In.

Access to SQL Server data

When you import data from or link to data in a Microsoft SQL Server table, you must define valid connection
information. The steps for linking or importing depend on the connection method that you choose, as described
in Authentication for linked tables.
Use Windows impersonated security connection
Link to or import data from a SQL Server table with the Impersonate Client option. See Data access
recommendations for linked tables.
Note: If linking to a SQL Server that is not on the same computer as the PI AF server, it may be necessary to
configure Kerberos to allow the client's identity to be forwarded from the PI AF server to the SQL Server.
1. Create a local user group for impersonated clients.
2. Configure security on the target table's database.
3. Import or link SQL server tables.
Create a local user group for impersonated clients
If the table to which you want to connect resides in a SQL Server instance other than the one where the PI AF
SQL database (PIFD) resides, ensure that the table is accessible via Windows authentication.
1. On the computer where the SQL Server instance resides, click Start > Administrative Tools > Computer
Management.
The Computer Management application starts.
2. Expand Local Users and Groups.
3. Right-click Groups and choose New Group.
4. In the New Group window, create a local user group for the users that require access to the database table.
5. Add to this group the accounts of all users that might be impersonated.
6. Click OK to add the selected users, and then click Close to dismiss the New Group window.
7. Close the Computer Management application.
Use Windows non-impersonated security
Link to or import from a SQL Server table with the no additional security context option.
1. Create a local user group for PI AF application service account
2. Configure security on the target table's database
3. Import or link SQL server tables
Create a local user group for PI AF application service account
If the table to which you want to connect resides in a SQL Server instance other than the one where the PI AF
database (PIFD) resides, ensure that the table is accessible to the PI AF application service account.
1. On the computer where the SQL Server Instance resides, click Start > Administrative Tools > Computer
Management.
The Computer Management application starts.
2. Expand Local Users and Groups.
3. Right-click Groups and choose New Group.
4. In the New Group window, create a local user group to hold the identity of the PI AF Server Application
Service.
5. Add the account of the user associated with the PI AF Server Application Service to the new group. If the PI
AF Server Application Service is running under the NT AUTHORITY\NetworkService account, then add the PI
AF server’s computer account to this group.
Note: If the PI AF Server Application Service is running as the Local System or Local Service account, you
most likely need to use SQL Server authentication (SQL Server and Windows authentication mode) instead of
Integrated security. In order to avoid malicious attacks on the SQL Server, OSIsoft does not recommend using
 Local System. Instead use the Network Service or Local Service account or a specifically created account with
limited privileges.
6. Click OK to add the selected user.
7. Close the Computer Management application.
Use SQL Server security
If you are connecting to a remote SQL Server instance, ensure SQL Server is configured to accept Remote
Connections.
If you are using a SQL Server account, ensure the SQL Server instance is configured to allow mixed mode
authentication.
Link or import data from a SQL Server table using SQL Server authentication.
1. Create a SQL Server user.
2. Configure security on the target table's database.
3. Import or link SQL server tables.
Create a SQL Server user
If the target table (the table to which you want to connect) resides in a SQL Server instance other than the one in
which the PI AF database (PIFD) resides, create a user and enable database access for the user as described in
this topic.
1. Open Microsoft SQL Server Management Studio and connect to the SQL Server Instance that contains the
target table.
2. Under the SQL Server Instance, expand the Security folder and then expand the Logins folder.
3. Create a new Login and enter a name in the Login Name field.
4. Select the SQL Server Authentication option.
5. Enter the password in the Password and Confirm Password fields.
6. From the Default Database list, select the database that contains the target table.
7. Select the User Mapping page.
8. Select the row for the Database that contains the target table.
9. Select the Map check box for the selected database.
10. Click OK to close the Login – New window and save the new Login.
11. Expand the Databases folder, then the folder for the target database, and grant the necessary permission to
execute the query that will be used to the Login just created.
For example, if the query that will be used is a SELECT statement that specifies a single table, expand the
Tables folder for the target database, expand the Tables folder, then right-click the table to which the query
refers and choose Properties.
12. In the Table Properties window, select the Permissions page, then the Login, then Grant the Login the Select
Permission. Click OK to close the Table Properties window.
13. Close Microsoft SQL Server Management Studio.
Configure security on the target table's database
Any account under which the specified query might be executed needs to be granted permission to execute that
query.
1. Open Microsoft SQL Server Management Studio and connect to the SQL Server Instance that contains the
target table.
2. Under the SQL Server Instance, expand the Security folder, and then expand the Logins folder.
3. Right-click the Logins folder and choose New Login.
4. Use the Search button to find the group created in the previous section and choose that group for the Login
name.
5. Select the Windows authentication option, and select the database that contains the target table as the
Default database.
6. Select the User Mapping page.
7. Select the row for the Database that contains the target table.
8. Select the Map check box for the selected database.
9. Expand the Databases folder, then the folder for the target database, and grant the necessary permission to
execute the query that will be used to the Login just created.
For example, if the query that will be used is a SELECT statement that specifies a single table, expand the
Tables folder for the target database, expand the Tables folder, then right-click the table to which the query
refers and choose Properties.
10. In the Table Properties window, select the Permissions page, search for and select Login, then Grant the
Login the Select Permission and click OK to close the Table Properties window.
11. Close Microsoft SQL Server Management Studio.
Import or link SQL server tables
Whether you are importing from or linking to Microsoft SQL Server tables, the process is essentially the same.
The following instructions describe how to link to an existing PI AF table using the PI System Explorer.
1. To browse to the target PI AF table, display the Library pane, expand the Tables node, and click the desired
table.
Table properties display in the right pane.
2. Click Link.
The Table Link window opens.
3. Click the Connection down arrow, then click Build.
The Data Link Properties window opens.
4. On the Provider tab, select SQL Server Native Client 11.0.
5. On the Connection tab, configure the SQL Server instance that contains the database to which you want to
connect.
6. Configure authentication:
 • For Integrated security, select the Use Windows NT Integrated Security option. See Authentication for
linked tables for more information.
• For SQL Server security, select the Use a Specific user name and password option. Then, enter the SQL
Server Login name in the User Name field. Click to unselect the Blank password checkbox and specify
that a password be required. Enter a password in the Password field.
Note: Ensure that support for external PI AF tables for non-impersonated users has been enabled with
the afdiag /DTImp command.
7. Click the Select the database down arrow and choose the database that contains the table to which you
want to connect.
8. To verify that connection settings work, click Test Connection. If the settings are correct, PI System Explorer
displays a success message.
Note: Test Connection verifies that the account with which the PI System Explorer is running has access to
the specified database. However, if you choose Windows NT Integrated Security in the Table definition and
choose the No additional security context option for table connection security, the account associated with
the PI AF Server Application Service is used to connect when a user displays the data by viewing the Table
tab.
9. Click OK.
10. If prompted, enter a password and click OK.
You are returned to the Table Link window.
11. In the Query field, specify the SQL query that returns the desired data and click OK.
If the connection string requires a user ID and password, select the Supply password option. To change the
password used connect to the SQL table, click the Change Password button and enter the new SQL login
password. This replaces the value previously entered in the Password field.
12. To display the data retrieved by the query, view the Table tab.
13. On the toolbar, click Check In to check in and save the table connection.

Remove control characters from imported AF tables

After importing or linking data from an external data source, you should inspect AF tables for control characters,
such as carriage returns and line feeds prior to executing a query. The presence of control characters can cause
an AF table lookup query to fail. Remove control characters from these tables to avoid issues with retrieving
query results. See WHERE clause syntax for information on using the WHERE clause to obtain values from a table
column in a table lookup data reference.
In AF tables, cells highlighted in yellow indicate the presence of control characters. If the table contains imported
data, you can view and remove control characters using the Text Visualizer text box.
Note: Cells that contain control characters in linked tables are also highlighted. You can use the Text Visualizer to
view these control characters, but you cannot edit or remove them.
1. In the Library browser, navigate to the imported or linked table.
2. Click the Table tab.
3. On the Table tab, locate cells highlighted in yellow.
4. Place your mouse pointer over the highlighted cell and then click the cell.
 A tool tip displays the cell contents and the <*Contains Control Characters*> text.
5. Right-click the highlighted cell, then click Show Selected Cell's Content.
The Text Visualizer text box opens.
6. Click the Show Control Characters check box to display all control characters in the cell.
Note: The Text Visualizer text box is read-only when control characters are displayed. You cannot edit cell
contents or delete control characters in an imported table when the Show Control Characters option is
selected. You must deselect the Show Control Characters option before you can edit cell contents in an
imported table.
7. Click the Show Control Characters check box to deselect the option and hide all control characters.
8. Optional: If you have imported data into an AF table, you can remove all control characters, such as carriage
returns (<CR>), spaces (·), and line feeds (<LF>), to ensure only essential characters remain.
9. When all control characters have been deleted, click OK.
The cell is no longer highlighted in yellow after control characters have been removed.
10. Repeat steps 3-9 to continue viewing and removing control characters in an imported table.
11. To save your work, right-click the table in the Library browser and select Check In.

Configure table lookup data references

Create a table lookup data reference when you want an attribute to obtain its value from a table column.
1. In the Elements or Library browser, select the desired element or element template.
2. In the viewer, select the attribute or attribute template for which you want a table lookup value.
3. In the Data Reference field in the palette, choose Table Lookup from the list.
4. Click Settings.
5. In the Table Lookup Data Reference window, select a previously defined table from the Table drop-down list.
You can also choose from the following options:

▪ Click (Manage Tables) to open a list of tables you can search or filter. To select a table, highlight it in
the list and click OK.

▪ Click (Table Properties) to view or edit properties for the selected table.

▪ Click (Create New Table) to define a new table.

6. From the Result column list, select the column in the table from which you want to read the value.
Note: Select the Stepped check box for the value to be stepped when plotted in a trend. With this setting,
there is no interpolation between the table values.
7. From the Unit of Measure list, select the appropriate unit of measure in which the data in the result column
is stored.
Note: It is preferable to set the UOM directly in the table definition so that you do not need to specify it with
each table lookup.
8. In Time Zone, you can define a setting if it has not previously been set in the table or column definition.
 9. From the Rule list, choose an option:
▪ Select first row matching criteria
Use the Order by list to specify the sorting order. This order is used to select a row when more than
one row matches the criteria. For more information, see Select first row matching criteria.
▪ Summarize all rows matching criteria
Select a summary operation from the Summary list to perform the selected operation on the
selected column over the range of rows that match the criteria. For more information, see
Summarize all rows matching criteria.
▪ Table provided time series data
Choose this option if the table has values with associated time stamps and you wish to treat these
values as time series data. From the Time Column list, select the table column that contains the time
stamps you want to use. Only columns with a value type of DateTime are listed. The WHERE clause is
not required when you choose this option. For more information, see Table provided time series
data.
Note: To ensure that columns with DateTime value types are displayed, only specify time zone
settings on the General tab of the overall table definition. Do not specify time zones on the column
definition (on the Define Table tab).
10. In the Where pane, use the menus and buttons to build the table query.
Note: You can manually type the entire clause into the Complete WHERE Clause text field. See WHERE
clause syntax for more information.
• From the Column list, select the column of the table to use in the query.
• From the Operator list, select the relational operator to use in the query.
• From the Attribute or Value list, select an attribute or a literal value to use in the query.
• Click Add And or Add Or to write the WHERE clause into the Complete WHERE Clause field with an AND
or an OR operator.
• Edit the clause in the Complete WHERE Clause field as needed.
Note: The Add And or Add Or buttons automatically generate the necessary syntax, UOM, and time zone
conversions when possible.
11. Optional. Edit values for table parameters.
Table parameters apply only to linked tables. For more information, see Parameters for linked table queries.
12. Optional. For Replacement Values, choose attributes or literal values to return when the table query cannot
find a matching row or encounters a null result.

Select first row matching criteria

The Select first row matching criteria rule enables you to specify the first row that matches the value returned
from the WHERE clause.
Syntax
SELECT column FROM table WHERE where clause ORDER BY column ASC|DESC; options and
parameters
Arguments
• SELECT column
If a column name contains non-alphanumeric characters, including spaces, it must be enclosed in [ ]
brackets.
• FROM table
If a table name contains non-alphanumeric characters, including spaces, it must be enclosed in [ ] brackets.
• WHERE clause
In addition to =, <>, >, >=, <, <=, LIKE, and IN relational operators, you can specify INTERPOLATE to
interpolate a value for the result column based on an interpolation of the specified input columns.
Beginning with PI AF 2018, you can perform two kinds of interpolation:
• Linear interpolation, in which interpolation is for 2 columns of data. To specify linear interpolation, use
INTERPOLATE(column, value) syntax.
• Standard bilinear interpolation, in which interpolation is for 3 columns of data. To specify bilinear
interpolation, use INTERPOLATE(column_X,value_X) AND INTERPOLATE(column_Y,value_Y) syntax.
Irregular bilinear interpolation and bilinear extrapolation are not currently supported.
Note: The default behavior of the INTERPOLATE operator is to extrapolate if the input value is outside
the observed table range. Note also that extrapolation behavior changes when the Stepped check box is
selected.
For more information on WHERE clause syntax, see WHERE clause syntax. For examples of INTERPOLATE
operator usage, see Examples of linear and bilinear interpolation in table lookup data references.
• ORDER BY column
Optional. Specifies the sorting order so that the correct row is used when more than one row matches the
WHERE clause. Ascending (ASC) order is the default unless descending (DESC) is specified.
• Options
You can enter the following options in a list separated by semicolons.
Stepped When set to True, the returned value plots as stepped in applications.

TZ=time zone Specifies the time zone of the source table.

Note: Set the time zone in the general description of the table, so that you
do not need to specify it with each table lookup.

UOM=uom Specifies the unit of measure for the value returned by the result column.
Note: You can also set the unit of measure in the table column definition, so
that you do not need to specify it with each table lookup.

RWM=value Specifies the value to return when there is no column match. If the value is
No Data, the digital state of No Data is returned.

RWN=value Specifies the value to return when the result column is null. If the value is No
Data, the digital state of No Data is returned.
 • Parameters
You can enter parameters in a list separated by semicolons. Begin each parameter name with the @
character in @parameter=value format (value is described in "Attribute or Value" in WHERE clause syntax).
For additional information on using parameters, see Parameters for linked table queries.
Example
SELECT [Installation Date] FROM [Equipment Specifications] WHERE [Asset ID] = '%Element%'
Examples of linear and bilinear interpolation in table lookup data references
Linear interpolation example
In a tank strapping table that contains a Level column and a Volume column, the following configuration string
interpolates the volume based on the level reading:
SELECT Volume FROM MyTable WHERE INTERPOLATE(Level, @MyLevelReading)
Assume the sample table has the following rows:

Level Volume

1 0.0
2 20.0
3 30.0
4 40.0
5 60.0
6 70.0
• A Level reading of 2.2 results in a returned Volume of 22.0.
• A Level reading of 2.7 results in a returned Volume of 20.0 when Stepped is selected (true).
• Extrapolation: A Level reading of 6.5 results in a returned Volume of 75.0 when Stepped is cleared (false).
• Extrapolation: A Level reading of 6.5 results in a returned Volume or 70.0 when Stepped is selected (true).
Bilinear interpolation example
In an air velocity table that contains an X Horizontal Position column, a Y Vertical Position column, and a Velocity
column, the following configuration string interpolates the velocity based on the X horizontal and Y vertical
positions.
SELECT Velocity FROM Table1 WHERE INTERPOLATE([X Horizontal Position], @X) AND
INTERPOLATE([Y Vertical Position], @Y)
Assume the sample table has the following rows:

X Horizontal Position Y Vertical Position Velocity

180 140 4.6

220 140 4.1
260 140 2.7
180 180 4.8
220 180 4.4
260 180 2.5
180 220 4.5
220 220 4.4
260 220 2.5
An X Horizontal Position of 245 and a Y Vertical Position of 165 results in a returned Velocity of 3.2171875.

Summarize all rows matching criteria

The Summarize all rows matching criteria rule enables you to perform a summary operation on the rows in a
table column that match your selection criteria.
Syntax
SELECT summary(column) FROM table WHERE where clause; options and parameters
Arguments
• SELECT summary(column)
If a column name contains non-alphanumeric characters, including spaces, it must be enclosed in [ ]
brackets.
You can select one of the following summary operations.
Operation Description

Sum The total of all row values.

Avg The average of all row values.
Min The minimum value of all rows.
Max The maximum value of all rows.
Count The number of rows.
StDev The extent of deviation for all row values.
Var The average measure of how far all row values differ from the mean.
None When no operation is specified:
• If the result attribute is not an array, the value of the selected column in the first
row that matches the WHERE clause is returned.
• If the result attribute is an array, an array with one value from each column of all
rows that match the WHERE clause is returned.
• FROM table
If a table name contains non-alphanumeric characters, including spaces, it must be enclosed in [ ] brackets.
 • WHERE clause
For more information on WHERE clause syntax, see WHERE clause syntax.
• Options
You can enter the following options in a list separated by semicolons.
Stepped When set to True, the returned value plots as stepped in applications.

TZ=time zone Specifies the time zone of the source table.

Note: Set the time zone in the general description of the table, so that you do
not need to specify it with each table lookup.

UOM=uom Specifies the unit of measure for the value returned by the result column.
Note: You can also set the unit of measure in the table column definition, so that
you do not need to specify it with each table lookup.

RWM=value Specifies the value to return when there is no column match. If the value is No
Data, the digital state of No Data is returned.

RWN=value Specifies the value to return when the result column is null. If the value is No
Data, the digital state of No Data is returned.

• Parameters
You can enter parameters in a list separated by semicolons. Begin each parameter name with the @
character in @parameter=value format (value is described in "Attribute or Value" in WHERE clause syntax).
For additional information on using parameters, see Parameters for linked table queries.

Table provided time series data

The Table provided time series data rule enables you to select a table containing values with a DateTime data
type, and specify the column that contains time series data.
Syntax
SELECT column FROM table WHERE where clause; TC=column; options and parameters
Arguments
• SELECT column
If a column name contains non-alphanumeric characters, including spaces, it must be enclosed in [ ]
brackets.
• FROM table
If a table name contains non-alphanumeric characters, including spaces, it must be enclosed in [ ] brackets.
• WHERE clause
Optional. For more information on WHERE clause syntax, see WHERE clause syntax.
• TC column
Specifies the column that contains time series values. If a column name contains non-alphanumeric
characters, including spaces, it must be enclosed in [ ] brackets.
 • Options
You can enter the following options in a list separated by semicolons.
Stepped When set to True, the returned value plots as stepped in applications.

TZ=time zone Not supported at the column level. You need to specify the time zone in the
Time Zone field on the General tab for the overall table.
UOM=uom Specifies the unit of measure for the value returned by the result column.
Note: You can also set the unit of measure in the table column definition, so that
you do not need to specify it with each table lookup.

RWM=value Specifies the value to return when there is no column match. If the value is No
Data, the digital state of No Data is returned.

RWN=value Specifies the value to return when the result column is null. If the value is No
Data, the digital state of No Data is returned.

• Parameters
You can enter parameters in a list separated by semicolons. Begin each parameter name with the @
character in @parameter=value format (value is described in "Attribute or Value" in WHERE clause syntax).
For additional information on using parameters, see Parameters for linked table queries.
Example
In the following example,
SELECT [Installation Date] FROM location; WHERE RowID =@id; TZ=China Standard Time;
TC=Installation Date

WHERE clause syntax

The WHERE clause uses SQL syntax and conforms in general to the syntax described on the MSDN
DataColumn.Expression Property page. You can type the clause directly into the Complete WHERE Clause field in
the Table Lookup Data Reference window, or allow PSE to provide the correct syntax by using the Column,
Operator, and Attribute or Value lists in the Where section. The WHERE clause is optional for the Table provided
time series data rule.
The WHERE clause syntax follows these guidelines.

Column Column names that contain non-alphanumeric symbols must be surrounded by

brackets:
[Asset ID] ='%Element%'
Operator • The INTERPOLATE operator is available with the Select first row matching
criteria rule.
• The comparison operators =, <>, >, >=, <, <=, IN, and LIKE are supported for
all lookup rules.
You can use the * and % characters interchangeably for wildcard characters
in a LIKE comparison. A wildcard is allowed at the start and end of a pattern,
or at the end of a pattern, or at the start of a pattern, but not in the middle
of a string. If the string in a LIKE clause contains a * or %, those characters
should be enclosed in [ ] brackets.
Attribute or Value @attribute
Returns the value of the PI AF attribute. The attribute must be enclosed in [ ]
brackets if it contains any non-alphanumeric character, including spaces, or
includes a UOM or Time Zone specification. For example:
[height] >= @[Level Gauge;UOM=m]
literal
• Strings should be enclosed in single quotes.
• Numeric values are not quoted and should be in invariant format (where the
decimal character is '.').
• Timestamps are best specified in yyyy.mm.dd hh.mm.ss format (0-23 for
hh), and enclosed in the # character. For example:
• #2015.01.30 14:00:00#
substitution
Select or enter a substitution parameter in '%substitution parameter%'
format. For more information on substitution parameters, see List of PI AF
substitution parameters.
The Like and IN operators
The LIKE and IN operators enable you to specify a non-exact match for query results in a WHERE clause. Use the
% character to specify zero, one or multiple characters at the beginning or end of a string.
Note: You can use the LIKE and IN operators as an alternative to the = operator when query results cannot be
retrieved from a table due to the presence of control characters. See Remove control characters from imported
AF tables for more information on removing control characters from an imported AF table.
Failed query example
In the following example, no data is returned by the query because the search value (ValueA) is located in a cell
that contains control characters and the = operator specifies an exact match on a value in the same cell. The
presence of control characters prevents the SELECT statement from returning an exact match.
SELECT ColumnB FROM Table1 WHERE ColumnA = 'ValueA'
Successful query examples
You can use the LIKE or IN operators to specify a non-exact match from a column that contains control
characters. Consider the following examples that execute a successful search for data in MyTable. Both ColumnA
and ColumnB contain control characters.
SELECT ColumnA FROM MyTable WHERE ColumnB LIKE '%ValueA%'
Another alternative is to use the IN operator to specify multiple values in a WHERE clause.
SELECT ColumnA FROM MyTable WHERE ColumnB IN ('ValueA', 'ValueB', 'ValueC')

Parameters for linked table queries

The query for a linked table determines which data from an external source to include in the table. You can
include parameters in the query, and, as you configure a table lookup data reference that uses the linked table,
you can specify parameter values. This enables you to use a single linked table to obtain different results in every
table lookup data reference that uses it.
Using parameters in a linked table query is useful, for example, to limit the number of rows returned from a very
large external table. You can add conditions and parameters to return more targeted results, such as all rows that
include a device or manufacturer ID number, specific for each table lookup data reference.
As you configure a linked table in the Table Link window, you can add table parameters to its query and set
default values for them. Then, in the Table Lookup Data Reference window, as you define a data reference using
the linked table, you can enter table parameter values specific for that data reference. You can also supply
parameter values programmatically using AF SDK. Parameter values can be specific values or come from other
attribute values or from pre-defined substitution variables, such as %Element%.
Add table parameters to a linked table query
As you define a linked table in the Table Link window, you can add parameters to the table query and set default
values for them.
1. Edit the text in the Query box to include the new parameter(s).
Parameter names must begin with the @ character.
2. Click inside the Parameters table to display the new parameters from the query.
3. Enter default values for each parameter to determine the default results from the query and click OK.
After you have added parameters to the query, you can specify values for them as you configure a table
lookup data reference that uses the linked table.
Example
Consider the following query for a linked table named MyTable. The WHERE clause limits the selection from an
external table (BigTable) to those rows with a particular RowID:
SELECT * FROM BigTable WHERE RowID = 101
Replace the fixed value 101 with a table query parameter @id (note that query parameter names must begin
with the @ character):
SELECT * FROM BigTable WHERE RowID = @id
Now, for every table lookup data reference that uses MyTable, you can supply different table parameter values
for @id to get different results from the query.
 For example, in the Table Lookup Data Reference window, as you configure a data reference, enter @AssetID for
the value of @id in the Table Parameters list. This sets @id to the current value of the attribute AssetID. The
corresponding query for this would be:
SELECT Result FROM MyTable; @id=@AssetId
This query returns rows whose RowID matches the current value of AssetID.

URI Builder data references

In previous versions of PI Notifications, you could define a web link or a link to a client application such as PI
WebParts or AVEVA PI Vision as content within a notification. However, because the links were disconnected
from the elements and attributes in PI System Explorer, only users with PI Notifications installed were able to go
find objects referenced in the email notification itself. Also, you could only include dynamic content as a value of
a parameter.
With URI Builder in PI AF 2016, you can configure data references that create dynamic links on event frames,
transfers, elements or models, and include the same Attribute references in String Builder and List of PI AF
substitution parameters as other data references such as String Builder or Formula. URI Builder conforms to
standard syntax rules (described in the Requests for Comments document RFC 3986 URI Generic Syntax) and
automatically handles the escaping of characters which are complex and cumbersome to enter manually. It
supports generic web links (that use http and https schemes), as well as AVEVA PI Vision links.
You can also use PI Notifications 2016 to send the link to other users via electronic mail, an instant messaging
client, or a client application such as AVEVA PI Vision.

Create URI Builder data references

When a URI Builder data reference is used in a template, value substitution takes place at run time.
Copy an existing web link or AVEVA PI Vision link and make it dynamic in a URI Builder data reference in which
you substitute part of the URI with a value derived from an attribute, an attribute reference or a substitution
parameter. You assign the dynamic web link value or AVEVA PI Vision link value to an attribute template or
attribute.
1. Open a web browser and locate the web link or the AVEVA PI Vision link you use as a starting point in
creating a link value on an attribute template or attribute.
2. Select the entire URI and copy it.
3. In the navigator pane of PI System Explorer, choose from the following actions.
To create a URI data reference on ... Do this ...

A template a. Click Library.

b. Expand Templates in the browser tree.
c. Choose a template type and select an
existing template, or click New Template.
An element a. Click Elements.
b. Select an existing element in the browser
tree, or click New Element.
 To create a URI data reference on ... Do this ...

A model a. Click Elements.

b. Select an existing model in the browser tree,
or right-click and click New Model.
An event frame a. Click Event Frames.
b. Expand a search collection for event frames
in the browser tree.
c. Select an existing event frame, or click New
Event Frame.
A transfer a. Click Event Frames.
b. Expand a search collection for transfers in the
browser tree.
c. Select an existing transfer or click New
Transfer.
4. Choose from the following actions.
▪ In the Attribute Templates tab, select an existing attribute template, or click New Attribute Template to
create a new attribute template.
▪ In the Attributes tab, select an existing attribute, or click New Attribute to create a new attribute.
5. In the attribute configuration panel, configure the attribute template or attribute as needed, and choose URI
Builder from the Data Reference drop-down list.
6. Click Settings.
7. In the URI Builder Data Reference window, click in the Paste a URI from a web browser to use as a template
for configuration field and paste the URI you copied in step 2.
8. Click Continue.
The pasted URI is displayed in the URI Builder Data Reference window, broken down into its Scheme,
Address or Host, Port, and Path field components. If the URI contains queries and fragments, those are also
displayed in the Query and Fragment fields.
9. In the URI Builder Data Reference window, choose one of the following actions.
To configure ... Do this ...

A dynamic web link Modify the components of the pasted URI as needed.
• You can choose between Scheme values of
http and https.
• You can change the Port value to any number
between 1 and 65535. The default values
for http and https schemes are 80 and
443 respectively.
• To make portions of the Path field dynamic,
select a segment. Then click and select
from the following options:
A•list of other attributes for the selected
object. Note that attributes must
appear in single quotes.
A•list of attribute references. You can also
select Search to enter search criteria
in the Attribute Search window.
A•list of commonly used substitution
parameters. For more information,
see List of PI AF substitution
parameters.
• In the Query table, you can modify Key and
Value settings as needed.
To• add a key, click . In the Key and
Value fields, type a value or click
and select from the same options as
above.
To• delete a parameter, select a key or
value and click .
 To configure ... Do this ...

A AVEVA PI Vision link a. Click the PI Vision option.

b. In the Display field, modify the value as
needed. You can also click and select
from the following options:
A•list of other attributes for the selected
object. Note that attributes must
appear in single quotes.
A•list of attribute references. You can also
select Search to enter search criteria
in the Attribute Search window.
A•list of commonly used substitution
parameters. For more information,
see List of PI AF substitution
parameters.
c. In the Parameters table, modify Key and
Value settings as needed.
To• add a key, click . In the Key field,
click , select a parameter and
assign a value. In addition to typing a
value you can select from the same
options as in step b above.
To• delete a parameter, select a key or
value and click .
When linking to a display on an event
frame, URI Builder automatically adds
Asset, Start Time and End Time
parameters. For more information on
other parameters, see the AVEVA PI
Vision topic URL parameters
reference.
10. Click OK.
Chapter 9

Units of measure in PI AF

PI AF ships preloaded with numerous standard unit-of-measure classes and conversion factors. You can extend
these classes by adding new units of measure, as well as new measurement classes. The implementation of the
units of measure (UOM) feature in PI AF is based on the International System of Units (SI).
UOM database
All PI AF databases use the same set of UOMs, which are defined in the UOM database. All UOMs have the Read
permission set, but other permissions can be set for the UOM database as a whole, as described in Configure
security for the UOM database.
Beginning with PI AF 2017 R2, users with administration privileges can review audit trail data on the UOM
database by selecting File > Audit Trail Events after they have clicked Unit of Measure in the navigator. For more
information, see Track PI AF changes with Audit Trail.
UOM classes and canonical units
In PI AF, each unit of measure is based on a UOM class. Classes represent measurable properties, such as
temperature, length, time, and mass. Each class has a canonical unit. This is the base unit from which PI AF
converts values to other units when required. For example, the canonical unit for the Length class is meter, and
the abbreviation is m.
UOM conversions in client applications
The UOM feature enables automatic unit conversions in client applications. For example, suppose a PI AF
attribute has a UOM of meter. A PI ProcessBook user who is viewing that attribute value can choose to view the
value in a different unit, such as foot. PI AF automatically converts the data from meters to feet.
UOM abbreviations
By default, UOM abbreviations within PI AF are case insensitive. Beginning in PI AF 2015 R2 (v2.7.5), you can
configure the PI System to support case-sensitive UOM abbreviations, which enables you to define abbreviations
that differ only by case, such as MV (megavolt) and mV (millivolt), or s (second) and S (Siemens).
Note: All PI AF clients must be upgraded to PI AF 2015 R2 or later before they can access a PI AF server on which
case-sensitive UOMs are enabled.
Time integral UOMs
Beginning with PI AF 2017, you can view the UOMs associated with a time-weighted total (Automatic and Per-
Day) of rate UOMs. Rate UOMs are from classes that contain time in the denominator of their Base Units of
Measure (for example, Mass Flow Rate contains Time-1, Pressure contains Time-2). Each time-weighted total
property displays the name of the UOM that will result from a summary Total (Per-Day) or TotalWithUOM
(Automatic) data call.
 UOM groups
Beginning with PI AF 2017 R2, UOM groups such as Metric, and US Customary are available so that you can map
UOMs in a UOM class to the setting that is most appropriate for your location. By selecting the Display UOM
Group option in Tools > Options, you can then see attribute values displayed in the preferred unit of measure
instead of the value selected in an attribute template's Default UOM field. For more information on the US
Customary UOM group, see the Wikipedia article United States customary units.
UOM origin
Beginning with PI AF 2017 R2, you can check the origin of a UOM definition in the UOM database. Possible
values shown in the Origin column are:
Origin Description

Unknown The origin of how the UOM was defined is unknown.

System Defined The UOM is system-defined and has not been
modified.
System Modified The UOM was system-defined but the Name and/or
Description fields have been modified.
System Replaced The UOM retains its original system-defined
abbreviation and canonical UOM values but other
fields besides Name and Description have been
modified.
User Defined The UOM was created by the user.
Video
For information on how to edit units of measure, watch this video:

Case sensitivity of UOM abbreviations

A PI AF Client that is older than PI AF 2015 R2 (v2.7.5) cannot connect to a PI System that has been enabled to
use case-sensitive UOM abbreviations. This is due to the possibility of UOM abbreviations being misinterpreted:
they are often stored in data references, analysis rules, and client application files, such as spreadsheets and PI
ProcessBook displays.
Note: You must upgrade a PI AF Client to PI AF 2015 R2 or later before it can use case-sensitive UOMs.
References to UOM abbreviations
When UOM case-sensitivity is enabled in PI AF 2015 R2 or later, any stored reference to a UOM abbreviation
requires that the correct case for the abbreviation be used. For example:
• Data references that are configured with UOMs (such as Formula data references) must use the correct
abbreviation, or else the UOM lookup fails.
• Analysis rules, such as the Convert function, fail if configured with incorrect casing: Convert('x', 'Kg')
instead of Convert('x', 'kg').
• Applications or data references that programmatically access the UOM database must use the correct casing.
 Note: You cannot use the case-sensitivity option in the PI System to alert you to any configured uses that contain
incorrect casing.
UOM names
Unlike abbreviations, UOM names remain case-insensitive in PI AF 2015 R2 or later when UOM case-sensitivity is
enabled. However, when you create a UOM abbreviation, it cannot match the name of a different UOM, even if it
differs in casing.
For example, the following is valid:

Name Abbreviation

UOM1_name UOM1
UOM2 uom1
UOM3 Uom1
The following is invalid and generates the error message: 'uom1' already exists in Unit of Measure 'UOM1' in
Unit-of-Measure Database.

Name Abbreviation

UOM1 uom
UOM2 uom1

Configuration of case-sensitive UOM abbreviations

Although case-sensitive UOM abbreviations are enabled by default in new PI AF 2017 R2 installations, for older
PI AF server versions you can change the setting for case-sensitive UOMs from the disabled state with the PI AF
Diagnostics command-line utility (afdiag).
For more information on the afdiag utility, see PI AF Diagnostics utility.
Enable case-sensitive UOM abbreviations
To enable case-sensitive UOM abbreviations, you enter afdiag /ucs on the command line.
A new UOM, millivolt with a UOM abbreviation of mV, is added to the UOM database provided that there is no
conflict with existing units of measure.
Disable case-sensitive UOM abbreviations
You can reset the PI AF server to case-insensitive UOM abbreviations with the same afdiag utility.
To disable case-sensitive UOM abbreviations, you enter afdiag /ucs- on the command line.
If any existing UOM abbreviations differ only by case, the utility does not allow the feature to be disabled and
displays a list of the conflicting abbreviations. At a minimum, you need to remove the millivolt unit of measure
that was created when you enabled case-sensitive UOM abbreviations, because millivolt (mV) conflicts with
megavolt (MV).
Base classes and derived classes
PI AF has predefined a small set of base classes, and a larger set of classes that are derived from the base classes,
called derived classes. Derived classes are simply classes that can be expressed in terms of the UOM base
classes. For example, both the Area class and the Volume class are derived from the Length class. You can define
virtually all units of measure in terms of a small group of UOM base classes.
PI AF uses the canonical unit for the base class to determine the canonical units for all classes derived from that
base class. You cannot change the canonical unit for a base class or a derived class. For example, since the Area
class is based on the Length class, the canonical unit for Area is the square meter (m²).
PI AF includes numerous standard UOMs, UOM classes, and conversion factors, but you can always add new
ones. It is not typically necessary to create a new base class, although you might occasionally want to add one
for non-physical measurements.

UOM base classes

The following predefined UOM base classes are available in PI AF.

Class Canonical unit

Electric Current ampere (A)

Length meter (m)
Mass kilogram (kg)
Moles (amount of substance) mole (mol)
Plane Angle radian (rad)
Quantity count
Ratio percent (%)
Temperature kelvin (K)
Time second (s)

Common UOM derived classes

The following predefined UOM derived classes are available in PI AF.

Class Based on … Canonical unit

Angular Velocity Plane Angle * Time-1 radian per second (rad/s)

Area Length 2 square meter (m2)

Density Mass*Length-3 kilogram per cubic meter (kg/m3)
Electric Charge Electric Current * Time coulomb (C)
 Class Based on … Canonical unit

Electric Potential Electric Current-1 * Length2 * Mass * volt (V)

Time-3
Energy Length2 * Mass * Time-2 joule (J)

Force Mass * Length * Time-2 newton (N)

Frequency Time-1 hertz (Hz)

Mass Flow Rate Mass * Time-1 kilogram per second (kg/s)

Power Mass * Length2 * Time-3 watt (W)

Pressure Mass * Length-1 * Time-2 pascal (Pa)

Specific Energy, Specific Length2 * Time-2 joule per kilogram (J/kg)

Enthalpy
Speed Length * Time-1 meter per second (m/s)

Volume Length3 cubic meter (m3)

Volume Flow Rate Length3 * Time-1 cubic meter per second (m3/s)

Create UOM classes

Create UOM classes when you need additions to the predefined classes in the UOM database.
1. In the navigator, click Unit of Measure.
2. Choose from the following actions.
▪ On the toolbar, click the New Class icon.
▪ Right-click in the Unit of Measure browser and select New Unit-of-Measure Class.
3. In the Unit-of-Measure Class Properties window, fill out the properties on the General tab.
a. In the Name field, enter a name for the class. See Valid characters in PI AF object names, if necessary.
b. Optional. In the Description field, provide a description of the UOM class.
c. In the Canonical UOM field, type the name of the canonical UOM for this class. If the UOM does not
exist, PI AF creates it when it creates the new class.
d. In the Canonical UOM Abbreviation field, enter a unique abbreviation.
e. In the Base Units of Measure field, enter a calculation for the unit of measure. Choose from the
following actions.
 To ... Do this ...

Add a base class calculation a. Click .

b. In the Add Base UOM Class window, select a
base class from the Base UOM Classes
list.
c. In the Base Power field, type the exponent
value or click one of the arrow keys until
the exponent you want is displayed.
d. Click OK.
e. Repeat these steps as needed, to create a
multiplication (positive base power) or
division (negative base power)
calculation.
Remove a base class calculation a. Select a base class calculation entry.
b. Click .
c. In the Delete confirmation window, click Yes.
Note: If you are defining a base class, leave the Base Units of Measure field blank.
1. Optional. You can add new units of measure to the class you are defining.
a. Click the Units of Measure tab.
b. Right-click in the list and select New Unit of Measure.
c. In the Unit of Measure Properties window, define the new unit of measure. For more information, see
Create units of measure.
2. Click OK.

Create units of measure

You create units of measure for a UOM class in the UOM database.
1. In the navigator, click Unit of Measure.
2. In the Unit of Measure browser, select the class to which you want to add a new unit of measure.
3. Choose from the following actions.
▪ On the toolbar, click New UOM.
▪ Right-click the class in the browser and select New Unit of Measure.
▪ Right-click in the UOM viewer and select New Unit of Measure.
4. In the Unit of Measure Properties window, enter a unique name for the unit of measure in the Name field.
Note: The name cannot be the same as a previously defined UOM abbreviation or UOM name.
5. In the Abbreviation field, enter a unique abbreviation for the unit of measure.
 If UOM case-sensitivity has been enabled, you can use the same abbreviation as a previously defined UOM
abbreviation, so long as the case is different. For example, you can use FR, fr, Fr, and fR for four different
UOM abbreviations.
Note: The abbreviation cannot be the same as a previously defined UOM name, regardless of case.
6. Optional. In the Description field, enter a description for the unit of measure.
7. In the Reference UOM field, select the unit of reference class from which the new unit can be converted. The
default value is the same as the read-only Canonical UOM value.
8. Choose one of the following conversion methods.
Caution: Conversions that are based on Formula have some limitations as well as impact on performance.
You should only select Formula when Simple conversions are inadequate.

Option Description

Simple Converts a UOM based on scaling factor and base

offset values that you enter in the following fields.
• In the Factor field, enter the conversion
factor from the reference UOM to the
new UOM. For example, °C has a factor of
1 relative to kelvin.
• In the Offset field, enter a conversion offset
from the reference UOM value. For
example, °C has an offset of 273.15 from
kelvin.
Note: Although PI AF supports time-weighted
totalizations that can automatically assign the
appropriate units of measure, it is essential that the
conversion factor of the UOM be defined to as precise
a level as possible for this feature to activate. For
example, if you were to define a flow rate UOM such
as US gallons per day with a conversion factor of
4.38126E-08, automatic conversions for this UOM
would be disabled, whereas if the conversion factor
were 4.381263638889E-08, automatic conversions
would be active.

Formula Converts a UOM based on a complex conversion

calculation. For more information, see UOM
conversion calculation with a formula.
9. Optional. To establish an alternative UOM name so that users can see attribute values returned in their
preferred UOM, in the Mappings list, select a UOM name from the Mapping list for each UOM group.
Note: Although default mappings are provided for Metric and US Customary, you can modify them as
needed. To modify multiple UOM mappings in UOM groups, use PI Builder.
10. Click OK to save the new UOM.
 UOM conversion calculation with a formula
In general, you should specify UOM conversion calculations with a scaling factor and base offset from the
Reference UOM value.
Caution: Conversions that are based on Formula have some limitations as well as impact on performance. You
should only select Formula when Simple conversions are inadequate.
Conversion calculation limitations
The following constraints exist with UOM conversion calculations.

Conversion type Limitations

Factor None.
Factor with offset For delta conversion calculations, you need to define a separate UOM.
See the Temperature (Delta) UOM class for examples.
Formula • Delta calculations are not assigned UOMs.
• Summary calculations over a range of data are not assigned UOMs.
This affects analysis expression functions, such as Maximum,
Minimum, Popular Standard Deviation, Range, Standard Deviation,
and Total. It also affects programmatic Summary data calls against
PI point data references with a UOM assigned.
• Searches for attribute values exclude attributes whose value is
measured in formula UOMs.
UOM formula evaluation
PI AF uses C# for UOM formula evaluation. Follow these guidelines:
• Write all Units of Measure in terms of the UOM abbreviation. If an abbreviation is not a valid C# variable
name, enclose it in brackets.
• Adhere to C# evaluation rules.
• You can optionally invoke standard .NET static methods, such as Math.Log10(), to perform the computation.
You are limited to what is available in the System Assembly (.NET Framework Math Class).
Formula conversion method example
As an example, watts (W) is the canonical UOM in the Power class. To create a UOM of Decibel-milliwatts (dBm)
in the Power class, you could enter the following formula:
W = Math.Pow(10,(dBm - 30)/10)
dBm = 10 * Math.Log10( W ) + 30

Calculate conversion values for a UOM

Use the Unit of Measure Conversion Calculator to convert a given UOM quantity into an equivalent value for
other members in its class.
1. In the navigator, click Unit of Measure.
 2. In the Unit of Measure browser, select a UOM class.
3. In the Quantity field of the Conversion Calculator pane, enter the quantity you want to convert.
4. Optional. In the UOM field, change the UOM from the default value to another UOM in the class.
Converted values for each UOM in the class are displayed.

UOM groups
Beginning with PI AF 2017 R2, units of measure that are included as part of PI AF are mapped to UOM groups,
such as Metric and US Customary. Once you have selected which UOM group you prefer to use at your location,
you can display all attribute values with units of measure mapped to that UOM group rather than the default
UOMs that are defined in attribute templates.
You select which UOM group you prefer in Tools > Options. When no preferred UOM group is selected, all
attribute values are displayed with the default UOM defined in attribute templates, unless Use Source Unit-of-
Measure for attribute display is also selected. For more information, see PI System Explorer customization
options.
Sample mappings for a UOM class
As an example, the table below illustrates mappings for the Length UOM class.

UOM Metric UOM group US Customary UOM group

centimeter inch
foot meter
inch centimeter
international nautical mile
kilometer mile
meter yard
millimeter sixteenth of an inch
sixteenth of an inch millimeter
yard meter
If a mapping is not defined, such as international nautical mile, a UOM is not mapped and uses the original UOM
setting.
UOM database
UOM groups are available to all users and are stored on the PI AF server as part of the UOM database. Each
user's UOM group selection in Tools > Options is also stored in the UOM database.
Users with permission to modify the UOM database can modify the UOM groups and mappings, including those
shipped by default. For more information, see Configure security for the UOM database.
 UOM database import/export
You can import and export UOM groups, as well as their mappings, with File > Export to File and File > Import
from File. When you export, ensure that Include All Referenced Objects option is selected.

Manage UOM groups

To create, modify, and delete UOM groups, you must have Write permission for the UOM database.
In addition to the Metric and US Customary UOM groups that are installed with PI System Explorer, you can
create additional UOM groups to which you can map units of measure. You can also modify and delete group
names and descriptions.
1. To manage UOM groups, click Unit of Measure in the navigator.
2. Choose from the following actions.
▪ On the toolbar, click the UOM Groups icon.
▪ Click File > UOM Groups.
3. Choose from the following actions.
To... Do this...

Create a new group a. Click New UOM Group.

b. In the Unit-of-Measure Properties window,
enter a unique name for the UOM group
in the Name field.
c. Optional. In the Description field, enter a
description for the UOM group.
d. Click OK. The new group is added to the list
in the UOM Groups window.
Modify a group a. Select the group you want to modify and
click Properties.
b. In the Unit-of-Measure Properties window,
make changes as needed to the name
and/or description.
c. Click OK.
Delete a group a. Select the group you want to delete and click
Delete.
b. In the Delete confirmation window, click Yes.
Note: If the deleted UOM group was
previously selected in Tools > Options on
the General tab, the Display UOM Group
value is reset to <None>. Attributes are
reset to the default UOM defined in the
associated element template.
 4. Check in your changes to the UOM database.

Origin of UOMs
Beginning with PI AF 2017 R2, you can check the origin of a UOM definition in the UOM database. The Origin
field is included in the Unit of Measure Properties window, as well as the UOM viewer. It is also supported in PI
Builder.
Possible values shown in the Origin column are:

Origin Description

Unknown The origin of how the UOM was defined is unknown.

System Defined The UOM is system-defined and has not been modified.
Note: If only a UOM mapping is changed, Origin remains set to System Defined.

System Modified The UOM was system-defined but the Name and/or Description fields have been
modified.
System Replaced The UOM retains its original system-defined abbreviation and canonical UOM
values but other fields besides Name and Description have been modified.
User Defined The UOM was created by the user.
If a UOM is modified that results in Origin being set to either System Modified or System Replaced, but is later
reset to the original definition, Origin also reverts to System Defined.
Chapter 10

Security configuration in PI AF

PI AF supports both claims-based authentication via OpenID Connect (OIDC) and integrated Windows security for
authentication. PI AF also provides its own authorization to PI AF objects through PI AF identities and mappings.
You can map roles to PI AF identities on claims-aware PI AF servers. See Map a role to a PI AF identity for more
information.
Note: The security configuration information described in this section presumes a PI AF 2015 server and a PI AF
2015 client.
The PI AF security model enables administrators to configure access for PI AF identities at each level of the PI AF
hierarchy. PI AF uses Windows integrated security to grant or deny connection to the PI AF server, view or edit
databases, and change collections.
For detailed information on how security is implemented on Data Archive, see Data Archive security.
Video
For information on how to create, map, and grant permissions to PI AF identities on a PI AF server that uses
Windows authentication, watch this video:

PI AF identities and mappings

A PI AF identity represents a set of access permissions on the PI AF server. Each PI AF mapping points from a
Windows user or group or an Identity provider (IdP) role to a PI AF identity.
A role represents a group of users with similar job functions and access permissions. Roles are stored and
managed by the IdP service. The AVEVA Identity Manager is the provided identity service for PI Server 2023. A
role that is mapped to a PI AF identity inherits the access permissions for that identity.
Beginning with PI AF Server 2015 (v2.7), you cannot directly grant a Windows user or group access to a PI AF
server resource (such as an element collection or objects). Instead, you create a PI AF identity that has that
access and then you create a PI AF mapping between the Windows user or group and that PI AF identity.
Members of the Windows groups that are mapped to a PI AF identity are also automatically granted the access
permissions for that PI AF identity. For example, in the following illustration, the PI AF identity called Engineers
has read/write access to the Elements collection. Because the Active Directory (AD) group Engineering Team is
mapped to Engineers, all the members in that AD group get read/write permission for the Elements collection.
AD group mapping to a PI AF identity
Multiple identities
A single Windows user can be mapped to multiple PI AF identities, typically via mappings of the various Windows
group memberships to which he or she belongs. A user is granted permissions based on all the PI AF identities to
which he or she is mapped. Effective permissions are determined by taking the union of all identities' allowed
permissions and removing the union of all denied permissions. For example, in the following illustration, the
Windows user Bob belongs to both AD groups. Bob therefore gets the permissions that are configured for PI AF
IDENTITY1 and PI AF IDENTITY2.
Windows user with cumulative access permissions
 Additionally, a user must have read permission on a PI AF database to be able to read any object within it.
Likewise, a user must have write permission on a PI AF database to write to any object within it.
For more information on working with identities and mappings, see Manage identities in PI AF and Manage
mappings in PI AF.

Built-in PI AF identities
The following table includes a list and descriptions of all the built-in PI AF identities.

PI AF identity Description

Administrators By default, this identity has all access permissions to every collection
and object on the PI AF server, including all databases. It cannot be
modified or deleted. Mappings, however, can be added and removed,
and this identity can be denied access permissions to objects if the
need arises.
Access to this identity should be restricted to only a few users.
PI AF identity Description

Asset Analytics (Part of PI Analysis Service installation.) This identity has the necessary
access permission to work with analyses. By default, the account used
to run PI Analysis Service is mapped to this identity during installation.
Mappings to this account can be added or removed.
Asset Analytics Recalculation (Part of PI Analysis Service installation.) This identity has Execute
permission, allowing users mapped to it to backfill and recalculate
analyses.1
Engineers This identity has the same privileges as Administrators, with the
exception of the Admin (a) permission. This identity is also not allowed
to delete PI AF databases.
This identity should be restricted only to users who are defining the
asset database. Additional identities should be created to narrow the
scope of access within PI AF.
Notifications (Part of PI Notifications Service installation.) This identity has the
necessary access permission to work with notification rules. By default,
the account used to run PI Notifications Service is mapped to this
identity during installation. Mappings to this account can be added or
removed.
Owner This read-only identity can be explicitly added to the security
configuration of specific PI AF objects to enable administrator users to
configure privileges for the owner of an object. The following
restrictions apply:
• You cannot add mappings to this identity.
• You cannot modify, disable, or delete this identity.
• Beginning with PI AF 2018 SP2, this identity no longer automatically
has Read and ReadData permission. Read and ReadData permission
must be set in another of the user's mapped identities.
World This identity has read access permissions to every collection and object
on the PI AF server. It cannot be modified or deleted. Mappings,
however, can be added and removed.
By default, this identity is mapped to the Windows Everyone users
group.
1
If you have installed 2017 (version 2.9) or later versions for the first time, users need to be added to the Asset Analytics Recalculation
identity in order to backfill or recalculate. If you are upgrading from versions prior to 2017 (version 2.9), all users will automatically be
mapped to Asset Analytics Recalculation identity. It is recommended that upon upgrading, such automatic mapping for all users is
removed and users that require backfilling or recalculation permissions are explicitly mapped.

Note: In a typical installation, for security reasons, we recommend providing users with identities that grant
them the minimum viable permissions to perform the tasks for their business needs.
Security hierarchy
PI AF supports both OpenID Connect (OIDC), used for implementing claims-based authentication, and Windows
integrated security to authenticate users and establish their PI AF identities through mappings.
If you use OIDC for authentication, you can map Identity provider roles to PI AF identities to assign a group of
users to one or more PI AF identities.
PI AF uses the PI AF identities to control read, write, delete, and various other permissions on PI AF components
shown in the following illustration. Each securable PI AF object (element, event frame, and notification, and so
on) throughout the hierarchy has an associated security descriptor that contains the access permissions
information for that object.
All PI AF objects of the same type belong to a collection. For example, every PI AF element in a database belongs
to the Elements collection for that database. Each collection also has an associated security descriptor that
contains access permission information. Security descriptors for some collections are configured for an entire PI
AF server (such as Identities and Mappings), whereas others (such as Analyses, Elements, and Event Frames) can
be configured for a specific database.
PI AF hierarchy of securable collections
 For more information on collection security, see PI AF collection security.

Security inheritance of PI AF objects

The following table provides details on the security that is required to create specific objects.

Object Security inheritance

Element A child element inherits the security of its parent element if it is added as a Parent-
Child (strong) or Composition reference. For more information, see Permission
inheritance of element objects.
The security rights of an element created at the database level are derived from the
Element collection associated with a PI AF database. For more information, see PI AF
collection security.
Event frame A child event frame inherits the security of its parent event frame if it is added as a
Parent-Child (strong) reference. If an event frame does not have a Parent-Child
reference, security rights are derived from the event frame template if it was created
from a template. If it was not created from a template, security rights are derived
from the Event Frame collection associated with a PI AF database.
Note: To allow users to make changes to event frames that are based on a template,
but prevent them from modifying the source template, you configure security rights
on the event frame template by setting the following access permissions for the
associated PI AF identities:
• To prevent users from accessing or modifying an event frame template, clear the
Allow check box on the Write permission in the Security Configuration window.
See Configure security for objects to learn how to set access permissions for PI AF
identities.
• Select the Write Data permission to enable users to make changes to event frames
that are based on the template.
• Select the Read Data permission to give users the ability to view and read the
event frame object. Granting the Read Data permission on an object also grants
the Read permission.
See PI AF access rights for more information on access permissions.
Transfer If a transfer is created from a template, security rights are derived from the template.
If it was not created from a template, security rights are derived from the Transfer
collection associated with a PI AF database.
Case Security rights are derived from the analysis that owns the case.
For all other types of objects, initial security access rights are calculated from the corresponding collection
associated with a PI AF database. For example, security access rights for a notification are initially derived from a
PI AF database's Notification Rule collection.
Note: When an analysis or analysis template is associated with a legacy notification or notification template,
(Notifications 2012 or earlier), security access rights for the two objects are synchronized.
Permission inheritance of element objects
When you change access permissions for an element, the access permissions for any parent or child elements
might also change. The behavior depends on the reference type.
Parent-child reference type
When an object or collection is created, a default set of access permissions is assigned, based on the access
permissions that are set on the parent. When access permissions are set on a parent, the following Child
Permission settings on the Permissions page of the Security Configuration window are evaluated:

Option Description

Do not modify child permissions Prevents access permissions that have been set for the current object
or collection from being replicated to child collections and objects in
the PI AF hierarchy.
This option is the default when the connected PI AF server is running
2.5 and earlier versions.
Update child permissions for For each selected item on the Items to Configure list in the Security
modified identities Configuration window, replicates the access permissions for all child
collections and objects for each identity on the Identities list whose
access permissions have been modified.
This option is the default when the connected PI AF server is running
2.6 and later versions. This option is not available when the connected
PI AF server is running 2.5 and earlier versions.
Replace child permissions for all For each selected item on the Items to Configure list in the Security
identities Configuration window, replaces all child permissions for every identity
on the Identities list with the parent access permissions.
Note: Before you apply this option, be sure to review access permission
settings for all items on the Items to Configure list to avoid
unintentionally overwriting custom permissions that may have been
applied elsewhere in the collection hierarchy. Review the following
example for clarification.

Examples
The following hierarchy has three elements, each with a different access permissions setting.
Sample element hierarchy
 • The Administrators and World identities have access permissions to all three elements: EasternUS,
SavannahSite, and ProductionLine1.
• The Savannah_IT identity has access to the SavannahSite element.
• The SavnEngineers identity has access to the ProductionLine1 element.
Access permissions for sample hierarchy

Suppose you want to add a CorporateEngineering identity to each element in the hierarchy. You would add the
identity to the parent element EasternUS:
Add identity to parent element
To replicate the parent permissions without affecting identities already assigned access permissions, you would
set the Child Permissions option to Update child permissions for modified entries. The security string for all
three elements shows that the CorporateEngineering identity has been added, but the other identities remain
unchanged:
Replicate identity and modify existing access permissions

To replicate the parent permissions for all identities down the hierarchy, you would set the Child Permissions
option to Replace child permissions for all identities. The security string for all three elements shows that the
 CorporateEngineering identity has been added, but has replaced the access permissions with those assigned to
the EasternUS element:
Replicate identity and replace existing access permissions

Notice that the Savannah_IT and SavnEngineers identities no longer appear in the security string for the
SavannahSite and ProductionLine1 elements because they were not included in the Identities list of the parent
EasternUS element.
Composition reference type
Access permissions for child and parent are always the same.
If you change the access permissions for the child, the parent access permissions are automatically changed to
match the child permissions. Similarly, if you change the access permissions for the parent, the child access
permissions are automatically changed to match the parent permissions. These changes cascade down (and up)
through the hierarchy.
Weak reference type
Access permissions are never inherited.

PI AF access rights
The following table describes the access permissions you can assign to PI AF identities for all objects in the
hierarchy.
Access right Security string Definition
abbreviation

Read r Enables a user to view the object. Read security rights are
required to view the object in client applications. The Read
permission also enables a user to view configuration values
from attributes of elements.
The following objects always have Read permission
regardless of their security settings, so long as the logged-
in user has Read access to the PI System and the PI AF
database. The one exception is the notification contact
template, where the logged-in user only requires Read
access to the PI System:
• Analysis template
• Categories
• Element template
• Enumeration set
• Event frame template
• Model template
• Notification contact template
• Notification template
• Reference type
• Transfer template
• UOM database
Write w Enables a user to create and modify an object. The
exception is that event frames and transfers also require
Write Data permission on the element template from
which they are created, and cases require Write Data
permission on the analysis in which they are contained.
Read/Write Not applicable Enables a user to read and write to the associated object.
When selected, automatically selects the Read and Write
permissions.
Access right Security string Definition
abbreviation

Read Data rd Enables a user to read non-configuration values from

attributes of elements (the Configuration Item property for
an attribute is cleared). Additionally, this permission
controls whether a user can see transfers created from a
specific transfer element template. Similarly, it controls
whether a user can see cases created in a specific analysis.
If the following objects have Read Data permission, they
are also granted Read permission:
• Case
• Element
• Event frame
• Model
• Notification
• Transfer
Write Data wd Enables a user to write non-configuration values to
attributes of elements (the Configuration Item property for
an attribute is cleared). Additionally, this permission
controls whether a user can create or modify event frames
or transfers created from a specific transfer element
template. Similarly, it controls whether a user can create or
modify cases in a specific analysis.
Read/Write Data Not applicable Enables a user to read data and write data to the
associated object. When selected, automatically selects the
Read and Write Data permissions.
Delete d Enables a user to delete an object. Delete security rights
are required to delete an object, either directly or indirectly
by removing it from other objects.
Note: All users have Delete permission on the PI System
regardless of other security settings as long as the logged-
in user has Read access to the PI System. This permission
enables the user to remove an AF Server from a list of
registered servers on the local machine only.

Execute x Enables a user to queue backfilling or recalculation of

analyses in the analysis service. It also enables a user to
perform most actions on an analysis case.
 Access right Security string Definition
abbreviation

Admin a Enables a user to modify the security settings, or owner, of

an object. Administration security rights are required to
force an Undo Check Out on an object that is checked out
to another user, as well as to lock and unlock an event
frame.
Note: Users with the administration permission on the PI
AF server object are granted all rights not only to the
system, but to all objects within the system, including
databases.

Subscribe s Enables a user to subscribe and unsubscribe to a

notification.
Subscribe Others so Enables a user to subscribe and unsubscribe other users to
a notification.
Annotate an Enables a user to annotate and acknowledge event frames.
Note: This access right was added in PI AF 2016. After an
upgrade from earlier server versions, objects with the
Write Data (wd) access right are granted the Annotate
access right automatically. Both client and server upgrades
must use this new permission.

PI Data Archive permissions

In order to connect to a Data Archive server, PI AF requires that Read permission be configured on that server.
Note that because determining the permissions on a Data Archive server requires an actual connection to be
made, the full list of Data Archive servers configured on a client machine is always available. Data Archive also
always has Delete permission.

Deny permission option

You select the Deny option for these cases:
• To exclude a subset of an identity mapping that has allowed permissions.
• To exclude one special permission when you have already granted full control to an identity.
Note: PI Module Database does not support the Deny option. If you are using both PI MDB and PI AF, avoid the
Deny option to prevent synchronization problems. In addition, if a user is mapped to an identity that has the
Admin permission assigned at the server level, any Deny option will be overridden.
Security Configuration window
You can view and configure access permissions for identities, and also look up a user's permissions and
restrictions by assigned identities in the Security Configuration window. Access permissions are shown for both
Windows domain users and users who have signed on using claims-based authentication.
You can open the Security Configuration window in PI System Explorer anywhere a Security link appears in a
window or Security is displayed on a context menu.

Permissions tab
You can view and configure access permissions for individual or multiple items by a PI AF identity on the
Permissions tab of the Security Configuration window.

Note: If you signed on using OpenID Connect (OIDC), the Effective Access tab displays the current user's
permissions on PI AF objects.
Items to Configure list
The content of the Items to Configure list is determined by the hierarchy context and indicates whether you can
configure access permissions for the entire PI AF hierarchy, a single database and containers, or a single
container and single object.
 To configure access permissions for only some of the items, you can clear those you do not want to configure.
Identities list
The Identities list contains a list of identities that have permissions for all checked items in the Items to
configure list. You use the Add and Remove functions to manage which identities appear on the list.
If the currently connected PI AF server does not support identities (PI AF 2014 or earlier), the Security
Configuration window displays access permissions for Groups or Users and you can add and remove Windows
accounts using standard Active Directory windows.
Permissions list
As each identity is selected in the Identities list, the permissions associated with that identity for the checked
entries in the Items to Configure list are shown in the Permissions list. You can allow or deny permissions as
desired for each identity without losing the changes. The access permissions you set for each identity are
retained until you click the OK, Cancel, or Apply button.
Note: If more than one Items to Configure entry is selected and the currently selected identity has one of the
permissions in one or more, but not all entries selected in the Items list, the checkbox for that permission
displays a dot ( ) to indicate some entries in the Items list have the permission set whereas some do not.

Effective access tab

Effective access allows you to see a user's overall access permissions on PI AF objects, such as databases and
collections. Access permissions are based on the user's current PI AF identity mappings. Each identity has its own
set of access permissions on the PI AF server. Access permission settings allow or deny a user the ability to read,
write, delete, and take additional actions on objects. A user's access rights are determined by "merging" or
taking the union of all identities' allowed permissions and removing the union of all denied permissions. A user is
then granted effective access to items based on the "merged" permissions of his or her mapped identities.
For example, the Windows user Maria is a member of the PI AF Engineers, Administrators, and Plant Operators
identities. Both the Engineers and Administrators identities can read analyses, but the Plant Operators identity is
denied access to reading analyses. As a result, Maria's effective access in PI AF is the ability to read analyses. To
learn more about identities and mapping, see PI AF identities and mappings.
Effective Access tab

Account section
The Account section is where you enter a Windows domain user name, for example rsmith, to begin viewing his
or her permissions on items. The user's security identifier and identity mappings are also displayed in this
section.
 Note: If you are using OpenID Connect (OIDC) for claims-based authentication and role mapping, the Effective
Access tab shows the OIDC user's permissions on PI AF objects. The User SID field is not shown.
Items to View Access list
The Items to View Access list is based on the items selected for security configuration on the Permissions tab. To
view a user's permissions on an item, select the item in the Items to View Access list.
Permissions list
You can view a user's specific access permissions on a selected item in the Permissions list. For more information
about assigned permissions, see PI AF access rights.

View effective access by user

Use the Effective Access page of the Security Configuration window to view details about a user's access
permissions on PI AF objects.
To display a user's access permissions, you need the user's Windows domain name.
1. Choose one of the following methods to open the Security Configuration window:
To open from ... Do this ...

PI AF Server Properties window a. On the toolbar, click .

b. In the PI AF Server Properties window, click
the Security link.
Select Database window a. On the toolbar, click the Database button.
b. In the Select Database window, click the Edit
Security button.
PI System Explorer browser a. Right -click an object or collection and click
Security.
b. In the PI AF Server Properties window, click
the Security link.
2. In the Security Configuration window, click the Effective Access tab.
3. In the Domain User field, enter a user's Windows domain name whose permissions you want to view. If you
are using OIDC, enter the user's name in the OIDC User field.
4. Press Tab or Enter to validate your entry.

Note: You can click next to the Domain User or OIDC User field to search for a user's Windows domain
name.
The fields and lists on the Effective Access page are populated with the following information:
• User SID field: Displays the user's security identifier
• Identities list: Lists all the PI AF identities that are mapped to the Windows domain user account entered
in step 3
 • Items to View Access list: Displays the item(s) selected for security configuration. This list is reflective of
the item(s) shown in the Items to Configure list on the Permissions card.
• Permissions list: Displays the access permissions for the currently selected item in the Items to
Configure list.
Note: If you are using OpenID Connect (OIDC) for claims-based authentication and role mapping, the
Effective Access tab shows the OIDC user's permissions on PI AF objects. The User SID field is not shown.
5. Click-and-drag the horizontal splitter bar up or down to adjust the amount of information shown in the list
boxes.
6. Select a different item in the Items to View Access list.
The user's access permissions for the selected item are displayed in the Permissions list. To learn more about
access rights, see PI AF access rights.
7. Repeat step 6 as needed to view access permissions for other items.
8. Click OK to exit the Security Configuration window.

PI AF server security
When PI AF Server is first installed, admin access (all permissions) is given to the built-in Administrators identity,
and read access to all objects and collections is given to the World identity. For all other identities that are
mapped to Windows users and groups, an administrator needs to configure appropriate access to the PI AF
server, databases, collections and objects.

Configure security for a PI AF server

To connect to a PI AF server, an identity must have read permissions to the PI AF server object.
Configure access permissions for a connected PI AF server so that a PI AF identity can access databases,
collections and objects.
1. Choose one of the following methods to open the Permissions tab on the Security Configuration window for
a PI AF server:
To open from ... Do this ...

Servers window a. Select File > Connections.

b. In the Servers window, right-click the default
connected ( ) PI AF server and click
Security.
PI AF Server Properties window a. On the toolbar, click .
b. In the PI AF Server Properties window, click
the Security link.
Select Database window a. On the toolbar, click the Database button.
b. In the Select Database window, click the Edit
Security button.
 In the Items to Configure list of the Security Configuration window, the server and every collection is selected.
2. Clear those collections that you do not want to be assigned the same permission settings as the server. For
example, you might want to assign access rights for server-wide collections such as Mappings and Identities,
but use a different set of access permissions for databases and their collections.
3. In the Identities list, review existing identities and validate their permissions. You can also add and remove
identities, as needed.
To ... Do this ...

Add or modify permissions of existing identities a. Select an identity in the Identities list.
b. In the Permissions for Identity list, select or
clear the Allow or Deny check boxes
beside the permissions you wish to set.
Add another identity to the Identities list a. Click Add.
b. In the Select Identity window, select the
identity you wish to add.
c. Click OK. The identity is added to the list.
d. In the Permissions for Identity list, set the
access permissions as needed (the
default setting is all are selected).
Tip: If you need to create a new identity and
mapping, click New Identity. For more information,
see Manage identities in PI AF.

Remove an identity from the Identities list a. Select an identity in the Identities list.
b. Click Remove.
4. Select one of the Child Permissions options. For more information, see Permission inheritance of element
objects.
5. Optional. To view all of a user's access permissions on items in PI AF based on his or her current PI AF
identity mappings, click the Effective Access tab.
6. Optional. In the Domain User field, enter a user's Windows domain name whose permissions you want to
view. If you are using OIDC, enter the user's name in the OIDC User field.
7. Optional. Press Tab or Enter to validate your entry.
8. Click OK.
Note: If you are using OpenID Connect (OIDC) for claims-based authentication and role mapping, the
Effective Access tab shows the OIDC user's permissions on PI AF objects. The User SID field is not shown.

PI AF database security
To view a PI AF database, an identity must have at least read permissions to the database object. You configure
permissions individually for each database, or for the entire databases collection.
 Beginning with PI AF 2017 R2, it is no longer necessary for users to have write permission on a PI AF database in
order to have write permission on other objects in the database. Users need only be assigned an identity with
write access to objects such as elements to be able to edit them. To prevent users from having write access to
specific objects, assign them to an identity with read-only access to those objects.

Configure security for new PI AF databases

Configure default PI AF access rights for all identities that need access to databases on a PI AF server.
1. On the toolbar, click the Database button.
2. In the Select Database window, click the Edit Security button.
In the Items to Configure list of the Security Configuration window, the server and every collection is
selected.
3. In the Items to Configure list, clear the server and the following collections: Contacts, Notification Contact
Templates, Identities, and Mappings. Databases and all Database - Collections should be selected.
4. In the Identities list, review existing identities and validate their permissions. You can also add and remove
identities, as needed.
To ... Do this ...

Add or modify permissions of existing identities a. Select an identity in the Identities list.
b. In the Permissions for Identity list, select or
clear the Allow or Deny check box beside
each permission you wish to set.
c. Repeat for each identity.
Add another identity to the Identities list a. Click Add.
b. In the Select Identity window, select the
identity you wish to add.
c. Click OK. The identity is added to the list.
d. In the Permissions for Identity list, set the
access permissions as needed (the
default setting is all are checked).
Tip: If you need to create a new identity and
mapping, click New Identity. For more information,
see Manage identities in PI AF.

Remove an identity from the Identities list a. Select an identity in the Identities list.
b. Click Remove.
5. In the Child Permissions section, choose one of the permission inheritance options. For more information,
see Permission inheritance of element objects.
6. Optional. To view all of a user's access permissions on items in PI AF based on his or her current PI AF
identity mappings, click the Effective Access tab.
 7. Optional. In the Domain User field, enter a user's Windows domain name whose permissions you want to
view. If you are using OIDC, enter the user's name in the OIDC User field.
8. Optional. Press Tab or Enter to validate your entry.
9. Click OK.
Note: If you are using OpenID Connect (OIDC) for claims-based authentication and role mapping, the
Effective Access tab shows the OIDC user's permissions on PI AF objects. The User SID field is not shown.

Configure security for a single PI AF database

For a single database, configure PI AF access rights for identities that need access to its collections and objects.
1. On the toolbar, click the Database button.
2. In the Select Database window, right-click a database in the Databases list and click Security.
In the Items to Configure list of the Security Configuration window, the database and every collection in the
database is selected.
3. Optional. Clear any collection that you do not wish to modify from their default settings and assigned
identities.
4. In the Identities list, review existing identities and validate their permissions. You can also add and remove
identities, as needed.
To ... Do this ...

Add or modify permissions of existing identities a. Select an identity in the Identities list.
b. In the Permissions for Identity list, select or
clear the Allow or Deny check boxes
beside the permissions you wish to set.
c. Repeat for each identity.
Add another identity to the Identities list a. Click Add.
b. In the Select Identity window, select the
identity you wish to add.
c. Click OK. The identity is added to the list.
d. In the Permissions for Identity list, set the
access permissions as needed (the
default setting is all are checked).
Tip: If you need to create a new identity and
mapping, click New Identity. For more information,
see PI AF identities and mappings.

Remove an identity from the Identities list a. Select an identity in the Identities list.
b. Click Remove.
5. In the Child Permissions section, choose one of the permission inheritance options. For more information,
see Permission inheritance of element objects.
 6. Optional. To view all of a user's access permissions on items in PI AF based on his or her current PI AF
identity mappings, click the Effective Access tab.
7. Optional. In the Domain User field, enter a user's Windows domain name whose permissions you want to
view. If you are using OIDC, enter the user's name in the OIDC User field.
8. Optional. Press Tab or Enter to validate your entry.
9. Click OK.
Note: If you are using OpenID Connect (OIDC) for claims-based authentication and role mapping, the
Effective Access tab shows the OIDC user's permissions on PI AF objects. The User SID field is not shown.

PI AF collection security
The security descriptor for a PI AF collection determines access permissions to that collection, as well as default
access permissions for new objects in the collection. For example, the Elements collection permissions
determine which identities can create and delete elements. The Elements collection permissions are replicated
as the security descriptor for any newly-created Element objects.
You can configure access permissions to collections at several points in the PI AF hierarchy. You can set them at
the server level so that permissions assigned to identities on the server are also assigned to the same identities
for every collection in every database (see Configure security for a PI AF server). You can set them at the
database level so that permissions assigned to identities in a database are also assigned to the same identities
for every collection in that database (see Configure security for a single PI AF database).
Note: Library objects (Templates, Enumeration Sets, Reference Types, Tables, Table Connections, and Categories)
always have Read (r) permission regardless of their security settings.

Configure security for collections

Assign access permissions for a specific collection in a PI AF database.
1. Choose one of the following methods to open the Security Configuration window for a database collection:
To open ... Do this ...

Elements collection In the Elements browser, right-click the Elements

collection ( ) and click Security.
Event Frame collection In the Event Frames browser, right-click an event
frame search ( ) and click Security.
Transfer collection In the Event Frames browser, right-click a transfer
search ( ) and click Security.
Element Templates collection In the Library browser, right-click Element Templates
and click Security.
Note: Access permissions for the Element Templates
collection also set access permissions for Event Frame
Templates, Model Templates, and Transfer Templates.
 To open ... Do this ...

Enumeration Sets collection In the Library browser, right-click Enumeration Sets

and click Security.
Reference Types collection In the Library browser, right-click Reference Types
and click Security.
Tables collection In the Library browser, right-click Tables and click
Security.
Table Connections collection In the Library browser, right-click Table Connections
and click Security.
Categories collection In the Library browser, right-click Categories and click
Security.
In the Items to Configure list of the Security Configuration window, the collection is selected.
2. In the Identities list, review existing identities and validate their permissions. You can also add and remove
identities, as needed.
To ... Do this ...

Add or modify permissions of existing identities a. Select an identity in the Identities list.
b. In the Permissions for Identity list, select or
clear the Allow or Deny check box beside
each permission you wish to set.
c. Repeat for each identity.
Add another identity to the Identities list a. Click Add.
b. In the Select Identity window, select the
identity you wish to add.
c. Click OK. The identity is added to the list.
d. In the Permissions for Identity list, set the
access permissions as needed (the
default setting is all are selected).
Tip: If you need to create a new identity and
mapping, click New Identity. For more information,
see Manage identities in PI AF.

Remove an identity from the Identities list a. Select an identity in the Identities list.
b. Click Remove.
3. In the Child Permissions section, choose one of the permission inheritance options. For more information,
see Permission inheritance of element objects.
4. Optional. To view all of a user's access permissions on items in PI AF based on his or her current PI AF
identity mappings, click the Effective Access tab.
 5. Optional. In the Domain User field, enter a user's Windows domain name whose permissions you want to
view. If you are using OIDC, enter the user's name in the OIDC User field.
6. Optional. Press Tab or Enter to validate your entry.
7. Click OK.
Note: If you are using OpenID Connect (OIDC) for claims-based authentication and role mapping, the
Effective Access tab shows the OIDC user's permissions on PI AF objects. The User SID field is not shown.

PI AF object security
You can set specific access permissions for an identity that differ from the default settings inherited from
elsewhere in the PI AF hierarchy on any object (or object group) and collection in a database.

Configure security for objects

Set access permissions for identities to objects in the browser or the viewer in situations where access needs to
be different from inherited permissions. You can also set custom permissions for identities to a specific collection
in the Library.
Note: You must have administrative privileges and belong to the PI AF Administrators identity to configure
security settings.
1. Choose from the following actions:
To set access permissions for ... Do this ...

A browser object Right-click the object and click Security.

Multiple objects a. With multiple objects listed in the viewer
(after a search, for example), use
standard Windows keystrokes to highlight
contiguous (SHIFT+<click>) or non-
contiguous (CTRL+<click>) objects.
b. Right-click and click Security.
2. In the Identities list, review the identities and validate their permissions. You can also add to and remove an
identity from the list.
To ... Do this ...

Add or modify permissions of existing identities a. Select an identity in the Identities list.
b. In the Permissions for Identity list, select or
clear the Allow or Deny check boxes
beside the permissions you wish to set.
c. Repeat for each identity.
 To ... Do this ...

Add another identity to the Identities list a. Click Add.

b. In the Select Identity window, select the
identity you wish to add.
c. Click OK. The identity is added to the list.
d. In the Permissions for Identity list, set the
access permissions as needed (the
default setting is all are selected).
Tip: If you need to create a new identity and
mapping, click New Identity. For more information,
see Manage identities in PI AF.

Remove an identity from the Identities list a. Select an identity in the Identities list.
b. Click Remove.
3. In the Child Permissions section, choose one of the permission inheritance options. For more information,
see Permission inheritance of element objects.
4. Optional. To view all of a user's access permissions on items in PI AF based on his or her current PI AF
identity mappings, click the Effective Access tab.
5. Optional. In the Domain User field, enter a user's Windows domain name whose permissions you want to
view. If you are using OIDC, enter the user's name in the OIDC User field.
6. Optional. Press Tab or Enter to validate your entry.
7. Click OK.
Note: If you are using OpenID Connect (OIDC) for claims-based authentication and role mapping, the
Effective Access tab shows the OIDC user's permissions on PI AF objects. The User SID field is not shown.

Configure security for analyses and analysis templates

Use the Security Configuration window to manage access permissions for PI AF identities that can work with
analyses or analysis templates.
For information on specific permissions that are needed to work with analyses, see PI AF access rights.
1. Choose from the following actions:
To ... Do this ...

Configure access permissions for an analysis a. In the Elements browser, select the element
that contains the analysis.
b. Click the Analyses tab.
c. Right-click the analysis name and click
Security.
 To ... Do this ...

Configure access permissions for an analysis template a. In the Library browser, select the element
template that contains the analysis
template.
b. Click the Analysis Templates tab.
c. Right-click the analysis name and click
Security.
Configure access permissions for all analyses in a PI a. On the toolbar, click Database.
AF database
b. In the Select Database window, right-click
the database name and click Security.
c. In the Security Configuration window, clear
the Item check box above the Items to
Configure list.
d. Select the database - Analyses item.
Configure access permissions for all analysis a. On the toolbar, click Database.
templates in a PI AF database
b. In the Select Database window, right-click
the database name and click Security.
c. In the Security Configuration window, clear
the Item check box above the Items to
Configure list.
d. Select the database - Analysis Templates
item.
2. In the Identities list, review the identities and validate their permissions. You can also add to and remove an
identity from the list, as described in Configure security for objects.
3. In the Child Permissions section, choose one of the permission inheritance options. For more information,
see Permission inheritance of element objects.
4. Optional. To view all of a user's access permissions on items in PI AF based on his or her current PI AF
identity mappings, click the Effective Access tab.
5. Optional. In the Domain User field, enter a user's Windows domain name whose permissions you want to
view. If you are using OIDC, enter the user's name in the OIDC User field.
6. Optional. Press Tab or Enter to validate your entry.
7. Click OK.
Note: If you are using OpenID Connect (OIDC) for claims-based authentication and role mapping, the
Effective Access tab shows the OIDC user's permissions on PI AF objects. The User SID field is not shown.

Configure security for the UOM database

Units of measurement (UOM) always have Read permission set regardless of other security settings.
 You cannot set permissions for individual UOMs or UOM classes. However, you can set permissions for the entire
UOM database.
1. In the navigator, select Unit of Measure.
2. On the toolbar, click UOM Security.
In the Items to Configure list of the Security Configuration window, the Unit-of-Measure Database item is
selected.
3. In the Identities list, review existing identities and validate their permissions. You can also add and remove
identities, as described in Configure security for objects.
4. In the Child Permissions section, choose one of the permission inheritance options. For more information,
see Permission inheritance of element objects.
5. Optional. To view a user's access permissions on PI AF objects based on his or her current PI AF identity
mappings, click the Effective Access tab.
6. Optional. In the Domain User field, enter a user's Windows domain name whose permissions you want to
view. If you are using OIDC, enter the user's name in the OIDC User field.
7. Optional. Press Tab or Enter to validate your entry.
8. Click OK.
Note: If you are using OpenID Connect (OIDC) for claims-based authentication and role mapping, the
Effective Access tab shows the OIDC user's permissions on PI AF objects. The User SID field is not shown.

Differences from Data Archive security model

Although the security model is similar to that which Data Archive uses, there are a number of differences:
• The Deny privilege is supported. See Deny permission option.
• A more expansive set of access permissions is available. See PI AF access rights.
• The equivalent of PI user and PI group identities are not supported.
• PI trusts and PI explicit logins are not supported.
• The concept of an undeletable flag on an identity or mapping is not supported.
• Mappings cannot be disabled. Only PI AF identities can be disabled.
• A single Windows user identity can be mapped to more than one PI AF identity.
• An Identity provider role can be mapped to multiple PI AF identities.
• A different built-in set of identities is installed: Administrators, Engineers, and World.
Chapter 11

Event frames in PI AF

Capturing important events in your process and collecting relevant data around those events can help analyze
why they occurred. For example, you can closely monitor events such as asset downtime, process excursions,
equipment startup or shutdown, and environmental excursions to identify possible causes or potential points of
failure.
Collecting data around repeatable time periods such as product tracking batches, product runs, or operator shifts
can help make those processes more efficient. The capture of comprehensive data associated with such an event
helps track, compare, or analyse the process or event.
Just as elements allow you to collect and store data about assets, event frames allow you to collect and store
data about events. It is recommended you use asset analytics to track your events using event frames. PI
Datalink, AVEVA PI Vision, and PI WebParts are the client tools that support event frame visualization.
Sample event data
An event frame encapsulates the time period of the event with relevant, comprehensive asset data:

Videos
For information on event frames, watch this video:
Alternatively, you can view all the videos on the event frames playlist:
Structure of event frames
Each event frame has a name, start time, end time, one or more attributes, and one or more referenced PI AF
elements. As with elements, you should create event frame templates to standardize and manage the attributes
for different types of events.
With event frames you can easily search the PI System for the events themselves, rather than search for events
by time. You can configure event frames to return all related event data automatically in real-time so that you do
not need to query multiple systems for event and process data, and then merge them together manually. You
can also set up event frames to retrieve historical data.
When to use event frames
There are two categories of trackable events that would fit an event frame profile:
• "Good" events: Events that you want to track as a normal part of business, such as product tracking, shifts,
and so on.
• "Bad" events: Events that are unexpected and need to be analyzed and perhaps fixed quickly if they ever
occur, such as expected shutdowns or excursions. These are events that you want to track and report in
aggregate, over a period of time.
Asking questions such as these can help identify events or conditions that must be tracked:
• What are all the times that event X occurred on this type of asset?
• Can I associate data from different tags for a time-range, or for a single point in time?
• What is the associated data for a particular time period when a problem occurred or may occur in the
future?
• What are the critical process events that someone needs to be notified on?
• Are there digital states for PI tags that are significant when they change, and must they trigger other actions?

Advantages of event frames

Event frames provide these advantages:
• Flexibility
Event frames:
• Reference multiple elements within the same event.
• Support multiple overlapping events on a PI AF element.
• Capture any event; a "batch" is just one type of capturable event.
• Easy search options
Searches can be specified on a number of configurable event frame attributes: it is optional to
specify a time range. For example, you can search just by entering the name of the event frame.
The most commonly searched event frame attributes can be configured as indexed attributes
through event frame templates, which speeds up end-user searches.
• Scalability
 Event frames are extremely scalable whereas search performance degrades with a large number
(tens of thousands) of batches.

Examples of event frames

Example of event frames in a wind power generation company
Take the example of a wind power generation company that has different types of windmills across different
locations and uses PI AF to organize their data. Their asset framework structure is based off a base element
template of type "windmill", and has various child templates based off OEM, model, and megawatt ratings. The
wind operator may want to win favorable warranty contracts by showing that the blades are operating safely. Or,
the operator may need to monitor parameters such as oil bearing pressure, maximum voltage, power-factor, or
performance of electronic and mechanical brakes in the minutes before process trips occur. In all these cases,
you can associate event frames with the specific event frame attributes.
The sample windmill element may include these asset attributes and associated event frame attributes:
Asset attribute Event frame attribute

RPM Instantaneous and maximum speeds

Voltage Maximum voltage
Power Power at current time
Yaw Yaw at current time
Pitch Pitch at current time
Oil bearing pressure Maximum oil bearing pressure
Since all types of turbines share many identical attributes, you can create just one event frame template and use
it to monitor similar events across the different assets. For example, you may be interested in the RPM attribute
to capture a speed-based event. Using the special notation .\Elements[.]|RPM in the template enables you to
use the template on any windmill, and access the attribute of the particular referenced element.
Example of event frames using Asset Analytics
For an example of creating event frames using asset analytics, see Create event frames automatically to track
inefficiency.

Event frames or batch?

Batch provides you with a means to generate batch event data based on PI tags. Event frames provide you with a
way to track and analyze process and business data related to events that are defined on PI AF attributes.
Different companies and users come from different levels of PI System implementation and use of PI System
features; hence, the recommendation of whether to choose batch or event frames is highly subjective. However,
as a general recommendation, all customers should migrate to event frames in the near future. Here are a few
examples of scenarios that customers may find themselves in:
• You are a batch user and use RtReports.
 • Since RtReports 4.1 now supports AF and event frames, you should run the 'Batch To Event Frames'
migration, and then migrate your RtReport templates to utilize AF contexts.
• You do not currently use Batch but have batch use-cases or must use RtReports.
• Event frames are recommended. Event frames will support all your needs!
• You do not use Batch and do not have batch use-cases.
• You must use event frames. Typical event frame use-cases include downtime or outages in power industries,
excursions in water utility industries, and so on.
Note: Do not run dual or parallel instances of Batch and event frame interfaces in production as it adds to your
migration complexity.

Ways to create event frames

Although you can create event frames with several different of our products, we strongly recommend asset
analytics.
Asset analytics
Data Archive supports creation of single-layer events and can trigger expressions that open or close event
frames. See Event frame generation analyses.
PI Event Frame Generator (PI EFGen)
PI EFGen uses both PI SDK and AF SDK to create a hierarchy of events or to convert a PI BaGen structure to an
event frame generator structure. Use PI System Explorer or PI Builder to create the event frame templates,
associated attributes and PI point references.
For instructions on how to create event frames with PI EFGen, watch this video:
PI interfaces for batch and manufacturing execution systems
PI Batch Framework 3.x and later versions can create event frames within a PI AF database or PI Batch objects
within a PI Batch database. For more information on creating event frames and using PI interfaces to populate
the PI AF database with events-based data, see:
•
• PI Event Frames Interface Manager
Programmable interfaces
You can create your own custom program using AF SDK to create and monitor events.
Manual creation of event frames
The manual creation and management of event frames is strongly discouraged. Instead, use Data Archive with
asset analytics support or PI Batch, depending on your process needs. See Event frames or batch?

Visualization of event frames

You can use PI Datalink, AVEVA PI Vision, and PI WebParts client tools to visualize event frames. You can also use
PI OLEDB Enterprise, PI JDBC Driver, or PI Web Services to integrate event frame data into other third-party
reporting tools.
 Note: PI ProcessBook, PI BatchView, and PI Manual Logger do not currently support event frame visualization.
• PI Datalink
PI Datalink support for event frames includes exploring and comparing hierarchical events. For more
information, see Events in worksheets.
• AVEVA PI Vision
AVEVA PI Vision enables you to view and analyze your PI System data during the time range of a particular
event. For example, you may want to examine the performance of an asset during an operator shift or
compare the data for several assets during a downtime period.
AVEVA PI Vision supports event frames through the "Related Events" viewer. For more information,
see Analyzing and comparing events.
• PI WebParts
PI WebParts does not include specific features related to event frame visualization. However, you can create
a data set based on a relational data source that retrieves event frame data via PI OLEDB Enterprise. This
event frame data can then be displayed in a PI Table web part, for example, and used to provide context,
such as start and end times, to other web parts on the page.

Event frame templates

Using event frame templates, you can define and standardize the related data (event frame attributes)
associated with different types of events. For consistency, it is recommended to create event frame objects from
templates. To learn more, see Base and derived templates. You can use event frame attributes to provide
additional context around the event that are useful for searches and reports. For example, downtime events
often have a reason code that users want to search for or filter on during analysis of their downtime events.
Note: Event frames cannot be created directly from templates marked Base Template Only (BTO). You create a
derived template from the BTO template and then create event frames from the derived template. When you
create an event frame based on a derived template, it inherits all the attributes of the derived template and the
BTO template.
You can also configure event frame attributes to reference process data in the context of the event. For example,
a temperature excursion event is likely to have an attribute for the maximum temperature. You can configure
event frames to record those values for you. Additionally, for each event type, you can configure an index for the
most frequently searched attributes. This approach enables faster and easier searches on the PI AF server when
you track several event types or millions of events.
Data references in event frame templates
When you create event frames dynamically with event frame templates, you typically need to reference
elements, attributes, templates or other related objects based on those event frame templates. Because each
individual event frame occurs in a slightly different context, you can use substitution parameters to reference
other PI AF objects dynamically, rather than static, absolute references. For example, you can use a downtime
event frame template for any number of assets, such as a pump, motor, boiler, compressor, and so on.
In PI point data references, substitution parameters are useful for:
• Building tag name references based on hierarchy or other attribute values.
• Referencing other PI point attributes, such as from an event frame to the primary referenced element.
 The main limitation of PI point data references is that the element attribute must also be a PI point data
reference.
In String Builder data references, substitution parameters are useful for:
• Obtaining numeric values or string values when referenced element attributes do not have a PI point data
reference.
• Creating a string by concatenating multiple values from referenced element attributes and other text.
• Passing a time context, including the end time of the event frame.
• Obtaining the name of referenced elements or their parents.
The limitation of String Builder data references is that they do not perform unit of measure conversions or
perform aggregations or calculations.
A specific syntax is required to reference attributes from event frame templates, as described in Data references
to attributes in the primary referenced element and Data references to attributes in other elements.
Video
For information on how to set up event frame templates, watch this video:

Primary referenced element

Each event frame references one or more elements. The event frame's Referenced Elements tab lists all
elements that the event frame refers to. The main element referenced by the event frame is called the primary
referenced element, and is indicated by a checkmark on the element icon:
By default, the first referenced element added is set as the primary referenced element, but you can change it by
right-clicking on another element and selecting Set as Primary Element Reference.
Note: If you delete the reference to the primary element, PI System Explorer does not automatically set a new
primary referenced element. You must select a new primary referenced element manually.

Data references to attributes in the primary referenced element

In data references from an event frame template, you can refer to an attribute in an event frame's primary
referenced element with the syntax:
.\Elements [.]|AttributeName

. Indicates the current object, which is the event

frame.
\Elements Specifies the elements collection of the current
object.
[.] Indicates the default object of the current object. In
this case, it is the event frame's primary referenced
element.
|AttributeName Specifies the name of the attribute.
For example, .\Elements [.]|Flowrate obtains the value of the Flowrate attribute from the primary referenced
element.
 Note: This syntax is primarily used to reference PI point data references. For more information on assigning a
static value to an attribute, see Configuration Item attribute property, Define constant values for attribute
templates, and Create attributes on event frames.

Data references to attributes in other elements

In data references from an event frame template, you can reference other elements and attributes with
collection filters and relative paths.
Examples that use collection filters
You can reference other elements and attributes with the collection filters shown in the following table.

Collection filter Example Explanation

@Category .\Elements[@Category=MyCategory] Obtains the value of the first

referenced element that is assigned
to the MyCategory category.
@Description .\Elements[@Description=My Description] Obtains the value of the first
referenced element that has the
My Description description.
@Index .\Elements[@Index=3] Obtains the value of the third
referenced element.
.\Elements[@Index=2]|FlowRate Obtains the value of the FlowRate
attribute from the second
referenced element.
@Name .\Elements[@Name=Tank1] Obtains the value of the element
named Tank1.
Note: You can use
wild cards with .\Elements[@Name=*2]|FlowRate Obtains the value of the FlowRate
@Name. attribute from the first referenced
element whose name ends in 2.
@ReferenceType .\Elements[@ReferenceType=Area] Obtains the value of the first
referenced element that uses the
Area reference type.
@Template .\Elements[@Template=MyTemplate] Obtains the value of the first
referenced element that uses the
MyTemplate template.
.\Elements[@Template=Pump Template]|%attribute% Obtains the value of the attribute
that has the same name as this
event frame attribute from the first
referenced element that uses the
Pump Template.
Collection filter Example Explanation

@Trait .\Elements[@Name=Tank*]|Attributes[@Trait=LoLo] Obtains the value of the attribute

with a LoLo trait in the first
referenced element whose name
begins with Tank.
@Type .\Elements[@Name=Tank*]| Obtains the value of the first
Attributes[@Type=System.Int32] attribute that has an Int32 value
type in the first referenced element
whose name begins with Tank.
@UOM .\Elements[@Name=Tank*]|[@UOM=meter] Obtains the value of the first
attribute that uses the meter unit of
measure in the first referenced
element whose name begins with
Tank.
Examples that combine collection filters
You can also combine collection filter criteria, as shown in the following examples:

Example Explanation

.\Elements[@Name=*2][@Category=Pump]|FlowRate Obtains the value of the FlowRate

attribute from the first referenced
element whose name ends in 2 and
whose element category is Pump.
.\Elements[@Name=Pump*][@Template=Pump Template]|FlowRate Obtains the value of the FlowRate
attribute from the first referenced
element whose name starts with
Pump and whose element template
is Pump Template.
.\EventFrames[@Template=Machine Template]|Pressure Obtains the value of the Pressure
attribute from the first child event
frame whose template is Machine
Template.
 Example Explanation

.\EventFrames[@Template=Machine Template][@Index=-1]|Pressure Obtains the value of the Pressure

attribute from the most recent child
or
event frame whose template is
.\EventFrames[@Template=Machine Template][-1]|Pressure Machine Template.
Note: Beginning with PI AF 2017,
you can use a negative number for
an index from the end of a
collection (for example -1 indicates
the last item, -2 indicates the
penultimate item).
The @Index filter is optional if
another filter is specified before the
index filter.
Examples that use relative paths
You can use relative path syntax to navigate the Elements hierarchy from an event frame and obtain other
attribute values. For example, suppose you have the following element hierarchy:
In an event frame that has Production Line 1 as the primary referenced element, you can obtain the value of the
Price attribute that is assigned to the Unit 1 parent element with the following syntax:

.\Elements[.]\..\|Price
If the Price attribute were two levels up the hierarchy, you would use:
.\Elements[.]\..\..|Price
You can obtain the value of the Inflow PI point attribute that is assigned to the Pump 1 child element with the
following syntax:
.\Elements[.]\Pump 1|Inflow
If the Pump 1 child element were based on the Pump element template, you would use:
.\Elements[.]\[@Template=Pump]|Flow

Create event frame templates

Create and configure event frame templates to ensure consistent definitions for event frames in your asset
structure.
1. In the navigator, click Library.
2. In the Library browser, click Event Frame Templates.
3. To create a new event frame template, choose one of the following actions:
▪ On the toolbar, click New Template.
▪ Right-click Event Frame Templates and click New Template.
 ▪ Right-click in the Event Frame Templates pane and click New Template.
4. In the General tab of the Event Frame Template Properties window, enter a unique name and a description
for the event frame template in the Name and Description fields.
5. Adjust settings on tabs to configure the event frame template. PI System Explorer provides defaults for all
required settings, but you can configure settings yourself. The settings include:
Option Description

Base Template You can base the template on an existing event frame template, which you select
from the drop-down list. For more information on base templates, see Base and
derived templates.
Severity Select a severity setting for event frames based on the template. You can choose
None (default), Information, Warning, Minor, Major, and Critical.
Note: Event frames that have already been created with a specific severity
setting are not updated automatically if the Severity setting in an event frame
template is later changed.

Categories Optional. Organize event frame templates by grouping them into element
categories. To browse available categories or to create a new category, click .
Default Attribute Optional. After you have created attributes for the template, you can select a
default attribute from the drop-down list. For more information, see Default
attribute.
Option Description

Naming Pattern Optional. You can enter a text string, or click to choose from the following
substitution parameters to define a naming pattern.
• %STARTTIME:yyyy-MM-dd HH:mm:ss.fff%
The current local start time of the object using the specified formatting.
If no formatting is specified, the default formatting is used. The
formatting uses standard format strings supported by the
DateTime.ToString method, as described in Format strings for
time substitution parameters.
• %UTCSTARTTIME:yyyy-MM-dd HH:mm:ss.fff%
The current Coordinated Universal Time (UTC) start time of the object
using the specified formatting. If no formatting is specified, the
default formatting is used.
• %TEMPLATE%
The name of the object's template.
• %@Attribute%
The value of the object's attribute template, represented by the path.
• %ELEMENT%
The name of the primary referenced element of the object's event
frame.
• %ELEMENTDESCRIPTION%
The description of the primary referenced element of the object's event
frame.
You can also use other naming pattern substitution parameters. For
example, if you want an event frame generation analysis name
included in the naming pattern, enter %ANALYSIS% as a substitution
parameter. For a complete list of naming pattern substitution
parameters, see Naming patterns.
Each element derived from the template will have a unique, identifiable
name. To ensure that new elements created from the template have
an incremental number, enter * at the end of any pattern you enter
here.
Naming patterns are re-evaluated on an event frame when the Start
time, End time, or primary referenced element is modified after it
has been created. It will not be re-evaluated when loaded from
another application. To force an element or event frame to re-
evaluate its naming pattern, right-click the object and click
Reevaluate Naming Pattern.
Some substitution parameters may not be applied when a derived event
frame is created. To ensure a derived event frame's name fully
reflects the naming pattern, right-click the event frame and click
Reevaluate Naming Pattern.
Note: The name generated by the naming pattern must be less than the
maximum name length of 260 characters.
 Option Description

Allow Extensions Select this check box to enable additional attributes to be defined for an event
frame, beyond those defined in its template. For more information, see
Extensions.
Note: Categories, analyses and notifications are not affected by whether the
Allow Extensions check box is enabled.

Can Be Acknowledged Select this check box to enable users to acknowledge an event frame. For more
information, see Acknowledgment of event frames.
Note: This setting only affects event frames that are created after a template is
created or modified.

Base Template Only Select this checkbox to assign the Base Template Only (BTO) property to an
event frame template. An event frame cannot be created directly from a BTO
template. For more information, see Base and derived templates.
Extended Properties This link is an advanced feature. For more information, see Storage of
application-specific information.
Location Click this link if you wish to specify location attribute traits for the event frame
template. For more information, see Set location attribute traits.
Reason Click this link if you wish to set up reason attribute traits for the event frame
template so that users can select reason codes for downtime, excursions, and
other events. For more information, see Set reason attribute traits.
Security Click this link if you wish to set up custom access permissions to the event frame
template beyond those already established at the server and database level. For
more information, see Configure security for objects.
6. Use the Attribute Templates tab to create an attribute template for each property or data item for the
template. See Create attribute templates.

Change event frame templates

Exercise caution when you change an event frame template, since there can be unintended consequences. For
example, attributes could be deleted if they were defined by the old template and are not present in the new
template. Be sure that attributes with the same name in both the old and new template have the same data
type.
You can change the template on which an existing event frame is based, or add a template to an event frame
that is not currently based on a template.
1. In the navigator, click Event Frames.
2. In the Event Frames browser, right-click the Event Frame Searches collection and click New Search.
3. In the Event Frame Search window, enter criteria to locate the event frame that you want to change.
4. Right-click the appropriate event frame in the browser and click Convert > Change Template.
 5. In the Choose Event Frame Template window, select the desired template from the Event Frame Template
list.
▪ Optional. To display only templates in a specific category, select a category from the Templates of
category list.
6. Click OK.

Create event frames

Although you typically use event-frame-generation analyses or PI Event Frames Generator (PI EFGen) to create
event frames, you can create an event frame manually. It is simply not recommended.
1. In the navigator, select Event Frames.
2. To create a new event frame, choose one of the following actions:
▪ On the toolbar, click New Event Frame.
▪ In the Event Frames browser, right-click the Event Frame Searches collection and click New Event Frame.
▪ In the viewer, right-click and click New > New Event Frame.
3. In the Event Frame Template section of the Choose Event Frame Template window, select an event frame
template and click OK.
The new event frame is displayed in the viewer with four tabs for configuring the event frame.
4. In the General tab, enter a unique name and a description for the event frame in the Name and Description
fields.
5. Adjust settings on tabs to configure the event frame. PI System Explorer provides defaults for all required
settings, but you can configure settings yourself. The settings include:
Option Description

Template Displays the template that you selected when you

created the event frame. To review the template
properties, click .
Severity Select a severity setting for the event frame. You can
choose None (default), Information, Warning, Minor,
Major, and Critical.
Start time Defaults to current date and time. Press F2 or click
to open the Date and Time Picker window where you
can select a different start time.
End time Defaults to no date or time. Press F2 or click to
open the Date and Time Picker window where you
can select a different end time.
Categories Optional. You can organize event frames by grouping
them into element categories. To browse available
categories, click .
 Option Description

Default Attribute Optional. This field is read-only if the event frame is

based on a template. After you have created
attributes for the event frame in the Attributes tab,
you can select a default attribute from the drop-down
list. For more information, see Default attribute.
Extended Properties This link is an advanced feature. For more
information, see Storage of application-specific
information.
Annotations Click this link if you wish to enter a comment and/or
add a file attachment specific to the event frame. For
more information, see Add annotations to event
frames.
Location Click this link if you wish to specify location attribute
traits for the event frame. For more information, see
Set location attribute traits.
Reason Click this link if you wish to set up a reason attribute
trait for the event frame. For more information, see
Set reason attribute traits.
Security Click this link if you wish to set up custom access
permissions to the event frame beyond those already
established at the server and database level. For
more information, see Configure security for objects.
6. Optional. You can choose from the following actions, as needed.
Option Description

Capture values To improve performance, you can save event-frame

attribute values in PI AF rather than have data
references calculated and executed. For more
information, see Value capture for event frames and
transfers.
Lock After the underlying action for an event frame has
completed, such as batch completion, you can click
this link to prevent further changes to it. For more
information, see Lock event frames or transfers.
Note: Only Administrator users can unlock an event
frame.
 Option Description

Acknowledge If the event frame is based on a template where both

the Can Be Acknowledged setting and the annotation
access right are enabled, click this link to indicate that
you have acknowledged the event frame. For more
information, see Acknowledgment of event frames.
7. Edit the remaining tabs as needed.
▪ To add attributes, see Create attributes on event frames.
▪ To set a primary referenced element, see Primary referenced element.

Create attributes on event frames

Create attributes on event frames in the same way as on elements.
1. In the Event Frames browser, find and select the parent event frame.
2. In the viewer, select the Attributes tab.
3. If no attributes exist, click the New Attribute link. Alternatively, click New Attribute on the toolbar.
Note: If the event frame is based on a template, you cannot add an attribute unless the template allows
extensions.
4. In the Name field, enter a unique name for the attribute.
5. In the Description field, enter a description for the attribute.
6. In the Properties field, select attribute properties as needed. For more information, see Attribute properties.
7. Optional. In the Categories field, assign the attribute to a category. To browse available categories, click .
8. In the Default UOM field, select the unit of measure for the attribute.
9. In the Value Type field, select the data type of the attribute.
10. To assign a value to the attribute, choose from the following actions.
To ... Do this ...

Enter a static value Type a value in the Value field.

Derive or calculate a value from a data reference a. Select a data reference type from the Data
Reference list.
b. Click Settings to configure the data
reference. For details about configuring
a data reference, see Configuration of
data references.
11. Optional. When the Use DisplayDigits for Attribute and Attribute Template values system option is selected,
you can override the default DisplayDigits property value of -5 and specify the number of digits to display in
the Display Digits field. Only numeric values in the Value field are affected. For attributes that are not based
on a template, the precision of PI point data references is obtained from the PI point itself.
 ▪ Enter a negative number up to -20 to indicate the total number of digits to display.
▪ Enter a positive number up to 10 to indicate the number of digits after the decimal point to display,
including trailing zeros.
For more information, see Control the display of attribute and attribute template values and PI System
Explorer customization options.
12. To save your work, press CTRL-S or click Check In.

Value capture for event frames and transfers

To display values for an event frame or transfer, PI AF executes data references to retrieve associated attribute
values for the time period. You can, however, use Capture Values to save those values in a PI AF database table
(AFEventFrameAttributeValue). Doing this can improve performance, since it is faster to display the saved values
than to retrieve them.
You can also use Capture Values to ensure attribute values displayed for event frames are the same at any future
point as when they were captured. Additionally, Capture Values provides a way to preserve values that might not
be available later, such as streaming data that is not persisted long-term.
Value recapture
Automatic recapture occurs whenever the start time and end time of a captured event frame or transfer is
modified.
Whenever you add new attributes to an event frame or transfer, you must recapture values to ensure that values
are also captured for the new attributes.
Note that when you recapture values, data loss can occur if a data reference has changed since the initial value
capture: For example, if values in a table accessed by a table lookup data reference have been modified.

Capture values
You capture values to save event frame or transfer attribute values to a table in the PI AF database. This can
improve performance since PI AF does not execute any data references.
Note: If you add new attributes to event frames or transfers with captured values, you should recapture those
values to ensure that values are also captured for the new attributes.
1. In the navigator, click Event Frames.
2. In the Event Frames browser, choose from the following actions.
To capture values for ... Do this ...

All transfers or parent event frames in a collection a. Right-click a search or recent collection.
b. Click Capture or Recapture Values.
Alternatively, follow these steps.
c. Click a search or recent collection.
d. In the viewer, right-click below the list of
event frames or transfers.
e. Click Capture or Recapture Values.
Child event frames in a collection a. Click a search or recent collection.
b. In the viewer, click beside each event frame
for which you want to capture values.
The child event frames are displayed.
c. In the viewer, use Windows selection
keystrokes to select event frames and
child event frames:
To• select contiguous objects, press
SHIFT+<click>.
To• select non-contiguous objects, press
CTRL+<click>.
To• select all displayed objects, press
CTRL+A.
d. Right-click a selected event frame.
e. Click Capture or Recapture Values.
A single event frame a. Expand a search or a recent event frame
collection.
b. Select the event frame.
c. Choose from the following actions.
In•the General tab, click the Capture
Values link.
Right-click
• and click Capture or
Recapture Values.
Note: For subsequent value captures, the link
changes to Recapture Values.
 To capture values for ... Do this ...

A single transfer a. Expand a search or a recent transfer

collection.
b. Select the transfer.
c. Right-click and click Capture or Recapture
Values.
3. In the Capture or Recapture Values window, check the status and click Close.
A Has Captured Values icon ( ) is displayed in the viewer beside each event frame or transfer that has a captured
value.

Lock event frames or transfers

After the underlying action for an event frame or transfer has completed (for example, after a batch has
finished), the event frame or transfer is still open and can continue to receive data. You can lock an event frame
or transfer, preventing further changes to it.
Unlocking an event frame or transfer requires Administrator permission. Only users with Administrator
permissions on an object have the ability to unlock it.
1. In the navigator, click Event Frames.
2. In the Event Frames browser, open the Event Frame Searches (or Transfer Searches) collection that contains
the object you want to lock.
3. Right-click the object and click Lock.
4. To verify that the object is locked, select the event frame or transfer search collection that contains the
object.
The object is displayed in the viewer with next to it in the Lock column.

Acknowledgment of event frames

In PI AF 2016 and later, you can require that an event frame be acknowledged. The acknowledgment feature is
used by notifications and PI AF client applications, such as AVEVA PI Vision. The event-frame acknowledgment
feature replaces the acknowledge notification functionality in the legacy version of Notifications.
• For more information on setting up event-frame acknowledgment in notifications, see Configuration of
notification rules for analyses or event frames.
• For more information on viewing and acknowledging event frames using AVEVA PI Vision, see the AVEVA PI
Vision user guide.
Security for event-frame acknowledgment
A user needs to have a PI AF identity for which the Annotate permission (an) is enabled. For more information on
access rights, see PI AF access rights.
 Setup of event-frame acknowledgment
You set up an acknowledgment by selecting the Can Be Acknowledged check box as you configure an event
frame template. Any event frame that is based on that template displays an Acknowledge link on the General
tab. In event frames based on event frame templates where the Can Be Acknowledged check box is not
selected, the Acknowledge link is inactive. You also cannot acknowledge event frames that are not based on an
event frame template.
Note: The Can Be Acknowledged setting only affects event frames that are created after a template is created or
modified.
Search for event-frame acknowledgments
You can search for event frames that can be acknowledged, as well as those that have been acknowledged. You
review acknowledgment status in the Viewer for the Event Frame Searches collection, where an Acknowledged
column is displayed ( ). Possible values are:
Is not acknowledged
Is acknowledged
blank Not acknowledgeable
To group event frames by their acknowledged status, click the column icon.

Acknowledge event frames

You acknowledge event frames in the Event Frames browser or in the General tab of a selected event frame in
the Event Frames viewer.
1. In the navigator, click Event Frames.
2. In the Event Frames browser, click an Event Frame Search collection.
The contents of the collection are displayed in the viewer.
3. Optional. To group event frames by their acknowledged status, click the column icon.
4. Choose from the following actions.
 To ... Do this ...

Acknowledge an event frame a. Choose one of the following actions:

Right-click
• an event frame in the viewer
and click Acknowledge on the
context menu.
Double-click
• an event frame in the
viewer and, on the General tab, click
the Acknowledge link.
b. Click Yes in response to the Are you sure you
want to acknowledge
Event_Frame_Name? prompt.
c. The following changes occur:
In•the Event Frame Search collection that
is displayed in the viewer, the
Acknowledged ( ) column changes to
OK status.
On
• the General tab, the Acknowledged
field is displayed with a time and date
stamp. The user ID of the user who
made the acknowledgment is
displayed in the By field.
Review an acknowledgment a. In the Event Frame Search collection that is
displayed in the viewer, double-click an
event frame that has a status of OK ( ).
b. On the General tab, review the time and date
stamp in the Acknowledged field, as well
as the user ID of the user who made the
acknowledgment.

Transfers
Transfers are a type of event frame. They mark movement of material in discrete quantities. They have a start
time and an end time. Transfers are unique in a model because they are temporal and appear in a model only
when a transfer of material has taken place. For example, use transfers to track material movements in and out
of the facility, track raw materials used in the process and finished product being stored, and track tank-to-tank
material transfers.

Create transfer templates

Create and configure transfer templates to ensure consistent definitions for transfers in your asset structure.
1. In the navigator, click Library.
2. In the Library browser, click Transfer Templates.
3. To create a new transfer template, choose one of the following actions:
▪ On the toolbar, click New Template.
▪ In the Transfer Templates pane, click New Template.
▪ Right-click Transfer Templates and click New Template.
4. In the General tab of the Transfer Template Properties window, enter a unique name and a description for
the transfer template in the Name and Description fields.
5. Adjust settings on tabs to configure the transfer template. PI System Explorer provides defaults for all
required settings, but you can configure settings yourself. The settings include:
Option Description

Base Template You can base the template on an existing transfer template, which you select
from the list. For more information on base templates, see Base and derived
templates.
Categories Optional. Organize transfer templates by grouping them into element categories.
To browse available categories or to create a new category, click .
Default Attribute Optional. After you have created attributes for the template, you can select a
default attribute from the list. For more information, see Default attribute.
Option Description

Naming Pattern Optional. You can enter a text string, or click to choose from the following
substitution parameters to define a naming pattern.
• %TIME:yyyy-MM-dd HH:mm:ss.fff%
The current local time of the object using the specified formatting. If no
formatting is specified, the default formatting is used. The formatting
uses standard format strings supported by the DateTime.ToString
method, as described in Format strings for time substitution
parameters.
• %UTCTIME:yyyy-MM-dd HH:mm:ss.fff%
The current Coordinated Universal Time (UTC) time of the object using
the specified formatting. If no formatting is specified, the default
formatting is used.
• %STARTTIME:yyyy-MM-dd HH:mm:ss.fff%
The current local start time of the object using the specified formatting.
If no formatting is specified, the default formatting is used.
• %UTCSTARTTIME:yyyy-MM-dd HH:mm:ss.fff%
The current Coordinated Universal Time (UTC) start time of the object
using the specified formatting. If no formatting is specified, the
default formatting is used.
• %TEMPLATE%
The name of the object's template.
• %@Attribute%
The value of the object's attribute template, represented by the path.
• %SOURCE%
Name of the source element for the transfer.
• %DESTINATION%
Name of the destination element for the transfer.
You can also use other naming pattern substitution parameters. For a
complete list of naming pattern substitution parameters, see
Naming patterns.
Each transfer derived from the template will have a unique, identifiable
name. To ensure that new transfers created from the template have
an incremental number, enter * at the end of any pattern you enter
here.
Naming patterns are re-evaluated on a transfer when the Start time is
modified after it has been created. It will not be re-evaluated when
loaded from another application. To force a transfer to re-evaluate
its naming pattern, right-click the object and click Reevaluate
Naming Pattern.
Some substitution parameters may not be applied when a derived
transfer is created. To ensure a derived transfer's name fully reflects
the naming pattern, right-click the transfer and click Reevaluate
 Option Description

Allow Extensions Select this check box to enable additional attributes to be defined for a transfer,
beyond those defined in its template. For more information, see Extensions.
Note: Categories are not affected by whether the Allow Extensions check box is
enabled.

Base Template Only Select this checkbox to assign the Base Template Only (BTO) property to a
transfer template. BTO templates can only be used to create derived templates.
Transfers cannot be created directly from BTO templates. For more information,
see Base and derived templates.
Extended Properties This link is an advanced feature. For more information, see Storage of
application-specific information.
Reason Click this link if you wish to set up a reason attribute trait for the transfer
template. For more information, see Set reason attribute traits.
Security Click this link if you wish to set up custom access permissions to the transfer
template beyond those already established at the server and database level. For
more information, see Configure security for objects.
6. Use the Attribute Templates tab to create an attribute template for each property or data item for the
template. See Create attribute templates.
7. Optional. Use the Ports tab to define additional ports that define end-points for connections between
transfer elements, or to modify the default In and Out ports. See Create transfer ports.

Create transfers
Default In and Out transfer ports with Boundary and Node connection types are automatically created for every
transfer.
You create a transfer in the Event Frames browser.
1. In the navigator, click Event Frames.
2. In the Event Frames browser, click the Transfer Searches (or Recent Transfers) collection.
3. To create a new transfer, choose one of the following actions:
▪ On the toolbar, click the New Transfer button.
▪ In the Event Frames browser, right-click the Transfer Searches collection and click New Transfer.
▪ In the viewer, right-click and click New Transfer.
4. In the Choose Transfer Template window, choose an existing template for the transfer. Although not
recommended, you can also choose <None>.
▪ Optional. To assign the transfer to a category, select one from the Templates of category list.
5. Click OK.
The new transfer is displayed in the viewer with three tabs for configuring the transfer. In the General tab, a
default name for the new transfer is displayed based on the naming pattern, as well as a default start time.
 6. Optional. Replace the default name with a unique name and enter a description for the transfer in the Name
and Description fields.
7. Optional. You can organize objects by grouping them into categories. To browse the available categories, click
. See Categorization of objects for more information.
8. In the Start time and End time fields, enter the start and end times for when the transfer takes place. To
browse for a date, click .
9. In the Source and Port fields, select the element and port providing the material of the transfer.
10. In the Destination and Port fields, select the element and port receiving the transfer.
11. If the transfer is based on a template, a read-only value is displayed in the Default Attribute field. However, if
you are creating a transfer manually, you can select a default attribute after you have added attributes in the
Attributes tab.
12. Optional. To add an annotation to the transfer, click Annotations. For more information, see Add annotations
to transfers.
If the Allow Extensions check box is selected in the transfer template or you are creating a transfer manually,
follow these additional steps.
• Use the Attributes tab to define an attribute for each property or data item. See Create attribute templates.
• Use the Ports tab to define additional ports that define end-points for connections between transfer
elements, or to modify the default In and Out ports. For more information, see Create transfer ports.

Create transfer ports

You can only modify or add ports for a transfer derived from a template if Allow Extensions is enabled on the
transfer template.
Use the Ports tab to review settings for default In and Out transfer ports.
1. To create a new transfer port or review existing ports, choose one of the following actions:
▪ In the Event Frames browser, expand a Transfer Searches collection. Select a transfer, or right-click a
transfer and click Properties.
▪ In the Library browser, expand Transfer Templates. Select a transfer template, or right-click a transfer
template and click Properties.
2. Click the Ports tab.
3. Choose from the following actions.
 To ... Do this ...

Create a new port a. Choose one of the following actions.

On
• the toolbar, click New Port.
Right-click
• in the viewer and click New
Port.
b. Choose one of the following actions. Refer to
Transfer Ports tab properties for
descriptions of required values.
Edit
• the values in the Ports columns
directly.
Right-click
• the port and click Properties.
Enter values and click OK to save your
changes.
Modify an existing port Choose one of the following actions. Refer to Transfer
Ports tab properties for descriptions of required
values.
• Edit the values in the Ports columns directly.
• Right-click the port and click Properties. Edit
values and click OK to save your changes.
Specify a default port a. Right-click a port that displays the icon.
b. Select Set as Default Port.
Modify a default port
a. Right-click a port that displays the icon.
b. Select Properties.
c. In the Port Properties window, clear the
Default Port check box.
d. Click OK.
4. Check in your changes.

Transfer Ports tab properties

The Ports tab for a transfer contains the following columns.

Field Description

Name The name of the port.

Description Optional. The description of the port.
Port Type Indicates the type of port: Input, Output, or Undirected (for meters, for
example).
Field Description

Allowed Categories The categories to which the port belongs. To assign categories, click and
select categories in the Categorize window.
Maximum Connections The maximum number of connections that can be made to the port. The default
number of connections for a transfer is 1. A value of zero indicates an unlimited
number of connections.
Connection Type The type of connections to which the port can connect. The default connection
types for a transfer are Boundary and Node. For more information on
connection type values, see Element types in models.
Allowed Template Defaults to all element templates, but you can select a specific template from
the list.
Chapter 12

Annotations in PI AF

Beginning with PI AF 2016, the annotation feature is used by client applications such as AVEVA PI Vision, but can
easily be used by administrators to make notes on the following objects:
• Case
• Element
• Event frame
• Model
• Transfer
File attachments
Users can attach a single file to an annotation. By default, the following file types are allowed:
File type Allowed extension

MS Office csv, docx, pdf, xlsx

Text rtf, txt
Image gif, jpeg, jpg, png, svg,
tiff
The maximum file size defaults to 10MB.
Administrators can use the PI AF Diagnostics utility (afdiag located in the \PIPC\AF folder) to specify the file
types that can be attached to annotations (with the FileExtensions parameter), as well as the maximum file size
(with the FileMaxLength parameter).
Security for annotations
A user needs to have a PI AF identity for which the Annotate permission (an) is enabled. For more information on
access rights, see PI AF access rights.

Element annotations
Users can annotate an element, as well as upload a file to link to an annotation.
 Setup of element annotations
You set up an annotation by opening an Annotations window for a specific element that you have selected in the
Elements browser or viewer. In the Annotations window, you can add, edit, and delete annotations, as well as
upload, change, and delete an attachment for an annotation.
Review of element annotations
You review annotation status for an element in the Elements viewer, where an Is Annotated column is displayed
( ).
To view the content of an annotation, move the mouse pointer over the icon beside an element to see the
annotation text. If a file is attached, the name of the file is also displayed.

Add annotations to elements

You can add one or more annotations to an element.
1. In the navigator, click Elements.
2. In the Elements browser, choose one of the following actions.
▪ Click the Elements collection.
▪ Navigate to the specific element you want to annotate.
3. To add a new annotation, choose one of the following actions.
▪ In the Elements browser, right-click an element and click Annotate.
▪ If an element is selected in the Elements browser, click the Annotations link on the General tab in the
viewer.
▪ If the Elements collection is selected in the browser, right-click an element in the viewer and click
Annotate.
Note: To add another annotation to a previously annotated element in the viewer, double-click
beside the element.
4. In the Annotations window, click New Annotation.
5. Enter an annotation in the Comment field.
Note: If you require more space as you type, press F2 and enter an annotation in the Text Visualizer window.
Click OK to close the window.
6. To attach a file to the annotation, click Add Attachment.
a. In the Open window, navigate to the directory where the file you wish to upload is located.
b. Select the file and click Open.
The filename is displayed in the Attachment field.
7. Click Close.
When elements are listed in the Elements viewer, an Is Annotated column is displayed beside the element. Move
the mouse pointer over the icon to see the annotation text. If a file is attached, the name of the file is also
displayed.
Event frame annotations
Users can annotate an event frame, as well as upload a file to link to an annotation.
Setup of event frame annotations
You set up an annotation by opening an Annotations window for a specific event frame that you have selected in
the Event Frames browser or viewer. In the Annotations window, you can add, edit, and delete annotations, as
well as upload, change, and delete an attachment for an annotation.
Search for event frame annotations
You can search for event frames that have been annotated. You review annotation status in the viewer for an
Event Frame Searches collection, where an Is Annotated column is displayed ( ).
To group event frames by their annotation status, you click the column icon.

Add annotations to event frames

To annotate a locked event frame, a user with Administrator permission must first unlock it.
You can add one or more annotations to an event frame.
1. In the navigator, click Event Frames.
2. In the Event Frames browser, click an Event Frame Searches collection.
The contents of the collection are displayed in the viewer. Event frames with existing annotations display an
Is Annotated icon ( ) beside them.
3. To add a new annotation, choose one of the following actions.
▪ In the viewer, right-click an event frame and click Annotate.
▪ In the viewer, double-click an event frame and click the Annotations link on the General tab.
▪ In the Event Frames browser, right-click an event frame in an event frame search collection and click
Annotate.
▪ To add another annotation to a previously annotated event frame, double-click beside the event
frame.
4. In the Annotations window, click New Annotation.
5. Enter an annotation in the Comment field.
Note: If you require more space as you type, press F2 and enter an annotation in the Text Visualizer window.
Click OK to close the window.
6. To attach a file to the annotation, click Add Attachment.
a. In the Open window, navigate to the directory where the file you wish to upload is located.
b. Select the file and click Open.
The filename is displayed in the Attachment field.
7. Click Close.
In the Is Annotated column, is displayed beside the event frame. Move the mouse pointer over the icon to see
the annotation text. If a file is attached, the name of the file is also displayed.
Transfer annotations
Users can annotate a transfer, as well as upload a file to link to an annotation.
Setup of transfer annotations
You set up an annotation by opening an Annotations window for a specific transfer that you have selected in the
Event Frames browser or viewer. In the Annotations window, you can add, edit, and delete annotations, as well
as upload, change, and delete an attachment for an annotation.
Review transfer annotations
You can review annotation status in the viewer for a Transfer Searches collection, where an Is Annotated column
is displayed ( ).
To group transfers by their annotation status, you click the column icon.

Add annotations to transfers

You can add one or more annotations to a transfer.
1. In the navigator, click Event Frames.
2. In the Event Frames browser, click a Transfer Searches collection.
The contents of the collection are displayed in the viewer. Transfers with existing annotations display an Is
Annotated icon ( ) beside them.
3. To add a new annotation, choose one of the following actions.
▪ In the viewer, right-click a transfer in the search result list and click Annotate.
▪ In the viewer, double-click a transfer and click the Annotations link on the General tab.
▪ In the Event Frames browser, right-click a transfer in a Transfer Searches collection and click Annotate.
▪ To add another annotation to a previously annotated transfer, double-click beside the transfer.
4. In the Annotations window, click New Annotation.
5. Enter an annotation in the Comment field.
Note: If you require more space as you type, press F2 and enter an annotation in the Text Visualizer window.
Click OK to close the window.
6. To attach a file to the annotation, click Add Attachment.
a. In the Open window, navigate to the directory where the file you wish to upload is located.
b. Select the file and click Open.
The filename is displayed in the Attachment field.
7. Click Close.
In the Is Annotated column, is displayed beside the transfer. Move the mouse pointer over the icon to see the
annotation text. If a file is attached, the name of the file is also displayed.
Chapter 13

Asset analytics

Asset analytics is the feature in Asset Framework (PI AF) that you use to create and manage analyses. An analysis
reads values of PI AF attributes, performs calculations, and writes results to other attributes. Within PI System
Explorer, you can access asset analytics when you work with elements and element templates.

Introduction to analyses
An analysis performs calculations on a specified schedule. An analysis takes existing PI AF attribute values as
inputs and produces new outputs, either new calculated values or new event frames. Every analysis has an
associated element or element template.
The following types of analyses are available:
• Expression
Calculates one or more output values from specified functions, operators, and input values.
• Rollup
Calculates standard statistical functions for a group of selected attributes. This group is selected from
attributes on an element or from the set of all attributes on its sub-elements.
• Event frame generation
Starts or ends event frames based on specified conditions.
• SQC
Uses Statistical Quality Control (SQC) methods to monitor that attribute values lie within predetermined
boundaries.
All analyses can be created from analysis templates with either Enabled or Disabled status; by default, analyses
will be enabled when created. To create an analysis with Disabled status, make sure to clear the Enable analyses
when created from template check box in the analysis template.
For event frame generation analyses and SQC analyses with event frame outputs, you can create a notification
rule template by clicking Create a new notification rule template for Analysis Template Name.
For expression analyses and event frame generation analyses, you specify inputs in expressions.
For event frame generation analyses (running PI Analysis Service 2017 R2 or later versions), expression and
rollup analyses, you can map analysis outputs to PI AF attributes. If you map outputs to attributes configured as
PI point data references, the analysis saves the history of the output to a PI point. We recommend you save
analysis outputs to PI points. You can use the PI point in visualization tools to view the trend of the analysis.
 Saving outputs to PI points also results in better PI AF performance than saving outputs to attributes without
data references.
Note: PI Analysis Service does not use exception reporting while writing to output configured as PI point data
references. Although exception settings for the output PI point are not used, compression settings for the output
PI point will be used to determine the outputs that are written to Data Archive.
Starting from PI AF 2018 SP2, analyses will honor the display digits configured on an attribute or attribute
template. Values you see when you evaluate an analysis or preview results will display the same number of digits
as your output attribute so long as you have mapped your output attribute. For more information, see Control
the display of attribute and attribute template values.

Configure and manage analyses on an element

A newly-created analysis is listed in the table in Analyses tab. You can see its current status, whether or not it is
associated with a template, its analysis type, name, and backfilling/recalculation status. Hover over items or
icons in the list to see descriptive tooltips. To manage multiple analyses in the Management pane, see
Management of analyses.
To view the expression and scheduling for an analysis, select it from the Analyses viewer.
You can perform these operations from the Analyses viewer:
• Create a new analysis
You can click (New Analysis) at the top of the viewer, or right-click anywhere in the viewer and click New.
• Enable or disable a selected analysis
You can select an analysis and click (Enable Analysis) or (Disable Analysis) at the top of the viewer.
• Choose columns to display
You can right-click any column heading and select headings to display.
• Preview results
You can preview results for an analysis to see how it operates over a specified time range by right-
clicking an analysis and selecting Preview Results. You can export the results table to a
spreadsheet or you can copy selected rows from the results table into other applications.
For information on viewing trend charts for output times that are specified relative to trigger times, see
Trend charts in Preview Results.
• Backfill or recalculate data for an analysis
You can execute an analysis over an earlier time period to backfill or recalculate data, as described in Backfill
or recalculate data for an analysis.
An expression, rollup, or SQC analysis can backfill or recalculate data if the analyses outputs are mapped to
PI point attributes. You can backfill the missing data in a time range and retain existing data, or you can
recalculate, which deletes and recalculates data in the time range.
An event frame generation analysis can also recalculate event frames over a specified time period. The
recalculation process, however, automatically deletes all existing event frames for that time period, as well
as annotations on affected event frames.
 In order to backfill/recalculate, you need Execute permission on the analyses. Proper permission can be
obtained by mapping your account to Asset Analytics Recalculation identity. Note that recalculation is only
available for PI Analysis Service 2016 R2 or later. In addition, Data Archive that stores PI points must be
running version 2016 R2 or later.
• Enable automatic recalculation for an analysis
From PI AF 2017 R2, you can automatically recalculate analyses. Although automatic recalculation is globally
enabled by default, you need to opt in at individual analysis (template) level if you expect late-arriving or
out-of-order data that may trigger recalculation.
An analysis listed with means automatic recalculation is enabled. See Configure automatic recalculation of
analyses and analyses templates for more information.
• Go to template
An analysis listed with alongside is based on an analysis template. You can open the template directly from
the analysis by right-clicking the analysis and selecting Go to Template.
Note: You can go to the analysis directly from the attribute by right-clicking the attribute and clicking Go to
Analysis. If there is no analysis configured on the attribute, you will see New Analysis instead.
• Audit Trail Events
You can open the audit log directly from the analysis by right-clicking the analysis and selecting Audit Trail
Events. For more information on audit trail, see Track PI AF changes with Audit Trail.
• Reset to template
Only scheduling changes can be made to an analysis that is based on an analysis template. To revert an
analysis' scheduling to template scheduling, right-click the analysis and click Reset to Template.
• Convert to template
If the element for an analysis is derived from an element template, you can convert the analysis to an
analysis template on that element template by right-clicking the analysis and selecting Convert to Template.
This feature enables you to develop and debug an analysis against a specific element before generalizing it as
a template.
Note: If any of the analysis outputs write to a specific PI point, you will be prompted to choose how to
specify the PI point in the analysis template to ensure the outputs of derived analyses write to unique PI
points.
To create specific types of analyses, see:
• Create an expression analysis
• Create a rollup analysis
• Create an event frame generation analysis
• Create an SQC analysis

Analysis templates
To apply an analysis to an element, you specify the element directly as you create the analysis. However, to apply
an analysis to a group of elements (created from the same element template), it is much more efficient to use an
analysis template than to apply the analysis individually to each element.
 An analysis template defines the form of an analysis. Analyses derived from it are all similar but have specific
input and output attributes. Analysis templates let you take advantage of your PI AF hierarchy. Every element
derived from an element template automatically acquires analyses from its analysis templates.
You create an analysis template on an element template in much the same way you create an analysis on an
element. When you add or change an analysis template on an element template, those changes propagate to
every element derived from the element template. Deleting an analysis template deletes all analyses derived
from it, except for analyses tied to notifications.
With PI Server 2015 R2 and later versions, while creating an analysis template on an element template that is
derived from a base element template, you can choose input attributes from attribute templates that are
defined on derived as well as base element templates. Similarly, you can map analysis outputs to derived as well
as base template attributes.
Note: An analysis derived from an analysis template cannot be removed from an element directly.
To create specific types of analysis templates, see:
• Create an expression analysis template
• Create a rollup analysis template
• Create an event frame generation analysis template
• Create an SQC analysis template

Updates of analyses and analysis templates

As soon as a new analysis is checked in, it is automatically enabled and available to run. Any change that is
checked in is immediately picked up by all the analyses affected by it, even if they are running. Changes that can
affect an analysis include:
• Edits made directly to the analysis
• Changes to an element that impact its analyses, including adding or deleting an analysis
• Changes to an element template, which propagate to all elements that come from the template, including
adding or deleting an analysis template
• Changes to an analysis template, which propagate to all analyses that come from the template
• Changes to an event frame template used by an analysis; new event frames are based on the updated
template

Excluded attributes in analyses

In PI Asset Framework 2015, excluded attributes were introduced. For more information on excluded attributes,
see Excluded attribute property. Beginning with PI AF 2018, behavior and handling of excluded attributes have
changed in expression, event frame generation and SQC analyses.
Prior to 2018, analyses configured with excluded attributes would return Calc Failed when evaluated and go into
error. Beginning with PI AF 2018, such analyses will be suspended and marked by an icon ( ) in the Analyses
Viewer. If you hover over the icon, you will see a tooltip with more information.
If you do not want the analyses with excluded attributes to go into a suspended state, you can validate the
excluded attribute with an expression function BadVal. Assuming 'att1' is an excluded attribute, below is an
 example of how BadVal could be used to prevent the analysis from being suspended. In this case, the analysis
will continue to run:
If BadVal('att1') Then ('att2') Else ('att1' + 'att2)
Note: Any change in the configuration of the excluded attribute in the analysis is automatically picked up by PI
Analysis Service. For example, if you decide to change the property of 'att1' to be no longer excluded and check it
in, the service will detect it and run the analysis with 'att1.'
When you select Event-Triggered as a scheduling option, you are required to select a triggering input. Note that
if the excluded attribute is the only available triggering input, the analysis will be suspended whether or not you
validate it with BadVal. It is because analyses do not trigger on excluded attributes. Make sure that you have
other inputs to trigger on in your analyses. For more information, see Analysis scheduling.

Analysis scheduling
Each analysis requires you to specify scheduling. Scheduling indicates when to evaluate an analysis automatically.
There are two types of scheduling:
• Periodic
With periodic scheduling, evaluation occurs based on clock time (DateTime object expressed as
Coordinated Universal Time (UTC)). You can specify a specific time for evaluation each day or the
time between evaluations. With PI Server 2015 R2 and later versions, the maximum frequency you
can set for analyses is 120 times per second.
Note: If you have analyses that are previously configured to run more than 120 times per second, you must
reduce the period to less than the allowed maximum, else they will generate errors while running with PI
Server 2015 R2. Similarly, if you are setting periodic scheduling outside of the PI System Explorer user
interface, make sure that the period is set to less than the allowed maximum.
If the period is not divisible by the 24, 7 minutes for example, the evaluation time will reset at the beginning
of each day. Let's say you have scheduled the analysis to run every 7 minutes and the last evaluation was at
11:56pm. The next evaluation will be at midnight (4 minutes later), not at 12:03am the next day.
• Event-Triggered
With event-triggered scheduling, evaluation occurs based on events. You can specify one or more
input attributes that trigger an evaluation whenever the attribute value changes.
Note: When auto-backfilling is enabled, triggering events with time stamps before analysis service start-time
are ignored for the purpose of real-time evaluation. For more discussion on real-time evaluation and auto-
backfilling, including the setting of the AutoBackfillingEnabled configuration parameter, see Analysis service
configuration.
By default, analyses use event-triggered scheduling, triggered on changes to any input.
Many factors affect the speed that an analysis runs and writes output values:
• System architecture, including inputs and outputs
• Network configuration
• Load and performance of different computers
Monitor and test your analyses, especially those scheduled at high frequencies, to ensure the system resources
support the configuration.
Output time stamps for analyses
For any scheduled analysis, the default time stamp for output values is the trigger time. For periodic scheduling,
the trigger time is the scheduled evaluation time, and for event-triggered scheduling, the trigger time is the time
that a specified attribute changes values.
You can specify the time stamp of analysis output values. By specifying an output time stamp, you can:
• Produce results that are time-stamped at a specified offset from the trigger time.
• Produce results that are time-stamped at a particular time each day, regardless of when the analysis is
actually evaluated. For example, you can ensure a 6:00 p.m. time stamp for the output of an analysis that
calculates results for a daily production shift ending at 6:00 p.m., even if the analysis is not actually evaluated
until 10:00 p.m.
• Repeatedly evaluate an analysis to calculate a forecast value for a particular date and time, as input
conditions change. The results of each evaluation have the same timestamp: the analysis output values
reflect results from the most recent evaluation.

Specify time stamp for analysis outputs

Use the Advanced options window in an analysis to specify the time stamp of analysis output values.
1. In the Elements browser, select an element, and in the viewer, click the Analyses tab.
2. From the list of analyses, select an analysis, and then click Advanced in the scheduling area near the bottom
of the window.
3. In the Advanced options window, specify the output time stamp:
▪ Trigger Time
Default value. The clock time that a schedule specifies or that an input value changes.
▪ Execution Time
The clock time at which the analysis calculates the value. This differs from the trigger time when the
system has a lag time or when there is a configured calculation wait time (see
CalculationWaitTimeInSeconds in Analysis service configuration).
▪ Relative to Trigger Time
A time specified by a PI time expression. Enter a valid time expression, such as a time relative to the
trigger time or a fixed time. In the expression, the current time and implied reference time is the
trigger time (that is, the clock time that the schedule specifies or that an input value changes). If you
enter a fixed time, all output values from the analysis will have the entered time stamp. When not
specified, the default unit of measure for relative time is hours.
For information on viewing trend charts for output times that are specified relative to trigger times,
see Trend charts in Preview Results.
▪ Variable
Use the value of a variable as an output timestamp. Variable must be a timestamp of value type
DateTime or, a String that can be parsed as DateTime. If this value is calculated from an expression,
PI Analysis Service uses the calculated value for each trigger events as the output timestamp. This
option is only available for expression analyses.
 You can preview your results by right-clicking the analysis and selecting Preview Results. For more
information, see Trend charts in Preview Results.

Trend charts in Preview Results

When you right-click an expression or rollup analysis and select Preview Results, you see the trend chart with
input and output attribute values at different trigger times.
If you select Relative to Trigger Time and specify '*-8h' as output time stamp for example, you see two trend
charts displayed, one for input and the other for output. The input chart shows the same time range as the
configured start and end time; however, the output chart shows the time that is calculated using the output time
stamp override to the trigger time. Each trend chart shows a maximum of four input and four output attributes;
currently, the input or output attributes that are displayed on the chart are automatically selected by PI Analysis
Service.
In the table, the column Output Time indicates the output time calculated with the time stamp override.
Note: The Preview Results charts may depict data that differs from the actual results of the PI Analysis Service.
For example, if the same timestamp data is overwritten several times, the Preview Results table and charts show
each written value of the data point, but the PI Analysis Service only uses the last written value.

Expressions for analyses

For expression analyses and event frame generation analyses, you specify inputs and calculations in expressions.
In PI System Explorer, you enter each expression in a row. Each row has the following columns:
• Name
A variable name for the value computed by the row. This variable is internal to the analysis. You can use this
variable as an input to expressions specified by subsequent rows in the analysis.
• Expression
The specification of a calculation performed. The expression can include PI AF attributes, variables from
earlier rows in the analysis, and functions.
• Value at Evaluation
The current computed value of the expression. Click Evaluate to compute again.
• Value at Last Trigger
The value when the last trigger was computed.
• Output Attribute
For expression analyses, the attribute that stores the computed value. If the analysis contains multiple
expressions, you can map the value from any expression to an output attribute. However, at least one
expression must be mapped to an output attribute.
For example, an expression analysis might contain one expression, specified in a single row.
Name Expression Value at Output Attribute
Evaluation

Variable1 PrevVal('Att1') - 100 505 Analysis1_Output

You can also specify the calculation of an analysis with multiple expressions across several rows. For example, an
analysis might contain three expressions: the first two calculate variables V1 and V2, which are used as inputs to
the last expression.
Name Expression

V1 'Att1'/2

V2 'Att2' - 'Att3'

Result V1 + 3*V2

Analyses with multiple expressions evaluate the expressions in order: the top row first, the one below it next,
and so on. Because expressions in lower rows may depend on results from higher rows, you can reorder the rows
to evaluate them in the proper order.

You can click Add a new variable to add a row and the icon to delete it.
Tip: You can add a line break within the expression by clicking shift+enter.
You can make your expressions easier to read by adding comments next to or within an expression. Use double
slash (//) to introduce a comment or place the comment between slash asterisk (/*) and asterisk slash (*/).
// Add comments here
IF x THEN y ELSE /*Do this if x is false*/ z

Expression specification
To create an expression, click in the Expression column of a row and then specify the input attributes, variables,
and functions that define a calculation. You can do the following:
• Select and insert attributes and functions into the expression from the Functions and Attributes panels to
the right of the expression.
• Enter the text directly into the expression. As you type, functions, attributes, and variables that match what
you entered appear in a selection list at the cursor: you can select an item you want to insert.
• Attributes and time expressions are enclosed in single quotes.
• Strings are enclosed in double quotes.

Expression simplification with refactoring

In real-world applications, the expression in an analysis can be extremely complex; lengthy attribute names can
add to the complexity. To simplify a complicated expression, refactor it into a group of smaller expressions
assigned to variables.
Refactored analyses are easier to understand. Refactored analyses are also easier to test and debug: you can
evaluate the smaller expressions one at a time and isolate any errors.
To refactor an analysis, define components of the analysis as separate expressions and reference by variable
name. For example, you might define a separate expression that defines a long attribute name as a separate
 variable or that defines a particular calculation as a separate variable. To create these separate expressions,
simply add new expression rows to the analysis and enter text in the Name and Expression columns.
To reduce typing, you can select a term in an expression, right-click the selection, and then click Assign to
variable. In the row above the expression, PI System Explorer inserts a new row that maps the selected term to a
new variable name. In the original expression, PI System Explorer replaces the term with the new variable name.
You can edit the name of any row. However, if you change the name of an expression row already used as a
variable in other expressions, you break the connection between the expressions.
Example
Suppose you have a complex expression defined in a single row:

Name Expression

Variable1 2*'LongAttributeName' + Avg('Att2', 'Att3', 'Att4')

You can refactor the expression into the following three rows that contain simpler expressions. Note that the
third row uses the names of the earlier rows as variables.

Name Expression

Variable1 'LongAttributeName'

Variable2 Avg('Att2', 'Att3', 'Att4')

Variable3 2*Variable1 + Variable2

Future data and analyses

You can use future data as input to an analysis. You can also use an analysis to produce future data by specifying
a future time stamp for the output from an analysis.
Expressions can use values from future events as input to an analysis. However, if an analysis uses event-
triggered scheduling, inputs with future data can generate analysis evaluations. If a trigger attribute has future
events, an evaluation occurs as each event becomes current, when the clock time coincides with the time of that
event.
The following sections show two uses of future data in analyses. The first example shows how to use future data
as an input to an analysis. The second example shows how to use an analysis to produce future data.
Example: Input future data to evaluate forecast values
Suppose you need to evaluate forecast values for the outside temperature provided by a third-party service. To
do that, create an analysis that finds the difference between forecast and actual values.
The analysis needs two input attributes:
• ActualTemp
Stores near real-time temperature readings from an outside thermometer.
• ForecastTemp
Stores future data, in this case forecast values for the outside temperature each day at 6 a.m., 2 p.m., and 10
p.m.
The analysis calculates the difference between the ActualTemp and ForecastTemp values and writes results to an
output attribute named DeltaTemp.
Choose event-triggered scheduling for the analysis with the ForecastTemp attribute as the only triggering input
attribute. With event-triggered scheduling, an evaluation occurs when the analysis detects a new event for a
trigger attribute. Because this trigger attribute stores future data, the analysis detects a new event three times a
day, when the clock time reaches 6 a.m., 2 p.m., and 10 p.m.; this triggers an evaluation and a new result for the
DeltaTemp attribute.
Example: Output future data to calculate weekly emissions goals
Suppose you need to set weekly goals for emissions at a cement plant that operates under a voluntary annual
CO2 cap. The weekly goal will likely change every week in response to the actual emission levels of the past week
and to the amount remaining under the voluntary annual cap.
At the end of every week, you know actual emissions since the beginning of the year and can calculate a new
weekly emissions goal. You want the time stamp for the new goal to be exactly one week from the calculation
time, which coincides with the calculation time of the actual emissions for the next week.
In PI AF, create attributes for the parameters the calculations require, such as the annual cap.
Next, create a new expression analysis that calculates an output attribute named WeeklyGoal. The analysis
completes the following steps:
1. Find the actual emissions since the beginning of the year.
2. Find the difference between the year-to-date total and the annual cap.
3. Divide the difference by the number of days remaining under the annual cap and multiply by seven to
calculate the WeeklyGoal attribute.
4. Save the WeeklyGoal attribute as a future PI point, which preserves history and allows for trending and other
uses.
When creating the analysis, choose periodic scheduling for every day at 12:00 a.m. The syntax of the analysis
ensures the calculations only run on Sunday.
Finally, specify the time stamp for the analysis outputs. Enter the expression * + 7d to set the time stamp to
exactly seven days from the trigger time. The WeeklyGoal attribute will have a time stamp that is one week in the
future (that is, the following Sunday at 12:00 a.m.).
Chapter 1 Types of analyses
There are four categories of analyses you can create in Asset Analytics:
• Expression
• Rollup
• Event frame generation
• Statistical Quality Control (SQC)

Expression analyses
Expression analyses calculate one or more output values from specified functions, operators, and input values.
You specify the inputs and calculations for these analyses in expressions. You can map any output that an
expression calculates to an attribute. You must map at least one output to an attribute.
You can map the output to an existing attribute or you can create a new attribute when you map the output. If
you create a new attribute when you map the output (from the Analyses tab in PI System Explorer), you must
choose whether or not to save the output history; the system creates the appropriate type of attribute:
• If you choose to save output history, the system creates an attribute with a PI point data reference and
creates a PI point in the specified Data Archive. With the output saved in a PI point, you can use visualization
tools to see the trend associated with the calculation, and you can retrieve the value for any time that the
analysis performed the calculation. The analysis calculates and stores a value as specified by the analysis
schedule.
• If you choose not to save output history, PI System Explorer creates an attribute with an analysis data
reference. An analysis only calculates the value for expressions mapped to attributes with an analysis data
reference when requested. For best performance, map output attributes to attributes with analysis data
references if you only need to know the most recent value and do not need previous values.

Create an expression analysis template

In PI System Explorer, you can create an expression analysis template for an element template. In the template,
you can create an expression for each calculation. To record the value that an expression calculates, map the
output to an attribute template. You can create new attribute templates from the expression-analysis template.
1. In the navigator, click Library.
2. In the Library browser, select the element template where you want to create the analysis template.
3. In the viewer, click the Analysis Templates tab.
The tab lists any analysis templates already defined for the element template.
4. Create a new analysis template for the element template:
▪ If no analysis templates exist, click Create a new analysis template to create the first one.
▪ Otherwise, click New Analysis Template to create a new one.
5. Enter information to identify the analysis:
▪ Name
 The name that uniquely identifies this analysis.
▪ Description
Optional text that describes the analysis.
▪ Categories
Optional category that you can assign to the analysis. Click the list and select the check box next to
categories you want to assign or click New to create a new category.
▪ Analysis Type
Click Expression.
6. Optional. Clear the Enable analyses when created from template check box so that the analysis is created in
Disabled status.
By default, a new analysis will be created with Enabled status. You must clear the option if you do not want
to start the analysis when created.
7. Optional. To temporarily evaluate expressions in the analysis template based on values of a particular
element, click the Select an example element link and select an element based on the current element
template.
If no elements have been created from the current element template, you must create an element first.
Templates have no concrete data associated with their attributes. You cannot evaluate an expression in an
analysis template, unless you borrow attribute values from a specific element.
PI System Explorer sets Example Element to the element you selected.
8. Specify one or more expressions for the analysis.
Enter each expression in a row. An expression specifies inputs and calculations. See Expressions for analyses.
9. Map at least one expression to an output attribute template.
a. In the Output Attribute column for the expression, click Map.
b. Specify the attribute template.

To ... Do this ...

Map the output to an existing attribute template Click the name of the attribute template.
Select an attribute template with a PI point data
reference to store the history of the calculation. For
best performance when you do not require history,
use an attribute template with an analysis data
reference.
To ... Do this ...

Map the output to a new attribute template 1. Click New Attribute Template to open the
Attribute Template Properties window.
2. Indicate whether the attribute should save the
history of the output:
▪ Click Yes to create an attribute with a PI point
data reference. This attribute saves the
history of the output.
▪ Click No to create an attribute with an
analysis data reference. This attribute
calculates a new value when requested.
3. Configure the attribute template to create:
▪ Name
Name of created attribute.
▪ Description
Optional text that describes the attribute.
▪ Data Server
For attributes that save output history,
the Data Archive server that stores the PI
point data reference. By default, this is
set to %Server%, which sets to the default
Data Archive server.
▪ Value Type
The data type the attribute stores.
After creating the attribute template, you can
refine its definition from the Attribute
Templates tab.
4. Click OK to create the attribute template.
1. Optional. If you specified an example element, click Evaluate to verify that output values of individual
expressions.
Specify scheduling for the analysis. See Analysis scheduling.
2. Optional. If you specified an example element, verify the analysis by reviewing the results produced with
historical data:
a. In the analysis list, right-click the analysis and then click Preview Results.
b. Enter a start time and end time not later than the current time, and click Generate Results to see a list of
results.
3. To apply changes and save your work locally, click on the toolbar.
4. Click Check In on the toolbar to save the analysis template to the PI AF server and to create the analysis for
any element based on the element template.

Create an expression analysis

In PI System Explorer, you can create a unique expression analysis for an individual element. In the analysis, you
can create an expression for each calculation. To record the value that an expression calculates, map the output
to an attribute. You can create new attributes as you configure an analysis.
1. In the navigator, click Elements.
2. In the Elements browser, select the element where you want to create the analysis.
3. In the viewer, click the Analyses tab.
The tab lists any analyses already defined for the element.
4. Create a new analysis for the element:
▪ If no analyses exist, click Create a new analysis to create the first one.
▪ Otherwise, click New Analysis to create a new one.
5. Enter information to identify the analysis:
▪ Name
The name that uniquely identifies this analysis.
▪ Description
Optional text that describes the analysis.
▪ Categories
Optional category that you can assign to the analysis. Click the list and select the check box next to
categories you want to assign or click New to create a new category.
▪ Analysis Type
Click Expression.
6. Specify one or more expressions for the analysis.
Enter each expression in a row. An expression specifies inputs and calculations. See Expressions for analyses.
7. Map at least one expression to an output attribute:
a. In the Output Attribute column for the expression, click Map.
b. Specify the attribute.

To ... Do this ...

Map the output to an existing attribute Click the name of the attribute.
Select an attribute with a PI point data reference to
store the history of the calculation. For best
performance when you do not require history, use
an attribute with an analysis data reference.
Map the output to a new attribute 1. Click New Attribute to open the Attribute
Properties window.
2. Indicate whether the attribute should save the
history of the output:
▪ Click Yes to create an attribute with a PI
point data reference. This attribute saves
the history of the output.
▪ Click No to create an attribute with an
analysis data reference. This attribute
calculates a new value when requested.
3. Configure the attribute:
▪ Name
Name of created attribute.
▪ Description
Optional text that describes the
attribute.
▪ Data Server
For attributes that save output history,
the Data Archive server that stores the
PI point data reference. By default, this
is set to %Server%, which sets to the
default Data Archive server.
▪ Value Type
The data type the attribute stores.
After creating the attribute, you can refine
its definition from the Attributes tab.
4. Click OK to create the attribute.
1. Optional. Click Evaluate to verify the output values at both Value at Last Trigger and Value at Evaluation
times.
Specify scheduling for the analysis. See Analysis scheduling.
2. Optional. To verify the analysis, review the results produced with historical data:
a. In the analysis list, right-click the analysis and then click Preview Results.
b. Enter a start time and end time not later than the current time, and click Generate Results to see a list of
results.
3. To apply changes and save your work locally, click on the toolbar.
This does not run the analysis.
4. Click Check In on the toolbar.
 PI System Explorer saves and checks in your analysis, and then starts running the analysis.

Rollup analyses
A rollup analysis calculates statistical values such as sum and average for selected attributes associated with an
element. For example, a rollup analysis on a factory element might use temperature attribute values for all
pumps in the factory to calculate their average temperature.
You can choose either of two sources for attributes to include in a rollup analysis:
• Attributes of the element
For example, you want to verify that the level of a tank is constant by checking that all inflows and outflow
sum to zero. From the list of the tank element's attributes, select its inflow and outflow attributes for a
summation calculation. A rollup using an element's own attributes is also known as an aggregation.
• Attributes of the element's child elements
For example, you want to calculate average energy consumption for a group of pumps in a refinery. To do
that, you create a roll-up analysis on the parent element (the refinery) that averages energy consumption
attributes from its child elements (pumps).
Use selection criteria to select attributes for rollup. You can select attributes that match attribute name text you
enter or that are associated with a category or element template you specify.
With PI Server 2015 R2 and later versions, you can select child attributes for rollup analyses. For more
information, see Create a rollup analysis.
You must specify one or more functions to calculate statistics on the selected attributes in the rollup (see Rollup
analysis functions). Be sure each output is mapped to an output attribute.
Be aware that:
• You should select attributes carefully to obtain sensible results. Avoid selecting a set with mixed units of
measure (UOM; such as temperature and mass) or value types (such as numeric values and time stamps). As
long as the inputs and outputs have different units within the same UOM class, the system makes reasonable
effort to convert the input units to that of the output for calculation.
• You can add or delete elements or attributes in your hierarchy without the need to update roll-up analyses.
Because a rollup identifies input attributes each time it is executed, it automatically includes any new
attributes that meet its selection criteria.
• Some selected attributes (such as those with string values) will not participate in rollup calculations, which
operate only on numeric or DateTime values.

Rollup analysis functions

You can specify one or more of the functions listed below to calculate statistics on the input attributes in a rollup
analysis.
• Bad input attributes are omitted from rollup analysis. For example, if you have 5 attributes that match the
criteria but 1 is a bad value, Count function will return 4.
• Input value types numeric, DateTime and Enumeration value are supported for functions Minimum,
Maximum, and Count. Function Average takes numeric and DateTime value types. Input values for all other
functions must be of numeric value type.
 Function Description Supported data types

Sum The sum of values from selected attributes. Numeric

Average The average (mean) of values from two or more selected attributes. Numeric, DateTime
Minimum The minimum value from selected attributes. Numeric, DateTime,
Enumeration value
Maximum The maximum value from selected attributes. Numeric, DateTime,
Enumeration value
Count The number of attributes actually used in rollup calculations, which can Numeric, DateTime,
differ from the total number of selected attributes. For example, an Enumeration value
attribute containing a string value (such as a part name) might meet the
selection criteria but would not participate in rollup calculations and
would be excluded for Count.
Median The middle value of three or more values from selected attributes; for Numeric
an even-numbered group of values, the average of the two middle
values. An equal number of values fall above and below the median.
Population The population standard deviation, which is calculated using the entire Numeric
standard population. Useful when all values in a population are available to
deviation include as inputs for the calculation.
Sample The sample standard deviation, which is calculated using values from a Numeric
standard sample of a population. Useful to provide an estimate of the population
deviation standard deviation when it is impractical or impossible to include all
population values in the calculation.

Create a rollup analysis template

In PI System Explorer, you can create a rollup analysis template for a selected element template. You select input
values for the rollup either from attributes of the selected element template or from the attributes of a child
element template (whose parent element is derived from the element template). You can choose an example
child element and use its attributes to help you develop a rollup analysis template.
Prerequisite: Identify the statistical functions you want the rollup to calculate and where you want to save the
results. You can map results from a function to an existing attribute of the element template, or you can create a
new output attribute when you configure an analysis template.
1. In the Library browser, select the element template where you want to create the analysis template.
2. Under Rollup attributes from, indicate the source of input values:
▪ Click Child elements of Element Template Name to roll up attributes of child elements of an element
based on the current element template.
▪ Click This element - Element Template Name to roll up attributes of an element based on the current
element template.
3. In the viewer, click the Analysis Templates tab.
The tab lists any analysis templates already defined for the element template.
4. Create a new analysis template for the element template:
▪ If no analysis templates exist, click Create a new analysis template to create the first one.
▪ Otherwise, click New Analysis Template to create a new one.
5. Enter information to identify the analysis:
▪ Name
The name that uniquely identifies this analysis.
▪ Description
Optional text that describes the analysis.
▪ Categories
Optional category that you can assign to the analysis. Click the list and select the check box next to
categories you want to assign or click New to create a new category.
▪ Analysis Type
Click Rollup.
6. Optional. Clear the Enable analyses when created from template check box so that the analysis is created in
Disabled status.
By default, a new analysis will be created with Enabled status. You must clear the option if you do not want
to start the analysis when created.
7. Under Rollup attributes from, indicate the source of input values:
▪ Click Child elements of Element Template Name to roll up attributes of child elements of an element
based on the current element template.
▪ Click This element - Element Template Name to roll up attributes of an element based on the current
element template.
8. Select an example element to provide candidate attributes:
▪ Click the Select an example element link to open a window that shows elements derived from the
selected element template.
▪ Select an element and click OK.
9. Select the attributes to include in the rollup:
If rollup attributes come from: Then:

Child elements a. From the Sample Child Element list, select

the element from which you want to view
attributes.
The table shows attributes of the
selected element. To improve
performance, the table only shows a
limited number of attributes. You can
click the Show more attributes link
below the table to show additional
attributes from the selected element.
b. To the left of the table, specify criteria that
select attributes to roll up:
Attribute
• Name
Type an entire attribute name or part of
a name with wildcard characters. For
example, type temp* to select all
attributes that begin with "temp",
such as Temperature and Temp1.
Note: The selection of attributes
depends on whether Attribute Level
is set to "Root Level" or "Child Level".
•
Attribute Level
Select Root Level to choose from top-
level attributes or Child Level for
child attributes. You cannot choose
both child attributes and top-level
attributes in a single roll-up analysis.
Attribute
• Category
Select a category to limit selected
attributes to those in that category.
Element
• Category
Select an element category to limit
selected attributes to attributes that
have parent elements in that
category.
•
Element Template
Select an element template to limit
selected attributes to attributes that
have parent elements based on that
template.
Note: The criteria apply to all
attributes of any child element,
not just those shown in the table.
You can specify criteria that select
attributes not shown in the table. For
 If rollup attributes come from: Then:

This element To the left of the table, specify criteria that select
attributes to roll up:
• Attribute Name
Type an entire attribute name or part of
a name with wildcard characters. For
example, type temp* to select all
attributes that begin with "temp",
such as Temperature and Temp1.
Note: The selection of attributes
depends on whether Attribute Level
is set to "Root Level" or "Child Level".
• Attribute Level
Select Root Level to choose from top-
level attributes or Child Level for
child attributes. You cannot choose
both child attributes and top-level
attributes in a single roll-up analysis.
• Attribute Category
Select a category to limit selected
attributes to that category.
The table shows a check mark next to any displayed attribute included in the rollup.
10. In the functions table, specify the rollup calculations and output:
a. Select the check boxes next to any statistical function you want the rollup to calculate.
b. Click Map to store results from a calculation to an output attribute.
You can map the output to an existing attribute or map the output to a new output attribute.
c. Optional. At the top of the table, click Evaluate to verify the output values of the selected functions.
11. Optional. To verify the analysis, examine the results produced with historical data:
a. In the analysis list, right-click the analysis and then click Preview Results.
b. Enter a start time and end time not later than the current time, and click Generate Results to see a list of
results.
12. To apply changes and save your work locally, click on the toolbar.
13. Click Check In on the toolbar to save the analysis template to the PI AF server and to create the analysis for
any element based on the element template.

Create a rollup analysis

In PI System Explorer, you create a rollup analysis for a selected element. You select input attributes for the rollup
either from attributes of the selected element or from attributes of child elements.
Prerequisite: Identify the statistical functions you want the rollup to calculate and where you want to save the
results. You can map results from a function to an existing attribute of the element, or you can create a new
output attribute when you configure the analysis.
1. In the navigator, click Elements.
2. In the Elements browser, select the element where you want to create the analysis.
3. In the viewer, click the Analyses tab.
The tab lists any analyses already defined for the element.
4. Create a new analysis for the element:
5. If no analyses exist, click Create a new analysis to create the first one.
6. Otherwise, click New Analysis to create a new one.
7. Enter information to identify the analysis:
▪ Name
The name that uniquely identifies this analysis.
▪ Description
Optional text that describes the analysis.
▪ Categories
Optional category that you can assign to the analysis. Click the list and select the check box next to
categories you want to assign or click New to create a new category.
▪ Analysis Type
Click Rollup
8. Under Rollup attributes from, indicate the source of input values:
▪ Click Child elements of Element Name to roll up attributes of a child element.
▪ Click This element - Element Name to roll up attributes of the current element.
9. Select the attributes to include in the rollup:
If rollup attributes come from ... Do this ...

Child elements a. From the Sample Child Element list, select the elemen
you want to view attributes.
The table shows attributes of the selected element
performance, the table only shows a limited nu
attributes. You can click the Show more attribu
below the table to show additional attributes fr
selected element.
b. To the left of the table, specify criteria that select attrib
up:
Attribute
• Name
Type an entire attribute name or part of a name wi
characters. For example, type temp* to select a
that begin with "temp," such as Temperature a
Note: The selection of attributes depends on whet
Level is set to "Root Level" or "Child Level".
Attribute
• Level
Select Root Level to choose from top-level attribut
Level for child attributes. You cannot choose bo
attributes and top-level attributes in a single ro
analysis.
Attribute
• Category
Select a category to limit selected attributes to tho
category.
Element
• Category
Select an element category to limit selected attribu
attributes that have parent elements in that cat
Element
• Template
Select an element template to limit selected attribu
attributes that have parent elements based on
template.
Note: The criteria apply to all attributes of the
child element, not just those shown in the
You can specify criteria that select attributes not sh
table. For example, if you set Sample Child Elem
element from category CatX but set Element Ca
CatY, you will select none of the attributes in th
the analysis will still include the attributes in th
 If rollup attributes come from ... Do this ...

This element To the left of the table, specify criteria that select attributes to r
• Attribute Name
Type an entire attribute name or part of a name wi
characters. For example, type temp* to select a
that begin with "temp," such as Temperature a
Note: The selection of attributes depends on whet
Level is set to "Root Level" or "Child Level".
• Attribute Level
Select Root Level to choose from top-level attribut
Level for child attributes. You cannot choose bo
attributes and top-level attributes in a single ro
analysis.
• Attribute Category
Select a category to limit selected attributes to tha
The table shows a check mark next to any displayed attribute included in the rollup.
10. In the functions table, specify the rollup calculations and output:
a. Select the check boxes next to any statistical function you want the rollup to calculate.
b. Click Map to store results from a calculation to an output attribute.
You can map the output to an existing attribute or map the output to a new output attribute.
c. Optional. At the top of the table, click Evaluate to verify the output values of the selected functions.
11. Specify scheduling for the analysis. See Analysis scheduling.
12. Optional. To verify the analysis, review the results produced with historical data:
a. In the analysis list, right-click the analysis and then click Preview Results.
b. Enter a start time and end time not later than the current time, and click Generate Results to see a list of
results.
13. To apply changes and save your work locally, click on the toolbar.
This does not run the analysis.
14. Click Check In on the toolbar.
PI System Explorer saves and checks in your analysis, and then starts running the analysis.

Event frame generation analyses

An event frame generation analysis specifies the conditions to start and end event frames automatically.
This type of analysis includes either one or two expressions. When a single condition triggers both the start and
the end of an event frame, only a start trigger expression is needed, depicted by the StartTrigger1 field. For
example, a temperature value rising above a threshold might start an event frame and end it when the value
returns below the threshold. When the start and end conditions are different, an EndTrigger expression is also
needed. Because they test start and end conditions, expressions in event frame generation analyses must
evaluate to true or false. For more information, see Start and end trigger conditions.
You can write up expressions to be used as start or end triggers. If your expression gets very complex, you can
break it into a group of smaller expressions and assign them to variables. For more information, see Expression
simplification with refactoring.
Beginning with the 2018 release, a new way of event frame generation is possible where you do not have to set
an explicit trigger. For more information, see Implicit modes of event frame generation in asset analytics.
When configuring event frame generation analyses, you can add expressions to Outputs at Close group to write
outputs back to event frame attributes. Depending on whether you want to save the history of the output, you
can select either attributes configured with a PI point data reference or static event frame attributes. When
saving output history to event frame attributes configured as a PI Point data reference, the attribute must be
mapped to a corresponding PI Point data reference attribute of the referenced element.
• Outputs from root cause event frames are only written to static attributes.
• Parent event frames with multiple child event frames will also write only to static attributes. For more
information on child event frame generation, see Child event frame generation with multiple start triggers.
In your expressions, you can use inputs that come from assets to write outputs to event frame attributes at the
close of an event frame. You can also use the EventFrame function to access the start time, end time and
duration of the event frame. For more information, see expression function EventFrame.
An event frame naming pattern typically includes substitution parameters. For more information on naming
pattern, see Naming patterns.
• Parameters %Endtime% and %Duration% in an event frame naming pattern will be evaluated at the end of
an event frame when the event frame closes.
• An attribute value may update at any given time. To avoid confusion, substitution parameter %@Attribute%
(which resolves to a value of an attribute) in an event frame naming pattern will always be (re-)evaluated in
the context of a start of an event frame.
• Default naming pattern (%ANALYSIS% %STARTTIME:yyyy-MM-dd HH:mm:ss.fff%) will be used in the absence
of a name or if the event frame name evaluates to a null value.
• In a rare case when the duration of an event frame with %@Attribute% in its naming pattern matches the
configured True for, the event frame name will revert to the default naming pattern.
You can create multiple start triggers for your analysis and specify different Boolean conditions to trigger each
event frame. For more information on multiple start triggers and child event frame generation, see Child event
frame generation with multiple start triggers.
Note: If you change the name of a start trigger from the default name, you must change all the start triggers and
use unique names for each trigger.
A spike in input data can trigger the start of an unwanted event frame. To counter the effects of data spikes, you
can require that the start trigger remain true for a set time interval before creating an event frame. Enter a value
in the True for field to specify the time interval.
You can also specify a Severity level for the trigger. The choices for severity are: None, Information, Warning,
Minor, Major, and Critical.
An event frame generation analysis is based on an event frame template, which specifies the attributes for the
generated event frames. Before you create an event frame generation analysis, be sure an appropriate event
frame template is available.
Event frames usually include a referenced element collection. The element associated with an event frame
generation analysis becomes the primary reference element for its generated event frames. For more
information, see Primary referenced element. Other elements can be referenced using relative paths based on
the primary referenced element, as described in Data references to attributes in other elements.
For some events, such as a forced shutdown, you may want to evaluate the conditions leading up to the event.
To do that, you can have PI Analysis Service generate root cause event frames. When configured, every
generated event frame includes a child root cause event frame that captures attributes for a specified time
interval just before the start of the generated event frame. For more information on generating a root cause
event frame, see step 11 on Create an event frame generation analysis template.
Video
For information on how to set up event frame generation analyses, watch this video:

Implicit modes of event frame generation in asset analytics

Beginning with the 2018 release, users of asset analytics in PI AF have the option to select different modes of
event frame generation. Prior to 2018, users had to explicitly set a start trigger (now called Explicit Trigger). In
2018 or later versions of PI AF, you can choose among the three implicit modes in addition to an explicit trigger:
pulse, step and step continuous. After having selected Event Frame Generation as your analysis type, select one
of the following as Generation Mode:
• Pulse: a transition from zeroth state to any other state starts an event frame, and transition to the zeroth
state ends the event frame. You have an option to generate a root cause event frame in Advanced Event
Frame Settings.
• Step: any change in value ends one event frame and starts the next, except when the value changes to the
zeroth state, which ends the current event frame but does not start a new event frame.
• Step Continuous: all transitions would close the open event frame and start a new event frame
Note that you must select a triggering attribute that is either integer, string or enumeration value for these event
frames. For pulse and step event frames, you will need to select an attribute as a trigger and set zeroth state.
Zeroth state is not supported for step continuous event frames. Zeroth state determines when the event frame
should be closed. You can select zeroth states from digital state or enumeration sets. For more information, see
PI EFGen topic Event start and end detection.

Create an event frame generation analysis template

In PI System Explorer, you can create an event frame generation analysis template for an element template.
1. In the navigator, click Library.
2. In the Library browser, select the element template where you want to create the analysis template.
3. In the viewer, click the Analysis Templates tab.
The tab lists any analysis templates already defined for the element template.
4. Create a new analysis template for the element template:
▪ If no analysis templates exist, click Create a new analysis template to create the first one.
 ▪ Otherwise, click New Analysis Template to create a new one.
5. Enter information to identify the analysis:
▪ Name
The name that uniquely identifies this analysis.
▪ Description
Optional text that describes the analysis.
▪ Categories
Optional category that you can assign to the analysis. Click the list and select the check box next to
categories you want to assign or click New to create a new category.
▪ Analysis Type
Click Event Frame Generation.
6. Optional. Clear the Enable analyses when created from template check box so that the analysis is created in
Disabled status.
By default, a new analysis will be created with Enabled status. You must clear the option if you do not want
to start the analysis when created.
7. Optional. To temporarily evaluate expressions in the analysis template based on values of a particular
element, click the Select an example element link and select an element based on the current element
template.
If no elements have been created from the current element template, you must create an element first.
Templates have no concrete data associated with their attributes. You cannot evaluate an expression in an
analysis template, unless you borrow attribute values from a specific element.
PI System Explorer sets Example Element to the element you selected.
8. From the Event Frame Template list, select the template for the event frame that this analysis generates.
To create an event frame template, see Create event frame templates. An event frame naming pattern
typically includes substitution parameters. For more information on naming pattern, see Naming patterns.
Note: Parameters %Endtime% and %Duration% in an event frame naming pattern will be evaluated at the
end of an event frame when the event frame closes.An attribute value may update at any given time. To
avoid confusion, substitution parameter %@Attribute% (which resolves to a value of an attribute) in an event
frame naming pattern will always be (re-)evaluated in the context of a start of an event frame. Default
naming pattern (%ANALYSIS% %STARTTIME:yyyy-MM-dd HH:mm:ss.fff%) will be used in the absence of a
name or if the event frame name evaluates to a null value.
9. Specify the necessary expressions for the analysis:
a. In the StartTrigger1 row, enter the Boolean expression that specifies the condition that starts an event
frame.
b. Optional. Change the default name of the start trigger.
Note: If you change the name of a start trigger from the default name, you must change the names
of all start triggers and use unique names for each trigger.
 c. Optional. In the True for field, enter the amount of time that the start-trigger condition must be true
before the analysis starts an event frame.
Note: Specify a value in the True for field to reduce unwanted event frames caused by momentary
fluctuations in input data.
d. Optional. In the Severity field, enter the severity of the trigger.
The choices for severity are: None, Information, Warning, Minor, Major, and Critical. If you have defined
multiple start triggers, the one with the highest severity will be the effective start trigger; if all start triggers
have the same severity, the first start trigger in the list will be the effective start trigger.
e. Add multiple start triggers by clicking on Add a new start trigger.
For each start trigger, enter a Boolean expression, specify a value for True for and select a value for Severity.
Note: If you have changed the default name of a start trigger, make sure to assign unique names to
all the start triggers.
f. Optional. If a different condition ends the event frame, enter the expression in the EndTrigger row.
Otherwise, the event frame will close when the start trigger condition is no longer true.
g. Optional. Click Add a new variable to insert a new expression row where you can specify a variable and
expression for use in one of the trigger expressions.
h. Optional. Click Add a new output expression to insert a new expression to write outputs to event frame
attributes.
You can map the output as static (doesn't save history) or PI point (saves history) attribute. When mapping to
PI point attribute, make sure that it is mapped back to the attribute on the asset.
10. Optional. If you specified an example element, click Evaluate to verify that output values of individual
expressions.
11. Optional. Generate a root cause event frame for every event frame that the analysis generates.
A root cause event frame captures asset data, which can help you analyze conditions just before the start of
the event frame.
Note: Outputs from root cause event frames are only written to static attributes.
a. From the Advanced Event Frame Settings window, select Generate child root cause event frame before
parent event frame starts.
b. In the Duration field, enter the length of the root cause event frame.
The root cause event frame starts this long before the generated parent event.
12. Optional. Map a start trigger name and start trigger expression to an event frame attribute.
a. From the Advanced Event Frame Settings window, select Save start trigger name to event frame
attribute and then select an attribute (template) or create a new attribute template on the event frame
template to which the start trigger name is saved.
b. From the Advanced Event Frame Settings window, select Save start trigger expression to event frame
attribute and then select an attribute (template) or create a new attribute template on the event frame
template to which the start trigger expression is saved.
The start trigger name and start trigger expression can now be seen on generated event frames, on the
selected attributes.
13. Specify scheduling for the analysis.See Analysis scheduling.
14. Optional. If you specified an example element, verify the analysis by reviewing the results produced with
historical data:
a. In the analysis list, right-click the analysis and then click Preview Results.
b. Enter a start time and end time not later than the current time, and click Generate Results to see a list of
results.
15. To apply changes and save your work locally, click on the toolbar.
16. Click Check In on the toolbar to save the analysis template to the PI AF server and to create the analysis for
any element based on the element template.

Create an event frame generation analysis

In PI System Explorer, you can create an event frame generation analysis for an individual element.
Prerequisites: Check that an event-frame template is available for the analysis.
1. In the navigator, click Elements.
2. In the browser, select the element where you want to create the analysis.
3. In the viewer, click the Analyses tab.
The tab lists any analyses already defined for the element.
4. Create a new analysis for the element:
5. If no analyses exist, click Create a new analysis to create the first one.
▪ Otherwise, click New Analysis to create a new one.
6. Enter information to identify the analysis:
▪ Name
The name that uniquely identifies this analysis.
▪ Description
Optional text that describes the analysis.
▪ Categories
Optional category that you can assign to the analysis. Click the list and select the check box next to
categories you want to assign or click New to create a new category.
▪ Analysis Type
Click Event Frame Generation.
7. From the Event Frame Template list, select the template for the event frame that this analysis generates.
To create an event frame template, see Create event frame templates. An event frame naming pattern
typically includes substitution parameters. For more information on naming pattern, see Naming patterns.
Note: Parameters %Endtime% and %Duration% in an event frame naming pattern will be evaluated at the
end of an event frame when the event frame closes. An attribute value may update at any given time. To
avoid confusion, substitution parameter %@Attribute% (which resolves to a value of an attribute) in an event
 frame naming pattern will always be (re-)evaluated in the context of a start of an event frame. Default
naming pattern (%ANALYSIS% %STARTTIME:yyyy-MM-dd HH:mm:ss.fff%) will be used in the absence of a
name or if the event frame name evaluates to a null value.
8. Specify the necessary expressions for the analysis:
a. In the StartTrigger1 row, enter the Boolean expression that specifies the condition that starts an event
frame.
b. Optional. Change the default name of the start trigger.
Note: If you change the name of a start trigger from the default name, you must change all the start
triggers and use unique names for each trigger.
c. Optional. In the True for field, enter the amount of time that the start-trigger condition must be true
before the analysis starts an event frame.
Note: Specify a value in the True for field to reduce unwanted event frames caused by momentary
fluctuations in input data.
d. Optional. In the Severity field, enter the severity of the trigger.
The choices for severity are: None, Information, Warning, Minor, Major, and Critical. If you have defined
multiple start triggers, the one with the highest severity will be the effective start trigger; if all start triggers
have the same severity, the first start trigger in the list will be the effective start trigger.
e. Add multiple start triggers by clicking on Add a new start trigger.
For each start trigger, enter a Boolean expression, specify a value for True for and select a value for Severity.
Note: If you have changed the default name of a start trigger, make sure to assign unique names to
all the start triggers.
f. Optional. If a different condition ends the event frame, enter the expression in the EndTrigger row.
Otherwise, the event frame will close when the start trigger condition is no longer true.
g. Optional. Click Add a new variable to insert a new expression row where you can specify a variable and
expression for use in one of the trigger expressions.
h. Optional. Click Add a new output expression to insert a new expression to write outputs to event frame
attributes.
You can map the output as static (doesn't save history) or PI point (saves history) attribute. When mapping to
PI point attribute, make sure that it is mapped back to the attribute on the asset. See Expressions for
analyses for more information.
9. Optional. Generate a root cause event frame for every event frame that the analysis generates.
A root cause event frame captures asset data, which can help you analyze conditions just before the start of
the event frame.
Note: Outputs from root cause event frames are only written to static attributes.
a. From the Advanced Event Frame Settings window, select Generate child root cause event frame before
parent event frame starts .
b. In the Duration field, enter the length of the root cause event frame.
The root cause event frame starts this long before the generated parent event.
 Note: The root cause event frame is created only for the first instance, not for each time that the
trigger is True.
10. Optional. Map a start trigger name and start trigger expression to an event frame attribute.
Note: We recommend that you provide meaningful names to your analysis start triggers while saving them
to an event frame attribute.
a. From the Advanced Event Frame Settings window, select Save start trigger name to event frame
attribute and then select an attribute (template) or create a new attribute template on the event frame
template to which the start trigger name is saved.
b. From the Advanced Event Frame Settings window, select Save start trigger expression to event frame
attribute and then select an attribute (template) or create a new attribute template on the event frame
template to which the start trigger expression is saved.
The start trigger name and start trigger expression can now be seen on generated event frames, on the
selected attributes.
11. Specify scheduling for the analysis. See Analysis scheduling.
12. Optional. To verify the analysis, review the results produced with historical data:
a. In the analysis list, right-click the analysis and then click Preview Results.
b. Enter a start time and end time not later than the current time, and click Generate Results to see a list of
results.
13. To apply changes and save your work locally, click on the toolbar.
This does not run the analysis.
14. Click Check In on the toolbar.
PI System Explorer saves and checks in your analysis, and then starts running the analysis.

Start and end trigger conditions

An event frame generation analysis starts an event frame when the start trigger condition evaluates to true.
Because a random spike in an input value can make the condition true, noisy data can lead to the creation of
many unwanted event frames. To counter the effects of data spikes, you can set a time interval before starting an
event frame by entering a value in the True for field.
When a start trigger condition changes to true, the True for value determines how long to wait to evaluate it
again; if it is still true, an event frame is started.
Note: With Periodic scheduling, the analysis will only evaluate at the time specified in the schedule irrespective
of the True for setting. True for evaluation in this case will be the first periodic evaluation following the end of
True for period.
Depending on how you configure the Periodic schedule, there may not be any evaluation within the True for
period. If you want to ensure that the analysis evaluates within that time frame, you may do so by setting the
periodic schedule to be shorter than the True for value (for example, evaluate every minute and True for 5
minutes) or, opt for an Event-Triggered scheduling.
If you want the analysis to evaluate right at the end of True for period, align the True for to fall on the periodic
schedule (evaluate every 3 minutes with True for value of 9 minutes, for example) or, choose the Event-Triggered
scheduling.
With Event-Triggered scheduling, the analysis will evaluate every time the value of the triggering input attribute
updates. Configuring the analysis to be Event-Triggered and having it triggered off of every input attribute in the
start trigger condition can prevent the analysis from missing evaluations.
The start time for the event frame is the time that the start trigger condition first evaluated to true. The True for
value has no effect on the start or end time of the event frame.
The event frame will close when the start trigger condition is false. Configuring an end trigger is optional. If both
the start and end trigger conditions are configured, the event frame will end when the end trigger condition is
met. This is regardless of whether the start trigger condition still holds true.
Tip: If using both start and end triggers, make sure the expressions never evaluate to TRUE at the same time
since this may lead to event frames with zero second durations.
Try to configure your event frames to use only a start trigger expression.

Child event frame generation with multiple start triggers

PI Analysis Service can capture child event frames. Child event frames are useful when you need to send
escalating notifications or perform an in-depth analysis of the past events. This topic discusses the following:
• Video that shows you how to configure event frames with multiple start triggers
• Effective start triggers
• Example of child event frame generation
Note: This topic is only applicable to the explicit trigger.
Video
For information on setting up event frames with multiple start triggers and severities, watch this video:
Effective start triggers
Event frame generation analysis supports multiple start triggers. When triggering an analysis, the effective start
trigger is determined by taking the following three things into account: trigger evaluation, severity and order of
the triggers.
• Evaluation
If only one start trigger is True, then that is the effective start trigger. If multiple start triggers
evaluate to True, then the analysis must take severity into account.
• Severity
If the multiple start triggers evaluate to True, the one with the highest severity level is the effective
start trigger. For example, if there are two start triggers, StartTrigger1 with severity Major and
StartTrigger2 with severity Critical, and they both evaluate to True at the same point in time, then
StartTrigger2 is considered the effective trigger as it has the higher severity.
Note: Severity levels in decreasing order of magnitude are: Critical, Major, Minor, Warning, Information and
None (default).
• Order
If multiple start triggers with the same severity evaluate to True, then the start trigger defined first is
the effective start trigger.
 In the end, there is only one effective start trigger.
Child event frame generation due to change in the effective start trigger
An analysis with multiple start triggers may automatically create child event frames. For example, an event frame
generation analysis would complete the following steps:
1. A start trigger evaluates to True and there is no open event frame. The analysis starts an event frame.
2. In a subsequent evaluation, while the event frame is still open, the effective start trigger does not change
and continues to evaluate to True. Then the event frame will remain open.
3. Another evaluation causes the effective start trigger to be different than step 1. This causes the analysis to
do the following:
a. Start a new parent event frame with the same start time as the original event frame.
b. Make the original event frame a child of this new parent event frame.
c. Close the original event frame (now a child event frame).
d. Create a new child event frame with the new effective start trigger.
4. Another evaluation does not cause the effective start trigger to change. The analysis keeps both the child
and the parent event frames open.
5. Another evaluation causes the effective start trigger to change again. Then:
a. The child event frame created in 3d closes.
b. Yet another child event frame is created by this new effective start trigger.
6. Another evaluation causes all of the start triggers to be False. Then:
a. Child event frame created in 5b closes.
b. Parent event frame created in 3a closes.

SQC analyses
Using PI System Explorer, you can create SQC analyses that use standard Statistical Quality Control (SQC) tests to
determine if the value of a PI AF attribute lies within user-specified margins of error. Further, you can specify
either attributes or event frames as outputs of your SQC analysis.
The following SQC pattern tests may be selected:
• Outside Control:
Counts the number of samples outside the control limit on one side of the center line.
• Outside 2 Sigma:
Evaluates the sample against a limit drawn 2/3 of the way between the center line and the control limit.
• Outside 1 Sigma:
Evaluates the sample against a limit drawn 1/3 of the way between the center line and the control limit.
• One Side of Center Line:
Counts the number of samples on one side of the center line.
• Stratification:
 Counts the number of samples that fall within the upper and lower One Sigma limits on both sides of the
center line.
• Mixture:
Counts the number of samples that fall outside the upper and the lower One Sigma limits on both sides of
the center line.
• Trend:
Counts the number of samples which are increasing or decreasing in a monotonic sequence.

Create an SQC analysis template

In PI System Explorer, you can create an SQC analysis template for an element template.
1. In the navigator, click Library.
2. In the Library browser, select the element template where you want to create the analysis template.
3. In the viewer, click the Analysis Templates tab.
The tab lists any analysis templates already defined for the element template.
4. Create a new analysis template for the element template:
▪ If no analysis templates exist, click Create a new analysis template to create the first one.
▪ Otherwise, click New Analysis Template to create a new one.
5. Enter information to identify the analysis:
▪ Name
The name that uniquely identifies this analysis.
▪ Description
Optional text that describes the analysis.
▪ Categories
Optional category that you can assign to the analysis. Click the list and select the check box next to
categories you want to assign or click New to create a new category.
▪ Analysis Type
Click SQC.
6. Optional. Clear the Enable analyses when created from template check box so that the analysis is created in
Disabled status.
By default, a new analysis will be created with Enabled status. You must clear the option if you do not want
to start the analysis when created.
7. Optional. Select an example element.
8. Provide the inputs for the SQC pattern test. All these inputs should be attribute templates previously defined
in your PI System.
a. In the Source field, select the PI AF attribute template that provides the data for the pattern test.
 b. In the Upper Control Limit and Lower Control Limit fields, select the PI AF attribute template that
provides the data for the largest and smallest limits on the dimension of the data being tested.
c. In the Center Line field, select the PI AF attribute template that provides the normal or ideal value of the
data.
9. Choose the output of your analysis as either Event Frame or AF attribute.
If you choose Event Frame, select an event frame template. If you choose AF attribute, you can either
choose from a list, or create a new attribute template. SQC Analysis rule automatically creates an
enumeration set named SQC Enumeration. This enumeration set has the same values used in Data Archive
SQC DigitalState set so that continuity with the existing Data Archive is preserved. SQC Enumeration is
created when: 1) you map the output to a new AF attribute, 2) this or another enumeration set with the
required name and values does not already exist and 3) you have the right to create enumeration sets.
AF attribute output defaults to a string attribute if the aforementioned conditions are not met.
10. Optional. Generate a root-cause event frame for every event frame that the analysis generates.
A root-cause event frame captures asset data, which can help you analyze conditions just before the start of
the event frame.
a. From the Advanced Event Frame Settings menu, select Generate Child Root Cause Event Frame Before
Parent Event Frame Starts.
b. In the Duration field, enter the length of the root-cause event frame.
The root-cause event frame starts this long before the generated parent event.
Note: The root-cause event frame is created only for the first instance, not for each time that the
trigger is True.
11. Optional. Map a start trigger name and start trigger expression to an event frame attribute.
a. From the Advanced Event Frame Settings window, select Save start trigger name to event frame
attribute and then select an attribute template on the event frame template to which the start trigger
name is saved.
b. From the Advanced Event Frame Settings window, select Save start trigger expression to event frame
attribute and then select an attribute template on the event frame template to which the start trigger
expression is saved.
The start trigger name and start trigger expression can now be seen on generated event frames, on the
selected attributes.
12. Enter SQC pattern test information.
a. Select the check box for each SQC pattern test that you wish to apply to your data.
b. In the X of Y column, select appropriate numerical values for X and Y for each selected pattern test that
requires this input.
Specify the number of values X out of a number of sampled values Y that can be above or below the
corresponding pattern test limits.
Patterns (X and Y values) suggested by Western Electric are shown by default.
Note: X may not be greater than Y.
c. Select the Limit as Above, Below or Both, for each selected pattern test.
 By default, tests are applied on both sides of the center line.
13. Optional. Select the Clear on Control Limit Change check box.
With Clear on Control Limit Change selected, if any of the control limits changes, asset analytics resets the
state of a running SQC calculation, and the SQC calculation is restarted with the changed values. In addition,
associated open event frames are closed before the calculation is resumed.
With Clear on Control Limit Change not selected, the calculation simply proceeds using the changed values
for the control limits.
If all selected SQC tests pass, the Output Value field displays "Normal". If some tests fail, the Output Value
field shows the highest priority test that failed. Changing any of the SQC inputs will clear the Output Value
field.
14. Optional. Click Evaluate to verify the output values at both Value at Last Trigger and Value at Evaluation
times.
If all selected SQC tests pass, the Output Value field displays "Normal". If some tests fail, the Output Value
field shows the highest priority test that failed. Changing any of the SQC inputs will clear the Output Value
field.
15. Specify scheduling for the analysis. See Analysis scheduling.
16. Click Check In on the toolbar to save the analysis template to the PI AF server and to create the analysis for
any element based on the element template.

Create an SQC analysis

Identify the Statistical Quality Control (SQC) pattern tests that you wish to use. See SQC analyses for more
information.
1. In the navigator, click Elements.
2. In the Elements browser, select the element where you want to create the analysis.
3. In the viewer, click the Analyses tab.
The tab lists any analyses already defined for the element.
4. Create a new analysis for the element:
▪ If no analyses exist, click Create a new analysis to create the first one.
▪ Otherwise, click New Analysis to create a new one.
5. Enter information to identify the analysis:
▪ Name
The name that uniquely identifies this analysis.
▪ Description
Optional text that describes the analysis.
▪ Categories
Optional category that you can assign to the analysis. Click the list and select the check box next to
categories you want to assign or click New to create a new category.
 ▪ Analysis Type
Click SQC.
6. Provide the inputs for the SQC pattern test. All these inputs should be attributes or attribute templates
previously defined in your PI System.
a. In the Source field, select the PI AF attribute or attribute template that provides the data for the pattern
test.
b. In the Upper Control Limit and Lower Control Limit fields, select the PI AF attribute or attribute
template that provides the largest and smallest limits on the dimension of the data being tested.
c. In the Center Line field, select the PI AF attribute or attribute template that provides the normal or ideal
value of the data.
7. Choose the output of your analysis as either Event Frame or AF attribute.
If you choose Event Frame, select an event frame template. If you choose AF attribute, you can either
choose from a list, or create a new attribute. SQC Analysis rule automatically creates an enumeration set
named SQC Enumeration. This enumeration set has the same values used in Data Archive SQC DigitalState
set so that continuity with existing Data Archive is preserved. SQC Enumeration is created when: 1) you map
the output to a new AF attribute, 2) this or another enumeration set with the required name and values
does not already exist and 3) you have the right to create enumeration sets.
AF attribute output defaults to a string attribute if the aforementioned conditions are not met.
8. Optional. Generate a root-cause event frame for every event frame that the analysis generates.
A root-cause event frame captures asset data, which can help you analyze conditions just before the start of
the event frame.
a. From the Advanced Event Frame Settings menu, select Generate Child Root Cause Event Frame Before
Parent Event Frame Starts .
b. In the Duration field, enter the length of the root-cause event frame.
The root-cause event frame starts this long before the generated parent event.
Note: The root-cause event frame is created only for the first instance, not for each time that the
trigger is True.
9. Optional. Map a start trigger name and start trigger expression to an event frame attribute.
a. From the Advanced Event Frame Settings window, select Save start trigger name to event frame
attribute and then select an attribute or attribute template on the event frame template to which the
start trigger name is saved.
b. From the Advanced Event Frame Settings window, select Save start trigger expression to event frame
attribute and then select an attribute or attribute template on the event frame template to which the
start trigger expression is saved.
The start trigger name and start trigger expression can now be seen on generated event frames, on the
selected attributes.
10. Enter SQC pattern test information.
a. Select the check box for each SQC pattern test that you wish to apply to your data.
 b. In the X of Y column, select appropriate numerical values for X and Y for each selected pattern test that
requires this input.
Specify the number of values X out of a number of sampled values Y that can be above or below the
corresponding pattern test limits.
Patterns (X and Y values) suggested by Western Electric are shown by default.
Note: X may not be greater than Y.
c. Select the Limit as Above, Below or Both, for each selected pattern test.
By default, tests are applied on both sides of the center line.
11. Optional. Select the ClearOnControlLimitChange check box.
With ClearOnControlLimitChange selected, if any of the control limits changes, asset analytics resets the
state of a running SQC calculation, and the SQC calculation is restarted with the changed values. In addition,
associated open event frames are closed before the calculation is resumed.
With ClearOnControlLimitChange not selected, the calculation simply proceeds using the changed values for
the control limits.
If all selected SQC tests pass, the Output Value field displays "Normal". If some tests fail, the Output Value
field shows the highest priority test that failed. Changing any of the SQC inputs will clear the Output Value
field.
12. Optional. Click Evaluate to verify the output values at both Value at Last Trigger and Value at Evaluation
times. If all selected SQC tests pass, the Output Value field displays "Normal". If some tests fail, the Output
Value field shows the highest priority test that failed. Changing any of the SQC inputs will clear the Output
Value field.
13. Click Check In on the toolbar.
PI System Explorer saves and checks in your analysis, and then starts running the analysis.

Sample analyses
The sample analyses in this section perform the following calculations in the same PI AF database:
1. Uses an expression type analysis to track the deviation from target efficiency for the asset and processes
represented by the element, Ethylene.
2. Creates a template to generate a set of rollup analyses that aggregate the total power draw of all processes
at a refinery. The element template from which the element for each refinery was created is called Refinery.
3. Creates event frames to capture data any time the 15-minute running-average efficiency for the element,
Ethylene, drops below 90%.

Build an expression analysis to study efficiency deviation

This example demonstrates how to build an expression type analysis. The analysis tracks how the efficiency of a
process deviates from the target efficiency.
First, we'll calculate the hourly average efficiency, then determine how much it varies from the target efficiency.
This example creates a new PI point to store the output data (the deviation from target efficiency, as it varies
over time). When you create your own analyses, it is also recommended that you create the PI points required
for output data before you start to create the analysis.
Prerequisite: Create an element named Ethylene that has an attribute named Efficiency that contains a PI point
data reference.
1. Under Elements, select the element for which you want to build the analysis, such as Ethylene.

2. Click the Analyses tab.

3. Create a new analysis for the element:
▪ If no analyses exist, click Create a new analysis to create the first one.
▪ Otherwise, click New Analysis to create a new one.
4. Enter information to identify the analysis:
▪ Name
The name that uniquely identifies this analysis. For example, EfficiencyCalc.
▪ Analysis Type
Click Expression. The expression analysis is the simplest type of analysis; it contains one or more
expressions plus scheduling information. For more information, see Expression analyses.
5. In the expressions table, create a variable to hold the constant value of the target efficiency:
a. In the Name column, type Target.
 b. In the Expression column, enter 90.
This sets this variable to the constant value of 90.
6. Create a second variable to calculate the hourly average efficiency:
a. Click Add a new expression.
b. Name the variable HourlyEfficiency.
c. In the Expression column, enter the following performance equation syntax:
TagAvg('Efficiency', '*-1h', '*')
This expression calculates the average value of the attribute called Efficiency over the past hour.
7. Create a third variable to calculate how much the hourly efficiency deviates from the target of 90:
a. Click Add a new expression.
b. Name the variable Deviation.
c. In the Expression column, enter the following expression:
HourlyEfficiency - Target
8. Save the output from the Deviation variable to a PI point:
a. In the Output Attribute column, click Map.
b. Click New Attribute to create a new PI AF attribute.
c. To define the attribute as a PI point data reference, click Yes to save output history.
d. In the Name field, enter the attribute name, such as EfficiencyDifference.
e. Click OK to create the attribute.
9. Specify scheduling for the analysis:
a. Set the Scheduling option to Periodic.
b. Click Configure and specify a period of 30 seconds.
The calculation will run every 30 seconds.
10. Verify that the results look reasonable:
a. In the analyses table, right-click the analysis and then click Preview Results.
b. Enter the time range of the preview.
The default time range starts at the preceding midnight and ends at the current time, but you can enter
different start and end times, if you prefer.
c. Click Generate Results.
11. When you are satisfied with your new analysis, click Check In on the toolbar to check in your work.
 PI System Explorer saves and checks in your analysis, and then starts running the analysis.
A green circle in the Status column of the analyses table indicates that PI Analysis Service is running the
analysis.
12. Optional. Backfill the PI point with results from the calculation using past data.
PI Analysis Service can back fill calculation results that have output attributes mapped to PI point data
references. However, the PI point cannot contain data at the specified times. If desired, you can delete pre-
existing data and then back fill that time range.
a. Right-click the analysis in the analyses table, and click Backfill/Recalculate.
b. Specify a start and end time for back filling.
c. Select Permanently delete existing data and recalculate.
d. Click Start.

Create a template for power rollup analyses

This example demonstrates how to create a template that you can use to generate a set of rollup analyses. The
analysis template aggregates the total power draw of all processes at a refinery.
Prerequisites: Create the following necessary objects in your PI AF database:
• Element template named Refinery.
• Element named Rotterdam Refinery, derived from the Refinery template
• Child element named Catalytic Cracking under the Rotterdam Refinery element
• Attribute named Power Draw under the Catalytic Cracking child element
1. In the Library browser, select the element template for which you want to create the analysis template.
In this example, the element template is called Refinery. This template is used to create refinery elements.
2. Click the Analysis Templates tab.
▪ Name
The name that uniquely identifies this analysis. For example, PowerRollup.
▪ Analysis Type
Click Rollup. A rollup analysis calculates statistical data for specified attributes, such as a total or an
average value. For more information, see Rollup analyses.
3. Enter information to identify the analysis:
▪ Name
The name that uniquely identifies this analysis. For example, PowerRollup.
▪ Analysis Type
Click Rollup. A rollup analysis calculates statistical data for specified attributes, such as a total or an
average value. For more information, see Rollup analyses.
4. Select an example element to provide candidate attributes:
 a. Click the Select an example element link to open a window that shows elements derived from the
selected element template.
b. Select an element and click OK.
For example, in the list of elements derived from the Refinery template, click Rotterdam Refinery.
5. For the Rollup attributes from option, click Child elements of Rotterdam Refinery to indicate that the
analysis rolls up attributes of child elements of the refinery element.
6. Select the attributes to include in the rollup:
a. From the Sample Child Element list, select the element from which you want to view attributes.
For example, select Catalytic Cracking to see attributes from the Catalytic Cracking element in the
attributes table.
The table only shows attributes from the selected element. The rollup include attributes from all child
elements that match the criteria that you specify.
b. To the left of the attributes table, specify criteria that select attributes to roll up.
For example, in the Attribute Name field, type Power* to specify all attributes that begin with Power.
The attributes table shows a check mark next to any attributes in the selected child element that
match this criteria. However, the rollup includes attributes from any child element that match the
criteria, not just those in the table.
7. In the functions table, specify the rollup calculations and output:
a. Select the check boxes next to any statistical function you want the rollup to calculate.
For example, click the Sum check box to total values.
b. In the Output(s) column, click Map to store results from the calculation to an output attribute.
c. Click New Attribute Template to create a new attribute template with a PI point data reference.
d. Specify values that define the created attribute and point, and then click OK.
For example, you can use the default values, which name the point and attribute PowerRollup_Sum and
write the point to the default Data Archive, indicated by the substitution parameter.
8. Click Evaluate and check whether the result returned in the Value column is reasonable.
9. Set the Scheduling option to Event-Triggered.
10. To verify the analysis, examine the results produced with historical data:
a. In the analyses list, right-click the analysis and then click Preview Results.
b. Enter a start time and end time not later than the current time, and click Generate Results to see a list
of results.
11. Click Check In on the toolbar to save the analysis template to the PI AF server and to create the analysis for
any element based on the element template.

Create event frames automatically to track inefficiency

We created a sample analysis to track how the efficiency of a process deviates from the target efficiency in Build
an expression analysis to study efficiency deviation. In this example, we create event frames to capture data any
time the 15-minute running-average efficiency drops below 90%.
Prerequisite: Complete the steps in Build an expression analysis to study efficiency deviation.
1. In the Library browser, expand Templates.
2. Right-click Event Frame Templates and then click New Template to create a new event frame template.
3. In the Name field, enter EfficiencyAnomaly.
4. In the Naming Pattern field, specify the name of the event frames produced from the template.
You can use substitution parameters to specify a varying name. PI AF resolves the parameters when creating
the event frames. Then, each event frame will have a unique, identifiable name.
a. Click the arrow next to the field to see valid substitution parameters that you can add to the name.
b. Select %ELEMENT%.
c. Select %STARTTIME:yyyy-MM-dd HH:mm:ss.fff%.
The STARTTIME substitution parameter includes the date-time formatting pattern to use.

5. Click the Attribute Templates tab.

6. Create a new PI point data reference attribute using an attribute template.
a. Click New Attribute Template.
b. In the Name field, enter Efficiency.
c. Click Settings and enter the following configuration string in the Tag name field:
.\Elements[.]|Efficiency; uom=%
d. From the Default UOM list, select percent.
 7. In the Elements pane, click Ethylene, the element for which you built an analysis in Build an expression
analysis to study efficiency deviation.
8. Click the Analyses tab.
9. Click New Analysis .
▪ Name
Enter EfficiencyAnomalyEvent.
▪ Analysis Type
Click Event Frame Generation.
10. From the Event Frame Template list, select EfficiencyAnomaly.
This is the event frame template you created in the earlier steps.
11. Enter expressions that specify the start and end of the event frame:
▪ StartTrigger1
TagAvg('Efficiency', '*-15m', '*') <90
Creates an event frame whenever the 15-minute average efficiency drops below 90%.
▪ EndTrigger
TagAvg('Efficiency', '*-15m', '*') >92
Ends the event frame whenever the 15-minute average efficiency has recovered and exceeds 92%.
12. Click Evaluate to check the current values of the expressions.
The Value column is populated with either True or False for each condition.
a. For the Scheduling option, click Periodic.
b. Click Configure and set the analysis to run every minute.
 13. Specify scheduling for the analysis.
a. For the Scheduling option, click Periodic.
b. Click Configure and set the analysis to run every minute.
14. Check in your work.

Management of analyses
The Management feature enables you to use analyses and notification rules. For information on how to manage
notification rules, see Management of notification rules.
When you select the Analyses option in the Management window, information about your analyses is shown on
the Analyses tab. Information about your PI Analysis Service's performance is found on the Performance,
Service Summary, and Service Details tabs.
You can also manage, search for, backfill or recalculate, and enable or disable analyses from this window. See
Management window to learn more.
Note: The Management feature is only available if your installation of PI System Explorer includes the
Management plug-in.

Management window
The Management window is where you view and manage your analyses and notification rules.
Analyses option
The Analyses option allows you to see performance details for both analyses and the PI Analysis Service. It also
provides access to search and operations features.
The table below lists the sections in the Management window when the Analyses option is selected.
 Numbered section Description

1. Analysis Searches Allows you to search for analyses. See Search for analyses.
2. Management tabs Provides access to information about performance for both analyses and the
service statistics.
3. Analyses list Contains a list of all the analyses in the current AF database.
4. Analysis Details Lists configuration details and error and warning messages for the selected an
5. Operations Provides access to enable/disable, automatic calculation, and other operation
6. Pending Operations Shows the status of bulk operations for analyses when the Analyses tab is op
Note: The Analyses tab lists details for analyses in the currently selected AF database only. The other three tabs
-- Performance, Service Summary, and Service Details -- provide details on analytic performance across the
entire AF server.

Analyses tab
The Analyses tab displays information about analyses in these columns:
• Status

• (Automatic recalculation)
• (Analysis Type)
• Element
• Name (of analysis)
• Template
• Backfilling (status)
Note: Click one or more column headers to sort analyses by element, name or template.
On the Analyses tab, you may see the number of analyses depicted with the "~" character, or with the word
"about"; for example: "~1000" or "1-500 of about 1000". In certain cases, the exact number of analyses is
unknown until they all are loaded.
• Analysis selection
Each page of results can contain up to 500 individual analyses.
Use the following techniques to quickly select analyses on the Analyses tab:
To• select one or more analyses: Select the check box to the left of an analysis.
To• select all analyses on the current page: Click the checkbox on the top-left corner.
To• select all analyses in the results (when more than 500 analyses exist): Click the checkbox on the
top-left corner then click the Select all analyses on all pages link.
 Note: Clearing specific analyses automatically makes your subsequent operation page-based. For
example, if you first select all 1000 analyses, and then clear two, the operation will be performed
on 498 (500 minus 2) and not 998 (1000-2) analyses.
• Operations
You can enable, disable, or backfill/recalculate the analyses you have selected. For specific selection
criteria, see the "Analysis selection" section above. From PI AF 2017 R2 and later, you can enable or
disable automatic recalculation of the analyses you selected. For more information, see Enable or
disable automatic recalculation for multiple analyses.
Execute permission on analyses you wish to backfill/recalculate data is required. Proper permission can
be obtained by mapping your account to the Asset Analytics Recalculation identity. Manual
recalculation is only available for PI Analysis Service 2016 R2 or later. In addition, the PI Data Archive
that stores PI points must run version 2016 R2 or later. For more information, see Backfill or
recalculate data for multiple analyses.
Expression, rollup, or Statistical Quality Control (SQC) analyses can backfill or recalculate data if the
analysis outputs are mapped to PI point attributes. If PI points already have data for the backfill time
period, you can retain existing data and fill in missing data, or delete the data and recalculate.
Event frame generation analyses can also recalculate event frames over a specified time period. The
recalculation process, regardless of the selected option, automatically deletes all existing event
frames for that time period, as well as annotations on affected event frames.
• Pending Operations
See the status of following bulk operations: enable, disable, backfill or recalculate a group of analyses.
• Analysis details
Select an analysis to view detailed information.
To• see a summary of the analysis configuration and status, click the Overview tab.
To• see error details, click the Errors and Warnings tab.
To• view or edit the selected analysis, click Analysis Configuration to go to the Analyses tab of its
associated element.

View analyses details

Follow the procedure below to view, sort, filter, and edit analysis details. See Analyses tab for a detailed
description of the operations you can perform on this tab.
1. Navigate to the Management window.
2. Select the Analyses option.
The Analyses tab opens.
3. Optional. On the center pane, select the Analyses tab.
The Analyses tab opens and lists all your analyses.
Note: One page of results can contain up to 500 analysis records.
4. Optional. Use the back and forward arrows to navigate through analyses page results.
5. Perform any of the optional, following steps to sort, filter, view details, and edit analyses:
 To... Do this...

Sort analyses by element, name or template. Select a column header to sort analyses data by the co
order.
Filter all analyses on the current page by keyword(s). Enter search criteria in the Filter text box, then press E
Note: Use the Filter text box to search only analyses o

Remove a search filter from the current page. Delete the search criteria in the Filter text box.
Filter all analyses in the current AF database. See Search for analyses.
View an analysis' type, description, name, element path, Select the checkbox to the left of an analysis in the tab
template, schedule, and any assigned categories.
Note: Information is displayed on the Overview tab of

View error or warning messages for an analysis. Select the checkbox to the left of an analysis in the tab
Enable or disable an analysis. Select the checkbox to the left of an analysis in the tab
Enable or disable an automatic recalculation for an analysis. Select the checkbox to the left of an analysis in the tab
View or edit a selected analysis. Select an analysis in the table, then select the Analysi
Opens the Analyses tab of the associated element.
Note: To enable or disable a group of analyses, select the checkbox to the left of the first analysis, then navigate
to the last analysis and [SHIFT+Click] the checkbox next to it. You can then select and apply the desired operation
from the right pane under the Operations heading.
See Backfilling and recalculation of analyses and Backfill or recalculate data for multiple analyses to learn more
about these tasks.

Performance tab
The Performance tab in the Management window provides helpful insights into individual analytic and group
analyses performance. The metrics on this tab can help identify potential issues and problematic analyses.
Note: The analyses on the Performance tab are retrieved from the default PI AF Server, not just the current AF
database.
From this tab, you can perform the following tasks:
• View analysis performance
• Sort analyses by column headers
• Add and remove column headers
• Filter analyses
• Export table data to a file
By default, analyses are grouped by element template with the following column headers and data shown:
Default column heading Shows...

Element Template Name of the AF element template where an analysis is configured.

Group Name The name of the analysis or analyses group.
AF Database The name of the AF database where an analysis is stored.
A rating that indicates an analysis's impact on system performance. This score is calculat
Impact score
group using the following formula: Average Elapsed / Average Trigger x Average Analysis
How often an analysis is scheduled to run. There are two types of scheduling: Periodic an
Schedule
See Analysis scheduling.
Skip Count The number of times the execution of an analysis was skipped.
Success Count The number of times an analysis was evaluated successfully.
Error Count The number of times an analysis tried to run but failed due to an error.
Average Elapsed (ms) The average amount of time in milliseconds the analysis took to execute.
Average Trigger (ms) The average interval in milliseconds between analysis executions.
Group Trigger Ratio A ratio of the average interval between analyses group executions.
You can also add these column headings to the Performance tab to display more information on analytic
performance for a data period:

Column heading Shows...

Template path The path of the AF element template where an analysis is stored.
Indicates the depth of the analysis or analysis group in a dependency chain. Analyses wh
do not come from any other analyses are rank 0. For example, an analysis with 1 or more
that are outputs of rank 0 analyses is rank 1. An analysis with 1 or more input attributes
Rank
rank 1 analyses is rank 2. The rank of a given analysis corresponds to the deepest input a
dependency chain, no rank N analyses will be evaluated until every related analysis of ra
been evaluated for that same timestamp.
Total Evaluation Count The total number of times an analysis was evaluated.
The average amount of lag time in milliseconds between when the analysis should have
Average Lag (ms)
actually ran.
Average Success Ratio The ratio of the average number of times an analysis successfully ran.
Average Error Ratio The ratio of the average number of times an analysis failed due to an error.
Skipped Evaluation Count The count of the number of times an analysis evaluation was skipped.
When an analysis is triggered at a timestamp that is prior to the latest trigger time, that
Out of Order Ignored Count out of order and discarded. This indicates that one or more input attributes received trig
out-of-order with respect to one or more other triggering input attributes.
 Column heading Shows...

This indicates that the Analysis or group received a triggering event that matched exactly
trigger time. This may be harmless and simply indicate that one or more inputs received
Duplicate Ignored Count
the same time with the same timestamp, or it could indicate that one of the triggering in
data.
Skipped Evaluation
The percentage of skipped evaluations since the Analysis Service started.
Percentage
The amount of time in milliseconds between the expected time an analysis was suppose
Current Lag (ms)
trigger or schedule and the actual time it executed.
The amount of lag time in milliseconds that an analysis execution was delayed due to wa
Current Scheduling Lag (ms)
evaluation queue.
The lag time in milliseconds between how long it took the Analysis Service to start and fi
Current Evaluation Lag (ms)
evaluation.
Indicates the average number of analyses running in the group since the service started
Average Analysis Count will stay constant at the number of analyses that belong to the group, but can fluctuate i
enabled or disabled over time.
First Trigger Time The time that the first trigger executed an analysis for evaluation.
Last Trigger Time The time that the last trigger executed an analysis for evaluation.

View analytic performance data

Follow this procedure to view group analyses and individual analytic performance data. You can also sort
analyses by column headers, add or remove columns, group and ungroup analyses by template, search for
analyses, and export data to a CSV file. See Performance tab for a description of the column headers on this tab.
1. Navigate to the Management window.
2. Select the Analyses option.
The Analyses tab opens.
3. On the center pane, click the Performance tab.
The Performance tab opens and displays analytic performance data.
4. Perform any of the optional, following steps to modify which analytic performance data is shown on the
Performance tab:
To... Do this...

Select a column header to sort analyses data in ascending order (A-Z or highest
Sort analyses by a
to lowest value). Select the column header again to sort analysis data in
column header
descending order.
Reorder columns Drag-and-drop a column header to a new position.
 To... Do this...

Filter analyses by
keyword or character Enter search criteria in the Filter text box, then press Enter.
string
Remove a search filter Delete the search criteria in the Filter text box.

Show or hide column Select the icon, then select a column header to add or remove it from the
headers table.
Display all column
headers Select the icon, then select Show All Columns.

Display only default

column headers Select the icon, then select Show Default Columns.

Ungroup or group
analyses by AF element Select the Group by: Template checkbox to clear or select this option.
template
Export analytic data to a Select the Export button to open the Save As dialog, navigate to the desired
CSV file folder location, enter a file name in the File name text box, then select Save.

Search for analyses

You can create a customized search to locate analyses in the current AF database that meet specific criteria.
1. Navigate to the Management pane.
2. Select the Analyses option.
3. Use the provided search or create your own.
To Then

Use a provided search Select All, Enabled or Disabled. These are view-only
and cannot be modified, as indicated by the (View
selected search) icon.
 To Then

Create a custom search Note: Customized search is only visible to the user
who created it on the computer where it was created.
Creating your own search is a new feature in PI AF
2017. Refer to the previous versions of PI System
Explorer User Guide if you are using an earlier version
of PI AF.

a. Click the (Add new search) button.

b. Select a search criteria. Choices are:
• Name
• Description
• Element Name
• Template
• Category
• Enabled/Disabled: enabled or disabled
• Service Status: PI Analysis/Notifications
Service status
Error
•
Running
•
Stopped
•
Suspended
•
Warning
•
Note: Service Status is based on the PI
Analysis Service connection and its
running status. This cannot be
combined with other search criteria.

View/edit a search Click the (View/edit selected search) button to

view or edit your search.
Delete a search To delete, click the (Delete selected search)
button.

PI Analysis Service management

Asset Analytics provides tools and metrics to help you gain insights into PI Analysis Service performance. You can
use the information on these tabs to diagnose and troubleshoot issues related to analysis service performance:
• Service Summary tab: Contains a summary of your PI Analysis Service's performance.
• Service Details tab: Provides detailed statistics related to PI Analysis Service performance.
 PI Analysis Service runs all analyses in the current PI AF server. Two features help you manage the service:
• The Service Details tab enables you to explore statistics about the service to monitor its operations. These
statistics are particularly important in diagnosing and identifying a solution for performance issues. You can
save these statistics as a text file, which can provide a detailed snapshot of your analysis service to share
with support staff helping you troubleshoot a problem. See View analysis service statistics.
• The Configuration window enables you to view or modify settings for analysis service properties to adjust
performance. See View or modify analysis service settings and Analysis service configuration.
Note: These options are available if your installation of PI System Explorer includes the Management plug-in and
you are signed in to a user account with permissions to configure PI Analysis Service.

View performance data

You can view a summary of your PI Analysis Service's performance on the Service Summary tab. Information
such as startup time, number of calculations performed, and other details are listed on this tab.
1. Navigate to the Management window, then click Analyses.
The Analyses tab opens in the Management window.
2. Select the Service Summary tab.
The Service Summary tab opens and displays current information about your PI Analysis Service operations
and performance.
3. Hover over a tile title to view a pop-up description of the information shown on the tile.
Tile title Description

Service Startup The amount of time between the initial startup of the AF Analysis Service and when
Time the calculation of analytics began.
Calculations per
The average number of analytics calculations evaluated per second.
Second
Skipped
The total number of calculations skipped by the AF Analysis Service since its startup.
Calculations
Max. Calculation The latency of the worst-performing analysis since the startup of the AF Analysis
Lag Service. This metric includes a built-in wait time of 5 seconds.
Cache Hit to Miss The ratio of the number of AF analysis inputs retrieved from the cache to the number
Ratio of analysis inputs not in the cache.
Max. Update
The time taken to update the cache for any AF analysis input.
Duration
The AF analysis template with the highest average trigger ratio. This ratio should be
Highest Trigger
less than 1. This ratio is defined as the template's average elapsed time divided by its
Ratio
average trigger time.
Service Details tab
The Service Details tab contains statistics on PI Analysis Service operations and installed PI AF plug-ins. The
amount of information shown on this tab depends on which version of the PI Analysis Service is installed. To
ensure access to the newest statistics and improvements, we strongly recommend you upgrade to the latest
version. See also View analysis service statistics.
The following table provides a description of the main sections shown on this tab.
Note: Do not use the information on this tab to troubleshoot performance issues. Instead, use the Performance
and Service Summary tabs. See View analyses details and View analytic performance data.

Group Subheading Description

EventFrame Provides information on event frame analyses.

Natural Provides information on event triggered analyses.
Plug-Ins PerformanceEquation Provides information on performance equation analyses.
PerformanceEquation_EventFrame Provides information on performance equation/event frame ana
Rollup Provides information on rollup analyses.
Provides statistics for the Manager plug-in, such as the amount o
ManagerStatistics
RAM on the PI Analysis Server.
Service Provides statistics on the PI Analyses Service's analyses processin
ProcessorStatistics
summary performance.
Provides information about the PI Analyses Service's processor
RecalculationProcessorStatistics
recalculation performance.
Provides statistics on the steps performed during service startup
ServiceStartupStatistics
length of time before calculations begin.
Provides counts of analyses configuration such as how many ana
AnalysisConfigurationStatistics are configured from a template or not, output timestamp, PI poin
Service output or not, scheduling, and analysis type, status, and rank.
details
Provides statistics on analyses calculation groups, the top five mo
EvaluationStatistics
expensive analyses, and data caching.
Provides statistics on analysis recalculation and backfilling that ar
RecalculationStatistics
sorted into two categories (AutoBackfill and Manual).

View analysis service statistics

The Analysis Service Statistics window enables you to explore statistics about PI Analysis Service to monitor its
operations. These statistics are particularly important in diagnosing and identifying a solution for performance
issues. You can save these statistics as a text file, which can provide a detailed snapshot of your analysis service
to share with support staff helping you troubleshoot a problem. For more information, see the OSIsoft
Knowledge Base article PI Analysis Service Best Practices and PI Analysis Service Best Practices - Detailed
Example - Variables. To access the Analysis Service Statistics window, follow this procedure.
 Note: The Management plug-in is required to view analysis service statistics in PI System Explorer.
1. Navigate to the Management window, then select the Analysis option.
The Management window opens.
2. In the center pane, select the Service Details tab.
The Service Details tab opens.
Note: You can also right-click anywhere in the Operations panel and select View Analysis Service Statistics to
open the Service Details pane.
3. Use the arrow to expand the Plug-ins, Service summary or Service details headings and reveal subheadings.
4. Select a subheading to display details on a particular plug-in or set of service statistics.
A table that contains information about the selected service or plug-in displays below the headings. See
Service Details tab for descriptions of these sections.
5. To filter analysis service statistics by a particular value or keyword, enter filter criteria in the Filter text box,
then select [Enter].
Search results display based on filter criteria.
6. Optional. Select the Refresh button to update statistics with the most current data.
7. Optional. Click Save to open the Save As dialog, then enter a new filename and navigate to the desired folder
and click Save.
The current statistics are saved as a text file.
Note: Share this text file with customer support staff to help troubleshoot problems.

View or modify analysis service settings

You can change PI Analysis Service configuration settings to help improve performance. See Analysis service
configuration for details about these settings.
Note: Changing the settings can greatly impact system performance. If you have any questions about changing
the default settings, contact customer support staff for help. You need to have administrative rights to view or
change these settings.
1. In the navigator, click Management, and then select Analysis to view the analysis management area.
2. Right-click anywhere in the Operations panel, and then click Edit Analysis Service Configuration.
The Configuration window opens.
3. To modify a property, edit its setting in the Configuration column.
4. Click OK to apply any changes and close the window.

Analysis service configuration

You can modify these settings in the Configuration window. For information on how to configure the parameters
below, see View or modify analysis service settings.
Note: Changes to the AutoBackfillingEnabled, MaximumAllowedAutoBackfillingSpanInHours or
NumberParallelDataPipes settings require a restart of PI Analysis Service to take effect.
• AutoBackfillingEnabled
This property enables or disables automatic backfilling of gaps in data that result from periods when PI
Analysis Service is not active. Automatic backfilling is enabled by default. In some cases, it may not be
needed (in a test environment, for example). Enter False to disable this property. If you update this setting,
you must restart PI Analysis Service.
• AutoRecalculationEnabled
This property enables or disables automatic recalculation of analyses. Automatic recalculation executes
analyses when a new input with a time stamp before the latest evaluated trigger is received. This useful
feature automatically recalculates late-arriving inputs. Automatic recalculation is enabled by default. Enter
False to disable this property.
Note: Although automatic recalculation is enabled globally by setting this parameter, you need to opt in for
an automatic recalculation at individual analysis (template) level. For more information, see Configure
automatic recalculation of analyses and analyses templates.
• AutoRecalculationIgnoreTimeInSeconds
This setting allows users to specify a duration whereby any input events with time stamps within this
duration and older than the latest trigger time are ignored for automatic recalculation. The default value for
this property is 30 seconds. Setting this parameter can be useful for filtering out noises in some analysis
inputs that are not desirable for automatic recalculation, for example, if they are known to be delayed.
• AutoRecalculationMinWaitTimeInSeconds
This setting controls how long analysis service will wait before queuing an analysis for automatic
recalculation upon receiving an out-of-order triggering event. A valid range for this setting is 30 to 900
seconds, with a default of 60 seconds. The wait time is reset with the arrival of new out-of-order triggering
events. Regardless of this setting, any analyses that have had an out-of-order triggering event will be queued
for recalculation after 900 seconds.
• CacheTimeSpanInMinutes
PI Analysis Service dynamically determines data cache time span for AF attributes used as inputs in
calculations. For example, for analyses calculating hourly summary, PI Analysis Service would automatically
cache an hour worth of data for required input attributes. This ensures that data required for calculations is
available in the data cache, while unnecessary data can be trimmed. Manually set CacheTimeSpanInMinutes
only if the time span cannot be determined by calculation configuration. A longer time setting means that
any input data needed for calculations is available in the data cache, but it uses more system resources. For
calculations that require earlier data (for example, from an hour earlier), you can specify a longer period for
this setting to keep data cached, thus avoiding calls to Data Archive. The maximum time span that would be
cached is 7 days and any data in the time span beyond 7 days would be trimmed. Note that the
MaxCacheEventsPerAttribute setting takes precedence over this setting, so both settings may have to be
adjusted simultaneously.
• CalculationWaitTimeInSeconds
A period of time to wait before evaluating analyses that are running in real-time. This wait time can be used
to compensate for late-arriving inputs. For example, if a calculation depends on an interface with a known
latency of up to 30 seconds, you might adjust this setting to at least 30 seconds to make sure you get the
most current event from the interface. Longer settings reduce the chance of missing calculation inputs
caused by latency but increase the delay in getting calculation results. Note that calculations use input values
at the trigger time stamp when they are evaluated. The default value for this property is 5 seconds.
• CreateFuturePIPointsForAmbiguousOutputTimes
A flag that determines the type of PI point to create for newly mapped output attributes that save output
history when the time stamp of the output is uncertain. PI Analysis Service attempts to create the PI point
type that matches the time stamp of the output, future PI points for output with future time stamps or
historical PI points for output with present or past time stamps. If set to False, PI Analysis Service creates
historical PI points in cases when the time stamp of the output is ambiguous. If set to True, PI Analysis
Service creates future PI points in cases when the time stamp of the output is ambiguous.
• Default to Auto Create PI Points for Template
When this check box is selected, PI Analysis Service automatically creates PI points for output attributes in
analyses derived from analysis templates.
• EvaluationPartitionSize
Calculations are grouped for efficient evaluation. Analyses based on an analysis template with periodic
scheduling, for example, are evaluated together as one calculation group. To speed up evaluation time, very
large calculation groups are partitioned into subgroups based on the EvaluationPartitionSize setting; the
subgroups can then be evaluated in parallel. The default value for this property is 10,000. For a group of
analyses with long individual evaluation times, you may want to specify a smaller partition size. A group of
100 analyses, each performing summary calculations for a day’s worth of data, may evaluate faster as 4
subgroups with a partition size of 25, depending on the CPU resources available on the machine.
• EvaluationsToQueueBeforeSkipping
If it takes too long to execute a group of calculations, the queue of waiting calculations may become
unmanageable. This setting determines when to skip calculations to avoid running out of resources. At the
default setting, if more than 50 evaluations are found, PI Analysis Service starts skipping the oldest
evaluations to try to return to its normal processing.
• IsLoadSheddingEnabled
For some applications, accuracy and completeness are critical, and no calculations can be skipped regardless
of the delay in completing them. To disable skipping calculations, enter False for this setting.
• IsTelemetryAllowed
Enter False to stop sending usage data from PI Analysis Service for the Customer Experience Improvement
Program. (This does not affect the corresponding setting for program participation you can configure in PI
System Explorer.)
• MaxAllowedAutoRecalculationSpanInDays
The maximum time span in days for which an analysis will be automatically recalculated on receiving an out
of order event. Any recalculation time span exceeding this limit will not be considered for automatic
recalculation. The default value for this parameter is 180 days.
• MaxCacheEventsPerAttribute
Once this limit is reached, the oldest events are trimmed from the data cache. Note that this setting takes
precedence over the CacheTimeSpanInMinutes setting.
• MaxConcurrentRecalculationRequests
The maximum number of backfilling or recalculation operations that PI Analysis Service can perform
concurrently. PI Analysis Service dynamically scales the number of threads used for backfilling or
recalculation between 1 and the number specified, depending on available resources (CPU and memory) of
 the machine that is running the service. You can set this parameter to any integer value between 1 and 256.
The default value for this parameter is (1/2)*P, where P represents the number of logical processors on the
machine that PI Analysis Service is running.
• MaximumAllowedAutoBackfillingSpanInHours
Specify the maximum downtime (in hours) for the PI Analysis Service to initiate automatic backfilling. Setting
the parameter to "0" or a negative number will restore the previously recorded setting for this option. If you
update this setting, you must restart PI Analysis Service.
Note: To disable automatic backfilling, you must disable the AutoBackfillingEnabled parameter.
• MinCacheEventsPerAttribute
The default setting of 1 ensures that at least one event per attribute remains in the data cache.
• NumberDataWriterThreads
The number of threads PI Analysis Service uses to write analysis outputs. More threads are useful for high
frequency calculations that write values at high rates and for writing to Data Archive on a computer with
high network latency (other threads can write values while waiting for a response from Data Archive).
Consider increasing the number of threads when analyses skip many evaluations or analyses have high
evaluation lag. More threads can help if data writes cause a bottleneck. You might set the number of threads
to the number of processors on the computer where PI Analysis Service runs.
• NumberEvaluationThreads
The number of threads PI Analysis Service uses for evaluating analyses concurrently. You can set this
parameter to any integer value between 1 and 256. The default value for this parameter is P, where P
represents the number of logical processors on the machine that PI Analysis Service is running. Consider
increasing the number of evaluation threads when analyses are evaluating with high lag or skipping
evaluations, but PI Analysis Service is not fully utilizing available CPU resources. This may happen when you
have a lot of analyses with summary calculations that are triggered frequently. Having a larger number of
evaluation threads is helpful for analyses that require frequent access to massive amount of input attribute
data from outside the data cache. Note that increasing the number of threads for reducing lag or skipped
evaluations may not help in cases where PI Analysis Service is already using high CPU.
• NumberParallelDataPipes
Attributes receive updates from data sources, including Data Archive, through data pipes. Using a single data
pipe to update a large number of attributes may take an unacceptably long time. You can increase the
number of data pipes which can operate simultaneously to decrease update time. This can be especially
useful for calculations with high-frequency data. Keep in mind, however, that increasing the number of data
pipes increases the load on Data Archive. If you update this setting, you must restart PI Analysis Service.
• RuntimeStorageFolderPath
Specify the location of the directory that contains PI Analysis Service run-time information such as user
backfilling and calculation groups . By default, PI Analysis Service stores run-time information in \
\ProgramData\OSIsoft\PIAnalysisNotifications.
• Suggested PI Point Name
You can modify the naming pattern here with a substitution parameter. For a complete list, see List of PI AF
substitution parameters. Note, however, that some parameters may not be meaningful in the context of a PI
point name.
 You can specify PI Point attributes as well as PI Point names. For more information on the attribute syntax,
see the examples in Configuration strings for PI point data references. Do not enter the pointtype and future
attributes as they are automatically set by asset analytics.

Buffering PI point outputs for PI Analysis Service

You can set up buffering for PI point attributes that write outputs to Data Archive from PI Analysis Service. This
way, you can optimize throughput and create data resiliency by preventing data loss. You can access Buffering
manager from PI System Explorer under Tools > Buffering Manager. See Configure buffering for analysis outputs
to PI points for more information.

Backfilling and recalculation of analyses

Backfill or recalculate
When you backfill an analysis for a specified time range, data that are missing are calculated to fill in the gaps for
the outputs. Recalculation, on the other hand, deletes all of the data in the time range and calculate results for
the analysis outputs again. Currently, there are four different options of backfill and recalculation. For more
information, see the OSIsoft Knowledge Base article Asset analytics backfilling and recalculation milestones and
requirements.
Expression, rollup or SQC analyses can be backfilled or recalculated over an earlier time period if the analyses
outputs are mapped to PI point attributes. You can backfill the missing data in a time range and retain existing
data, or you can recalculate, which deletes and recalculates data in the time range. Event frame generation
analyses can recalculate event frames over a specified time period, but automatically delete all existing event
frames in that time period, as well as annotations on affected event frames.
In order to backfill/recalculate, you need Execute permission on the analyses. Proper permission can be obtained
by mapping your account to Asset Analytics Recalculation identity. For more information on identity mapping,
see PI AF identities and mappings.
Note: For analyses writing outputs to attributes configured as PI point, backfilling or recalculation may result in
writing out-of-order events. Such events are written to the Data Archive without compression.
Enabling automatic backfilling is useful as it fills the gaps in case a short analysis service downtime occurs. For
more information, see parameters AutoBackfillingEnabled and MaximumAllowedAutoBackfillingSpanInHours in
Analysis service configuration.
From PI AF 2017 R2, you can enable automatic recalculation of analyses. PI AF Server and PI Analysis Service
2017 R2 or later are required to make use of automatic recalculation. Although automatic recalculation is
globally enabled by default (AutoRecalculationEnabled), you need to opt in at individual analysis (template) level
if you expect late-arriving or out-of-order data that may trigger recalculation. For more information, see
Configure automatic recalculation of analyses and analyses templates, Enable or disable automatic recalculation
for multiple analyses and parameters AutoRecalculationEnabled, AutoRecalculationIgnoreTimeInSeconds,
AutoRecalculationMinWaitTimeInSeconds, and MaxAllowedAutoRecalculationSpanInDays in Analysis service
configuration. To examine a log file with a list of queued automatic and manual backfill/recalculation requests for
troubleshooting, see Open recalculation log folder.
Note: Event frame generation and SQC analyses that are configured to generate event frames are excluded from
automatic recalculation.
Backfill or recalculate data for an analysis
PI Analysis Service 2016 R2 introduced recalculation capabilities for expression, rollup and SQC analyses. Data
Archive storing the output PI points must be running version 2016 R2 or later. Beginning with PI Analysis Service
2018, you can opt for recalculation of all dependent analyses. An analysis whose input comes from an output of
another analysis is considered dependent.
1. In the Elements browser, select an element, and click the Analyses tab to see the analyses defined for the
element.
2. From the list of analyses, right-click the running analysis that you want to use to backfill or recalculate data,
and click Backfill/Recalculate.
3. In the Backfilling or recalculation for analysis name window, perform the following actions.
a. In the Start Time and End Time fields, specify the time period for which you want to backfill missing data
while retaining existing data, or delete and recalculate data. You can use standard PI time expressions or
click to select a specific date period.
b. Decide how existing data should be treated. For an expression, rollup or SQC analysis that outputs to an
attribute:
• To ensure that existing data is retained and only missing data is backfilled, select Leave existing data
and fill in gaps.
• If input data or analysis algorithms have changed and you want to delete existing output data, select
Permanently delete existing data and recalculate.
• Optional. Check the box next to Recalculate dependent analyses to queue all dependent analyses
for manual recalculation.
Note: Selecting this option may cause recalculation to occur multiple times for dependent analyses.
The recalculation time range for dependent analyses may be different than the time range you
selected when queuing recalculation. For more information, see note at the end of step 7 in Backfill
or recalculate data for multiple analyses.
Note: Event frames are automatically deleted and recalculated for event frame generation analyses.
Be aware that information such as annotations, acknowledgments, reason codes on those event
frames will be lost.
4. Click Start to start the backfill or recalculation.
5. For details on the backfill or recalculation status or to cancel, right-click the analysis and click Backfill/
Recalculate Status.
Video
For information on how to backfill or recalculate data for an analysis, watch this video:

Backfill or recalculate data for multiple analyses

PI Analysis Service 2016 R2 introduced recalculation capabilities for expression, rollup and SQC analyses. Data
Archive storing the output PI points must be running version 2016 R2 or later. Beginning with PI Analysis Service
2018, you can opt for recalculation of all dependent analyses. An analysis whose input comes from an output of
another analysis is considered dependent.
1. In the navigator, select Management at the bottom of the list.
2. Select Analyses radio button in the Management pane.
3. Optional. From Analysis Searches, select a search query and then select the result you want to operate
upon.
For example, select Enabled.
Only the analyses that meet the criterion ( ) are displayed.
4. In the Analyses pane, select the analyses you want to backfill or recalculate.
5. In the Operations pane, select Queue backfilling or recalculation for selected analyses.
Note: From PI AF 2018 SP2, you can also cancel backfilling on multiple analyses with Cancel backfilling or
recalculation for selected analyses.
6. In the Start Time and End Time fields, specify the time period for which you want to backfill missing data
while retaining existing data, or delete and recalculate data. You can use standard PI time expressions, or
click to select a specific date period.
7. Choose from the following actions:
To backfill or recalculate ... Do this ...

Expression, rollup, or SQC analyses only Decide how existing data should be treated:
• To ensure that existing data is retained and
only missing data is backfilled, select Leave
existing data and fill in gaps.
• If input data or analysis algorithms have
changed and you want to delete existing
output data, select Permanently delete
existing data and recalculate.
 To backfill or recalculate ... Do this ...

A mix of analyses that includes event frame Perform one of the following actions:
generation analyses
• Keep Leave existing data and fill in gaps
or selected and acknowledge that event frames in
the time range will be permanently deleted
More than a page of analyses selections
along with all annotations on those event
frames.
• Select Permanently delete existing data and
recalculate. All annotations on event frames
will be lost.
• Optional. Check the box next to
Recalculate dependent analyses to queue
all dependent analyses for manual
recalculation.
• Selecting this option may cause
recalculation to occur multiple times
for dependent analyses
• The recalculation time range for
dependent analyses may be different
than the time range you selected when
queuing recalculation
There are three factors affecting the recalculation time range of dependent analyses:
• Time range of the original analysis
• How the output of the original analysis is used in the dependent analyses
• Whether or not the output time override is configured in the original analysis
8. Click Queue to start multiple backfills or recalculations.
9. Review the Pending Operations pane for details on the backfill or recalculation status.

Reconciliation of event frames during backfilling

When PI Analysis Service is restarted after short down-times, it initiates automatic backfilling concurrently with
real-time analysis.
Note: With PI Server 2015 and PI Server 2015 R2, PI Analysis Service does not initiate the automatic backfilling
process if down-time is greater than 72 hours. With PI Server 2016, you can configure the
MaximumAllowedAutoBackfillingSpanInHours configuration parameter in the PI Analysis Service to specify the
desired time.
When PI Analysis Service restarts, it will reconcile the open event frames. When automatic backfilling for
analyses is completed, asset analytics determines if there are event frames to be reconciled and, accordingly,
starts the reconciliation phase. Event frame reconciliation may be necessary for any in-progress event frames
that cannot be closed within the auto-backfilling time range because no closing event can be found. These event
frames may be generated in either of these ways:
 • The event frame may be already present when the analysis service was stopped
• The event frame may be newly created during auto-backfilling
Such in-progress event frames may have to be reconciled with those generated during real-time evaluation.
When you select an analysis using the Analysis tab or the Management plug-in, an orange icon ( ) in the
analysis window indicates that the event frame reconciliation is pending completion. Hover over the icon to see
details such as the number of events being processed, start and end times, and the time of last evaluation. When
reconciliation is complete, the icon turns from orange to green.

Configure automatic recalculation of analyses and analyses templates

Automatic analysis recalculation is available with PI AF 2017 R2 and later. Event frame generation and SQC
analyses that are configured to generate event frames are excluded from automatic recalculation. An event is
considered late if its timestamp is earlier than the last execution time of the analysis. The last execution time is
the same as the timestamp of the latest triggering event in an analysis (event-triggered) or the last time an
analysis ran (periodic).
Prerequisites: Although automatic recalculation is globally enabled by default, you need to opt in at individual
analysis (template) level if you expect late-arriving or out-of-order data that may trigger recalculation. PI AF
Server and PI Analysis Service 2017 R2 or later are required.
To configure automatic recalculation for a particular analysis (template), follow this procedure.
1. Go to the analysis (template) for which you want to enable automatic recalculation.
2. Click Advanced button at the bottom of the pane.
Advanced options window opens.
3. Check the box next to Recalculate analysis for out-of-order input events and click OK.
Note: You cannot opt in or out of automatic recalculation by accessing the analysis if it is based on a
template. Go to the template to make changes.

Enable or disable automatic recalculation for multiple analyses

For analyses writing to attributes (expression, rollup and SQC), automatic recalculation is available for PI Analysis
Service 2017 R2 or later. In addition, PI AF server 2017 R2 or later is required.
Note: Event frame generation and SQC analyses that are configured to generate event frames are excluded from
automatic recalculation.
1. In the navigator, select Management at the bottom of the list.
2. Select Analyses radio button in the Management pane.
3. Optional. From Analysis Searches, select a search query and then select the result you want to operate
upon.
For example, select Enabled.
Only the analyses that meet the criterion ( ) are displayed.
4. In the Analyses pane, select the analyses you want to enable or disable automatic recalculation.
5. In the Operations pane, click either Enable or Disable automatic recalculation for selected analyses.
 6. Check the box next to acknowledgment and click Enable or Disable.
7. Review the Pending Operations pane to track the progress of enabled or disabled operation.

Open recalculation log folder

To access a comprehensive log file of queued automatic/manual backfilling and recalculation requests for
troubleshooting, follow this procedure.
1. In the navigator, select Management at the bottom of the list.
2. Select Analyses radio button in the Management pane.
3. Right-click anywhere in the Operations panel and click Open Recalculation Log folder.
A folder containing a csv file with queued backfill/recalculation opens.

Asset analytics expression functions by type

The following list contains links to asset analytics expression functions by type.
Array operations
• ArrayLength
• FilterData
• FirstValue
• LastValue
• MapData
Date and time
• Bod
• Bom
• Bonm
• Day
• DaySec
• Hour
• Minute
• Month
• Noon
• ParseTime
• Second
• Weekday
• Year
• Yearday
Event frame properties
• EventFrame
Logical
• AND
• ELSE
• Exit
• IF
• IN
• NOT
• OR
• THEN
Math
• Abs
• Acos
• Asin
• Atn
• Atn2
• Ceiling
• Cos
• Cosh
• Cot
• Coth
• Csc
• Csch
• Curve
• E
• Exp
• Float
• Floor
• Frac
• Int
• Log
• Log10
 • Logbase
• Mod
• Pi
• Poly
• Pow
• Rate
• Remainder
• Round
• Roundfrac
• Sec
• Sech
• Sgn
• Sin
• Sinh
• Sqr
• Tan
• Tanh
• Trunc
Operators
• Mod
PI Data Archive digital states
• DigState
• DigText
• StateNo
Point attributes
• TagDesc
• TagEU
• TagExDesc
• TagName
• TagNum
• TagSource
• TagSpan
• TagType
 • TagTypVal
• TagZero
Search and retrieval
• Convert
• DeltaValue
• FindEq
• FindGE
• FindGT
• FindLE
• FindLT
• FindNE
• InterpolatedValues
• NextEvent
• NextVal
• NumOfChanges
• PrevEvent
• PrevVal
• RecordedValues
• RecordedValuesByCount
• SecSinceChange
• TagVal
• TimeEq
• TimeGE
• TimeGT
• TimeLE
• TimeLT
• TimeNE
• TimeStamp
Statistical
• Avg
• Compare
• Max
• Median
 • Min
• Normalrnd
• Poisson
• PStDev
• Rand
• SStDev
• Total
Status
• BadVal
• HasChanged
• HasValueChanged
• IsSet
• NoOutput
• TagBad
String
• Ascii
• Char
• Compare
• Concat
• Contains
• Format
• InStr
• LCase
• Left
• Len
• LTrim
• Mid
• Right
• RTrim
• Split
• String
• Text
• Trim
 • UCase
Time series value statistics
• Cov
• EventCount
• LinRegr
• PctGood
• Range
• StDev
• TagAvg
• TagMax
• TagMean
• TagMin
• TagTot

Expression functions reference

Expression functions available for use in expression and event frame generation analyses are listed
alphabetically. These functions follow performance equation (PE) syntax.
Note: Expression functions (ArrayLength, FilterData, FirstValue, InterpolatedValues, LastValue, MapData,
RecordedValues and RecordedValuesByCount) that enable you to retrieve and manage multiple values as an
array may not work very well with attributes configured as PI point array data reference.

Abs
Return the absolute value of an integer or real number.
Syntax
Abs(x)

Arguments
• x
An integer or real number
Returns
The absolute value of x
Exceptions
Return an error value if x is not an integer or real number
Notes
Unit of measure of the argument, if it exists, is carried over to the result
 Example
• Abs(-2.2)
[Returns 2.2]
• Abs('att1')
[Return the absolute value of 'att1' at trigger time]

Acos
Return the inverse cosine (arccos) of an integer or real number. The inverse cosine of x is the angle in radians
whose cosine is equal to x.
Syntax
Acos(x)

Arguments
• x
Must be a real number between -1.0 and 1.0, inclusive
Returns
The inverse cosine of x, in radians
Exceptions
If x is not a number, or is less than -1.0 or greater than 1.0, returns an error value
Example
• Acos(-0.5)
[Returns 2.0944]
• Acos(0.75)
[Returns 0.72273]

AND
The logical conjunction of two expressions that returns True if both expressions are true and False otherwise.
Syntax
expression1 AND expression2

Arguments
• expression1, expression2
Any expression that evaluates to true or false
Returns
True if both expressions are true (non-zero) and False (zero) otherwise
 Exceptions
None
Notes
If the inputs are numeric, AND can do bitwise operations.
Example
• ('att1' > 50) AND ('att2' = "good")

ArrayLength
Get the length of an array.
Syntax
ArrayLength(a1)

Arguments
• a1
a variable representing the array to operate on
Returns
The number of values in the array
Exceptions
None
Notes
None
Example
• ArrayLength(Data)
[Return the number of values in an array named Data]

Ascii
Return the ASCII character code of the first character of a string.
Syntax
Ascii(s1)

Arguments
• s1
Any expression evaluating to a string
Returns
The character code of the first character of the string
 Exceptions
If the argument is not a string, an error value is returned
Example
• Ascii("D")
[Returns 68, the ASCII character code for D]
• Ascii("Program")
[Returns 80, the ASCII character code for the first letter of the string]

Asin
Return the inverse sine (arcsin) of a number. The inverse sine of x is the angle in radians whose sine is equal to x.
Syntax
Asin(x)

Arguments
• x
Must be a real number between -1.0 and 1.0, inclusive
Returns
The inverse sine of x, in radians
Exceptions
If x is not a number, or is less than -1.0 or greater than 1.0, an error value is returned
Example
• Asin(-0.5)
[Returns -0.5236]
• Asin(TagVal('att1','y+8h'))
[Return the inverse sine of the value of 'att1' at 8am yesterday]
• Asin('att1')
[Return the inverse sine of the value of 'att1' at trigger time]

Atn
Return the inverse (or arc) tangent of an integer or real number. The inverse tangent of x is the angle in radians
whose tangent is equal to x.
Syntax
Atn(x)

Arguments
• x
 Must be an integer or real number
Returns
The inverse tangent of x, in radians
Exceptions
Returns an error if x is not an integer or real number
Example
• Atn(1)
[Returns 0.7854]
• Atn(-2.2)
[Returns -1.1442]
• Atn('att1')
[Return the inverse tangent of the value of 'att1' at trigger time]
• Atn('att1' - 'att2')
[Return the inverse tangent of the difference of 'att1' and 'att2' at trigger time]

Atn2
Return the inverse tangent (arctan) of a tangent value a/b. The inverse tangent is the angle measured in radians
from the positive x-axis to a line whose endpoints are the origin and the Cartesian coordinates (b, a).
Syntax
Atn2(x, y)
Arguments
• x
An integer or real number
• y
A non-zero integer or real number
Returns
The inverse tangent in radians of the tangent value x/y
Exceptions
Returns an error if x or y is not an integer or real number
Example
Atn2(1,2)
• [Returns 0.46365]
Atn2('att1', 'att2')
• [Return the inverse tangent in radians of the tangent value 'att1'/'att2' at trigger time]
Atn2(TagVal('att1','y+8h'), TagVal('att2', 'y+8h'))
 • [Return the inverse tangent in radians of the tangent value 'att1'/'att2' at 8am yesterday]

Avg
Return the time-weighted or event-weighted average from a set of one or more values.
Syntax
Avg(x1 [, ... xn])
Avg(array [, calculationBasis])

Arguments
• x1, ... xn
Arguments or a single array of same value type (integers and real numbers, time expressions, or time
intervals)
• calculationBasis
Optional. The type of calculation to be performed enclosed in double quotes. Choose between
"EventWeighted" or "TimeWeighted." If omitted, the default is event-weighted. If you select
"TimeWeighted," the earliest timestamp of the value marks the start time and the latest timestamp the end
of a time range
Returns
The average of one or more values. The result is of the same data type as arguments
Exceptions
Arguments whose run-time values are character strings or digital states are not included in the average. If all
values are character strings or digital states, Avg returns an error value. Returns an error if the array does not
consist of same value type
Notes
• Unit of Measure (UOM) of the arguments is carried over to the result when at least one argument has a
defined UOM while others don't. The returned value lacks a UOM if arguments have different UOMs
Example
• Avg(14, 'att1', 14.5, TagVal('att2', '14-Dec-16'))
[Find the average of these values: 14, the current value of 'att1', 14.5, and the value for 'att2' at the start of
day (12:00am) on Dec 14, 2016]
• Avg('*', 'y+8h', 'Saturday')
[Find the average of these time stamps: now, 8:00am yesterday, and start of day (12:00am) last Saturday]
• Avg('*'-'*-1h', 't+4h'-'y+8h', 'y+2h'-'20')
[Find the average of these time periods: from 1 hour ago to now, from 8:00am yesterday to 4:00am today,
and 2:00am yesterday to the start of day (12:00am) on the 20th of this month]
• Avg(Variable1)
 Name Expression Value at Evaluation

Variable1 RecordedValues('att1', [1, 3, 5, 7, 9]

'*-10m', '*')

Variable 2 Avg(Variable1) 5
[Find the average of values in an array named Variable1]
• Avg(Data)
[Return the event-weighted average of values for an array named Data]
• Avg(Data, "EventWeighted")
[Return the event-weighted average of values for an array named Data]
• Avg(Data, "TimeWeighted")
[Return the time-weighted average of values for an array named Data using the earliest timestamp of the
value as the start time and the latest timestamp as the end time]

BadVal
Test a value to see if it is bad. For an attribute associated with a PI point, any system digital state value is
considered bad (No Data or Calc Failed, for example).
Syntax
Badval(x)
Arguments
• x
any expression evaluating to a value
Returns
True if the value is bad
False if the value is not bad
Exceptions
Returns True for blob PI points. Returns False for string PI points
Example
• BadVal(1/0)
[Returns True]
• BadVal(10)
[Returns False]
• BadVal('att1')
[Returns True if the value of 'att1' is bad]
• BadVal(FindEq('att1', 't', '*', 10))
 [Returns True if the embedded function (FindEq in this example) has no result or has error for any reason]

Bod
Return a timestamp for beginning of the day from a time expression.
Syntax
Bod(t1)

Arguments
• t1
A time expression, enclosed in single quotes
Returns
Timestamp for the start of the day
Exceptions
None
Notes
This function is useful for establishing a time at a unique clock time independent of the length of particular days.
Example
• Bod('*')
[Return a timestamp for beginning of the day today]
• Bod('y')
[Return a timestamp for beginning of the day yesterday]
• Bod(FindEq('att1', '-3d', '*', 50))
[Return a timestamp for beginning of the day when 'att1' value was first equal to 50 in the past 72 hours]

Bom
Return a timestamp for midnight on the first day of the month from a given time expression.
Syntax
Bom(t1)

Arguments
• t1
A time expression
Returns
Timestamp for the start of the month
Exceptions
None
 Notes
This function is useful for establishing a time at a unique clock time independent of the length of particular days.
Example
• Bom('*')
[Return a timestamp for midnight on the first day of this month]
• Bom(PrevEvent('att1', '*'))
[Return a timestamp for midnight on the first day of the month when 'att1' had a value before the current
one]
• Bom(FindEq('att1', '-60d', '*', 50))
[Return a timestamp for midnight on the first day of the month when the value of 'att1' was first equal to 50
in the past 60 days]

Bonm
Return a timestamp for midnight on the first day of a following month from a given time expression.
Syntax
Bonm(t1)

Arguments
• t1
Time expression, enclosed in single quotes
Returns
Timestamp for the start of the next month
Exceptions
None
Notes
This function is useful for establishing a time at a unique clock time independent of the length of particular days.
Example
• Bonm('*')
[Return a timestamp for midnight on the first day of next month]
• Bonm('y')
[Return a timestamp for midnight on the first day of the following month from yesterday's date]
• Bonm(FindEq('att1', '-60d', '*', 50))
[Return a timestamp for midnight on the first day of the following month when the value of 'att1' was first
equal to 50 in the past 60 days]
Ceiling
Return the nearest integer greater than or equal to x.
Syntax
Ceiling(x)

Arguments
• x
integer or a real number, an attribute whose value evaluates to a number
Returns
The nearest integer greater than or equal to x
Exceptions
Returns an error if x is a digital state, time expression, time interval or a string
Notes
Unit of measure of the argument, if it exists, is carried over to the result
Example
• Ceiling(2.3)
[Returns 3]
• Ceiling(-2.3)
[Returns -2]
• Ceiling(TagVal('att1', '12/30/16'))
[Return the nearest integer to the value of 'att1' at the start of day (12:00am) on December 30, 2016]

Char
Build a string from ASCII character codes.
Syntax
Char(x1, ... xn)

Arguments
• x1, ... xn
Integers
Returns
A string built from the 80 character codes
Exceptions
Returns an error if an argument is not a number
 Example
• Char(80, 73)
[Returns "PI"]
• Char(65)
[Returns "A"]
• Char(5 * 10)
[Returns "2"]

Compare
Compare two strings using wildcard characters ("*" and "?") or compare two operands using logical operators
and deadband value.
Syntax
Compare {[(s1, s2 [, caseSensitive])]|[x1, x2, op, deadband]}

Arguments
• s1, s2
string (s2 can contain wildcard characters)
• caseSensitive
Optional flag indicating if the comparison is case sensitive. If False (the default), the comparison is not case-
sensitive. If True, the comparison is case-sensitive
• x1, x2
Numeric value (integer or real number) or time expression
• op
An operator used for comparison. Must be one of the following operators, or a variable defined as one of
these: <, >, <=, >=
• deadband
Numeric value (integer or real number) or timespan. Deadband specifies a buffer (tolerance) around x2 and
prevents repeated alerts when the value fluctuates within the deadband range
Returns
• True if s1 = s2
• True if x1 <op> x2 is true, and uses deadband value for subsequent evaluations
False otherwise
Exceptions
Wildcard characters in s1 are treated literally and not as wildcards
The deadband value is applied to x2, not x1
 Example
• Compare('att1', 100, "<=", 5)
[Returns True if 'att1' is less than or equal to 100, and uses the deadband value of 5 for subsequent
evaluations]
• Compare("What", "what", True)
[Returns False]
• Compare("b", "a")
[Returns False]
• Compare("What", "wha?")
[Returns True]
• Compare("What", "wh")
[Returns False]

Concat
Concatenate two or more strings.
Syntax
Concat(s1, s2 [, ... sn])

Arguments
• s1, ... sn
Must be character strings, or expressions yielding character strings.
Returns
The character strings, concatenated together. This function does not insert blanks between its arguments. To
include a space in the concatenated string, add an argument consisting of a string that has a single space
enclosed in double quotes.
Example
• Concat("shut", "down")
[Returns "shutdown"]
• Concat("shut ", "down")
[Returns "shut down"]

Contains
Determine if first string contains second string and return True or False.
Syntax
Contains(s1, s2 [,caseSensitive])
 Arguments
• s1
Primary string
• s2
Substring searched for in primary string
• caseSensitive
Optional: Boolean that indicates whether the search is case sensitive. If False (or omitted), the search is not
case sensitive. If True, the search is case sensitive
Returns
True if the primary string (s1) contains the substring (s2) and False otherwise
Exceptions
If either of the first two arguments (s1 or s2) is not a string, the function returns an error value
If the optional third argument (caseSensitive) is not a Boolean, the function returns an error value
Example
• Contains("What","Hat",True)
[Returns False]
• Contains("What","Hat")
[Returns True]
• Contains("What","at")
[Returns True]
• Contains("hat","what")
[Returns False]

Convert
Convert a value from its current unit of measure (UOM) to a specified UOM; for a value with no UOM, assign the
specified UOM.
Syntax
Convert(x, toUnit)

Arguments
• x
Any expression that resolves to a numeric value, including the name of a numeric attribute enclosed in single
quotation marks, a variable name, or a constant value
• toUnit
The output UOM enclosed in double quotation marks
 Returns
The numeric value converted to the specified UOM
Exceptions
Returns an error if toUnit and the initial UOM for x are not in the same UOM class
Example
• Convert('MetricWeight', "lb")
• Convert('Ambient Temperature', "degC")
Note: PI AF substitutes deg with °, if not otherwise found in the lookup.

Cos
Return the trigonometric cosine of an integer or real number.
Syntax
Cos(x)

Arguments
• x
Must be an integer or real number, which represents an angle in radians
Returns
The cosine of x
Exceptions
If x is not an integer or real number, returns an error value
Example
• Cos(1.1)
[Returns 0.4536]
• Cos(1)
[Returns 0.5403]
• Cos('att1')
[Return the trigonometric cosine of the value of 'att1' at trigger time]

Cosh
Return the hyperbolic cosine of a number.
Syntax
Cosh(x)

Arguments
• x
 Must be an integer or real number
Returns
The hyperbolic cosine of x
Exceptions
If x is not an integer or real number, returns an error
Example
• Cosh(1)
[Returns 1.5431]
• Cosh(-1)
[Returns 1.5431]
• Cosh('att1')
[Return the hyperbolic cosine of the value of 'att1' at trigger time]

Cot
Return the trigonometric cotangent of a number.
Syntax
Cot(x)

Arguments
• x
Must be an integer or real number, which represents an angle in radians
Returns
The cotangent of x
Exceptions
If x is not a number, returns an error
Example
• Cot(1)
[Returns 0.64209]
• Cot(1.1)
[Returns 0.50897]
• Cot('att1')
[Return the trigonometric cotangent of the value of 'att1' at trigger time]

Coth
Return the hyperbolic cotangent of a number.
 Syntax
Coth(x)

Arguments
• x
Must be an integer or real number
Returns
The hyperbolic cotangent of x
Exceptions
If x is not a number, returns an error value
Example
• Coth(1)
[Returns 1.313]
• Coth(1.1)
[Returns 1.2492]
• Coth('att1')
[Return the hyperbolic cotangent of the value of 'att1' at trigger time]

Cov
Determine the covariance between two sets of values given by attributes over a specified time range.
Syntax
Cov(x, y, mode, starttime, endtime, type [, pctgood])

Arguments
• x
an attribute with the first set of time series data (such as PI point data reference) enclosed in single quotes
• y
an attribute with the second set of time series data (such as PI point data reference) enclosed in single
quotes
• mode
a number that specifies how to align time-stamped values
choose from 0, 1 or 2 where:
0 represents the combination of time-stamped values from x and y
1 represents values from both attributes according to x's time stamps
2 represents values from both attributes according to y's time stamps
• starttime
 a time expression representing the beginning of a time range enclosed in single quotes; can be a relative
time (such as '-3h') in reference to an absolute endtime
• endtime
a time expression representing the end of a time range enclosed in single quotes; can be a relative time
(such as '+1h') in reference to an absolute starttime
• type
a number specifying the covariance type: use 0 for "population" and 1 for "sample"
• pctgood
Optional. Minimum percentage of time during the time range that attribute values must be good.
You can set pctgood as a threshold to ensure that there are sufficient good values to calculate Cov.
Returns
Covariance of x and y
Exceptions
If the attribute has no good values or the pctgood minimum is not reached for the given time range, returns an
error value
Notes
Bad values are excluded from Cov calculation
Note: If the attribute has very few good values during the time range, this function's result may not be
trustworthy. Use the PctGood function to find out what percentage of the values is good
Example
• Cov('att1', 'att2', 0, 't', '+1h', 1, 80)
[Return the sample covariance of 'att1' and 'att2' between 12:00 and 1:00am today when at least 80% of the
values were good. Return an error when minimum pctgood is not reached]
• Cov('att1', 'att2', 1, 't', '+1h', 1)
[Return the population covariance of 'att1' and 'att2' based on time stamps of 'att1' between 12:00 and
1:00am today]

Csc
Return the trigonometric cosecant of a number.
Syntax
Csc(x)

Arguments
• x
Must be an integer or real number, which represents an angle in radians
 Returns
The cosecant of x
Exceptions
If x is not a number, returns an error
Example
• Csc(1)
[Returns 1.1884]
• Csc(1.1)
[Returns 0.7487]
• Csc('att1')
[Return the trigonometric cosecant of the value of 'att1' at trigger time]

Csch
Return the hyperbolic cosecant of a number.
Syntax
Csch(x)

Arguments
• x
Must be an integer or real number
Returns
The hyperbolic cosecant of x
Exceptions
If x is not a number, returns an error value
Example
• Csch(1)
[Returns 0.85092]
• Csch(1.1)
[Returns 0.748]
• Csch('att1')
[Return the hyperbolic cosecant of the value of 'att1' at trigger time]

Curve
For a given x, returns the value of a piecewise linear interpolation function defined by the set of n points (x1,y1)...
(xn,yn).
 Syntax
Curve(x, (x1,y1) (x2,y2) … (xn,yn))

Arguments
• x
Expression evaluating to a number
• x1, y1
The first point on the curve. The xi's and yi's are numeric constants evaluated at compile time. The values set
for xi's must be in ascending order.
Returns
For a given x, returns the value of a piecewise linear interpolation function defined by the set of n points (x1,y1)...
(xn,yn). If the value of x is less than x1 then y1 is returned and if it is greater than xn, yn is returned. The points are
assumed to be ordered in the x direction from smallest to largest.
Exceptions
If the value of x is not an integer or real number, an error value is returned
Example
• Curve(3, (0,100) (100,0))
[Returns 97]
• Curve('att1', (25,25) (75,75))

Day
Extract the day of the month from a time expression.
Syntax
Day(t1)

Arguments
• t1
time expression enclosed in single quotes
Returns
The day of the month of a time expression in the range 1 through 31
Exceptions
None
Example
• Day('*')
[Return what day of the month today is]
• Day('y')
 [Return what day of the month yesterday was]
• Day(FindEq('att1', '-28d', '*', 50))
[Return what day of the month it was when the value of 'att1' was first equal to 50 in the past 28 days]

DaySec
Return the total time in seconds between the start of day (midnight) and the time denoted in the argument.
Syntax
DaySec(t1)

Arguments
• t1
A time expression, enclosed in single quotes
Returns
Total seconds since the start of day (midnight) till t1, in the range 0-86399
Exceptions
None
Example
• DaySec('*')
[Return the number of seconds from the start of day (midnight) until now]

DeltaValue
Return the difference between the current and immediately previous values or evaluations of an attribute with a
numeric or DateTime value type.
Syntax
DeltaValue(x [, prevEval])

Arguments
• x
An attribute or expression of a numeric or DateTime value type
• prevEval
(Boolean) If False or not specified, x must be an attribute, and DeltaValue returns the difference between its
current value and immediately previous value.
If True, DeltaValuereturns the difference between the current and immediately previous evaluations of x,
which can be any expression with a numeric or DateTime value type
 Returns
Returns the difference between the current value and the immediately previous value of an attribute with a
numeric or DateTime value type, or the difference between the current and immediately previous evaluations
for any expression with a numeric or DateTime value type
Notes
When x is of DateTime data type, DeltaValue returns the time interval (in seconds) between two DateTime
values. If the time interval value is output to an attribute, make sure the attribute data type is set to double
This function may use input values from PI points. If the compression is on for a PI point, all of its values may not
be preserved in PI Data Archive. Before you try to validate the results of this function using a client tool such as
PI Datalink, make sure the compression is turned off. This is to ensure that all associated PI point values are
included for validation. When validation is complete, be sure to turn the compression back on again as a best
practice
Unit of measure of the argument, if it exists, is carried over to the result
Example
• DeltaValue('att1' [, FALSE])
[Return the difference between the current and immediately preceding value of 'att1']
• DeltaValue('att1', TRUE)
[Return the difference between the current and last evaluated value of 'att1']

DigState
Convert a string into a corresponding Data Archive digital state object, either based on the attribute's digital
state enumeration or on a system enumeration set values (for example, Calc Failed). Use DigState embedded in
other functions when Data Archive digital state object is required for input (such as with StateNo) or in
conjunction with other functions for comparison with digital state attributes.
Syntax
DigState(s1 [, x])

Arguments
• s1
A string representing a digital state in double quotes
• x
Optional: An attribute with PI point digital state reference or of value type enumeration set. If omitted, only
the system digital set is searched for the given string.
Returns
An enumeration value
Exceptions
If the string does not represent a digital state of the specified attribute, the function returns Calc Failed. If the
attribute is omitted and string does not represent a system digital state, Calc Failed is returned.
 Example
• 'att1' > DigState("Program", 'att1')
[Returns True if current digital state of 'att1' is greater than the digital state represented by "Program" value]
• DigState("No Result")
[Construct a value with system digital state No Result]

DigText
Obtain the text corresponding to the digital state.
Syntax
DigText(digstate)

Arguments
• digstate
An argument that evaluates to a digital state
Returns
The text for the digital state
Exceptions
Returns an error if the argument is not a digital state
Example
• DigText(TagVal('enum_att1', 'y'))
[Returns the digital state value in string]
• DigText('enum_att1')
[Returns digital state value in string. Returns an error message if 'enum_att1' is not a PI point attribute with
digital state value]

E
Return the value for e (the base of the natural logarithm).
Syntax
E()

Arguments
None
Returns
The value for e (the base of the natural logarithm)
Exceptions
None
 Example
• E()

ELSE
Operator that returns the second of two specified values when the conditional expression in IF-THEN-ELSE
statement is True.
Syntax
IF (expression) THEN (x) ELSE (y)

Arguments
• expression
Any expression that evaluates to true or false
• x, y
An expression that evaluates to an output value
Returns
x when the conditional expression is true and y when the expression is false
Exceptions
None
Example
• IF ('att1' > 50) THEN ('att2') ELSE ('att3')
[If the value of 'att1' is greater than 50, then return the value of 'att2'; otherwise return the value of 'att3']

EventCount
Find the number of events for an attribute during a specified time range.
Syntax
EventCount(attname, starttime, endtime [, pctgood])

Arguments
• attname
attribute with time series data (such as PI point data reference) enclosed in single quotes
• starttime
time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as '-3h') in reference to an absolute endtime
• endtime
time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as '+1h') in reference to an absolute starttime
• pctgood
 Optional: Minimum percentage of good values for events within the specified time interval.
Returns
Number of events for the attribute during a specified time range.
Exceptions
Returns an error if the pctgood minimum is not reached for the given time interval.
Notes
If the attribute has very few good values during the time range, this function's result may not be trustworthy.
Use the PctGood function to find out what percentage of the values is good.
Example
• EventCount('att1', 't', '+1h')
[Return the count of events between 12:00 and 1:00am today.]
• EventCount('att1', 't', '+1h', 80)
[Return the count of events between 12:00 and 1:00am today when at least 80% of the values were good.]

EventFrame
Return the value of event frame properties.
Syntax
EventFrame(parameter)

Arguments
• parameter
parameter string StartTime, EndTime or Duration enclosed in double quotes; not case-sensitive
Returns
The value of the parameter
Exceptions
If the event frame is not active or still open, returns No Results
Notes
• This function is only to be used when configuring output expressions in an event frame generation analysis
• The output can be mapped to an attribute with value type DateTime for StartTime and EndTime. For
Duration, select double (time returned in seconds)
• You can preview results by right-clicking the analysis
Example
• EventFrame("Duration")
[Return the duration of an event frame. Time is returned in seconds]
• TagAvg('att1', EventFrame("StartTime"), EventFrame("EndTime"))
 [Find the time-weighted average of the values of 'att1' during an event frame]

Exit
Stop the analysis from running further evaluation.
Syntax
Exit()

Arguments
None
Notes
• It is important to include the parentheses after this function. Use Exit() instead of Exit.
• Suppose you have multiple expressions within a single analysis or a sequence of analyses that forms a
dependency chain. The calculation ends when it hits Exit.
• Unlike Exit, which immediately exits out of the analysis, NoOutput will continue until it goes through every
expression in an analysis.
Example
• IF 'att1' < 100 OR 'att1' > 200 THEN 'att1' ELSE Exit()

Exp
Return the exponential of an integer or real number. This is the number ex, where e = 2.7182818...
Syntax
Exp(x)

Arguments
• x
Must be an integer or real number
Returns
The exponential of x
Exceptions
If x is not an integer or real number, returns an error value
Example
• Exp(11)
[Returns 59874]
• Exp('att1')
[Return the exponential of the value of 'att1' at trigger time]
• Exp(TagVal('att1','t'))
 [Return the exponential of the value of 'att1' at the start of day (12am) today]

FilterData
Get all the values in an array that satisfy a given condition.
Syntax
FilterData(a1, condition($val))

Arguments
• a1
a variable representing the array to operate on
• condition($val)
any supported PE statement, as a function of $val, that returns a true or false. $val is a placeholder for each
value in the array
Returns
An array of all the values that satisfy the given condition
Exceptions
None
Notes
None
Example
• FilterData(Data, (NOT BadVal($val) AND $val > 50))
[From an array named Data, return a new array of values where none are bad values and all are greater than
50]

FindEq
Find the timestamp closest to starttime within a specified time interval when the attribute is equal to a specified
value.
Syntax
FindEq(attname, starttime, endtime, x)

Arguments
• attname
name of an attribute enclosed in single quotes
• starttime
time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as "-3h") in reference to an absolute endtime
• endtime
 time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as "+1h") in reference to an absolute starttime
• x
The value to search for; must be an integer or real number or digital state (character string)
Returns
The timestamp closest to starttime within the specified interval when the attribute was equal to the specified
value
Exceptions
If the attribute was never equal to the specified value, an error value is returned
Notes
• If needed, interpolation is done between attribute values to determine when the attribute was equal to the
specified value
• Interpolation occurs when:
• the underlying PI point has step attribute turned off
• there is no recorded value with the specified timestamp
• The interpolated value will be based on the values before and after the timestamp
• No value will be interpolated if the step attribute is turned on. In this case, the value of record will be that at
the time of the event (if it exists) or the previously-recorded value
• If endtime is earlier than starttime, the time interval is searched backwards
Example
• FindEq('att1', '-1h', '*', 40)
[Return the timestamp of the first time since an hour ago (starttime) when ' att1' was equal to 40]
• FindEq('enum_att1', '30-March-17', '*', "On")
[Return the timestamp of the first time since the start of day (12am; starttime) on March 30th, 2017 when
enumeration value 'enum_att1' was equal to "On"]

FindGE
Find the first time within a time interval when an attribute is greater than or equal to a specified value.
Syntax
FindGE(attname, starttime, endtime, x)

Arguments
• attname
The name of an attribute enclosed in single quotation marks
• starttime
 time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as "-3h") in reference to an absolute endtime
• endtime
time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as "+1h") in reference to an absolute starttime
• x
The value to search for; must be an integer or real number or digital state (character string)
Returns
The timestamp closest to starttime within the specified interval when the attribute was greater than or equal to
the specified value. Returns the corresponding system digital state (No Result, No Data, and the like) if the
attribute was always less than the specified value.
Exceptions
None
Notes
• If needed, interpolation is done between attribute values to determine when the attribute was greater than
or equal to the specified value
• Interpolation occurs when:
• the underlying PI point has step attribute turned off
• there is no recorded value with the specified timestamp
• The interpolated value will be based on the values before and after the timestamp
• No value will be interpolated if the step attribute is turned on. In this case, the value of record will be that at
the time of the event (if it exists) or the previously-recorded value
• If endtime is earlier than starttime, the time interval is searched backwards
Example
• FindGE('att1', 'y', '+2h', 40)
[Return the timestamp between midnight and 2:00 am yesterday when 'att1' was first greater than or equal
to 40]

FindGT
Find the first time within a time interval when an attribute is greater than a specified value.
Syntax
FindGT(attname, starttime, endtime, x)

Arguments
• attname
The name of an attribute enclosed in single quotation marks
• starttime
 time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as "-3h") in reference to an absolute endtime
• endtime
time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as "+1h") in reference to an absolute starttime
• x
The value to search for; must be an integer or real number or digital state (character string)
Returns
The timestamp closest to starttime within the specified interval when the attribute was greater than the
specified value. Returns the corresponding system digital state (No Result, No Data, and the like) if the attribute
was never greater than the specified value.
Exceptions
None
Notes
• If needed, interpolation is done between attribute values to determine when the attribute was greater than
the specified value
• Interpolation occurs when:
• the underlying PI point has step attribute turned off
• there is no recorded value with the specified timestamp
• The interpolated value will be based on the values before and after the timestamp
• No value will be interpolated if the step attribute is turned on. In this case, the value of record will be that at
the time of the event (if it exists) or the previously-recorded value
• If endtime is earlier than starttime, the time interval is searched backwards
Example
• FindGT('att1', 't', '*', 40)
[Return the timestamp of the first time after midnight today when 'att1' was greater than 40]
• FindGT('att1', '-1h', '*', TagVal('att1', 'y+18h'))
[Return the timestamp of the first time since an hour ago when the value of 'att1' was greater than its value
at 6pm yesterday]

FindLE
Find the first time within a time interval when an attribute is less than or equal to a specified value.
Syntax
FindLE(attname, starttime, endtime, x)

Arguments
• attname
 The name of an attribute enclosed in single quotation marks
• starttime
time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as "-3h") in reference to an absolute endtime
• endtime
time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as "+1h") in reference to an absolute starttime
• x
The value to search for; must be an integer or real number or digital state (character string)
Returns
The timestamp closest to starttime within the specified interval when the attribute was less than or equal to the
specified value. Returns the corresponding system digital state (No Result, No Data, and the like) if the attribute
was always greater than the specified value.
Exceptions
None
Notes
• If needed, interpolation is done between attribute values to determine when the attribute was equal to the
specified value
• Interpolation occurs when:
• the underlying PI point has step attribute turned off
• there is no recorded value with the specified timestamp
• The interpolated value will be based on the values before and after the timestamp
• No value will be interpolated if the step attribute is turned on. In this case, the value of record will be that at
the time of the event (if it exists) or the previously-recorded value
• If endtime is earlier than starttime, the time interval is searched backwards
Example
• FindLE('att1', 't', '*', 40)
[Return the timestamp of the first time after midnight today when att1 was less than or equal to 40]

FindLT
Find the first time within a time interval when an attribute is less than a specified value.
Syntax
FindLT(attname, starttime, endtime, x)

Arguments
• attname
 The name of an attribute with a PI point data reference, enclosed in single quotation marks
• starttime
time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as "-3h") in reference to an absolute endtime
• endtime
time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as "+1h") in reference to an absolute starttime
• x
Must be an integer or real number or digital state (character string), the value to search for
Returns
The timestamp closest to starttime within the specified interval when the attribute was less than the specified
value. Returns the corresponding system digital state (No Result, No Data, and the like) if the attribute was never
less than the specified value.
Exceptions
None
Notes
• If needed, interpolation is done between attribute values to determine when the attribute was lower than
the specified value
• Interpolation occurs when:
• the underlying PI point has step attribute turned off
• there is no recorded value with the specified timestamp
• The interpolated value will be based on the values before and after the timestamp
• No value will be interpolated if the step attribute is turned on. In this case, the value of record will be that at
the time of the event (if it exists) or the previously-recorded value
• If endtime is earlier than starttime, the time interval is searched backwards
Example
• FindLT('att1', 'y', 't', 40)
[Return the timestamp of the first time between midnight yesterday and midnight today that 'att1' was less
than 40]
• FindLT('att1', '-1h', '*', TagVal('att1', 'y+18h'))
[Return the timestamp of the first time since an hour ago when the value of 'att1' was less than its value at
6pm yesterday]

FindNE
Find the first time within a time interval when an attribute is not equal to a specified value. "No Data" events will
be skipped.
Syntax
FindNE(attname, starttime, endtime, x)

Arguments
• attname
The name of an attribute enclosed in single quotation marks
• starttime
time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as "-3h") in reference to an absolute endtime
• endtime
time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as "+1h") in reference to an absolute starttime
• x
The value to search for; must be an integer or real number or digital state (character string)
Returns
The timestamp closest to starttime, within the specified interval, for which the attribute was not equal to the
specified value. "No Data" events will be skipped
Exceptions
If the attribute was always equal to the specified value, an error value is returned
Notes
• If needed, interpolation is done between attribute values to determine when the attribute was not equal to
the specified value
• Interpolation occurs when:
• the underlying PI point has step attribute turned off
• there is no recorded value with the specified timestamp
• The interpolated value will be based on the values before and after the timestamp
• No value will be interpolated if the step attribute is turned on. In this case, the value of record will be that at
the time of the event (if it exists) or the previously-recorded value
• If endtime is earlier than starttime, the time interval is searched backwards
Example
• FindNE('att1', '-1h', '*', 40)
[Return the timestamp of the first time since an hour ago when ' att1' was not equal to 40]
• FindNE('enum_att1', '30-March-17', '*', "On")
[Return the timestamp of the first time since the start of day (12am) on March 30th, 2017 when
enumeration value 'enum_att1' was not equal to "On"]
FirstValue
Get the first value in an array that satisfies a given condition.
Syntax
FirstValue(a1 [, condition($val)])

Arguments
• a1
a variable representing the array to operate on
• condition($val)
any supported PE statement, as a function of $val, that returns a true or false. $val is a placeholder for each
value in the array
Returns
The first value that satisfies the given condition
Exceptions
None
Notes
None
Example
• FirstValue(Data)
[Return the first value from an array named Data]
• FirstVal(Data, $val < 90)
[From the array named Data, return the first value in the array that is less than 90]

Float
Convert a string to a number.
Syntax
Float(x)

Arguments
• x
A string or a number, or an attribute whose value evaluates to a number at time of evaluation
Returns
A number for a numeric string. If x is already a number, x is returned
Exceptions
If x is not a number or a numeric string, returns Calc Failed
 Notes
Unit of measure of the argument, if it exists, is carried over to the result. Float also takes timespan and boolean
as argument. Note, however, that Float only converts timespan format to the number of seconds from 12:00am
Jan 1, 1970.
Example
• Float("12.3")
[Converts string to a number and returns 12.3]
• Float(12.3)
[Returns 12.3]
• Float('*')
[Return the total number of seconds passed since Jan 1, 1970]

Floor
Return the nearest integer less than or equal to x.
Syntax
Floor(x)

Arguments
• x
Integer or a real number, or an attribute whose value evaluates to a number at time of evaluation
Returns
The nearest integer less than or equal to x
Exceptions
Returns an error if x is a digital state, time expression, time interval or a string
Notes
Unit of measure of the argument, if it exists, is carried over to the result
Example
• Floor(3.14)
[Returns 3]
• Floor(-3.14)
[Returns -4]
• Floor(TagVal('att1', '*'))
[Return the nearest integer less than or equal to the current value of 'att1']
Format
Convert a number to string according to a format expression.
Syntax
Format(x, format [,culture])

Arguments
• x
An integer or a real number
• format
Format-control string, similar to that used by the C language function Sprintf
• culture
Optional. Culture name string, enclosed in double quotation marks. Example values include "de-DE", "ja-jp",
"pt-br", "zh-cn". Use "" to specify the culture-invariant setting (the default setting).
Returns
A formatted string
Example
• Format(1234.567, "%10.2f", "de-DE")
[Returns "1234,57", a formatted string]
• Format(45, "%3.3d")
[Returns "045"]

Frac
Return the fractional part of a real number. Returns 0 for integers.
Syntax
Frac(x)

Arguments
• x
Must be an integer or real number
Returns
The fractional part of x
Exceptions
If x is not an integer or real number, returns an error value
Notes
By definition: Int(x) + Frac(x) = x
 Unit of measure of the argument, if it exists, is carried over to the result
Example
• Frac(1)
[Returns 0]
• Frac(1.3)
[Returns 0.3]
• Frac(TagVal('att1', '*'))
[Return the fractional part of the value of 'att1' at current time.]

HasChanged
Return True if an attribute has had any event in the specified time period; otherwise return False.
Syntax
HasChanged(attname, t1)

Arguments
• attname
The name of an attribute enclosed in single quotation marks
• t1
The start of a time period ending at execution time; can be any relative time expression in single quotation
marks (such as 't - 4h')
Returns
True if attname has any event in the specified time period; otherwise returns False
Example
• HasChanged('att1', 't-4h')
[Returns True if 'att1' received any updates since 8 p.m. last night, regardless of whether the update changed
the actual attribute value]

HasValueChanged
Determine if the value of an attribute or expression has changed since it was last evaluated during an analysis.
Syntax
HasValueChanged(x)

Arguments
• x
attribute or expression
 Returns
True if the value of x has changed since last evaluated during the analysis; otherwise returns False.
If x is an expression that this function has not yet evaluated during the analysis, then the function returns False.
If x is an attribute that this function has not yet evaluated during the analysis, then the function finds the
previous recorded value and compares the current value to that previous value. If there is no previous value,
then the function returns False.
Notes
HasValueChanged is a "stateful" function. Previous evaluations are stored in memory and compared against the
new value to see if there has been a change in state. If PI Analysis Service restarts during an analysis, memory is
flushed and any previous evaluations are lost.
Example
• HasValueChanged('att1')
• [Returns True if the value of att1 has changed since last evaluated during the analysis]
• HasValueChanged('att1'+'att2')
[Returns True if the value of sum of att1 and att2 has changed since last evaluated during the analysis]

Hour
Extract the hour from a time expression.
Syntax
Hour(t1)

Arguments
• t1
A time expression, enclosed in single quotes
Returns
The hour of time, in the range 0-23
Exceptions
None
Example
• Hour('*')
[Return the hour portion of current time]
• Hour('Saturday')
[Returns 0]
• Hour(FindEq('att1', '-1d', '*', 50))
[Return the hour of the time when the value of 'att1' was first equal to 50 in the past 24 hours]
IF
Operator that introduces the condition in IF-THEN-ELSE statement. Return the first of two specified values if the
conditional expression is true. Otherwise, return the second value.
Syntax
IF (expression) THEN (x) ELSE (y)

Arguments
• expression
Any expression that evaluates to true or false
• x, y
An expression that evaluates to an output value
Returns
x when the conditional expression is true and y when the expression is false
Exceptions
None
Example
• IF ('att1' > 50) THEN ('att2') ELSE ('att3')
[If the value of 'att1' is greater than 50, then return 'the value of 'att2'; otherwise return the value of 'att3']

IN
Return True if a value is included in a set or a range of inclusive values.
Syntax
x In (y1 [, ... yn])
x In (y1...yn)

Arguments
• x
numeric value or string
• y1 [, ... yn]
a set of numeric or string values
• y1 ... yn
a range of numeric values
Returns
True when x is included in a set or a range of values
 Exceptions
None
Notes
If y1 is a decimal number that defines a range (as in the second syntax), use 2 dots instead of 3 between y1 and
yn.
Example
• 1 In (9, 10)
[Returns False since 1 is not included in a set of 9 and 10]
• 2 In (1...10)
[Returns True since 2 is included in a range of 1 to 10]
• 2 In (1.5..10)
• [Returns True since 2 is included in a range of 1.5 to 10]

InStr
Return the location within a string where a sub-string match is first found.
Syntax
InStr([start,] s1, s2 [,caseSensitive])

Arguments
• start
Optional: An integer specifying which character in s1 to start the comparison. Must be larger than or equal
to 1.
• s1, s2
Two strings to be compared.
• caseSensitive
Optional: A flag indicating if the comparison is case-sensitive. If 0 (the default) the comparison is case-
insensitive, if 1, the comparison is case-sensitive.
Returns
0 if s2 is not a sub-string of s1 starting from the start position; otherwise, the location of character where s2 first
matches the characters in s1 from the start position.
Exceptions
Wildcard characters are not treated as wildcards.
Example
• InStr("What", "At")
[Returns 3]
• InStr("What What What", "What")
 [Returns 1]
• InStr("what", "At", 1)
[Returns 0]
• InStr(4, "what", "At")
[Returns 0]
• InStr('att1', "Error")
[Returns 1 if the value of att1 is "Error"]

Int
Return the integer part of an integer or real number.
Syntax
Int(x)

Arguments
• x
Number, Boolean, numeric string, timespan, or an attribute whose value evaluates to a number at time of
evaluation
Returns
If x is a number, the integer part of x is returned. If x is a string, it is first converted into a number. If x is a
timespan, the number of seconds from 12:00am January 1, 1970 is returned
Exceptions
Returns error if the variable is not assigned
Notes
Int('*') returns UTC time in seconds from 12:00am January 1, 1970
Example
• Int('att1')
[Return the integer part of the value of 'att1' at current time]
• Int('*'-'t')
[Return how many seconds have passed since the start of day today]
• Int(2.1)
[Returns 2]
• Int("2.1")
[First converts the string to a number and returns 2]
• Int(true)
[Returns 1]
InterpolatedValues
Obtain interpolated values over a specified time range using the specified time step.
Syntax
InterpolatedValues(attname, starttime, endtime, timestep)

Arguments
• attname
attribute of time series data (such as PI point data reference) enclosed in single quotes
• starttime
a time expression representing the beginning of a time range enclosed in single quotes; can be a relative
time (such as '-3h') in reference to an absolute endtime
• endtime
a time expression representing the end of a time range enclosed in single quotes; can be a relative time
(such as '+1h') in reference to an absolute starttime
• timestep
a time interval enclosed in single quotes (such as '+1m' or '-10s') representing the incremental change in
time between the specified range to obtain the interpolated values
Returns
An array of the values obtained within the specified range in intervals of the time step
Exceptions
If the attribute does not support range calls or interpolated values of range calls, the function returns an error
indicating as such
Notes
• If the starttime is earlier than the endtime, the resulting values will be in time-ascending order, otherwise
they will be in time-descending order.
• When a positive timestep is specified, the interval calculation begins at the earliest bounding time in the
time range and applies the interval repeatedly in the time-ascending direction to generate the calculation
intervals.
• If a negative timestep is specified, the interval calculation begins at the latest bounding time in the time
range and applies the interval repeatedly in the time-descending direction to generate the calculation
intervals.
• Note that the order of values returned will still be reflected by the time range, regardless of the timestep
sign.
Example
• InterpolatedValues('att1', 't', '+1h', '+10m')
[Return the values of 'att1' between 12:00 and 1:00am today in 10-minute intervals]
• InterpolatedValues('att1', 't', '+1h', '-14m')
 [Return the values of 'att1' between 12:00 and 1:00am today in 14-minute intervals, anchoring from 1:00am
(that is, 12:04,12:18,12:32,12:46,1:00)]

IsSet
For an attribute associated with a PI point, determine if the point is annotated, substituted, or questionable.
Syntax
IsSet(attname, select)

Arguments
• attname
An attribute associated with a PI point of value type integer, real number, enumeration value, or string
• select
A string but only the first character is considered: "a" for annotate, "s" for substituted and "q" for
questionable. Not case-sensitive.
Returns
True or False
Exceptions
None
Example
• IsSet('att1', "a")
[Returns True if the value of 'att1' is annotated]
• IsSet('att1', "s")
[Returns True if the value of 'att1' is substituted]]
• IsSet('att1', "q")
[Returns True if the value of 'att1' is questionable]

LastValue
Get the last value in an array that satisfies a given condition.
Syntax
LastValue(a1 [, condition($val)])

Arguments
• a1
a variable representing the array to operate on
• condition($val)
any supported PE statement, as a function of $val, that returns a true or false. $val is a placeholder for each
value in the array
 Returns
The last value that satisfies the given condition
Exceptions
None
Notes
None
Example
• LastValue(Data)
[Return the last value from an array named Data]
• LastValue(Data, $val > 90 and $val < 105)
[From the array named Data, return the last value in the array that is greater than 90 and less than 105]

LCase
Convert a string to a lowercase string.
Syntax
LCase(s1)

Arguments
• s1
string
Returns
A string that has been converted to lowercase
Exceptions
If the argument is not a string, returns an error value
Example
• LCase("String")
[Returns "string"]

Left
Return a specified number of characters of a string from the left.
Syntax
Left(s1, len)

Arguments
• s1
String
 • len
Integer
Returns
The first len characters of the string, starting from the left
Exceptions
If the arguments are not of the required types, returns an error
Example
• Left("String_att", 3)
[Returns "Str"]

Len
Return the length of a string.
Syntax
Len(s1)

Arguments
• s1
string
Returns
The length of a string
Exceptions
If the argument is not a string, returns an error value
Example
• Len("String")
[Returns 6]
• Len('sinusoid')
[Returns Calc Failed]

LinRegr
Apply linear least squares fitting to two sets of values given by attributes over a specified time range. The output
is a one-based array with the values of the slope, intercept and R2.
Syntax
LinRegr(x, y, mode, starttime, endtime [, pctgood])
LinRegr(y, starttime, endtime [, pctgood])
Arguments
• x
an attribute with the first set of time series data (such as PI point data reference) enclosed in single quotes
• y
an attribute with the second set of time series data (such as PI point data reference) enclosed in single
quotes
• mode
a number that specifies how to align time-stamped values
• choose from 0, 1 or 2 where:
0 represents the combination of time-stamped values from x and y
1 represents values from both attributes according to x's time stamps
2 represents values from both attributes according to y's time stamps
• starttime
a time expression representing the beginning of a time range enclosed in single quotes; can be a relative
time (such as '-3h') in reference to an absolute endtime
• endtime
a time expression representing the end of a time range enclosed in single quotes; can be a relative time
(such as '+1h') in reference to an absolute starttime
• pctgood
Optional. Minimum percentage of time during the time range that attribute values must be good.
You can set pctgood as a threshold to ensure that there are sufficient good values to calculate LinRegr.
Returns
One-based array with the values of slope, intercept and R2.
Exceptions
If the attribute has no good values or the pctgood minimum is not reached for the given time range, returns an
error value
Notes
Bad values are excluded from LinRegr calculation.
For LinRegr(y, starttime, endtime [, pctgood]), the unit of the output slope is unit of y/second.
Note: If the attribute has very few good values during the time range, this function's result may not be
trustworthy. Use the PctGood function to find out what percentage of the values is good.
 Index the slope, intercept and R2 outputs from [1].
Example
• LinRegr('att1', 'att2', 0, 't', '+1h', 80)
[Return a one-based array of slope, intercept and R2 based on time-stamped values of 'att1' and 'att2'
between 12:00 and 1:00am today when at least 80% of the values were good. Return an error when
minimum pctgood is not reached]
• LinRegr('att1', 'att2', 1, 't', '+1h')
[Return a one-based array of slope, intercept and R2 based on time-stamped values of 'att1' between 12:00
and 1:00am today]
• LinRegr('att1', 't', '+1h', 80)
[Return a one-based array of slope, intercept and R2 of 'att1' between 12:00 and 1:00am today when at least
80% of the values were good. Return an error when minimum pctgood is not reached]
• LinRegr('att1', 't', '+1h')
[Return a one-based array of slope, intercept and R2 of 'att1' between 12:00 and 1:00am today]

Log
Return the natural logarithm (base e = 2.7182818...) of an integer or real number.
Syntax
Log(x)

Arguments
• x
Must be an integer or real number greater than zero
Returns
The natural logarithm of x
Exceptions
If x is zero or negative, or not a number, returns an error value
 Example
• Log(14)
[Returns 2.6391]
• Log(TagVal('att1', '14-Dec-16'))
[Return the natural log of the value of 'att1' at 12:00am on Dec 14, 2016]

Log10
Return the base 10 logarithm of an integer or real number.
Syntax
Log10(x)

Arguments
• x
Must be an integer or real number greater than zero
Returns
The base 10 logarithm of x
Exceptions/Errors
If x is zero or negative, or not a number, returns an error value
Example
• Log10(100)
[Returns 2]
• Log10(TagVal('att1', '14-Dec-16'))
[Return the base 10 logarithm of the value of 'att1' at 12:00am on Dec 14, 2016]

Logbase
Return the logarithm of positive numeric value x to a specified base y.
Syntax
Logbase(x,y)

Arguments
• x
An integer or real number greater than zero
• y
A positive integer indicating the base of the logarithm
Returns
The logarithm of x to base y
 Exceptions
If x is zero or negative, or not a number, returns an error value
Example
• Logbase(256, 2)
[Returns 8]
• Logbase(1000, 10)
[Returns 3]
• Logbase(TagVal('att1', '14-Dec-16'), 16)
[Return the logarithm of the value of 'att1' at 12:00am on Dec 14, 2016 to base 16]

LTrim
Remove the leading blanks from a string.
Syntax
LTrim(s1)

Arguments
• s1
string
Returns
A string with leading blanks removed
Exceptions
If s1 is not a string, an error value is returned.
Example
• LTrim(" String")
[Returns "String"]
• LTrim("String ")
[Returns "String "]

MapData
Apply a function to each value in an array.
Syntax
MapData(a1, function($val))

Arguments
• a1
a variable representing the array to operate on
 • function($val)
any supported PE statement, as a function of $val, that performs an operation. $val is a placeholder for each
value in the array
Returns
The transformed array of all the values
Exceptions
None
Notes
The output array has the same timestamps as the input array.
Example
• MapData(Data, (IF BadVal($val) THEN 0 ELSE $val))
[From an array named Data, return a new array with bad values set to 0]

Max
Return the time-weighted or event-weighted maximum from a set of values.
Syntax
Max(x1, ... xn)
Max(array [, calculationBasis])

Arguments
• x1, ... xn
Arguments or a single array of same value type (integers and real numbers, enumeration values, time
expressions, or time intervals)
• calculationBasis
Optional. The type of calculation to be performed enclosed in double quotes. Choose between
"EventWeighted" or "TimeWeighted." If omitted, the default is event-weighted. If you select
"TimeWeighted," the earliest timestamp of the value marks the start time and the latest timestamp the end
of a time range
Returns
The maximum from a set of arguments. The result is of the same data type as the arguments
Exceptions
Arguments whose run-time values are digital states are ignored. If all values are digital states, Max returns an
error. Returns an error if the array does not consist of same value type
Notes
• Unit of Measure (UOM) of the arguments is carried over to the result when at least one argument has a
defined UOM while others don't. The returned value lacks a UOM if arguments have different UOMs
 Example
• Max(14, 'att1', 14.5, TagVal('att2','14-Dec-16'))
[Find the maximum from these values: 14, value of 'att1' at trigger time, 14.5, and the value for 'att2' at start
of day (12:00am) on Dec 14, 2016]
• Max('enum_att1', 'enum_att2', 'enum_att3')
[At trigger time, find the highest value from an enumeration set and return its name]
• Max('*', 'y', 'Saturday')
[Find the most recent timestamp. Returns current time from the example above]
• Max('*'-'*-1h', 't+8h'-'y+4h', '*'-'t')
[Find the longest interval from these time periods: from 1 hour ago to now, from 4:00am yesterday to today
at 8am, from 12:00am yesterday to 12:00am on 20th of this month, and from the beginning of day today
(12:00am) till now]
• Max(Variable1)
Name Expression Value at Evaluation

Variable1 RecordedValues('att1', '*-10m', [1, 3, 5, 7, 9]

'*')
Variable 2 Max(Variable1) 9
[Find the maximum of values in an array named Variable1]
• Max(Data)
[Return the event-weighted maximum of values from an array named Data]
• Max(Data, "EventWeighted")
[Return the event-weighted maximum of values from an array named Data]
• Max(Data, "TimeWeighted")
[Return the time-weighted maximum of values from an array named Data using the timestamps of the
earliest and latest values of the array as the start time and end time respectively]

Median
Return the time-weighted or event-weighted median (middle value) of one or more values.
Syntax
Median(x1 [, ... xn])
Median(array)

Arguments
• x1 [, ... xn]
Arguments and single array of same value type (integers and real numbers, time expressions, or time
intervals)
 Returns
The median value of the input argument(s). If there are even number of arguments, the average of the two
middle values is returned. Returns an error if the array does not consist of same value type
Exceptions
Arguments whose run-time values are digital states are ignored. The function must have one or more arguments
that evaluate to non-digital states; otherwise, Median returns an error value. Also returns an error if the array
does not consist of same value type
Notes
Arguments must be of same value type. The data type of the first argument sets the tone for the rest
Unit of Measure (UOM) of the arguments is carried over to the result when at least one argument has a defined
UOM while others don't. The returned value lacks a UOM if arguments have different UOMs
Examples
• Median(14, 'att1', 14.5, TagVal('att2', '14-Dec-16'))
[Find the median of these values: 14, the current value of att1, 14.5, and the value for att2 at midnight on
Dec 14, 2016]
• Median('*', 'y', 'Saturday')
[Find the median of these timestamps: now, 12:00am yesterday, and 12:00am last Saturday]
• Median('*'-'*-1h', 't+4h'-'y+8h', 'y+2h'-'20')
[Find the median of these time periods: from 1 hour ago to now, from 8:00am yesterday to 4:00am today,
and 2:00am yesterday to the start of day (12am) on the 20th of this month]
• Median(Variable1)
Name Expression Value at Evaluation

Variable1 RecordedValues('att1', '*-10m', [1, 3, 5, 7, 9]

'*')
Variable 2 Median(Variable1) 5
[Find the median of values in an array named Variable1]
• Median(Data)
[Return the event-weighted median of values for an array named Data]

Mid
Return a sub-string within a string.
Syntax
Mid(s1, start [,len])

Arguments
• s1
 string
• start
An integer specifying the position of the first character within the string. The first character in the string is
number 1
len
Optional: The maximum length of the returned string. The default is the length of the string
Returns
len characters of the string to the right of (and including) the first character whose position is specified by start

Exceptions
If the arguments are not of the required types, an error value is returned. The maximum number of characters
that can be returned is 999
Example
• Mid("String", 3)
[Returns "ring"]
• Mid("String", 3, 2)
[Returns "ri"]

Min
Return the time-weighted or event-weighted minimum from a set of values.
Syntax
Min(x1, ... xn)
Min(array [, calculationBasis])

Arguments
• x1, ... xn
Arguments or a single array of same value type (integers and real numbers, enumeration values, time
expressions, or time intervals)
• calculationBasis
Optional. The type of calculation to be performed enclosed in double quotes. Choose between
"EventWeighted" or "TimeWeighted." If omitted, the default is event-weighted. If you select
"TimeWeighted," the earliest timestamp of the value marks the start time and the latest timestamp the end
of a time range
Returns
The minimum from a set of arguments. The result is of the same data type as arguments
Exceptions
Arguments whose run-time values are digital states are ignored. If all values are digital states, Min returns an
error. Returns an error if the array does not consist of same value type
 Notes
• Unit of Measure (UOM) of the arguments is carried over to the result when at least one argument has a
defined UOM while others don't. The returned value lacks a UOM if arguments have different UOMs
Example
• Min(14, 'att1', 14.5, TagVal('att2','14-Dec-16'))
• [Find the minimum from these values: 14, value of 'att1' at trigger time, 14.5, and the value for 'att2' at start
of day (12:00am) on Dec 14, 2016]
• Min('enum_att1', 'enum_att2', 'enum_att3')
• [At trigger time, find the lowest value from an enumeration set and return its name]
• Min('*', 'y', 'Saturday')
[Find the oldest timestamp from a set]
• Min('*'-'*-1h', 't+8h'-'y+4h', 'y'-'20', '*'-'t')
[Find the shortest interval from these time periods: from 1 hour ago to now, from 4:00am yesterday to today
at 8am, from 12:00am yesterday to 12:00am on 20th of this month, and from the beginning of day today
(12:00am) till now]
• Min(Variable1)
Name Expression Value at Evaluation
Variable1 RecordedValues('att1', '*-10m', [1, 3, 5, 7, 9]
'*')
Variable 2 Min(Variable1) 1
[Find the minimum of values in an array Variable1]
• Min(Data)
[Return the event-weighted minimum of values from an array named Data]
• Min(Data, "EventWeighted")
[Return the event-weighted minimum of values from an array named Data]
• Min(Data, "TimeWeighted")
[Return the time-weighted minimum of values from an array named Data using the timestamps of the
earliest and latest values of the array as the start time and end time respectively]

Minute
Extract the minute from a time expression.
Syntax
Minute(t1)

Arguments
• t1
 A time expression, enclosed in single quotes
Returns
The minute of time, in the range 0-59
Exceptions
None
Example
• Minute('*')
[Extract the minute from current time]
• Minute(FindGT('att1', '-1h', '*', 5)
[Extract the minute from a timestamp when the value of 'att1' was first greater than 5 in the past hour.
Return error if it was never over 5]

Mod
The modulus operator (mod) returns the remainder from the quotient of two numeric values. For x Mod y, this is
the remainder from x/y.
Syntax
x Mod y

Arguments
• x
Any expression that evaluates to a numeric value
• y
Any non-zero numeric value
Returns
Remainder from x/y
Exceptions
None
Notes
UOM of x, if it exists, is carried over to the result
Example
• 11 Mod 3
[Returns 2]

Month
Extract the month from a given time expression.
 Syntax
Month(t1)

Arguments
• t1
A time expression, enclosed in single quotes
Returns
The month of time, in the range 1-12
Exceptions
None
Example
• Month('*')
[Return the current month]
• Month(FindEq('att1', '-10d', '*', 5')
[Return the month from a timestamp when the value of 'att1' was first equal to 5 in the past 10 days]

NextEvent
Find the timestamp of the next recorded value after a specified time.
Syntax
NextEvent(attname, t1)

Arguments
• attname
The name of an attribute, enclosed in single quotation marks
• t1
A time expression
Returns
The timestamp of the next recorded value after the specified time for the specified attribute
Exceptions
If there is no recorded value after the specified time, then the function returns No Data
Example
• NextEvent('att1', 't')
[Find and return the timestamp of the next recorded value of 'att1' since the start of day (12am) today]

NextVal
Find the next recorded value after a specified time.
 Syntax
NextVal(attname, t1)

Arguments
• attname
The name of an attribute, enclosed in single quotation marks
• t1
A time expression
Returns
The next recorded value after the specified time for the specified attribute
Exceptions
If there is no recorded value after the specified time, the function returns an error.
Example
• NextVal('att1', 't')
[Find and return the next recorded value of 'att1' since the start of day (12am) today]

Noon
Return a timestamp for noon on the day of a given time expression.
Syntax
Noon(t1)

Arguments
• t1
A time expression enclosed in single quotes
Returns
A timestamp corresponding to noon of the day of the input time
Exceptions
None
Notes
This function is useful for establishing a unique clock time independent of the length of particular days.
Example
• Noon('*')
[Return the timestamp for noon of current day]
• Noon(FindEq('att1', '-3d', '*', 50))
[Return the timestamp for noon of the day when 'att1' was first equal to 50 in the past 3 days]
NoOutput
Do not write current calculation result.
Syntax
NoOutput()

Arguments
None
Notes
It is important to include the parentheses after this function (use NoOutput() instead of NoOutput as NoOutput is
an invalid syntax). This function applies only to the current calculation.
Example
• If 'att1' < 100 or 'att1' > 200 then 'att1' else NoOutput()

Normalrnd
Return a random number that maps the normal distribution curve using a specified mean and standard
deviation.
Syntax
Normalrnd(x, y)

Arguments
• x
A real number specifying the mean of the normal distribution curve
• y
A real number specifying the standard deviation of the normal distribution curve
Returns
A random number that maps the normal distribution curve with a specified mean and standard deviation
Exceptions
None
Example
• Normalrnd(300, 2.5)

NOT
Return the negation of an expression. Return True if the truth value of an expression is false and False if the truth
value of an expression is true.
Syntax
NOT expression
 Arguments
• expression
Any expression that evaluates to true or false
Returns
True when the expression is false and False when the expression is true
Exceptions
None
Example
• NOT (1 In (1...10))
[Returns False since (1 In (1...10)) is true]

NumOfChanges
Return the number of changes in value for an attribute within a specified time range.
Syntax
NumOfChanges(attname, starttime, endtime)

Arguments
• attname
The name of an attribute
• starttime
A time expression that specifies the start of a time range, or a time span (such as '-3h') that specifies the
start time relative to endtime; entries must be enclosed in single quotation marks
• endtime
A time expression that specifies the end of a time range, or a time span (such as '+3h') that specifies the end
time relative to startime; entries must be enclosed in single quotation marks
Returns
The count of changes in value for attname in the specified time range excluding bad values
Example
• NumOfChanges('att1', 't', '*')
[Return the number of times the value of 'att1' changed since midnight until now]

OR
The logical disjunction of two expressions that returns True if either expression is true and False if both are false.
Syntax
expression1 OR expression2
 Arguments
• expression1
Any expression that evaluates to true or false
• expression2
Any expression that evaluates to true or false
Returns
True if either expression is true and False if both are false
Exceptions
None
Notes
If the inputs are numeric, OR can do bitwise operations.
Example
• ('att1' > 50) OR ('att2' = "good")

ParseTime
Translate a PI time expression to a timestamp. Use regular time expression inside single quotes for better
performance.
Syntax
ParseTime(s1)

Arguments
• s1
A character string or an array of strings in PI time format, enclosed in double quotes
Returns
The timestamp corresponding to s1
Exceptions
If s1 is not a character string, or if there is a syntax error, returns an error value.
If the array does not consist of strings in a time format, returns an error.
Notes
Use of the time expression '01-Jan-2018' over the string "01-Jan-2018" is strongly recommended.
Example
• ParseTime(Concat("12", "-31", "-16"))
[Returns 12/31/2016 12:00:00 AM, which is the same as '12/31/16']
• ParseTime("14-Dec-16")
[Renders the same result as '14-Dec-16'. Use only when string operations are necessary]
 • ParseTime("*")
[Renders the same result as '*'. Use only when string operations are necessary]
• ParseTime(Variable1)
Name Expression Value at Evaluation
Variable1 'TimeStringArray' [t, t+3h, t+14h]
Variable 2 ParseTime(Variable1) [3/14/2018 12:00:00 AM,
3/14/2018 3:00:00 AM,
3/14/2018 2:00:00 PM]
[Renders the array results in a proper PI Time format, assuming today is 3/14/18]

PctGood
Find the time-weighted or event-weighted percentage, over a specified time range, for which the attribute had
good values.
Syntax
PctGood(attname, starttime, endtime [, calculationBasis])

Arguments
• attname
attribute with time series data (such as PI point data reference) enclosed in single quotes
• starttime
time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as'-3h') in reference to an absolute endtime
• endtime
time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as '+1h') in reference to an absolute starttime
• calculationBasis
Optional. A string indicating the type of calculation to be performed enclosed in double quotes. Choose
between "TimeWeighted" or "EventWeighted". If omitted, the default is time-weighted
Returns
An integer or real number from 0 to 100: time-weighted or event-weighted minimum time percentage during a
specified time range for which the attribute had good values
Example
• PctGood('att1', 't', '+1h')
[Return the time-weighted percentage between 12:00 and 1:00am today for which 'att1' had good values]
• PctGood('att1', '-1h', '*')
[Return the time-weighted percentage between now and hour ago today for which 'att1' had good values]
• PctGood('att1', '-1h', '*', "EventWeighted")
 [Return the event-weighted percentage between now and hour ago today for which 'att1' had good values]

Pi
Returns the value for pi.
Syntax
Pi()

Arguments
Returns
The value for pi
Exceptions
None
Example
• Pi()

Poisson
Return a random number that maps a Poisson distribution with a specific mean.
Syntax
Poisson(x)

Arguments
• x
Must be an integer or real number
Returns
A random number that maps a Poisson distribution with a specified mean
Exceptions
None
Example
• Poisson(15)

Poly
Return the polynomial c0 + c1x + c2x2 + … +cnxn.
Syntax
Poly(x, c0 [, ... cn])

Arguments
• x
 Variable. An integer or real number
• c0 [, ... cn]
Coefficients. There must be at least one coefficient. All must be numbers.
Returns
The value of the polynomial
Exceptions
If x or any coefficient is not an integer or real number, Poly returns an error value
Example
• Poly(3, 4, 5)
[Returns 19]
• Poly('att1', 2, 3)

Pow
Return x raised to the power y.
Syntax
Pow(x, y)

Arguments
• x
numeric value
• y
numeric value
Returns
The value of x raised to the power y
Exceptions
None
Notes
• The Pow function only works in PI Asset Framework (PI AF) asset analytics expression functions. Use caret (^)
operator for same effect in Data Archive performance equations
• Both Pow(2, 3) and 2^3 are acceptable in PI AF asset analytics expression functions
Example
• Pow(2, 3)
[Returns 8]
• Pow(2.5, 3)
[Returns 15.625]
 • Pow(TagVal('att1', '*'), 8)
[Return the current value of 'att1' raised to the power 8]

PrevEvent
Find the timestamp of the last recorded value before a specified time.
Syntax
PrevEvent(attname, t1)

Arguments
• attname
The name of an attribute, enclosed in single quotation marks
• t1
A time expression
Returns
The timestamp of the last recorded value before the specified time for the specified attribute
Exceptions
If there is no recorded value before the specified time, the function returns an error.
Example
• PrevEvent('att1', '*')
[Find the timestamp of the last recorded value of 'att1' before current time]

PrevVal
Find the last recorded value before a specified time.
Syntax
PrevVal(attname, t1)

Arguments
• attname
The name of an attribute, enclosed in single quotation marks
• t1
A time expression
Returns
The last recorded value before the specified time for the specified attribute
Exceptions
If there is no recorded value before the specified time, the function returns an error.
 Example
• PrevVal('att1', '*')
[Find and return the last recorded value of 'att1' before current time]
• PrevVal('att1', '15-Mar-17')
[Find and return the last recorded value of 'att1' before start of day (12am) March 15th, 2017]

PStDev
Return the time-weighted or event-weighted population standard deviation for a population of one or more
values.
Syntax
PStDev(x1 [, ... xn])
PStDev(array [, calculationBasis])

Arguments
• x1, ... xn
Arguments and a single array of same value type (integers and real numbers, time expressions, or time
intervals)
• calculationBasis
Optional. The type of calculation to be performed enclosed in double quotes. Choose between
"EventWeighted" or "TimeWeighted." If omitted, the default is event-weighted. If you select
"TimeWeighted," the earliest timestamp of the value marks the start time and the latest timestamp the end
of a time range
Returns
The population standard deviation for the arguments. Returns a numeric value if the arguments are numbers.
For arguments that are time expressions (time or time period), a number indicating a time period expressed in
seconds is returned
The population standard deviation of a population x1, ..., xn is

where is the mean of the arguments; that is,

 Exceptions
Arguments whose run-time values are digital states are ignored. If all values are digital states, an error value is
returned. Returns an error if the array does not consist of same value type
Notes
• PStDev uses every value in a population to calculate the population standard deviation. However, it is
common, especially for a large population, to estimate standard deviation from a sample of the population.
SStDev uses a set of sample values to calculate sample standard deviation, which approximates the
population standard deviation
• Unit of Measure (UOM) of the arguments is carried over to the result when at least one argument has a
defined UOM while others don't. The returned value lacks a UOM if arguments have different UOMs
Example
• PStDev(14, 'att1', 14.5, TagVal('att2','14-Dec-16'))
[Return the "population standard deviation" of these values: 14, the current value of 'att1', 14.5, and the
value for 'att2' at start of day (12:00am) on Dec 14, 2016]
• PStDev('*', 'y', 'Saturday')
[Return the "population standard deviation" of these timestamps]
• PStDev('*'-'*-1h', 't+8h'-'y+4h', 'y'-'20', '*'-'t')
[Return the "population standard deviation" of these time periods: from 1 hour ago to now, from 4:00am
yesterday to today at 8am, from 12:00am yesterday to 12:00am on 20th of this month, and from the
beginning of day today (12:00am) till now]
• PStDev(Variable1)
Name Expression Value at Evaluation

Variable1 RecordedValues('att1', '*-10m', [1, 3, 5, 7, 9]

'*')
Variable 2 PStDev(Variable1) 2.8284
[Find the "population standard deviation" of values in an array named Variable1]
• PStDev(Data)
[Return the event-weighted "population standard deviation" of values in an array named Data]
• PStDev(Data, "EventWeighted")
[Return the event-weighted "population standard deviation" of values in an array named Data]
• PStDev(Data, "TimeWeighted")
[Return the time-weighted "population standard deviation" of values in an array named Data using the
timestamps of the earliest and the latest values of the array as the start time and end time respectively]

Rand
Return a random number between 0 and 1. For specified x and y values, return a random number between x -
y/2 and x + y/2.
 Syntax
Rand(x, y)

Arguments
• x
A real number specifying the center point of the range
• y
A real number specifying the size of the range.
If no arguments are specified, the default range is from 0 to 1.
Returns
A random number between 0 and 1. For specified x and y values, returns a random number between x- y/2 and x
+ y/2.
Exceptions
None
Example
• Rand()
• Rand(500, 250)

Range
Find the time-weighted or event-weighted difference between the maximum and minimum values for an
attribute during a specified time range. Time-weighted values are interpolated at time boundaries when possible
and extrapolated otherwise.
Syntax
Range(attname, starttime, endtime [, pctgood, calculationBasis])

Arguments
• attname
attribute with time series data (such as PI point data reference) enclosed in single quotes
• starttime
time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as'-3h') in reference to an absolute endtime
• endtime
time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as '+1h') in reference to an absolute starttime
• pctgood
Optional. Time-weighted or event-weighted minimum time percentage over a specified time range for which
the attribute had good values
 • calculationBasis
Optional. A string indicating the type of calculation to be performed enclosed in double quotes. Choose
between "TimeWeighted" or "EventWeighted". If omitted, the default is time-weighted
Returns
The time-weighted or event-weighted difference between the attribute's maximum and minimum values during
the specified time. Time-weighted values are interpolated at time boundaries when possible and extrapolated
otherwise
Exceptions
If the attribute has no good values or the pctgood minimum is not reached in the given time range, an error is
returned
Notes
• Bad values are excluded from Range calculation
• In order to configure an optional parameter, any previous optional parameter must be specified
Note: If the attribute has very few good values during the time range, this function's result may not be
trustworthy. Use the PctGood function to find out what percentage of the values is good
Example
• Range('att1', 't', '+1h')
[Return the time-weighted difference between the maximum and minimum values for 'att1' between 12:00
and 1:00am today]
• Range('att1', 't', '+1h', 80)
[Return the time-weighted difference between the maximum and minimum values for 'att1' between 12:00
and 1:00am today when at least 80% of the values were good]
• Range('att1', 't', '+1h', 80, "EventWeighted")
[Return the event-weighted difference between the maximum and minimum values for 'att1' between 12:00
and 1:00am today when at least 80% of the values were good]

Rate
Return the difference over time between the current value and a previously evaluated value of an attribute or
(time) expression.
Syntax
Rate(x)

Arguments
• x
An attribute or (time) expression that resolves to a numeric value
 Returns
• The calculated difference, using the value of the attribute, numeric, or timestamp value of the expression
parameter, according to this formula: (current value – previously evaluated value) / (current timestamp –
timestamp from previous evaluation)
Example
• Rate(‘att1’)
• Rate('sinusoid')
• Rate(DaySec(‘*’) + 1)

RecordedValues
Obtain values within a particular time range based on user-specified boundary type.
Syntax
RecordedValues(attname, starttime, endtime [, boundarytype])

Arguments
• attname
attribute of time series data (such as PI point data reference) enclosed in single quotes
• starttime
a time expression representing the beginning of a time range enclosed in single quotes; can be a relative
time (such as '-3h') in reference to an absolute endtime
• endtime
a time expression representing the end of a time range enclosed in single quotes; can be a relative time
(such as '+1h') in reference to an absolute starttime
• boundarytype
a string indicating the data retrieval behavior at the end points of a specified time in double quotes:
"Inside" - return the nearest recorded values inside the requested time range as the first and last values
"Outside" - return the nearest recorded values on the outside of the requested time range as the first and
last values
"Interpolated" - create an interpolated value at the end points of the requested time range if a recorded
value does not exist at that time
Note: If unspecified, the default is the "Inside" mode.
Returns
An array of the values obtained within the specified range
Exceptions
If the attribute does not support range calls, the function returns an error with indication
 Notes
• If the starttime is earlier than the endtime, the resulting values will be in time-ascending order, otherwise
they will be in time-descending order.
• When no values are available but you specified "Outside" or "Interpolated" boundary types, a special value
(NoData) is returned.
• This function retrieves up to 500,000 values at a time.
Example
• RecordedValues('att1', 't+2h', 't+8h')
[Return the values of 'att1' between 2:00 and 8:00am today using the default "Inside" retrieval mode]
• RecordedValues('att1', 't', '+1h', "Outside")
[Return the values of 'att1' between 12:00 and 1:00am today using the "Outside" retrieval mode]

RecordedValuesByCount
Obtain a specified number of values beginning at the requested start time in the direction specified.
Syntax
RecordedValuesByCount(attname, starttime, count [, timedirection, boundarytype])

Arguments
• attname
attribute of time series data (such as PI point data reference) enclosed in single quotes
• starttime
a time expression representing the beginning of request
• count
the number of stored (recorded) values to return. The value must be greater than zero
• timedirection
a string indicating the time direction in data retrieval enclosed in double quotes:
"Backward" - begin at the start time and move backward in time. Values will be returned in time-descending
order
"Forward" - begin at the start time and move forward in time. Values will be returned in time-ascending
order
Note: If unspecified, the default is the "Backward" mode.
• boundarytype
a string indicating the data retrieval behavior at the end point of a specified time in double quotes:
"Inside" - return the nearest recorded values inside the requested time boundary
"Outside" - return the nearest recorded values on the outside of the requested time boundary
 "Interpolated" - create an interpolated value at the requested time boundary if a recorded value does not
exist at that time
Note: If unspecified, the default is the "Inside" mode.
Returns
An array of the specified number of values (if available)
Exceptions
If the attribute does not support the calls, the function returns an error with indication
Notes
• When no values are available but you specified "Outside" or "Interpolated" boundary types, a special value
(NoData) is returned.
Example
• RecordedValuesByCount('att1', 't+2h', 5)
[Return 5 values of 'att1' in time-descending order starting from 2:00am today using the default "Inside"
retrieval mode moving backwards in time]
• RecordedValuesByCount('att1', 't+8h', 3, "Forward", "Outside")
[Return the first 3 values of 'att1' since 8am today using the "Outside" retrieval mode]

Remainder
Return the remainder resulting from the division of x by y using the IEEERemainder method. This remainder is
equal to x - (y Q), where Q is the quotient of x / y rounded to the nearest integer (if x / y falls halfway between
two integers, the even integer is returned). If x - (y Q) is zero, the value +0 is returned if x is positive, or -0 if x is
negative. If y = 0, NaN (not a number) is returned.
Syntax
Remainder(x, y)

Arguments
• x
Any numeric value
• y
Any non-zero numeric value
Returns
Return the remainder resulting from the division of x by y using the IEEERemainder method
Note: This is not the same as the remainder returned using the Mod (modulus) operator
Exceptions
None
 Notes
Unit of measure of x, if it exists, is carried over to the result
Example
• Remainder(11, 3)
[Returns -1]
• Remainder(10, 3)
[Returns 1]

Right
Return a specified number of characters of a string from the right.
Syntax
Right(s1, len)

Arguments
• s1
string
• len
integer
Returns
len characters of the string from the right
Exceptions
If the arguments are not of the required types, an error value is returned.
Example
• Right("String", 3)
[Returns "ing"]
• Right("String", 20)
[Returns "String"]

Round
Round a number or time to the nearest unit.
Syntax
Round(x [, unit] [, roundingMode])

Arguments
• x
Integer, real number, time expression, or time interval
 • unit
Optional. The size of the unit to round to. If x is a number, unit must be a number. If x is a time expression or
time period, unit must be a time expression. If unit is omitted, Round rounds to the nearest even integer (for
numbers) or second (for time expressions).
• roundingMode
Optional. The type of rounding to apply. Using the string "AwayFromZero" applies rounding of midpoint
values away from zero. Omission of this parameter, or the use of "ToEven", applies the default banker's
rounding.
Returns
The nearest value to x which is an integer multiple of unit. Returns the same data type as x. For more details, see
the following examples.
Exceptions
If x is a string, or if unit is of the wrong data type, an error value is returned.
Notes
The system uses a banker's rounding which rounds a number to the nearest even number.
If x is time and unit is omitted, this routine has no effect: times are accurate only to a second.
Unit of measure of the argument, if it exists, is carried over to the result.
Example
• Round(12.499)
[Returns 12 (rounded to the nearest integer)]
• Round(12.5)
[Returns 12 (rounded to the nearest even integer)]
• Round(12.5, "AwayFromZero")
[Returns 13 (rounded up to the nearest integer)]
• Round (13.5)
[Returns 14 (rounded to the nearest integer)]
• Round(13.45, 0.1)
[Returns 13.4 (rounded to the nearest even number in one decimal place)]
• Round(13.45, 0.1, "AwayFromZero")
[Returns 13.5 (rounded up to the nearest number in one decimal place)]
• Round(1285, 10)
[Returns 1280 (rounded to the nearest even 10)]
• Round(1285, 10, "AwayFromZero")
[Returns 1290]
• Round(1285, 10, "ToEven")
 [Returns 1280 (rounded to the nearest even 10)]
• Round('14-Dec-16 11:47:16')
[Returns 14-Dec-16 11:47:16 (rounded to the nearest second)]
• Round('14-Dec-16 12:30', '+1h')
[Returns 14-Dec-97 12:00:00 (rounded to the nearest even hour)]
• Round('18:47:15'-'15:00:09')
[Returns 03:47:06 (rounded to the nearest second)]
• Round('18:45:40'-'15:15:10','+1m')
[Returns 03:30:00 (rounded to the nearest minute)]
Note: Round to the nearest day results in a timestamp of the closest day in UTC time and not local time.

Roundfrac
Round a numeric value x to y decimal places.
Syntax
Roundfrac(x, y [,roundingMode] )

Arguments
• x
Must be an integer, real number or time expression
• y
Integer that specifies the number of decimal places to round x to
• roundingMode
Optional. The type of rounding to apply. Using the string "AwayFromZero" applies rounding of midpoint
values away from zero. Omission of this parameter, or the use of "ToEven", applies the default banker's
rounding
Returns
The value of x rounded to y decimal places. Returns the same data type as x. For more details, see the examples
Exceptions
If x is a string, neither a numeric value nor a time expression, returns an error
Notes
The system uses a banker's rounding which rounds a number to the nearest even number.
Unit of measure of the argument, if it exists, is carried over to the result.
If x is time and unit is omitted, this routine has no effect: times are accurate only to 1 second.
Example
• Roundfrac (Pi(), 4)
 [Returns 3.1416 ]
• Roundfrac (0.005, 2)
[Returns 0]
• Roundfrac (0.005, 2, "ToEven")
[Returns 0]
• Roundfrac (0.005, 2, "AwayFromZero")
[Returns 0.01]
• Roundfrac (TagVal('att1'), 2)
[Return the value of 'att1' rounded to 2 decimal places]

RTrim
Trim trailing blanks from a string.
Syntax
RTrim(s1)

Arguments
• s1
string
Returns
The source string with trailing blanks removed
Exceptions
If s1 is not a string, an error value is returned
Example
• RTrim("String ")
[Returns "String"]
• RTrim(" String")
[Returns " String"]

Sec
Return the trigonometric secant of a number.
Syntax
Sec(x)

Arguments
• x
Must be an integer or real number, which represents an angle in radians
 Returns
The secant of x
Exceptions
If x is not a number, returns an error value
Example
• Sec(1)
[Returns 1.8508]
• Sec(1.1)
[Returns 2.2046]
• Sec('att1')
[Return the trigonometric secant of the value of 'att1' at time of evaluation]

Sech
Return the hyperbolic secant of a number.
Syntax
Sech(x)

Arguments
• x
Must be an integer or real number
Returns
The hyperbolic secant of x
Exceptions
If x is not a number, returns an error value
Example
• Sech(1)
[Returns 0.64805]
• Sech(1.1)
[Returns 0.59933]
• Sech('att1')
[Return the hyperbolic secant of the value of 'att1' at trigger time]

Second
Extract the second from a time expression.
 Syntax
Second(t1)

Arguments
• t1
A time expression enclosed in single quotes.
Returns
The second of time, in the range 0-59
Exceptions
None
Example
• Second('*')
[Return the second from current time]
• Second(FindEq('att1', '-1m', '*', 2)
[Return the second from a timestamp when the value of 'att1' was first equal to 2 in the past minute]

SecSinceChange
Return the time in seconds since an attribute value or the timestamp was updated.
Syntax
SecSinceChange(attname)

Arguments
• attname
The name of an attribute, enclosed in single quotation marks
Returns
The number of seconds since the last update of the value or a timestamp for an attribute
Example
• SecSinceChange('att1')
[Return the number of seconds since the value of 'att1' or the timestamp was updated]

Sgn
Return an indicator of the numerical sign of a number.
Syntax
Sgn(x)

Arguments
• x
 Must be an integer or real number
Returns
-1 if x < 0; 0 if x = 0; 1 if x > 0
Exceptions
If x is not an integer or real number, returns an error value
Example
• Sgn(1.1)
[Returns 1]
• Sgn(0)
[Returns 0]
• Sgn(-0.1)
[Returns -1]
• Sgn('att1')
[Returns 1 if the value of 'att1' is positive, 0 if it equals 0, and -1 if it is negative]

Sin
Return the trigonometric sine of a number.
Syntax
Sin(x)

Arguments
• x
Must be an integer or real number, which represents an angle in radians
Returns
The sine of x
Exceptions
If x is not a number, returns an error value
Example
• Sin(1)
[Returns 0.84147]
• Sin(1.1)
[Returns 0.89121]
• Sin('att1')
[Return the trigonometric sine of the value of 'att1' at trigger time]
Sinh
Return the hyperbolic sine of a number.
Syntax
Sinh(x)

Arguments
• x
Must be an integer or real number
Returns
The hyperbolic sine of x
Exceptions
If x is not a number, returns an error value
Example
• Sinh(1)
[Returns 1.1752]
• Sinh(1.1)
[Returns 1.3356]
• Sinh('att1')
[Return the hyperbolic sine of the value of 'att1' at trigger time]

Split
Split a string into substrings based on a specified delimiter and return an array.
Syntax
Split(s1, delimiter)

Arguments
• s1
Input string in double quotes
• delimiter
Space or character separating the input string such as "|" or "," in double quotes
Returns
Returns an array of substrings obtained by the separation of the input string based on the delimiter
Exceptions
If either of the two arguments (s1 or delimiter) is not a string, the function returns an error
 Example
• Split("Value1|Value2|Value3", "|")
[Returns [Value1, Value2, Value3] ]

Sqr
Return the square root of a number.
Syntax
Sqr(x)

Arguments
• x
Must be an integer or real number equal to or greater than zero
Returns
The square root of x
Exceptions
If x is negative, or is not a number, returns an error value
Example
• Sqr(2)
[Returns 1.4142]
• Sqr(2.1)
[Returns 1.4491]
• Sqr('att1')
[Return square root of the value of 'att1' at trigger time]

StateNo
Translate a digital state into its corresponding enumeration value.
Syntax
StateNo(digstate)

Arguments
• digstate
An enumeration value
Returns
The offset into the Digital State Set corresponding to digstate
Exceptions
If a point is passed as digstate that is not a digital point, returns an error value
 Notes
A digital state may appear more than once in the digital state table. In this case, the value that StateNo returns
may vary. If digstate is the value of a digital point, StateNo returns a code number appropriate for that point.
Example
• StateNo(DigState("No Data"))
[Returns 248]
• StateNo(TagVal('enum_att1', '*-1h'))
[Return the digital state number corresponding to the value of 'enum_att1' an hour ago]

SStDev
Return the time-weighted or event-weighted sample standard deviation for two or more arguments that are a
sample of a larger population.
Syntax
SStDev(x1, x2 [, ... xn])
SStDev(array [, calculationBasis])

Arguments
x1, ... xn
• Arguments and a single array of same value type (integers and real numbers, time expressions, or time
intervals)
• calculationBasis
Optional. The type of calculation to be performed enclosed in double quotes. Choose between
"EventWeighted" or "TimeWeighted." If omitted, the default is event-weighted. If you select
"TimeWeighted," the earliest timestamp of the value marks the start time and the latest timestamp the end
of a time range
Returns
The sample standard deviation of the arguments. Returns a numeric value if the arguments are numbers. For
arguments that are time expressions (time or time period), a number indicating a time period expressed in
seconds is returned
The standard deviation of a sample x1, ... xn is equal to

Where is the sample mean; that is,

Exceptions
Arguments whose run-time values are digital states are ignored. If there are not at least two numeric values,
SStDev returns a zero. Returns an error if the array does not consist of same value type
Notes
• In the rare case where you have the entire population, rather than a sample, you might use the function
PstDev, rather than SStDev
• Unit of Measure (UOM) of the arguments is carried over to the result when at least one argument has a
defined UOM while others don't. The returned value lacks a UOM if arguments have different UOMs
Example
• SStDev(14, 'att1', 14.5, TagVal('att2','14-Dec-16'))
[Return the "sample standard deviation" of these values: 14, the current value of 'att1', 14.5, and the value
for 'att2' at start of day (12:00am) on Dec 14, 2016]
• SStDev('*', 'y', 'Saturday')
[Return the "sample standard deviation" of these timestamps]
• SStDev('*'-'*-1h', 't+8h'-'y+4h', 'y'-'20', '*'-'t')
[Return the "sample standard deviation" of these time periods: from 1 hour ago to now, from 4:00am
yesterday to today at 8am, from 12:00am yesterday to 12:00am on 20th of this month, and from the
beginning of day today (12:00am) till now]
• SStDev(Variable1)
Name Expression Value at Evaluation
Variable1 RecordedValues('att1', '*-10m', [1, 3, 5, 7, 9]
'*')
Variable 2 SStDev(Variable1) 3.1623
[Find the "sample standard deviation" of values in an array named Variable1]
• SStDev(Data)
[Return the event-weighted "sample standard deviation" of values in an array named Data]
• SStDev(Data, "EventWeighted")
[Return the event-weighted "sample standard deviation" of values in an array named Data]
• SStDev(Data, "TimeWeighted")
[Return the time-weighted "sample standard deviation" of values in an array named Data using the
timestamps of the earliest and latest values of the array as the start time and end time respectively]
StDev
Find the time-weighted or event-weighted standard deviation of values for an attribute from a specified time
range.
Syntax
StDev(attname, starttime, endtime [, pctgood, calculationBasis])

Arguments
• attname
attribute with time series data (such as PI point data reference) enclosed in single quotes
• starttime
time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as'-3h') in reference to an absolute endtime
• endtime
time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as '+1h') in reference to an absolute starttime
• pctgood
Optional. Time-weighted or event-weighted minimum time percentage during a specified time range for
which the attribute had good values
• calculationBasis
Optional. A string indicating the type of calculation to be performed enclosed in double quotes. Choose
between "TimeWeighted" or "EventWeighted". If omitted, the default is time-weighted
Returns
The time-weighted or event-weighted standard deviation for attribute values from the specified time range
Exceptions
If the attribute has no good values or the pctgood minimum is not reached for the given time range, an error is
returned
Notes
• Bad values are excluded from StDev calculation
• In order to configure an optional parameter, any previous optional parameter must be specified
Note: If the attribute has very few good values during the time range, this function's result may not be
trustworthy. Use the PctGood function to find out what percentage of the values is good
Example
• StDev('att1', 't', '+1h')
[Return the time-weighted standard deviation of values for 'att1' between 12:00 and 1:00am today]
• StDev('att1', 't', '+1h', 80)
 [Return the time-weighted standard deviation of values for 'att1' between 12:00 and 1:00am today when at
least 80% of the values were good]
• StDev('att1', 't', '+1h', 80, "EventWeighted")
[Return the event-weighted standard deviation of values for 'att1' between 12:00 and 1:00am today when at
least 80% of the values were good]

String
Convert any value to a string.
Syntax
String(x)

Arguments
• x
Any expression that is of normal PI value type
Returns
The string representing the value argument
Exceptions
None
Example
• String("Hello, PI user!")
[Returns "Hello, PI user!"]
• String(12.23)
[Returns "12.23"]
• String('sinusoid')
[Return current value of 'sinusoid' in string]
• String('*')
[Return the current time in string]

TagAvg
Find the time-weighted or event-weighted average of values for an attribute during a specified time range.
Syntax
TagAvg(attname, starttime, endtime [, pctgood, calculationBasis])

Arguments
• attname
attribute with time series data (such as PI point data reference) enclosed in single quotes
• starttime
 time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as '-3h') in reference to an absolute endtime
• endtime
time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as '+1h') in reference to an absolute starttime
• pctgood
Optional. Time-weighted or event-weighted minimum time percentage in a specified time range for which
the attribute had good values
calculationBasis
Optional. A string indicating the type of calculation to be performed enclosed in double quotes. Choose
between "TimeWeighted" or "EventWeighted". If omitted, the default is time-weighted
Returns
The time-weighted or event-weighted average of attribute values during a specified time range
Exceptions
If the point has no good values or the pctgood minimum is not reached for the given time range, returns an error
value
Notes
• Bad values are excluded from TagAvg calculation.
• In order to configure an optional parameter, any previous optional parameter must be specified.
• For more information, see the OSIsoft Knowledge Base article How Time-Weighted and Event-Weighted
Totals and Averages Work.
Note: If the attribute has very few good values during the time range, this function's result may not be
trustworthy. Use the PctGood function to find out what percentage of the values is good
Example
• TagAvg('att1', 't', '+1h')
[Return the time-weighted average of values for 'att1' between 12:00 and 1:00am today]
• TagAvg('att1', 't', '+1h', 80)
[Return the time-weighted average of values for 'att1' between 12:00 and 1:00am today when at least 80%
of the values were good]
• TagAvg('att1', 't', '+1h', 80, "EventWeighted")
[Return the event-weighted average of values for 'att1' between 12:00 and 1:00am today when at least 80%
of the values were good]

TagBad
For an attribute associated with a PI point, test the point for an abnormal state at a specified time. If the point is
an integer or real number, any digital state is considered abnormal. For digital points, the states that are defined
for that point are normal; all others are abnormal.
 Syntax
TagBad(attname [, t1])

Arguments
• attname
An attribute associated with a PI point
• time
Optional: A time expression. If omitted, current time ('*') is used.
Returns
False if the point's state at time is normal, True if it is abnormal.
Exceptions
None
Notes
BadVal can test any value or expression; TagBad can only test a PI point.
Example
• TagBad('att1')
[Returns True if PI point for 'att1' does not exist or its value corresponds to system digital state (No Data, for
example)]
• TagBad('enum_att1', '14-Dec-16')
[Returns True if PI point for 'enum_att1' does not exist or its value corresponds to system digital state (No
Data, for example) at 12:00am on December 14th, 2016]

TagDesc
For an attribute associated with a PI point, retrieve that point's descriptor from the point database.
Syntax
TagDesc(attname)

Arguments
• attname
The name of an attribute with a PI point data reference, enclosed in single quotes
Returns
The point's descriptor
Exceptions
If the PI point does not exist, an error value is returned
Example
• TagDesc('sinusoid')
 [Returns 12 Hour Sine Wave]
• TagDesc('cdt158')
[Returns Atmospheric Tower OH Vapor]

TagEU
For an attribute associated with a PI point, retrieve the point's engineering unit string from the point database.
Syntax
TagEU(attname)

Arguments
• attname
The name of an attribute with a PI point data reference, enclosed in single quotes
Returns
The PI point's engineering units
Exceptions
If the PI point does not exist, an error values is returned
Notes
Returns blank when PI point lacks an engineering unit
Example
• TagEU('cdt158')
[Returns DEG.C]

TagExDesc
For an attribute associated with a PI point, retrieve the point's extended descriptor from the point database.
Syntax
TagExDesc(attname)

Arguments
• attname
An attribute with a PI point data reference, enclosed in single quotes
Returns
The PI point's extended descriptor
Exceptions
If the PI point does not exist, an error values is returned
Notes
Returns blank when PI point lacks extended descriptor
 Example
• TagExDesc('cdt158')
[Returns blank since the point lacks extended descriptor]

TagMax
Find the time-weighted or event-weighted maximum value of an attribute during a specified time range. Time-
weighted values are interpolated at time boundaries when possible and extrapolated otherwise.
Syntax
TagMax(attname, starttime, endtime [, pctgood, calculationBasis])

Arguments
• attname
attribute with time series data (such as PI point data reference) enclosed in single quotes
• starttime
time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as'-3h') in reference to an absolute endtime
• endtime
time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as '+1h') in reference to an absolute starttime
• pctgood
Optional. Time-weighted or event-weighted minimum time percentage over a specified time range for which
the attribute had good values
calculationBasis
Optional. A string indicating the type of calculation to be performed enclosed in double quotes. Choose
between "TimeWeighted" or "EventWeighted". If omitted, the default is time-weighted
Returns
The attribute's time-weighted or event-weighted maximum value during the specified time range. Time-
weighted values are interpolated at time boundaries when possible and extrapolated otherwise
Exceptions
If the attribute has no good values or the pctgood minimum is not reached for the given time range, an error
value is returned
Notes
• Bad values are excluded from TagMax calculation
• In order to configure an optional parameter, any previous optional parameter must be specified
Note: If the attribute has very few good values during the time range, this function's result may not be
trustworthy. Use the PctGood function to find out what percentage of the values is good
 Example
• TagMax('att1', 't', '+1h')
[Return the time-weighted maximum value of 'att1' between 12:00 and 1:00am today]
• TagMax('att1', '14-Dec-16', '15-Dec-16')
[Return the time-weighted maximum value of 'att1' between 12:00am 12/14/2016 and 12:00am
12/15/2016]
• TagMax('att1', 't', '+1h', 80)
[Return the time-weighted maximum value of 'att1' between 12:00 and 1:00am today when at least 80% of
the values were good]
• TagMax('att1', 't', '+1h', 80, "EventWeighted")
[Return the event-weighted maximum value of 'att1' between 12:00 and 1:00am today when at least 80% of
the values were good]

TagMean
Find the average (mean) of values for an attribute during a specified time range. TagAvg with event-weighted
option provides the same result as TagMean. Consider using TagAvg rather than TagMean especially if time-
weighted TagAvg is used in other analyses.
Syntax
TagMean(attname, starttime, endtime [, pctgood])

Arguments
• attname
attribute with time series data (such as PI point data reference) enclosed in single quotes
• starttime
time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as'-3h') in reference to an absolute endtime
• endtime
time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as '+1h') in reference to an absolute starttime
• pctgood
Optional: Minimum percentage of the specified time range that attribute values must be good.
Returns
The attribute's average value over the given time. Notice that the average is not time-weighted. For time-
weighted average, use TagAvg instead
Exceptions
If the attribute has no good values or the pctgood minimum is not reached for the specified time range, an error
value is returned. Unlike some other summary functions, TagMean does not interpolate any value on the
boundary. Thus, if there is no value in the specified interval, an error value is returned
 Notes
Bad values are excluded from TagMean calculation
Note: If the attribute has very few good values during the time range, this function's result may not be
trustworthy. Use the PctGood function to find out what percentage of the values is good
Example
• TagMean('att1', 't', '+1h')
[Return the average (mean) value of 'att1' between 12:00 and 1:00am today]
• TagMean('att1', 't', '+1h', 80)
[Return the average (mean) value of 'att1' between 12:00 and 1:00am today when at least 80% of the values
were good]
• TagMean('att1', '14-Dec-16', '15-Dec-16')
[Return the average (mean) value of 'att1' between 12:00am 12/14/2016 and 12:00am 12/15/2016]

TagMin
Find the time-weighted or event-weighted minimum value of an attribute during a specified time range. Time-
weighted values are interpolated at time boundaries when possible and extrapolated otherwise.
Syntax
TagMin(attname, starttime, endtime [, pctgood, calculationBasis])

Arguments
• attname
attribute with time series data (such as PI point data reference) enclosed in single quotes
• starttime
time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as'-3h') in reference to an absolute endtime
• endtime
time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as '+1h') in reference to an absolute starttime
• pctgood
Optional. Time-weighted or event-weighted minimum time percentage over a specified time range for which
the attribute had good values
calculationBasis
Optional. A string indicating the type of calculation to be performed enclosed in double quotes. Choose
between "TimeWeighted" or "EventWeighted". If omitted, the default is time-weighted
Returns
The time-weighted or event-weighted minimum value for the attribute during the specified time range. Time-
weighted values are interpolated at time boundaries when possible and extrapolated otherwise
 Exceptions
If no good attribute values exist or if the pctgood minimum is not reached for the specified time range, an error
value is returned
Notes
• Bad values are excluded from TagMin calculation
• In order to configure an optional parameter, any previous optional parameter must be specified
Note: If the attribute has very few good values during the time range, this function's result may not be
trustworthy. Use the PctGood function to find out what percentage of the values is good
Example
• TagMin('att1', 't', '+1h')
[Return the time-weighted minimum value of 'att1' between 12:00 and 1:00am today]
• TagMin('att1', '14-Dec-16', '15-Dec-16')
[Return the time-weighted minimum value of 'att1' between 12:00am 12/14/2016 and 12:00am
12/15/2016]
• TagMin('att1', 't', '+1h', 80)
[Return the time-weighted minimum value of 'att1' between 12:00 and 1:00am today when at least 80% of
the values were good. Return error when minimum pctgood is not reached]
• TagMin('att1', 't', '+1h', 80, "EventWeighted")
[Return the event-weighted minimum value of 'att1' between 12:00 and 1:00am today when at least 80% of
the values were good. Return error when minimum pctgood is not reached.]

TagName
For an attribute associated with a PI point, get a point's name from the point database.
Syntax
TagName(attname)

Arguments
• attname
The name of an attribute with a PI point data reference, enclosed in single quotes
Returns
The name of the PI point associated with attname
Exceptions
If the PI point does not exist, an error value is returned
Example
• TagName('sinusoid')
[Returns SINUSOID]
 • TagName('cdt158')
[Returns CDT158]

TagNum
For an attribute associated with a PI point, get a point's number from the point database.
Syntax
TagNum(s1)

Arguments
• string
The name of an attribute with a PI point data reference, enclosed in double quotes
Returns
The point's number
Exceptions
If the point does not exist, returns an error value
Example
• TagNum("sinusoid")
[Returns 1]
• TagNum("cdt158")
[Returns 3]

TagSource
For an attribute associated with a PI point, get a point's point source string from the point database.
Syntax
TagSource(attname)

Arguments
• attname
The name of an attribute with a PI point data reference, enclosed in single quotes
Returns
The point's point source string
Exceptions
If the point does not exist, an error value is returned
Example
• TagSource('sinusoid')
[Returns R]
 • TagSource('cdt158')
[Returns R]

TagSpan
For an attribute associated with a PI point, get a point's span from the point database.
Syntax
TagSpan(attname)

Arguments
• attname
The name of an attribute with a PI point data reference, enclosed in single quotes
Returns
The point's span. If the point's type is digital, returns an integer whose value is the number of digital state
defined for the point.
Example
• TagSpan('sinusoid')
[Returns 100]
• TagSpan('cdt158')
[Returns 200]

TagTot
Find the time-weighted (time integral) or event-weighted totalized value of an attribute's values over a specified
time range, optionally converting the totalized value from its current unit of measure (UOM) to a specified UOM
in same class. Time-weighted values are interpolated at time boundaries when possible and extrapolated
otherwise.
Syntax
TagTot(attname, starttime, endtime [, toUnit, pctgood, calculationBasis])

Arguments
• attname
attribute with time series data (such as PI point data reference) enclosed in single quotes
• starttime
time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as '-3h') in reference to an absolute endtime
• endtime
time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as '+1h') in reference to an absolute starttime
• toUnit
 Optional. The UOM to which the totalized value is converted. The specified UOM must be compatible with
the UOM of the input attribute. Specifying an empty string ("") produces the same result as if no UOM were
specified.
pctgood
Optional. Time-weighted or event-weighted minimum time percentage over a specified time range for which
the attribute had good values
calculationBasis
Optional. A string indicating the type of calculation to be performed enclosed in double quotes. Choose
between "TimeWeighted" or "EventWeighted". If omitted, the default is time-weighted.
Returns
The time-weighted (time integral) or event-weighted totalized value of an attribute's values over a specified time
range. Time-weighted values are interpolated at time boundaries when possible and extrapolated otherwise.
Exceptions
• If the attribute has no good values or the pctgood minimum is not reached for the given time range, an error
value is returned.
• If the specified UOM for conversion is incompatible with the UOM of the input attribute, an error value is
returned. For example, if the UOM of the input attribute is gallons/minute, and the UOM for conversion is
"m" (meters), then an error is returned.
Notes
• In case toUnit is not specified, the system chooses a scale factor such that the integral is correct only if the
flow is expressed in units per day. If the flow is expressed in units per hour, or per some other time unit, you
must multiply this result by a conversion factor. The conversion factor equals the number of actual flow time
units in a day.
• For instance, if you totalize values measured in gallons per minute, multiply the result of TagTot by 1440 to
get the answer in gallons. This conversion factor is not related to the time period you are totalizing over; it is
strictly a function of the attribute's engineering units.
• Bad values are excluded from TagTot calculation.
• When the percentage of good data is less than 100%, TagTot determines the total based on good data and
divides the fraction of good data in the interval. The time period during which the data is bad is ignored
when calculating the total.
• In order to configure an optional parameter, any previous optional parameter must be specified.
Note: If the attribute has very few good values during the time range, this function's result may not be
trustworthy. Use the PctGood function to find out what percentage of the value is good.
Example
• TagTot('att1', 't', '+1h')
[Return the time-weighted totalized value of 'att1' between 12:00 and 1:00am today.]
• TagTot('att1', 't', '+1h', "m")
[Return the time-weighted totalized value of 'att1' calculated based on its unit between 12:00 and 1:00am
today and convert to meters.]
 • TagTot('att1', 't', '+1h', "", 80)
[Return the time-weighted totalized value of 'att1' calculated based on its unit between 12:00 and 1:00am
today when at least 80% of the values were good. Return error when minimum pctgood is not reached.]
• TagTot('att1', 't', '+1h', "", 80, "TimeWeighted")
[Return the time-weighted totalized value of 'att1' calculated based on its unit between 12:00 and 1:00am
today when at least 80% of the values were good. Return error when minimum pctgood is not reached.]
• TagTot('att1', 't', '+1h', "m", 80)
[Return the time-weighted totalized value of 'att1' calculated based on its unit between 12:00 and 1:00am
today and convert to meters when at least 80% of the values were good. Return error when minimum
pctgood is not reached.]
• TagTot('att1', 't', '+1h', "m", 80, "EventWeighted")
[Return the event-weighted totalized value of 'att1' calculated based on its unit between 12:00 and 1:00am
today and convert to meters when at least 80% of the values were good. Return error when minimum
pctgood is not reached.]

TagType
For an attribute associated with a PI point, get a point's point type from the point database.
Syntax
TagType(attname)

Arguments
attname
• The name of an attribute with a PI point data reference, enclosed in single quotes
Returns
Point type
Exceptions
If the point does not exist, returns an error
Example
• TagType('sinusoid')
[Returns Float32]
• TagType('cdm158')
[Returns Digital]

TagTypVal
For an attribute associated with a PI point, get a point's typical value from the point database.
Syntax
TagTypVal(attname)
 Arguments
• attname
The name of an attribute with a PI point data reference, enclosed in single quotes
Returns
The point's typical value. If the point is an integer or real number, a number is returned; if the point's value type
is digital, this indicates a digital state
Exceptions
If the point does not exist, returns an error
Example
• TagTypVal('sinusoid')
[Returns 50]
• TagTypVal('cdm158')
[Returns 3, a digital state]

TagVal
Return the value of an attribute at a specified time.
Syntax
TagVal(attname [, t1])

Arguments
• attname
The name of an attribute with a PI point data reference, enclosed in single quotation marks
• t1
Optional: A time expression. If you omit this argument, '*' is used
Returns
The value of an attribute at a specified time. This value is interpolated unless the associated PI Point has the Step
property set to True or the value type of the attribute cannot be interpolated (for example, if it is a string)
Exceptions
If the associated point does not exist or has no value at the specified time, an error is returned
Example
• TagVal('att1')
[Return the value of 'att1' at current time]
• TagVal('att1', 't+8h')
[Return the value of 'att1' at 8am today]
• TagVal('enum_att1')
 [Return the value of 'enum_att1', an attribute from an enumeration set at current time]

TagZero
For an attribute with a PI point data reference, get a PI point's "zero" value from the point database.
Syntax
TagZero(attname)

Arguments
• attname
The name of an attribute with a PI point data reference, enclosed in single quotes
Returns
The point's zero value. If the point type is integer or real number, this is a number; if the point's type is digital,
this is a digital state (character string)
Exceptions
If the point does not exist, returns an error
Example
• TagZero('sinusoid')
[Returns 0]
• TagZero('cdt158')
[Returns 50]

Tan
Return the trigonometric tangent of a number.
Syntax
Tan(x)

Arguments
• x
Must be an integer or real number, which represents an angle in radians
Returns
The tangent of x.
Exceptions
If x is not a number, returns an error
Example
• Tan(1)
[Returns 1.5574]
 • Tan(1.1)
[Returns 1.9648]
• Tan('att1')
[Return the trigonometric tangent of the value of 'att1' at trigger time]

Tanh
Return the hyperbolic tangent of a number.
Syntax
Tanh(x)

Arguments
• x
Must be an integer or real number
Returns
The hyperbolic tangent of x
Exceptions
If x is not a number, returns an error value
Example
• Tanh(1)
[Returns 0.76159]
• Tanh(1.1)
[Returns 0.8005]
• Tanh('att1')
[Return the hyperbolic tangent of the value of 'att1' at trigger time]

Text
Concatenate strings representing argument values.
Syntax
Text(x1 [, x2, … xn])

Arguments
• x1 … xn
Any expression of normal PI value type
Returns
A string that is the concatenation of strings representing the argument values.
 Example
• Text(Round('sinusoid', 1), " is the current value of 'sinusoid' at ", '*')
[Returns rounded current value of 'sinusoid' at current time]

THEN
Operator that returns the first of two specified values when the conditional expression in IF-THEN-ELSE
statement is True.
Syntax
IF(expression) THEN (x) ELSE (y)

Arguments
• expression
Any expression that evaluates to true or false
• x,y
An expression that evaluates to an output value
Returns
x when the conditional expression is true and y when the expression is false
Exceptions
None
Example
• IF ('att1' > 50) THEN ('att2') ELSE ('att3')
[If the value of 'att1' is greater than 50, then return the value of 'att2'; otherwise return the value of 'att3']

TimeEq
Find the total time, within a range, when an attribute value is equal to a specified value. Time returned is in
seconds.
Syntax
TimeEq(attname, starttime, endtime, x)

Arguments
• attname
The name of an attribute with a PI point data reference, enclosed in single quotation marks
• starttime
time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as '-3h') in reference to an absolute endtime
• endtime
 time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as '+1h') in reference to an absolute starttime
• x
The reference value of the search; must be an enumeration set (string), integer or real number
Returns
The total time (in seconds), within a range, when an attribute value is equal to a given value
Notes
Bad values are excluded from TimeEq calculation
Example
• TimeEq('att1', 't', '+1h', 80)
[Find the total time between 12:00 and 1:00am today when 'att1' was equal to 80. Return the result in
seconds]
• TimeEq('att1', '-1h', '*', TagVal('att1', 't+8h'))
[Find the total time in the past hour when the value of 'att1' was equal to the value at 8am today. Return the
result in seconds]
• TimeEq('Temperature Status', '-1h', '*', "Normal")
Expression Output Attribute (attribute mapped to a PI point)

If 'Temp' > 500 THEN "HiLimit" ELSE "Normal" Temperature Status

TimeEq('Temperature Status', '-1h', '*', "Normal")
[Find the total time in the past hour when the value of the attribute 'Temperature Status' was equal to
"Normal". Return the result in seconds]
• TimeEq('enum_att1', '*-1d', '*', DigState("Normal", 'enum_att1'))
[Find the total time in the past 24 hours when the value of 'enum_att1' was equal to "Normal". Return the
result in seconds]

TimeGE
Find the total time, within a range, when an attribute value is greater than or equal to a specified value. Time
returned is in seconds.
Syntax
TimeGE(attname, starttime, endtime, x)

Arguments
• attname
The name of an attribute with a PI point data reference, enclosed in single quotation marks
• starttime
 time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as '-3h') in reference to an absolute endtime
• endtime
time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as '+1h') in reference to an absolute starttime
• x
The reference value of the search; must be an enumeration set (string), integer or real number
Returns
The total time (in seconds), within a range, when an attribute value is greater than or equal to a given value
Exceptions
None
Notes
TimeGE interpolates between events, if necessary, to find the times when the attribute value crossed the given
value
Bad values are excluded from TimeGE calculation
Example
• TimeGE('att1', 't', '+1h', 80)
[Find the total time between 12:00 and 1:00am today when 'att1' was greater than or equal to 80]
• TimeGE('att1', '-1h', '*', TagVal('att1', 't+8h'))
[Find the total time in the past hour when the value of 'att1' was greater than or equal to the value at 8am
today. Result is in seconds]
• TimeGE('enum_att1', '*-1d', '*', DigState("Normal", 'enum_att1'))

TimeGT
Find the total time, within a range, when an attribute value is greater than a specified value. Time returned is in
seconds.
Syntax
TimeGT(attname, starttime, endtime, x)

Arguments
• attname
The name of an attribute with a PI point data reference, enclosed in single quotation marks
• starttime
time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as '-3h') in reference to an absolute endtime
• endtime
 time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as '+1h') in reference to an absolute starttime
• x
The reference value of the search; must be an enumeration set (string), integer or real number
Returns
The total time (in seconds), within a range, when an attribute value is greater than a given value
Exceptions
None
Notes
TimeGT interpolates between events, if necessary, to find the times when the attribute value crossed the
specified value
Bad values are excluded from TimeGT calculation
Example
• TimeGT('att1', 't', '+1h', 80)
[Find the total time between 12:00 and 1:00am today when 'att1' was greater than 80]
• TimeGT('att1', '-1h', '*', TagVal('att1', 't+8h'))
[Find the total time in the past hour when the value of 'att1' was greater than the value at 8am today. Result
is in seconds]
• TimeGT('enum_att1', '*-1d', '*', DigState("Normal", 'enum_att1'))

TimeLE
Find the total time, within a range, when an attribute value is less than or equal to a given value. Time returned
is in seconds.
Syntax
TimeLE(attname, starttime, endtime, x)

Arguments
• attname
The name of an attribute with a PI point data reference, enclosed in single quotation marks
• starttime
time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as '-3h') in reference to an absolute endtime
• endtime
time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as '+1h') in reference to an absolute starttime
• x
 The reference value of the search; must be an enumeration set (string), integer or real number
Returns
The total time (in seconds), within a range, when an attribute value is less than or equal to a given value
Exceptions
None
Notes
TimeLE interpolates between archive events, if necessary, to find the times when the point crossed the given
value
Bad values are excluded from TimeLE calculation
Examples
• TimeLE('att1', 't', '+1h', 80)
[Find the total time between 12:00 and 1:00am today when 'att1' was less than or equal to 80]
• TimeLE('att1', '-1h', '*', TagVal('att1', 't+8h'))
[Find the total time in the past hour when the value of 'att1' was less than or equal its value at 8am today.
Result is in seconds]
• TimeLE('enum_att1', '*-1d', '*', DigState("Normal", 'enum_att1'))

TimeLT
Find the total time, within a range, when an attribute value is less than a specified value. Time returned is in
seconds.
Syntax
TimeLT(attname, starttime, endtime, x)

Arguments
• attname
The name of an attribute with a PI point data reference, enclosed in single quotation marks
• starttime
time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as '-3h') in reference to an absolute endtime
• endtime
time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as '+1h') in reference to an absolute starttime
• x
The reference value of the search; must be an enumeration set (string), integer or real number
Returns
The total time (in seconds), within a range, when an attribute value is less than a given value
 Exceptions
None
Notes
TimeLT interpolates between Archive events, if necessary, to find the times when the attribute value crossed the
specified value
Bad values are excluded from TimeLT calculation
Example
• TimeLT('att1', 't', '+1h', 80)
[Find the total time between 12:00 and 1:00am today when 'att1' was less than 80]
• TimeLT('att1', '-1h', '*', TagVal('att1', 't+8h'))
[Find the total time in the past hour when the value of 'att1' was less than its value at 8am today. Result is in
seconds]
• TimeLT('enum_att1', '*-1d', '*', DigState("Normal", 'enum_att1'))

TimeNE
Find the total time, within a range, when an attribute value is not equal to a specified value. Time returned is in
seconds.
Syntax
TimeNE(attname, starttime, endtime, x)

Arguments
• attname
The name of an attribute with a PI point data reference, enclosed in single quotation marks
• starttime
time expression representing the beginning of a time range enclosed in single quotes; can be a relative time
(such as '-3h') in reference to an absolute endtime
• endtime
time expression representing the end of a time range enclosed in single quotes; can be a relative time (such
as '+1h') in reference to an absolute starttime
• x
The reference value of the search; must be an enumeration set (string), integer or real number
Returns
The total time (in seconds), within a range, when an attribute value is not equal to a specified value
Exceptions
None
 Notes
Bad values are excluded from TimeNE calculation
Example
• TimeNE('att1', 't', '+1h', 80)
[Find the total time between 12:00 and 1:00am today when 'att1' was not equal to 80]
• TimeNE('att1', '-1h', '*', TagVal('att1', 't+8h'))
[Find the total time in the past hour when the value of 'att1' was not equal to the value at 8am today. Result
is in seconds]
• TimeNE('enum_att1', '*-1d', '*', DigState("Normal", 'enum_att1'))

TimeStamp
Return the time stamp for a single time-stamped value or an array of time-stamped values.
Syntax
TimeStamp(x)

Arguments
• x
A time-stamped value or an array of time-stamped values
Returns
The timestamp of the specified time-stamped value
Exceptions
If the value of x is No Data, then Calc Failed is returned
Example
• TimeStamp(PrevVal('sinusoid', '*'))
[Return the time stamp of the last recorded value before the current one for 'sinusoid']
• TimeStamp(Variable1)
Name Expression Value at Evaluation

Variable1 RecordedValues('att1', [1, 3, 5]

'*-10m', '*')
Variable 2 TimeStamp(Variable1) [1/3/2018 8:15:00 AM, 1/3/ 8:16:17 AM,
1/3/2018 8:20:00 AM]
[Assuming current time is 8:23 AM on 1/3/2018, returns the timestamps of 3 recorded values in the past 10
minutes]
Total
Return the time-weighted or event-weighted sum of two or more values.
Syntax
Total(x1, x2 [, ... xn])
Total(array [, calculationBasis])

Arguments
• x1, ... xn
Numbers, time intervals or a single array of numbers or time intervals
• calculationBasis
Optional. The type of calculation to be performed enclosed in double quotes. Choose between
"EventWeighted" or "TimeWeighted." If omitted, the default is event-weighted. If you select
"TimeWeighted," the earliest timestamp of the value marks the start time and the latest timestamp the end
of a time range
Returns
The total of the arguments. The result has the same data type as the arguments
Exceptions
Arguments whose run-time values are digital states are not included in the total. If all values are digital states,
Total returns an error value. Returns an error if the array does not consist of same value type
Notes
• Unit of Measure (UOM) of the arguments is carried over to the result when at least one argument has a
defined UOM while others don't. The returned value lacks a UOM if arguments have different UOMs
Example
• Total('att1', 'att2', TagVal('att1', 'y+2h'), 40)
[Return the sum of following values: values of 'att1' and 'att2' at current time, the value of 'att1' at 2am
yesterday and 40]
• Total('t'-'y', '+1h')
[Returns 1.01:00:00]
• Total(Variable1)
Name Expression Value at Evaluation

Variable1 RecordedValues('att1', '*-10m', [1, 3, 5, 7, 9]

'*')
Variable 2 Total(Variable1) 25
[Return the sum of values in an array named Variable1]
• Total(Data)
 [Return the event-weighted sum of values from an array named Data]
• Total(Data, "EventWeighted")
[Return the event-weighted sum of values from an array named Data]
• Total(Data, "TimeWeighted")
[Return the time-weighted sum of values from an array named Data using the timestamps of the earliest and
latest values of the array as the start time and end time respectively]

Trim
Trim blanks on both sides of a string.
Syntax
Trim(s1)

Arguments
• s1
string
Returns
The source string with leading and trailing blanks removed.
Exceptions
If s1 is not a string, an error value is returned.
Example
• Trim(" String ")
[Returns "String"]
• Trim(" String is a string attribute. ")
[Returns "String is a string attribute."]

Year
Extract the year from a time expression.
Syntax
Year(t1)

Arguments
• t1
A time expression, enclosed in single quotes
Returns
The year of time, in the range 1970-present
 Exceptions
None
Example
• Year('*')
[Return what year it is now]
• Year(FindGT('att1', '1/1/1970', '*', 50))
[Return what year it was when the value of 'att1' was first greater than 50 since 1/1/1970]

Trunc
Truncate a number or time to the next lower unit.
Syntax
Trunc(x [, unit])

Arguments
• x
An integer or real number, time expression, or time period.
• unit
Optional. The size of the unit to truncate to; x will be truncated to a multiple of unit. If x is a number, unit
must be a number. If x is a time expression or time period, unit must be a time period. If unit is omitted,
Trunc truncates to the next lower integer (for a number) or second (for a time period).
Returns
The largest multiple of unit that is less than x. For a negative x, it returns the lowest multiple of unit larger than x.
The return is the same data type as x.
Exceptions
If x is a string, or if unit is of the wrong data type, an error is returned.
Notes
If x is a time, and unit is omitted, this routine has no effect, as times are only accurate to one second.
When |x| < |unit|, 0 is returned.
Example
• Trunc(12.999)
[Returns 12, truncated to the next lower integer]
• Trunc(28.75, 10)
[Returns 20, truncated to next lower multiple of 10]
• Trunc('14-Dec-16 11:47', '+1h')
[Returns 12/14/2016 11:00:00 AM, truncated to next lower hour]
 • Trunc('18:47'-'15:00','+1h')
[Returns 03:00:00, truncated period to next lower hour]
Note: Truncating to the next lower day results in a timestamp of the next lower day in UTC time, not local
time.

UCase
Convert a string to an uppercase string.
Syntax
UCase(s1)

Arguments
• s1
String in double quotes
Returns
s1 in uppercase
Exceptions
If the argument is not a string, returns an error value.
Example
• UCase("String")
[Returns "STRING"]

Weekday
Extract the day of the week from a given time expression.
Syntax
Weekday(t1)

Arguments
• t1
A time expression, enclosed in single quotes
Returns
The day of the week, in the range 1-7, where 1 represents a Sunday
Exceptions
None
Example
• Weekday('*')
[Return what day of the week today is]
 • Weekday(FindEq('att1', '-7d', '*', 50))
[Return what day of the week it was when the value of 'att1' was 50 for the first time in the past 7 days]

Yearday
Extract the day of the year from a time expression. The day of the year (also known as a Julian day) is an integer
ranging from 1 to 366, where 1 represents January 1.
Syntax
Yearday(t1)

Arguments
• t1
A time expression, enclosed in single quotes
Returns
The day of the year of time, in the range 1-366, where 1 represents January 1
Exceptions
None
Example
• Yearday('*')
[Return what day of the year today is, where 1 represents January 1]
• Yearday('y')
[Return what day of the year yesterday was, where 1 represents January 1]

Steam functions for analysis expressions

You can include steam functions in analysis expressions to calculate the thermodynamic properties of steam.
These functions are based on the 1997 IAPWS Industrial Formulation. The implementation is based on the
combination of officially published forward and backward equations for all applicable regions.
Note: Avoid confusing these steam functions with a similar set of steam functions used for PI Performance
Equations in tag-based analytics. For more information on steam functions in asset and tag-based analytics, see
Steam functions in asset and tag-based analytics.
The table below lists supported functions and descriptions. Ranges and units of measure for steam function
properties are detailed in Ranges for steam function inputs. Reference states that apply to steam are listed in
Steam property reference states.
Steam function descriptions

Function Description

Steam_TsatP Saturation temperature as a function of pressure.

Steam_HsatP Saturation vapor specific enthalpy as a function of pressure.
Function Description

Steam_SsatP Saturation vapor specific entropy as a function of pressure.

Steam_VsatP Saturation vapor specific volume as a function of pressure.
Steam_PsatT Saturation pressure as a function of temperature.
Steam_HsatT Saturation vapor specific enthalpy as a function of temperature.
Steam_SsatT Saturation vapor specific entropy as a function of temperature.
Steam_VsatT Saturation vapor specific volume as a function of temperature.
Steam_VPT Vapor specific volume as a function of pressure and temperature.
Steam_VPTL Liquid specific volume as a function of pressure and temperature. (For
water.)
Steam_VPH Vapor specific volume as a function of pressure and enthalpy.
Steam_VPS Vapor specific volume as a function of pressure and entropy.
Steam_HPT Vapor specific enthalpy as a function of pressure and temperature.
Steam_HPTL Liquid specific enthalpy as a function of pressure and temperature. (For
water.)
Steam_HPS Vapor specific enthalpy as a function of pressure and entropy.
Steam_SPT Vapor specific entropy as a function of pressure and temperature.
Steam_SPTL Liquid specific entropy as a function of pressure and temperature. (For
water.)
Steam_SPH Vapor specific entropy as a function of pressure and enthalpy.
Steam_TPH Temperature as a function of enthalpy and pressure.
Steam_TPS Temperature as a function of entropy and pressure.
Steam_XPH Steam quality (vapor fraction) as a function of pressure and enthalpy. (For
wet steam.)
Steam_XPS Steam quality (vapor fraction) as a function of entropy and pressure. (For
wet steam.)
Steam_VPX Steam specific volume as a function of pressure and steam quality. (For wet
steam.)
Steam_HPX Specific enthalpy as a function of pressure and steam quality. (For wet
steam.)
Steam_SPX Steam specific entropy as a function of pressure and steam quality. (For wet
steam.)
Steam functions in asset and tag-based analytics
Asset and tag-based analytics tools both include steam functions that calculate thermodynamic properties of
steam and water. Both sets of tools provide a complete set of steam functions but are based on different
standards and have different implementations.
• Steam functions in asset analytics
Steam functions in asset analytics are based on the 1997 IAPWS Industrial Formulation. The
implementation is based on the combination of officially published forward and backward equations
for all applicable regions.
Note: The steam function names in asset analytics begin with "Steam_".
• Steam functions in tag-based analytics
Steam functions in tag-based analytics refer to the PI PE Steam Functions Module (PI Steam),
which is an extension to the PI Performance Equations Scheduler. These functions are based on
the ASME Steam Tables, 6th Ed., and are also available in a COM library,
PISteamTableFunctions.dll, which is distributed with our other products.
Note: Tag-based steam functions support both English and SI units; the function names begin with "StmSI_"
or "StmEng_" for SI units and English units respectively.

Ranges for steam function inputs

The table below shows ranges and default units of measure for each of the five properties involved in steam
function calculations.
The default units of measure are SI units. For information about using steam functions with other units of
measure, see Unit of measure conversion for steam functions.
Pressure affects the state of steam. Several things to keep in mind for functions with pressure as an input are
described in Considerations for steam functions that have pressure as an input.
Range of inputs for steam function properties

Function Temp (°C) Pressure (kPa) Enthalpy(J/g) Entropy(J/(g K)) Quality

Steam_TsatP 0.611212678 to 22064

Steam_HsatP 0.611212678 to 22064
Steam_SsatP 0.611212678 to 22064
Steam_VsatP 0.611212678 to 22064
Steam_PsatT 0.0 to 373.946
Steam_HsatT 0.0 to 373.946
Steam_SsatT 0.0 to 373.946
Steam_VsatT 0.0 to 373.946
Steam_VPT 0.0 to 800 0.611212678 to
100000
Function Temp (°C) Pressure (kPa) Enthalpy(J/g) Entropy(J/(g K)) Quality

Steam_VPT (high 800 to 2000 0.611212678 to 50000

temperature and
pressure)

Steam_VPTL 0.0 to 800 0.611212678 to

100000
Steam_VPH 0.611212678 to -0.04159 to
100000 4160.7
Steam_VPS 0.611212678 to -0.000155 to 11.921
100000
Steam_HPT 0.0 to 800 0.611212678 to
100000
Steam_HPT (high 800 to 2000 0.611212678 to 50000
temperature and
pressure)

Steam_HPTL 0.0 to 800 0.611212678 to

100000
Steam_HPS 0.611212678 to -0.000155 to 11.921
100000
Steam_SPT 0.0 to 800 0.611212678 to
100000
Steam_SPT (high 800 to 2000 0.611212678 to 50000
temperature and
pressure)

Steam_SPTL 0.0 to 800 0.611212678 to

100000
Steam_SPH 0.611212678 to -0.04159 to
100000 4160.7
Steam_TPH 0.611212678 to -0.04159 to
100000 4160.7
Steam_TPS 0.611212678 to -0.000155 to 11.921
100000
Steam_XPH 0.611212678 to 22064 -0.04159 to
4160.7
Steam_XPS 0.611212678 to 22064 -0.000155 to 11.921
Steam_VPX 0.611212678 to 22064 0.0 to 1.0
Steam_HPX 0.611212678 to 22064 0.0 to 1.0
 Function Temp (°C) Pressure (kPa) Enthalpy(J/g) Entropy(J/(g K)) Quality

Steam_SPX 0.611212678 to 22064 0.0 to 1.0

Considerations for steam functions that have pressure as an input

Because pressure affects the state of steam, be aware of these considerations for functions that have pressure as
an input.
Functions with pressure and temperature as inputs
Steam_HPT, Steam_SPT and Steam_VPT can be used for compressed water, superheated or saturated dry
steam. For input temperature and pressure on the saturated curve, the calculated entropy, enthalpy or volume is
a property of saturated vapor. These three functions can also accept high-range input temperatures (800 to 2000
°C) with pressures from 0.611212678 to 50000 kPa.
Steam_HPTL, Steam_SPTL and Steam_VPTL are used only for compressed water.
Functions with pressure and enthalpy or entropy as inputs
Steam_VPH, Steam_VPS, Steam_HPS, Steam_SPH, Steam_TPH and Steam_TPS can be used for compressed
water, superheated or wet steam. For these functions, the range for enthalpy (H) is -0.04159 to 4160.7 J/g and
for entropy (S) is -0.000155 to 11.921 J/(g K).
For Steam_XPH and Steam_XPS, input enthalpy or entropy greater than saturated vapor properties or less than
saturated liquid properties returns an error.

Unit of measure conversion for steam functions

The default units of measure (UOM) for the steam functions are SI units. Any inputs to the steam functions
defined in English units are automatically converted to the corresponding SI units. Similarly, if a steam function is
configured with an output attribute, its output is automatically converted to the UOM configured for that
attribute.
Note: Automatic conversion requires that all UOM have been defined properly in the UOM database. If the
definition of conversion from one unit to another of the same type is missing from the UOM database,
conversion will fail.
In the expression editor, when you evaluate a steam function expression, results are displayed in the default SI
units. To display the results in other UOM, you can use the Convert function.
The following example expressions use numeric values, variables, and attributes to show how steam functions
handle UOM for input and output quantities.
Numeric input values
Numeric input values are recognized as quantities in the default UOM. In the following example for Steam_VPT,
the numeric inputs are recognized as 300 kPa and 200 °C, and the output value is in cm3/g, the default UOM for
specific volume.
Name Expression Value Output Attribute

Variable1 Steam_VPT(300, 200) 716.44 cm3/g Click to map

 Input and output attributes
In the following expression, Steam_VsatT takes as its only input the attribute 'TempSat', whose current value is
300 °F. The temperature is automatically converted to °C to evaluate the expression, and the result is displayed in
the default SI UOM for Steam_VsatT.
Name Expression Value Output Attribute

Variable1 Steam_VsatT('TempSat') 403.7 cm3/g OutputVolume

The result is also mapped to the 'OutputVolume' output attribute. This attribute is configured in English UOM
(ft3/lb), so the result is automatically converted to that UOM. (On the Attributes tab in PI System Explorer,
'OutputVolume' would be listed with a value of 6.466627 ft3/lb.)
Variables and the Convert function
This example uses variables and the Convert function to specify quantities in English UOM as steam function
inputs.
1. In the P and T rows of the expression below, Convert assigns numeric values to English UOM for pressure
and temperature.
2. In the B row, the variables P and T are automatically converted to SI units for the Steam_VPT calculation; the
result is displayed in default SI UOM. The result is also mapped to the output attribute 'OutputVolume'. That
attribute is configured in English UOM (ft3/lb), so the result is automatically converted to that UOM.
3. In the last row, Convert is used to convert the result (B) to English UOM and display it in the expression.
Name Expression Value Output Attribute

P Convert(2000, "psia") 2000 psia Click to map

T Convert(800, "°F") 800 °F Click to map
B Steam_VPT(P, T) 19.206 cm3/g OutputVolume
Volume Convert(B, "ft3/lb") 0.30762 ft3/lb DisplayedVolume

Steam property reference states

The American Society of Mechanical Engineers (ASME) establishes the following reference states:
• triple point
Triple point of water is at 273.16 K or 0.01 °C or 32.018 °F.
• Celsius scale
The Celsius temperature is exactly Tk - 273.15.
• critical point
Critical point of steam is at 647.096 K and 22,064 kPa, or 705.103 °F and 3200.1 psia.
• reference state
The specific internal energy and specific entropy of the liquid phase were fixed at zero at the triple
point of water.
Steam functions reference (asset analytics)
Steam functions available for use in expression analyses are listed alphabetically.

Steam_HPS
Calculate the vapor specific enthalpy as a function of pressure (P in kPa) and entropy (S in J/(g K)). Use for both
superheated and wet steam as well as compressed water. By default, input arguments and returned values are in
SI units. You can change the units of measure, for example, by using the Convert function.
Syntax
Steam_HPS(P, S)

Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 100000 kPa.
• S
Specific entropy of the steam. S can range from -0.000155 to 11.921J/(g K).
Returns
Computed vapor specific enthalpy in J/g.
Example
• Steam_HPS(2500, 7.5956)
[Returns 3684.9 J/g]

Steam_HPT
Calculate the vapor specific enthalpy as a function of pressure (P in kPa) and temperature (T in °C). Use for an
entire range from compressed water to superheated steam. By default, input arguments and returned values are
in SI units. You can change the units of measure, for example, by using the Convert function.
Syntax
Steam_HPT(P, T)

Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 100000 kPa.
• T
Temperature of the steam. T can range from 0.0 to 800 °C.
Returns
Computed vapor specific enthalpy in J/g.
Example
• Steam_HPT(40000, 600)
 [Returns 3350.4 J/g]

Steam_HPTL
Calculate the liquid specific enthalpy as a function of pressure (P in kPa) and temperature (T in °C). Only use for
compressed water. For any T greater than the saturation temperature for P, the function returns an out-of-range
error. The function accepts any T in the temperature range as long as P is greater than the critical pressure. By
default, input arguments and returned values are in SI units. You can change the units of measure, for example,
by using the Convert function.
Syntax
Steam_HPTL(P, T)

Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 100000 kPa.
• T
Temperature of the steam. T can range from 0.0 to 800 °C.
Returns
Computed liquid specific enthalpy in J/g.
Example
• Steam_HPTL(40000, 100)
[Returns 449.27 J/g]

Steam_HPX
Calculate the specific enthalpy as a function of pressure (P in kPa) and quality (vapor fraction). Use only for wet
steam. By default, input arguments and returned values are in SI units. You can change the units of measure, for
example, by using the Convert function.
Syntax
Steam_HPX(P, X)

Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 22064 kPa.
• X
Steam quality (vapor fraction). X can range from 0.0 to 1.0.
Returns
Computed specific enthalpy in J/g.
Example
• Steam_HPX(10000, 0.9)
 [Returns 2593.7 J/g]

Steam_HsatP
Calculate the saturated vapor specific enthalpy as a function of pressure (P in kPa). By default, input arguments
and returned values are in SI units. You can change the units of measure, for example, by using the Convert
function.
Syntax
Steam_HsatP(P)

Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 22064 kPa.
Returns
Computed specific enthalpy for saturated vapor in J/g.
Example
• Steam_HsatP(10000)
[Returns 2725.5 J/g]

Steam_HsatT
Calculate the saturated vapor specific enthalpy as a function of temperature (T in °C). By default, input
arguments and returned values are in SI units. You can change the units of measure, for example, by using the
Convert function.

Syntax
Steam_HsatT(T)

Arguments
• T
Temperature of the steam. T can range from 0.0 to 373.946 °C.
Returns
Computed saturated vapor specific enthalpy in J/g.
Example
• Steam_HsatT(250)
[Returns 2801 J/g]

Steam_PsatT
Calculate the saturation pressure as a function of temperature (T in °C). By default, input arguments and
returned values are in SI units. You can change the units of measure, for example, by using the Convert function.
Syntax
Steam_PsatT(T)

Arguments
• T
Temperature of the steam. T can range from 0.0 to 373.946 °C.
Returns
Computed saturation pressure of the steam in kPa.
Example
• Steam_PsatT(250)
[Returns 3975.9 kPa]

Steam_SPH
Calculate the vapor-specific entropy as a function of pressure (P in kPa) and enthalpy (H in J/g). Use for both
superheated and wet steam as well as compressed water. By default, input arguments and returned values are in
SI units. You can change the units of measure, for example, by using the Convert function.
Syntax
Steam_SPH(P, H)

Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 100000 kPa.
• H
Enthalpy of the steam. H can range from -0.04159 to 4160.7 J/g.
Returns
Computed vapor specific entropy in J/(g K).
Example
• Steam_SPH(10000, 3500)
[Returns 6.756 J/(g K)]

Steam_SPT
Calculate the vapor specific entropy as a function of pressure (P in kPa) and temperature (T in °C). Use for an
entire range from compressed water to superheated steam. By default, input arguments and returned values are
in SI units. You can change the units of measure, for example, by using the Convert function.
Syntax
Steam_SPT(P, T)
Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 100000 kPa.
• T
Temperature of the steam. T can range from 0.0 to 800 °C.
Returns
Computed vapor specific entropy in J/(g K).
Example
• Steam_SPT(40000, 600)
[Returns 6.017 J/(g K)]

Steam_SPTL
Calculate the liquid specific entropy as a function of pressure (P in kPa) and temperature (T in °C). Only use for
compressed water. For any T higher than the saturation temperature for P, the function returns an out-of-range
error. The function accepts any T in the temperature range as long as P is greater than the critical pressure. By
default, input arguments and returned values are in SI units. You can change the units of measure, for example,
by using the Convert function.
Syntax
Steam_SPTL(P, T)

Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 100000 kPa.
• T
Temperature of the steam. T can range from 0.0 to 800 °C.
Returns
Computed liquid specific entropy in J/(g K).
Example
• Steam_SPTL(30000, 500)
[Returns 5.7956 J/(g K)]

Steam_SPX
Calculate the steam specific entropy as a function of pressure (P in kPa) and quality (vapor fraction). Use for only
wet steam. By default, input arguments and returned values are in SI units. You can change the units of measure,
for example, by using the Convert function.
Syntax
Steam_SPX(P, X)
Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 22064 kPa.
• X
Steam quality (vapor fraction). X can range from 0.0 to 1.0.
Returns
Computed specific entropy of the steam in J/(g K)
Example
• Steam_SPX(15000, 0.7)
[Returns 4.8229 J/(g K)]

Steam_SsatP
Calculate the saturated vapor specific entropy as a function of pressure (P in kPa). By default, input arguments
and returned values are in SI units. You can change the units of measure, for example, by using the Convert
function.
Syntax
Steam_SsatP(P)

Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 22064 kPa.
Returns
Computed saturated vapor specific entropy in J/(g K)
Example
• Steam_SsatP(10000)
[Returns 5.6159 J/(g K)]

Steam_SsatT
Calculate the saturated vapor specific entropy as a function of temperature (T in °C). By default, input arguments
and returned values are in SI units. You can change the units of measure, for example, by using the Convert
function.
Syntax
Steam_SsatT(T)

Arguments
• T
Temperature of the steam. T can range from 0.0 to 373.946 °C.
Returns
Computed saturated vapor specific entropy in J/(g K).
Example
• Steam_SsatT(250)
[Returns 6.0722 J/(g K)]

Steam_TPH
Calculate the steam temperature as a function of pressure (P in kPa) and enthalpy (H in J/g). Use for both
superheated and wet steam as well as compressed water. By default, input arguments and returned values are in
SI units. You can change the units of measure, for example, by using the Convert function.
Syntax
Steam_TPH(P, H)

Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 100000 kPa.
• H
Enthalpy of the steam. H can range from -0.04159 to 4160.7 J/g.
Returns
Computed steam temperature in °C.
Example
• Steam_TPH(40000, 3500)
[Returns 643.48 °C]

Steam_TPS
Calculate the steam temperature as a function of pressure (P in kPa) and entropy (S in J/(g K)). Use for both
superheated and wet steam as well as compressed water. By default, input arguments and returned values are in
SI units. You can change the units of measure, for example, by using the Convert function.
Syntax
Steam_TPS(P, S)

Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 100000 kPa.
• S
Specific entropy of the steam. S can range from -0.000155 to 11.921J/(g K).
Returns
Computed steam temperature in °C.
Example
• Steam_TPS(40000, 6)
[Returns 595.93 °C]

Steam_TsatP
Calculate the saturation temperature as a function of pressure (P in kPa). By default, input arguments and
returned values are in SI units. You can change the units of measure, for example, by using the Convert function.
Syntax
Steam_TsatP(P)

Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 22064 kPa.
Returns
Computed saturation temperature in °C.
Example
• Steam_TsatP(10000)
[Returns 311 °C]

Steam_VPH
Calculate the vapor specific volume as a function of pressure (P in kPa) and enthalpy (S in J/g). Use for both
superheated and wet steam as well as compressed water. By default, input arguments and returned values are in
SI units. You can change the units of measure, for example, by using the Convert function.
Syntax
Steam_VPH(P, H)

Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 100000 kPa.
• H
Enthalpy of the steam. H can range from -0.04159 to 4160.7 J/g.
Returns
Computed vapor specific volume in cm3/g.
Example
• Steam_VPH(25000, 3500)
 [Returns 14.197 cm3/g]

Steam_VPS
Calculate the vapor specific volume as a function of pressure (P in kPa) and entropy (S in J/(g K)). Use for both
superheated and wet steam as well as compressed water. By default, input arguments and returned values are in
SI units. You can change the units of measure, for example, by using the Convert function.
Syntax
Steam_VPS(P, S)

Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 100000 kPa.
• S
Specific entropy of the steam. S can range from -0.000155 to 11.921J/(g K).
Returns
Computed vapor specific volume in cm3/g
Example
• Steam_VPS(40000, 6)
[Returns 8.0055 cm3/g]

Steam_VPT
Calculate the vapor specific volume as a function of pressure (P in kPa) and temperature (T in °C). Use for an
entire range from compressed water to superheated steam. You can change the units of measure, for example,
by using the Convert function.
Syntax
Steam_VPT(P, T)

Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 100000 kPa.
• T
Temperature of the steam. T can range from 0.0 to 800 °C.
Returns
Computed vapor specific volume in cm3/g.
Example
• Steam_VPT(50000, 500)
[Returns 3.8894 cm3/g]
Steam_VPTL
Calculate the liquid specific volume as a function of pressure (P in kPa) and temperature (T in °C). For any T
higher than the saturation temperature for P, the function returns an out-of-range error. The function accepts
any T in the temperature range as long as P is greater than the critical pressure. By default, input arguments and
returned values are in SI units. You can change the units of measure, for example, by using the Convert function.
Syntax
Steam_VPTL(P, T)

Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 100000 kPa.
• T
Temperature of the steam. T can range from 0.0 to 800 °C.
Returns
Computed liquid specific volume in cm3/g
Example
• Steam_VPTL(75000, 500)
[Returns 2.308 cm3/g]

Steam_VPX
Calculate the steam specific volume as a function of pressure (P in kPa) and quality (vapor fraction). Use for only
wet steam. By default, input arguments and returned values are in SI units. You can change the units of measure,
for example, by using the Convert function.
Syntax
Steam_VPX(P, X)

Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 22064 kPa.
• X
Steam quality (vapor fraction). X can range from 0.0 to 1.0.
Returns
Computed steam specific volume in cm3/g
Example
• Steam_VPX(15000, 0.7)
[Returns 7.7352cm3/g]
Steam_VsatP
Calculate the saturated vapor specific volume as a function of pressure (P in kPa). By default, input arguments
and returned values are in SI units. You can change the units of measure, for example, by using the Convert
function.
Syntax
Steam_VsatP(P)

Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 22064 kPa.
Returns
Computed vapor specific volume in cm3/g
Example
• Steam_VsatP(10000)
[Returns 18.034 cm3/g]

Steam_VsatT
Calculate the saturated vapor specific volume as a function of temperature (T in °C). By default, input arguments
and returned values are in SI units. You can change the units of measure, for example, by using the Convert
function.
Syntax
Steam_VsatT(T)

Arguments
• T
Temperature of the steam. T can range from 0.0 to 373.946 °C.
Returns
Computed saturated vapor specific volume in cm3/g.
Example
• Steam_VsatT(250)
[Returns 50.087 cm3/g]

Steam_XPH
Calculate the steam quality (vapor fraction) as a function of pressure (P in kPa) and enthalpy (H in J/g). Use only
for wet steam. By default, input arguments and returned values are in SI units. You can change the units of
measure, for example, by using the Convert function.
Syntax
Steam_XPH(P, H)

Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 22064 kPa.
• H
Enthalpy of the steam. H can range from -0.04159 to 4160.7 J/g.
Returns
Computed steam quality (vapor fraction)
Example
• Steam_XPH(10000, 2500)
[Returns 0.82888]

Steam_XPS
Calculate the steam quality (vapor fraction) as a function of pressure (P in kPa) and entropy (S in J/(g K)). Use
only for wet steam. By default, input arguments and returned values are in SI units. You can change the units of
measure, for example, by using the Convert function.
Syntax
Steam_XPS(P, S)

Arguments
• P
Pressure of the steam. P can range from 0.611212678 to 22064 kPa.
• S
Specific entropy of the steam. S can range from -0.000155 to 11.921J/(g K).
Returns
Computed steam quality (vapor fraction)
Example
• Steam_XPS(10000, 5)
[Returns 0.72695]
Chapter 14

Notifications

Notifications is the feature in Asset Framework (PI AF) that you use to create and manage notification rules.
Notification rules are the mechanism by which users are alerted for response in real time, for conditions that
signal events of interest. Notification messages may be customized to include information that is specifically
relevant to the event, and may be sent via email to individuals, groups, or to a web service. Further, escalations
are also configurable in the notification system.
Within PI System Explorer, you can configure and manage notification rules from the Notification Rules tab
(visible after you select an element), and from the Management plug-in.
Note: You can open the audit log directly from notification rules by right-clicking the notification rule and
selecting Audit Trail Events. For more information on audit trail, see Track PI AF changes with Audit Trail.

Introduction to notifications
Notification rules: Definition and scope
Notifications is included as a feature of PI Server, starting with the 2016 R2 version, and is not installed as a
separate product. The notifications feature allows you to configure "notification rules" to send email messages or
to call a web service; you can also configure message content and set up escalations.
Note: Notifications created using PI Notifications 2012 or earlier are henceforth referred to as "legacy
notifications".
Notifications are alerts that are generated when an event of interest is detected in the PI Server; such events are
detected by examining and comparing real-time and static data with user-defined conditions configured in the PI
Server. User-specified information can be configured in notifications that are sent to users or groups in real time
to alert users of conditions to which they may need to respond. Notifications integrate with, and leverage, PI AF
and other PI System services, and can be shared, managed, and maintained enterprise-wide. All notification
actions, such as notification send times, acknowledgments, entry of comments, and escalations, are stored for
later retrieval and examination.
Notification rules are based on event frames and notification messages can include information from event
frame templates. For more information, see Notifications and event frames.
PI Notifications Service
PI Notifications Service is a Windows service that evaluates notification rules, processes incoming real-time
event frames, and sends notifications. The PI Notifications Service need not run on the same machine as the
Data Archive, PI AF server, or the client applications.
For information on event frames, see Event frames in PI AF.
 Training video
For more information on using notifications in PI Asset Framework, watch the videos on the OSIsoft Learning
channel playlist:

Notifications and event frames

You can create notification rules based on any generated event frames (regardless of the method used to create
them). The notification rules will be triggered when the configured condition or event is detected in the system
or process, and a customized notification message is sent to a user, a group, or a web service.
Notification triggers are based on event frames; the event frames may come from different sources like analyses,
the Event Frame Generator (EFGen) interface or custom AF SDK applications. Relevant information for events are
stored in event frames and compatible tools can retrieve such information. Information contained in elements,
event frame templates, and other places may also be added to the notification content. Further, event frame
annotations contain historical notification information and may also include attachments; all annotations may be
viewed using AVEVA PI Vision or other client tools that support viewing annotations.
Relationship between event frames and notification rules

• 1. Analysis-generated event frames. For more information, see Event frame generation analyses to create
analyses from the Analyses tab, and Trigger criteria in notification rules to create analyses from the
Notification Rules tab of PI System Explorer.
• 2. Event Frames Generator (EFGen) interface-generated event frames. See Introduction to PI EFGen.
• 3. Custom AF SDK applications-generated event frames. See the AF SDK documentation.
• 4. Manually created event frames.
Notifications history
Information associated with previous times that a notification was generated is stored as annotations on each
event frame that triggered the notification. The annotations can be accessed by selecting the specific event
frame of interest from the Event Frames plug-in on PI System Explorer. Each event frame annotation includes
such information as the notification rule corresponding to the send event, the subscribers who were notified and
when they were notified, and whether the attempt to notify was successful.
If you have migrated from PI Notifications 2012, and elected to migrate both configuration and history, your
legacy notifications history is fully migrated; the historical information is migrated as annotations on the event
frames created during migration. The migration report includes information on the legacy history instances that
were processed during migration.
Note: For information on permissions required during migration, see Migration from PI Notifications 2012.
Event frame annotations may also be viewed using AVEVA PI Vision or other client tools that support viewing
annotations.
Acknowledge a notification
In PI AF 2016, you can require that an event frame be acknowledged. The acknowledgment feature is used by
notifications and PI AF client applications, such as AVEVA PI Vision. The event-frame acknowledgment feature
replaces the acknowledge notification functionality in legacy PI Notifications 2012 and older versions.
For more information on acknowledging event frames in PI AF, see Acknowledgment of event frames and
Acknowledge event frames.
For more information on viewing and acknowledging event frames using AVEVA PI Vision, see the AVEVA PI
Vision user guide. topic View event details and annotate events.

Requirements for notifications

Both PI AF Server 2023 and PI Notifications Service 2023 are required to connect to a claims-enabled AVEVA PI
Vision server. In addition, TLS certificates and OpenID Connect (OIDC) must also be enabled and configured.
To use the notifications feature, you must install these PI Server components in the following order:
1. PI AF Client 2017 R2 or later; PI AF Client 2023 with OIDC enabled is required to include screenshots from a
claims-enabled AVEVA PI Vision server
2. PI Notifications Service 2017 R2 or later; PI Notifications Service 2023 with OIDC enabled is required to
include screenshots from a claims-enabled AVEVA PI Vision server
3. Optional. AVEVA PI Vision.
▪ This is required if you want to use the acknowledgment link in the notifications feature, which is a link to
the event details page in AVEVA PI Vision.
▪ To include screenshots in notifications from an AVEVA PI Vision server that is configured for Windows
authentication, NTLM provider for Windows Authentication needs to be enabled in AVEVA PI Vision. For
more information, see Delivery formats in notification rules. Also see the AVEVA PI Vision user guide
topics Enable Kerebos delegation using a custom PI Vision service account and Enable basic
authentication.
4. Management plug-in from PI AF Client 2017 R2 or later, which allows for managing analyses and notification
rules in bulk.
Client support for notifications
AVEVA PI Vision and PI DataLink 2016 and later versions support notifications with the ability to display event
frames and associated data. Notification messages can include links and screenshots to pre-configured AVEVA PI
Vision and thereby provide visual representation of the event that triggered the notification. See AVEVA PI Vision
or PI DataLink product documentation for details on notifications feature support.

Notifications security
The notifications feature uses Windows security for communicating internally and with the PI AF server.
Note: See the PI Server topic PI AF objects and local permissions for PI Notifications Service for information on PI
Notifications Service account permissions.
You can secure access to notification rules, notification rule templates, contacts, and contact templates. Object
permissions are granted according to the PI AF Security model.
If Active Directory (AD) access is configured, information from the AD is accessed to create individual contacts.
You cannot delete an AD contact from PI System Explorer, and you cannot modify security settings for the
contact. To configure AD access, see the PI Server topic Configure Active Directory objects for delegation.
If you are using a screenshot feature in your email delivery format, see the security guidelines in the PI Server
Installation and Upgrade guide topic Trusted sites for screenshots. For more information, see also Add a
screenshot in notification email delivery format and Add a domain to the list of trusted sites.
In line with PI Asset Framework, Notifications supports Windows environments that enforce the use of U.S.
Federal Information Processing Standards (FIPS) cryptographic algorithms. For more information, see Support for
FIPS section in and Microsoft Support article "System cryptography: Use FIPS compliant algorithms for
encryption, hashing, and signing" security setting effects in Windows XP and in later versions of Windows.

Security for contacts

Microsoft Windows security is used to control access to groups, escalation teams, and custom, non-Active
Directory contacts. Security settings for Active Directory contacts cannot be changed using PI System Explorer.
Newly created contact objects will inherit default permissions from the parent collections; a newly created
custom contact will have security defined by the server's contacts collection.

Summary of permissions for contacts

Windows security must be set appropriately for contacts to view, modify, delete, or assign privileges to other
contacts.
Permission Description

Read Can view information on contacts.

Write Can modify contacts.
Delete Can delete contacts.
Admin Can assign privileges to contacts.
 Edit security for existing contacts
Edit security settings from the Contacts plug-in to allow desired access to contacts. Administrator access is
required to edit contact security. See Summary of permissions for contacts.
Note: You can also edit security configurations for contacts by navigating to Database > Edit Security, and then
selecting the appropriate Notification Contact Templates for your PI AF server (from the Item column). For
example, if your PI AF Server is named MyServer, you must select MyServer-Notification Contact Templates.
1. In PI System Explorer, click Contacts in the navigator pane.
2. Search for the group, escalation team or delivery endpoint whose permissions you want to change.
You may need to double-click the contact to see its delivery endpoints.
3. Right-click the contact's delivery endpoint and select Security.
The Security Configuration window for the delivery endpoint appears.
4. Change security settings for the delivery endpoint.
Permissions can be changed for all identities that have been configured. You can also map new identities and
configure their permissions.

Security for notification rules and templates

Notifications uses Microsoft Windows security to control access to notification rules and templates. To edit a
notification rule or template, you need write access to notification rules.

Summary of permissions for notification rules and templates

Windows security must be set appropriately to perform specific tasks with notifications.
Permission Description

Read Can view a notification rule.

Write Can modify settings in the Trigger Criteria,
Subscriptions, and Formats panes.
Subscribe Can subscribe oneself to a notification and customize
the subscription.
SubscribeOthers Can subscribe others to a notification and customize
their subscriptions.
Delete Can delete a notification rule.
Execute Can start, stop or reset a notification rule.
Admin Can assign privileges to notification rules.
Write permission at the PI AF server level is needed for global formats. See Configure security for a PI AF server
for more information.
 Edit security for a notification rule or template
Edit security settings to allow desired access to notification rules and templates.
Note: Administrator access is required to edit notification rule and template security. See Summary of
permissions for notification rules and templates.
1. In PI System Explorer, navigate to Database > Edit Security.
You see the Security Configuration window.
2. From the Item column, select the appropriate notification rule or notification rule template for your PI AF
server.
For example, on a PI AF server named "MyServer", you must select:
▪ MyServer-Database-Notification Rule to modify notification rule permissions
▪ MyServer-Database-Notification Rule Template to modify notification rule template permissions.
3. Change security settings for notification rules or templates.
Permissions can be changed for all identities that have been configured. You can also map new identities and
configure their permissions.

Configure authentication for SMTP server connection

Best practice is to use a secure connection when using basic authentication. To use a secure connection with an
SMTP server, enable the Use TLS option. The server must present a valid certificate for a secure connection to be
established. To configure authentication for SMTP server connection, follow this procedure.
1. To start PI System Explorer, click Start > Programs > PI System > PI System Explorer.
2. Click on the PI System Explorer toolbar, or click File > Server Properties.
3. Click the Plug-Ins tab.
4. Scroll down to the Delivery Channel Plug-Ins section, then right-click Email and select Settings.
5. In the Email Delivery Channel Configuration window, click Authentication Options link under SMTP Server.
Note: The same can be done for the Backup SMTP Server by clicking the link by the same name under it.
Primary SMTP Server Authentication Options window opens.
6. Choose among the 3 authentication options.
▪ Windows: PI Notifications Service will pass the network credentials of its service account to the SMTP
server
▪ Anonymous: no credentials will be provided to the SMTP server
▪ Basic: enter a username and password the service will provide to the SMTP server
Note: New username and password you put in will override existing credentials saved in the PI
Notifications Service. For basic authentication in a failover cluster setting, see PI Server installation
topic Install PI Notifications Service in a failover cluster.
7. Click Save and Close or Cancel.
 8. Optional. Check Use TLS box to enable encryption with basic authentication. Otherwise, the username and
password will be sent in plain text.

Configure authentication for a web service connection

Best practice is to use a secure connection when using basic authentication. To use a secure connection for a
web service, use the https:// URI scheme. The server must present a valid certificate for a secure connection to
be established. To configure authentication for a web service connection, follow this procedure.
1. Go to Contacts plug-in.
2. Under Delivery Endpoints, select the web service delivery endpoint you want to authenticate.
Note: Both SOAP and REST delivery methods are supported. Be sure to check in the delivery endpoint if it is
newly configured.
3. Click a hyperlink next to Authentication Option at the bottom of the window.
Select Authentication Option window opens.
4. Choose among the 3 authentication options.
▪ Windows: PI Notifications Service will pass the network credentials of its service account to the web
service
▪ Anonymous: no credentials will be provided to the web service
▪ Basic: enter a username and password the service will provide to the web service
Note: New username and password you put in will override existing credentials saved in PI
Notifications Service. For basic authentication in a failover cluster setting, see Install PI Notifications
Service in a failover cluster.
5. Select Basic radio button.
6. Enter the user name and password and click Save and Close.

Create a notification rule

Configuring a notification rule includes specifying trigger criteria, adding subscribers to the notification rule, and
formatting the message to suit the needs of your organization.
For a detailed sample, see Configuration of notification rules for analyses or event frames.
1. In PI System Explorer, select the element on which you want to create notification rules.
2. From either the Notifications Rules tab, or from an existing event frame analysis, select Create a new
notification rule.
3. Enter a name for the new notification rule and (optionally) select a category.
4. In the Trigger Criteria pane, specify the set of conditions that causes a notification to be sent.
For more information, see Trigger criteria in notification rules.
5. In the Subscriptions pane, select Manage Formats and specify the format for notifications.
For more information, see Delivery formats in notification rules.
 6. In the Subscriptions pane, select View/edit subscriptions and specify the contacts to which notifications will
be sent.
For more information, see Subscriptions in notification rules.
7. Test that the notification is triggered when an event occurs that satisfies all of the trigger criteria specified.

Create a notification rule template

You can create a new notification rule template for an existing element template in PI System Explorer. You can
also convert an existing notification rule into a notification rule template by right-clicking on the notification rule
and selecting Convert to Template.
For a detailed sample, see Configuration of notification rules for analyses or event frames.
1. In the navigator pane of PI System Explorer, click Library.
2. Select Templates > Element Templates.
3. Select the specific element template where you want to create the notification rule template.
4. Click on the Notification Rule Templates tab.
The tab lists the notification rule templates already defined for the selected element template.
5. Create a new notification rule template for the selected element template.
If no notification templates exist, click Create a new notification rule template to create the first one.
Otherwise, click the New Notification Rule Template icon to create a new notification rule template.
6. Enter information to identify the notification rule template.
▪ Name
The name that uniquely identifies this notification rule template.
▪ Description
Optional text that describes the notification rule template.
▪ Categories
Optional category that you can assign to the notification rule template. Click the list and select the
check box next to the category you want to assign, or click New to create a new category.
7. Configure trigger criteria for the notification rule template.
For specific instructions, see Trigger criteria in notification rules.
8. Click on Manage Formats to customize the message that is sent with the notification.
For specific instructions, see Delivery formats in notification rules.
9. Click on View/Edit Subscriptions to configure subscriptions.
For specific instructions, see Subscriptions in notification rules.

10. Click Check In to save the changes.

Trigger criteria in notification rules
You can configure trigger criteria for an event to determine when a notification will be sent to the appropriate
delivery channel, for example, an email address or web service. The trigger conditions are configurable in the
Trigger Criteria pane, and further options can be configured in the Options pane.
To see the Trigger Criteria and Options panes on PI System Explorer, navigate to the Notification Rules tab for a
selected element, and then click View/Edit Trigger in the Trigger pane.
Trigger Criteria pane
The Trigger Criteria pane allows you to configure either of these trigger criteria modes: Analysis or Event Frame
Search.
Use analysis mode to trigger a notification rule on event frames generated by a particular analysis. In the
Analysis mode, you can select an existing analysis or configure a new analysis of type Event Frame Generation or
SQC, and optionally configure additional trigger conditions based on event frame attribute values. If you choose
to create a new analysis with either the default or a custom name, you see the same analysis creation window as
from the Analyses tab. For information on configuring an SQC analysis, see Create an SQC analysis. For
information on creating an Event Frame Generation analysis, see Create an event frame generation analysis. For
information on expression functions to be used as a trigger condition, see Expression functions reference.
Note: For notifications to take effect, you must check in both the analysis and the notification rule. When
creating an SQC analysis from the Trigger Criteria pane, you can only choose Event Frame as the analysis output.
Use event frame search mode to trigger a notification rule based on event frame name, template and category.
In the Event Frame Search mode, you can select a configured event frame template, from the drop-down list,
and then configure the name and category for the event frames that will trigger your notifications. The name
may contain wildcard characters that are supported by event frame search. You can optionally configure
additional trigger conditions based on event frame attribute values.
For both Analysis and Event Frame Search modes, you can add additional trigger criteria using event frame
attribute values. Criteria can be specified for any event frame template attribute that is specified in the
notification rule trigger criteria. The attribute values that you select in the conditions must be specifically those
for which you want to be notified of event frames (that match the analysis event frame template). For example,
if your event frame template defines an event like "downtime" but you only want an email about "unplanned"
downtime, you can configure an attribute value condition where a "reason code" attribute on the "downtime"
event frame template has a value indicating "unplanned" downtime.
Note: Multiple conditions are grouped using the AND operator.
Options pane
The Options pane allows you to configure these trigger options:
• Resend Interval
The time interval after which PI Notifications Service will send additional alerts until the event frame
matching the notification rule is acknowledged or closed.
• Non-repetition Interval
The time interval during which PI Notifications Service will not send similar alerts associated with the same
notification rule.
• Event Frame Can Be Acknowledged
 Option to enable event frame to be acknowledged; the event frame template is also modified accordingly.
This option is automatically selected if the event frame template has been configured for acknowledgment.
• Severity option
This option applies only to event frame generation analyses. If you have configured multiple start triggers for
your analysis, you may choose to be notified in these ways:
• When the current trigger severity is higher than any trigger severity encountered so far.
• When the current trigger severity is higher than the previous trigger severity.
• Every time a trigger condition is true, regardless of its relative severity to other previous triggers.

Non-Repetition Interval in notification rules

You can configure the Non-Repetition Interval setting to prevent notifications from sending similar alerts, which
are associated with the same condition, within a specified amount of time. The non-repetition interval is not
applied for close sends.
Alerts will be sent for triggering events with a higher severity even if a prior alert has been sent for a triggering
event of lower severity, and within the time-frame of the non-repetition interval.
The system determines when to resend the notification based on the time the last notification was sent, and not
based on the start time of the triggering event. For example, if the event frame started at time t, and the service,
after processing, sends the notification at time t1, the system uses t1 as the basis to calculate the time between
alerts.
Note: If you specify both a resend interval and a non-repetition interval, the resend interval must be longer.

Resend Interval in notification rules

You can configure the Resend Interval setting so that additional alerts are sent when the event frame has not
been acknowledged or closed; it is a reminder that the event of interest leading to the notification is yet to be
resolved. The resend interval specifies the time between sending successive alerts.
The system determines when to resend the notification based on the time the last notification was sent, and not
based on the start time of the triggering event. For example, if the event frame started at time t, and the service,
after processing, sends the notification at time t1, the system uses t1 as the basis to calculate the time between
alerts.
Note: If you specify both a resend interval and a non-repetition interval, the resend interval must be longer.

Delivery formats in notification rules

You can configure the format of the message that is delivered when a notification rule is triggered in the
Message and Content panes. To access the Message and Content panes, navigate to the Notification Rules tab
for a selected element, and then click Manage Formats in the Subscriptions pane.
Global default formats
The system provides one global format that is used as the default format when a subscriber is added to a
notification rule. You can edit or rename the global format, but you cannot delete it.
You can also create additional global formats. These global formats can be viewed in notification rules or
notification rule templates. To create, edit or delete global formats, navigate to Tools > Global Formats in PI
System Explorer. You can edit the fields in the Manage Global Formats window. To create and edit global formats,
follow the procedures in the "Custom delivery formats" heading below. For more information on additional
global configuration parameters for notifications, see the OSIsoft Knowledge Base article Manually Managing
Global Configuration Parameters in Notifications 2.x.
Custom delivery formats
To create a custom delivery email format, copy the default Global Default Email format by clicking on the copy
icon in the Message pane. Alternatively, you can create a new delivery format by clicking the new delivery
format icon . The default format includes basic notification information such as the notification rule name,
trigger time and event frame start time, as well as system information such as system and database names.
To customize your delivery format, you can drag and drop the following types of information from the Content
pane to the Message pane:
• PI AF Server properties
• Database properties
• Notification Rule properties
• Event frame properties
• Event frame attributes. If an event frame template is selected, you may add the event frame template
attributes to the content of your email notification.
• Referenced element properties
• Referenced element attributes
These properties and attributes can provide a lot of input to analyzing the event of interest; for example,
including the event frame start time property can tell you when the event of interest started. Including specific
event frame and referenced element attributes can give you supporting information about key parameters.
Starting from PI AF 2018, any numerical attributes in email notifications will display number of digits according to
how Display Digit is configured on the attribute or attribute template. For more information, see Control the
display of attribute and attribute template values.
For AVEVA PI Vision users, you can construct a link that specifies a full path to a display. You can select Full Path
from Referenced element properties or Referenced element attributes under the Content pane.
• PI Notifications Service and PI System Explorer 2017 R2 or later are required to use the Full Path option.
• Full Path can also be configured for global delivery formats.
• The existing Path option is relative to the reference element or attributes.
When sending a notification email, you can include a web, AVEVA PI Vision URI, or a file link. That way, you can
easily navigate to specific locations for relevant information about attributes, event frames, and so on. To add a
link, click in the Message pane, and then click the link icon. You will be prompted to enter your base address.
When you click the Continue button, Create a link window will open. There, you can configure your link.
The link feature allows you to include a Screenshot (or a static image) of the data that triggered a notification.
You can also specify display options if you choose to display the link as a screenshot. See Add a screenshot in
notification email delivery format.
 You can edit the message if you choose to display your link as a text. Display link as option can be found in 2
other places: in Event Details Hyperlink (if AVEVA PI Vision is configured) and URI hyperlink (under Referenced
element attributes; see Create URI Builder data references for more information).
If you are configuring a Web URI, you can specify a fragment, which is a string that is appended at the end of the
URI. For more information on query string parameters, see the PI Vision user guide topic URL parameters
reference.
You can add a file attachment to your delivery format by clicking on the + symbol in the Attachments field. The
selected attachment will be uploaded as an attribute on the referenced element. For acceptable types of
attachment files, see /FileExtensions in AFDiag utility parameters.
Tip: If the Content pane has a message indicating that your selected format is "read-only", you must first add a
new format before you can customize it.
Training video
For more information on message formats, watch the OSIsoft Learning channel video:

Add a domain to the list of trusted sites

Protect your system from unwanted security incidents by allowing screenshots only from a trusted source. If you
want to receive screenshots from a claims-enabled site that uses OpenID Connect (OIDC), such as PI Vision, you
will need to enter the domain to the list of trusted sites.
To add a website to the trusted-sites list, follow this procedure.
1. Click Database on the PI System Explorer toolbar.
2. Select the Configuration database.
3. In the Elements pane, click OSIsoft > PIANO.
4. Select the Attributes tab.
5. Select PageRender > TrustedSites.
6. Add the sites in the Value field of the attribute delimited by a space.
Add a claims-enabled site
1. Optional. To add a claims-enabled site, select PageRender > OpenIDConnectSites.
2. Optional: Add the sites in the Value field of the attribute delimited by a space.
The wildcard (*) character is allowed. Here are some examples:
Note: Whitelisting applies to the website and all of its embedded elements (images, scripts).

If you entered ... The system allows ... The system blocks ...

* All websites No website

https://* All websites using the https://URI All other websites
scheme
If you entered ... The system allows ... The system blocks ...

https://*.osisoft.com https://www.osisoft.com http://www.osisoft.com

https://techsupport.osisoft.com www.osisoft.com
https://www.osisoft.com/ https://osisoft.com
index.html
https://www.osisoft.com:80/
index.html
www.osisoft.com/index.html www.osisoft.com/index.html www.osisoft.com/index
www.osisoft.com/index.html? www.osisoft.com/index.htmlabc
abc=123
www.osisoft.com/abc www.osisoft.com/abc http://www.osisoft.com/abcdef
www.osisoft.com/abc/def www.osisoft.com/abc.def
www.osisoft.com/abc.html
www.osisoft.com/abc?def=123
*.osisoft.com www.osisoft.com osisoft.com
www.osisoft.com:80 notosisoft.com
www.osisoft.com/index.html www.osisoft.com.baddomain
techsupport.osisoft.com
https://www.osisoft.com
http://www.osisoft.com/
index.html
osisoft.com www.osisoft.com notosisoft.com
www.osisoft.com:80 osisoft.com.baddomain
www.osisoft.com/index.html
techsupport.osisoft.com
https://www.osisoft.com
http://www.osisoft.com/
index.html
https://localserver/PIVision https://localserver/PIVision https://localserver/
https://localserver/PIVision/#/ https://localserver/PI
Displays
http://localserver/PIVision
https://localserver.int/PIVision
 If you entered ... The system allows ... The system blocks ...

*://*.int http://internal.website.int https://www.osisoft.com

http://internalwebsite.int http://www.osisoft.com
http://internal.website.int:80
http://internal.website.int/
index.html
192.168.1.* 192.168.1.123 192.168.22.123
192.168.1.123/abc.html
http://192.168.1.123:8080/
abc.html

Add a screenshot in notification email delivery format

You can include a screenshot (or a static image) of the data that triggered the notification.
To include a screenshot in an email from a site that uses OIDC for claims-based authentication, you will need to
add the site to the list of trusted sites. See Add a domain to the list of trusted sites for instructions on adding
both Windows and claims-enabled sites to this list. Also, see the installation topic Trusted sites for screenshots.
To add a screenshot in notification email delivery format, follow this procedure.
1. Navigate to the element that you want to receive the notification.
2. Click on the Notification Rules tab.
3. Select the notification rule that you want to add a screenshot.
Click Create a new notification rule if you are creating a new notification rule.
4. Click Manage Formats in the Subscriptions pane.

5. Copy the default Global Default Email format by clicking on the copy icon in the Message pane.

Alternatively, you can create a new delivery format by clicking the new delivery format icon .

6. Click in the Message pane, and then click the link icon.
7. Enter your base address in Paste a Link window and click Continue.
8. In the Display link as row, click the Screenshot radio button.
9. Optional. In the Image options row, choose Format and Size from each drop down list.
10. Click OK.
Subscriptions in notification rules
Contacts and Subscriptions panes in PI System Explorer
From the Subscriptions pane, you can configure the subscribers to be alerted when a notification rule is
triggered. A subscriber is an individual entity or group of entities that can receive notification messages by
subscribing to notification rules.
To see the Contacts and Subscriptions panes on PI System Explorer, navigate to the Notification Rules tab for a
selected element, and then click View/Edit Subscriptions in the Subscriptions pane.
To add a subscriber from the Notifications Rules tab of PI System Explorer, simply drag and drop a contact from
the Contacts pane to the Subscriptions pane.
Note: To unsubscribe a contact, right-click on the contact and select Unsubscribe.
When you install PI AF, information from Active Directory (AD) is imported and individual contacts are
automatically created in Contacts. For more information, see Configure Active Directory access for contacts. If a
user does not have an AD account, you can create a custom contact.
Subscriptions pane
When a contact is added to the Subscriptions pane, the following details are included for the contact:
• Name
The name of the contact.
• Configuration
The default, inherited, or custom delivery format for this subscriber.
• Notify Option
The notify option may be one of:
• Event start and end. You can receive a notification when an event frame matching the notification rule is
created or closed.
• Event start.
• Event end. You can receive a notification only when an event frame is closed.
Contacts pane
Subscribers may be configured from these types of contacts on the Contacts pane:
• Individual contact
• Escalation teams
• Groups
• Delivery endpoints
Use Contacts Search to find individual contacts to include in a group or escalation team, or subscribe to a
notification rule. You may use wildcards to expand your name searches; this will search both first and last names.
For example, searching for "A*" will list both "Adam Smith" and "John Adams".
Note: The search results show the display name as configured in Active Directory.
For more information on configuring contacts using the Contacts plug-in, see Contacts plug-in.
 Training video
For information on how to configure subscribers, watch this video:
Setup Contacts, Delivery Endpoints, Groups, & Escalation Teams for Notifications[2016 R2]

Customization of subscription content and delivery

The default delivery format specified on the Message tab is automatically applied to all subscriptions in the
notification. To send a different message, you can customize subscription formats by applying a different delivery
format.
Note: If you customize subscriptions and later want to change delivery formats, you might need to manually
change the delivery formats of subscriptions that you previously customized. For example, if you change the
default delivery format, or specify a different delivery format as the default, only subscriptions that inherit that
format will be changed; customized subscriptions are not affected.
For more information on delivery formats, see Delivery formats in notification rules.

Configuration of notifications delivery endpoints

A delivery endpoint is a single entity to which a notification is delivered, such as an individual email address or
web service call. Each delivery endpoint is associated with a delivery channel, the conduit through which
notification messages are sent. Notifications provides delivery channels for email and for both SOAP and REST
web services.
To configure email delivery endpoints, see Configure an email delivery endpoint. To configure dynamic email
delivery endpoints, new in PI AF 2017 R2, see Configure a dynamic email delivery endpoint.
To configure web service delivery endpoints, see Configure a REST web service delivery endpoint.
To configure notifications to be sent as text messages, see the OSIsoft Knowledge Base article How do I set up PI
Notifications to send text messages to my cellular phone.

Configure an email delivery endpoint

If you have not already configured the SMTP server settings for the email delivery channel, follow the
instructions in: Update SMTP settings for the email delivery channel.
To configure an email delivery endpoint and add an email subscriber to your notification rule, follow this
procedure.
1. Add an email delivery endpoint using the PI System Explorer Contacts plug-in.
For specific information, see Manage contacts and Options for the notifications email delivery channel. See
Configure authentication for SMTP server connection for setting up authentication.
2. Navigate to Elements > your_element > Notification Rules and add the configured email delivery endpoint
to your notification rule as a subscriber.
a. Click View/Edit subscriptions in the Subscriptions pane of the notification rule
b. Drag and drop the configured contact from the Contacts to the Subscriptions pane.
 Update SMTP settings for the email delivery channel
You need to configure the email delivery channel to be able to receive email notifications. This must be done
once for each PI AF server.
1. To start PI System Explorer, click Start > Programs > PI System > PI System Explorer.
2. Click on the PI System Explorer toolbar, or click File > Server Properties.
3. Click the Plug-Ins tab.
4. Scroll down to the Delivery Channel Plug-Ins section, then right-click Email and select Settings.
5. In the Email Delivery Channel Configuration window, change the following parameters as needed:
▪ SMTP Server: The fully-qualified domain name of the machine running the SMTP server.
▪ Port: The listener port of the SMTP Server.
▪ Authentication options: Options for a primary SMTP server authentication. See Configure authentication
for SMTP server connection.
▪ Use TLS: Option to enable Transport Layer Security (TLS) encryption for the primary server
▪ Backup SMTP Server: The fully-qualified domain name of the machine running the backup SMTP Server.
▪ Port: The listener port of the backup SMTP Server.
▪ Authentication options: Options for a secondary SMTP server authentication.
▪ Use TLS: Option to enable Transport Layer Security (TLS) encryption for the secondary server
▪ Sender Email: The email address from which notification messages will be sent.
▪ Allow contacts to set sender email: Specifies whether individual contacts can change the email address
from which their notification emails are sent.
▪ Send Timeout: Time allowed for sent emails to be received by the primary SMTP server before failover
to the backup SMTP server occurs.
▪ Backup Fail Back Time: During failover, specifies how long the backup SMTP server sends email before
attempting to fail back to the primary server.

Configure a dynamic email delivery endpoint

In PI AF 2017 R2, you can configure an email delivery endpoint as a value of an attribute. This provides an
additional flexibility in situations where notification emails can be sent to different recipients without making
changes to the notification rule template. To configure a dynamic email delivery endpoint and add an email
subscriber to your notification rule, follow this procedure. For a conventional email delivery endpoint
configuration, see Configure an email delivery endpoint.
1. Navigate to the element that you want to receive the notifications from and add an attribute with your email
address as a value.
The value of this attribute must be a string. You can enter multiple email addresses delimited by comma.
2. Navigate to Notification Rules tab to configure and add an email delivery endpoint as a subscriber to your
notification rule.
a. Click View/Edit subscriptions in the Subscriptions pane of the notification rule.
 b. Click Create a new dynamic endpoint under Dynamic Endpoints.
c. Select an email attribute configured in step 1.
d. Click Create.
e. Drag and drop the configured contact from the Contacts to the Subscriptions pane.
f. Click OK.
3. Go to Contacts plug-in to edit or delete a configured delivery endpoint.
It will be found in Delivery Endpoints folder.
▪ The email attribute endpoint can be edited from the Subscriptions pane as well.
▪ Test button in the Contacts plug-in is not supported for an attribute-based endpoint at this time.

Configure a REST web service delivery endpoint

To configure a web service delivery endpoint and add a REST web service subscriber to your notification rule,
follow this procedure. For SOAP web service, see Configure a SOAP web service delivery endpoint.
1. Add a web service delivery endpoint using the PI System Explorer Contacts plug-in.
a. Go to the Contacts plug-in of the PI System Explorer.
b. Right-click the Delivery Endpoints folder.
c. Select New Delivery Endpoint.
d. Optional. Retry interval. Select the time interval at which PI Notifications Service will contact the web
service. The web service will be contacted as frequently as the system allows if zero is entered.
e. Optional. Maximum Retries. Select the number of times PI Notifications Service will try to connect to the
web service. Entering zero means there will be no retries.
f. Select WebService from the drop-down list next to Delivery channel.
g. Select REST.
h. Enter the URL of your web service.
i. Select Http Method, a default web method to be used for the notification. Supported methods are POST,
PUT and PATCH.
j. Select Authentication Option.
• Windows: the default option. PI Notifications Service will pass the network credentials of its service
account to the web service
• Anonymous: no credentials will be provided to the web service
• Basic: enter a username and password the service will provide to the web service
k. Check in the changes.
See Create a delivery endpoint such as a stand-alone email or a web service row in Manage contacts
and Options for the notifications web service delivery channel for more information. See also Configure
authentication for a web service connection for authentication of web service.
2. Add the configured web service delivery endpoint to your notification rule as a subscriber.
a. Go to the Notification Rules tab of the element you want to add the web service as the delivery
endpoint.
b. Click View/Edit subscriptions in the Subscriptions pane of the notification rule.
c. From the Contacts pane on the right side, expand Delivery Endpoints and drag the configured REST web
service to the Subscriptions pane on the left.

d. Click the wrench icon to open the Web Service Configuration window to configure the JSON object
for the REST API method.
REST can send a JSON object to the REST server in HTTP methods PUT, POST or PATCH.
e. Click the Body tab to enter the path and value on each row.
Currently, only JSON payloads are supported; query string parameters are not supported.

If you hover over the help icon, you see sample JSON parameters (path and value) that are necessary
for configuring this method:

You can validate the method using the Test Send button.
f. Click the Headers tab to enter HTTP headers for your request.
 You use headers to pass additional information along with your request. You can enter the key and value
pair on each row. Common HTTP headers will be available in a drop-down list to enter as a key (for
example, Content-Type).
Note: The default value of the HTTP header Content-Type is application/json; charset=utf-8.
You can also enter a custom header if your web service requires a specific type of header (for example, a
custom API key header.)
You can validate the request using the Test Send button.

Configure a SOAP web service delivery endpoint

To configure a web service delivery endpoint and add a SOAP web service subscriber to your notification rule,
follow this procedure.
1. Add a web service delivery endpoint using the PI System Explorer Contacts plug-in.
a. Go to the Contacts plug-in of the PI System Explorer.
b. Right-click the Delivery Endpoints folder.
c. Select New Delivery Endpoint.
d. Optional. Retry interval. Select the time interval at which PI Notifications Service will contact the web
service. The web service will be contacted as frequently as the system allows if zero is entered.
e. Optional. Maximum Retries. Select the number of times PI Notifications Service will try to connect to the
web service. Entering zero means there will be no retries.
f. Select WebService as the Delivery channel.
g. Select SOAP.
h. Enter the web service address, the URL of your web service.
You can validate the connection using the Get Web Services button.
i. Enter the name of the web service to be used for notification in the Web Service field.
j. Default Web Method: select the default web method to be used for the notification.
This menu displays all of the parameters defined in the web service.
k. Select Authentication Option.
• Windows: the default option. PI Notifications Service will pass the network credentials of its service
account to the web service
• Anonymous: no credentials will be provided to the web service
• Basic: enter a username and password the service will provide to the web service
l. Check in the changes.
See Create a delivery endpoint such as a stand-alone email or a web service row in Manage contacts
and Options for the notifications web service delivery channel for more information. See also Configure
authentication for a web service connection for authentication of web service.
2. Add the configured web service delivery endpoint to your notification rule as a subscriber.
 a. Go to the Notification Rules tab of the element you want to add the web service as the delivery
endpoint.
b. Click View/Edit subscriptions in the Subscriptions pane of the notification rule.
c. From the Contacts pane on the right, expand Delivery Endpoints and drag and drop the configured web
service to the Subscriptions pane on the left.
d. Configure the SOAP web service.

SOAP can call the web service methods. Click the "wrench" icon to configure the SOAP API method.
The "Information" icon gives you information about the parameters (path and value) that must be
configured for this method, and their complexity. Enter the path and value on each row (the path
depends on how the web service server is configured); clicking on a row brings up a drop-down list of
expected values for that path. The interface also automatically validates the parameters that you enter
on each row. You can validate the method using the Test Send button.
You have the option to cancel or retry a connection that is taking a long time to complete; this may
happen if you have a high latency (commonly called "laggy") connection where the WSDL information is
not quickly retrieved.
Note: Complex data may be required by the method. To enter the correct information, refer to the
Web Service Definition Language (WSDL) documentation for the API method.

Contacts plug-in
In PI System Explorer, the Contacts plug-in provides you with contact options for individual users and groups.
Contacts plug-in versions
PI System Explorer works with different versions of the Contacts plug-in.
• To work with the version that is compatible with the new version of notifications that was released in 2016
R2, execute the 64-bit version of PI System Explorer.
• To work with the legacy version that is compatible with legacy notifications, execute the 32-bit version of PI
System Explorer. Note that if legacy notifications is not installed, the new version of the Contacts plug-in will
load. For more information on PI System Explorer versions, see .
Subscriber configuration
You can configure subscribers from these types of contacts:
• Delivery endpoints
A delivery endpoint is an entity to which notifications can be sent, and is typically an individual user
or an application.
• Groups
A group contact is an unordered collection of delivery endpoints, other groups or escalation teams.
Notification messages are sent to all members of the group simultaneously.
Note: Group contacts that you create in PI System Explorer are not the same as Active Directory (AD) groups.
• Escalation teams
 An escalation team is an ordered collection of delivery endpoints or groups.
Notification messages are sent immediately to the first contact on the list. If the event frame matching the
notification rule is not acknowledged or closed within a specified time, notification messages are sent
sequentially to the remaining members of the escalation team until the event frame is acknowledged or closed.
The escalation period defines the amount of time to elapse before a notification is sent to the next contact on
the list.
Search for contacts
Click the icon to open the Search Contacts window in the Contacts pane on the top left of the screen.
Currently available search criteria are: Name, Description, Department and Email.
Note: You must be running the 2018 or later version of PI AF server to use email as search criterion. Note that
search by email address only works for contacts in Active Directory but does not find contacts created manually.

Configure Active Directory access for contacts

When you use notifications with PI AF server, you may need to specify how to access Microsoft’s Active Directory
to retrieve contact names for the PI Notifications Service Contacts lists.
Each PI AF server provides the option to specify the domain and contact sub-folder, as well as the account
needed to access Active Directory and retrieve contact names. By default, the account under which the PI AF
server application service is running is used for Active Directory access. To use a different account or to access an
Active Directory in a different domain, configure access from the Configure Active Directory Access for Contacts
window.
Note: Beginning with PI AF 2017 R2, Active Directory group is shown by default under Contacts in PI System
Explorer once it is configured.
Notifications 2016 R2 or later will automatically handle a change in email address of the user or a group in Active
Directory by contacting the domain controller before sending an email each time.
1. Open PI System Explorer and connect to a database on the PI AF server for which you want to configure
Active Directory access.
2. Click File > Server Properties.
3. In the PI AF Server Properties window, click the Configure Active Directory Access for Contacts link.
4. In the Active Directory Domain Name text box, enter the full DNS name of the Active Directory domain from
which the contact names will be retrieved for the PI Notifications Service Contacts (for example,
contoso.com).
If this field is left blank, the domain in which the PI AF application service resides will be used.
5. In the Active Directory Contact Sub-Folder text box, enter the path to the folder containing the list of
contacts for this domain.
In larger Active Directory domains, contacts may be organized within sub-folders. The use of sub-folders can
allow for faster retrieval of a list of Active Directory contacts.
Use the following structure for the sub-folder:
DomainUserFolder/SubDomainUserFolder/Sub-SubDomainUserFolder
6. Choose an option for Active Directory Access Account:
 ▪ Use the account the PI AF Server runs as
This is the default option. Select it to access Active Directory using the account under which the PI
AF application service runs. By default, the PI AF server is installed using a virtual account, NT
SERVICE\AFService. However, the PI AF server service account can be changed. If the PI AF server
service account does not have the necessary permission to read the Active Directory, no contact
names will be retrieved in the Contacts list. If your Active Directory security is configured to allow
the PI AF server service account to read the Active Directory, this is the simplest option.
▪ Use the account the AF Client is running as
Select this option to use the credentials of the user account under which the connecting client
application is running. If the PI AF server service is running under an account (a virtual account, NT
SERVICE\AFService is the default account) that does not have permission to read the Active
Directory, this option can be used. As long as the user account under which the connecting client
application is running has permission to read Active Directory, a list of contact names is returned to
the Contacts list. The contents of the Contacts list may vary, depending upon the access account
used, since the security to read the contact list is determined by Active Directory.
Note: Specifying this option may require Kerberos configuration if a PI AF SDK application will be
using impersonation in a middle tier, such as a Web Service.
▪ Use the specified account
This option allows you to specify an account to use to read the Active Directory. This can be useful
when the Active Directory and PI AF server are in different domains or when the accounts in the first
two options have no permission to read the Active Directory. For Account Name, use the format
Domain\User. Make sure the specified account has the appropriate permission to read the target
Active Directory.
7. Check Use Active Directory's locally cached Global Catalog to use the global catalog for Active Directory
domain controller searches. Otherwise searches must go to the owning domain controller.
Active Directory holds information in a distributed data repository called a global catalog. For installations
where there are multiple, distributed domain controllers, each domain controller has a cache of the portions
of the global catalog for which it is not responsible, so that Active Directory searches do not have to be
referred to the owning domain controller. This improves performance for queries that must otherwise have
to access a remote domain controller.
8. Choose a setting for Return All Persons.
Active Directory objects are derived from one another as follows:
Top>Persons>OrganizationalPerson>Contact
and
Top>Persons>OrganizationalPerson>User
• Select this check box to return Persons, Organizational Persons, Contacts and Users from the target
Active Directory.
• Clear the check box to return only Users.

Manage contacts
You cannot nest escalation teams.
Use the Contacts plug-in to manage individual contact information, as well as manage groups, escalation teams,
and delivery endpoints for use with notifications.
1. In the navigator, click Contacts.
2. In the Contacts browser, choose from the following actions.
To ... Do this ...

Edit an existing contact a. Choose one of the following actions:

• search criteria in Search for contacts and pr
Enter
Click
• next to Search for contacts, enter search
OK.
Expand
• the Contacts folder, click New search..., e
and click OK.
Search results are displayed in the Contacts brows
b. Click beside the contact you want to update and clic
c. In the viewer, you can make the following changes:
In•the Description field, add additional contact inf
Enter
• notification contact options in the Retry int
Create a custom contact that is not already in Active a. Right-click the Contacts folder and click New Contact.
Directory
b. In the viewer, enter a name and an email address. All
The contact is displayed in the Contacts browser.
c. Click beside the newly created contact.
Note: The icon indicates non-AD contacts (as oppos
d. Click the email delivery endpoint and, in the viewer, e
interval and Maximum Retries fields.
Create a group a. Right-click the Groups folder and click New Group.
b. In the Name field, enter a unique name for the group
c. Choose from the following actions:
Click
• and, in the Select a Contact window, loca
group, an escalation team, or a delivery endpo
In•the Contacts palette, locate a contact with a ne
team, or a delivery endpoint, and drag it onto
d. Set notification contact options for the group.
Right-click
• each subscriber delivery endpoint, click
the Retry interval and Maximum Retries field
If•escalation teams are included in a group, right-c
notification contact options in the Escalation
 To ... Do this ...

Create an escalation team a. Right-click the Escalation Teams folder and click New
b. In the Name field, enter a unique name for the escala
c. In Escalation period, specify how long you want an es
d. In If not acknowledged, specify the action to be taken
sent to all contacts in a team:
To• stop the escalation process, select End escalati
To• repeat the escalation process for a specified nu
acknowledged, select Repeat N times.
To• repeat the escalation process indefinitely until
Repeat while active.
e. Choose from the following actions:
Click
• and, in the Select a Contact window, loca
group, or a delivery endpoint, and click OK.
In•the Contacts palette, locate a contact with a ne
endpoint, and drag it onto the viewer.
f. Configure the sequence for the escalation chain.
Click
• a subscriber and click and to position as
To• remove a subscriber, click the subscriber to be
Create a delivery endpoint such as a stand-alone a. Right-click the Delivery Endpoints folder and click New
email or a web service
b. In the Name field, enter a unique name for the delive
c. Enter notification contact options for the delivery end
fields.
d. From Delivery channel, select a deliver option.
For
• Email, enter address configuration informatio
email delivery channel.
For
• WebService, enter web service address config
the notifications web service delivery channel
3. To save changes you have made to contacts, press Ctrl+S or click Check In.

Options for the notifications email delivery channel

An email delivery endpoint can be configured in ways specific to the email delivery channel, such as the address
to which notification is sent. The following table shows options that are available for all email delivery endpoints:
 Option Description

To Email Email address to which the notification is sent.

This option cannot be changed in the default email
delivery endpoint that was derived from the Active
Directory (AD) contact.
Multiple email addresses can be entered delimited by
comma.
From Email Email address from which the notification is sent.
This option is available solely if your PI System
manager has configured the email delivery channel
with the setting Allow contacts to set sender
email.
Use HTML formatting Specifies if the delivery endpoint receives messages
in HTML format. HTML formatting makes messages
easier to read and allows messages to contain
hyperlinks.

Options for the notifications web service delivery channel

Creating a web service delivery endpoint
Using the Contacts plug-in of the PI System Explorer (PSE), you can configure a web service delivery endpoint for
SOAP or REST web services. To map parameters for the API call, create and configure body of the message, see
Configure a REST web service delivery endpoint. For authentication of a web service, see Configure
authentication for a web service connection.
Configuring the SOAP web service
The following table lists the options you must set for a SOAP web service delivery endpoint:
SOAP web service options

Option Description

Web Service Address The URL of your web service. You can validate the
connection using the Get Web Services button.
Web Service The name of the web service to be used for
notification.
Default Web Method Default web method to be used for the notification.
This menu displays all of the parameters defined in
the web service.
The PI System Explorer user interface automatically retrieves the associated Web Service Definition Language
(WSDL) methods, provides useful information about the parameters, and guides you through configuring the
web service.
 Configuring the REST web service
The following table lists the options you must set for a REST web service delivery endpoint:
REST web service options

Option Description

URL The URL of your web service.

HTTP Method Default web method to be used for the notification.
Supported methods are POST, PUT AND PATCH.

Notification rules management

To manage your notification rules, use the Management plug-in, accessible on the bottom left of the main screen
of the PI System Explorer. When accessed, the plug-in gives you a choice of two radio buttons to manage either
your analyses or your notification rules. Select the Notification Rules button to view and manage your
notification rules. For more information, go to Management of notification rules. To search for notification rules
configured in your database, see Search for notification rules.

Management of notification rules

The Management plug-in gives you a choice of two radio buttons to manage either your analyses or your
notification rules. Select the Notification Rules button to view and manage your notification rules.
Notification Rules pane
The Notification Rules pane displays information about selected notifications rules in these columns:
• Status
• Element
• Notification rule name
• Template (Notification rule template)
• Categories
You can select or deselect notification rules from the list of configured notification rules, and monitor individual
status on the Notification Rule Details pane; you can also enable or disable selected notification rules from the
Operations pane.
Operations, Pending Operations, and Notification Rule Details panes
The other screens on the Management plug-in include:
• An Operations pane where you can enable or disable notification rules.
• A Pending Operations pane that provides information on whether an operation is queued or complete.
• A Notification Rule Details pane that is displayed when you select a notification rule, and has details, status
and error information about the notification rule. Click on Notification rule configuration to go back to the
element Notification Rules tab.
Search for notification rules
1. Navigate to the Management pane.
2. Select the Notification Rules option.
3. Use the provided search or create your own.
To Then

Use a provided search Select All, Enabled or Disabled. These are view-only
and cannot be modified, as indicated by the (View
selected search) icon.
Create a custom search Note: Customized search is only visible to the user
who created it on the computer where it was created.
Creating your own search is a new feature in PI AF
2017. Refer to the previous versions of PI System
Explorer User Guide if you are using an earlier version
of PI AF.

1. Click the (Add new search) button.

2. Select a search criteria. Choices are:
• Name
• Description
• Element Name
• Template
• Category
• Enabled/Disabled: enabled or disabled
• Service Status: PI Analysis/Notifications
Service status
• Error
• Running
• Stopped
• Suspended
• Warning
Note: Service Status is based on the PI
Analysis Service connection and its
running status. This cannot be combined
with other search criteria.

View/edit a search Click the (View/edit selected search) button to

view or edit your search.
 To Then

Delete a search To delete, click the (Delete selected search)

button.

Configuration of notification rules for analyses or event frames

The asset analytics and notifications features of the PI AF server together provide effective ways for you to
perform condition-based or predictive maintenance. Notification rules leverage the event frame feature of PI AF
to notify you of important events that affect your system.
This section guides you in creating notification rules for your analyses or event frames.

Configure notification rules from analyses

If you have already configured analyses to detect anomalies in your PI AF asset data, or you wish to configure
such analyses, follow this procedure to configure notification rules on configured analyses.
Note: For information on software and system requirements, see Requirements for notifications. If you want to
configure notification rules to trigger on event frames from sources like event frame interfaces or custom
applications, see Configure notification rules for user-defined event frames. For information on creating an event
frame generation analysis, see Event frame generation analyses.
1. Select the existing event frame generation analysis for which you want to create a notification rule.

2. Click Create a new notification rule for the selected analysis.

You see the Notifications Rules tab highlighted, as well as the options to configure a notification rule with
the default name "Notification Rule".
3. Edit the created notification rule.
Provide one or more of the specified criteria; some of your criteria may be pre-selected from your analysis.
The notification rule is triggered when all criteria are satisfied. You may change the name of the notification
rule from the default, add a suitable description, and select a suitable category.
Selecting a category aids in organizing and searching for your notification rules.
4. Click View/Edit Trigger
The Trigger Criteria pane allows you to configure either of these trigger criteria modes: Analysis or Event
Frame Search. Make sure that the Analysis criteria mode is selected.
5. Configure options in the Trigger Criteria pane.
▪ You see the details of the selected analysis such as the event frame template name, the start and end
triggers, and so on.
▪ You can configure a new analysis of type Event Frame Generation or SQC. When you choose to create a
new analysis with either the default or a custom name, you see the same analysis creation window as
from the Analyses tab of PI System Explorer.
▪ For more information, see Trigger criteria in notification rules.
6. Configure options in the Options pane.
▪ Optional. Resend Interval. Select the time interval at which PI Notifications Service will send additional
alerts if the event frame matching the notification rule is not acknowledged or closed. For more
information, see Resend Interval in notification rules.
▪ Optional. Non-repetition Interval. Select the time interval for which PI Notifications Service will not send
similar alerts associated with the same notification rule. For more information, see Non-Repetition
Interval in notification rules.
▪ Event Frame Can Be Acknowledged. This option is automatically selected if the event frame template
has been configured for acknowledgment.
▪ Optional. Options based on multiple start triggers. If you have configured multiple start triggers for your
analysis, choose between the options of being notified (a) when the current trigger severity is higher
than any trigger severity encountered so far, (b) when the current trigger severity is higher than the
previous trigger severity, or (c) every time a trigger condition is true, regardless of its relative severity to
other previous triggers.
7. Optional. To configure the email format, click Manage Formats in the Subscriptions pane.
You see the Message and Content panes. By default, the notifications feature uses the Global Default Email
format for each subscriber. For more information, see Delivery formats in notification rules.
Note: If the Content pane has a message indicating that your selected format is "read-only", you must first
add a new format before you can customize it.
8. Optional. To create a custom delivery email format, copy the default Global Default Email format by clicking
on the copy icon in the Message pane. Alternatively, you can create a new delivery format by clicking the
new delivery format icon .
The default format includes basic notification information such as the notification rule name, trigger time
and event frame start time, as well as system information such as system and database names. To add more
information to your custom format, drag and drop information from the Content pane to the Message pane.
Tip: A hyperlink indicates that an event frame template is selected; you may add the attributes defined
below the event frame template to the content of your email notification by dragging and dropping the
attributes from the Content pane to the Message pane.
You can designate your custom format as the default by clicking the Is Default box in the Message pane.
9. Click View/edit subscriptions in the Subscriptions pane.
You can search for contacts using Contacts Search in the Contacts pane. To add a subscriber, drag and drop a
specific contact from the Contacts pane to the Subscriptions pane. Make sure to select your customized
email format if you have created one, or pick the Global Default Email format. For more information, see
Subscriptions in notification rules.
 10. Optional. Configure escalation teams.
You can configure members of escalation teams from the Contacts plug-in on PI System Explorer, as
described in Manage contacts. The escalation team contacts or groups will be notified one by one at the end
of time segments specified in Escalation period. You can also control the frequency of the escalation
notification.
Note: Escalations are triggered on event frame templates that can be acknowledged. Open the Library plug-
in on PI System Explorer, select your event frame template and verify that the Event Frame Can Be
Acknowledged check box is selected.
11. Check in the notification rule.
When the event of interest occurs, an email will be sent to the subscriber's mailbox. The email shows the
event frame that triggered the notification rule with customized details that you have configured.
To manage your notification rules, use the Management plug-in on PI System Explorer. See Management of
notification rules.

Configure notification rules for user-defined event frames

For information on software and system requirements, see Requirements for notifications.
Note: If you have already configured an analysis on your PI AF asset, or wish to create new analyses to generate
the event frames, use the procedure Configure notification rules from analyses.
Use this procedure if you want to configure notification rules to trigger on event frames from sources like event
frame interfaces or custom applications.
1. In the PI System Explorer navigator, click Elements and select the element for which you want to define the
notification rule.
2. Select the Notification Rules tab.
3. Click Create a new notification rule.
 Change the name of the notification rule from the default, add a suitable description, and select a suitable
category. Selecting a category aids in organizing and searching for your notification rules.
4. In the Trigger pane, click on the hyperlink Please configure trigger criteria for this Notification Rule.
The Trigger Criteria pane allows you to configure either of these trigger criteria modes: Analysis or Event
Frame Search.
5. Select the Event Frame Search trigger criteria mode.
6. Configure options in the Trigger Criteria pane.
You can select the event frame template from the drop-down list, and add conditions using any of the
attribute templates for the event frame template.

7. Configure options in the Options pane.

• Optional. Resend Interval. Select the time interval at which PI Notifications Service will send additional
alerts if the event frame matching the notification rule is not acknowledged or closed.
• Optional. Non-repetition Interval. Select the time interval for which PI Notifications Service will not send
similar alerts associated with the same notification rule.
Note: Verify that the event frame template has the Event Frame Can Be Acknowledged check box
selected.
 8. Optional. To configure the email format, click Manage format in the Subscriptions pane.
You see the Message and Content panes. By default, notifications uses the Global Default email format for
each subscriber.
Note: If the Content pane has a message indicating that your selected format for a subscriber is "read-only",
you must first add a new format before you can customize it.

9. Optional. To create a custom delivery email format, copy the default Global Default Email format by clicking
on the copy icon in the Message pane. Alternatively, you can create a new delivery format by clicking the
new delivery format icon .
The default format includes basic notification information such as the notification rule name, trigger time
and event frame start time, as well as system information such as system and database names. To add more
information to your custom format, drag and drop information from the Content pane to the Message pane.
Tip: A hyperlink indicates that an event frame template is selected; you may add the attributes defined
below the event frame template to the content of your email notification by dragging and dropping the
attributes from the Content pane to the Message pane.
You can designate your custom format as the default by clicking the Is Default box in the Message pane.
10. Click View/edit subscription in the Subscriptions pane.
 You can search for contacts using Contacts Search in the Contacts pane. To add a subscriber, drag and drop a
specific contact from the Contacts pane to the Subscriptions pane. Make sure to select your customized
email format if you have created one, or pick the Global Default email format.

11. Optional. Configure escalation teams.

You can configure members of escalation teams from the Contacts plug-in on PI System Explorer, as
described in Manage contacts. The escalation team contacts or groups will be notified one by one at the end
of time segments specified in Escalation period. You can also control the frequency of the escalation
notification.
12. Check in the notification rule.
When the event of interest is generated, an email is sent to the subscriber's mailbox. The email shows the
event frame that triggered the notification rule with the customized details that you have configured.
To manage your notification rules, use the Management plug-in on PI System Explorer. See Management of
notification rules.

Configure escalations for notification rules

An escalation team is an ordered collection of delivery endpoints or groups. Notification messages are sent
sequentially to the members of escalation teams until the event frame matching the notification rule is
acknowledged or closed. You can set up an escalation structure to ensure that the right people are notified with
the right information, and in the right order.
Subscribe an escalation team to send notification messages sequentially to a group of contacts. For more
information on creating an escalation team, see Create an escalation team in Manage contacts.

Changes from PI Notifications 2012

The notifications feature is based on event frames and does not have an analysis engine like PI Notifications 2012
and earlier versions (henceforth referred to as "legacy" versions). Notification rules leverage PI Analysis Service,
as well as other applications that generate event frames, to identify important events in the PI Server, to use
 event frames as the container for relevant information for the event, and to use annotations on the event frame
to store notification history.
The notifications feature is driven by event frames; therefore, some legacy notification features are either
different or rendered obsolete. A migration tool is included to enable migration of notifications from your PI
Notifications 2012 legacy version to notification rules, thereby preserving the investment you made in your
legacy system.
Note: If you choose to migrate, the migration tool converts your legacy notifications into analyses and
notification rules.
For more details on the migration tool, see Migration from PI Notifications 2012.
User interface changes from PI Notifications 2012
Notifications in PI Server 2016 R2 (and later versions) is fundamentally different from the legacy PI Notifications
2012, and you cannot share configurations between the two systems.
To configure event-based notifications, you must use the Notification Rules tab in the Elements view of 32-bit or
64-bit PI System Explorer. To manage legacy notifications, you must use the Notifications plug-in on the 32-bit PI
System Explorer.

Note: The notifications feature no longer supports the Microsoft Office Communication Service (OCS) or custom
delivery channels. However, using REST-based web services, you may be able to integrate notifications with third-
party delivery channels.

Migration from PI Notifications 2012

PI Server 2016 R2 and later versions include a migration tool to enable migration of your 2012 notifications to
notification rules based on event frames. The migration tool is run at the end of the PI Notifications Service
install, and you may choose to migrate your legacy notifications at that time.
You may also run the migration again from PI System Explorer, after the installation is complete. To run the
migration tool from PI System Explorer, make sure that all these conditions are true:
• PI Notifications Service is installed on your machine
• The migration tool executable file PINotificationsMigrationTool.exe is installed on your machine, typically in
the PIPC\Notifications folder
The Notifications Migration Tool attempts to migrate all existing notifications by modifying the rule and if
necessary prompting you to accept or reject the change if a feature is no longer supported. This section
describes the types of notification features that are migrated and those that cannot be migrated.
The migration tool causes these object migrations:
• Legacy notification triggers are migrated as event frame generation analyses and are run in PI Analysis
Service.
• Legacy notifications created in previous versions are migrated to notification rules, and they run in the PI
Notifications Service.
• Legacy notifications history is fully migrated and created as event frames. History in PI points are migrated as
annotations on event frames.
• Legacy notification template name, description and properties are mapped to the notification and target
properties; a message is also logged in the migration report.
Note: Properties of the notification rule template cannot be overridden on a notification rule based on the
template with an exception of the description field.
Due to this, if a legacy notification deviates from the legacy notification template, that information may be
lost during migration. For example, if the legacy notification template is named "Notification for Pumps", but
a legacy notification based on this template is named "Notification for Pumps - Houston", the migrated
notification rule template and all notification rules based on this template will be named "Notification for
Pumps". The description field of the migrated notification rule, however, will contain the name of the legacy
notification. The migration report will contain the name changes and any other changes that have been
made.
The migration tool does not migrate the following legacy notifications:
• Custom delivery channels
• Alarm functions
• Monthly and daily period time rules
• Notifications with the Notify only on change in status option unchecked.
• Notifications containing a nested escalation
• Notifications with multiple triggers:
• If a legacy notification has multiple triggers and you have assigned states from different state groups, the
legacy notification is not migrated.
• If a legacy notification has multiple triggers and you have assigned the same state to more than one
trigger, the legacy notification is not migrated.
Note: For a list of legacy notifications that are not migrated or migrated with some loss of content, see the
OSIsoft Knowledge Base article Caveats in Migrating from Notifications 2012 to 2.x.
Training video
For more information on migration, watch the OSIsoft Learning channel video:
Running the migration tool
If you are running the migration from PI System Explorer, make a backup of the PIFD database before starting the
migration. For instructions on how to perform a backup, see the PI Server Installation and Upgrade guide topic
OSIsoft Backup job. Note that you can also migrate notifications when you are upgrading PI Server.
Before you begin migration you must verify that you have read permissions on the PI Data Archive where the
legacy notifications history is stored and read/write permissions on the PI AF database where the legacy
notifications are configured.
You may need to back up the PIFD (SQL database) if you want to re-run the migration and avoid having duplicate
notification rule and analysis objects created. If you re-run your migration and are warned that duplicates may
be created during the re-migration, you can first restore your PIFD database from the backup and avoid the
creation of duplicates.
You can re-run the migration tool by clicking Tools > Notifications Migration from PI System Explorer. The
migration tool first determines and displays information on your state, which is one of:
• Not migrated
Legacy notifications may be created and managed using the Notifications plug-in on the bottom left of the PI
System Explorer window. You must use the 32-bit version of PI System Explorer to manage legacy
notifications.
You can choose to be in the "Not migrated" state by choosing the appropriate option while running the
migration tool. In this state, you cannot create new notification rules.
• Migrating
Legacy notifications are read-only; only new notification rules may be created. You can stop and start legacy
notifications while in this state.
In the migrating state, you may run and test legacy notifications and new notification rules side-by-side to
ensure that the migration is successful and that the new analyses and notification rules are working as
intended. You can check the migration report, fix the errors indicated on legacy notifications, and then
choose to re-run migration for only those legacy notifications that encountered errors in the previous
migration run.
You may move to the migrated state when you have successfully tested that your migrated notification rules
match your legacy notifications. Move to the migrated state only when the following are true:
• You intend to continue to work only with the new notification rules
• You will never need to revert to your legacy notifications
• You have successfully migrated all the legacy notifications that you wanted to migrate
• Migrated
When you move to this state, you can create only new notification rules in the system. Your legacy
notifications are deleted and you cannot revert to your legacy notifications or create legacy notifications.
From the migrated state, you may re-run the migration tool to revert to the "Not migrated" state; however,
your legacy notifications cannot be recovered.
After all legacy notifications have been converted, you may want to run both versions of notifications in parallel
for a while to ensure that the notification rules are functioning as expected. When you are satisfied with the
migrated notifications, run the migration tool again and select Complete migration and delete all legacy
notifications from server. After running the tool you can also uninstall PI Notifications 2012. OSIsoft strongly
recommends that you uninstall the legacy PI Notifications after any transition period.
If you do choose to run both versions of notifications simultaneously for a period of time, be aware that each
notification may be sent twice, once from the PI Notifications Scheduler, which is part of the legacy PI
Notifications, and once from the PI Notifications service. If you do not want to receive duplicates during this
transitional period, you can disable the PI Notifications Scheduler.
You must manually create notification rules for any unsupported legacy notifications that were not migrated.
Note: The Notifications Migration Tool only needs to be run once against an AF Collective.
Sample migration report
The migration tool generates a report when it completes the migration process. The report includes information
on whether legacy notifications are migrated successfully. The "Errors" section and the "Not Supported" sections
indicate notifications that are not migrated. The "Warnings" section indicates notifications with changed
functionality, and the report provides more information.
Note: Migration report can be found in %userprofile%\Documents folder of the person running the migration.
This is a sample migration report summary:
In addition to the summary, the report also contains information on legacy and migrated notification rules and
templates, and specific information such as notification rules and analysis names, number of migrated event
frames, and the number of processed history events.
Additional resources
Training video
For more information on using notifications in PI Asset Framework, watch the videos on the OSIsoft Learning
channel playlist:
Chapter 15

Process models in PI AF

A PI AF model consists of connected elements that represent a logical model of your process. A model is itself an
element, but with two additional element properties: layers and connections. Elements in the model can
represent physical entities in your process, such as tanks, pipes, and process units, or logical entities, such as
recipes and summary data. The model is composed of connected elements.
PI AF models can be simple, containing only a handful of elements, or they can be very complex, containing
thousands of elements and measurements. The size of the model is only limited by the data available to fulfill
the information requirements of an analysis on the model.

The scope of a PI AF model

While the number or variety of elements that a model encompasses does not change how a model is stored, it
does help in planning both the initial model design and the information needed to complete a model analysis
and get meaningful results. When considering the scope of a model, remember that it needs to be small enough
for the relationships between properties to be well defined, but large enough to include some redundant data.
Redundant data can be calculated from other data in the model.
At different levels of scale, or modeling scope, the consumers of the resulting information will change. For
example, an engineer looking at equipment performance of a section of the facility may need more detailed
information than a resource planning individual who tracks materials throughout a facility. The planner needs
measurements in the model that are different from the measurement needs of the engineer. Elements that are
common to both models use the same source elements; this aids in the construction of a variety of models using
the same element library.
Three modeling levels, in order of increasing scope, are the following:
• Unit Model
• This level of modeling typically includes the smallest details of information within a processing unit or
area. This scope is useful for monitoring equipment performance and is used primarily by the engineers
on that equipment. Auxiliary loops and heating systems that occur at this modeling level might not have
influence outside of this area, and therefore would not be included at the next scale.
• To perform a meaningful analysis on a unit level model, detailed data must be available on the materials
and quantities within the unit. If there is only information available on the parameter of the unit (the
inputs and the outputs), this is an indication that the data model is at its smallest granularity.
• Multi-Unit Model
 • When considering unit-to-unit type models, detail within the unit is typically summarized by the
connections to and from that unit. Material added and sent to storage areas (tanks, stockpiles, etc.)
would also be included.
• At the multi-unit modeling level, measurements within the unit that do not affect the main inputs and
output quantities are not included in the model.
• Boundary Model (Facility and Business Unit)
• It is useful to create an analysis for the materials entering and leaving the "fence line" of the facility,
further summarizing the unit-to-unit information to only the transactions to and from the process from
material transfer points (shipping docks, weigh scales, tank feeds, pipelines). This level is also useful to
analyze transactions between business units within a facility.

Guidelines for PI AF models

Consider the following rules as you set up a model for analysis:
• Use a systematic approach to identify the location and calibration setup for each instrument in the model.
• Associate every instrument with the correct flow, and make sure that temperature and specific gravity
corrections are applied to flow measurements if needed. Check whether this function of correction is
performed by your control system or historian.
• Validate tank/inventory properties by building a tank-only model, including shipments and receipts. Enter
the materials list with its properties at the same time.
• Determine the calibration tolerance of each instrument (you can use ISO 5167 for orifice meters), or refer to
meter data sheets and manufacturers.
• Build and examine individual unit models before attempting to connect them and run a multi-unit analysis.
• After you achieve full unit connectivity, examine the entire drawing, and then run a balance analysis to
identify flows and connections that cannot be solved.

Submodels
A model is also an element, which means that a model can be composed of other models - referred to as
submodels. This allows for either top-down or bottom-up development of a plant model. The boundary
elements of a model normally define the elements with ports that can be used for connections outside the
model.

Element types in models

Six core element types are used to enforce connectivity rules between elements of a model.
• Use a Node to represent a physical entity in your model, such as a tank, valve, or process unit.
• Use Measurement to indicate that the element is used for ascertaining dimensions, quantities, capacities,
etc., such as, meters or scales.
• Use Flow to indicate that the element carries material from one element to another.
 • Use Transfer as a temporal flow. The existence of a transfer in a model is only available in the context of
time, for example, in a case. Transfers can also be accessed by performing time-based searches of the
database.
• Use Boundary to define the input and output ports for the model.
• Use Other to represent a logical collection of attributes, such as a recipe.
In addition to the core element types, two other types are supported: Any and None. Use the Any and None
element types when you define the connectivity rules for a port.

Create PI AF models
You create a PI AF model in the Elements browser.
1. In the navigator, click Elements.
2. Right-click the collection of elements and click New Model.
3. In the Choose Model Template window, select a template on which to base the model or select None.
4. Click OK.
The model configuration tabs appear in the viewer.
5. In the Name field of the General tab, enter a name for the model.
6. Optional. In the Description field, enter a description for the model.
7. The read-only Template and Type fields list the template and element type chosen when the model was
created. To view the template properties, click . Element types are described in Element types in models.
8. Optional. You can organize objects by grouping them into categories. To browse the available categories, click
.
9. To assign a default attribute, select the attribute from the Default Attribute drop-down list. Note that you
must add attributes in the Attributes tab first before they appear in the list. This field is read only if the
model is based on a template; the box displays the attribute specified in the template.
10. Optional. To specify location attribute traits for the model, click the Location link. For more information, see
Set location attribute traits.
11. Optional. To specify asset health attribute traits for the model, click the Health link. For more information,
see Set health attribute traits.
12. Optional. To configure access permissions for the new model that are different from those inherited from the
Elements collection, click the Security link. For more information, see Configure security for objects.
13. Click OK and check in your work.

Edit PI AF models
You view or edit PI AF models in the <Model Name> Connections window.
1. Right-click on a model in the Elements browser and click Model Connections.
 The <Model Name> Connections window shows a visual representation of the elements in the model and
how they are connected.
2. To edit the model:
▪ Right-click an element in the Connections pane to create a new connection or to view or edit the
properties of the element.
▪ Click an element to center it in the Connections pane and show any other connected elements. You can
move along the flow of the model this way, element by element.
▪ Click a connection to view or edit the connection or to add another source or destination.
▪ Right-click a connection to make another connection, view the properties of the selected connection, or
to copy and paste the properties of the connection.

Ports and connections

Elements in a model are connected through any number of ports, which are defined by the element template. A
port can be defined as an input port, an output port, or as an undirected port. The port defines how many
connections can be made and the types of elements that can be connected.
In analyses, directed ports (input and output ports) represent positive material flow and are used by
connections. Undirected ports are used by attachments of meters and analyzers. The most common type of
attachment in a model is a measurement or meter attached to a flow element.
A connection represents the link between the ports of two elements. The ports, which are defined by the
element template, can be defined as input ports, output ports, or undirected ports.

Create ports
To specify a port as the default port, you must open the Properties window.
1. In the Elements browser, select an element and then click the Ports tab in the viewer.
Note: If the element is based on a template, you cannot add a port unless the template allows extensions.
2. Click New Port, and create a port for the element. Right-click an existing port to view or edit its properties.
3. Configure the port.
• Port Type: Select the port type: Input, Output, or Undirected (for meters, for example).
• Allowed Categories: Select the categories of which the port is allowed to be a member.
• Maximum Connections: Specify the maximum number of connections that can be made to the port.
Enter zero for an unlimited number of connections.
• Connection Type: Select the type of element to which the port can connect, for example, Node,
Boundary, Measurement, and so on.
• Allowed Templates: Select elements allowed to connect to the port. Select only elements created from
the selected template.

Create connections
Use the Connections tab to display the connections in a model.
 1. To create a new model in the Elements browser, right-click the collection of elements as described in Create
PI AF models, and click New Model.
2. Follow these steps to fill in the Connections tab.
a. Right-click in the field and select New Connection.
b. In the Make Connection window, right-click an existing connection to view or edit its properties.
c. In the Source field, select the source for the connection. Select the appropriate port of the source in the
corresponding Port field.
d. In the Destination field, select the destination for the connection. Select the appropriate port of the
destination in the corresponding Port field.
To include child elements, select the Include Child Elements check box.

Layers
You can organize the elements of a model into layers. Layers provide a mechanism for including or excluding
portions of the model as needed for analysis. An element of a model can belong to more than one layer. You can
also use the Layers feature with a graphic modeling tool, such as PI ProcessBook, to provide a visual overlay
functionality.

Create layers
Create a Layer to enable you to include or exclude portions of a model.
1. In the Elements browser, select the model to which you want to add a layer.
2. Click the Layers tab in the viewer.
3. Right-click and click New Layer.
4. In the Name field of the Layer Properties window, enter a unique name for the layer.
5. Optional. In the Description field, describe the purpose of the layer.
6. In the element list, select one or more elements that comprise the layer.
7. Click OK.
Chapter 16

PI AF utilities and plug-ins

After you install PI AF, several utilities are available to assist you in your administration of PI AF and management
of plug-ins.

Launch PSE with command line options

The PI System Explorer (PSE) can be invoked with command line options that control its initial selection. The PI
System Explorer application is named AFExplorer.exe and is located in the \PIPC\AF folder.
1. Open a Windows command window and change to the \PIPC\AF folder.
2. Type:
afexplorer parameter=paramValue
where parameter is one of the following three parameters:
• /system
• /database
• /navigator
To display a list of available parameters, type:
afexplorer /?

AFExplorer parameters
The following table lists the available parameters for the AFExplorer utility.

Parameter Description Example

/system Sets the system parameter to the afexplorer /system=MyAFServer

hostname of the PI AF server to
which PSE should connect by
default.
/database Sets the database parameter to the afexplorer /database=MyAFDatabase
name of the PI AF database that
PSE should open initially.
 Parameter Description Example

/navigator Sets the navigator parameter to the afexplorer /navigator=Elements

browser plug-in that should be
selected initially in PSE.
Navigator parameter values
The following table lists the available values for the navigator parameter.

Parameter value Example

Elements afexplorer /Navigator=Elements

EventFrames afexplorer /Navigator=EventFrames
Library afexplorer /Navigator=Library
UnitOfMeasure afexplorer /Navigator=UnitOfMeasure
Analyses afexplorer /Navigator=Analyses
MyPI afexplorer /Navigator=MyPI
Note: Use only if legacy notifications are present on a PI AF client computer.

Notifications afexplorer /Navigator=Notifications

Note: Use only if legacy notifications are present on a PI AF client computer.

AFContactNavigator afexplorer /Navigator=AFContactNavigator

Management afexplorer /Navigator=Management

PI AF Diagnostics utility
The PI AF Diagnostics (AFDiag) utility is a command-line utility that you can use to enable or disable PI AF server
features and perform other administrative functions. The utility makes a direct connection with the associated
SQL Server database and requires the SQL Server sysadmin or db_AFadmin role.
AFDiag is located in the \PIPC\AF folder.

Grant permissions for PI AF Diagnostics utility

To use the PI AF Diagnostics utility, you need to grant the db_AFadmin database role to the SQL Server Login.
1. In the Microsoft SQL Server Management Studio, connect to the SQL Server instance in which the PIFD
database resides.
2. Under the SQL Server instance, expand the Security folder; then expand the Logins folder.
3. Right-click the login that corresponds to the appropriate Windows user and select Properties.
4. Select the User Mapping page.
 5. Select the row for the PIFD database.
6. Select the Map check box for the PIFD database.
7. With the database still selected, select the db_AFadmin database role check box, as shown in the following
figure.

8. Click OK to save your changes and close the Microsoft SQL Server Management Studio.

Run the AFDiag utility

You run the AFDiag utility in an elevated Windows command prompt window.
1. As an administrator, open a Windows command prompt and change directory to \PIPC\AF.
2. Choose one of the following actions.
 To ... Do this ...

Display current configuration settings Type afdiag with no parameter specified.

A list of current settings is displayed for the PI AF
server, database, Active Directory, and other
configuration items such as audit trail, file extensions,
and maximum size for files attached to PI AF objects.
Display a list of available parameters Type afdiag /?
Execute a specific configuration task Type afdiag parameter
where parameter is one of the parameters listed in
AFDiag utility parameters.

AFDiag utility parameters

Parameters for the AFDiag utility are listed in alphabetical order below.
• /ActiveDirectory:string or /AD:string
Tests access to Active Directory using the currently configured settings in the PI AF server. An optional user
account can be specified to test another account. If an account is specified or set in the PI AF server settings,
you also need to specify the Password parameter.
• /AddIdentity:string or /AI:string
Adds a security identity with the specified permissions to all security strings in the system. For example, to
allow read and write access for IdentityName to all security strings, enter:
/AI:"IdentityName:A(r,w)"
If the specified security identity does not exist, it is created. Use PI System Explorer to create and/or
configure mappings to the new identity.
• /AuditTrailCleanupAdd:string or /ATCA:string
Adds the specified user to the audit trail cleanup list. The audit cleanup job deletes audit records associated
with this user from the PI AF SQL Server database.This parameter may be specified more than once.
• /AuditTrailCleanupRemove:string or /ATCR:string
Removes the specified user from the audit trail cleanup list. The audit cleanup job no longer deletes audit
records associated with this user from the PI AF SQL Server database.This parameter may be specified more
than once.
• /CertificateAdd or /CA
Adds the specified client certificate to the PI AF SQL Server database. Use the Password parameter to specify
a password for the certificate, if required.
• /CertificateList or /CL
Lists the client certificates stored in the PI AF SQL Server database.
• /CertificateRemove or /CR
Removes a client certificate from the PI AF SQL Server database by specifying the name of the certificate.
• /CertificateSet:string or /CS:string
Sets the server certificate in the PI AF server configuration file to the specified file. Use the Password
parameter to specify a password for the certificate, if required.
• /ChangeID:string or /CID:string
Changes the ID for the PI AF server to the specified GUID.
• A return value of 1 means that the configuration change will be delayed.
• A return value of 2 means that you must restart the PI AF server.
• A negative return value indicates an error has occurred.
• /ClearChangeTables or /CCT
Clears the findChanges and afdiag tables, which record information on changes to the system.
• /DeleteAuditTrail or /ATD
Disables audit trail feature and deletes audit trail records in the PI AF SQL Server database. This operation
permanently deletes the audit trail records, and requires sysadmin privileges. The audit trail records cannot
be recovered if a delete is performed.
• /DeleteCases:string or /DelC:string
Deletes cases from the PI AF SQL Server database with a start time between the dates specified in local time
format, using standard date notation or PI time syntax (described in PI time). If only one time is provided, it is
treated as the end time.
• To specify a time, include a time string in hh:mm:ss format.
• To specify a database, include a database string in /Database:"DBname" or /DB:"DBname" format.
• To specify a template in a database, include a template string in /Template:"Template Name" or /
Temp:"Template Name"format, in addition to the database string.
For example, to delete cases that start between 11 P.M. on January 31st, 2017 and 4 P.M. on June 21st,
2017, enter /DelC:"2017-01-31 23:00:00";"2017-06-21 16:00:00".
• /DeleteDuplicates or /DD
When used in conjunction with /FindDuplicates, deletes the duplicates that were found in SQL object tables.
It is recommended that you make a backup of the PI AF SQL Server database (PIFD) before you use this
parameter to delete the duplicate entries.
• /DeleteEventFrames:string or /DelEF:string
Deletes event frames from the PI AF SQL Server database with an end time between the dates specified in
local time format, using standard date notation or PI time syntax (described in PI time). If only one time is
provided, it is treated as the end time.
• To specify a time, include a time string in hh:mm:ss format.
• To specify a database, include a database string in /Database:"DBname" or /DB:"DBname" format.
• To specify a template in a database, include a template string in /Template:"Template Name" or /
Temp:"Template Name"format, in addition to the database string.
For example, to delete event frames that end between 11 P.M. on January 31st, 2017 and 4 P.M. on June
21st, 2017, enter /DelEF:"2017-01-31 23:00:00";"2017-06-21 16:00:00".
 Note: Child event frames are also deleted, even if they do not match the criteria.
• /DeleteTransfers:string or /DelTR:string
Deletes transfers from the PI AF SQL Server database with an end time between the dates specified in local
time format, using standard date notation or PI time syntax (described in PI time). If only one time is
provided, it is treated as the end time.
• To specify a time, include a time string in hh:mm:ss format.
• To specify a database, include a database string in /Database:"DBname" or /DB:"DBname" format.
• To specify a template in a database, include a template string in /Template:"Template Name" or /
Temp:"Template Name"format, in addition to the database string.
For example, to delete transfers that end between 11 P.M. on January 31st, 2017 and 4 P.M. on June
21st, 2017, enter /DelTR:"2017-01-31 23:00:00";"2017-06-21 16:00:00".
• /EnableAuditTrail or /AT
Enables audit trail feature for the PI AF SQL Server database.
• /EnableAuditTrailCleanup[-] or /ATC[-]
Enables audit trail cleanup feature for the PI AF SQL Server database. Requires sysadmin privileges.
• /EnableExternalDataTables[-] or /DT[-]
Enables support for external PI AF tables.
• /EnablePropagationOfTargetDeletion[-] or /PTD[-]
Enables support for propagating the deletion of targets (elements) to the referencing analyses and
notifications.
• /ExeFile:string or /F:string
The path to the PI AF server executable file. Default value is AFService.exe.
• /ExternalDataTablesAllowNonImpersonatedUsers[-] or /DTImp[-]
Enables support for external PI AF tables for non-impersonated users.
• @file
Reads response file for more options. The response file must contain one parameter per line. Comment lines
start with the '#' character.
• /FileExtensions:string or /FE:string
Defines the types of file objects that can be attached to a PI AF file object, such as an annotation. The
following file types are supported:
• MS Office: csv, docx, pdf, xlsx
• Text: rtf, txt
• Image: gif, jpeg, jpg, png, svg, tiff
Enter the extensions as a colon-separated list, for example:
/FE:docx:xlsx:csv:pdfd:jpg:png
• /FileExtensionsAdd:string or /FEA:string
 Adds an additional file extension to the list of allowed PI AF file object types. See the list of supported file
types above.
You can specify this parameter more than once.
• /FileExtensionsRemove:string or /FER:string
Removes a file extension from the list of allowed PI AF file object types. See the list of supported file types
above.
You can specify this parameter more than once.
• /FileMaxLength:integer or /FML:integer
Defines the maximum size in megabytes of a PI AF file object, such as an annotation. A value of zero disables
support for all files. The default maximum allowed file size is 10MB.
• /FindDuplicates or /FD
Searches for duplicate entries in all object tables and returns a list of tables. It identifies how many
duplicates were found in each object table and logs them in an XML file. Be sure to make a backup of the PI
AF SQL Server database (PIFD) before you use this parameter in conjunction with the /DeleteDuplicates
parameter to delete the duplicate entries.
Note: Since duplicate rows are unexpected under normal circumstances, contact Technical Support to help
diagnose how the duplicate rows may have been created.
• /NewID or /NID
Generates a new ID for the PI AF server.
• A return value of 1 means that the configuration change will be delayed.
• A return value of 2 means that you must restart the PI AF server.
• A negative return value indicates an error has occurred.
• /Password or /PWD
Specifies a certificate password for the ActiveDirectory, CertificateAdd, CertificateSet, or
PasswordEncryptionCertificate options.
• /PasswordEncryptionCertificate:string or /PEC:string
Replaces the default password encryption for external database passwords with a custom certificate file. Use
the Password option to specify a password for the certificate, if required.
• /PlugInVerifyLevel:level or /VL:level
Configures the level of verification required for plug-ins to run. Valid levels are:
• RequireSigned
Runs only plug-ins with valid signatures.
• RequireSignedTrustedProvider
Runs only plug-ins with a valid signature from a trusted provider.
Note: The None and AllowUnsigned levels are only supported in PI AF Client 2018 SP3 Patch 1 and earlier
versions. (None: Disables validation; runs all plug-ins. AllowUnsigned: Runs unsigned plug-ins and plug-
ins with valid signatures.)
• /Port:integer or /P:integer
Tests the specified port to the PI AF server. This is used to perform a basic port test to see if specified port on
the computer used by the PI AF server can be opened and something is listening for a connection on the
port. The standard ports used by the PI AF server are 5457 and 5459. This is similar to attempting to test a
port using Telnet. It tests all IP addresses for the computer (both IPv4 and IPv6 addresses). Typically, you
would test both ports 5457 and 5459.
• /RebuildPathCache or /RPC
Rebuilds the path cache to each element in the PI AF SQL Server database. The path cache can become
outdated after significant data insertions, edits, and/or deletions. Rebuilding the path cache can improve the
PI AF server’s performance.
Note: The stored procedure used to rebuild the path cache is not supported on a secondary PI AF server (a
subscriber) in a PI AF collective.
• /Reindex or /RI
Completely rebuilds every index in the PI AF SQL Server database. This substantially improves the PI AF
server’s performance after a massive data insertion.
• /ResetAdministrator:string or /SRA:string
Resets the permissions on the Administrators identity to allow full privileges on the local PI System. This
parameter requires sysadmin or db_owner privileges.
The default /sra enables privileges for the BUILTIN\Administrators account.
/sra:domainName\username enables privileges for a particular user account.
• /Silent[-] or /S[-]
Runs silent mode and prevents message display.
• /TrustedProviderAdd:providername or /PA:providername
Adds the specified provider to the list of trusted plug-in providers. To add providers, you must have SQL
Server sysadmin server role or db_AFadmin database role.
• /TrustedProviderList or /PL
Displays a list of trusted plug-in providers. To list providers, you must have SQL Server sysadmin server role
or db_AFadmin database role.
• /TrustedProviderRemove:providername or /PR:providername
Removes the specified provider from the list of trusted plug-in providers. To delete providers, you must have
SQL Server sysadmin server role or db_AFadmin database role.
• /UomCaseSensitive[-] or /UCS[-]
Changes configuration of UOM abbreviations from case insensitive to case sensitive in the PI AF SQL Server
database. When enabled, only a 2015 R2 (v2.7.5) or later PI AF Client can connect.
For more information, see Configuration of case-sensitive UOM abbreviations.
• /UpgradeAuditTrail or /ATU
Upgrades audit trail records in the PI AF SQL Server database. Supports upgrades from PI AF 2.6 or later.
• /Version or /V
 Displays version information.

Audit Trail implementation

You can use the audit trail feature to examine audit trail records in the PI AF SQL database. Once enabled, audit
trail records are created using SQL Server Agent jobs. You can view the audit trail with PI System Explorer.
Requirements
The audit trail feature uses SQL Server Change Data Capture (CDC) to generate an audit trail. CDC is supported in
the following versions of SQL Server:
Version Standard Enterprise Developer ¹ Evaluation ¹

SQL Server 2008

SQL Server 2008 R2

SQL Server 2012

SQL Server 2014

SQL Server 2016 ²

SQL Server 2016 SP1 and later ²

¹
Development system only.
²
Only supported in 2016 and later. For more details on CDC support, see the OSIsoft Knowledge Base article PI AF error: Could not find
stored procedure sys.sp_cdc_parse_captured_column_list.

The audit trail feature has the following additional requirements:

• The SQL Server Agent must be running before you enable the audit trail feature.
• You must be a member of the sysadmin role on the SQL Server that contains the PI AF SQL database.
Enable audit trail
To enable the audit trail feature, you use the AFDiag utility and the EnableAuditTrail (/AT) parameter. For
example:
afdiag /AT
Disable audit trail
To disable the audit trail feature and delete all audit trail records permanently, you must have sysadmin
privileges on the SQL Server. To disable the audit trail feature, you use the AFDiag utility and the DeleteAuditTrail
(/ATD) parameter. For example:
afdiag /ATD
Once you use this parameter, the audit trail is not recoverable.
Previous versions
The audit trail feature that was released in PI AF 2014 or later is supported by this installation and is upgraded
when the PI AF SQL scripts are executed. At that time, the audit trail records are upgraded to the current format.
 If for some reason a failure occurs during the upgrade, you can use the AFDiag UpgradeAuditTrail (/ATU)
parameter to fix the audit trail tables and records.
Versions of the audit trail feature prior to PI AF 2014 have a different format and are no longer updated with new
change records after an upgrade of the PI AF SQL database. Existing tables and data remain intact, but new
records cannot be added.
Audit trail support in SQL Server availability groups
The audit trail feature is supported in SQL Server availability groups. For instructions on how to enable audit trail
on secondary machines in a SQL Server high availability environment, please see the installation topic Use PI AF
Audit Trail in a SQL Server availability group.
Audit trail support in PI AF collectives
The audit trail feature is not supported on secondary members of PI AF collectives. If the audit trail feature is
currently enabled on a server that you wish to add as a secondary server to a PI AF collective, you must run the
AFDiag utility and disable the feature. Audit trail data is only stored on the primary member of a PI AF collective
and is not replicated to any secondary member of a PI AF collective.
Note: When you are designing SQL Server backup procedures for your PI AF data, please be aware that if the
primary member of a PI AF collective becomes unavailable, the audit trail data will also be unavailable. If the
primary member of a PI AF collective cannot be recovered from a backup, the audit trail data cannot be
recovered either.
Re-enabling audit trail
If you add an existing PI AF server with audit trail enabled to a collective as a secondary member, but later
remove that server from the collective, you need to re-enable the audit trail feature on that particular server.
Otherwise, auditing remains disabled.

AF Update Plug-in Configurations utility

The AFUpdatePlugInConfigurations utility provides a Repair, a CreateConfig, and a ReplacePIServer feature that
enable you to perform bulk updates of attribute configuration strings with a single command. After you run the
utility, click in PI System Explorer to see the changes.
The following table lists the available parameters for the AFUpdatePlugInConfigurations utility. Only one feature
can be specified at a time in combination with the /Root, /List, and /EventFrames parameters.

Parameter Description

/Root:string Use in conjunction with /Repair, /CreateConfig, and /Replace parameters.

Specifies the PI AF server or database on which to operate. Enclose the entire
parameter string in quotation marks (" ").
Parameter Description

/Repair[-] Default parameter if no parameter is specified. For attributes on the PI AF server

or database specified in the /Root parameter, corrects PI Point data reference
attributes for which the stored configuration string has become out of
synchronization with the Data Archive. This can occur for the following reasons:
• Deleted PI points: When PI points are deleted and then recreated with the
same name, the ID of the new point does not match the ID in the stored
configuration string.
• Renamed PI points: When PI points are renamed, the stored configuration
string still uses the old PI point name.
• Unresolved attributes: If the PI point to which a data reference points is not
yet created, the stored configuration string does not contain the point ID.
/CreateConfig [-] For attributes on the PI AF server or database specified in the /Root parameter,
creates the PI point if it does not already exist, or updates it with any changes.
This is the same operation as when you right-click an element or attribute in PI
System Explorer and choose Create or Update PI Point.
/ReplacePIServer: string For PI Point data reference attributes on the PI AF server or database specified in
the /Root parameter, redirects attributes to a different Data Archive.
Use a colon (:) to precede the existing Data Archive name. Separate the existing
Data Archive name from the new Data Archive name with a semi colon (;) .
Short form: /Replace
/List [-] Use in conjunction with /Repair, /CreateConfig, and /Replace parameters. For
the PI AF server or database specified in the /Root parameter, lists all attributes
to be operated on.
/EventFrames:string Use in conjunction with /Repair, /CreateConfig, and /Replace parameters.
Performs specified operation on each attribute of all event frame templates and
event frames that occurred between the start and end time specified, format,
using standard international date notation YYYY-MMDD. Use a semi colon to
separate the start and end time.
Short form: /EF
/? or /help Displays list of parameters
@file Uses the specified file to provide additional input arguments. The file should
contain one argument per line. Comment lines start with the '#' character.
/Repair syntax example
To repair stored configuration strings in the specified PI AF database so that they correctly map to the PI points
on the Data Archive, use the following syntax:
afupdatepluginconfigurations "/Root:\\MyAFServer\MyAFDatabase" /Repair
 /CreateConfig syntax example
To perform the CreateConfig operation in bulk on all attributes in a PI AF database, use the following syntax:
afupdatepluginconfigurations "/Root:\\MyAFServer\MyAFDatabase" /CreateConfig
To perform the CreateConfig operation on all attributes on a specific PI AF server, use the following syntax:
afupdatepluginconfigurations "/Root:\\MyAFServer" /CreateConfig
/ReplacePIServer syntax example
To redirect all PI point data reference attributes in a specified PI AF database to a new Data Archive, use the
following syntax:
afupdatepluginconfigurations "/Root:\\MyAFServer\MyAFDatabase"
/ReplacePIServer:OldPIDataArchive;NewPIDataArchive
/EventFrames syntax example
To perform the CreateConfig operation in bulk on all event frame attributes in a PI AF database over a specific
time range, use the following syntax:
afupdatepluginconfigurations "/Root:\\MyAFServer\MyAFDatabase" /EF:"2017-01-31
23:00:00";"2017-06-21 16:00:00" /CreateConfig

Set PI AF server utility

The SetPISystem utility (setpisystem) enables you to configure known PI AF servers. setpisystem is located in the
PIPC\AF directory.

SetPISystem utility parameters

The following table lists the available parameters for the SetPISystem utility.

Parameter Short form Description

/Name:string /N Specifies the name of the PI AF server to modify or

create. If not specified, the default PI AF server is
used.
/Host:string /H Specifies the hostname for the PI AF server.
/Protocol:Tcp|NamedPipe /C Specifies the protocol for the PI AF server.
/Port:integer /P Specifies the port for the PI AF server.
/Timeout:integer /T Specifies the timeout for the PI AF server in seconds.
/AccountName:string /A Specifies the account name for the PI AF server.
/DefaultPISystem /D Sets the specified PI AF server as the default PI AF
server.
/Remove /R Removes the specified PI AF server from the list of
known PI AF servers.
/Silent[-] /S Establishes silent mode, which prevents message
display.
 Parameter Short form Description

/List /L Lists the current known PI AF servers.

/AddAlias:string /AA Adds the specified alias to the PI AF server.
/RemoveAlias:string /RA Removes the specified alias from the PI AF server.

Capture AF SDK event trace output

You use the AFGetTrace utility (afgettrace.exe) to capture event trace output from the AF SDK. Event tracing can
help you debug an application and perform capacity and performance analysis.
Note: Starting with PI AF 2018, the AFGetTrace utility includes a graphical user interface (GUI) that allows you to
configure and view event trace sessions. By default, the AFGetTrace utility runs in GUI mode. To run AFGetTrace
in the old console mode, use the /NoGUI (/NG) switch.
1. Open a command window and change directory to PIPC\AF.
2. Choose from the following actions:
To ... Do this ...

Display syntax and parameters At the command prompt, type:

afgettrace /?

Run AFGetTrace with default settings At the command prompt, type:

afgettrace
Default output goes to standard output.
Run AFGetTrace with specific parameters At the command prompt, type:
afgettrace /parameter
Refer to AFGetTrace utility parameters for details on
the parameters you can use.
Terminate event tracing In the command window, type:
X
Note: If you close the command window without
terminating afgettrace, trace events continue to be
generated, which can slow down your AF SDK
applications.

AFGetTrace utility parameters

The following table lists the available parameters for the AFGetTrace utility.
Parameter Short form Description

/Provider:string /P Specifies the name of the event tracing session. You

only need to specify to use an existing event trace
provider. The default value is AFGetTrace.
/Level:{Critical|Error|Warning| /L Specifies the level of detail to be included in the
Information|Verbose|Detail} events written by the AF SDK. Detail at or above
severity of the level chosen is generated. The default
value is Verbose.
You can specify that only a particular level is written
to the log file:
• Critical: Only Critical events are generated.
• Error: Error and Critical events are
generated.
• Warning: Warning events plus Error and
Critical are generated.
• Information: Information events plus Warning,
Error, and Critical events are generated.
• Verbose: Verbose AF SDK events and
Information PI Data Archive events plus
Information, Warning, Error, and Critical are
generated.
• Detail: Detail AF SDK events and Verbose PI
Data Archive events plus Information, Warning,
Error, and Critical are generated.
Parameter Short form Description

/Keywords:{None|Server|Connection| /K Specifies the keywords used to determine the

Cache|Events|Trace|Data|All} category of events that you want the AF SDK to write.
The default value is All. The AF SDK writes the event
if any of the event's keywords match the keywords
specified in this setting.
You can specify to have one or more keywords
written to the log file:
• None: No events associated with keywords will be
generated. Only Warning, Error, and Critical level
events will be generated.
• Server: Events are logged when calling a remote
method to the PI AF Server or PI Data Archive.
• Connection: Events are logged for PI AF Server or
PI Data Archive connection information.
• Cache: Events are logged for object caching
information.
• Data: Events are logged when making data access
calls.
• Events: Events are logged when raising client
events.
• Trace: Events are logged for AFTrace messages.
• All: Events for all keywords will be generated.
/EnableAF[-] /AF Enables messages from the AF SDK message provider.
The default value is True.
/EnablePI[-] /PI Enables messages relating to communication with the
Data Archive from the MDA message provider. The
default value is True.
/LogFile:string /Log Specifies the name of the log file for trace output
messages. Messages are still displayed on standard
output unless you specify the Silent parameter.
/LogFileMaxSize:double /FileMax Specifies the maximum size of the log file in
megabytes. The trace ends once the size is reached.
Enter 0 for no limit. The default value is 0.
/Timeout:integer /TO Specifies the number of minutes before the trace
ends. Enter 0 for no timeout. The default value is 0.
 Parameter Short form Description

/Mask:string /M Prevents any message containing the specified mask

from being displayed. Enclose the mask in quotes if it
contains spaces. This parameter can be specified
more than once, but values must be unique.
/MaskPID:UInt32 /MPID Prevents any message associated with the specified
Process ID from being displayed. This parameter can
be specified more than once.
Note: This parameter is ignored if the ProcessID
parameter is specified.

/MaskTID:UInt32 /MTID Prevents any message associated with the specified

Thread ID from being displayed. This parameter can
be specified more than once.
Note: This parameter is ignored if the ThreadID
parameter is specified.

/NoGui /NG Specifies that the AFGetTrace utility be launched in

console mode.
/NoHeader[-] /NH Disables header information on each message.
Header information includes the time stamp, process
identifier, and thread identifier.
/ProcessID:UInt32 /PID Displays any message associated with the specified
process ID. This parameter can be specified more
than once.
/ThreadID:UInt32 /TID Displays any message associated with the specified
thread ID. This parameter can be specified more than
once.
/WordWrap /W Word wraps output messages to the width of the
console.
/Silent[-] /S Establishes silent mode, which prevents message
display.

Track PI AF changes with Audit Trail

If Audit Trail is enabled for your system, users with administration privileges can use the utility to view changes
to PI AF objects from all PI AF databases, or to a single object.
Beginning with PI AF 2017 R2, users with administration privileges can right-click an object in the browser or an
object on a list in the viewer and click Audit Trail Events to review audit data specific to that object only.
See Audit Trail implementation for details about enabling the Audit Trail feature.
 Each row in the table of the AF Audit Trail window contains data that identifies a specific change to a PI AF
object. You can double-click a row to view details about that change in the AF Audit Trail Details window.
You can press CTRL+C and CTRL+V to copy and paste rows from either window into another document, such as a
spreadsheet.

Overview of Audit Trail

The Audit Trail feature allows you to review changes to PI AF objects, as well as certain system and security
settings. You must have administrative privileges to turn on or off Audit Trail and view audit information. See
Audit Trail implementation for instructions on how to enable Audit Trail.
Note: Audit Trail requires the use of SQL Server Change Data Capture (CDC), which is a feature of Microsoft SQL
Server. Audit Trail does not capture changes related to enabling or disabling the CDC table.
What is audited?
The following PI AF objects are tracked when Audit Trail is enabled:
• Element objects:
• Databases
• Elements
• Static attribute values that are not data references
• Analyses
• Notifications
• Models
• Event frame objects:
• Event frames
• Transfers
• Cases
• Library objects:
• Templates
• Enumeration sets
• Reference types
• Tables and table connections
• Categories
What user actions are audited?
The following user actions are recorded when Audit Trail is enabled:
• When an AF object is added, modified, or deleted. For example, when an object is renamed or when its
description is changed.
• Changes to the security rights for a system collection, a database collection or an individual object.
• Changes to the UOM database. For example, adding a UOM.
 • Changes to the AF Server. For example, turning on the Audit Trail feature or removing a plug-in.
• When the Audit Trail feature is turned on
• Changes to an AF security certificate (when a certificate is added, modified or deleted)
• When an AF plug-in is added or deleted
• When a trusted AF plug-in provider is added or deleted
• When an AF database is deleted
• When analyses, legacy notifications or notification rules are enabled or disabled
When Audit Trail is enabled, you can view changes that are tracked and also export or copy and paste audit
records to a file. See Review changes with the Audit Trail utility for how to view and export audit trail information
using PI System Explorer.

Review changes with the Audit Trail utility

Only users given administrator privileges to the AF Server can use the Audit Trail utility.
Use the Audit Trail utility to track changes to one or more PI AF objects.
1. Choose from the following actions:
To ... Do this ...

Review changes to PI AF objects in all databases Click Tools > Audit Trail.
Review changes to a single PI AFobject a. Open the database that contains the object
you want to audit.
b. In the navigator, click the object type you
want to audit. For example, to audit a
table, click Library.
c. In the browser, expand the tree until the
object you want to audit is displayed in
either the browser tree or listed in the
viewer.
d. Right-click the object and click Audit Trail
Events.
Review changes to the UOM database a. In the navigator, click Units of Measure.
b. Click File > Audit Trail Events.
2. In the table displayed in the AF Audit Trail window, review changes made to PI AF data. The following
columns are displayed:
Column Description

Date The date and time of the change.

Action The type of change ( Insert, Update, or Delete).
Type The type of object that changed.
Column Description

Database The PI AF database containing the changed object.

Path The hierarchical path to the changed object (when the object is a child of a
parent object, the path shows the parent object).
Name The name of the changed object.
User The user who made the change, in the form of domain\user.
a. You can filter the results shown in the AF Audit Trail window by changing the start and end times:
To ... Do this ...

Adjust the time period a. Change Start Time and End Time to adjust
the time period. You can choose from the
following actions:
Click
• to choose or enter a new date
and/or time.
Click
• to construct a relative time
expression.
b. Click (or press Enter) to display the
updated table.
View changes for a subsequent time period Click .
View changes for a previous time period Click .
Adjust the number of change rows for current time a. In the Maximum field, enter the number of
period records you want returned in the results
list.
b. Click (or press Enter) to refresh the results
in the list.
c. If there are additional records that are not
displayed in the results list, the Next
button appears active. Click Next to
display the next page of records in the
query results.
Note: You can also display additional records by
increasing the value in the Maximum field and then
pressing Enter.
 To ... Do this ...

Filter the returned results a. Click to select a filter type.

b. Enter text in the Filter field.
c. If necessary, click .
The table displays only those rows that
contain your filter criteria.
3. Optional. To view details for a specific row, double-click it.
a. In the AF Audit Trail Details window, review the details of the row you selected. In addition to
Path\Name, Indentity and Date, the following information is displayed:
Column Description

Action Type of change (Insert, Update, or Delete) and the PI AF object sub-object (such
as an attribute or attribute value).
Name The PI AF sub-object; can be blank.
Id The identity of the object referenced in the detail record. The value is either a
GUID or an integer. The identity can be useful in situations where an object is
renamed, since the underlying identity does not change.
Property Name The column name from the SQL table in PI AF SQL Database (PIFD) for the
changed sub-object. This name provides a specific reference to the data within
the record that has been changed.
Old Value The value before the change.
New Value The value after the change.
b. Click Close to return to the AF Audit Trail window.
4. Optional. You can export selected data grid rows or all the rows from the time range (if no rows are selected)
in CSV format:
a. In the Export to File field, enter a name for the export file.
b. Click to open the Save As window and navigate to a specific directory.
c. If you want to export the data from Audit Trail Details window for each selected row, select the Detailed
check box.
d. Click Export All or Export Selected, depending on whether you selected specific rows. (A tooltip
indicates the number of rows selected.)
The status bar initially indicates the total number of rows and then appends the time when the export
completed. Note that while the export is executing, you can cancel it by clicking Cancel Export. The status
bar indicates the time when the export was canceled.
5. To exit the Audit Trail utility, click Close.
View installed plug-ins
You check on installed plug-ins in the PI AF Server Properties window.
1. Select File > Server Properties.
2. In the PI AF Server Properties window, click the Plug-Ins tab.
▪ Move the pointer over a plug-in to see whether it is loaded and the version loaded.
▪ Right-click a plug-in and select Properties to view details, such as the assembly, version, loaded version,
support assemblies, and so on.
Note: The loaded plug-in version usually matches the version on the PI AF server. However, if the version
on the server changes, you must restart PI System Explorer to load the new plug-in version on the server.

Command-line plug-in registration

You can register different Plug-In implementations and support assemblies on the command line, using the
RegPlugIn and RegPlugIn64 utilities. For a list of parameters, see RegPlugIn parameters.
Note: The AF SDK .NET 3.5 is no longer shipped beginning with the release of PI AF 2018 SP3 Patch 2. OSIsoft
recommends all customers migrate to the AF SDK .NET 4 and update their plugins accordingly. OSIsoft has no
plans for additional development work on the .NET 3.5 version of the AF SDK.
The Plug-In registration utilities are located in the \PIPC\AF folders for their corresponding Program Files
directories:
\Program Files\PIPC\AF\RegPlugIn64.exe
\Program Files (x86)\PIPC\AF\RegPlugIn.exe
Examples
In the following examples, MyPISystem is the PI AF server where the Plug-In is to be registered, MyPlugIn.dll is
the name of the Plug-In assembly, and Support.dll is the name of a support assembly for the Plug-In.
• .NET 3.5 Only Plug-In Targeting Any CPU
The simplest to register, this implementation works on any operating system architecture and both versions
of the .NET Framework. It cannot use new features that are specific to the .NET 4 version of AF SDK.
RegPlugIn /PISystem:MyPISystem PlugIns\MyPlugIn.dll
• .NET 4 Only Plug-In Targeting Any CPU
This implementation works on any operating system architecture and the .NET 4 Framework. It does not
work with the .NET 3.5 version of the AF SDK.
RegPlugIn /PISystem:MyPISystem PlugIns\4.0\MyPlugIn.dll
• .NET 3.5 and .NET 4 Plug-In Targeting Any CPU
This Plug-In has two implementations. One targets the .NET 3.5 Framework and works with the .NET 3.5
version of AF SDK, and the other targets the .NET 4 Framework and works with the .NET 4 version of AF SDK.
Both implementations are registered with the following command:
RegPlugIn /PISystem:MyPISystem PlugIns\MyPlugIn.dll PlugIns\4.0\MyPlugIn.dll
• .NET 3.5 Only Plug-In Targeting 32- and 64-Bit Platforms
This Plug-In has two implementations for the .NET 3.5 Framework. One implementation targets 32-bit
operating systems and the other one targets 64-bit operating systems. With both implementations
 registered, the Plug-In works on any operating system architecture and both versions of the .NET Framework,
but cannot use the new features that are specific to the .NET 4 version of AF SDK.
RegPlugIn /PISystem:MyPISystem PlugIns\x86\MyPlugIn.dll
RegPlugIn64 /PISystem:MyPISystem PlugIns\x64\MyPlugIn.dll
• .NET 3.5 and .NET 4 Plug-In Targeting 32- and 64-Bit Platforms
This Plug-In has four implementations. Two implementations are for the .NET 3.5 Framework, one for 32-
and one for 64-bit platforms. The other two implementations are for the .NET 4, one for 32- and one for 64-
bit platforms. With all implementations registered, it works on any operating system architecture and both
versions of the .NET Framework.
RegPlugIn /PISystem:MyPISystem PlugIns\x86\MyPlugIn.dll PlugIns\4.0\x86\MyPlugIn.dll
RegPlugIn64 /PISystem:MyPISystem PlugIns\x64\MyPlugIn.dll
PlugIns\4.0\x64\MyPlugIn.dll
• .NET 3.5 Only Plug-In and Support Assembly Targeting Any CPU
This implementation, with its support assembly, works on any operating system architecture and both
versions of the .NET Framework. It cannot use the new features that are specific to the .NET 4 version of AF
SDK.
RegPlugIn /PISystem:MyPISystem PlugIns\MyPlugIn.dll PlugIns\Support.dll
• .NET 3.5 and .NET 4 Plug-In and Support Assembly Targeting Any CPU
This Plug-In has two implementations with two implementations of its support assembly. One targets
the .NET 3.5 Framework and works with the .NET 3.5 version of AF SDK. The other targets the .NET 4
Framework and works with the .NET 4 version of AF SDK. Both implementations along with their support
assemblies are registered with the following command.
RegPlugIn /PISystem:MyPISystem PlugIns\MyPlugIn.dll PlugIns\Support.dll
PlugIns\4.0\MyPlugIn.dll PlugIns\4.0\Support.dll

RegPlugIn parameters
The following table lists available parameters for the RegPlugin utility.

Parameter Short form Description

/PISystem:string /P Specifies the PI AF server to process. If not specified,

the default PI AF server is used.
/OutputFile:string /O Specifies an output file. If specified, a SQL script is
generated to create Plug-Ins. Use the AppendFile
parameter to append to an existing file.
/AppendFile[-] /A Used in conjunction with the OutputFile parameter,
specifies whether to append to an existing output file.
/List /L Lists registered assemblies in the specified PI AF
server.
Parameter Short form Description

/Recursive[-] /R Automatically processes support assemblies in

subdirectories based upon assembly and directory
names. Use the RootDirectory parameter to specify a
root directory that is different than the current
working directory.
/Force[-] /F Forces registration of assemblies that are older than
currently registered assemblies or forces the
deregistration of assemblies that do not appear to be
registered.
/Silent[-] /S Silent mode. Prevents messages from being
displayed.
/Unregister /U Removes assembly and plug-ins from the specified PI
AF server.
/RegFile:string /RF Creates a registration XML file for the specified
assembly that can be used to register a plug-in
assembly and all its related support assemblies. Any
additional files specified are treated as support
assemblies.
/Version /V Displays version information. All other parameters are
ignored.
/User:string /user Specifies a different Windows user account to
connect to the PI AF server.
/Password:string /PW Used in conjunction with the User parameter,
specifies the password of a different Windows user
account to connect to the PI AF server.
/Owner:string /Own Provides the owner file name of all specified support
assemblies. Normally used with the Directory
parameter when registering support assemblies. By
default, the directory name will be determined
relative to the RootDirectory parameter or current
working directory if the root directory is not specified.
/Directory:string /Dir Provides the directory name for all specified support
assemblies. Normally used with the Owner parameter
when registering support assemblies. By default, the
directory name is determined relative to the
RootDirectory parameter or current working directory
if the root directory is not specified.
 Parameter Short form Description

/RootDirectory:string /RootDir Registers all assemblies relative to the specified root

directory name. Normally used with the Recursive
parameter when registering assemblies instead of
using the Directoryparameter. By default this
parameter is set to the current working directory.
/Exclude:string /E Specifies input files or directories to exclude when
searching a directory for files. You can specify this
parameter more than once, but values must be
unique.
files Specifies the input assembly files, registration files, or
directories to process. You can use the following
wildcard specifiers to filter files processed in
directories:
• '*' matches zero or more characters
• '?' matches exactly one character
You can also use the Exclude parameter to filter
the processed files.
@file Provides additional input parameters to the specified
file. The file should contain one parameter per line.
Comment lines start with the '#' character.
/?, /help Displays these option descriptions.

Create an XML registration file

Note: The AF SDK .NET 3.5 is no longer shipped beginning with the release of PI AF 2018 SP3 Patch 2. OSIsoft
recommends all customers migrate to the AF SDK .NET 4 and update their plugins accordingly. OSIsoft has no
plans for additional development work on the .NET 3.5 version of the AF SDK.
For complex or frequently-executed registrations, you can create an XML file that contains the required settings.
To create the XML file, invoke RegPlugin, specifying both the required settings and the XML file name using the /
RegFile: (/RF:) parameter.
Example
To create an XML file that registers a .NET 3.5 and .NET 4.0 version of MyPlugIn.dll, issue the following
command:
RegPlugIn /RF: PlugIns\MyPlugIn.dll PlugIns\4.0\MyPlugIn.dll
The resulting registration file can be edited to supply any additional information required for the registration of
the plug-in (not normally necessary). For 64-bit plug-ins, the registration file must be edited to set
LoadProperties to x64 and ensure that Directory is set to x64:
<SupportAssembly>
<FilePath>x64\AFDRTest32Bit64Bit.dll</FilePath>
<ID>1e00000c-3228-366a-3809-737433324269</ID>
 <Name>AFDRTest32Bit64Bit</Name>
<Description>AFDRTest32Bit64Bit.dll Support Assembly</Description>
<Directory>x64</Directory>
<LoadProperties>x64</LoadProperties>
</SupportAssembly>
To register both implementations using the registration file, issue the following command:
RegPlugIn /PISystem:MyPISystem MyPlugIn.xml

Create an SQL registration script

To create an SQL registration script, invoke the RegPlugIn utility, specifying the required details and the /
OutputFile or /AppendFile parameter. The resulting script can be loaded into the SQL database using SQL Server
Management Studio or executed from a command line using the sqlcmd utility, enabling you to install plug-ins
on machines where the PI AF SDK is not installed.
Note: For plug-in developers: The SQL script needs to be generated every time you compile a new version of the
plug-in.
Note: The AF SDK .NET 3.5 is no longer shipped beginning with the release of PI AF 2018 SP3 Patch 2. OSIsoft
recommends all customers migrate to the AF SDK .NET 4 and update their plugins accordingly. OSIsoft has no
plans for additional development work on the .NET 3.5 version of the AF SDK.
Example
For example, to create a script that registers a NET 3.5-only Plug-In targeting any CPU, issue the following
command:
RegPlugIn /O:MyPlugIn.sql PlugIns\MyPlugIn.dll
To generate an SQL registration script named MyPlugIn.sql that registers two implementations of MyPlugIn,
a .NET 3.5-only Plug-In targeting x86 and x64, issue the following commands:
RegPlugIn /O:MyPlugIn.sql PlugIns\x86\MyPlugIn.dll
RegPlugIn64 /A:MyPlugIn.sql PlugIns\x64\MyPlugIn.dll
To generate an SQL registration script from a previously-created XML registration file, specify the XML file name
on the command line. For example:
RegPlugIn /O:MyPlugIn.sql MyPlugIn.xml

Register plug-ins with generated SQL scripts

You register a plug-in from Microsoft SQL Server Management Studio or from the command line.
1. Launch Microsoft SQL Server Management Studio.
2. Choose File > Open > File
3. Browse to the script and load it.
4. Execute the script.
5. To run the script from the command line, invoke the sqlcmd utility, specifying the -i inputfile option with the
path and name of the SQL script as inputfile and the connection settings required to connect to the database
server.
Plug-in provider management
By default, you can run PI AF plug-ins from any provider. For increased security, you can configure PI AF so that
only plug-ins from trusted providers are allowed to be loaded and executed in the client application (PI AF server
2.5 and higher). Plug-in providers are encouraged to code-sign their plug-ins using Authenticode technology. You
control how plug-in security is enforced by setting the verify level.
Verification level
You can display the verification level used when plug-ins are loaded by issuing the afdiag command with no
parameters. The verification level is listed in the Configuration Settings section of the resulting output as
PluginVerifyLevel.
/PlugInVerifyLevel parameter
You set the verify level with the afdiag command, and specify the /PlugInVerifyLevel parameter. Valid levels are:
• None: Disable validation; run all plug-ins. This level is only supported in the PI AF Client 2018 SP3 Patch 1 and
earlier versions.
• AllowUnsigned: Run unsigned plug-ins and plug-ins with valid signatures. This level is supported only in the
PI AF Client 2018 SP3 Patch 1 and earlier versions.
• RequireSigned: Run only plug-ins with valid signatures.
• RequireSignedTrustedProvider: Run only plug-ins with a valid signature from a trusted provider.
Other AFDiag parameters for managing plug-in providers
The following afdiag parameters are available to manage plug-in providers:
• Display a list of trusted providers: /TrustedProviderList
• Add a trusted provider: /TrustedProviderAdd:providername
• Remove a trusted provider: /TrustedProviderRemove:providername
For more information on these parameters, see AFDiag utility parameters. You can locate the provider name by
viewing the digital signature for the plug-in DLL, as described in Locate the names of trusted providers.

Locate the names of trusted providers

Determine the name of a trusted provider of a plug-in DLL by viewing the details of its digital signature. The
string for the trusted provider name must be contained in the certificate's subject.
1. Right-click the plug-in DLL and click Properties.
2. In the Properties window, click the Digital Signatures tab. (If the plug-in is unsigned, this tab is absent.)
3. Select a Name of signer in the Signature list and click Details.
4. In the Digital Signature Details window, click View Certificate.
5. In the Certificate window, click the Details tab and scroll to the Subject field.
The value displayed for this field is the name of the trusted provider. You can you use any subset or the
whole name of any of the names that are part of the subject as the <providername> variable for the /
TrustedProviderAdd and /TrustedProviderRemove parameters.