Acerca de la herramienta Migrador de actividades

Migre los proyectos de automatización heredados a la plataforma moderna de UiPath utilizando la herramienta CLI de Activity Migrator.

Propósito del Migrador de actividades

El migrador de actividades es una herramienta esencial de interfaz de línea de comandos (CLI) para las organizaciones que hacen la transición de proyectos de automatización heredados a la moderna UiPath Platform, lo que permite el acceso a las características y capacidades más recientes:

• Automatiza el proceso de migración simplificando y agilizando la transferencia de la configuración y las dependencias del proceso.
• Reduce el esfuerzo manual y los errores garantizando la coherencia y la precisión durante la migración, en lugar de transferir dependencias y actividades manualmente.

Escenarios de migración admitidos

Migración del marco del proyecto

Se recomienda encarecidamente migrar un proyecto de Windows: heredado a la compatibilidad de Windows por diversos motivos estratégicos, técnicos y relacionados con el soporte:

1. Rendimiento mejorado: los proyectos de Windows se ejecutan más rápido y de forma más eficiente debido a una mejor integración con .NET Core y las API modernas de Windows.
2. Mejor compatibilidad con bibliotecas externas: los proyectos de Windows admiten versiones más recientes de bibliotecas y dependencias, lo que facilita la integración con sistemas externos.

Acceso a capacidades modernas de UI Automation

Muchas características nuevas de UI Automation, como Unified Target y Healing Agent, solo son compatibles con el marco moderno de UI Automation. Por lo tanto, es necesario migrar desde las actividades clásicas de UI Automation a la experiencia moderna.

Migración de actividades obsoletas de Outlook

Microsoft está cancelando Outlook clásico y fomentando la adopción de Microsoft 365. Como Resultado, el Migrador de actividades permite hacer la transición de dependencias de automatización desde UiPath.Mail.Activities (que depende de la API clásica de Outlook) a UiPath.MicrosoftOffice365.Activities que se basa en UiPath Integration Service.

Migración de actividades de GSuite

Para beneficiarse de las últimas mejoras, recomendamos utilizar las actividades de Google Workspace basadas en conexiones de Integration Service. El Migrador de actividades admite la conversión de actividades clásicas en actividades modernas dentro del mismo paquete UiPath.GSuite.Activities. Estas actividades modernas se automatizan en las aplicaciones de Google Workspace (anteriormente conocido como GSuite), y abarcan seis servicios: Gmail, Calendario, Drive, Documentos, Hojas de cálculo y Apps Script.

Migrador de actividad frente al convertidor de Studio Windows: heredado

Usa el conversor de Studio Windows: heredado cuando:

• Solo necesitas convertir los proyectos de Windows: heredado a Windows uno por uno.
• No se requieren migraciones de actividades.

Usa el migrador de actividades cuando:

• Quieres convertir varios proyectos de Windows: heredado a Windows (admite conversión en masa).
• Se necesita la migración de las actividades de Automatización de IU, Correo o GSuite clásico .
• Se aplica cualquier combinación de los escenarios anteriores.

Dónde obtener el Migrador de actividades

Sigue los pasos a continuación para descargar la herramienta:

1. Ve a UiPath Automation Cloud.
2. Selecciona el botón Ayuda en la esquina superior derecha.
3. En Recursos, selecciona Descargas.
4. En la lista Descarga destacada , selecciona Herramienta de migración de actividades.
5. Selecciona el enlace de descarga.

Resultado

El archivo Migrador de actividades .zip se descarga en tu máquina. Extráelo e instala la herramienta en la carpeta <tool-install-dir> antes de ejecutar cualquier comando.

Requisitos

• Si la herramienta se utiliza en una máquina en la que Studio no está instalado, instala .NET Desktop Runtime 8.0.
• Abre proyectos migrados con las versiones 2024.10 o posteriores de Studio.

Cómo utilizar el Migrador de actividades

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

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

Opciones globales

Opción	Descripción
-?, -h, --help	Muestra la información de ayuda y uso.

Comandos disponibles

