Manuale utente: Flow Designer

Questo manuale descrive tutte le funzionalità disponibili nell'interfaccia grafica del Flow Designer presenti nella sezione Insegna (Teach) → Q&As. Il documento è pensato per l'utente finale e non contiene frammenti di codice: spiega cosa si può fare usando la GUI.

Panoramica

Il Flow Designer è un editor visivo per costruire flussi conversazionali e azioni automatiche del bot. Gli elementi principali dell'interfaccia sono:

• Area di disegno (canvas): dove vengono posizionati i nodi e i collegamenti.
• Toolbar superiore: controlli globali (zoom, undo/redo, salva, chiudi).
• Dialog per modifica messaggi e codici: finestre modali per modificare il contenuto dei nodi.
• Nodi: unità logiche che rappresentano azioni del bot, condizioni, chiamate a API, invio email, esecuzione di codice, ecc.
• Controlli sui singoli nodi: selezione del tipo, impostazioni specifiche, aggiungi/rimuovi figli, duplicazione, icone di errore.

Come iniziare

• Aprire il Flow Designer tramite il pulsante corrispondente nella UI di editing di una Q&A. Verrà caricata la rappresentazione grafica del flusso esistente.

• L'area di disegno supporta pan (trascina lo sfondo) e zoom (toolbar o scorciatoie). Quando si trascina dentro l'area il cursore cambia tra "grab" e "grabbing".

Toolbar superiore

La toolbar in alto offre i seguenti controlli (da sinistra a destra):

• Zoom In (lente con +): ingrandisce il canvas per visualizzare i dettagli dei nodi.
• Zoom Out (lente con -): riduce lo zoom per avere una visione d'insieme.
• Reset Zoom (1:1): riporta la vista alla scala 1:1.
• Undo: annulla l'ultima operazione fatta nell'editor. Disabilitato se non ci sono azioni da annullare.
• Redo: ripristina l'ultimo cambiamento annullato. Disabilitato se non ci sono azioni da ripristinare.
• Save (icona disco): salva il flusso corrente. Salva anche lo stato di validità del flusso.
• Close (icona X): chiude il Flow Designer. Quando possibile, verrà eseguito il salvataggio prima della chiusura.

Suggerimenti:

• Ogni pulsante mostra un tooltip descrittivo quando ci si passa sopra.
• Undo/Redo seguono la cronologia delle modifiche del singolo editor.

Validazione del flusso

• In basso a destra della toolbar appare un indicatore di errori (chip) se il flusso contiene problemi di validazione.
• Il chip mostra il numero di errori e, posizionandosi sopra, fornisce i messaggi di errore dettagliati.
• Alcuni nodi mostrano icone di errore direttamente sull'header del nodo; cliccando sull'icona è possibile leggere i messaggi relativi a quel nodo.

Nodi: tipi e controlli generali

Ogni nodo è contenuto in una card con tre aree principali:

• Header: mostra icone, tipo/azione, bot class selector, eventuali link alla documentazione e l'ID del nodo.
• Data: contiene i campi editabili specifici del nodo (es. testo del messaggio, input per email, selettori, ecc.).
• Actions: pulsanti rapidi (es. imposta configurazioni, aggiungi/rimuovi figlio, duplica, salva).

Comportamenti comuni ai nodi:

• Selezione del tipo/azione: molti nodi permettono di scegliere il tipo di azione (es. BotReplies, BotRunsCode, MailLead, SmtpMail, ecc.) tramite un selettore nel header.

• Bot class: è possibile passare un nodo tra "Bot" e "User" classi (quando applicabile) usando il selettore di classe nodo.
• Documentazione: alcuni nodi mostrano un pulsante help che apre la pagina di documentazione relativa.
• ID del nodo: mostrato in basso a destra dell'header (utile per debug/tracciamento).

Azioni sui nodi

Per ogni nodo sono disponibili azioni rapide:

• Aggiungi figlio (Add): aggiunge un nodo figlio collegato. Il pulsante è visibile solo se non esiste già un figlio nello slot corrispondente.
• Rimuovi figlio (Remove): rimuove il collegamento con il figlio selezionato.
• Duplicazione: alcuni nodi (come quelli che rappresentano messaggi o esecuzione codice) offrono un pulsante per duplicare il nodo.
• Impostazioni/Config: molte tipologie di nodo hanno un pulsante di settings che apre un dialog con campi aggiuntivi (es. impostazioni SMTP, configurazione del codice, parametri API).
• Salva: nei dialog/modals per modifiche complesse (es. editor messaggi, editor HTML, impostazioni codice) è presente un pulsante salva che applica le modifiche al nodo e spesso chiude la finestra.

Collegamenti tra nodi

• I nodi si collegano tramite edge/connessioni: l'editor permette di creare e rimuovere connessioni tra nodi (di solito con drag & drop sui connettori del nodo).

• È possibile avere ramificazioni (fork) con nodi condizionali che dirigono il flusso su percorsi alternativi.

