Documentare i flussi di import/export in Access significa descrivere in modo verificabile come i dati entrano nel database, come vengono trasformati, dove vengono inviati e come si controlla che ogni esecuzione sia corretta. È un’attività spesso trascurata finché una persona lascia l’azienda, un file cambia formato o un’automazione smette di funzionare. A quel punto la documentazione diventa la differenza tra una correzione rapida e ore di analisi.
Microsoft Access può salvare specifiche e passaggi di importazione/esportazione, ma queste informazioni tecniche non sostituiscono una documentazione completa. Un processo professionale deve spiegare anche finalità, proprietario, frequenza, struttura dei campi, dipendenze, sicurezza, controlli e recupero dopo un errore. La guida è pensata per Access per Microsoft 365 e Access 2024 su Windows, con indicazioni valide anche per applicazioni distribuite tramite Access Runtime.
Indice
- Perché documentare
- Inventario dei flussi
- Scheda standard
- Mapping campi
- Specifiche Access
- Macro e VBA
- Logging
- Versionamento
- Sicurezza
- Test e ripristino
- FAQ
Perché la documentazione è parte dell’integrazione
Un flusso dati non è soltanto una macro o una procedura VBA. È un accordo tra una sorgente e una destinazione. Se un file CSV contiene CodiceCliente, DataOrdine e Importo, entrambi i sistemi devono sapere cosa significano i campi, quale formato usano e quali valori sono validi.
Senza documentazione, piccole modifiche diventano rischiose. Un collega rinomina una colonna Excel, la procedura Access continua a cercare il vecchio nome e l’importazione fallisce. Oppure un fornitore passa dal formato data giorno-mese-anno a anno-mese-giorno e alcuni record vengono interpretati in modo errato.
La documentazione deve quindi essere mantenuta insieme al processo, non scritta una volta e dimenticata.
Creare un inventario di tutti i flussi
Il primo passo è costruire una tabella o un documento che elenchi tutte le integrazioni. Per ogni flusso registra un identificatore univoco, un nome leggibile, la direzione e lo stato. Per esempio:
- IMP-001 Import clienti da gestionale.
- IMP-002 Import listino Excel.
- EXP-001 Esportazione vendite mensili.
- EXP-002 File CSV per corriere.
- SYNC-001 Allineamento anagrafiche.
L’identificatore deve comparire anche nei nomi delle specifiche, nei log e nei documenti. In questo modo quando compare un errore EXP-002 sai immediatamente quale scheda consultare.
La scheda standard di un flusso
Ogni integrazione dovrebbe avere una scheda con almeno: ID, nome, descrizione, proprietario funzionale, proprietario tecnico, sorgente, destinazione, frequenza, modalità di avvio, formato, oggetto Access coinvolto, percorso, credenziali richieste, prerequisiti, regole di trasformazione, controlli, gestione errori, retention, backup e procedura di ripristino.
Aggiungi anche la data dell’ultima modifica e la versione. Se il processo è critico, indica SLA o orario entro cui deve completarsi.
Documentare la sorgente
Scrivi esattamente da dove arrivano i dati. Non limitarti a “file Excel”. Indica nome atteso, cartella, foglio, intervallo o tabella, proprietario e convenzione di naming. Se il file cambia ogni giorno, documenta il pattern, per esempio Ordini_YYYYMMDD.xlsx.
Per una sorgente ODBC indica server logico, database, DSN o modalità DSN-less, driver richiesto e autenticazione. Non inserire la password nel documento se non è gestito come segreto; indica invece il sistema autorizzato che fornisce la credenziale.
Documentare la destinazione
Per un import Access indica tabella staging e tabella finale. È una buona pratica non importare direttamente nelle tabelle operative quando il file è esterno e deve essere validato. Una tabella temporanea consente di controllare duplicati, tipi e campi obbligatori.
Per un export indica percorso, nome file, formato, destinatario e retention. Se il file viene caricato da un altro sistema, specifica come viene segnalato che è completo: nome definitivo, cartella ready, file di controllo o altra convenzione.
Creare un mapping dei campi
Il mapping è una tabella che mette in relazione campo sorgente e campo destinazione. Per ogni colonna registra nome sorgente, nome destinazione, tipo, lunghezza, obbligatorietà, trasformazione, valore di default e note.
Esempio: CustomerCode diventa CodiceCliente, tipo Testo breve, massimo 20 caratteri, obbligatorio, rimozione spazi iniziali/finali. OrderDate diventa DataOrdine, tipo Data/Ora, nessun valore di default, record rifiutato se non convertibile.
Questo mapping è fondamentale quando cambia uno dei sistemi. Permette di capire rapidamente quali campi sono coinvolti e quali regole devono essere aggiornate.
Documentare i tipi di dato
Non scrivere solo “numero”. Specifica se è intero, decimale, valuta, percentuale o codice numerico che in realtà deve essere testo. I codici con zeri iniziali non devono essere trattati come numeri se non vengono usati in calcoli.
Per le date definisci il formato di scambio. Un formato ISO non ambiguo è più sicuro di stringhe dipendenti dalla lingua. In Access il campo finale dovrebbe essere un vero tipo Data/Ora, non una stringa formattata.
Documentare valori nulli e vuoti
Null, stringa vuota e zero hanno significati diversi. Il mapping deve dire come interpretarli. Se un campo DataConsegna è Null significa che la consegna non è ancora avvenuta; sostituirlo con una data convenzionale può rendere i report errati.
Per un file CSV definisci se un campo vuoto diventa Null, stringa vuota o valore di default. Queste decisioni devono essere esplicite.
Specifiche di importazione ed esportazione Access
Access permette di salvare dettagli di operazioni di importazione ed esportazione. Microsoft documenta la possibilità di salvare i passaggi completati con successo e rieseguirli. Per file di testo esistono inoltre specifiche che descrivono delimitatori, tipi e struttura.
Nella documentazione registra il nome esatto della specifica, il tipo di file e l’oggetto che la richiama. Se la specifica viene modificata, aggiorna la versione del flusso.
Per approfondire consulta salvare le specifiche di importazione in Access e usare le specifiche di esportazione.
Documentare le query coinvolte
Un flusso può usare una catena di query: import staging, controllo errori, append, update e cleanup. Elenca tutte le query in ordine di esecuzione e spiega lo scopo di ciascuna. Non limitarti ai nomi.
Se una query è utilizzata anche da report o integrazioni esterne, segnalalo. Evita che un manutentore la rinomini pensando che sia inutilizzata.
Documentare macro Access
Per una macro indica nome, evento o pulsante che la richiama, azioni principali e condizioni. Le macro UI possono automatizzare apertura oggetti, filtri e operazioni di import/export. Alcune azioni richiedono un database attendibile.
Se usi AutoExec, documentalo chiaramente perché viene eseguito all’apertura del database. Spiega anche come bypassarlo per manutenzione, quando supportato e appropriato.
Documentare VBA
Per una procedura VBA registra modulo, nome Sub o Function, parametri, risultato, dipendenze e gestione errori. Commenta il codice per spiegare il perché delle regole, non ogni singola istruzione ovvia.
Se la procedura usa DoCmd.TransferSpreadsheet, TransferText, DAO, FileSystemObject o automazione Office, elenca le dipendenze. Per codice che deve funzionare a 64 bit documenta eventuali dichiarazioni API e requisiti.
Separare configurazione e codice
Non disseminare percorsi e nomi file dentro decine di moduli. Crea una tabella Configurazione con chiavi come CartellaImport, CartellaExport, NomeServer e GiorniRetention. La documentazione deve indicare quali valori possono essere modificati senza cambiare codice.
Questo rende il rilascio tra ambiente test e produzione molto più semplice. Il codice resta uguale; cambia la configurazione.
Documentare le credenziali senza esporle
La documentazione non deve contenere password in chiaro. Indica il metodo di autenticazione e chi gestisce il segreto. Per SQL Server preferisci autenticazione Windows quando adatta; per altri sistemi usa meccanismi sicuri.
Se una password viene cambiata, il processo di aggiornamento deve essere documentato senza rivelare il valore.
Logging: documentazione che si aggiorna da sola
Una tabella log completa la documentazione statica. Registra ID flusso, data inizio, data fine, utente, file, record letti, record validi, record scartati, esito e messaggio errore.
Con questi dati puoi rispondere a domande concrete: l’import di ieri è partito? Quanti record ha caricato? Quale file ha elaborato? Ci sono stati scarti?
Tabella degli errori
Per importazioni esterne crea una tabella Scarti con ID flusso, numero riga, chiave, campo, valore originale e motivo. Non limitarti a mostrare “errore di tipo”. Chi corregge il file deve sapere quale riga ha causato il problema.
Controlli di riconciliazione
Documenta i controlli che dimostrano che il processo è completo. Per un import possono essere numero righe, somma importi e data massima. Per un export, numero record e totale.
Un processo che termina senza eccezioni può essere comunque sbagliato. Se normalmente esporta 5.000 righe e oggi ne esporta 5, il log dovrebbe segnalarlo.
Versionare il tracciato
Quando cambia la struttura, assegna una versione. Per esempio CSV Vendite v1 contiene sei colonne; v2 aggiunge CodiceCanale. Mantieni una cronologia con data, motivo, sistema impattato e responsabile.
Per cambi incompatibili valuta un periodo di convivenza. Genera temporaneamente v1 e v2 finché tutti i consumer sono aggiornati.
Versionare il database Access
Aggiungi una versione applicativa visibile nel front-end e nel documento di rilascio. Se un utente segnala un errore puoi sapere quale build sta eseguendo. Per applicazioni multiutente distribuisci un front-end locale aggiornato in modo controllato.
Documentare Access Runtime
Se gli utenti usano Runtime, indica la versione e architettura previste, prerequisiti e percorso di installazione. Runtime non offre tutte le funzioni di progettazione; la procedura di supporto deve spiegare come recuperare log e configurazioni senza chiedere all’utente di modificare query.
Compatibilità 32 e 64 bit
Documenta se l’applicazione è testata su Office 32 bit, 64 bit o entrambi. Elenca driver ODBC, provider e librerie COM. Un cambio di architettura può rompere un flusso perfettamente funzionante.
Ambiente test e produzione
Non testare un import distruttivo direttamente sui dati reali. Mantieni un ambiente o una copia di test. La documentazione deve indicare come cambiare sorgenti e destinazioni e come evitare che il test invii file o email reali.
Piano di test
Per ogni flusso crea casi: file corretto, file vuoto, file duplicato, campo mancante, data non valida, numero fuori range, percorso non disponibile, credenziali scadute e interruzione durante il processo. Registra risultato atteso.
Procedura di rollback
Se un import sbagliato inserisce migliaia di record, come torni indietro? La risposta deve esistere prima dell’incidente. Può essere ripristino backup, tabella di audit, batch ID che consente una cancellazione controllata o transazione server.
Non progettare il rollback dopo l’errore. Documentalo e testalo.
Backup
Indica quando viene eseguito, dove è conservato, per quanto tempo e come si ripristina. Un backup non verificato non è sufficiente. Esegui periodicamente un test di restore.
RTO e criticità
Per flussi importanti indica quanto tempo può restare fermo il processo. Un export mensile può essere ripetuto il giorno dopo; un’integrazione ordini ogni ora potrebbe richiedere un ripristino rapido. La criticità guida investimenti e livello di automazione.
Documentare i collegamenti esterni
Access può usare tabelle collegate a SQL Server, Excel, SharePoint e altri database. Mantieni un elenco delle sorgenti collegate con percorso o server, driver, tabella remota e nome locale.
Microsoft 365 offre una Gestione tabelle collegate più ricca rispetto ad alcune versioni perpetue. Non basare però la documentazione solo sull’interfaccia: mantieni anche un inventario esterno.
Esportare l’inventario dei collegamenti
Alcune versioni Access hanno funzioni diverse nella Gestione tabelle collegate. Microsoft documenta differenze tra Microsoft 365 e versioni precedenti. Se serve un inventario automatico, puoi anche creare una procedura VBA che legge le TableDef e registra le stringhe Connect, facendo attenzione a non esporre segreti.
Documentare Power Query e Power BI
Se una query Access alimenta un workbook o un report Power BI, registra il nome del consumer. Il database potrebbe non sapere automaticamente chi lo sta leggendo. Una modifica apparentemente innocua può rompere un report esterno.
Documentare Outlook e Word
Se esistono automazioni Office, indica se richiedono Outlook classico o altre applicazioni installate. Il nuovo Outlook per Windows non supporta il tradizionale modello VBA/COM allo stesso modo. Questa dipendenza deve essere evidente nella scheda.
Runbook operativo
Oltre alla documentazione tecnica crea un runbook semplice: come avviare, cosa controllare, cosa fare se compare errore A, chi contattare, dove trovare i file e come ripetere il processo.
Il runbook deve essere utilizzabile da un operatore che conosce il processo ma non il codice.
Checklist di revisione periodica
- Il proprietario è ancora corretto?
- Il percorso esiste?
- Il tracciato è aggiornato?
- Le query esistono?
- Le credenziali sono valide?
- I driver sono supportati?
- I log vengono scritti?
- Il backup funziona?
- Il rollback è testato?
- I consumer esterni sono aggiornati?
Errori comuni nella documentazione
Screenshot senza testo
Uno screenshot invecchia rapidamente e non è ricercabile come una descrizione strutturata. Usalo come supporto, non come unica fonte.
Nomi generici
“Macro1” o “Query2” non spiegano nulla. Usa nomi orientati allo scopo.
Password nel documento
È un rischio di sicurezza. Documenta il metodo di autenticazione, non il segreto.
Assenza di controlli
Scrivere “import completato” non prova che i dati siano corretti. Documenta conteggi e riconciliazioni.
Nessuna procedura di rollback
È uno degli errori più gravi per query di azione e importazioni.
Esempio di scheda sintetica
ID: IMP-CLIENTI-01. Scopo: aggiornare anagrafica clienti. Sorgente: file CSV giornaliero. Destinazione: tblStagingClienti, poi tblClienti. Avvio: pulsante amministratore. Controlli: righe, codici duplicati, email non valide. Log: tblLogImport. Rollback: batch ID. Proprietario: ufficio dati. Versione: 2.1.
Una scheda così breve è già molto più utile di nessuna documentazione. Per processi critici aggiungi mapping completo e diagrammi.
FAQ
Le specifiche salvate di Access bastano?
No. Memorizzano dettagli tecnici della procedura, ma non scopo, responsabilità, mapping completo, sicurezza e recupero.
Dove conservare la documentazione?
In una posizione aziendale versionata e accessibile ai responsabili, non soltanto nel PC dello sviluppatore.
Serve documentare anche una semplice esportazione?
Sì, se è ricorrente o importante. Bastano poche righe, ma devono esistere.
Posso generare automaticamente parte dell’inventario?
Sì, con VBA puoi leggere oggetti e collegamenti. La parte funzionale e le responsabilità richiedono comunque documentazione umana.
Quanto spesso va aggiornata?
Ogni volta che cambia il flusso e con una revisione periodica per processi critici.
Runtime cambia la documentazione?
Devi aggiungere prerequisiti di distribuzione e procedure di supporto, perché l’utente Runtime non dispone dell’ambiente completo.
Fonti Microsoft
Microsoft documenta la possibilità di salvare i dettagli di un’operazione di importazione o esportazione e la gestione delle tabelle collegate. Usa inoltre la documentazione Microsoft Learn per i metodi VBA impiegati dal processo.
Conclusione
Documentare i flussi di import/export in Access significa rendere il sistema manutenibile, verificabile e trasferibile. Inventaria ogni flusso, crea un mapping, registra specifiche, query, macro, moduli, dipendenze, controlli, log e rollback.
La documentazione migliore non è la più lunga ma quella che consente a un’altra persona di capire cosa succede e ripristinare il servizio senza indovinare. Per altre procedure consulta Guide Access e automatizzare importazioni periodiche in Access.