Règles de déclaration de tickets¶

Définition¶

Les règles de déclarations de tickets dans Canopsis permettent d'interagir avec des outils tiers de ticketing par l'intermédiaire de webhooks.
Ces règles sont très proches des webhooks présents dans la fonctionnalité de scénario.

Information

Le déclenchement de la déclaration de ticket ne peut se faire que manuellement via le bouton de déclaration de ticket.

Configuration¶

Paramètres généraux¶

Paramètre	Description
Activé	Si activé, la règle est prise en compte, sinon elle est ignorée
Emettre un déclencheur	Si activé, le déclencheur "declareticket" est émis
Nom	Nom de la règle, affiché dans l'interface de gestion des règles de déclaration de tickets
Nom du système	Nom du système de gestion de tickets

Différents webhooks de déclaration de tickets¶

Paramètre	Description
Methode	Méthode HTTP à utiliser.
URL	URL de la requête HTTP de l'outil de gestion de tickets.
Autoriser plusieurs URLs	Si cette option est activée alors le champ URL peut être multivalué. La chaine "URL" sera découpée en utilisant la "," comme séparateur
Paramètres de délai d'attente	Délai à attendre avec l'exécution de l'action.
Répéter la demande	Nombre de tentatives avant d'abandonner en cas de problème avec la requête.
Ne pas vérifier les certificats HTTPS	Si coché, la validité du certificat HTTPS n'est pas vérifiée et la requête est exécutée même si le serveur HTTP présente un certificat invalide.
Type d'authentification	Non nécessaire : Désactive l'authentification Avec identifiants : Active l'authentification avec login/mdp Avec Jeton : Propose une méthode pour exploiter un jeton d'authentification externe
Entêtes	Entêtes HTTP à ajouter à la requête.
Payload	Corps de la requête. Supporte les Templates GO.
URL et identifiant du ticket)	Si activé, permet de définir les valeurs du numéro de ticket retourné par l'outil de ticketing.
La valeur peut être une expression régulière	Permet d'appliquer une REGEX dans les champs ID du ticket et Champs personnalisés.
ID de ticket	Champ de réponse de l'API qui contient le numéro de ticket
URL du ticket	Champ de réponse de l'API qui contient l'URL du ticket
Les champs personnalisés	Champs de la réponse de l'API que vous souhaitez ajouter à l'alarme. La réponse doit être au format JSON. (exemple : `Nom du champ d'alarme` = `myprop`, `Champ de réponse` = `ticket.msg` et la réponse de l'api est `{"ticket":{"msg" : "Ticket message"}}` alors le champ `myprop` de l'alarme aura pour valeur `"Ticket message"`).
Si cette étape échoue	Décide de la suite des opération si le webhook échoue.
Ajouter un webhook	Permet d'ajouter un autre webhook.

Vérification du statut du ticket¶

Le paramètre Vérifier le statut du ticket est disponible uniquement lorsque la section URL et identifiant du ticket est activée dans le webhook.

Lorsqu'il est activé, Canopsis interroge périodiquement une API externe pour connaître le statut du ticket déclaré et le synchroniser dans l'alarme.

Paramètre	Description
Méthode	Méthode HTTP utilisée pour interroger l'API de statut.
URL	URL de l'API à interroger. Supporte les mêmes suggestions que les champs Webhooks.
Paramètres de délai d'attente	Durée et unité de la durée maximale d'attente avant d'abandonner la requête.
Répétition	Les paramètres de répétition sont configurés dans le fichier toml. En cas d'échec d'une requête de lecture de statut, elle est relancée selon ces paramètres.
Ignorer la vérification du certificat HTTPS	Si activé, la validité du certificat HTTPS n'est pas vérifiée.
Réutiliser les en-têtes et l'authentification de la règle de déclaration de ticket	Si activé, les en-têtes et l'authentification du webhook de déclaration sont réutilisés. Désactivé par défaut. Si désactivé, l'authentification et les en-têtes peuvent être configurés manuellement.
Authentification	Disponible uniquement si Réutiliser les en-têtes et l'authentification est désactivé. Modes disponibles : Non requise, Avec identifiants, Avec jeton.
En-têtes	En-têtes HTTP supplémentaires. Disponibles uniquement si Réutiliser les en-têtes et l'authentification est désactivé.
Payload	Corps de la requête. Supporte les Templates GO.
Champ source du statut du ticket	Champ de la réponse de l'API contenant le statut du ticket. L'option Autoriser les variables dans le champ source du statut du ticket permet d'utiliser les variables `.Response` et `.Header`.
Correspondance des statuts de ticket	Association entre les valeurs retournées par l'API externe et les statuts Canopsis. Au moins une valeur source doit être mappée vers la valeur Canopsis Fermé. Toutes les valeurs sources non mappées sont associées au statut Canopsis Inconnu.

