Schedules in Zoho CRM: functie Deluge la ora fixa, configurare si verificare

Tema Schedules in Zoho CRM: functie Deluge la ora fixa se rezuma la un singur mecanism. CRM-ul porneste singur o functie scrisa de dumneavoastra, la data si ora alese, o data sau recurent. Schedule-ul il creati in Setup > Automation > Schedules, unde alegeti o functie din categoria Schedule, data de start, ora si frecventa.

Un schedule este o actiune automata definita de utilizator, executata printr-o functie, fie la un moment anume, fie recurent. O functie este logica proprie scrisa in Deluge, limbajul de scripting al Zoho, sau in Java, pentru actiuni pe care configurarea standard nu le acopera. Documentatia Zoho spune clar ca o functie nu ruleaza singura. Trebuie asociata unui trigger, iar asocierea se face in configurarea trigger-ului, nu in editorul functiei.

Regula practica este simpla. Daca formularea cerintei suna a "in fiecare noapte", "in fiecare ora" sau "in fiecare luni", aveti nevoie de o functie programata. Daca suna a "cand se modifica o inregistrare", aveti nevoie de un workflow. Acest ghid construieste un exemplu complet: in fiecare dimineata lucratoare, fiecare proprietar al unui deal neatins de 14 zile primeste un singur task de urmarire.

Prima optiune de verificat este mereu cea fara cod. O regula de validare, un field update sau un task creat de o regula de workflow rezolva o mare parte din cerinte fara nicio linie de Deluge. Regulile de workflow sunt seturi de actiuni, precum notificari email, taskuri si actualizari de campuri, executate cand sunt indeplinite anumite conditii.

Codul intra in joc abia cand configurarea standard nu ajunge. Tabelul de mai jos arata cele trei variante cu cod si locul fiecareia, alaturi de varianta fara cod.

Mecanism	Cand ruleaza	Potrivit pentru
Regula fara cod (validare, field update, task)	La salvarea sau modificarea inregistrarii	Reguli simple pe o singura inregistrare
Client script	In formular, in browser	Validari si ajutor pentru utilizator in timp ce completeaza
Functie Deluge pe o regula de workflow	Dupa salvarea inregistrarii, asincron	Logica pe inregistrarea care tocmai s-a schimbat
Functie Deluge pe un schedule	La ora fixa sau recurent, fara eveniment	O rulare peste multe inregistrari sau o sincronizare

Diferenta de timp disponibil conteaza. Pagina Zoho despre limite da 30 de secunde functiilor de automatizare (Workflow, Blueprint, Approval) si 15 minute functiilor de tip Schedule. O functie pe workflow ruleaza asincron: inregistrarea se salveaza imediat, fara sa astepte functia. Varianta pe workflow este descrisa in ghidul despre functia Deluge intr-o regula de workflow Zoho CRM.

Un schedule merita efortul doar cand logica priveste mai multe inregistrari deodata sau depinde de calendar. Pentru un singur task per deal la 14 zile dupa ultima activitate nu aveti nevoie de cod. O regula de workflow bazata pe data, pe campul Last Activity Time, poate crea acel task.

Functia programata isi castiga locul in situatii precise. Acestea sunt cazurile in care o regula fara cod devine greu de controlat:

• o singura rulare care parcurge multe inregistrari, in loc de cate o actiune pe fiecare;
• logica valabila doar in zilele lucratoare, de exemplu fara taskuri create sambata sau duminica;
• evitarea taskurilor duplicate, cand un task deschis trebuie sa blocheze crearea altuia;
• calcule peste mai multe inregistrari, precum totaluri sau comparatii;
• sincronizari cu alte sisteme.

Ultimul caz este descris direct de centrul de ajutor Zoho. Schedules permit integrarea datelor din CRM cu site-ul sau intranetul companiei, cu aplicatii terte sau cu alte aplicatii Zoho. Daca cerinta dumneavoastra nu intra in niciuna dintre categoriile de mai sus, ramaneti la regula fara cod. Este mai usor de intretinut si o poate modifica si un administrator care nu scrie Deluge.

Schedules au limite stricte, iar paginile Zoho nu spun peste tot acelasi lucru. Functiile au acces complet pe editiile Enterprise, CRM Plus, Ultimate si Zoho One. Pe 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 decideti.

Limitele de verificat inainte de a scrie codul sunt urmatoarele:

