Nonprofit Membership Workflow Beta

Assistenza

Una guida calma e pratica per risolvere gli errori più comuni: prima capisci cosa sta succedendo, poi intervieni con pochi passaggi sicuri.

Diagnosi rapida Problemi comuni

Prima diagnosi

Sei controlli, in ordine

Quando qualcosa non funziona, non partire dal codice. Parti dal punto in cui il flusso si ferma: modulo, foglio, trigger, integrazione esterna o comunicazione.

Metodo semplice

Segui questi passaggi prima di modificare impostazioni o rigenerare file. Sono pensati per isolare il problema senza rompere una configurazione già buona.

Apri il foglio delle risposte e controlla se l'ultima riga contiene davvero i dati arrivati dal modulo.
In Apps Script apri Esecuzioni: cerca l'ultima funzione in rosso e leggi solo la prima riga dell'errore.
Apri il diario di bordo, se l'hai attivato: dice cosa stava facendo il sistema nel momento esatto in cui si è fermato.
Controlla 0_Secrets.gs: nessun valore deve essere ancora {{TOKEN}} o INSERISCI_....
Apri Trigger e verifica che ci siano tutti quelli attesi, sull'evento giusto.
Se il problema riguarda email, account o tessera, prova una sola pratica di test e annota l'ID Pratica.

Dove guardare

Quattro posti bastano per capire quasi tutto.

Il foglio: dice se i dati sono arrivati e in che stato è la pratica.
Apps Script > Esecuzioni: mostra la funzione fallita e la prima riga dell'errore.
Il diario di bordo: racconta la sequenza, non solo l'errore finale.
Trigger: conferma che le automazioni siano installate sull'evento giusto.

Problemi comuni

Cosa vedi, cosa significa, cosa fare

Ogni scheda parte dal sintomo. Leggi solo quella che assomiglia al tuo caso, poi prova i passaggi in ordine.

Modulo e foglio

Il modulo è stato inviato, ma non compare nessuna riga

La web app non è riuscita a scrivere sul foglio: quasi sempre è l'ID del foglio sbagliato, o un deployment vecchio che punta altrove.

Prova così

Verifica che SHEET_ID sia quello del foglio a cui è agganciato il progetto Apps Script, non di una copia.
Controlla in Esecuzioni se la funzione di salvataggio è partita e con quale errore.
Se hai modificato il codice di recente, crea una nuova versione del deployment: l'URL serve ancora la versione precedente.

Deployment

Ho corretto il codice ma il comportamento non cambia

È il problema più comune di tutti. Salvare nell'editor non aggiorna ciò che risponde all'URL pubblico: serve una nuova versione del deployment.

Prova così

Deploy > Manage deployments > Edit > New version, poi salva.
Verifica di stare modificando il progetto giusto: il portale dei membri è un progetto separato.
Ricarica la pagina della web app con la cache disattivata.

Apps Script

Vedo «Authorization required» o «Autorizzazione necessaria»

Google sta bloccando una funzione finché l'account amministratore non concede i permessi.

Prova così

Esegui manualmente inizializzaColonneAggiuntive() dall'editor Apps Script.
Quando appare la schermata di Google, scegli l'account Super Admin e completa Avanzate > Vai al progetto.
Riprova installaTriggers() solo dopo aver completato l'autorizzazione.

Trigger

La pratica resta in corso e non parte l'onboarding

Il trigger non vede una combinazione valida di stato, data e gruppo, oppure il lavoro differito non è stato creato.

Prova così

Controlla che lo stato della domanda sia esattamente Ammesso o Rifiutato, senza spazi in coda.
Controlla che il gruppo corrisponda a una delle chiavi previste nella configurazione.
Se sei un Socio Ordinario con quota non ancora regolare, è il comportamento atteso: l'onboarding parte da solo quando il pagamento arriva.
In ultima istanza esiste una funzione di recupero manuale: vedi la tabella più in basso.

Volontari

Un volontario resta in errore e non si sblocca

Il genitore indicato non è stato trovato, oppure non è ancora ammesso e in regola con la quota.

Prova così

Verifica che codice fiscale e ID Pratica del genitore, inseriti nel modulo, corrispondano a una pratica esistente.
Controlla che quella pratica sia ammessa e con quota regolare: servono entrambe le condizioni.
Non intervenire a mano. Quando il genitore completa l'iscrizione, il sistema sblocca da sé tutti i volontari collegati e manda le comunicazioni arretrate.

