Schedules in Zoho CRM: Deluge-Funktionen zeitgesteuert ausführen und absichern

Mit Schedules in Zoho CRM können Sie Deluge-Funktionen zeitgesteuert ausführen: einmalig zu einem festen Zeitpunkt oder wiederkehrend, ohne dass ein Datensatz angelegt oder geändert werden muss. Sie legen den Zeitplan unter Setup > Automation > Schedules an und verknüpfen ihn mit einer Funktion der Kategorie Schedule. Das ist die Kurzantwort.

Ein Schedule ist laut Zoho eine automatisierte, benutzerdefinierte Aktion, die über eine Funktion zu einem bestimmten Zeitpunkt oder regelmäßig ausgeführt wird. Deluge ist Zohos Skriptsprache, in der Sie in Zoho CRM eigene Logik für Funktionen schreiben. Eine Funktion läuft nie von selbst. Sie braucht einen Auslöser, und die Verknüpfung erfolgt immer in der Konfiguration dieses Auslösers, nicht im Funktionseditor.

Dieser Leitfaden zeigt, wann ein Schedule die richtige Wahl ist und welche Limits gelten. Er führt außerdem durch ein vollständiges Beispiel: Jeden Werktag um 08:00 Uhr erhalten die Verantwortlichen ruhender Deals genau eine Aufgabe, nie eine zweite, solange die erste offen ist. Zum Schluss geht es um Fehlerbehandlung und darum, was das für ein Unternehmen in Deutschland bedeutet.

Prüfen Sie zuerst, ob eine Automatisierung ohne Code genügt. Eine Validierungsregel, eine Workflow-Regel mit Feldaktualisierung oder eine Workflow-Regel, die eine Aufgabe anlegt, deckt viele Fälle ab. Zoho beschreibt Workflow-Regeln als Aktionen wie E-Mail-Benachrichtigungen, Aufgaben und Feldaktualisierungen, die ausgeführt werden, wenn festgelegte Bedingungen erfüllt sind. Code lohnt sich erst, wenn diese Mittel nicht mehr reichen.

Für die drei Varianten mit Code hilft eine einfache Faustregel. Läuft etwas jede Nacht, jede Stunde oder jeden Montag, ist es ein Schedule. Passiert etwas, wenn sich ein Datensatz ändert, gehört es in eine Workflow-Regel. Soll das Formular reagieren, während jemand tippt, ist es ein Client Script.

Variante	Auslöser	Typischer Einsatz	Zeitlimit laut Zoho
Validierungsregel, Workflow ohne Code	Speichern oder Ändern eines Datensatzes	Pflichtwerte, Feldaktualisierung, einzelne Aufgabe	entfällt
Client Script	Aktion des Nutzers im Formular	Hinweise und Prüfungen direkt in der Oberfläche	nicht Gegenstand dieses Leitfadens
Funktion in einer Workflow-Regel	Ereignis an einem Datensatz	Logik für genau diesen Datensatz	30 Sekunden
Schedule	Uhrzeit oder Wiederholung	ein Lauf über viele Datensätze	15 Minuten

Wie Sie eine Funktion an ein Datensatzereignis hängen, zeigt unser Beitrag zur Deluge-Funktion in einer Workflow-Regel. Funktionen aus Workflow-Regeln laufen asynchron: Der Datensatz wird sofort gespeichert, ohne auf die Funktion zu warten. Wie Workflow-Regeln und Prozessabläufe zusammenspielen, erklärt der Beitrag zu Workflows und Blueprint in Zoho CRM. Den Client Script behandelt ein eigener Beitrag dieser Reihe.

Ein Schedule lohnt sich, wenn ein einziger Lauf viele Datensätze gemeinsam betrachten muss. Eine einzelne Erinnerung pro Deal lässt sich dagegen oft ohne Code über eine Workflow-Regel mit Aufgaben-Aktion abbilden. Prüfen Sie diesen Weg ehrlich, bevor Sie Code schreiben, denn eine Regel ohne Code ist leichter zu pflegen.

Ein Schedule verdient seinen Platz in diesen Fällen:

• Ein Lauf behandelt viele Datensätze auf einmal, etwa alle offenen Deals einer Kategorie.
• Die Logik soll nur an Werktagen greifen, nicht am Wochenende.
• Der Job muss doppelte Aufgaben vermeiden und dafür vorhandene Aufgaben prüfen.
• Sie brauchen Berechnungen über mehrere Datensätze, zum Beispiel mit den COQL-Funktionen SUM, AVG, COUNT, MIN oder MAX.
• Daten sollen regelmäßig mit anderen Systemen abgeglichen werden.

Den letzten Punkt nennt Zoho selbst: Schedules können CRM-Daten mit der eigenen Website oder dem Intranet, mit Drittanwendungen oder anderen Zoho-Apps verbinden. Für einen Abgleich mit einem ERP-System wie bei einer SAP-Anbindung an Zoho CRM ist ein Schedule daher ein naheliegender Baustein.

Grenzen, ab denen ein externer Job besser passt

Ein externer Job ist die bessere Wahl, wenn die Grenzen der Plattform erreicht sind. Ein Lauf darf höchstens 15 Minuten dauern, jede Organisation hat höchstens 10 Schedules. COQL liefert pro eindeutigem Kriterium höchstens 100.000 Datensätze über mehrere Aufrufe, darüber verweist Zoho auf die Bulk Read API. Wie Sie eine solche Anbindung von außen stabil planen, beschreibt der Beitrag zur Zoho CRM API Anbindung.

Schedules setzen eine Edition voraus, in der Funktionen voll verfügbar sind. Laut Zoho ist das bei Enterprise, CRM Plus, Ultimate und Zoho One der Fall. In Standard und Professional sind Funktionen nur über Erweiterungen zugänglich. Prüfen Sie die Verfügbarkeit von Schedules in Ihrer Edition deshalb, bevor Sie planen.

Zwei Berechtigungen sind nötig. Wer Schedules konfiguriert, braucht die Profilberechtigung Manage Workflow. Wer Funktionen anlegt und verwaltet, braucht Manage Extensibility unter den Developer Permissions (Entwicklerberechtigungen) im Profil. Außerdem gilt: Schedule-Namen dürfen nicht doppelt vorkommen, und das Startdatum darf höchstens ein Jahr in der Zukunft liegen.

Zohos eigene Seiten widersprechen sich bei einigen Limits. Die folgende Tabelle stellt die Entwicklerseite zu Custom Schedules dem Hilfe-Center-Artikel zu Schedules und den übrigen Entwicklerseiten gegenüber.

Limit	Entwicklerseite Custom Schedules	Hilfe-Center und weitere Entwicklerseiten
Laufzeit pro Lauf	5 Minuten	15 Minuten (auch Seiten zu Limits und Triggern)
Anzahl Schedules	10 aktive pro Organisation	10, egal ob aktiv oder inaktiv
Takt	Once, Daily, Weekly, Monthly, Yearly	Triggerseite: hourly, daily, weekly, monthly, custom
Ausführungszeilen	200.000	200.000
Manuell per Run Now	zweimal täglich	zweimal täglich

Die Entwicklerdokumentation zu Limits nennt 15 Minuten für Schedule-Funktionen. Planen Sie trotzdem mit Reserve und halten Sie Läufe deutlich kürzer. Zählen Sie auch inaktive Schedules gegen die Obergrenze von 10. Welche Taktung angeboten wird, sehen Sie verbindlich im Menü Frequency Ihrer eigenen Organisation.

Jeder Lauf einer Deluge-Funktion verbraucht einen Credit, und jede Edition hat ein tägliches Kontingent. Credits sind die Einheit, mit der Zoho die Ausführung von Funktionen begrenzt. Das Kontingent erneuert sich in einem rollierenden 24-Stunden-Fenster. Für Enterprise und Zoho One nennt Zoho 20.000 freie Credits plus 500 je Nutzerlizenz plus Zusatz-Credits, höchstens 400.000. Für CRM Plus und Ultimate sind es 20.000 plus 1.000 je Nutzerlizenz plus Zusatz-Credits.

Innerhalb der Funktion kosten Datenabrufe zusätzlich. Eine COQL-Abfrage mit LIMIT zwischen 1 und 200 kostet einen API-Credit, zwischen 201 und 1.000 zwei, zwischen 1.001 und 2.000 drei. COQL ist Zohos SQL-ähnliche Abfragesprache für CRM-Daten. Die Syntax lautet LIMIT offset, limit, also zuerst der Versatz, dann die Menge.

