Search for assets by filtering

Use the Asset Filter Search function to search a PI AF database for elements and to filter the returned elements by attribute value. You can choose to output either the filtered elements or selected attributes of the filtered elements. You can also choose whether to paste the output into the worksheet as static values or as a function array, which can update automatically.

1. Select the upper leftmost cell of the range in the worksheet where you want to insert retrieved assets.

2. On the PI DataLink tab, in the Search group, select Asset Filter to open the Asset Filter Search task pane.

3. In the Root path field, enter the common path to the elements you want to find.

   The common path must contain the server and database, and can contain any parent elements. Specify in the format \\ServerName\DatabaseName\ParentElementName.

   For example, to find elements at the root level of the database MyDatabase on the server MyPIAFServer, enter \\MyPIAFServer\MyDatabase; to find elements under the Boilers element in that same database, enter \\MyPIAFServer\MyDatabase\Boilers.

4. Specify the PI AF elements to retrieve:

   1. From the Element template list, select the template of retrieved elements.

      You must select a template to filter elements based on attribute values. Note that if you select a base template, the function also retrieves elements from derived templates.

   2. In the Element name field, enter the name of elements to retrieve.

      Use wildcard characters to specify part of the name.

   3. From the Element category list, select the category of elements to retrieve.

   4. In the Element description field, enter text found in the description of all elements to retrieve.

      Use wildcard characters to specify part of the description.

   5. Select the Limit to root level check box to only retrieve elements at the level specified in the Root path field. Clear the check box to retrieve child elements as well.

   6. Optional: In the Attribute value filters table, specify conditions for the attribute values of elements to retrieve.

      You must select an element template before specifying any attribute-value condition. You can only filter using values of attributes defined in the selected element template or in a base template of the selected element template.

      You can specify up to five conditions. For each condition, set three fields:

      • From the Attribute list, select an attribute found in elements based on the selected element template.

      • From the Operator list, select the relational operator, such as =, <, or >. For attributes that store string, Boolean, or enumerated values, the only valid operators are = and <>.

      • In the Value field, enter the value to filter for. You can use wildcard characters for string attributes.

      For example, to retrieve elements that have the Manufacturer attribute that starts with ABC and a ZipCode attribute between and including 94102 and 94188, enter three conditions:

      Manufacturer = ABC*

      ZipCode >= 94102

      ZipCode <= 94188

      For best performance, limit attributes to those that have values stored in the PI AF database (that is, omit attributes with data references). If you specify an attribute with a data reference, the function uses the preference setting for maximum filter search count to limit the number of elements searched for matching attribute values. See Manage PI DataLink settings from Excel.

5. Specify the worksheet output:

   1. From the Attributes to display list, select the attributes to include and set the order to display the attributes.

      If you select no attributes, the Asset Filter Search function only returns the matching elements. If you select at least one attribute, the function returns the selected attributes for each element.

      By default, the list includes the attributes in the selected element template. You can:

      • Select the Select all check box to include all the listed attributes.

      • Select a check box to include an attribute, or clear a check box to exclude an attribute.

      • Type the name of an attribute next to the blank check box at the bottom of the list.

      • Select an attribute and select to move the attribute up in the list of displayed attributes.

      • Select an attribute and select to move the attribute down in the list of displayed attributes.

      • Select an attribute and click to remove the attribute from the list of displayed attributes.

   2. Indicate how to paste the matching elements or attributes into the worksheet:

      • Select Column to insert the full path to the elements or attributes into the designated worksheet cells.

      • Select Drop-down list to insert a drop-down list that contains the paths to the attributes (that is, the unique server, database, and parent elements) followed by the selected attributes into the designated worksheet cells.

        Only select Drop-down list if you have selected at least one attribute.

        From another PI DataLink function, you can reference the inserted drop-down list from a Root path field and the attributes from a Data item field to create an asset-relative display: the worksheet will dynamically update the retrieved values when you select a different path in the list. See Asset-relative displays.

   3. Indicate the output format:

      • Select Function array to paste a function array. This is the output format of other PI DataLink functions. With a function array, you can easily update the inputs from the task pane and recalculate the output.

      • Select Values to paste the output as values. You can easily copy values for use elsewhere.

      Tip: Function arrays are particularly useful when the function results change frequently. However, function-array recalculation, which occurs each time you open a worksheet, can be slow. By contrast, values are useful when you do not expect results to change and do not want to wait for function-array recalculation.

   4. Verify that the Output cell field contains the upper leftmost cell of the range in the worksheet where you want to insert returned assets.

6. Select OK to insert the matching elements or attributes into the worksheet and close the task pane.