Comando	Descripción
version	Mostrar información de la versión.
analyze	Analiza un proyecto para migrarlo sin realizar cambios.
upgrade	Migra un proyecto o partes del mismo.
bulk	Analiza o migra todos los proyectos de una carpeta.

Analizar un proyecto

Esta opción simula la migración y genera un informe sin realizar la migración real ni modificar el proyecto.

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

Uso: UiPath.Upgrade.exe analyze [options]

Opción	Descripción
-?, -h, --help	Muestra la información de ayuda y uso.
-p, --project-path (obligatorio)	Ruta al proyecto que analizar o actualizar. La carpeta proporcionada como <project-path> debe contener el archivo project.json del proyecto.
-o, --output-path	Ruta de salida para el proyecto actualizado (opcional). Si no se especifica, se crea una nueva carpeta con el sufijo _Upgraded.
-v, --verbose	Habilitar el registro verbose.
-f, --output-format	Formato de salida: console (predeterminado) o sarif.
-e, --extension-directory	Directorio en el que buscar extensiones. Solo para uso avanzado.
--ignore-missing-dependencies	Ignora las dependencias que faltan durante la actualización. Las dependencias que faltan aparecen como advertencias. Los flujos de trabajo afectados pueden informar de que faltan tipos, dar error al compilar o dar error al realizar otras migraciones necesarias.
--orchestrator-url	La URL completa de Orchestrator, incluido el nombre de la organización (por ejemplo, https://cloud.uipath.com/myorg). Si no se especifica, se utiliza la conexión de Studio. Cuando se especifica, también debes proporcionar credenciales a través del Token de acceso personal (PAT) utilizando --orchestrator-pat o el ID de aplicación y el secreto externos utilizando --orchestrator-application-id y --orchestrator-application-secret.
--orchestrator-tenant	El nombre del tenant de Orchestrator. El valor predeterminado es DefaultTenant si no se especifica.
--orchestrator-pat	Token de acceso personal (PAT) para la autenticación de Orchestrator, que se utiliza para acceder a las fuentes de la biblioteca de Orchestrator. Crea un token de acceso personal y añade un ámbito de acceso a la API de Orchestrator OR.Execution.Read. Consulta Tokens de acceso personal.Como alternativa, configura un ID de aplicación y un secreto utilizando --orchestrator-application-id y --orchestrator-application-secret.
--orchestrator-application-id	ID de aplicación de OAuth para la autenticación de Orchestrator (alternativa a PAT). Úsala con --orchestrator-application-secret. Consulta Gestionar aplicaciones de OAuth externas.
--orchestrator-application-secret	Secreto de aplicación OAuth para la autenticación de Orchestrator (alternativa a PAT). Úsala con --orchestrator-application-id. Consulta Gestionar aplicaciones de OAuth externas.
--enabled-extensions	Lista de extensiones separadas por comas para habilitar. Consulta Extensiones disponibles.
--disabled-extensions	Lista separada por comas de extensiones que deshabilitar. Las extensiones disponibles se rellenan dinámicamente en función de las extensiones descubiertas.
--disable-all-extensions	Deshabilita todas las extensiones. Esta opción es mutuamente excluyente con --enabled-extensions y --disabled-extensions.
--uia-package-version	La versión del paquete de actividades de UI Automation que se utilizará para la migración. El valor predeterminado es 25.10.21 si no se especifica. La versión de destino debe ser superior a la predeterminada. Si no es así, se utiliza la predeterminada.
--uia-fix-selector-strategy	Cuando se establece en true, corrige la ambigüedad de la enumeración SelectorStrategy en expresiones preexistentes después de la migración. Se aplica a la versión 25.10.29 de UIAutomation o posteriores. Predeterminado: false. La ambigüedad resulta de la enumeración SelectorStrategy existente tanto en el UiPath.Core como en los espacios de nombres UiPath.UIAutomationNext.Enums. El uso del nombre completamente cualificado resuelve esta incidencia.
--uia-enable-partial-migration	Migrar actividades incluso cuando no se pueda garantizar la compatibilidad total. La migración genera el equivalente compatible más cercano, que puede requerir ajustes manuales para funcionar correctamente. Requiere el paquete Automatización de IU 25.10.38 o posterior (ver --uia-package-version). Esta opción se ignora cuando se utilizan versiones de paquete anteriores. Predeterminado: false.
--mail-o365-package-version	La versión del paquete de actividades de Microsoft Office 365 que se utilizará en la migración. El valor predeterminado es la versión 3.6.10. La versión de destino debe ser superior a la predeterminada. Si no es así, se utiliza la predeterminada.
--config, --mail-config	Especifica la ruta a un Archivo JSON de configuración personalizado. La configuración puede utilizarse para modificar el comportamiento predeterminado de ciertas actividades o asignar valores constantes a propiedades que requieren la entrada del usuario durante la migración. Consulta Archivo de Configuración.
--gsuite-package-version	La versión del paquete de actividades UiPath.GSuite.Activities que se utilizará para la migración. El valor predeterminado es la versión 3.8.10 si no se especifica. La versión de destino debe ser superior a la versión predeterminada. Si la versión de destino es inferior, se utilizará la versión predeterminada.
--gsuite-config	Especifica la ruta a un Archivo JSON de configuración personalizado. La configuración puede utilizarse para modificar el comportamiento predeterminado de ciertas actividades o asignar valores constantes a propiedades que requieren la entrada del usuario durante la migración. Consulta Archivo de Configuración.
--gsuite-migrate-only	Lista separada por comas de servicios incluidos en el migrador de GSuite (distingue mayúsculas de minúsculas). Valores disponibles: gmail, calendar, drive, docs, sheets, appsscript. Si se especifica, solo se ejecutarán esos servicios.

Migrar un proyecto

Esta opción realiza la migración real de un proyecto o de partes del mismo.

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

Uso: UiPath.Upgrade.exe upgrade [options]

Opción	Descripción
-?, -h, --help	Muestra la información de ayuda y uso.
-p, --project-path (obligatorio)	Ruta a la carpeta que contiene el archivo project.json del proyecto.
-o, --output-path	Ruta de salida para el proyecto actualizado (opcional). Si no se especifica, se crea una nueva carpeta con el sufijo _Upgraded.
-v, --verbose	Habilitar el registro verbose.
-f, --output-format	Formato de salida: console (predeterminado) o sarif.
-e, --extension-directory	Directorio en el que buscar extensiones. Solo para uso avanzado.
--ignore-missing-dependencies	Ignora las dependencias que faltan durante la actualización. Las dependencias que faltan aparecen como advertencias. Los flujos de trabajo afectados pueden informar de que faltan tipos, dar error al compilar o dar error al realizar otras migraciones necesarias.
--orchestrator-url	La URL completa de Orchestrator, incluido el nombre de la organización. Si no se especifica, se utiliza la conexión de Studio. Cuando se especifica, se requieren credenciales.
--orchestrator-tenant	El nombre del tenant de Orchestrator. El valor predeterminado es DefaultTenant si no se especifica.
--orchestrator-pat	Token de acceso personal (PAT) para la autenticación de Orchestrator. Requiere el ámbito OR.Execution.Read.
--orchestrator-application-id	ID de aplicación de OAuth para la autenticación de Orchestrator (alternativa a PAT).
--orchestrator-application-secret	Secreto de aplicación OAuth (alternativa a PAT).
--enabled-extensions	Lista de extensiones separadas por comas para habilitar. Consulta Extensiones disponibles.
--disabled-extensions	Lista separada por comas de extensiones que deshabilitar. Las extensiones disponibles se rellenan dinámicamente en función de las extensiones descubiertas.
--disable-all-extensions	Deshabilita todas las extensiones. Mutuamente excluyentes con --enabled-extensions y --disabled-extensions.
--uia-package-version	Versión del paquete de destino UiPath.UIAutomation.Activities. Es 25.10.21 de forma predeterminada.
--uia-fix-selector-strategy	Cuando se establece en true, corrige la ambigüedad de la enumeración SelectorStrategy en expresiones preexistentes después de la migración. Se aplica a la versión 25.10.29 de UIAutomation o posteriores. Predeterminado: false. La ambigüedad resulta de la enumeración SelectorStrategy existente tanto en el UiPath.Core como en los espacios de nombres UiPath.UIAutomationNext.Enums. El uso del nombre completamente cualificado resuelve esta incidencia.
--uia-enable-partial-migration	Migrar actividades incluso cuando no se pueda garantizar la compatibilidad total. La migración genera el equivalente compatible más cercano, que puede requerir ajustes manuales para funcionar correctamente. Requiere el paquete Automatización de IU 25.10.38 o posterior (ver --uia-package-version). Esta opción se ignora cuando se utilizan versiones de paquete anteriores. Predeterminado: false.
--mail-o365-package-version	La versión del paquete de actividades de Microsoft Office 365 que se utilizará en la migración. El valor predeterminado es la versión 3.6.10. La versión de destino debe ser superior a la predeterminada. Si no es así, se utiliza la predeterminada.
--config, --mail-config	Especifica la ruta a un Archivo JSON de configuración personalizado. La configuración puede utilizarse para modificar el comportamiento predeterminado de ciertas actividades o asignar valores constantes a propiedades que requieren la entrada del usuario durante la migración. Consulta Archivo de Configuración.
--gsuite-package-version	La versión del paquete de actividades UiPath.GSuite.Activities que se utilizará para la migración. El valor predeterminado es la versión 3.8.10 si no se especifica. La versión de destino debe ser superior a la versión predeterminada. Si la versión de destino es inferior, se utilizará la versión predeterminada.
--gsuite-config	Especifica la ruta a un Archivo JSON de configuración personalizado. La configuración puede utilizarse para modificar el comportamiento predeterminado de ciertas actividades o asignar valores constantes a propiedades que requieren la entrada del usuario durante la migración. Consulta Archivo de Configuración.
--gsuite-migrate-only	Lista separada por comas de servicios incluidos en el migrador de GSuite (distingue mayúsculas de minúsculas). Valores disponibles: gmail, calendar, drive, docs, sheets, appsscript. Si se especifica, solo se ejecutarán esos servicios.

Migración en masa de repositorios

Esta opción analiza o migra todos los proyectos que se encuentran en una jerarquía de carpetas.

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

Uso: UiPath.Upgrade.exe bulk [options]

Opción	Descripción
-?, -h, --help	Muestra la información de ayuda y uso.
-p, --path (obligatorio)	Ruta al repositorio o carpeta. La migración se realiza en todas las subcarpetas que contienen un archivo project.json.
-c, --command (obligatorio)	Comando para ejecutar: analyze o upgrade.
-v, --verbose	Habilitar el registro verbose.
-o, --output-path	Ruta raíz de salida para proyectos actualizados. Esta carpeta se crea si no existe. Se crea una nueva carpeta con el sufijo _Upgraded para el proyecto actualizado.
--orchestrator-url	La URL completa de Orchestrator, incluido el nombre de la organización.
--orchestrator-tenant	El nombre del tenant de Orchestrator. El valor predeterminado es DefaultTenant si no se especifica.
--orchestrator-pat	Token de acceso personal (PAT) para la autenticación de Orchestrator. Requiere el ámbito OR.Execution.Read.
--orchestrator-application-id	ID de aplicación de OAuth para la autenticación de Orchestrator (alternativa a PAT).
--orchestrator-application-secret	Secreto de aplicación OAuth (alternativa a PAT).
--enabled-extensions	Lista de extensiones separadas por comas para habilitar. Consulta Extensiones disponibles.
--disabled-extensions	Lista separada por comas de extensiones que deshabilitar. Las extensiones disponibles se rellenan dinámicamente en función de las extensiones descubiertas.
--disable-all-extensions	Deshabilita todas las extensiones. Mutuamente excluyentes con --enabled-extensions y --disabled-extensions.

Ejemplos

Analiza un solo proyecto con salida verbose:

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

Migra un proyecto y especifica una versión de paquete de UI Automation de destino:

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

Migra un proyecto utilizando una configuración de conexión personalizada:

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

Ejecuta un análisis masivo en una carpeta:

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

Migra solo las actividades clásicas de Correo y GSuite en el proyecto, sin tocar otras actividades, como las actividades clásicas de Automatización de IU:

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

Migra solo el proyecto heredado a Windows (lo mismo que el convertidor de Studio Windows - Legacy). El comando no migra ninguno de los tipos de actividad compatibles:

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

Nota:

• Las opciones de línea de comandos utilizan las siguientes convenciones:
  • Las opciones cortas (por ejemplo, -p value) deben utilizar un espacio para separar la opción de su valor.
  • Las opciones largas (por ejemplo, --project-path=value) suelen utilizar el signo igual para vincular explícitamente el valor al indicador específico. En la mayoría de los casos, las opciones largas también pueden especificarse utilizando un espacio (por ejemplo, --project-path value). La opción --config es una excepción y solo admite la sintaxis del signo igual (por ejemplo, --config=value).
• La salida predeterminada del comando upgrade es un informe SARIF almacenado bajo una carpeta .upgrade en el proyecto original. El proyecto migrado se guarda en la ruta de salida.

Sintaxis admitida para colecciones

Varias opciones de CLI aceptan valores de colección: --enabled-extensions, --disabled-extensions y --gsuite-migrate-only. Cada uno admite varias sintaxis para especificar valores.

Formatos compatibles

Por ejemplo, todos estos vinculan los mismos valores a la colección ["drive", "gmail"]:

• Separados por comas: --gsuite-migrate-only=drive,gmail o --gsuite-migrate-only=drive --gsuite-migrate-only=gmail
• Separados por espacios: --gsuite-migrate-only drive,gmail o --gsuite-migrate-only drive --gsuite-migrate-only gmail
• Sintaxis de dos puntos (menos común): --gsuite-migrate-only:drive,gmail
• Sintaxis mixta: --gsuite-migrate-only=drive --gsuite-migrate-only gmail

Comportamiento predeterminado

Si falta la opción en el comando:

• --gsuite-migrate-only: migra todos los servicios de Google Workspace
• --enabled-extensions: todas las extensiones están habilitadas
• --disabled-extensions- ninguna extensión está deshabilitada

Nota:

El validador rechaza especificar una ocurrencia sin valores (por ejemplo, --gsuite-migrate-only "").

Extensiones disponibles

Se pueden especificar las siguientes extensiones para la opción --enabled-extensions o --disabled-extensions:

Extensión	Descripción
UiAutomationActivities	Migra las actividades clásicas de Automatización de IU en el paquete UiPath.UIAutomation.Activities a actividades modernas de Automatización de IU.
MailActivities	Migra dependencias de UiPath.Mail.Activities (actividades clásicas basadas en Outlook) a UiPath.MicrosoftOffice365.Activities (actividades basadas en Integration Service).
MicrosoftActivitiesExtension	Intenta convertir actividades del paquete Microsoft.Activities.Extensions , que solo funciona en.NET Framework (heredado).
GSuiteActivities	Migra las actividades clásicas de GSuite en el paquete UiPath.GSuite.Activities a actividades modernas dentro del mismo paquete.

Ejemplo: --enabled-extensions MailActivities,GSuiteActivities

De forma predeterminada, todas las extensiones están habilitadas. Si no se especifica la opción --enabled-extensions, los comandos analyze, upgrade y bulk procesarán todas las actividades en los paquetes compatibles.

Archivo de configuración

Usa un archivo de configuración para establecer valores constantes para las propiedades de la actividad que requieren entrada manual durante la migración, o para anular el comportamiento de migración predeterminado.

Pasa la ruta del archivo al migrador utilizando la opción --config con el operador de asignación =, como en este ejemplo: --config=C:\to-migrate\connection.json. Debes utilizar la opción de configuración adecuada dependiendo del tipo de migración:

• Para la migración de actividades de correo de Outlook: --config o --mail-config
• Para la migración de actividades clásicas de GSuite: --gsuite-config

El archivo de configuración debe seguir este formato:

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

Notas especiales

• El único {property-name} que se puede asignar es ConnectionId.
• * actúa como comodín y coincide con cualquier valor en {path-to-workflow}, {connector-type} y {activity-display-name}. Por lo tanto, se pueden especificar varios flujos de trabajo o actividades para la misma colección de propiedades. Cuando varias entradas coinciden con el mismo flujo de trabajo, actividad, tupla del conector, solo se aplica la última coincidencia.
• La parte [{connector-type}] es opcional. Cuando se omite, la entrada coincide con cualquier actividad independientemente del tipo de conector. Cuando se especifica, la entrada solo coincide con las actividades vinculadas a ese conector. Al menos uno de [{connector-type}] o {activity-display-name} debe estar presente.

Claves de configuración reservadas

{reserved-configuration-key} representa cambios de comportamiento específicos de la actividad:

• SaveOutlookMailMessage_IgnoreSaveAsType: si se establece en true, la opción deshabilita la marca Save as type de tipos no compatibles. Por lo tanto, la actividad puede migrarse independientemente del Save as type option.

Tipos de conectores disponibles

Los siguientes tipos de conectores se pueden utilizar con el patrón [{connector-type}]:

Conectores de Google (GSuite):

• uipath-google-drive: conector de Google Drive
• uipath-google-docs: conector de Google Docs
• uipath-google-sheets: conector de hojas de cálculo de Google
• uipath-google-gmail: conector de Gmail
• uipath-google-workspace: conector de Google Workspace
• uipath-google-tasks: conector de Google Tasks
• uipath-google-forms: conector de formularios de Google

Conectores de Microsoft:

• uipath-microsoft-outlook365: conector de Microsoft Outlook 365 Graph
• uipath-microsoft-outlook365ews: conector de Microsoft Outlook 365 EWS (Exchange Web Services)
• uipath-microsoft-onedrive: conector de Microsoft OneDrive
• uipath-microsoft-365: conector de Microsoft Office 365
• uipath-mail-mail: conector de correo

Obtener el ConnectionId de Orchestrator

A partir de marzo de 2026, las conexiones se han movido de Integration Service a Orchestrator.Puedes recuperar el ConnectionId directamente desde la URL de conexión en Orchestrator:

1. Ve a tu conexión en Orchestrator: ve a la carpeta de Orchestrator donde se encuentra tu conexión de Microsoft Outlook 365.
2. Abrir la conexión: selecciona la conexión para ver sus detalles.
3. Comprueba la URL: El ConnectionId es visible en la URL del explorador con el siguiente formato: https://cloud.uipath.com/{OrganizationName}/{TenantName}/orchestrator_/connections/{ConnectionId}/edit/tid={TId}

Resultado

El ID de conexión es visible en la URL del navegador en el formato .../connections/{ConnectionId}/edit/tid={TId}.

Configuración de los ID de conexión para las actividades de correo

La propiedad ConnectionId no se rellena automáticamente durante la migración. Debes establecerlo manualmente por flujo de trabajo/actividad utilizando un archivo de configuración. El archivo de configuración puede pasarse al Migrador de actividades utilizando el argumento de la línea de comandos --config <config> o --mail-config <config>.

El siguiente ejemplo asigna diferentes ID de conexión a actividades específicas de Productividad (Microsoft Office 365), utilizando un comodín alternativo:

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

En este ejemplo:

• * > * coincide con todas las actividades y actúa como alternativa cuando no hay entradas coincidentes a continuación.
• *\\Projects\\MailMigration\\Main.xaml > Get * coincide con cualquier actividad cuyo nombre para mostrar comience con Get en Main.xaml.
• *\\Projects\\MailMigration\\* > Send Mail coincide con la actividad Send Mail en todos los flujos de trabajo de la carpeta MailMigration.

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

En este ejemplo:

• * > * coincide con todas las actividades y actúa como alternativa cuando no hay entradas coincidentes a continuación.
• * > [uipath-microsoft-outlook365] * anula para todas las actividades de Outlook.
• *\\Projects\\MailMigration\\Main.xaml > [uipath-microsoft-outlook365] Get * se reduce aún más a Get * actividades en un flujo de trabajo específico.

Configuración de los ID de conexión para las actividades de GSuite

Las actividades modernas de servicio de conexión requieren un ConnectionId que el migrador generalmente no puede inferir. Dos casos:

1. Dentro de un OAuth GSuiteApplicationScope : la actividad hereda la conexión del ámbito en tiempo de ejecución, por lo que ConnectionId se deja vacío (UseConnectionService se establece en false en la actividad).
2. Fuera de un ámbito, O después de que un ámbito de servicio de conexión se haya desenvuelto en un Sequence durante la migración : la actividad necesita un ConnectionId explícito. El migrador no puede generar uno porque el runtime de Studio, y no el migrador, es el propietario del ciclo de vida de la conexión de IS.

Para desbloquear este caso, el migrador acepta un archivo de configuración JSON (--gsuite-config <path>) que asigna de forma declarativa las instancias de actividad a valores ConnectionId. El mismo mecanismo es utilizado por Correo (--mail-config, alias --config).

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

En el esquema anterior, cada regla es un globo sobre tres coordenadas:

• {path-to-workflow} : la ruta del archivo del flujo de trabajo (separadores de estilo Windows normalizados). * es un comodín.
• [{connector-type}] — opcional. La clave del conector IS vinculada a la actividad moderna (por ejemplo uipath-google-drive, uipath-google-gmail). Si se omite, la regla coincide con cualquier conector.
• {activity-display-name} : el nombre para mostrar de la actividad migrada. * es un comodín.

Cuando varias reglas coinciden con la misma tupla de flujo de trabajo + actividad + conector, la última coincidencia gana por propiedad, y las propiedades establecidas por una coincidencia anterior se conservan cuando no se sobrescriben, lo que facilita la superposición de un valor predeterminado global con anulaciones por actividad:

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

El ejemplo anterior también configura diferentes ID de conexión para diferentes servicios de Google Workspace (Drive, Sheets, Docs, Gmail).

ConnectionId es la única propiedad que la configuración puede rellenar. Cuando se requiere un ConnectionId pero ninguna regla coincide, el migrador emite una acción requerida que apunta al usuario de nuevo al archivo de configuración.

Comportamiento del ámbito de la aplicación de UI Automation después de la migración

La mayoría de las actividades modernas de UI Automation requieren un ámbito de aplicación (actividad Usar aplicación/explorador). Durante la migración, se crean dos tipos de ámbitos:

Ámbitos creados orgánicamente

Estos ámbitos se generan automáticamente al migrar actividades clásicas con ámbito, como Abrir Explorador y Asociar Explorador. Estos ámbitos no están optimizados para evitar alterar la intención y el flujo originales del flujo de trabajo migrado.

Ámbitos generados sintéticamente

Estos ámbitos se generan para garantizar que el flujo de trabajo se compila y se ejecuta correctamente después de la migración. Cuando dos ámbitos consecutivos tienen propiedades idénticas (por ejemplo, el mismo selector o motor de OCR), se fusionan en un solo ámbito conservando el orden original de la actividad.

Limitaciones

Actividades UIAutomation

• La versión de destino mínima admitida de UiPath.UIAutomation.Activities es 25.10.21.
• Algunas propiedades de actividad tienen limitaciones de migración. Consulta las listas de actividades compatibles:
  • Actividades compatibles con UI Automation
  • Actividades no compatibles con UI Automation
• Los flujos de trabajo migrados que utilizan actividades modernas de UI Automation pueden ejecutarse más lentamente que los flujos de trabajo originales que utilizan actividades clásicas de UI Automation.

Actividades de productividad

• La versión de destino mínima admitida de UiPath.MicrosoftOffice365.Activities es 3.6.10.
• Consulta las listas de actividades compatibles:
  • Actividades compatibles con Correo
  • Actividades no compatibles con correo

Limitaciones de la herramienta

• De forma predeterminada, la herramienta Migrador de actividad utiliza fuentes NuGet configuradas en NuGet.config: Oficial, Local y Marketplace. Para incluir fuentes de la biblioteca de Orchestrator, utiliza las opciones para los comandos analyze, upgrade y bulk: --orchestrator-url, --orchestrator-tenant, --orchestrator-pat, --orchestrator-application-id y --orchestrator-application-secret.
• Las actividades que utilizan tipos o ensamblajes generados dinámicamente (por ejemplo, algunas actividades de Excel pueden tener nombres de columna como propiedades en un tipo generado dinámicamente) pueden causar un error de tipo no encontrado en archivos .xaml después de la migración.

Regla del analizador de flujo de trabajo de Studio

• La regla del analizador de flujo de trabajo ST-AMG-001 está disponible a partir de Studio 2024.10.25 LTS, Studio 2025.10.8 LTS y Studio 2026.0.189 STS.

Prácticas recomendadas de migración

Antes de la migración

1. Haz copias de seguridad de tus proyectos: crea siempre una copia de seguridad completa antes de ejecutar cualquier comando de migración.
2. Actualizar Studio y los paquetes de actividades: utiliza la última versión de UiPath Studio y asegúrate de que las versiones del paquete de destino cumplan los requisitos mínimos (UiPath.UIAutomation.Activities >= 25.10.21 y UiPath.MicrosoftOffice365.Activities >= 3.6.10).
3. Analizar antes de actualizar: ejecuta el comando analyze primero. Usa UiPath.Upgrade.exe analyze -p -v para generar un informe SARIF e identificar posibles incidencias sin modificar el proyecto.
4. Verificar las dependencias y las fuentes NuGet: confirma que las fuentes Oficial, Local y de Marketplace están configuradas correctamente en NuGet.config.
5. Migra primero las bibliotecas cuando un proyecto depende de proyectos de biblioteca: solo entonces migra los proyectos que las consumen.

Durante la migración

5. Comienza con un solo proyecto: prueba la migración en un proyecto usando UiPath.Upgrade.exe upgrade -p -v antes de ejecutar una operación en masa.
6. Usa la migración en masa para varios proyectos: una vez validada, ejecuta UiPath.Upgrade.exe bulk -p -v. Asegúrate de que la estructura de carpetas esté limpia y sea coherente.
7. Proporciona un archivo de configuración para los ID de conexión: para las actividades de Microsoft 365 o GSuite, crea un archivo de configuración con los valores ConnectionId requeridos y pásalo con --config:

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

Después de la migración

8. Revisa el informe SARIF: consulta la carpeta .upgrade en el directorio del proyecto y soluciona cualquier incidencia marcada.
9. Abre el proyecto migrado en Studio y ejecuta Analizar proyecto: revisa los resultados de la regla del Analizador de flujo de trabajo ST-AMG-001 (disponible en Studio 2025.10.8 Soporte a largo plazo/Studio 2026.0.189 STS o superior) para identificar actividades que requieren acciones tras la migración.
10. Validar ámbitos de aplicación: confirma que los ámbitos fusionados se comportan como se espera. Probar flujos de trabajo con actividades Usar aplicación/explorador.
11. Ejecutar pruebas de extremo a extremo: ejecuta los flujos de trabajo migrados en un entorno controlado antes de implementarlos en producción.

Rendimiento y mantenimiento

12. Optimizar los selectores de UI Automation: después de la migración, revisa la precisión y la estabilidad de los selectores.
13. Supervisar el tiempo de ejecución: las actividades modernas pueden ejecutarse más lentas al principio. Optimiza donde sea necesario.
14. Documenta tus cambios: lleva un registro de los proyectos migrados, las versiones de destino y las configuraciones aplicadas con fines de auditoría y reversión.