Gestione degli errori nelle esecuzioni di Zoho Flow: storico, rilanci e avvisi

La gestione degli errori nelle esecuzioni di Zoho Flow si regge su tre abitudini. Primo, si legge con regolarità lo storico delle esecuzioni. Secondo, si separano gli errori che Zoho Flow rilancia da solo da quelli da correggere. Terzo, si decide in anticipo chi riceve l'avviso e chi interviene.

Un'esecuzione è una singola corsa di un flusso. Un evento nell'app di partenza, detto trigger, avvia una o più azioni in altre app. La gestione degli errori è l'insieme di controlli che rende visibile ogni esecuzione non riuscita. Gli stessi controlli la portano a una correzione prima che i dati divergano.

Il rischio concreto è la perdita silenziosa di allineamento. Un contatto creato in Zoho CRM non arriva in contabilità. Un aggiornamento di stato non raggiunge il sistema esterno, e nessuno se ne accorge per settimane. Zoho Flow registra ogni esecuzione, ma lo storico serve solo se qualcuno lo consulta con un metodo.

Questa guida segue l'ordine pratico del lavoro. Parte da dove trovare lo storico e da come leggere stati e messaggi. Prosegue con gli errori che si risolvono da soli, i percorsi alternativi, gli avvisi e i casi che richiedono una persona. Se sta ancora valutando lo strumento, la pagina su Zoho Flow e i servizi di configurazione riassume cosa collega e come lo impostiamo.

Lo storico delle esecuzioni di Zoho Flow è disponibile a due livelli: per l'intera organizzazione e per il singolo flusso. La documentazione ufficiale Fix errors in flows lo indica come il punto di partenza di ogni diagnosi.

Storico dell'organizzazione

Lo storico di tutta l'organizzazione si apre dal percorso Settings > History. Questa vista serve al controllo quotidiano, perché mostra in un solo elenco le esecuzioni di tutti i flussi. È la schermata da cui il responsabile dell'integrazione dovrebbe iniziare la giornata.

Storico del singolo flusso

Lo storico del singolo flusso serve quando un errore è già stato individuato e occorre capire se si ripete. Permette di confrontare un'esecuzione fallita con quelle riuscite dello stesso flusso, a parità di trigger e di azioni.

Il dettaglio di un'esecuzione

Il dettaglio di un'esecuzione si apre facendo clic sul record dello storico. Zoho Flow mostra i dati scambiati tra il trigger e le azioni in formato JSON o XML. JSON e XML sono due formati di testo strutturato: ogni campo compare con il suo nome e il suo valore. Leggendo questi dati si vede esattamente quale valore è arrivato a quale passaggio, e quindi dove il flusso si è fermato.

Lo stato di un'esecuzione di Zoho Flow non è sempre "riuscita" o "fallita", e gli stati intermedi meritano la stessa attenzione. Le segnalazioni nella community di Zoho mostrano almeno altri due casi che un controllo ben fatto deve intercettare.

Esecuzioni filtrate

Un'esecuzione filtrata è un'esecuzione che il flusso non ha portato a termine perché una condizione l'ha esclusa. In una discussione sulla community, un utente descrive due flussi che funzionavano in modalità test. Una volta attivati, però, ogni esecuzione finiva come "filtered". L'utente dichiarava di non aver impostato filtri e otteneva il risultato atteso solo rilanciando il test a mano.

Esecuzioni in coda

Un'esecuzione in coda è un'esecuzione avviata ma non ancora elaborata. In un'altra segnalazione, un utente riferisce che quasi ogni flusso restava "Queued" per almeno qualche minuto. Riattivare il flusso a volte lo sbloccava, ma secondo l'utente causava problemi separati.

Esecuzioni che non partono

Il caso più insidioso è l'esecuzione che non compare affatto. Un membro della community ha chiesto perché un workflow non scattasse: email e SMS non partivano e Zoho Flow non veniva eseguito. Un controllo serio confronta quindi anche il numero di esecuzioni con il numero di eventi attesi.

Un messaggio di errore in Zoho Flow indica prima di tutto da dove viene il problema, e questa distinzione decide chi deve intervenire. La documentazione di Zoho fornisce due indizi pratici per orientarsi.

Il messaggio inizia con il nome dell'app

Un messaggio che inizia con il nome dell'app dell'azione, per esempio "Zoho Mail says...", segnala un errore restituito dall'API di quell'app. L'API è l'interfaccia tecnica con cui Zoho Flow scrive e legge i dati dell'app. In questo caso il problema riguarda l'applicazione di destinazione: permessi, campi, record mancanti o regole dell'app.

Compare la scheda errore senza la scheda input

Una scheda di errore visibile senza la scheda di input indica, secondo Zoho, un probabile errore di mappatura dei dati. La mappatura è il collegamento tra un valore prodotto da un passaggio e il campo che lo riceve nel passaggio successivo. Le cause tipiche sono un tipo di dato non valido o una formula formattata in modo scorretto.

Frasi da riconoscere

