Client Script in Zoho CRM: wann sinnvoll, mit Code für eine Rabattregel

Ein Client Script in Zoho CRM ist sinnvoll, wenn ein Mensch beim Ausfüllen sofort eine Rückmeldung braucht. Typische Fälle sind eine Prüfung, ein automatisch gefülltes Feld, ein Pflichtfeld abhängig von einem anderen Feld oder eine Warnung. Für eine Regel, die für jeden Datensatz immer gelten muss, ist ein Client Script dagegen das falsche Werkzeug. Wann es sinnvoll ist, zeigt dieser Leitfaden mit Code.

Dieser Beitrag gehört zu einer Reihe von drei Beiträgen über Automatisierung mit Code in Zoho CRM. Die übrigen zwei behandeln die Funktion an einer Workflow-Regel und den Zeitplan. Für alle drei gilt eine einfache Reihenfolge:

• Zuerst ohne Code: eine Validierungsregel, ein Workflow mit Feldaktualisierung oder Aufgabe, ein datumsbasierter Workflow.
• Client Script: sofortige Rückmeldung auf dem Bildschirm, während jemand tippt oder speichert.
• Funktion an einer Workflow-Regel: Logik, die auf dem Server für jeden gespeicherten Datensatz läuft, gleich woher er kommt.
• Zeitplan: Logik, die zu festen Zeiten läuft, ohne dass jemand einen Datensatz öffnet.

Wie Workflows ohne Code aufgebaut sind und wo Blueprint hinzukommt, beschreibt der Beitrag Workflows und Blueprint in Zoho CRM. Der Rest dieses Leitfadens geht tief in das Client Script: was es ist, wo es läuft, welche Grenzen es hat und wie Sie eine Rabattregel mit drei kurzen Skripten umsetzen.

Ein Client Script ist JavaScript-Code, der im Webbrowser des Anwenders läuft statt auf dem Server. So formuliert es Zoho in der Übersicht zum Client Script. Das Skript reagiert auf Ereignisse, also auf Aktionen des Anwenders wie das Laden einer Seite, das Verlassen eines Felds oder den Klick auf Save (Speichern).

Die Funktion steht in den Editionen Professional, Enterprise und Ultimate von Zoho CRM zur Verfügung. Das Profil, mit dem Sie Skripte anlegen, braucht aktivierte Developer Permissions (Entwicklerberechtigungen). Laut den FAQ unterstützt Client Script ausschließlich JavaScript, und zwar alle Kernfunktionen bis ES7, einschließlich asynchroner Funktionen.

Der Code greift über das Zoho Development Kit auf das CRM zu. Das Zoho Development Kit (ZDK) ist eine JavaScript-Bibliothek mit Client- und Web-Schnittstellen, mit der Sie Bedienoberflächen steuern und REST-API-Aufrufe auslösen. In den Beispielen dieses Beitrags kommen zwei Bereiche vor:

• ZDK.Page liest und steuert Felder auf der geöffneten Seite.
• ZDK.Client zeigt Meldungen und Dialoge an.

Ein Client Script wirkt auch über den Browser am Schreibtisch hinaus. Es funktioniert in den Zoho CRM Apps für iOS und Android. Außerdem läuft es automatisch in Zoho CRM Portalen und ist für neu angelegte Benutzertypen standardmäßig aktiviert.

Die Wahl des Werkzeugs hängt davon ab, ob eine Regel nur auf dem Bildschirm helfen oder für jeden Datensatz gelten soll. Die folgende Tabelle ordnet typische Anforderungen dem passenden Werkzeug zu. Sie ersetzt keine Prüfung im Einzelfall, verhindert aber die häufigsten Fehlgriffe.

