Nonprofit Membership Workflow Beta

Installazione

Una guida completa, fase per fase, per portare il workflow sul dominio della tua associazione: dagli account alle web app, dai pagamenti ai libri sociali, fino al collaudo finale.

Prima di iniziare

Una guida completa, fase per fase

Il percorso è diviso in fasi sequenziali. Le fasi A–C preparano account, foglio e risorse su Drive; la fase D genera i file con il Configuratore; le fasi E–G installano il codice, pubblicano le web app e attivano le automazioni; la fase H mette in regola i libri sociali; le fasi I–J aggiungono i componenti opzionali e collaudano tutto. Pagamenti, Microsoft 365, app mobile, liberatorie e registro eventi sono opzionali: il sistema degrada in modo pulito senza di loro.

Una nota sulle credenziali. I sorgenti pubblici contengono solo segnaposto {{TOKEN}}. Dopo la configurazione, il tuo 0_Secrets.gs conterrà chiavi reali: non condividerlo, non caricarlo su repository pubbliche e, se esposto, ruota subito le chiavi. In alternativa puoi conservare i valori nelle Script Properties del progetto.
Da ricordare per sempre. Ogni volta che modifichi i moduli del pannello della Presidenza devi creare una nuova versione del deployment (Deploy › Manage deployments › Edit › New version): salvare nell'editor non aggiorna ciò che risponde all'URL /exec. È la causa più comune di «ho corretto il codice ma non cambia niente».

Fase A · Account e strumenti

Account e strumenti

Prepara gli account e i permessi. Sono operazioni che si fanno una volta sola, prima di toccare il codice.

  1. Google Workspace con un Super Admin

    Attiva un piano Google Workspace sul dominio dell'associazione. Lo script va eseguito da un utente con ruolo Super Admin: Admin Console › Utenti › [utente] › Ruoli e privilegi amministratore. Serve perché lo script crea utenze, gestisce i gruppi di dominio e verifica chi può accedere al pannello della Presidenza.

    ✓ Fatto quando disponi di un account @tuodominio.it con ruolo Super Admin.

  2. Verifica il dominio e l'email

    In Admin Console › Account › Domini verifica la proprietà del dominio e configura i record DNS per la deliverability.

    • MX verso Google Workspace
    • SPF: v=spf1 include:_spf.google.com ~all
    • DKIM attivato da Apps › Google Workspace › Gmail › Autentica email
    ✓ Fatto quando il dominio risulta Verificato e DKIM è attivo.

  3. Crea i tre Google Groups

    In Admin Console › Gruppi crea un gruppo per la Presidenza, uno per i soci e uno per i volontari o i musicisti (es. presidenza@, soci@, musicisti@). Le chiavi di WORKSPACE_GROUPS dovranno corrispondere esattamente ai valori usati nella colonna Gruppo del foglio.

    • L'appartenenza al gruppo della Presidenza è ciò che autorizza l'accesso al pannello: non è una formalità.
    ✓ Fatto quando i tre gruppi esistono e sono attivi.

  4. Account Stripe (opzionale)

    Solo se incassi le quote online: registra un account su dashboard.stripe.com e completa l'attivazione dell'ente. Se preferisci incassare fuori dal sistema, salta questo punto: la Presidenza segnerà la quota come regolare dal pannello.

  5. Account Cloudflare (se usi Stripe)

    Serve per pubblicare un piccolo Worker che fa da tramite fra Stripe e Apps Script. Il piano gratuito è sufficiente. Il perché è spiegato nella Fase F: senza, i pagamenti non aggiornano il foglio.

    • Installa anche wrangler, la riga di comando di Cloudflare.

  6. Tenant Microsoft 365 / Entra ID (opzionale)

    Solo se assegni anche utenze Office: predisponi un tenant Microsoft 365 con un amministratore globale, necessario per registrare l'applicazione.

  7. Progetto Supabase (opzionale)

    Solo se vuoi alimentare un'app mobile con i dati dei soci. È una sincronizzazione che non può mai far fallire un'ammissione o un pagamento: se non la configuri, viene semplicemente saltata.

Fase B · Il foglio dati

Il foglio dati