Alcune frasi ricorrenti indicano la causa con buona probabilità. Le espressioni "pattern mismatch" o "invalid data type" suggeriscono una variabile sbagliata mappata su un campo. Anche le date sono una fonte frequente di errore. Se il formato di data passato da un'app non corrisponde a quello atteso dall'altra, l'esecuzione fallisce.

I codici di errore HTTP che compaiono nello storico di Zoho Flow puntano a cause diverse e quindi a persone diverse. La tabella seguente riassume i casi descritti nella documentazione di Zoho e indica a chi conviene assegnare la verifica.

Messaggio nello storico	Causa probabile secondo Zoho	Chi interviene
401 Unauthorized, "Authentication failed"	Problema di connessione: password cambiata, accesso di Zoho Flow revocato o token scaduto	Chi amministra la connessione
403 Forbidden	L'account collegato nega a Zoho Flow il permesso per quel passaggio	Amministratore dell'app di destinazione
404 Not found	Un campo, un record o un dato richiesto non esiste nell'app collegata	Chi gestisce i dati dell'app
405 Method not allowed	L'app collegata non consente il metodo dell'azione: Create, Update, Fetch o Delete	Chi ha progettato il flusso
400 Bad Request	A un trigger o a un'azione manca un passaggio obbligatorio	Chi ha progettato il flusso
"pattern mismatch", "invalid data type"	Variabile errata mappata su un campo	Chi ha progettato il flusso
408 Request timed out, 504 Gateway timeout	Tempi di risposta scaduti; Zoho Flow rilancia in automatico	Nessuno subito; si verifica l'esito del rilancio

La colonna "Chi interviene" è la parte che di solito manca. Un errore 401 non si risolve modificando il flusso, ma ricollegando l'account. Un errore 405 invece non si risolve ricollegando nulla, perché va cambiata l'azione scelta.

Auto Rerun è la funzione di Zoho Flow che rilancia automaticamente le esecuzioni fallite per alcuni errori interni o di app esterne. La documentazione cita come esempi l'errore 408 Request timed out e l'errore 504 Gateway timeout. Sono errori di tempo: l'app di destinazione non ha risposto abbastanza in fretta, ma la richiesta in sé era corretta.

Gli errori coperti da Auto Rerun non richiedono un intervento immediato, ma richiedono una verifica. Conviene controllare nello storico che il rilancio automatico sia andato a buon fine. Se lo stesso timeout si ripete ogni giorno alla stessa ora, il problema è strutturale e va segnalato a chi gestisce l'app esterna.

Tutti gli altri errori della tabella dei codici richiedono prima una correzione e poi un rilancio. Rilanciare un'esecuzione con una connessione scaduta o una mappatura sbagliata produce solo un secondo fallimento.

Prima di rilanciare, controllare la destinazione

Il rilancio manuale ha un rischio proprio: un'azione che in realtà è stata eseguita a metà può essere ripetuta. L'utente che segnalava i flussi in coda osservava che riattivarli causava problemi separati. La regola prudente è aprire l'app di destinazione e controllare se il record esiste già. Solo dopo si rilancia, oppure si corregge il dato a mano.

Un caso reale della community di Zoho mostra come applicare il metodo di lettura passo per passo. Un utente aveva un flusso che recuperava e creava righe in Zoho Analytics. Durante la sequenza attiva riceveva questo errore: Zoho Analytics says "You need to have atleast one column for INSERT or UPDATE action".

1. Aprire lo storico. Da Settings > History si individua l'esecuzione fallita e si apre il dettaglio.
2. Leggere l'inizio del messaggio. Il messaggio comincia con "Zoho Analytics says". Secondo la documentazione di Zoho, quindi, l'errore arriva dall'API dell'app di destinazione.
3. Leggere il contenuto. L'API lamenta l'assenza di colonne per l'inserimento o l'aggiornamento. Il problema riguarda quindi i campi passati all'azione, non la connessione.
4. Controllare i dati in JSON. Nel dettaglio si verifica quali colonne sono arrivate davvero all'azione e con quali valori.
5. Correggere, poi rilanciare. Si sistema la mappatura delle colonne e si rilancia una sola esecuzione di prova.

Il punto istruttivo è nella risposta dell'utente: dichiarava di aver configurato le colonne e non capiva l'errore. Una mappatura che sembra completa nell'editor può non produrre valori in esecuzione, per esempio quando il trigger passa un campo vuoto. Il dettaglio JSON dell'esecuzione mostra ciò che è stato inviato davvero, non ciò che si è configurato.

Un percorso alternativo è un ramo del flusso che gestisce il caso anomalo prima che l'azione fallisca. Esempi di caso anomalo sono un campo obbligatorio vuoto o una data nel formato sbagliato. Invece di lasciare l'errore nello storico, il flusso riconosce la situazione e la tratta.

Controlli prima delle azioni di scrittura

Una decisione inserita prima di un'azione di creazione o aggiornamento previene diversi errori della tabella dei codici. Si verifica che i campi obbligatori siano presenti, causa tipica del 400. Si verifica che le date abbiano il formato atteso dall'app di destinazione. Se il controllo non passa, il ramo alternativo invia un avviso invece di scrivere.

