PI AF Templates - White Paper

Document created by srobertson on Mar 7, 2015Last modified by ldieffenbach on Jun 1, 2017
Version 3Show Document
  • View in full screen mode

Please refer to the newer version of this paper here: https://pisquare.osisoft.com/docs/DOC-2951-pi-af-templates 



This paper will establish the current best practices for building the PI AF structures for an Enterprise PI AF deployment. This document includes best practices for, but is not limited to:


  • The use of PI AF templates
  • Classifying templates, elements, and attributes templates and analysis templates
  • Using attributes and PI AF data references
  • Working with PI AF administrator tools
  • Using and building PI AF hierarchies
  • Working with existing PI AF elements
  • Working with Event Frames

   Summaries of the key best practices outlined in this paper are: 

  • With the implementation PI Analysis Services within PI AF, PI Analytics should be the first choice for PI System calculations and writing the results to the PI Data Archive. PI ACE and PI Performance Equations should only be used if PI Analytics can not solve the specified use case.

  • When configuring PI Analysis Templates,  results should be configured to write the analytical results to PI Tags.
  • Templates should be utilized for the creation of all elements, event frames, and notifications in order to save implementation effort, decrease maintenance, standardize data, enable easier searching and reporting, and improve performance and scalability.
  • Derived templates should be used to push common attributes into a higher level template in order to save implementation effort and enable cross-asset reporting.
  • It is a best practice to set security at the top levels of the PI AF security model, as all PI AF objects created from that point forward will inherit the security of the parent.
  • All PI AF objects, including templates of all types, elements, notifications, and attributes, should follow a standard naming convention whenever possible, either from an industry standard or an internal standard. This will help users locate data, simplify reporting and analytics, and help streamline data exchanges with 3rd parties.
  • Element categories should be used to separate elements into groups to make it easier for users to locate data in PI System clients and improve the ability of reporting and analytics tools to locate relevant data.
  • Data attributes should be primarily at the top level, with child attributes used primarily for configuration items and parameters of the parent attribute. This will streamline the user experience and ensure that attributes are available in all PI AF clients.
  • Data attributes should be separated into at least a few categories to enhance reporting and searching.
  • If PI tags have not been created, it is a best practice to use PI AF to define the PI tag configuration and create the tags. This applies to normal PI tags as well as calculation PI tags such as PI Performance Equation tags and PI Totalizer tags. This will reduce user error in tag creation as well as enforcing tag naming and configuration standards.
  • When using PI Point data references, the PI tag names in the references should be auto configured based on the template and other configuration attributes. Automating PI tag name generation will streamline element creation and result in less maintenance in the long run in most cases.
  • Once elements containing PI Point data references have been created, it is a best practice to lock in the PI tag referenced by the PI Point data references by using the “Create or Update Data References” function. This will reduce round trips between PI AF clients and the PI System servers resulting in better performance.
  • In addition to PI data references, other data references should be auto configuring where possible, including formula, table lookup, and custom data references.
  • Formula data references are evaluated client-side when they are accessed and are not historized, so it is a best practice to use them primarily for simple calculations that will evaluate quickly when a user loads the element. They should be kept to one level if possible, i.e. not based on the results of other formula data references, as this can cause slow performance. When formula data references perform too slowly, it is a best practice to move them to use PI Analyis Services and historized the results. Other options could include PI ACE to a historized analysis. Using PI Performance Equations PI Tag is an still an option but using a PI Analytic for calculation and historization is the recommend design approach.
  • Use PI Analysis Services and historized results for calculations and Event Frame Triggering. Currently PI Analysis Service can not overwrite historized archive results, PI ACE or PI Performance Equations would be required to update the historized data. For use cases where historized results may require recalculation, the OSIsoft Center of Excellence should be consulted directly.
  • Table lookup data references are primarily intended for configuration items and smaller real-time data sets. Linking an AF table to a large external database and using table lookup data references against it can cause slow performance. It is a best practice to keep table lookup data references against configuration items and smaller real-time data sets (10,000 rows or less).
  • If the external data that needs to be linked or imported to a PI AF table cannot be reduced to less than 10,000 rows by the query, it is recommended to consider bringing the data into the PI Server with the PI-RDBMS interface or PI OLEDB COM Connector.
  • Custom data references are very useful and powerful, but because they are evaluated client side they can cause performance problems. They should always be carefully planned and extensively tested for performance.
  • There are a number of administrator tools available to work with PI AF, including PI System Explorer, PI Builder in Excel, PI AF XML Import/Export, and the PI AF SDK. The best practice approach to working with PI AF is to use a combination of tools, typically starting with PI System Explorer for initial work and testing and moving to PI Builder for bulk operations. In cases where large-scale automation is possible, XML Import/Export and the PI AF SDK can be used.
  • When there is an industry standard governing the relationship between elements, best practice states that at least one hierarchy should be built to meet the standard. This will enable the usage of industry reporting standards and interoperability.
  • When starting to build hierarchies as part of building out the elements structure of the PI AF implementation, it is a best practice to focus on high value areas of the hierarchy first while using “placeholder” elements to leave room for future work in the hierarchy.
  • Building multiple hierarchies using weak references is a best practice when there are multiple use cases that each derives value from different hierarchies.


If PI AF elements need to be synchronized back to the PI MDB for purposes like PI ACE, it is best practice to consider the limitations of the PI MDB in terms of functionality and scalability. It may be necessary to create special PI AF hierarchies to synchronize which contain only the relevant elements, or in cases where elements have many attributes it may be necessary to make smaller duplicates of those elements that contain only the attributes necessary for calculations. For PI AF element synchronization issues refer to the PI Asset Framework Installation and Upgrade Guide, the PI Server 2010 MDB to AF Transition GuideKB00692 - Limitations with MDB to PI AF Synchronization and PI Server 2010 Configuring PI Server Security, Chapter 7,MDB to AF Security Synchronization Considerations.


4 people found this helpful