DocumentazioneAEMGuida utente

Utilizzo dell’abilità di migrazione ad AEM Cloud using-cloud-migration-skill

Ultimo aggiornamento: 11 ottobre 2026
  • Si applica a:
  • Experience Manager as a Cloud Service

Creato per:

  • Sviluppatore

Questa documentazione descrive ogni modello di migrazione supportato, come fornire i risultati BPA e come gestire le sessioni in un progetto di grandi dimensioni. Per un’introduzione e le istruzioni di installazione, vedere la panoramica.

Generare un Runbook di migrazione migration-runbook

Per una valutazione dell’intero progetto, inizia con un runbook invece di denominare un singolo pattern. Chiedi all’agente:

Review my code for AEMaaCS migration

L’abilità genera un migration-runbook.md di sola lettura nella directory principale del progetto senza modificare il codice. Il runbook copre ogni pattern che l’abilità di migrazione può risolvere e, per ciascuno, registra:

  • La strategia di rilevamento utilizzata (risultati BPA/CAM, analizzatore o scansione del contenuto euristico)
  • I file interessati e un conteggio dei risultati per pattern
  • Un prompt di copia e incolla per avviare la sessione di migrazione del modello

Poiché il runbook scrive anche una cache dei risultati insieme al markdown, una sessione di pattern successiva riutilizza i risultati già scoperti, l’agente non esegue una nuova scansione. Utilizza il runbook per assegnare la priorità ai pattern da affrontare per primi, quindi avvia le sessioni di pattern come descritto di seguito.

NOTE
Runbook di sola lettura. Non modifica mai il codice, e i risultati euristici (non-BPA) sono corrispondenze candidate da confermare piuttosto che da conteggi autorevoli.

Funzionamento di una sessione workflow-overview

Ogni sessione di migrazione segue questa sequenza:

  1. Denomina il pattern: specifica un pattern (ad esempio, scheduler)
  2. Fornisci risultati: da un file BPA CSV, CAM tramite MCP o percorsi di file specifici
  3. L’agente legge le regole di trasformazione: l’abilità legge le regole di trasformazione pertinenti dall’abilità code-assessment associata prima di apportare modifiche al codice
  4. Primo batch di cinque: l’agente trasforma fino a cinque risultati e segnala le modifiche apportate
  5. Rivedi e continua: dopo aver esaminato ogni batch, rispondi continue per passare al successivo

L’agente elabora un modello e un batch alla volta. Non procede automaticamente; ogni batch richiede la tua conferma.

Modelli di migrazione patterns

Modulo di pianificazione scheduler

Esegue il targeting delle classi Java utilizzando l’iniezione di sling.commons.scheduler o Scheduler incompatibili con il runtime AEMaaCS senza stato e containerizzato.

ID pattern BPA: scheduler

L’agente converte Scheduler processi inseriti in @Component implementazioni di Runnable utilizzando @Designate, sostituendo la registrazione dell’utilità di pianificazione basata sul costruttore con i metodi del ciclo di vita @Activate / @Deactivate.

ResourceChangeListener resource-change-listener

Destinazioni delle implementazioni del listener ResourceChangeListener o ResourceChange che richiedono aggiornamenti per AEMaaCS.

ID pattern BPA: resourceChangeListener

Replica replication

Destinazione classi che importano com.day.cq.replication.Replicator o API di replica correlate, non supportate in AEMaaCS. L’agente li sostituisce con equivalenti basati su ContentDistribution e aggiorna i riferimenti del servizio OSGi corrispondenti.

ID pattern BPA: replication

Listener di eventi event-listener

Ha come target le implementazioni OSGi EventListener o EventHandler che devono essere aggiornate per la semantica di elaborazione degli eventi AEMaaCS.

ID pattern BPA: eventListener

Gestore di Evento event-handler

Ha come target i servizi OSGi EventHandler sincroni che devono essere adattati per AEMaaCS.

ID pattern BPA: eventHandler

API Asset asset-api

