- Index

< Previous |  | Next >

# OSIsoft PI Adapters

## Introduction

The TIBCO StreamBase® Adapter for OSIsoft PI allows StreamBase to interact with data from an OSIsoft PI database. The adapters in this set include:

- The OSI PI Snapshot adapter, which is used to access the current value of PI Points (or the values they had over a given time range)

- The OSI PI Summaries adapter, which is used to get summaries (average, min, max, std deviation, and so on) of PI Point values over a given time period

- The OSI PI DataPipe adapter, which is used to get on-the-fly events when a PI Point's value has changed

- The OSI PI Write adapter, which is used to update PI Point values

- The OSI PI Delete adapter, which is used to delete PI Point values

- The OSI PI AF adapter, which uses OSIsoft's Asset Framework to access Element and Attribute values and metadata (Deprecated. Instead, use the Elements and Attributes adapters).

- The OSI PI Elements adapter, which uses OSIsoft's Asset Framework to search for Elements

- The OSI PI Attributes adapter, which uses OSIsoft's Asset Framework to search for Attributes

- The OSI PI Event Frames adapter, which uses OSIsoft's Asset Framework to access Event Frames functionality

### Note

The OSIsoft PI adapters are provided for Windows systems only.

### Placing an OSI PI Adapter on the Canvas

The OSI PI adapters are members of the Java Operators group in the Palette view in StreamBase Studio. Select the operator from the Insert an Operator or Adapter dialog, following these steps:

1. Open the Insert an Operator or Adapter dialog with one of the following methods:

   1. Drag the Adapters, Java Operators token from the Operators and Adapters drawer of the Palette view to the canvas.

   2. Click on the canvas where you want to place the operator, then invoke the keyboard shortcut `O V`.

   3. From the top-level menu, invoke Insert → Operator → Java.

2. In the search field, enter `OSI` to narrow the list of adapters.

3. Select the OSIsoft adapter of interest and click OK.

### Prerequisites

In order run correctly, the adapters require that the OSIsoft PI Asset Framework (AF) Client version 2016 R2 or later and the OISsoft PI SDK version 2014 R2 or later be installed on development and deployment machines that are expected to run StreamBase applications that call these adapters. The OSIsoft software can be obtained from OSIsoft.

When you install and configure the OSIsoft software, you establish a set of defaults for server name, user name, password; those defaults are used if not explicitly defined in the adapter properties.

### How the Adapters Work

All adapters have two input streams, one for commands and the other for queries. The command stream currently takes one command, `SERVER`. This command is used to set up the user, password, PIServer/PISystem, and domain used to log in. When used, if any of these fields are null, the current value is used. If they are an empty string, the field is cleared. This is useful if you want to use the default PIServer/PISystem or user and password.

## OSIsoft Adapter Properties

This section describes the properties you can set for the adapters, using the various tabs of the Properties view in StreamBase Studio.

In following section tables, the Property column shows each property name as found in the one or more adapter properties tabs of the Properties view for this adapter.

Use the StreamSQL names of the adapter's properties when using this adapter in a StreamSQL program with the APPLY JAVA statement.

### OSI PI General Tab

Name: Use this required field to specify or change the component's name, which must be unique in the current module. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.

Operator: A read-only field that shows the formal name of the operator.

Start with application: If this field is set to Yes (default) or to a module parameter that evaluates to `true`, this instance of this operator starts as part of the JVM engine that runs this EventFlow fragment. If this field is set to No or to a module parameter that evaluates to `false`, the operator instance is loaded with the engine, but does not start until you send an epadmin container resume command (or its sbadmin equivalent), or until you start the component with StreamBase Manager.

Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports to learn about Error Ports.

Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

### OSI PI Adapters Properties

The OSI Pi adapters have the following properties, with the exceptions noted for some properties only on particular adapters:

#### Properties Tab