• Permisiuni: configurarea schedule-urilor cere Manage Workflow, iar crearea functiilor cere Manage Extensibility.
• Numar: cel mult 10 schedule-uri per organizatie. Pagina pentru dezvoltatori spune "10 active", iar centrul de ajutor spune 10 indiferent daca sunt active sau inactive. Tratati limita ca pe 10 in total.
• Durata: pagina de limite si pagina despre triggeri dau 15 minute: "The execution time limit for Scheduled Functions is 15 minutes." O pagina mai veche pentru dezvoltatori mentioneaza 5 minute, deci proiectati functia sa termine mult mai repede.
• Linii executate: maximum 200.000 per rulare. Se numara liniile executate efectiv, inclusiv buclele, nu liniile din cod.
• Run Now: rularea manuala este permisa doar de doua ori pe zi.
• Configurare: data de start nu poate depasi un an de la data curenta, iar numele schedule-urilor trebuie sa fie unice.

La frecventa, paginile difera din nou. Pagina de configurare enumera Once, Daily, Weekly, Monthly si Yearly, iar pagina despre triggeri mentioneaza hourly, daily, weekly, monthly si intervale custom. Verificati ce ofera meniul din organizatia dumneavoastra.

Exemplul din acest ghid rezolva o problema frecventa de vanzari: deal-urile deschise care stau neatinse. In fiecare dimineata de luni pana vineri, functia cauta deal-urile deschise nemodificate de 14 zile. Proprietarul fiecarui deal primeste un task de urmarire, dar niciodata un al doilea cat timp primul este deschis.

Functia urmeaza principiul "intai citesti tot, apoi actionezi". Ordinea este importanta, pentru ca o functie care creeaza taskuri in timp ce inca citeste risca sa se incurce in propriile rezultate. Pasii sunt trei:

1. citeste taskurile deschise create anterior de acest job, recunoscute dupa prefixul din subiect;
2. citeste toate deal-urile deschise cu Modified_Time mai vechi de 14 zile;
3. creeaza un task doar pentru deal-urile care nu au deja unul deschis.

Pentru citire, functia foloseste COQL, prescurtarea de la CRM Object Query Language. COQL permite interogari in stil SQL, scrise cu numele API ale modulelor si campurilor. Cererea se trimite prin invokeurl, clientul HTTP din Deluge, catre adresa {api-domain}/crm/{version}/coql. Metoda este POST, chiar daca doar cititi, pentru ca interogarea se "posteaza" catre endpoint.

Pentru scriere, functia foloseste zoho.crm.createRecord, care creeaza taskul in modulul Tasks. Legatura dintre task si deal se face prin campul What_Id. Documentatia COQL precizeaza ca suportul pentru What_Id exista doar pentru Tasks, Calls si Events.

Functia de mai jos implementeaza cei trei pasi descrisi mai sus. O lipiti in editorul de functii din Zoho CRM, intr-o functie noua din categoria Schedule. Comentariile sunt traduse, iar logica, metodele si numele API sunt cele din codul de referinta.

void schedule.stale_deals_nudge()
{
    apiDomain = "https://www.zohoapis.eu";   // domeniul API al centrului de date
    crmConn = "crm_coql";                     // numele de legatura al conexiunii
    staleDays = 14;
    orgTimeZone = "Europe/Berlin";            // fusul orar, nume din baza TZ
    closedStages = "'Closed Won','Closed Lost'";
    taskPrefix = "Deal inactiv: ";
    // weekday(): 1 = duminica ... 7 = sambata
    dayNo = today.weekday();
    if(dayNo != 1 && dayNo != 7)
    {
        cutoff = now.subDay(staleDays).toString("yyyy-MM-dd'T'HH:mm:ssXXX",orgTimeZone);
        headers = Map();
        headers.put("Content-Type","application/json");
        // 1) deal-urile care au deja un task deschis creat de acest job
        openTaskDeals = Map();
        tBody = Map();
        tq = "select What_Id from Tasks where (Subject like '" + taskPrefix + "%'";
        tq = tq + " and Status != 'Completed') limit 0, 2000";
        tBody.put("select_query",tq);
        tResp = invokeurl
        [
            url :apiDomain + "/crm/v8/coql"
            type :POST
            body :tBody.toString()
            headers :headers
            connection :crmConn
        ];
        tRows = tResp.get("data");
        if(tRows != null)
        {
            for each t in tRows
            {
                if(t.get("What_Id") != null)
                {
                    openTaskDeals.put(t.get("What_Id").get("id").toString(),true);
                }
            }
        }
        // 2) citim intai toate deal-urile deschise inactive, apoi actionam
        stale = List();
        offsets = {0,200,400,600,800};
        for each off in offsets
        {
            q = "select id, Deal_Name, Stage, Owner, Modified_Time from Deals";
            q = q + " where ((Stage not in (" + closedStages + "))";
            q = q + " and (Modified_Time < '" + cutoff + "'))";
            q = q + " order by Modified_Time asc limit " + off + ", 200";
            qBody = Map();
            qBody.put("select_query",q);
            resp = invokeurl
            [
                url :apiDomain + "/crm/v8/coql"
                type :POST
                body :qBody.toString()
                headers :headers
                connection :crmConn
            ];
            rows = resp.get("data");
            if(rows == null || rows.size() == 0)
            {
                break;
            }
            stale.addAll(rows);
            if(resp.get("info").get("more_records") == false)
            {
                break;
            }
        }
        // 3) un task pentru proprietarul fiecarui deal inactiv care nu are deja unul
        created = 0;
        for each d in stale
        {
            dealId = d.get("id").toString();
            if(!openTaskDeals.containKey(dealId))
            {
                task = Map();
                task.put("Subject",taskPrefix + d.get("Deal_Name"));
                task.put("Owner",d.get("Owner").get("id"));
                task.put("Due_Date",today.toString("yyyy-MM-dd"));
                task.put("What_Id",dealId);
                task.put("$se_module","Deals");
                info zoho.crm.createRecord("Tasks",task);
                created = created + 1;
            }
        }
        info "deal-uri inactive: " + stale.size() + ", taskuri create: " + created;
    }
}

