About the Activity Migrator Tool

Purpose of the Activity Migrator

The Activity Migrator is an essential command-line interface (CLI) tool for organizations transitioning legacy automation projects to the modern UiPath platform, enabling access to the latest features and capabilities:

• Automate the migration process by simplifying and streamlining the transfer of process configuration and dependencies.
• Reduce manual effort and errors by ensuring consistency and accuracy during migration, instead of manually transferring dependencies and activities.

Supported migration scenarios

Project framework migration

Migrating a Windows - Legacy project to the Windows compatibility is highly recommended for several strategic, technical, and support-related reasons:

1. Improved performance: Windows projects run faster and more efficiently due to better integration with .NET Core and modern Windows APIs.
2. Better compatibility with external libraries: Windows projects support newer versions of libraries and dependencies, making it easier to integrate with external systems.

Access to modern UI Automation capabilities

Many new UI Automation features, such as Unified Target and Healing Agent, are only compatible with the modern UI Automation framework. Therefore, migrating from classic UI Automation activities to the modern experience is necessary.

Deprecated Outlook activities migration

Microsoft is sunsetting Classic Outlook and encouraging adoption of Microsoft 365. As a result, the Activity Migrator supports transitioning automation dependencies from UiPath.Mail.Activities (which rely on the Classic Outlook API) to UiPath.MicrosoftOffice365.Activities based on UiPath Integration Service.

Activity Migrator vs. the Studio Windows - Legacy converter

Use the Studio Windows - Legacy converter when:

• You only need to convert projects from Windows - Legacy to Windows one by one.
• No activity migrations are required.

Use the Activity Migrator when:

• You want to convert multiple Windows - Legacy projects to Windows (bulk conversion supported).
• Migration of UI Automation or Mail activities is needed.
• Any combination of the above scenarios applies.

Where to get the Activity Migrator

Follow the steps below to download the tool:

1. Navigate to UiPath Automation Cloud.
2. Select the Help button in the top-right corner.
3. Under Resources, select Downloads.
4. Under the Feature Download list, select Activity Migrator Tool.
5. Select the download link.

After downloading the .zip file, make sure to install it in the <tool-install-dir> folder.

Anforderungen

• If the tool is used on a machine where Studio is not installed, install .NET Desktop Runtime 8.0.
• Open migrated projects with Studio versions 2024.10 or higher.

How to use the Activity Migrator

Command: <tool-install-dir>\UiPath.Upgrade.exe

Usage: UiPath.Upgrade.exe [command] [options]

Global options:

Option	Beschreibung
-?, -h, --help	Zeigen Sie Hilfe- und Nutzungsinformationen an.

Available commands:

Befehl	Beschreibung
version	Show version information.
analyze	Analyze a project for migration without making changes.
upgrade	Migrate a project or parts of it.
bulk	Analyze or migrate all projects in a folder.

Analyze a project

This option simulates the migration and generates a report without performing the actual migration or modifying the project.

Command: <tool-install-dir>\UiPath.Upgrade.exe analyze

Usage: UiPath.Upgrade.exe analyze [options]