Il foglio Google è il database operativo: ogni domanda diventa una riga, e le colonne gestionali sono ciò che i trigger sorvegliano.

  1. Crea il foglio dati

    Apri il foglio template e fai File › Crea una copia sul Drive dell'organizzazione. Le colonne del richiedente sono già predisposte; quelle gestionali le creerà lo script nella Fase G.

    ✓ Fatto quando hai una copia del foglio sul Drive dell'organizzazione.

  2. Annota l'ID del foglio

    Dall'URL del foglio copia l'ID compreso tra /d/ e /edit: lo inserirai nel Configuratore come SHEET_ID.

  3. Nessun servizio di moduli esterno

    Il modulo di iscrizione non è un servizio di terze parti da collegare: è una web app che fa parte del pacchetto (ModuloIscrizioneHTML.html) e che pubblicherai tu nella Fase F. È quella pagina a scrivere direttamente sul foglio.

    • Vantaggio pratico: i consensi, la firma e gli allegati restano sul Drive dell'ente, senza passare da nessun altro.

Fase C · Risorse Drive e tessera

Risorse Drive e tessera

Il sistema salva allegati e genera documenti su Drive. Qui prepari le cartelle e il template della tessera.

  1. Crea la cartella delle tessere

    Su Google Drive: Nuovo › Cartella (es. "Tessere associative"). Aprila e copia l'ID dall'URL (la parte dopo /folders/): sarà TESSERE_FOLDER_ID.

    ✓ Fatto quando hai una cartella dedicata e ne conosci l'ID.

  2. Crea la cartella degli allegati

    Una seconda cartella riceverà i documenti d'identità e le immagini delle firme caricati dal modulo. Trattala come un archivio riservato: i file ereditano i permessi della cartella e nient'altro, quindi chi ha accesso alla cartella ha accesso ai documenti.

    • Rivedi periodicamente l'elenco degli autorizzati e non lasciarci account di prova.
    • Non condividere mai la cartella con un link pubblico.
    ✓ Fatto quando la cartella esiste e vi accede solo chi deve.

  3. Scarica il template tessera (pronto)

    Scarica il template della tessera (.pptx), caricalo su Google Drive, poi clic destro › Apri con › Presentazioni Google: Drive lo converte in Slides. Personalizza logo, nome e colori, infine copia l'ID dall'URL: sarà SLIDES_TEMPLATE_ID.

    • È già in formato orizzontale, con gli otto segnaposto e lo spazio per il QR al posto giusto.
    • Non rinominare i segnaposto ({{NOME}}, {{COGNOME}}, ...): lo script li sostituisce con i dati del socio.
    ✓ Fatto quando hai una presentazione Google Slides personalizzata e ne conosci l'ID.

  4. In alternativa: crea il template da zero

    Preferisci partire da una tua grafica? Crea una presentazione Slides in formato orizzontale e inserisci caselle di testo con esattamente questi segnaposto, lasciando libero lo spazio in basso a destra per il QR:

    • {{NOME}} · {{COGNOME}}
    • {{DATA_NASCITA}} · {{CODICE_FISCALE}}
    • {{TIPO}} (Socio Ordinario / Volontario)
    • {{ID_PRATICA}}
    • {{DATA_AMMISSIONE}} · {{DATA_SCADENZA}}

  5. Cartelle per ricevute e liberatorie (opzionali)

    Se incassi le quote, servono una cartella per le ricevute PDF e un template del documento; se raccogli liberatorie per foto e video, una cartella per i PDF firmati e il relativo template. Gli ID si inseriscono nel Configuratore.

  6. Cartella guide PDF (opzionale)

    Se vuoi allegare guide ai nuovi membri, crea una cartella Drive con i PDF e copiane l'URL: sarà DRIVE_GUIDE_URL.

Fase D · Genera i file

Genera i file

Invece di compilare i file a mano, usa il Configuratore: inserisci i dati raccolti finora e scarichi tutti i file già personalizzati. I dati restano nel tuo browser.

Configuratore guidato. Tieni a portata di mano gli ID raccolti nelle fasi B e C e i tre gruppi della fase A. Il Configuratore prende i file pubblici con segnaposto e genera i moduli adattati — compresi 0_Secrets.gs e 1_CONFIG_V8.gs — insieme alle pagine delle web app, al manifest, alla licenza e al template della tessera. Nessun dato viene inviato ai nostri server.
Apri il Configuratore Scarica i sorgenti con segnaposto

