Functie Deluge intr-o regula de workflow Zoho CRM, pas cu pas

O functie Deluge intr-o regula de workflow Zoho CRM se leaga din Setup > Automation > Workflow Rules. Alegeti declansatorul si adaugati la Instant Actions actiunea Function. Apoi selectati o functie din categoria Automation si mapati argumentele la campuri de imbinare, de exemplu Deal Id. Functia ruleaza asincron: inregistrarea se salveaza fara sa astepte terminarea ei.

Doi termeni apar in tot ghidul. Deluge este limbajul de scripting propriu Zoho, cel mai profund integrat limbaj pentru functiile din Zoho CRM. O regula de workflow este un set de actiuni, cum ar fi notificari pe email, sarcini si actualizari de camp, care se executa cand sunt indeplinite anumite conditii.

Regula de decizie pentru automatizarea cu cod

Acest ghid face parte dintr-un set de trei articole despre automatizarea Zoho CRM cu cod. Inainte de orice cod, verificati varianta fara cod: o regula de validare, o actualizare de camp sau o sarcina in workflow, ori un workflow declansat de un camp de tip data. Daca aceste variante nu ajung, alegeti astfel:

• un client script, cand logica trebuie sa lucreze in interfata, in timp ce utilizatorul completeaza formularul;
• o functie pe o regula de workflow, cand o actiune asupra unei inregistrari trebuie sa declanseze mai multi pasi pe server;
• o functie programata, cand lucrul trebuie facut la intervale regulate, independent de orice actiune a utilizatorului.

Restul ghidului trateaza varianta din mijloc, cu un exemplu complet pe care il puteti reproduce.

Alegeti o functie Deluge doar cand actiunile standard ale regulii de workflow nu acopera cerinta. Zoho CRM ofera ca Instant Actions notificari pe email, sarcini, actualizari de camp, webhook-uri, crearea de inregistrari si functii. Documentatia Zoho descrie actiunile personalizate ca solutie pentru situatiile in care actiunile implicite nu sunt suficiente.

O functie isi merita locul in cateva situatii clare. Prima este o valoare calculata, cum ar fi un total. A doua este citirea altor inregistrari, de exemplu toate deal-urile unui cont. A treia este logica conditionala, iar a patra sunt mai multi pasi executati impreuna. Tabelul de mai jos compara variantele de declansare pentru care documentatia Zoho da limite concrete.

Varianta	Cand o folositi	Comportament si limita de timp
Actiuni standard de workflow (camp, email, sarcina, webhook)	Cerinta se rezolva fara calcul si fara alte inregistrari	Fara cod; se configureaza direct in regula
Functie Automation pe o regula de workflow	Calcule, citirea altor inregistrari, mai multi pasi	Ruleaza asincron, maximum 30 de secunde
Functie programata	Procesari in lot, sincronizari, curatenie de date	Orar, zilnic, saptamanal, lunar sau personalizat; maximum 15 minute
Functie pe buton personalizat	Utilizatorul porneste manual actiunea	Returneaza un text afisat intr-o fereastra modala; maximum 10 secunde

O regula de workflow accepta o singura functie personalizata in Instant Actions, alaturi de pana la 5 notificari pe email, 5 sarcini si 5 actualizari de camp. Daca aveti nevoie de mai multe operatii legate intre ele, le puneti pe toate in aceeasi functie.

Functiile au acces complet in editiile Enterprise, CRM Plus, Ultimate si Zoho One ale Zoho CRM. In editiile Standard si Professional, functiile sunt accesibile doar prin extensii. Daca sunteti inca in faza de alegere a editiei, comparatia Zoho One vs Zoho CRM va ajuta sa vedeti ce primiti in fiecare pachet.

Utilizatorul care scrie functia are nevoie de permisiunea Manage Extensibility. Aceasta se gaseste la Developer Permissions, in setarile profilului.

Creditele si limitele de executie

Zoho CRM guverneaza executia functiilor printr-un sistem de credite. Fiecare executie a unei functii Deluge consuma un credit. Pentru Enterprise si Zoho One, alocarea zilnica este de 20.000 de credite gratuite plus 500 pentru fiecare licenta de utilizator, plus creditele cumparate suplimentar. Maximul este de 400.000 de credite, dintre care 200.000 gratuite si 200.000 suplimentare. Creditele se reseteaza pe o fereastra mobila de 24 de ore.

Functiile pornite din workflow au o limita de 30 de secunde pe executie. Peste aceasta limita sunt oprite fortat. O singura executie poate rula cel mult 200.000 de linii. Limita priveste liniile executate efectiv, inclusiv buclele, ramurile si functiile apelate, nu liniile din codul sursa.

Paginile Zoho care nu se potrivesc

Pagina de ajutor despre regulile de workflow arata o cifra mai mica: 20.000 de apeluri pe zi sau 200 pe licenta, oricare este mai mic. Documentatia pentru dezvoltatori este mai recenta si descrie sistemul de credite de mai sus. Pentru planificare, folositi pagina de limite si cote din documentatia Zoho pentru dezvoltatori.

O functie Deluge nu primeste automat datele inregistrarii care a declansat regula. Fiecare argument trebuie declarat in functie si apoi mapat la un camp CRM in momentul asocierii cu regula. Un camp de imbinare (merge field) este o variabila care inlocuieste, la executie, valoarea unui camp din inregistrare, de exemplu Deal Id.

Asocierea se face intotdeauna in configurarea declansatorului, nu in editorul functiei. Declarati argumentul fie in panoul Arguments, fie direct in semnatura functiei. In exemplul din acest ghid, semnatura este void automation.deal_won_follow_up(string dealId).

Trei reguli care evita erorile frecvente

• Functia trebuie sa fie in categoria Automation. Categoria stabileste unde poate fi asociata functia: o functie Automation merge pe Workflow Rules, Blueprints si Approvals, dar nu pe butoane personalizate sau programari.
• Campurile de imbinare ajung in functie intotdeauna ca text (string). Un ID trebuie convertit cu toLong() inainte de a fi folosit in apeluri catre CRM.
• Functiile de workflow returneaza void. Salvarea inregistrarii se incheie independent de executia functiei, deci utilizatorul nu vede rezultatul pe ecran.

Functiile scrise in Java, Node.js sau Python primesc contextul automat, printr-un mecanism numit basicIO, fara mapare manuala. Ghidul de fata ramane la Deluge, unde maparea este explicita.

Exemplul din acest ghid automatizeaza momentul in care un deal (o oportunitate de vanzare) trece in etapa Closed Won. Functia face trei lucruri intr-o singura executie:

1. creeaza o sarcina de apel de pornire pentru proprietarul deal-ului, cu termen peste 3 zile, legata de deal;
2. aduna valoarea tuturor deal-urilor castigate ale contului si marcheaza contul drept client;
3. bifeaza un camp de control pe deal, ca functia sa nu mai lucreze a doua oara pentru acelasi deal.

Punctul 3 face functia idempotenta. Asta inseamna ca o poti rula de mai multe ori pe aceeasi inregistrare fara sa dublezi rezultatul.

Cele trei campuri personalizate

Creati campurile inainte sa scrieti codul. Numele API din exemplu sunt:

• Follow_Up_Created, o caseta de bifat in modulul Deals;
• Won_Deals_Total, un camp numeric sau de tip moneda in modulul Accounts;
• Last_Won_Date, un camp de tip data in modulul Accounts.

Numele API ale campurilor sunt exemple. La fel sunt numele de etapa Closed Won si valoarea Customer din campul Account_Type. Verificati-le in propria organizatie, in Setup, la modulul si campul respectiv. Zoho genereaza numele API la crearea campului. Un singur caracter diferit face ca functia sa scrie in gol sau sa esueze.

Codul de mai jos este functia completa. Il lipiti in Setup > Developer Hub > Functions, intr-o functie noua scrisa in Deluge, din categoria Automation, cu argumentul dealId de tip string.

