AVEVA™ PI Vision OMI App User Guide

aveva.com
© 2022 AVEVA Group plc and its subsidiaries. All rights reserved.

No part of this documentation shall be reproduced, stored in a retrieval system, or transmitted by any means,
electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of AVEVA.
No liability is assumed with respect to the use of the information contained herein.
Although precaution has been taken in the preparation of this documentation, AVEVA assumes no responsibility
for errors or omissions. The information in this documentation is subject to change without notice and does not
represent a commitment on the part of AVEVA. The software described in this documentation is furnished under
a license agreement. This software may be used or copied only in accordance with the terms of such license
agreement.
ArchestrA, Avantis, Citect, DYNSIM, eDNA, EYESIM, InBatch, InduSoft, InStep, IntelaTrac, InTouch, OASyS,
PIPEPHASE, PRiSM, PRO/II, PROVISION, ROMeo, SIM4ME, SimCentral, SimSci, Skelta, SmartGlance, Spiral
Software, WindowMaker, WindowViewer, and Wonderware are trademarks of AVEVA and/or its subsidiaries. An
extensive listing of AVEVA trademarks can be found at: https://sw.aveva.com/legal. All other brands may be
trademarks of their respective owners.
Publication date: Friday, February 4, 2022
Contact Information
AVEVA Group plc
High Cross
Madingley Road
Cambridge
CB3 0HB. UK
https://sw.aveva.com/
For information on how to contact sales and customer training, see https://sw.aveva.com/contact.
For information on how to contact technical support, see https://sw.aveva.com/support.
To access the AVEVA Knowledge and Support center, visit https://softwaresupport.aveva.com.
Contents

Chapter 1 AVEVA™ PI Vision OMI App ............................................................... 5

AVEVA PI Vision OMI App Requirements ...............................................................................................6
SSL Certificate for Run-Time Nodes........................................................................................................7
Export the PI Vision SSL Digital Certificate ................................................................................................... 7
Install the Exported SSL Digital Certificate ................................................................................................... 7

Chapter 2 Configure the AVEVA PI Vision OMI App ............................................ 9

Configure PI Vision Properties ...............................................................................................................9
PI Vision OMI App Properties ..................................................................................................................... 12
Types of Displays ........................................................................................................................................ 17
Dashboard Displays............................................................................................................................. 18
Configure Dashboard Displays ................................................................................................................... 18
Ad Hoc Displays .................................................................................................................................. 20
Configure Ad Hoc Displays ......................................................................................................................... 20
Syntax Rules for Data Items in Ad Hoc Displays ......................................................................................... 21
Freeform Displays ............................................................................................................................... 21
Configure Freeform Displays ...................................................................................................................... 22
Time Properties .................................................................................................................................. 22
Contextualization................................................................................................................................ 23
Contextualized Dashboard Displays ........................................................................................................... 23
Contextualized Ad Hoc Displays ................................................................................................................. 25
PI Vision OMI App Scripting ................................................................................................................. 27
Scripting Methods ...................................................................................................................................... 28
PI Vision OMI App Properties in Layout Scripts ......................................................................................... 28
Event Scripting............................................................................................................................................ 29

Chapter 3 PI Vision OMI App Property Validation ............................................ 30

Chapter 4 Using the PI Vision OMI App During Runtime .................................. 32

Chapter 5 Troubleshooting .............................................................................. 33

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 3
 Chapter 6 Upgrade and Migration of the PI Vision OMI App ............................ 35

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 4
Chapter 1

AVEVA™ PI Vision OMI App

The AVEVA™ PI Vision OMI App enables a PI Vision dashboard or ad hoc display to be shown within a layout
pane of a running ViewApp. Displays can be configured to follow the current navigation context, and thus allow
users to view the status of assets in different locations. In this document, the AVEVA™ PI Vision OMI App is also
referred to as the OMI app to distinguish between the app and the native PI Vision application.
The OMI app incorporates the ease-of-use and fast access for which PI Vision is noted. The OMI app also allows
some of PI Vision's ad hoc visualization capabilities, including trends, meters and charts, to be utilized directly in
an OMI ViewApp. Note that the OMI app includes only a subset of PI Vision's capabilities.

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 5
 AVEVA™ PI Vision OMI App User Guide
Chapter 1 – AVEVA™ PI Vision OMI App

AVEVA PI Vision OMI App Requirements

Preparing the PI Vision OMI App to run in an OMI ViewApp includes several preliminary steps that must be
completed by both PI Vision designers and ViewApp builders. The primary focus of this User Guide is to describe
the work done by the ViewApp builder to integrate the PI Vision OMI App into System Platform.
Compatible PI System Versions
The AVEVA PI Vision OMI App is compatible with the following OSIsoft PI System products:
 AF SDK: version 2.10. The AF SDK is used by ad hoc displays within the OMI app for search and retrieval of
data items when in context mode.
 PI Coresight: version 3.0 and later. PI Coresight 3.0 was originally named PI Coresight 2016, and was