Consente di eseguire il targeting delle classi utilizzando API DAM AssetManager, DAMEvent o non supportate. L’agente li sostituisce con gli equivalenti API di AEM Assets supportati.

ID pattern BPA: assetApi

Cache Guava alla caffeina guava-cache

Destinazione dei bundle che utilizzano la cache di Guava (com.google.common.cache.*, ad esempio Cache, CacheBuilder e LoadingCache). In AEM as a Cloud Service la libreria cache in-process supportata è Caffeina, pertanto l’agente scambia la dipendenza Maven, aggiorna le importazioni e regola i siti di chiamata interessati. Poiché la caffeina è stata scritta dallo stesso autore e la sua API è intenzionalmente quasi identica, il cambiamento è per lo più meccanico.

ID pattern BPA: guavaCache

BPA segnala questo pattern con granularità bundle (sottotipo custom.guava.cache), in modo che l’agente risolva il bundle nei file Java che importano effettivamente la cache Guava e li modifichi. Questo modello viene fornito solo dall’abilità di migrazione, non da code-assessment, perché l’utilizzo della cache Guava avviene solo nel codice trasferito da AEM legacy, mai nel codice nativo di Cloud Service.

NOTE
guavaCache si basa su BPA come fonte di verità. Se non è disponibile alcuna origine BPA o CAM, l'agente esegue il fallback alla scansione dei file Java per import com.google.common.cache importazioni come candidati non confermati.

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

Esegue il targeting dei modelli HTL in ui.apps che generano data-sly-test: redundant constant value comparison avvisi di lint. L’agente rileva i modelli interessati analizzando direttamente il pacchetto di contenuti; questo modello non richiede una connessione BPA CSV o CAM.

ID pattern BPA: htlLint

NOTE
htlLint risultati non vengono visualizzati nelle esportazioni CSV BPA. L'agente li rileva mediante l'analisi diretta dei file quando si avvia una sessione per questo modello.

Configurazioni OSGi per Cloud Manager osgi-cloud-manager

Converte le configurazioni OSGi in ui.config nel formato .cfg.json compatibile con Cloud Manager con una gestione completa specifica dell’ambiente. Ciò riguarda diverse attività correlate:

Conversione formato configurazione

AEMaaCS richiede che le configurazioni OSGi siano memorizzate come file .cfg.json, con configurazioni specifiche per l’ambiente nelle cartelle con ambito di runmode (config.author/, config.publish/, config.dev/ e così via). L’agente:

  • Converte le configurazioni OSGi esistenti di .config, .cfg e in formato XML in .cfg.json
  • Suddivide le configurazioni contenenti valori specifici dell’autore e della pubblicazione in file con ambito di modalità di esecuzione separati
  • Convalida i tipi di proprietà in base alla specifica del metatipo OSGi (stringhe, interi, booleani, array)
  • Segnala i PID di proprietà di Adobe per la revisione manuale anziché per la conversione automatica

Segreti e variabili di ambiente

Sposta i segreti di testo normale e i valori specifici dell’ambiente dai file di configurazione salvati e li sostituisce con i segnaposto di Cloud Manager:

  • $[secret:NAME]: per password, token e altri valori sensibili
  • $[env:NAME]: per valori non sensibili che differiscono per ambiente (ad esempio, URL del servizio)

Le variabili e i segreti corrispondenti vengono applicati in Cloud Manager e inseriti in fase di runtime; nessun valore viene memorizzato nel controllo del codice sorgente.

IMPORTANT
L'agente non restituisce mai valori segreti nella conversazione. Tutti i dati sensibili vengono scritti in un file handoff ignorato da applicare tramite l’API o l’interfaccia utente di Cloud Manager.

Modalità di esecuzione non supportate (URC)

AEM as a Cloud Service supporta un set fisso di identificatori in modalità di esecuzione. Le cartelle di configurazione che utilizzano una modalità di esecuzione non supportata non hanno alcun effetto una volta distribuite. L’agente contrassegna queste configurazioni in modalità di esecuzione (URC) non supportate, tra cui:

  • Token modalità di esecuzione sconosciuti, ad esempio config.qa o install.local
  • Un token di livello che segue invece di precedere il token di ambiente: config.dev.author invece del config.author.dev valido
  • Token non minuscoli, come config.Author.dev, e config.preview riservati (l’anteprima eredita dalla pubblicazione)

