Über das Aktivitäts-Migrator-Tool

Migrieren Sie ältere Automatisierungsprojekte zur modernen UiPath-Plattform mithilfe des CLI-Tools Activity Migrator.

Zweck des Aktivitäts-Migrators

Der Aktivitäts-Migrator ist ein unverzichtbares Befehlszeilenschnittstellen-Tool (CLI) für Organisationen, die ältere Automatisierungsprojekte auf die moderne UiPath-Plattform umstellen, und ermöglicht den Zugriff auf die neuesten Funktionen und Fähigkeiten:

• Automatisieren Sie den Migrationsprozess, indem Sie die Übertragung von Prozesskonfiguration und Abhängigkeiten vereinfachen und optimieren.
• Reduzieren Sie manuellen Aufwand und Fehler, indem Sie Konsistenz und Genauigkeit während der Migration sicherstellen, anstatt Abhängigkeiten und Aktivitäten manuell zu übertragen.

Unterstützte Migrationsszenarien

Projekt-Framework-Migration

Die Migration eines Windows-Legacy-Projekts zur Windows-Kompatibilität wird aus mehreren strategischen, technischen und supportbezogenen Gründen dringend empfohlen:

1. Verbesserte Leistung: Windows-Projekte werden aufgrund einer besseren Integration mit .NET Core und modernen Windows-APIs schneller und effizienter ausgeführt.
2. Bessere Kompatibilität mit externen Bibliotheken: Windows-Projekte unterstützen neuere Versionen von Bibliotheken und Abhängigkeiten, wodurch die Integration in externe Systeme einfacher wird.

Zugriff auf moderne UI Automatisierungs-Funktionen

Viele neue UI-Automatisierungs-Funktionen wie Unified Target und Healing Agent sind nur mit dem modernen UI Automation-Framework kompatibel. Daher ist die Migration von klassischen UI Automatisierungs-Aktivitäten zur modernen Benutzeroberfläche erforderlich.

Migration von veralteten Outlook-Aktivitäten

Microsoft stellt das klassische Outlook ein und fördert die Einführung von Microsoft 365.Infolgedessen unterstützt der Aktivitäts-Migrator die Übertragung von Automatisierungsabhängigkeiten von UiPath.Mail.Activities (die auf der klassischen Outlook-API basieren) zu UiPath.MicrosoftOffice365.Activities, basierend auf UiPath Integration Service.

Migration von GSuite-Aktivitäten

Um von den neuesten Erweiterungen zu profitieren, empfehlen wir die Verwendung der verbindungsbasierten Google Workspace-Aktivitäten des Integration Service. Der Aktivitäts-Migrator unterstützt die Konvertierung klassischer Aktivitäten in moderne Aktivitäten innerhalb desselben UiPath.GSuite.Activities -Pakets. Diese modernen Aktivitäten automatisieren über Google Workspace-Anwendungen (früher bekannt als GSuite) hinweg und decken sechs Dienste ab: Gmail, Calendar, Drive, Docs, Sheets und Apps Script.

Aktivitäts-Migrator vs. Studio Windows – Legacy-Konverter

Verwenden Sie den Studio Windows-Konverter – Legacy, wenn:

• Sie nur Projekte nacheinander von Windows-Legacy zu Windows konvertieren müssen.
• Es sind keine Aktivitätsmigrationen erforderlich.

Verwenden Sie den Aktivitäts-Migrator, wenn:

• Sie mehrere Windows-Legacy-Projekte in Windows konvertieren möchten (Massenkonvertierung wird unterstützt).
• Migration von UI-Automatisierungs-, E-Mail- oder klassischen GSuite- Aktivitäten ist erforderlich.
• Jede Kombination der oben genannten Szenarien gilt.

Woher Sie den Aktivitäts-Migrator beziehen

Führen Sie die folgenden Schritte aus, um das Tool herunterzuladen:

1. Navigieren Sie zu UiPath Automation Cloud.
2. Wählen Sie oben rechts die Schaltfläche Hilfe aus.
3. Wählen Sie unter Ressourcen die Option Downloads aus.
4. Wählen Sie unter der Liste „Empfohlener Download“ die Option Activity-Migrator-Tool aus.
5. Wählen Sie den Download-Link aus.

Ergebnis

Die Activity Migrator .zip -Datei wird auf Ihre Maschine heruntergeladen. Extrahieren Sie es und installieren Sie das Tool im Ordner <tool-install-dir> , bevor Sie Befehle ausführen.

Anforderungen

• Wenn das Tool auf einem Gerät verwendet wird, auf dem Studio nicht installiert ist, installieren Sie .NET Desktop Runtime 8.0.
• Öffnen Sie migrierte Projekte mit Studio-Version 2024.10 oder höher.

So verwenden Sie den Aktivitäts-Migrator

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

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

Globale Optionen

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

Verfügbare Befehle

Befehl	Beschreibung
version	Versionsinformationen anzeigen.
analyze	Analysieren Sie ein Projekt für die Migration, ohne Änderungen vorzunehmen.
upgrade	Migrieren Sie ein Projekt oder Teile davon.
bulk	Analysieren oder migrieren Sie alle Projekte in einem Ordner.