Fase E · Apps Script

Apps Script

Porta il codice dentro al foglio. È fondamentale aprire l'editor dal foglio, non dal sito di Apps Script.

  1. Apri l'editor dal foglio

    Nel foglio: Estensioni › Apps Script. Apri sempre da qui (non da script.google.com): solo così i trigger onChange/onEdit riconoscono il foglio.

    ✓ Fatto quando il progetto Apps Script risulta associato al tuo foglio.

  2. Crea i file del progetto principale

    Per ciascun modulo usa + › Script e incollane il contenuto mantenendo lo stesso nome. Nel progetto principale vanno i moduli da 0 a 8 e da 10 a 22.

    • Il modulo 9_MembroPortal.gs è una web app separata: lo userai nella fase Componenti opzionali, non qui.
    • Mantieni l'ordine numerico: aiuta a ritrovarli.

  3. Crea le quattro pagine HTML

    Con + › HTML aggiungi le pagine delle web app, mantenendo esattamente questi nomi:

    • ModuloIscrizioneHTML — il modulo di iscrizione (Fase 1)
    • ModuloPagamentoHTML — il modulo di pagamento (Fase 2)
    • PresidenzaAdminHTML — l'interfaccia del pannello
    • LiberatoriaHTML — la pagina della liberatoria immagini
    ✓ Fatto quando il progetto elenca i moduli e le quattro pagine HTML.

  4. Imposta fuso orario

    In Impostazioni progetto imposta il fuso su Europe/Rome, così date e trigger giornalieri scattano all'ora corretta.

  5. Manifest (appsscript.json)

    In Impostazioni progetto attiva Mostra il file manifest "appsscript.json", poi sostituisci il contenuto con il file appsscript.json incluso nel pacchetto.

    • Pre-dichiara i servizi avanzati (Admin SDK, People, Calendar): così nella fase successiva non devi aggiungerli a mano.
    • Imposta la web app come endpoint pubblico.
    ✓ Fatto quando il manifest elenca i tre servizi avanzati.

Fase F · Servizi, web app e pagamenti

Servizi, web app e pagamenti

Configura le integrazioni esterne e pubblica le web app. Se hai sostituito il manifest con quello del pacchetto, i tre servizi avanzati sono già dichiarati: in tal caso salta i primi tre punti.

  1. Admin SDK Directory API

    Se non usi il manifest del pacchetto: nell'editor Servizi (+) › Admin SDK API. Necessario per creare le utenze, gestire i gruppi e verificare chi accede al pannello della Presidenza.

  2. People API

    Aggiungi People API (Google Contacts): aggiorna il telefono nella Directory e fornisce il link del profilo per il QR della tessera.

  3. Calendar API

    Aggiungi Calendar: serve per i link Meet nelle notifiche e, se lo attivi, per la storicizzazione dei calendari nel registro degli eventi.

  4. Pubblica la web app (il router unico)

    Esegui Deploy › New deployment › Web app con Esegui come: me e Accesso: chiunque. L'URL /exec che ottieni è l'indirizzo di tutte le pagine del sistema: modulo di iscrizione, modulo di pagamento, pannello della Presidenza e liberatoria si distinguono per parametro.

    • Il modulo di iscrizione è l'URL nudo: è il link da pubblicare sul sito dell'ente.
    • Il pannello è lo stesso URL con ?pagina=presidenza: è protetto dall'appartenenza al gruppo, non dall'indirizzo.
    ✓ Fatto quando aprendo l'URL /exec compare il modulo di iscrizione.

  5. Il tramite per i pagamenti Stripe (obbligatorio se usi Stripe)

    Qui c'è un ostacolo della piattaforma che va aggirato, non una preferenza: le web app di Apps Script rispondono a ogni richiesta POST con un redirect 302 prima di restituire il contenuto vero, e Stripe non segue i redirect — segna la consegna come fallita e il foglio non si aggiorna mai. Per questo l'endpoint da registrare su Stripe non è l'URL di Apps Script, ma un piccolo Cloudflare Worker incluso nel progetto, che sta in mezzo.

    • Il Worker verifica la firma crittografica di Stripe con la Web Crypto API, rifiuta le richieste con un timestamp più vecchio di cinque minuti e, se la firma non torna, non inoltra nulla.
    • Poi richiama la web app seguendo lui il redirect e restituisce a Stripe una risposta diretta.
    • Configura APPS_SCRIPT_URL con il tuo URL /exec, imposta il segreto del webhook come secret del Worker, poi wrangler deploy.
    • In Stripe registra come endpoint l'URL del Worker. Rimane stabile: se in futuro cambia l'URL di Apps Script, aggiorni il Worker e non tocchi Stripe.
    ✓ Fatto quando un evento di prova inviato da Stripe risulta consegnato con esito positivo.

  6. Gli eventi Stripe da ascoltare

    Sull'endpoint del Worker sottoscrivi sei eventi. Non serve invece creare a mano un prodotto o un prezzo ricorrente: l'abbonamento viene creato al volo dal sistema al primo pagamento, a partire dall'importo della quota che hai indicato nel Configuratore.

    • checkout.session.completed — collega cliente e abbonamento alla pratica
    • invoice.payment_succeeded — quota regolare, ricevuta, e al primo pagamento avvia l'onboarding
    • invoice.paid — per gli importi a zero, che non generano l'evento precedente
    • invoice.payment_failed — avvisa il socio e sblocca un nuovo tentativo
    • customer.subscription.deleted — avvia l'annullamento
    • customer.subscription.updated — annulla solo se è stata chiesta la disdetta a fine periodo

  7. App Microsoft 365 (opzionale)

    Registra un'applicazione nel tenant e assegna i permessi Microsoft Graph con consenso amministratore.

    • Permessi tipici: User.ReadWrite.All, Directory.ReadWrite.All, Organization.Read.All.
    • Crea un client secret e annota Tenant ID, Client ID, Secret e License SKU.
    • Un errore su Microsoft 365 non blocca il resto dell'onboarding: viene annotato sulla pratica e il socio nasce lo stesso.

  8. Service Account firma Gmail (opzionale)

    In Google Cloud Console crea un Service Account con chiave JSON, poi in Admin Console › Sicurezza › Controllo API › Delega a livello di dominio autorizza il suo Client ID con lo scope https://www.googleapis.com/auth/gmail.settings.basic.

