EWSMailCapture

EWSMailCapture est un module de MaarchCapture permettant de récupérer les courriels d’un dossier de votre boîte mail Microsoft Exchange, via EWS.

Appel du module dans le batch

Il faut d’abord inclure la configuration du module dans le fichier de paramétrage général des batchs de MaarchCapture : config/Capture.xml.

En haut du fichier, inclure le module :

<?xml version="1.0" encoding="UTF-8"?>
<capture>
    <modules>
        <module name="EWSMailCapture" src="modules/EWSMailCapture/EWSMailCapture.php" type="class"/>
        <!-- ... autres modules -->
    </modules>
    <batches>
        <!-- ... définitions des processus ... -->
    </batches>
</capture>

Et l’appel concret dans un batch :

<batch name="MAARCH_MAIL_TO_MC" directory="/opt/maarch/MaarchCapture/files/" id="{batchname}-{timestamp}-{rand}" lock="0">
    <workflow name="MAARCH_MAIL_TO_MC" debug="true" logMode="Maarch" maarchLogParam="/var/www/html/MaarchCourrier/apps/maarch_entreprise/xml/log4php.xml" maarchLoggerName="loggerTechnique">
        <step function="CaptureMails" module="EWSMailCapture" name="CAPTURE_MAIL_1">
            <!-- nom du compte dans EWSMailCapture -->
            <input name="account">account_1</input>

            <!-- action à effectuer sur les courriels traités : move (déplacer), delete (supprimer), ou none (aucune action) -->
            <input name="action">move</input>

            <!-- nom du fichier de configuration dans le dossier modules/EWSMailCapture/ -->
            <input name="configFile">EWSMailCapture_standard_sample.xml</input>

            <!-- dossier de la boîte mail vers lequel déplacer les courriels en cas d’action move -->
            <input name="folder">capture/purge</input>

            <!-- ajout des entêtes dans le corps du mail - champs De, À, Cc, Date, Objet - true/false -->
            <input name="addHeaderInMailContent">true</input>
        </step>

        <!-- ... suite du workflow (ex. : appel de MaarchWSClient) ... -->
    </workflow>
</batch>

Authentification

L’authentification à la boîte mail Exchange peut se faire avec la méthode Basic : adresse email & mot de passe, ou en OAuth2 : jeton d’application autorisée. La méthode d’authentification est déterminée selon la présence des champs idoines explicités dans l’exemple du fichier de configuration plus bas sur cette page.

Pour la méthode Basic, il suffit de renseigner l’adresse mail en <username> et son mot de passe en <password>.

Pour la méthode OAuth2, il faut procéder à une configuration sur le portail AzureAD.

• naviguer vers https://aad.portal.azure.com/
• se connecter avec un compte administrateur de votre AzureAD
• cliquer sur Azure Active Directory dans le panneau latéral gauche
• cliquer sur Inscriptions d'applications dans le second panneau latéral gauche qui vient d’apparaître
• cliquer sur Nouvelle inscription et renseigner :
  • Nom : MaarchCapture - EWSMailCapture
  • Types de comptes pris en charge : Comptes dans cet annuaire d’organisation uniquement
  • URI de redirection : Client public/natif (mobile & bureau), avec https://login.microsoftonline.com/common/oauth2/nativeclient
• une fois l’application créée, aller dans Gérer > Certificats & secrets
  • cliquer sur Nouveau secret client, lui donner un nom (arbitraire), et une durée d’expiration, valider la création
  • copier-coller le secret immédiatement dans un fichier temporaire, il ne sera plus affichable par la suite
• aller dans Gérer > API autorisées, puis Ajouter une autorisation
  • trouver Office 365 Exchange Online, puis sous Autorisations d’application, ajouter full_access_as_app
  • donner le consentement administrateur.
• la configuration est maintenant terminée.

En cas de problème, se référer à la documentation de référence publiée par Microsoft, notamment la partie Register your application : https://learn.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-authenticate-an-ews-application-by-using-oauth#register-your-application (en anglais)

