Exchange Connector vtenext
Manuale operativo per amministratori e utenti vtenext: migrazione dalla 20.04.xx alla nuova struttura 24.08/26.04, aggiornamento 24.08→26.04, configurazione Microsoft 365/Exchange, collegamento utenti, scelta cartelle, mappatura campi, utilizzo e risoluzione dei problemi.
- 1. Introduzione
- 2. Migrazione dalla 20.04.xx alla 24.08 o 26.04
- Prima di migrare dalla 20.04.xx
- Migrare dalla 20.04.xx alla 24.08 o 26.04
- Aggiornare dalla 24.08 alla 26.04
- Microsoft 365: riattivazione temporanea di EWS durante la migrazione
- Controlli dopo migrazione o aggiornamento
- 3. Configurazione del connettore
- Aprire e configurare Exchange Connector
- Configurare Microsoft 365
- Configurare Exchange Server
- Scegliere cosa sincronizzare
- Cambiare tipo di Exchange o modalità di connessione
- 4. Configurazione degli utenti
- Collegare un utente Microsoft 365
- Configurare un utente Exchange Server
- Scegliere o cambiare le cartelle da sincronizzare
- Utenti Resource e Impersonation
- 5. Mappatura dei campi
- Visualizzare la mappatura dei campi
- Modificare una mappatura
- Cosa succede quando si cambia una mappatura
- Esempi di mappatura consigliata
- 6. Uso quotidiano del connettore
- 7. Problemi comuni e controlli
1. Introduzione
A cosa serve il connettore, ambienti supportati e cosa cambia nella versione 24.08.
A cosa serve il connettore
Il connettore Exchange permette di mantenere allineati alcuni dati di vtenext con Microsoft 365 o Microsoft Exchange.
Può essere utilizzato per sincronizzare:
- Calendario / Eventi;
- Attività / Task;
- Contatti;
- Aziende
La sincronizzazione può avvenire in entrambe le direzioni: una modifica fatta in vtenext può essere riportata in Exchange e una modifica fatta in Exchange può essere riportata in vtenext, in base alle funzioni abilitate.
Due modalità di collegamento
La versione 24.08 distingue due casi:
- Microsoft 365 / Exchange Online: utilizza Microsoft Graph;
- Exchange Server installato presso il cliente: utilizza EWS.
Per l'utente finale questa distinzione incide soprattutto sul modo in cui viene configurato l'account:
- con Microsoft 365 l'utente autorizza il collegamento tramite login Microsoft;
- con Exchange Server vengono utilizzate le credenziali Exchange e le cartelle configurate.
Chi configura cosa
L'amministratore vtenext configura il connettore, sceglie cosa sincronizzare e imposta la mappatura dei campi.
Ogni utente deve poi completare il collegamento del proprio account e scegliere le cartelle da utilizzare, quando previsto.
Una volta completata la configurazione, il connettore lavora automaticamente in background.
Cosa cambia dalla 20.04.xx alle versioni 24.08 e 26.04
La differenza più importante rispetto alla versione 20.04 non riguarda soltanto Microsoft Graph: cambia anche il modo in cui il connettore è integrato in vtenext.
Dalla 20.04 alla nuova struttura
Nella versione 20.04 il connettore Exchange era installato con la vecchia procedura dedicata e non era registrato come un normale modulo vtlib di vtenext.
Con le versioni 24.08 e 26.04 il connettore viene invece gestito come un vero modulo/estensione vtenext. Questo permette, dopo il primo passaggio, di gestire gli aggiornamenti successivi con la normale procedura di aggiornamento del modulo.
Per questo motivo il passaggio dalla 20.04 alla 24.08 o alla 26.04 richiede una procedura di migrazione specifica e l'esecuzione una sola volta dello script di registrazione del modulo.
Se si utilizza Microsoft 365
Con la nuova generazione del connettore Microsoft 365 / Exchange Online utilizza Microsoft Graph.
Dopo la migrazione è quindi necessario verificare la configurazione Office365 e il collegamento degli utenti.
Il connettore può essere configurato tramite:
- Proxy vtenext;
- App Microsoft personalizzata.
Se si utilizza Exchange Server
Per Exchange Server installato presso il cliente continua a essere utilizzato EWS.
Sono previste le configurazioni per:
- Exchange 2016;
- Exchange 2019;
- Exchange Server Subscription Edition.
Aggiornamenti successivi
Una volta che il connettore è già nella nuova struttura, ad esempio in versione 24.08, il passaggio alla 26.04 non richiede più lo script di registrazione.
Il passaggio 24.08 → 26.04 viene eseguito come normale aggiornamento del modulo utilizzando il relativo pacchetto ZIP.
Questa distinzione è importante:
- 20.04 → 24.08 o 26.04 = migrazione strutturale;
- 24.08 → 26.04 = aggiornamento normale del modulo.
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.
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.
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.
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.
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
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.
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.
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.
5. Se si utilizza Microsoft 365
Con Microsoft 365 / Exchange Online la nuova versione utilizza Microsoft Graph.
Dopo la migrazione:
- aprire Impostazioni > Exchange Connector;
- verificare che il tipo di server sia Office365;
- scegliere tra Proxy vtenext e App Microsoft personalizzata;
- se si usa una App personalizzata, reinserire i relativi dati di configurazione;
- salvare;
- verificare il collegamento degli utenti tramite Connect;
- controllare le cartelle selezionate;
- eseguire un test di sincronizzazione.
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
- Eseguire un backup dell'istanza vtenext.
- Verificare che Exchange Connector 24.08 funzioni correttamente prima dell'aggiornamento.
- Utilizzare il pacchetto ZIP Exchange Connector previsto per la versione 26.04.
- Eseguire il normale aggiornamento del modulo tramite la gestione moduli di vtenext.
Attendere il completamento dell'aggiornamento.
- Aprire Impostazioni > Exchange Connector e verificare la versione installata.
- Controllare che configurazione, utenti, cartelle e mappature siano ancora corretti.
- 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
Inizia il blocco progressivo di EWS nei tenant Exchange Online che non hanno configurato esplicitamente l'eccezione prevista.
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.
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:
- valutare se riabilitare temporaneamente EWS per evitare un'interruzione immediata;
- migrare Exchange Connector dalla 20.04.xx alla 24.08 o 26.04 seguendo la procedura specifica di registrazione del modulo;
- configurare Office365 con Microsoft Graph;
- ricollegare gli utenti se necessario;
- verificare la sincronizzazione;
- 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:
- creazione da vtenext verso Exchange;
- modifica da Exchange verso vtenext;
- evento ricorrente, se utilizzato;
- Contatto con e-mail e telefono;
- Task con stato e scadenza;
- 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.
3. Configurazione del connettore
Impostazioni principali, scelta del tipo di Exchange e configurazione Microsoft 365 o Exchange Server.
Aprire e configurare Exchange Connector
La configurazione globale è disponibile in Impostazioni > Exchange Connector.
Da questa pagina l'amministratore può impostare il tipo di Exchange utilizzato e scegliere quali dati devono essere sincronizzati.
Requisiti di connettività
Prima di configurare il connettore verificare i requisiti di rete del tipo di Exchange utilizzato. Con Exchange Server/EWS è sufficiente che il server vtenext possa raggiungere Exchange/Microsoft verso Internet: vtenext apre e mantiene il canale di streaming verso Exchange e non è necessario che il CRM sia pubblicamente raggiungibile da Internet. Con Microsoft 365/Graph, invece, l'endpoint vtenext deve essere raggiungibile dai server Microsoft per ricevere le notifiche push degli eventi.
Se vtenext utilizza Microsoft 365/Graph ma non può essere pubblicato o raggiunto da Internet, la gestione standard delle notifiche in ricezione non può funzionare correttamente. Esiste la possibilità di predisporre una sincronizzazione basata su controlli periodici via cron, ma si tratta di una configurazione manuale ad hoc, non prevista come configurazione self-service e fortemente sconsigliata rispetto al funzionamento standard tramite notifiche push.
Attivazione della licenza
Se il connettore non è ancora attivo, la pagina richiede l'inserimento della chiave di licenza.
Inserire la chiave fornita e premere Verifica. Una volta validata, si accede alla configurazione completa.
Se la licenza risulta non valida, verificare che la chiave sia stata copiata correttamente prima di procedere.
Impostazioni principali
Le impostazioni da verificare sono:
- Exchange Version;
- sincronizzazione Eventi;
- sincronizzazione Contatti;
- sincronizzazione Task;
- sincronizzazione Aziende;
- eventuale eliminazione dei Contatti per utenti inattivi;
- modalità di connessione Microsoft 365, quando si utilizza Office365.
Scelta della versione Exchange
Selezionare il valore corrispondente all'ambiente utilizzato:
- Office365 per Microsoft 365 / Exchange Online;
- Exchange 2016;
- Exchange 2019;
- Exchange SE per Exchange Server Subscription Edition.
La scelta della versione è importante perché determina il tipo di collegamento utilizzato dal connettore.
Prima di salvare
Verificare che il tipo di Exchange sia corretto e che siano abilitate soltanto le funzioni che si desidera realmente sincronizzare.
Dopo il salvataggio passare alla configurazione degli utenti.
Configurare Microsoft 365
Per Microsoft 365 / Exchange Online selezionare Office365 come versione Exchange.
Quando il campo Mail Server è vuoto, il connettore propone normalmente outlook.office365.com.
Requisito di rete per Microsoft Graph
Con Microsoft 365/Graph il connettore utilizza notifiche push per ricevere gli eventi e le modifiche da Microsoft. L'endpoint pubblico di vtenext utilizzato dal connettore deve quindi essere raggiungibile via Internet dai server Microsoft. Se Microsoft non riesce a raggiungere l'endpoint, la gestione standard degli eventi in ricezione non funziona correttamente.
Prima di mettere in produzione il connettore verificare quindi che l'istanza vtenext sia pubblicata in modo corretto, raggiungibile dall'esterno tramite HTTPS e che firewall, reverse proxy o altri sistemi di sicurezza non impediscano a Microsoft di contattare l'endpoint del connettore.
È tecnicamente possibile predisporre manualmente una modalità di sincronizzazione basata su controlli periodici via cron anziché sulle notifiche push. Questa configurazione è fortemente sconsigliata, non rappresenta il funzionamento standard del connettore e non è prevista come configurazione self-service: richiede una configurazione specifica ad hoc.
Scegliere la modalità di collegamento
Sono disponibili due modalità.
È la modalità più semplice quando non si vuole configurare e gestire direttamente una propria applicazione Microsoft. Non richiede l'inserimento manuale di Tenant ID, Client ID e Client Secret. Ogni utente dovrà comunque effettuare il proprio login Microsoft tramite Connect.
App Microsoft personalizzata
Utilizzare questa modalità quando il cliente vuole gestire direttamente la propria applicazione nel tenant Microsoft.
Devono essere inseriti:
- Tenant ID;
- Client ID;
- Client Secret.
L'app Microsoft deve essere configurata con il redirect URI dell'istanza vtenext:
https://VOSTRO-VTENEXT/modules/Exchange/oAuth2/AuthorizationCode.php
Sostituire https://VOSTRO-VTENEXT con l'indirizzo reale del CRM.
Permessi richiesti
L'app deve consentire all'utente di autorizzare l'accesso a:
- Calendario;
- Contatti;
- Attività / To Do;
- accesso offline necessario al rinnovo della sessione.
L'autorizzazione è delegata al singolo utente: ogni utente collega il proprio account Microsoft.
Attenzione quando si cambia modalità
Se si passa da Proxy vtenext ad App personalizzata, o viceversa, i collegamenti Microsoft esistenti devono essere riautorizzati.
Dopo il cambio:
- salvare la nuova configurazione;
- aprire i profili degli utenti Exchange;
- ripetere Connect;
- verificare nuovamente le cartelle;
- eseguire un test di sincronizzazione.
Programmare prima la riautorizzazione degli utenti e i test di verifica.
Configurare Exchange Server
Se il cliente utilizza un server Exchange installato presso la propria infrastruttura, selezionare la versione corretta:
- Exchange 2016;
- Exchange 2019;
- Exchange SE per Exchange Server Subscription Edition.
Requisiti di rete con EWS
Con Exchange Server/EWS il connettore utilizza il sistema di streaming degli eventi: è vtenext ad aprire verso Exchange la connessione necessaria e a mantenerla attiva per ricevere gli aggiornamenti. Per questo motivo il CRM può anche non essere raggiungibile pubblicamente via web.
Il requisito fondamentale è che il server vtenext possa raggiungere il server Exchange e disponga quindi della connettività in uscita necessaria. Non è invece richiesto un collegamento in ingresso da Exchange verso un endpoint pubblico di vtenext.
Mail Server
Nel campo Mail Server indicare il server Exchange utilizzato dall'azienda.
L'indirizzo deve essere raggiungibile dal server vtenext.
Credenziali utenti
Con Exchange Server ogni utente utilizza normalmente le proprie credenziali Exchange.
Le credenziali vengono configurate nel profilo utente, non nella pagina generale del connettore.
Cartelle
Dopo avere inserito credenziali valide, l'utente deve selezionare le cartelle da utilizzare per:
- Calendario;
- Attività;
- Contatti.
Il connettore può mostrare sia le cartelle principali sia eventuali cartelle personalizzate disponibili nella mailbox.
Resource e Impersonation
Se il cliente utilizza mailbox di risorsa o accesso tramite impersonation, queste opzioni devono essere configurate solo se l'ambiente Exchange è già predisposto per questo tipo di accesso.
Attivare il flag in vtenext non assegna automaticamente i permessi necessari sul server Exchange.
Verifica consigliata
Dopo la configurazione:
- testare username e password;
- selezionare le cartelle;
- salvare l'utente;
- verificare un evento in entrambe le direzioni;
- verificare Contatti e Task se abilitati.
Scegliere cosa sincronizzare
Nella configurazione del connettore è possibile abilitare o disabilitare separatamente le principali funzioni di sincronizzazione.
Eventi / Calendario
Abilitare questa funzione se gli appuntamenti e gli eventi devono essere mantenuti allineati tra vtenext ed Exchange.
È consigliato verificare anche il comportamento degli eventi ricorrenti e, con Microsoft 365, degli eventuali meeting online.
Contatti
Abilitare la sincronizzazione Contatti quando i contatti personali o aziendali devono essere disponibili anche in Exchange.
Per i Contatti è possibile scegliere quale utente vtenext deve essere utilizzato come riferimento di sincronizzazione.
La mappatura dei campi determina quali informazioni vengono effettivamente trasferite, ad esempio e-mail, telefono, indirizzo e altri dati.
Task / Attività
Abilitare questa funzione se le attività devono essere sincronizzate con le attività Microsoft / Exchange.
Con Microsoft 365 la cartella attività corrisponde a una lista To Do scelta dall'utente.
Aziende
La sincronizzazione Aziende permette di trasferire i dati aziendali secondo la mappatura configurata.
Anche per le Aziende è possibile scegliere un utente di riferimento per la sincronizzazione.
Utente specifico o "same as entity"
Per Contatti e Aziende la configurazione può prevedere:
- un utente specifico;
- same as entity, per mantenere il comportamento legato all'assegnatario del record.
La scelta deve essere coerente con il modo in cui l'azienda gestisce proprietà e condivisione. Scegliendo un utente specifico tutti record saranno sincornizzati su una casella predefinita. Questo può permettere poi a livello di exchange di creare liste condivise
Contatti e utenti inattivi
L'opzione relativa all'eliminazione dei Contatti per utenti inattivi deve essere attivata solo se questo comportamento è realmente desiderato.
Prima di abilitarla in un ambiente con Contatti condivisi, effettuare un test su un utente e su pochi record.
Regola pratica
Non abilitare una funzione solo perché disponibile. È preferibile sincronizzare soltanto i moduli realmente utilizzati e verificare prima la relativa mappatura.
Cambiare tipo di Exchange o modalità di connessione
Cambiare il tipo di Exchange su un connettore già in uso deve essere considerato una migrazione della configurazione.
Non cambiare il tipo di Exchange o la modalità di connessione direttamente in produzione senza pianificare l'intervento. Il cambio può richiedere una nuova autenticazione degli utenti, una nuova selezione delle cartelle e un nuovo allineamento.
Passare da Exchange Server a Microsoft 365, o viceversa
Quando il cambio porta da una modalità Exchange Server a Office365, oppure da Office365 a Exchange Server, vtenext mostra un messaggio di conferma.
Confermando il cambio, il connettore resetta lo stato di collegamento necessario alla sincronizzazione.
In pratica, dopo il salvataggio è necessario verificare nuovamente gli utenti perché possono dover:
- effettuare di nuovo l'accesso;
- reinserire o verificare le credenziali;
- scegliere nuovamente le cartelle;
- attendere un nuovo allineamento del connettore.
Le mappature dei campi e i record vtenext non vengono cancellati semplicemente perché si cambia provider.
Passare da Proxy vtenext ad App personalizzata
Passando da Proxy vtenext ad App personalizzata, o viceversa, le autorizzazioni Microsoft esistenti devono essere rifatte dagli utenti.
Procedura consigliata:
- scegliere la nuova modalità;
- compilare i dati dell'app, se necessari;
- salvare e confermare l'avviso;
- aprire ogni utente Exchange;
- eseguire nuovamente Connect;
- controllare le cartelle;
- effettuare un test di sincronizzazione.
Quando fare il cambio
Effettuare il cambio in un momento controllato, evitando contemporaneamente:
- importazioni massive;
- cambi di mappatura;
- modifiche massive dei record;
- spostamenti di grandi quantità di elementi tra cartelle Exchange.
È preferibile completare prima il cambio del provider e verificare che la sincronizzazione sia stabile, quindi eseguire eventuali altre modifiche.
4. Configurazione degli utenti
Collegamento degli utenti, autenticazione Microsoft 365, credenziali Exchange e scelta delle cartelle.
Collegare un utente Microsoft 365
Con Microsoft 365 l'utente collega il proprio account direttamente dal profilo vtenext.
Procedura
- Aprire il profilo dell'utente.
- Individuare la sezione Exchange.
- Premere Connect.
- Accedere con l'account Microsoft corretto.
- Confermare l'autorizzazione richiesta.
- Tornare a vtenext.
- Se richiesto, scegliere le cartelle da sincronizzare.
- Salvare.
Quando il collegamento è completo e le cartelle sono configurate, il profilo mostra lo stato Connected.
Quale account utilizzare
Se non è configurata l'impersonation, è obbligatorio che l'indirizzo e-mail presente nel profilo vtenext corrisponda all'account Microsoft che deve essere collegato.
Non utilizzare due utenti vtenext con lo stesso indirizzo e-mail: può causare problemi di sincronizzazione e nella gestione degli inviti di calendario, in particolare con utenti esterni a vtenext o all'azienda.
Avviso quando l'accesso Microsoft scade
Nelle nuove versioni Exchange Connector controlla lo stato delle autorizzazioni Microsoft 365. Se uno o più account risultano disconnessi o l'accesso Microsoft è scaduto, nel Calendario vtenext viene mostrato un avviso popup.
L'avviso elenca gli account per i quali l'accesso Exchange è scaduto e rende disponibile il comando Renew access. L'utente deve rinnovare l'autorizzazione per ripristinare il normale collegamento con Microsoft 365.
Quando compare l'avviso:
- individuare l'account indicato come Exchange access expired;
- premere Renew access;
- completare nuovamente il login Microsoft e l'autorizzazione;
- tornare in vtenext e verificare che l'avviso non venga più mostrato;
- eseguire un test di sincronizzazione se l'account è rimasto disconnesso per un periodo significativo.
Se compare ancora Connect o il rinnovo non riesce
Verificare che il login Microsoft venga completato fino al ritorno a vtenext, che la sessione vtenext non sia scaduta e che la configurazione Office365 sia corretta. Per i controlli completi vedere L'utente non riesce a collegarsi.
Quando ripetere il collegamento
Ripetere Connect o Renew access quando l'autorizzazione Microsoft è scaduta o revocata, dopo un reset della configurazione Exchange oppure quando richiesto dal supporto. Se viene cambiata la modalità Proxy/App personalizzata, seguire invece la procedura descritta in Cambiare tipo di Exchange o modalità di connessione.
Configurare un utente Exchange Server
Con Exchange Server l'utente viene configurato dal proprio profilo vtenext utilizzando le credenziali Exchange.
Dati da compilare
Verificare almeno:
- Exchange Username;
- Exchange Password;
- eventuale Exchange Sync Date;
- cartelle Exchange;
- eventuali opzioni Is Resource o Impersonation, se realmente utilizzate.
Test delle credenziali
Dopo avere inserito username e password, salvando le preferenze utente il connettore proverà ad effettuare il login nel server. se andrà a buon fine il profilo verrà salvato senza alcun problema, se invece le credenziali non sono corrette o ci sono altre problematiche il sistema lo segnalerà impedendo di salvare.
Se il test segnala che nome utente o password sono errati, correggere prima le credenziali. Non serve continuare a modificare cartelle o riavviare la sincronizzazione finché il login Exchange non funziona.
Scelta delle cartelle
Una volta verificato l'accesso, scegliere le cartelle da utilizzare per:
- Calendario;
- Attività;
- Contatti.
Il connettore può mostrare sia le cartelle principali sia eventuali cartelle personalizzate presenti nella mailbox.
Dopo il salvataggio
Eseguire un test semplice:
- creare un evento in vtenext;
- verificare che arrivi nella cartella calendario scelta;
- modificarlo in Exchange;
- verificare che la modifica torni in vtenext.
Ripetere poi il controllo per gli altri moduli abilitati.
Cambio password Exchange
Se l'utente cambia password sul server Exchange, aggiornare anche la password nel profilo vtenext.
Fino a quando la password non viene aggiornata, la sincronizzazione dell'utente può interrompersi.
Scegliere o cambiare le cartelle da sincronizzare
Per ogni utente il connettore utilizza una cartella specifica per ciascun tipo di dato.
Normalmente vengono scelte:
- una cartella Calendario;
- una cartella Attività / Task;
- una cartella Contatti.
Microsoft 365
Dopo il collegamento con Connect, vtenext mostra le cartelle disponibili nell'account Microsoft.
Per le Attività vengono mostrate le liste Microsoft To Do disponibili; la lista Flagged Emails non viene utilizzata come cartella di sincronizzazione.
Per i Contatti è disponibile anche la cartella principale dei Contatti.
Exchange Server
Con Exchange Server vengono mostrate le cartelle principali e, quando disponibili, le cartelle personalizzate della mailbox.
Quale cartella scegliere
Scegliere una cartella dedicata e facilmente riconoscibile quando si vuole separare i dati gestiti da vtenext dagli altri dati personali dell'utente.
Se invece il processo aziendale prevede l'uso della cartella principale, selezionarla consapevolmente sapendo che le modifiche effettuate lì possono essere sincronizzate con vtenext.
Le cartelle di sincronizzazione di un utente posso essere create anche direttamente dall'interfaccia di selezione
Cambiare una cartella già utilizzata
Le cartelle di sincronizzazione di un utente già operativo non devono essere cambiate direttamente. La modifica richiede l'intervento dell'amministratore e deve essere preventivamente concordata e pianificata con il proprio vendor o partner vtenext.
Quando una cartella è già stata utilizzata per la sincronizzazione, vtenext ed Exchange hanno memorizzato le corrispondenze tra le entità sincronizzate. Cambiare semplicemente la cartella può quindi causare conflitti, duplicazioni o comportamenti non corretti sui record già sincronizzati, ad esempio Contatti, Eventi e Attività.
La procedura deve essere pianificata e prevede, in linea generale:
- identificare gli utenti e le cartelle interessate;
- concordare l'intervento con il proprio vendor o partner vtenext;
- interrompere o controllare la sincronizzazione durante l'intervento;
- eliminare le informazioni relative ai record precedentemente sincronizzati con Exchange, secondo la procedura prevista dall'amministratore;
- selezionare le nuove cartelle di sincronizzazione;
- riavviare la sincronizzazione in modo controllato;
- verificare il risultato con record di test prima di considerare conclusa l'operazione.
Su un'installazione in produzione non cambiare le cartelle e non eliminare record o riferimenti di sincronizzazione senza una procedura concordata. L'operazione deve essere valutata caso per caso per evitare perdita di associazioni, duplicazioni o conflitti tra vtenext ed Exchange.
Utenti Resource e Impersonation
Le opzioni Is Resource e Impersonation servono solo in configurazioni particolari e non devono essere abilitate per tutti gli utenti.
Is Resource
Utilizzare Is Resource quando il profilo vtenext rappresenta una risorsa Exchange, ad esempio una mailbox o un calendario dedicato a una sala, un'attrezzatura o un'altra risorsa aziendale.
Se l'utente rappresenta una normale persona con la propria mailbox, normalmente questa opzione non è necessaria.
Impersonation
Utilizzare Impersonation quando il collegamento Exchange è stato predisposto per permettere a un account di operare sulla mailbox di un altro utente o di una risorsa.
Questa funzione richiede che i relativi permessi siano già configurati in Microsoft/Exchange. Abilitare la casella in vtenext non crea automaticamente tali permessi.
Prima di utilizzare queste opzioni
Verificare con l'amministratore Microsoft/Exchange:
- quale mailbox deve essere sincronizzata;
- quale account deve effettuare l'accesso;
- se sono già presenti i permessi necessari;
- quali cartelle devono essere utilizzate.
Se non esiste una configurazione specifica di questo tipo, utilizzare il normale collegamento un utente vtenext ↔ una mailbox Exchange.
5. Mappatura dei campi
Come leggere e modificare la mappatura tra vtenext ed Exchange e cosa accade dopo una modifica.
Visualizzare la mappatura dei campi
La mappatura stabilisce quale campo Exchange corrisponde a quale campo vtenext.
Per esempio, il campo e-mail di Exchange può essere collegato al campo E-mail del Contatto vtenext, il telefono business al telefono aziendale e così via.
Dove si trova
Aprire Impostazioni > Exchange Field Mapping.
La pagina permette di scegliere il modulo e mostra per ogni riga:
- il campo Exchange;
- il campo vtenext associato.
Moduli disponibili
La configurazione contiene mappature per:
- Contatti;
- Aziende;
- Calendario / Eventi;
- Task.
Nella normale interfaccia della versione 24.08 la modifica personalizzata è disponibile per Contatti e Aziende. Le mappature di Calendario e Task sono visualizzabili ma non vengono modificate con lo stesso pulsante di editing.
Campi bloccati
Alcune righe sono definite come obbligatorie o strutturali e vengono mostrate come locked.
Questi campi non possono essere modificati dalla pagina di mappatura.
Prima di modificare
Prima di premere Modifica è consigliato:
- annotare o acquisire uno screenshot della mappatura attuale;
- verificare se il modulo è già in uso da molti utenti;
- identificare quali campi sono realmente necessari;
- leggere la pagina Cosa succede quando si cambia una mappatura.
Una modifica della mappatura non è solo una modifica grafica: può provocare una nuova sincronizzazione dei record interessati.
Modificare una mappatura
La modifica della mappatura è disponibile per Contatti e Aziende.
Salvare uno screenshot della mappatura attuale e verificare la pagina Cosa succede quando si cambia una mappatura.
Procedura
- Aprire Impostazioni > Exchange Field Mapping.
- Selezionare Contatti oppure Aziende.
- Premere Modifica.
- Per ogni riga scegliere il campo Exchange e il campo vtenext corrispondente.
- Se serve una nuova associazione, utilizzare Aggiungi mappatura.
- Controllare tutte le righe.
- Premere Salva e confermare l'avviso.
Regole applicate dalla pagina
Tipi di campo compatibili
Un campo Exchange può essere associato soltanto a campi vtenext di tipo compatibile.
Un campo non può essere usato due volte
Lo stesso campo Exchange o vtenext non può essere riutilizzato in due associazioni diverse.
Campo e-mail obbligatorio
Per Contatti e Aziende deve essere presente una corrispondenza per il campo Exchange E-mail principale (EMAIL_ADDRESS_1). Se manca, il salvataggio viene bloccato.
Campi locked
Le righe contrassegnate come bloccate non possono essere modificate.
Usare --None--
Quando una coppia di campi non deve essere sincronizzata, è possibile lasciarla su --None--.
Prima di premere Salva
Il pulsante Salva non modifica soltanto la configurazione: per Contatti e Aziende può avviare una ricostruzione della sincronizzazione Exchange. Leggere la pagina successiva prima di procedere in produzione.
Cosa succede quando si cambia una mappatura
Cambiare e salvare la mappatura di Contatti o Aziende ha un effetto operativo importante.
La modifica della mappatura deve essere considerata una riscostruzione della sincronizzazione, non una semplice modifica di configurazione.
Effetto del salvataggio
Quando il modulo è attivo e la nuova mappatura viene salvata, il connettore non si limita ad applicarla ai record futuri.
Per gli utenti Exchange abilitati, il connettore procede a rimuovere da Exchange le copie dei Contatti o delle Aziende già sincronizzate e a ripubblicarle da vtenext utilizzando la nuova mappatura.
I record originali in vtenext non vengono cancellati dalla modifica della mappatura: la ricostruzione riguarda le copie sincronizzate su Exchange.
Cosa può notare l'utente
Durante questa operazione è possibile che:
- i record interessati scompaiano temporaneamente da Exchange;
- vengano poi ricreati con i nuovi campi;
- la risincronizzazione richieda tempo se i record o gli utenti sono numerosi;
- gli identificativi Exchange delle copie ricreate cambino;
- eventuali modifiche contemporanee rendano più difficile capire quale versione del dato sia corretta.
Procedura consigliata in produzione
Eseguire la modifica in un momento controllato, preferibilmente dopo un test, e conservare uno screenshot della mappatura precedente.
Prima di modificare la mappatura:
- salvare uno screenshot della configurazione attuale;
- verificare che non siano in corso importazioni o modifiche massive;
- scegliere un momento con poca attività degli utenti;
- se possibile, provare prima la nuova mappatura in un ambiente di test;
- verificare che l'e-mail principale sia correttamente mappata;
- salvare la nuova configurazione;
- lasciare completare la risincronizzazione;
- controllare alcuni record campione su vtenext e su Exchange.
Se si cambia un solo campo
Anche una modifica apparentemente piccola viene salvata come nuova configurazione del modulo. Non bisogna quindi presumere che venga aggiornato soltanto quel singolo campo sui record esistenti.
Se qualcosa non è corretto dopo il cambio
Attendere il completamento della risincronizzazione e verificare prima la configurazione salvata, il collegamento degli utenti e alcuni record campione.
Esempi di mappatura consigliata
La configurazione iniziale contiene già una serie di associazioni utili. Prima di personalizzarle è consigliato partire da queste e modificare soltanto ciò che serve realmente al processo aziendale.
Esempio Contatti
Tra le associazioni predefinite più comuni troviamo:
| Exchange | vtenext |
|---|---|
| Cognome | Cognome |
| Nome | Nome |
| E-mail principale | |
| Telefono business | Telefono |
| Cellulare | Cellulare |
| Telefono casa | Telefono casa |
| Fax business | Fax |
| Reparto | Reparto |
| Qualifica | Titolo |
| Compleanno | Data di nascita |
| Indirizzo business | Indirizzo di spedizione principale |
| Altro indirizzo | Altro indirizzo |
Il campo E-mail principale deve rimanere associato a un campo e-mail vtenext valido per poter salvare la mappatura.
Esempio Aziende
Tra le associazioni predefinite più comuni troviamo:
| Exchange | vtenext |
|---|---|
| Nome azienda | Nome Azienda |
| E-mail principale | |
| Telefono business | Telefono |
| Descrizione | Descrizione |
| Indirizzo business | Indirizzo fatturazione |
| Altro indirizzo | Indirizzo spedizione |
Il Nome Azienda è una delle associazioni strutturali e non va modificato come una normale riga libera.
Quando aggiungere un campo personalizzato
Aggiungere una nuova associazione solo se:
- il dato è realmente utilizzato dagli utenti;
- il campo vtenext ha un tipo compatibile;
- il dato deve essere visibile anche in Exchange;
- è chiaro quale sistema deve essere considerato la fonte corretta del dato.
Evitare mappature eccessive
Sincronizzare molti campi non utilizzati rende più difficile capire perché un valore è cambiato.
È preferibile una mappatura più semplice e chiara, composta dai dati realmente necessari al processo.
6. Uso quotidiano del connettore
Come si comporta la sincronizzazione durante l'uso normale e cosa aspettarsi per eventi, attività, contatti e aziende.
Come avviene la sincronizzazione
Dopo la configurazione, il connettore lavora automaticamente in background e può mantenere allineati i dati nei due sensi.
Sincronizzazione nei due sensi
Quando una funzione è abilitata, il connettore può gestire modifiche da vtenext verso Exchange e da Exchange verso vtenext. Il comportamento effettivo dipende dal modulo abilitato, dalla cartella scelta e dalla mappatura configurata.
Come vengono ricevute le modifiche
Il meccanismo cambia tra Exchange Server/EWS e Microsoft 365/Graph. I requisiti di rete e la differenza tra streaming EWS e notifiche push Graph sono descritti nella pagina Aprire e configurare Exchange Connector.
Per i requisiti specifici vedere anche Configurare Microsoft 365 oppure Configurare Exchange Server.
La sincronizzazione non è sempre immediata
Normalmente le modifiche vengono recepite rapidamente, ma possono esserci alcuni minuti di differenza tra un sistema e l'altro. Il connettore esegue anche controlli periodici per recuperare modifiche che non sono state elaborate al primo tentativo.
Se una modifica non compare immediatamente, attendere il normale ciclo di sincronizzazione prima di ripetere la stessa operazione più volte.
Primo collegamento di un utente
Dopo avere collegato un nuovo utente o dopo una migrazione, il primo allineamento può richiedere più tempo. La durata dipende dal numero di record e utenti, dalla presenza di eventi ricorrenti e dalla velocità della connessione con Microsoft/Exchange.
Evitare modifiche massive durante il primo allineamento
Durante il primo ciclo evitare importazioni massive, cambi di mappatura, modifiche massive degli assegnatari o spostamenti di grandi quantità di elementi tra cartelle Exchange. Prima verificare che la sincronizzazione normale sia stabile.
Come verificare che funzioni
Utilizzare un record di prova facilmente identificabile:
- crearlo in vtenext;
- verificare che compaia in Exchange;
- modificarlo in Exchange;
- verificare il ritorno della modifica in vtenext.
Questo test è più affidabile che controllare un record storico di cui non si conoscono tutte le modifiche precedenti.
Eventi, ricorrenze e riunioni online
La sincronizzazione Calendario mantiene allineati gli eventi tra vtenext ed Exchange quando la funzione Eventi è attiva.
Creazione e modifica
Un evento creato o modificato in vtenext viene inviato al calendario Exchange dell'utente.
Allo stesso modo, una modifica effettuata nell'evento Exchange può essere riportata in vtenext.
Per i test è consigliato utilizzare eventi con oggetto facilmente riconoscibile, ad esempio TEST EXCHANGE - NON USARE.
Cancellazioni
Le cancellazioni vengono gestite dal connettore, ma prima di verificare questo comportamento in produzione è consigliato fare un test con un evento creato appositamente.
Non utilizzare un appuntamento reale come primo test di cancellazione.
Eventi ricorrenti
Il connettore gestisce anche gli eventi ricorrenti.
Per le serie senza una data di fine, vtenext mantiene progressivamente le occorrenze future necessarie alla sincronizzazione.
Dopo una migrazione o una modifica importante, testare almeno:
- una serie settimanale;
- una modifica alla serie;
- una modifica a una singola occorrenza, se questo caso viene utilizzato dagli utenti.
Microsoft 365 e riunioni Microsoft Teams
Nelle nuove versioni di Exchange Connector, quando il connettore è configurato con Microsoft 365 / Exchange Online, è possibile creare e gestire una riunione online Microsoft Teams e utilizzare il relativo link Teams direttamente nell'evento sincronizzato.
La funzionalità è disponibile con Microsoft 365 tramite Microsoft Graph. Non è disponibile con Exchange Server on-premise tramite EWS.
Quando il processo aziendale utilizza Microsoft Teams, verificare che:
- l'evento venga creato correttamente;
- il link Teams venga generato e sia disponibile dove previsto;
- una modifica dell'evento non elimini il collegamento alla riunione.
Se un evento sembra duplicato
Prima di cancellare manualmente uno dei due eventi verificare:
- se l'utente è stato ricollegato di recente;
- se sono state cambiate le cartelle;
- se è appena avvenuta una migrazione EWS → Graph;
- se sono state eseguite importazioni o modifiche massive.
Evitare di continuare a creare nuovi eventi di prova finché non è stata identificata la causa.
Attività, Contatti e Aziende
Oltre al Calendario, il connettore può sincronizzare Attività, Contatti e Aziende quando le relative funzioni sono abilitate.
Attività / Task
Le Attività vengono sincronizzate con la cartella scelta dall'utente; con Microsoft 365 corrisponde a una lista Microsoft To Do. Durante i test verificare oggetto, scadenza, stato e modifiche nei due sensi.
Contatti e Aziende
I campi trasferiti dipendono dalla mappatura configurata. Per conoscere e modificare le associazioni vedere Visualizzare la mappatura dei campi ed Esempi di mappatura consigliata.
Se un campo non è presente nella mappatura, non deve essere considerato automaticamente sincronizzato.
Assegnatario e utente di sincronizzazione
Per Contatti e Aziende l'amministratore può configurare un utente specifico oppure il comportamento same as entity. Se un record non viene sincronizzato con l'utente atteso, verificare questa impostazione e l'assegnatario del record.
Dopo una modifica della mappatura
Il salvataggio di una nuova mappatura può avere effetti sui record già sincronizzati. Prima di intervenire in produzione leggere Cosa succede quando si cambia una mappatura.
7. Problemi comuni e controlli
Controlli da eseguire quando un utente non si collega o i dati non si sincronizzano correttamente.
L'utente non riesce a collegarsi
Quando un utente non riesce a collegare Exchange, verificare prima se il problema riguarda Microsoft 365 oppure Exchange Server.
Microsoft 365
La procedura normale di collegamento, lo stato Connected e il rinnovo di un'autorizzazione scaduta sono descritti in Collegare un utente Microsoft 365.
Se compare Exchange synchronization requires your attention con Exchange access expired, utilizzare Renew access. Non è necessario riconfigurare il connettore globale come prima azione.
Se Connect o Renew access non completano il collegamento, controllare l'account Microsoft utilizzato, la sessione vtenext e la configurazione Office365. Per Proxy/App personalizzata e relativi parametri vedere Configurare Microsoft 365.
Exchange Server
Se il test dell'utente Exchange Server fallisce, verificare Exchange Username, Exchange Password, Mail Server, raggiungibilità del server Exchange ed eventuali permessi Resource/Impersonation. La configurazione completa è descritta in Configurare un utente Exchange Server.
Un errore 401 corrisponde normalmente a credenziali non accettate dal server.
Dopo la correzione
- salvare la configurazione o il profilo utente;
- ripetere il collegamento o il test delle credenziali;
- verificare le cartelle;
- creare un solo record di prova;
- controllare la sincronizzazione nei due sensi.
I dati non si sincronizzano
Se l'utente risulta collegato ma un record non viene sincronizzato, controllare prima configurazione e contesto del record.
Controlli iniziali
Verificare:
- che il modulo interessato sia abilitato nel connettore;
- che l'utente sia collegato correttamente;
- che sia stata scelta la cartella corretta;
- che il record appartenga all'utente previsto;
- che, per Contatti o Aziende, la mappatura contenga il campo che si sta controllando;
- che non sia appena iniziata una prima sincronizzazione o una risincronizzazione.
Il record esiste ma un campo non cambia
Per Contatti e Aziende verificare la mappatura.
Se il campo non è mappato, il connettore non può trasferirne il valore.
Se la mappatura è stata modificata di recente, attendere il completamento della risincronizzazione prima di cambiare nuovamente la configurazione.
Funziona in una direzione ma non nell'altra
Eseguire due test separati:
- creare/modificare un record in vtenext e controllare Exchange;
- modificare lo stesso record in Exchange e controllare vtenext.
Se una sola direzione non funziona, annotare esattamente quale passaggio fallisce. Questa informazione permette di distinguere più facilmente un problema di invio da un problema di ricezione.
Il problema riguarda un solo utente
Se gli altri utenti funzionano, controllare prima:
- collegamento dell'utente;
- credenziali o login Microsoft;
- cartelle selezionate;
- assegnatario dei record;
- eventuale Resource/Impersonation.
Il problema riguarda tutti gli utenti
Se nessun utente sincronizza, controllare prima la configurazione globale e i processi automatici del connettore.
Non scollegare tutti gli utenti come prima azione: se il problema è globale, la riautorizzazione non risolve la causa.
Controllare i processi automatici
Il connettore utilizza processi automatici per mantenere attiva la sincronizzazione e gestire le ricorrenze.
Nella pagina Impostazioni > Exchange Connector è possibile controllarne lo stato.
Processi principali
Sono presenti due attività principali:
- ExchangeControlCron: gestisce la normale sincronizzazione e i controlli Exchange;
- InfiniteRecurrencesCron: gestisce l'estensione degli eventi ricorrenti senza data di fine.
Dopo una nuova installazione i processi possono essere inizialmente disattivati e devono essere abilitati solo dopo avere completato la configurazione.
Cosa controllare
Per ogni processo verificare:
- che sia Attivo;
- che Last Run sia aggiornato;
- che lo stato non rimanga bloccato;
- che il numero di tentativi non continui ad aumentare.
Se il processo è disattivato
Dopo avere verificato che il connettore sia configurato correttamente, utilizzare Activate.
Se il problema è stato corretto ma il processo non riparte
Dopo avere risolto la causa dell'errore è possibile usare Reset Status, Reset Attempts e infine Run Now per un controllo immediato.
Quando usare Kill
Non utilizzare Kill come normale metodo di riavvio e non premerlo ripetutamente.
Se tutti gli utenti smettono di sincronizzare
Prima di scollegare o riconfigurare gli utenti, verificare questi processi. Se il processo principale non viene eseguito, il problema è globale e non dipende necessariamente dagli account dei singoli utenti.
Problemi dopo una modifica della mappatura
Questa pagina raccoglie soltanto i controlli da eseguire quando, dopo un cambio di mappatura, il risultato non è quello previsto. Per il comportamento normale del salvataggio vedere prima Cosa succede quando si cambia una mappatura.
I record sono spariti da Exchange
Se la mappatura è stata appena salvata, attendere la risincronizzazione prima di intervenire. I record originali in vtenext non vengono eliminati dalla modifica della mappatura.
I record ricompaiono ma alcuni campi sono vuoti
Controllare che il campo sia associato, che il tipo sia compatibile, che il valore esista in vtenext e che l'e-mail principale sia ancora mappata correttamente. Per le regole della pagina vedere Modificare una mappatura.
Vengono creati duplicati
Non continuare a modificare la mappatura finché non è stata identificata la causa.
Verificare se la risincronizzazione precedente era terminata, se sono state cambiate anche le cartelle, se gli utenti sono stati ricollegati nello stesso momento o se sono state eseguite importazioni massive.
Tornare alla mappatura precedente
Utilizzare lo screenshot o la documentazione salvata prima della modifica. Anche il nuovo salvataggio provoca una nuova risincronizzazione: non è un annullamento istantaneo.
Licenza o componenti del connettore non disponibili
Se la pagina Exchange Connector mostra una richiesta di licenza o un messaggio che impedisce di utilizzare normalmente il modulo, verificare il tipo di avviso prima di modificare utenti o mappature.
Licenza non attiva
Se viene richiesta la chiave di licenza:
- inserire la chiave fornita per il connettore;
- premere Verifica;
- attendere la conferma di attivazione;
- ricaricare la pagina Exchange Connector.
Controllare che sia stata copiata completamente e senza spazi aggiuntivi. Se il problema continua, contattare chi ha fornito la licenza.
Errore durante l'installazione dei componenti
Dopo un'installazione o un aggiornamento può comparire un messaggio che indica che alcuni componenti necessari al connettore non sono stati installati correttamente.
In questo caso utilizzare la funzione Retry presente nella pagina, se disponibile.
Se il retry fallisce nuovamente, il problema deve essere verificato sul server vtenext. Le cause più comuni sono:
- server senza accesso a Internet verso i servizi necessari;
- firewall o proxy che bloccano il download;
- estensioni PHP richieste non disponibili;
- permessi di scrittura insufficienti.
Questi controlli devono essere eseguiti dall'amministratore del server.
Cosa non fare
Evitare di scollegare tutti gli utenti, cambiare ripetutamente il tipo di Exchange, modificare le mappature o avviare risincronizzazioni massive. Prima va ripristinato il corretto funzionamento del connettore.
Informazioni da raccogliere prima di contattare il supporto
Prima di aprire una richiesta di supporto è utile raccogliere alcune informazioni precise. Questo permette di capire più rapidamente se il problema riguarda un singolo utente, un modulo, la mappatura o la configurazione generale.
Informazioni da indicare
Annotare:
- versione del connettore Exchange;
- tipo di Exchange configurato: Office365, Exchange 2016, Exchange 2019 o Exchange SE;
- se Office365 utilizza Proxy vtenext o App personalizzata;
- nome dell'utente interessato;
- modulo interessato: Eventi, Task, Contatti o Aziende;
- direzione che non funziona: vtenext → Exchange oppure Exchange → vtenext;
- data e ora approssimativa del test;
- identificativo o nome del record utilizzato per la prova;
- cartella Exchange selezionata;
- eventuali modifiche recenti a provider, account, cartelle o mappatura.
Screenshot utili
Quando possibile allegare:
- stato del collegamento dell'utente;
- pagina Exchange Connector con lo stato dei processi automatici;
- mappatura del modulo interessato;
- messaggio di errore completo;
- record di prova in vtenext e corrispondente elemento Exchange.
Evitare di includere password, Client Secret o altre credenziali negli screenshot.
Descrivere un test riproducibile
Un buon esempio di segnalazione è:
Utente Mario Rossi, Office365 Proxy. Alle 10:15 ho creato in vtenext l'evento “TEST EXCHANGE 123”. Dopo il normale ciclo di sincronizzazione l'evento non compare nel calendario Exchange selezionato. Le modifiche da Exchange verso vtenext invece funzionano.
Una descrizione di questo tipo è molto più utile di una segnalazione generica come “Exchange non funziona”.