Aller au contenu principal

Reference de scripting

Ce document fournit une reference complete pour l'ecriture de scripts dans les regles de workflow. Les scripts vous permettent d'implementer une logique d'automatisation avancee en utilisant JavaScript.

Vue d'ensemble​

L'action Run Script dans les regles de workflow execute du code JavaScript pour automatiser des scenarios complexes de gestion de tickets. Les scripts s'executent dans un environnement isole avec acces aux donnees des tickets, au contexte des messages et aux fonctions d'aide.

Fonctionnalites cles :

  • Lire et modifier les proprietes des tickets
  • Acceder aux informations sur le client et le proprietaire
  • Travailler avec des champs personnalises
  • Utiliser la logique conditionnelle et les boucles
  • Timeout d'execution de 10 secondes pour la securite

Objet Ticket​

L'objet ticket est le contexte principal pour vos scripts. Il fournit un acces en lecture et en ecriture aux donnees des tickets.

Proprietes en lecture seule​

// Informations de base du ticket
ticket.id        // Chaine UUID
ticket.subject   // Ligne de sujet du ticket

// Statut actuel (objet)
ticket.status.id     // UUID du statut
ticket.status.code   // Code du statut (par ex., "open", "closed")
ticket.status.name   // Nom d'affichage du statut

// Priorite actuelle (objet)
ticket.priority.id   // UUID de la priorite
ticket.priority.name // Nom d'affichage de la priorite

// Departement actuel (objet)
ticket.department.id   // UUID du departement
ticket.department.name // Nom d'affichage du departement

// Proprietaire assigne (objet, peut etre undefined)
ticket.owner.id        // UUID de l'utilisateur
ticket.owner.email     // Email de l'utilisateur
ticket.owner.firstname // Prenom de l'utilisateur
ticket.owner.lastname  // Nom de l'utilisateur

// Informations client (objet)
ticket.customer.id        // UUID du client
ticket.customer.email     // Email du client
ticket.customer.firstname // Prenom du client
ticket.customer.lastname  // Nom du client
ticket.customer.name      // Nom complet du client

// Dossier et tags
ticket.folder // Dossier actuel : "INBOX", "ASSIGNED", "SPAM", "ARCHIVE"
ticket.tags   // Tableau de chaines de tags

Proprietes modifiables​

Vous pouvez modifier ces proprietes par affectation directe :

// Definir le statut par code ou ID
ticket.status = "closed";
ticket.status = "550e8400-e29b-41d4-a716-446655440000";

// Definir la priorite par nom ou ID
ticket.priority = "High";
ticket.priority = "550e8400-e29b-41d4-a716-446655440001";

// Definir le departement par nom ou ID
ticket.department = "Sales";
ticket.department = "550e8400-e29b-41d4-a716-446655440002";

// Definir le proprietaire par email ou ID
ticket.owner = "[email protected]";
ticket.owner = "550e8400-e29b-41d4-a716-446655440003";

// Definir le dossier
ticket.folder = "ASSIGNED";
ticket.folder = "SPAM";
ticket.folder = "ARCHIVE";
ticket.folder = "INBOX";

// Definir les tags (remplace tous les tags existants)
ticket.tags = ["urgent", "vip"];

Champs personnalises​

Les champs personnalises peuvent etre lus et ecrits en utilisant leur code (pas le nom d'affichage).

Lecture des champs personnalises​

// Acceder directement a la valeur du champ personnalise
var orderId = ticket.order_id;      // Champ texte
var amount = ticket.order_amount;   // Champ nombre
var isVip = ticket.is_vip;          // Champ booleen
var region = ticket.region;         // Champ selection

Ecriture des champs personnalises​

// Definir un champ personnalise texte
ticket.order_id = "ORD-12345";

// Definir un champ personnalise nombre
ticket.order_amount = 199.99;

// Definir un champ personnalise booleen
ticket.is_vip = true;

// Definir un champ personnalise selection
ticket.category = "billing";

// Definir un champ personnalise date (format ISO 8601)
ticket.due_date = "2024-12-31T23:59:59Z";
ticket.due_date = "2024-12-31";

Objet Message​

L'objet message est disponible lorsque la regle est declenchee par un evenement de message (New Customer Reply, New Staff Reply, etc.).

if (message) {
    message.id        // UUID du message
    message.body_text // Contenu du message (texte brut)
    message.body_html // Contenu du message (HTML)
    message.createdAt // Timestamp ISO 8601
}

Exemple :

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

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

Fonctions d'aide​

getStatuses()​

Retourne un tableau de tous les statuts disponibles.

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

// Trouver un statut specifique
for (var i = 0; i < statuses.length; i++) {
    if (statuses[i].code === "pending") {
        ticket.status = statuses[i].id;
        break;
    }
}

getPriorities()​

Retourne un tableau de toutes les priorites disponibles.

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

getDepartments()​

Retourne un tableau de tous les departements disponibles.

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

getUsers()​

Retourne un tableau de tous les utilisateurs disponibles (agents).

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

fetch()​

Effectue des requetes HTTP vers des API externes. Synchrone - retourne directement le resultat.

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

Options : method (GET/POST/PUT/DELETE), headers (objet), body (chaine ou objet)

Exemple : Recuperer depuis un CRM et mettre a jour les champs personnalises

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

Exemple : POST vers un webhook

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

Notes : HTTPS uniquement, timeout de 5s, limite de reponse de 1MB, reseaux internes bloques.

Modeles courants​

Affectation conditionnelle​

// Definir la priorite en fonction du sujet
if (ticket.subject.toLowerCase().includes("urgent")) {
    ticket.priority = "High";
} else if (ticket.subject.toLowerCase().includes("question")) {
    ticket.priority = "Low";
}

Routage par departement​

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

Logique basee sur le domaine client​

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

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

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

Gestion des tags​

// Ajouter des tags sans perdre les existants
var existingTags = ticket.tags || [];
existingTags.push("processed");
existingTags.push("automated");
ticket.tags = existingTags;

Travailler avec les messages​

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

    // Detecter les mots-cles de frustration
    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;
        }
    }
}

Affectation en round-robin​

var users = getUsers();
if (users.length > 0) {
    // Round-robin simple base sur le hash de l'ID du 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;
}

Gestion des erreurs​

Les scripts sont executes dans un environnement sur :

  • Les erreurs de syntaxe sont capturees et enregistrees ; le script est ignore.
  • Les valeurs de champ invalides (par ex., nom de statut inexistant) sont ignorees.
  • Les timeouts (10 secondes) empechent les boucles infinies.
  • Les erreurs ne se propagent pas aux autres regles ou composants systeme.

Meilleures pratiques :

// Verifier null/undefined avant d'acceder aux proprietes
if (ticket.customer && ticket.customer.email) {
    // Sur d'acceder a ticket.customer.email
}

if (message) {
    // Sur d'acceder aux proprietes du message
}

// Utiliser try-catch pour la logique complexe
try {
    var data = JSON.parse(ticket.custom_json);
    ticket.parsed_field = data.value;
} catch (e) {
    // Gerer l'erreur gracieusement
}

Limitations​

  • Timeout d'execution : Les scripts sont termines apres 10 secondes.
  • Pas d'acces au systeme de fichiers : Les operations sur fichiers ne sont pas disponibles.
  • Pas d'etat persistant : Les variables ne persistent pas entre les executions de script.
  • Champs en lecture seule : ticket.id, ticket.subject, ticket.customer ne peuvent pas etre modifies.
  • JavaScript ES5 : Les fonctionnalites JavaScript modernes (fonctions flechees, const/let, etc.) peuvent ne pas etre disponibles.