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

Cinque 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 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.
Controlla 0_Secrets.gs: nessun valore deve essere ancora {{TOKEN}} o INSERISCI_....
Apri Trigger: devono esistere RouterModuli, TriggerAmmissione, TriggerStorico, controlloScadenzeGiornaliero e processaCodaNotifiche.
Se il problema riguarda email, account o tessera, prova una sola pratica di test e annota l'ID Pratica.

Dove guardare

Tre posti bastano per capire quasi tutto.

Foglio Risposte: 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.
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

Il workflow non è ancora entrato in gioco: il problema è quasi sempre nel collegamento Jotform → Google Sheets.

Prova così

In Jotform apri Settings > Integrations > Google Sheets e riconnetti l'account Google corretto.
Verifica che il foglio scelto sia quello collegato al progetto Apps Script, non una copia vecchia.
Fai un invio di prova e controlla se la riga arriva entro 30 secondi.

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 ammissione e Gruppo, oppure il job differito non è stato creato.

Prova così

Nel foglio controlla che Stato domanda sia esattamente Ammesso o Rifiutato.
Controlla che Gruppo corrisponda a una chiave prevista in CONFIG.WORKSPACE_GROUPS.
Apri Apps Script > Trigger e verifica che TriggerAmmissione sia installato come on edit.

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.
Controlla gli URL: devono iniziare con https:// quando il campo è un link.
Rigenera lo ZIP dal Configuratore e sostituisci il file interessato, senza incollare chiavi in chat o ticket.

Google Chat

Le notifiche Chat non arrivano

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

Prova così

Verifica CHAT_WEBHOOK_URL_RICHIESTE e CHAT_WEBHOOK_URL_CONFERME in 0_Secrets.gs.
In Google Chat ricrea il webhook nello spazio corretto e sostituisci l'URL completo.
Se l'orario è fuori dalla finestra 09:00-22:30, controlla la coda: l'invio può essere differito.

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 Template_Tessera.pptx incluso nel pacchetto, poi convertilo in Google Slides.
Esegui testGeneraTessera() prima di approvare pratiche reali.

Stripe

Il pagamento riesce, ma il foglio non si aggiorna

Stripe non sta chiamando la Web App corretta o il webhook secret non corrisponde.

Prova così

In Apps Script crea un deployment Web App e copia il suo URL in Stripe come endpoint webhook.
In Stripe ascolta almeno invoice.payment_succeeded, invoice.payment_failed e customer.subscription.deleted.
Copia il nuovo whsec_... dentro STRIPE_WEBHOOK_SECRET.

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 in CONFIG.DOMINIO sia corretto.

Microsoft 365

Nei log compare “Token Microsoft Graph non disponibile”

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

Prova così

Controlla M365_TENANT_ID, M365_CLIENT_ID e M365_CLIENT_SECRET.
In Azure assegna consenso amministratore ai permessi Graph richiesti.
Se Microsoft 365 non serve, lascia la sezione vuota: il workflow continua con Google Workspace.

Firma Gmail

La firma non viene impostata automaticamente

La Domain-Wide Delegation richiede un Service Account valido e lo scope Gmail corretto.

Prova così

Verifica che SA_CLIENT_EMAIL e SA_PRIVATE_KEY siano compilati.
In Admin Console autorizza lo scope https://www.googleapis.com/auth/gmail.settings.basic.
Se non hai DWD pronta, usa l'email manuale con anteprima firma come soluzione temporanea.

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 sempre la catena Jotform, foglio e trigger.

Jotform deve scrivere nel foglio giusto
Le colonne A-AA non vanno riordinate
Il trigger RouterModuli parte solo su nuove righe

Onboarding differito

Dopo l'approvazione, il workflow attende circa 5 minuti per evitare modifiche accidentali.

Stato, Data e Gruppo devono essere coerenti
Il job è salvato nelle Script Properties
I log mostrano se il job è stato creato

Account e gruppi

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

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

Quote e rinnovi

Stripe aggiorna il foglio solo se il webhook arriva alla Web App corretta e supera la firma.

Endpoint aggiornato dopo ogni nuovo deploy
Signing secret coerente
Eventi Stripe selezionati

Tessera e QR

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

Non cambiare i token nel template
Controlla ID Slides e cartella tessere
Testa il PDF prima della produzione

Firma Gmail

La firma automatica è comoda, ma è anche la parte più sensibile ai permessi Google Cloud.

Service Account valido
Private key integra
Scope DWD autorizzato

Quando chiedi aiuto

Invia poche informazioni, ma giuste

Per ricevere una risposta utile, non inviare chiavi API, webhook, private key 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 / Stripe / 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, private key, dati personali reali

Regola d'oro. Se un testo contiene AIza, sk_live, sk_test, whsec_, PRIVATE KEY o un webhook Chat 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