Setting paths for PI Web Services

Blog Post created by hanyong Employee on May 9, 2013

PI Web Services 2012 added support for searching through PI AF for Elements, Attributes and Event Frames. These features are added in the IPISoap interface that is added only in this release. One parameter that is required in most of these new search methods in IPISoap is RootPath. This essential is used to identify which AF Server and Database you are searching in. If you want to be searching for a subtree instead of the whole database, then you can also use this to specify that. The problem is you might start specifying this path parameter like you would in any other PI System products, like \\myafserver\myafdatabase. But this would not be recognized as a valid path with PI Web Services.


The format for this RootPath parameter is somewhat similar to how you would specify a path to the AF Attribute for reading values in the previous releases.


Referencing our usual NuGreen demo AF Database as an example:




Where the AF Server is piafserver and database name is afdb.


If you want to specify the AF Server and Database to search in, for finding Elements (IPISoap's FindElements method), it is:
af:\\<af server>\<af database>




If you want to specify to search within a specific subtree or element, it is:
af:\\<af server>\<af database>\<path to af element>


For example, I only want the elements that fulfill the name criteria in the subtree under Houston, my path should be:


You can use this simple code snippet for a console application to test this:

private void FindElement()
    PISoapServiceClient sClient = new PISoapServiceClient();
    ElementSearchConstraints constraints = new ElementSearchConstraints();
    constraints.AllowMatchOnDerivedTemplates = true;
    constraints.NameMask = "B-*";
    constraints.RootPath = @"af:\\piafserver\afdb";
    //constraints.RootPath = @"af:\\piafserver\afdb\NuGreen\Houston";

    ElementSearchManner manner = new ElementSearchManner();
    manner.FlatHierarchy = true;

    Element[] elements = sClient.FindElements(constraints, manner);

    foreach (Element e in elements)

For finding path of attributes through PI Web Services, you have to provide a Root Path as well. The difference that I've found out is that you cannot specify a path to just the database. Meaning you have to provide a path to a specific element or a subtree that you want to search:
af:\\<af server>\<af database>\<path to af element>


af:\\piarserver\afdb\NuGreen\Houston\Cracking Process\Equipment\B-210 


Here's a sample code snippet:

private static void FindAttribute()
    PISoapServiceClient sClient = new PISoapServiceClient();

    AttributeSearchConstraints constraints = new AttributeSearchConstraints();
    constraints.NameMask = "Process Feedrate";
    constraints.RootPath = @"af:\\piafserver\afdb\NuGreen";
    //constraints.RootPath = @"af:\\piafserver\afdb\NuGreen\Houston\Cracking Process\Equipment\B-210";

    AttributeSearchManner manner = new AttributeSearchManner();

    string[] attributepaths = sClient.FindAttributePaths(constraints, manner);

    foreach (string path in attributepaths)

If you are searching for Event Frames instead, replace "af:" with "ef:", like:
ef:\\<af server>\<af database>


The reason for using the "ef:" prefix is because for searching Event Frames, PI Web Services is expecting a path to an event frame instead of a element or attribute for the RootPath parameter. This is because you can have setup hierarchy for your events like batch, unit-batch and sub-batch. The RootPath parameter is for you to specify which event frame is the root event that the search runs through. To do that the path format should be:
ef:\\<af server>\<af database>\EventFrames[<name of event>] or
ef:\\<af server>\<af database>\EventFrames[{<GUID of event>}] 


As an example, here's some sample event frames created for this:




Note: If your AF server has Event Frame feature enabled, you can manually create event frames to test this.


If I want to find all event frames in the AF database, I can simply use the path:


But if what I want is limited to just the child event frame of Process Downtime 20130506 I can set the RootPath as:
ef:\\piafserver\afdb\EventFrames[Process Downtime 20130506]


Again a simple code snippet:

private static void FindEventFrames()
    PISoapServiceClient sClient = new PISoapServiceClient();

    EventFrameSearchConstraints constraints = new EventFrameSearchConstraints();
    constraints.NameMask = "*";
    constraints.RootPath = @"ef:\\piafserver\afdb";
    //constraints.RootPath = @"ef:\\piafserver\afdb\EventFrames[Process Downtime 20130506]";
    constraints.RefElementNameMask = "*";
    constraints.SearchRootLevelOnly = false;
    constraints.Start = "*-30d";
    constraints.Template = null;

    EventFrameSearchManner manner = new EventFrameSearchManner();
    manner.UseName = true;

    EventFrame[] efs = sClient.FindEventFrames(constraints, manner);

    foreach(EventFrame ef in efs)

Hopefully this quick introduction of the path format expected in PI Web Services will be helpful for you in using these new search methods introduced in PI Web Services 2012.