User Guide

Application Modeller Conversion Tool

Document Revision 1.4

 User Guide | Application Modeller Conversion Tool
Revision History

Revision History
Date Revision Description

30/07/2020 1.2 First release to Digital Exchange (DX)

02/09/2020 1.3 v1.1, with Blue Prism v6.9 release support

16/04/2021 1.4 Add instructions to generate Application Manager Operations.html file

using Blue Prism set in English language

Commercial in Confidence Page 2 of 15

 User Guide | Application Modeller Conversion Tool
Trademarks and copyrights

Trademarks and copyrights

The information contained in this document is the proprietary and confidential information of Blue Prism Limited and should not be
disclosed to a third party without the written consent of an authorised Blue Prism representative. No part of this document may be
reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying without the written
permission of Blue Prism Limited.
© Blue Prism Limited, 2001 – 2021
®Blue Prism is a registered trademark of Blue Prism Limited
All trademarks are hereby acknowledged and are used to the benefit of their respective owners.
Blue Prism is not responsible for the content of external websites referenced by this document.
Blue Prism Limited, 2 Cinnamon Park, Crab Lane, Warrington, WA2 0XP, United Kingdom
Registered in England: Reg. No. 4260035. Tel: +44 870 879 3000. Web: www.blueprism.com

Commercial in Confidence Page 3 of 15

 User Guide | Application Modeller Conversion Tool
Contents

Contents
Revision History ...........................................................................................................................................................2
Trademarks and copyrights ........................................................................................................................................3
Contents .......................................................................................................................................................................4
Introduction .................................................................................................................................................................5
Installation and Setup .................................................................................................................................................6
Pre-requisites ...........................................................................................................................................................6
Application Setup ....................................................................................................................................................6
Conversion Process......................................................................................................................................................7
Step 1: Load an “Application Manager Operations.html” File ...............................................................................7
Step 2: Load a “Conversion Rules” File ...................................................................................................................9
Step 3: Load a Blue Prism Release or Object File.................................................................................................. 10
Step 4: Start Conversion ........................................................................................................................................ 10
Step 5: Import Converted BP Release or Business Object (VBO) File into Blue Prism ........................................ 11
Step 6: Review the Conversion .............................................................................................................................. 12
Application Options ................................................................................................................................................... 13
Configuration File .................................................................................................................................................. 13
Troubleshooting ........................................................................................................................................................ 15

Commercial in Confidence Page 4 of 15

 User Guide | Application Modeller Conversion Tool
Introduction

Introduction
The Blue Prism® Application Modeller Conversion Tool has been designed to allow quick conversion of
application modeller elements and attributes. The principal audience for this utility is those wishing to convert
Internet Explorer objects to Chrome, Firefox or Edge Chromium browsers, but it also has the scope to support
customized conversions between other application modes.
Although there are not one-to-one conversions possible for all Internet Explorer elements and attributes, this
conversion tool will convert most cases, providing consistency and time savings over performing the
conversion manually.
The application requires:
• An Application Manager Operations.html file specific to your version of Blue Prism. Some files are
available from the Digital Exchange but instructions on how to easily create this file yourself will be
covered in this document.
• A Conversion Rules file. A conversion file for Blue Prism v6.3 to v6.8 can be downloaded from the Digital
Exchange for conversion from Internet Explorer to any Chromium browser. This rules file makes no
changes to UIA or AA elements and attributes.
• A Blue Prism object or release file.
The application will output a new object or release file for you to import into Blue Prism and optionally, a log
files describing all changes that have been made.

Care must be taken when importing the new object or release file as the application does not
make any attempt to alter Business Object internal IDs during conversion. This means that
unless you direct Blue Prism to Assign new internal IDs then the original object will be
overwritten.

Once imported into Blue Prism, amended stages will contain breakpoints allowing you to see the full scope of
the change, aid regression testing and the output report provides a record of all changes that have been made.

Commercial in Confidence Page 5 of 15

 User Guide | Application Modeller Conversion Tool