Configuration du module

La configuration fine de EWSMailCapture se fait dans un fichier XML dans le dossier du module. Pour commencer, copier le fichier d’exemple pour éditer votre copie :

cp modules/EWSMailCapture/samples/EWSMailCapture_standard_sample.xml modules/EWSMailCapture/
nano modules/EWSMailCapture/EWSMailCapture_standard_sample.xml

Le fichier de configuration a la structure suivante :

<?xml version="1.0" encoding="UTF-8"?>
<EWSMailCapture>
    <accounts>
        <account name="account_1" >
            <mailbox>{mail.name.com}INBOX</mailbox>
            <exchangeversion>Exchange2016</exchangeversion>

            <!-- pour l’authentification Basic -->
            <username>your-email@name.com</username>
            <password>******</password>

            <!-- pour l’authentification OAuth2 -->
            <username>your-email@name.com</username>
            <tenantID>******</tenantID>
            <clientID>******</clientID>
            <clientSecret>******</clientSecret>

        </account>
    </accounts>
    <messagerules>
        <messagerule name="NO_CC_IN_SUBJECT" info="subject" action="none" folder="tmp" op="contains">Cc</messagerule>
    </messagerules>
    <messageoutputs>
        <messageoutput name="doc_date" info="date" formatter="date"/>
        <messageoutput name="type_id">108</messageoutput>
        <messageoutput name="destination">6</messageoutput>
        <messageoutput name="subject" info="subject"/>
        <messageoutput name="fromaddress" info="fromaddress"/>
        <messageoutput name="frompersonal" info="from[0]/personal"/>
        <messageoutput name="toaddress" info="toaddress"/>
        <messageoutput name="xpriority" info="xpriority"/>
        <messageoutput name="message_id" info="message_id"/>
        <messageoutput name="ccaddress" info="ccaddress"/>
        <!-- AR -->
        <messageoutput name="email" info="fromaddress"/>
        <messageoutput name="res_subject" info="subject"/>
    </messageoutputs>
    <attachmentrules>
        <attachmentrule name="images" info="format" op="in">gif, jpg, jpeg, png</attachmentrule>
        <attachmentrule name="application" info="format" op="in">json pdf msword vnd.oasis.opendocument.text octet-stream</attachmentrule>
    </attachmentrules>
    <attachmentoutputs mode="attachment">
        <attachmentoutput name="status">TRA</attachmentoutput>
    </attachmentoutputs>
</EWSMailCapture>

Explication des champs du fichier :

Format des <messagerule>

Les règles de prétraitement des courriels prennent le format suivant :

<messagerule name="blacklist_sender" action="move" folder="spam" info="fromaddress" op="in">spammer1@spam.com spammer2@spam.com</messagerule>

• name est le nom donné à la règle ; il sera affiché dans les logs ;
• action est l’action à effectuer si la règle s’applique : move, delete, ou none ;
• folder est le dossier de la boîte mail vers lequel seront déplacés les courriels en cas d’action move (mettre uniquement le nom sans le chemin) ;
• info est le champ du courriel testé par la règle, parmi :
  • date : la date du courriel au format ISO-8601 (ex : 2022-09-02T10:43:47+02:00)
  • subject : l’objet du courriel
  • fromaddress : l’adresse email de l’expéditeur
  • from[0]/personal : le nom de l’expéditeur
  • toaddress : la ou les destinataires directs (champ « À »), séparés par des points-virgules ;
  • ccaddress : la ou les destinataires en copie (champ « Cc »), séparés par des points-virgules ;
  • xpriority : l’importance du message, en anglais parmi Low, Normal, High
  • message_id : l’identifiant technique (base64) du courriel dans MS Exchange
