Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Migrating solutions from 19.1 to 21.1

Updated on November 15, 2021

Use the Preview Migration utility to migrate your 19.1 solutions into 21.1 projects that you can open and modify in the Robot Studio v21 Preview. Migrating your solutions allows you to test the preview using actual projects.

Note: The Preview Migration utility only migrates 19.1 solutions. If you have solutions created in 8.0 SP1 or earlier, you must migrate those solutions to 19.1 before you can use this utility. For more information, see the Migrating from version 8.0 SP1 to 19.1 topic in the Pega Robotic Automation 19.1 Release Notes.

Because version 21.1 no longer requires Microsoft Visual Studio, naming conventions and folder structures for your automation files have been redesigned to better reflect the needs of automation developers. The Preview Migration utility makes a copy of your 19.1 solution, renames the affected files, and then moves all of the solution files into the new 21.1 folder structure.

After you run the Preview Migration utility, inspect the result and report your experience using the Collaboration Center. By reporting your results, the version 21.1 team can continue to improve the migration process so that the migration features in the initial release of Robot Studio 21.1 require as little effort on your part as possible. You may need to repeat the migration of some of your solutions after initial release.

When you run the Preview Migration utility, the utility performs the following tasks.

  • Creates a root folder for the 21.1 version of each project, and then copies all the contents of the 19.1 project into subfolders of that root folder. The Preview Migration utility places global items in a similar folder structure within Globals.
  • Renames files as needed.
  • Adds dependencies to automations to ensure that dependent automations appear in the Palette.
  • Migrates 19.1 variables to version 21.1 variables. Version 19.1 enhanced many variables. The Preview Migration utility ensures that all variables in the project are updated, so you have access to the additional functionality.
  • Combines all global items into a single global container, and includes any global items that were placed directly into the global tray of automations. The utility creates a detailed folder structure to ensure that you can identify where the items were originally stored.
  • Migrates entry-point and exit-point parameters to the new 21.1 format.
  • Migrates methods that reference the Runtime core, for example the AllProjectsStarted and TerminateRuntime methods.
  • Migrates stringUtils, dateTimeUtils, timeSpanUtils, fileUtils, asoManager, startMyDay, DocumentOCR, and messageManifest components to the new 21.1 methods. These legacy components have been deprecated. In version 21.1, the new Toolbox provides you with direct access to these legacy component properties, methods, and events.
  • Migrates configuration information to the new 21.1 environment overrides. Environment overrides provide the same functionality as the 19.1 Configuration project items option, but in an easier-to-use format.
  • Migrates the Message Manifest messages to the new 21.1 format.

The Preview Migration utility does not yet convert the following items:

  • Interaction Framework
  • Citrix settings

Translator support for the following software is not yet available:

  • ComponentOneOCX
  • Delphi
  • LegaSuite
  • OracleForm6
  • PowerBuilder
  • QuickBooks

The following diagram illustrates the process:

Migrating 19.1 robotic automation solutions into version 21.1
Migrating automations from 19.1 to 21.1

When you install the Robot Studio 21.1 Preview, the instllation wizard installs the Preview Migration utility in your installation folder. The following is an example of where the utility is located.

C:\Program Files (x86)\Pegasystems\Pega Robot Studio\Pega.Upgrade.exe

Running the Preview Migration utility

Migrating your 19.1 soluttions enables you to use the new features in the Robot Studio 21.1 Preview when working with existing automations.

The migration process applies the new file-naming conventions and folder structures for your automation files. Complete the following tasks to prepare your 19.1 solutions before you start the migration:
  • Compile your 19.1 solution to make sure it compiles correctly.
  • Inspect your 19.1 solution and make any necessary changes.
  • Back up your 19.1 solutions.
After you complete the pre-migration tasks, run the Preview Migration utility to migrate 19.1 solutions to version 21.1. The Preview Migration utility copies the solution files to the new folder structure and changes file extensions to match the 21.1 file-naming conventions.
  1. On the Windows desktop, open a command window.
  2. Go to the Robot Studio 21.1 Preview installation folder.
    The following is an example of where this folder is located during a default installation: C:\Program Files (x86)\Pegasystems\Pega Robot Studio\.
  3. On the command line, enter the command to run the Preview Migration utility.
    1. Type Pega.Upgrade.exe.
    2. Add a space and the -s parameter, followed by the path to the 19.1 solutions. Include the path in quotation marks. The following is an example: -s "C:\Users\Administrator\Documents\Visual Studio 2015\Projects\BaseProject_191_09\BasePro]ect\BasePro]ect.sln”
    3. Add a space and the -p parameter, followed by the path for the 21.1 solutions. Include the path in quotation marks. The following is an example: -p “C:\RPA Projects\BaseProject_211_01\”
    4. Add the -a parameter to indicate that you want to perform all conversion tasks. The following is an example of the entire command that you would enter: C:\Program Files (x86)\Pegasystems\Pega Robot Studio>Pega.Upgrade.exe -s "C:\Users\Administrator\Documents\Visual Studio 2015\Projects\BaseProject_191_09\BasePro]ect\BasePro]ect.sln” -p “C:\RPA Projects\BaseProject_211_01\” -a
  4. Press Enter to start the Preview Migration utility.
    After the Preview Migration utility completes the conversion tasks, it displays the PegaUpgrade.log file. Use this log file as a guide to note any issues. See Inspecting the PegaUpgrade.log file for more information.

Reviewing the migration results

Review the comments in the Message column in the PegaUpgrade.log file to see the changes made by the Preview Migration utility.

The following figure is an example log file:

Example PegaUpgrade.log file
Review the results of the migration.

  1. Scroll to the end of the PegaUpgrade.log file.
  2. In the Message column, look for the following comments:
    STEP 20: Completed successfully!
    Upgrade completed successfully
    If the migration did not complete successfully, search for STEP to quickly scan the messages and locate the step that failed.
  3. Start the Robot Studio 21.1 Preview, and then open the newly migrated solution.
  4. Open the scripts in your solution, and then click Validate to have Robot Studio test the scripts.
  5. Open each automation, application, and Windows form.
  6. Open the environment override and message designers.
  7. Report the results of the migration on the Collaboration Center.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us