Funzione Deluge in una regola workflow di Zoho CRM: come configurarla e testarla

Per usare una funzione Deluge in una regola workflow di Zoho CRM si scrive la funzione nella categoria Automation e si dichiarano i suoi argomenti. Poi la si aggiunge alla regola sotto Instant Actions (azioni immediate), scegliendo Function e mappando ogni argomento a un campo del record. La funzione gira in modo asincrono: il record si salva subito, senza attendere la fine dell'esecuzione.

Una funzione Deluge su regola workflow è un breve programma scritto in Deluge che Zoho CRM esegue quando una regola workflow scatta. Deluge è il linguaggio di scripting proprietario di Zoho ed è il linguaggio più integrato per scrivere le funzioni di Zoho CRM. Una regola workflow, secondo la documentazione di Zoho, è un insieme di azioni (notifiche email, task, aggiornamenti di campo) eseguite quando si verificano determinate condizioni.

Una funzione non parte mai da sola. Zoho CRM la esegue solo se è associata a un trigger, e l'associazione avviene nella configurazione della regola, non nell'editor della funzione. Questo post è il secondo di tre dedicati all'automazione di Zoho CRM con il codice: il client script, la funzione su regola workflow e la funzione pianificata. Qui si approfondisce la funzione su regola workflow, con un esempio completo sulle trattative vinte, i limiti da conoscere e gli errori più comuni.

La regola di scelta è semplice: si usa il codice solo quando le azioni già presenti nella regola workflow non bastano. Zoho stessa prevede azioni personalizzate soltanto quando le azioni predefinite di Zoho CRM non sono sufficienti. Un aggiornamento di campo, un'email, un task o un webhook si configurano in pochi minuti e non richiedono manutenzione del codice.

Una funzione diventa utile quando serve un valore calcolato o la lettura di altri record. Serve anche per una logica condizionale, per più passaggi insieme o per un'altra app Zoho come Books. La tabella riassume dove si colloca ciascuna opzione.

Strumento	Quando si esegue	Adatto a
Azioni della regola workflow (field update, email, task, webhook)	Quando la regola scatta su un record	Valori fissi, notifiche, un solo passaggio
Regola workflow su un campo data	In base a una data del record	Promemoria e scadenze senza codice
Client Script	Nell'interfaccia, tramite lo ZDK che collega il front-end alle funzioni lato server	Interazione con l'utente mentre lavora
Funzione su regola workflow	Dopo il salvataggio del record, in modo asincrono, entro 30 secondi	Calcoli, record collegati, più passaggi
Funzione pianificata	A intervalli regolari, orari, giornalieri, settimanali, mensili o personalizzati, entro 15 minuti	Elaborazioni in blocco e pulizie periodiche

Può restare il dubbio tra una semplice regola e un processo guidato. In quel caso la guida sulle differenze tra Workflow e Blueprint in Zoho CRM aiuta a decidere prima di scrivere codice. La logica a volte deve dialogare con un gestionale esterno. Allora il lavoro diventa un'integrazione vera e propria, come l'integrazione tra SAP Business One e Zoho CRM.

Le funzioni sono disponibili con accesso completo nelle edizioni Enterprise, CRM Plus, Ultimate e Zoho One. Nelle edizioni Standard e Professional si accede alle funzioni soltanto tramite le estensioni. Chi crea e gestisce le funzioni deve avere il permesso Manage Extensibility, nelle Developer Permissions del profilo.

Zoho CRM regola l'esecuzione con un sistema a crediti. Ogni esecuzione di una funzione Deluge consuma un credito, e i crediti si ricaricano su una finestra mobile di 24 ore. La dotazione giornaliera dipende dall'edizione e dal numero di licenze, come indicano i limiti e le quote delle funzioni nella documentazione per sviluppatori.

Edizione	Accesso alle funzioni	Crediti al giorno	Massimo
Standard	Solo tramite estensioni	5.000 gratuiti + licenze × 200	15.000
Professional	Solo tramite estensioni	5.000 gratuiti + licenze × 200	20.000
Enterprise / Zoho One	Completo	20.000 gratuiti + licenze × 500 + crediti aggiuntivi	400.000 (200.000 gratuiti e 200.000 aggiuntivi)
CRM Plus / Ultimate	Completo	20.000 gratuiti + licenze × 1.000 + crediti aggiuntivi	Dipende dal numero di licenze

Se la dotazione gratuita non basta, si possono acquistare crediti aggiuntivi. Il consumo si controlla nella scheda Credits, visibile solo agli amministratori dell'organizzazione. Per chi valuta il passaggio a una suite completa, la pagina su Zoho CRM Plus in Italia descrive cosa include quell'edizione.