Nodi specifici e loro uso nella GUI

Di seguito una panoramica delle tipologie di nodi più rilevanti e le opzioni che l'utente può modificare tramite l'interfaccia.

• Scopo: inviare una risposta testuale del bot o una risposta che usa una knowledge base.

• Cosa si può fare in GUI: aprire l'editor messaggi (modal) per scrivere il testo/markdown della risposta, usare toolbar di formattazione, salvare o annullare le modifiche, impostare la classe del nodo.

• Scopo: nodo in cui il bot pone una domanda all'utente.

• Cosa si può fare: modificare il testo della domanda tramite l'editor messaggi, impostare collegamenti verso i nodi successivi.

• Scopo: eseguire logica custom/Script e restituire output tramite slot.

• Cosa si può fare: aprire il pannello di configurazione del codice (editor con evidenziazione), scegliere il linguaggio, inserire una descrizione, aggiungere o rimuovere output slots (nomi variabili), salvare o chiudere il pannello.

• Scopo: instradare il flusso su percorsi diversi in base a condizioni.

• Cosa si può fare: il nodo mostra la descrizione della condizione; tramite UI è possibile vedere se è un ramo IF o ELSE, rimuovere o aggiungere bot node figlio; la condizione viene visualizzata con una etichetta.

• Scopo: chiamare endpoint esterni o servizi (es. invio email via SMTP, invio lead via API).

• Cosa si può fare: per i nodi email c'è un form attraverso cui impostare mittente, destinatario, oggetto, corpo del messaggio e allegati; aprire le impostazioni SMTP per host/porta/utente/password/secure via dialog; salvare le impostazioni.

• Per MailLead: selezionare destinatari da una lista dei membri del team (select), impostare reply-to, subject, message e file attachments.

Interfaccia API (stile "Postman") per i nodi BotCallsAPI

Alcuni nodi che invocano servizi esterni (tipicamente il gruppo BotCallsAPI, incluse varianti come MailLead o nodi custom che chiamano endpoint) espongono un'interfaccia tipo "Postman" nella GUI. Questa interfaccia permette di configurare tutti gli elementi necessari per effettuare la chiamata HTTP senza scrivere codice.

Di seguito i campi e i controlli che l'utente trova e come usarli:

• Endpoint (URL)

  • Campo testuale dove inserire l'URL del servizio che si vuole chiamare.
  • Può essere un URL assoluto o un URL costruito a partire da variabili di ambiente/placeholder del bot (se supportato dall'istanza).

• Metodo HTTP

  • Selettore per scegliere il verbo della richiesta (es. POST, GET). Di solito è preimpostato su POST per invii di dati.

• Content Type

  • Campo che indica il tipo di contenuto della richiesta (es. multipart/form-data, application/json). Il tipo scelto influenza quali controlli del form sono attivi.

• Headers

  • Sezione per inserire header HTTP personalizzati (es. Authorization, Content-Type personalizzati, custom headers).
  • Nella GUI si possono impostare header statici o con placeholder; header critici come Authorization possono essere precompilati dalla configurazione del bot (es. token) e mostrati in lettura o editabili a seconda dei permessi.

• Form Data / Body

  • Sezione equivalente al tab "Body" di Postman. Permette di definire coppie chiave/valore chiamate formData quando il content type è multipart/form-data, oppure un campo body libero quando si usa JSON o altri content-type.
  • Per ogni voce del form è possibile scegliere il tipo:
    • text (campo testuale)
    • file (per allegati)
    • json (testo strutturato)
  • L'interfaccia consente di aggiungere, modificare o rimuovere campi formData con comodità (input dedicati, selettori per il tipo e pulsanti per rimuovere).

• Parametri di autenticazione

  • Se il servizio richiede credenziali (es. SMTP o header Authorization), la GUI include campi per inserirle (username/password, toggle secure, ecc.). Questi campi possono comparire nella sezione specifica del nodo (es. settings SMTP) o all'interno della sezione headers/form.

• Validazione dei campi

  • Molti campi sono soggetti a regole di validazione: campi obbligatori devono essere compilati prima di poter salvare; se mancano valori richiesti, il nodo mostra icone di errore e il salvataggio globale potrebbe essere disabilitato.
  • Le validazioni sono segnalate con messaggi testuali e icone accanto ai campi.

• Salvataggio della configurazione

  • Dopo aver impostato endpoint, method, headers e form data, usare il pulsante Save presente nel partial SaveFlow o nei dialog specifici per rendere persistente la configurazione sul nodo.
  • Il salvataggio aggiorna lo stato del flusso e sincronizza la Q&A con la configurazione del bot.

• Test e anteprima (cosa aspettarsi)

  • L'interfaccia offre un bottone per testare la chiamata API prima di slavare il flusso.

• Esempi di uso pratico (descritti senza codice)

  • Invio di un lead: impostare il method su POST, inserire l'endpoint del servizio di CRM, aggiungere i campi formData corrispondenti ai campi richiesti (nome, email, telefono), aggiungere eventuali header Authorization e salvare.
  • Invio email tramite connettore: compilare i campi "from", "to", "subject", "html" (o "message"), impostare allegati in formData tipo file, aprire le impostazioni SMTP per inserire host/porta/user/pass e salvare.

• BotStops

  • Scopo: terminare il flusso o passare a un'azione di handover/ritorno al menu principale/call QA.
  • Cosa si può fare: scegliere il tipo di uscita (listen, main_menu, handover, call QA), scegliere quale Q&A chiamare in caso di 'call QA', abilitare/disabilitare il clear slots (toggle) e salvare.

Editor Messaggi (Message Editor)

• Apertura: cliccando il pulsante di modifica sul nodo (edit) si apre un balloon/modal con l'editor markdown WYSIWYG.
• Funzionalità dell'editor:
  • Toolbar: undo/redo, emoji, intestazioni, grassetto, corsivo, barrato, citazione, liste, orizzontale, link, immagine (a seconda del tipo di nodo alcune opzioni sono disabilitate), code block.
  • Modalità preview: possibilità di vedere il rendering del markdown.
  • Salvataggio: pulsante di salvataggio applica le modifiche al nodo; se ci sono errori il salvataggio può essere disabilitato.
  • Annulla: bottone per scartare le modifiche e ripristinare il testo precedente.
  • Footer sticky: mostra errori specifici al nodo se presenti.

Editor Codice (Code Settings / Code Editor)

• Accesso: per i nodi di tipo esecuzione codice (BotRunsCode) si apre un dialog con un editor di codice (CodeMirror) integrato.
• Funzionalità nell'UI:
  • Scelta del linguaggio di codice (es. JavaScript, Python) tramite un selettore.
  • Area di inserimento del codice con evidenziazione sintattica.
  • Descrizione: campo per inserire una breve descrizione del comportamento dello script.
  • Aggiunta/rimozione output slots: campi per definire i nomi delle variabili di output che il codice produce. È possibile aggiungerne di nuovi e rimuoverli tramite chip removibili.
  • Un help/tooltip mostra esempi di codice e spiegazioni relative alla lingua selezionata.
  • Pulsante per chiudere senza salvare.

Editor HTML (HtmlCodeMessage)

• Usato per nodi che permettono contenuto HTML come corpo di email o messaggi in formato avanzato.
• Permette l'editing con evidenziazione e l'anteprima; il contenuto ha un salvataggio dedicato e può essere convalidato prima di salvare.

Impostazioni SMTP (per nodi SmtpMail)

• Accesso: il pulsante Settings nel nodo apre un dialog che mostra i campi per host, port, secure (toggle), username e password.
• Validazione: i campi sono validati; finché non sono compilati correttamente, il salvataggio è disabilitato e viene mostrata un'icona di errore.
• Salvataggio: il pulsante Salva applica le impostazioni al nodo.

Aggiungere / Rimuovere nodi e rami

• Aggiungere un nodo: usare il pulsante "add" disponibile nello slot azione del nodo o trascinare un nuovo nodo se supportato dall'editor (dipende dall'interfaccia del canvas).
• Rimuovere un collegamento: selezionare il nodo da cancellare e usare il comando da tastiera "command+delete" (MAC) oppure control+delete (su Windows).
• Duplicare: se il nodo supporta la duplicazione, cliccando l'icona di copia si crea un nuovo nodo identico collegato o posizionato nelle vicinanze.

Comportamenti di salvataggio e chiusura

• Salvataggio esplicito: il pulsante save salva il flusso, sincronizza la Q&A con la configurazione del bot e aggiorna lo stato di validità.
• Salvataggio dai dialog/modals: molte finestre di modifica (es. editor messaggi, HTML, codice) includono un pulsante save che applica le modifiche al nodo e, in alcuni casi, richiama la funzione di salvataggio globale.
• Chiusura: premendo Close viene eseguito il salvataggio se possibile, quindi la finestra del Flow Designer viene chiusa.

Suggerimenti di utilizzo

• Prima di chiudere il designer, usa il pulsante Save per assicurarti che tutte le modifiche siano persistite.
• Controlla sempre l'indicatore degli errori: il chip con il numero di errori aiuta a non dimenticare problemi di validazione.
• Quando lavori con l'editor di codice, definisci chiaramente gli output slot per collegare i risultati ad altri nodi.
• Per l'invio di email, configura correttamente le impostazioni SMTP e verifica mittente/destinatario prima di salvare.

Messaggi di errore comuni (cosa significa)

• Errori di validazione del flusso: indicano collegamenti mancanti o campi richiesti non compilati in uno o più nodi.
• Errori nodali: icona di avviso sul nodo significa che quel nodo ha campi non validi o configurazioni mancanti; aprire il nodo e leggere i messaggi a comparsa.

Riferimenti e documentazione

• Alcuni nodi includono link diretti alla documentazione esterna (icona help). Usali per approfondire comportamenti specifici (es. integrazioni e mail).