---

name: matlab-find-pi-assets description: > Find and query PI assets using MATLAB's Industrial Communication Toolbox. Two paths: (1) direct PI tag lookup via piclient + tags when user provides a tag name or description (R2022a+), (2) Asset Framework navigation via afclient when user needs element/attribute hierarchy (R2026a+). Use when working with PI AF servers, PI Data Archive tags, asset hierarchies, element templates, attribute lookup, or historical data from OSIsoft PI systems. license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.0"

PI Asset Identification & Data Query

Connect to PI systems, locate assets, and read historical data using MATLAB's Industrial Communication Toolbox wrappers — not raw .NET SDK interop.

Release Requirements

Workflow	Minimum Release	Functions
A: PI Data Archive (tag lookup)	R2022a+	piclient, tags, read (piclient)
B: PI Asset Framework (AF navigation)	R2026a+	afclient, findElementByName, getAttributes, readHistory, etc.

When to Use

• User wants to find or query PI Asset Framework elements or attributes
• User provides a PI tag name or tag description and wants to look it up
• User needs historical data from a PI AF attribute or PI tag
• User mentions PI AF server, PI Data Archive, OSIsoft, AVEVA PI, or asset hierarchy
• User wants to list elements by template (e.g., "all generation units")

When NOT to Use

• Creating or modifying AF elements/templates (administration)
• Real-time streaming, event frames, or notifications
• PI Vision or PI Web API access
• Writing data back to PI AF or PI Data Archive

Decision Logic

Choose the workflow based on what information the user provides:

User provides	Workflow	Entry function
A PI tag name (e.g., "GU1.ActivePower")	A: Direct Tag Lookup	piclient → tags
A tag description or partial tag name	A: Direct Tag Lookup	piclient → tags
An element name, template, or attribute in AF	B: AF Navigation	afclient
A request to browse/explore the asset hierarchy	B: AF Navigation	afclient

If unclear, ask the user: "Do you have a specific PI tag name, or do you need to navigate the Asset Framework hierarchy?"

Workflow A: Direct Tag Lookup (R2022a+)

Use when the user provides a PI tag name or description.

1. Identify PI Data Archive server (MUST ask user) — If the user has not specified a server name, run the PI server discovery pattern (see Discover Available PI Data Archive Servers) to enumerate available servers. If no servers are found, inform the user that no PI Data Archive servers are discoverable on the host machine and ask them to provide the server name manually. If servers are found, you MUST present the list to the user and ask them to select a server — never auto-select or assume which server to use. Include descriptions (if available) and a "None of these" option. If the user selects "None of these", ask them to provide the server name manually. Do not proceed to the next step until the user has confirmed a server.

2. Connect — piObj = piclient('serverName')

3. Search for tags — tagList = tags(piObj, Name='pattern*') using the name or description the user provided

4. Present results — Show the matching tags to the user for confirmation. tags() returns a table with a Tags column (string array).

5. Read data — Extract the tag name with tagName = tagList.Tags(N), then choose based on what the user asked:

   • Current value or no time range specified: data = read(piObj, tagName) — returns the snapshot/current value of the tag
   • Historical data with time range: data = read(piObj, tagName, DateRange=[start end], Interval=..., AggregateFcn=...)

   If the user says "get the value", "what is the current reading", or requests data without specifying a date range, use read(piObj, tagName) without DateRange.

Workflow B: Asset Framework Navigation (R2026a+)

Use when the user needs to navigate the element/attribute hierarchy.

1. Identify AF server (MUST ask user) — If the user has not specified a server name, run the AF server discovery pattern (see Discover Available AF Servers) to enumerate available servers. If no servers are found, inform the user that no AF servers are discoverable on the host machine and ask them to provide the server name manually. If servers are found, you MUST present the list to the user and ask them to select a server — never auto-select or assume which server to use. Include descriptions (if available) and a "None of these" option. If the user selects "None of these", ask them to provide the server name manually. Do not proceed to the next step until the user has confirmed a server.

2. Connect — afObj = afclient('serverName')

3. Clarify database (MUST ask user) — Use listDatabases(afObj) to show available databases and you MUST ask the user to select one — never auto-select or assume which database to use, even if only one database exists. listDatabases returns a string array of names only — to show descriptions alongside names, use the .NET SDK fallback (see List Databases with Descriptions). If the user is unsure which database contains their element, run the cross-database search pattern (see Search for Element Across All Databases) to find the correct database. Do not proceed to the next step until the user has confirmed a database. Once identified, connect with selectDatabase(afObj, dbList(N)) or afObj = afclient('serverName', Database='dbName').

