# JE6 - I flussi

# JE6.1 - Il primo flusso

**In una frase.** Un flusso dice cosa succede e in che ordine: lo disegni collegando dei nodi, e salvandolo nasce già la schermata.

Form, tabella ed endpoint da soli sono pezzi fermi. Il flusso li mette in moto: «quando si apre la pagina leggi i dati, quando l'utente preme Cerca rileggili con i suoi filtri, e metti le righe nella tabella».

<div drawio-diagram="2706"><img src="https://gsdoc.genesyssoftware.eu/uploads/images/drawio/2026-11/come-gira-un-flusso-qualcosa-lo-avvia-i-nodi-lavorano-alla-fine-resta-lesito.png" alt="Come gira un flusso: qualcosa lo avvia, i nodi lavorano, alla fine resta l&#039;esito"/></div>

*Come gira un flusso: qualcosa lo avvia, i nodi lavorano, alla fine resta l'esito*

1. **Crea il flusso.** Dal menu: **Low-Code Platform › Dynamic Flows**, poi **Nuovo flusso**. Scegli una delle due strade.
    
    ![Nuovo flusso: la strada guidata per le ricerche, il grafo libero per il resto](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/nuovo-flusso-la-strada-guidata-per-le-ricerche-il-grafo-libero-per-il-resto.png)
    
    *Nuovo flusso: la strada guidata per le ricerche, il grafo libero per il resto*
    
    
    - **Quick Flow Designer**: sei passi guidati per una ricerca completa, con filtri, risultati, grafico, azioni e voce di menu. Per consultare dati è la strada più corta.
    - **Flow Designer**: il disegno libero, nodo per nodo. I passi qui sotto seguono questa.
2. **Metti i nodi.** Trascinali dall'elenco a sinistra, o premi **Tab** e scrivi il nome. Per una ricerca ne bastano quattro: **Start**, **Form**, **Endpoint**, **Tabella**.
3. **Collegali.** Trascina dal quadratino a destra di un nodo a quello a sinistra del successivo. Se colleghi due nodi che non si capiscono, il bordo diventa rosso subito.
4. **Riempi ogni nodo.** Un clic sul nodo apre le proprietà a destra. Nel Form scegli quale form, nell'Endpoint quale endpoint e da dove prende ogni filtro, nella Tabella quale tabella.
    
    ![Il Flow Designer: a sinistra i nodi, al centro il disegno, a destra le proprietà del nodo scelto](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/il-flow-designer-a-sinistra-i-nodi-al-centro-il-disegno-a-destra-le-proprieta-del-nodo-scelto.png)
    
    *Il Flow Designer: a sinistra i nodi, al centro il disegno, a destra le proprietà del nodo scelto*
5. **Salva.** In basso la barra dice se il disegno regge. Salvando, la schermata nasce da sola: un riquadro per ogni nodo che si vede, il form sopra e la tabella sotto.
6. **Prova.** **Anteprima** apre la pagina vera, con i dati veri.

<p class="callout success">**Cosa ci guadagni.** A ogni salvataggio la schermata si riallinea al disegno. Aggiungi un nodo e compare il suo riquadro. Dove stanno i riquadri lo decidi tu, e resta.</p>

<p class="callout info">**Per chi sviluppa.** Il nome del flusso è un identificatore: lettere, numeri, trattino basso. La schermata prende lo stesso nome con «View» in fondo. Il designer è in `frontend/ade-next/src/studio/flow-designer`, la strada guidata in `frontend/ade-next/src/studio/velocizzatore`.</p>

<p class="callout info">**Per approfondire.**  
• Flow Designer — guida a un flusso semplice: `docs/guide/flussi/flow-designer/README.md`  
• Quick Flow Designer — una funzione con celle collegate, e funzioni che si riusano: `docs/guide/flussi/quick-flow-designer/README.md`</p>

# JE6.2 - Nodi e proprietà

