DocumentaciónAEMGuía del usuario

Uso de la habilidad de migración de AEM Cloud using-cloud-migration-skill

Última actualización: 17 de septiembre de 2026
  • Se aplica a:
  • Experience Manager as a Cloud Service

Creado para:

  • Developer

Esta referencia abarca cada patrón de migración admitido, cómo proporcionar conclusiones de BPA y cómo administrar las sesiones en un proyecto grande. Para obtener instrucciones de introducción y configuración, consulte la descripción general.

Generación de un Runbook de migración migration-runbook

Para una evaluación de todo el proyecto, comience con un runbook en lugar de nombrar un solo patrón. Pregunte al agente:

Review my code for AEMaaCS migration

La aptitud genera un elementomigration-runbook.md de solo lectura en la raíz del proyecto sin cambiar ningún código. El runbook cubre cada patrones que la habilidad de migración puede abordar y, para cada uno, registra:

  • La estrategia de detección utilizada (resultados de BPA/CAM, analizador o análisis de contenido heurístico)
  • Los archivos afectados y un recuento de búsqueda por patrón
  • Un mensaje de copia y pegado para iniciar la sesión de migración de ese patrón

Dado que el runbook también escribe una caché de resultados junto con el markdown, una sesión de patrón posterior reutiliza los hallazgos ya descubiertos: el agente no vuelve a escanear. Utilice el runbook para priorizar qué patrones abordar primero y luego iniciar sesiones de patrones como se describe a continuación.

NOTE
El runbook es de solo lectura. Nunca edita el código, y los resultados heurísticos (que no son de BPA) son coincidencias candidatas para confirmar en lugar de recuentos autorizados.

Cómo funciona una sesión workflow-overview

Cada sesión de migración sigue esta secuencia:

  1. Asigne un nombre al patrón: especifique un patrón (por ejemplo, scheduler)
  2. Proporcione resultados: desde un archivo CSV de BPA, CAM a través de MCP o rutas de acceso a archivos específicas
  3. El agente lee las reglas de transformación: la aptitud lee las reglas de transformación relevantes de la aptitud de code-assessment acompañante antes de realizar cualquier cambio de código
  4. Primer lote de cinco: el agente transforma hasta cinco resultados e informa de los cambios
  5. Usted revisa y continúa: después de revisar cada lote, responda continue para continuar con el siguiente

El agente procesa un patrón y un lote a la vez. No se realiza automáticamente; cada lote requiere su confirmación.

Patrones de migración patterns

Planificador scheduler

Se dirige a clases Java que utilizan la inyección sling.commons.scheduler o Scheduler que son incompatibles con el tiempo de ejecución en contenedores sin estado de AEMaaCS.

Id. de patrón BPA: scheduler

El agente convierte los trabajos insertados por Scheduler en @Component implementaciones de Runnable mediante @Designate, reemplazando el registro de programador basado en constructor con los métodos de ciclo de vida @Activate / @Deactivate.

ResourceChangeListener resource-change-listener

Se dirige a ResourceChangeListener o ResourceChange implementaciones de escucha que requieren actualizaciones para AEMaaCS.

Id. de patrón BPA: resourceChangeListener

Replicación replication

Clases de destino que importan com.day.cq.replication.Replicator o API de replicación relacionadas, que no se admiten en AEMaaCS. El agente los reemplaza con equivalentes basados en ContentDistribution y actualiza las referencias del servicio OSGi correspondientes.

Id. de patrón BPA: replication

Escuchador de eventos event-listener

Se dirige a implementaciones OSGi EventListener o EventHandler que deben actualizarse para la semántica del procesamiento de eventos AEMaaCS.

Id. de patrón BPA: eventListener

Controlador de eventos event-handler

Se dirige a servicios sincrónicos de OSGi EventHandler que deben adaptarse para AEMaaCS.

Id. de patrón BPA: eventHandler

API de recursos asset-api

Clases de Target que utilizan AssetManager, DAMEvent o API de DAM no admitidas en desuso. El agente los reemplaza por los equivalentes de API de AEM Assets admitidos.

Id. de patrón BPA: assetApi

Caché de guayaba a cafeína guava-cache

Se dirigen a paquetes que utilizan la caché de Guava (com.google.common.cache.*, como Cache, CacheBuilder y LoadingCache). En AEM as a Cloud Service, la biblioteca de caché en proceso admitida es Caffeine, por lo que el agente intercambia la dependencia de Maven, actualiza las importaciones y ajusta los sitios de llamada afectados. Debido a que Caffeine fue escrito por el mismo autor y su API es intencionalmente casi idéntico, el cambio es principalmente mecánico.

Id. de patrón BPA: guavaCache

BPA informa de este patrón con una granularidad de bundle (subtipo custom.guava.cache), de modo que el agente resuelve el paquete en los archivos Java que realmente importan la caché de Guava y los edita. Este patrón lo proporciona solamente la aptitud de migración, no code-assessment, porque el uso de la caché de Guava se produce solamente en el código transferido del AEM heredado, nunca en el código nativo de Cloud Service.

NOTE
guavaCache depende de BPA como origen de la verdad. Cuando no hay ningún origen BPA o CAM disponible, el agente vuelve a analizar los archivos Java para detectar import com.google.common.cache importaciones como candidatos no confirmados.

HTL Lint (data-sly-test) htl-lint

Se dirige a plantillas HTL en ui.apps que producen data-sly-test: redundant constant value comparison advertencias de pelusa. El agente detecta las plantillas afectadas analizando el paquete de contenido directamente; este patrón no requiere una conexión CSV o CAM de BPA.

Id. de patrón BPA: htlLint

NOTE
Los resultados de htlLint no aparecen en las exportaciones de CSV de BPA. El agente los descubre a través del análisis directo de archivos cuando inicia una sesión para este patrón.

Configuraciones de OSGi para Cloud Manager osgi-cloud-manager

Convierte las configuraciones de OSGi en ui.config al formato .cfg.json compatible con Cloud Manager con un control completo específico del entorno. Esto abarca varias tareas relacionadas:

Conversión de formato de configuración

AEMaaCS requiere que las configuraciones de OSGi se almacenen como archivos de .cfg.json, con configuraciones específicas del entorno en carpetas con ámbitos en modo de ejecución (config.author/, config.publish/, config.dev/, etc.). El agente:

  • Convierte las configuraciones existentes de OSGi de .config, .cfg y formato XML a .cfg.json
  • Divide las configuraciones que contienen valores específicos de autor y publicación en archivos con ámbitos de modo de ejecución independientes
  • Valida los tipos de propiedad con la especificación del tipo de metal OSGi (cadenas, enteros, booleanos, matrices)
  • Indica los PID propiedad de Adobe para su revisión manual en lugar de convertirlos automáticamente

Secretos y variables de entorno

Quita los secretos de texto sin formato y los valores específicos del entorno de los archivos de configuración confirmados y los reemplaza por marcadores de posición de Cloud Manager:

  • $[secret:NAME]: para contraseñas, tokens y otros valores confidenciales
  • $[env:NAME]: para valores no confidenciales que difieren por entorno (por ejemplo, direcciones URL de servicio)

Las variables y los secretos correspondientes se aplican en Cloud Manager y se insertan durante la ejecución; no se almacena ningún valor en el control de código fuente.

IMPORTANT
El agente nunca emite valores secretos en la conversación. Todos los datos confidenciales se escriben en un archivo de transferencia ignorado para que los aplique a través de la API o la IU de Cloud Manager.

Modos de ejecución no compatibles (URC)

AEM as a Cloud Service admite un conjunto fijo de identificadores del modo de ejecución. Las carpetas de configuración que utilizan un modo de ejecución no compatible no tienen ningún efecto una vez implementadas. El agente marca estas configuraciones de modo de ejecución no admitidas (URC), incluidas:

  • Tokens de modo de ejecución desconocidos, por ejemplo config.qa o install.local
  • Un token de nivel que sigue en lugar de precede al token de entorno—config.dev.author en lugar del config.author.dev válido
  • Tokens que no están en minúsculas, como config.Author.dev, y los reservados config.preview (la vista previa se hereda de la publicación)

Los resultados de URC provienen primero del Analizador de prácticas recomendadas (subtipo unsupported.runmode, gravedad CRITICAL); cuando ningún origen de BPA los informa, el agente analiza las carpetas config.* y install.* localmente como una red de seguridad. Para cada búsqueda, informa de la ruta de la carpeta, el modo de ejecución infractor y la corrección: evalúe si la configuración sigue siendo necesaria, cambie el nombre a un modo de ejecución admitido o elimínela si está obsoleta. Para infracciones de solo pedido, donde cada token es válido pero está desordenado, el agente puede aplicar un repedido seguro automáticamente (por ejemplo, cambiar el nombre de config.dev.author a config.author.dev); se marcan tokens desconocidos y otros casos ambiguos para que los resuelva.

La conversión de formato de configuración y la externalización secreta no requieren un CSV o CAM de BPA, y la detección de URC usa los resultados de BPA cuando están disponibles. Inicie una sesión con:

Scan my config files and create Cloud Manager environment secrets or variables.

Migración de cuadros de diálogo (IU heredada) dialog-migration

Convierte los cuadros de diálogo de IU clásica a IU táctil. El agente administra dos subtipos de cuadros de diálogo: las definiciones de ExtJS/IU clásica cq:Dialog se vuelven a crear como estructuras de Coral 3 _cq_dialog y los cuadros de diálogo de Coral 2 existentes se actualizan a Coral 3. También transfiere agentes de escucha optionsProvider, namePrefix y actualizaciones filter.xml.

Id. de patrón BPA: lui (solo subtipos de diálogo)

Cuando existan conclusiones tanto de widgets de diálogo como personalizados para los mismos componentes, ejecute primero la migración de widgets personalizados de modo que todas las referencias de xtype se resuelvan antes de que se conviertan los cuadros de diálogo.

Convert my Classic UI dialogs to Touch UI Coral 3.

Widgets de diseño personalizados (IU heredada) custom-design-widgets

Migra widgets personalizados de ExtJS (cq:Widget definiciones con xtype valores personalizados). El agente realiza un inventario de los widgets y, a continuación, asigna cada xtype a un equivalente de Coral 3 conocido o andamiaje un componente de formulario de la interfaz de usuario de Granite cuando no existe ninguna asignación directa.

Id. de patrón BPA: cdw

Migrate my custom ExtJS widgets (CDW findings) from CAM.

Modernización de plantillas template-modernization

Convierte las plantillas estáticas en plantillas editables y genera las Herramientas de modernización de AEM correspondientes para reescribir reglas (estructura, componente y reglas de directiva). El agente se ejecuta en tres fases: detecta las plantillas y produce un plan por plantilla, ejecuta la plantilla de plan por plantilla y valida las estructuras /conf generadas.

Durante la detección, el agente explora las plantillas bajo apps/<appId>/templates/ a cualquier profundidad (incluidas las carpetas de plantillas anidadas o agrupadas) y clasifica cada plantilla estática como heredada o personalizada en función de su tipo de recurso de componente de página. Esta clasificación se mantiene incluso sin un informe de BPA, por lo que las plantillas personalizadas se gestionan de forma distintiva de las heredadas.

Este patrón no usa un id. de patrón BPA. Inicie una sesión con:

Migrate my static templates to editable templates and generate the Modernize Tools rewrite rules.

Conversión de Dispatcher dispatcher-conversion

Convierte una configuración de AMS o Apache HTTPD y Dispatcher local en la estructura de AEM as a Cloud Service. Esta capacidad ajusta la herramienta Dispatcher Converter de Adobe que se mantiene, agregando detección, generación de configuración, verificación de salida y validación alrededor de ella.

El agente trabaja mediante un flujo por fases:

  1. Detectar e inventario: determina la configuración mode y registra un recuento de línea de base de reglas de filtro, reescritura y caché. Los modos reconocidos son standard (AMS), flexible (monolítico local), v1 (diseños más antiguos), already-cloud, not-dispatcher y unknown. Para already-cloud, not-dispatcher o unknown, el agente se detiene y le pide que confirme antes de continuar.
  2. Planificar y generar configuración: genera la configuración del convertidor y confirma el plan con usted.
  3. Convert: ejecuta el convertidor Dispatcher de Adobe (se instala automáticamente la primera vez que se usa).
  4. Verificar: comprueba el resultado con la línea de base. Un conjunto de filtros vaciado (filter-acl-loss) es una detención de hardware que debe resolverse antes de continuar.
  5. Envío transfronterizo: enruta las variables de entorno de Cloud Manager al flujo de configuraciones de OSGi y marca candidatos de CDN o encabezados de seguridad.
  6. Validar: ejecuta el validador de Cloud Service Dispatcher y genera un informe de conversión consolidado.

id. de patrón Runbook: dispatcherConversion (detectado heurísticamente desde el diseño de configuración). Este patrón no utiliza BPA ni CAM. Inicie una sesión con:

Convert my AMS / on-prem Dispatcher config to AEM as a Cloud Service.
NOTE
Ejecute esto con un árbol de trabajo limpio para que el resultado convertido sea fácil de revisar y revertir. El grado de automatización depende del modo detectado: las configuraciones de standard (AMS) están casi automatizadas, mientras que los diseños de flexible y v1 necesitan más revisión.

Opciones de Source de BPA bpa-source

Origen
Cuándo se usa
archivo CSV de BPA
Ha exportado un CSV desde su instancia de AEM o Cloud Acceleration Manager. Proporcione la ruta de acceso al iniciar la sesión.
CAM a través de MCP
Tiene configurado el MCP de migración de AEM Cloud. El agente enumera sus proyectos CAM, usted confirma cuál utilizar y los resultados se recuperan directamente. Consulte Uso del MCP de migración de nube.
Rutas de archivo manuales
Desea migrar archivos específicos sin un informe de BPA. Proporcione las rutas directamente en el mensaje.

Gestión de errores de MCP mcp-errors

Si la conexión MCP devuelve un error (incluidos los errores de autenticación o los que no se encuentran en el proyecto), el agente se detiene y le muestra el error. No cambia automáticamente a otra fuente. Desde el estado detenido, puede:

  • Confirme el proyecto correcto de la lista que muestra el agente
  • Proporcione una ruta CSV de BPA como alternativa
  • Proporcionar rutas de archivo Java específicas para una migración manual

Administración de sesiones en informes grandes large-reports

Para los informes de BPA con muchas conclusiones, el método por lotes le permite validar de forma incremental:

  1. Revisar la diferencia de cada lote
  2. Confirmar el lote con un mensaje de confirmación de ámbito de patrón
  3. Responder continue para iniciar el siguiente lote
  4. Repita el proceso hasta que el agente informe de que se han realizado todos los resultados del patrón

Un patrón por confirmación mantiene el historial de Git legible y hace que las transformaciones de patrones individuales sean fáciles de revertir si es necesario.

NOTE
Si finaliza una sesión antes de que se procesen todos los resultados, reinicie con el mismo patrón y origen de BPA en una nueva sesión. El agente se reanuda desde donde lo dejó.

Ámbito de Workspace workspace-scope

El agente busca y edita archivos sólo en las carpetas abiertas del espacio de trabajo del IDE. No analiza los directorios principales, las carpetas del mismo nivel ni otras ubicaciones del disco.

Si un hallazgo de BPA hace referencia a una ruta de archivo que no existe en el espacio de trabajo, el agente se detiene y le informa de qué rutas faltan. Abra la carpeta de proyecto correcta o proporcione las rutas explícitamente para continuar.

recommendation-more-help
experience-manager-cloud-service-help-main-toc