Path Syntax (Core Services)

Some PI Web API methods accept AF paths as parameters.

The path is segmented into parts, and each part represents an object or list of objects derived from the AFObject base class. Parts are typically separated with a single backslash (\), with the exception of either an AFAttribute or an AFAttributeTemplate, which use the pipe character (|). Additionally, the PISystem or PIServer portion begins with two backslashes (\\). Depending on the encoding option chosen, each part of the path will contain information on the specific object(s) in that part of the path. That information may consist of the type of collection the object is in, as well either the Name and/or UniqueID of the object or one or more collection filters. There is a default object type for each parent object, therefore the type of collection for the object is only required if it is not the default or a filter is specified. The default collection types are specified in the Default Collection Types table in the AF SDK documentation.

If the collection is specified, then the collection filter or Name and/or UniqueID are enclosed in square brackets ([ and ]). If both the Name and UniqueID are specified, then they are separated by a semicolon (;), and their relative order defines the precedence when used when finding the object (the first one specified has higher precedence). UniqueIDs must include the surrounding curly brackets ({ and }). A single period enclosed in square brackets ([.]) represents the default collection member of the parent object.

A collection filter starts with the at sign (@) followed by the filter name. Multiple filters may be specified and are evaluated in the specified order. The index filter "[@Index=int]" or "[int]" is used to specify the index of the matched object to return and should be the last filter specified. If the index filter is not specified, then the first match is returned if returning a single object. When using the index filter, the first item is at index 1. The Path Filter table below specifies the supported filters. If a filter does not apply to the type of object in the collection, then an object will not be found.

The PISystem starts a fully qualified path and is preceded by two backslashes (\\). The collection name "Systems" is not needed since its location within the path is well known. A relative path starting with "\\." indicates to begin using the same system as the relative object. For example, "\\.\Database2" can be used to reference a database in the same system as the relative object. If the relative object is not specified or the PISystem is not specified as part of the path, then the PISystems.DefaultPISystem will be used.

The AFDatabase is the default object which follows a PISystem. To access other non-database objects off of the system, the collection must be identified (e.g. "\\MySystem\Contacts[JSmith]"). A relative path starting with a single backslash (\), indicates to begin using the same database as the relative object. For example, paths "\Element2" and "\Tables[MyTable]" can be used to reference objects in the same database as the relative object. If the relative object is not specified or the AFDatabase is not specified as part of the path, then the AFDatabases.DefaultDatabase will be used.

The parent is indicated by a double period (..). An example parent path is "..\Element2|Attribute1". The single period (.) represents the current relative object and can be used to create a relative path from itself. When the relative object is an AFAttribute, then the single period followed by a backslash (.\) represents the owning AFBaseElement while the single period followed by a vertical bar (.|) will reference a child AFAttribute. Examples of a self relative path are ".\|Attribute1" and ".|Attribute1|Attribute2" where the specified relative object was an AFAttribute. All other Element reference types will create a relative path from the database: "\Element1\Element2|Attribute1".

For a complete specification of the AF path grammar, see the AF SDK documentation.

Note that when retrieving resources by path, a fully qualified path or a relative path whose defaults imply a fully qualified path is required. Example paths:

\\MySystem\MyDatabase
\\Systems[MySystem]\Databases[MyDatabase]
\\{5c64c379-c182-4f35-8d30-78d8c2f84502};MySystem\{5c64c379-c182-4f35-8d30-78d8c2f84503};MyDatabase
\\MySystem\Databases[MyDatabase]\Elements[@Category=Tutorial]|Volume
Enabling Operational Intelligence