Fonctionnalité d’envoi des compléments Outlook

La fonctionnalité d’envoi pour les compléments Outlook permet de gérer un message ou un élément de réunion, ou de bloquer les utilisateurs de certaines actions, et permet à un complément de définir certaines propriétés lors de l’envoi.

Par exemple, utilisez la fonctionnalité d’envoi pour :

• Empêcher un utilisateur d’envoyer des informations sensibles ou de laisser la ligne d’objet vide.
• Ajouter un destinataire spécifique à la ligne CC dans les messages ou à la ligne destinataires facultatifs des réunions.

La fonctionnalité d’envoi est déclenchée par le type d’événement ItemSend et est sans interface utilisateur.

Pour en savoir plus sur les limites de la fonctionnalité d’envoi, consultez la section Limites plus loin dans cet article.

Clients et plateformes pris en charge

Le tableau suivant présente les combinaisons client-serveur prises en charge pour la fonctionnalité d’envoi, y compris la mise à jour cumulative minimale requise le cas échéant. Les combinaisons exclues ne sont pas prises en charge.

Comment marche la fonctionnalité d’envoi ?

Vous pouvez utiliser la fonctionnalité d’envoi pour créer un complément Outlook qui intègre l’événement synchrone ItemSend. Cet événement détecte le moment où l’utilisateur clique sur le bouton Envoyer(ou le bouton Envoyer mise à jour pour les réunions existantes) et peut servir à bloquer l’envoi de l’élément s’il n’est pas validé. Par exemple, quand un utilisateur déclenche un événement d’envoi de message, un complément Outlook qui utilise la fonctionnalité d’envoi peut :

• Lisez et validez le contenu du message électronique.
• Vérifiez que le message inclut une ligne d’objet.
• Définissez un destinataire prédéterminé.

La validation est effectuée côté client dans Outlook lorsque l’événement d’envoi est déclenché et que le complément a jusqu’à 5 minutes avant son expiration. Si la validation échoue, l’envoi de l’élément est bloqué et un message d’erreur s’affiche dans une barre d’informations qui invite l’utilisateur à prendre des mesures.

La capture d’écran suivante montre une barre d’informations invitant l’expéditeur à renseigner l’objet du message.

La capture d’écran suivante montre une barre d’informations informant l’expéditeur que des mots bloqués ont été trouvés.

Limites

Les limites de la fonctionnalité d’envoi sont les suivantes.

• Fonctionnalité Append-on-send : si vous appelez item.body.AppendOnSendAsync dans le gestionnaire lors de l’envoi, une erreur est retournée.

• AppSource : vous ne pouvez pas publier de compléments Outlook qui utilisent la fonctionnalité d’envoi à AppSource , car ils échouent à la validation AppSource. Les compléments qui utilisent la fonctionnalité d’envoi doivent être déployés par les administrateurs. Si vous souhaitez que l’option de publier votre complément sur AppSource, envisagez d’utiliser des alertes intelligentes à la place, qui est une version plus récente de la fonctionnalité d’envoi. Pour en savoir plus sur les alertes intelligentes et sur le déploiement de ces compléments, voir Utiliser les alertes intelligentes et les événements OnMessageSend et OnAppointmentSend dans votre complément Outlook et les options de liste AppSource pour votre complément Outlook basé sur les événements.

  Importante

  Lorsque vous exécutez npm run validate pour valider le manifeste de votre complément, vous recevez l’erreur « Le complément de boîte aux lettres contenant l’événement ItemSend n’est pas valide. Le manifeste du complément de boîte aux lettres contient l’événement ItemSend dans VersionOverrides, ce qui n’est pas autorisé. » Ce message s’affiche car les compléments qui utilisent l’événement ItemSend , requis pour cette version de la fonctionnalité d’envoi, ne peuvent pas être publiés sur AppSource. Vous pourrez toujours charger une version test et exécuter votre complément, à condition qu’aucune autre erreur de validation n’ait été trouvée.

• Manifeste : un ItemSend seul événement est pris en charge par complément. Si votre manifeste comprend plusieurs événements ItemSend, il ne sera pas validé.

• Performances : plusieurs allers-retours vers le serveur web qui héberge le complément peuvent affecter les performances du complément. Tenez compte des effets sur les performances lorsque vous créez des compléments qui nécessitent plusieurs opérations basées sur des messages ou des réunions.

• Envoyer plus tard (Mac uniquement) : s’il existe des compléments lors de l’envoi, la fonctionnalité Envoyer plus tard n’est pas disponible.

