Eventi e Trigger per gli Apps Script

In questo nuovo articolo sui Google Apps Script volevo approfondire un argomento che ho già accennato negli episodi precedenti: i trigger ovvero gli strumenti che ci consentono di automatizzare l'esecuzione dei nostri script

Ho già avuto modo di farvi creare dei trigger e di mostrarvi del codice che li gestisce in maniera programmatica ma quello era giusto per incuriosirvi e darvi subito del materiale interessante. Le possibilità a nostra disposizione sono molte di più ;)

Uno dei punti di forza dei GAS è il fatto che non dobbiamo per forza eseguirli manualmente ma abbiamo la possibilità di associare l'esecuzione a determinati eventi oppure in determinati momenti (come abbiamo già sperimentato). I trigger ci danno la possibilità di eseguire una determinata funzione al verificarsi di una determinata condizione.

In questo modo possiamo, ad esempio:

• creare un menù all'apertura di un documento
• controllare i dati inviati da un form
• controllare ogni giorno che non siano rimaste mail importanti senza risposta

La lista completa degli eventi è questa:

• allo scoccare di un'ora
• installazione di uno script
• apertura di un foglio di calcolo
• cambiamento nel foglio di calcolo
• modifica nel foglio di calcolo (simile a quello di prima ma diverso)
• invio dei dati da un form a un foglio di calcolo
• apertura dell'editor dei form
• invio dei dati da un form
• apertura di un documento

Tramite i trigger per ognuno di questi eventi possiamo associare un'azione diversa nel nostro script. Alla funzione così chiamata verrà passato un parametro specifico con dati inerenti. Ad esempio nel caso di un evento a tempo il parametro indicherà il momento in cui è pianificato mentre all'apertura di un foglio di calcolo il parametro riporterà un riferimento al foglio di calcolo stesso. Bisogna comunque tener presente che non tutti gli eventi sono disponibili per tutti gli script., ovviamente non ha senso pensare a un evento di invio dati da un form se non si ha un form ...

I trigger si dividono in due gruppi: quelli semplici e quelli installabili. Tra i due tipi ci sono molte similitudini ma diverse differenze sostanziali.

I trigger semplici possono esistere solo in script creati all'interno di altri documenti (torneremo in seguito a esaminare i vari tipi di script) e sono funzioni con nomi speciali. Per fare un esempio posso creare una funzione onEdit (attenzione a maiuscole e minuscole, javascript ci tiene molto) in uno script creato in un foglio di calcolo e questa funzione verrà automaticamente eseguita quando si modificherà un valore. Una funzionalità simile si può ottenere anche con uno trigger installabile dando un qualsiasi altro nome (mi raccomando un nome diverso da onEdit o la funzione verrà eseguita due volte) e creare un trigger sull'evento che la richiami.

Qual'è la differenza tra questi due tipi di trigger se all'apparenza sono così simili?

Le differenze sostanziali stanno nelle limitazioni dei trigger semplici:

• non possono essere eseguiti se il documento che li contiene è in sola lettura
• non possono determinare quale sia l'utente corrente
• non possono accedere a servizi che richiedono autenticazione (es. gmail o calendar)
• non possono accedere ad altri documenti

I trigger installabili (manualmente o programmaticamente) hanno la possibilità di essere scatenati da molti più eventi e sono molto meno limitati. Tenete sempre conto che i trigger installabili vengono eseguiti con i permessi dell'utente che ha installato il trigger stesso, non con quelli dell'utente che lo ha scatenato. Questo significa quindi che una funzione che invii una mail in base ad una modifica di un documento (nel caso di trigger installato) invierà sempre per conto dell'utente che ha installato il trigger, non per conto di chi ha effettivamente fatto la modifica. Analizzeremo più avanti la gestione dei permessi e delle autorizzazioni.

Rimane da parlare solo degli eventuali errori. Ebbene si, a volte gli errori capitano, anche ai programmatori. Gli Apps Script di default inviano una mail a mezzanotte con il riepilogo di tutti gli errori ma si può configurare il sistema per inviare le notifiche di fallimento in maniera istantanea. In questo modo appena un problema dovesse verificarsi la mail di notifica sarà prontamente inviata.

Ovviamente nessuno vieta a un programmatore di sfruttare il classico try ... catch per gestire eventuali errori.

