MailIntegration - Création d'incidents ou d'événements à partir de courriels

Table des matières

Articles reliés

Introduction

Le programme MailIntegration (ESI.Octopus.MailIntegrationApp.exe) permet de recevoir des courriels dans Octopus pour créer un nouvel incident, un événement ou pour mettre à jour une requête existante en y ajoutant une activité. Le programme doit être automatisé à partir du planificateur de tâche dans Windows. 

Pour créer des événements à partir d'un système de surveillance (System Center Operations Manager 2007, à titre d'exemple), veuillez consulter la section Création d'événements à partir de courriels.

Ce que vous devez savoir :
Pour utiliser le programme MailIntegration, vous devez avoir un compte de courriel dédié à Octopus et vous assurer que le protocole POP3 est activé sur votre serveur de messagerie électronique.

Important : 
À partir de la version 3.8, un nouveau paramètre doit être ajouté à la ligne de commande pour indiquer à MailIntegration dans quelle équipe il doit faire la mise à jour. Pour plus de détails, vous référer à la section Exécuter MailIntegration à partir d'une ligne de commande.

Description du fonctionnement

Lorsque le programme MailIntegration est exécuté, la boîte de courriel est lue pour vérifier si elle contient de nouveaux messages. Si c'est le cas, le programme va vérifier si le courriel est un nouvel incident, un événement ou un ajout d'activité à une requête existante. 

La méthode utilisée par Octopus pour reconnaître un courriel est la suivante : Octopus fait la lecture du sujet du courriel, s'il retrouve un numéro de requête dans le format attendu, il mettra cette requête à jour, sinon, il créera un nouvel incident/événement. 

Dans l'image plus bas, la première partie du sujet représente le format qu'Octopus recherche pour mettre une requête à jour :

  • Le type de communication entre crochets [ ].
  • Suivi parfois du nom de la BD ou du nom de l'équipe.
  • Le numéro de la requête.

Dans le cas d'un tout nouveau courriel, MailIntegration va créer un nouvel incident ou événement dans Octopus. Le sujet du courriel sera le sujet de l'incident/événement et le contenu du courriel sera la description. Dans le cas d'un incident, l’émetteur du courriel deviendra le demandeur/utilisateur. Si l'adresse de courriel de la personne qui envoie le message n'est pas dans Octopus, l'incident sera relié à un utilisateur fictif préalablement défini (Fallback user). 

Si le courriel concerne une requête déjà existante, une activité sera ajoutée à cette requête et contiendra le nom de la personne qui envoie le courriel, la date et l'heure de l'ajout de l'activité dans Octopus. 

Chaque courriel traité par MailIntegration sera ensuite supprimé.  Il s'agit du fonctionnement par défaut du protocole POP3 utilisé. Pour conserver une copie des courriels, vous aurez à configurer votre système d'une des manières suivantes, selon le produit de messagerie utilisé. Nous vous invitons à communiquer avec votre administrateur de messagerie pour pouvoir effectuer ces configurations.

  • Utiliser une liste de distribution qui copie les courriels dans la boite destinée à MailIntegration ainsi que dans une boite d'archive.
  • Configurer une règle de messagerie sur le serveur pour que le courriel soit envoyé dans une boite d'archive.
  • Configurer une règle de messagerie sur le serveur pour que le courriel soit aussi archivé dans un dossier à cet effet.

Veuillez noter qu'il n'est pas possible de créer une demande de service directement à partir du programme MailIntegration.

Prérequis

Compte courriel

Avoir un compte de courriel dédié à Octopus. Pour configurer le programme MailIntegration, vous devez avoir en main les informations suivantes :

  • L'adresse complète du compte.
  • Le nom de l'utilisateur du compte.
  • Le mot de passe du compte.
  • Le nom du serveur de courriel.

Protocole POP3

ATTENTION : la version d'Octopus Automne 2012 est un prérequis au mode sécurisé SSL.