Property | Data Type | Default | Description | StreamSQL Property
--- | --- | --- | --- | ---
Status Output | check box | Cleared | Select this check box to enable a status output port, where tuples will be emitted to indicate command results as well as any errors for the adapter. | piStatus
Enable passthrough | check box | Cleared | When enabled, the input tuple is copied through to the output stream. | piPassthrough
Connect on Startup | check box | Cleared | Attempt to connect to the server when the application starts. | piStatus
Number of connection retries | integer | 0 | Number of times a connection should be attempted before an error occurs. -1 means unlimited attempts. | numRetry
Retry Sleep | integer | 0 | Number of seconds between retry attempts. | waitRetry
Result As Single Tuple | check box | false | If enabled the output will be a single list<tuple> for all items found instead of one tuple per result. This applies only for Summaries/Snapshot/EventFrames/Elements/Attributes. | queryResultAsSingleTuple
Log Level | drop-down list | INFO | Controls the level of verbosity the adapter uses to send notifications to the console. This setting can be higher than the containing application's log level. If set lower, the system log level will be used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE. | LogLevel

#### Server Tab

Property | Data Type | Default | Description | StreamSQL Property
--- | --- | --- | --- | ---
Pi Server | string | Cleared | Specifies the server to access. If blank, it uses the default server. | piServer
User | string | Cleared | Specifies the PI user for authenticate on the server. If blank, use the default user. | piUser
Password | string | Cleared | Specifies the password that authenticates the user on the server. If blank, use the default. | piPassword
Domain | string | Cleared | Domain to use to authenticate against. If blank, use the server's domain. | piDomain

### Concurrency Tab

Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.

### Caution

Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.

## Input Ports

The adapters have two input ports, the command and data ports. The command port is used to set up the adapter programmatically. The only currently supported command is SERVER. It establishes a connection to the PiServer using the given parameters (server, user, password, and domain). All required values should be supplied and any unneeded ones should be set to blank or null. If all parameters are blank or null, the system default credentials are used. When the tuple is received, the current connection to the server closes and a new connection initiates. If the connection is successful, the parameter is saved. If it is not, the old parameters are not overwritten. The proposed input schema contains the required fields.

Field Name | Field Type | Description
--- | --- | ---
Command | string | The command to execute. Currently the only supported command is SERVER, which causes the adapter to attempt to (re)connect to the server specified by the tuple's other fields.
Server | string | The name of the server to which to connect. Leaving this null causes the adapter to connect to the server specified on the Server tab of the adapter properties.
User | string | The user name to use to connect. Leaving this null causes the adapter to connect with the user name specified on the Server tab of the adapter properties.
Password | string | The password to use to connect. Leaving this null causes the adapter to connect with the password specified on the Server tab of the adapter properties.
Domain | string | The name of the domain to which to connect. Leaving this null causes the adapter to connect to the domain specified on the Server tab of the adapter properties.

### OSI PI Snapshot Adapter Query Input Port

Field Name | Field Type | Description
--- | --- | ---
tagNames | list<string> | The list of PI tags to query. For each specified tag, one output tuple will be produced to contain its value(s).
startTime | string or timestamp | When querying for values over a time range, this field determines the start time of the range. The field may be either of time Timestamp or String. If the latter, the format is expected to follow the OSI PI format. If the field is left null, no time range will be specified, and the result tuples will only contain the latest value for each tag. If a range is specified, the result tuple for each tag will contain all the values for the tag over the time range.
endTime | same type as `startTime` | If specified, the field determines the end time of the time range to use for the query. If left null, the current time is used.
rangeType | string | Determines how to interpret the specified time range. One of: `Inside`, `Interpolated`, `Outside`. If not set, `Inside` is used.
filterExpression | string | A filter expression that follows the performance equation syntax.
includeFilteredValues | boolean | Specify true to indicate that values which fail the filter criteria are present in the returned data at the times where they occurred, with a value set to a `Filtered` enumeration value with bad status. Repeated consecutive failures are omitted; default is false.
pageSize | int | The page size that will be returned. Default is 1000.
maxCount | int | The maximum number of values to be returned. If zero, then all of the events within the requested time range will be returned. Default is 0.

