Uipath Activity Migrator

UiPath Activity Migrator

Drive the standalone Activity Migrator (UiPath.Upgrade.exe) end to end: acquire, analyze, upgrade, verify, report. The tool converts a Windows-Legacy project to the Windows framework and rewrites UiPath's classic activities into their modern UiPath equivalents; third-party and custom packages are only moved to a Windows-compatible version by restore, never rewritten. It runs without Studio. It requires Windows and the .NET Desktop Runtime 8.

<!--skill-flavor:host-availability-extra:start-->

<!--skill-flavor:host-availability-extra:end-->

Read referenced files in full. This SKILL.md is a router. Before running analyze, open and read the whole package guide for every classic package the project uses (see Package Routing). Package guides add flags, config files, triage rules, and post-migration steps that the core workflow does not know.

<SKILL_DIR> below is the folder that contains this SKILL.md. <PROJECT_DIR> is the absolute path of the folder holding project.json. <OUTPUT_DIR> is the migrated copy, a sibling folder, <PROJECT_DIR>_Upgraded by default, always as an absolute path: uip rpa rejects relative ones.

When to Use This Skill

• User wants to migrate, upgrade, convert, or modernize a Windows-Legacy project or its classic UiPath activities
• User wants classic UiPath UI Automation activities rewritten as their modern counterparts
• User wants to run the Activity Migrator or mentions UiPath.Upgrade.exe
• User wants a migration dry run or migration report produced by the tool (analyze)
• User wants classic Outlook mail, classic GSuite, or Microsoft.Activities.Extensions activities migrated
• User wants a post-migration fix: an already-migrated project whose expression-selector targets fail at runtime or silently report not-found, or one carrying [PostMigration Action Required] annotations. The skill owns such a failure while the failing target or an enclosing construct carries one of three signals: the .ToStringWithDelimiter() marker, a [PostMigration Action Required] line, or a by uipath-activity-migrator line (Rule 12). Otherwise the failure belongs to uipath-troubleshoot

Do not use for: authoring or editing Legacy workflows (uipath-rpa, Legacy mode), a readiness review that does not run the tool (uipath-review), diagnosing a runtime failure of an already-migrated project whose failing construct carries none of the three signals above (uipath-troubleshoot), uip solution deploy upgrade, or Maestro instance migrate.

Critical Rules