Nel prossimo articolo spiegherò dettagliatamente come implementare uno script che crei un gruppo di contatti a partire dalle mail presenti in una specifica etichetta. Rimanete sintonizzati.

Nel caso vogliate approfondire gli argomenti trattati consiglio le seguenti pagine di documentazione ufficiale;

• https://developers.google.com/apps-script/understanding_events
• https://developers.google.com/apps-script/understanding_triggers

Rimandare la lettura di una mail/2

Continuiamo la serie di articoli, per tutti, incentrati sugli Apps Script. Nel caso arriviate solo adesso vi consiglio di dare almeno un'occhiata all'introduzione all'argomento.

Oggi andremo ad implementare un'ottimizzazione per il meccanismo proposto nell'articolo precedente. Come avevo fatto notare infatti la soluzione proposta aveva il difetto che tutti i post filtrati venivano recuperati solo una volta al giorno. Questo faceva si che anche se avessimo impostato il trigger tra le 21 e le 22 tutti i messaggi ricevuti dalle 22 in avanti sarebbero rimasti nascosti fino al giorno successivo, a prescindere dalla nostra disponibilità a leggerli subito.

Per ovviare a questo servirebbe che lo script venisse periodicamente eseguito durante tutto il periodo di disponibilità. Purtroppo non è possibile abilitare/disabilitare un filtro di Gmail tramite Apps Script quindi la soluzione più semplice che mi è venuta in mente mi aiuterà a mostrare come poter impostare programmaticamente un trigger.

In maniera abbastanza banale rimuoveremo il trigger creato precedentemente, creeremo due nuove funzioni che si occuperanno di create e rimuove un trigger che verrà eseguito ogni minuto il quale lancerà effettivamente la funzione originaria per il recupero delle mail. Non ci occuperemo solo di definire l'orario di esecuzione delle sue nuove funzioni che saranno l'inizio e la fine del nostro periodo di disponibilità.

Il codice aggiornato sarà questo

Si nota l'aggiunta delle due funzioni startAvailability e stopAvailability che si occupano reciprocamente di creare un trigger per eseguire (ogni 5 minuti) la funzione che recupera le mail e per rimuovere questo trigger.
Di fatto la funzione di rimozione potrebbe essere snellita se alla creazione del trigger venisse salvato il riferimento in modo da aver modo di puntare al trigger corretto da rimuovere. Personalmente preferisco questa versione perchè gestisce anche eventuali duplicazioni date da errori.

L'unica cosa che rimane da fare è modificare i trigger

in modo che appaiano così

Ovviamente dovrete avere l'accortezza di impostare i vostri orari di disponibilità, non i miei.
Inoltre potete impostare più fasce definendo altre coppie di trigger ...
Da notare che anche se il trigger riporta una fascia di un'ora la funzione verrà richiamata una volta sola. Google specifica che i trigger non sono da considerarsi puntuali ma hanno un certo margine di tolleranza. In realtà mi è capitato raramente di sperimentare dei ritardi nell'esecuzione ma per sicurezza non usateli per pianificare l'assunzione delle vostre medicine ;)

Il filtro rimane quello definito nel precedente articolo (ovviamente potete espanderlo quando volete) quindi in poco tempo siamo riusciti a ottimizzare ulteriormente questa funzionalità aggiuntiva.

Come sempre sono disponibile a rispondere alle vostre domande e desideroso di ricevere il vostro feedback. Vi sembro troppo tecnico o poco interessante ? Dite pure la vostra ;)

Rimandare la lettura di una mail

La fine arte della procrastinazione può affinarsi anche grazie ai Google Apps Script.
Io adoro essere sempre raggiungibile ma essere in controllo su chi mi possa raggiungere e quando e i  questo trovo un valido aiuto in una versione leggermente modificata di uno script rilasciato da Google diverso tempo fa.

Facciamo un esempio concreto della problematica che andremo a affrontare in questo articolo della serie #GAS.

Poniamo che siamo iscritti ad alcune newsletter commerciali (non tutto il commerciale è spam) o riceviamo notifiche di forum. Si tratta di informazioni che noi vogliamo ricevere ma magari non vogliamo che ci disturbino durante il lavoro o lo studio.