Leggibilità del flusso

I rami vanno tenuti pochi. Un utente della community osserva che con più alberi decisionali il layout di Zoho Flow diventa contorto e difficile da seguire. Anche la disposizione automatica, secondo l'utente, non lo rende facile da diagnosticare.

Avvisi con subflow e funzioni personalizzate

I subflow sono porzioni ripetibili di un flusso, riutilizzabili in tutta l'organizzazione. Un unico subflow di avviso può servire tutti i flussi. Un utente della community segnala però che un subflow non può chiamare un altro subflow, quindi l'avviso va tenuto semplice. Se l'avviso parte da un'istruzione sendmail in una funzione personalizzata, conti sull'indirizzo mittente. Zoho aveva annunciato che dal 1 dicembre 2024 sarebbero stati ammessi solo indirizzi verificati.

Un errore di Zoho Flow richiede una persona quando la sua correzione cambia dati, permessi o la struttura del flusso. Gli errori di tempo coperti da Auto Rerun possono essere lasciati al rilancio automatico, con una verifica dell'esito. Tutto il resto merita un responsabile nominato.

Le categorie che a nostro giudizio passano sempre da una persona sono queste:

• errori di connessione, come 401 e "Authentication failed", perché richiedono di ricollegare un account;
• errori di permesso, come 403, perché coinvolgono l'amministratore dell'app di destinazione;
• errori su record mancanti, come 404, perché possono indicare un dato cancellato o rinominato;
• esecuzioni filtrate o in coda senza una causa evidente;
• errori che compaiono dopo una modifica alla configurazione dell'app collegata.

L'ultima voce nasce da casi concreti. Un utente ha ricevuto INVALID_URL_PATTERN collegando Zoho Flow a Zoho CRM. Si chiedeva se la causa fosse la ridenominazione del modulo Contacts in "Clients". Un altro ha ricevuto "given url is wrong" in un flusso che aggiornava lo stato di un'attività.

In Svennis assegniamo a ogni flusso di integrazione un responsabile nominativo. Prima di rilanciare un'esecuzione fallita, controlliamo nell'app di destinazione se il record esiste già.

Per un'azienda italiana la gestione degli errori di Zoho Flow è soprattutto una questione di responsabilità condivisa tra reparti. Il CRM appartiene alle vendite, Zoho Books all'amministrazione, il sistema esterno spesso a un fornitore. Un'esecuzione fallita tra due di questi sistemi rischia di non appartenere a nessuno.

Tre aspetti pratici pesano in modo particolare:

• Lingua dei messaggi. I messaggi di errore citati nella documentazione e nella community sono in inglese. Il responsabile deve saperli leggere o avere una tabella di riferimento come quella di questa guida.
• Formati di data. Le date scritte come giorno, mese e anno possono non corrispondere al formato atteso da un'app esterna. Zoho indica questa mancata corrispondenza come causa diretta di errore.
• Accesso allo storico. Il dettaglio di un'esecuzione mostra in JSON o XML i dati scambiati, quindi anche i dati dei clienti. Conviene limitare l'accesso a chi ne ha davvero bisogno.

Quando un errore non si risolve internamente, Zoho indica il supporto di Zoho Flow all'indirizzo support@zohoflow.com. Zoho consiglia di abilitare in anticipo Support Access, cioè l'accesso concesso al supporto, per accelerare la soluzione.

Le esecuzioni di Zoho Flow si mettono sotto controllo con pochi passi, da fare nell'ordine seguente:

1. Aprire Settings > History e annotare quali flussi hanno esecuzioni fallite, filtrate o in coda nell'ultimo periodo.
2. Per ogni errore, leggere l'inizio del messaggio e classificarlo con la tabella dei codici: connessione, permesso, dati, mappatura o tempo.
3. Nominare un responsabile per ogni flusso e un sostituto, con il compito di consultare lo storico a intervalli fissi.
4. Aggiungere controlli prima delle azioni di scrittura e un unico avviso riutilizzabile per i casi anomali.
5. Stabilire la regola di rilancio: verificare sempre la destinazione prima di rilanciare a mano.
6. Abilitare Support Access prima di averne bisogno.

Se i flussi collegano più sistemi e il controllo coinvolge più reparti, conviene progettare monitoraggio e avvisi insieme all'integrazione stessa. La pagina sulle integrazioni Zoho personalizzate descrive come impostiamo questi collegamenti tra CRM, contabilità e sistemi esterni.

• Zoho Flow: Fix errors in flows
• Zoho Community: All Zoho Flows are filtered
• Zoho Community: Almost all Flows are being queued
• Zoho Community: Campaigns are not firing
• Zoho Community: Error trying to Fetch and Create Rows in Zoho Analytics with Flow
• Zoho Community: Zoho Flow connection to Zoho CRM
• Zoho Community: Flow error "given url is wrong"
• Zoho Community: UI Improvement - Ability to Collapse Flow
• Zoho Flow Community