1. Windows only. Check the OS before anything else. On macOS or Linux, stop and tell the user to run the migration from a Windows machine that holds the project. The tool is a .NET 8 desktop process and cannot run elsewhere.
2. Never run the tool in console mode. Always pass --output-format sarif and redirect stdout to a file. Console mode opens an HTML report in the browser and prints no machine-readable result.
3. Never trust the exit code. The tool exits 0 whether the migration succeeded, partially succeeded, or failed. Status comes only from the SARIF results, classified per sarif-triage-guide.md.
4. Analyze before upgrade, every time. Run analyze, triage it, and only then run upgrade. When the analyze triage shows no stop condition, proceed to upgrade without asking, unless the user asked only for an analysis, a report or a plan: then stop after the triage, present the findings with the proposed treatment of each needs-attention item, and run upgrade only on the user's go. Any request whose deliverable is information rather than a migrated project counts as that: analysis, report, plan, dry run, "can this be migrated", "what would change"; when the wording leaves it open, ask one yes/no before upgrade. Rule 13 governs a treatment the user chooses there. One exception: a Step 4 rerun that the build guide or a package guide prescribes with an added flag reuses the Step 3 analyze; it counts as one build-fix iteration (Rule 10), and the skill deletes the <OUTPUT_DIR> it created in this session without asking.
5. Never write into the source project. upgrade writes to a fresh sibling folder. Never point --output-path at <PROJECT_DIR>, never copy the output back over the source, never delete the source, and never edit a file in it, project.json included. This holds for every source project the task touches, including a library's source project. Two folders inside the source are the only exception: .upgrade/, which holds the tool's reports and the logs, summaries and config files this skill's steps write there, and .local/, the tool's restore cache.
6. Never pass secrets through the agent. Do not type --orchestrator-pat or --orchestrator-application-secret values yourself. When a tenant feed is required, rely on the tool's fallback to the local Studio or Robot connection; if that fails, hand the user the complete command with <PLACEHOLDER> values to run themselves.
7. Resolve the target UIAutomation package line explicitly. When the project uses UiPath.UIAutomation.Activities, resolve the latest stable patch of a release line per Step 2 and pass it as --uia-package-version=<UIA_VERSION>. Extension options bind only in the --name=value form; the space-separated form parses without error and is silently ignored. Accept the tool default only when the feed is unreachable, and say so in the report. The target version is settled before the migration runs; the skill never edits package versions on the output afterwards to reach it.
8. Verify with the modern CLI. Migration is not done until uip rpa build passes on <OUTPUT_DIR>, or the remaining errors are reported as needs-attention items after the bounded fix loop in build-verification-guide.md. Every uip rpa command this skill runs unsets UIPATH_STUDIO_PID in the syntax of the shell that runs it: in bash, the Bash tool on Windows included, prefix env -u UIPATH_STUDIO_PID; in PowerShell, put $env:UIPATH_STUDIO_PID = $null; in the same command, before uip, which removes it; a separate tool call starts a new process and loses the assignment. The PowerShell form does not unset the variable in bash, the bash prefix fails in PowerShell, and setting the variable to an empty string does not unset it. A brief to a subagent passes this rule on together with the commands, so the subagent writes the form for its own shell. Dropping it is never an acceptable translation. runtime-verification-guide.md says why.
9. Libraries first. When analyze reports RESTORE-CUSTOM-LIBRARY-MIGRATION-REQUIRED, stop. Tell the user to migrate and publish that library to the feed before migrating this project. The tool cannot order dependencies.
10. Bounded loops. At most 3 build-fix iterations in Step 5. Then report what remains.
11. Never run the migrated project unasked. The runtime check of Step 6 runs only after the user answers yes to its one question. An earlier explicit request to run the migrated project, given in the same task, counts as that yes, and the question is then not asked. Every fix and every rerun after it happens only through the runtime guide's fix and rerun loop, each behind one yes/no; outside that loop the check only observes. It runs in the headless Studio, never in the Studio the user has open (Rule 8).
12. Mark every edit. Every construct the skill edits or adds outside the tool, in the post-migration fix guide, the build loop, the runtime loop, a plan treatment or an edit delegated to the RPA authoring skill, carries the annotation line Remediated by uipath-activity-migrator on <YYYY-MM-DD>: <what changed>. It replaces the matching [PostMigration Action Required] line when there is one and is added as a new annotation otherwise. Write it as part of the edit itself, so an undone fix loses it with the backup restore and a standing fix keeps it whatever happens next. One exception: a construct whose only edit is the fix guide's rewrite of an annotation line to Verified healthy by uipath-activity-migrator carries that line as its mark and gets no Remediated line. A later failure at a construct carrying either line is this skill's to diagnose.
13. Plan-mode treatments. When the user asked for a plan (Rule 4), the treatment their go names is the edit, even when it differs from the one proposed. A proposal leaves open any name only a run can reveal, such as the exception an activity actually throws ("retype the Catch to the exception the run reports"); it never guesses one. Step 5a applies the chosen treatment.

Workflow

Fix-only entry. When the user asks to fix or scan a project that was already migrated, or reports a UI failure in one, none of the steps below apply. First settle ownership: grep the project's XAML for the three signals, ToStringWithDelimiter, PostMigration Action Required and by uipath-activity-migrator. When the failing construct and its ancestors carry none, or for a project-wide request no file carries any, hand the failure to uipath-troubleshoot together with that result: do not build, do not run. Otherwise run uia-post-migration-fix-guide.md with that project as <MIGRATED_DIR>, then build it with the build and fix loop in build-verification-guide.md, offer the runtime check per runtime-verification-guide.md with <MIGRATED_DIR> as its <OUTPUT_DIR>, and report once, at the end, in the shape given by the fix guide's Output section. Do not resolve a package version, do not run package-guide hooks, and do not use the Step 6 template: nothing was analyzed or upgraded.

Step 0 — Preflight and acquire the tool

Run the acquisition script with node, which Steps 2 to 4 already use for their scripts; the same command works in bash and in PowerShell. It executes no PowerShell or shell script file, so script execution policies and hosts that gate a script invocation do not apply. The script locates a cached tool, downloads and extracts it when missing, checks the .NET Desktop Runtime 8, and prints one JSON object on its last stdout line. Any run can download the archive, a first install or an update, a few hundred MB: give the command at least 10 minutes, not the host's default timeout. Every other shell command in this skill assumes Git Bash, which the Bash tool uses on Windows: the redirections and the grep pipelines are not translated, and the only PowerShell alternative given is Rule 8's variable.

node "<SKILL_DIR>/scripts/ensure-migrator.mjs"