4. Find elements with disambiguation — Always use a wildcard search to discover related elements:

   • Search: results = findElementByName(afObj, 'baseIdentifier*') where baseIdentifier is the shortest identifier the user mentioned (e.g., 'GU1' from "GU1 generator")
   • By template (if searching by type): elems = findElementByTemplate(afObj, 'templateName')
   • By path (when full path is known): elem = findElementByPath(afObj, "\\server\database\path\to\element") — MUST use string (double-quoted), NEVER char (single-quoted) — char input silently fails and returns an error even when the path is correct

   Always present results for user confirmation: Regardless of how many elements are returned, present a table to the user showing Name, Template, Description, hierarchy path using arrow notation (e.g., Flynn River Hydro->Flynn I->GU1->GU1 Generator — strip \\server\database\ prefix and join with ->), and NumChildren. Ask the user to confirm which element they mean. If the user asks for more detail, use getChildren or getAttributes on a specific element to help them navigate. Only proceed once the user confirms.

5. Get attributes and confirm — Use getAttributes(elem, 'attributeName*') with a wildcard name filter. If only one attribute matches and it clearly corresponds to the user's request, proceed directly. Important If multiple attributes match or there is ambiguity (e.g., "Active Power" vs "Active Power Generated", or multiple attributes with the same name from different elements), present the matching attributes in a table showing Name, ElementName, ServerDataType, DefaultUnit, HasTimeSeriesData, and Description — then ask the user to select the correct one(s). The element name and data type help the user distinguish between identically-named attributes on different elements.

6. Validate attribute — After the user confirms an attribute, perform these checks before reading data:

   • Verify parent element: Confirm attr.ElementName matches the user's intended asset. For full hierarchy verification, use attr.Path (format: \\server\database\...\element|attribute) — when displaying to the user, strip the \\server\database\ prefix and join with -> (e.g., Flynn River Hydro->Flynn I->GU1->GU1 Generator|Active Power). If the element suggests a different asset than what the user asked for (e.g., a similarly-named attribute on a sibling element), flag this to the user before proceeding.
   • Check time series availability: If the user requested historical/range-based data and HasTimeSeriesData is false, inform the user that the selected attribute does not contain time series data and ask whether they would still like to proceed with reading the current value instead.

7. Read data — Choose based on what the user asked:

   • Current value or no time range specified: data = read(attr) — returns the snapshot/current value of the attribute
   • Historical data with time range: data = readHistory(attr, startTime, endTime, Interval=hours(1), AggregateFcn="average")

   If the user says "get the value", "what is the current reading", or requests data without specifying a date range, use read(attr).

8. Verify — Check that returned data has valid status (not all "Bad" or NaN)

Key Functions

See references/key-functions.md for the full function table, attribute properties, and return types.

Patterns

Discover Available AF Servers

NET.addAssembly('OSIsoft.AFSDK');
ps = OSIsoft.AF.PISystems;
numServers = ps.Count;
if numServers == 0
    fprintf('No AF servers discovered on this machine.\n');
else
    fprintf('Available AF Servers:\n');
    for i = 0:numServers-1
        serverName = string(ps.Item(i).Name);
        desc = string(ps.Item(i).Description);
        fprintf('  %d. %s\n', i+1, serverName);
        if strlength(desc) > 0
            fprintf('     Description: %s\n', desc);
        end
    end
end

If numServers == 0, ask the user to provide the AF server name manually — no servers are discoverable on the host machine.

Discover Available PI Data Archive Servers

NET.addAssembly('OSIsoft.AFSDK');
piServers = OSIsoft.AF.PI.PIServers;
numServers = piServers.Count;
if numServers == 0
    fprintf('No PI Data Archive servers discovered on this machine.\n');
else
    fprintf('Available PI Data Archive Servers:\n');
    for i = 0:numServers-1
        serverName = string(piServers.Item(i).Name);
        desc = string(piServers.Item(i).Description);
        fprintf('  %d. %s\n', i+1, serverName);
        if strlength(desc) > 0
            fprintf('     Description: %s\n', desc);
        end
    end
end

