# 2. Migrazione dalla 20.04.xx alla 24.08 o 26.04
Procedura speciale di migrazione dalla vecchia struttura 20.04 alla nuova struttura modulo vtenext, più aggiornamento ordinario dalla 24.08 alla 26.04.
# Prima di migrare dalla 20.04.xx
La migrazione da una versione della famiglia **20.04.xx** è un passaggio particolare perché Exchange Connector passa dalla vecchia installazione dedicata alla nuova struttura come modulo/estensione vtenext.
## Percorsi di migrazione
- **20.04.xx → 24.08**;
- **20.04.xx → 26.04**.
In entrambi i casi è necessario eseguire una sola volta il passaggio manuale di registrazione del modulo Exchange. Se il connettore è già in versione 24.08, utilizzare invece la procedura [Aggiornare dalla 24.08 alla 26.04](https://manual.vtenext.ch/books/exchange-connector-vtenext/page/aggiornare-dalla-2408-alla-2604).
## Prima di iniziare
Eseguire un backup completo dell'istanza vtenext e annotare la configurazione Exchange esistente. Controllare almeno:
- versione attuale del connettore;
- tipo di Exchange utilizzato;
- moduli sincronizzati;
- utenti che utilizzano il connettore;
- cartelle selezionate dagli utenti;
- mappature personalizzate di Contatti e Aziende;
- eventuali errori di sincronizzazione già presenti.
## Perché serve lo script di registrazione
Lo script registra l'Exchange Connector già esistente come modulo vtlib di vtenext. Non reinstalla il connettore e deve essere eseguito **una sola volta** sull'istanza proveniente dalla famiglia 20.04.xx.
La procedura operativa completa è descritta in [Migrare dalla 20.04.xx alla 24.08 o 26.04](https://manual.vtenext.ch/books/exchange-connector-vtenext/page/migrare-dalla-2004xx-alla-2408-o-2604).
## Se si utilizza Microsoft 365
La nuova generazione utilizza Microsoft Graph per Exchange Online. Prima della migrazione decidere se utilizzare **Proxy vtenext** oppure una **App Microsoft personalizzata**. Differenze, requisiti e configurazione sono descritti in [Configurare Microsoft 365](https://manual.vtenext.ch/books/exchange-connector-vtenext/page/configurare-microsoft-365).
## Se si utilizza Exchange Server
Per Exchange Server on-premise la migrazione della struttura del modulo è comunque necessaria, ma la comunicazione continua a utilizzare EWS. Vedere [Configurare Exchange Server](https://manual.vtenext.ch/books/exchange-connector-vtenext/page/configurare-exchange-server).
# Migrare dalla 20.04.xx alla 24.08 o 26.04
Il passaggio dalla 20.04.xx alla 24.08 o alla 26.04 richiede una procedura speciale perché Exchange Connector deve essere trasformato dalla vecchia installazione in un modulo vtenext registrato.
## 1. Eseguire il backup
**Attenzione**
Prima di iniziare eseguire un backup completo di database e file dell'istanza vtenext e annotare utenti, cartelle e mappature personalizzate.
## 2. Portare l'istanza alla versione vtenext di destinazione
Aggiornare l'istanza vtenext alla versione di destinazione prevista:
- **24.08.xx**
- **25.xx**
- **26.xx**
Utilizzare il pacchetto Exchange Connector previsto per la stessa generazione di vtenext.
## 3. Registrare Exchange Connector come modulo vtenext
Sulle installazioni provenienti dalla 20.04.xx deve essere eseguito una sola volta lo script di registrazione del modulo Exchange.
Lo script previsto è:
`register_exchange_module.php`
Lo script va copiato in `../plugins/script/` ed eseguito via web, ad esempio `https://miocrm.ch/plugins/script/register_exchange_module.php`.
**Operazione critica**
Rimuovere il file `register_exchange_module.php` dalla cartella immediatamente dopo l'esecuzione. Lo script deve essere eseguito una sola volta.
La sua funzione è registrare l'Exchange Connector già presente come modulo/estensione vtlib di vtenext.
Lo script:
- verifica che l'installazione Exchange precedente sia presente;
- registra Exchange Connector nel sistema dei moduli vtenext;
- non ricrea le tabelle Exchange già esistenti;
- non ricrea cron, impostazioni o campi già presenti;
- permette al modulo di comparire nel Module Manager e di essere aggiornato normalmente in futuro.
Per verificare che il plugin sia stato correttamente promosso a modulo, aprire la gestione moduli, sezione **Personalizzati**, e verificare che Exchange Connector sia presente.
[](https://manual.vtenext.ch/uploads/images/gallery/2026-09/PwpDSGkpmYUdqrFQ-immagine.png)
**Verifica**
Se Exchange Connector compare correttamente nel Module Manager, la registrazione del modulo è avvenuta.
## 4. Aggiornare il modulo alla versione di destinazione
Dopo la registrazione, installare/aggiornare Exchange Connector con il pacchetto ZIP previsto per la versione di destinazione.
A questo punto il connettore viene gestito come un normale modulo vtenext.
[](https://manual.vtenext.ch/uploads/images/gallery/2026-09/RADb41uWTc1WTlpd-immagine.png)
[](https://manual.vtenext.ch/uploads/images/gallery/2026-09/wOhg3K7ns0gewS2a-immagine.png)
## 5. Se si utilizza Microsoft 365
Con Microsoft 365 / Exchange Online la nuova versione utilizza Microsoft Graph.
Dopo la migrazione:
1. aprire **Impostazioni > Exchange Connector**;
2. verificare che il tipo di server sia **Office365**;
3. scegliere tra **Proxy vtenext** e **App Microsoft personalizzata**;
4. se si usa una App personalizzata, reinserire i relativi dati di configurazione;
5. salvare;
6. verificare il collegamento degli utenti tramite **Connect**;
7. controllare le cartelle selezionate;
8. eseguire un test di sincronizzazione.
**Vecchie configurazioni Office365**
Nel passaggio alla nuova struttura la configurazione Office365 viene portata verso la modalità Proxy vtenext. Se il cliente vuole utilizzare una propria App Microsoft, Tenant ID, Client ID e Client Secret devono essere riconfigurati dopo la migrazione.
## 6. Se si utilizza Exchange Server
Per Exchange Server on-premise la migrazione strutturale del modulo è la stessa, ma il collegamento continua a utilizzare EWS.
Dopo l'aggiornamento verificare versione Exchange, Mail Server, credenziali utenti, cartelle e sincronizzazione nei due sensi.
## 7. Verifica finale
La migrazione è conclusa quando il modulo compare correttamente nel Module Manager, la versione è quella prevista, utenti e cartelle sono corretti e i test di sincronizzazione nei due sensi hanno esito positivo.
# Aggiornare dalla 24.08 alla 26.04
Se Exchange Connector è già in versione 24.08, il passaggio alla 26.04 è un normale aggiornamento del modulo.
Non è più necessario eseguire lo script di registrazione usato per la migrazione dalla 20.04, perché il connettore è già registrato come modulo/estensione vtenext.
## Procedura
1. Eseguire un backup dell'istanza vtenext.
2. Verificare che Exchange Connector 24.08 funzioni correttamente prima dell'aggiornamento.
3. Utilizzare il pacchetto ZIP Exchange Connector previsto per la versione 26.04.
4. Eseguire il normale aggiornamento del modulo tramite la gestione moduli di vtenext.
[](https://manual.vtenext.ch/uploads/images/gallery/2026-09/mOykXiHOKKsXzicQ-immagine.png)
[](https://manual.vtenext.ch/uploads/images/gallery/2026-09/UsZmIa53Y28LQxIz-immagine.png)
Attendere il completamento dell'aggiornamento.
5. Aprire **Impostazioni > Exchange Connector** e verificare la versione installata.
[](https://manual.vtenext.ch/uploads/images/gallery/2026-09/P3M65eFGLdt16cNP-immagine.png)
6. Controllare che configurazione, utenti, cartelle e mappature siano ancora corretti.
7. Eseguire un test di sincronizzazione nei due sensi.
## Cosa non bisogna fare
Nel passaggio **24.08 → 26.04** non bisogna:
- rieseguire `register_exchange_module.php`;
- trattare il connettore come una vecchia installazione 20.04;
- reinstallare da zero il modulo;
- cancellare configurazioni o utenti prima dell'aggiornamento.
Lo script di registrazione appartiene esclusivamente al primo passaggio dalla vecchia struttura 20.04 alla nuova struttura modulo.
## Controlli dopo l'aggiornamento
Verificare almeno:
- versione del modulo;
- tipo di Exchange configurato;
- stato degli utenti;
- cartelle selezionate;
- mappatura Contatti/Aziende;
- sincronizzazione di un evento di prova;
- sincronizzazione di Contatti e Task, se abilitati.
Se tutto è corretto, gli aggiornamenti successivi della nuova struttura continueranno a essere gestiti come normali aggiornamenti del modulo tramite pacchetto ZIP.
# Microsoft 365: riattivazione temporanea di EWS durante la migrazione
Microsoft sta dismettendo EWS in **Exchange Online / Microsoft 365**. La modifica non riguarda Exchange Server installato presso il cliente.
Per questo motivo, migrando dalla 20.04.xx alla nuova generazione del connettore (**24.08 o 26.04**), Microsoft 365 deve essere portato verso Microsoft Graph.
## Date principali
Dal 1 ottobre 2026
Inizia il blocco progressivo di EWS nei tenant Exchange Online che non hanno configurato esplicitamente l'eccezione prevista.
Dal 1 aprile 2027: disattivazione definitiva
EWS sarà disabilitato definitivamente in Exchange Online e non sarà più possibile riattivarlo tramite la relativa impostazione amministrativa.
## Se durante la migrazione un'integrazione EWS smette di funzionare
Microsoft permette ancora una **riattivazione temporanea** di EWS durante la fase transitoria.
L'amministratore Microsoft 365 può intervenire sull'impostazione `EWSEnabled` e, se necessario, sulla lista delle applicazioni EWS autorizzate.
Soluzione temporanea
La riattivazione EWS serve solo a mantenere operativo il servizio mentre si completa la migrazione verso Microsoft Graph. Non deve essere considerata una soluzione definitiva.
## Indicazione pratica per il connettore vtenext
Se dopo il blocco Microsoft il vecchio connettore 20.04.xx basato su EWS non comunica più con Exchange Online:
1. valutare se riabilitare temporaneamente EWS per evitare un'interruzione immediata;
2. migrare Exchange Connector dalla 20.04.xx alla **24.08 o 26.04** seguendo la procedura specifica di registrazione del modulo;
3. configurare Office365 con Microsoft Graph;
4. ricollegare gli utenti se necessario;
5. verificare la sincronizzazione;
6. rimuovere la dipendenza da EWS appena completata la migrazione.
Se Exchange Connector è già in versione 24.08, il passaggio alla 26.04 non richiede questa migrazione strutturale: si esegue il normale aggiornamento tramite pacchetto ZIP.
## Riferimento Microsoft
https://techcommunity.microsoft.com/blog/exchange/exchange-online-ews-your-time-is-almost-up/4492361
# Controlli dopo migrazione o aggiornamento
Dopo una migrazione dalla 20.04 o un aggiornamento dalla 24.08 alla 26.04, non considerare il lavoro concluso finché non sono stati verificati configurazione, utenti e sincronizzazione.
## Controlli sul modulo
Verificare che:
- Exchange Connector compaia correttamente nel Module Manager;
- la versione installata sia quella prevista;
- il tipo di Exchange sia corretto;
- le funzioni da sincronizzare siano quelle previste;
- la licenza risulti valida;
- non siano presenti errori bloccanti nella pagina Exchange Connector.
Dopo una migrazione dalla 20.04, la presenza del modulo nel Module Manager è un controllo particolarmente importante perché conferma che la registrazione della nuova struttura è avvenuta.
## Controlli sugli utenti
Per ogni utente Exchange verificare:
- stato di collegamento;
- account corretto;
- cartelle corrette;
- eventuali impostazioni Resource o Impersonation;
- assenza di errori di autenticazione.
Per Microsoft 365, se il collegamento non è più valido, ripetere **Connect**.
## Controlli sulla mappatura
Aprire **Exchange Field Mapping** e verificare soprattutto le mappature di:
- Contatti;
- Aziende.
Se erano presenti personalizzazioni nella 20.04, confrontarle prima di modificare o salvare la nuova mappatura.
## Test consigliato
Utilizzare record di prova riconoscibili e verificare almeno:
1. creazione da vtenext verso Exchange;
2. modifica da Exchange verso vtenext;
3. evento ricorrente, se utilizzato;
4. Contatto con e-mail e telefono;
5. Task con stato e scadenza;
6. Azienda, se la relativa sincronizzazione è attiva.
## Quando il passaggio può considerarsi concluso
Il passaggio può considerarsi completato quando:
- il modulo è registrato e aggiornabile normalmente;
- tutti gli utenti previsti risultano collegati;
- i test nei due sensi sono corretti;
- non vengono creati duplicati nei test;
- la mappatura è quella desiderata;
- non sono presenti errori persistenti nella configurazione del connettore.