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
Type
Specifies the type of data to read. The different types are described below.
| Read Type | Description |
|---|---|
| Asset | Reads the values for one or more assets in AF given an AF query. This includes current value, historical, and more. |
| Asset Metadata | Reads the metadata for one or more assets in AF given an AF query. Metadata includes template definitions, attribute data types, point mappings, and more. |
| Event Frame | Reads one or more event frames from AF given an AF query. |
| Point | Reads point data from the archive. This includes current, historical data, raw data, averages, and more. |
| Point Change | Creates a DataPipe for one or more points, and returns new values, changed values, deleted, and more. |
| Point Browse | Returns point names and metadata given a PI point query. |
Type: Asset
The following settings are available for Asset reads. See the Time Settings below for details on historical queries.
| Setting | Description |
|---|---|
| Database | The AF Database to read from. |
| Query | The AF query to run against the AF Database. This supports the full PI AF syntax used in PI System Explorer. For example PlantB\\Boilers returns all Assets under this part of the tree. Template:Boiler returns all Assets backed by the Boiler template. |
| Get | The type of query to make. Options include Current Value, Interpolated, and Raw Values. Current Value returns the current value of the assets, including all all attributes. Interpolated returns the interpolated values over time, and raw values returns the values at different periods of time. See below for details on the start/end time settings. |
| Attributes | For asset reads, select a subset of attributes to return in the results. When left blank all attributes are returned. This is helpful to speed up queries when assets have many attributes and only a few are required. |
| Include Metadata | Enable this to include information for each asset like the template name, timestamp, etc. |
| Include Children | Enable this to recursively include all child assets in the result. |
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.
| Setting | Description |
|---|---|
| Database | Same as the Asset read. |
| Query | Same as the Asset read. |
| Subscription ID | A unique ID used to track the subscription on the PI Agent. This way the PI agent knows how to update the subscription if the point list changes. The ID should be unique per input and should not be shared across installations. |
Type: Asset Metadata
The following settings are available for Asset Metadata reads.
| Setting | Description |
|---|---|
| Database | The AF Database to read from. |
| Query | The AF query to run against the AF Database. This is the same as the Asset Query. |
Type: Event Frame
The following settings are available for Event Frame reads.
| Setting | Description |
|---|---|
| Database | The AF Database to read from. |
| Query | The AF query for the Events. This supports the full AF query query syntax available in System Explorer. For example \* returns all events, and name:Boiler\* returns all events named Boiler. |
Type: Point
The following settings are available for Point reads. See the Time Settings below for details on historical queries.
| Setting | Description |
|---|---|
| Points | A list of PI points to read. |
| Use Reference | When enabled, PI points are read from another data source like a CSV file or an Asset Meta Query. For example, a PI Point read can be setup to read all PI Points referenced under a given branch of the AF Hierarchy. The reference must return an array of strings, where each string is a point name (ex. ['point1', 'point2']). An example of a Custom Condition is included below to read points from an Asset Metadata Query. |
| Get | The type of query to make. Options include Current Value, Raw Values, and Aggregates. |
| Include Metadata | Includes data type, quality, unit of measure, and other metadata for to point in the read result. |
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.
| Setting | Description |
|---|---|
| Points | Same as the Point read. |
| Use Reference | Same as the Point read. |
| Subscription ID | A unique ID used to track the subscription on the PI Agent. This way the PI agent knows how to update the subscription if the point list changes. The ID should be unique per input and should not be shared across installations. |
| Inactive Timeout MS | This controls how long the subscription is left open with no reads before it is closed by the PI Agent. This exists to prevent the PI Agent from queueing changes forever and running out of memory. This should generally be set to twice the read interval for the input. |
Type: Point Browse
The following settings are available for Point Browse read types.
| Setting | Description |
|---|---|
| Query | The PI syntax query used to retrieve one of more points. For example SIN* returns everything that starts with “SIN”. This is the same syntax supported in native PI tools. |
| Include Metadata | When disabled, the browse result is an array of point names. When enabled, information like the description, data type, unique ID, etc are returned per point. |
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.
| Setting | Description |
|---|---|
| Start Time | Specifies the start time for the query. This uses the standard PI time syntax. Relative and absolute times are supported (ex. *-1h). Absolute times must include a Z at the end to be treated as UTC. |
| End Time | Specifies the end time for the query. The supported formats are the same as Start Time. |
| Interval | Specifies the interval to interpret data samples. For example, 5m, means every 5 minutes. Use this setting to break reads into chunks. As an example, get the average value of a point every 5 minutes over a 1-hour period When left blank the interval defaults to the time range between Start and End Time. |
| Index | When enabled, reads are performed from the Start to the End Time, in window intervals. After each successful read, the last read index is updated and stored to disk so that in the case of a system restart the reads start from where they last ended. Indexing is useful when querying a large amount of historical data. |
| Index Window | Used when indexing is enabled. This is the window size to read on each read request. As an example, with the following settings each read gathers one days' worth of data in 5 minute intervals and reads stop after the full 100 days is read. |
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
Index = true
Window Size = 1dRead 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
Type
Specifies the type of write; options include Asset and Points.
Point
Point writes write data as PI points. Arrays and simple types are not supported. Hierarchy is flattened using the parent.child.attribute syntax.
| Setting | Description |
|---|---|
| Path | Specifies a prefix for the PI points. For example, “myPrefix” will write points as “myPrefix.pointName” |
| Point Name | The point name. If left blank, the point name is derived from the keys in the data. |
| Timestamp | Provides a way to set the timestamp of the write. When left blank, the timestamp will be taken from _timestamp in the outgoing payload. If no timestamp is provided and the payload doesn’t contain _timestamp, the timestamp is set to the time of the write. This setting is used to pull the timestamp from the payload. As an example, {{this.mytimestamp}} pulls the timestamp from a mytimestamp attribute in the data. The timestamp must be in ISO8601 format. |
| Point Delimiter | Sets the delimiter used when flattening point names. By default it’s “.” |
| Update Option | Controls the API call made to insert data into the archive. All PI options are available. |
| Create | When enabled, points are created if they are not found. |
| Point Source | The source assigned to created points. By default this is HB. |
Asset
Asset writes data as PI points, and then builds the templates and element hierarchy inside of PI’s Asset Framework.
| Setting | Description |
|---|---|
| Database | The Database to write the AF Assets to. |
| Path | Specifies the AF path to write to. For example Portland\Shipping writes to the shipping branch. |
| Asset Name | Overrides the element name assigned to elements. By default, when left blank, the element name is taken from the data (ex. Instance name). |
| Timestamp | Same as Point writes. |
| Point Delimiter | Same as Point writes. |
| Update Options | Same as Point writes. |
| Create | When enabled Assets are created in AF. |
| Point Source | Same as Point writes. |
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.