En outre, il n’est pas recommandé d’appeler item.close() dans le gestionnaire d’événements lors de l’envoi, car la fermeture de l’élément doit se produire automatiquement une fois l’événement terminé.

Limites concernant le type ou le mode de boîte aux lettres

La fonctionnalité d’envoi est prise en charge uniquement pour les boîtes aux lettres utilisateur dans Outlook sur le web, Windows (nouveau et classique) et Mac. En plus des situations où les compléments ne s’activent pas comme indiqué dans la section Éléments de boîte aux lettres disponibles pour les compléments de la page de vue d’ensemble des compléments Outlook, la fonctionnalité n’est actuellement pas prise en charge pour le mode hors connexion où ce mode est disponible.

Dans les cas où les compléments Outlook ne s’activent pas, le complément lors de l’envoi ne s’exécute pas et le message est envoyé.

Toutefois, si la fonctionnalité d’envoi est activée et disponible, mais que le scénario de boîte aux lettres n’est pas pris en charge, Outlook n’autorise pas l’envoi.

Compléments d’envoi multiples

Si plusieurs compléments d’envoi sont installés, ils s’exécutent dans l’ordre dans lequel ils sont reçus par les API getAppManifestCall ou getExtensibilityContext. Si le premier complément autorise l’envoi du message, le deuxième complément peut modifier un paramètre qui le bloque. Par contre, le premier complément n’est pas réexécuté si les autres compléments installés autorisent l’envoi.

Par exemple, Complément1 et Complément2 utilisent la fonctionnalité d’envoi. Complément1 est installé en premier, et Complément2 en deuxième. Complément1 vérifie que le mot Fabrikam apparaît dans le message pour autoriser l’envoi. À l’inverse, Complément2 supprime toutes les occurrences du mot Fabrikam. Le message est alors envoyé sans le mot Fabrikam (à cause de l’ordre d’installation de Complément1 et Complément2).

Déployer des compléments Outlook qui utilisent la fonctionnalité d’envoi

Nous recommandons aux administrateurs de déployer les compléments Outlook qui utilisent la fonctionnalité d’envoi. Les administrateurs doivent vérifier que le complément d’envoi :

• est présent lors de l’ouverture d’un élément de composition (pour les e-mails : nouveau message, répondre ou transférer).
• ne peut pas être fermé ou désactivé par l’utilisateur.

Installer des compléments Outlook qui utilisent la fonctionnalité d’envoi

Dans Outlook, la fonctionnalité d’envoi exige la configuration des compléments en fonction des types d’événement d’envoi. Sélectionnez la plateforme que vous voulez configurer.

$Data=Get-Content -Path '.\Contoso Message Body Checker.xml' -Encoding Byte –ReadCount 0

New-App -OrganizationApp -FileData $Data -DefaultStateForUser Enabled

Get-CASMailbox joe@contoso.com | Set-CASMailbox –OWAMailboxPolicy "ContosoCorpOWAPolicy"

Get-OWAMailboxPolicy OWAOnSendAddinAllUserPolicy | Set-OWAMailboxPolicy –OnSendAddinsEnabled:$false

$Data=Get-Content -Path '.\Contoso Message Body Checker.xml' -Encoding Byte –ReadCount 0

New-App -OrganizationApp -FileData $Data -DefaultStateForUser Enabled

Get-CASMailbox joe@contoso.com | Set-CASMailbox –OWAMailboxPolicy "ContosoCorpOWAPolicy"

Get-OWAMailboxPolicy OWAOnSendAddinAllUserPolicy | Set-OWAMailboxPolicy –OnSendAddinsEnabled:$false

Scénarios de la fonctionnalité d’envoi

Voici tous les scénarios pris en charge et non pour les compléments qui utilisent la fonctionnalité d’envoi.

Les gestionnaires d’événements sont définis dynamiquement

Les gestionnaires d’événements de votre complément doivent être définis à l’heure Office.initialize ou Office.onReady() sont appelés (pour plus d’informations, voir Démarrage d’un complément Outlook et Initialiser votre complément Office). Si votre code de gestionnaire est défini dynamiquement par certaines circonstances lors de l’initialisation, vous devez créer une fonction stub pour appeler le gestionnaire une fois qu’il est complètement défini. La fonction stub doit être référencée dans l’attribut de FunctionName l’élément <Event> de votre manifeste. Cette solution de contournement garantit que votre gestionnaire est défini et prêt à être référencé une fois Office.initialize ou s’exécute Office.onReady() .

