Passaggi, decisioni e attese
Il catalogo dei nodi di un workflow — condizioni, scritture nel record, notifiche, email, script, IA, attese, cicli, parallelismo e unioni.
Questa pagina percorre tutti i tipi di passaggio che si trascinano dalla palette Nodi sulla tela. Per ognuno: cosa fa, cosa si compila e cosa succede durante l'esecuzione.
Prima, però, un pezzo che si ripete in quasi tutti: la provenienza di un valore.
Da dove viene un valore
Ogni volta che un passaggio chiede un valore — il lato destro di una condizione, quello che si scrive in un campo — l'interfaccia offre le stesse quattro provenienze:
| Provenienza | Cosa porta |
|---|---|
| Valore fisso | Un testo scritto a mano ("Ganha", "25000"). |
| Campo del record | Un campo del record di cui l'esecuzione si occupa. |
| Variabile | Una delle variabili del processo. |
| Chi ha avviato | Chi ha fatto partire il processo — Nome utente (lo username) o Id utente. |
È per questo che un processo non ha bisogno di codice per la maggior parte di quello che fa: le decisioni e le scritture si compongono con questi quattro pezzi.
Condizione
Apre due strade a partire da una domanda. Ha sempre due uscite fisse: Vero e Falso.

- Seleziona il passaggio e apri Condizioni dal pulsante ….
- Clicca su Aggiungi condizione.
- Scegli la provenienza del lato sinistro (di solito Campo del record), il campo, l'operatore e il lato destro.
Gli operatori sono gli stessi dei filtri e delle regole di formattazione del resto della piattaforma:
| Operatore | Significa |
|---|---|
eq / neq |
Uguale a / diverso da |
gt / gte |
Maggiore di / maggiore o uguale a |
lt / lte |
Minore di / minore o uguale a |
contains |
Contiene il testo |
startsWith / endsWith |
Comincia con / finisce con |
isEmpty / isNotEmpty |
È vuoto / non è vuoto |
"Devono valere tutte" — più condizioni nello stesso passaggio si combinano con E, mai con O. Per un O, usa due passaggi di condizione in catena.
Senza nessuna condizione, "prosegue sempre per «Vero»" — utile mentre si disegna, pericoloso se resta così.
Scrivi nel record
Salva campi nel record di cui l'esecuzione si occupa. È il passaggio che chiude il cerchio: il processo ha deciso, ora la scheda del CRM deve rifletterlo.

- Apri Campi da scrivere dal pulsante ….
- Clicca su Aggiungi campo.
- Scegli il Campo e la provenienza del valore.
Nell'esempio, il passaggio Marcar como Ganha scrive fase = "Ganha" (valore
fisso) e responsavel = Chi ha avviato (lo username di chi ha avviato il
processo).
Nota
La scrittura avviene "dallo stesso GraphQL dell'app, con l'autorizzazione di chi lo ha avviato". Ossia: le autorizzazioni contano. Se chi ha avviato il processo non può modificare quell'entità, il passaggio fallisce — e fa bene a fallire, perché un processo non è una porta di servizio alle autorizzazioni.
Un passaggio senza nessun campo "non fa nulla" — l'interfaccia lo dice invece di nasconderlo.
Notifica
Manda una notifica dentro l'app — la campanella della navigazione, in tempo reale per chi ha la sessione aperta, e nella casella in arrivo per chi non ce l'ha.
| Campo | Note |
|---|---|
| Utenti | Account dell'app, scelti a mano. |
| Ruoli | Tutti gli utenti con quel ruolo. Sopravvive agli ingressi e alle uscite di persone. |
| Titolo | La riga che compare nella notifica. |
| Testo | Il corpo. |
Nel titolo e nel testo puoi inserire valori del record o di variabili fra
parentesi graffe: A oportunidade {titulo} foi rejeitada.
Uguale a Notifica, ma la destinazione è l'email, tramite il canale configurato nelle impostazioni dell'app. Ha due campi in più: il corpo è HTML, scritto in un editor apposito, e può portare un report in allegato.

