Skip to content

PI Data Archive Scanner

PI Data Archive Scanner

Overview

The PI Data Archive Scanner is a component of Tycho Data Osprey that connects to your AVEVA PI Data Archive to:

  • Scan time-series tag for tag metadata

  • Scan time-series tag data to evaluate tag health

This scanner is ideal for industrial environments that rely on PI System data integrity for operational decision-making. This scanner can work independently or alongside PI Asset Framework (AF) for enhanced context and automation.

How It Works

Once configured, the scanner connects securely to your PI Data Archive server. At scheduled intervals, it:

  1. Authenticates using the PI user account or Windows Identity.

  2. Scans PI tag configuration in bulk

  3. Scans for PI data quality in bulk

  4. Uploads results to the Tycho Data Osprey via API

Collected Information

Data Type Description
PI Data Archive information Metadata on the PI Data Archive
PI Tag Information Tag name, pointsource, engunits, and related metadata
Data quality Metrics PercentGood, Min, Max, Status, and other related metadata
Scan status Runtime details, including scanner ID, timestamps, and upload results

Scan Modes

The PI Data Archive Scanner supports two scanning modes:

Full Scan (Default)

A full scan collects all tag metadata and data quality metrics from the PI Data Archive on every run. This is the default behaviour and requires no additional configuration.

Incremental Scan

Incremental scanning compares asset metadata changes since the last run and only uploads tags that have changed. This reduces the volume of data sent to Osprey and improves performance in large PI environments.

To enable incremental scanning, add the following to your [scan-pidataarchive] section:

incrementalScanEnabled = true
fullScanInterval = 10
  • incrementalScanEnabled - When true, the scanner compares metadata changes before uploading to Osprey.
  • fullScanInterval - Number of incremental runs between forced full scans. A value of 10 means a full scan runs every 10th execution, ensuring Osprey stays in sync even if incremental changes are missed.

Preflight

Before running the PI Data Archive Scanner, ensure the following requirements are met:

Network

  • Port 5450 must be open between the scanner host and the PI Data Archive server. This is the default port used by PI Data Archive for client connections.

Service Account

The scanner requires a user account with sufficient permissions to read from PI Data Archive. For initial setup or testing, an individual user account can be used. For production deployments, a dedicated Windows Service Account is recommended.

The account must have the following PI Data Archive security permissions:

  • Data Security: Read access (required to retrieve tag data values)
  • Point Security: Read access (required to retrieve tag metadata and configuration)

To configure these permissions, use PI System Management Tools (SMT):

  1. Open PI SMT and connect to your PI Data Archive server.
  2. Navigate to Security > Database Security (for point security) and Security > Data Security (for data security).
  3. Add the service account and grant Read access under each.
  4. Click Apply to save.

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

To create and configure your PI Data Archive scanner:

  1. Go to Scanners in the left navigation.

  2. Click Add Scanner.

  3. Choose PI Data Archive.

  4. Enter a scanner Name (e.g., "Houston PI Server").

  5. Once created, copy the Scanner ID shown. You'll need to paste this ID into your local configuration file (see below).

2. Update Configuration File

If you prefer to configure manually, edit the following file on the machine where your scanner will run. See Configuration File Reference for information on each parameter.

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

A sample file is provided below:

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

[scan-pidataarchive]
scannerId = 74ab197c-4f1f-48be-879b-58a8040097cd
serverName = WIN-PI-System
piUser =
piPassword =
dataQualityLevel = 2
pointsource_filter = *
dataQualityStartTime = *-1d
dataQualityEndTime = *
performScan = true
upload = true
incrementalScanEnabled = true
fullScanInterval = 10

3. Run Scanner

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

To run manually via PowerShell:

  1. Open PowerShell

  2. Navigate to the folder containing TychoScanner.exe

  3. Run the scanner with:

.\TychoScanner.exe

The scanner will execute once based on your configuration (e.g., scanning past day's data or via cron schedule). If you've enabled scheduled runs in Task Scheduler or a background job, this command is typically wrapped in an automation script.

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-pidataarchive] Section

Key Description
scannerId Unique identifier for this scanner. Copy this from the Osprey UI after adding the scanner.
serverName Hostname of the PI Data Archive server to connect to.
piUser Username for accessing the PI Data Archive. Typically not recommended (Set up Windows Identity in PI Data Archive and run the scanner with the same Active Directory account).
piPassword Password for the PI user. Typically not recommended.
dataQualityLevel Controls the depth of data quality checks (e.g., 0 = no data quality metrics collected, 1 = basic checks using current value, 2 = standard checks over default 1 day window).
pointsource_filter Wildcard filter for selecting PI points by their pointsource attribute (e.g., *, R*).
dataQualityStartTime Start time for the scan window, relative to now (e.g., *-1d = past day).
dataQualityEndTime End time for the scan window (e.g., *). Defaults to *.
performScan If true, the scanner will collect and evaluate data on each run.
upload If true, scan results will be uploaded to Tycho Data for dashboards and alerts.
incrementalScanEnabled If true, the scanner compares asset metadata changes since the last run and only uploads changed tags. Defaults to false (full scan every run).
fullScanInterval When incremental scanning is enabled, forces a full scan every N runs (e.g., 10 = full scan on every 10th run). Ensures Osprey stays fully in sync.

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

Running the Scanner

Once everything is configured:

  • Launch the scanner executable (TychoScanner.exe) manually, or

  • Schedule it via Windows Task Scheduler or equivalent automation.

The scanner will begin pulling data and uploading checks to Tycho Data Osprey according to your specified schedule. Refer to Automating Scanners if you want to automate this.