Si votre gestionnaire n’est pas défini une fois votre complément initialisé, l’expéditeur reçoit une notification indiquant que « La fonction de rappel est inaccessible » via une barre d’informations dans l’élément de courrier.

La fonctionnalité d’envoi est activée sur la boîte aux lettres de l’utilisateur, mais aucun complément n’est installé.

Dans ce scénario, l’utilisateur peut envoyer des messages et des éléments de réunion sans qu’aucun complément ne s’exécute.

La fonctionnalité d’envoi est activée sur la boîte aux lettres de l’utilisateur et les compléments qui prennent en charge cette fonctionnalité sont installés et activés

Les compléments s’exécutent pendant l’événement d’envoi pour autoriser ou empêcher l’utilisateur d’envoyer son message.

Délégation de boîte aux lettres, où la Boîte aux lettres 1 dispose des autorisations d’accès total à la Boîte aux lettres 2

Navigateur web (Outlook classique)

Navigateur web (Outlook moderne), Windows, Mac

Pour appliquer l’envoi, les administrateurs doivent s’assurer que la stratégie a été activée sur les deux boîtes aux lettres. Pour savoir comment prendre en charge l’accès délégué dans un complément, consultez Activer les scénarios de boîte aux lettres partagées et de dossiers partagés.

La fonctionnalité/stratégie d’envoi est activée sur la boîte aux lettres de l’utilisateur, les compléments qui prennent en charge cette fonctionnalité sont installés et activés et le mode hors connexion est activé

Les compléments d’envoi s’exécutent en fonction de l’état en ligne de l’utilisateur, du serveur principal du complément et d’Exchange.

État de l’utilisateur

Les compléments d’envoi s’exécutent pendant l’envoi, si l’utilisateur est en ligne. Si l’utilisateur est hors ligne, les compléments d’envoi ne s’exécutent pas pendant l’envoi et l’élément message ou réunion n’est pas envoyé.

État du serveur de complément

Un complément sur envoi s’exécute si son serveur principal est en ligne et joignable. Si le serveur principal est hors connexion, l’envoi est désactivé.

État d’Exchange

Les compléments d’envoi s’exécutent pendant l’envoi, si le serveur Exchange est en ligne et joignable. Si le complément sur envoi ne peut pas accéder à Exchange et que la stratégie ou l’applet de commande applicable sont activés, l’envoi est désactivé.

L’utilisateur peut modifier l’élément pendant que les compléments d’envoi y travaillent

Pendant que les compléments lors de l’envoi traitent un élément, l’utilisateur peut modifier l’élément en ajoutant, par exemple, du texte ou des pièces jointes inappropriés. Si vous souhaitez empêcher l’utilisateur de modifier l’élément pendant le traitement de votre complément lors de l’envoi, vous pouvez implémenter une solution de contournement à l’aide d’une boîte de dialogue. Cette solution de contournement peut être utilisée dans Outlook sur le web (classique), Windows (classique) et Mac.

Dans votre gestionnaire d’envoi :

1. Appelez displayDialogAsync pour ouvrir une boîte de dialogue afin que les clics de souris et les séquences de touches soient désactivés.

   Importante

   Pour obtenir ce comportement dans les Outlook sur le web classiques, vous devez définir la propriété truedisplayInIframe sur dans le options paramètre de l’appeldisplayDialogAsync.

2. Implémenter le traitement de l’élément.

3. Fermez la boîte de dialogue. Gérez également ce qui se passe si l’utilisateur ferme la boîte de dialogue.

Exemples de code

Les exemples de code ci-dessous vous montrent comment créer un complément d’envoi simple. Pour télécharger l’exemple de code sur lequel se basent ces exemples, consultez l’article Outlook-Add-in-On-Send.

Manifeste, remplacement de version et événement

L’exemple de code Outlook-Add-in-On-Send comprend deux manifestes :

• Contoso Message Body Checker.xml: montre comment case activée le corps d’un message pour les mots restreints ou les informations sensibles lors de l’envoi.

• Contoso Subject and CC Checker.xml : montre comment ajouter un destinataire à la ligne CC et vérifier que le message inclut une ligne d’objet lors de l’envoi.

Dans le fichier manifeste Contoso Message Body Checker.xml, insérez le fichier de fonction et le nom de la fonction qui doit être appelée lors d’un événement ItemSend. L’opération s’exécute de façon synchrone.