Then read the flag list of this build once. It is the only authority on which flags exist.

"<MIGRATOR_EXE>" analyze --help

Keep the output for Steps 3 and 4. For this run, the flags in that output are the only flags that exist: a guide-named flag is passed only when it appears there, and its absence is not a finding, not a note, and not a report item. A flag the help lists but no guide names may be used only when its help text directly addresses a problem this run has shown (a specific SARIF result or build error); pass it as --name=value and say so in the report. Never one that changes what migrates or which extensions run; those are passed only on the user's request. Behavior the help does not state (option binding, exit code, output streams, folders) is in tool-behavior-guide.md.

Summarize to the user in one line: tool version and location.

Step 1 — Discover the project

1. Resolve <PROJECT_DIR>: the folder containing project.json. If several exist under the working directory, ask which one, unless the user named it. For "migrate everything in this repo", see tool-behavior-guide.md § bulk.
2. Read project.json and record: targetFramework, expressionLanguage, dependencies. Legacy (or absent) is the primary case. Windows projects still qualify when they hold classic activities; tell the user the framework step will be a no-op.
3. Match dependencies against the Package Routing table. Read every matching package guide in full now.
4. Pick <OUTPUT_DIR>: the user's choice, else <PROJECT_DIR>_Upgraded. If it already exists, ask whether to delete it or use a different name. Never reuse it silently: the tool merges into an existing folder.
5. If the project is under git, run git status --short in it and mention uncommitted changes in the report. Do not commit or stash. The tool's .upgrade/ and .local/ folders will show as untracked afterwards; say so.

Step 2 — Resolve the target package line

Only when UiPath.UIAutomation.Activities is a dependency. Rationale and details: packages/uia-guide.md § Resolve the target line.

1. If the user named a line or version ("migrate to 26.10", "use 25.10.40"), resolve that and skip the question. A version below the minimum in uia-guide.md § Version gates cannot be used: say so, name the minimum, and ask for another; the tool enforces the same minimum in Step 3.

2. Otherwise resolve the candidate lines from the official UiPath NuGet feed. The script needs no project and no login. Do not use uip rpa packages versions here: the headless Studio host it starts refuses to open Legacy projects.

   node "<SKILL_DIR>/scripts/resolve-package-lines.mjs" --package UiPath.UIAutomation.Activities --min 25.10.21

   Output: the two most recent LTS lines (<year>.10) with their highest stable patch; the newest is recommended.

3. Ask once with AskUserQuestion: newest line first, labeled (Recommended), each option showing <line>.x → <version>. Say once that a package version runs only on Studio and robots at or above the minimum its release notes list, so the older line is the safe pick when the fleet is behind. The project's studioVersion field is not a signal: it records the Studio that last saved the Legacy project. If the user defers the choice, take the recommended line.

4. If the script prints error (feed unreachable), pass no version and let the tool pin its built-in default: do not ask. Step 3 sets <UIA_VERSION> from the version the tool reports, and the report line carries the suffix "(tool default, feed unreachable)".

Record the chosen version as <UIA_VERSION>.

Step 3 — Analyze

Assemble <PACKAGE_FLAGS> from every package guide read in Step 1 (Hook 1 sections). Then:

mkdir -p "<PROJECT_DIR>/.upgrade"
"<MIGRATOR_EXE>" analyze --project-path "<PROJECT_DIR>" --uia-package-version=<UIA_VERSION> --output-format sarif <PACKAGE_FLAGS> > "<PROJECT_DIR>/.upgrade/analyze-latest.sarif" 2> "<PROJECT_DIR>/.upgrade/analyze-latest.err"
node "<SKILL_DIR>/scripts/summarize-sarif.mjs" "<PROJECT_DIR>/.upgrade/analyze-latest.sarif" --out "<PROJECT_DIR>/.upgrade/analyze-latest.md"

Omit --uia-package-version when the project has no UIAutomation dependency or when Step 2 fell back to the tool default; never pass the flag with an empty value. The summarizer prints a short summary (status, counts, blockers, a Reason: line for a failed without blockers or an unknown, step failures, what needs attention grouped by reason and by file) and writes the full per-item report to the --out file. Show the user the short summary as is.

Read the UiPath.UIAutomation.Activities entry on the summarizer's Packages: line. Its to value, the version after → or the one marked (unchanged), is what <OUTPUT_DIR>/project.json will hold. Decide by what the entry says, first matching row wins:

Then apply the stop conditions: