Client Script in Zoho CRM: quando usarlo e come scriverlo, con esempi di codice

Un Client Script in Zoho CRM conviene quando serve un controllo immediato mentre una persona compila una scheda. I casi tipici sono una convalida, un compilazione automatica, un campo reso obbligatorio da un altro o un avviso prima del salvataggio. Non conviene per una regola che deve valere sempre, perché il Client Script agisce solo sullo schermo a cui è collegato.

Un Client Script è un blocco di codice JavaScript che Zoho CRM esegue nel browser dell'utente, invece che sul server. Lo script parte in risposta a un evento, cioè a un'azione dell'utente come l'apertura di una pagina, la modifica di un campo o il clic su Save. Per leggere i campi e mostrare messaggi usa lo Zoho Development Kit (ZDK), la libreria di funzioni che Zoho mette a disposizione per le operazioni sull'interfaccia e per le chiamate alle API REST.

Questa guida è la prima di tre dedicate all'automazione con codice in Zoho CRM. Le altre due tratteranno la funzione collegata a una regola di workflow e la pianificazione. Qui trova la regola di scelta, i requisiti, un esempio completo con tre script da adattare e i limiti da verificare prima della produzione.

La regola di scelta è semplice: prima si prova lo strumento senza codice, poi si scrive codice solo se serve. Una regola di validazione, un aggiornamento di campo o un'attività da workflow e un workflow basato su una data coprono molti casi senza una riga di JavaScript. Il Client Script entra in gioco quando l'utente deve ricevere un riscontro mentre lavora, non dopo.

La regola di validazione è spesso sufficiente. L'articolo di Zoho sulle regole di validazione mostra come limitare lo sconto di una trattativa al 15% senza codice. La preferenza "Stop with error" impedisce il salvataggio, mentre "Allow by alert" lo consente dopo una conferma dell'utente. Zoho avverte che l'opzione di avviso viene rilasciata per fasi e potrebbe mancare nel Suo account.

Strumento	Quando interviene	Codice	Adatto a
Regola di validazione	Al salvataggio da Create, Quick create, Edit, quick edit, Convert e Kanban	No	Limiti su un campo, su quasi tutte le schermate
Workflow con aggiornamento campo o attività	Quando il record soddisfa le condizioni della regola	No	Azioni ripetitive standard
Workflow basato su data	A una data legata al record	No	Promemoria e scadenze
Client Script	Mentre l'utente lavora sulla pagina	Sì, JavaScript	Riscontro immediato a schermo
Funzione su regola di workflow	Quando scatta la regola	Sì	Logica sui dati che non dipende dalla schermata
Pianificazione	A orari stabiliti	Sì	Controlli periodici su molti record

Il Client Script è disponibile nelle edizioni Professional, Enterprise e Ultimate di Zoho CRM. Il profilo di chi scrive lo script deve avere attive le Developer Permissions. Senza quel permesso la voce non compare in Setup.

Il percorso standard è Setup > Developer Hub > Client Script, poi +New Script. Zoho chiede per prima cosa la categoria. Module fa partire lo script con gli eventi della pagina, mentre Commands lo lega alla command palette o a scorciatoie da tastiera. Per una convalida si sceglie Module.

Poi si indicano tre elementi:

• il modulo, per esempio Leads, Contacts, Accounts, Deals, Quotes o un modulo personalizzato;
• la pagina: Create, Clone, Edit, List, Detail (Standard o Canvas) oppure Create ed Edit in versione Wizard;
• il layout, perché ogni script vale solo per il layout scelto in configurazione.

In alternativa, uno script si può aggiungere direttamente dalla pagina Create, Clone o Edit di un record, con Add Script. In quel caso Zoho precompila i dettagli della pagina. Il Client Script collegato a un pulsante personalizzato si crea invece solo dalla pagina Buttons. La pagina di setup elenca ogni script con nome, dimensione, ultimo utente che l'ha modificato e stato, abilitato o disabilitato.

Gli eventi del Client Script decidono in quale momento il codice viene eseguito. Sulle pagine Create, Clone ed Edit esistono tre eventi di pagina: onLoad, onChange e onSave. Esistono poi eventi di campo, di subform e di pulsante.