<Hosts>
    <Host xsi:type="MailHost">
        <DesktopFormFactor>
            <!-- The functionfile and function name to call on message send.  -->
            <!-- In this case, the function validateBody will be called within the JavaScript code referenced in residUILessFunctionFileUrl. -->
            <FunctionFile resid="residUILessFunctionFileUrl" />
            <ExtensionPoint xsi:type="Events">
                <Event Type="ItemSend" FunctionExecution="synchronous" FunctionName="validateBody" />
            </ExtensionPoint>
        </DesktopFormFactor>
    </Host>
</Hosts>

Pour le fichier manifeste Contoso Subject and CC Checker.xml, l’exemple suivant montre le fichier de fonction et le nom de la fonction à appeler dans l’événement d’envoi du message.

<Hosts>
    <Host xsi:type="MailHost">
        <DesktopFormFactor>
            <!-- The functionfile and function name to call on message send.  -->
            <!-- In this case the function validateSubjectAndCC will be called within the JavaScript code referenced in residUILessFunctionFileUrl. -->
            <FunctionFile resid="residUILessFunctionFileUrl" />
            <ExtensionPoint xsi:type="Events">
                <Event Type="ItemSend" FunctionExecution="synchronous" FunctionName="validateSubjectAndCC" />
            </ExtensionPoint>
        </DesktopFormFactor>
    </Host>
</Hosts>

L’API d’envoi nécessite VersionOverrides v1_1. L’exemple vous montre comment ajouter le nœud VersionOverrides dans votre manifeste.

 <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
     <!-- On-send requires VersionOverridesV1_1 -->
     <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
         ...
     </VersionOverrides>
</VersionOverrides>

Les objets Event et item et les méthodes body.getAsync et body.setAsync

Pour accéder au message ou élément de réunion sélectionné (dans cet exemple, le message que vous venez de composer), utilisez l’espace de noms Office.context.mailbox.item. L’événement ItemSend est automatiquement passé par la fonctionnalité d’envoi à la fonction spécifiée dans le manifeste, dans cet exemple, la validateBody fonction .

let mailboxItem;

Office.initialize = function (reason) {
    mailboxItem = Office.context.mailbox.item;
}

// Entry point for Contoso Message Body Checker add-in before send is allowed.
// <param name="event">ItemSend event is automatically passed by on-send code to the function specified in the manifest.</param>
function validateBody(event) {
    mailboxItem.body.getAsync("html", { asyncContext: event }, checkBodyOnlyOnSendCallBack);
}

La validateBody fonction obtient le corps actuel au format spécifié (HTML) et transmet l’objet ItemSend d’événement auquel le code souhaite accéder dans la fonction de rappel. En plus de la méthode getAsync, l’objet Body fournit également une méthode setAsync utile pour remplacer le corps du message par le texte spécifié.

Objet NotificationMessages et méthode event.completed

La fonction checkBodyOnlyOnSendCallBack utilise une expression régulière pour déterminer si le corps du message contient des mots bloqués. Si elle trouve une correspondance dans un tableau de mots bloqués, il bloque l’envoi du message et avertit l’expéditeur via la barre d’informations. Pour ce faire, il utilise la notificationMessages propriété de l’objet Item pour renvoyer un objet NotificationMessages . Il ajoute ensuite une notification à l’élément en appelant la méthode addAsync, comme illustré dans l’exemple suivant.

// Determine whether the body contains a specific set of blocked words. If it contains the blocked words, block email from being sent. Otherwise allow sending.
// <param name="asyncResult">ItemSend event passed from the calling function.</param>
function checkBodyOnlyOnSendCallBack(asyncResult) {
    const listOfBlockedWords = new Array("blockedword", "blockedword1", "blockedword2");
    const wordExpression = listOfBlockedWords.join('|');

    // \b to perform a "whole words only" search using a regular expression in the form of \bword\b.
    // i to perform case-insensitive search.
    const regexCheck = new RegExp('\\b(' + wordExpression + ')\\b', 'i');
    const checkBody = regexCheck.test(asyncResult.value);

    if (checkBody) {
        mailboxItem.notificationMessages.addAsync('NoSend', { type: 'errorMessage', message: 'Blocked words have been found in the body of this email. Please remove them.' });
        // Block send.
        asyncResult.asyncContext.completed({ allowEvent: false });
    }

    // Allow send.
    asyncResult.asyncContext.completed({ allowEvent: true });
}

Voici les paramètres de la addAsync méthode .

• NoSend : chaîne qui est une clé spécifiée par le développeur pour référencer un message de notification. Vous pouvez l’utiliser pour modifier ce message ultérieurement. La clé ne peut pas comporter plus de 32 caractères.
• type : une des propriétés du paramètre d’objet JSON. Représente le type d’un message ; les types correspondent aux valeurs de l’énumération Office.MailboxEnums.ItemNotificationMessageType. Les valeurs possibles sont Indicateur de progression, Message d’information ou Message d’erreur. Dans cet exemple, type est un message d’erreur.
• message : une des propriétés du paramètre d’objet JSON. Dans cet exemple, message correspond au texte du message de notification.

