OSIsoft PI Adapters

Contents

Introduction
OSIsoft Adapter Properties
Input Ports
Output Ports
Typechecking and Error Handling
Suspend and Resume Behavior
OSIPI Adapter Sample

Introduction

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

The OSI PI Snapshot adapter, used to access the current value of PI Points (or the values they had over a given time range)
The OSI PI Summaries adapter, 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, used to get on-the-fly events when a PI Point's value has changed

The OSI PI Write adapter, used to update PI Point values
The OSI PI AF adapter, which uses OSIsoft's Asset Framework to to access Element and Attribute values and metadata

Note

The OSIsoft PI adapters are provided for Windows systems only.

Placing an OSI PI Adapter on the Canvas

The OSIPI 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:

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.
In the search field, enter OSI to narrow the list of adapters.
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 2015 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

These adapters are used to read and write values from and to an OSIsoft database. The first adapter, OSIPI, uses the PiPoint interfaces. It accepts a list of PIPoint names, along with an optional time range and optional range type, and returns the values of those PIPoints. If the range is not specified, it returns the current value of the PIPoint. If a range is given, it returns a set of values for that PIPoint over the given span. The result is an output tuple for each PIPoint found, followed by an empty marker tuple to announce the end of the list. Each PIPoint tuple contains a list of the values found for that point along with its associated metadata (such as timestamp, status, unit of measure, etc). In the case of a snapshot, there is only one value. For a range result, there are multiple values in the list.

This adapter has 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, 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 or user and password.

The OISPIWRITE adapter is similar to the OISPI adapter in that it uses the same interfaces to write data. It also accepts a list of PiPoint names, along with the new value (as a string), the type of the value, and an optional StreamBase Timestamp that is used to set the time at which this value is to be assumed to have been written. The string is converted to the appropriate type before being written. Currently supported types are string, bool, int32, int64, float, double, and timestamp.

The OSIPIAF adapter uses the Asset Framework to access the data. Here, a query is made using a path to the starting point, similar to a hierarchical file system. From that point, a search is made for the number of specified levels and the asset information found is returned. A single query can produce hundreds of results and there is one tuple output for each asset found. This adapter has a single input stream. The supported commands are discussed below.

You can set the initial parameters during authoring for all three adapters types. In addition, you can send commands any time to adjust these parameters. They also share some common settings. For example, the Log Level is used as for other StreamBase operators and adapters. These adapters also have a setting which causes the input tuple to be passed along to the output in a sub-tuple named passthrough. Each also has a status output stream which can be enabled. This is useful during development as the status of each command is sent, along with any errors encountered.

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 field to specify or change the component's name, which must be unique in the application. 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 or to a module parameter that evaluates to true, an instance of this operator starts as part of the containing StreamBase Server. If this field is set to No or to a module parameter that evaluates to false, the adapter is loaded with the server, but does not start until you send an sbadmin resume command, or until you start the component with StreamBase Manager. With this option set to No or false, the operator does not start even if the application as a whole is suspended and later resumed. The recommended setting is selected by default.

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 and Error Streams 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 Snapshot Adapter Properties

The OSI PI Snapshot adapter exposes several tabs and settings in its StreamBase Properties window, described in this section.

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
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, and ALL.	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

OSI PI Write Adapter Properties

The OSI PI Write adapter exposes several tabs and settings in its StreamBase Properties window, described in this section.

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
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, and ALL.	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

OSI PI Summaries Adapter Properties

The OSI PI Summaries adapter exposes several tabs and settings in its StreamBase Properties window, described in this section.

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
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, and ALL.	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

OSI PI DataPipe Adapter Properties

The OSI PI DataPipe adapter exposes several tabs and settings in its StreamBase Properties window, described in this section.

Properties Tab

Property	Data Type	Default	Description	StreamSQL Property
Event Type	drop-down list	Snapshot	The type of events the adapter should subscribe to: Snapshot (tuples are issued on current value change events), Archive (tuples are issued on archive data change events) or TimeSeries (tuples are issued on change events for a PI time series). Note TimeSeries is only available when running against PI Data Archive 3.4.395 or later.	eventType
Polling Interval in milliseconds	integer	500	Period to wait between checks for new events.	pollingInterval
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
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, and ALL.	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

OSI PI AF Adapter Properties Tab

Adapter Properties Tab

Property	Data Type	Default	Description	StreamSQL Property
Status Output	check box	Cleared	Select this check box to have a status tuple emitted on the status output stream for each input tuple.The status tuple includes any errors generated by the script for this tuple.	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
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, and ALL.	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
Database	string	Cleared	The database on the server to use.	piDataBase

Query Tab

These options are used to describe how a query is made to the AF system.

