TrendMiner PI Vision Plugin - extended guidelines

Compatibility

PI Vision 3
TrendMiner 2019.R3 or later 

TrendMiner PI Vision Plugin

Note: A working PI Vision and PI Web API should be available. Some basic troubleshooting regarding the configuration of both PI Vision and PI Web API can be found in the troubleshooting section.

The Trendminer PI Vision plugin enables you to send your data directly from your PI vision board to your TrendHub platform ready for analysis. 

The advantage of this option is that there is now no need to look for your tags in the asset browser setup in TrendMiner, you select your tags in PI Vision and send them directly to TrendHub where they will be readily displayed for analysis.

With the first release of the PI Vision TrendMiner plugin, users can now access a PI Vision symbol in their symbol list.

PI_Vision_1.png
The symbol can be configured with the url of your TrendMiner environment (cloud or on-premise) and optional prefix of the connected historian.

Once setup, the TrendMiner symbol in PI Vision can open up all the attributes on your PI Vision display in the TrendHub interface in the same time frame as defined in your display.

Installation procedure

1. Download the navigationLink zip file from https://files.trendminer.com/hps/pivision/.

2. Use the file explorer to go to the PI Vision directory. In the file explorer navigation bar type in %pihome64%, this will open up the PI Vision directory.
e.g. C:\Program Files\PIPC

                 a. Navigate to \PIVision\Scripts\app\editor\symbols\ext.
                     e.g. C:\Program Files\PIPC\PIVision\Scripts\app\editor\symbols\ext

3. Extract the downloaded file in this directory.
    ! Important: do not change the names of these files.

     a. Three files are added to this directory:

  • i. sym-navigationLink.js
  • ii. sym-navigationLink-config.html
  • iii. sym-navigationLink-template.html

     b. Three directories, each containing one file, are added to this directory:

  • i. libraries/angular-piwebapi-kerberos-1.11.0.min.js
  • ii. icons/trendminer-icon.svg
  • iii. assets/open-in-trendhub.svg

4. Confirming the plugin is visible within PI Vision.

     a. Go to PI Vision
     e.g. https://example.com/PIVision, example.com has to be replaced with the configured url.

     b. Click on 'New Display' in the top right of the screen.

PI_Vision_2.png

     c. A new 'symbol' (highlighted in the picture below) has been added.

PI_Vision_3.png

Example usage

For this example another 'symbol' will be used to provide the data we want to visualize in TrendHub. More specifically the 'Trend symbol' will be used.

1. Click on 'New Display' in the top right of the screen.

PI_Vision_4.png

2. Select the 'Trend symbol' in the top bar.

PI_Vision_5.png

3. Select in the list below the assets or attributes/tags you want to visualize.

PI_Vision_6.png

4. Drag and drop the selected asset or attribute/tag onto the dashboard.
Example asset:

PI_Vision_7.png

Example attribute/tag:

PI_Vision_8.png

5. Repeat step 1-3 if you want to add multiple assets or attributes/tags.

PI_Vision_9.png

6. Select the 'TrendMiner Navigation Link symbol'.

PI_Vision_10.png

7. Select an asset or attribute/tag.

Note: This can be any random attribute/tag, it will not be included in the attributes/tags that will  be visualized in TrendHub. Selecting an attribute/tag in order to be able to drag and drop a symbol on the dashboard is a requirement of PI Vision.

8. Drag and drop the 'TrendMiner Navigation Link symbol' onto the dashboard.

PI_Vision_11.png

9. Right click on the 'Open in TrendHub' button and select 'Configure...', resulting in a sidebar appearing on the right side of the screen.

PI_Vision_12.png

     a. TrendMiner server: the full url pointing towards the TrendMiner installation e.g. https://my-trendminer-application.my-company.com.

     b.PI Web API url: the full url pointing towards the PI Web API e.g. https://my-pi-web-api-server.com/piwebapi

     c. Prefix: Sometimes historian servers in TrendMiner are configured with a prefix. Ask an admin what the configured prefixes for the servers are. If no prefix has been configured, this field can be left empty.

PI_Vision_13.png

PI_Vision_14.png

The screen where a configured prefix can be found by an admin.

10. Click the 'Open in TrendHub symbol' on the dashboard. This will open a view in TrendHub, visualizing all the attribute/tags that are configured on the other symbols that are on the dashboard.

PI_Vision_15.png

Note: Duplicate attributes/tags will be filtered out. In the examples used in this guide 'Temperature' and 'Concentration' are visible twice on the dashboard (step 5), once in the TrendHub visualization.

Important: All attributes/tags (used in steps 3. and 4.) must come from the same 'historian server'. Or in other words, they all need to use the same prefix (as described in step 9b).

Troubleshooting

Opening the developer tools (console / network tab)

If one of the solutions in the troubleshooting list refers to 'open the console' or 'open the network tab', these steps can be followed to do so.

