PI System

Connection Settings

Token

The connection token used by the PI System AF SDK Agent to authenticate the Intelligence Hub connection.

Connect Timeout (seconds)

The maximum amount of time to wait for successful connection to the agent. If this time is exceeded the connection fails with an error return.

Request Timeout (ms)

The maximum amount of time to wait for a read or write response. If this time is exceeded the read or write fails with an error return.

Compression

When enabled, communication between the Intelligence Hub and the PI Agent is compressed using GZip. This improves read times in cases where returned payloads are large. For smaller payloads, there may be little or no performance improvement.

PI Agent Authentication

In cases where the PI Agent and the PI Server are on the same Windows Domain, leave this as Windows. In Windows mode the PI Agent authenticates with the PI Server using the Windows credentials used to run the Agent. In cases where the Agent and Server are on different domains use Credentials mode. This mode passes the provided username/password to the PI Server for authentication.

Input Settings

Types

Specifies the type of data to read. The different types are described below.

Type: Asset

The following settings are available for Asset reads. See the Time Settings below for details on historical queries.

Type: Asset Changes

Subscribe to asset changes from the AF Server. This includes new data, changed data, deleted, and late arriving data. The first read browses the assets and all their attributes, and creates a subscription on the PI Agent for each attribute. Sub-sequent reads return point changes since the last read was performed.

Type: Asset Metadata

The following settings are available for Asset Metadata reads.

Query Paging, Include Children, and Include Attributes work the same as the Asset input. See the Asset input for details.

Type: Event Frame

The following settings are available for Event Frame reads.

Query Paging, Include Children work the same as the Asset input. See the Asset input for details.

Type: Point

The following settings are available for Point reads. See the Time Settings below for details on historical queries.

Type: Point Changes

Subscribe to point changes from an archive. This includes new data, changed data, deleted, and late arriving data. The first read creates a subscription on the PI Agent for the points, and sub-sequent reads return point changes since the last read was performed.

Type: Point Browse

The following settings are available for Point Browse read types.

Type: Digital State Table

Reads the digital state sets (digital state tables) defined on the PI Data Archive. Digital points store an integer that maps to a state in one of these sets, so reading the sets themselves is useful when the raw values are sent to a system that has no access to the PI server. As an example, publish the state sets to a data warehouse alongside digital point data so the numeric values can be resolved to their labels.

The following settings are available for Digital State Table reads.

The result is an object keyed by state set name. Each value is the list of states in that set, where value is the integer stored on the point and name is the label assigned to it.

{
  "Modes": [
    { "value": 0, "name": "Manual" },
    { "value": 1, "name": "Auto" }
  ],
  "Phases": [
    { "value": 0, "name": "Idle" },
    { "value": 1, "name": "Running" }
  ]
}

Time Settings

These settings apply to Asset and Point reads, and allow for running queries over a large time range and reading the data in chunks.

Interval Values

The following rules govern which forms are accepted:

• All forms are case-insensitive — d or D, and hour or HOUR, all work.
• Fractional values are allowed only on the clock units (ms, s, m, h) — for example 1.5h (1h 30m), 0.25h (15m), 2.75m, or 1.5s (1s 500ms). The calendar units (d, w, mo, y) must be whole numbers — values such as 1.5d, 0.5d, 1.5w, 1.5mo, and 1.5y are invalid.

The following additional forms are also accepted:

• Clock format HH:MM:SS — for example 1:30:00 or 01:00:00.
• A bare number is interpreted as hours — for example 60 means 60 hours.
• Signed values are supported for relative offsets — for example +60m or -1h.
• A space between the number and unit is tolerated — for example 1 h.

Below is an example configuration. This reads data from 100 days ago until now, in 5 minute intervals, where each read returns one day of data.

Start Time = \*-100d
End Time = \*
Interval = 5m
Time Index = true
Window Size = +1d

Read Points from an Asset Meta Query

Below is an example of Custom Condition code that converts an Asset Meta query into a point list that can be used in a Point read. Using this technique you can read all the points referenced in an AF query, and detect new points when they are added. Note that asset queries are slower than point queries, so it’s recommended to enabled input caching on the Asset Meta query. This avoids making Asset queries for every raw read.

Create a custom condition that references the Asset Meta query, and run it through this condition.

var assets = {{this.currentValue}}
var pointsOut = new Set();

// Get the point name for all attributes assigned to a point.
for (asset of assets){
    if ('attributes' in asset){
        for (attribute of asset.attributes){
            if ('point' in attribute){
                pointsOut.add(attribute.point.name)
            }
        }
    }
}

Array.from(pointsOut);

Output Settings

Types

Specifies the type of write; options include Asset and Points.

Type: Point

Point writes write data as PI points. Arrays and simple types are not supported. Hierarchy is flattened using the parent.child.attribute syntax.

Type: Asset

Asset writes data as PI points, and then builds the templates and element hierarchy inside of PI’s Asset Framework.

Note that if Create is enabled the output updates existing Elements and Templates if there are schema change. All updates are additive, meaning that renaming an attribute will keep the old attribute and add the new one.