onSave, l'unico che ferma il salvataggio

L'evento onSave scatta dopo il clic su Save o Save and New, ma prima che il record venga salvato davvero. Se lo script termina con return false, il record non viene salvato. Zoho indica onSave come l'evento per le convalide prima del salvataggio.

onChange di campo, un avviso e non un blocco

L'evento onChange di un campo scatta quando l'utente esce dal campo o passa a un altro. Serve per la convalida appena il dato è inserito. Da solo però non impedisce il salvataggio: avvisa, ma il record passa comunque. Esiste anche onType, che parte a ogni carattere digitato.

onBeforeUpdate, per la modifica inline

Sulla pagina Detail l'utente può modificare un campo direttamente, senza aprire Edit. L'evento di campo onBeforeUpdate intercetta quella modifica inline e return false la annulla. Senza questo evento, un controllo scritto per Create ed Edit resta aggirabile dalla scheda del record.

Un'avvertenza pratica: sulle pagine Create, Clone ed Edit i campi standard Salutation, Adjustment e Discount non supportano gli eventi di campo.

Un Client Script protegge solo la schermata a cui è collegato, quindi non è una regola sui dati né un controllo di sicurezza. I record che arrivano da API, import, webform, aggiornamento massivo o workflow non passano dal browser di un utente. Per quei record lo script non viene mai eseguito.

Anche Quick Create resta fuori. Alcune indicazioni elencano Quick Create tra le pagine, ma la documentazione per sviluppatori è esplicita: "currently Client Script in Zoho CRM cannot be executed in Quick Create Page". Se la regola deve valere anche lì, una regola di validazione la copre, perché Zoho la supporta in Quick create.

La regola di validazione ha però un suo limite. Zoho scrive che, se un campo usato nelle condizioni viene aggiornato da workflow, Blueprint, API, import o webform, l'aggiornamento prevale sulla regola. I record da webform che soddisfano i criteri finiscono invece in approvazione manuale. Una regola che deve reggere su ogni canale appartiene quindi a una funzione lato server, tema del prossimo post della serie.

Due altri limiti riguardano le azioni dell'utente. Il Client Script può disattivare il pulsante di eliminazione, ma non convalidare un record prima di eliminarlo. Inoltre non è possibile creare eventi personalizzati: si usano solo quelli previsti da Zoho.

L'esempio di questa guida impone una motivazione a ogni trattativa con sconto superiore al 15%. Servono tre script sul modulo Deals: uno blocca il salvataggio, uno rende obbligatorio il campo al volo, uno chiude la modifica inline. Prima del codice vanno creati i campi e configurate le pagine.

1. In Deals, layout Standard, crei due campi personalizzati: uno numerico per la percentuale di sconto e uno di testo per la motivazione.
2. Annoti il nome API dei due campi in Setup. Nel codice di questo post sono Discount_Percent e Discount_Reason, ma sono esempi da verificare nella Sua organizzazione.
3. Apra Setup > Developer Hub > Client Script > +New Script, categoria Module, modulo Deals, pagina Create, layout Standard, evento di pagina onSave. Qui andrà lo script A.
4. Ripeta la stessa configurazione per le pagine Edit e Clone.
5. Per lo script B scelga un evento di campo sul campo della percentuale, evento onChange, sulle stesse tre pagine.
6. Per lo script C scelga la pagina Detail (Standard), lo stesso campo e l'evento onBeforeUpdate.

Il campo personalizzato non è un capriccio. Il campo standard Discount non supporta gli eventi di campo sulle pagine Create, Clone ed Edit, quindi lo script B non potrebbe agganciarsi a esso. Lo stesso controllo dei nomi vale per le fasi di vendita, come Closed Won, se le userà in una condizione: il nome da scrivere nel codice va letto in Setup.

Lo script A controlla lo sconto al clic su Save e ferma il salvataggio se manca la motivazione. Lo incolli nell'editor dello script creato per la pagina Create, evento onSave, e poi nelle copie per Edit e Clone.