Primele linii contin tot ce veti ajusta. apiDomain este domeniul centrului de date UE; o organizatie pe alt centru de date foloseste domeniul API propriu. crmConn este numele de legatura al conexiunii create de dumneavoastra. staleDays stabileste pragul de inactivitate, iar orgTimeZone fusul orar dupa numele din baza TZ, de exemplu Europe/Bucharest pentru Romania.

Numele de campuri si de etape sunt exemple de verificat in propria organizatie, in Setup. Aici intra Deal_Name, Stage, Owner, Modified_Time, Due_Date, statusul Completed si etapele Closed Won si Closed Lost. Daca ati redenumit etapele de inchidere, actualizati closedStages. Pastrati acelasi taskPrefix pe toata durata de viata a job-ului, pentru ca dupa el functia recunoaste taskurile deschise.

Fiecare apel COQL din bucla consuma credite API, iar bucla le inmulteste. Documentatia Deluge spune explicit ca un invokeurl dintr-un for each care se repeta de cinci ori consuma cinci apeluri externe. Codul apare o singura data, dar costul apare la fiecare iteratie.

COQL pagineaza prin clauza LIMIT, scrisa ca LIMIT offset, limit: primul numar arata cate inregistrari se sar, al doilea cate se aduc. Valoarea implicita este 200, iar maximul este 2.000 de inregistrari per apel. Costul in credite creste cu marimea paginii:

Valoare LIMIT	Credite API per apel
1 - 200	1
201 - 1000	2
1001 - 2000	3

Functia din acest ghid citeste deal-urile in pagini de 200, cu offset 0, 200, 400, 600 si 800. Asta inseamna cel mult 1.000 de deal-uri per rulare si cel mult cinci apeluri de cate un credit. Bucla se opreste mai devreme cand nu mai vin randuri sau cand raspunsul raporteaza more_records fals. Daca aveti mai multe deal-uri inactive, adaugati valori in lista offsets. Paginarea COQL aduce cel mult 100.000 de inregistrari per criteriu; peste acest volum Zoho recomanda Bulk Read API.

Separat de creditele API, fiecare executie a unei functii Deluge consuma un credit din alocarea zilnica a editiei. Pe Enterprise si Zoho One alocarea este 20.000 gratuite plus 500 pentru fiecare licenta de utilizator, cu un maxim de 400.000 inclusiv creditele cumparate suplimentar.

Configurarea unui schedule urmeaza o ordine fixa, iar testul vine inaintea programarii. Pasii de mai jos folosesc etichetele in engleza, asa cum apar in Setup:

1. Conexiunea. Creati o conexiune OAuth Zoho cu numele de legatura crm_coql si scope-ul de citire pentru COQL. Daca interogarile cer si metadate de campuri, adaugati ZohoCRM.settings.fields.READ; fara el, Zoho returneaza eroarea OAUTH_SCOPE_MISMATCH.
2. Functia. Creati o functie noua din categoria Schedule si lipiti codul. Categoria conteaza: o functie de tip Automation nu poate fi asociata unui schedule.
3. Testul. Comentati linia cu zoho.crm.createRecord si rulati functia din editor. Mesajul info de la final arata cate deal-uri inactive a gasit.
4. Schedule-ul. Mergeti in Setup > Automation > Schedules, dati un nume unic, alegeti functia, data de start, ora 08:00 si frecventa Daily. Codul sare singur peste sambata si duminica, deci nu aveti nevoie de o frecventa separata pentru zilele lucratoare.
5. Monitorizarea. In primele zile, urmariti tab-ul Failure al schedule-ului si consumul de credite.