Anforderung	Passendes Werkzeug	Grund
Wert beim Speichern auf Grenzen prüfen, ohne Programmierung	Validierungsregel	Ohne Code, mit Fehlermeldung oder Warnung, je Layout einstellbar
Feld nachträglich setzen oder Aufgabe anlegen	Workflow mit Feldaktualisierung oder Aufgabe	Läuft nach dem Speichern, ohne dass jemand eingreifen muss
Aktion zu einem Datum, etwa vor Vertragsende	Datumsbasierter Workflow	Zeitgesteuert, kein offener Datensatz nötig
Rückmeldung während der Eingabe, Pflichtfeld abhängig von einem anderen	Client Script	Reagiert sofort im Browser, vor dem Speichern
Regel, die auch für Import, API und Webformular gilt	Funktion an einer Workflow-Regel	Läuft auf dem Server, unabhängig vom Bildschirm
Regelmäßige Sammelaufgabe, etwa nachts	Zeitplan	Läuft zu festen Zeiten ohne Auslöser durch Anwender

Die Validierungsregel verdient einen genaueren Blick, weil sie viele Client Scripts überflüssig macht. Zohos Artikel zum Anlegen von Validierungsregeln zeigt, wie sich ein Rabatt bei Deals ohne Code auf 15 % begrenzen lässt. Als Voreinstellung wählen Sie Stop with error (Speichern wird verhindert) oder Allow by alert (Speichern nach Bestätigung). Die Warnoption führt Zoho schrittweise ein, sie fehlt daher womöglich noch in Ihrem Konto. Eine Regel erlaubt bis zu 10 Primärbedingungen mit je fünf Sekundärbedingungen.

Ein Client Script schützt nur die Seite, an der es hängt. Es ist weder eine Datenregel noch eine Sicherheitskontrolle. Datensätze, die per API, Import, Webformular, Massenaktualisierung oder Workflow entstehen oder geändert werden, laufen nie durch das Skript. Eine Rabattgrenze im Client Script hält also nur, solange jemand den Datensatz auf genau dieser Seite bearbeitet.

Auch die Validierungsregel hat eine Lücke, die Sie kennen sollten. Zoho schreibt: Wird ein Feld aus der Regel per Workflow-Regel, Blueprint, API, Import oder Webformular aktualisiert, hat diese Aktualisierung Vorrang. Datensätze aus Webformularen, die die Regelkriterien erfüllen, gehen in eine manuelle Freigabe. Eine Regel, die ausnahmslos gelten muss, gehört deshalb in eine Funktion auf dem Server. Wie Sie Schnittstellen dafür sauber planen, beschreibt der Beitrag zur Zoho CRM API Anbindung.

Für den Alltag heißt das: Das Client Script liefert Komfort und frühe Rückmeldung, die Serverlogik liefert Verlässlichkeit. Bei Svennis legen wir zu jedem Client Script, das eine Geschäftsregel auf dem Bildschirm durchsetzt, dieselbe Regel auch serverseitig an und testen zuerst die Wege am Skript vorbei, etwa Import und Inline-Bearbeitung. Wer Altdaten übernimmt, sollte diese Prüfung vor dem Import einplanen, wie im Beitrag Daten in Zoho CRM importieren beschrieben.

Ein Client Script hängt immer an einem Modul, einer Seite, einem Layout und einem Ereignis. Die Ereignisdokumentation nennt als Seiten Create, Clone, Edit, List (Standard), Detail (Standard), Detail (Canvas) sowie Create und Edit im Wizard. Die Anleitung zum Anlegen erwähnt nur Create, Clone und Edit. Maßgeblich ist die Ereignisdokumentation. Die Quick-Create-Seite unterstützt Client Script laut FAQ derzeit nicht.

Ereignisse auf Create-, Clone- und Edit-Seiten

• Seitenereignis onLoad: läuft beim Öffnen der Seite.
• Seitenereignis onChange: läuft bei Änderungen auf der Seite und eignet sich für mehrere Felder in einem Skript.
• Seitenereignis onSave: läuft nach dem Klick auf Save oder Save and New, aber bevor der Datensatz gespeichert ist. Ein return false verhindert das Speichern.
• Feldereignis onChange: läuft, wenn der Anwender das Feld verlässt. Es kann warnen, hält das Speichern aber nicht auf.

