FlowSharp - Flow e designer operativo

I Flow sono il cuore di FlowSharp. Una Process Map mostra il quadro complessivo, ma e' il Flow che rende eseguibile un processo, fase dopo fase, task dopo task.

1. Perche i Flow sono il cuore di FlowSharp

Un Flow descrive come una pratica deve muoversi dentro l'organizzazione.

Senza un Flow, il processo resta una procedura raccontata. Con un Flow, diventa un percorso operativo:

• con fasi chiare;
• con passaggi consentiti;
• con task assegnati;
• con dati richiesti;
• con regole di avanzamento;
• con automazioni controllate;
• con audit e misurazione.

Il Flow e' quindi il punto in cui FlowSharp passa dalla mappa concettuale al lavoro reale.

2. Dal processo alla macchina operativa

Quando disegni un Flow, stai rispondendo a domande molto concrete:

• da dove parte la pratica?
• quali fasi puo' attraversare?
• chi interviene in ogni fase?
• quali dati servono per andare avanti?
• quali controlli sono obbligatori?
• quando puo' intervenire l'automazione?
• quando serve una decisione umana?
• quando il processo e' concluso?

Questa struttura permette di evitare processi impliciti, eccezioni nascoste e passaggi non tracciati.

3. Designer visuale

Il designer visuale permette di costruire il Flow su canvas.

Gli stati sono nodi. Le transizioni sono collegamenti. Il pannello laterale permette di configurare fase, task, regole, dati, AI, timeout e comportamento operativo.

Puoi creare un Flow in due modi:

• manuale, partendo da un canvas vuoto;
• con AI, descrivendo il processo e usando una prima bozza da rifinire.

La modalita AI accelera il primo disegno, ma non sostituisce la validazione del team. Il Flow pubblicato deve sempre rappresentare il modo in cui l'organizzazione vuole lavorare.

Strumenti utili durante il disegno:

• Duplica stato: ogni stato ha un bottone di duplicazione che clona la fase con i suoi task, regole e sottoscrizioni eventi, pronta da ricollegare. Anche il singolo task puo' essere duplicato.
• Selettore {x}: i campi che accettano espressioni hanno un pulsante {x} per inserire variabili e campi dati in modo guidato, con espansione anche di oggetti annidati e array (es. item.data.righe[].codice).
• Nomi di stato duplicati segnalati: il designer avvisa se due stati hanno lo stesso nome, per evitare ambiguita' nei menu di selezione.

4. Stati e fasi

Ogni stato rappresenta una fase significativa del processo.

Uno stato puo' essere:

• una lavorazione umana;
• una verifica automatica;
• una valutazione AI;
• una fase di attesa dati;
• un checkpoint di compliance;
• un passaggio di integrazione;
• una fase finale.

La parola "fase" aiuta il business a leggere il processo. La parola "stato" aiuta a capire che FlowSharp governa un percorso preciso, non una lista libera di attivita.

5. Transizioni e percorsi consentiti

Le transizioni definiscono quali passaggi sono possibili.

Questo e' uno dei punti piu' importanti: in FlowSharp una pratica non puo' andare ovunque. Puo' andare solo dove il Flow lo consente.

Le transizioni aiutano a:

• evitare salti non autorizzati;
• rendere chiaro il percorso;
• distinguere avanzamento, rifiuto, ritorno, escalation e chiusura;
• misurare quanto spesso si passa da una fase all'altra;
• mantenere uno storico leggibile.

6. Task dentro i Flow

Un task e' un'azione che si attiva quando un item entra in una fase.

I task possono essere bloccanti o non bloccanti. Un task bloccante ferma il percorso finche' non viene completato; un task non bloccante puo' partire in background.

Un task Auto in modalita' Spawn crea un item figlio senza copiare implicitamente i dati business del padre. Il designer puo' definire un mapping childData, che funge da allowlist esatta, oppure attivare consapevolmente l'eredita' completa. Quest'ultima opzione genera un warning perche' amplia i dati trasferiti al flusso figlio; _source, _taskError e la provenienza del padre non vengono comunque copiati.

7. Regole, Data Gate e qualita dei dati