In linea di massima la priority Inbox fa un ottimo lavoro consentendoci di ricevere notifiche solo le le mail che riteniamo importanti ma tutte le altre rimarranno, archiviate o nella posta in arrivo, non lette, in attesa di ricevere le nostre attenzioni. Questo però rischia di diventare uno stimolo a interrompere la nostra attività per andare a leggere quelle mail che distolgono la nostra attenzione. Con questo metodo invece le mail verranno archiviate e segnate come lette. In questo modo non ci sarà nulla a distrarci. 

Successivamente, all'orario che avremo stabilito (una volta usciti dall'ufficio, dopo cena o rientrando a casa da scuola) le mail verranno riesumate raggiungendoci con tanto di eventuale notifica.

In questo modo non dovremo rinunciare alle informazioni che ci interessano e non correremo il rischio di venir distratti.

Vediamo subito come implementare questa utilissima funzionalità in pochi semplici passi.
Andiamo al solito indirizzo script.google.com e creiamo uno script vuoto in cui incolleremo questo codice

I commenti nel codice sono abbastanza chiari. La funzione setup è quasi superflua visto che si farebbe prima a creare l'etichetta direttamente in Gmail ma in questo modo vediamo una funzione che verrà chiamata solo una volta per preparare l'ambiente e vediamo correttamente tutto il flusso delle autorizzazioni. Adesso però diamo il via alle danze.

Lanciamo la funzione setup

alla prima richiesta di autorizzazione continuiamo

e CONTROLLIAMO SEMPRE quali autorizzazioni ci vengono richieste prima di accettare

In questo caso lo script noi vogliamo che lo script possa accedere alle nostre email e gestirle modificando etichette e stato quindi l'autorizzazione richiesta coincide con quanto vogliamo.
A questo punto andiamo a configurarlo affinché venga eseguito ogni giorno quando torniamo ad essere meno impegnati

Io ho impostato l'esecuzione tra le 21 e le 22 ma ovviamente voi ovviamente potete impostare l'esecuzione quando più vi aggrada.

Adesso lo script è pronto e autorizzato e ha impostato quanto gli serviva.

Ricordiamoci sempre che in qualsiasi momento possiamo revocare qualsiasi autorizzazione a siti/applicazioni da qui.

A questo punto tutto è pronto per recuperare le mail e non rimane altro da fare che creare un filtro per posticiparla. I criteri ovviamente li scegliete voi, l'importante è che le azioni da eseguire siano:

• saltare la posta in arrivo (archiviare)
• applicare l'etichetta "Snooze"
• segnare come letta

Fatto!

Adesso potete godervi i frutti del vostro lavoro.

Da notare che tutte le mail che verranno filtrate dopo l'esecuzione giornaliera dello script finiranno posticipate al giorno dopo (ho in programma una versione più evoluta che tratterò in seguito).

Se vi interessa l'articolo di google con lo script originale è qui

Come sempre resto in attesa dei vostri feedback ;)

Google Apps Script

Con questo post voglio inaugurare una nuova serie di post un po' più tecnici del solito su un argomento che mi sta decisamente a cuore. Non preoccupatevi però, la mia intenzione non è solo di fornire sterile nozionismo ma voglio guidare per mano coloro che sono interessati a conoscere l'argomento e fornire comunque un prodotto finito per l'utente finale che potrà saltare le spiegazioni e godersi il risultato finale.

Una serie di post per tutti per poter ottenere il meglio dai prodotti Google.

Iniziamo un attimo a capire cosa di cosa sto parlando: Google Apps Script è un sistema cloud per l'esecuzione di codice JavaScript per estendere le funzionalità delle Google Apps. Detto così sembra Arabo ma un mio collega egiziano mi conferma che non lo è. In pratica Google fornisce la possibilità di scrivere di semplici programmi che vengono eseguiti direttamente sui suoi server collegati ai suoi prodotti. Si può creare uno script che salva gli allegati di mail con una certa etichetta in una cartella su Drive. Si può controllare il calendario e mandare delle mail in base a determinati eventi. Si può creare un template per delle mail in Drive e automatizzare la personalizzazione e l'invio a un gruppo di contatti. Si può fare anche molto di più andando a creare interfacce web per l'interazione umana e elaborare i dati fornendo un feed rss o un json per renderli accessibili a terze parti (o ad applicazioni Android). Si può fare ancora molto di più e sempre in maniera molto semplice e veloce.