Les valeurs Canopsis disponibles pour la correspondance sont :

Valeur	Description
Ouvert	Ticket ouvert dans le système externe.
Assigné	Ticket assigné.
En cours	Ticket en cours de traitement.
Fermé	Ticket fermé. Canopsis cesse d'interroger l'API dès réception de ce statut.

Comportement de la vérification

Le statut initial d'un ticket nouvellement créé est Ouvert, ou le statut reçu dans la réponse du webhook si celui-ci en retourne un.
Canopsis arrête d'interroger l'API dès réception d'un statut mappé à Fermé ou dès réception de tout statut de la part de l'API externe.
La durée maximale de vérification est configurée dans le fichier toml (limite absolue : 1 mois). Passé ce délai, si le ticket n'est pas fermé, son statut devient Inconnu.
Si une règle existante est mise à jour pour activer la vérification de statut, les tickets déjà déclarés avant cette modification ne seront pas vérifiés rétroactivement.

Exécuter un webhook sur plusieurs URLs¶

Grâce à l'option Autoriser plusieurs URLs, un même webhook peut contacter plusieurs URLs.
L'attribut "URL" est découpé en utilisant la virgule comme séparateur.

Prenons l'exemple concret de ces règles d'informations dynamiques à partir desquelles nous allons construire plusieurs URL

{
            "name": "Webhook URL 2",
            "author": "root",
            "description": "Test webhook multi url",
            "enabled": true,
            "infos": [
                {
                    "name": "type",
                    "value": "webhook"
                },
                {
                    "name": "webhookURL",
                    "value": "http://172.18.0.1:8080/URL2"
                }
            ],
            "disable_during_periods": [],
            "alarm_pattern": [
                [
                    {
                        "field": "v.component",
                        "cond": {
                            "type": "eq",
                            "value": "webhookmultiurl"
                        }
                    }
                ]
            ]
}

{
            "name": "Webhook URL 1",
            "author": "root",
            "description": "Test webhook multi url",
            "enabled": true,
            "infos": [
                {
                    "name": "type",
                    "value": "webhook"
                },
                {
                    "name": "webhookURL",
                    "value": "http://172.18.0.1:8080/URL1"
                }
            ],
            "disable_during_periods": [],
            "alarm_pattern": [
                [
                    {
                        "field": "v.component",
                        "cond": {
                            "type": "eq",
                            "value": "webhookmultiurl"
                        }
                    }
                ]
            ]
}

Nous souhaitons générer la chaine d'URL suivante : "http://172.18.0.1:8080/URL1,http://172.18.0.1:8080/URL2"
Pour cela, nous définissons le template suivant : "{{ range $link := .Alarm.Value.Infos }}{{ if (eq $link.type \"webhook\") }}{{ $link.webhookURL }},{{ end }}{{ end }}"

Modèle¶

Les règles de déclaration de tickets s'appliquent sur des alarmes qui respectent

Des modèles d'alarmes
Des modèles d'entités
Des modèles de comportements périodiques

Tester la requête¶

Vous avez la possibilité de tester vos règles de déclaration de tickets à partir d'une alarme existante.
Vous devez sélectionner ou indiquer l'identifiant court de l'alarme et cliquer sur "Excéuter le test".

Exploitation¶

Prenons l'exemple d'une règle de déclaration de tickets sur l'outil iTop.

Requête correspondante vers l'API