Pannello Presidenza

Il pannello dice che non sono autorizzato

L'accesso è deciso dall'appartenenza al gruppo Google della Presidenza, verificata sul server a ogni azione.

Prova così

Verifica in Admin Console di essere membro del gruppo indicato nella configurazione, con l'account con cui hai fatto l'accesso.
Controlla che l'Admin SDK Directory API sia attiva: senza, il sistema non riesce a leggere l'elenco dei membri.
Se hai appena aggiunto qualcuno al gruppo, attendi qualche minuto: la propagazione non è istantanea.

Pagamenti

Il pagamento riesce, ma il foglio non si aggiorna

Nella dashboard del servizio di pagamento l'evento risulta fallito con un codice di redirect. È il sintomo classico: l'endpoint punta direttamente ad Apps Script invece che al Worker.

Prova così

Controlla l'endpoint registrato: deve essere l'URL del Cloudflare Worker, non l'URL /exec di Apps Script.
Verifica che nel Worker APPS_SCRIPT_URL sia l'URL /exec corrente e che il segreto del webhook sia impostato come secret.
Se hai creato un nuovo deployment di Apps Script, l'URL è cambiato: aggiorna il Worker e rilancia il deploy. Su Stripe non devi toccare nulla.
Controlla di aver sottoscritto tutti e sei gli eventi elencati nella guida all'installazione.

Pagamenti

La ricevuta non arriva, o non compare in contabilità

Il pagamento è stato registrato ma il ponte verso il sistema contabile non è configurato, o non trova le sue risorse.

Prova così

Verifica che la cartella delle ricevute e il template del documento siano stati creati e che i loro ID siano compilati.
Controlla che lo spreadsheet contabile sia raggiungibile dall'account che esegue lo script.
Nel diario di bordo cerca le righe relative alla generazione della ricevuta.

Segreti

Nei log compare «configurazione mancante»

Il codice è stato copiato prima di compilare tutti i valori necessari, oppure è rimasto un segnaposto.

Prova così