• valeur du champ : la valeur à comparer avec le champ du courriel
• op : l’opérateur à appliquer entre info et la valeur du champ, parmi :
  • = : égalité entre info et la valeur du champ
  • >= : info supérieur ou égal à la valeur du champ
  • <= : info inférieur ou égal à la valeur du champ
  • > : info supérieur strictement à la valeur du champ
  • < : info inférieur strictement à la valeur du champ
  • != ou <> : info différent de la valeur du champ
  • in : info est l’une des valeurs dans la valeur du champ séparées par des espaces
  • notin : info n’est pas l’une des valeurs dans la valeur du champ séparées par des espaces
  • contains : info contient le texte de la valeur du champ (insensible à la casse)
  • nocontains : info ne contient pas le texte de la valeur du champ (insensible à la casse)

Ainsi, l’exemple plus haut déplace dans le dossier « spam » les courriels expédiés par spammer1@spam.com ou spammer2@spam.com. Les logs mentionneront le nom de la règle blacklist_sender, et ces courriels ne seront pas capturés.

Format des <messageoutput>

Les champs <messageoutput> servent à transmettre des valeurs aux modules suivants de MaarchCapture. Ils peuvent prendre deux formes :

<messageoutput name="doc_date" info="date"/>

Ici, la valeur est nommée doc_date (nom à utiliser dans le prochain module), et prend la information date du courriel – voir dans la note sur les <messagerule> les différentes info possibles.

<messageoutput name="type_id">105</messageoutput>

Ici, la valeur est nommée type_id, prend la valeur en dur 105.

Format des <attachmentrule>

Les règles de prétraitement des pièces-jointes des courriels n’ont qu’un seul format disponible :

<attachmentrule name="images" info="format" op="in">gif, jpg, jpeg, png</attachmentrule>

Les valeurs info="format" op="in" sont fixes. Le nom de la règle (attribut name) est libre. La valeur du champ doit contenir les extensions de fichiers autorisées, séparées par des virgules. Ici, on autorise uniquement les gif, jpg, jpeg et png.

Format des <attachmentoutput>

Les champs <attachmentrule> servent uniquement à transmettre des valeurs en dur aux modules suivants de MaarchCapture.

<attachmentoutput name="status">TRA</attachmentoutput>

Deux valeurs sont toujours transmises :

• filename : le nom de fichier de la pièce-jointe, sans son extension ;
• extension : l’extension du nom de fichier de la pièce-jointe.

Migrer depuis MailCapture

Suivant les étapes de configuration listées plus haut dans ce document, la migration de la capture de boîte mail de MailCapture vers EWSMailCapture se fait selon la procédure suivante :

Commencer par l’adaptation des fichiers XML du dossier config/ – voir les instructions en haut de cette page. Ordinairement, il devrait être suffisant de remplacer les occurrences de MailCapture par EWSMailCapture grâce à :

sed -i 's/MailCapture/EWSMailCapture/g' config/*.xml

Puis vérifier les champs <input> dans <step function="CaptureMails" module="EWSMailCapture" name="..."> tels que décrits plus haut sur cette page.

Ensuite, procéder à la création du fichier de configuration du module :

cp modules/MailCapture/*.xml modules/EWSMailCapture/

Et renommer également ces fichiers en remplaçant MailCapture par EWSMailCapture dans les noms de fichiers, par exemple :

mv modules/EWSMailCapture/{,EWS}MailCapture_standard_sample.xml

Renommer la balise <MailCapture> en <EWSMailCapture> :

sed -i 's/MailCapture/EWSMailCapture/g' modules/EWSMailCapture/*.xml

Finalement, éditer dans chaque fichier modules/EWSMailCapture/*.xml leurs sections <account> :

• remplacer <mailbox>{mail.name.com:993/imap/ssl/novalidate-cert}chemin/du/dossier</mailbox> par <mailbox>{mail.name.com}chemin/du/dossier</mailbox> (suppression du port et des options IMAP) ;
• ajouter dans <account> la balise <exchangeversion> et y renseigner la valeur idoine telle que décrit plus haut sur cette page.