Passa al contenuto principale

Riferimento per lo Scripting

Questo documento fornisce un riferimento completo per scrivere script nelle regole del flusso di lavoro. Gli script consentono di implementare una logica di automazione avanzata utilizzando JavaScript.

Panoramica​

L'azione Esegui Script nelle regole del flusso di lavoro esegue codice JavaScript per automatizzare scenari complessi di gestione dei ticket. Gli script vengono eseguiti in un ambiente isolato con accesso ai dati del ticket, al contesto del messaggio e alle funzioni helper.

Caratteristiche principali:

  • Leggere e modificare le proprieta del ticket
  • Accedere alle informazioni del cliente e del proprietario
  • Lavorare con campi personalizzati
  • Utilizzare logica condizionale e cicli
  • Timeout di esecuzione di 10 secondi per sicurezza

Oggetto Ticket​

L'oggetto ticket e il contesto principale per i tuoi script. Fornisce accesso in lettura e scrittura ai dati del ticket.

Proprieta di Sola Lettura​

// Informazioni di base sul ticket
ticket.id        // Stringa UUID
ticket.subject   // Oggetto del ticket

// Stato corrente (oggetto)
ticket.status.id     // UUID dello stato
ticket.status.code   // Codice dello stato (es. "open", "closed")
ticket.status.name   // Nome visualizzato dello stato

// Priorita corrente (oggetto)
ticket.priority.id   // UUID della priorita
ticket.priority.name // Nome visualizzato della priorita

// Reparto corrente (oggetto)
ticket.department.id   // UUID del reparto
ticket.department.name // Nome visualizzato del reparto

// Proprietario assegnato (oggetto, puo essere undefined)
ticket.owner.id        // UUID utente
ticket.owner.email     // Email utente
ticket.owner.firstname // Nome utente
ticket.owner.lastname  // Cognome utente

// Informazioni sul cliente (oggetto)
ticket.customer.id        // UUID cliente
ticket.customer.email     // Email cliente
ticket.customer.firstname // Nome cliente
ticket.customer.lastname  // Cognome cliente
ticket.customer.name      // Nome completo cliente

// Cartella e tag
ticket.folder // Cartella corrente: "INBOX", "ASSIGNED", "SPAM", "ARCHIVE"
ticket.tags   // Array di stringhe tag

Proprieta Modificabili​

E possibile modificare queste proprieta tramite assegnazione diretta:

// Imposta lo stato per codice o ID
ticket.status = "closed";
ticket.status = "550e8400-e29b-41d4-a716-446655440000";

// Imposta la priorita per nome o ID
ticket.priority = "High";
ticket.priority = "550e8400-e29b-41d4-a716-446655440001";

// Imposta il reparto per nome o ID
ticket.department = "Sales";
ticket.department = "550e8400-e29b-41d4-a716-446655440002";

// Imposta il proprietario per email o ID
ticket.owner = "[email protected]";
ticket.owner = "550e8400-e29b-41d4-a716-446655440003";

// Imposta la cartella
ticket.folder = "ASSIGNED";
ticket.folder = "SPAM";
ticket.folder = "ARCHIVE";
ticket.folder = "INBOX";

// Imposta i tag (sostituisce tutti i tag esistenti)
ticket.tags = ["urgent", "vip"];

Campi Personalizzati​

I campi personalizzati possono essere letti e scritti utilizzando il loro codice (non il nome visualizzato).

Lettura dei Campi Personalizzati​

// Accedi direttamente al valore del campo personalizzato
var orderId = ticket.order_id;      // Campo di testo
var amount = ticket.order_amount;   // Campo numerico
var isVip = ticket.is_vip;          // Campo booleano
var region = ticket.region;         // Campo di selezione

Scrittura dei Campi Personalizzati​

// Imposta campo personalizzato di testo
ticket.order_id = "ORD-12345";

// Imposta campo personalizzato numerico
ticket.order_amount = 199.99;

