Перейти до основного вмісту

Довідник скриптів

Цей документ надає вичерпний довідник для написання скриптів у правилах робочого процесу. Скрипти дозволяють реалізувати розширену логіку автоматизації за допомогою JavaScript.

Огляд​

Дія Run Script у правилах робочого процесу виконує JavaScript-код для автоматизації складних сценаріїв обробки тікетів. Скрипти виконуються в ізольованому середовищі з доступом до даних тікета, контексту повідомлення та допоміжних функцій.

Ключові можливості:

  • Читання та зміна властивостей тікета
  • Доступ до інформації про клієнта та власника
  • Робота з кастомними полями
  • Використання умовної логіки та циклів
  • 10-секундний таймаут виконання для безпеки

Об'єкт Ticket​

Об'єкт ticket є основним контекстом для ваших скриптів. Він надає доступ на читання та запис до даних тікета.

Властивості лише для читання​

// Базова інформація про тікет
ticket.id        // UUID рядок
ticket.subject   // Тема тікета

// Поточний статус (об'єкт)
ticket.status.id     // UUID статусу
ticket.status.code   // Код статусу (наприклад, "open", "closed")
ticket.status.name   // Відображувана назва статусу

// Поточний пріоритет (об'єкт)
ticket.priority.id   // UUID пріоритету
ticket.priority.name // Відображувана назва пріоритету

// Поточний відділ (об'єкт)
ticket.department.id   // UUID відділу
ticket.department.name // Відображувана назва відділу

// Призначений власник (об'єкт, може бути undefined)
ticket.owner.id        // UUID користувача
ticket.owner.email     // Email користувача
ticket.owner.firstname // Ім'я користувача
ticket.owner.lastname  // Прізвище користувача

// Інформація про клієнта (об'єкт)
ticket.customer.id        // UUID клієнта
ticket.customer.email     // Email клієнта
ticket.customer.firstname // Ім'я клієнта
ticket.customer.lastname  // Прізвище клієнта
ticket.customer.name      // Повне ім'я клієнта

// Папка та теги
ticket.folder // Поточна папка: "INBOX", "ASSIGNED", "SPAM", "ARCHIVE"
ticket.tags   // Масив рядків тегів

Властивості для запису​

Ви можете змінювати ці властивості прямим присвоєнням:

// Встановити статус за кодом або ID
ticket.status = "closed";
ticket.status = "550e8400-e29b-41d4-a716-446655440000";

// Встановити пріоритет за назвою або ID
ticket.priority = "High";
ticket.priority = "550e8400-e29b-41d4-a716-446655440001";

// Встановити відділ за назвою або ID
ticket.department = "Sales";
ticket.department = "550e8400-e29b-41d4-a716-446655440002";

// Встановити власника за email або ID
ticket.owner = "[email protected]";
ticket.owner = "550e8400-e29b-41d4-a716-446655440003";

// Встановити папку
ticket.folder = "ASSIGNED";
ticket.folder = "SPAM";
ticket.folder = "ARCHIVE";
ticket.folder = "INBOX";

// Встановити теги (замінює всі існуючі теги)
ticket.tags = ["urgent", "vip"];

Кастомні поля​

Кастомні поля можна читати та записувати, використовуючи їх код (не відображувану назву).

Читання кастомних полів​

// Доступ до значення кастомного поля напряму
var orderId = ticket.order_id;      // Текстове поле
var amount = ticket.order_amount;   // Числове поле
var isVip = ticket.is_vip;          // Логічне поле
var region = ticket.region;         // Поле вибору

Запис кастомних полів​

// Встановити текстове кастомне поле
ticket.order_id = "ORD-12345";

// Встановити числове кастомне поле
ticket.order_amount = 199.99;

// Встановити логічне кастомне поле
ticket.is_vip = true;

// Встановити поле вибору
ticket.category = "billing";

// Встановити поле дати (формат ISO 8601)
ticket.due_date = "2024-12-31T23:59:59Z";
ticket.due_date = "2024-12-31";

Об'єкт Message​

Об'єкт message доступний, коли правило запускається подією повідомлення (New Customer Reply, New Staff Reply тощо).