Pour signaler que le complément a terminé le traitement de l’événement ItemSend déclenché par l’opération d’envoi, appelez la méthode event.completed({allowEvent :Boolean}). La propriété allowEvent est une valeur booléenne. Si la valeur est définie sur true, l’envoi est autorisé. Si la valeur est définie sur false, l’envoi du message est bloqué.

Méthodes replaceAsync, removeAsync et getAllAsync

En plus de la méthode addAsync, l'objet NotificationMessages inclut également les méthodes replaceAsync, removeAsync et getAllAsync. Ces méthodes ne sont pas utilisées dans cet exemple de code. Pour plus d’informations, consultez l’article relatif à l’objet NotificationMessages.

Code vérificateur de l’objet et de la ligne CC

L’exemple de code suivant vous montre comment ajouter un destinataire à la ligne Cc et vérifier que le message comporte un objet pendant l’envoi. Cet exemple utilise la fonctionnalité d’envoi pour autoriser ou interdire l’envoi d’un e-mail.

// Invoke by Contoso Subject and CC Checker add-in before send is allowed.
// <param name="event">ItemSend event is automatically passed by on-send code to the function specified in the manifest.</param>
function validateSubjectAndCC(event) {
    shouldChangeSubjectOnSend(event);
}

// Determine whether the subject should be changed. If it is already changed, allow send. Otherwise change it.
// <param name="event">ItemSend event passed from the calling function.</param>
function shouldChangeSubjectOnSend(event) {
    mailboxItem.subject.getAsync(
        { asyncContext: event },
        function (asyncResult) {
            addCCOnSend(asyncResult.asyncContext);
            //console.log(asyncResult.value);
            // Match string.
            const checkSubject = (new RegExp(/\[Checked\]/)).test(asyncResult.value)
            // Add [Checked]: to subject line.
            subject = '[Checked]: ' + asyncResult.value;

            // Determine whether a string is blank, null, or undefined.
            // If yes, block send and display information bar to notify sender to add a subject.
            if (asyncResult.value === null || (/^\s*$/).test(asyncResult.value)) {
                mailboxItem.notificationMessages.addAsync('NoSend', { type: 'errorMessage', message: 'Please enter a subject for this email.' });
                asyncResult.asyncContext.completed({ allowEvent: false });
            }
            else {
                // If can't find a [Checked]: string match in subject, call subjectOnSendChange function.
                if (!checkSubject) {
                    subjectOnSendChange(subject, asyncResult.asyncContext);
                    //console.log(checkSubject);
                }
                else {
                    // Allow send.
                    asyncResult.asyncContext.completed({ allowEvent: true });
                }
            }
        });
}

// Add a CC to the email. In this example, CC contoso@contoso.onmicrosoft.com
// <param name="event">ItemSend event passed from calling function</param>
function addCCOnSend(event) {
    mailboxItem.cc.setAsync(['Contoso@contoso.onmicrosoft.com'], { asyncContext: event });
}

// Determine whether the subject should be changed. If it is already changed, allow send, otherwise change it.
// <param name="subject">Subject to set.</param>
// <param name="event">ItemSend event passed from the calling function.</param>
function subjectOnSendChange(subject, event) {
    mailboxItem.subject.setAsync(
        subject,
        { asyncContext: event },
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed) {
                mailboxItem.notificationMessages.addAsync('NoSend', { type: 'errorMessage', message: 'Unable to set the subject.' });

                // Block send.
                asyncResult.asyncContext.completed({ allowEvent: false });
            }
            else {
                // Allow send.
                asyncResult.asyncContext.completed({ allowEvent: true });
            }
        });
}

Pour savoir comment ajouter un destinataire à la ligne Cc et vérifier que le message comporte une ligne d’objet pendant l’envoi, et découvrir les API disponibles, consultez l’article relatif à l’exemple Outlook-Add-in-On-Send. Le code est accompagné de commentaires détaillés.

Déboguer des compléments Outlook qui utilisent l’envoi

Pour obtenir des instructions sur le débogage de votre complément lors de l’envoi, voir Debug function commands in Outlook add-ins.

Voir aussi

• Présentation de l’architecture et des fonctionnalités des compléments Outlook
• Démonstration de la commande du complément Outlook