curl -H "Content-Type: application/json" -X POST -u root:root -d '{
"name": "Ticket iTop3",
"system_name": "iTop",
"enabled": true,
"emit_trigger": true,
"webhooks": [
  {
    "request": {
      "url": "https://itop/webservices/rest.php?version=1.3&login_mode=basic",
      "method": "POST",
      "auth": {
        "username": "admin",
        "password": "itop"
      },
      "headers": {
        "Content-Type": "application/x-www-form-urlencoded"
      },
      "payload": "json_data={\n              \"operation\":\"core/create\",\n              \"comment\":\"Alarm created by Canopsis\",\n              \"class\":\"UserRequest\",\n              \"output_fields\":\"id, friendlyname\",\n              \"fields\":\n              {\n                \"org_id\":\"SELECT Organization WHERE name = \\\"Demo\\\"\",\n                \"title\":\"Alarm on: {{ range .Alarms }}{{ .Value.Component }}{{ end }} {{ range .Alarms }}{{ .Value.Resource }}{{ end }}\",\n                \"description\":\"Message: {{ range .Alarms }}{{ .Value.State.Message }}{{ end }}<br><a href=http://localhost/alarms/{{ range .Alarms }}{{ .ID }}{{ end }} target=_blank>Alarm Link</a>\",\n                \"functionalcis_list\" : [{\"functionalci_id\":\"SELECT Server WHERE name=\\\"{{ range .Alarms }}{{ .Value.Component }}{{ end }}\\\"\"}]\n              }\n            }",
      "skip_verify": false,
      "timeout": null,
      "retry_count": 0,
      "retry_delay": null
    },
    "declare_ticket": {
      "empty_response": false,
      "is_regexp": true,
      "sys_id": "objects\\.UserRequest::.*\\.fields\\.id",
      "ticket_id": "objects\\.UserRequest::.*\\.fields\\.friendlyname",
      "ticket_url": ""
    },
    "stop_on_fail": false
  }
],
"author": {
  "_id": "root",
  "name": "root"
},
"created": 1678799414,
"updated": 1678806513,
"alarm_pattern": [
  [
    {
      "field": "v.component",
      "cond": {
        "type": "contain",
        "value": "Server"
      }
    }
  ]
]
}' 'http://localhost:8082/api/v4/cat/declare-ticket-rules'

Lorsqu'une demande de déclration de ticket sera effectuée par un utilisateur, le webhook défini sera exécuté.
Le numéro de ticket reçu dans le champ friendlyname sera associé à l'alarme dans Canopsis.
Le champ supplémentaire sys_id sera également inséré dans l'alarme; Il vaudra alors l'id renvoyée par l'API.

L'alarme suivante est éligible à la règle précédemment créée.

Déclarer un ticket¶

Pour déclarer un ticket, l'utilisateur peut exécuter l'action de manière unitaire ou en masse, puis sélectionner la règle de déclaration souhaitée.

Information

Une alarme peut être éligible à plusieurs règles de déclaration de tickets.
Dans ce cas, vous avez la possibilité de sélectionner les différentes règles.

Option : Déclarer un seul ticket à partir de plusieurs alarmes

En cas de sélection multiples d'alarmes, vous avez la possibilité de demander la création d'un ticket par alarme ou un ticket commun pour toutes les alarmes.

Visualiser les informations du ticket¶

Lorsque vous dépliez une alarme, l'onglet Tickets Déclarés affiche les tickets actifs associés à l'alarme.

Les tickets supprimés (via l'action cancel assocticket) et les tentatives échouées ne sont pas affichés, à l'exception du dernier ticket si la dernière déclaration a échoué.

La colonne Statut affiche le statut synchronisé du ticket lorsque la vérification de statut est activée :

Statut	Description
Inconnu	Aucune synchronisation configurée, ticket associé manuellement, ou période de vérification expirée sans fermeture
Ouvert	Ticket ouvert dans le système externe
Assigné	Ticket assigné
En cours	Ticket en cours de traitement
Fermé	Ticket fermé

Note

Au survol du statut Inconnu après expiration de la période de vérification, une info-bulle affiche le dernier statut connu et la date de la dernière vérification.

Dans la timeline¶

Chaque changement de statut de ticket est enregistré dans la timeline de l'alarme avec l'événement Statut du ticket modifié.

Chaque entrée précise l'identifiant du ticket, le statut précédent et le nouveau statut.

Exemple : Ticket ID: mon-ticket. Previous status: Open. New status: In progress