Ovviamente ci sono anche delle restrizioni. I nostri script avranno a disposizione delle risorse limitate: una singola esecuzione non può protrarsi oltre i 6 minuti (che è già un bel tempo) quindi dovremo elaborare grosse quantità di dati in più scaglioni. Ci sono anche limitazioni sulle 24 ore, sul traffico generato e su altre cose ma in linea di massima impareremo a convivere con questi limiti creando comunque delle piccole meraviglie (lo stato di funzionamento dei vari servizi e il riepilogo delle quote è consultabile qui).

Ovviamente per raggiungere i massimi livelli di competenza i requisiti sono la conoscenza della lingua Inglese, una mentalità da programmatore e la conoscenza di JavaScript. Il mio obiettivo però è ampliare il più possibile il bacino d'utenza includendo anche chi non abbia alcuno di questi requisiti.

Il modo migliore per iniziare è puntare direttamente su script.google.com

Come si può vedere di default abbiamo una schermata con 3 sezioni:

•  a sinistra abbiamo la possibilità di sfruttare dei semplici template per utilizzare, velocemente ed in modo guidato, i vari servizi
• a destra nella metà superiore abbiamo link ad alcuni tutorial
• a destra in basso abbiamo gli script più recenti che abbiamo aperto

Una volta divenuti degli esperti non avremo più bisogno di questa schermata e potremo evitare di farla comparire ogni volta.

Vi consiglio di provare a selezionare Gmail dalla colonna di sinistra, di dare un'occhiata al codice che viene mostrato e all'ambiente con cui cercherò di farvi familiarizzare nell'arco dei prossimi post.

Questo esempio non vi darà problemi se avete la inbox quasi vuota altrimenti girerà molto a lungo ...
Il mio consiglio è di modificare la riga numero 9 da

for (var i = 0; i < threads.length; i++) {

in

for (var i = 0; i < threads.length && i < 3; i++) {

in questo modo (oltre ad aver fatto la vostra prima modifica a uno script) vi assicurerete che lo script sia eseguito al massimo sulle prime 3 discussioni della vostra inbox.
Il passo successivo è salvare questo nuovo semplice progetto in modo da poterlo testare. Una volta datogli un nome (io l'ho chiamato "test gmail") possiamo aprire il menù "Esegui", cliccare su "processInbox" e ammirare la prima finestra di sicurezza "Autorizzazione richiesta". Uno script per accedere ai dati richiede delle autorizzazioni da parte dell'utente, approfondiremo in seguito. Per ora iniziamo a cliccare su "Continua" e controlliamo nella nuova finestra il dettaglio delle autorizzazioni richieste che in questo caso si limitano a "Visualizza e gestisci la tua posta" (considerando che la funzione in questione andrà a scorrere i messaggi nella inbox e loggare gli oggetti direi che è sensato). Una volta terminata l'esecuzione dal menù "Visualizza" si può accedere al "Log" e troveremo una lista degli oggetti dei messaggi delle discussioni presenti nella nostra inbox (al massimo delle prime 3).

Una volta finiti i vostri test potete rimuovere l'autorizzazione concessa andando qui e cercando il nome del progetto (nel mio caso "test gmail") e cliccando sul pulsante a fianco.

Il prossimo articolo sarà su un mio piccolo adattamento di uno script pubblicato da Google diverso tempo fa incentrato sull'ottimizzazione delle mail ricevute per non essere distratti durante il lavoro ma essere sicuri di non perdere nemmeno una delle mail che vogliamo ricevere.

Spero con questo di aver iniziato a incuriosirvi e di invogliarvi a seguire questa serie di articoli taggati #GAS.
Nel frattempo potete iniziare a dare un'occhiata alla sezione ufficiale sul portale per gli sviluppatori di Google https://developers.google.com/apps-script (in Inglese)

P.S. si, so che alcuni di voi se ne saranno accorti: sto cercando di guadagnarmi il titolo di GDE per Apps Script quindi il vostro apprezzamento, i vostri consigli e le vostre critiche sono ben più che graditi. SONO RICHIESTI !!!