Subscribe

UiPath Orchestrator

The UiPath Orchestrator Guide

Migrating from classic to modern folders

This page describes how to upgrade your deployment from using classic folders to using modern folders instead, which is assisted by the Modern Migration wizard.

 

Modern folders have been introduced to improve and simplify the orchestration of automations and offer several benefits compared to classic folders.
In Classic folders vs modern folders you can read more about the differences between these types of folders.

📘

Classic folders will be deprecated in October 2022

Classic folders are no longer the standard for managing automations and have been replaced by modern folders, a better and more feature-rich alternative. For this reason, we have already removed the option of creating new classic folders and we will be deprecating classic folders starting with October 2022.

 

To assist you in transitioning to modern folders, you can use the Modern migration wizard to easily recreate your classic folder hierarchy and entities in modern folders, preserving all dependencies.

📘

Temporary availability

The wizard is only available up to feature removal, which is scheduled in April 2023.

 

Overview of the migration process


To convert your current deployment, in whole or in part, to utilize modern folders, some entities must be redeployed while others must be recreated entirely.

Here is an overview of what the migration wizard does during and after migration:

  • Recreates each classic folder as a modern folder with a name of the form Migrated <folder name>.
  • For each environment, creates a corresponding subfolder in the target modern folder. If there is only one environment, it does not create any subfolders.
  • Redeploys each process to the modern folder (or subfolder) that corresponds to its previous folder or environment.
  • Migrates assets, queues, and triggers from each classic folder to the corresponding modern folder.
  • Migrates robots and user accounts to the corresponding modern folders:
    • Maps each classic attended robot to a user account and sets up each user account with personal automation settings (previously known as attended robot settings), and access to the corresponding modern folders and machines needed to run the attended automations that it ran in classic folders.
      Grants the Allow to be Automation User role to user accounts to which a classic attended robot was mapped.
    • Maps each classic unattended robot to robot accounts (recommended), unless configured otherwise, and sets up each robot account with access to the corresponding modern folders and machines needed to run the automations that the unattended robot ran in classic folders.
      Grants the Automation User folder-level role to existing robot accounts that are mapped to classic unattended robots.
      New, automatically-generated robot accounts receive the Automation User folder-level role and the Allow to be Automation User tenant-level role.
  • Some user licenses that include attended capability may become available after the migration completes. This is because, in modern folders, each user needs only one user license for personal automations (previously attended). If the same user had multiple licenses, they retain the superior license and the inferior one is released.
    For example, if one of the user's attended robots used an Attended license and another used a Citizen Developer license, the user retains the Citizen Developer license and the Attended license is released.

🚧

Manual action required

While the wizard can greatly simplify the migration process for you, there are post-migration tasks that you need to perform so that your automations can run properly.
Make sure that you have the required knowledge and that you allocate time to perform these tasks before starting the migration.

Changes to tenant settings

After running the Modern migration wizard, some tenant-level settings automatically change. These changes are required to used modern folders.

The following changes apply after all classic folders have been successfully migrated:

  • Interactive sign-in is enforced.
    After the migration completes, users need to update their UiPath Studio or UiPath Assistant connection settings to switch from using a machine key to using interactive sign-in to be able to work in modern folders.
  • Classic folders and their entities are still usable.
    You can retain these until validation is complete, after which you can delete them.
  • Account-machine mappings are enabled at the tenant level.

 

Prerequisites


Permissions

  • To be able to successfully run the Modern migration wizard, you must be an organization administrator.

  • To be able to open the Modern migration wizard, you need the following permissions:

    • Roles: View, Create, and Edit
    • Settings: View and Edit
    • Users: View, Create, and Edit
    • Robots: View, Create, Edit, and Delete
    • Units: Create and Edit.

Volume limitation

The Modern migration wizard is not suitable for large deployments, which require dedicated migration tools and strategy.

We recommend that you do not use the migration wizard on folders that contain more than 2,000 classic robots. This can cause performance issues and can cause the migration to fail.

 

Step 1. Using the Modern migration wizard


Preparing for the migration

🚧

It is important that you do not make any configuration changes to your classic folder setup until the migration is complete.
Please limit pre-migration checks and changes to the ones laid out below.

Known issue

After you start the migration, you can no longer edit queue triggers in classic folders. In the event of any issues that would require editing a queue trigger, you will not be able to use the faulty queue trigger between the time the migration started and the time the migration successfully completes.

Including and excluding folders

Before starting the wizard, add yourself to all of the classic folders that you want to migrate.
Folders that you are not assigned to are not migrated.

Including and excluding classic robots

Before starting the wizard, check that all of the robots that you want to migrate are added to an environment.
Classic robots that are not part of any environment are presumed to not be in use and are not targeted for migration.

If a robot is not migrated, the asset robot values and process schedules for that robot are not migrated either, unless also used by another robot that is migrated.

Preventing permission elevation

Following the migration, attended users and robot accounts are automatically assigned the Automation Users role at folder level (in the corresponding folder they are assigned to at migration time). If you have customized the service-level roles or the license allocation rule for this group, we recommend that you remove any elevated roles or extra licenses from this group before proceeding with the migration.

Check that no jobs are running

It is important to make sure that prior to starting the migration no jobs are running.
If you have triggers that would start a job during migration, we recommend that you disable them and re-enable them after the migration finishes.

Before starting the migration, you can check job status from the Folder > Monitoring page of each classic folder to be migrated.

When the migration starts, all jobs that are not in a final state are terminated. If a terminated job does not reach the stopped status by the time the migration concludes, the migration fails with a related error.

 

Using the wizard

To migrate classic folders to modern folders for a tenant:

  1. Go to Tenant > Settings.
    The Settings page opens on the General tab.
  2. In the Classic Folders section, click Start migration.
    The Modern migration wizard opens on the Getting started step.
  3. Review the information and, under the Summary section, click Copy the summary above and save that information for your records.
    The summary lists the types and number of entities that are included for migration.
    Notes:
    • Only those classic folders to which you have access are targeted for migration. Folders where you are not added are not migrated.
    • Classic robots that are not added to an environment are assumed to not be in use and are not targeted for migration.
  4. When ready, click Next to proceed to the Attended users step.

Attended users

Because in modern folders we manage the relationship between users and robots differently and we create the user's robot automatically, you need to map each classic attended robot to the account of the user who uses it.

The Attended users page lists all of the attended robots that were found in the targeted classic folders and their details.
In the Target user account column, for each attended robot found, you must select the account of the user who uses the attended robot, based on the information in the other columns.

If you do not set an account for a robot, that robot is not migrated. The processes associated with that robot will no longer be able to run.

  1. For each target account that is not correct or not set, you must manually set the account:
    a. Click Assign in the Target user account column.
    b. In the Search for a user field, start typing to search, and then select the user from the results.
    c. Click Save in the bottom right to set the target account and return to the previous page.
    For information about how to map robots to user accounts, see Mapping rules for attended robots.
  2. When ready, click Next to move to the Unattended users step.

 

Mapping rules for attended robots

The following are the rules we use to validate your selection when you attempt to map classic attended robots to their users.

  • Robots with the same Username (shown on the Attended users page) must be mapped to the same target user account.
    Similarly, robots with a different Username value must be mapped to different target user accounts.

  • If you have an integration with an external user directory, when mapping robots to directory user accounts, the Username value of the robot must match the email address or user name of the target user account.
    You can view the email address and user name for a user account on the Tenant > Manage Access > Assign Roles page.

  • When mapping robots to local user accounts:

    • If interactive sign-in is enforced for the tenant, you are allowed to map any classic robot to any user.
    • If the tenant-level robot authentication setting is set to Hybrid and the target user account has personal automation enabled, the Username value for the robot must match user's Domain\Username value, as shown on the user's Personal automations setup page.
    • If the tenant-level robot authentication setting is set to Hybrid, the target user account has personal automation enabled, and the option Inherit license from user's group is set in user's Personal automations setup page, then the user has a generated personal automation username which is not shown, but is required to match the Username of the robot, otherwise mapping is not allowed.

When multiple attended robots are mapped to the same target account, the robot username in the modern folder will be one of the usernames of the migrated robots, at random. This can result in access problems when trying to connect to machines.

 

Unattended users

For unattended robots, you must map them to new or existing robot accounts. Robot accounts are designed for running unattended automations and we recommend using them instead of user accounts.

The Unattended users page lists all the unattended robots that were found in classic folders.

  1. In the top right, under Bulk Actions, select how you want the wizard to handle classic unattended robots that do not have a target robot account mapped:
    • Recommended: Select Automatically generate robot accounts if you want to migrate all of the listed unattended robots and want to allow the wizard to create new robot accounts for them. Details...
    • Not recommended: Select Ignore them if you want to only migrate some of the classic robots that were found.
  2. Review the Target robot account column to make sure that any existing mappings are correct.
    • If you selected Automatically generate robot accounts, skip this step.
    • If you selected Ignore them, you must manually map only those classic unattended robots that you want to migrate to a target robot account by clicking Assign in the Target robot account column. You can also create new robot accounts at this time, if needed.
      Any classic robots that are not mapped to a target robot account are not migrated to modern folders.
  3. When ready, click Next to proceed to the final step.
    The Finishing page opens.

 

What Automatically generate robot accounts does