var discountField = ZDK.Page.getField('Discount_Percent');
var reasonField = ZDK.Page.getField('Discount_Reason');
var discount = Number(discountField.getValue()) || 0;
var reason = reasonField.getValue();
if (discount > 15 && (!reason || String(reason).trim() === '')) {
    reasonField.showError('Uno sconto superiore al 15% richiede una motivazione.');
    ZDK.Client.showAlert(
        'Questa trattativa ha uno sconto del ' + discount +
            '%. Aggiunga una motivazione prima di salvare.',
        'Motivazione obbligatoria',
        'OK'
    );
    return false; // impedisce il salvataggio del record
}

Le righe da adattare sono poche. I due nomi tra apici in ZDK.Page.getField vanno sostituiti con i nomi API dei Suoi campi. Il numero 15 è la soglia di sconto: se la Sua politica commerciale usa un altro valore, lo cambi qui e negli altri due script.

La riga con Number(...) || 0 tratta un campo vuoto come sconto zero, così lo script non si blocca su un valore mancante. showError segna in rosso il campo della motivazione, mentre showAlert apre una finestra con titolo e pulsante. Può tradurre liberamente i testi dei messaggi. L'ultima riga, return false, è quella che ferma il salvataggio e non va tolta.

Lo script B rende obbligatoria la motivazione appena l'utente esce dal campo della percentuale. Lo incolli nell'evento di campo onChange di Discount_Percent, sulle pagine Create, Edit e Clone. L'argomento value contiene il nuovo valore del campo, quindi non serve rileggerlo con getField.

var reasonField = ZDK.Page.getField('Discount_Reason');
var needsReason = (Number(value) || 0) > 15;
reasonField.setMandatory(needsReason);
if (needsReason) {
    ZDK.Client.showMessage(
        'Gli sconti superiori al 15% richiedono una motivazione.',
        { type: 'warning' }
    );
}

setMandatory accende o spegne l'obbligatorietà in base allo sconto. Se l'utente riporta lo sconto sotto la soglia, il campo torna facoltativo. showMessage con type: 'warning' mostra un avviso breve. Lo script B migliora l'esperienza, ma non sostituisce lo script A: un onChange di campo avvisa senza fermare il salvataggio.

Lo script C chiude la strada della modifica inline sulla pagina Detail. Lo incolli nell'evento di campo onBeforeUpdate di Discount_Percent, pagina Detail (Standard).

if ((Number(value) || 0) > 15) {
    ZDK.Client.showAlert(
        'Gli sconti superiori al 15% richiedono una motivazione. ' +
            'Usi Edit e compili Discount Reason.',
        'Usi la pagina Edit',
        'OK'
    );
    return false; // impedisce il salvataggio della modifica inline
}

Sulla pagina Detail lo script non può compilare il campo al posto dell'utente, perché setValue() non è supportato nei campi della pagina Detail, Standard o Canvas. Per questo lo script C rimanda alla pagina Edit, dove lo script A fa il controllo completo. Nel messaggio sostituisca "Discount Reason" con l'etichetta che i Suoi utenti vedono.

Un Client Script va provato in quattro passaggi prima di considerarlo in produzione. L'editor offre l'opzione Run: i log dello script compaiono nel pannello Messages e la sezione Terminal permette di provare subito le funzioni ZDK. Attenzione, durante Run le operazioni sui dati CRM sono reali, quindi usi record di prova.

1. Esegua ogni script con Run e controlli i messaggi nel pannello Messages.
2. Abiliti lo script: lo stato nella pagina di setup passa a enabled.
3. Acceda come utente senza profilo amministratore e crei una trattativa con sconto del 20% senza motivazione. Il salvataggio deve fermarsi.
4. Apra una trattativa esistente in Detail e provi a portare lo sconto sopra il 15% con la modifica inline. Lo script C deve annullarla.

Zoho indica che il Client Script funziona anche nelle app iOS e Android, con gli eventi onLoad, onChange e onSave sulle pagine Create, Edit e Clone. Se i venditori lavorano dal telefono, includa l'app nei test.

In Svennis proviamo ogni script di convalida con un utente senza privilegi di amministratore e su tutti i layout del modulo. L'errore che vediamo più spesso è un layout aggiunto in seguito, rimasto senza la sua copia dello script, da cui le trattative passano senza controllo.

I limiti del Client Script sono pochi ma rigidi, e conviene verificarli prima di scrivere codice più ambizioso. Questi sono quelli indicati nella documentazione per sviluppatori di Zoho:

• ogni esecuzione ha un timeout di 10 secondi, e una chiamata API più lenta interrompe lo script;
• si possono creare fino a 30 Client Script per pagina;
• ogni script vale per un solo layout, quindi un nuovo layout richiede la sua copia;
• per ogni pagina si caricano al massimo 5 risorse statiche, cioè file JavaScript condivisi tra più script;
• il linguaggio è solo JavaScript, con le funzioni del nucleo fino a ES7;
• metodi come setTimeout, setInterval, addEventListener, WebSocket, window e document non sono disponibili, e nemmeno window.localStorage;
• le chiamate a servizi esterni funzionano solo verso domini inseriti in Trusted Domains.

Anche il consumo di API va considerato. Ogni chiamata alle Web API di ZDK, cioè le operazioni che leggono o scrivono dati in Zoho CRM, conta sul limite giornaliero di chiamate API. I tre script di questa guida usano solo funzioni sulla pagina e sul client, ZDK.Page e ZDK.Client. Se in futuro aggiungerà letture di altri record, per esempio per cercare duplicati, tenga conto di quel consumo.

Per le chiamate lente Zoho suggerisce di mostrare un loader, che sospende l'esecuzione fino alla risposta. Per più campi sulla stessa pagina consiglia un unico script con evento di pagina onChange e condizioni if o switch, invece di tanti script separati.

Per un'azienda italiana il Client Script è utile soprattutto dove le regole commerciali sono personali e passano per le mani dei venditori. Sconti da motivare, campi obbligatori solo per certi clienti, avvisi sulle condizioni di pagamento: sono controlli che il venditore deve vedere mentre compila, non il giorno dopo.

Il primo punto pratico riguarda la lingua. Gli utenti vedono etichette in italiano, ma il codice usa i nomi API dei campi e delle fasi. Chi scrive lo script deve leggerli in Setup e non dedurli dall'interfaccia.

Il secondo riguarda i layout. Molte aziende tengono layout diversi per linee di prodotto o canali, per esempio il canale diretto e la rete di agenti. Chi vende wholesale B2B, come descritto nella pagina su Zoho CRM per la moda e il wholesale, ha spesso listini e sconti per cliente. Ogni layout richiede la propria copia dello script, e un layout dimenticato è un varco.

Il terzo riguarda chi lavora fuori sede. Gli agenti usano spesso l'app mobile, e Zoho indica che il Client Script funziona anche lì. Se Zoho CRM ha un portale per rivenditori, Zoho precisa che il Client Script funziona automaticamente anche nei portali ed è abilitato per i nuovi tipi di utente. Conviene quindi decidere in anticipo quali script devono valere per gli utenti esterni.

Il primo passo concreto è scrivere su carta la regola che vuole imporre e chiedersi se una regola di validazione basta. Se basta, la configuri senza codice. Se serve un riscontro immediato o un campo che diventa obbligatorio al volo, passi al Client Script.

1. Verifichi di avere l'edizione Professional, Enterprise o Ultimate e le Developer Permissions sul Suo profilo.
2. Elenchi i layout del modulo e le pagine da coprire: Create, Edit, Clone e Detail per la modifica inline.
3. Crei i campi personalizzati e annoti i nomi API in Setup.
4. Adatti gli script A, B e C, li provi con Run su record di prova e li abiliti.
5. Ripeta i test come utente non amministratore e dall'app mobile.
6. Per i record da API, import e webform preveda una regola lato server.

Prima del rilascio, la checklist di configurazione di Zoho CRM prima della messa in produzione aiuta a non dimenticare layout, profili e permessi. Se valuta anche altre applicazioni collegate al CRM, la pagina su Zoho CRM Plus descrive il pacchetto. Per un progetto di configurazione completo, trova i dettagli nella pagina sull'implementazione di Zoho CRM in Italia.

• Zoho CRM, Validation Rule
• Zoho CRM, Client Script for Mobile Apps
• Zoho CRM, Client Script FAQs
• Zoho CRM, Best Practices of Client Script
• Zoho CRM, Creating a Client Script
• Zoho CRM, Client Script Events
• Zoho CRM, Client Script Overview