PI ProcessBook to PI Vision Migration Utility

User Guide
OSIsoft, LLC
1600 Alvarado Street
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web: http://www.osisoft.com

PI ProcessBook to PI Vision Migration Utility User Guide

© 2019 by OSIsoft, LLC. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or
by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission
of OSIsoft, LLC.
OSIsoft, the OSIsoft logo and logotype, Managed PI, OSIsoft Advanced Services, OSIsoft Cloud Services,
OSIsoft Connected Services, PI ACE, PI Advanced Computing Engine, PI AF SDK, PI API,
PI Asset Framework, PI Audit Viewer, PI Builder, PI Cloud Connect, PI Connectors, PI Data Archive,
PI DataLink, PI DataLink Server, PI Developers Club, PI Integrator for Business Analytics, PI Interfaces,
PI JDBC Driver, PI Manual Logger, PI Notifications, PI ODBC Driver, PI OLEDB Enterprise,
PI OLEDB Provider, PI OPC DA Server, PI OPC HDA Server, PI ProcessBook, PI SDK, PI Server, PI Square,
PI System, PI System Access, PI Vision, PI Visualization Suite, PI Web API, PI WebParts, PI Web Services,
RLINK, and RtReports are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein
are the property of their respective owners.
U.S. GOVERNMENT RIGHTS
Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC
license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12-212, FAR
52.227-19, or their successors, as applicable. OSIsoft, LLC.
Version: 1.0
Published: 15 October 2019
Contents

What is the PI ProcessBook to PI Vision Migration Utility.............................................. 1

Installation information................................................................................................................................... 1
Software requirements................................................................................................................................ 1

Migration analysis...................................................................................................... 3
Add files and run analysis.................................................................................................................................3
Remove a display from the Files and Folders pane....................................................................................... 3

Analysis results.......................................................................................................... 5
Analysis summary view................................................................................................................................... 5
Migration limitations.......................................................................................................................................6

View reports............................................................................................................ 11
Export VBA.................................................................................................................................................... 11

Migration settings.................................................................................................... 13
Select folders and files for migration..............................................................................................................13
Complete the migration settings window...................................................................................................... 13

Technical support and other resources....................................................................... 15

PI ProcessBook to PI Vision Migration Utility User Guide iii

Contents

iv PI ProcessBook to PI Vision Migration Utility User Guide

What is the PI ProcessBook to PI Vision Migration
Utility
PI ProcessBook to PI Vision Migration Utility allows you to analyze and migrate your PI
ProcessBook displays to PI Vision. Results are viewable in the utility itself and in generated
reports.
PI ProcessBook to PI Vision Migration Utility analyzes your selected PI ProcessBook .PDI
and .PIW files and provides information about which displays or portions of displays will or
will not migrate into PI Vision. Differences in the feature sets between PI ProcessBook and
PI Vision might affect the migration of some symbols, data types, and other drawing features.
The generated, migrated PI Vision displays match their source PI ProcessBook displays as
closely as possible in terms of size, position, and color of symbols and data items.
Migrated displays are editable and immediately usable in the most up-to-date OSIsoft
visualization infrastructure.

Installation information
PI ProcessBook to PI Vision Migration Utility, Version 1.0, is the first release of this product. It
can be installed on many Windows operating systems, including those running various
versions of PI ProcessBook and PI Vision 2019. See Software requirements.

Software requirements
You can install PI ProcessBook to PI Vision Migration Utility on any machine using the
following operating systems:
• Windows 8.1
• Windows Server 2008 R2
• Windows 10
• Windows Server 2012 R2
• Windows Server 2016
• Windows Server 2019
The PI ProcessBook to PI Vision Migration Utility can be used to migrate PI ProcessBook
displays from versions 3.0.15.7 or later to PI Vision 2019.

PI ProcessBook to PI Vision Migration Utility User Guide 1

What is the PI ProcessBook to PI Vision Migration Utility