Die mobile Dokumentation nennt zusätzlich das Feldereignis onType, das schon beim Tippen auslöst. Dazu kommen Ereignisse für Unterformulare, Schaltflächen und Blueprint-Übergänge. Auf der Detailseite blockiert das Feldereignis onBeforeUpdate eine Inline-Bearbeitung, wenn das Skript false zurückgibt.

Ein Detail entscheidet über das spätere Beispiel. Auf Create-, Clone- und Edit-Seiten unterstützen Feldereignisse die Standardfelder Salutation, Adjustment und Discount nicht. Eine Rabattprüfung per Feldereignis braucht deshalb ein eigenes Rabattfeld.

Ein Client Script unterliegt festen Grenzen, die Zoho in Übersicht, FAQ und Best Practices dokumentiert. Die wichtigsten Zahlen:

• 10 Sekunden Laufzeit je Ausführung. Braucht ein API-Aufruf länger, bricht das Skript ab.
• Bis zu 30 Client Scripts je Seite.
• Bis zu 5 statische Ressourcen je Seite, also hochgeladene JavaScript-Dateien für gemeinsam genutzten Code.
• Ein Skript gilt nur für das bei der Einrichtung gewählte Layout. Jedes weitere Layout braucht eine eigene Kopie.

API-Verbrauch ist der zweite Punkt. Jede Ausführung einer ZDK-Web-API ruft intern die Zoho CRM API auf und zählt gegen das tägliche API-Limit. Die Beispiele in diesem Leitfaden nutzen nur Funktionen für Seite und Meldungen und keine ZDK-Web-API.

Einige Browserfunktionen fehlen vollständig. Die FAQ schließen unter anderem setTimeout, setInterval, addEventListener, WebSocket, window und document aus. Auch window.localStorage steht nicht zur Verfügung. Weitere Stolpersteine:

• setValue() funktioniert nicht in Feldern der Detailseite, weder Standard noch Canvas.
• Aufrufe externer Dienste gehen nur an Domains in der Liste Trusted Domains (vertrauenswürdige Domains).
• Die Löschen-Schaltfläche lässt sich deaktivieren, eine Prüfung vor dem Löschen ist aber nicht möglich.
• Eigene Ereignisse lassen sich nicht definieren, nur die von Zoho vorgesehenen.

Das durchgehende Beispiel lautet: Ein Deal mit mehr als 15 % Rabatt braucht eine Begründung. Drei Skripte teilen sich die Arbeit. Skript A stoppt das Speichern ohne Begründung, Skript B macht das Begründungsfeld sofort zur Pflicht, Skript C schließt die Lücke der Inline-Bearbeitung auf der Detailseite.

Legen Sie zuerst im Modul Deals zwei eigene Felder an:

1. Ein Zahlen- oder Prozentfeld für den Rabatt, hier mit dem API-Namen Discount_Percent.
2. Ein Textfeld für die Begründung, hier mit dem API-Namen Discount_Reason.

Diese API-Namen sind Beispiele. Zoho vergibt sie beim Anlegen selbst, prüfen Sie die tatsächlichen Namen in Ihrer Organisation unter Setup bei den Feldern des Moduls. Das Standardfeld Discount scheidet für Feldereignisse aus, wie im Abschnitt zu Seiten und Ereignissen beschrieben. Wie Sie Felder und Layouts insgesamt planen, steht in der Checkliste zum Einrichten von Zoho CRM.

Anschließend legen Sie die Skripte an. Der Weg führt über Setup, Developer Hub, Client Script und +New Script. Wählen Sie die Kategorie Module, dann das Modul Deals, die Seite, das Layout Standard und das Ereignis.

