Difference between revisions of "OSIPI (Plugin)"
(→Prerequesites) |
|||
| (20 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
| − | The OSIPI interface module enables support for reading data from [https://www.osisoft.com/pi-system/ OSIsoft PI systems]. | + | The OSIPI interface module enables support for reading data from [https://www.osisoft.com/pi-system/ OSIsoft PI systems] as well as data from the [https://docs.osisoft.com/bundle/ocs/page/ocs-content-portal-overview.html OSIsoft Cloud Services] and provides them as [[Live_Values]] within Ubik. |
== Features == | == Features == | ||
| − | * | + | The module allows live data from the Data Archive to be read via both the '''PI Web API''' as well as from the '''OCS system'''{{Version/ServerSince|3.6.0}}. |
| − | * | + | |
| − | * | + | Furthermore, it supports: |
| + | * Values of multiple types | ||
| + | * Configuration of multiple server instances to handle multiple sources simultaneously | ||
| + | * Correct value formatting according to the docs{{Version/ServerSince|3.5.0}} | ||
== Prerequesites == | == Prerequesites == | ||
| + | They vary slightly by the type of interface. For the common things, you need a functioning Ubik Server setup (Studio, Database, and Web Service). | ||
| + | |||
| + | === PIWebAPI=== | ||
To be able to successfully set up the system, the Ubik server/development machine needs access to the OSIPI instance. This can be easily checked in the web browser by navigating to the provided URL. [https://techsupport.osisoft.com/Documentation/PI-Web-API/help.html OSIsoft's PiWebAPI] is a [https://en.wikipedia.org/wiki/Representational_state_transfer REST API], from which the plugin reads data. | To be able to successfully set up the system, the Ubik server/development machine needs access to the OSIPI instance. This can be easily checked in the web browser by navigating to the provided URL. [https://techsupport.osisoft.com/Documentation/PI-Web-API/help.html OSIsoft's PiWebAPI] is a [https://en.wikipedia.org/wiki/Representational_state_transfer REST API], from which the plugin reads data. | ||
| + | === OCS API=== | ||
| + | The Ubik server/development machine needs access to the OCS server, which usually means internet access, as it's somewhere in the cloud. The API uses OpenID Connect for authentication, and the Ubik module supports the [https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow OAuth2 Client Credentials Flow] only, so make sure to have a valid <code>TenantID</code>, <code>ClientID</code> and <code>ClientSecret</code> ready. | ||
== Configuration in Ubik == | == Configuration in Ubik == | ||
| Line 25: | Line 33: | ||
|<code>String</code> | |<code>String</code> | ||
|- | |- | ||
| − | |<code>Int16</code> | + | |<code>Int16</code> {{Version/ServerSince|3.5.0}} |
|<code>Integer</code> | |<code>Integer</code> | ||
|- | |- | ||
| Line 31: | Line 39: | ||
|<code>Integer</code> | |<code>Integer</code> | ||
|- | |- | ||
| − | |<code>Float16</code> | + | |<code>Float16</code> {{Version/ServerSince|3.5.0}} |
|<code>Float</code> | |<code>Float</code> | ||
|- | |- | ||
| Line 37: | Line 45: | ||
|<code>Float</code> | |<code>Float</code> | ||
|- | |- | ||
| − | |<code>Float64</code> | + | |<code>Float64</code> {{Version/ServerSince|3.5.0}} |
|<code>Float</code> | |<code>Float</code> | ||
|} | |} | ||
| + | |||
| + | The same is true for the '''OCS API''', nullables are not yet supported. | ||
=== Authentication === | === Authentication === | ||
| − | The | + | The following authentication methods are supported. |
| − | + | ||
| − | + | ||
| − | + | ==== PI Web API ==== | |
| + | The OSIPI plugin supports two types of authentication for the '''PIWebAPI''': | ||
| + | * Basic {{Version/ServerSince|3.5.0}} | ||
| + | * Current User/Windows Authentication | ||
| − | If you leave the <code>LOGINNAME</code> field empty, the client tries to authenticate against the OSIPI server with <code>[https://docs.microsoft.com/en-us/dotnet/api/system.net.webclient.usedefaultcredentials WebClient.UseDefaultCredentials]</code>. Should this be the authentication of your choice, be aware that the Ubik Studio/Enterprise Service/Web Service needs to be started as that user that has access to the PI system. | + | In the case of '''Basic authentication''', put the credentials in the respective fields <code>LOGINNAME</code> and <code>PASSWORD</code>. Be aware that domain backslashes might need to be doubled, thanks to their escaping nature, e.g.: <code>DOMAIN\\USER</code> |
| + | |||
| + | If you leave the <code>LOGINNAME</code> field empty, the client tries to authenticate against the OSIPI server with <code>[https://docs.microsoft.com/en-us/dotnet/api/system.net.webclient.usedefaultcredentials WebClient.UseDefaultCredentials]</code>. Should this be the authentication of your choice, be aware that the Ubik Studio/Enterprise Service/Web Service needs to be started as that user that has access to the PI system. | ||
| + | |||
| + | Also, make sure that <code>USE_OCS</code> is '''not''' checked. | ||
| + | |||
| + | === Asset framework {{Version/ServerSince|3.7.0}} === | ||
| + | |||
| + | Since the version of 3.7 it is possible to fetch attributes from the asset framework. | ||
| + | To do this derive from <code>OSIPI datapoint</code> and add a new integer property <code>OSIPI_SOURCE</code>, for which you select the <code>OSIPI_SOURCES</code> selective list (namespace: <code>System.Interface.Module.OSIPI</code>).<br/> | ||
| + | Choose <code>Attributes</code> as its value.<br/> | ||
| + | Since the version of 3.7.1 this property is provided as a system property via database update. | ||
| + | |||
| + | |||
| + | ==== OCS API ==== | ||
| + | Only one type of authentication is supported for the '''OCS API''': | ||
| + | * OAuth2.0/OpenID Connect Client Credentials Flow | ||
| + | |||
| + | For that, make sure to fill up the required fields <code>TENANT_ID</code>, <code>CLIENT_ID</code>, <code>CLIENT_SECRET</code>, <code>API_VERSION</code>, <code>OCS_NAMESPACE</code> and make sure that <code>USE_OCS</code> is checked. | ||
| + | |||
| + | == Attributes {{Version/WinXSince|3.6}} {{Version/XamarinSince|1.1}} {{Version/ServerSince|3.5.0}} == | ||
| + | The Ubik OSIPI Plugin also supports [[Live_Values#Attributes|Live Value Attributes]], which can be [[Live_Values#Binding_to_Attributes|bound to directly from XAML]]. Not all attributes are delivered for all live values. | ||
| + | {| class="wikitable" | ||
| + | |'''Live Value Attribute''' | ||
| + | |'''Description''' | ||
| + | |- | ||
| + | |<code>UNIT</code> | ||
| + | |The unit of the OSIPI datapoint from OSIPI. | ||
| + | |||
| + | |||
| + | This attribute is only available if the unit from OSIPI is not empty. | ||
| + | |- | ||
| + | |<code>FORMATTED</code> | ||
| + | |The value in the format ''{Value} {Unit}'', with the option to set the [https://docs.microsoft.com/en-us/dotnet/api/system.globalization.cultureinfo value formatting culture] (with the <code>FORMATTING_CULTURE</code> field on the ''OSIPI_SERVER''). There is also an option to trim leading zeroes (with the <code>TRIM_LEADING_ZEROES</code> field), however, this is only available with the '''PIWEBAPI'''. This functionality is available in Ubik.Server 3.5.x as well, however, the fields <code>FORMATTING_CULTURE</code> and <code>TRIM_LEADING_ZEROES</code> are not generated automatically. This was repaired in 3.6.0. | ||
| + | |||
| + | |||
| + | This attribute is only available when the live value is numeric. | ||
| + | |- | ||
| + | |<code>DIGITS</code> | ||
| + | |The [https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&uact=8&ved=2ahUKEwjFrLe1vaPlAhXQDmMBHYFUBycQFjAAegQIAxAB&url=https%3A%2F%2Flivelibrary.osisoft.com%2FLiveLibrary%2Fcontent%2Fen%2Fwebparts-v4%2FGUID-13DC1C74-40B9-4FFE-B0B2-FCD204D8C337&usg=AOvVaw2Zg1surxOxQ9sAedVz70DG OSIPI display digits] described. | ||
| + | |||
| + | |||
| + | This attribute is only available when the live value is numeric and only when using the '''PIWEBAPI'''. | ||
| + | |} | ||
| − | + | [[Category:Live Values|OSIPI (Plugin)]] | |
| − | + | [[Category:OSIPI|OSIPI (Plugin)]] | |
| − | + | ||
Latest revision as of 14:19, 13 January 2023
The OSIPI interface module enables support for reading data from OSIsoft PI systems as well as data from the OSIsoft Cloud Services and provides them as Live Values within Ubik.
Contents
Features
The module allows live data from the Data Archive to be read via both the PI Web API as well as from the OCS system.
Furthermore, it supports:
- Values of multiple types
- Configuration of multiple server instances to handle multiple sources simultaneously
- Correct value formatting according to the docs
Prerequesites
They vary slightly by the type of interface. For the common things, you need a functioning Ubik Server setup (Studio, Database, and Web Service).
PIWebAPI
To be able to successfully set up the system, the Ubik server/development machine needs access to the OSIPI instance. This can be easily checked in the web browser by navigating to the provided URL. OSIsoft's PiWebAPI is a REST API, from which the plugin reads data.
OCS API
The Ubik server/development machine needs access to the OCS server, which usually means internet access, as it's somewhere in the cloud. The API uses OpenID Connect for authentication, and the Ubik module supports the OAuth2 Client Credentials Flow only, so make sure to have a valid TenantID, ClientID and ClientSecret ready.
Configuration in Ubik
Live value servers get added to instances of the OSIPI_SERVER metaclass, whereas the data points are objects of the OSIPI_DATAPOINT metaclass.
With that difference in mind, follow this guide: Implementing Live Values.
Not all data types of OSIPI are available to be configured in Ubik. The following table shows the matches:
| OSIPI Data Type | Ubik Data Type |
Digital
|
Integer (0 or 1)
|
String
|
String
|
Int16
|
Integer
|
Int32
|
Integer
|
Float16
|
Float
|
Float32
|
Float
|
Float64
|
Float
|
The same is true for the OCS API, nullables are not yet supported.
Authentication
The following authentication methods are supported.
PI Web API
The OSIPI plugin supports two types of authentication for the PIWebAPI:
In the case of Basic authentication, put the credentials in the respective fields LOGINNAME and PASSWORD. Be aware that domain backslashes might need to be doubled, thanks to their escaping nature, e.g.: DOMAIN\\USER
If you leave the LOGINNAME field empty, the client tries to authenticate against the OSIPI server with WebClient.UseDefaultCredentials. Should this be the authentication of your choice, be aware that the Ubik Studio/Enterprise Service/Web Service needs to be started as that user that has access to the PI system.
Also, make sure that USE_OCS is not checked.
Asset framework
Since the version of 3.7 it is possible to fetch attributes from the asset framework.
To do this derive from OSIPI datapoint and add a new integer property OSIPI_SOURCE, for which you select the OSIPI_SOURCES selective list (namespace: System.Interface.Module.OSIPI).
Choose Attributes as its value.
Since the version of 3.7.1 this property is provided as a system property via database update.
OCS API
Only one type of authentication is supported for the OCS API:
- OAuth2.0/OpenID Connect Client Credentials Flow
For that, make sure to fill up the required fields TENANT_ID, CLIENT_ID, CLIENT_SECRET, API_VERSION, OCS_NAMESPACE and make sure that USE_OCS is checked.
Attributes
The Ubik OSIPI Plugin also supports Live Value Attributes, which can be bound to directly from XAML. Not all attributes are delivered for all live values.
| Live Value Attribute | Description |
UNIT
|
The unit of the OSIPI datapoint from OSIPI.
|
FORMATTED
|
The value in the format {Value} {Unit}, with the option to set the value formatting culture (with the FORMATTING_CULTURE field on the OSIPI_SERVER). There is also an option to trim leading zeroes (with the TRIM_LEADING_ZEROES field), however, this is only available with the PIWEBAPI. This functionality is available in Ubik.Server 3.5.x as well, however, the fields FORMATTING_CULTURE and TRIM_LEADING_ZEROES are not generated automatically. This was repaired in 3.6.0.
|
DIGITS
|
The OSIPI display digits described.
|