Installation and Setup

Installation and Setup

Pre-requisites
• 64bit Windows OS, Windows 7 or above
• .NET Framework v4.7.2
• Google Chrome browser installed on a machine where Blue Prism Interactive Client is deployed. Google
Chrome is only needed to generate a version of Application Manager Operations.html file.

Application Setup
The application is distributed via a zip file called BP_AM_Converter.zip
Unpack the contents of the zip file to your chosen location.

To start the Application Modeller Conversion Tool, click BPAppModellerConversionTool.exe

.NET Plugin Project

An optional .NET plugin project written in C# can be downloaded. Once compiled, the resultant DLL
BPAMConversionToolPlugin.dll can be used to replace the file of the same name included in the tool. This plugin
allows customised functions to be used in the conversion rules file.
Please follow the instructions as detailed in the plugin source code to determine the appropriate changes you
may make there. Note that certain functions, for example, SetPath, are integral to the success of the conversion
therefore should never be modified.

Commercial in Confidence Page 6 of 15

 User Guide | Application Modeller Conversion Tool
Conversion Process

Conversion Process
Step 1: Load an “Application Manager Operations.html” File
The Application Manager Operations file contains a comprehensive list of all the actions, their attributes and
element types that they work with for a specific version of Blue Prism. This file is required so that the
conversion tool can convert for a specific version of Blue Prism.

It is important that an English version of the file is generated and subsequently feed into the
conversion tool. This means Blue Prism must be launched using English language prior.

If you do not already have an Application Manager Operations file for your version of Blue Prism please go to
the end of this section to see how you can create your own file.
• Start Blue Prism Application Modeller Conversion Tool by double-clicking the executable
“BPAppModellerConversionTool.exe”.
• Click Browse… button as highlighted below

• Navigate to the “Application Manager Operations.html” file saved previously. Please note that the
application only takes in a file with name Application Manager Operations.html.
• You should now see the full path to the file reflected to the left of the Browse.. button.
• Optionally, you may click View Elements button to view the structure loaded from the file. If this button
is not enabled then the file has not been imported correctly and is likely to be of an incorrect format.

How to Generate an “Application Manager Operations.html” File from Blue Prism

Please follow the steps below to generate your own “Application Manager Operations.html” file.

Commercial in Confidence Page 7 of 15

 User Guide | Application Modeller Conversion Tool
Conversion Process

• Start your Blue Prism Interactive Client.

• Click Studio to arrive at the Studio screen with all accessible processes and objects presented in tree-
like structures.
• If you do not have any existing object under the Objects tree, please create a new object now and give it
a name.
• Open any existing object. Note that any changes made to the object will be discarded in the end.
• Add a Navigate stage onto any page and double click to open it. The following screen is shown:

• Click the blue round-shaped icon as highlighted above.

• This will open your default browser loaded with a file titled “Application Manager Operations”.
• If your browser opened is not Google Chrome, please start your Google Chrome while keeping the other
browser open on the desktop.
• Copy the URL from your default browser to Google Chrome address bar and hit “Enter” key to load the
page in Google Chrome. The URL should look similar like below:
file:///C:/Users/{USER_NAME}/AppData/Roaming/Blue%20Prism%20Limited/Automate%20V3/Temp/A
MI%20Documentation%20Version%206.6.0.15260-9.html
• Close your default browser but leave Google Chrome open.
• From Google Chrome, press Ctrl + S to bring up Save As… screen.
• Navigate to the folder you wish to save the file to.
• Make sure the “File name” is exactly as “Application Manager Operations.html”.

Commercial in Confidence Page 8 of 15

 User Guide | Application Modeller Conversion Tool
Conversion Process

• In the “Save as type…” dropdown, select “Web Page, HTML Only (*.html;*.htm)” option.
• Double check if you have “File name” and “Save as type” the same as shown below:

•
• Click Save button. This should result in a single HTML file saved to the destination, no associated
folders.
• You may now close the object by discarding any changes made. If a new object is created to generate
the file, you may delete the object as well.
• This should leave you with an HTML file that can be consumed by the application.

Step 2: Load a “Conversion Rules” File

• Click Browse… button as highlighted below. Please note that a Conversion Rules file cannot be loaded if
an Application Manager Operations.html file has not already been loaded by the application.

• Navigate to a Conversion Rules XML file. It is possible to modify any Conversion Rules file to tweak the
existing rules or create a new set of mapping between two application modes. Conversion rules files for
converting Internet Explorer objects to Chrome or to Edge can be downloaded from the Blue Prism
Digitial Exchange.
• You should now see the full path to the file reflected to the left of the Browse.. button.
• Following information will be populated in the user interface
o Internal name of the Conversion Rules File
o Associated BP version
o Object Name Suffix to Add

Commercial in Confidence Page 9 of 15

 User Guide | Application Modeller Conversion Tool
Conversion Process

o Three panes will be populated on the application, from left to right:

▪ AppTypeInfo Conversion Rules from the loaded Conversion Rules file. This lists the
conversion rules for the main application details in Application Modeller e.g. path to
your browser, Window title, command line parameters,
▪ Attribute Conversion Rules from the loaded Conversion Rules file. This lists all the
changes that will be made during the conversion. New attributes are colored blue,
changes colored black and deletions colored red.
▪ Element Conversion Rules from the loaded Conversion Rules file. This list all the changes
to the elements in Application Modeller.

Step 3: Load a Blue Prism Release or Object File

• Click Browse… button as highlighted below. You may select either a Blue Prism Release file
(*.bprelease) or a Business Object (*.bpobject or *.xml) file to load into the application.

• You should now see the full path to the file reflected to the left of the Browse.. button.
• Converted File Path is automatically populated with a converted file name, with a timestamp appended
at the end of the file name but before the file extension. The file name can be altered if necessary. Once
conversion is completed, the converted file will be saved into the file path as described there. Any
existing file with the same name will be overwritten.

Step 4: Start Conversion

• Conversion is possible once a valid copy of all following three files are loaded into the application:
o Application Manager Operations.html
o Conversion Rules XML file
o Blue Prism Release (*.bprelease) or Business Object File (*.xml)

Commercial in Confidence Page 10 of 15

 User Guide | Application Modeller Conversion Tool
Conversion Process

• Click the Convert button as highlighted below:

• A message should appear in the status bar at the bottom of the UI indicating the status of the
conversion. The file will be saved into the Converted File Path textbox.
• To the right of the Convert button, a Download Report button will be activated when conversion is
completed. It allows a conversion report in CSV format to be saved using the same file name and same
destination folder as the converted release/object file.

Step 5: Import Converted BP Release or Business Object (VBO) File into Blue Prism
The application does not make any attempt to alter Business Object (VBO) internal IDs during conversion. This
means upon reimporting the converted file to Blue Prism, existing objects are subject to be overwritten, even if
they do not share the same object name.
If overwriting existing objects is not intended behaviour, please select Assign a new internal ID to the incoming
business object option during importing process against every affected object, so that a new ID can be assigned
to those objects, allowing objects before and after conversions to co-exist in the same Blue Prism environment.

Commercial in Confidence Page 11 of 15

 User Guide | Application Modeller Conversion Tool
Conversion Process

Step 6: Review the Conversion

Provided you have left the Set Breakpoint on Stage Conversion option checked, when you open your object you
will see that all affected stages contain breakpoints. This will allow you to clearly see the impact of the changes
and provide a useful aid in regression testing.
The Operation field in the Conversion Report will indicate where elements or attributes have been deleted,
updated or added.

There is not always a one-to-one mapping of elements, attributes and associated actions and consequently you
will need to provide manual fixes where these occur. For example, in Internet Explorer there is an action to
Navigate to URL. This does not exist in Chrome. Hence, you will need to provide a workaround.
Filtering on the Severity field to display Critical items will direct you to the areas of your object that require
immediate attention.