2 PI ProcessBook to PI Vision Migration Utility User Guide

Migration analysis
Use the left pane of the PI ProcessBook to PI Vision Migration Utility to analyze the PI
ProcessBook displays you want to migrate to PI Vision. Results are viewable in the utility itself
and in generated reports. For more information, see View reports. Select folders and files from
your PI ProcessBook directories for migration analysis.

Add files and run analysis

Add and then select display folders and files for migration analysis.

Procedure
1. Click Add Files to open the Files and Folders selection list.
2. Click Folders or Files to browse your directory structure for folders or files for migration. To
select multiple files in a folder, press CTRL or SHIFT while clicking additional files. Your
selections display in the analysis pane on the right.
3. Select the check boxes next to folders and files, or Select all in the status bar at the bottom
of the analysis pane to populate all check boxes and include all of the files in the migration
analysis. The number of files listed and selected is displayed in the status bar.
4. (Optional) Select any file and then click Remove From List to remove it from the analysis
list. Selected files are removed from the list. (See Remove a display from the Files and
Folders pane.)
5. Click Run Analysis. Analysis results display in the Analysis Results pane. (See Analysis
results.)

Remove a display from the Files and Folders pane

If you have added a folder or file to the listed files and folders in error, you can remove it.

Procedure
1. Select the check box next to the folders and files you want to remove from the list in the Files
and Folders pane.
2. Click Remove from list. The selected folders and files are removed from the Files and Folders
pane.

PI ProcessBook to PI Vision Migration Utility User Guide 3

Migration analysis

4 PI ProcessBook to PI Vision Migration Utility User Guide

Analysis results
After the migration analysis, PI ProcessBook to PI Vision Migration Utility provides information
about which displays or portions of a display will or will not migrate into PI Vision. The
migration analysis is summarized in the right-hand results pane. See Analysis summary view.

Analysis summary view

The migration analysis appears in the right-hand Analysis Results pane. There are two results
views:
• Summary
• Tree View

Summary
(Default) The Summary view has a Path and Filename column for each file analyzed and an
Issue Tags column which contains icons to represent warnings about any symbols or display
components that will not appear in PI Vision exactly as it appeared in PI ProcessBook. Folders
and files are divided into categories that describe the extent to which files can be migrated. The
categories are:

• Can be fully migrated

All of the contents of the displays listed in this category can be migrated to PI Vision in full.
Note that in some cases the formatting options in PI Vision are different from those in PI
ProcessBook, and so migrated displays may appear slightly different in PI Vision.

• Can be partially migrated

Displays in this category contain one or more components that cannot be migrated to
PI Vision. See Migration limitations for specific information about general functionality and
symbol limitations.

• Cannot be migrated

Displays in this category cannot be migrated because they cannot be analyzed by the PI
ProcessBook to PI Vision Migration Utility. This may occur if a file was last saved in an older
version of PI ProcessBook that is not compatible with the Migration Utility.

Tree View
The Tree View has filterable columns that contain all of the files that were analyzed for
migration along with the following information:

• Path and Filename

Filter allows search for a file based on characters in the file name.

PI ProcessBook to PI Vision Migration Utility User Guide 5

Analysis results

• Status
Filter allows you to search by status:
◦ Can be fully migrated

◦ Can be partially migrated

◦ Cannot be migrated

• Issues
Filter allows you to exclude displays with specific issues.

• Progress
Indicates if the file has already been migrated.
Once you review the list of displays in each category, you can filter the lists in each category
and make informed decisions on which files to select and migrate. For more information on
functional and symbol limitations, see Migration limitations.