Fase G · Inizializzazione

Inizializzazione

Prepara il foglio e attiva le automazioni. Si esegue una volta sola, dall'editor di Apps Script.

  1. Inizializza le colonne

    Seleziona ed esegui inizializzaColonneAggiuntive() una sola volta: crea le colonne gestionali fino alla BV e la scheda Storico. Il foglio arriva così a circa settanta colonne.

    ✓ Fatto quando il foglio mostra le colonne gestionali e la scheda Storico.

  2. Concedi le autorizzazioni

    Al primo avvio Google chiede l'accesso a Gmail, Sheets, Drive, Slides e Admin SDK: accetta tutto con l'account Super Admin (schermata Avanzate › Vai al progetto).

  3. Installa i trigger

    Esegui installaTriggers() una volta: crea il trigger onChange sulle nuove righe, i tre onEdit sulle colonne sorvegliate e i giornalieri.

    • I tre trigger dei lavori differiti non compaiono qui: il sistema li crea e li distrugge da sé quando servono.
    • Se rilanci la funzione, i lavori ancora in coda vengono protetti e non cancellati.
    ✓ Fatto quando la sezione Trigger del progetto elenca i trigger attesi.

Fase H · Libri sociali e registri

Libri sociali e registri

Questa fase non è facoltativa per un ente del Terzo Settore: il libro degli associati e il registro dei volontari sono obbligatori per legge, e il sistema li genera dal foglio delle domande.

  1. Censisci la polizza dei volontari

    Compila CONFIG.ASSICURAZIONE_VOLONTARI con gli estremi della copertura assicurativa dei volontari. Se la lasci vuota il registro si genera comunque, ma riporta DA DOCUMENTARE al posto degli estremi.

    • Se iscrivi volontari, l'assicurazione va stipulata prima di aprire le iscrizioni.
    ✓ Fatto quando il registro mostra gli estremi reali e non il segnaposto.

  2. Genera i libri sociali

    Esegui generaRegistroVolontari() e generaLibroAssociati(). Il libro degli associati non coincide con il foglio delle domande: contiene solo chi è effettivamente diventato membro, compresi i cessati, in ordine di ammissione e con numero d'iscrizione.

    ✓ Fatto quando le due schede compaiono nel foglio e sono popolate.

  3. Attiva il diario di bordo (consigliato)

    Esegui inizializzaTracciamentoLive(): crea uno spreadsheet separato dove il sistema annota ciò che fa, riga per riga, mascherando da sé chiavi e segreti. È separato di proposito — scrivere i log nel foglio operativo farebbe scattare i trigger.

    ✓ Fatto quando lo spreadsheet di log esiste e riceve le prime righe.