Una funzione su regola workflow ha 30 secondi per completare ogni esecuzione. È il limite della categoria Automation, che comprende Workflow, Blueprint e Approval. Le funzioni legate a pulsanti, regole di validazione, related list e REST API hanno 10 secondi, quelle pianificate 15 minuti. Zoho CRM termina forzatamente una funzione che supera il timeout della sua categoria.

Il secondo limite riguarda le righe eseguite: al massimo 200.000 per singola esecuzione. Le righe di esecuzione sono quelle che il runtime esegue davvero, non quelle scritte nel codice. Un ciclo su 200 record moltiplica quindi le righe del suo corpo per 200.

Anche le chiamate verso i servizi contano. Ogni esecuzione di zoho.crm.createRecord genera una richiesta API che viene scalata dal limite di chiamate esterne. Se il task si trova in un ciclo che gira cinque volte, consuma cinque chiamate. Una regola workflow accetta inoltre una sola funzione personalizzata tra le azioni immediate.

Quale cifra vale per le chiamate giornaliere

Le pagine di Zoho non coincidono sul numero di esecuzioni giornaliere. La pagina di aiuto sulle regole workflow indica ancora 20.000 chiamate al giorno oppure 200 per licenza, il valore più basso tra i due. La documentazione per sviluppatori descrive invece il sistema a crediti riportato nella tabella delle edizioni, con 20.000 crediti più 500 per licenza su Enterprise. La documentazione per sviluppatori è la fonte aggiornata e conviene pianificare su quei valori.

In Deluge gli argomenti di una funzione non arrivano da soli: vanno dichiarati nella funzione e mappati a un campo del CRM quando la si associa al trigger. Si dichiarano nel pannello Arguments oppure direttamente nella firma del codice, per esempio string dealId. Le funzioni scritte in Java, Node.js o Python ricevono invece il contesto in automatico tramite basicIO, un meccanismo standard di input e output.

Nella regola, ogni argomento si collega a un merge field, cioè un segnaposto che Zoho sostituisce con il valore del record al momento dell'esecuzione. Per una trattativa l'argomento dealId si mappa su Deals > Deals Id. Le variabili di merge delle regole workflow arrivano sempre come stringhe. Per questo il codice converte l'ID con toLong() prima di passarlo alle chiamate su Zoho CRM.

La categoria della funzione decide dove si può usarla. Una funzione della categoria Automation si associa a regole workflow, Blueprint e processi di approvazione, ma non a pulsanti personalizzati o pianificazioni. Se una funzione non compare nell'elenco quando si configura la regola, la prima verifica è proprio la categoria.

Conviene passare solo l'ID del record e rileggere il resto dentro la funzione. Così la funzione lavora sempre sui valori salvati e un solo argomento da mappare riduce gli errori di configurazione.

L'esempio di questa guida automatizza ciò che accade quando una trattativa passa a Closed Won. La funzione crea un task di avvio per il proprietario, somma le trattative vinte dell'azienda collegata e la segna come cliente. Infine imposta un flag sulla trattativa, così il lavoro viene fatto una volta sola.

Prima del codice servono tre campi personalizzati, da creare in Setup nei rispettivi moduli:

• Follow_Up_Created nel modulo Deals, una casella di controllo che indica se la trattativa è già stata elaborata.
• Won_Deals_Total nel modulo Accounts, un campo numerico o valuta per il totale delle trattative vinte.
• Last_Won_Date nel modulo Accounts, un campo data per l'ultima trattativa vinta.

Il codice usa anche campi standard come Deal_Name, Owner, Account_Name, Stage, Amount e Account_Type, con il valore Customer. Tutti questi nomi API, come il nome della fase Closed Won, sono esempi. Nella Sua organizzazione i nomi API reali si leggono in Setup, nell'elenco dei campi di ogni modulo. Se le fasi delle trattative sono state rinominate, nel codice va scritto il valore effettivo della fase.

Il flag Follow_Up_Created rende la funzione idempotente: rieseguirla sullo stesso record non produce effetti in più. Senza il flag, ogni nuovo salvataggio della trattativa rischierebbe di creare un secondo task.

Il blocco seguente è la funzione completa. Va incollato in Setup > Developer Hub > Functions, creando una nuova funzione Deluge nella categoria Automation con l'argomento dealId di tipo stringa.