Schleifen vervielfachen Aufrufe. Die Deluge-Dokumentation zu invokeUrl nennt ein Beispiel: Steht der Aufruf in einer Schleife mit fünf Durchläufen, werden fünf externe Aufrufe verbraucht. Für die ganze Organisation gilt eine Tagesgrenze von 5.000.000 invokeUrl-Anfragen über alle Funktionen zusammen. Antwortet ein Dienst nicht innerhalb von 40 Sekunden, bricht invokeUrl mit einem Socket-Timeout ab.

200 oder 2.000 Datensätze pro Aufruf

Auch hier widersprechen sich Zohos Seiten. Die COQL-Übersicht erlaubt bis zu 2.000 Datensätze pro Aufruf mit LIMIT 0, 2000. Die Seite zum Abruf über COQL nennt höchstens 200 Datensätze und 50 Felder pro Aufruf. Das Beispiel in diesem Leitfaden liest Deals deshalb in Seiten zu 200. Das funktioniert unter beiden Angaben.

Das Beispiel findet jeden Werktag die offenen Deals, die seit 14 Tagen nicht geändert wurden, und gibt jedem Verantwortlichen genau eine Aufgabe. Hat ein Deal bereits eine offene Aufgabe aus diesem Job, entsteht keine zweite. Das Grundprinzip lautet: erst alles lesen, dann handeln. So arbeitet der Job mit einem festen Datenstand und nicht mit Datensätzen, die er gerade selbst verändert.

Verbindung für den COQL-Abruf

Der Code ruft die COQL-Schnittstelle über invokeUrl auf und braucht dafür eine Zoho-OAuth-Verbindung (Connection). Legen Sie diese mit dem Lese-Scope für COQL an und geben Sie ihr den Linknamen crm_coql. Wollen Sie Feld-Metadaten abrufen, verlangt Zoho zusätzlich den Scope ZohoCRM.settings.fields.READ, sonst erscheint der Fehler OAUTH_SCOPE_MISMATCH.

Feldnamen und Phasen, die Sie prüfen müssen

Die API-Namen im Code sind Beispiele. Deal_Name, Stage, Owner, Modified_Time und What_Id sowie die Phasennamen Closed Won und Closed Lost müssen Sie unter Setup in Ihrer eigenen Organisation prüfen. Gerade Phasennamen sind oft angepasst. Das Feld What_Id verknüpft eine Aufgabe mit einem Deal. Laut Zoho wird es in COQL nur für Tasks, Calls und Events unterstützt, was für diesen Job genügt.

Beachten Sie: Das Beispiel misst Ruhe am Feld Modified_Time, also an der letzten Änderung des Deals. Wollen Sie stattdessen die letzte Aktivität messen, tauschen Sie das Feld nach Prüfung des API-Namens aus. Grundlagen zu Datenmodell und Feldern finden Sie in unserer Checkliste zum Einrichten von Zoho CRM.

Der folgende Code ist die komplette Funktion. Fügen Sie ihn in eine neue Funktion der Kategorie Schedule ein. Er prüft den Wochentag, liest offene Aufgaben des Jobs, liest dann alle ruhenden Deals und legt erst am Ende die Aufgaben an.

void schedule.stale_deals_nudge()
{
    apiDomain = "https://www.zohoapis.eu";   // API-Domain Ihres Rechenzentrums
    crmConn = "crm_coql";                     // Linkname der Verbindung
    staleDays = 14;
    orgTimeZone = "Europe/Berlin";            // Zeitzone, Name aus der TZ-Datenbank
    closedStages = "'Closed Won','Closed Lost'";
    taskPrefix = "Deal ruht: ";
    // weekday(): 1 = Sonntag ... 7 = Samstag
    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) Deals, die schon eine offene Aufgabe aus diesem Job haben
        openTaskDeals = Map();
        tBody = Map();
        tQuery = "select What_Id from Tasks where (Subject like '" + taskPrefix + "%'";
        tQuery = tQuery + " and Status != 'Completed') limit 0, 2000";
        tBody.put("select_query",tQuery);
        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) erst alle ruhenden offenen Deals lesen, dann handeln
        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) eine Aufgabe je ruhendem Deal ohne offene Job-Aufgabe
        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 "ruhende Deals: " + stale.size() + ", neue Aufgaben: " + created;
    }
}