With this option selected, at migration time, the wizard attempts to automatically map each classic robot as follows:
i. Looks for an existing user or robot account with a matching unattended username.
If found, it maps the unattended robot to that existing account. If no matches are found, it moves to the next step.
ii. Looks for other classic unattended robots with the same Username that were already mapped to an account.
If found, it maps this robot to the same account. If no matches are found, it creates a new robot account for the classic robot.
New robot accounts created by the wizard have a name of the form Migrated folderName_robotName.

Mapping rules for unattended robots

The following rules apply when you attempt to map classic unattended robots to robot or user accounts.
If you choose to manually map robots to robot accounts (not recommended) instead of allowing the wizard to create new robot accounts, then you must follow these rules.

i. Looks for an existing robot account that uses the same credentials as the classic unattended robot.
If a match is found, the wizard requires that you map the classic unattended robot to the existing robot account. If not, it moves to the next step.
ii. Looks for another classic unattended robot that has the same credentials as the classic robot to be mapped. If found and already mapped to a target account, the wizard requires that you map the current robot to the same target account.

If you map multiple robots with different credentials to the same robot account, after migration the robot account uses the credentials of one of the classic robots, at random. There is a risk that these credentials do not work on all of the target machines and, after migration, can result in a failure to connect to machines.

 

Starting the migration

  1. When ready, click Execute migration to start the process.
    A confirmation dialog opens.
  2. Click Execute to start the migration.
    The page refreshes to show migration progress for each folder.
    If any failures occur, check the error messages shown. After resolving the problem in each classic folder, you can restart or retry the migration.
  3. Click Close to exit the wizard.

Next steps: If migration was successful, continue with Post-migration setup.

 

Troubleshooting

Jobs are not in final state yet

When the migration starts, the wizard automatically terminates any running jobs so that it can run. If, by the time the migration finished, a terminated job remains in the Terminating status and does not reach the Stopped status, migration fails.

If this happens, after 24 hours, we automatically set Terminating jobs to Stopped status. At this point, you can restart the migration.

 

Restarting or retrying the migration

If the migration failed for some or all folders, you can try again after you resolve the misconfigurations that caused errors.

To restart or retry a migration that failed:

  1. Review the error messages for each folder and then check the classic folder setup to resolve the errors.
  2. After resolving all errors, go to Tenant > Settings > Start migration.
    The wizard opens on the final page.
  3. To re-run the migration:
    • If you want to re-run the migration with your previous settings, click the Retry icon () to the right of the row of a folder that failed migration. This option restarts the migration as it was previously set up, without giving you the option to change mappings.
      (Optional) Select the checkbox Clean-up before retrying if you want to delete any partially-migrated data for folder for which migration failed. If you do not select this checkbox, migration is performed only for those entities which could not be migrated previously.
    • If you want to redo the mappings for attended and unattended robots, click Restart in the bottom right. This option takes you back to the first step of the wizard. Follow the instructions in Using the wizard to complete the setup once more.

 

Step 2. Post-migration setup


Following migration, you must perform the following manual steps to address backward compatibility issues:

  1. Recompile existing workflows that use Orchestrator activities or are making direct HTTP calls to the Orchestrator API to use version 2019.10 or later for UiPath.System.Activities.
  2. Re-provision all other existing entities in the corresponding modern folder, including:
    • Action catalogs
    • For testing, if used: test sets, test schedules, test data queues.
      You do not need to re-provision attended and unattended robots (they are automatically provisioned for users with access to the new modern folder) and environments (they are not used in the context of a modern folder).
  3. Update the classic folder process used in UiPath Apps to use the newly-migrated modern folder process.
  4. Update any workflows that:
    • have a dependency on the old folder path
    • use the Start Job activity. In classic folders, where you had processName_envName, you now need to change to processName for modern folders.
  5. If not already enabled, enable interactive sign-in for the tenant. This is mandatory for working in modern folders.
  6. Run the unattended processes from Orchestrator using Start Job to test them in modern setup.

📘

Allow 10 minutes after the migration completes for the wizard to disable the robots from the migrated classic folders. This is required so that licenses are released and can be used in modern folders.

  1. Upgrade end-user workstations to use UiPath Robot version 2019.10 or later.
  2. (Optional) Remove the now-unused classic folders.

 

Reverting to classic folders


If you ran the migration wizard, but your automations do not run properly in modern folders, you can temporarily re-enable your classic folders setup so that you can continue to run automations until you can resolve the migration issues and successfully move to modern folders.

To temporarily revert to using classic folders after running the migration:

  1. Set robot authentication settings for the tenant back to Hybrid.
  2. Enable all classic robots.
  3. Enable triggers in classic folders.
  4. Delete the modern folders.
  5. Delete the new robot accounts.
  6. Investigate what in the classic folders setup caused automations to fail and potentially clean up your classic folders.
  7. Run the migration again.

Updated 28 days ago


Migrating from classic to modern folders


This page describes how to upgrade your deployment from using classic folders to using modern folders instead, which is assisted by the Modern Migration wizard.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.