### OSI PI Write Adapter Write Input Port

Field Name | Field Type | Description
--- | --- | ---
tags | tuple | Contains the list of tag values to write to the server.
^ | tagName | string | The name of the tag to update.
value | string | The value of the tag to write.
valueType | string | The data type of the value to write.
timestamp | timestamp | The timestamp of the value to write.
insert | boolean | If the tag is missing the flag will determine if it is created or ignored, if true it will be created.
attributes | list | The attributes to set during insert or update
| ^ | key | string | The attribute key from the PICommonPointAttributes list
| value | string | The attribute value

### OSI PI Delete Adapter Delete Input Port

Field Name | Field Type | Description
--- | --- | ---
tags | tuple | Contains the list of tag values to delete from the server.
^ | tagName | string | The name of the tag to delete.

### OSI PI Summaries Adapter Query Input Port

Field Name | Field Type | Description
--- | --- | ---
tagNames | list<string> | The list of PI tags to query. For each specified tag, one output tuple will be produced to contain its value(s).
startTime | string or timestamp | Start time of the time range. The field may be either of time Timestamp or String. If the latter, the format is expected to follow the OSI PI format. This field must be set to a non-null value.
endTime | same type as `startTime` | End time of the time range to use for the query. If left null, the current time is used.
summaryTypes | string | Comma-separated list of summary types to perform. Valid values are: `none, range, stddev, populationstddev, minimum, maximum, average, total, count, percentgood, allfornonnumeric, all`. Case-insensitive.
calculationBasis | string | Method of evaluating the data over the time range. Valid values are: `TimeWeighted, EventWeighted, TimeWeightedContinuous, TimeWeightedDiscrete, EventWeightedExcludeMostRecentEvent, EventWeightedExcludeEarliestEvent, EventWeightedIncludeBothEnds`. Case-insensitive.
timestampCalculation | string | Indicates how to calculate the timestamp for each interval. One of: `auto, earliestTime, mostRecentTime`.
timespanYears | string | The time span years to query the summaries with, if all time span values are null the entire query span is used.
timespanMonths | string | The time span months to query the summaries with, if all time span values are null the entire query span is used.
timespanDays | string | The time span days to query the summaries with, if all time span values are null the entire query span is used.
timespanHours | string | The time span hours to query the summaries with, if all time span values are null the entire query span is used.
timespanMinutes | string | The time span minutes to query the summaries with, if all time span values are null the entire query span is used.
timespanSeconds | string | The time span seconds to query the summaries with, if all time span values are null the entire query span is used.
timespanMilliseconds | string | The time span milliseconds to query the summaries with, if all time span values are null the entire query span is used.

### OSI PI DataPipe Adapter Subscription Port

Field Name | Field Type | Description
--- | --- | ---
tagNames | List<String> | The list of PI tags to which to (un)subscribe.
command | string | `Subscribe, Unsubscribe` or `UnsubscribeAll`. Commands are cumulative: One `Subscribe` command for tags A and B and a subsequent `Subscribe` command for tag C results in all three tags A, B, C being subscribed. If left null, `Subscribe` is assumed. Use `Unsubscribe` to unsubscribe only from the tags specified in `tagNames`; use `UnsubscribeAll` to remove all subscriptions (`tagNames` is ignored and may be left null in this case). If the SERVER gets disconnected and a `SERVER` command is issued to reconnect, active subscriptions will be reestablished automatically.

### OSI PI Event Frames Adapter Query Port

Field Name | Field Type | Description
--- | --- | ---
searchName | string | An informational (and optional) name to identify this query. If no value is specified, a reasonably unique default is provided.
startTime | string | The starting time to be used in the generated search query. The search may compare against either the StartTime or EndTime of the Event Frame based on the `searchMode` parameter. The format is expected to follow the OSI AF format for time values. This field must be set to a non-null value.
searchMode | string | Specifies the direction in time from the StartTime or EndTime to proceed when returning Event Frames. One of: `BackwardFromStartTime`, `ForwardFromStartTime`, `BackwardFromEndTime`, `ForwardFromEndTime`, `BackwardInProgress`, `ForwardInProgress` (the default).
query | string | The optional search query string. If specified, this will add additional search filters to the generated search query in addition to the ones for the specified mode and times.