void automation.deal_won_follow_up(string dealId)
{
    deal = zoho.crm.v8.getRecordById("Deals", dealId.toLong());
    if(deal.get("id") == null)
    {
        info "Trattativa non trovata: " + deal;
    }
    else if(deal.get("Follow_Up_Created") == true)
    {
        info "Gia elaborata: " + dealId;
    }
    else
    {
        // 1. Task di avvio per il proprietario, scadenza tra 3 giorni, collegato alla trattativa
        taskMap = Map();
        taskMap.put("Subject","Chiamata di avvio: " + deal.get("Deal_Name"));
        taskMap.put("Due_Date",zoho.currentdate.addDay(3).toString("yyyy-MM-dd"));
        taskMap.put("Owner",{"id":deal.get("Owner").get("id")});
        taskMap.put("What_Id",{"id":dealId});
        taskMap.put("$se_module","Deals");
        info zoho.crm.v8.createRecord("Tasks",taskMap);
        // 2. Somma delle trattative vinte sull'azienda
        account = deal.get("Account_Name");
        if(account != null)
        {
            accountId = account.get("id");
            related = zoho.crm.v8.getRelatedRecords("Deals","Accounts",accountId.toLong(),1,200);
            total = 0.0;
            for each d in related
            {
                if(d.get("Stage") == "Closed Won" && d.get("Amount") != null)
                {
                    total = total + d.get("Amount").toDecimal();
                }
            }
            accMap = Map();
            accMap.put("Account_Type","Customer");
            accMap.put("Won_Deals_Total",total);
            accMap.put("Last_Won_Date",zoho.currentdate.toString("yyyy-MM-dd"));
            info zoho.crm.v8.updateRecord("Accounts",accountId.toLong(),accMap);
        }
        // 3. Flag sulla trattativa: un nuovo salvataggio non crea un secondo task
        info zoho.crm.v8.updateRecord("Deals",dealId.toLong(),{"Follow_Up_Created":true});
    }
}

La funzione legge la trattativa e si ferma subito se non la trova o se il flag è già attivo. Le istruzioni info scrivono ogni risposta nel log, utile in fase di test. I parametri 1,200 di getRelatedRecords chiedono la prima pagina, fino a 200 trattative collegate. Un'azienda con più trattative richiede di leggere anche le pagine successive.

Le righe da adattare sono poche: i nomi API dei campi personalizzati, il valore della fase Closed Won, i giorni di scadenza in addDay(3), l'oggetto del task e il valore Customer del tipo di azienda.

Una funzione Deluge si testa dall'editor prima di associarla a qualsiasi regola, con il pulsante Run e l'ID di una trattativa reale. È un passaggio obbligato perché le funzioni Deluge non hanno bozze. Ogni salvataggio nell'editor aggiorna subito la funzione attiva, e ogni salvataggio crea una nuova revisione. La scheda Revisions conserva le ultime 30 versioni, dalla più recente.

Per il test conviene usare una trattativa di prova già in fase Closed Won, collegata a un'azienda di prova. Dopo l'esecuzione, i controlli da fare sono tre:

1. Nel log compaiono le risposte di createRecord e dei due updateRecord, senza errori.
2. Nella trattativa c'è un nuovo task con la scadenza a tre giorni, assegnato al proprietario.
3. L'azienda risulta di tipo Customer, con totale e data aggiornati, e sulla trattativa il flag è attivo.

Poi si esegue di nuovo la funzione sullo stesso ID. Il log deve mostrare solo il messaggio di trattativa già elaborata, e nessun secondo task deve comparire. Questa seconda esecuzione verifica l'idempotenza, cioè la proprietà che rende sicuro un nuovo salvataggio del record.

Se un campo obbligatorio manca, la risposta di Zoho contiene il codice MANDATORY_NOT_FOUND con il messaggio "required field not found" e il nome API del campo. È il segnale più comune di un nome API scritto in modo diverso da quello dell'organizzazione.

La regola workflow si crea in Setup > Automation > Workflow Rules, sul modulo Deals. Il trigger da scegliere è un'azione sul record, Edit (modifica). Le alternative sono Create, Create or Edit, Delete oppure un campo data. Il trigger scelto alla creazione non si può più cambiare modificando la regola: se è sbagliato, la regola va ricreata.

La configurazione dell'esempio, in ordine:

1. Modulo Deals, trigger Edit.
2. Condizione: Stage is modified to Closed Won (la fase viene modificata in Closed Won), con la ripetizione disattivata.
3. In Instant Actions, scegliere Function e selezionare deal_won_follow_up.
4. Mappare l'argomento dealId sul merge field Deals > Deals Id.
5. Salvare la regola.

La funzione si può mettere anche tra le Scheduled Actions, eseguite dopo un intervallo; una regola accetta al massimo 5 azioni pianificate. Nell'esecuzione, Zoho lancia in parallelo avvisi, task, webhook, funzioni e creazione di record, mentre aggiornamenti di campo, tag e conversione avvengono in sequenza. Se la stessa regola contiene anche un aggiornamento di campo, la funzione non deve presumere che quel campo sia già stato scritto.