Alternativ klicken Sie auf einer Create-, Clone- oder Edit-Seite eines Deals auf Add Script, dann füllt Zoho die Seitenangaben vor. Skript A und Skript B brauchen Sie je einmal für Create, Edit und Clone, weil jede Seite ein eigenes Skript erhält.

Skript A läuft beim Seitenereignis onSave und verhindert, dass ein Deal mit mehr als 15 % Rabatt ohne Begründung gespeichert wird. Legen Sie es für die Seite Create im Layout Standard an, fügen Sie den Code in den Editor ein und wiederholen Sie das für Edit und Clone.

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('Ein Rabatt über 15 % braucht eine Begründung.');
    ZDK.Client.showAlert(
        'Dieser Deal hat ' + discount + ' % Rabatt. Bitte vor dem Speichern begründen.',
        'Begründung fehlt',
        'OK'
    );
    return false; // verhindert das Speichern des Datensatzes
}

Die ersten vier Zeilen lesen beide Felder. Number(...) || 0 macht aus einem leeren Rabattfeld eine Null, damit der Vergleich nicht scheitert. Die Bedingung prüft, ob der Rabatt über 15 liegt und die Begründung leer ist oder nur Leerzeichen enthält.

Trifft beides zu, markiert showError das Begründungsfeld mit einer Fehlermeldung. showAlert öffnet zusätzlich einen Dialog mit Text, Titel und Schaltflächenbeschriftung. Das abschließende return false stoppt das Speichern, genau wie es die Ereignisdokumentation für onSave vorsieht.

Anpassen müssen Sie drei Dinge: die beiden Feldnamen in den ersten Zeilen, den Schwellenwert 15 und die Meldungstexte. Ändert sich die Grenze, ändern Sie sie in allen Skripten und in der serverseitigen Regel zugleich.

Skript B macht das Begründungsfeld zur Pflicht, sobald der Anwender einen Rabatt über 15 % einträgt. Legen Sie es auf denselben Seiten wie Skript A an, diesmal als Feldereignis onChange auf Discount_Percent. Die Variable value enthält dabei den neuen Feldwert.

var reasonField = ZDK.Page.getField('Discount_Reason');
var needsReason = (Number(value) || 0) > 15;
reasonField.setMandatory(needsReason);
if (needsReason) {
    ZDK.Client.showMessage('Rabatte über 15 % brauchen eine Begründung.', { type: 'warning' });
}

setMandatory schaltet die Pflicht ein oder, bei kleinerem Rabatt, wieder aus. showMessage zeigt einen kurzen Warnhinweis. Weil ein Feldereignis das Speichern nicht aufhält, bleibt Skript A trotzdem nötig. Zoho empfiehlt bei mehreren Feldern auf einer Seite ein einziges Skript mit Seitenereignis onChange und Bedingungen statt vieler Einzelskripte.

Skript C schließt die Lücke auf der Detailseite. Dort kann jemand den Rabatt direkt im Feld ändern, ohne die Edit-Seite zu öffnen. Legen Sie das Skript für die Seite Detail (Standard) als Feldereignis onBeforeUpdate auf Discount_Percent an.

if ((Number(value) || 0) > 15) {
    ZDK.Client.showAlert(
        'Rabatte über 15 % brauchen eine Begründung. '
            + 'Bitte über Edit das Feld Discount Reason ausfüllen.',
        'Bitte die Edit-Seite nutzen',
        'OK'
    );
    return false; // verhindert das Speichern der Inline-Änderung
}

Das Skript verweist auf die Edit-Seite, statt die Begründung abzufragen, denn setValue() funktioniert auf der Detailseite nicht. Anpassen müssen Sie wieder Schwellenwert, Feldnamen und Texte.

Ein Client Script gehört erst nach einem geordneten Test in den Betrieb. Die folgende Reihenfolge deckt die typischen Fehler ab:

1. Im Editor mit Run testen. Achtung: CRM-Operationen, die das Skript im Testlauf auslöst, sind echt. Ausgaben von Log-Anweisungen erscheinen im Messages-Panel. Einzelne ZDK-Aufrufe probieren Sie im Terminal-Bereich aus.
2. Skript aktivieren. Die Übersicht unter Client Script zeigt je Skript Name, Größe, letzten Bearbeiter und Status (enabled oder disabled).
3. Als Anwender ohne Administratorrechte testen. Legen Sie einen Deal mit 20 % Rabatt an, einmal ohne und einmal mit Begründung. Wiederholen Sie das auf Edit und Clone.
4. Inline-Bearbeitung prüfen. Ändern Sie auf der Detailseite den Rabatt direkt auf über 15. Skript C muss die Änderung abweisen.
5. Wege am Skript vorbei prüfen. Ein Import oder eine Massenaktualisierung mit hohem Rabatt zeigt, ob die serverseitige Regel greift.

Stellen die Skripte in einer bestimmten Reihenfolge Anforderungen aneinander, lässt sich die Reihenfolge ändern. Das gilt laut Zoho nur innerhalb eines Ereignisses auf einer Seite eines Moduls. Kommt später ein neues Layout hinzu, kopieren Sie alle drei Skripte dorthin und wiederholen den Test.

Für Unternehmen in Deutschland, Österreich und der Schweiz ist vor allem die Sprache der Meldungen wichtig. Die Menüs in Setup tragen die englischen Bezeichnungen, die Texte in showError, showAlert und showMessage schreiben Sie dagegen selbst. Formulieren Sie sie so, wie Ihr Vertrieb spricht, und nennen Sie das Feld, das fehlt.

Mobile Anwender im Außendienst sehen dieselben Regeln. Client Script läuft in den Apps für iOS und Android, auf Create-, Edit- und Clone-Seiten mit onLoad, onChange und onSave. Testen Sie deshalb auch auf dem Telefon, bevor Sie eine Regel freigeben.

Wer ein Kundenportal betreibt, sollte ebenfalls prüfen. Client Script läuft automatisch in Portalen und ist für neue Benutzertypen standardmäßig aktiv. Eine interne Rabattwarnung darf dort nicht bei Kunden erscheinen.

Schließlich zur Edition: Client Script setzt Professional, Enterprise oder Ultimate voraus. Vor dem Bau sollten Sie daher klären, welche Edition Ihre Organisation nutzt und wer die Developer Permissions erhält. Einen Überblick über die ersten Einstellungen gibt der Beitrag Erste Schritte mit Zoho CRM.

Beginnen Sie mit einer Bestandsaufnahme, bevor Sie Code schreiben. Notieren Sie jede Regel, die Ihr Team heute im Kopf trägt, und ordnen Sie sie mit der Entscheidungstabelle zu. Was ohne Code geht, setzen Sie als Validierungsregel oder Workflow um.

Für die verbleibenden Fälle gehen Sie so vor:

1. Prüfen Sie Edition und Developer Permissions.
2. Legen Sie die benötigten eigenen Felder an und notieren Sie deren API-Namen.
3. Bauen Sie zuerst das onSave-Skript, dann die Komfortskripte für Feldereignisse und Detailseite.
4. Legen Sie für jede Regel, die immer gelten muss, zusätzlich eine serverseitige Prüfung an.
5. Testen Sie als normaler Anwender, am Telefon und über Import.

Wenn Sie die Automatisierung in Ihrem System gemeinsam planen möchten, finden Sie auf der Seite zur Zoho CRM Implementierung den Ablauf und die Kontaktmöglichkeit. Die Beiträge zur Funktion an einer Workflow-Regel und zum Zeitplan ergänzen diesen Leitfaden, sobald sie erschienen sind.

• Zoho CRM: Client Script - An Overview
• Zoho CRM: Creating a Client Script
• Zoho CRM: Client Script Events
• Zoho CRM: Client Script - FAQs
• Zoho CRM: Best Practices of Client Script
• Zoho CRM: Client Script for Mobile Apps
• Zoho CRM: Validation Rule