The shortcut for all browsers is normally the key 'F12'.
For Firefox and Chrome on Windows and Linux 'Ctrl + Shift + i' should also work.
For Firefox and Chrome on MacOS Command + Option + i' should also work.

Manual steps for each browser are documented below.

Chrome

Official documentation

Firefox

Official documentation

Internet Explorer 11

Left click on the cogwheel in the top right of the browser window.

PI_1.png

Click on 'F12 Developer Tools'.

This will open the developer tools.

PI.3.png

Blocked by CORS policy

 

Quick solution

If PIVision is visited over 'http://', try to visit it over 'https://'.

Problem

When clicking on a correctly configured 'Open in TrendHub' button, nothing happens. When looking at the console it shows an error.

The error shown looks different for each browser:

Chrome

PI.4.png

Firefox

PI.5.png

Internet Explorer 11

PI.6.png

Solution

Make sure that the URL used, exists in the configuration of PI Web API.

To see which URL or 'origin' is allowed, the following link can be visited:
https://PI_SERVER/piwebapi/system/configuration 

PI_SERVER should be replaced by the server on which PI is installed. This is the part before '/PIVision' of the URL on which PI Vision can be viewed.

E.g. If http://my-company.something-else.com/PIVision is used to visit PI Vision, the URL for the PI Web API would be https://my-company.something-else.com/PIWebAPI.

Note: Depending on how the server is configured, this might show a screen that says 'Insecure connection'.

When visiting this URL, a response will be shown including the 'CorsOrigins' (see following figure).

The 'CorsOrigins' list should contain the 'origin' on which PI Vision is visited.

PI.7.png

E.g. http://tm-pi2018.ad.trendminer.net/PIVision is used, the 'origin' in this case is 'http://tm-pi2018.ad.trendminer.net', which is not in the list of 'CorsOrigins'. However 'https://tm-pi2018.ad.trendminer.net' is in the list of 'CorsOrigins'.

 

PI 

Disclaimer: Not all steps might be necessary in order for PI Vision and PI Web API to work correctly.

Prerequisites

  • PI has to be installed on a server
  • The server must use domain users (e.g. TRENDMINER\tm-user)
  • An asset server must be configured
  • Know that you have to 'Check In' changes done in 'PI System Explorer':
    • Click 'Check In' in the menu bar

PI1.png

Click 'Check In' on the dialog

PI2.png

Adding a database

1. Open 'PI System Explorer'

PI3.png

2. Click on 'Database' (top left)

PI4.png

3. Click on 'New Database' (top left of dialog)

PI5.png

4. Click 'Apply' and 'OK'

PI6.png

5. Click 'OK'

PI7.png

Adding assets and attributes/tags

 

Adding an asset

1. Right click on 'Elements' in the list on the left and click on 'New Element'

PI8.png

2. Click on 'OK'

PI9.png

3. Right click on the newly created element and select 'Properties'

PI10.png

4. Fill in the information for this asset

PI11.png

Adding an attribute/tag to an asset

1. Select an asset in the left panel and select 'Attributes' tab

PI12.png

2. Click on 'New Attribute', this will open a panel on the right side

PI13.png

3. Fill in the information and select 'PI Point' as 'Data Reference'

PI14.png

Note: This fills in '\\TM-PI2018' because we selected while adding the database.

PI15.png

4. Click on 'Settings ...'

PI16.png

5. Click on the 'search icon' (the magnifying glass)

PI17.png

6. Click on 'Search', select the data representing the temperature data and click 'OK'

PI18.png

7. This fills in the 'Tag name', select '°C' as 'Source Units' and click 'OK'

PI19.png

8. This will update the information

PI20.png

Note: Do not forget to 'Check In' your changes.

PI Vision - Login

1. Visit https://[THE URL]/PIVision/#/

  • Replace [THE URL] with the actual URL/domain on which PI Vision is installed. E.g. https://tm-pi2018.trendminer.net/PIVision/#/

2. Login with the credentials for a domain user that has access to the server on which PI Vision is installed

PI21.png

Note: The URL, domain and user will be different compared to this image

PI Vision - Make database visible

1. Go to https://[THE URL]/PIVision/Admin and login

  • Replace [THE URL] with the actual URL/domain on which PI Vision is installed. E.g. https://tm-pi2018.trendminer.net/PIVision/Admin

2. In the left panel, click on 'Configuration'

3. Choose the 'Asset Servers' tab

PI22.png

4. In the 'Databases' column, toggle on the databases you want to be visible in PI Vision and hit Save (bottom right)

PI23.png

5. Visit https://[THE URL]/PIVision/ and login

  • Replace [THE URL] with the actual URL/domain on which PI Vision is installed. E.g. https://tm-pi2018.trendminer.net/PIVision/

6. Click on PI24.png in the top bar

7. In the left panel the database is now visible to use

PI25.png

PI Vision - Re-index

In Adding assets and attributes/tags assets and attributes/tags got added to a database.