renamed PI Vision 2017 at the time of the version 3.2 release.
AVEVA PI Vision OMI App Requirements
Before you configure the AVEVA PI Vision OMI App, you must:
 Be familiar with the PI Vision system.
 Have an operational PI Vision application server.
 Have Asset Framework (AF) server(s), data archive server(s), and any other required PI System components
running and configured. All databases and other components of the PI System must be installed and
configured with the appropriate user access permissions as needed for the displays you want to create and
use at run time.
 Have a hierarchy of assets that exists with the same name as it appears in the OMI Navigation Model
hierarchy.
 OSIsoft PI System products, including the Asset Framework server and PI Vision server, must be in the same
domain as the AVEVA OMI client workstation. Make sure that users of the OMI client workstations, including
the logged-in Windows user and the user logged-in to the OMI ViewApp, have user permissions to access
the PI System products.
 OMI client workstations must have the PI System AF client installed, and have the appropriate databases
and servers configured. This is required for contextualization to work within the PI Vision OMI App.
 Have an SSL digital certificate from your PI Vision server node installed on OMI client workstations that will
run the PI Vision OMI App. See SSL Certificate for Run-Time Nodes on page 7 for details.
 Have enough experience with System Platform to be able to create screen profiles, layouts, and ViewApps.
Note: A FLEX license is required to download the PI Vision OMI App from the AVEVA System Platform
product website.
Make sure that the asset hierarchy and asset names match between the hierarchies by renaming assets and
reconfiguring hierarchies as needed. Synchronization between the two will allow the PI Vision app to work in the
context of the currently selected asset in the OMI ViewApp during run time.
Note that the PI Vision OMI App does not automatically synchronize the System Platform hierarchy with the
Asset Framework server hierarchy of the PI System. This synchronization work is outside the scope of this user
guide.

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 6
 AVEVA™ PI Vision OMI App User Guide
Chapter 1 – AVEVA™ PI Vision OMI App

SSL Certificate for Run-Time Nodes

An SSL certificate must be installed on OMI workstations that will use the PI Vision OMI App at run time. This
must be the same SSL certificate that is installed on the PI Vision application server.
If an SSL certificate is not configured, using the PI Vision OMI App for Dashboard displays in context mode will
fail and result in an SSL exception. Contextualization is enabled by the Follow Current Context property. For
more information, see Contextualization on page 23.
For additional information about using the certificate, see the following sections:
 Export the PI Vision SSL Digital Certificate on page 7
 Install the Exported SSL Digital Certificate on page 7

Export the PI Vision SSL Digital Certificate

Export the SSL digital certificate from your PI Vision application server. This certificate is normally obtained from
a trusted third party trusted certificate registrar, and is installed on the PI Vision application server during the
installation of PI Vision software. For more information, refer to the PI Vision Installation and Administration
Guide.
The simplest way to access the certificate is through a web browser on the PI Vision web server.
1. Open a PI vision dashboard in the browser of your choice on the PI Vision application server.
2. Click on the site information (the lock symbol) in the address bar. This may vary based on the type of
browser you are using.
3. In the connection details menu, click to see the certificate. This option varies, based on which browser you
are using.
Look for Show Certificate or the Certficate Icon and click on it. This will bring up the Certificate window
where you can click on the Details tab.
4. Click on the CopyToFile button. This opens the Export Certificate Wizard. Follow the wizard steps to finish
exporting the certificate.
Note that there are a number of different methods to export this certificate from the PI Vision web server. Some
of these methods are listed in the following Digicert web page:
 PFX Certificate Export | Certificate Utility | DigiCert.com
https://www.digicert.com/kb/util/pfx-certificate-management-utility-import-export-instructions.htm

Install the Exported SSL Digital Certificate

The SSL certificate you exported from the PI Vision server must be installed on each AVEVA OMI client
workstation that will run the PI Vision OMI App.

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 7
 AVEVA™ PI Vision OMI App User Guide
Chapter 1 – AVEVA™ PI Vision OMI App

A simple way to install the certificate is as follows:

1. Go to the location of the downloaded certificate and right-click on the certificate file.
2. From the context menu, select the Install Certificate option. This opens the Import Certificate Wizard.
3. Follow the wizard steps to save the certificate in the appropriate certificate store, as directed by your IT
department.
Note that there are a number of different methods to install the certificate on the client machine. Some of these
methods are listed in the following Digicert article:
IIS 10 Exporting/Importing SSL Certificates | digicert.com
https://www.digicert.com/kb/ssl-support/certificate-pfx-file-export-import-iis-10.htm#import-pfx

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 8
Chapter 2

Configure the AVEVA PI Vision OMI App

Preparing the AVEVA PI Vision OMI App to run in an AVEVA ViewApp includes several major workflows that must
be completed by both PI Vision designers and ViewApp builders. The primary focus of this User Guide is to
describe the work done by the ViewApp builder to integrate the PI Vision OMI App into System Platform.
On the PI Vision side, a designer must ensure that the hierarchy of assets matches the System Platform
hierarchy. In addition, when using PI Vision dashboards when the PI Vision OMI App is in context mode,
keywords must be added to ensure that the correct dashboard is selected and displayed by the OMI app at run
time.
Configuring the OMI app requires setting properties for the app in the System Platform Layout Editor. These
properties are described in the following sections.
Note that some validation of property settings is done during configuration. Configuration errors will be
highlighted by a red box around the mis-configured item.