### OSI PI Elements Adapter Query Port

Field Name | Field Type | Description
--- | --- | ---
databaseName | string | The database to use with this search, relative to the current database. If blank, the default database is used.
timestamp | timestamp | The time index to use in queries.
searchRoot | string | The root object to start the search relative to the current database. If null, then the search starts at the AFDatabase.
nameFilter | string | The name filter string used for finding objects.
descriptionFilter | string | The element description filter string used for finding objects.
elemCategory | string | Specify that the owner of the returned elements must have this category.
elemTemplate | string | Specify that returned elements must have this template or a template derived from this template.
elemType | string | Specify that returned elements must have this Type (None, Other, Node, Measurement, Flow, Transfer, Boundary, PIPoint, Any). Default is Any.
searchFullHierarchy | boolean | Specifies if the search should include objects nested further than the immediate children of the searchRoot. Default is true.
sortField | string | The field or property of the object used to sort the returned collection (ID, Name, Type, StartTime, EndTime). Default is Name.
sortOrder | string | The order that the returned collection is sorted (Ascending or Descending). Default is Ascending.
maxCount | int | The maximum number of objects to be returned.

### OSI PI Attributes Adapter Query Port

Field Name | Field Type | Description
--- | --- | ---
databaseName | string | The database to use with this search relative to the current database. If blank, the default database is used.
timestamp | timestamp | The time index to use in queries.
searchRoot | string | The root object to start the search relative to the current database. If null, then the search starts at the AFDatabase.
nameFilter | string | The element name filter string used for finding objects.
descriptionFilter | string | The element description filter string used for finding objects.
elemCategory | string | Specify that the owner of the returned elements must have this category.
elemTemplate | string | Specify that returned elements must have this template or a template derived from this template.
elemType | string | Specify that returned elements must have this type (None, Other, Node, Measurement, Flow, Transfer, Boundary, PIPoint, Any). Default is Any.
attrNameFilter | string | The attribute name filter string used for finding objects.
attrDescriptionFilter | string | The attribute description filter string used for finding objects.
attrCategory | string | Specify that returned attributes must have this category.
attrType | string | Specify that returned attributes must have this type (Boolean, Byte, Char, DateTime, DBNull, Decimal, Double, Empty, Int16, Int32, Int64, Object, SByte, single, String, UInt16, UInt32, UInt64). Default is Empty, which ignores this filter.
searchFullHierarchy | boolean | Specifies if the search should include objects nested further than the immediate children of the searchRoot. Default is true.
sortField | string | The field or property of the object used to sort the returned collection (ID, Name, Type, StartTime, EndTime). Default is Name.
sortOrder | string | The order that the returned collection is sorted (Ascending or Descending). Default is Ascending.
maxCount | int | The maximum number of objects to be returned.

### OSI PI AF Adapter Input Port

Field Name | Field Type | Description
--- | --- | ---
command | string | Command to execute. The available commands and relevant support fields are listed below this table.
server | string | (SERVER command) The server to which to connect.
user | string | (SERVER command) The user name to use when connecting.
password | string | (SERVER command) The password to use when connecting.
domain | string | (SERVER command) The domain to which to connect.
queryBase | string | (QUERY command) The query base to set.
databaseName | string | (DATABASE command) The database to use for queries.
filterString | string | (FILTER command) The filter to set.
preloadElements | boolean | (PRELOAD command) If true, elements and their attributes will be preloaded when executing a query. This may improve performance by reducing the number of network round trips.
timestamp | string | (DATETIME command) Sets the timestamp for queries.
pageSize | integer | (PAGESIZE command) Sets the page size (number of elements to load at a time).
depth | integer | (LEVEL command) Set the number of sublevels to include in the queries.
leavesOnly | boolean | (LEAVESONLY command) If true, only the leaf elements (those at the lowest level of the hierarchy returned by the query) are be included in the results.

