Client Script Zoho CRM: cand il folosesti, cu cod pentru validari in formular

Folositi Client Script in Zoho CRM cand un utilizator completeaza un formular si trebuie sa primeasca un raspuns pe loc: o eroare, un camp devenit obligatoriu sau o avertizare. Pentru o regula care trebuie sa tina la orice inregistrare, indiferent de unde vine, alegeti o validation rule sau o functie care ruleaza pe server.

Client Script este o bucata de cod JavaScript care ruleaza in browserul utilizatorului, nu pe server. Scriptul raspunde la evenimente, adica la actiuni facute in interfata Zoho CRM. Exemple de evenimente sunt deschiderea unei pagini, iesirea dintr-un camp sau apasarea butonului Save. Documentatia Zoho precizeaza ca functia accepta doar JavaScript.

Acest ghid este primul dintr-o serie de trei despre automatizarea Zoho CRM cu cod. Regula de decizie pentru cele trei instrumente este urmatoarea:

• Client Script: reactie instantanee in ecran, cat timp persoana lucreaza in formular.
• Functie pe un workflow rule: logica pe server, aplicata dupa salvare, inclusiv pentru inregistrarile care nu trec prin formular.
• Programare (schedule): o actiune care ruleaza la o anumita ora sau data, fara sa astepte un utilizator.

Inaintea oricarui cod, verificati optiunea nativa, fara cod. Daca o setare din Zoho CRM rezolva deja problema, un script nu face decat sa adauge intretinere.

O validation rule este o regula nativa din Zoho CRM care verifica valoarea unui camp la salvare si opreste sau avertizeaza utilizatorul, fara nicio linie de cod. Pentru a crea una, utilizatorul are nevoie de permisiunea de profil Modules Customization. Articolul Zoho despre crearea unei validation rule in Zoho CRM foloseste chiar exemplul unui discount pe Deals limitat la 15%.

Zoho ofera doua preferinte de validare. Stop with error impiedica salvarea inregistrarii. Allow by alert permite salvarea dupa ce utilizatorul confirma avertizarea. Zoho mentioneaza ca optiunea de alerta este lansata treptat si poate lipsi din unele conturi.

O validation rule poate avea pana la 10 conditii primare, cinci conditii secundare pentru fiecare conditie primara si cinci criterii pentru fiecare conditie secundara. Regula nu functioneaza insa pe orice tip de camp. Zoho exclude lookup-urile cu selectie multipla, multi-picklist, campurile multi-user, formula, auto-number, incarcare de imagine si campurile multi-line.

Celelalte optiuni fara cod sunt regulile de workflow:

• un workflow cu actualizare de camp sau cu sarcina, pentru o consecinta simpla a salvarii;
• un workflow bazat pe data, pentru actiuni legate de un termen.

Treceti la Client Script doar cand aveti nevoie de ceva ce aceste reguli nu ofera: reactie in timp ce utilizatorul scrie, un camp care devine obligatoriu in functie de altul sau un mesaj explicativ inainte de salvare.

Diferenta esentiala dintre cele trei instrumente este locul in care ruleaza. Client Script ruleaza in pagina deschisa de utilizator si protejeaza doar acel ecran. Scriptul nu este o regula a datelor si nici un control de securitate.

Criteriu	Client Script	Validation rule	Functie pe workflow rule
Unde ruleaza	In browser, pe pagina la care este atasat	In Zoho CRM, la salvare	Pe server
Necesita cod	Da, JavaScript	Nu	Da, Deluge
Reactie in timp ce utilizatorul scrie	Da, cu onChange sau onType	Nu, la salvare	Nu, dupa salvare
Quick Create	Nu ruleaza	Suportat	Nu lucreaza in formular
Date din API, import, webform	Nu trec prin script	Actualizarea campului are prioritate	Varianta potrivita pentru o regula fara exceptii
Potrivit pentru	Feedback imediat, campuri obligatorii conditionat	Limite simple, de exemplu un discount maxim	Reguli aplicate oricum ajunge inregistrarea

Randul despre import si API merita citit de doua ori. Zoho precizeaza ca, daca un camp folosit intr-o validation rule este actualizat printr-un workflow rule, Blueprint, API, import sau webform, actualizarea are prioritate fata de regula. Inregistrarile din webform care indeplinesc criteriile regulii ajung la aprobare manuala. Pentru o regula care trebuie sa tina fara exceptie, logica pe server ramane plasa de siguranta.

In practica, cele trei instrumente se combina. Client Script explica problema pe loc, validation rule acopera paginile native precum Quick Create si Kanban, iar functia pe server prinde restul.