Configure PI Vision Properties

PI Vision app properties can be shown in the Layout or ViewApp editors by placing the PI Vision app on a layout
pane. After adding the app to a pane, its properties appear on the Properties page by functional groups.
To configure PI Vision OMI App properties
1. Open the Layout or ViewApp Editor and show the items listed in the System Platform IDE Toolbox tab.
2. Open the folder in the Toolbox that contains the PIVisionApp and select it.
3. Drag and drop the PIVisionControl (the app thumbnail) onto a layout pane.
4. Select the Properties tab for the layout.
The Properties tab shows the properties of the PI Vision App, and is similar to the following screen capture.
Properties are categorized as:
o General: General properties are similar to the general properties of other OMI apps and define the
control, content, and pane names.
o Connection: Connection properties define how the app will connect to the PI Vision server and website.
o Dashboard Displays: These properties define if a dashboard (saved) display will be shown, and define
the display to be shown. Ad hoc and freeform displays must be disabled if a dashboard display will be
shown.
o Ad Hoc Displays: These properties define the parameters for showing ad hoc (temporary) display
queries. Dashboard and freeform displays must be disabled if an ad hoc display will be shown.

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 9
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

o Freeform Displays: These properties define the parameters for showing a freeform display from a URL.
Ad hoc and dashboard displays must be disabled if a freeform display will be shown.
o Context: This property disables or enables the ability to view the attributes of the currently selected
asset in dashboard and ad hoc displays. If disabled, the app will show only the performance of those
attributes defined by property settings within the dashboard or ad hoc display settings.
Note: Context is not applicable to freeform displays.
o Time Range: These optional properties set start and end times for dashboard or ad hoc displays (not
applicable to freeform displays).
o Appearance: These properties disable/enable toolbars and the Kiosk mode for dashboard and ad hoc
displays (not applicable to freeform displays).
o Browser: This property lets you designate a cascading style sheet to control the appearance of
dashboard and ad hoc displays (not applicable to freeform displays).

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 10
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

For more information about PI Vision OMI App properties, see PI Vision OMI App Properties on page 12.

Configuration errors are indicated by a red outline around the misconfiguration.

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 11
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

PI Vision OMI App Properties

Connection

Web Server Fully qualified computer name of the PI Vision server.

Underlying Default Value Read/Write Runtime Scriptable

Data Type Mode Property
String Empty Read/Write Yes Yes
Website Name of the PI Vision website. Typically, the website name is PIVision.

Underlying Default Value Read/Write Runtime Scriptable

Data Type Mode Property
String Empty Read/Write Yes Yes
Dashboard Displays

View Dashboard Boolean property that enables/disables viewing a saved display from the PIVision
Display server. If True, the Dashboard Id is used to determine which dashboard display to
show at runtime.
Boolean properties for setting display mode (View Dashboard Display, View Ad hoc
Display, View Freeform Display) are mutually exclusive. If this setting is True, the other
display settings must be set to False.

Underlying Default Value Read/Write Runtime Scriptable

Data Type Mode Property
Boolean True Read/Write Yes Yes
Dashboard Id Display Id, as an integer of a saved PIVision display URL. For example, the Display Id is
3117 for a display with the following URL:
https://PIVisionwebserver/PIVision/#/Displays/3117/PowerAnalysis

Underlying Default Read/Write Runtime Scriptable

Data Type Value Mode Property
Integer 0 Read/Write Yes Yes
Asset Path Specifies an asset path for an existing display to swap related assets that share the
same PI AF template.
Note: This is an additional, optional configuration on the saved dashboard display.
This property lets you configure an existing display to use other assets that share the
same AF template. See Configure Dashboard Displays on page 18 for more information.

Underlying Default Value Read/Write Runtime Scriptable

Data Type Mode Property
String Empty Read/Write Yes Yes

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 12
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

Ad Hoc Displays

View Ad hoc Boolean property that enables/disables the ad hoc display mode. If True, you can
Display specify data items to show in a single temporary trend (ad hoc) display.
Boolean properties for setting display mode (View Dashboard Display, View Ad hoc
Display, View Freeform Display) are mutually exclusive. If this setting is True, the other
display settings must be set to False.

Underlying Default Value Read/Write Runtime Scriptable

Data Type Mode Property
Boolean False Read/Write Yes Yes
Symbol Type Determines the type of symbol that is used for a temporary (ad hoc) display.
Depending on the symbol type, you can add multiple data items per symbol. If you do
not specify a symbol type, the property uses Trend as the default.
Each specified data item in an ad hoc display is shown in a single trend, using the
specified Symbol Type. The symbol type is designated by an enum type, which
correlates to a PIVisionSymbolType, and can be any of the following:

Trend (default) VerticalGauge XYPlot

Value HorizontalGauge ACT (Asset Comparison Table)
Table RadialGauge
If no symbol is specified, a trend symbol type is used for the ad hoc display.

Underlying Default Value Read/Write Runtime Scriptable