#### Commands

This section details the possible values for the command field, along with their required support fields. Any field not listed for a given command is ignored, if set.

- `SERVER`: Causes the adapter to connect or reconnect to the specified server. Expected fields are:

  - `command`: `SERVER`

  - `server`: Name of the server to which to connect

  - `user`: User name with which to connect

  - `password`: Password with which to connect

  - `domain`: Domain to which to connect

- `QUERY`: Sets the queries' base element. This element, and every subelement up to the number of sublevels specified by the adapter's `Query depth` property's value or the value previously set by a `LEVEL` command, are included in the results. If `leavesOnly` was set to true in a previous `LEAVESONLY` command, only the leaf elements resulting from this query are included. Expected fields are:

  - `command`: `QUERY`

  - `queryBase`: Path to the element node at the root of this query

- `DATABASE`: Sets the name of the database to use in subsequent queries. Expected fields are:

  - `command`: `DATABASE`

  - `databaseName`: Name of the database to use

- `FILTER`: Sets the filter to use when executing subsequent queries. Expected fields are:

  - `command`: `FILTER`

  - `filterString`: Filter to use for queries

- `PRELOAD`: If set to true, only the leaf elements resulting from subsequent queries are included. Expected fields are:

  - `command`: `PRELOAD`

  - `preloadElements`: Set to true to cause elements returned by subsequent queries to be preloaded, which may improve performance by reducing the number of network round trips. A null value is interpreted as `false`.

- `DATETIME`: Sets the timestamp to use in subsequent queries. Expected fields are:

  - `command`: `DATETIME`

  - `timestamp`: Time value to use

- `PAGESIZE`: Sets the number of elements to retrieve at a time when executing queries. Expected fields are:

  - `command`: `PAGESIZE`

  - `pageSize`: Non-zero, positive value representing the number of elements to load in each batch of a query. Default value is 1000.

- `LEVEL`: Set the number of sub-levels to traverse below queries' base element. A value of `0` represents the base element itself, with no recursion. Expected fields are:

  - `command`: `LEVEL`

  - `depth`: Non-zero, positive value

- `LEAVESONLY`: Sets whether all elements traversed in queries are returned in the result, or only the leaf elements. Expected fields are:

  - `command`: `LEAVESONLY`

  - `leavesOnly`: `true` to only return leaf elements, `false` or null to return all intermediate elements.

## Output Ports

Every adapter has one output port to emit tuples resulting from executing queries. In addition, if an adapter's `Status output` property is checked, a second port will be added to receive status events.

### Status Output Port

The status port emits tuples that describe the status of processing each input tuple. It is only present when the Output Status Tuples option is selected. The schema of the output tuple consists of four fields:

Field Name | Field Type | Description
--- | --- | ---
Type | string | The type of report, usually `Status`.
Action | string | The action that caused the report.
Message | string | Any results from the processing of the tuple. Examples: `Success`, `Parse Error`.
Object | string | Any extra information about the operation.

## Typechecking and Error Handling

There are no required parameters. Typechecking fails if the input schema does not contain all the required fields. It also fails if the types of the schema fields are incorrect. For the OSI PI operator, it fails if the types of both the start and end fields are not both string or both timestamp.

A check is made each time a query or write is requested. In the event that the adapter is not connected to the OSI system, an inline attempt is made to connect using the last known good credentials, or, if there has never been a successful connection, the credentials established by the adapter's starting properties.

## Suspend and Resume Behavior

Upon suspension, the OSI PI adapters finish processing the current tuple, outputs the result tuple(s), then pauses waiting for input.

Upon resumption, the OSI PI adapters continue processing with the next input tuple.

In either case, any database connection is not modified.

## OSI PI Adapter Sample

The StreamBase installation includes a sample demonstrating the use of this operator. To load the sample in StreamBase, select File → Load StreamBase Sample and look under the Extending StreamBase section for an entry called OSI PI Adapters.

Back to Top ^