Les seuls protocoles supportés par le programme MailIntegration sont POP3 et POP3 en mode sécurisé (SSL). Vous devez vous assurer que le protocole à utiliser est activé sur votre serveur de messagerie électronique.

Si vous désirez utiliser le mode POP3 en mode sécurisé (SSL), vous devez vous assurer que la machine qui exécute MailIntegration reconnaisse l'authenticité du certificat utilisé, soit par un certificat émis par une autorité de certification de confiance (trusted certificate authority), ou par l'installation locale du certificat auto-signé (self-signed) du serveur.

Test du protocole POP3

MailIntegration ne fonctionnera pas si le test du protocole ne fonctionne pas, vous trouverez les informations pour ce test sur la page MailIntegration - Tester la connexion POP3.

Utilisateur système

Vous avez besoin d'un compte utilisateur fictif pour qu'il soit associé à l'incident lorsqu'un message est envoyé via une adresse inconnue d'Octopus.

De plus, vous aurez besoin d'utiliser le compte système Octopus pour la configuration de la tâche planifiée Windows. Pour plus d'information à ce sujet, voir l'article Compte système Octopus.

Répertoire des pièces jointes

Avant d'utiliser le programme MailIntegration, vous devez avoir configuré le chemin du répertoire réseau qui contiendra les fichiers joints dans Octopus.
Menu Outils Options > section 3 - Options générales importantes > Répertoire réseau contenant les fichiers joints.

Création automatique d'un événement en cas de problème

Il est à noter qu'en cas de problème avec MailIntegration, Octopus va créer un événement avec les instructions à suivre pour régler le problème. Pour cette raison, avant d’utiliser le programme MailIntegration, nous vous conseillons de vous assurer que les membres de votre Centre de services soient abonnés à la notification Nouvel événement

  • Menu Fichier > Mes préférences de notifications... > Nouvel événement.
  • De plus, la permission Accéder au module de gestion des événements est aussi nécessaire.

Octopus vous affiche un contenu d’événement précis lorsqu'une erreur se produit avec un courriel.

Dans le cas où une panne est détectée, la gestion d’événement affiche une nouvelle entrée qui contient le courriel original bloquant l'application.
 

Voir en image


Ce courriel peut être consulté via l'onglet Fichiers joints.

Voir en image

MailIntegration agit de la même façon lorsqu'un événement déjà existant reçoit une activité supplémentaire.

Dans le cas où une panne d'infrastructure est détectée, Octopus va aussi créer un événement, mais cette fois-ci, il affiche plutôt un message en lien avec la raison de la panne.

Voir en image

Le fichier de configuration sera attaché (tout en retirant les mots de passes, si nécessaire) dans un fichier de format .XML.

Voir en image

Octopus continue d'alimenter cet événement en activités supplémentaires tant que le problème se produit.

Voir en image

De plus, lorsque le problème avec MailIntegration est résolu, Octopus procède alors à la fermeture automatique de l'événement.

Voir en image

Utilisation du programme MailIntegration