Data Type Mode Property
Enum Trend Constant No No
Data Items Specifies one or more data items for a temporary (ad hoc) PI Vision display. These
items will appear regardless of the currently selected navigation node, even if Follow
Current Context is True and you have navigated away from the asset containing the
specified data items. See Configure Ad Hoc Displays on page 20 for additional
information about the Data Items property.

Underlying Default Value Read/Write Runtime Scriptable

Data Type Mode Property
String Empty Read/Write Yes Yes

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 13
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

Context Asset Name of the of asset server for the PI system. The app uses this property to connect to
Server the AF server using the currently logged in Windows user credential. Once connected,
it gets attributes automatically from the currently selected asset, when the Follow
Current Context property is enabled.
This is an optional property. If a Context Asset Server is not configured, the PI Vision
OMI App tries connecting to the default AF Server.

Underlying Default Value Read/Write Runtime Scriptable

Data Type Mode Property
String Empty Read/Write Yes Yes
Context Asset Name of the Asset database that contains the attributes of the current asset on a given
Database AF server.
This property is used to connect to the AF server to get the attributes automatically
from the currently selected asset, when the Follow Current Context is enabled.
This is an optional configuration property. If a context database is not specified, the PI
Vision OMI App tries to discover the current selected asset from the default database
of the given AF server.

Underlying Default Value Read/Write Runtime Scriptable

Data Type Mode Property
String Empty Read/Write Yes Yes
Max Context Determines the number of data items from the current context that can be shown in
Data Items to the ad hoc display, when the Follow Current Context property is enabled. A value of 10
Show or less is recommended. The default is 10.
When Follow Current Context is disabled, the Max Context Data Items property is
inactive, and any number entered is ignored.

Underlying Default Value Read/Write Runtime Scriptable

Data Type Mode Property
Integer 10 Read/Write Yes Yes

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 14
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

Freeform Displays

View Display Boolean property that enables/disables the freeform display mode. If True, the Display
URL URL Parameters property appends to the base URL configured in the Connection
properties, and shows the display called by the complete URL at runtime.
Boolean properties for setting display mode (View Dashboard Display, View Ad hoc
Display, View Freeform Display) are mutually exclusive. If this setting is True, the other
display settings must be set to False.
When freeform display mode is enabled, Display URL Parameters is the only other
property (in addition to Connection properties) that is used for configuring the display
for the given PI Vision webserver and website. All other properties, including Time
Range and Appearance, are ignored.

Underlying Default Value Read/Write Runtime Scriptable

Data Type Mode Property
Boolean False Read/Write Yes Yes
Display URL Specifies parameters to be appended to the base path of the configured PI Vision web
Parameters server URL for a display from PI Vision. The Display URL Parameters property lets you
directly call displays that are not dashboard (saved) or ad hoc displays, such as
EventDetails or EventComparison displays. You can also include additional parameters
(Time Range, Appearance, etc.).
For example:
 To call an Event Comparison, you would enter something like
"EventComparison/24"
 To call an Event Detail display, you would enter something like
"EventDetails?srcdisplayid=23&server=PIVISIONSERVERP&eventid=c80dc366-82e4
-11ec-a058-00155d754303"

Underlying Default Value Read/Write Runtime Scriptable

Data Type Mode Property
String Empty Read/Write Yes Yes

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 15
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

Time Range

Start Time Specifies the start time of a dashboard or ad hoc display. If this property is not
specified, the start time defaults to the current time at run time.
Note: Start and end times must be used in pairs. OSIsoft recommends using ISO 8601
standards because they are not affected by time zones. Start/End time properties
cannot be used with freeform displays.

Underlying Default Value Read/Write Runtime Scriptable

Data Type Property
String Empty Read/Write Yes Yes
End Time Specifies the end time of a display. If this property is not specified, the end time
defaults to eight hours from the current time.
Note: Start and end times must be used in pairs. OSIsoft recommends using ISO 8601
standards because they are not affected by time zones. Start/End time properties
cannot be used with freeform displays.

Underlying Default Value Read/Write Runtime Scriptable

Data Type Property
String Empty Read/Write Yes Yes
Context

Follow Current If enabled, automatically discovers the applicable ad hoc or dashboard display
Context (depending on mode) associated with the asset in the AF server. Context cannot be
used with freeform displays.

Underlying Default Value Read/Write Runtime Scriptable

Data Type Property
Boolean False Read/Write Yes Yes
Appearance

Hide Toolbar Boolean value that determines if the display toolbar is shown or hidden. When set to
true, the toolbar is hidden. This property cannot be used with freeform displays.

Underlying Default Value Read/Write Runtime Scriptable

Data Type Property
Boolean True Read/Write Yes Yes

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 16
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

Hide Timebar Boolean value that determines if the display timebar is shown or hidden. When set to
true, the timebar is hidden. This property cannot be used with freeform displays.

Underlying Default Value Read/Write Runtime Scriptable

Data Type Property
Boolean False Read/Write Yes Yes
Hide Sidebar Boolean value that determines if the display sidebar is shown or hidden. When set to
true, the sidebar is hidden. This property cannot be used with freeform displays.

Underlying Default Value Read/Write Runtime Scriptable