Property	Data Type	Default	Description	StreamSQL Property
Query base	string	Cleared	Where in the hierarchy to start searching from. The string uses the formate described in the OSIsoft documentation.	piQuery
Filter	string	Cleared	When set, only attributes which have this string in their tags are retrieved.	piFilter
Query depth	int	0	How many levels to search from starting at the base.	piLevels
Data at leaves only	check box	set	Should data be retrieved from the bottom of the search tree or at all intermediate nodes also.	piLeaves
Pagesize	int	100	Queries are returned in batches of Pagesize items from the AF system.	piPagesize
Preload data	check box	Cleared	When set, elements found will preload their attributes. This can improve performance by reducing the number of network round trips.	piPreload

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 OSIPI and OSIPIWRITE adapters have two input ports, the command and data ports. The command port is used to setup 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.

The second OISIPI input port is the data port. This port accepts a tuple containing a list of PiPoints to query for. This list contains the name of the PiPoint, an optional time range for the query, and an optional range type for the result. If the start and end fields are empty, a snapshot query is used to return the current value of the PiPoint. If a range is present, the values found that occurred within that time period is returned. The range must be either StreamBase timestamps or OSI time strings. They must both be of the same type. If using OSI time strings, consult the OSI documentation on time ranges. As an example, having start = -5D and end = *, the query will return the values for the past five days. Supported range types are inside, outside, and interpolated. See the OSIsoft documentation for an explanation of what these are.

The second OISIPIWRITE input port is the data port. This port accepts a tuple that contains a list of PiPoints to write values to. This list contains the name of the PiPoint, the new value, the type of the value, and an optional time for the write. If the timestamp field is empty, the current time is used.

The OISPIAF adapter has one input port, the command port. The commands are:

server — takes the parameters server, user, password and domain. Attempts a connection to the requested. A connection is needed before any queries will complete. If set in the parameters at design time, an initial connection is attempted when the application starts if Connect on start is set.

Note that you should always supply all the needed parameters for this command.
database — takes one parameter, dataBaseName. It checks to see if the database exists, and if it does, uses that database in subsequent queries. If the parameter is null, the default database is chosen.
query — takes one parameter, queryBase. If queryBase is null or empty, the previous value is used if one exists.
filter — takes one parameter, filterString. If the string is empty or null, it is cleared.
load — takes one parameter, loadFlag. If null, the current value is returned on the status port. Otherwise it is set to the given value.
level — takes one parameter, depth. If null, the current value is returned on the status port. Otherwise it is set to the given value.
pagesize — takes one parameter, pageSize, which must be a positive number. If null, the current value is returned on the status port.
leavesonly — takes one parameter, leavesFlag. If null, the current value is returned on the status port.

OSI PI Snapshot Adapter Input Ports

The Snapshot adapter has two ports: one receives commands, and the other receives queries.

The Command port has the following 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.

The Query input port has the following fields:

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, OUTSIDE, INTERPOLATED. If not set, `INSIDE` is used.

OSI PI Write Adapter Input Ports

The Write adapter has two ports: one receives commands, and the other receives the list of tag values to write to the server.

The Command port has the following 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.

The Write input port has the following fields:

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.

OSI PI Summaries Adapter Input Ports

The Summaries adapter has two ports: one receives commands, and the other receives queries.

The Command port has the following 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.