Client Script este disponibil in editiile Professional, Enterprise si Ultimate ale Zoho CRM. Profilul cu care lucrati trebuie sa aiba activate Developer Permissions (permisiunile de dezvoltator). Daca alegeti inca intre pachete, comparatia dintre Zoho One si Zoho CRM va ajuta sa vedeti ce editie primiti.

Un Client Script se creeaza din Setup in patru pasi:

1. Deschideti Setup > Developer Hub > Client Script si apasati +New Script.
2. Alegeti categoria Module, pentru declansare prin evenimente. Categoria Commands porneste scriptul din command palette sau prin scurtaturi de tastatura.
3. Selectati modulul, de exemplu Deals, Leads, Accounts, Quotes sau un modul personalizat.
4. Selectati pagina si layout-ul, apoi tipul de eveniment si evenimentul.

Exista si o a doua cale: butonul Add Script din pagina de creare, clonare sau editare a unei inregistrari. Acolo Zoho completeaza automat detaliile paginii.

Paginile Zoho nu spun acelasi lucru despre locurile in care ruleaza scriptul. Ghidul de creare enumera doar "Create Page, Clone Page, or Edit Page". Pagina despre evenimente, din documentatia pentru dezvoltatori, adauga List Page (Standard), Detail Page (Standard), Detail Page (Canvas) si paginile Wizard. Pentru Quick Create, FAQ-ul pentru dezvoltatori este clar: "No, currently Client Script in Zoho CRM cannot be executed in Quick Create Page."

Client Script functioneaza si in aplicatiile mobile Zoho CRM pentru iOS si Android, pe paginile Create, Edit si Clone. In portalurile Zoho CRM scriptul functioneaza automat.

Pentru validare conteaza trei evenimente de pagina pe paginile Create, Clone si Edit: onLoad, onChange si onSave. Evenimentul onSave apare dupa apasarea butonului Save sau Save and New, dar inainte ca inregistrarea sa fie salvata efectiv. O instructiune return false in scriptul onSave impiedica salvarea.

Evenimentul de camp onChange porneste cand utilizatorul iese din camp sau trece la alt camp. Evenimentul onType porneste imediat ce utilizatorul tasteaza o valoare. Un onChange de camp poate afisa o avertizare, dar nu opreste singur salvarea. O validare care trebuie sa blocheze are deci nevoie si de un script onSave.

Pe pagina Detail, evenimentul de camp onBeforeUpdate ruleaza la editarea inline a unui camp. Cu return false, modificarea inline nu se salveaza. Exista si evenimente pentru subformulare, precum onCellChange si onRowAdd, si pentru butoane personalizate. Scriptul unui buton personalizat se configureaza doar din pagina Buttons.

Doua detalii din documentatia Zoho schimba modul de lucru:

• Pe paginile Create, Clone si Edit, campurile standard Salutation, Adjustment si Discount nu suporta evenimente de camp. Exemplul din acest ghid foloseste deci un camp personalizat pentru procentul de discount.
• Pentru reactii pe mai multe campuri ale aceleiasi pagini, Zoho recomanda un singur script cu evenimentul de pagina onChange si conditii if sau switch, in locul mai multor scripturi.

Exemplul lucrat impune o regula simpla pe modulul Deals: orice discount peste 15% trebuie insotit de un motiv scris. Regula foloseste trei scripturi. Scriptul A blocheaza salvarea, scriptul B face motivul obligatoriu imediat ce procentul depaseste pragul, iar scriptul C inchide calea editarii inline din pagina Detail.

Numele API folosite mai jos, Discount_Percent si Discount_Reason, sunt exemple. Verificati numele API reale ale campurilor in contul dumneavoastra, in Setup, inainte de a lipi codul. Acelasi lucru este valabil pentru numele etapelor, de exemplu Closed Won, daca le folositi in conditii.

Pasii de configurare, in ordine:

1. Creati in Deals doua campuri personalizate in layout-ul Standard: un camp numeric pentru procent (Discount Percent) si un camp text pentru motiv (Discount Reason).
2. In Setup > Developer Hub > Client Script, creati un script nou: categoria Module, modulul Deals, pagina Create, layout-ul Standard, evenimentul de pagina onSave. Lipiti scriptul A.
3. Repetati pasul pentru paginile Edit si Clone.
4. Creati scriptul B pe aceleasi trei pagini, ca eveniment de camp onChange pe Discount_Percent.
5. Creati scriptul C pe pagina Detail (Standard), ca eveniment de camp onBeforeUpdate pe Discount_Percent.
6. Testati fiecare script cu Run in editor, activati-l, apoi testati din nou ca utilizator fara drepturi de administrator.