If numServers == 0, ask the user to provide the PI Data Archive server name manually — no servers are discoverable on the host machine.

Direct Tag Lookup by Name

piObj = piclient('myPIServer');
tagList = tags(piObj, Name='GU1*');
disp(tagList)

tags() returns a table with a Tags column (string array). Extract a tag name with tagList.Tags(N) before passing to read().

Read Current Value from PI Tag

Use when the user asks for the current/snapshot value of a PI tag without specifying a time range.

piObj = piclient('myPIServer');
tagList = tags(piObj, Name='GU1.Active Power*');
tagName = tagList.Tags(1);
data = read(piObj, tagName);
disp(data)

Read Historical Data from PI Tag

piObj = piclient('myPIServer');
tagList = tags(piObj, Name='GU1.Active Power*');
tagName = tagList.Tags(1);
startTime = datetime(2025, 1, 1);
endTime = datetime(2025, 2, 1);
data = read(piObj, tagName, DateRange=[startTime endTime], ...
    Interval=hours(1), AggregateFcn="average");
disp(data)

AF Connection with Server and Database Clarification

afObj = afclient('myAFServer', Database='OSIDemo_PG_HydroPlant');
fprintf('Connected to: %s\n', afObj.ServerName);
fprintf('Database: %s\n', afObj.Database);

List Databases with Descriptions

Use after connecting to an AF server to present databases. listDatabases returns a string array of database names (no descriptions). To show descriptions alongside names, use the .NET SDK fallback below.

afObj = afclient('myAFServer');
dbList = listDatabases(afObj);
fprintf('Available Databases on %s:\n', afObj.ServerName);
for i = 1:numel(dbList)
    fprintf('  %d. %s\n', i, dbList(i));
end

To retrieve descriptions (requires .NET AFSDK):

NET.addAssembly('OSIsoft.AFSDK');
ps = OSIsoft.AF.PISystems;
afServer = ps.Item('myAFServer');
afServer.Connect();
fprintf('Available Databases on %s:\n', string(afServer.Name));
for i = 0:afServer.Databases.Count-1
    db = afServer.Databases.Item(i);
    dbName = string(db.Name);
    desc = string(db.Description);
    fprintf('  %d. %s\n', i+1, dbName);
    if strlength(desc) > 0
        fprintf('     Description: %s\n', desc);
    end
end

Find Elements by Template

afObj = afclient('myAFServer', Database='OSIDemo_PG_HydroPlant');
genUnits = findElementByTemplate(afObj, 'GenerationUnit');
disp(genUnits)

Find Element with Wildcard and Confirm

Always wildcard the base identifier to discover parent and child elements. Present results for user confirmation — even when only one element is found.

