Deluge-Funktion in einer Workflow-Regel von Zoho CRM einrichten und sicher testen

Eine Deluge-Funktion in einer Workflow-Regel von Zoho CRM richten Sie in drei Schritten ein. Sie schreiben die Funktion unter Setup > Developer Hub > Functions in der Kategorie Automation. Dabei deklarieren Sie ein Argument wie dealId. In der Regel wählen Sie die Funktion dann unter Instant Actions als Function aus und ordnen das Argument einem Merge-Feld zu. Vor dem Livegang testen Sie mit einem echten Test-Datensatz.

Deluge ist Zohos eigene Skriptsprache und laut Zoho die am tiefsten integrierte Sprache für Funktionen in Zoho CRM. Eine Workflow-Regel ist eine Reihe von Aktionen, etwa E-Mail-Benachrichtigungen, Aufgaben und Feldaktualisierungen. Diese Aktionen laufen, wenn festgelegte Bedingungen erfüllt sind. Eine Deluge-Funktion in einer Workflow-Regel ist also Code, den die Regel als zusätzliche Aktion startet, sobald ihre Bedingungen zutreffen.

Eine Funktion läuft in Zoho CRM nie von selbst. Sie braucht einen Auslöser, und die Verknüpfung mit dem Auslöser nehmen Sie in dessen Konfiguration vor, nicht im Funktionseditor. Der Code weiß deshalb nichts von der Regel, bis Sie ihn dort auswählen.

Dieser Beitrag gehört zu einer Reihe von drei Beiträgen über Automatisierung mit Code in Zoho CRM. Die anderen beiden behandeln das Client Script und die zeitgesteuerte Funktion. Hier geht es ausschließlich um die Funktion in der Workflow-Regel. Das Beispiel führt Sie vom Feld bis zum Protokoll durch alle Schritte.

Prüfen Sie zuerst, ob eine Standardaktion der Workflow-Regel die Anforderung erfüllt. Feldaktualisierung, Aufgabe, E-Mail-Benachrichtigung und Webhook brauchen keinen Code, den jemand pflegen muss. Eine Funktion lohnt sich erst für berechnete Werte, das Lesen anderer Datensätze, bedingte Logik oder mehrere Schritte auf einmal.

Die folgende Tabelle ordnet typische Anforderungen dem passenden Werkzeug zu:

Anforderung	Werkzeug	Wann es läuft
Feld setzen, Aufgabe anlegen, E-Mail senden, Daten an eine URL schicken	Standardaktion der Workflow-Regel	Wenn die Bedingungen der Regel zutreffen
Eingaben prüfen oder Felder im Formular steuern	Validierungsregel oder Client Script	In der Oberfläche, beim Bearbeiten
Nach dem Speichern rechnen, andere Datensätze lesen, mehrere Schritte	Deluge-Funktion in der Workflow-Regel	Asynchron nach dem Speichern, bis zu 30 Sekunden
Aktion relativ zu einem Datum, etwa vor Vertragsende	Workflow-Regel mit Datumsfeld als Auslöser	Bis zu 5000 Datensätze alle 10 Minuten
Viele Datensätze regelmäßig verarbeiten	Geplante Funktion	Stündlich, täglich, wöchentlich, monatlich oder frei, bis zu 15 Minuten

Client Scripts rufen Funktionen über das ZDK auf, das Zoho Developer Kit. Das ZDK ist die Brücke zwischen der Oberfläche und serverseitigen Funktionen. Wie Workflow-Regeln und Blueprint zusammen einen Prozess steuern, zeigt unser Beitrag zu Workflows und Blueprint in Zoho CRM.

Voller Zugriff auf Funktionen besteht in den Editionen Enterprise, CRM Plus, Ultimate und Zoho One. In Standard und Professional erreichen Sie Funktionen nur über Erweiterungen (Extensions). Wer eine eigene Funktion an eine Workflow-Regel hängen will, braucht also in der Regel eine der vier größeren Editionen. Einen Überblick über das Paket gibt unsere Seite zur Einführung von Zoho CRM Plus.

Berechtigung Manage Extensibility