Option	Beschreibung
-?, -h, --help	Zeigen Sie Hilfe- und Nutzungsinformationen an.
-p, --project-path (erforderlich)	Path to the project to analyze or upgrade. The folder provided as <project-path> should contain the project’s project.json file.
-o, --output-path	Output path for the upgraded project (optional). If not specified, a new folder with the suffix _Upgraded is created.
-v, --verbose	Enable verbose logging.
-f, --output-format	Output format: console (default) or sarif.
-e, --extension-directory	Directory to search for extensions. For advanced use only.
--ignore-missing-dependencies	Ignore missing dependencies during upgrade. Missing dependencies appear as warnings. Affected workflows may report missing types, fail to compile, or fail to perform other needed migrations.
--orchestrator-url	The full Orchestrator URL, including organization name (for example, https://cloud.uipath.com/myorg). If not specified, the connection from Studio is used. When specified, you must also provide credentials via Personal Access Token (PAT) using --orchestrator-pat or external Application ID and secret using --orchestrator-application-id and --orchestrator-application-secret.
--orchestrator-tenant	The Orchestrator tenant name. Defaults to DefaultTenant if not specified.
--orchestrator-pat	Personal Access Token (PAT) for Orchestrator authentication, used to access Orchestrator library feeds. Create a Personal Access Token, and add Orchestrator API access scope OR.Execution.Read. Refer to Personal Access Tokens. Alternatively, configure an application id and secret using --orchestrator-application-id and --orchestrator-application-secret.
--orchestrator-application-id	OAuth Application ID for Orchestrator authentication (alternative to PAT). Use with --orchestrator-application-secret. Refer to Managing External OAuth Applications.
--orchestrator-application-secret	OAuth application secret for Orchestrator authentication (alternative to PAT). Use with --orchestrator-application-id. Refer to Managing External OAuth Applications.
--enabled-extensions	Comma-separated list of extensions to enable. By default, all extensions are enabled. Available extensions: UiAutomationActivities, MailActivities, MicrosoftActivitiesExtension. Example: --enabled-extensions MailActivities,MicrosoftActivitiesExtension
--disabled-extensions	Comma-separated list of extensions to disable. Available extensions are dynamically populated based on discovered extensions.
--disable-all-extensions	Disable all extensions. This option is mutually exclusive with --enabled-extensions and --disabled-extensions.
--uia-package-version	The version of the UI Automation activities package to use for migration. Defaults to 25.10.21 if not specified. The target version must be higher than the default. If not, the default is used.
--uia-fix-selector-strategy	When set to true, fixes the SelectorStrategy enumeration ambiguity in pre-existing expressions after migration. Applies to UIAutomation version 25.10.29 or higher. Default: false. The ambiguity results from the SelectorStrategy enumeration existing in both the UiPath.Core and UiPath.UIAutomationNext.Enums namespaces. Using the fully-qualified name resolves this issue.
--mail-o365-package-version	The version of the Microsoft Office 365 activities package to use for migration. Defaults to version 3.6.10. The target version must be higher than the default. If not, the default is used.
--config	Specifies the path to a custom configuration JSON file. The configuration can be used to modify the default behavior of certain activities or assign constant values to properties that require user input during the migration. Refer to Configuration file.

Migrate a project

This option performs the actual migration of a project or parts of it.

Command: <tool-install-dir>\UiPath.Upgrade.exe upgrade

Usage: UiPath.Upgrade.exe upgrade [options]

Option	Beschreibung
-?, -h, --help	Zeigen Sie Hilfe- und Nutzungsinformationen an.
-p, --project-path (erforderlich)	Path to the folder containing the project's project.json file.
-o, --output-path	Output path for the upgraded project (optional). If not specified, a new folder with the suffix _Upgraded is created.
-v, --verbose	Enable verbose logging.
-f, --output-format	Output format: console (default) or sarif.
-e, --extension-directory	Directory to search for extensions. For advanced use only.
--ignore-missing-dependencies	Ignore missing dependencies during upgrade. Missing dependencies appear as warnings. Affected workflows may report missing types, fail to compile, or fail to perform other needed migrations.
--orchestrator-url	The full Orchestrator URL, including organization name. If not specified, the connection from Studio is used. When specified, credentials are required.
--orchestrator-tenant	The Orchestrator tenant name. Defaults to DefaultTenant if not specified.
--orchestrator-pat	Personal Access Token (PAT) for Orchestrator authentication. Requires the OR.Execution.Read scope.
--orchestrator-application-id	OAuth Application ID for Orchestrator authentication (alternative to PAT).
--orchestrator-application-secret	OAuth application secret (alternative to PAT).
--enabled-extensions	Comma-separated list of extensions to enable. Available extensions: UiAutomationActivities, MailActivities, MicrosoftActivitiesExtension. Example: --enabled-extensions MailActivities,MicrosoftActivitiesExtension
--disabled-extensions	Comma-separated list of extensions to disable. Available extensions are dynamically populated based on discovered extensions.
--disable-all-extensions	Disable all extensions. Mutually exclusive with --enabled-extensions and --disabled-extensions.
--uia-package-version	Target UiPath.UIAutomation.Activities package version. Defaults to 25.10.21.
--uia-fix-selector-strategy	When set to true, fixes the SelectorStrategy enumeration ambiguity in pre-existing expressions after migration. Applies to UIAutomation version 25.10.29 or higher. Default: false. The ambiguity results from the SelectorStrategy enumeration existing in both the UiPath.Core and UiPath.UIAutomationNext.Enums namespaces. Using the fully-qualified name resolves this issue.
--mail-o365-package-version	The version of the Microsoft Office 365 activities package to use for migration. Defaults to version 3.6.10. The target version must be higher than the default. If not, the default is used.
--config	Specifies the path to a custom configuration JSON file. The configuration can be used to modify the default behavior of certain activities or assign constant values to properties that require user input during the migration. Refer to Configuration file.

Bulk repository migration

This option analyzes or migrates all projects found in a folder hierarchy.

Command: <tool-install-dir>\UiPath.Upgrade.exe bulk

Usage: UiPath.Upgrade.exe bulk [options]

Option	Beschreibung
-?, -h, --help	Zeigen Sie Hilfe- und Nutzungsinformationen an.
-p, --path (erforderlich)	Path to the repository or folder. The migration is performed on all sub-folders that contain a project.json file.
-c, --command (erforderlich)	Command to run: analyze or upgrade.
-v, --verbose	Enable verbose logging.
-o, --output-path	Output root path for upgraded projects. This folder is created if it does not exist. A new folder with the suffix _Upgraded is created for the upgraded project.
--orchestrator-url	The full Orchestrator URL, including organization name.
--orchestrator-tenant	The Orchestrator tenant name. Defaults to DefaultTenant if not specified.
--orchestrator-pat	Personal Access Token (PAT) for Orchestrator authentication. Requires the OR.Execution.Read scope.
--orchestrator-application-id	OAuth Application ID for Orchestrator authentication (alternative to PAT).
--orchestrator-application-secret	OAuth application secret (alternative to PAT).
--enabled-extensions	Comma-separated list of extensions to enable. Available extensions: UiAutomationActivities, MailActivities, MicrosoftActivitiesExtension. Example: --enabled-extensions MailActivities,MicrosoftActivitiesExtension
--disabled-extensions	Comma-separated list of extensions to disable. Available extensions are dynamically populated based on discovered extensions.
--disable-all-extensions	Disable all extensions. Mutually exclusive with --enabled-extensions and --disabled-extensions.

Beispiele

Analyze a single project with verbose output:

UiPath.Upgrade.exe analyze -p C:\to-migrate\LegacyProcess -v

Migrate a project and specify a target UI Automation package version:

UiPath.Upgrade.exe upgrade -p C:\to-migrate\LegacyProcess -o C:\to-migrate\WindowsProcess --uia-package-version=25.10.27 -v

Migrate a project using a custom connection configuration:

UiPath.Upgrade.exe upgrade --project-path=C:\to-migrate\LegacyProcess --config=C:\to-migrate\connection.json

Run a bulk analysis on a folder:

UiPath.Upgrade.exe bulk -p C:\to-migrate -c analyze

Hinweis:

The default output of the upgrade command is a SARIF report stored in the original project under a .upgrade folder. The migrated project is saved to the output path.

Konfigurationsdatei

Use a configuration file to set constant values for activity properties that require manual input during migration, or to override default migration behavior.

Pass the file path to the migrator using the --config option.

The configuration file must follow this format:

{
  "{reserved-configuration-key}": "{value}",
  "...": "...",
  "{path-to-workflow} > {activity-display-name}": {
    "{property-name}": "{property-value}"
  }
}

Hinweis:

• Currently, the only {property-name} that can be assigned is Connection Id.
• {reserved-configuration-key} represents activity-specific behavior changes:
  • SaveOutlookMailMessage_IgnoreSaveAsType: If set to true, the option disables the Save as type check for unsupported types. The activity can thus be migrated regardless of the Save as type option.
• * acts as a wildcard and matches any value in both {path-to-workflow} and {activity-display-name}.
• When multiple entries match the same workflow and activity, only the last match is applied.

Getting the ConnectionId from Orchestrator

AS of March 2026, connections have moved from Integration Service to Orchestrator. You can retrieve the ConnectionId directly from the connection URL in Orchestrator:

1. Navigate to your connection in Orchestrator: Go to the Orchestrator folder where your Microsoft Outlook 365 connection is located.
2. Open the connection: Click on the connection to view its details.
3. Check the URL: The ConnectionId is visible in the browser URL with the following format: https://cloud.uipath.com///orchestrator_/connections//edit/tid=

Setting Connection IDs for Productivity activities

The ConnectionId property is not populated automatically during migration. You must set it manually per workflow/activity using a configuration file. The configuration file can be passed to the Activity Migrator using the --config <config> command line argument.

The following example assigns different connection IDs to specific Productivity activities (Microsoft Office 365, GSuite), using a wildcard fallback:

{
    "* > *": {
        "ConnectionId": "00000000-0000-0000-0000-000000000001"
    },
    "*\\Projects\\MailMigration\\Main.xaml > Get *": {
        "ConnectionId": "00000000-0000-0000-0000-000000000002"
    },
    "*\\Projects\\MailMigration\\* > Send Mail": {
        "ConnectionId": "00000000-0000-0000-0000-000000000003"
    }
}

In this example:

• * > * matches all activities and acts as a fallback when there are no matching entries below.
• *\\Projects\\MailMigration\\Main.xaml > Get * matches any activity whose display name starts with Get in Main.xaml.
• *\\Projects\\MailMigration\\* > Send Mail matches the Send Mail activity across all workflows in the MailMigration folder.

Post-migration UI Automation Application Scope behavior

Most modern UI Automation activities require an application scope (Use Application/Browser activity). During migration, two types of scopes are created:

Organically created scopes

These scopes are generated automatically when migrating classic scoped activities such as Open Browser and Attach Browser. These scopes are not optimized to avoid altering the original intent and flow of the migrated workflow.

Synthetically generated scopes

These scopes are generated to ensure the workflow compiles and runs correctly after migration. When two consecutive scopes have identical properties (for example, the same selector or OCR engine), they are merged into a single scope while preserving the original activity order.

Einschränkungen

UIAutomation-Aktivitäten

• The minimum supported target version of UiPath.UIAutomation.Activities is 25.10.21.
• Some activity properties have migration limitations. See the supported activities lists:
  • UI Automation supported activities
  • UI Automation unsupported activities
• Migrated workflows using modern UI Automation activities may execute more slowly than the original workflows using classic UI Automation activities.

Produktivitätsaktivitäten

• The minimum supported target version of UiPath.MicrosoftOffice365.Activities is 3.6.10.
• See the supported activities lists:
  • Mail supported activities
  • Mail unsupported activities

Tool limitations

• By default, the Activity Migrator tool uses NuGet feeds configured in NuGet.config: Official, Local, and Marketplace. To include Orchestrator library feeds, use the options for the analyze, upgrade, and bulk commands: --orchestrator-url, --orchestrator-tenant, --orchestrator-pat, --orchestrator-application-id, and --orchestrator-application-secret.
• Activities that use dynamically generated types or assemblies (for example, some Excel activities may have column names as properties in a dynamically generated type) may cause a Type not found error in .xaml files after migration.

Studio Workflow Analyzer rule

• The ST-AMG-001 Workflow Analyzer rule is available starting with Studio 2025.10.8 LTS and Studio 2026.0.189 STS.

Migration best practices

Before migrating

1. Back up your projects: Always create a full backup before running any migration commands.
2. Update Studio and activity packages: Use the latest version of UiPath Studio and ensure target package versions meet the minimum requirements (UiPath.UIAutomation.Activities >= 25.10.21 and UiPath.MicrosoftOffice365.Activities >= 3.6.10).
3. Analyze before upgrading: Run the analyze command first. Use UiPath.Upgrade.exe analyze -p -v to generate a SARIF report and identify potential issues without modifying the project.
4. Verify dependencies and NuGet feeds: Confirm that the Official, Local, and Marketplace feeds are correctly configured in NuGet.config.
5. Migrate the libraries first when a project depends on library projects: Only then migrate the projects that consume them.

During migration

5. Start with a single project: Test migration on one project using UiPath.Upgrade.exe upgrade -p -v before running a bulk operation.
6. Use bulk migration for multiple projects: Once validated, run UiPath.Upgrade.exe bulk -p -v. Ensure the folder structure is clean and consistent.
7. Provide a configuration file for Connection IDs: For Microsoft 365 or GSuite activities, create a config file with the required ConnectionId values and pass it with --config:

{
    "* > *": {
        "ConnectionId": "00000000-0000-0000-0000-000000000001"
    }
}

After migrating

8. Review the SARIF report: Check the .upgrade folder in the project directory and address any flagged issues.
9. Open the migrated project in Studio and run Analyze Project: Review the results of the ST-AMG-001 Workflow Analyzer rule (available in Studio 2025.10.8 LTS / Studio 2026.0.189 STS or higher) to identify activities that require post‑migration actions.
10. Validate application scopes: Confirm that merged scopes behave as expected. Test workflows with Use Application/Browser activities.
11. Run end-to-end tests: Execute migrated workflows in a controlled environment before deploying to production.

Performance and maintenance

12. Optimize UI Automation selectors: After migration, review selectors for accuracy and stability.
13. Monitor execution time: Modern activities may run slower initially. Optimize where needed.
14. Document your changes: Keep a record of migrated projects, target versions, and applied configurations for audit and rollback purposes.