# About the Activity Migrator Tool

> Migrate legacy automation projects to the modern UiPath platform using the Activity Migrator CLI tool in Studio.

## 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](https://docs.uipath.com/activities/other/latest/productivity/new-outlook-impacts-outlook-desktop-activities) 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](https://docs.uipath.com/activities/docs/about-the-ui-automation-activities-pack) or [Mail](https://docs.uipath.com/activities/other/latest/productivity/mail-activities) 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.

### Result

The Activity Migrator `.zip` file is downloaded to your machine. Extract it and install the tool in the `<tool-install-dir>` folder before running any commands.

## Requirements
* If the tool is used on a machine where Studio is not installed, install [.NET Desktop Runtime 8.0](https://dotnet.microsoft.com/en-us/download/dotnet/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 | Description |
|---|---|
| `-?`, `-h`, `--help` | Show help and usage information. |

### Available commands

| Command | Description |
|---|---|
| `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 | Description |
|---|---|
| `-?, -h, --help` | Show help and usage information. |
| `-p, --project-path` **(Required)** | 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](https://docs.uipath.com/automation-suite/automation-suite/2.2510/admin-guide/external-applications-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](https://docs.uipath.com/orchestrator/standalone/2025.10/user-guide/managing-external-applications). |
| `--orchestrator-application-secret` | OAuth application secret for Orchestrator authentication (alternative to PAT). Use with `--orchestrator-application-id`. Refer to [Managing External OAuth Applications](https://docs.uipath.com/orchestrator/standalone/2025.10/user-guide/managing-external-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](#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 | Description |
|---|---|
| `-?, -h, --help` | Show help and usage information. |
| `-p, --project-path` **(Required)** | 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](#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 | Description |
|---|---|
| `-?, -h, --help` | Show help and usage information. |
| `-p, --path` **(Required)** | Path to the repository or folder. The migration is performed on all sub-folders that contain a `project.json` file. |
| `-c, --command` **(Required)** | 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`. |

### Examples

Analyze a single project with verbose output:
```shell
UiPath.Upgrade.exe analyze -p C:\to-migrate\LegacyProcess -v
```

Migrate a project and specify a target UI Automation package version:
```shell
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:
```shell
UiPath.Upgrade.exe upgrade --project-path=C:\to-migrate\LegacyProcess --config=C:\to-migrate\connection.json
```

Run a bulk analysis on a folder:
```shell
UiPath.Upgrade.exe bulk -p C:\to-migrate -c analyze
```

:::note
* The command-line options use the following conventions:
  * Short options (for example, `-p value`) must use a **space** to separate the option from its value.
  * Long options (for example, `--project-path=value`) typically use the **equals sign** to explicitly bind the value to the specific flag. In most cases, long options can also be specified using a space (for example, `--project-path value`). The `--config` option is an exception and **only** supports the equals sign syntax (for example, `--config=value`).
* 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.
:::

### Configuration file

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 with the assignment operator `=`, as in this example: `--config=C:\to-migrate\connection.json`.

The configuration file must follow this format:

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

:::note
* 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: Select 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/{OrganizationName}/{TenantName}/orchestrator_/connections/{ConnectionId}/edit/tid={TId}`

#### Result

The Connection ID is visible in the browser URL in the format `.../connections/{ConnectionId}/edit/tid={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:

```json
{
    "* > *": {
        "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](https://docs.uipath.com/activities/other/latest/ui-automation/n-application-card) 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](https://docs.uipath.com/activities/other/latest/ui-automation/open-browser) and [Attach Browser](https://docs.uipath.com/activities/other/latest/ui-automation/browser-scope). 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.

## Limitations

### UI Automation activities

- 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](https://docs.uipath.com/studio/standalone/latest/user-guide/ui-automation-supported-activities)
  - [UI Automation unsupported activities](https://docs.uipath.com/studio/standalone/latest/user-guide/ui-automation-unsupported-activities)
- Migrated workflows using modern UI Automation activities may execute more slowly than the original workflows using classic UI Automation activities.

### Productivity activities

- The minimum supported target version of `UiPath.MicrosoftOffice365.Activities` is `3.6.10`.
- See the supported activities lists:
  - [Mail supported activities](https://docs.uipath.com/studio/standalone/latest/user-guide/mail-supported-activities)
  - [Mail unsupported activities](https://docs.uipath.com/studio/standalone/latest/user-guide/mail-unsupported-activities)

### Tool limitations

- By default, the Activity Migrator tool uses NuGet feeds configured in `NuGet.config`: Official, Local, and [Marketplace](https://marketplace.uipath.com/). 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](https://docs.uipath.com/studio/standalone/latest/user-guide/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](https://docs.uipath.com/studio/standalone/2025.10/user-guide/introduction) and ensure target package versions meet the minimum requirements ([UiPath.UIAutomation.Activities](https://docs.uipath.com/activities/other/latest/ui-automation/about-the-ui-automation-activities-pack) >= 25.10.21 and [UiPath.MicrosoftOffice365.Activities](https://docs.uipath.com/activities/other/latest/productivity/about-the-microsoft-office-365-activities-pack) >= 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](https://marketplace.uipath.com/) 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`:

```json
{
    "* > *": {
        "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.