Nur Nutzer mit der Berechtigung Manage Extensibility dürfen Funktionen anlegen und verwalten. Sie finden sie im Profil unter Developer Permissions (Entwicklerberechtigungen). Vergeben Sie diese Berechtigung nur an wenige Personen, denn jede Speicherung wirkt sofort im Livesystem.

Kategorie Automation

Die Kategorie einer Funktion bestimmt, mit welchen Auslösern Sie sie verbinden können. Eine Automation-Funktion lässt sich mit Workflow-Regeln, Blueprints und Genehmigungen verknüpfen, nicht aber mit benutzerdefinierten Schaltflächen oder Zeitplänen. Legen Sie die Funktion deshalb von Anfang an in der Kategorie Automation an.

Sprache und Argumente

Funktionen lassen sich in Deluge, Java, Node JS oder Python schreiben. Java, Node.js und Python erhalten den Kontext automatisch über basicIO, einen standardisierten Ein- und Ausgabemechanismus. In Deluge werden Argumente dagegen nicht automatisch übergeben. Sie deklarieren sie im Code und ordnen sie bei der Verknüpfung manuell CRM-Feldern zu. Pro Regel können Sie den Sofortaktionen genau eine benutzerdefinierte Funktion zuordnen.

Eine Workflow-Funktion darf laut Entwicklerdokumentation höchstens 30 Sekunden laufen und höchstens 200.000 Zeilen ausführen. Überschreitet sie die Zeitgrenze ihrer Kategorie, beendet Zoho sie zwangsweise. Dazu kommt ein tägliches Kontingent an Credits. Jede Ausführung einer Deluge-Funktion verbraucht einen Credit.

Die wichtigsten Grenzen im Überblick, jeweils nach der Entwicklerdokumentation zu Limits und Kontingenten:

Grenze	Wert	Was zählt
Laufzeit	30 Sekunden für Automation (Workflow, Blueprint, Approval)	Gesamte Ausführung, danach Abbruch
Ausgeführte Zeilen	200.000 pro Aufruf	Tatsächlich ausgeführte Zeilen, auch Schleifen und Unterfunktionen
Credits Enterprise und Zoho One	20.000 frei plus 500 je Nutzerlizenz plus Zukauf, höchstens 400.000	Eine Ausführung, ein Credit
Credits CRM Plus und Ultimate	20.000 frei plus 1.000 je Nutzerlizenz plus Zukauf	Obergrenze hängt von der Lizenzzahl ab, der Zoho-Support stellt sie ein
Credits Standard und Professional	5.000 frei plus 200 je Nutzerlizenz, höchstens 15.000 bzw. 20.000	Nur über Erweiterungen

Die 400.000 Credits bei Enterprise setzen sich aus 200.000 freien und 200.000 zugekauften Credits zusammen. Credits erneuern sich in einem gleitenden Fenster von 24 Stunden.

Die ältere Hilfeseite zu Workflow-Regeln nennt eine niedrigere Grenze: 20.000 Aufrufe pro Tag oder 200 je Nutzerlizenz, je nachdem, was niedriger ist. Die Seiten widersprechen sich also. Wir richten uns nach der Entwicklerdokumentation, weil sie das aktuelle Credit-Modell beschreibt. Den Verbrauch sehen Administratoren im Reiter Credits unter Developer Hub > Functions.

Das Beispiel dieses Leitfadens braucht drei benutzerdefinierte Felder. Wenn ein Deal in die Phase Closed Won wechselt, legt die Funktion eine Kick-off-Aufgabe für den Inhaber an. Sie summiert die gewonnenen Deals des Kontos, markiert das Konto als Kunde und setzt am Deal ein Kennzeichen. Dieses Kennzeichen sorgt dafür, dass alles nur einmal passiert.

Legen Sie diese Felder an, bevor Sie Code schreiben:

• Im Modul Deals ein Kontrollkästchen mit dem API-Namen Follow_Up_Created.
• Im Modul Accounts ein Währungsfeld mit dem API-Namen Won_Deals_Total.
• Im Modul Accounts ein Datumsfeld mit dem API-Namen Last_Won_Date.