La Svennis lasam linia createRecord comentata la primul test al oricarui schedule nou. Comparam numarul raportat de info cu o vizualizare filtrata din CRM, iar abia cand cele doua coincid activam scrierea. Pastrati una dintre cele doua rulari Run Now permise pe zi pentru verificarea de dupa activare.

Un schedule esuat nu va anunta singur, deci verificarea esecurilor trebuie sa fie o rutina. Zoho inregistreaza esecurile in doua locuri. Primul este tab-ul Failure din pagina de configurare Schedules, unde datele raman cat timp exista in Audit Log-ul CRM. Al doilea este tab-ul Failures din pagina Functions, unde functiile esuate apar cel mult 30 de zile.

Documentatia enumera cauzele tipice ale esecului unei functii:

• erori in codul functiei;
• parametri gresiti transmisi functiei;
• probleme de server, precum "Internal Server Error";
• timp de executie prea lung;
• erori ale unui API extern.

La functiile care apeleaza servicii externe mai exista o limita. Un invokeurl arunca eroarea "socket timeout" daca serviciul apelat raspunde in peste 40 de secunde.

Rerun-ul poate dubla actiunile

Un rerun foloseste valorile vechi, cele prezente in inregistrari la prima rulare. Daca alta automatizare a modificat intre timp inregistrarile, Zoho avertizeaza ca pot aparea actiuni duplicate. Cand aceeasi functie a esuat de mai multe ori, reparati intai codul si rulati din nou doar ultimul esec. Fiecare rerun consuma un apel din totalul editiei, iar Zoho accepta cel mult 100 de rerun-uri selectate deodata. Verificarea prefixului din functia de mai sus reduce riscul de taskuri duplicate, dar nu inlocuieste disciplina la rerun.

Pentru o companie din Romania, trei setari din cod cer atentie inainte de lansare. Prima este fusul orar: inlocuiti Europe/Berlin cu Europe/Bucharest, ca pragul de 14 zile sa fie calculat dupa ora locala. A doua este domeniul API, care trebuie sa corespunda centrului de date pe care este gazduita organizatia.

A treia setare priveste calendarul. Functia sare doar peste sambata si duminica, nu si peste sarbatorile legale. Daca echipa de vanzari nu lucreaza intr-o zi libera de lucru, taskurile vor aparea totusi in acea dimineata. Pentru un pipeline obisnuit, un task ramas deschis o zi nu este o problema, dar merita stiut dinainte.

Multe cerinte din Romania sunt, de fapt, sincronizari programate. Actualizarea zilnica a cursului BNR intr-un camp din CRM este un exemplu tipic de logica rulata la ora fixa. Inainte de a scrie un schedule, verificati daca o extensie existenta acopera deja nevoia. De exemplu, extensia ANAF pentru Zoho CRM preia datele firmei dupa CUI, iar integrarea SmartBill cu Zoho CRM acopera facturarea. Limita de 10 schedule-uri per organizatie face ca fiecare schedule scris inutil sa ocupe un loc de care veti avea nevoie mai tarziu.

Primul schedule se construieste cel mai sigur in ordinea din acest ghid. Pasii concreti pentru saptamana aceasta sunt urmatorii:

1. Verificati editia si permisiunile Manage Workflow si Manage Extensibility pe profilul care va configura schedule-ul.
2. Numarati schedule-urile existente in Setup > Automation > Schedules, ca sa stiti cate locuri din cele 10 mai aveti.
3. Confirmati in Setup numele API ale campurilor si etapelor folosite in cod.
4. Creati conexiunea, functia din categoria Schedule si rulati testul cu createRecord comentat.
5. Programati rularea zilnica la 08:00 si verificati tab-ul Failure in fiecare dimineata din prima saptamana.

Daca logica depinde de modificarea unei inregistrari, nu de ora, reveniti la ghidul despre functiile Deluge pe regulile de workflow. Pentru o imagine de ansamblu asupra automatizarilor posibile, consultati pagina Zoho CRM pentru companiile din Romania, unde gasiti si modalitatea de a discuta despre configurarea propriei organizatii.

• Custom Schedules, Zoho CRM Developer
• Schedules, Zoho CRM Online Help
• Functions - Triggers and Associations, Zoho CRM
• Functions - Platform Limits and Quotas, Zoho CRM
• Function Failure & Rerun, Zoho CRM
• Query (COQL) API Overview, Zoho CRM API V8
• Get Records through COQL Query, Zoho CRM API V8
• invokeURL task for API calls, Zoho Deluge