// Imposta campo personalizzato booleano
ticket.is_vip = true;

// Imposta campo personalizzato di selezione
ticket.category = "billing";

// Imposta campo personalizzato data (formato ISO 8601)
ticket.due_date = "2024-12-31T23:59:59Z";
ticket.due_date = "2024-12-31";

Oggetto Message​

L'oggetto message e disponibile quando la regola viene attivata da un evento messaggio (Nuova Risposta Cliente, Nuova Risposta Staff, ecc.).

if (message) {
    message.id        // UUID del messaggio
    message.body_text // Contenuto del messaggio (testo semplice)
    message.body_html // Contenuto del messaggio (HTML)
    message.createdAt // Timestamp ISO 8601
}

Esempio:

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

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

Funzioni Helper​

getStatuses()​

Restituisce un array di tutti gli stati disponibili.

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

// Trova uno stato specifico
for (var i = 0; i < statuses.length; i++) {
    if (statuses[i].code === "pending") {
        ticket.status = statuses[i].id;
        break;
    }
}

getPriorities()​

Restituisce un array di tutte le priorita disponibili.

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

getDepartments()​

Restituisce un array di tutti i reparti disponibili.

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

getUsers()​

Restituisce un array di tutti gli utenti disponibili (agenti).

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

fetch()​

Effettua richieste HTTP verso API esterne. Sincrono - restituisce il risultato direttamente.

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

Opzioni: method (GET/POST/PUT/DELETE), headers (oggetto), body (stringa o oggetto)

Esempio: Recuperare dati dal CRM e aggiornare campi personalizzati

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

Esempio: POST a webhook

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

Note: Solo HTTPS, timeout di 5s, limite di risposta di 1MB, reti interne bloccate.

Pattern Comuni​

Assegnazione Condizionale​

// Imposta la priorita in base all'oggetto
if (ticket.subject.toLowerCase().includes("urgent")) {
    ticket.priority = "High";
} else if (ticket.subject.toLowerCase().includes("question")) {
    ticket.priority = "Low";
}

Instradamento per Reparto​

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

Logica Basata sul Dominio del Cliente​

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

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

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

Gestione Tag​

// Aggiungi tag senza perdere quelli esistenti
var existingTags = ticket.tags || [];
existingTags.push("processed");
existingTags.push("automated");
ticket.tags = existingTags;

Lavorare con i Messaggi​

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

    // Rileva parole chiave di frustrazione
    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;
        }
    }
}

Assegnazione Round-Robin​

var users = getUsers();
if (users.length > 0) {
    // Round-robin semplice basato sull'hash dell'ID ticket
    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;
}

Gestione degli Errori​

Gli script vengono eseguiti in un ambiente sicuro:

  • Errori di sintassi vengono catturati e registrati; lo script viene saltato.
  • Valori di campo non validi (es. nome stato inesistente) vengono ignorati.
  • Timeout (10 secondi) prevengono cicli infiniti.
  • Gli errori non si propagano ad altre regole o componenti di sistema.

Best practice:

// Controlla null/undefined prima di accedere alle proprieta
if (ticket.customer && ticket.customer.email) {
    // Sicuro accedere a ticket.customer.email
}

if (message) {
    // Sicuro accedere alle proprieta del messaggio
}

// Usa try-catch per logica complessa
try {
    var data = JSON.parse(ticket.custom_json);
    ticket.parsed_field = data.value;
} catch (e) {
    // Gestisci l'errore in modo elegante
}

Limitazioni​

  • Timeout di esecuzione: Gli script vengono terminati dopo 10 secondi.
  • Nessun accesso al file system: Le operazioni sui file non sono disponibili.
  • Nessuno stato persistente: Le variabili non persistono tra le esecuzioni degli script.
  • Campi di sola lettura: ticket.id, ticket.subject, ticket.customer non possono essere modificati.
  • JavaScript ES5: Le funzionalita JavaScript moderne (arrow function, const/let, ecc.) potrebbero non essere disponibili.