Descrizione Configurazione Modulo Twilio

Revisione 001 del 29/06/2020

Autore Francesco Manca

Configurazione Modulo Twilio

Cosa è Twilio

Twilio è una piattaforma di sviluppo che tramite l’uso delle API appositamente sviluppate permette di
aggiungere alla propria applicazione delle funzionalità vocali e di messaggistica senza occuparsi dei
protocolli di trasporto e instradamento del settore delle telecomunicazioni.

Twilio con Ignition

Il modulo Twilio è disponibile come download separato dall’ installer di Ignition. Tale modulo abilita l’invio
di messaggi SMS agli utenti, per la notifica di allarmi o per ricevere informazioni riguardanti lo stato del
gateway.

Come si usa

E’ necessario scaricare ed installare il Twilio Notification Module e l’Alarm Notification Module dalla sezione
per la propria versione di Ignition (https://inductiveautomation.com/downloads/ignition/8.0.14).

Il modulo Twilio abilita la creazione di un profilo dedicato alla notifica di allarmi via SMS ed inoltre sblocca
le funzioni di scripting system.twilio, che consentono di inviare messaggi SMS tramite codice Python: per
maggiori dettagli si veda la sezione (https://docs.inductiveautomation.com/display/DOC80/system.twilio)
dell'Appendice del manuale utente di Ignition.

Prerequisiti:

Il modulo dipende dalla presenza del modulo Notifica allarmi che deve essere già installato per permettere
l’invio di allarmi SMS con Twilio. L’Invio di notifiche di allarme via SMS avviene senza un dispositivo fisico:
non è quindi richiesto un modem cellulare, ma il Gateway deve avere accesso ad Internet e deve essere
stato creato un account Twilio con funzionalità SMS su www.twilio.com .

L'account Twilio, una volta attivo, deve essere opportunamente registrato in una sezione della
configurazione del Gateway Ignition.

Pag. 1 di 16
 Descrizione Configurazione Modulo Twilio
Revisione 001 del 29/06/2020
Autore Francesco Manca

Creazione dell’account Twilio

1. Creare un account gratis su www.twilio.com. L’account gratuito, appena creato, contiene un
credito di partenza pari a 15.50 $, che serve per acquistare i servizi. L’account è caratterizzato da
due codici:

 1 SID specifico dell’account Twilio;

 Un authorization Token: quest’ultimo viene di base mascherato nella dashboard
dell’account ed è necessario premere “show” per mostrarlo e poter copiare il codice
associato, che servirà nella successiva fase di inserimento dell’account nel gateway Ignition;

E’ necessario acquistare un numero di telefono al costo di 1$, che verrà usato poi come riferimento del
chiamante all’interno della configurazione di invio in Ignition. Il numero acquistato per la prova è di tipo
americano, in quanto tale tipologia di numero permette l’invio di sms internazionali. Per un account free si
può acquistare al massimo un numero di telefono. I numeri Twilio si distinguono in due categorie: Dual
functionality e Voice enabled only e non tutti consentono l’uso delle funzioni SMS che serviranno dentro
Ignition per la notifica.

Pag. 2 di 16
 Descrizione Configurazione Modulo Twilio
Revisione 001 del 29/06/2020
Autore Francesco Manca

I numeri appartenenti alla categoria Dual functionality offrono le funzionalità di invio SMS internazionali.
Sono disponibili al momento dello scrivere le seguenti nazioni, tra cui l’Italia è assente:

Chiamate SMS
Country Tipo
internazionali Internazionali

Australia Mobile Yes Yes

Belgio Mobile No Yes

Canada Local No No

Cile Local No Yes

Cile Local Yes Yes

Danimarca Mobile No No

Francia Mobile No No
Israele Mobile No No

Olanda Mobile No No

Puerto Rico Local No No

Sud Africa Mobile No Yes

Regno Unito Mobile No No

Regno Unito Local No No

Stati Uniti Local No No

Pag. 3 di 16
 Descrizione Configurazione Modulo Twilio
Revisione 001 del 29/06/2020
Autore Francesco Manca

Configurazione dell’account Twilio nel Gateway Ignition

Attenzione! IL MODULO ALARM NOTIFICATION DEVE ESSERE GIÀ INSTALLATO AL FINE DI ABILITARE
L’USO DEL TWILIO NOTIFICATION MODULE

https://inductiveautomation.com/downloads/ignition

e quindi scarichiamo il Twilio Notification Module dalla sezione Notification alla pagina di Download.

A seguito dell’ installazione del modulo viene aggiunta una sezione di configurazione nel Gateway
denominata “Twilio”. In questa sezione inseriremo l’SID e il token dell’account Twilio che abbiamo
configurato al punto 1.

Pag. 4 di 16
 Descrizione Configurazione Modulo Twilio
Revisione 001 del 29/06/2020
Autore Francesco Manca

Al termine delle operazioni di configurazione, se il gateway è installato su un PC connesso ad

internet, l’account diviene immediatamente attivo come indicato nell’immagine seguente:

Pag. 5 di 16
 Descrizione Configurazione Modulo Twilio
Revisione 001 del 29/06/2020
Autore Francesco Manca

Creazione di un profilo di notifica

Un profilo di notifica definisce un canale di consegna attraverso il quale un messaggio di allarme può essere
inviato a un utente. Il modulo di notifica allarmi viene fornito con vari profili di notifica e-mail /SMS e voce,
sia unidirezionali che bidirezionali. Creiamo un nuovo profilo dedicatoa ll’invio di SMS con Twilio.

Scegliamo il profilo di notifica dedicato a Twilio:

Pag. 6 di 16
 Descrizione Configurazione Modulo Twilio
Revisione 001 del 29/06/2020
Autore Francesco Manca

Diamo un nome al profilo di notifica ed associamolo all’account precedentemente inserito: compiliamo il

numero di telefono in base al numero acquistato riportandolo esattamente come indicato dalla Dashboard
di Twilio.

Pag. 7 di 16
 Descrizione Configurazione Modulo Twilio
Revisione 001 del 29/06/2020
Autore Francesco Manca

Pag. 8 di 16
 Descrizione Configurazione Modulo Twilio
Revisione 001 del 29/06/2020
Autore Francesco Manca

Compilazione di un profilo Utente

Per usare il modulo è ora necessario creare un profilo utente che possieda un utenza telefonica associata. Si
può inserire il numero di telefono nella sezione “Contact info” avendo cura di indicare il formato
internazionale con il codice +39 se si desidera chiamare un numero italiano.

Pag. 9 di 16
 Descrizione Configurazione Modulo Twilio
Revisione 001 del 29/06/2020
Autore Francesco Manca

Il sistema di notifica degli allarmi utilizza poi il sistema di pianificazione utente incorporato in Ignition. I
messaggi di notifica di allarme verranno pertanto inviati SOLO agli utenti la cui pianificazione è attualmente
attiva. Verificare pertanto questa impostazione nel corso della configurazione dell’utente.

Creazione di un On-Call Roster

Un On-Call Roster è un raggruppamento ordinato di utenti. Questi gruppi sono usati per riunire gli utenti in
modo che gli allarmi possano essere inviati a delle liste preordinate. A seconda del profilo di notifica degli
allarmi utilizzato, gli utenti possono essere avvisati uno alla volta (in sequenza) o tutti insieme (in parallelo).
È possibile creare e gestire gli elenchi su chiamata dalla pagina di configurazione del gateway:

Nel nostro caso è stata creata una lista denominata “Reperibili” che include gli utenti che desideriamo
vengano contattati all’attivazione della condizione di allarme.

La configurazione degli utenti viene fatta selezionando dalla user source gli utenti da assegnare al roster
predefinito:

Salviamo le impostazioni, e al fine di poter testare la nostra configurazione, è necessario a questo punto
della procedura entrare nel designer e creare una nuova pipeline di notifica.

Pag. 10 di 16
 Descrizione Configurazione Modulo Twilio
Revisione 001 del 29/06/2020
Autore Francesco Manca

Creazione di una Pipeline Allarme per invio SMS con Twilio

L’Alarm Pipeline gestisce le azioni da compiere quando un allarme transita in una delle seguenti condizioni:

 Active
 Clear
 Acknowledge

Essa è composta da uno o più elementi, detti blocchi di notifica, all’interno dei quali sono codificate le
azioni da intraprendere. Ogni blocco di notifica contiene la configurazione specifica necessaria per definire
gli utenti a cui notificare l’allarme.

Creiamo una pipeline denominata “SMSPipeline” in cui inseriamo un blocco di tipo notification

E’ necessario configurare il blocco con l’account Twilio , specificando il corrispondente numero telefonico
ad esso associato:

Nel tab di configurazione “Contacts” è necessario specificare la configurazione dell’On-Call Roster.

Pag. 11 di 16
 Descrizione Configurazione Modulo Twilio
Revisione 001 del 29/06/2020
Autore Francesco Manca

Nella configurazione di un sistema di notifica allarme è buona pratica configurare anche la sezione
“Consolidation”. Il consolidamento delle notifiche consente di limitare il numero di SMS spediti dal sistema,
grazie all’introduzione di un tempo di ritardo durante il quale verranno raccolti gli eventi di allarme in
arrivo. Alla scadenza del ritardo, tutti gli eventi giunti verranno inviati insieme al profilo di notifica.

Dato l’uso di un servizio a consumo, come Twilio, è quindi opportuno configurare la sezione

Il delay definisce quanti secondi attendere per raccogliere altri allarmi che eventualmente si sono attivati
(in questo caso si aspettano altri allarmi per un tempo massimo di 15 secondi), mentre il parametro
Frequency definisce la cadenza di invio delle notifiche (in questo caso dopo una prima notifica si attenderà
un minuto prima di inviarne una nuova).

La configurazione grafica risultante dalla semplice pipeline creata è la seguente:

Pag. 12 di 16
 Descrizione Configurazione Modulo Twilio
Revisione 001 del 29/06/2020
Autore Francesco Manca

Che significa che per ogni invocazione dell’alarm pipeline il sistema entrerà direttamente nel blocco di
notifica e invierà gli allarmi.

Possiamo ora testare il funzionamento andando nella sezione “Notification\Test Pipelines and Notification
profiles”

Scegliamo il profilo di Notifica SMS

Quindi premiamo Invio. Il sistema effettuerà un tentativo di invio del messaggio presentando il progresso
dell’operazione sino a presentare un errore o a dare conferma della corretta esecuzione.

Pag. 13 di 16
 Descrizione Configurazione Modulo Twilio
Revisione 001 del 29/06/2020
Autore Francesco Manca

Subito dopo dovremmo ricevere al numero indicato per il nostro utente l’SMS di notifica di prova.

ATTENZIONE!

DEGLI UTENTI INSERITI NEL REGISTRO DELL’ON-CALL ROSTER, SOLO GLI UTENTI LA CUI PIANIFICAZIONE È
ATTUALMENTE ATTIVA RICEVERANNO EFFETTIVAMENTE IL MESSAGGIO DI NOTIFICA DI ALLARME.
ACCERTARSI DUNQUE CHE LO SCHEDULING PER GLI UTENTI VERSO CUI SI FA IL TEST SIA COMPATIBILE
CON LA FASCIA ORARIA DI DISPONIBILITÀ DEGLI STESSI !

Pag. 14 di 16
 Descrizione Configurazione Modulo Twilio
Revisione 001 del 29/06/2020
Autore Francesco Manca

Pag. 15 di 16
 Descrizione Configurazione Modulo Twilio
Revisione 001 del 29/06/2020
Autore Francesco Manca

Esempi di impiego delle funzioni system.twilio

Le funzioni abilitate dall’installazione del modulo Twilio consentono di operare via scripting python con il
proprio account. La lista completa della funzioni è la seguente:

 system.twilio.getAccounts
 system.twilio.getAccountsDataset
 system.twilio.getPhoneNumbers
 system.twilio.getPhoneNumbersDataset
 system.twilio.sendSms

Vediamo alcuni esempi:

1: Per ottenere il nome dell’account Twilio registrato nel proprio sistema

account = system.twilio.getAccounts()[0]
print account

2: Ottenere il numero di telefono associato al proprio account:

account = system.twilio.getAccounts()[0]
getNumber = str(system.twilio.getPhoneNumbers(account)[0])
print getNumber

3: Invio di un SMS mediante script.

#Invio SMS.
#Recuperiamo il nome dell’account Twilio
#getAccounts() restituisce una lista, quindi l’operatore "[0]" operator prende
il primo oggetto della lista.
account = system.twilio.getAccounts()[0]

#Recuperiamo il numero associato all’account

fromNumber = str(system.twilio.getPhoneNumbers(account))
#print fromNumber
#Prendiamo le informazioni di contatto dell’utente
#Qui si usa un valore statico, ma system.user.getUser() può essere usato per
acquisire il numero di telefono dell’utente
toNumber = "+393331234567"

#Definiamo il corpo del messaggio

# Qui sotto viene usato un messaggio fisso, ma può essere usato un testo preso
da un database o da un campo di testo.
textMessage = "This is the body of a text message"

#Inviamo il messaggio
system.twilio.sendSms(account, fromNumber, toNumber, textMessage)

Pag. 16 di 16