Analysieren eines Projekts

Diese Option simuliert die Migration und generiert einen Bericht, ohne die eigentliche Migration durchzuführen oder das Projekt zu ändern.

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

Nutzung: UiPath.Upgrade.exe analyze [options]

Option	Beschreibung
-?, -h, --help	Zeigen Sie Hilfe- und Nutzungsinformationen an.
-p, --project-path (erforderlich)	Pfad zum zu analysierenden oder zu aktualisierenden Projekt. Der als <project-path> bereitgestellte Ordner soll die Datei des Projekts project.json enthalten.
-o, --output-path	Ausgabepfad für das aktualisierte Projekt (optional). Wenn nicht angegeben, wird ein neuer Ordner mit dem Suffix _Upgraded erstellt.
-v, --verbose	Aktivieren Sie die ausführliche Protokollierung.
-f, --output-format	Ausgabeformat: console (Standard) oder sarif.
-e, --extension-directory	Verzeichnis zum Suchen nach Erweiterungen. Nur für erweiterte Verwendung.
--ignore-missing-dependencies	Ignorieren Sie fehlende Abhängigkeiten während des Upgrades. Fehlende Abhängigkeiten werden als Warnungen angezeigt. Betroffene Workflows melden möglicherweise fehlende Typen, können nicht kompiliert werden oder können andere erforderliche Migrationen nicht ausführen.
--orchestrator-url	Die vollständige Orchestrator-URL, einschließlich des Namens der Organization (z. B. https://cloud.uipath.com/myorg).Wenn nicht angegeben, wird die Verbindung aus Studio verwendet.Wenn angegeben, müssen Sie auch Anmeldeinformationen über Personal Access Token (PAT) unter Verwendung von --orchestrator-pat oder externe Anwendungs-ID und Geheimnis unter Verwendung von --orchestrator-application-id und --orchestrator-application-secret bereitstellen.
--orchestrator-tenant	Der Orchestrator-Mandantenname. Standardmäßig eingestellt auf DefaultTenant, wenn nicht angegeben.
--orchestrator-pat	Personal Access Token (PAT) für die Orchestrator-Authentifizierung, das für den Zugriff auf Orchestrator-Bibliotheksfeeds verwendet wird. Erstellen Sie ein persönliches Zugriffstoken und fügen Sie den Orchestrator-API-Zugriffs-Scope OR.Execution.Read hinzu. Weitere Informationen finden Sie unter Persönliche Zugriffstoken. Alternativ können Sie eine Anwendungs-ID und ein Geheimnis mit --orchestrator-application-id und --orchestrator-application-secret konfigurieren.
--orchestrator-application-id	OAuth-Anwendungs-ID für die Orchestrator-Authentifizierung (Alternative zu PAT). Mit --orchestrator-application-secret verwenden.Weitere Informationen finden Sie unter Verwalten von externen OAuth-Anwendungen.
--orchestrator-application-secret	OAuth-Anwendungsgeheimnis für die Orchestrator-Authentifizierung (Alternative zu PAT). Mit --orchestrator-application-id verwenden.Weitere Informationen finden Sie unter Verwalten von externen OAuth-Anwendungen.
--enabled-extensions	Kommagetrennte Liste der zu aktivierenden Erweiterungen. Siehe Verfügbare Erweiterungen.
--disabled-extensions	Kommagetrennte Liste der zu deaktivierenden Erweiterungen. Verfügbare Erweiterungen werden basierend auf erkannten Erweiterungen dynamisch aufgefüllt.
--disable-all-extensions	Deaktivieren Sie alle Erweiterungen. Diese Option schließt sich mit --enabled-extensions und --disabled-extensions gegenseitig aus.
--uia-package-version	Die Version des UI Automatisierungs-Aktivitätenpakets, das für die Migration verwendet werden soll. Standardmäßig eingestellt auf 25.10.21, wenn nicht angegeben.Die Zielversion muss höher als der Standard sein. Andernfalls wird der Standard verwendet.
--uia-fix-selector-strategy	Wenn auf true festgelegt, behebt es die SelectorStrategy Aufzählungsmehrdeutigkeit in bereits vorhandenen Ausdrücken nach der Migration. Gilt für UIAutomation-Version 25.10.29 oder höher. Standard (false)Die Ambiguität ergibt sich aus der SelectorStrategy Aufzählung, die sowohl im Namensraum UiPath.Core als auch im Namensraum UiPath.UIAutomationNext.Enums vorhanden ist. Die Verwendung des vollqualifizierten Namens behebt dieses Problem.
--uia-enable-partial-migration	Migrieren Sie Aktivitäten, auch wenn die vollständige Kompatibilität nicht garantiert werden kann. Die Migration generiert das nächstgelegene unterstützte Äquivalent, für das möglicherweise manuelle Anpassungen erforderlich sind, um korrekt zu funktionieren. Erfordert das UI Automation-Paket 25.10.38 oder höher (siehe --uia-package-version). Diese Option wird ignoriert, wenn frühere Paketversionen verwendet werden. Standard: false.
--mail-o365-package-version	Die Version des Microsoft Office 365-Aktivitätenpakets, das für die Migration verwendet werden soll. Standardmäßig ist Version 3.6.10. Die Zielversion muss höher als der Standard sein. Andernfalls wird der Standard verwendet.
--config, --mail-config	Gibt den Pfad zu einer benutzerdefinierten JSON-Konfigurationsdatei an.Die Konfiguration kann verwendet werden, um das Standardverhalten bestimmter Aktivitäten zu ändern oder Eigenschaften, die während der Migration eine Benutzereingabe erfordern, konstante Werte zuzuweisen.Weitere Informationen finden Sie unter Konfigurationsdatei.
--gsuite-package-version	Die Version des UiPath.GSuite.Activities -Aktivitätspakets, das für die Migration verwendet werden soll. Standardmäßig Version 3.8.10, wenn nicht angegeben. Die Zielversion muss eine höhere Version als die Standardversion sein. Wenn die Zielversion niedriger ist, wird die Standardversion verwendet.
--gsuite-config	Gibt den Pfad zu einer benutzerdefinierten JSON-Konfigurationsdatei an.Die Konfiguration kann verwendet werden, um das Standardverhalten bestimmter Aktivitäten zu ändern oder Eigenschaften, die während der Migration eine Benutzereingabe erfordern, konstante Werte zuzuweisen.Weitere Informationen finden Sie unter Konfigurationsdatei.
--gsuite-migrate-only	Durch Kommas getrennte Liste der Dienste, die im GSuite-Migrator enthalten sind (Groß-/Kleinschreibung beachten). Verfügbare Werte: gmail, calendar, drive, docs, sheets, appsscript. Wenn angegeben, werden nur diese Dienste ausgeführt.

Migrieren eines Projekts

Diese Option führt die eigentliche Migration eines Projekts oder von Teilen davon aus.

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

Nutzung: UiPath.Upgrade.exe upgrade [options]

Option	Beschreibung
-?, -h, --help	Zeigen Sie Hilfe- und Nutzungsinformationen an.
-p, --project-path (erforderlich)	Pfad zum Ordner, der die Datei des Projekts project.json enthält.
-o, --output-path	Ausgabepfad für das aktualisierte Projekt (optional). Wenn nicht angegeben, wird ein neuer Ordner mit dem Suffix _Upgraded erstellt.
-v, --verbose	Aktivieren Sie die ausführliche Protokollierung.
-f, --output-format	Ausgabeformat: console (Standard) oder sarif.
-e, --extension-directory	Verzeichnis zum Suchen nach Erweiterungen. Nur für erweiterte Verwendung.
--ignore-missing-dependencies	Ignorieren Sie fehlende Abhängigkeiten während des Upgrades. Fehlende Abhängigkeiten werden als Warnungen angezeigt. Betroffene Workflows melden möglicherweise fehlende Typen, können nicht kompiliert werden oder können andere erforderliche Migrationen nicht ausführen.
--orchestrator-url	Die vollständige Orchestrator-URL, einschließlich des Organisationsnamens. Wenn nicht angegeben, wird die Verbindung aus Studio verwendet.Wenn angegeben, sind Anmeldeinformationen erforderlich.
--orchestrator-tenant	Der Orchestrator-Mandantenname. Standardmäßig eingestellt auf DefaultTenant, wenn nicht angegeben.
--orchestrator-pat	Personal Access Token (PAT) für die Orchestrator-Authentifizierung. Erfordert den OR.Execution.Read Scope.
--orchestrator-application-id	OAuth-Anwendungs-ID für die Orchestrator-Authentifizierung (Alternative zu PAT).
--orchestrator-application-secret	OAuth-Anwendungsgeheimnis (Alternative zu PAT).
--enabled-extensions	Kommagetrennte Liste der zu aktivierenden Erweiterungen. Siehe Verfügbare Erweiterungen.
--disabled-extensions	Kommagetrennte Liste der zu deaktivierenden Erweiterungen. Verfügbare Erweiterungen werden basierend auf erkannten Erweiterungen dynamisch aufgefüllt.
--disable-all-extensions	Deaktivieren Sie alle Erweiterungen. Schließen sich gegenseitig mit --enabled-extensions und --disabled-extensions aus.
--uia-package-version	Zielpaketversion UiPath.UIAutomation.Activities. Standardmäßig auf 25.10.21.
--uia-fix-selector-strategy	Wenn auf true festgelegt, behebt es die SelectorStrategy Aufzählungsmehrdeutigkeit in bereits vorhandenen Ausdrücken nach der Migration. Gilt für UIAutomation-Version 25.10.29 oder höher. Standard (false)Die Ambiguität ergibt sich aus der SelectorStrategy Aufzählung, die sowohl im Namensraum UiPath.Core als auch im Namensraum UiPath.UIAutomationNext.Enums vorhanden ist. Die Verwendung des vollqualifizierten Namens behebt dieses Problem.
--uia-enable-partial-migration	Migrieren Sie Aktivitäten, auch wenn die vollständige Kompatibilität nicht garantiert werden kann. Die Migration generiert das nächstgelegene unterstützte Äquivalent, für das möglicherweise manuelle Anpassungen erforderlich sind, um korrekt zu funktionieren. Erfordert das UI Automation-Paket 25.10.38 oder höher (siehe --uia-package-version). Diese Option wird ignoriert, wenn frühere Paketversionen verwendet werden. Standard: false.
--mail-o365-package-version	Die Version des Microsoft Office 365-Aktivitätenpakets, das für die Migration verwendet werden soll. Standardmäßig ist Version 3.6.10. Die Zielversion muss höher als der Standard sein. Andernfalls wird der Standard verwendet.
--config, --mail-config	Gibt den Pfad zu einer benutzerdefinierten JSON-Konfigurationsdatei an.Die Konfiguration kann verwendet werden, um das Standardverhalten bestimmter Aktivitäten zu ändern oder Eigenschaften, die während der Migration eine Benutzereingabe erfordern, konstante Werte zuzuweisen.Weitere Informationen finden Sie unter Konfigurationsdatei.
--gsuite-package-version	Die Version des UiPath.GSuite.Activities -Aktivitätspakets, das für die Migration verwendet werden soll. Standardmäßig Version 3.8.10, wenn nicht angegeben. Die Zielversion muss eine höhere Version als die Standardversion sein. Wenn die Zielversion niedriger ist, wird die Standardversion verwendet.
--gsuite-config	Gibt den Pfad zu einer benutzerdefinierten JSON-Konfigurationsdatei an.Die Konfiguration kann verwendet werden, um das Standardverhalten bestimmter Aktivitäten zu ändern oder Eigenschaften, die während der Migration eine Benutzereingabe erfordern, konstante Werte zuzuweisen.Weitere Informationen finden Sie unter Konfigurationsdatei.
--gsuite-migrate-only	Durch Kommas getrennte Liste der Dienste, die im GSuite-Migrator enthalten sind (Groß-/Kleinschreibung beachten). Verfügbare Werte: gmail, calendar, drive, docs, sheets, appsscript. Wenn angegeben, werden nur diese Dienste ausgeführt.

Massen-Repository-Migration

Diese Option analysiert oder migriert alle in einer Ordnerhierarchie gefundenen Projekte.

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

Nutzung: UiPath.Upgrade.exe bulk [options]

Option	Beschreibung
-?, -h, --help	Zeigen Sie Hilfe- und Nutzungsinformationen an.
-p, --path (erforderlich)	Pfad zum Repository oder Ordner. Die Migration wird für alle Unterordner ausgeführt, die eine project.json Datei enthalten.
-c, --command (erforderlich)	Auszuführender Befehl: analyze oder upgrade.
-v, --verbose	Aktivieren Sie die ausführliche Protokollierung.
-o, --output-path	Ausgabestammpfad für aktualisierte Projekte. Dieser Ordner wird erstellt, wenn er nicht vorhanden ist.Für das aktualisierte Projekt wird ein neuer Ordner mit dem Suffix _Upgraded erstellt.
--orchestrator-url	Die vollständige Orchestrator-URL, einschließlich des Organisationsnamens.
--orchestrator-tenant	Der Orchestrator-Mandantenname. Standardmäßig eingestellt auf DefaultTenant, wenn nicht angegeben.
--orchestrator-pat	Personal Access Token (PAT) für die Orchestrator-Authentifizierung. Erfordert den OR.Execution.Read Scope.
--orchestrator-application-id	OAuth-Anwendungs-ID für die Orchestrator-Authentifizierung (Alternative zu PAT).
--orchestrator-application-secret	OAuth-Anwendungsgeheimnis (Alternative zu PAT).
--enabled-extensions	Kommagetrennte Liste der zu aktivierenden Erweiterungen. Siehe Verfügbare Erweiterungen.
--disabled-extensions	Kommagetrennte Liste der zu deaktivierenden Erweiterungen. Verfügbare Erweiterungen werden basierend auf erkannten Erweiterungen dynamisch aufgefüllt.
--disable-all-extensions	Deaktivieren Sie alle Erweiterungen. Schließen sich gegenseitig mit --enabled-extensions und --disabled-extensions aus.

Beispiele

Analysieren eines einzelnen Projekts mit ausführlicher Ausgabe:

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

Migrieren Sie ein Projekt und geben Sie eine UI Automatisierungs-Zielpaketversion an:

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

Migrieren eines Projekts mit einer benutzerdefinierten Verbindungskonfiguration:

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

Massenanalyse für einen Ordner ausführen:

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

Migrieren Sie nur die klassischen E-Mail- und GSuite-Aktivitäten im Projekt, ohne andere Aktivitäten zu beeinträchtigen, z. B. die klassischen UI-Automatisierungsaktivitäten:

UiPath.Upgrade.exe upgrade --project-path="C:\To Migrate\LegacyProcess" --enabled-extensions=MailActivities,GSuiteActivities

Migrieren Sie nur das Legacy-Projekt zu Windows (genauso wie Studio Windows – Legacy-Konverter). Der Befehl migriert keine der unterstützten Aktivitätstypen:

UiPath.Upgrade.exe upgrade -p "C:\To Migrate\LegacyProcess" -o "C:\To Migrate\WindowsProcess" --disable-all-extensions

Hinweis:

• Die Befehlszeilenoptionen verwenden die folgenden Konventionen:
  • Kurze Optionen (z. B. -p value) müssen ein Leerzeichen verwenden, um die Option von ihrem Wert zu trennen.
  • Lange Optionen (z. B. --project-path=value) verwenden in der Regel das Gleichheitszeichen, um den Wert explizit an das spezifische Flag zu binden. In den meisten Fällen können lange Optionen auch mithilfe eines Leerzeichens angegeben werden (z. B. --project-path value). Die --config Option ist eine Ausnahme und unterstützt nur die Syntax des Gleichheitszeichens (z. B. --config=value).
• Die Standardausgabe des upgrade Befehls ist ein SARIF-Bericht, der im Originalprojekt unter einem .upgrade Ordner gespeichert ist. Das migrierte Projekt wird im Ausgabepfad gespeichert.

Unterstützte Syntax für Sammlungen

Mehrere CLI-Optionen akzeptieren Sammlungswerte: --enabled-extensions, --disabled-extensions und --gsuite-migrate-only. Jede unterstützt mehrere Syntaxen zum Angeben von Werten.

Unterstützte Formate

Alle diese Elemente binden beispielsweise dieselben Werte an die Sammlung ["drive", "gmail"]:

• Durch Kommas getrennt: --gsuite-migrate-only=drive,gmail oder --gsuite-migrate-only=drive --gsuite-migrate-only=gmail
• Durch Leerzeichen getrennt: --gsuite-migrate-only drive,gmail oder --gsuite-migrate-only drive --gsuite-migrate-only gmail
• Doppelpunktsyntax (weniger häufig): --gsuite-migrate-only:drive,gmail
• Gemischte Syntax: --gsuite-migrate-only=drive --gsuite-migrate-only gmail

Standardverhalten

Wenn die Option im Befehl fehlt:

• --gsuite-migrate-only – Migriert alle Google Workspace-Dienste
• --enabled-extensions - Alle Erweiterungen sind aktiviert
• --disabled-extensions– Es sind keine Erweiterungen deaktiviert

Hinweis:

Das Angeben eines Vorkommens ohne Werte (z. B. --gsuite-migrate-only "") wird vom Validierer abgelehnt.

Verfügbare Erweiterungen

Die folgenden Erweiterungen können für die Option --enabled-extensions oder --disabled-extensions angegeben werden:

Erweiterung	Beschreibung
UiAutomationActivities	Migriert klassische UI-Automatisierungsaktivitäten im UiPath.UIAutomation.Activities -Paket zu modernen UI-Automatisierungsaktivitäten.
MailActivities	Migriert Abhängigkeiten von UiPath.Mail.Activities (klassische Outlook-basierte Aktivitäten) zu UiPath.MicrosoftOffice365.Activities (Integration Service-basierte Aktivitäten).
MicrosoftActivitiesExtension	Versucht, Aktivitäten aus dem Paket Microsoft.Activities.Extensions zu konvertieren, das nur mit.NET Framework (Legacy) funktioniert.
GSuiteActivities	Migriert klassische GSuite-Aktivitäten im UiPath.GSuite.Activities -Paket zu modernen Aktivitäten innerhalb desselben Pakets.

Beispiel: --enabled-extensions MailActivities,GSuiteActivities.

Standardmäßig sind alle Erweiterungen aktiviert. Wenn die Option --enabled-extensions nicht angegeben ist, verarbeiten die Befehle analyze, upgrade und bulk alle Aktivitäten in unterstützten Paketen.

Konfigurationsdatei

Verwenden Sie eine Konfigurationsdatei, um konstante Werte für Aktivitätseigenschaften festzulegen, die während der Migration manuelle Eingabe erfordern, oder um das Standard-Migrationsverhalten zu überschreiben.

Übergeben Sie den Dateipfad an den Migrator mithilfe der Option --config mit dem Zuweisungsoperator =, wie in diesem Beispiel: --config=C:\to-migrate\connection.json. Sie müssen je nach Migrationstyp die entsprechende Konfigurationsoption verwenden:

• Für die Migration von Outlook Mail-Aktivitäten: --config oder --mail-config
• Für die Migration von klassischen GSuite-Aktivitäten: --gsuite-config

Die Konfigurationsdatei muss diesem Format entsprechen:

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

Spezielle Hinweise

• Nur {property-name}, das zugewiesen werden kann, ist ConnectionId.
• * fungiert als Platzhalter und entspricht einem beliebigen Wert in {path-to-workflow}, {connector-type} und {activity-display-name}. Somit können mehrere Workflows oder Aktivitäten für dieselbe Sammlung von Eigenschaften angegeben werden. Wenn mehrere Einträge mit demselben Workflow, derselben Aktivität und demselben Connector-Tutorial übereinstimmen, wird nur die letzte Übereinstimmung angewendet.
• Der Teil [{connector-type}] ist optional. Wenn er weggelassen wird, entspricht der Eintrag jeder Aktivität unabhängig vom Connectortyp. Wenn angegeben, stimmt der Eintrag nur mit Aktivitäten überein, die an diesen Connector gebunden sind. Von den Optionen [{connector-type}] und {activity-display-name} muss mindestens eine vorhanden sein.

Reservierte Konfigurationsschlüssel

{reserved-configuration-key} stellt aktivitätsspezifische Verhaltensänderungen dar:

• SaveOutlookMailMessage_IgnoreSaveAsType: Wenn auf true festgelegt, deaktiviert die Option Save as type bei nicht unterstützten Typen.Die Aktivität kann somit unabhängig von Save as type option migriert werden.

Verfügbare Connector-Typen

Folgende Connector-Typen können mit dem Muster [{connector-type}] verwendet werden:

Google (GSuite)-Connectors:

• uipath-google-drive: Google Drive-Connector
• uipath-google-docs: Google Docs-Connector
• uipath-google-sheets: Google Spreadsheets-Connector
• uipath-google-gmail: Gmail-Connector
• uipath-google-workspace: Google Workspace-Connector
• uipath-google-tasks: Google Tasks-Connector
• uipath-google-forms: Google Formulare-Connector

Microsoft-Connectors:

• uipath-microsoft-outlook365: Microsoft Outlook 365 Graph-Connector
• uipath-microsoft-outlook365ews: Microsoft Outlook 365 EWS-Connector (Exchange Web Services).
• uipath-microsoft-onedrive: Microsoft OneDrive-Connector
• uipath-microsoft-365: Microsoft Office 365-Connector
• uipath-mail-mail: E-Mail-Connector

Abrufen der Verbindungs-ID aus Orchestrator

Ab März 2026 wurden Verbindungen von Integration Service zu Orchestrator verlagert. Sie können ConnectionId direkt von der Verbindungs-URL in Orchestrator abrufen:

1. Navigieren Sie zu Ihrer Verbindung in Orchestrator: Gehen Sie zum Orchestrator-Ordner, in dem sich Ihre Microsoft Outlook 365-Verbindung befindet.
2. Öffnen Sie die Verbindung: Wählen Sie die Verbindung aus, um ihre Details anzuzeigen.
3. Aktivieren Sie die URL: ConnectionId ist in der Browser-URL im folgenden Format sichtbar: https://cloud.uipath.com/{OrganizationName}/{TenantName}/orchestrator_/connections/{ConnectionId}/edit/tid={TId}.

Ergebnis

Die Verbindungs-ID ist in der Browser-URL im Format .../connections/{ConnectionId}/edit/tid={TId} sichtbar.

Festlegen von Verbindungs-IDs für E-Mail-Aktivitäten

Die Eigenschaft ConnectionId wird während der Migration nicht automatisch aufgefüllt. Sie müssen es manuell pro Workflow/Aktivität mithilfe einer Konfigurationsdatei festlegen. Die Konfigurationsdatei kann mit dem Befehlszeilenargument --config <config> oder --mail-config <config> an den Activity Migrator übergeben werden.

Im folgenden Beispiel werden bestimmten Produktivitätsaktivitäten (Microsoft Office 365) unterschiedliche Verbindungs-IDs mithilfe eines Platzhalter-Fallbacks zugewiesen:

{
    "* > *": {
        "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 diesem Beispiel:

• * > * stimmt mit allen Aktivitäten überein und dient als Fallback, wenn unten keine übereinstimmenden Einträge vorhanden sind.
• *\\Projects\\MailMigration\\Main.xaml > Get * stimmt mit jeder Aktivität überein, deren Anzeigename mit Get in Main.xaml beginnt.
• *\\Projects\\MailMigration\\* > Send Mail stimmt mit der Send Mail Aktivität über alle Workflows im Ordner MailMigration hinweg überein.

{
    "* > *": {
        "ConnectionId": "00000000-0000-0000-0000-000000000001"
    },
    "* > [uipath-microsoft-outlook365] *": {
        "ConnectionId": "00000000-0000-0000-0000-000000000002"
    },
    "*\\Projects\\MailMigration\\Main.xaml > [uipath-microsoft-outlook365] Get *": {
        "ConnectionId": "00000000-0000-0000-0000-000000000003"
    }
}

In diesem Beispiel:

• * > * stimmt mit allen Aktivitäten überein und dient als Fallback, wenn unten keine übereinstimmenden Einträge vorhanden sind.
• * > [uipath-microsoft-outlook365] * Überschreibungen für alle Outlook-Aktivitäten.
• *\\Projects\\MailMigration\\Main.xaml > [uipath-microsoft-outlook365] Get * wird weiter auf Get * Aktivitäten in einem bestimmten Workflow eingeschränkt.

Festlegen von Verbindungs-IDs für GSuite-Aktivitäten

Die modernen Connection-Service-Aktivitäten erfordern ein ConnectionId, das der Migrator im Allgemeinen nicht ableiten kann. Zwei Fälle:

1. Innerhalb eines OAuth GSuiteApplicationScope – die Aktivität erbt die Verbindung des Scope zur Laufzeit, sodass ConnectionId leer bleibt (UseConnectionService wird für die Aktivität auf false festgelegt).
2. Außerhalb eines Scope, ODER nachdem ein Verbindungsservice-Scope während der Migration auf einen Sequence entpackt wurde – benötigt die Aktivität eine explizite ConnectionId. Der Migrator kann keines generieren, da die Studio-Laufzeit und nicht der Migrator den Lebenszyklus der IS-Verbindung besitzt.

Um die Blockierung in diesem Fall aufzuheben, akzeptiert der Migrator eine JSON-Konfigurationsdatei (--gsuite-config <path>), die Aktivitätsinstanzen deklarativ zu ConnectionId -Werten zuordnet. Der gleiche Mechanismus wird von Mail (--mail-config, Alias --config) verwendet.

{
  "{path-to-workflow} > [{connector-type}] {activity-display-name}": {
    "ConnectionId": "00000000-0000-0000-0000-000000000001"
  }
}

Im obigen Schema ist jede Regel ein Glob über drei Koordinaten:

• {path-to-workflow} – Der Workflow-Dateipfad (Windows-Trennzeichen normalisiert). * ist ein Platzhalter.
• [{connector-type}] – optional. Der an die moderne Aktivität gebundene IS-Connectorschlüssel (z. B. uipath-google-drive, uipath-google-gmail). Wenn sie weggelassen wird, entspricht die Regel einem beliebigen Connector.
• {activity-display-name} – Der Anzeigename der migrierten Aktivität. * ist ein Platzhalter.

Wenn mehrere Regeln mit demselben Workflow + Aktivität + Connector-Tutorial übereinstimmen, gewinnt die letzte Übereinstimmung pro Eigenschaft und die von einer früheren Übereinstimmung festgelegten Eigenschaften werden beibehalten, wenn sie nicht überschrieben werden – so dass es einfach ist, einen globalen Standard mit Überschreibungen pro Aktivität zu überschreiben:

{
  "* > *": {
    "ConnectionId": "00000000-0000-0000-0000-000000000001"
  },
  "* > [uipath-google-drive] *": {
    "ConnectionId": "00000000-0000-0000-0000-000000000002"
  },
  "*\\Projects\\Demo\\Main.xaml > [uipath-google-drive] Get *": {
    "ConnectionId": "00000000-0000-0000-0000-000000000003"
  },
  "* > [uipath-google-sheets] *": {
    "ConnectionId": "00000000-0000-0000-0000-000000000004"
  },
  "* > [uipath-google-docs] *": {
    "ConnectionId": "00000000-0000-0000-0000-000000000005"
  },
  "* > [uipath-google-gmail] *": {
    "ConnectionId": "00000000-0000-0000-0000-000000000006"
  }
}

Im obigen Beispiel werden auch verschiedene Verbindungs-IDs für verschiedene Google Workspace-Dienste (Drive, Sheets, Docs, Gmail) konfiguriert.

ConnectionId ist die einzige Eigenschaft, die die Konfiguration ausfüllen kann. Wenn eine ConnectionId erforderlich ist, aber keine Regel übereinstimmt, gibt der Migrator eine Aktion erforderlich aus, die den Benutzer zurück zur Konfigurationsdatei verweist.

Verhalten des UI Automatisierungs-Anwendungs-Scopes nach der Migration

Die meisten modernen UI-Automatisierungs-Aktivitäten erfordern einen Anwendungs-Scope (Aktivität Anwendung/Browser verwenden). Während der Migration werden zwei Arten von Scopes erstellt:

Organisch erstellte Scopes

Diese Scopes werden automatisch generiert, wenn klassische Scope-Aktivitäten wie „Browser öffnen“ und „Browser anhängen“ migriert werden. Diese Scopes sind nicht optimiert, um eine Änderung der ursprünglichen Absicht und des Ablaufs des migrierten Workflows zu vermeiden.

Synthetisch generierte Scopes

Diese Scopes werden generiert, um sicherzustellen, dass der Workflow nach der Migration korrekt kompiliert und läuft. Wenn zwei aufeinanderfolgende Scopes identische Eigenschaften haben (z. B. denselben Selektor oder dieselbe OCR-Engine), werden sie zu einem einzigen Scope zusammengeführt, wobei die ursprüngliche Reihenfolge der Aktivität erhalten bleibt.

Einschränkungen

UIAutomation-Aktivitäten

• Die mindestens unterstützte Zielversion von UiPath.UIAutomation.Activities ist 25.10.21.
• Einige Aktivitätseigenschaften haben Migrationsbeschränkungen. Siehe die Listen der unterstützten Aktivitäten:
  • Unterstützte UI Automation-Aktivitäten
  • Nicht unterstützte Aktivitäten von UI Automation
• Migrierte Workflows mit modernen UI Automatisierungs-Aktivitäten werden möglicherweise langsamer ausgeführt als die ursprünglichen Workflows, die klassische UI Automatisierungs-Aktivitäten verwenden.

Produktivitätsaktivitäten

• Die mindestens unterstützte Zielversion von UiPath.MicrosoftOffice365.Activities ist 3.6.10.
• Siehe die Listen der unterstützten Aktivitäten:
  • Von Mail unterstützte Aktivitäten
  • Nicht unterstützte Mail-Aktivitäten

Tool-Einschränkungen

• Standardmäßig verwendet das Aktivitäts-Migrator-Tool NuGet-Feeds, die in NuGet.config: Offiziell, Lokal und Marketplace konfiguriert sind. Um Orchestrator-Bibliotheksfeeds einzubeziehen, verwenden Sie für die Befehle analyze, upgrade, und bulk die Optionen --orchestrator-url, --orchestrator-tenant, --orchestrator-pat, --orchestrator-application-id, und --orchestrator-application-secret.
• Aktivitäten, die dynamisch generierte Typen oder Assemblies verwenden (z. B. können einige Excel-Aktivitäten Spaltennamen als Eigenschaften in einem dynamisch generierten Typ haben), können nach der Migration einen „Typ nicht gefunden“-Fehler in .xaml Dateien verursachen.

Studio Workflow-Analyse-Regel

• Die Workflow-Analyse-Regel ST-AMG-001 ist ab Studio 2024.10.25 LTS, Studio 2025.10.8 verfügbar LTS und Studio 2026.0.189 STS.

Bewährte Methoden für die Migration

Vor der Migration

1. Sichern Sie Ihre Projekte: Erstellen Sie immer eine vollständige Sicherung, bevor Sie Migrationsbefehle ausführen.
2. Aktualisieren Sie Studio- und Aktivitätspakete: Verwenden Sie die neueste Version von UiPath Studio und stellen Sie sicher, dass Zielpaketversionen die Mindestanforderungen erfüllen (UiPath.UIAutomation.Activities >= 25.10.21 und UiPath.MicrosoftOffice365.Activities >= 3.6.10).
3. Analysieren vor dem Upgrade: Führen Sie zuerst den analyze Befehl aus. Verwenden Sie UiPath.Upgrade.exe analyze -p -v, um einen SARIF-Bericht zu generieren und potenzielle Probleme zu identifizieren, ohne das Projekt zu ändern.
4. Abhängigkeiten und NuGet-Feeds überprüfen: Bestätigen Sie, dass die Feeds Offiziell, Lokal und Marketplace korrekt konfiguriert sind in NuGet.config.
5. Migrieren Sie zuerst die Bibliotheken, wenn ein Projekt von Bibliotheksprojekten abhängt: Migrieren Sie erst dann die Projekte, die sie verbrauchen.

Während der Migration

5. Beginnen Sie mit einem einzigen Projekt: Testen Sie die Migration in einem Projekt unter Verwendung von UiPath.Upgrade.exe upgrade -p -v, bevor Sie einen Massenvorgang ausführen.
6. Massenmigration für mehrere Projekte verwenden: Nach der Validierung führen Sie die Option UiPath.Upgrade.exe bulk -p -v aus.Stellen Sie sicher, dass die Ordnerstruktur sauber und konsistent ist.
7. Geben Sie eine Konfigurationsdatei für Verbindungs-IDs an: Erstellen Sie für Microsoft 365- oder GSuite-Aktivitäten eine Konfigurationsdatei mit den erforderlichen ConnectionId Werten und übergeben Sie sie mit --config:

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

Nach der Migration

8. Überprüfen Sie den SARIF-Bericht: Prüfen Sie den Ordner .upgrade im Projektverzeichnis und beheben Sie alle gekennzeichneten Probleme.
9. Öffnen Sie das migrierte Projekt in Studio und führen Sie „Projekt analysieren“ aus: Überprüfen Sie die Ergebnisse der Workflow-Analyse-Regel ST-AMG-001 (verfügbar in Studio 2025.10.8langfristiger Support Studio 2026.0.189STS oder höher), um Aktivitäten zu identifizieren, die Aktionen nach der Migration erfordern.
10. Anwendungs-Scopes validieren: Bestätigen Sie, dass sich zusammengeführte Scopes wie erwartet verhalten. Testen Sie Workflows mit Verwenden von Anwendung/Browser-Aktivitäten.
11. End-to-End-Tests ausführen: Führen Sie migrierte Workflows in einer kontrollierten Umgebung aus, bevor Sie sie in der Produktion anwenden.

Leistung und Wartung

12. Optimieren von UI Automatisierungs-Selektoren: Überprüfen Sie nach der Migration die Selektoren auf Genauigkeit und Stabilität.
13. Ausführungszeit überwachen: Moderne Aktivitäten laufen möglicherweise zu Beginn langsamer. Optimieren Sie, wenn nötig.
14. Dokumentieren Sie Ihre Änderungen: Erstellen Sie Aufzeichnungen über migrierte Projekte, Zielversionen und angewendete Konfigurationen zu Prüfungs- und Rollback-Zwecken.