Acerca de la herramienta Migrador de actividades

Propósito del Migrador de actividades

El Migrador de actividades es una herramienta de interfaz de línea de comandos (CLI) esencial para las organizaciones que hacen la transición de proyectos de automatización heredados a la plataforma UiPath moderna, que permite el acceso a las últimas características y capacidades:

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

Escenarios de migración compatibles

Migración del marco del proyecto

Se recomienda encarecidamente migrar un proyecto de Windows: heredado a la compatibilidad de Windows por varias razones estratégicas, técnicas y relacionadas con el soporte:

1. Rendimiento mejorado: los proyectos de Windows se ejecutan de forma más rápida y 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 automatización de IU

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

Migración de actividades obsoletas de Outlook

Microsoft está eliminando Outlook clásico y fomentando la adopción de Microsoft 365. Como resultado, el Migrador de actividades admite la transición de dependencias de automatización de UiPath.Mail.Activities (que se basan en la API de Outlook clásica) a UiPath.MicrosoftOffice365.Activities basada en UiPath Integration Service.

Migrador de actividades frente al convertidor de Studio Windows: heredado

Utiliza el convertidor de Studio Windows: heredado cuando:

• Solo tienes que convertir los proyectos de Windows: heredado a Windows uno por uno.
• No se requieren migraciones de actividad.

Utiliza el Migrador de actividades cuando:

• Desea convertir varios proyectos de Windows: heredado a Windows (conversión masiva compatible).
• Se necesita la migración de las actividades de Automatización de IU o Correo .
• Se aplica cualquier combinación de los escenarios anteriores.

Dónde obtener el Migrador de actividades

Sigue los siguientes pasos 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 de características , selecciona Herramienta de migración de actividades.
5. Selecciona el enlace de descarga.

Después de descargar el archivo .zip , asegúrate de instalarlo en la carpeta <tool-install-dir> .

Requisitos

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

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	Analice un proyecto para la migración sin realizar cambios.
upgrade	Migrar un proyecto o partes de él.
bulk	Analizar o migrar todos los proyectos en 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 a 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	Habilita el registro detallado.
-f, --output-format	Formato de salida: console (predeterminado) o sarif.
-e, --extension-directory	Directorio para 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 tipos que faltan, no compilar o no 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 especifique, también debes proporcionar las credenciales a través del token de acceso personal (PAT) utilizando --orchestrator-pat o el ID de la aplicación externa y el secreto 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, utilizado para acceder a las fuentes de la biblioteca de Orchestrator. Crea un token de acceso personal y añade el á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 OAuth para la autenticación de Orchestrator (alternativa a PAT). Usar con --orchestrator-application-secret. Consulta Gestionar aplicaciones OAuth externas.
--orchestrator-application-secret	Secreto de aplicación OAuth para la autenticación de Orchestrator (alternativa a PAT). Usar con --orchestrator-application-id. Consulta Gestionar aplicaciones OAuth externas.
--enabled-extensions	Lista separada por comas de extensiones para habilitar. De forma predeterminada, todas las extensiones están habilitadas. Extensiones disponibles: UiAutomationActivities, MailActivities, MicrosoftActivitiesExtension. Ejemplo: --enabled-extensions MailActivities,MicrosoftActivitiesExtension
--disabled-extensions	Lista separada por comas de extensiones para deshabilitar. Las extensiones disponibles se rellenan de forma dinámica en función de las extensiones descubiertas.
--disable-all-extensions	Deshabilitar 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 automatización de IU 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, se utiliza el valor predeterminado.
--uia-fix-selector-strategy	Cuando se establece en true, corrige la ambigüedad de la enumeración SelectorStrategy en las expresiones preexistentes después de la migración. Se aplica a la versión 25.10.29 de UIAutomation o superior. Predeterminado: false. La ambigüedad resulta de la enumeración SelectorStrategy existente en los espacios de nombres UiPath.Core y UiPath.UIAutomationNext.Enums . El uso del nombre completo resuelve este problema.
--mail-o365-package-version	La versión del paquete de actividades de Microsoft Office 365 que se utilizará para 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, se utiliza el valor predeterminado.
--config	Especifica la ruta a un archivo JSON de configuración personalizada. La configuración se puede utilizar 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.

Migrar un proyecto

Esta opción realiza la migración real de un proyecto o 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	Habilita el registro detallado.
-f, --output-format	Formato de salida: console (predeterminado) o sarif.
-e, --extension-directory	Directorio para 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 tipos que faltan, no compilar o no 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 OAuth para la autenticación de Orchestrator (alternativa a PAT).
--orchestrator-application-secret	Secreto de aplicación OAuth (alternativa a PAT).
--enabled-extensions	Lista separada por comas de extensiones para habilitar. Extensiones disponibles: UiAutomationActivities, MailActivities, MicrosoftActivitiesExtension. Ejemplo: --enabled-extensions MailActivities,MicrosoftActivitiesExtension
--disabled-extensions	Lista separada por comas de extensiones para deshabilitar. Las extensiones disponibles se rellenan de forma dinámica en función de las extensiones descubiertas.
--disable-all-extensions	Deshabilitar todas las extensiones. Mutuamente excluyente con --enabled-extensions y --disabled-extensions.
--uia-package-version	Versión del paquete de destino UiPath.UIAutomation.Activities . El valor predeterminado es 25.10.21.
--uia-fix-selector-strategy	Cuando se establece en true, corrige la ambigüedad de la enumeración SelectorStrategy en las expresiones preexistentes después de la migración. Se aplica a la versión 25.10.29 de UIAutomation o superior. Predeterminado: false. La ambigüedad resulta de la enumeración SelectorStrategy existente en los espacios de nombres UiPath.Core y UiPath.UIAutomationNext.Enums . El uso del nombre completo resuelve este problema.
--mail-o365-package-version	La versión del paquete de actividades de Microsoft Office 365 que se utilizará para 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, se utiliza el valor predeterminado.
--config	Especifica la ruta a un archivo JSON de configuración personalizada. La configuración se puede utilizar 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.