Data Type Property
Boolean True Read/Write Yes Yes
Kiosk Mode Boolean value that determines if the PI Vision display is operating in kiosk mode. In
kiosk mode, users cannot search for data or save the display. This property cannot be
used with freeform displays.

Underlying Default Value Read/Write Runtime Scriptable

Data Type Property
Boolean True Read/Write Yes Yes
Browser Property
StyleSheet Applies a string-based cascading style sheet (CSS) to the PI Vision page.

Data Type Default Value Read-Write Runtime Layout

Mode Property Scriptable
String Empty Read/Write Yes Yes

Types of Displays
The PI Vision OMI App lets you choose different types of displays to show in a particular pane during run time:
 Dashboard
 Ad Hoc
 Freeform

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 17
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

The types are mutually exclusive during configuration. Therefore, only one type can be configured for each
instance of the PI Vision OMI App. If you enable more than one during configuration, an error indication (red
highlight around the misconfiguration), will be shown.

Dashboard Displays on page 18, also called saved displays, show a previously saved display from your PI Vision
server.
Ad Hoc Displays on page 20, also called temporary displays, show attributes from the specified asset server and
asset database, and then plot the items on an ad hoc display.
Freeform Displays on page 21 let you specify a URL within the app during configuration. Freeform displays can
be dashboards displays, comparison displays, or any other valid URL that contains the PI System data that you
want to show at run time. In contrast to the other display types, you have to manually enter all URL parameters,
instead of configuring properties that are then passed to a PI System server.
Contextualized Displays
Both dashboard and ad hoc displays can be configured to to show attributes that belong to the currently
selected asset. This is determined by the Follow Current Context property. When Follow Current Context is
disabled (set to False), the display does not change when you select different assets. When Follow Current
Context is enabled (set to True), the display changes to the context of the selected asset. See Contextualization
on page 23 for more information.
Note: Freeform displays cannot be contextualized.

Dashboard Displays
Dashboard displays are saved displays on the PI Vision server. Each saved display has a unique ID (Display ID)
that can be used to call the display. The Display ID property is used to designate which display to show in the
ViewApp.

Configure Dashboard Displays

Dashboard displays use the Dashboard ID, a component of the display URL, to find the display to be shown. The
following properties must be specified to show dashboard displays in when the PI Vision OMI App is in
non-contextual mode:
 View Dashboard Display must be True (set the checkmark next to the property).
 Dashboard ID must be set with an integer that matches the saved PI Vision dashboard ID to be displayed.

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 18
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

View Dashboard Display and and the other view boolean values (View Dashboard Display, View Freeform
Display) are mutually exclusive. Make sure View Ad hoc Display and View Freeform Display are disabled if View
Dashboard Display is enabled.
Each saved PI Vision display (dashboard) has a unique URL, which includes a unique number. The Dashboard ID
property in the OMI app is configured with this number, for example:
https://PIVisionwebserver/PIVision/#/Displays/3117/PowerAnalysis
In this example, you would configure the Display ID property as 3117.
Asset Path is an optional property that you can use to to swap related assets that share the same PI Vision AF
template with an existing dashboard display. Specify the asset by appending the asset to the URL, followed by
the path of the new asset.
The Asset Path property lets you configure an existing display to use other assets that share the same AF
template. To do this:
1. Obtain the paths of the assets you want to use to replace the existing assets on the display. You can find
these paths in PI Vision search results, or in PI System Explorer.
2. Specify the asset path in this property to show in a display.
Path for a data item on a PI AF server: \\AFServerName\DatabaseName\ParentElement\ChildElement

The following screenshot shows a number of saved displays on the PI Vision server.

Note: Dashboard displays can be configured to show the status of different assets as you navigate around your
system, via the Follow Current Context property. See Contextualized Dashboard Displays on page 23 for more
information.

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 19
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

Ad Hoc Displays
To enable ad hoc (temporary) displays within the OMI App for PI Vision, you must set View Ad hoc Display to
True by setting the checkmark.
This setting and the other view boolean values (View Dashboard Display, View Freeform Display) are mutually
exclusive. Make sure the other display types are disabled, and that Dashboard ID is set to 0 when configuring ad
hoc displays.
The Symbol Type property specifies a PIVisionSymbolType that shows each data item of the ad hoc display in a
single trend.

Configure Ad Hoc Displays

The Data Items parameter lets you designate the path on the PI Vision AF server to the data items that you want
shown, regardless of the current context. The number of additional data items that you specify here has no
effect on, and is not constrained by the number context items shown, as defined by the Max Context Data Items
to Show property.
You can find the path to the data item by navigating to the asset in the PI System Explorer. Then, copy the path
from the Settings pane.

Use the following format to designate data items from an AF Server for display in the PI Vision OMI app:
\\AFServerName\DatabaseName\ParentElement\ChildElement|ChildAttribute
To select an item from a PI Data Archiver server, use the following format:
\\ArchiveServerName\TagName

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 20
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

