OSIsoft PI Adapters

Contents

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

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

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 ^