Migración masiva del repositorio

Esta opción analiza o migra todos los proyectos encontrados 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 a ejecutar: analyze o upgrade.
-v, --verbose	Habilita el registro detallado.
-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 OAuth para la autenticación de Orchestrator (alternativa a PAT).
--orchestrator-application-secret	Secreto de aplicación OAuth (alternativa a PAT).
--enabled-extensions	Lista separada por comas de extensiones para habilitar. Extensiones disponibles: UiAutomationActivities, MailActivities, MicrosoftActivitiesExtension. Ejemplo: --enabled-extensions MailActivities,MicrosoftActivitiesExtension
--disabled-extensions	Lista separada por comas de extensiones para deshabilitar. Las extensiones disponibles se rellenan de forma dinámica en función de las extensiones descubiertas.
--disable-all-extensions	Deshabilitar todas las extensiones. Mutuamente excluyente con --enabled-extensions y --disabled-extensions.

Ejemplos

Analizar un único proyecto con salida detallada:

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

Migra un proyecto y especifica una versión del paquete de automatización de IU de destino:

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

Migrar 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

Ejecutar un análisis masivo en una carpeta:

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

Nota:

• Las opciones de la línea de comandos utilizan las siguientes convenciones:
  • Las opciones cortas (por ejemplo, -p value) deben usar 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 marcador 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 en el proyecto original en una carpeta .upgrade . El proyecto migrado se guarda en la ruta de salida.

Archivo de configuración

Utiliza 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.

El archivo de configuración debe seguir este formato:

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

Nota:

• Actualmente, el único {property-name} que se puede asignar es Connection Id.
• {reserved-configuration-key} representa cambios de comportamiento específicos de la actividad:
  • SaveOutlookMailMessage_IgnoreSaveAsType: si se establece en true, la opción deshabilita la comprobación Save as type para tipos no compatibles. Por lo tanto, la actividad puede migrarse independientemente de Save as type option.
• * actúa como comodín y coincide con cualquier valor tanto en {path-to-workflow} como {activity-display-name}.
• Cuando varias entradas coinciden con el mismo flujo de trabajo y actividad, solo se aplica la última coincidencia.

Obtener el ConnectionId de Orchestrator

A partir de marzo de 2026, las conexiones se han trasladado 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: haz clic en la conexión para ver sus detalles.
3. Comprueba la URL: ConnectionId es visible en la URL del navegador con el siguiente formato: https://cloud.uipath.com/{OrganizationName}/{TenantName}/orchestrator_/connections/{ConnectionId}/edit/tid={TId}

Establecer ID de conexión para actividades de productividad

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> .

El siguiente ejemplo asigna diferentes ID de conexión a actividades específicas de Productividad (Microsoft Office 365, GSuite), 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 por Get en Main.xaml.
• *\\Projects\\MailMigration\\* > Send Mail coincide con la actividad Send Mail en todos los flujos de trabajo de la carpeta MailMigration .

Comportamiento del ámbito de la aplicación de automatización de IU después de la migración

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

Ámbitos creados de forma orgánica

Estos ámbitos se generan automáticamente al migrar actividades de ámbito clásico como Abrir navegador y Adjuntar navegador. Estos ámbitos no están optimizados para evitar alterar la intención original y el flujo 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 OCR), se fusionan en un único ámbito conservando el orden de actividad original.

Limitaciones

Actividades UIAutomation

• La versión de destino mínima compatible 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 UIAutomation
  • Actividades no compatibles de UIAutomation
• Los flujos de trabajo migrados que utilizan actividades de automatización de IU modernas pueden ejecutarse más lentamente que los flujos de trabajo originales que utilizan actividades de automatización de IU clásicas.

Actividades de productividad

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

Limitaciones de la herramienta

• De forma predeterminada, la herramienta Migrador de actividades 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 conjuntos 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 los 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 2025.10.8 LTS y Studio 2026.0.189 STS.

Mejores prácticas de migración

Antes de migrar

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

Durante la migración

5. Comenzar con un solo proyecto: prueba la migración en un proyecto utilizando UiPath.Upgrade.exe upgrade -p -v antes de ejecutar una operación masiva.
6. Utilizar la migración masiva para varios proyectos: una vez validado, ejecuta UiPath.Upgrade.exe bulk -p -v. Asegúrate de que la estructura de carpetas sea limpia y 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 necesarios y pásalo con --config:

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

Después de migrar

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

Rendimiento y mantenimiento

12. Optimizar los selectores de automatización de IU: 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 lentamente al principio. Optimice donde sea necesario.
14. Documenta tus cambios: mantén un registro de los proyectos migrados, las versiones de destino y las configuraciones aplicadas con fines de auditoría y reversión.