Use the full URI of the asset or attribute. For example, to plot all attributes of an asset at run time, provide the
URI of the asset, as shown in following example:
\\AFServer1\pumpcbm\pump station\plant
To specify a particular attribute of an asset to display, append the attribute name to the asset name, using the
pipe symbol as separator between asset name and attribute:
\\AFServer1\pumpcbm\pump station\plant|bearing temperature
To specify multiple attributes, use a semicolon as the separator between attributes. You must provide the full
asset name for each attribute specified, even if all the attributes belong to the same asset.
\\AFServer1\pumpcbm\pump station\plant|bearing temperature; \\AFServer1\pumpcbm\pump
station\plant|pump\flow rate; \\AFServer1\pumpcbm\pump station\plant|pump speed
Note: Ad hoc displays can be configured to show show the status of different assets as you navigate around your
system, via the Follow Current Context property. See Contextualized Ad Hoc Displays on page 25for more
information.

Syntax Rules for Data Items in Ad Hoc Displays

The following points summarize the syntax rules for specifying data items to show in an ad hoc display:
 Use the pipe (|) character to separate the attribute name from the asset name.
 Use semicolons to separate multiple data items. You must provide the full path to the server for each data
item.
Example:
\\AFserver1\Houston\B-210|Temperature;\\AFserver\B-210|Pressure
 If you specify an asset in the Data Items parameter without including an attribute, all of the plottable
attributes that belong to the asset will appear in the symbol.

Freeform Displays
To enable freeform displays within the OMI App for PI Vision, you must set View Freeform Display to True by
setting the checkmark.
View Freeform Display and the other view boolean display type values (View Dashboard Display, View Ad Hoc
Display) are mutually exclusive. Make sure the other display types are disabled, and that Dashboard ID is set to 0
when configuring freeform displays.
Freeform displays use the base URL configured for the app by the Web Server and Website parameters, and
then append additional arguments to the base URL through the Display URL Parameters property. To configure
a freeform display, you must enter the Display URL Parameters property with parameters needed. See PI Vision
OMI App Properties on page 12 for details about the Display URL Parameters property.
Other properties that can be configured in the OMI app, such as time and appearance parameters are ignored.
To pass these additional parameters, you must configure them in the Display URL Parameters property.

Note: Freeform displays cannot be contextualized.

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 21
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

Configure Freeform Displays

URL Composition
A typical URL for a freeform display includes the following components:
Base URL: The base URL uses the configured Web Server and Website properties under the Connection
category. Base URL example:
https://PISystemServer/PIVision/#

URL Parameters: You can pass additional URL parameters that are appended to the base URL, via the Display
URL Parameters property. For example, you can pass parameters to show an event comparison display, to
configure the pane appearance via a stylesheet or to hide the toolbar, or to configure a time range.
For an Event Detail display, enter the following Display URL Parameters:
EventDetails?srcdisplayid=23&server=PIVISIONSERVERP&eventid=c80dc366-82e4-11ec-a058-00155d754303
For an Event Comparison display, enter:
EventComparison/24
To hide the toolbar on an Event Display, enter:
EventDetails?server=srcdisplayid=23&server=PIVISIONSERVERP&eventid=c80dc366-82e4-11ec-a058-00155d754
303&hidetoolbar

To configure the time range on an event Comparison Display, enter:

EventComparison/24?starttime2/1/2022&endtime2/2/2022

Time Properties
Dashboard and ad hoc displays allow you to specify start and end times for visualizing your data.
Note: The start/end time properties cannot be directly applied to freeform displays. If you wish to provide a
time interval for a freeform display, you must pass the start and end times through the Display URL Parameters
property.
Start Time: Specifies the start time of the display. If this property is not specified, the start time defaults to the
current time. Start and end times must be used in pairs. OSIsoft recommends using ISO 8601 standards because
they are not affected by time zones.
End Time: Specifies the end time of the display. If this property is not specified, the end time defaults to 8 hours
from the current. Start and end times must be used in pairs.
If no start and end times are specified, the time range of the saved display applies.

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 22
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

Contextualization
Both dashboard displays and ad hoc displays can be contextualized. Contextualization is enabled by setting the
Follow Current Context property to true. With contextualization enabled, data applicable to the
currently-selected asset is shown for both dashboard and ad hoc displays. Your OMI asset hierarchy and
navigation node names must correlate with the structure of your PI Vision AF database for contextualization to
work.
Note: Freeform displays cannot be contextualized.

Contextualized Dashboard Displays

Contextualization for dashboard displays works by discovering the dashboard that contains the same keyword as
the name of the current asset.
Associate the saved PI Vision dashboard displays with one or more keywords, where at least one of the
keywords is an asset name. The keyword list from the saved PI Vision displays is matched against the currently
selected asset name in OMI ViewApp.
If more than one dashboard has the same keyword that matches the asset, the first dashboard that matches the
asset name is shown, and the remainder of the dashboards are ignored. A custom flag in the logger will provide
a message if this occurs.
From the keyword data, the Dashboard ID is retrieved by an internal web API call to PI Vision. This Dashboard ID
is then used to retrieve the saved display.
The currently logged-in Windows user credential is used to retrieve the keyword and Dashboard ID.
To contextualize Dashboard Displays
1. Enable the Follow Current Context property.
2. Use the PI Vision UI to add keywords to the saved display. This is required for dashboard displays to work
contextually within the PI Vision OMI app.
Keywords assigned to displays should correlate with the appropriate asset names. As you navigate to an
item with has the same name as a keyword, the applicable display is shown.
Note: Keywords are added to displays from within the PI Vision application, not the OMI app.

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 23
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

