Zum Hauptinhalt springen

Scripting-Referenz

Dieses Dokument bietet eine umfassende Referenz zum Schreiben von Skripten in Workflow-Regeln. Skripte ermöglichen es Ihnen, erweiterte Automatisierungslogik mit JavaScript zu implementieren.

Überblick​

Die Aktion Run Script in Workflow-Regeln führt JavaScript-Code aus, um komplexe Ticket-Verarbeitungsszenarien zu automatisieren. Skripte laufen in einer Sandbox-Umgebung mit Zugriff auf Ticket-Daten, Nachrichtenkontext und Hilfsfunktionen.

Hauptmerkmale:

  • Ticket-Eigenschaften lesen und ändern
  • Auf Kunden- und Besitzerinformationen zugreifen
  • Mit benutzerdefinierten Feldern arbeiten
  • Bedingte Logik und Schleifen verwenden
  • 10-Sekunden-Ausführungs-Timeout für Sicherheit

Ticket-Objekt​

Das ticket-Objekt ist der primäre Kontext für Ihre Skripte. Es bietet Lese- und Schreibzugriff auf Ticket-Daten.

Schreibgeschützte Eigenschaften​

// Grundlegende Ticket-Informationen
ticket.id        // UUID-String
ticket.subject   // Ticket-Betreffzeile

// Aktueller Status (Objekt)
ticket.status.id     // Status-UUID
ticket.status.code   // Statuscode (z.B. "open", "closed")
ticket.status.name   // Status-Anzeigename

// Aktuelle Priorität (Objekt)
ticket.priority.id   // Prioritäts-UUID
ticket.priority.name // Prioritäts-Anzeigename

// Aktuelle Abteilung (Objekt)
ticket.department.id   // Abteilungs-UUID
ticket.department.name // Abteilungs-Anzeigename

// Zugewiesener Besitzer (Objekt, kann undefiniert sein)
ticket.owner.id        // Benutzer-UUID
ticket.owner.email     // Benutzer-E-Mail
ticket.owner.firstname // Benutzer-Vorname
ticket.owner.lastname  // Benutzer-Nachname

// Kundeninformationen (Objekt)
ticket.customer.id        // Kunden-UUID
ticket.customer.email     // Kunden-E-Mail
ticket.customer.firstname // Kunden-Vorname
ticket.customer.lastname  // Kunden-Nachname
ticket.customer.name      // Kunden-Vollname

// Ordner und Tags
ticket.folder // Aktueller Ordner: "INBOX", "ASSIGNED", "SPAM", "ARCHIVE"
ticket.tags   // Array von Tag-Strings

Schreibbare Eigenschaften​

Sie können diese Eigenschaften durch direkte Zuweisung ändern:

// Status nach Code oder ID setzen
ticket.status = "closed";
ticket.status = "550e8400-e29b-41d4-a716-446655440000";

// Priorität nach Name oder ID setzen
ticket.priority = "High";
ticket.priority = "550e8400-e29b-41d4-a716-446655440001";

// Abteilung nach Name oder ID setzen
ticket.department = "Sales";
ticket.department = "550e8400-e29b-41d4-a716-446655440002";

// Besitzer nach E-Mail oder ID setzen
ticket.owner = "[email protected]";
ticket.owner = "550e8400-e29b-41d4-a716-446655440003";

// Ordner setzen
ticket.folder = "ASSIGNED";
ticket.folder = "SPAM";
ticket.folder = "ARCHIVE";
ticket.folder = "INBOX";

// Tags setzen (ersetzt alle vorhandenen Tags)
ticket.tags = ["urgent", "vip"];

Benutzerdefinierte Felder​

Benutzerdefinierte Felder können mit ihrem Code (nicht dem Anzeigenamen) gelesen und geschrieben werden.

Benutzerdefinierte Felder lesen​

// Auf benutzerdefinierten Feldwert direkt zugreifen
var orderId = ticket.order_id;      // Textfeld
var amount = ticket.order_amount;   // Zahlenfeld
var isVip = ticket.is_vip;          // Boolean-Feld
var region = ticket.region;         // Auswahlfeld

Benutzerdefinierte Felder schreiben​

// Text-Feld setzen
ticket.order_id = "ORD-12345";

// Zahlen-Feld setzen
ticket.order_amount = 199.99;

// Boolean-Feld setzen
ticket.is_vip = true;

// Auswahlfeld setzen
ticket.category = "billing";

// Datumsfeld setzen (ISO 8601-Format)
ticket.due_date = "2024-12-31T23:59:59Z";
ticket.due_date = "2024-12-31";

Message-Objekt​

Das message-Objekt ist verfügbar, wenn die Regel durch ein Nachrichtenereignis ausgelöst wird (Neue Kundenantwort, Neue Mitarbeiterantwort usw.).

if (message) {
    message.id        // Nachrichten-UUID
    message.body_text // Nachrichteninhalt (Klartext)
    message.body_html // Nachrichteninhalt (HTML)
    message.createdAt // ISO 8601-Zeitstempel
}

Beispiel:

if (message && message.body_text) {
    var bodyLower = message.body_text.toLowerCase();

    if (bodyLower.includes("cancel subscription")) {
        ticket.department = "Retention";
        ticket.priority = "High";
    }
}

Hilfsfunktionen​

getStatuses()​

Gibt ein Array aller verfügbaren Status zurück.

var statuses = getStatuses();
// Gibt zurück: [{ id: "...", code: "open", name: "Open" }, ...]

// Einen bestimmten Status finden
for (var i = 0; i < statuses.length; i++) {
    if (statuses[i].code === "pending") {
        ticket.status = statuses[i].id;
        break;
    }
}

getPriorities()​

