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».

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

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

    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

    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.

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.

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.

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

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

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

Le quattro schede

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

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:

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

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.

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.

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

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

    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.

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.

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.

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.

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.

Per approfondire.
• Trigger — come un flusso parte da solo: docs/guide/flussi/flow-triggers/README.md

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»

    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

    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

    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).

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.

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.

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.

Per approfondire.
• Esecuzione durevole — un flusso che si ferma e riprende: docs/guide/flussi/flow-durevole/README.md

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

    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.

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.

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.

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.

Per approfondire.
• Versioni del flusso — cronologia, confronto, ripristino, export: docs/guide/flussi/flow-versions/README.md

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

    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

    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

    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.

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.

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.

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.

Per approfondire.
• I problemi del grafo — vederli, capirli, raggiungerli: docs/guide/flussi/graph-problems/README.md