**In una frase.** Ogni nodo fa una cosa sola, e le sue proprietà stanno in quattro schede: chi è, cosa fa, cosa riceve, come si comporta se va storto.

Un flusso si legge bene se ogni passo è piccolo e dice cosa fa. I nodi sono fatti per questo: ne scegli uno per ogni cosa da fare e lo regoli dal pannello a destra.

## Le famiglie di nodi

- **Avvio**: Start, il punto da cui il flusso parte.
- **Interfaccia**: Tabella, Form, Grafico, Scheda, Bottone. Sono i pezzi che l'utente vede.
- **Logica**: Condizione, Switch, Ciclo, Finché, Unione, Attesa, Filtra, Email, Attività umana.
- **Dati**: Endpoint, Validazione, Variabili, Chiamata HTTP, JSON, File, CSV, Sotto-flusso.
- **Fine**: End, e Ferma con errore.

La forma del nodo dice la famiglia prima ancora dell'etichetta.

## Le quattro schede

- **Nodo**: etichetta e descrizione. La descrizione non cambia niente nell'esecuzione: serve a chi leggerà il disegno fra sei mesi.
- **Configurazione**: cosa fa il nodo. È la scheda che si apre per prima.
- **Ingresso**: cosa riceve, campo per campo.
- **Esecuzione**: come si comporta.

![La scheda Esecuzione: spegnere il nodo, eseguirlo solo a condizione, dargli un tempo massimo, decidere cosa fare se fallisce](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/la-scheda-esecuzione-spegnere-il-nodo-eseguirlo-solo-a-condizione-dargli-un-tempo-massimo-decidere-cosa-fare-se-fallisce.png)

*La scheda Esecuzione: spegnere il nodo, eseguirlo solo a condizione, dargli un tempo massimo, decidere cosa fare se fallisce*

Nella scheda **Esecuzione** ci sono le cose che servono quando si cerca un problema o si vuole un flusso robusto:

- **Nodo spento**: il passo viene saltato senza staccare i collegamenti. Nel debug resta visibile, segnato come saltato.
- **Esegui solo se**: una condizione. Se è falsa il nodo si salta.
- **Tempo massimo**: oltre quel tempo il nodo fallisce invece di restare appeso.
- **Se questo nodo fallisce** e **Tentativi**: fermare il flusso, riprovare, o proseguire su un ramo d'errore.

Un pallino sulla scheda dice che lì c'è qualcosa di diverso dal solito.

<p class="callout info">**Nota.** La Chiamata HTTP verso servizi esterni ha limiti voluti, per sicurezza. L'Email parte solo se l'installazione ha configurato la posta. L'Attesa in un flusso normale arriva al massimo a trenta secondi: per attese lunghe vedi [Fermarsi e riprendere](https://gsdoc.genesyssoftware.eu/link/37841).</p>

<p class="callout info">**Per chi sviluppa.** Il nome interno del nodo (per esempio `n_cerca`) è quello che ritrovi nel debug e nei messaggi d'errore. Cosa ogni nodo riceve e produce lo dichiara il servizio, ed è lo stesso giudizio usato al salvataggio.</p>

<p class="callout info">**Per approfondire.**  
• Proprietà di nodo — l'inspector a schede: `docs/guide/flussi/flow-node-properties/README.md`  
• Tre nodi nuovi — JSON, Attesa, Chiamata HTTP: `docs/guide/flussi/flow-nodes/README.md`</p>

# JE6.3 - Partire da solo: i trigger

**In una frase.** Un trigger fa partire un flusso senza che nessuno prema un pulsante: a un orario, oppure quando lo chiama un altro programma.

Certi lavori non hanno un utente davanti: un controllo ogni notte, un riepilogo ogni mattina, un ordine che arriva da un sito. Prima, per cambiare l'ora di un lavoro del genere serviva un programmatore. Ora è una riga nel pannello del flusso.