Fase I · Componenti opzionali

Componenti opzionali

Attiva ciò che serve al tuo ente. Ognuno di questi componenti si può aggiungere anche in un secondo momento.

  1. Portale Membri

    Crea un progetto Apps Script separato, incolla 9_MembroPortal.gs, poi Deploy › New deployment › Web app (Esegui come: me; Accesso: chiunque con account Google). Copia l'URL ottenuto in MEMBER_PORTAL_URL e rigenera il pacchetto.

    • Il portale è autonomo: tieni allineati a mano SHEET_ID e LOGO_URL con il progetto principale.

  2. Liberatorie per foto e video

    Se pubblichi immagini dei soci, attiva la pagina della liberatoria: è raggiungibile sullo stesso URL /exec con il parametro dedicato e richiede il template e la cartella preparati nella Fase C.

    • Il consenso si chiede canale per canale, è facoltativo e si può revocare in qualsiasi momento.

  3. Registro degli eventi

    Se vuoi conservare la storia dei calendari dell'ente, crea lo spreadsheet del registro e indica i calendari da seguire. Il registro è in sola aggiunta e ogni riga porta l'impronta della precedente.

  4. Sincronizzazione con l'app mobile

    Se alimenti un'app mobile, configura l'indirizzo e il segreto della funzione di sincronizzazione. Per i soci ammessi prima di attivarla esiste una funzione di allineamento da eseguire una volta sola.

    • La sincronizzazione non può mai far fallire un'ammissione o un pagamento: se non risponde, viene saltata.

  5. Firma Gmail

    Con il Service Account della Fase F configurato, la firma istituzionale viene impostata automaticamente durante l'onboarding. La verifichi nel collaudo.

Fase J · Collaudo

Collaudo

Prova l'intero flusso end-to-end con dati di test prima di aprire le iscrizioni vere.

  1. Invio di prova

    Apri l'URL /exec e compila il modulo come farebbe un aspirante socio.

    ✓ Fatto quando compare una nuova riga sul foglio, arriva l'email di conferma con l'ID Pratica e la notifica allo staff.

  2. Tessera di prova

    Dall'editor esegui testGeneraTessera(): genera la tessera per l'ultima riga ammessa e la invia all'amministratore. Serve a verificare template, segnaposto e QR prima di andare in produzione.

    ✓ Fatto quando ricevi un PDF con i dati al posto giusto e il QR leggibile.

  3. Ammissione dal pannello

    Apri /exec?pagina=presidenza, trova la pratica di prova e usa Ammetti: il pannello chiede il gruppo e agisce subito, senza attese.

    • Se preferisci provare la strada del foglio, imposta lo stato a mano e attendi cinque minuti: l'attesa serve a darti il tempo di compilare data, gruppo e stato del pagamento.
    ✓ Fatto quando partono onboarding, creazione account, tessera ed email di benvenuto.

  4. Pagamento di prova

    Se usi Stripe, esegui un pagamento in modalità test e segui il giro completo: Stripe, Worker, foglio.

    • Nella dashboard Stripe l'evento deve risultare consegnato, non fallito.
    • Sul foglio devono aggiornarsi lo stato del pagamento e la scadenza della quota.
    • Al socio deve arrivare la ricevuta in PDF.
    ✓ Fatto quando l'evento è consegnato e il foglio si è aggiornato da solo.

  5. Verifica account e libri

    Controlla la creazione dell'utente in Admin Console (e in Microsoft 365 se attivo), poi rigenera i libri sociali e verifica che il socio di prova compaia nel libro degli associati con il suo numero d'iscrizione.

Pronto a generare i tuoi file?

Apri il Configuratore per creare il pacchetto su misura, oppure approfondisci l'architettura dei moduli.

Apri il ConfiguratoreVedi l'architettura