I risultati dell’URC provengono innanzitutto da Best Practices Analyzer (sottotipo unsupported.runmode, gravità CRITICAL). Quando nessuna origine BPA li segnala, l’agente analizza le cartelle config.* e install.* localmente come rete di sicurezza. Per ogni risultato vengono segnalati il percorso della cartella, la modalità di esecuzione che causa l’errore e la correzione. Valutare se la configurazione è ancora necessaria, rinominarla in una modalità di esecuzione supportata o rimuoverla se obsoleta. Per le violazioni di solo ordinamento, in cui ogni token è valido ma non in ordine, l’agente può applicare automaticamente un riordino sicuro (ad esempio, rinominando config.dev.author in config.author.dev); token sconosciuti e altri casi ambigui vengono contrassegnati per la risoluzione.

La conversione del formato di configurazione e l’esternalizzazione segreta non richiedono CSV o CAM BPA e il rilevamento URC utilizza i risultati BPA quando disponibili. Avvia una sessione con:

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

Migrazione finestre di dialogo (interfaccia utente legacy) dialog-migration

Converte le finestre di dialogo dell’interfaccia classica in interfaccia touch. L’agente gestisce due sottotipi di finestre di dialogo: le definizioni di ExtJS / Interfaccia classica cq:Dialog vengono ricompilate come strutture di Coral 3 _cq_dialog e le finestre di dialogo di Coral 2 esistenti vengono aggiornate a Coral 3. Trasporta anche i listener, optionsProvider, namePrefix, e gli aggiornamenti filter.xml.

ID pattern BPA: lui (solo sottotipi finestra di dialogo)

Quando esistono risultati sia di finestre di dialogo che di widget personalizzati per gli stessi componenti, esegui prima la migrazione dei widget personalizzati in modo che tutti i riferimenti xtype vengano risolti prima della conversione delle finestre di dialogo.

Convert my Classic UI dialogs to Touch UI Coral 3.

Widget per progettazione personalizzati (interfaccia utente legacy) custom-design-widgets

Esegue la migrazione di widget ExtJS personalizzati (cq:Widget definizioni con valori xtype personalizzati). L’agente archivia i widget, quindi mappa ogni xtype su un equivalente Coral 3 noto o scaffolds un componente modulo dell’interfaccia utente Granite quando non esiste alcuna mappatura diretta.

ID pattern BPA: cdw

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

Modernizzazione modello template-modernization

Converte i modelli statici in modelli modificabili e genera le regole di riscrittura degli strumenti di modernizzazione di AEM corrispondenti (regole per struttura, componente e criteri). L’agente viene eseguito in tre fasi: rileva i modelli e produce un piano per modello, esegue il modello di piano per modello e convalida le strutture /conf generate.

Durante l’individuazione, l’agente esamina i modelli in apps/<appId>/templates/ a qualsiasi profondità, incluse le cartelle di modelli nidificate o raggruppate, e classifica ogni modello statico come legacy o personalizzato in base al tipo di risorsa del componente pagina. Questa classificazione vale anche senza un rapporto BPA, pertanto i modelli personalizzati vengono gestiti in modo distinto da quelli legacy.

Questo modello non utilizza un ID di modello BPA. Avvia una sessione con:

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

Conversione Dispatcher dispatcher-conversion

Converte una configurazione AMS o Apache HTTPD e Dispatcher on-premise nella struttura AEM as a Cloud Service. Questa funzionalità esegue il wrapping dello strumento Dispatcher Converter gestito da Adobe, aggiungendo funzionalità di rilevamento, generazione della configurazione, verifica dell’output e convalida.

