Migrating From Classic to Modern Folders

Modern folders have been introduced to improve and simplify the orchestration of automations and offer several benefits compared to classic folders.

Note: 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.

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 each Test Suite entity to the modern subfolder that corresponds to the classic folder environment it previously belonged to.

• 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. Two scenarios can occur in terms of roles:

    • If the user account to which a classic attended robot is mapped was not assigned to the tenant at the moment the migration started, it is automatically included in the tenant and granted the Allow to be Automation User tenant-level role.
    • If the user account to which a classic attended robot is mapped was already assigned to the tenant, its roles do not change, so you need to manually grant it the Allow to be Automation User tenant-level role. This prevents automations from breaking.

  • 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.

  Important:

  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
  • Folders: 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

Important:

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.

Important: 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.

Important: 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.

   Note:

   • 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.

Using the Wizard for 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.

Important:

• 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.
• If the username of an attended robot involved in the migration does not contain the @ character, the migration will not succeed. To overcome this, local users need to be converted to directory users. This is done automatically during installation or upgrade, as long as impacted users log in to Orchestrator at least once. If they do not, you can use this script to convert them:

  DECLARE @domain VARCHAR(100) = 'your-domain-name-here'
  UPDATE u
  SET
      u.[UserName] = CONCAT(u.[UserName], '@', lower(@domain)),
      u.[Type] = 2
  FROM
      [dbo].[Users] u
      JOIN [dbo].[UserLogins] l ON u.[Id] = l.[UserId]
  WHERE 
      u.[Type] = 0
      AND l.[LoginProvider] = 'Windows'
      AND u.[IsDeleted] = 0

1. For each target account that is not correct or not set, you must manually set the account:
   1. Click Assign in the Target user account column.
   2. In the Search for a user field, start typing to search, and then select the user from the results.
   3. 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.

Important: 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.

Using the Wizard for 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.

     Important: 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:

1. 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.

2. 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.

1. 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.

2. 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.

Important: 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.

   Note: 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.

     Tip: If the migration fails with an error for Test Data Queues or Test Data Queue items, select the Clean-up before retrying checkbox before restarting the migration. This prevents duplicate Test Data Queue items in the modern folders.

   • 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

After migration is complete, 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, such as action catalogs, in the corresponding modern folder.

   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. Unlink the Test Sets from the classic folders, by deleting them from the corresponding Test Manager projects.
   
   

   

   
   
4. Link the Test Sets again, by selecting the Test Sets that have [Migrated] as their description.
   
   

   

   
   
5. Update the classic folder process used in UiPath Apps to use the newly-migrated modern folder process.
6. 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.
7. If not already enabled, enable interactive sign-in for the tenant. This is mandatory for working in modern folders.
8. Run the unattended processes from Orchestrator using Start Job to test them in modern setup.
   Note: 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.
9. Upgrade end-user workstations to use UiPath Robot version 2019.10 or later.
10. 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.

Manual migration

To take advantage of the features provided by modern folders, you must recompile existing workflows that are using Orchestrator activities or are making direct HTTP calls to the Orchestrator API, using UiPath.System.Activities v19.10.1 or higher. You must also reprovision all other existing entities in a modern folder structure except for: Robots - as they are automatically provisioned for users with access to the new modern folder; and Environments - as they are not used in the context of a modern folder.

Important:

Upgrading your existing entities to the modern model removes all backward compatibility. The recompiled workflows are only executable by 2019.10+ Robots.

Migrating to Modern Folders

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. A general overview of the migration process can be thought of as follows:

• Each previous Organization Unit, or Tenant if no OU's were used, becomes a First Level Folder. This is done automatically when you upgrade your Orchestrator instance.

• Each Environment becomes a separate subfolder or, alternatively, its own first-level Folder if you want to keep the users and processes in each segregated completely.

• The workflow of each Package must be recompiled using current activities and then republished or uploaded to Orchestrator.

• Using the newly compiled Packages, each Process must be redeployed to the Folder (or subfolder), which corresponds with its previous Environment.

• Each User must be added to the Folder(s) corresponding with the Processes they need to access.

This migration can be performed seamlessly for the User. The Orchestrator administrator creates and adds the entire modern folder structure and needed entities while the users still utilize the existing entities in the classic folders where they are assigned. During this time, you can create two robots with the same domain\username, one in a classic folder and one in a modern folder, and the user sees and executes only the classic processes available to them. When the classic robot is deleted, the modern robot takes over and executes the newly created and added modern versions of those same processes, with no change in the user's experience.

Important:

If a classic robot exists with the same domain/username as a user in a modern folder, the user will only have access to the classic robot and related processes. In order for the attended robot to work in a modern context, the classic floating robot has to be deactivated. After the migration is successfully tested and vetted, the classic robot can safely be deleted.

Assisted Migration Using Orchestrator Manager

To simplify the process of migrating to modern folders, you can use the UiPath Orchestration Manager. This is a Studio project that uses the Orchestrator API to manipulate entities based on Microsoft Excel workbooks. For instructions on how to use it for migration, see the product's documentation.