void automation.deal_won_follow_up(string dealId)
{
  deal = zoho.crm.v8.getRecordById("Deals", dealId.toLong());
  if(deal.get("id") == null)
  {
    info "Deal negasit: " + deal;
  }
  else if(deal.get("Follow_Up_Created") == true)
  {
    info "Deja procesat: " + dealId;
  }
  else
  {
    // 1. Sarcina pentru proprietarul deal-ului, termen peste 3 zile, legata de deal
    taskMap = Map();
    taskMap.put("Subject","Apel de pornire: " + 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. Totalul deal-urilor castigate, scris pe cont
    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. Marcheaza deal-ul, ca o noua salvare sa nu creeze a doua sarcina
    info zoho.crm.v8.updateRecord("Deals",dealId.toLong(),{"Follow_Up_Created":true});
  }
}

Primele doua ramuri opresc functia devreme. Prima opreste lucrul daca deal-ul nu exista, a doua daca a fost deja procesat. Fiecare apel catre CRM este precedat de info, deci raspunsul lui apare in log.

Liniile pe care le adaptati sunt urmatoarele:

• addDay(3), pentru alt termen al sarcinii;
• textul din Subject;
• numele etapei "Closed Won" si valoarea "Customer", daca in organizatia dumneavoastra difera;
• numele API ale celor trei campuri personalizate.

Parametrii 1,200 din getRelatedRecords cer prima pagina de rezultate. Pentru conturi cu foarte multe deal-uri, verificati paginarea in documentatie.

Testati functia manual, cu un ID real de deal, inainte sa o legati de vreo regula. Functiile Deluge nu au o etapa de ciorna si publicare. Fiecare salvare in editor actualizeaza imediat functia live. Java, Node.js si Python au un pas separat de publicare, dar Deluge nu.

Pentru test, deschideti un deal de proba si copiati ID-ul lui din adresa paginii. Apoi rulati functia din editor cu Run, dand acest ID ca valoare pentru dealId. Verificati trei lucruri:

• sarcina a aparut pe deal, cu proprietarul si termenul corecte;
• contul are totalul, data si tipul actualizate;
• caseta Follow_Up_Created este bifata.

Rulati apoi functia a doua oara, cu acelasi ID. Mesajul din log trebuie sa fie cel pentru deal deja procesat, iar pe deal nu trebuie sa apara o a doua sarcina. Daca a aparut, campul de control nu este citit corect, de obicei din cauza unui nume API gresit.

Pentru ca fiecare salvare este live, pastrati o copie a versiunii care functioneaza. Tab-ul Revisions arata ultimele 30 de versiuni ale functiei, cele mai noi primele. Pentru Deluge, fiecare salvare creeaza o revizie noua.

La Svennis legam regula de workflow abia dupa ce functia a trecut de doua ori testul manual pe un deal de proba si am citit in log raspunsul fiecarui apel. Greseala pe care o intalnim cel mai des la clienti este lipsa campului de control, care face ca fiecare salvare a deal-ului sa mai creeze o sarcina.

Regula de workflow se creeaza din Setup > Automation > Workflow Rules, pe modulul Deals. Pasii de mai jos leaga functia testata de momentul in care un deal devine castigat.

1. Creati o regula noua pe modulul Deals si dati-i un nume descriptiv.
2. Alegeti declansatorul la editarea inregistrarii (Edit). Optiunea de declansare nu mai poate fi schimbata ulterior prin editarea regulii, deci alegeti-o cu atentie.
3. Adaugati conditia ca etapa (Stage) sa fie modificata in Closed Won. Asa regula nu porneste la orice editare a deal-ului.
4. La Instant Actions, alegeti Function si selectati deal_won_follow_up. Apar doar functiile din categoria Automation.
5. Mapati argumentul: dealId = Deals > Deals Id, ca merge field.
6. Salvati regula.

Regula poate avea si alte actiuni instant in paralel. Documentatia Zoho spune ca alertele, sarcinile, webhook-urile, functiile si crearea de inregistrari ruleaza in paralel. Actualizarile de camp, etichetele si conversia ruleaza in secventa. Nu construiti deci o functie care se bazeaza pe o actualizare de camp din aceeasi regula facuta inaintea ei.

Ordinea automatizarilor conteaza si ea. Zoho executa regulile de atribuire, procesul de revizuire si regulile de scor inaintea regulii de workflow. Procesul de aprobare si Blueprint vin dupa ea. Daca folositi si Blueprint pe deal-uri, verificati ca cele doua nu fac aceeasi operatie de doua ori.

Erorile unei functii de workflow nu apar in fata utilizatorului. O exceptie netratata face ca functia sa esueze in tacere, iar eroarea se inregistreaza doar in logurile de executie. Le gasiti in Setup > Developer Hub > Functions, care are cinci tab-uri: Functions, Gallery, Analytics, Failures si Credits.

Unde cautati

• Failures listeaza executiile esuate; incepeti aici cand un deal castigat nu are sarcina.
• Logs, in vederea Glance a functiei, arata mesajele scrise cu info, inclusiv raspunsurile apelurilor catre CRM.
• Analytics poate intarzia pana la 15 minute; nu trageti concluzii dintr-un grafic gol imediat dupa test.
• Credits arata consumul de credite si este vizibil doar administratorilor organizatiei.

Capcane pe care le intalniti in practica

Crearea unei inregistrari din Deluge nu porneste implicit regulile de workflow. Documentatia pentru zoho.crm.createRecord precizeaza ca, fara parametrul de optiuni, se executa doar aprobarile, Blueprint-urile si orchestrarea. Sarcina creata de functie nu declanseaza deci regulile de workflow de pe Tasks decat daca le cereti explicit.

Fiecare apel de creare consuma un apel extern din limita planului. Un apel pus intr-o bucla care se repeta de cinci ori consuma cinci apeluri. In plus, declansatoarele de editare nu pornesc la fuzionarea automata a inregistrarilor, ci doar la fuzionarea manuala. Nu stergeti niciodata o functie asociata: stergerea strica regula care o foloseste.

Pentru o companie din Romania, prima intrebare este editia. Pe Standard si Professional, functiile se folosesc doar prin extensii. Multe firme ajung la ele prin extensii instalate pentru nevoi locale, cum ar fi verificarea CUI din ANAF in Zoho CRM. Codul propriu, legat de reguli de workflow, cere insa Enterprise, CRM Plus, Ultimate sau Zoho One.

A doua intrebare este ora de resetare a limitelor. Pagina de ajutor Zoho precizeaza ca limitele zilnice din workflow, de exemplu cea pentru emailuri, se calculeaza dupa ora PST. Ziua lor nu incepe deci la miezul noptii ora Romaniei. Creditele functiilor urmeaza, potrivit documentatiei pentru dezvoltatori, o fereastra mobila de 24 de ore. Daca rulati importuri mari dimineata, tineti cont de ambele.

A treia intrebare este ce automatizati. Un deal castigat declanseaza adesea si pasi financiari. Documentatia Zoho enumera printre motivele pentru o functie lucrul cu alta aplicatie Zoho, cum este Books. Daca facturarea ruleaza in alt sistem, o integrare SmartBill cu Zoho CRM poate prelua acea parte. Functia din workflow ramane astfel concentrata pe CRM.

Ultima intrebare este accesul. Doar utilizatorii cu permisiunea Manage Extensibility pot crea si modifica functii. Pastrati acest drept la o singura persoana sau echipa. Motivul este simplu: fiecare salvare ajunge direct in productie.

Pentru prima functie Deluge legata de o regula de workflow, urmati aceasta ordine:

1. Confirmati ca editia dumneavoastra ofera functii cu acces complet si ca aveti permisiunea Manage Extensibility.
2. Verificati daca o actiune standard, fara cod, rezolva cerinta.
3. Creati campurile personalizate si notati numele API exacte din Setup.
4. Scrieti functia in categoria Automation, cu argumentul declarat, si pastrati o copie a versiunii care functioneaza.
5. Testati manual de doua ori pe un deal de proba si cititi logurile.
6. Creati regula pe Deals, cu declansator la editare, conditia pe etapa si maparea dealId = Deals Id.
7. Urmariti tab-ul Failures in primele zile dupa lansare.

Daca doriti sa vedeti cum se integreaza astfel de automatizari intr-un proces complet de vanzari, pagina Zoho CRM in Romania, cu automatizarea vanzarilor descrie ce se poate configura si cum se leaga modulele intre ele.

• 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