Commercial in Confidence Page 12 of 15

 User Guide | Application Modeller Conversion Tool
Application Options

Application Options
Two options are currently available to the application via the Options tab.

• Set Breakpoint on Stage Conversion This option adds a breakpoint to the relevant Blue Prism stage if a
condition or action has been converted as part of the process. This forces user to review the stage in
Studio post conversion.
• Perform Object Name Manipulation This option activates manipulation logic for object names, it can
either invoke a customised function, or append suffix to object names post conversion completion.
Relevant configurations are defined in the Conversion Rules file.

Configuration File
The following application keys are available in BPAppModellerConversionTool.exe.config file that ships with the
application. They can be used to tailor the behaviour of the application, resulting in a smoother user
experience. However, care should be taken in altering some of the keys as they may result in the application
failing to work.

Key Name Default Description

ApplicationManagerOperationsHTM Empty Full file path to "Application Manager

LFilePath Operations.html", to allow preloading of the file.

ConversionRulesFilePath Empty Full file path to "Conversion Rules", to allow

preloading of the file.

SortElementsByName False If a list of elements loaded from "Application

Manager Operations.html" file is sorted by element
name.

SetBreakPointOnStageConversion True The default value to "Set Breakpoint on Stage

Conversion" UI option.

PerformObjectNameManipulation True The default value to "Perform Object Name

Manipulation” UI option.

LoadSourceBPFileUsingEncoding utf-8 The encoding used to load the source BP release file
or business object VBO. For a complete list of
possible values, please refer to
https://docs.microsoft.com/en-
us/dotnet/api/system.text.encoding?view=netframe
work-4.7.2

XPathFromReleaseToObject .//bpr:release/ [DO NOT CHANGE OR DELETE UNLESS INSTRUCTED]

bpr:contents/ XPath expression from BP Release to containing BP
object:object/ Object.
object:proces
s

Commercial in Confidence Page 13 of 15

 User Guide | Application Modeller Conversion Tool
Application Options

XPathProcessNamespacePrefix process: [DO NOT CHANGE OR DELETE UNLESS INSTRUCTED]

XPath Process Namespace Prefix.
Used in BP Release conversion.

BPReleaseNameSpace_bpr Empty [DO NOT CHANGE OR DELETE UNLESS INSTRUCTED]

XPath Namespace mapping for bpr prefix.
Used in BP Release conversion.

BPReleaseNameSpace_object Empty [DO NOT CHANGE OR DELETE UNLESS INSTRUCTED]

XPath Namespace mapping for object prefix.
Used in BP Release conversion.

BPReleaseNameSpace_process Empty [DO NOT CHANGE OR DELETE UNLESS INSTRUCTED]

XPath Namespace mapping for process prefix.
Used in BP Release conversion.

Commercial in Confidence Page 14 of 15

 User Guide | Application Modeller Conversion Tool
Troubleshooting

Troubleshooting
Error in loading “Application Manager Operations.html”
Possible Solution: have you generated the “Application Manager Operations.html” using “Web Page, HTML
Only (*.html;*.htm)” option instead of “Web Page, Complete (*.html;*.htm) which is the default option offered
by Chrome.”

Error in loading “Blue Prism Release or Business Object (VBO) File”.

Possible Solution: UTF-8 is used to read the BP file from file system. If you believe your file requires a different
encoding, please adjust the value associated with the application key “LoadSourceBPFileUsingEncoding”
accordingly to see if it helps. Details of the application key can be found in the “Appendix” section.

You are not certain about the nature of the error encountered, or that the error message itself is
ambiguous.
Possible Solution: please use “Show Detailed Error” menu option to reveal detailed error message associated.
It may provide insights into the real reason behind the error. At a minimum, detailed error message offers
sufficient details for developer of the application to understand the error you have encountered.

Commercial in Confidence Page 15 of 15