In PI Vision - Make database visible the database was made visible to use in PI Vision.

This indexed the assets and attributes/tags.

In the scenario where you decide to add more assets or attributes/tags to the database that has already been indexed, a re-indexing of the database is required.

1. Go to https://[THE URL]/piwebapi/admin/search/database.html and login

  • Replace [THE URL] with the actual URL/domain on which PI Vision is installed. E.g. https://tm-pi2018.trendminer.net/piwebapi/admin/search/database.html

PI26.png

2. Click on 'Rebuild Index' of the database and wait until it has a green check mark again, this can take a while

PI27.png

Note: The AF elements did not change, because in this scenario I added 2 extra attribute/tags and 0 assets.

3. Go to https://[THE URL]/PIVision and click PI28.png in the top bar

  • Replace [THE URL] with the actual URL/domain on which PI Vision is installed. E.g. https://tm-pi2018.trendminer.net/PIVision

4. Navigate in the database

PI29.png

5. Select the asset, this will now show the indexed attributes

PI30.png

PI Vision & PI Web API & PI Web Crawler - Troubleshooting

In any of the following scenarios:

  • Able to see the database in PI Vision, unable to access PI Web API (Unauthorized)
  • Unable to see the database in PI Vision, able to access the database through PI Web API
  • Re-indexing does not add assets and attributes/tags to PI Vision

Use the following steps to make sure everything is configured correctly:

PI System Explorer - Attributes must be of type 'Configuration Item'

1. Open PI System Explorer and drill down to the System Configuration in the left panel

PI31.png

PI32.png

2. Open the Attributes tab and check that all the attributes are a 'Configuration Item' in the right side panel

WRONG (Properties has the value '<None>')

PI33.png

RIGHT (Properties has the value 'Configuration Item'

PI34.png

 

Authorization

Normally the Authentication of PI Vision and the PI System Explorer are configured to use 'Windows Authentication' and 'Kerberos'. However, in a situation (like ours) where devices other than a Windows system need to authenticate, another option needs to be available. There are two options that would work. The first option is Basic Authentication and the other option is Anonymous Authentication. Because Anonymous Authentication does not require any credentials, it is preferred to use Basic Authentication.

Note: Windows Authentication + Kerberos is necessary for PI Vision and both the PI Web services to work properly. Never delete Kerberos as an authentication method.

IIS Manager - Verify Authentication settings

1. Open IIS Manager and in the left panel drill down to 'Default Web Site' and double click on 'Authentication' in the right side

PI35.png


PI36.png

2. Verify that both Windows Authentication and Basic Authentication are Enabled

PI37.png
Note: To set the status to 'Enabled', right click on 'Disabled' and click on 'Enabled'

PI System Explorer - Verify Authentication settings

1. Open PI System Explorer, drill down to the System Configuration in the left panel. Select the 'Attributes' tab.

PI38.png


PI39.png

2. In the right side panel click on PI60.pngat the end of the 'Value' property.

PI40.png

3. Verify that both Kerberos and Basic are in Values

PI41.png

Note: Kerberos must always be in here!
Note: If Basic is not in here, click on 'Add' and change the Value in the field next to 'Value'

Reminder: Check In your changes!

Verify user attached to PI Web Crawler and PI Web API service is a domain user

1. Open Services

PI42.png

PI43.png

2. Verify that the user in the 'Log On As' column, is a Domain User, for both the PI Web Crawler as well as the PI Web API
a. Open up User Accounts and click on 'Manage User Accounts'

PI44.png

PI45.png

b. Confirm that the user has PI61.png as an icon, this means it is a Domain User

Note: PI62.png is the icon for a Local User

For this example, we can see that TRENDMINER\PIVisionService is the user attached to both the PI Web Crawler and PI Web API and that it is a Domain User.

PI46.png

Alternative way is to open 'Edit local users and groups', click on 'Users' and confirm that the user (e.g. TRENDMINER\PIVisionService) is NOT in this list.

PI47.png

PI48.png

Verify the group of the domain user

The user attached to the services in ' Verify user attached to PI Web Crawler and PI Web API service is a domain user' needs to be in the correct group. Confirm this by:

1. Open 'Edit local users and groups' and click on 'Groups'

PI49.png

PI50.png

2. Double click on 'PI Web API Admins' and confirm that the user is in the 'Members' list
PI51.png

Note: If this is not the case, click on 'Add...', type in the name of the user and click on 'Check Names', then click 'OK'

PI52.png

3. Do step 2. for PI Vision Admins as well (not sure if necessary, but in the current configuration this is the case)

Configure PI Web API

Documentation of OSIsoft

Most important steps with screenshots:

PI_53.png

PI54.png

PI55.png

PI56.pngPI57.png

PI58.png

Note: The URL in this screenshot is also the URL that has to be configured in the 'PI Web API url' field of the 'open in TrendHub' custom symbol