Contents
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.
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:
-
Open the Insert an Operator or Adapter 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
→ → .
-
-
In the search field, enter
OSI
to narrow the list of adapters. -
Select the OSIsoft adapter of interest and click
.
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.
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.
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.
Name: Use this required field to specify or change the name of this instance of this component, which must be unique in the current EventFlow module. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.
Operator: A read-only field that shows the formal name of the operator.
Start with application: If this field is set to Yes (default) or to a module parameter that evaluates to true
, this instance of this operator starts as part of the JVM engine that runs this EventFlow module. If this field is set to
No or to a module parameter that evaluates to false
, the operator instance is loaded with the engine, but does not start until you send an sbadmin resume command, or until you start the component with StreamBase Manager.
Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports to learn about Error Ports.
Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.
The OSI Pi adapters have the following properties, with the exceptions noted for some properties only on particular adapters:
Property | Data Type | Default | Description |
---|---|---|---|
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. |
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 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. |
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. |
Property | Data Type | Default | Description |
---|---|---|---|
Pi Server | string | Cleared | Specifies the server to access. If blank, it uses the default server. |
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. |
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.
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. |
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. |
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 |
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. |
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. |
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 |
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: |
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. |
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. |
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. |
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. |
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'sQuery depth
property's value or the value previously set by aLEVEL
command, are included in the results. IfleavesOnly
was set to true in a previousLEAVESONLY
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 asfalse
.
-
-
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 of0
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.
-
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.
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. |
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.
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.
The StreamBase installation includes a sample demonstrating the use of this operator. To load the sample in StreamBase, select Extending StreamBase section for an entry called OSI PI Adapters.
→ and look under the