You can add multiple keywords, using a semicolon as the separator. The PI Vision OMI app then searches for
displays within the PI Vision Asset Framework to find the display that contains the matching keyword as you
navigate to different assets. For example, adding the keyword "Plant" to a display will allow the OMI app to
find the display that is applicable when the currently-selected asset is named "Plant."
If more than one dashboard display contains the same keyword, the PI Vision OMI app will use the first
display that was saved with the keyword.

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 24
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

Contextualized Ad Hoc Displays

Contextualization for ad hoc displays works by discovering the given number of data items for an asset from the
selected asset server and asset database, and plotting the items on the selected symbol type. Up to 10 context
tags are shown by default. If the asset you are viewing has more than 10 tags, the first 10 that are listed
alphabetically are shown. Showing more than 10 may impact performance.
The current asset is searched in the AF server and AF database, as specified by the Context Asset Server and
Context Asset Database properties of the app. If a context server and database are not specified, the default
server and database are used.
When the OMI app connects to the AF server and database, it retrieves the top N number of attributes, where N
is the number specified by the Max Context Data Item to Show property. The attributes are shown in the
selected symbol type.

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 25
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

If a matching asset is not found in the AF server, no data is shown and a message is provided in the System
Platform logger.
If the Data Items property is configured, those data items are shown together with the context-driven
attributes. The Data Items property can include data items from multiple databases from either the same AF
server or a different AF server.
The connection to the Context Asset Server uses the Windows credential of the currently logged-in user.
To contextualize Ad Hoc Displays
1. Enable the Follow Current Context property. When Follow Current Context is enabled, you can provide
entries for the following properties:
o Context Asset Server. This property specifies an asset server in your PI system that will be used to get
the current context. If you do not enter the server name, the PI Vision OMI app will try to connect to the
default asset server. The PI Vision OMI app will use the credentials of the currently logged-in Windows
user to connect to the asset server.
o Context Asset Database: This property names the asset database to retrieve from the specified Context
Asset Server, and is used to get the attributes from the currently-selected asset. If a database is not
specified, the PI Vision OMI app will attempt to discover the selected asset from the default database of
Context Asset Server (if specified). If the Context Asset Server is not specified, it will make the attempt
from the default asset server.
2. Set the Max Context Data Items to Show parameter to the number of data items that should be shown
from the selected asset. We recommend that you show no more than 10 to ensure good performance.
The Follow Current Context property will auto-discover the given number of attributes for the selected
asset. The attributes of the selected asset are retrieved from the PI Vision AF server and shown in the
selected type of symbol at run time. If there is no matching asset found in the AF server, no data is shown,
and a message is sent to the System Platform logger.

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 26
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

In addition to contextual data items, you can show data items for other assets, regardless of the the current
context. These additional data items do not impact the Max Context Data Items to Show property, and do not
change as the context changes.

PI Vision OMI App Scripting

The PI Vision app lets you script many of the PI Vision properties. Scripts that incorporate methods and their
parameters as well as PI Vision app properties are supported. Script statements can be specified using the
MyContent Namespace format in layout scripting by the following syntax formats:
MyContent.name of the PI Vision App instance.PIVisionApp_Method(parameter_1, parameter_2, parameter_n);
or
MyContent.name of the PIVision App instance.PIVisionApp_Property = xxx

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 27
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

Scripting Methods
The PI Vision OMI App includes the Refresh() scripting method for layout scripts.

PI Vision OMI App Properties in Layout Scripts

The following table lists PI Vision OMI App properties as they appear in the Properties page of Layout and
ViewApp editors and how they are specified in layout scripting. Notice that property names in layout scripting
are single words without blank spaces.
 Property Names: In most cases, with the exception of Max Context DataItems to Show, the scriptable
property name is identical to the property name as shown in the Properties page.
 Layout Scripts: All properties, with the exception of Symbol Type, are scriptable in layout scripts.
 Bindable Properties: All properties, with the exception of Symbol Type, can be configured in the property
grid to be bindable at run time.

PI Vision App Properties Layout Script Editor Scriptable Bindable

Web Server WebServer yes yes

Web Site WebSite yes yes
View Dashboard Display ViewDashboardDisplay yes yes
Dashboard ID DashboardID yes yes
Asset Path AssetPath yes yes
View Ad hoc Display ViewAdhocDisplay yes yes
Context Asset Server ContextAssetServer yes yes
Context Asset Database ContextAssetDatabase yes yes
Data Items DataItems yes yes
Symbol Type SymbolType NO NO
Start Time StartTime yes yes
End Time EndTime yes yes
Follow Current Context FollowCurrentContext yes yes
Max Context DataItems to Show MaxContextDataItemsCount yes yes
View Display URL ViewDisplayURL yes yes
Display URL Parameters DisplayURLParameters yes yes
Hide Toolbar HideToolbar yes yes
Hide Sidebar HideSibebar yes yes
Kiosk Mode KioskMode yes yes

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 28
 AVEVA™ PI Vision OMI App User Guide
