Acerca de la herramienta Migrador de actividades

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.

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).
• Es necesario migrar las actividades de UI Automation o Correo.
• 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 Descargar 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 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 separada por comas de extensiones que se van a 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 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.
--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	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.

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 separada por comas de extensiones que se van a habilitar. Extensiones disponibles: UiAutomationActivities, MailActivities, MicrosoftActivitiesExtension. Ejemplo: --enabled-extensions MailActivities,MicrosoftActivitiesExtension
--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.
--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	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.

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 separada por comas de extensiones que se van a habilitar. Extensiones disponibles: UiAutomationActivities, MailActivities, MicrosoftActivitiesExtension. Ejemplo: --enabled-extensions MailActivities,MicrosoftActivitiesExtension
--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

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.

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 usando 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 marca Save as type de tipos no compatibles. Por lo tanto, la actividad puede migrarse independientemente del Save as type option.
• * actúa como un comodín y coincidencias con cualquier valor tanto en {path-to-workflow} como en {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 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: haz clic en 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}

Configurar 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 se puede pasar al Migrador de actividades con el argumento de 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 una alternativa de comodín:

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

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 2025.10.8 Soporte a largo plazo 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.