afObj = afclient('myAFServer', Database='OSIDemo_PG_HydroPlant');
results = findElementByName(afObj, 'GU1*');
fprintf('Found %d element(s) matching "GU1*":\n', numel(results));
for i = 1:numel(results)
    pathParts = split(results(i).Path, '\');
    hierarchy = strjoin(pathParts(4:end), '->');
    fprintf('  %d. %s  [Template: %s]  Path: %s\n', ...
        i, results(i).Name, results(i).Template, hierarchy);
    if strlength(results(i).Description) > 0
        fprintf('     Description: %s\n', results(i).Description);
    end
end
fprintf('Which element would you like to proceed with?\n');

After the user confirms (e.g., element 2 = "GU1 Generator"), get attributes with a wildcard and show metadata:

selectedElem = results(2);
attrs = getAttributes(selectedElem, 'Active Power*');
fprintf('Matching attributes on "%s":\n', selectedElem.Name);
fprintf('  %-4s %-20s %-20s %-14s %-14s %-10s %s\n', ...
    '#', 'Name', 'Element', 'ServerDataType', 'Unit', 'TimeSeries', 'Description');
for i = 1:numel(attrs)
    desc = attrs(i).Description;
    if strlength(desc) == 0
        desc = "(none)";
    end
    fprintf('  %-4d %-20s %-20s %-14s %-14s %-10d %s\n', ...
        i, attrs(i).Name, attrs(i).ElementName, attrs(i).ServerDataType, ...
        attrs(i).DefaultUnit, attrs(i).HasTimeSeriesData, desc);
end

If only one attribute matches and it clearly corresponds to the user's request, proceed directly. If multiple attributes match or there is ambiguity (including multiple attributes with the same name from different elements), present the table above and ask the user to select. The ElementName and data type help distinguish identically-named attributes.

Note: Attribute names may differ between parent and child elements (e.g., GU1 has "Active Power Generated" while GU1 Generator has "Active Power"). A wildcard query may also return the same attribute from multiple sibling elements (e.g., all generators in a wind farm). Use the ElementName column to disambiguate.

Find Element by Name (Single Result)

Even when only one match is returned, present it for user confirmation before proceeding.

afObj = afclient('myAFServer', Database='OSIDemo_PG_HydroPlant');
results = findElementByName(afObj, 'GU3 Turbine*');
fprintf('Found %d element(s) matching "GU3 Turbine*":\n', numel(results));
for i = 1:numel(results)
    pathParts = split(results(i).Path, '\');
    hierarchy = strjoin(pathParts(4:end), '->');
    fprintf('  %d. %s  [Template: %s]  Path: %s\n', ...
        i, results(i).Name, results(i).Template, hierarchy);
end
fprintf('Proceed with this element?\n');

After confirmation:

elem = results(1);
attr = getAttributes(elem, 'Active Power');
fprintf('Name: %s\n', attr.Name);
fprintf('Unit: %s\n', attr.DefaultUnit);
fprintf('Has Time Series: %d\n', attr.HasTimeSeriesData);

Read Current Value from AF Attribute

Use when the user asks for the current value, snapshot, or data without specifying a time range.

afObj = afclient('myAFServer', Database='OSIDemo_PG_HydroPlant');
results = findElementByName(afObj, 'GU1*');
selectedElem = results(2);
attr = getAttributes(selectedElem, 'Active Power');
data = read(attr);
disp(data)

Historical Data Read with Aggregation

afObj = afclient('myAFServer', Database='OSIDemo_PG_HydroPlant');
elem = findElementByName(afObj, 'GU3 Turbine');
attr = getAttributes(elem, 'Cooling Water Output Temperature');

startTime = datetime(2025, 1, 1);
endTime = datetime(2025, 2, 1);
data = readHistory(attr, startTime, endTime, Interval=hours(1), AggregateFcn="average");
disp(data)

Verify Data Quality

readHistory and read return a table with a Status column. Check for "Bad" status before using the values:

badRows = data.Status == "Bad";
if all(badRows)
    warning('All returned data has "Bad" status — no valid values in this time range.');
elseif any(badRows)
    fprintf('%d of %d rows have "Bad" status.\n', sum(badRows), height(data));
end

Value column types differ by source:

• AF (readHistory, read(attr)): Value is a cell array — use cell2mat(data.Value) to extract numeric values, or index with data.Value{i}
• PI Data Archive (read(piObj, tagName, DateRange=...)): Value is a double array (direct numeric access)
• PI Data Archive current (read(piObj, tagName) without DateRange): Value is a string (e.g., "Pt Created" or the numeric value as text)

Browse Hierarchy with getChildren

afObj = afclient('myAFServer', Database='OSIDemo_PG_HydroPlant');
roots = getRootElements(afObj);
disp(roots)

children = getChildren(roots(1));
disp(children)

Search for Element Across All Databases

Use when the user is unsure which database contains the element they are looking for.

afObj = afclient('myAFServer');
dbList = listDatabases(afObj);
elementName = 'GU1';
foundIn = {};
for i = 1:numel(dbList)
    selectDatabase(afObj, dbList(i));
    results = findElementByName(afObj, elementName);
    if ~isempty(results)
        foundIn{end+1} = dbList(i); %#ok<SAGROW>
    end
end
if isempty(foundIn)
    fprintf('Element "%s" not found in any database.\n', elementName);
else
    fprintf('Element "%s" found in:\n', elementName);
    for i = 1:numel(foundIn)
        fprintf('  %d. %s\n', i, foundIn{i});
    end
end

If the element is found in multiple databases, present the list and ask the user to select the correct one. If not found in any database, ask the user to verify the element name.

Conventions

• Always use afclient for Asset Framework access — never raw .NET OSIsoft.AFSDK interop (exception: server discovery via OSIsoft.AF.PISystems / OSIsoft.AF.PI.PIServers is acceptable)
• Always use piclient for PI Data Archive tag access — never raw .NET interop (exception: server discovery)
• MUST present discovered servers to the user and ask them to select — never auto-select, assume, or skip server selection. Do not proceed until the user confirms a server
• When presenting server or database lists, display descriptions alongside names when available (descriptions require .NET SDK fallback — listDatabases returns names only)
• MUST present discovered databases to the user and ask them to select — never auto-select, assume, or skip database selection (even if only one database exists). Do not proceed until the user confirms a database
• Never assume server name is 'localhost' — ask the user to specify or select from available servers
• MUST use string (double-quoted) for findElementByPath and findAttributeByPath path arguments — char (single-quoted) silently fails. Write findElementByPath(afObj, "\\server\db\path"), NEVER findElementByPath(afObj, '\\server\db\path')
• Use getAttributes(elem, 'name') with the name filter — never retrieve all attributes and string-compare
• Use findElementByTemplate to find elements by type — never manually traverse the hierarchy comparing template names
• Always wildcard findElementByName(afObj, 'baseIdentifier*') to discover both parent and child elements — never search with an exact name only
• Always present element search results (Name, Template, Description, hierarchy path) for user confirmation before proceeding — even when only one element is found
• When multiple attributes match a wildcard or there is ambiguity, present a metadata table (Name, ElementName, ServerDataType, DefaultUnit, HasTimeSeriesData) and ask the user to select — if only one attribute clearly matches, proceed directly
• If the user asks for more hierarchy detail, use getChildren(elem) to show children of a specific element
• Use read(attr) or read(piObj, tagName) (without DateRange) when the user asks for "current value", "get the data", or any request without a time range — use readHistory or read(..., DateRange=...) only when a date range is specified
• Prefer piclient + tags when the user already knows the tag name — do not route through AF unnecessarily

Common Mistakes

Mistake	Why It's Wrong	Correct Approach
Using NET.addAssembly('OSIsoft.AFSDK') for data queries	Verbose, fragile, unnecessary — MATLAB wrappers exist	Use afclient or piclient (AFSDK is only acceptable for server discovery)
Using piclient for AF element queries	piclient is for PI Data Archive tags, not AF hierarchy	Use afclient for element/attribute navigation
Using afclient when user provides a tag name	AF navigation is overkill for direct tag lookup	Use piclient + tags(..., Name=...)
Assuming server is 'localhost'	Server name varies by environment	Ask the user for the server name
Scanning all databases without asking the user first	Resource-intensive and slow on large systems	Ask the user first; only scan all databases if user is unsure
Retrieving all attributes then filtering by string	Inefficient for elements with many attributes	Use getAttributes(elem, 'name') with name filter
Manually traversing hierarchy to find elements by template	Slow and error-prone for deep hierarchies	Use findElementByTemplate(afObj, 'templateName')
Picking a findElementByName result without showing it to the user	Parent and child elements often share name prefixes (e.g., GU1 vs GU1 Generator) — the first match may be the parent when the user means the child	Always wildcard search ('GU1*'), present all results with Template/Path/Description, and ask the user to confirm — even for single results
Proceeding to readHistory without confirming the attribute	Attribute names may differ across elements (e.g., "Active Power" vs "Active Power Generated") and wildcard may return multiple matches — or multiple sibling elements may share the same attribute name (e.g., all generators in a wind farm)	When multiple attributes match or there is ambiguity, show metadata (Name, ElementName, ServerDataType, Unit, HasTimeSeriesData, Description) and ask user to select
Using readHistory when user asks for current value	readHistory requires a time range — overkill for a snapshot value	Use read(attr) for AF attributes or read(piObj, tagName) without DateRange for PI tags; reserve readHistory/DateRange for historical queries
Using char (single-quoted) paths with findElementByPath or findAttributeByPath	These functions silently fail with char inputs — returns "Unable to find" error even when the path is correct	Always use string (double-quoted): findElementByPath(afObj, "\\server\db\path")
Treating listDatabases result as a struct (e.g., dbList(i).Name)	listDatabases returns a string array, not a struct — accessing .Name errors	Use dbList(i) directly: it's already a string. Pass to selectDatabase(afObj, dbList(i))
Using attrs(i).DataType on attributes	Property does not exist on icomm.af.Attribute — errors at runtime	Use attrs(i).ServerDataType for the data type string
Using data.Value directly for math on AF results	AF readHistory/read(attr) returns Value as a cell array — arithmetic fails	Use cell2mat(data.Value) to extract numeric values from AF data

---

Copyright 2026 The MathWorks, Inc.

---