Die ersten sechs Zeilen sind Ihre Einstellungen. Die Variable apiDomain enthält die Domain Ihres Rechenzentrums, crmConn den Linknamen Ihrer Verbindung. Mit staleDays legen Sie fest, ab wie vielen Tagen ein Deal als ruhend gilt. Die Variable closedStages enthält die Namen Ihrer abgeschlossenen Phasen.

Der COQL-Vergleich mit not in erlaubt höchstens 100 Werte. Ändern Sie taskPrefix nur zusammen mit bereits offenen Aufgaben, denn der Job erkennt seine eigenen Aufgaben an diesem Betreff.

Die Liste offsets begrenzt den Lauf auf fünf Seiten zu 200, also höchstens 1.000 Deals. Brauchen Sie mehr, verlängern Sie die Liste und behalten die Laufzeit im Blick. Die Abfrage der offenen Aufgaben nutzt LIMIT 0, 2000. Gilt in Ihrer Organisation die Grenze von 200 Datensätzen pro Aufruf, können bei sehr vielen offenen Job-Aufgaben einzelne fehlen. Dann entstehen doppelte Aufgaben.

Richten Sie den Schedule in fünf Schritten ein und aktivieren Sie die schreibende Zeile erst nach einem sauberen Testlauf. So sehen Sie die Trefferzahl, bevor eine einzige Aufgabe entsteht.

1. Verbindung anlegen: eine Zoho-OAuth-Verbindung mit dem Lese-Scope für COQL und dem Linknamen crm_coql.
2. Funktion anlegen: eine neue Funktion der Kategorie Schedule mit dem Namen stale_deals_nudge. Die Kategorie entscheidet, mit welchen Auslösern eine Funktion verknüpft werden kann. Eine Automation-Funktion lässt sich laut Zoho nicht mit einem Schedule verbinden.
3. Ohne Schreibzugriff testen: Setzen Sie zwei Schrägstriche vor die Zeile mit zoho.crm.createRecord und führen Sie die Funktion aus. Die info-Ausgabe zeigt dann, wie viele Aufgaben der Job anlegen würde.
4. Schedule konfigurieren: unter Setup > Automation > Schedules einen eindeutigen Namen vergeben, die Funktion wählen, Startdatum, Uhrzeit 08:00 und Frequency Daily einstellen und ein Ende festlegen. Das Wochenende überspringt der Code selbst.
5. Schreibzeile aktivieren und beobachten: Entfernen Sie den Kommentar und prüfen Sie in den ersten Tagen den Failure-Tab und den Verbrauch an Credits.

Bei Svennis vergleichen wir die Trefferzahl aus dem Testlauf immer mit einer gefilterten Listenansicht der Deals im CRM, bevor wir die Schreibzeile freigeben. Weichen beide ab, liegt der Fehler fast immer bei einem Phasennamen oder einem API-Feldnamen und nicht in der Logik.

Nutzen Sie Run Now sparsam, denn Zoho erlaubt den manuellen Start nur zweimal täglich. Schnelle Korrekturen testen Sie besser direkt an der Funktion.

Fehlgeschlagene Schedule-Läufe finden Sie an zwei Stellen. Der Failure-Tab auf der Konfigurationsseite der Schedules zeigt sie, solange sie in den Audit-Logs des CRM stehen. Der Tab Failures auf der Seite Functions listet nicht ausgeführte Funktionen höchstens 30 Tage lang. Dort können Sie nach Ausführungsort und Programmiersprache filtern.

Zoho nennt diese Fehlerursachen:

• Fehler im Code der Funktion
• fehlerhafte Parameter, die an die Funktion übergeben wurden
• Serverprobleme wie „Internal Server Error“
• eine zu lange Ausführungszeit
• Fehler in der angebundenen Drittanbieter-API

Was ein Rerun tut