Fiecare pagina primeste cel mult doua scripturi, mult sub limita Zoho de 30 de scripturi pe pagina. Daca modulul Deals are si alte layout-uri decat Standard, fiecare layout are nevoie de propria copie a scripturilor.

Scriptul A citeste procentul de discount si motivul in momentul in care utilizatorul apasa Save. Lipiti codul de mai jos in editorul unui script creat pe Deals, pagina Create, layout Standard, eveniment de pagina onSave, apoi repetati pentru Edit si Clone.

// Deals, pagina Create (repetati pentru Edit si Clone), layout Standard, eveniment onSave
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('Un discount peste 15% necesita un motiv.');
    ZDK.Client.showAlert(
        'Aceasta oportunitate are un discount de ' + discount +
        '%. Adaugati motivul inainte de salvare.',
        'Motiv obligatoriu', 'OK');
    return false; // opreste salvarea inregistrarii
}

ZDK.Page.getField citeste campul din formular, iar getValue returneaza valoarea lui. Constructia Number(...) || 0 transforma un camp gol in zero, ca scriptul sa nu esueze. Conditia verifica doua lucruri: procentul depaseste 15 si motivul lipseste sau contine doar spatii.

Cand conditia este adevarata, showError afiseaza eroarea langa campul Discount_Reason. ZDK.Client.showAlert deschide o fereastra cu mesaj, titlu si buton. Instructiunea return false opreste salvarea. Liniile pe care le schimbati sunt numele API ale celor doua campuri, pragul de 15 si textele mesajelor. Daca pragul se schimba, actualizati-l in toate cele trei scripturi, altfel regulile se contrazic.

Scriptul B face campul Discount_Reason obligatoriu cand utilizatorul paraseste campul de procent cu o valoare peste 15. Creati-l pe paginile Create, Edit si Clone, ca eveniment de camp onChange pe Discount_Percent, si lipiti codul urmator. Argumentul value contine noua valoare a campului.

// Aceleasi pagini, eveniment de camp onChange pe Discount_Percent
var reasonField = ZDK.Page.getField('Discount_Reason');
var needsReason = (Number(value) || 0) > 15;
reasonField.setMandatory(needsReason);
if (needsReason) {
    ZDK.Client.showMessage('Discounturile peste 15% necesita un motiv.', { type: 'warning' });
}

Metoda setMandatory primeste true sau false, deci campul redevine optional daca utilizatorul coboara discountul. ZDK.Client.showMessage afiseaza un mesaj scurt de tip warning. Scriptul B nu opreste salvarea. Rolul lui este sa anunte regula inainte ca utilizatorul sa ajunga la Save.

Scriptul C acopera editarea inline din pagina Detail, unde scripturile de pe Create si Edit nu ruleaza. Creati-l pe pagina Detail (Standard), eveniment de camp onBeforeUpdate pe Discount_Percent.

// Pagina Detail (Standard), eveniment de camp onBeforeUpdate pe Discount_Percent
if ((Number(value) || 0) > 15) {
    ZDK.Client.showAlert(
        'Discounturile peste 15% necesita un motiv. Folositi Edit si completati Discount Reason.',
        'Folositi pagina Edit', 'OK');
    return false; // opreste salvarea modificarii inline
}

Scriptul C blocheaza modificarea in loc sa ceara motivul pe loc, pentru ca Zoho nu suporta setValue() in campurile paginilor Detail, nici Standard, nici Canvas. Utilizatorul este trimis in pagina Edit, unde ruleaza scripturile A si B. In ambele scripturi schimbati, la nevoie, numele API ale campurilor, pragul si textul mesajelor.

Testati fiecare Client Script in editor cu optiunea Run inainte de a-l activa. Mesajele din instructiunile de logare apar in panoul Messages al optiunii Run. Functiile ZDK pot fi incercate direct in sectiunea Terminal. Operatiile CRM executate in timpul unui Run sunt reale, deci lucrati pe o inregistrare de test, nu pe oportunitatea unui client.

Dupa activare, verificati aceste cazuri:

1. Salvati o oportunitate cu discount 20% si motiv gol. Salvarea trebuie oprita de scriptul A.
2. Introduceti 20% in campul de procent si iesiti din camp. Motivul trebuie sa devina obligatoriu, cu mesaj de avertizare.
3. Coborati procentul la 10%. Motivul trebuie sa redevina optional.
4. Din pagina Detail, modificati inline procentul la 20%. Scriptul C trebuie sa refuze modificarea.
5. Repetati totul cu un utilizator obisnuit, nu cu administratorul care a scris scripturile.

