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

Note

The OSIsoft PI adapters are provided for Windows systems only.

The Spotfire Streaming 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. API diagnostic details are available with DEBUG and TRACE logging.

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 2018 R2 or later and the OSIsoft PI SDK version 2018 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.

Note

Each instance in a StreamBase fragment of the adapters listed above will be establishing its own connection to its configured OSI PI server. For example a StreamBase application using one instance of PI Snapshot and two instances of PI DataPipe will maintain three separate connections to the server. This means the target server(s) must be configured to allow multiple simultaneous connections from the same credentials, or only one adapter instance will be able to connect at any one time.

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.

OSI PI General Tab

Name: Use this required field to specify or change the name of this instance of this component. The name must be unique within the current EventFlow module. The name can contain alphanumeric characters, underscores, and escaped special characters. Special characters can be escaped as described in Identifier Naming Rules. The first character must be alphabetic or an underscore.

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

Class name: Shows the fully qualified class name that implements the functionality of this operator. If you need to reference this class name elsewhere in your application, you can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.

Start options: This field provides a link to the Cluster Aware tab, where you configure the conditions under which this operator starts.

Enable Error Output Port: Select this checkbox 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 purpose and function of the component. In the EventFlow Editor canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Operator Properties Tab

Property Data Type Default Description
Event Type drop-down list Snapshot OSI PI DataPipe adapter only  The type of event updates requested, one of Snapshot, Archive, or TimeSeries.
Polling Interval int 500 OSI PI DataPipe adapter only  The number of milliseconds between data pipe queries.
Status Output check box Cleared Select this checkbox to enable a status output port, where tuples are emitted to indicate command results as well as any adapter errors.
Enable passthrough check box Cleared When enabled, the input tuple is copied through to the output stream.
Connect on Startup check box Cleared Attempt to connect to the server when the application starts.
Number of connection retries integer 0 Number of times a connection should be attempted before an error occurs. -1 means unlimited attempts.
Retry Sleep integer 0 Number of seconds between retry attempts.
Result As Single Tuple check box false If enabled, the output is a single list(tuple) for all items found instead of one tuple per result. This applies only for Summaries, Snapshot, EventFrames, Elements, and Attributes.
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.

Server Tab

Property Data Type Default Description
PI Server string Cleared Specifies the server to access. If blank, it uses the default server.
PI Authentication Mode radio buttons PI User Authentication PI Authentication Mode to use when connecting to a PI Data Archive. Supported values are PI User Authentication and Windows Authentication.
User string Cleared Specifies the PI user for authenticate on the server. If blank, use the default user.
Password string Cleared Specifies the password that authenticates the user on the server. If blank, use the default.
Domain string Cleared Domain to use to authenticate against. If blank, use the server's domain.

Cluster Aware Tab

Use the settings in this tab to enable this operator or adapter for runtime start and stop conditions in a multi-node cluster. During initial development of the fragment that contains this operator or adapter, and for maximum compatibility with releases before 10.5.0, leave the Cluster start policy control in its default setting, Start with module.

Cluster awareness is an advanced topic that requires an understanding of StreamBase Runtime architecture features, including clusters, quorums, availability zones, and partitions. See Cluster Awareness Tab Settings on the Using Cluster Awareness page for instructions on configuring this tab.

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.

Command Input Port

The command port is used to set up the adapter dynamically. The only currently supported command is SERVER, which establishes a connection to the PiServer using the provided parameters (server, user, password, and domain). Provide all required values and set any unneeded values to blank or null. If all parameters are blank or null, the system default credentials are used. When a 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.
timespanInterval tuple The timespan interval to use. If not set, no interval is used in the query.
^ years int The number of years in this timespan.
months int The number of months in this timespan.
days int The number of days in this timespan.
hours double The number of hours in this timespan.
minutes double The number of minutes in this timespan.
seconds double The number of seconds in this timespan.
milliseconds double The number of milliseconds in this timespan.
timeZone string The timezone, in the format specified by the International Components for Unicode (ICU). Examples would include long form names such as "Pacific Standard Time", or abbreviated forms like "UTC". The default value will be whatever timezone the hosting machine uses.

OSI PI Write Adapter Write Input Port

Field Name Field Type Description
tags list(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(tuple) 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 values.
startTime string or timestamp Start time of the time range. The field may be either of type 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) List of PI tags to subscribe to or unsubscribe from.
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 are 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.
endTime string The ending time of the search period. 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.
searchMode string Specifies the direction in time from the StartTime or EndTime to proceed when returning Event Frames. If an end time is supplied then one of:

None, StartInclusive, EndInclusive, Inclusive (the default), Overlapped, InProgress

If no end time is supplied then 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.
attributes tuple The attributes query details, if this field is null or missing defaults are used. If this field is present the values field of the attributes output will be set to a list of values to allow for multiple value results.
attributes.startDateTime string The start date time to search for attribute values
attributes.endDateTime string The end date time to search for attribute values
attributes.count int The number of values to fetch, null or 0 for all
attributes.override list(tuple) Attribute overrides to specify options for a specific attribute
attributes.override.name string The name of the specific attribute to override search values for
attributes.override.startDateTime string The start date time to search for attribute values
attributes.override.endDateTime string The end date time to search for attribute values
attributes.override.count int The number of values to fetch, null or 0 for all
GetValues object Allow getting all values back within the given time event frame.

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 running 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.
GetValues object Allow getting all values back within the given time event frame.

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 running 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 running 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 on which to emit tuples resulting from running 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>Import Samples and Community Content and look under the Extending StreamBase section for an entry called OSI PI Adapters.

Back to Top ^