if (message) {
    message.id        // UUID повідомлення
    message.body_text // Вміст повідомлення (простий текст)
    message.body_html // Вміст повідомлення (HTML)
    message.createdAt // Мітка часу ISO 8601
}

Приклад:

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

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

Допоміжні функції​

getStatuses()​

Повертає масив усіх доступних статусів.

var statuses = getStatuses();
// Повертає: [{ id: "...", code: "open", name: "Open" }, ...]

// Знайти конкретний статус
for (var i = 0; i < statuses.length; i++) {
    if (statuses[i].code === "pending") {
        ticket.status = statuses[i].id;
        break;
    }
}

getPriorities()​

Повертає масив усіх доступних пріоритетів.

var priorities = getPriorities();
// Повертає: [{ id: "...", name: "Low" }, { id: "...", name: "High" }, ...]

getDepartments()​

Повертає масив усіх доступних відділів.

var departments = getDepartments();
// Повертає: [{ id: "...", name: "Support" }, { id: "...", name: "Sales" }, ...]

getUsers()​

Повертає масив усіх доступних користувачів (агентів).

var users = getUsers();
// Повертає: [{ id: "...", email: "[email protected]", firstname: "John", lastname: "Doe" }, ...]

fetch()​

Виконує HTTP-запити до зовнішніх API. Синхронний — повертає результат напряму.

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

Опції: method (GET/POST/PUT/DELETE), headers (об'єкт), body (рядок або об'єкт)

Приклад: Отримання з CRM та оновлення кастомних полів

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";
    }
}

Приклад: POST до webhook

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

Примітки: Тільки HTTPS, таймаут 5с, ліміт відповіді 1MB, внутрішні мережі заблоковані.

Поширені патерни​

Умовне присвоєння​

// Встановити пріоритет на основі теми
if (ticket.subject.toLowerCase().includes("urgent")) {
    ticket.priority = "High";
} else if (ticket.subject.toLowerCase().includes("question")) {
    ticket.priority = "Low";
}

Маршрутизація по відділах​

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";
}

Логіка на основі домену клієнта​

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

    // Обробка корпоративних клієнтів
    if (domain === "bigcorp.com" || domain === "enterprise.org") {
        ticket.priority = "High";
        ticket.department = "Enterprise Support";
        ticket.is_enterprise = true;
    }

    // Освітня установа
    if (domain.endsWith(".edu")) {
        ticket.segment = "education";
    }
}

Управління тегами​

// Додати теги без втрати існуючих
var existingTags = ticket.tags || [];
existingTags.push("processed");
existingTags.push("automated");
ticket.tags = existingTags;

Робота з повідомленнями​

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

    // Виявлення ключових слів розчарування
    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​

var users = getUsers();
if (users.length > 0) {
    // Простий round-robin на основі хешу ID тікета
    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;
}

Обробка помилок​

Скрипти виконуються в безпечному середовищі:

  • Синтаксичні помилки перехоплюються та логуються; скрипт пропускається.
  • Невалідні значення полів (наприклад, неіснуюча назва статусу) ігноруються.
  • Таймаути (10 секунд) запобігають нескінченним циклам.
  • Помилки не каскадуються на інші правила або компоненти системи.

Найкращі практики:

// Перевірте на null/undefined перед доступом до властивостей
if (ticket.customer && ticket.customer.email) {
    // Безпечно отримати ticket.customer.email
}

if (message) {
    // Безпечно отримати властивості message
}

// Використовуйте try-catch для складної логіки
try {
    var data = JSON.parse(ticket.custom_json);
    ticket.parsed_field = data.value;
} catch (e) {
    // Обробити помилку коректно
}

Обмеження​

  • Таймаут виконання: Скрипти завершуються після 10 секунд.
  • Немає доступу до файлової системи: Файлові операції недоступні.
  • Немає постійного стану: Змінні не зберігаються між виконаннями скриптів.
  • Поля лише для читання: ticket.id, ticket.subject, ticket.customer не можна змінювати.
  • ES5 JavaScript: Сучасні можливості JavaScript (arrow functions, const/let тощо) можуть бути недоступні.