Orchestra Giovanile
di Percussioni

Nonprofit Membership Workflow Beta

Installazione

Una guida completa, fase per fase, per portare il workflow sul dominio della tua associazione: dagli account alla tessera associativa, dai file su Apps Script al collaudo finale.

Prima di iniziare

Una guida completa, fase per fase

Il percorso è diviso in fasi sequenziali. Le fasi A–C preparano account, dati e risorse Drive (incluso il template della tessera); la fase D genera i file con il Configuratore; le fasi E–G installano e attivano il sistema; le fasi H–I aggiungono i componenti opzionali e collaudano tutto. Stripe, Microsoft 365 e firma Gmail sono opzionali.

Una nota sulle credenziali. I sorgenti pubblici contengono solo segnaposto {{TOKEN}}. Dopo la configurazione, il tuo 0_Secrets.gs conterrà chiavi reali (Stripe, Microsoft 365, webhook Chat, Service Account): non condividerlo, non committarlo su Git e, se esposto, ruota subito le chiavi. In alternativa puoi conservare i valori nelle Script Properties del progetto.

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 e gestisce i gruppi di dominio.

    ✓ 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 i gruppi per Presidenza, Soci e Volontari (es. presidenza@, soci@, volontari@). Le chiavi di WORKSPACE_GROUPS dovranno corrispondere esattamente ai valori usati nella colonna Gruppo del foglio.

    ✓ Fatto quando i tre gruppi esistono e sono attivi.

  4. Account Jotform

    Crea un account su jotform.com (anche il piano gratuito basta) per ospitare il modulo di ammissione.

  5. Account Stripe (opzionale)

    Solo se gestisci le quote con pagamento online: registra un account su dashboard.stripe.com e completa l'attivazione dell'ente.

  6. Tenant Microsoft 365 / Azure AD (opzionale)

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

Fase B · Modulo e foglio dati

Modulo e foglio dati

Collega il modulo di iscrizione al foglio che farà da database. Da qui ogni invio diventa una riga.

  1. Duplica il modulo Jotform

    Apri il template del modulo e usa Use Template per clonarlo nel tuo account. Adatta intestazioni, importi e testi mantenendo l'ordine dei campi.

    • Dati del socio: nome, cognome, codice fiscale, data di nascita, email, telefono
    • Per i minorenni: dati del volontario + codice fiscale del genitore + documento d'identità
    • Consensi: Politiche associative, Privacy, Statuto + firma

  2. Crea il foglio dati

    Apri il foglio template e fai File › Crea una copia sul Drive dell'organizzazione. Le colonne A–AA sono già predisposte per ricevere i campi del modulo.

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

  3. Annota l'ID del foglio

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

  4. Collega Jotform al foglio

    In Jotform: Settings › Integrations › Google Sheets, autorizza l'accesso e seleziona il foglio appena creato. Controlla che ogni campo del modulo finisca nella colonna corretta (A–AA).

    ✓ Fatto quando un invio di prova dal modulo crea una nuova riga nel foglio.

Fase C · Risorse Drive e tessera

Risorse Drive e tessera

Il sistema genera automaticamente una tessera associativa in PDF da un template Google Slides. Qui prepari le cartelle e il template.

  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. Qui finiranno i PDF generati, condivisi automaticamente con il membro.

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

  2. 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.

  3. 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 (inserito automaticamente dallo script):

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

  4. Annota gli ID di Slides e cartella

    Copia l'ID della presentazione dall'URL (tra /d/ e /edit): sarà SLIDES_TEMPLATE_ID. Tienilo insieme a TESSERE_FOLDER_ID: li inserirai nel Configuratore.

    • Il QR della tessera rimanda al profilo Google Contacts del socio: funziona dopo che l'utenza è stata creata (Fase H) e con la People API attiva (Fase F).

  5. 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 (SHEET_ID, SLIDES_TEMPLATE_ID, TESSERE_FOLDER_ID) e i tre gruppi della fase A. Il Configuratore prende i file pubblici con segnaposto, genera 0_Secrets.gs, 1_CONFIG_V8.gs e gli altri moduli adattati, pronti per Apps Script. 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 12.

    • 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. Imposta fuso orario

    In Impostazioni progetto imposta il fuso su Europe/Rome, così date e trigger giornalieri (08:00 / 09:00) scattano all'ora corretta.

  4. 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 per il webhook Stripe.
    ✓ Fatto quando il manifest elenca i tre servizi avanzati.

Fase F · Servizi e API

Servizi e API

Configura le integrazioni esterne. Se hai sostituito il manifest con l'appsscript.json del pacchetto, i tre servizi avanzati sono già dichiarati: in tal caso salta i primi tre punti. Le integrazioni Stripe, Microsoft 365 e firma sono opzionali.

  1. Admin SDK Directory API

    Se non usi il manifest del pacchetto: nell'editor Servizi (+) › Admin SDK API. Necessario per creare le utenze e gestire i gruppi di dominio.

  2. People API

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

  3. Calendar (opzionale)

    Aggiungi Calendar per generare i link Google Meet nelle notifiche su Chat.

  4. Webhook Stripe (opzionale)

    Per ricevere gli eventi di pagamento serve l'endpoint della Web App. Esegui Deploy › New deployment › Web app (Esegui come: me; Accesso: chiunque), copia l'URL e incollalo in Stripe come endpoint webhook.

    • In Stripe crea un prodotto/prezzo ricorrente annuale pari alla quota.
    • Eventi da ascoltare: invoice.payment_succeeded, invoice.payment_failed, customer.subscription.deleted.
    • Copia il signing secret (whsec_…) in STRIPE_WEBHOOK_SECRET.

  5. App Microsoft 365 (opzionale)

    In Azure AD registra un'applicazione 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.

  6. 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 (AS–BI) e la scheda Storico.

    ✓ 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 (RouterModuli), gli onEdit (Ammissione, Storico, Stripe) e i giornalieri delle 08:00 e 09:00.

    ✓ Fatto quando la sezione Trigger del progetto elenca i sei trigger attesi.

Fase H · Componenti opzionali

Componenti opzionali

Attiva il portale di consultazione per i membri e la firma Gmail automatica, se ti servono.

  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/aggiorna il file.

    • Il portale è standalone: tieni allineati manualmente SHEET_ID e LOGO_URL con il progetto principale.

  2. Firma Gmail

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

Fase I · Collaudo

Collaudo

Prova l'intero flusso end-to-end con dati di test prima di andare in produzione.

  1. Invio di prova

    Compila il modulo Jotform come un nuovo aspirante socio.

    ✓ Fatto quando arrivano la prima email di conferma e la notifica su Google Chat.

  2. Tessera di prova

    Dall'editor esegui testGeneraTessera(): genera la tessera per l'ultima riga Ammessa e la invia via email 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 completa

    Nel foglio imposta Stato = Ammesso, compila Gruppo e Data, poi attendi circa 5 minuti.

    ✓ Fatto quando partono onboarding, creazione account, tessera ed email di benvenuto.

  4. Verifica account e pagamenti

    Controlla la creazione dell'utente in Admin Console (e in Microsoft 365 se attivo). Se usi Stripe, esegui un pagamento di test e verifica l'aggiornamento di Stato pagamento e della scadenza quota.

Pronto a generare i tuoi file?

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

Apri il Configuratore Vedi l'architettura