1. **Salva il flusso.** I trigger si attaccano a un flusso già salvato.
2. **Premi Trigger.** È nella barra del Flow Designer, accanto a **Debug**.
3. **Aggiungi un orario.** **Aggiungi orario** propone già «ogni giorno alle sei». L'orario si scrive in sei campi: secondi, minuti, ore, giorno, mese, giorno della settimana. Accanto scegli il **fuso orario**: le sei sono le sei di chi ha scritto la regola, non del server. Sotto leggi quando sarà la prossima esecuzione.
4. **Oppure aggiungi un webhook.** **Aggiungi webhook** ti dà un indirizzo. Il programma che lo chiama deve firmare la richiesta con un segreto che scegli tu.
    
    ![Il pannello dei trigger: un orario con il suo fuso, un webhook con il segreto, e l'esito dell'ultima esecuzione](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/il-pannello-dei-trigger-un-orario-con-il-suo-fuso-un-webhook-con-il-segreto-e-lesito-dellultima-esecuzione.png)
    
    *Il pannello dei trigger: un orario con il suo fuso, un webhook con il segreto, e l'esito dell'ultima esecuzione*
5. **Di' a nome di chi gira.** Il campo **A nome di** decide chi risulta come autore di quello che il flusso scrive. Vuoto, vale l'utente tecnico dell'installazione.

<p class="callout warning">**Attenzione.** Un webhook senza segreto non accetta niente. È voluto: l'indirizzo contiene il nome del flusso, e un nome si indovina. Il segreto, una volta scritto, non si può più rileggere dalla pagina.</p>

<p class="callout info">**Nota.** Con il login acceso, i flussi a orario chiamano gli altri servizi con un'identità vera. Questa parte è scritta ma non ancora provata dal vivo su un'installazione.</p>

<p class="callout success">**Cosa ci guadagni.** L'ora di un lavoro automatico la cambia chi disegna il flusso, in un minuto. E ogni partenza lascia un esito che si può andare a guardare.</p>

<p class="callout info">**Per chi sviluppa.** L'orario è un cron a sei campi. La firma del webhook è `HMAC-SHA256` del corpo della richiesta, nell'intestazione `X-Signature-256`. Firma assente, sbagliata o segreto mancante danno lo stesso messaggio.</p>

<p class="callout info">**Per approfondire.**  
• Trigger — come un flusso parte da solo: `docs/guide/flussi/flow-triggers/README.md`</p>

# JE6.4 - Fermarsi e riprendere

**In una frase.** Un flusso può fermarsi ad aspettare una persona o una scadenza, anche per giorni, e ripartire da dove era rimasto.

Un'approvazione non si chiude in un secondo. Qualcuno deve guardare la richiesta e decidere, magari domani. Il nodo **Attività umana** serve a questo: ferma il flusso, mette la richiesta nell'elenco di chi deve decidere, e riparte quando arriva la risposta.