Migration limitations
When migrating from PI ProcessBook to PI Vision2019, some functionality and some symbols
may appear differently or may not appear in the display, altogether.
The following table lists general functionality in PI ProcessBook that is not supported or differs
in PI Vision:
Functional limitations
Function Migration Issue Flag Migration Limitation Description
impact
Datasets PI Vision does not currently support datasets or any form
of client-side calculations so datasets will not be migrated.
Element The migration tool must be able to connect to the AF
relative server. If no connection is made, the ERD context may
display migrate incorrectly.
(ERD)
Font Migrated PI ProcessBook content use the standard
PI Vision font, Arial.

Font style Font style (for example, bold, italic, underline) is not
configurable in PI Vision and display as unformatted Arial
font.
Layers PI Vision does not use the concept of layers within
displays, so layers will not be preserved after migration
from PI ProcessBook.

6 PI ProcessBook to PI Vision Migration Utility User Guide

 Analysis results

Function Migration Issue Flag Migration Limitation Description

impact
Multi-state Multi-state limits are migrated correctly if there is a
connection to the PI Data Archive or PI AF Server. If a
connection cannot be made at the time of migration, an
attempt to migrate the multi-state limits is made but the
limit values may migrate incorrectly.
Number PI Vision supports various number formatting options but
formatting does not support %, absolute value, and certain custom
number formats. In these cases, the number format in
PI Vision uses the same number of decimal places as those
specified in PI ProcessBook.
Symbol Symbol visibility, that is, hide or show, cannot be
visibility controlled in PI Vision. Any symbols set to be not visible in
PI ProcessBook are nonetheless displayed in PI Vision.
Time range PI Vision supports a single time range for a display (except
for XY plots). The time ranges for migrated displays is
determined by the time range of the first trend added to
the display. Where the time range cannot be determined, a
default time range of *-8h to * is used.
PI Vision does not support multiple time ranges for a
display.
Unit of PI Vision does not support converting the UOM for AF
Measure attributes. Symbols that are configured for UOM
(UOM) conversion are displayed using the units specified on the
conversion AF attribute.
Symbol size The minimum height of a symbol in PI Vision is 10 pixels.
Smaller PI ProcessBook symbols migrated to PI Vision
may be slightly larger in size and may result in some
misalignment.
VBA VBA code is not supported in PI Vision displays.
ProcessBook displays that contain VBA code are migrated
without the VBA code stored in them.

Symbol limitations are listed in the following table:

Symbol limitations
Symbol Migration Issue Flag Migration Limitation Description
Impact
Arc PI Vision only supports arcs with a base angle of 90
degrees. Any arc with a base angle other than 90 degrees
is migrated with a 90 degree base angle.

PI ProcessBook to PI Vision Migration Utility User Guide 7

Analysis results

Symbol Migration Issue Flag Migration Limitation Description

Impact
Bar There are a few bar symbol options in PI ProcessBook that
are not supported in PI Vision:
• The line style of the outside of the bar symbol cannot
be configured and is migrated as a solid line in
PI Vision.
• Scale values cannot be shown inside the bar symbol.
Migrated symbols configured this way in PI
ProcessBook show scale values on the outside of the
bar.
• Upper and lower scale limits cannot be set to different
scaling options in PI Vision. Migrated symbols
configured this way in PI ProcessBook are set to use
custom scale values in PI Vision.
• Bar scale start value and bar symbols must be
configured to hide the scale when migrated to
PI Vision.
BatchView This symbol cannot be migrated because there is no
BatchView symbol in PI Vision.
Button Since there is no button symbol in PI Vision, buttons will
be converted to text symbols and configured with a
navigation link, as long as it is not linked to a third-party
application. Displays that contain buttons that link to
other displays must be migrated at the same time as the
target display(s).
Buttons that link to an application or action not supported
in PI Vision will not be migrated with an action.
Buttons that link to an associated display that cannot be
resolved during the migration will not be migrated with an
action. Displays that contain buttons that link to other
displays must be migrated at the same time as the target
display(s).
Control Control (ActiveX) is not supported in modern browsers
and, therefore, cannot be migrated to PI Vision.
OLE Object OLE Objects are not supported in PI Vision.

