Skip to content

PI Asset Framework Scanner

Overview

The PI Asset Framework (AF) Scanner is a component of Tycho Data Osprey that connects to your AVEVA PI AF Server to:

  • Discover elements and attributes.

  • Scan metadata and structure for lineage and relationships.

  • Evaluate attribute-level data quality.

This scanner enhances Osprey with asset data models in large industrial deployments with PI Asset Framework. It complements the PI Data Archive scanner to build a full picture of asset health and data structure.

How It Works

Once configured, the scanner connects securely to the AF Server. At scheduled intervals, it:

  1. Authenticates using Windows Identity

  2. Scans AF Server and database structure (elements, attributes).

  3. Scans for Attribute-to-PI Point references for lineage.

  4. Scans Analysis runtime status if scanAnalysisRuntime = true

  5. Uploads results to the Tycho Data Osprey via API.

Collected Information

Data Type Description
AF Server Info AF server name and available databases
AF Hierarchy Elements, attributes, and hierarchy metadata
AF Analysis AF Analyses, input, and output references
Linked Tag Data If linked to PI tags, includes metadata and data quality info
Scan Status Runtime details, including scanner ID, timestamps, and upload results

Limitations

The PI Asset Framework Scanner has the following limitations:

  • Event Frames are not supported: The scanner does not collect or process Event Frame data from PI Asset Framework
  • Templates are not supported: AF templates and template-based configurations are not scanned or analyzed
  • Rollup analysis from attributes on element associated with rollup analysis are not supported: Complex rollup calculations and aggregations performed by AF analyses on element attributes are not captured. Rollup calculations from attributes of children elements are supported.

Preflight

Before running the PI Asset Framework Scanner, ensure the following requirements are met:

Network

  • Port 5457 must be open between the scanner host and the PI Asset Framework server. This is the default port used by PI AF Server for client connections.

Service Account

The scanner requires a user account with Read access to the PI Asset Framework databases it will scan. For initial setup or testing, an individual user account can be used. For production deployments, a dedicated Windows Service Account is recommended.

See Setting Up a Windows Service Account below for detailed steps on granting the required permissions in PI System Explorer.

Preparing authentication user

Running in Production: Set Up a Windows Service Account

When running the scanner in a production environment, it is recommended to set up a dedicated Windows Service Account. This account can be a domain user or a member of an Active Directory (AD) group. The service account (or group) must be granted sufficient permissions to read from PI Asset Framework.

Steps to Grant Permissions in PI System Explorer:

  1. Open PI System Explorer and connect to your AF Server.
  2. Go to the Database Security or Element Security tab for the relevant AF database(s).
  3. Add the service account or AD group (e.g., DOMAIN\ServiceAccount or DOMAIN\OspreyScannerUsers).
  4. Grant at least Read permissions (or higher, if required) to the AF database and elements.
  5. Click OK or Apply to save changes.

Ensure the Windows Service for the scanner is set to run as this account.

Setting Up the Scanner

!!! tip "Recommended: Use the Osprey Scanner Configuration Utility" The easiest way to configure the PI Data Archive scanner is with TychoScannerConfig.exe (Osprey Scanner Configuration Utility). This graphical tool lets you set all parameters, test connectivity, and save your configuration without manually editing any files. It can also generate an API token and register scanners directly with Osprey - so you don't need to log into the Osprey UI to complete those steps. Launch it from the scanner installation directory.

1. Add Scanner in Osprey UI

To set up your PI AF scanner:

  1. Navigate to Scanners in the Osprey left panel.

  2. Click Add Scanner.

  3. Select PI Asset Framework.

  4. Enter a scanner Name (e.g., AF Houston).

  5. Copy the generated Scanner ID. You'll need this in the configuration file.

2. Update Configuration File

Update the appsettings.ini file on the scanner host at:

C:/Users/\<your_user>/Documents/Tycho Data/Osprey/appsettings.ini

A sample file is provided below:

[common]
tychoDataHost = https://tychodata.int/
tychoDataDomainID = 30
tychoDataAPIToken = ${TYCHODATA_OSPREY_APITOKEN}
pathToCert = C:\cert\selfsigned.crt
updateStatus = false
schedule = "*/3 * * * *"

[scan-piassetframework]
scannerId = b0ad3c6e-b069-42ad-95bd-21d87e2ede84
serverName = WIN-N26UUHRC4P9
databaseNames = Terradyne, Pump Monitoring
afUser = ${AF_User}
afPassword = ${AF_Password}
dataQualityLevel = 2
dataQualityStartTime = *-1h
dataQualityEndTime = *
scanAnalysisRuntime = true
performScan = false
upload = true
includeAFServerAsset = true
includeFiltersRegex =
excludeFiltersRegex =

3. Run Scanner

Once your appsettings.ini is configured and your environment variable is set, you're ready to run the PI Asset Framework scanner.

To run manually via PowerShell:

  1. Open PowerShell

  2. Navigate to the folder containing TychoScanner.exe

  3. Run the scanner with:

.\TychoScanner.exe

Configuration File Reference

[common] Section

Key Description
tychoDataHost The base URL of your Tycho Data instance such as https://experience.tychodata.com.
tychoDataDomainID The numeric ID of the domain this scanner belongs to. You can find this ID in /domains. For instance, https://experience.tychodata.com/domains
tychoDataAPIToken The API token used for authenticating with Tycho Data Osprey. Typically set as an environment variable.
pathToCert Path to the SSL certificate used to verify the scanner's identity. Typically not required.
updateStatus If true, the scanner will update its run status via the API (optional feature).
schedule Cron expression that controls when scans run (e.g., "0 * * * *" = once every hour).

[scan-piassetframework] Section

Key Description
scannerId Unique ID assigned by Osprey when you add the scanner
serverName AF Server hostname
databaseNames Comma-separated AF database names to scan
afUser / afPassword Credentials for connecting to AF Server (preferably use environment vars). Not required if running scanner with Windows Impersonation.
dataQualityLevel Depth of attribute-level checks (e.g., 0 = no data quality metrics collected, 1 = basic checks using current value, 2 = standard checks over default 1 day window).
dataQualityStartTime Time window start for scanning PI data (e.g., *-1d). Defaults to *
dataQualityEndTime End time for the scan window (e.g., *). Defaults to *.
scanAnalysisRuntime If true, collects runtime details of AF Analyses
performScan If true, the scanner will collect data and perform checks
upload If true, uploads results to Tycho Data
includeAFServerAsset If true, includes the AF server itself as an asset
includeFiltersRegex Optional regex to include specific elements or templates
excludeFiltersRegex Optional regex to exclude specific elements or templates

Hint: To scan multiple PI Asset Framework server instances, create a new section. The section name must start with scan-pidataarchive. For instance, [scan-piassetframework-napi] or [scan-piassetframework-apac].