Apri 0_Secrets.gs e cerca {{: se trovi risultati, completa quei campi nel Configuratore.
Cerca anche INSERISCI_: è il valore che il Configuratore lascia sui campi non compilati.
Rigenera lo ZIP dal Configuratore e sostituisci il file interessato, senza incollare chiavi in chat o ticket.

Notifiche

Le notifiche su Chat non arrivano

Il webhook può essere vuoto, non più valido o collegato allo spazio sbagliato. Oppure è semplicemente notte.

Prova così

Verifica i due indirizzi dei webhook, per le richieste e per gli esiti, in 0_Secrets.gs.
In Google Chat ricrea il webhook nello spazio corretto e sostituisci l'URL completo.
Se l'orario è fuori dalla finestra serale, controlla la coda: l'invio è differito al mattino successivo, di proposito.

Tessera

La tessera viene creata, ma mancano dati o il QR è fuori posto

Il template Slides non ha i segnaposto corretti o non usa il layout previsto.

Prova così

Nel template cerca i segnaposto esatti: {{NOME}}, {{COGNOME}}, {{ID_PRATICA}} e gli altri.
Usa il template incluso nel pacchetto, poi convertilo in Google Slides.
Esegui testGeneraTessera() prima di approvare pratiche reali.
Se il QR non punta a nulla, ricorda che la tessera viene rigenerata quindici minuti dopo l'onboarding: è quella la copia buona.

Workspace

L'utente Google Workspace non viene creato

L'account che esegue lo script non ha privilegi sufficienti o il dominio/gruppo non è configurato.

Prova così

Esegui il workflow con un account Super Admin del dominio.
Verifica che Admin SDK Directory API sia attivo nei servizi avanzati.
Controlla che l'email generata non esista già e che il dominio configurato sia corretto.

Microsoft 365

Nei log compare un errore sul token Microsoft

Tenant ID, Client ID, Client Secret o permessi non sono completi.

Prova così

Controlla i tre valori dell'applicazione registrata e la scadenza del client secret.
Assegna il consenso amministratore ai permessi richiesti.
Se Microsoft 365 non ti serve, lascia la sezione vuota: l'errore non blocca l'onboarding, viene solo annotato sulla pratica.

Firma Gmail

La firma non viene impostata automaticamente

La delega a livello di dominio richiede un Service Account valido e lo scope corretto.

Prova così

Verifica che email e chiave privata del Service Account siano compilate e integre.
In Admin Console autorizza lo scope https://www.googleapis.com/auth/gmail.settings.basic.
Nel frattempo il membro riceve comunque la firma in HTML con le istruzioni per incollarla a mano: è previsto apposta.

Rimettere in moto

Le funzioni di recupero

Quando qualcosa si è fermato a metà, quasi sempre esiste una funzione che lo riprende da dove era. Si eseguono dall'editor di Apps Script, dopo aver capito il perché.

Situazione	Cosa fare
Onboarding non partito	Verifica stato, data, gruppo e quota, poi esegui la funzione di recupero manuale indicando l'ID Pratica.
Righe in ingresso da rielaborare	Esiste una funzione che ripassa le domande arrivate e non prese in carico.
Errori su Microsoft 365	Una funzione di diagnostica verifica la configurazione e l'elenco delle licenze disponibili.
Notifiche da provare	Una funzione di test invia una notifica di prova sul canale configurato.
Tessera da verificare	`testGeneraTessera()` genera una tessera di prova e la manda all'amministratore.
Sincronizzazione con l'app	Una funzione di test verifica il ponte; per i soci storici ne esiste una di allineamento, da eseguire una volta sola.
Serve il libro dei soci	`generaLibroAssociati()` lo rigenera dal foglio delle domande.
Serve il registro dei volontari	`generaRegistroVolontari()`. Se compare il segnaposto al posto degli estremi, la polizza non è ancora censita.
Riammettere una persona espulsa	Va prima rimosso a mano il segno dell'espulsione sul foglio: il pannello si rifiuta di ammettere chi risulta espulso.

Approfondimenti operativi

Piccoli paper, senza gergo inutile

Queste schede spiegano il perché dei controlli. Sono utili quando il problema si ripete o quando stai passando il progetto a una nuova persona.

Dal modulo alla riga

Prima di cercare errori nel codice, verifica la catena: web app, foglio, trigger.

La web app deve scrivere sul foglio giusto
Il deployment deve essere aggiornato
Il trigger delle nuove righe parte solo sugli inserimenti

Perché serve un tramite per i pagamenti

Le web app di Apps Script rispondono a ogni POST con un redirect, e i servizi di webhook non lo seguono.

L'endpoint su Stripe è il Worker, non Apps Script
Il Worker verifica la firma e rifiuta le richieste vecchie
Se cambia l'URL di Apps Script si aggiorna il Worker, non Stripe

Perché il sistema aspetta

Le attese non sono lentezza: sono finestre per correggere un errore prima che diventi un account.

Cinque minuti dall'ammissione dal foglio
Cinque minuti dal rifiuto, per scrivere il motivo
Quindici minuti prima di firma e tessera definitiva

Account e gruppi

La parte account richiede privilegi amministrativi: senza, tutto il resto funziona ma l'utente non nasce.

Admin SDK attivo
Super Admin come esecutore
Gruppi già creati nel dominio

Tessera e QR

La tessera è una presentazione trasformata in PDF; ogni segnaposto è un contratto con lo script.

Non cambiare i token nel template
Controlla gli ID di Slides e della cartella
La copia buona è quella rigenerata dopo quindici minuti

Il pannello non delibera

Registra ciò che gli organi hanno deciso. Se una funzione sembra mancare, spesso è perché richiede un atto che non c'è.

L'espulsione pretende una proposta aperta
La delibera pretende gli estremi del verbale
Il rifiuto pretende un motivo

Quando chiedi aiuto

Invia poche informazioni, ma giuste

Per ricevere una risposta utile, non inviare chiavi API, webhook, chiavi private o dati personali dei membri. Servono invece contesto, ID pratica di test e prima riga dell'errore.

Modello da copiare

Area del problema: Modulo / Apps Script / Pagamenti / Pannello / Workspace / Tessera / Email
ID pratica di test: ...
Funzione in errore: ...
Prima riga dell'errore: ...
Cosa ho già provato:
1. ...
2. ...
Valori NON inclusi: chiavi API, webhook, chiavi private, dati personali reali

Regola d'oro. Se un testo contiene AIza, sk_live, sk_test, whsec_, PRIVATE KEY o un webhook completo, non inviarlo in messaggi, email o issue pubbliche.

Hai risolto il primo blocco?

Rientra nella guida di installazione per completare la configurazione o controlla l'architettura se vuoi capire da quale modulo nasce un errore.

Torna all'installazione Vedi l'architettura