L’agente funziona attraverso un flusso graduale:

  1. Rileva e inventario - Determina la configurazione modalità e registra un conteggio di base di regole di filtro, riscrittura e cache. Le modalità riconosciute sono standard (AMS), flexible (monolitico on-premise), v1 (layout meno recenti), already-cloud, not-dispatcher e unknown. Per already-cloud, not-dispatcher o unknown, l’agente si arresta e richiede di confermare prima di continuare.
  2. Pianifica e genera configurazione - Genera la configurazione del convertitore e conferma il piano con te.
  3. Converti - Esegue il convertitore Dispatcher di Adobe (installato automaticamente al primo utilizzo).
  4. Verifica - Verifica l’output rispetto alla linea di base. Un set di filtri svuotato (filter-acl-loss) è un arresto rigido che deve essere risolto prima di continuare.
  5. Handoff transfrontaliero - Indirizza le variabili di ambiente Cloud Manager alla configurazione OSGi e contrassegna i candidati CDN o dell’intestazione di sicurezza.
  6. Convalida - Esegue la convalida di Cloud Service Dispatcher e genera un report di conversione consolidato.

ID pattern Runbook: dispatcherConversion (rilevato euristicamente dal layout di configurazione). Questo modello non utilizza BPA o CAM. Avvia una sessione con:

Convert my AMS / on-prem Dispatcher config to AEM as a Cloud Service.
NOTE
Eseguire questa operazione su una struttura di lavoro pulita in modo che l'output convertito sia facile da rivedere e ripristinare. Il grado di automazione dipende dalla modalità rilevata: le configurazioni di standard (AMS) sono quasi automatizzate, mentre i layout flexible e v1 richiedono un'ulteriore revisione.

Opzioni Source BPA bpa-source

Origine
Quando utilizzare
File CSV BPA
Hai esportato un file CSV dalla tua istanza di AEM o da Cloud Acceleration Manager. Immetti il percorso del file all’avvio della sessione.
CAM tramite MCP
Hai configurato AEM Cloud Migration MCP. L’agente elenca i progetti CAM, l’utente conferma quale utilizzare e i risultati vengono recuperati direttamente. Vedi Utilizzo di Cloud Migration MCP.
Percorsi file manuali
Desideri eseguire la migrazione di file specifici senza un rapporto BPA. Fornisci i percorsi direttamente nella richiesta.

Gestione degli errori MCP mcp-errors

Se la connessione MCP restituisce un errore (inclusi errori di autenticazione o di progetto non trovato), l’agente si arresta e mostra l’errore. Non passa automaticamente a un’altra sorgente. Dallo stato di arresto, è possibile:

  • Conferma il progetto corretto dall’elenco visualizzato dall’agente
  • Fornire un percorso CSV BPA in alternativa
  • Fornire percorsi di file Java specifici per una migrazione manuale

Gestione delle sessioni in report di grandi dimensioni large-reports

Per i rapporti BPA con molti risultati, l’approccio batch per batch consente di convalidare in modo incrementale:

  1. Esamina le differenze per ciascun batch
  2. Eseguire il commit del batch con un messaggio di commit con ambito pattern
  3. Rispondi continue per avviare il batch successivo
  4. Ripeti l’operazione finché l’agente non segnala che tutti i risultati del modello sono stati completati

Un pattern per commit mantiene la cronologia Git leggibile e, se necessario, semplifica il ripristino delle singole trasformazioni del pattern.

NOTE
Se si termina una sessione prima dell'elaborazione di tutti i risultati, riavviare con lo stesso pattern e la stessa origine BPA in una nuova sessione. L'agente riprende dal punto in cui era stato interrotto.

Ambito Workspace workspace-scope

L’agente cerca e modifica i file solo all’interno delle cartelle aperte dell’area di lavoro IDE. Non esegue la scansione delle directory principali, delle cartelle di pari livello o di altre posizioni su disco.

Se un risultato BPA fa riferimento a un percorso di file che non esiste nell’area di lavoro, l’agente si arresta e indica i percorsi mancanti. Apri la cartella del progetto corretta o fornisci i percorsi in modo esplicito per continuare.

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