MailIntegration est un programme de type ligne de commande (DOS). Il est conçu ainsi pour être facile à automatiser (la section Automatiser la réception de courriels dans Octopus décrit comment automatiser l'exécution de MailIntegration). 

  • Le nom complet du programme MailIntegration est : ESI.Octopus.MailIntegrationApp.exe.
  • Il est situé dans le répertoire local d'Octopus (C:\Program Files\Octopus) ou dans (\%homepath%\AppData\Local\Octopus).
  • Exemple du répertoire où peut se situer Octopus :
    • Pour Windows 7 : C:\Users\slevesque\AppData\Local\Octopus
    • Pour Windows XP : C:\Documents and Settings\Slevesque\Local Settings\Application Data\Octopus

Paramètres

Il y a 6 paramètres disponibles, dont 4 obligatoires, pour exécuter MailIntegration :

Paramètres obligatoires

  • /Login
    • Nom d’utilisateur Octopus.
      • Ce compte sera utilisé pour créer les incidents, il sera donc visible dans l'historique. Il est préférable d'utiliser un compte dédié à ce programme. (Exemple : Mail Octopus).
  • /Password
    • Mot de passe de l'utilisateur Octopus.
  • /Team (à partir de la version 3.8 seulement)
    • ​Le numéro de l'équipe à mettre à jour. Par défaut, l'équipe TI est la 1.
  • /ConfigFilePath
    • Chemin vers le fichier de configuration.

La section suivante explique comment préparer le fichier de configuration (XML).

Paramètre facultatifs

  • /LogFilePath
    • Remplace l'emplacement du fichier de journalisation. Par défaut, le fichier se nomme MailIntegration.log et sera situé dans le répertoire d'Octopus. Si vous déplacez le fichier dans un autre répertoire que celui d'Octopus, assurez-vous que ce répertoire existe (le système ne peut créer le répertoire). De plus, le chemin doit contenir le nom du fichier.
      • Ex.:/LogFilePath:C:\LogFiles\JournalMAIL.log
  • /Debug
    • En cas de problème avec un courriel en particulier, notre Centre de services Octopus peut vous demander d’ajouter ce paramètre pour créer un Raw Message (message au format texte brut) à chaque courriel reçu et ainsi investiguer la cause du problème. Attention si vous activez ce paramètre, le répertoire d’Octopus contiendra beaucoup de fichiers RawMessage.txt et devra être nettoyé régulièrement.

Journal des opérations

Fichiers générés à l'exécution du programme MailIntegration :

  • MailIntegrationApp.log
    •  Journal des opérations (LOG) généré automatiquement chaque fois que le programme est exécuté.
  • RawMessage.txt
    • Contenu du courriel en format texte brut généré en cas de problème ou à la demande en ajoutant le paramètre /DEBUG.

Ces fichiers seront créés dans le même répertoire que l'exécutable ESI.Octopus.MailIntegrationApp.exe. De plus, ces fichiers peuvent vous êtes demandés lors de l'analyse d'un problème avec l'utilisation de MailIntegration.

Fichier de configuration (XML)

Le fichier de configuration est un fichier texte qui contient l'information sur le serveur de courriel, le nom d'usager et le mot de passe de la boîte de courriel (mailbox) à utiliser, ainsi que d'autres paramètres nécessaires au programme. Ce fichier utilise le format XML. La section suivante explique les 2 formats disponibles du fichier XML, un pour le POP3 et l'autre pour SSL.

Avertissement

Avant de commencer la création du fichier de configuration, prenez soin de ne pas briser le format de fichier en modifiant les étiquettes ou la structure de fichier. Un seul "/" ou "<" ou ">" manquant ou additionnel pourra rendre le fichier inutile. Assurez-vous que les valeurs spécifiées sont valides. Ne laissez pas d'espaces vides avant ou après les valeurs.

En cas d'erreur avec le fichier de configuration, le logiciel arrête de fonctionner. 

Les informations contenues dans le fichier peuvent être vues avec un logiciel comme Internet Exploreur et nous recommandons Notepad ou Notepad++ pour éditer le fichier. 

Les caractères accentués ne sont pas supportés dans un fichier XML. Vous devez remplacer le caractère accentué par le code HTML Entity.

Exemple : 

 

doit être remplacé par :



Pour connaître la correspondance d'un caractère en HTML Entity vous pouvez consulter le lien Tableau de correspondance.                                                   

Création d'incidents avec un fichier XML POP3

Vous devez utiliser l'exemple de fichier XML suivant et modifier seulement les sections en jaune. Ces balises sont expliquées dans la section suivante.

<?xml version="1.0" encoding="utf-8" ?> 
<mailIntegration>
  <messageProcessorTypeName>ESI.Octopus.MailIntegration.EndUserIncidentMailMessageProcessor, ESI.Octopus.MailIntegration</messageProcessorTypeName> 
  <server> 
    <gatewayTypeName>ESI.Octopus.MailIntegration.SidePopMailboxGateway, ESI.Octopus.MailIntegration</gatewayTypeName>
    <serverName>SERVER</serverName> 
    <port>110</port> 
    <useSsl>false</useSsl> 
    <userName>MAILBOX</userName> 
    <password>PASSWORD-CLEAR-TEXT</password> 
  </server> 
  <incidentFallbackSiteName>FALLBACK-SITE</incidentFallbackSiteName> 
  <incidentFallbackUserLogon>FALLBACK-USER</incidentFallbackUserLogon> 
  <incidentGroup>ASSIGNED_GROUP</incidentGroup> 
  <incidentSource>Courriel</incidentSource> 
  <ignoredAttachments></ignoredAttachments>
  <CreateNewRequests>True</CreateNewRequests>
  <IncludeRawMessageAsAttachment>True</IncludeRawMessageAsAttachment>
</mailIntegration>


Explication des balises

  • <ServerName>SERVER</ServerName>
    • Nom du serveur de courriel.
      • Remplacez SERVER avec le nom de votre serveur de courriel.
  • <UserName>MAILBOX</UserName>
    • Nom de l'utilisateur de la boîte de courriel.
      • Remplacez MAILBOX par le nom d'utilisateur avec lequel vous vous authentifiez. Habituellement, la portion domaine de l'adresse courriel publique n'est pas incluse.
        Par exemple, on indiquerait nouvelincident au lieu de nouvelincident@macompagnie.com.
  • <Password>PASSWORD-CLEAR-TEXT</Password>
    • Mot de passe du compte de courriel.
      • Remplacez PASSWORD-CLEAR-TEXT avec le mot de passe de ce compte.
  • <IncidentFallbackUserLogon>FALLBACK-USER</IncidentFallbackUserLogon>
    • Utilisateur fictif à utiliser dans le cas où l'adresse de courriel de la personne qui envoie le message n'existe pas dans Octopus.
      • Remplacez FALLBACK-USER par le nom d'utilisateur Windows de votre utilisateur bidon. Ceci doit être identique au nom enregistré dans le champ Nom d'utilisateur Windows dans Octopus. Si jamais un courriel est reçu d'une adresse courriel qui n'est pas reconnue par Octopus, le système va utiliser le compte indiqué dans cette balise pour les valeurs Demandeur et Utilisateur de l'incident.
  • <IncidentFallbackSiteName>FALLBACK-SITE</IncidentFallbackSiteName>
    • Cette balise est obligatoire seulement dans le cas où le champ site est obligatoire dans Octopus (Menu Outils > Options > section 3 - Options générales importantes > Gestion des champs obligatoires). 
      • Remplacez FALLBACK-SITE avec le nom d'un site qui existe dans Octopus. Quand le programme s'exécute, il cherche le nom d'utilisateur Octopus associé à l'adresse courriel de l'expéditeur. Si l'expéditeur n'est pas reconnu ou s'il n'a pas de site, le programme va utiliser le site indiqué dans cette balise. Lorsque le champ site n'est pas obligatoire dans Octopus, vous n'avez pas à modifier la balise.
  • <IncidentSource>INCIDENT_SOURCE</IncidentSource>
    • Indique la source de création de l'incident.
      • Laissez Courriel dans cette balise pour indiquer que l'incident a été créé à partir d'un courriel. Si vous voulez utiliser une autre source, assurez-vous de l'avoir configuré dans Octopus.
  • <IncidentGroup>ASSIGNED_GROUP</IncidentGroup>
    • Cette balise n'est pas obligatoire. Elle permet de mettre le nom d'un groupe différent à celui du centre de services lors de la création de l'incident. Cette option est habituellement utilisée lorsque vous recevez plus d'une adresse de courriel dans Octopus
      • Remplacez ASSIGNED_GROUP par le nom du groupe que vous voulez assigner lors de la réception d'un courriel à cette adresse. Pour utiliser le groupe Centre de services par défaut, vous n'avez pas besoin de modifier la balise, la ligne doit être enlevée du fichier XML.
  • <IgnoredAttachments></IgnoredAttachments>
    • Cette balise n'est pas obligatoire. Elle permet d'ignorer certaines pièces jointes à un courriel. Par exemple, un logo.
      • Inscrivez une liste de fichiers à ne pas joindre en pièce jointe, incluant l'extension du fichier, le tout séparés par des virgules.
  • <CreateNewRequests>True</CreateNewRequests>
    • Cette balise permet de contrôler si de nouveaux incidents doivent être créés à partir de courriel ne faisant pas référence à une requête déjà active.
    • Si la création de nouvelles requêtes est désactivée, le système répondra à l'utilisateur à partir du gabarit de courriel disponible dans le menu Outils > Options > section Autres messagesRetour automatique pour refus de création de requête par MailIntegration
  • <IncludeRawMessageAsAttachment>True</IncludeRawMessageAsAttachment>
    • Cette balise permet de contrôler si le courriel en format EML sera attaché à l'incident créé.

Lorsque les balises ont été modifiées avec vos informations, sauvegardez le fichier dans le répertoire d'Octopus avec l'extension de fichier .xml. Par exemple, Email-Integration.xml. Nous vous conseillons de garder une copie de ce fichier ailleurs que dans le répertoire d'Octopus, car en cas de réinstallation du programme, le fichier peut être écrasé.

Utilisation du mode POP3 SSL

Les sections en jaunes sont les sections additionnelles lorsque vous utilisez SSL. Ces nouvelles balises sont expliquées dans la section suivante.

<?xml version="1.0" encoding="utf-8" ?>
<mailIntegration>
  <messageProcessorTypeName>ESI.Octopus.MailIntegration.EndUserIncidentMailMessageProcessor, ESI.Octopus.MailIntegration</messageProcessorTypeName> 
  <server> 
    <gatewayTypeName>ESI.Octopus.MailIntegration.SidePopMailboxGateway, ESI.Octopus.MailIntegration</gatewayTypeName>
    <serverName>SERVER</serverName> 
    <port>995</port> 
    <useSsl>true</useSsl> 
    <userName>MAILBOX</userName> 
    <password>PASSWORD-CLEAR-TEXT</password> 
  </server> 
  <incidentFallbackSiteName>FALLBACK-SITE</incidentFallbackSiteName> 
  <incidentFallbackUserLogon>FALLBACK-USER</incidentFallbackUserLogon> 
  <incidentGroup>ASSIGNED_GROUP</incidentGroup> 
  <incidentSource>Courriel</incidentSource> 
  <ignoredAttachments></ignoredAttachments>
  <CreateNewRequests>True</CreateNewRequests>
  <IncludeRawMessageAsAttachment>True</IncludeRawMessageAsAttachment>
</mailIntegration>

Explication des balises supplémentaires

Veuillez vous référer à la section précédente pour la description des balises communes aux deux types de fichiers.

  • <UseSsl>true</UseSsl>
    • Lorsque cette balise est à TRUE, le système va utiliser le protocole SSL.
  • <Port>995</Port>
    • Indique le port à utiliser.

Création d'événement à partir de courriels

Ouvrir le fichier modèle suivant dans Notepad :

<?xml version="1.0" encoding="utf-8" ?>
<mailIntegration>
  <messageProcessorTypeName>ESI.Octopus.MailIntegration.EventMailMessageProcessor, ESI.Octopus.MailIntegration</messageProcessorTypeName>
  <server>
    <gatewayTypeName>ESI.Octopus.MailIntegration.SidePopMailboxGateway, ESI.Octopus.MailIntegration</gatewayTypeName>
    <serverName>SERVER</serverName>
    <port>110</port>
    <useSsl>false</useSsl>
    <userName>MAILBOX</userName>
    <password>PASSWORD-CLEAR-TEXT</password>
  </server>
  <group>GROUP</group>
  <assignee>ASSIGNEE</assignee>
</mailIntegration>

Vous devez modifier les sections en jaune. Ces balises sont expliquées dans la section suivante. Ensuite, sauvegardez le fichier dans le dossier Octopus avec l'extension de fichier .xml. Par exemple, integration-événements.xml.

Explication des balises

  • <ServerName>SERVER</ServerName>
    • Nom du serveur de courriel.
      • Remplacez SERVER avec le nom de votre serveur de courriel.
  • <UserName>MAILBOX</UserName>
    • Nom de l'utilisateur de la boîte de courriel.
      • Remplacez MAILBOX par le nom d'utilisateur avec lequel vous vous authentifiez. Habituellement, la portion domaine de l'adresse courriel publique n'est pas incluse. 
        Par exemple, on indiquerait nouvelincident au lieu de nouvelincident@macompagnie.com.

  • <Password>PASSWORD-CLEAR-TEXT</Password>
    • Mot de passe du compte de courriel.
      • Remplacez PASSWORD-CLEAR-TEXT avec le mot de passe de ce compte.
  • <Group>GROUP</Group>
    • Cette balise sert à choisir le groupe d'assignation pour les événements.
      • Remplacez GROUP avec le nom du groupe à qui assigner les événements.
  • <Assignee>ASSIGNEE</Assignee>
    • ​Cette balise permet d'assigner les événements directement à un intervenant dans le cas où une seule personne en fait le suivi.
      • Remplacez ASSIGNEE avec le nom d'utilisateur windows du technicien à qui assigner les événements. Cet élément peut être laissé vide (<assignee></assignee>).

Exécuter MailIntegration à partir d'une ligne de commande

ATTENTION : Avant de tester MailIntegrationApp, il est recommandé de tester la connexion POP3 de votre serveur en utilisant la procédure suivante : Tester la connection POP3.

Pour lancer l'exécutable MailIntegration, vous devez ouvrir une fenêtre d'invite de commande (DOS) et vous positionner dans le répertoire d'Octopus. Par la suite, vous devez entrer la ligne de commande suivante :

Avant 3.8 

ESI.Octopus.MailIntegrationApp.exe /login:system /password:octo /ConfigFilePath:C:\Program Files\Octopus\email-integration.xml

Après 3.8 

ESI.Octopus.MailIntegrationApp.exe /login:system /password:octo /team:1 /ConfigFilePath:C:\Program Files\Octopus\email-integration.xml


Pour tester MailIntegrationApp la première fois, suivez les étapes suivantes :

  1. Envoyez un courriel au compte dédié à Octopus
  2. Ouvrir une fenêtre command-line
  3. Positionnez-vous dans le répertoire d'Octopus
  4. Entrez la commande suivante en fournissant les valeurs correctes pour les 3 ou 4 paramètres et appuyez sur ENTER :
    ESI.Octopus.MailIntegrationApp.exe /Login:NomUsagerOctopus /Password:MotDePasse /ConfigFilePath: (chemin vers le fichier XML)
    
    OU 
    
    ESI.Octopus.MailIntegrationApp.exe /Login:NomUsagerOctopus /Password:MotDePasse /team:NuméroDeL'équipe /ConfigFilePath: (chemin vers le fichier XML)
    

    Le programme va démarrer pour quelques secondes et va ensuite terminer.

  5. Entrez dans Octopus et ouvrez la liste des incidents Nouveaux pour voir le nouvel incident ou nouvel événement.

Automatiser la réception de courriels dans Octopus

MailIntegration ne va pas surveiller la boite de courriel. Quand vous démarrez MailIntegration, il lit une fois la boite, crée les incidents, puis s'arrête. Par conséquent, vous aurez besoin d'automatiser l'exécution de MailIntegration pour surveiller la boite.

Pour automatiser la réception des courriels de manière récurrente, référez-vous à l'article Tâches planifiées Windows.

X
Aidez-nous à améliorer l’article








Aidez-nous à améliorer l’article