SQC Chart This symbol cannot be migrated because there is no SQC

Chart equivalent in PI Vision.
Symbol Symbol library symbols are migrated provided the
Library corresponding symbol exists in PI Vision. PI Vision uses an
updated version of the symbol library which does not
contain all the same symbols that existed in PI
ProcessBook. Some of the symbols that do exist in both
versions have slightly different appearances and default
colors so that may be shown differently in PI Vision.

8 PI ProcessBook to PI Vision Migration Utility User Guide

 Analysis results

Symbol Migration Issue Flag Migration Limitation Description

Impact
Trend There are a few options on the trend symbol in PI
ProcessBook that are not supported in PI Vision:
• Legend options – legend configuration options to hide
server name, tag name, value, units, and hide entire
legend are not available in PI Vision.
• Logarithmic scales

• Data markers
• Description
• Plot title
• Regression line

• Scales:
◦ In PI ProcessBook, the Max and Min scale limits can
be set to different scaling options. This is not
supported in PI Vision. Migrated symbols configured
in this way are set to use custom scale values in
PI Vision.
◦ Value scale inside axis.
• Scroll direction (vertical trends).
• Timestamp format:
◦ The transparent trace color option is not available in
PI Vision.
◦ Plot element text color.
◦ Plot element axis settings (Time Axis, Value Axis,
Time Major/Minor Grid, Value Major/Minor Grid) .
• Vertical gridlines
The following options are not supported in PI Vision and
the data will be presented differently on the trend after
migration:
• Logarithmic scales
• Regression line
Value Value symbols in PI ProcessBook can be configured to
have the timestamp and data item name on the left, right,
top, or bottom of the data item value. PI Vision does not
support these same options for the location of this
information.
When migrated to PI Vision, value symbols that are
configured to show the timestamp or data item name will
have the timestamp below the value and the data item
name above the value. Because of this, the relative location
of value symbols may be different in PI Vision compared to
PI ProcessBook.

PI ProcessBook to PI Vision Migration Utility User Guide 9

Analysis results

Symbol Migration Issue Flag Migration Limitation Description

Impact
XYPlot There are a few options on the XYPlot symbol in PI
ProcessBook that are not supported in PI Vision:
• Scales:
◦ In PI ProcessBook, the Max and Min scale limits can
be set to different scaling options. This is not
supported in PI Vision. Migrated symbols configured
in this way are set to use custom scale values in
PI Vision.
◦ Value scale inside axis
• Timestamp format:
◦ PI Vision does not support partial or relative
timestamps.

10 PI ProcessBook to PI Vision Migration Utility User Guide

View reports
View Reports lets you select a report for your analysis or migration processes or view your
reports folder. You can also view a report about the use of VBA code:

• Analysis
Generated when a Run Analysis operation is performed. This report takes the form of .csv
file and is viewable in Notepad or Microsoft Excel.

• Migration
Generated with a Migrate Displays operation is performed. This report is in HTML format.

• VBA Code
Generated when the Export VBA operation is performed. You can find this file using the
Open Reports Folder selection. This report takes the form of a .vba file and is viewable
in Notepad (see Export VBA).

Export VBA
When migrating a display that contains VBA code modules, the migration utility flags that
display as Can be Partially Migrated and shows a VBA issue tag, . You can investigate the
impact of migrating that display without the VBA code, by exporting the code to a .vba file and
making a determination after your review.
Note:
There can be multiple VBA modules in a single display. Export VBA exports VBA for all
displays in the analysis results.

Procedure
1. Select a display that has been identified as Can be Partially Migrated and has an issue tag
indicating that the display contains VBA code ( ).

2. Click Export VBA at the bottom of the Analysis Results pane. The Export completed message
is displayed.
3. Click View Reports and select Open Reports Folder to view the associated .vba file.
4. Click OK.