The Query input port has the following fields:

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`.

OSI PI DataPipe Adapter Input Ports

The DataPipe adapter has two ports: one receives commands, and the other receives subscriptions and unsubscriptions. All subscriptions are assumed to be for tags on the server currently connected; to subscribe to tags from different servers, use multiple instances of this adapter.

The Command port has the following 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.

The Subscription input port has the following fields:

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 AF Adapter Input Ports

The AF adapter only has one input port, which receives queries.

The port has the following fields:

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 roundtrips.
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 roundtrips. 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.

Result Output Port

Every adapter has a Result port to emit tuples containing the query results.

The OSIPI schema of the result port consists of:

Optionally the input tuple, which is passed through unchanged in the passthrough item.
A list of tuples, each consisting of the name of the requested PiPoint and a list of results. Each result is a tuple consisting of a string containing the value of the PiPoint and a timestamp showing when the data was valid.

The OSIPIWRITE schema of the result port consists of:

Optionally the input tuple, which is passed through unchanged in the passthrough item.
A boolean which is true if every write operation in the input list succeeded; otherwise it is false.
A list of tuples, each one consisting of the name of the requested PiPoint, a boolean success flag, the value and type written, the time it was assumed to have been written, and the error string if there was an error.

The OISPIAF schema of the result port consists of:

Optionally the input tuple, which is passed through unchanged in the passthrough item.
The name of the attribute found (string: attributeName), the value of the attribute (string: value) and the element which has the attribute (string: elementName). Also present is a list (list: tagValues) of the elements found (string: element type).

One tuple is output for each attribute found.

OSI PI Snapshot Adapter Results Output Port

When a query tuple is received, the query is executed and its results are emitted on this port. One tuple is emitted for each requested PI Point in the tagNames list of the input tuple. Once the results have been returned, a marker tuple with tagName = null is emitted to indicate the end of the query results.

Field Name		Field Type	Description
tagName		string	The name of the PI Point for which values are returned.
tagValues		list<tuple>	The list of values returned for this PI Point.
^	value	string	The value of the tag.
	valueType	string	The data type of this value.
	timestamp	timestamp	The timestamp of the value.
	uom	string	The unit of measure used by this value.
	status	string	The status of this tag.
passthrough		tuple	If the adapter's `Enable passthrough` property is set, this field is added to the schema and will contain the input tuple that triggered the results.

OSI PI Write Adapter Results Output Port

When a tuple is received on the Write input port, the PI Point values are written to the server and the results of the operation are emitted on this port. One tuple is emitted containing the list of updated PI Points and the result of each write operation.

Field Name		Field Type	Description
overallResult		boolean	If true, the write operation was successful.
results		list<tuple>	The list of values returned for this PI Point.
^	name	string	The name of the tag.
	result	string	The result of writing this tag: `true` for success, `false` otherwise.
	value	string	The value that was written to the tag.
	valType	string	The data type of this value.
	timestamp	timestamp	The timestamp of the value.
	reason	string	When `result` = `false`, this contains the reason for failure.
passthrough		tuple	If the adapter's `Enable passthrough` property is set, this field will be added to the schema and will contain the input tuple that triggered the results.

OSI PI Summaries Adapter Results Output Port

Field Name		Field Type	Description
tagName		string	The name of the PI Point for which values are returned.
summaries		list<tuple>	The list of summaries returned for this PI Point.
^	summaryType	string	The type of summary represented by this tuple. Possible values are one of those listed for the `summaryTypes` field of the query input tuple.
	value	string	The value of the summary.
	valueType	string	The data type of the summary.
	timestamp	timestamp	The timestamp of the value.
	uom	string	The unit of measure used by this value.
	status	string	The status of this tag.
passthrough		tuple	If the adapter's `Enable passthrough` property is set, this field is added to the schema and will contain the input tuple that triggered the results.

OSI PI DataPipe Adapter Results Output Port

When subscriptions are active, as events occur over time the results are emitted on this port. One tuple is emitted for each event that occurs.

Field Name		Field Type	Description
tagName		string	The name of the PI Point for which values are returned.
action		string	The action that triggered this event. One of `Update, Add, Delete, Refresh, Insert`.
previousAction		string	Provides information about the previous data pipe events. Not every data source has information about previous data pipe events. One of `None, PreviousEventArchived, PreviousEventDiscarded`.
value		string	The value of the tag.
valueType		string	The data type of this value.
uom		string	The unit of measure used by this value.
timestamp		timestamp	The timestamp of the value.
status		string	The status of this tag.
specificUpdatedValue		tuple	For data pipe events coming from the PI Data Archive at or higher than 3.4.395, events generated with updateSpecific data call would have the old value in the SpecificUpdateValue property. This information is useful to identify a particular event within a sequence of events with same timestamps.
^	value	string	The value of the tag.
	valueType	string	The data type of this value.
	timestamp	timestamp	The timestamp of the value.
	uom	string	The unit of measure used by this value.
	status	string	The status of this tag.
passthrough		tuple	If the adapter's `Enable passthrough` property is set, this field is added to the schema and will contain the input tuple that triggered the results.

OSI PI AF Adapter Results Output Port

When a QUERY command is received, the query is executed and its results are emitted on this port. One tuple is emitted for each attribute found in the elements returned by the query. Once the results have been returned, a marker tuple with attributeName = null is emitted to indicate the end of the query results.

Field Name		Field Type	Description
attributeName		string	The name of the attribute represented by this tuple.
attributeID		string	ID of this attribute.
value		string	Value of this attribute.
valueType		string	Data type of the value.
elementName		string	Name of the element containing this attribute.
elementID		string	ID of the element containing this attribute.
parentAttributeName		string	Name of the parent attribute, if any.
parentAttributeID		string	ID of the parent attribute, if any.
description		string	Description of this attribute, if available.
categories		string	Comma-separated list of categories to which this attribute belongs, if any.
uom		string	Unit of measure used by the value.
timestamp		timestamp	Date and time of this value.
status		string	Status of this attribute.
dataReferenceValue		string	Value of the data referenced by this attribute, if applicable.
dataReferenceType		string	Type of reference (e.g. "PIPoint").
childAttributes		list<tuple>	Any child attributes of the attribute are listed here. Further nesting levels are unsupported. All fields have the same meaning as their counterpart above.
^	attributeName	string
	attributeID	string
	value	string
	valueType	string
	elementName	string
	elementID	string
	parentAttributeName	string
	parentAttributeID	string
	description	string
	categories	string
	uom	string
	timestamp	timestamp
	status	string
	dataReferenceValue	string
	dataReferenceType	string
passthrough		tuple	If the adapter's `Enable passthrough` property is set, this field will be added to the schema and will contain the input tuple that triggered the results.

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 OSIPI 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 OSIPI adapters finishes processing the current tuple, outputs the result tuple(s), then pauses waiting for input.

Upon resumption, the OSIPI adapters continues processing with the next input tuple.

In either case, any database connection is not modified.

OSIPI 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 OSIPI Adapter.