Ein Rerun startet die Funktion erneut, allerdings mit den alten Argumentwerten. Alte Werte sind laut Zoho die Werte, die beim ersten Lauf im Datensatz standen. Hat eine andere Automatisierung den Datensatz inzwischen verändert, können doppelte Aktionen entstehen. Jeder Rerun verbraucht einen Aufruf aus dem Kontingent Ihrer Edition. Bis zu 100 Fehler lassen sich auf einmal auswählen, das System führt sie aber nacheinander aus.

Beheben Sie zuerst die Ursache. Ein Rerun gegen einen unveränderten Code-Fehler oder eine gestörte Drittanbieter-API scheitert erneut. Der vorhandene Eintrag erhält dann nur neue Zeit und neuen Grund. Scheitert eine Funktion mehrfach, empfiehlt Zoho, den Code zu korrigieren und nur den letzten Fehler neu zu starten. Das Beispiel aus diesem Leitfaden mindert das Risiko, weil es vor jeder Aufgabe nach einer offenen Job-Aufgabe sucht.

Für eine Organisation im EU-Rechenzentrum lautet die API-Domain im Code https://www.zohoapis.eu. Liegt Ihre Organisation in einem anderen Rechenzentrum, hat dieses eine eigene API-Domain, die Sie in apiDomain eintragen. Stimmt die Domain nicht, schlägt schon der erste COQL-Aufruf fehl, und der Lauf erscheint im Failure-Tab.

Die Zeitzone steht im Code als Name aus der TZ-Datenbank, hier Europe/Berlin. Ein Name statt eines festen Versatzes ist robuster, wenn zwischen Sommer- und Winterzeit gewechselt wird. Prüfen Sie zusätzlich die Zeitzone Ihrer Organisation unter Setup, damit 08:00 Uhr im Schedule auch 08:00 Uhr am Standort bedeutet.

Der Code überspringt Samstag und Sonntag, gesetzliche Feiertage aber nicht. An einem Feiertag entstehen also Aufgaben, die erst am nächsten Arbeitstag jemand sieht. Wenn das stört, ergänzen Sie eine eigene Liste mit Feiertagsdaten und prüfen das heutige Datum dagegen. In Unternehmen mit Standorten in mehreren Bundesländern gehört diese Liste zu jedem Standort.

Lesen Sie mit dem Job nur die Felder, die er wirklich braucht. Das Beispiel fragt fünf Felder der Deals und ein Feld der Aufgaben ab, keine Kontaktdaten. Ist die Datenschutz-Funktion in einem Modul aktiviert, legt Zoho dort das Feld Data Processing Basis Details an. Beziehen Sie dieses Feld nur in Schedules ein, wenn Ihr Prozess es ausdrücklich verlangt.

Beginnen Sie mit einem kleinen, gut prüfbaren Job wie dem Beispiel dieses Leitfadens. Ein überschaubarer erster Schedule zeigt Ihnen Credits, Laufzeit und Fehlerbild, bevor Sie Abgleiche mit anderen Systemen planen.

Gehen Sie in dieser Reihenfolge vor:

1. Prüfen Sie Edition und Berechtigungen: Manage Workflow für Schedules, Manage Extensibility für Funktionen.
2. Klären Sie, ob eine Workflow-Regel ohne Code genügt. Wenn ja, bauen Sie diese und keinen Schedule.
3. Zählen Sie Ihre vorhandenen Schedules, aktive und inaktive, gegen die Obergrenze von 10.
4. Prüfen Sie Feldnamen und Phasennamen unter Setup und passen Sie die Einstellungen am Anfang des Codes an.
5. Testen Sie mit auskommentierter Schreibzeile und vergleichen Sie die Trefferzahl mit einer Listenansicht.
6. Beobachten Sie nach dem Start eine Woche lang den Failure-Tab und den Verbrauch an Credits.

Gehört eine Aktion eher an ein Datensatzereignis, lesen Sie den Beitrag zur Funktion in einer Workflow-Regel dieser Reihe. Wenn Sie mehrere Schedules, Workflow-Regeln und Anbindungen gemeinsam planen möchten, finden Sie auf unserer Seite zur Einführung von Zoho CRM den Ablauf unserer Projekte und den Weg zu einem ersten Gespräch.

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