Chapter 2 – Configure the AVEVA PI Vision OMI App

Style Sheet StyleSheet yes yes

Event Scripting
The following event is exposed for scripting:
PIVisionLoaded: This notifies the app that display has finished loading.

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 29
Chapter 3

PI Vision OMI App Property Validation

The properties listed in the PI Vision OMI App property grid are validated during design time to ensure proper
configuration.
For most of the properties, design time validation occurs only when the property value is modified in the
property grid. If the property is not modified in the property grid, validation will occur when the ViewApp is
deployed to run time. Values entered for properties are checked, and if the required minimum configuration is
not met, an visual cue indicating the error is shown in the app, and details of the error are sent to the System
Platform Logger.
The following is a summary of property validation.

Property Name Type Validation

Web Server string Cannot be empty; no spaces in name

Web Site string Cannot be empty; no spaces in name
View Dashboard Display Boolean Can only be true when ad hoc and freeform
display modes are false
Dashboard ID integer Must be > 0 when View Dashboard Display is
true.
Must = 0 when View Dashboard Display or View
Freeform Display is true.
Asset Path string Optional, not validated
View Ad hoc Display Boolean Can only be true when dashboard and freeform
display modes are false
Data Items string Optional, not validated
Context Asset Server string Optional, not validated
Context Asset Database string Optional, not validated
Follow Current Context Boolean Can only be true when either dashboard or ad
hoc display mode is true
View Display URL Boolean Can only be true when dashboard and ad hoc
display modes are false
Display URL Parameters string Can only be set when View Display URL is true

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 30
 AVEVA™ PI Vision OMI App User Guide
Chapter 3 – PI Vision OMI App Property Validation

Start Time string Optional. If Start Time is provided, End Time

must also be provided
End Time string Optional. If End Time is provided, Start Time
must also be provided

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 31
Chapter 4

Using the PI Vision OMI App During

Runtime

The applicable SSL certificate must be installed on the run time node that is running the PI Vision OMI App. See
SSL Certificate for Run-Time Nodes on page 7 for more information.
If an invalid app property value is detected when the ViewApp containing the PI Vision OMI App starts, an error
icon appears in the pane containing the app. The ViewApp continues running, but the pane containing the app
will show only the error icon.

One or more error messages appear in the System Management Console logger with descriptions of any
problems.
SSL Exceptions
If an SSL certificate is not configured, using the PI Vision OMI App for Dashboard displays in context mode will
fail and result into SSL Exception.

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 32
Chapter 5

Troubleshooting

The PI Vision OMI App utilizes the following custom log flags within the AVEVA Log Flag Editor, to facilitate
troubleshooting:
 AFSDK
 Context
 DashboardIDRetrieval
 PIVisionAPP
 PIVisionPropertySet
 URL

Of the custom flags applicable to the PI Vision OMI App, URL is the most significant, and can be used to
troubleshoot issues related to display loading. When enabled, this flag shows the URL that will be formed, based
on the configuration that was set in the app.
As the PI Vision OMI App is essentially a wrapper around the PI Vision product, this URL flag can be used to
expose and diagnose the display issue that you may be seeing in the PI Vision OMI App.
To identify if the issue is on the OMI side or PI Vision side, copy the URL, as shown in the System Platform logger
view, and paste it in your standard browser. The behavior of the PI Vision display in the browser with the given
URL parameters/values should match the behavior seen in the OMI app, if the issue is on the PI Vision side.

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 33
 AVEVA™ PI Vision OMI App User Guide
Chapter 5 – Troubleshooting

If the problem is identified on the PI Vision side, we recommend that you contact Osisoft – PI vision customer
support. Once the problem is fixed in PI Vision, the PI vision OMI App for will start working and displaying the
expected behavior.
Although many URL parameters can be changed while the application is running, PI Vision does not officially
support URL parameters as a run-time setting. This means that the parameters are intended to be used in the
URL that opens the application, but not to modify the running application. To the end user, this means that
some parameter changes will require either a browser refresh or to reload the app in a new tab.
Having said that, many parameters will work correctly at run-time. If you encounter a parameter that is not
working the way you think it should, and it is causing an issue at run time, use the custom flag URL to verify if
the same behavior is also seen in the standard browser. Based on the results, you may need to contact customer
support or upgrade your PI Vision application server.

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 34
Chapter 6

Upgrade and Migration of the PI Vision

OMI App

The PI Vision OMI App can be downloaded from AVEVA product website and then imported into AVEVA System
Platform 2020 R2 SP1. The AVEVA PI Vision OMI App Readme includes instructions for importing the app into
System Platform 2020 R2 SP1.
 The PI Vision OMI App is targeted for System Platform 2020 R2 SP1.
 The PI Vision OMI App can be migrated to subsequent versions of System Platform as they become
available.
 Users can export the PI Vision OMI App to an .aaPKG file and then import the aaPKG file into a future release
of System Platform.

© 2022 AVEVA Group plc and its subsidiaries. All rights reserved. Page 35