PI ProcessBook to PI Vision Migration Utility User Guide 11

View reports

12 PI ProcessBook to PI Vision Migration Utility User Guide

Migration settings
Once you have run an analysis of your selected folders and files and have viewed the results of
what can and cannot be fully migrated, select the folders and files to migrate (see Select folders
and files for migration).

Select folders and files for migration

The results of the migration analysis appears in the Analysis Results pane. Displays that can be
fully or partially migrated can be selected for migration.
Note:
Those folders or files that cannot be migrated cannot be selected and will not be included
in the Select all option.

Procedure
1. From the Summary or Tree view, select folders and files from those listed as Can be Fully
Migrated or Can be Partially Migrated or Select all.
2. Click Migrate. The Migration Setting window is displayed.
3. Complete the Migration Setting window. See Complete the migration settings window.

Complete the migration settings window

After you click Migrate, specify the URI for connecting to the web services.
Note:
If you need assistance completing these fields, contact your system administrator.

Procedure
1. Enter the URI for your PI Vision server in the Connect to the PI Vision Server field and click
Connect.
Note:
Enter the PI Vision Server URL as follows:
https://webServer/PIVision
where webServer is the name of the PI Vision web server.

If connected successfully, a green check is displayed .

2. Click Choose, then select the PI Vision folder in the Destination Folder Setting window to
which your PI ProcessBook displays will be migrated.

PI ProcessBook to PI Vision Migration Utility User Guide 13

Migration settings

Note:
To preserve links between PI ProcessBook displays when migrating them to PI Vision,
they must be migrated in the same migration operation. If PI ProcessBook displays
that are linked together are not migrated together, display links may no longer work.
In this case, during migration analysis a warning will appear in the Issues column
indicating that linked displays are not part of the same analysis operation.
3. Click Choose, then select the display owner from the Display Owner Setting window.
Note:
The default display owner is the user running the utility. Other owners that appear on
this list have previously created a display or have been granted access to PI Vision.
4. Click Choose, then, from the Display Identities Setting window, select target identities with
whom to share the displays. The default is World.
5. Select the Persist folder structure from migrated items check box to preserve the PI
ProcessBook file structure when you migrate to PI Vision.
◦ If this option is selected, displays that are selected in the Analysis Results Details pane
are placed in their parent folder, as depicted in the Analysis Results folder. This entire
structure is placed under the existing folder that is selected for the migration destination
folder path. If the folder name does not exist, folders are created as necessary.
◦ If this check box is not selected, all displays that are migrated are placed under the
destination folder in a flat list.
6. Select an action to take if a duplicate file name exists:
◦ Skip File: File will not be migrated. (Default)
◦ Overwrite Destination file: The file will be migrated and the version in the destination
folder will be overwritten.
7. Click OK. The selected files are migrated to the PI Vision web server.

14 PI ProcessBook to PI Vision Migration Utility User Guide

Technical support and other resources
For technical assistance, contact OSIsoft Technical Support at +1 510-297-5828 or through the
OSIsoft Customer Portal Contact Us page (https://customers.osisoft.com/s/contactus). The
Contact Us page offers additional contact options for customers outside of the United States.
When you contact OSIsoft Technical Support, be prepared to provide this information:
• Product name, version, and build numbers
• Details about your computer platform (CPU type, operating system, and version number)
• Time that the difficulty started
• Log files at that time
• Details of any environment changes prior to the start of the issue
• Summary of the issue, including any relevant log files during the time the issue occurred
To ask questions of others who use OSIsoft software, join the OSIsoft user community,
PI Square (https://pisquare.osisoft.com). Members of the community can request advice and
share ideas about the PI System. The PI Developers Club space within PI Square offers
resources to help you with the programming and integration of OSIsoft products.

PI ProcessBook to PI Vision Migration Utility User Guide 15

Technical support and other resources

16 PI ProcessBook to PI Vision Migration Utility User Guide