OSIsoft PI Adapters

Introduction

The TIBCO StreamBase® Adapter for OSIsoft PI (hereafter, the OSIPI, OSIPIWRITE and OSIPIAF adapters) allow StreamBase to access data from an OSIsoft PI database. There are three adapters in this set. The first is OSIPI, which is used to access the data using what are called PiPoints. The second is OSIPIWRITE which is used to update PiPoint values. The third, OSIPIAF, uses OSIsoft's Asset Framework (AF) for this access. From StreamBase's point of view, there are two input-only adapters which read from the database and and one output adapter which writes to the database.

Note

The OSIsoft PI adapters are provided for Windows systems only.

Placing an OSIPI 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. Invoke the dialog with one of the following methods:

Drag the Adapters, Java Operators token from the Operators and Adapters drawer of the Palette view to the canvas.
Click on the canvas where you want to place the operator, then invoke the keyboard shortcut O V.
From the top-level menu, invoke Insert → Operator → Java.

Prerequisites

In order run correctly, the adapters require that the OSIsoft PI Asset Framework (AF) Client 2014 R2 SP1 version or later and the OISsoft , 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, and such that are used if not explicitly defined in the adapter properties.

How the Adapter Works

These adapters are used to read and write values from/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 or snapshot 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. It contains a list of the values found and a StreamBase timestamp field that records when the value was valid. In the case of a snapshot, there is only one value. For a range result, there are multiple values in the list. For ranges, the query is made using an inner setting for the time span's endpoints (please consult the OSIsoft documentation for an explanation of inner settings).

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

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

All three of these adapters can have their initial parameters set during authoring. In addition, commands can be sent at any time to adjust these parameters. They also share some common settings. 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 OSIsoft PI adapters, using the various tabs of the Properties view in StreamBase Studio.

In the tables in this section, 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.

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

Class: A field that shows the fully qualified class name that implements the functionality of this operator. Use this class name when loading the operator in StreamSQL programs with the APPLY JAVA statement. You can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.

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.

OSIPI and OSIPIWRITE Operator 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	If 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

OSIPI and OSIPIW 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

OSIPIAF Operator 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	If 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

OSIPIAF 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

OSIPIAF 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	If 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

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 port is used to setup the adapter programmatically. The only currently supported command is SERVER. It will cause 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 will be used. When the tuple is received, the current connection to the server is closed and a new connection is initiated. If the connection is successful, the parameter is saved. If it is not, the old parameters will not be overwritten. The proposed input schema contains the required fields.

The second OISIPI input port is the data port. This port accepts a tuple which contains 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 explaination of what these are.

The second OISIPIWRITE input port is the data port. This port accepts a tuple which 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 will check to see if the database exists, and if it does, will use 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.

Output Ports

THe OSIPI, OSIPIWRITE, and OSIPIAF adapters have two output ports: an optional status port, and a result port.

Status 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 strings:

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 Port

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

Typechecking and Error Handling

There are no required parameters. Typechecking fails if the input schema does not contain all the required fields It will also fail if the types of the schema fields are incorrect. For the OSIPI operator, it will fail if the types of both the start and end fields are not both string or 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 will be 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

On suspend, the OSIPI adapters finishes processing the current tuple, outputs the result tuple(s), then pauses waiting for input.

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

Back to Top ^