Conta anche l'ordine delle automazioni: prima le regole di assegnazione, poi revisione e punteggio, quindi le regole workflow, approvazioni e Blueprint. Dopo il salvataggio, il test finale è spostare la trattativa di prova a Closed Won dall'interfaccia e controllare task, azienda e flag.

L'errore più insidioso è il fallimento silenzioso. In una funzione Automation un errore non gestito non mostra nulla all'utente, che vede il record salvato normalmente. L'errore compare solo nei log di esecuzione e nella scheda Failures di Setup > Developer Hub > Functions. La vista rapida di ogni funzione ha cinque schede, Overview, Analytics, Revisions, Logs e Failures; i dati di Analytics possono impiegare fino a 15 minuti per aggiornarsi.

Gli altri errori ricorrenti sono questi:

• Argomento non mappato o usato come numero senza toLong(): le variabili di merge arrivano sempre come stringhe.
• Automazioni a catena che non partono: createRecord senza options_map esegue solo approvazioni, Blueprint e orchestrazioni, non le regole workflow del modulo di destinazione.
• Lavoro duplicato a ogni salvataggio, quando manca un flag che blocchi la seconda esecuzione.
• Regola rotta dopo una pulizia: eliminare una funzione associata interrompe i componenti del CRM che la usano.
• Trigger mancati nelle fusioni automatiche: i trigger Edit e Delete non scattano quando i record vengono uniti in automatico, ma scattano con l'unione manuale.

Una funzione che aggiorna il proprio record deve tenere conto della protezione dai cicli di Zoho e, soprattutto, del flag. In Svennis, prima di attivare una regola in produzione, eseguiamo la funzione su una trattativa di prova e poi salviamo di nuovo lo stesso record, per verificare che il flag blocchi il secondo passaggio. È il controllo che più spesso fa emergere task duplicati prima che li vedano gli utenti.

Per un'azienda italiana il primo punto pratico riguarda il calcolo dei limiti giornalieri. La pagina di aiuto sulle regole workflow precisa che i limiti per giorno, come quello delle email, si calcolano sull'ora PST, cioè il fuso della costa pacifica statunitense. La giornata di calcolo quindi non coincide con la giornata lavorativa italiana. I crediti delle funzioni seguono invece una finestra mobile di 24 ore.

Il secondo punto è la lingua. Anche con l'interfaccia in italiano, la documentazione per sviluppatori e molte voci di Setup usano le etichette inglesi, come Developer Hub, Workflow Rules e Instant Actions. Nella documentazione interna conviene riportare entrambe le forme, così chi subentra ritrova subito i menu.

Il terzo punto è la responsabilità. Il permesso Manage Extensibility consente di creare e modificare funzioni, e ogni salvataggio va subito in produzione. Nelle PMI questo permesso finisce spesso a più persone di quante servano. Conviene assegnarlo a pochi profili, tenere traccia delle revisioni e affidare a un amministratore il controllo periodico della scheda Credits e della scheda Failures.

Infine, i valori come la fase Closed Won o il tipo Customer vanno allineati alle scelte fatte in fase di configurazione. Un CRM configurato in italiano con fasi rinominate richiede lo stesso valore esatto nel codice.

Il percorso consigliato parte dalla verifica dei requisiti e arriva al collaudo su un record reale. Questa lista di controllo riassume i passaggi descritti nella guida:

1. Verificare che le azioni senza codice della regola non bastino già al caso d'uso.
2. Controllare l'edizione di Zoho CRM, il permesso Manage Extensibility e la dotazione di crediti.
3. Creare i campi personalizzati, compreso il flag, e annotare i nomi API reali da Setup.
4. Scrivere la funzione nella categoria Automation, con un solo argomento per l'ID del record.
5. Testarla con Run su un record di prova, due volte, e leggere i log.
6. Creare la regola con il trigger giusto, perché non si potrà cambiare, e mappare l'argomento.
7. Controllare la scheda Failures nei primi giorni dopo l'attivazione.

Se l'automazione tocca più moduli o più app Zoho, è utile disegnare il processo prima del codice. La pagina sull'implementazione di Zoho CRM in Italia descrive come si imposta un progetto di configurazione e automazione, dal disegno dei processi al rilascio. Per le funzioni che girano a orari fissi, invece della modifica di un record, lo strumento corretto è la funzione pianificata, argomento del terzo post di questa serie.

• Configuring Workflow Rules, Zoho CRM Help
• Create Record in Zoho CRM, Zoho Deluge Help
• Managing Functions, Zoho CRM Developer Tools
• Functions, Deluge Guide, Zoho CRM Developer Tools
• Associate Functions with Zoho CRM, Developer Tools
• Functions, Platform Limits and Quotas, Zoho CRM Developer Tools
• Functions, Triggers and Associations, Zoho CRM Developer Tools