La Svennis, inainte sa activam un script onSave, il testam cu un cont fara profil de administrator si verificam separat editarea inline din pagina Detail, pentru ca acolo scripturile de pe Create si Edit nu ruleaza. Tot la testare merita sa importati o inregistrare cu discount mare, ca sa vedeti cu ochii dumneavoastra ca importul trece pe langa script.

Limitele Client Script sunt putine, dar fiecare poate opri un script care a mers la test. Lista de mai jos rezuma ce precizeaza documentatia Zoho:

• Timp de executie: 10 secunde pe rulare. Un apel API mai lent opreste executia, iar Zoho recomanda afisarea unui loader pana vine raspunsul.
• Numar de scripturi: cel mult 30 de Client Scripts pe pagina si cel mult 5 resurse statice pe pagina.
• Layout: scriptul ruleaza doar pe layout-ul ales la configurare. Un layout nou are nevoie de propria copie.
• Credite API: fiecare apel ZDK Web API face un apel catre Zoho CRM si intra in limita zilnica. Scripturile din acest ghid folosesc doar ZDK.Page si ZDK.Client, care lucreaza pe ecran.
• setValue() pe Detail: nesuportat pe paginile Detail, Standard sau Canvas.
• API-uri de browser: setTimeout, setInterval, addEventListener, WebSocket si window.localStorage nu sunt disponibile.
• Servicii externe: apelurile catre alte domenii functioneaza doar daca domeniul este adaugat in Trusted Domains.
• Stergere: puteti dezactiva butonul de stergere, dar nu puteti valida inainte de stergerea unei inregistrari.

Doua limite privesc flexibilitatea. Nu puteti crea evenimente personalizate, ci doar folosi setul de evenimente oferit de Zoho. Pentru filtrele pe lookup cu setCriteria(), sunt suportati doar operatorii starts_with si equals. JavaScript este suportat pana la ES7, inclusiv functiile async.

Pentru o firma din Romania, cel mai util Client Script verifica de obicei CUI-ul (codul unic de identificare fiscala) introdus manual pe o companie. Scriptul prinde greselile de tastare inainte de salvare, cand utilizatorul inca are documentul in fata. Un CUI gresit in CRM ajunge altfel in oferte si in facturare, de exemplu prin integrarea SmartBill cu Zoho CRM.

Scriptul urmator verifica doar formatul: accepta un prefix RO optional, urmat numai de cifre. Lipiti-l pe modulul Accounts, pagina Create (apoi Edit si Clone), eveniment de pagina onSave. Numele API CUI este un exemplu; verificati-l in Setup.

// Accounts, pagina Create (repetati pentru Edit si Clone), eveniment onSave
var cuiField = ZDK.Page.getField('CUI');
var cui = String(cuiField.getValue() || '').trim().toUpperCase().replace(/^RO/, '').trim();
if (cui !== '' && !/^[0-9]+$/.test(cui)) {
    cuiField.showError('CUI-ul trebuie sa contina doar cifre, cu prefixul RO optional.');
    return false; // opreste salvarea
}

Schimbati numele campului si textul mesajului dupa contul dumneavoastra. Scriptul nu confirma ca firma exista. Pentru datele oficiale ale firmei, extensia ANAF pentru Zoho CRM preia informatiile pe baza CUI-ului.

Limita discutata mai sus ramane valabila si aici. Companiile create prin import, API sau webform nu trec prin script. Daca formatul CUI trebuie sa fie corect la toate inregistrarile, dublati verificarea cu o regula pe server.

Primul pas este sa scrieti regula in cuvinte si sa decideti unde trebuie sa tina: doar in formular sau la orice inregistrare. Raspunsul alege instrumentul, conform tabelului de decizie din acest ghid.

O ordine practica de lucru arata astfel:

1. Verificati ca editia dumneavoastra este Professional, Enterprise sau Ultimate si activati Developer Permissions pe profilul care va scrie scripturile.
2. Incercati mai intai o validation rule sau un workflow. Daca acopera cerinta, opriti-va aici.
3. Notati numele API reale ale campurilor si layout-urile modulului, din Setup.
4. Construiti exemplul cu discountul pe o inregistrare de test, cu cele trei scripturi, si parcurgeti lista de testare.
5. Stabiliti cine intretine scripturile si unde este documentat pragul, ca sa nu ramana copii diferite pe pagini diferite.

Daca doriti ca regulile de validare sa fie gandite impreuna cu restul configurarii CRM, pagina despre implementarea Zoho CRM in Romania descrie serviciile disponibile. Urmatoarele doua ghiduri din serie trateaza functia pe un workflow rule si programarea actiunilor.

• 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