L'editor grafico
Installato ed attivato il modulo aggiuntivo BPMN.IO che aggiunge l'editor grafico, possiamo iniziare a costruire le procedure ECA (Eventi, Condizioni, Azioni), disegnandole direttamente nel web browser. Il disegno segue una versione semplificata e ridotta dello standard BPMN (Business Process Model and Notation). Non è importante che tu conosca questo standard, perché in questa Guida ti fornirò le informazioni essenziali, mentre nelle Guide seguenti costruiremo insieme alcuni esempi.
Per entrare nell'editor, vai in Configurazione - ECA e clicca Add new model (in Drupal le procedure ECA sono chiamate "modelli" ma questo nome a me sembra vago). Ti appare un foglio da disegno vuoto, racchiuso da due barra di icone (a sinistra e sotto il foglio) e da una barra di pulsanti in alto. Nella figura che segue, ti mostro anche le due finestre di configurazione che appaiono quando clicchi su un elemento disegnato nel foglio:
| ECA Model: NOME DELLA PROCEDURA | Salva | Archivio | Ricetta | Token |
 | |||||
 Spostati sul foglio da disegno |  FOGLIO DA DISEGNO | |||||||||
 Seleziona più elementi disegnati | ||||||||||
 Spazia gli elementi disegnati | ||||||||||
 Seleziona un elemento disegnato | ||||||||||
 Disegna un Evento | ||||||||||
 Disegna un gateway per le Condizioni | ||||||||||
 Disegna una Azione | ||||||||||
 Cambia nome della procedura |  Riordina il disegno |  Scarica il disegno |  Copia |  Incolla |  Zoom in |  Zoom out |  Zoom tutto |  Cerca |  Mini mappa | |
I comandi per spostare , zoomare, riordinare e scaricare il disegno e quelli con cui selezionare uno o più elementi del disegno sono intuitivi e non li spiego. Mi soffermo invece sui comandi di disegno vero e proprio, evidenziati in grassetto nella figura.
Disegnare una procedura
Disegnare una procedura ECA con l'editor grafico consiste nell'aggiungere al foglio da disegno uno o più elementi collegati da frecce e nella loro configurazione. Gli elementi sono:
 | un cerchio rappresenta un Evento |
 | un rettangolo rappresenta una Azione |
 | un rombo rappresenta un gateway, utile per introdurre diramazioni del disegno controllabili da Condizioni |
 | una freccia rappresenta un collegamento da un elemento al successivo; i collegamenti stabiliscono in quale ordine temporale gli altri elementi vengono eseguiti da Drupal |
 | un riquadro aperto collegato ad un elemento da un collegamento a puntini rappresenta un commento, utile per documentare la procedura |
