Mastering AFElementSearch for Derived Template Searches in OSIsoft PI System

In the expansive realm of industrial data systems, OSIsoft PI System plays a crucial role in data management and visualization, making it indispensable for industry professionals. One common requirement among users is the ability to efficiently search and retrieve elements based on specific templates, including any derived templates. This necessity is frequently encountered when using the AF (Asset Framework) SDK to manage complex data structures in PI System.

Navigating Template Searches in PI System

The challenge often arises in distinguishing between elements that match a specific template and those that are derived from it. Fortunately, the PI AF SDK offers a powerful tool for this: AFElementSearch. However, as many have discovered, the nuances of its usage can be vexing, particularly when trying to leverage it for templated element searches.

Understanding the Basics

The AF SDK provides the AFElementSearch class, a robust facility for querying elements. One might assume that by using the TemplateName filter within AFElementSearch, all elements based on the specified template, including any derived templates, would be returned. However, this isn't the case. The TemplateName filter specifically matches only the exact template name, excluding any derived templates.

Leveraging the 'Template' Filter

To address this, the key is to utilize the Template filter, which inherently includes elements from both the specified template and its derived templates. This mirrors the behavior of the includeDerived parameter in the older FindElementsByTemplate method, which some users may find familiar.

Here's a brief illustration of how this is structured:

using (AFElementSearch elementSearch = new AFElementSearch(database, "TemplateSearch", "Template:\"YourTemplateName\""))
{
    foreach (AFElement element in elementSearch.FindObjects())
    {
        Console.WriteLine($"Element: {element.Name}, Template: {element.Template.Name}");
    }
}

In this snippet, note the use of Template. It allows the query to fetch elements from the specified base template and any elements derived from said template. This approach efficiently substitutes the multifunctional yet deprecated FindElementsByTemplate method.

The Documentation Conundrum

Despite the logical structure of the new methods, PI System users often cite gaps in the documentation as a hindrance. The details around advanced search syntax and filter nuances are sometimes not as clear-cut as needed. Enhanced documentation and examples that delve deeper into complex search scenarios would significantly aid both novice and experienced users.

PI World talks and additional OSIsoft training provide expansive insights that are currently underrepresented in existing documentation. These resources can be instrumental in unlocking the full potential of the AF SDK’s search capabilities.

Conclusion

In the digital transformation journey of industries using the OSIsoft PI System, understanding and effectively utilizing the AFElementSearch class can enhance operational efficiency and clarity. By selecting the appropriate filters, users can ensure comprehensive data retrieval that accommodates both base and derived element templates. As the documentation evolves, we anticipate a smoother experience for all PI System users, fostering more robust data management strategies.