Die Funktion nutzt außerdem Standardfelder wie Stage, Amount und Account_Type mit dem Wert Customer. Alle diese API-Namen sind Beispiele. Prüfen Sie die tatsächlichen Namen in Ihrer Organisation unter Setup in den Feldeinstellungen des jeweiligen Moduls. Das gilt auch für Phasennamen wie Closed Won, die in vielen Organisationen angepasst sind. Wie Sie Felder und Module von Anfang an sauber anlegen, beschreibt unsere Checkliste zum Einrichten von Zoho CRM.

Das Kennzeichenfeld macht die Funktion idempotent. Idempotent heißt: Eine Funktion kann beliebig oft für denselben Datensatz laufen und liefert dasselbe Ergebnis wie beim ersten Lauf. Speichert jemand den gewonnenen Deal später erneut, findet die Funktion das gesetzte Kennzeichen und bricht ab. So entsteht keine zweite Aufgabe.

Die Funktion deal_won_follow_up erledigt alle drei Schritte des Beispiels in einem Durchlauf. Öffnen Sie Setup > Developer Hub > Functions und legen Sie eine neue Funktion in der Kategorie Automation mit der Sprache Deluge an. Fügen Sie den folgenden Code vollständig in den Editor ein:

void automation.deal_won_follow_up(string dealId)
{
    deal = zoho.crm.v8.getRecordById("Deals", dealId.toLong());
    if(deal.get("id") == null)
    {
        info "Deal nicht gefunden: " + deal;
    }
    else if(deal.get("Follow_Up_Created") == true)
    {
        info "Bereits verarbeitet: " + dealId;
    }
    else
    {
        // 1. Aufgabe fuer den Deal-Inhaber, faellig in 3 Tagen, mit dem Deal verknuepft
        taskMap = Map();
        taskMap.put("Subject","Kick-off-Gespraech: " + 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. Gewonnene Deals beim Konto summieren
        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. Deal markieren, damit ein erneutes Speichern keine zweite Aufgabe erzeugt
        info zoho.crm.v8.updateRecord("Deals",dealId.toLong(),{"Follow_Up_Created":true});
    }
}

Das Argument dealId kommt als Text an, denn Merge-Variablen aus Workflow-Regeln übergeben Werte immer als Strings. Deshalb wandelt toLong() die ID vor jedem Aufruf in eine Zahl um. Anpassen müssen Sie vor allem die Feldnamen Follow_Up_Created, Won_Deals_Total und Last_Won_Date sowie den Phasennamen "Closed Won". Die Zahl in addDay(3) legt die Fälligkeit der Aufgabe fest. Den Betreff der Aufgabe können Sie frei formulieren.

Die info-Zeilen schreiben jede Antwort von Zoho ins Protokoll. Diese Zeilen sind Ihre einzige Sicht auf den Lauf, denn Workflow-Funktionen geben nichts an den Nutzer zurück.

Testen Sie die Funktion, bevor Sie sie mit einer Workflow-Regel verbinden. Deluge-Funktionen kennen keinen Entwurfsstand: Jede Speicherung im Editor aktualisiert sofort die Livefunktion. Hängt die Funktion schon an einer aktiven Regel, trifft jede Änderung unmittelbar echte Datensätze.

Gehen Sie für einen sicheren Test so vor:

1. Legen Sie ein Testkonto und einen Test-Deal in der Phase Closed Won an.
2. Führen Sie die Funktion im Editor mit der ID dieses Test-Deals als Wert für dealId aus.
3. Prüfen Sie Aufgabe, Kontosumme, Kontotyp und Kennzeichen am Test-Deal.
4. Führen Sie die Funktion ein zweites Mal aus. Das Protokoll muss jetzt „Bereits verarbeitet“ zeigen.
5. Testen Sie einen Deal ohne verknüpftes Konto, damit der Zweig mit der Null-Prüfung einmal läuft.

Ein Testlauf ist kein Probelauf. Die Funktion legt echte Aufgaben an und ändert echte Konten. Verwenden Sie deshalb nie einen Kundendatensatz. Wer eine Sandbox nutzt, kann Verbindungen beim Autorisieren auf die Zoho-CRM-Sandbox richten.

Beim Übertragen aus der Sandbox in die Produktivumgebung werden Tag-Zuordnungen nicht mitgenommen. Diese Zuordnungen müssen Sie danach von Hand setzen.

Klicken Sie in der Funktionsliste auf den Namen der Funktion, öffnet sich die Glance-Ansicht. Sie hat fünf Reiter: Overview, Analytics, Revisions, Logs und Failures. Unter Revisions sehen Sie die letzten 30 Versionen, die neueste zuerst. Damit können Sie nach einer missglückten Speicherung nachvollziehen, was sich geändert hat. Analysedaten können bis zu 15 Minuten verzögert erscheinen.

Die Workflow-Regel verbindet die getestete Funktion mit dem Wechsel in die Phase Closed Won. Öffnen Sie Setup > Automation > Workflow Rules und legen Sie im Modul Deals eine neue Regel an. Wählen Sie als Auslöser die Bearbeitung eines Datensatzes (Edit). Diesen Auslöser können Sie später nicht mehr ändern. Bei einem Fehler legen Sie die Regel also neu an.

Richten Sie die Regel in dieser Reihenfolge ein:

1. Auslöser: Edit im Modul Deals.
2. Bedingung: Stage wird auf Closed Won geändert.
3. Unter Instant Actions die Aktion Function wählen und deal_won_follow_up auswählen.
4. Argument zuordnen: dealId = Deals > Deals Id als Merge-Feld.
5. Regel speichern und mit einem weiteren Test-Deal prüfen.

Die Funktion läuft asynchron. Der Datensatz wird sofort gespeichert, ohne auf das Ende der Funktion zu warten. Der Vertriebsmitarbeiter sieht Aufgabe und Kontosumme deshalb erst mit kurzer Verzögerung. Einen Fehler bemerkt er gar nicht.

Die Reihenfolge der Automatisierung spielt ebenfalls eine Rolle. Zoho führt zuerst Zuweisungsregeln aus, danach unter anderem Scoring-Regeln, dann die Workflow-Regel, später Genehmigung und Blueprint. Der Inhaber eines Deals steht also fest, bevor die Funktion ihn für die Aufgabe liest. Innerhalb einer Regel laufen Funktion, Aufgabe, Webhook und Benachrichtigung parallel.

Feldaktualisierungen, Tags und Konvertierung laufen innerhalb einer Workflow-Regel dagegen nacheinander. Schritte, die aufeinander aufbauen, gehören deshalb in dieselbe Funktion.

Der häufigste Fehler in Workflow-Funktionen ist eine fehlende Null-Prüfung. Ein Deal ohne Konto liefert für Account_Name keinen Wert. Ohne die Prüfung if(account != null) scheitert der Aufruf account.get("id"). Dasselbe gilt für leere Beträge, die das Beispiel mit d.get("Amount") != null abfängt.

Bei Svennis prüfen wir vor jeder Freigabe, ob jede Funktion leere Nachschlagefelder abfängt und ein Kennzeichenfeld setzt. Genau diese beiden Stellen fehlen in bestehenden Kundensystemen am häufigsten.

Fehler bleiben für Nutzer unsichtbar

Ein unbehandelter Fehler in einer Workflow-Funktion scheitert aus Sicht des Nutzers still. Zoho vermerkt ihn nur in den Ausführungsprotokollen. Kontrollieren Sie deshalb nach dem Livegang regelmäßig den Reiter Failures unter Setup > Developer Hub > Functions. Fehlt bei createRecord ein Pflichtfeld, antwortet Zoho mit dem Code MANDATORY_NOT_FOUND. Die info-Zeilen machen diese Antwort im Protokoll sichtbar.

Limits und externe Aufrufe

Jede ausgeführte Integrationsaufgabe wie createRecord zählt als externer Aufruf. Steht sie in einer Schleife mit fünf Durchläufen, verbraucht sie fünf Aufrufe. Das Beispiel ruft deshalb in der Schleife nur Werte ab, die bereits geladen sind. Auch jeder Schleifendurchlauf zählt zu den 200.000 ausgeführten Zeilen. Die letzten beiden Parameter von getRelatedRecords, 1 und 200, steuern Seite und Anzahl der gelesenen Deals.

Folgeautomatisierung und gelöschte Funktionen

Ohne den Parameter options_map führt zoho.crm.createRecord nur Genehmigungen, Blueprints und Orchestrierung aus. Workflow-Regeln im Modul Tasks starten für die neue Aufgabe also nicht. Löschen Sie außerdem nie eine verknüpfte Funktion. Die zugehörigen CRM-Komponenten funktionieren danach nicht mehr.

Für Unternehmen im deutschsprachigen Raum sind vor allem Zeitzone, Edition und Dokumentation wichtig. Zoho berechnet Tageslimits wie das E-Mail-Limit von Workflow-Regeln nach PST, also nach pazifischer Zeit und nicht nach mitteleuropäischer Zeit. Ein Tageskontingent endet deshalb nicht um Mitternacht in Berlin, Wien oder Zürich. Funktions-Credits erneuern sich zusätzlich in einem gleitenden Fenster von 24 Stunden. Die Funktionsanalyse zeigt die Zeitzone Ihrer Organisation an.

Viele mittelständische Unternehmen starten mit Standard oder Professional. In diesen Editionen erreichen Sie Funktionen nur über Erweiterungen. Wer eigene Workflow-Funktionen plant, sollte die Edition deshalb vor dem Projekt klären, nicht danach. Eine Enterprise-Organisation mit 20 Nutzerlizenzen erhält zum Beispiel 20.000 plus 20 mal 500, also 30.000 freie Credits pro Tag.

Funktionen, die Daten an andere Systeme senden, gehören in Ihre interne Dokumentation der Datenflüsse. Verbindungen speichern OAuth2-Token oder API-Schlüssel innerhalb von Zoho CRM. Deluge setzt die nötigen Autorisierungsköpfe dann automatisch. Halten Sie fest, welche Funktion welche Verbindung nutzt und wer Zugriff auf die Berechtigung Manage Extensibility hat. Wie Sie Schnittstellen zu anderen Systemen planen, beschreibt unser Beitrag zur Zoho CRM API Anbindung.

Planen Sie außerdem, wer Fehler überwacht. Weil Workflow-Funktionen still scheitern, braucht der Reiter Failures eine feste Zuständigkeit. Diese Zuständigkeit gehört in dieselbe Betriebsdokumentation wie Rechte und Verbindungen.

Beginnen Sie mit einer einzigen, klar begrenzten Workflow-Funktion wie dem Beispiel dieses Leitfadens. Prüfen Sie vorher, ob eine Standardaktion der Workflow-Regel die Aufgabe nicht schon erfüllt. Erst wenn Sie rechnen, andere Datensätze lesen oder mehrere Schritte verbinden müssen, schreiben Sie Code.

Diese Punkte sollten vor dem Livegang erledigt sein:

• Edition geklärt: Enterprise, CRM Plus, Ultimate oder Zoho One für vollen Zugriff.
• Berechtigung Manage Extensibility nur für wenige Personen vergeben.
• Funktion in der Kategorie Automation angelegt, API-Namen in der eigenen Organisation geprüft.
• Null-Prüfungen für jedes Nachschlagefeld und jeden Betrag eingebaut.
• Kennzeichenfeld gesetzt, zweiter Testlauf zeigt „Bereits verarbeitet“.
• Laufzeit unter 30 Sekunden, keine Integrationsaufgaben in Schleifen.
• Zuständigkeit für den Reiter Failures festgelegt.

Hängen mehrere Funktionen, Blueprints und Regeln zusammen, lohnt ein Blick auf das gesamte System statt auf die einzelne Regel. Wie wir Einführung und Automatisierung zusammen planen, beschreibt unsere Seite zur Implementierung von Zoho CRM. Wenn Sie gerade erst starten, helfen Ihnen die ersten Schritte mit Zoho CRM bei den Grundeinstellungen.

• 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