Ci sono due modi per aggiungere elementi al disegno:
- cliccare sull'icona corrispondente all'elemento nella barra di sinistra e trascinare l'elemento nel foglio (solo per cerchi, rettangoli e rombi)
- cliccare su un elemento già inserito nel disegno: nel menù grafico che appare sulla sua destra, cliccare sul nuovo elemento che si vuole aggiungere al disegno; in questo menù sono presenti anche il comando per cancellare l'elemento (bidone) e per colorare l'elemento (pennello)
Configurare un elemento
Un elemento aggiunto al disegno non serve a nulla se non si specifica quale funzione svolge ed quali sono i parametri necessari al suo funzionamento. Quando aggiungi un elemento nel disegno o clicchi su un elemento già disegnato, si apre la finestra Choose element template, in cui devi selezionare la funzione (template) svolta dall'elemento: le funzioni disponibili dipendono dal tipo di elemento (Evento, Condizione, Azione) e da quali moduli ECA hai attivato. Le funzioni sono elencate raggruppate per modulo. Selezionata una funzione, si apre la finestra di configurazione, in cui devi indicare i parametri richiesti dalla funzione. Se hai sbagliato a selezionare la funzione, nella finestra di configurazione clicca l'icona "bidone" per eliminarla dall'elemento e tornare a selezionare un'altra funzione.
I Token nelle procedure
Ogni elemento può creare o valorizzare un Token. Un Token creato o valorizzato da un elemento può essere usato per configurare gli elementi seguenti, nell'ordine indicato dalle frecce. Un Token quindi memorizza e trasporta lungo la procedura un valore, che può essere un testo, un numero, una data, una Entità o anche una lista di Entità. Ad esempio, se un elemento crea un Token di nome "attrezzo" e vi memorizza una Entità, nella configurazione di un elemento successivo potremo:
- usare il Token, digitandone il nome (senza parentesi): attrezzo
- usare il valore del Token (cioè l'Entità memorizzata in esso) digitiamone il nome tra parentesi quadre: [attrezzo]
Oltre ai Token creati lungo la procedura, per la configurazione degli elementi hai anche a disposizione i Token corrispondenti ai Campi delle Entità: per identificarli e copiarli nella configurazione degli elementi clicca il pulsante Token in alto a destra: ti viene mostrata la gerarchia dei Token da cui puoi copiare ed incollare i Token. Nella gerarchia, i Token sono però mostrati con un nome generico, che indica il tipo di Entità: ad esempio, il Token del Campo che contiene il nome dell'Autore di un Contenuto è [node:author], perché node è nome generico dei Contenuti. Quando incolli il Token nella configurazione di un elemento, devi invece specificare da quale Entità prelevare il valore del Campo sostituendo il nome generico col nome del Token in cui è memorizzata l'Entità: se l'Entità è memorizzata nel Token "attrezzo", nella configurazione modificherai [node:author] in [attrezzo:author].
Documentare una procedura
Se nella tua app crei più di una procedura ECA e, soprattutto, se le tue procedure non sono banali, è opportuno che documenti per bene cosa fa ogni procedura, per poterle manutenere nel tempo. Anzitutto dai un nome alla procedura che ricordi in modo stringato a cosa serve: clicca l'icona:
Appare una finestra in cui puoi digitare il nome ed una descrizione della procedura. Ti raccomando inoltre di descrivere cosa fa ogni elemento: basta cliccarci sopra e modificare la sua descrizione. Per descrivere cosa fa un percorso della procedura, puoi aggiungere un commento sul primo elemento del percorso e digitarvi una spiegazione. Infine, puoi scaricare il disegno della procedura cliccando l'icona:
Viene scaricato un file in formato SVG, che può essere importato in Word o LibreOffice.
Ogni procedura è esportabile col pulsante Archivio in formato YAML compresso (estensione .gz) , che è comprensibile con qualche difficoltà anche da un lettore umano. Puoi usare il file come base per scrivere un documento più chiaro. Oppure puoi andare su Gemini (o su altre IA generative), caricare il file esportato da Drupal con un prompt del tipo "traduci in un documento leggibile la configurazione del modello ECA di Drupal che ho caricato" e potresti ottenere una buona spiegazione della tua procedura.
Eseguire la procedura
Dopo che hai salvato la procedura col pulsante Salva, la procedura è pronta e resta in attesa che accada uno degli Eventi che hai inserito nel suo disegno. Quando infatti accade uno di essi, partendo da quell'elemento Drupal percorre il disegno seguendo le frecce ed esegue le funzioni associate agli elementi via via incontrati. L'esecuzione termina quando il percorso arriva su in un elemento da cui non partono altre frecce o che non richiama un'altra procedura (vedi Azione Custom Event).
Per impedire che una procedura venga eseguita, in Configurazione - ECA seleziona il comando Disattiva sulla procedura.
Gli Eventi
Per essere eseguita, la procedura deve contenere almeno un Evento. Se una procedura contiene più Eventi, verrà eseguita quando accade uno qualunque di essi, quindi la medesima procedura può rispondere a diversi Eventi. I tipi di Eventi sono molti. Ecco una breve spiegazione di quelli che, nella mia esperienza, sono più utili nella costruzione di una app:
| Evento | Attiva la procedura quando | Utile per |
| Presave content entity | un Utente salva una Entità. In Type seleziona il tipo di Entità per cui la procedura deve essere eseguita (es. "Contenuto - Attrezzo" o "Utente"). L'Evento memorizza nel Token [entity] l'Entità su cui è stata attivata. | modificare Campi dell'Entità prima di salvarla |
| Endpoint access | un Utente clicca il link corrispondente alla procedura. In First path argument digita una parola che identica la procedura (es. "consegna") cui puoi eventualmente aggiungere in Second path argument una seconda parola (es. "accettazione"): in questo caso la procedura sarà eseguita quando l'Utente clicca il link /eca/consegna/accettazione?id=453 che esporremo all'Utente come un comando all'interno di una Vista). Se, come in questo esempio, il link "passa" alla procedura un argomento (es. l'identificativo 453 della consegna da accettare), nella procedura useremo l'Azione Request: Get URL query parameter per memorizzare l'argomento in un Token. L'Evento memorizza nel Token [account] l'Utente che ha cliccato il link. | creare comandi non disponibili nativamente in Drupal |
| Cron event | si è arrivati ad una scadenza temporale. In Frequency digita ogni quanto eseguire la procedura, col formato spiegato in https://en.wikipedia.org/wiki/Cron | eseguire periodiche attività di manutenzione della app |
| Login of a user | un Utente entra in Drupal. L'Evento memorizza nel Token [account] l'Utente che ha fatto login. | mostrare un avviso all'ingresso dell'Utente |
| Custom event | un'altra procedura esegue l'Azione Trigger a custom event In Event ID assegna un nome univoco alla procedura: questo nome sarà usato dalla procedura "attivante" per eseguirla. | creare una "sub procedura", attivata in più punti di una procedura o da diverse procedure |
| Custom event (entity aware) | un'altra procedura esegue l'Azione Trigger a custom event (entity aware) passandole una Entità su cui agire. In Event ID assegna un nome univoco alla procedura: questo nome sarà usato dalla procedura "attivante" per eseguirla. L'Entità ricevuta è memorizzata nel Token [entity] | eseguire un ciclo di Azioni su Entità |
Le Azioni
Le Azioni sono le istruzioni eseguite da Drupal quando la procedura viene attivata. Ecco una breve spiegazione dei tipi di Azioni che, nella mia esperienza, sono più utili nella costruzione di una app:
| Azione | Cosa fa | Utile per |
| Mostra un messaggio all'utente | mostra un messaggio all'Utente, al termine dell'esecuzione della procedura. In Messaggio digita il testo da mostrare, che può contenere i valori di Token. | mostrare il valore di uno o più Token per verificare il corretto funzionamento della procedura (debug), avvisare l'Utente che la procedura ha effettuato modifiche ad una Entità. |
| Reindirizza all'URL | porta l'Utente su una pagina. Come parametro URL digita il link della pagina cui trasportare l'Utente; nel link puoi usare i valori di Token. | reindirizzare l'Utente dopo la eliminazione di una Entità o al termine dell'esecuzione della procedura |
| Entity: create new | crea una nuova Entità. In Name of token digita il nome del Token che memorizza l'Entità creata. In Tipo seleziona il tipo di Entità da creare. Parametri opzionali: in Etichetta il titolo della nuova Entità e in Owner UID l'identificativo dell'Utente che la crea. | creare nuove Entità come conseguenza di altre azioni |
| Entity: Load | memorizza in un Token una Entità esistente. In Name of token digita il nome del Token in cui memorizzare l'Entità. In Load entity from seleziona la modalità con cui identificare l'Entità. I parametri che seguono dipendono dalla modalità scelta: se selezioni Type and ID (l'opzione più semplice) in Tipo di Entità seleziona il tipo di Entità da caricare (es. Utente) e in ID Entità digita il suo identificativo. | mettere a disposizione della procedura le informazioni dell'Entità |
| Entity: Save | salva l'Entità memorizzata in un Token. In Name of token digita il nome del Token in cui è memorizzata l'Entità da salvare. | salvare le modifiche apportate dalla procedura all'Entità |
| Entity: Delete | elimina l'Entità memorizzata in un Token. In Name of token digita il nome del Token in cui è memorizzata l'Entità da eliminare. | eliminare Entità |
| Token: set value | crea un nuovo Token o aggiorna il valore di un Token esistente. In Name of token digita il nome del Token da creare o aggiornare. In Value of the token digita il valore da assegnare al Token, può contenere valori di Token.. | aggiungere e modificare Token nella procedura |
| Entity: set field value | aggiorna il Campo di una Entità. In Nome del campo digita il nome interno del Campo da aggiornare. In Valore del campo digita il valore da assegnare al Campo (può contenere valori Token). In Salvataggio Entità attiva l'immediato salvataggio dell'Entità (sconsiglio di farlo se la procedura è stata attivata dall'Evento Presave content entity). In Entità digita il nome del Token in cui è memorizzata l'Entità di cui modificare il Campo. | modificare i Campi di Entità |
| List: add item | aggiunge una Entità ad un elenco di Entità memorizzato in un Token. In Token containing the list digita il nome del Token che memorizza l'elenco. In Value to add digita il valore del Token che contiene l'Entità da aggiungere. Restituisce il Token aggiornato. | creare una lista di Entità su cui eseguire una procedura Custom event (entity aware) |
| Current user: load | memorizza in un Token l'Utente corrente. In Name of token digita il nome del Token in cui memorizzare l'Utente | mettere a disposizione della procedura le informazioni dell'Utente corrente |
| User: switch current account | cambia l'Utente che sta eseguendo la procedura. In User ID digita l'identificativo dell'Utente cui passare | eseguire la procedura come Amministratore superando i limiti imposti all'Utente corrente |
| Views: Execute query | memorizza in un Token le Entità elencate da una Vista. In Name of token digita il nome del Token in cui memorizzare l'elenco. In Visualizza seleziona la Vista. In Visualizzazione digita il nome interno della Visualizzazione della Vista. In Parametri digita gli argomenti da passare ai Filtri contestuali della Vista. | mettere a disposizione della procedura un elenco di Entità, su cui poi eseguire un ciclo di Azioni. |
| Trigger a custom event (entity-aware) | attiva una procedura secondaria, passandole un elenco di Entità su cui agire. In Event ID digita l'identificativo della procedura secondaria. In Entità digita il nome del Token che contiene l'elenco delle Entità. In Tokens to forward digita i nomi di eventuali altri Token passati alla procedura secondaria e che potranno da essa essere modificati. La procedura secondaria ha un evento di tipo Custom event (entity aware) | eseguire un ciclo di azioni sulle Entità |
| Request: Get URL query parameter | memorizza in un Token un argomento letto dal link di attivazione della procedura. In Name of token digita il nome del Token in cui memorizzare l'argomento. In Query parameter name digita il nome dell'argomento da cercare nel link | leggere gli argomenti in una procedura attivata dall'Evento Endpoint access |
| Tamper: Math | memorizza in un Token il risultato di una operazione matematica. In Data to be tampered digita il primo valore (può essere il valore di un Token). In Operazione seleziona l'operatore. In Valore digita il secondo valore (può essere il valore di un Token). In Result token name digita il nome del Token dove memorizzare il risultato. Richiede l'installazione del modulo aggiuntivo "ECA Tamper Integration" | eseguire calcoli nella procedura |
Le Condizioni (e i gateway)
Quando due elementi sono collegati da una freccia, Drupal li esegue sequenzialmente secondo il verso della freccia stessa. Applicando una Condizione alla freccia possiamo consentire o impedire l'esecuzione del secondo elemento (e di tutti quelli che lo seguono) sulla base dell'esito (positivo o negativo) di un confronto tra un valore dedotto da un Token ed un secondo valore (fisso o preso da un altro Token). Se da un elemento escono più frecce, applicando diverse Condizioni a ciascuna di esse possiamo far proseguire l'esecuzione in una parte della procedura oppure in un'altra. Quindi è come se le Condizioni facessero apparire o sparire le frecce in base ai valori assunti dei Token durante l'esecuzione.
Non è strettamente obbligatorio, però inserire un gateway (rombo) prima di un gruppo di frecce soggette a diverse Condizioni che dipartono da un medesimo elemento facilita la comprensione del disegno:
Le Condizioni sono applicate alle frecce, non al gateway. Oltre che come elemento che "divide" la procedura in tanti percorso alternativi, il gateway è usato anche come elemento che "raccoglie" percorsi precedentemente separati, come illustrato nell'esempio.
Ecco una breve spiegazione dei tipi di Condizioni che, nella mia esperienza, sono più utili nella costruzione di una app:
| Azione | Cosa fa | Utile per |
| Compare number of list items | Confronta il numero di Entità contenute in un Token con un altro numero. In Name of token containing the list digita il nome del Token che ha memorizzato l'elenco delle Entità. In Operatore di comparazione seleziona l'operatore di confronto (es. "maggiore di"). In Second value digita il valore con cui confrontare. Attiva Nega la condizione se vuoi invertire la condizione. | Verificare se ci sono ancora entità nella lista |
| Compare two scalar values | Confronta due valori. In First value digita il primo valore (accetta valori da Token). In Operatore di comparazione seleziona l'operatore di confronto (es. "maggiore di"). In Second value digita il secondo valore. Attiva Nega la condizione se vuoi invertire la condizione. | Confrontare due valori, ad esempio il valore di due Campi |
| Current user ID | Verifica se l'Utente corrente ha come identificativo un valore. In ID Utente digita il valore (accetta valore da un Token). Attiva Nega la condizione se vuoi invertire la condizione. | verificare se l'autore di una Entità (il cui identificativo è stato memorizzato in un Token) coincide con l'Utente corrente |
| Entity: field value is empty | Verifica se il Campo di una Entità è vuoto. In Nome del campo digita il nome interno del Campo. In Entità digita il nome del Token in cui è memorizzata l'Entità. Attiva Nega la condizione se vuoi invertire la condizione. | Verificare se il Campo di una Entità non è stato valorizzato. |