1. **Metti il nodo Attività umana.** È fra i nodi di Logica. Nel pannello scrivi cosa si chiede, a chi tocca (una persona o un ruolo), quali dati mostrare e quali sono le scelte possibili.
    
    ![Un'approvazione: il flusso si ferma sul nodo e prosegue su «Approvo» o su «Respingo»](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/unapprovazione-il-flusso-si-ferma-sul-nodo-e-prosegue-su-approvo-o-su-respingo.png)
    
    *Un'approvazione: il flusso si ferma sul nodo e prosegue su «Approvo» o su «Respingo»*
2. **Collega ogni scelta.** Ogni scelta diventa un'uscita del nodo. «Approvo» porta da una parte, «Respingo» dall'altra.
3. **Avvialo in secondo piano.** Nella finestra del **Debug**, **Esegui in background**. Non aspetti la fine: ricevi il numero dell'esecuzione, con cui la segui.
4. **Chi deve decidere apre Attività da fare.** Trova le richieste che toccano a lui o al suo ruolo. Aprendone una vede i dati su cui decide e un pulsante per ogni scelta.
    
    ![Attività da fare: le richieste in attesa, con cosa si chiede e in quale flusso](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/attivita-da-fare-le-richieste-in-attesa-con-cosa-si-chiede-e-in-quale-flusso.png)
    
    *Attività da fare: le richieste in attesa, con cosa si chiede e in quale flusso*
    
    ![Il dettaglio di un'attività: cosa si chiede, i dati della pratica e un pulsante per ogni scelta. Coperto il nome di chi decide. Attività di prova](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/e-adenext-img-fermarsi-e-riprendere-03-dettaglio-attivita.png)
    
    *Il dettaglio di un'attività: cosa si chiede, i dati della pratica e un pulsante per ogni scelta. Coperto il nome di chi decide. Attività di prova*
5. **Il flusso riparte.** Dopo la scelta prosegue sul ramo giusto. Una seconda risposta alla stessa attività viene rifiutata.

Nell'elenco **Esecuzioni dei flussi** le esecuzioni ferme si vedono: stato **In attesa**, con la colonna **Fermo su** (quale nodo) e **Riprende** (quando).

<p class="callout success">**Cosa ci guadagni.** Approvazioni, scadenze e lavori lunghi si disegnano come ogni altro passo. Il flusso fermo resta scritto nell'archivio e riprende da dove era, non da capo. Finché aspetta si può anche annullare.</p>

<p class="callout info">**Nota.** L'attività può avere una scadenza in minuti. Passata l'ora, il flusso riparte da un'uscita apposta, **Scaduta**: cosa succede dopo lo disegni tu.</p>

<p class="callout info">**Per chi sviluppa.** L'avvio in secondo piano risponde subito con il numero dell'esecuzione e l'indirizzo da cui leggerne lo stato. Chi vede un'attività si decide per nome utente e per ruolo.</p>

<p class="callout info">**Per approfondire.**  
• Esecuzione durevole — un flusso che si ferma e riprende: `docs/guide/flussi/flow-durevole/README.md`</p>

# JE6.5 - Versioni e ripristino

**In una frase.** Ogni salvataggio che cambia il disegno lascia una versione: puoi confrontarne due e tornare a quella che funzionava.

Un disegno si rompe in modi che non si notano subito: un collegamento staccato per sbaglio, una condizione girata al contrario. Te ne accorgi il giorno dopo, quando non ricordi più com'era. Con le versioni non serve ricordare.

1. **Premi Versioni.** È nella barra del Flow Designer, accanto a **Trigger**. Si apre la cronologia, dalla più recente.
2. **Leggi la cronologia.** C'è una riga per ogni salvataggio che ha cambiato davvero qualcosa. Spostare un nodo di poco o ritoccare la descrizione non lascia una versione: così l'elenco resta corto e si trova quella giusta.
3. **Confronta.** Scegli due versioni e premi **Confronta**. La risposta parla del disegno: quali nodi e quali collegamenti sono stati aggiunti, tolti o modificati.
    
    ![Il confronto fra due versioni: un nodo aggiunto, uno modificato, un collegamento aggiunto](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/il-confronto-fra-due-versioni-un-nodo-aggiunto-uno-modificato-un-collegamento-aggiunto.png)
    
    *Il confronto fra due versioni: un nodo aggiunto, uno modificato, un collegamento aggiunto*
4. **Ripristina.** Premi **Ripristina** sulla versione a cui vuoi tornare. Prima di farlo il sistema salva una versione di com'era adesso: se hai scelto quella sbagliata, torni indietro anche da lì.
5. **Esporta, se serve.** **Esporta** scarica il disegno in un file, per conservarlo o portarlo su un'altra installazione. Password e segreti non finiscono nel file.

<p class="callout success">**Cosa ci guadagni.** Si può provare una modifica senza paura. Anche form, tabelle ed endpoint tengono le loro versioni, allo stesso modo: la versione di prima viene messa da parte a ogni salvataggio che cambia qualcosa.</p>

<p class="callout info">**Nota.** Il ripristino non cambia il **nome** del flusso. Il nome è quello con cui lo chiamano le schermate e gli altri flussi: riportarlo indietro li lascerebbe senza.</p>

<p class="callout info">**Per chi sviluppa.** Il confronto è fatto sulla struttura del disegno, non sul testo, e ignora date e autore. Per form, tabelle ed endpoint le versioni si leggono dal servizio; il pannello con confronto e ripristino descritto qui è quello del Flow Designer.</p>

<p class="callout info">**Per approfondire.**  
• Versioni del flusso — cronologia, confronto, ripristino, export: `docs/guide/flussi/flow-versions/README.md`</p>

# JE6.6 - Trovare gli errori

**In una frase.** Il designer ti dice mentre disegni cosa non va e dove, e il Debug ti mostra passo per passo cosa è successo.

Un disegno sbagliato è peggio di un programma sbagliato se non te ne accorgi. Per questo il controllo è continuo: non devi salvare né eseguire per sapere che manca qualcosa.

1. **Guarda i nodi.** Un nodo con un problema ha il bordo colorato e un numero. Tratteggiato arancione: c'è qualcosa da completare. Rosso: c'è un errore.
    
    ![Un flusso con tre problemi: il ciclo ha un errore, la ricerca e il bivio un avviso](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/un-flusso-con-tre-problemi-il-ciclo-ha-un-errore-la-ricerca-e-il-bivio-un-avviso.png)
    
    *Un flusso con tre problemi: il ciclo ha un errore, la ricerca e il bivio un avviso*
2. **Apri l'elenco.** In basso a destra la barra conta errori e avvisi e, se c'è un errore, aggiunge «non pubblicabile». È un pulsante: premilo e leggi i problemi, in italiano, ciascuno con il nome del nodo.
    
    ![L'elenco dei problemi: cosa non va, e su quale nodo](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/lelenco-dei-problemi-cosa-non-va-e-su-quale-nodo.png)
    
    *L'elenco dei problemi: cosa non va, e su quale nodo*
3. **Clicca un problema.** Il disegno si sposta sul nodo e apre la scheda dove si corregge.
4. **Correggi.** Con un **errore** il flusso non si può pubblicare. Un **avviso** non blocca: segnala qualcosa che potrebbe essere voluto, come un bivio con un ramo solo.
5. **Esegui il Debug.** **Debug** fa girare il flusso e mostra l'elenco dei passi: quali nodi sono partiti, in che ordine, cosa hanno prodotto, quanto tempo è servito. Se un passo fallisce, dice quale e perché.
    
    ![Il Debug: riuscito in tre passi, con il percorso seguito e i dati usciti](https://gsdoc.genesyssoftware.eu/uploads/images/gallery/2026-11/il-debug-riuscito-in-tre-passi-con-il-percorso-seguito-e-i-dati-usciti.png)
    
    *Il Debug: riuscito in tre passi, con il percorso seguito e i dati usciti*

I controlli sono una ventina. Tre riguardano la forma del disegno, e sono quelli che ingannano di più: un ciclo che non torna indietro (farebbe un giro solo), un bivio con un ramo solo, un passo da cui non esce niente.

<p class="callout success">**Cosa ci guadagni.** Gli errori si trovano prima di consegnare la funzione, non quando la usa il cliente. E lo stesso controllo lo rifà il servizio al salvataggio: non si può aggirare.</p>

<p class="callout info">**Nota.** Se l'anteprima o il Debug mostrano un errore sui dati, non sono dati finti: vuol dire che in quel momento SIGEAnext non raggiunge i Dati aziendali.</p>

<p class="callout info">**Per chi sviluppa.** Il controllo del disegno gira uguale nell'app web e nel servizio, tenuto allineato da un file di casi in comune. Ogni problema ha un codice, per esempio `LOOP_NOT_CLOSED`.</p>

<p class="callout info">**Per approfondire.**  
• I problemi del grafo — vederli, capirli, raggiungerli: `docs/guide/flussi/graph-problems/README.md`</p>