| Campo | Note |
|---|---|
| Utenti / Ruoli | I destinatari. Chi non ha un'email resta fuori. |
| Oggetto | Accetta {campo} come il resto dei messaggi. |
| Testo | Apre un editor di HTML dal pulsante … (Corpo dell'email). |
| Allega report | Uno dei report dell'app, oppure Nessun allegato. |
Sull'allegato: "il PDF viene generato al momento dell'invio, per il record di questa esecuzione" — non è un file salvato, è il documento di quel caso, fatto in quell'istante. Vedi il capitolo Report.
Attenzione
Senza un canale email attivo e con SMTP completo nelle impostazioni dell'app, il passaggio non riesce a inviare. Configuralo in Impostazioni dell'app → Notifiche prima di mettere il processo in funzione.
Esegui script
Chiama uno script Python dell'app, a metà del processo. È la valvola di sfogo per tutto quello che il diagramma non fa: chiamare un servizio esterno, calcolare un margine, convalidare contro un altro sistema.

| Campo | Note |
|---|---|
| Script | Uno degli script dell'app. |
| Salva in | La variabile in cui resta ciò che lo script restituisce. Vuoto = "si scarta". |
Lo script "riceve il record, la chiave e le variabili negli argomenti" — non c'è bisogno di passarglieli a mano. Ciò che restituisce resta nella variabile indicata e diventa disponibile per i passaggi successivi.
Se lo script fallisce, l'esecuzione resta in Fallita su quel passaggio, con l'errore conservato nella cronologia.
IA
Fa una richiesta a un modello di IA dell'app a metà del processo: classificare una richiesta, riassumere una descrizione o estrarre i dati da un documento allegato. La risposta resta in una variabile, perché la usino i passaggi successivi.
| Campo | Note |
|---|---|
| Modello | Uno dei modelli di IA di testo dell'app. Predefinito usa quello segnato come predefinito nei Modelli di IA dell'app. |
| Richiesta | Cosa deve fare il modello. Accetta valori del record e di variabili tra parentesi graffe: Riassumi questa richiesta di assistenza: {descricao}. |
| Istruzioni | Facoltativo. Il ruolo e le regole del modello, uguali in tutte le esecuzioni. |
| File | Facoltativo. Campi file del record o variabili con file: immagini, PDF e testo, fino a 20 MB ciascuno. |
| Risposta in dati | Facoltativo. Un JSON Schema. Con esso, la risposta arriva in dati già convalidati, invece che in testo. |
| Salva in | La variabile che riceve la risposta. |
| Percorso nella risposta | Con un JSON Schema, salva solo una parte della risposta, per esempio urgente. |
Il passaggio ha due uscite: OK, quando il modello ha risposto, ed
Errore, quando la chiamata è fallita. Quando fallisce, la variabile
riceve { error, code }, con lo stesso codice che ricevono gli script (vedi
Usare l'IA negli script).
Perché il processo decida in base a ciò che il modello ha risposto:
Dichiara una variabile
urgente, del tipo Sì/No.Nel passaggio IA, scrivi in Richiesta
Questa richiesta di assistenza è urgente? {descricao}e, in Risposta in dati, lo schema:{ "type": "object", "properties": { "urgente": { "type": "boolean" } }, "required": ["urgente"] }In Salva in, scegli
urgente. In Percorso nella risposta, scriviurgente.Collega l'uscita OK a una Condizione con la variabile
urgente, l'operatoreeqe il valore fissotrue.
Con il Debug dei Modelli di IA dell'app attivo, la cronologia dell'esecuzione mostra il testo della richiesta e della risposta.
Nota
Un processo gira senza nessuno in attesa, per questo il passaggio IA non mostra la risposta sullo schermo mentre il modello la scrive. Per questo, vedi Risposte in diretta sullo schermo.
Attendi
Rimanda il processo di un tempo fisso: Giorni e Ore. "Zero in entrambi = nessuna attesa."
È il pezzo di "avvisami fra tre giorni se ancora non c'è risposta". L'esecuzione dorme e viene ripresa automaticamente all'ora giusta, anche se il server è stato riavviato nel frattempo.
Attendi evento
Rimanda il processo finché qualcuno non manda un segnale con un nome concordato.

L'unico campo è il Nome del segnale (nell'esempio, dados-completos). "Chi
invia il segnale scrive questo nome. Senza scadenza: se nessuno lo invia, il
processo resta in attesa."
Il segnale si manda in due modi:
- da un evento di schermata (TypeScript):
keplin.workflow.signal("dados-completos", id) - da uno script (Python):
workflow.signal("dados-completos", key=id)
Senza indicare il record, il segnale sveglia tutti i processi fermi su quel nome; con il record, solo quelli di quel record. Zero svegliati non è un errore — vuol dire che nessuno era in attesa.
Suggerimento
È comune combinare Attendi evento con una freccia di ritorno a un'attività: la persona rimanda indietro il caso chiedendo più dati, il processo resta in attesa del segnale, e quando il commerciale completa la scheda il segnale riporta il caso alla stessa attività. È esattamente quello che fa l'esempio di questa documentazione.
Ciclo
Percorre un elenco, un valore alla volta. Ha due uscite: Ciascuno (il corpo del ciclo, che viene eseguito una volta per valore) e Alla fine (quando l'elenco finisce).
| Campo | Note |
|---|---|
| Elenco | La variabile con i valori da percorrere. "Di solito è un passaggio di script a produrla." |
| Salva ciascuno in | La variabile che riceve il valore del giro corrente. |
Senza un elenco scelto, il diagramma avvisa: "Questo ciclo non dice quale elenco percorrere: esce subito da «Alla fine»."
Parallelo
Avvia più strade nello stesso momento. Ogni ramo è un'uscita del nodo.
- Apri Rami in parallelo dal pulsante ….
- Ogni riga è un ramo, con un'Etichetta (quello che si legge nel diagramma) e un Identificatore.
- Collega ogni uscita al primo passaggio del ramo corrispondente.
Nell'esempio, il passaggio Fechar e comunicar apre due rami: Registo (che salva la fase) e Cliente (che invia l'email). Nessuno aspetta l'altro.
Unione
Rimette insieme i rami di un Parallelo. È il passaggio che risponde a "quanti se ne aspettano?".

| Attendere | Cosa fa |
|---|---|
| Tutti i rami | Il processo prosegue solo quando arriva l'ultimo ramo. |
| Il primo decide | Prosegue con il primo che arriva — "gli altri rami vengono annullati quando uno arriva". |
| Un certo numero | Prosegue al termine di Quanti rami indichi. |
Sub-workflow
Chiama un altro processo, sullo stesso record.
| Campo | Note |
|---|---|
| Processo da eseguire | Uno dei workflow dell'app. |
| Attendi che finisca | Attivo, questo processo si ferma finché l'altro non termina. "Disattivato, questo processo prosegue e l'altro viene eseguito per conto suo." |
"Viene eseguito sullo STESSO record, e quindi deve trattare la stessa entità" — un processo sulle opportunità non può chiamare un processo sugli account. E un processo non può chiamare sé stesso: "sarebbe una ricorsione infinita", e il diagramma lo segnala.
Con Attendi che finisca attivo, questo processo prosegue quando l'altro termina — dal nodo di Fine, per mancanza di percorso, o per un errore. Lo storico di questo processo dice come è finito l'altro; un processo chiamato che fallisce non fa fallire quello che lo ha chiamato.
Fine
Termina l'esecuzione. Ha un unico campo, Risultato, un testo breve come
approvato, ganha o perdida. "Resta nella cronologia ed è ciò che mostra il
widget di stato."
Un processo può avere più nodi di Fine — uno per esito — ed è proprio quello che si deve fare: invece di una Fine generica, una per risultato, perché la cronologia dica qualcosa a chi la legge mesi dopo.
Come si legge un passaggio sulla tela
Ogni riquadro sulla tela mostra tre cose: il nome del passaggio (quello che hai scritto in Nome del passaggio, e quello che compare nella cronologia), il tipo in caratteri piccoli sotto, e le uscite a destra, con il nome di ciascuna. Un triangolo ambra nell'angolo segnala un passaggio con problemi.
Suggerimento
Dai ai passaggi nomi di business — "Aprovação da direcção", "Marcar como Ganha" — e non nomi tecnici. È quel testo che leggerai nella cronologia di ogni esecuzione quando qualcuno chiederà "dove è fermo questo caso?".