Gibt ein Array aller verfügbaren Prioritäten zurück.

var priorities = getPriorities();
// Gibt zurück: [{ id: "...", name: "Low" }, { id: "...", name: "High" }, ...]

getDepartments()​

Gibt ein Array aller verfügbaren Abteilungen zurück.

var departments = getDepartments();
// Gibt zurück: [{ id: "...", name: "Support" }, { id: "...", name: "Sales" }, ...]

getUsers()​

Gibt ein Array aller verfügbaren Benutzer (Agenten) zurück.

var users = getUsers();
// Gibt zurück: [{ id: "...", email: "[email protected]", firstname: "John", lastname: "Doe" }, ...]

fetch()​

Führt HTTP-Anfragen an externe APIs aus. Synchron - gibt Ergebnis direkt zurück.

var response = fetch(url, options);
// response: { ok, status, statusText, text, json }

Optionen: method (GET/POST/PUT/DELETE), headers (Objekt), body (String oder Objekt)

Beispiel: Aus CRM abrufen und benutzerdefinierte Felder aktualisieren

var response = fetch("https://api.example.com/customers/" + ticket.customer.email, {
    headers: { "Authorization": "Bearer YOUR_API_KEY" }
});

if (response.ok && response.json) {
    ticket.customer_tier = response.json.tier;
    ticket.lifetime_value = response.json.lifetime_value;

    if (response.json.tier === "enterprise") {
        ticket.priority = "High";
    }
}

Beispiel: POST an Webhook

var response = fetch("https://hooks.example.com/helpdesk", {
    method: "POST",
    body: { ticket_id: ticket.id, customer_email: ticket.customer.email }
});

Hinweise: Nur HTTPS, 5s Timeout, 1MB Antwortlimit, interne Netzwerke blockiert.

Häufige Muster​

Bedingte Zuweisung​

// Priorität basierend auf Betreff setzen
if (ticket.subject.toLowerCase().includes("urgent")) {
    ticket.priority = "High";
} else if (ticket.subject.toLowerCase().includes("question")) {
    ticket.priority = "Low";
}

Abteilungs-Routing​

var subject = ticket.subject.toLowerCase();

if (subject.includes("billing") || subject.includes("payment") || subject.includes("invoice")) {
    ticket.department = "Billing";
} else if (subject.includes("technical") || subject.includes("bug") || subject.includes("error")) {
    ticket.department = "Technical Support";
} else if (subject.includes("sales") || subject.includes("pricing") || subject.includes("quote")) {
    ticket.department = "Sales";
}

Domain-basierte Logik für Kunden​

if (ticket.customer && ticket.customer.email) {
    var email = ticket.customer.email;
    var domain = email.split("@")[1];

    // Unternehmenskundenbehandlung
    if (domain === "bigcorp.com" || domain === "enterprise.org") {
        ticket.priority = "High";
        ticket.department = "Enterprise Support";
        ticket.is_enterprise = true;
    }

    // Bildungseinrichtung
    if (domain.endsWith(".edu")) {
        ticket.segment = "education";
    }
}

Tag-Verwaltung​

// Tags hinzufügen ohne vorhandene zu verlieren
var existingTags = ticket.tags || [];
existingTags.push("processed");
existingTags.push("automated");
ticket.tags = existingTags;

Arbeiten mit Nachrichten​

if (message && message.body_text) {
    var body = message.body_text.toLowerCase();

    // Frustrationsstichwörter erkennen
    var frustrationKeywords = ["frustrated", "angry", "terrible", "worst", "unacceptable"];
    for (var i = 0; i < frustrationKeywords.length; i++) {
        if (body.includes(frustrationKeywords[i])) {
            ticket.priority = "High";
            ticket.needs_attention = true;
            break;
        }
    }
}

Round-Robin-Zuweisung​

var users = getUsers();
if (users.length > 0) {
    // Einfaches Round-Robin basierend auf Ticket-ID-Hash
    var ticketHash = 0;
    for (var i = 0; i < ticket.id.length; i++) {
        ticketHash += ticket.id.charCodeAt(i);
    }
    var assigneeIndex = ticketHash % users.length;
    ticket.owner = users[assigneeIndex].email;
}

Fehlerbehandlung​

Skripte werden in einer sicheren Umgebung ausgeführt:

  • Syntaxfehler werden abgefangen und protokolliert; das Skript wird übersprungen.
  • Ungültige Feldwerte (z.B. nicht existierender Statusname) werden ignoriert.
  • Timeouts (10 Sekunden) verhindern Endlosschleifen.
  • Fehler kaskadieren nicht zu anderen Regeln oder Systemkomponenten.

Best Practices:

// Auf null/undefined prüfen, bevor auf Eigenschaften zugegriffen wird
if (ticket.customer && ticket.customer.email) {
    // Sicherer Zugriff auf ticket.customer.email
}

if (message) {
    // Sicherer Zugriff auf Nachrichteneigenschaften
}

// Try-catch für komplexe Logik verwenden
try {
    var data = JSON.parse(ticket.custom_json);
    ticket.parsed_field = data.value;
} catch (e) {
    // Fehler elegant behandeln
}

Einschränkungen​

  • Ausführungs-Timeout: Skripte werden nach 10 Sekunden beendet.
  • Kein Dateisystemzugriff: Dateioperationen sind nicht verfügbar.
  • Kein persistenter Zustand: Variablen bleiben nicht zwischen Skriptausführungen erhalten.
  • Schreibgeschützte Felder: ticket.id, ticket.subject, ticket.customer können nicht geändert werden.
  • ES5 JavaScript: Moderne JavaScript-Funktionen (Pfeilfunktionen, const/let usw.) sind möglicherweise nicht verfügbar.