Le regole decidono quando un item puo' avanzare automaticamente.

Servono a:

• valutare importi, categorie, priorita o rischi;
• scegliere la prossima fase;
• applicare eccezioni controllate;
• gestire timeout o condizioni particolari;
• evitare decisioni manuali ripetitive.

Le condizioni possono combinare e annidare gruppi tutte (all), almeno una (any) e negazione (not). FlowSharp verifica struttura, operatori e stato di destinazione sia al salvataggio sia alla pubblicazione: una regola malformata o diretta verso una fase non consentita non viene pubblicata.

Il Data Gate impedisce al processo di procedere quando mancano informazioni essenziali. Questo e' particolarmente importante prima di task AI o integrazioni: se i dati sono vuoti, incompleti o incoerenti, il Flow deve fermarsi e chiedere qualita, non automatizzare male.

8. WIP limit e capacita di lavoro

Il WIP limit aiuta a governare la capacita del processo: quanti item possono essere attivi in un flow o dentro una fase prima che il lavoro diventi ingestibile.

Puoi usarlo a due livelli:

• a livello di flow, per impedire la creazione di nuovi item quando il processo e' gia' saturo;
• a livello di fase, per mettere gli item in attesa WIP quando quella fase ha raggiunto la capacita prevista.

Questo approccio rende visibile un concetto spesso nascosto: il fatto che una fase piena non deve necessariamente prendere altro lavoro solo perche' un item e' pronto ad arrivare.

In pratica:

• 0 o campo vuoto significa nessun limite; il limite puo' anche essere un'espressione (es. {{flow.vars.capacita}}), cosi la soglia diventa configurabile senza toccare il flow;
• una fase puo' mostrare solo un warning, mettere in attesa, consentire override manuale o deviare verso un'altra fase (parking su altro stato, utile per code di overflow ed escalation);
• gli item in attesa WIP restano visibili, ma non avviano lavoro operativo finche' non si libera capacita;
• il rilascio dalla coda segue la priorita' quando il flow e' marcato "prioritizzabile" (campo dati di priorita', numero piu' alto = piu' importante), altrimenti l'ordine di arrivo; la priorita' non scavalca mai il lavoro gia' ammesso;
• su una fase in modalita' "forzatura consentita", un Amministratore puo' far entrare un item oltre il limite indicando una motivazione obbligatoria (tracciata);
• il timeout di fase vince sempre: se un item in coda raggiunge il suo timeout, parte comunque e la coda resta pulita;
• le misurazioni aiutano a capire quante pratiche sono finite in WIP e per quanto tempo.

Ogni item registra inoltre il motivo di stato — perche' e' entrato nella fase corrente (avvio, cambio manuale, regola, evento, timeout, max iterazioni, deviazione WIP). Il motivo e' consultabile nelle regole e negli script, e alimenta i badge visibili nel dettaglio item e nella board (vedi la guida "Items, task e lavoro umano").

Il WIP Gate completa il Data Gate: il Data Gate chiede dati migliori, il WIP Gate chiede capacita disponibile.

9. Versioni e pubblicazione

Un Flow puo' essere disegnato in bozza e poi pubblicato.

Quando un Flow pubblicato viene aggiornato, una nuova versione permette di evolvere il processo senza rompere gli item gia' in corso.

La definizione e le risorse che ne fanno parte, come stati, task, campi, KPI, viste, collegamenti SOP e impostazioni di design, sono modificabili solo nella versione Draft. Published, Unpublished e Disabled sono snapshot immutabili: per cambiarli occorre creare una nuova versione Draft.

Questo e' fondamentale nei processi reali: il modo di lavorare evolve, ma una pratica gia' partita deve rimanere coerente con la versione con cui e' nata.

10. Import, export e Modelli

I Flow possono essere esportati e importati.

Questo aiuta a:

• riusare template;
• trasferire processi tra ambienti;
• creare librerie di processi;
• fare review e backup;
• accelerare demo e onboarding.

L'import e' protetto dai doppioni: importare due volte lo stesso flow (o crearne uno con un codice gia' in uso) viene bloccato con un messaggio chiaro.

Import e creazione da template condividono un preflight allineato ai contratti del designer per code, path dati, durate e date, regole, ruoli e riferimenti tra fasi. Se il grafo principale non e' valido il Draft non viene creato a meta'; eventuali risorse opzionali non trasferibili vengono invece dichiarate come warning.

La pagina Modelli

Dalla sezione Flows si apre la pagina Modelli, la libreria di template con tre schede:

• Business Model Flows: modelli pronti inclusi nel prodotto (es. Approvazione Ordine, Gestione Ticket), completi di dati di esempio, task e regole;
• I miei modelli: i modelli salvati dalla tua organizzazione;
• Marketplace: in arrivo.

Da un modello crei un nuovo flow in bozza con un click. Ogni modello ha un pulsante Anteprima che mostra il diagramma del flow (stati e transizioni) prima di crearlo. In direzione opposta, da un flow esistente puoi fare "Salva come modello" per aggiungerlo alla tua libreria.

Tre modi per creare un Flow

Oltre al canvas vuoto e alla modalita' AI (vedi sopra), la finestra "Nuovo Flow" offre una terza via: importa. Puoi incollare/caricare un file JSON o incollare un URL da cui FlowSharp scarica il documento (il download avviene lato server, non dal tuo browser). Un import da URL richiede https per default; l'installazione puo' abilitare eccezioni di rete locale.

Duplica un Flow

Il pulsante Duplica (⎘) nella lista Flows crea una copia indipendente, sempre a partire dalla versione piu' recente della famiglia: nuova famiglia, versione 1, Bozza. Nome e code ricevono un suffisso automatico ("Fatture" → "Fatture (2)"). La copia non ha alcun legame con l'originale: modificarla non tocca il flow sorgente, e viceversa. Un flow di sistema di FlowSharp non puo' essere duplicato.

Importare dentro un Flow esistente

Dalla scheda Esporta/Importa del pannello impostazioni di un Flow puoi importare un documento (file, incolla o URL) direttamente nella versione che stai modificando, invece di creare un flow separato:

• se la versione e' vuota (nessuno stato), il documento ne sostituisce il contenuto;
• se la versione ha gia' almeno uno stato, l'import crea la versione successiva in Bozza della stessa famiglia, senza toccare quella su cui stavi lavorando.

Nome e code restano sempre quelli del Flow che stai aggiornando: un documento con nome diverso non lo sovrascrive (un avviso te lo segnala).

Condividere un Flow con un link

La stessa scheda Esporta/Importa offre Condividi: genera un link pubblico temporaneo a questa versione del Flow, cosi' un'altra installazione puo' importarla incollando l'URL, senza scambiarsi un file.

• il link e' valido per il tempo che scegli (30 minuti, 2 ore, 24 ore, 7 giorni o un valore personalizzato) ed e' utilizzabile piu' volte finche' non scade;
• puoi revocarlo in ogni momento dalla stessa scheda;
• il token compare per intero solo al momento della creazione: copialo subito, FlowSharp non lo mostra piu' dopo;
• non serve alcun accesso a FlowSharp per usare il link: chi lo riceve lo incolla nella modalita' "importa da URL" di qualunque installazione FlowSharp;
• attenzione a cosa contiene: il link espone lo stesso documento completo di un export (vedi sotto Cosa viaggia in un export) — config dei task alla lettera (URL webhook, prompt AI), variabili non segrete e assegnatari. Chiunque riceva il link vede l'intera configurazione operativa del Flow: trattalo con la stessa cautela di un URL con credenziali.

Cosa viaggia in un export (e cosa no)

Esportare o condividere un Flow porta con se' l'intero disegno operativo: stati, transizioni, task, regole, KPI, viste, variabili di flusso (i valori segreti restano fuori, solo la dichiarazione viaggia), eventi con la loro configurazione completa, permessi e assegnatari (come testo, da riconciliare a destinazione).

Restano volutamente fuori, perche' non hanno senso o non sono sicuri fuori dall'installazione di origine:

• le note del designer (sticky note) e la disposizione dei nodi sul canvas;
• i parametri di costo dei task;
• il collegamento diretto al tipo di entita' aziendale dell'installazione sorgente;
• il valore delle variabili segrete (solo dichiarazione + segnaposto).

Un flow di sistema di FlowSharp non puo' essere duplicato ne' aggiornato tramite import (in una versione bianca o come nuova versione); resta invece esportabile e condivisibile come qualsiasi altro flow.

11. Buone pratiche per disegnare Flow

• Parti dal percorso reale, non dall'ideale.
• Mantieni pochi stati chiari, poi aggiungi dettaglio dove serve.
• Usa nomi leggibili per il business.
• Distingui task manuali, task automatici e task AI.
• Non automatizzare prima di sapere cosa stai misurando.
• Usa stati finali chiari.
• Metti Data Gate dove la qualita dei dati e' decisiva.
• Pubblica solo quando il team riconosce il processo come corretto.

12. Variabili di flusso e variabili globali

Le variabili permettono di definire valori riutilizzabili in un posto solo e richiamarli ovunque nel flusso.

Ci sono due livelli:

• Variabili globali: valide per tutto il tenant. Si gestiscono in Gestione → Variabili globali (richiede ruolo Admin). Si richiamano con {{global.vars.nomeVariabile}}.
• Variabili di flusso: specifiche di un singolo flusso. Si gestiscono nel pannello del Flow Designer (sezione "Variabili"). Si richiamano con {{flow.vars.nomeVariabile}}.

Ogni variabile ha un nome (chiave), un tipo (string, number, boolean, secret) e un valore. Il valore e' sempre salvato come stringa; il tipo governa la validazione in scrittura e il cast in lettura.

Dove puoi usarle:

• nei campi Timeout (minuti) e Max iterazioni degli stati;
• nelle condizioni e negli script delle regole di transizione;
• come valore di confronto di una regola di transizione — es. item.data.importo maggiore di {{flow.vars.sogliaMax}}: cambi la soglia in un punto solo e tutte le regole che la usano si adeguano;
• nei prompt AI dei task;
• nei payload dei task webhook ed evento;
• nei limiti WIP di flow e di fase;
• nei contenuti embed dei form e dei task Do It / How To;
• in qualsiasi campo che accetta template Handlebars.

Esempio pratico: se vuoi che il timeout di uno stato rispetti un SLA configurabile, definisci una variabile globale durataSla con valore 48h e nel campo Timeout scrivi {{global.vars.durataSla}}. Per cambiare il SLA per tutti i flussi, basta aggiornare la variabile in Gestione.

Il pulsante {x} accanto ai campi che supportano i template apre un menu di inserimento guidato con le variabili globali e di flusso disponibili, i campi dell'item (item.id, item.entityRefId, item.assignedTo, ecc.) e i campi dello schema dati. Selezionando una voce, l'espressione corretta viene inserita automaticamente nel campo (sostituendo l'eventuale testo selezionato). I campi che contengono una variabile mostrano direttamente il suo valore risolto, in corsivo e con un colore dedicato; al click il campo torna in modifica con la sintassi {{...}}.

Variabili di tipo secret

Il tipo secret e' pensato per token e credenziali usati nei webhook e nei task AI:

• il valore e' cifrato nel database e non compare mai in chiaro: liste, modifiche e selettore {x} mostrano solo ••••••••;
• solo un Admin puo' rivelare il valore in chiaro, e ogni rivelazione viene tracciata nell'audit log;
• nelle espressioni funziona come le altre variabili ({{global.vars.token}}, {{flow.vars.token}}) — in header, URL, body dei webhook e prompt AI; nei log di esecuzione dei task il valore viene redatto automaticamente;
• in modifica il campo valore parte vuoto: lasciarlo vuoto significa "invariato".

Attenzione: un template che scrive il secret dentro i dati dell'item lo rende visibile li' — la responsabilita' e' di chi disegna il flow.

13. Timeout, attese e iterazioni

Il timeout di una fase e l'attesa di un task Auto usano la stessa grammatica:

Valori validi:

• 60 — 60 minuti, perche' un numero nudo e' espresso in minuti;
• 30s, 5m, 2h, 1d, 1w — durata con unita' case-insensitive;
• 1h30m — durata composta;
• 2026-09-01T09:00:00+02:00 — data ISO assoluta;
• {{flow.vars.sla}} o {{item.data.scadenza}} — valore risolto a runtime.

Le durate devono essere positive e non possono superare 366 giorni. I letterali non validi vengono rifiutati al salvataggio; una data assoluta gia' trascorsa puo' restare nel Draft come warning, ma blocca la pubblicazione. Se un template di timeout produce a runtime un valore non valido, la scadenza e' immediata (fail-closed); se accade a un task delay, il task fallisce con una diagnostica che non espone il valore risolto.

Max iterazioni resta un conteggio distinto: accetta un intero maggiore o uguale a zero oppure un'espressione come {{global.vars.maxIter}}; 0 significa nessun limite.

Usa questa funzionalita' per centralizzare soglie configurabili — SLA, limiti di cicli, scadenze — senza dover modificare ogni singolo flusso ogni volta che cambiano le politiche operative.

14. Esiti e punteggio delle pratiche

Non tutte le chiusure hanno lo stesso significato. Sugli stati finali puoi dichiarare un esito di business:

• positivo (OK), per esempio ordine approvato o ticket risolto;
• negativo (KO), per esempio pratica rifiutata o opportunita' persa;
• neutro, quando il processo si chiude senza una valutazione positiva o negativa.

Ogni fase puo' anche aggiungere o sottrarre un punteggio all'item. Il punteggio si aggiorna quando la pratica entra nella fase: una rilavorazione puo' ridurlo, un controllo superato puo' aumentarlo. Cosi due pratiche nello stesso stato possono raccontare storie diverse, senza perdere il contesto del percorso.

Il punteggio puo' entrare anche nelle regole di avanzamento. Per esempio, una pratica sotto una certa soglia puo' essere inviata a una revisione piu' approfondita. Nel lavoro quotidiano score, esito e variazioni restano visibili nell'item, nel Monitor e nelle Analytics.

15. Percorso ideale e rotte di eccezione

Un Flow reale non e' una sola linea retta. Per questo FlowSharp permette di dichiarare il percorso ideale: la sequenza di fasi che rappresenta il tragitto atteso. Il designer la evidenzia in oro e il Monitor segnala le pratiche che se ne sono allontanate, con il punto in cui la deviazione e' avvenuta.

Una deviazione non e' automaticamente un errore: puo' essere un ritorno, un'escalation o un caso da seguire. Serve a rendere esplicito il lavoro fuori standard, cosi da poterlo misurare e migliorare. Una chiusura finale negativa, per esempio, puo' essere un esito previsto e non una deviazione.

Le rotte di eccezione rendono ordinati anche timeout, WIP e SLA:

• puoi creare fasi come Escalation, Scaduto o Fuori capacita' raggiungibili solo dal sistema, non selezionabili manualmente dagli operatori;
• timeout e WIP possono indirizzare la pratica a una fase dedicata; il designer rende questo percorso riconoscibile come eccezione;
• per lo SLA puoi scegliere se ricevere solo un avviso o spostare automaticamente la pratica verso una fase di escalation;
• un Amministratore puo' comunque sbloccare una pratica eccezionale con un cambio di stato forzato, lasciando traccia nello storico.

In questo modo le eccezioni non diventano scorciatoie invisibili: restano parte del processo, leggibili e misurabili.

16. Impostazioni del Flow e registro campi

Le impostazioni del Flow sono organizzate in un percorso unico: Generale, Attivazione, Data Schema, Form AI quando l'avvio manuale e' attivo, Entita, Variabili, KPI, Avanzate e Import/Export. La sezione Attivazione contiene anche endpoint, copia del nodo n8n e gestione delle chiavi API legate al Flow.

Nei nuovi Flow l'avvio tramite evento e' disabilitato per default. Va attivato solo dopo aver scelto consapevolmente gli eventi; dalla stessa tab si puo' aprire la gestione eventi in una nuova scheda e aggiornare la lista dopo averne creato uno.

La tab Data Schema tratta i dati dell'item come un contratto che puo' crescere dall'uso reale:

• i campi dichiarati definiscono path, tipo, etichetta e flag Sensibile;
• i campi osservati vengono registrati quando compaiono davvero da form, task, AI, n8n o API, con tipo rilevato e provenienza;
• un campo osservato puo' essere promosso nel contratto oppure ignorato;
• i conflitti tra tipo dichiarato e valore ricevuto restano visibili con un conteggio;
• in modalita normale il valore viene accettato e il conflitto viene registrato; con la modalita strict una scrittura non conforme viene rifiutata su tutti i canali.

I Flow esistenti inizializzano il registro dalla struttura e dai dati gia' disponibili. La modalita JSON avanzata resta utilizzabile, mentre il Form AI puo' generare il proprio esempio direttamente dai campi dichiarati. Il flag Sensibile alimenta Data Shield, mascheramento ed export protetti.

Il registro riguarda il payload dell'item, non trasforma le configurazioni operative in soli interi. In particolare slaMinutes continua ad accettare sia un numero sia un'espressione come {{flow.vars.sla}}; lo stesso principio resta valido per gli altri campi configurabili tramite espressione.

17. KPI configurabili sul Flow

Admin e FlowDesigner trovano nella tab KPI due livelli distinti:

• le metriche item calcolano formule sui campi dichiarati e sulle metriche di processo, per esempio eta, lead time, minuti lavorati, costi o score;
• i KPI di flusso aggregano campi o metriche item con conteggio, somma, media, minimo, massimo, deviazione standard e varianza, oppure combinano altri KPI tramite formula.

L'editor propone solo i riferimenti disponibili, segnala la posizione degli errori e rifiuta dipendenze circolari. Soglie con etichette come ok, attenzione e critico rendono leggibile il valore su item e dashboard. Se la formula usa un campo sensibile, il KPI viene marcato come sensibile: il badge dichiara la provenienza, ma il valore calcolato non viene automaticamente mascherato.

Le definizioni, le soglie e gli obiettivi viaggiano con una nuova versione del Flow, cosi il modello operativo e il suo sistema di misura restano coerenti.

18. Progettazione condivisa e salvataggi sicuri

Un Flow pubblicato evolve creando una nuova versione: gli item gia' avviati restano legati alla versione con cui sono nati. Nome e codice sono univoci nell'organizzazione anche rispetto a differenze di maiuscole, spazi o caratteri invisibili, evitando famiglie di Flow apparentemente identiche. Il code stabile usa solo lettere minuscole, numeri, trattino e underscore; se non viene indicato alla creazione e' derivato dal nome con un suffisso sicuro in caso di collisione.

Se due persone aprono lo stesso designer, il salvataggio include la revisione da cui ciascuna e' partita. Quando quella revisione non e' piu' corrente, FlowSharp non sovrascrive il lavoro dell'altra persona: mostra un avviso, ricarica la versione server e conserva le modifiche locali non salvate per poterle confrontare e riapplicare.

La stessa attenzione vale durante un singolo salvataggio: le modifiche fatte mentre la richiesta e' ancora in corso restano nel buffer e non vengono cancellate dalla risposta del server.

19. Controlli di terminazione prima del publish

FlowSharp pubblica soltanto design che hanno almeno un finale realmente raggiungibile e nessuna componente terminale composta soltanto da stati non finali. Il controllo segue i canali effettivi del motore: scelta umana, regole Eval, timeout, redirect WIP, limite iterazioni, eventi e SLA.

Il designer mostra gli stessi codici usati dall'API:

• FLOW_NO_REACHABLE_FINAL: collega un finale a una rotta che il runtime può percorrere;
• FLOW_NONFINAL_TRAP: aggiungi un'uscita dalla sink o dal ciclo, oppure rendi finale lo stato corretto;
• AUTOMATION_FALLBACK_REQUIRED: per uno stato Auto/AI non finale configura un default Eval o un'uscita temporale deterministica.

Una freccia disegnata da uno stato automatico non è da sola una garanzia: deve esistere una regola che la selezioni o un fallback esplicito.