Recurso Ao enviar para suplementos do Outlook

A funcionalidade de envio para suplementos do Outlook fornece uma forma de processar uma mensagem ou item de reunião, ou bloquear utilizadores de determinadas ações e permite que um suplemento defina determinadas propriedades no envio.

Por exemplo, utilize a funcionalidade no envio para:

• Impedir que um usuário envie informações confidenciais ou deixe a linha de assunto em branco.
• Adicionar um destinatário específico à linha CC em mensagens ou à linha destinatários opcionais em reuniões.

O recurso ao enviar é acionado pelo tipo de evento ItemSend e é sem interface de usuário.

Para obter informações sobre limitações relacionadas ao recurso Ao enviar, consulte as Limitações posteriormente neste artigo.

Clientes e plataformas suportados

A tabela seguinte mostra as combinações de cliente/servidor suportadas para a funcionalidade de envio, incluindo a Atualização Cumulativa mínima necessária, quando aplicável. As combinações excluídas não são suportadas.

Como o recurso Ao enviar funciona?

Você pode usar o recurso Ao enviar para criar um suplemento do Outlook que integre o evento síncrono ItemSend. Este evento detecta que o usuário está pressionando o botão Enviar (ou o botão Enviar Atualização para reuniões existentes) e pode ser usado para impedir que um item seja enviado se houver falha na validação. Por exemplo, quando um usuário dispara um evento de envio de mensagem, um suplemento do Outlook que usa o recurso Ao enviar pode:

• Leia e valide o conteúdo da mensagem de e-mail.
• Verifique se a mensagem inclui uma linha de assunto.
• Defina um destinatário predeterminado.

A validação é feita do lado do cliente no Outlook quando o evento de envio é acionado e o suplemento tem até 5 minutos antes de exceder o limite de tempo. Se a validação falhar, o envio do item é bloqueado e é apresentada uma mensagem de erro numa barra de informações que pede ao utilizador para tomar medidas.

A captura de tela a seguir mostra uma barra de informações que notifica que o remetente adicione um assunto.

A captura de tela a seguir mostra uma barra de informações que notifica que o remetente de que foram encontradas palavras bloqueadas.

Limitações

Atualmente, o recurso Ao enviar tem as seguintes limitações.

• Funcionalidade acrescentar ao envio – se chamar item.body.AppendOnSendAsync no processador no envio, é devolvido um erro.

• AppSource – não pode publicar suplementos do Outlook que utilizem a funcionalidade no envio para o AppSource , uma vez que irão falhar a validação do AppSource. Os suplementos que usam o recurso Ao enviar devem ser implantados pelos administradores. Se quiser que a opção publique o suplemento no AppSource, considere utilizar alertas inteligentes, que é uma versão mais recente da funcionalidade no envio. Para saber mais sobre Alertas Inteligentes e como implementar estes suplementos, consulte Utilizar Alertas Inteligentes e os eventos OnMessageSend e OnAppointmentSend no seu suplemento do Outlook e opções de listagem do AppSource para o seu suplemento do Outlook baseado em eventos.

  Importante

  Ao executar npm run validate para validar o manifesto do suplemento, receberá o erro "O suplemento caixa de correio que contém o evento ItemSend é inválido. O manifesto de suplemento da caixa de correio contém o evento ItemSend em VersionOverrides que não é permitido." Esta mensagem é apresentada porque os suplementos que utilizam o ItemSend evento, que é necessário para esta versão da funcionalidade no envio, não podem ser publicados no AppSource. Continuará a poder fazer sideload e executar o suplemento, desde que não sejam encontrados outros erros de validação.

• Manifesto – apenas um ItemSend evento é suportado por suplemento. Se você tiver dois ou mais eventos ItemSend em um manifesto, haverá falha na validação.

• Desempenho – várias viagens de ida e volta para o servidor Web que aloja o suplemento podem afetar o desempenho do suplemento. Considere os efeitos no desempenho quando cria suplementos que requerem várias operações baseadas em mensagens ou reuniões.

• Enviar Mais Tarde (apenas Mac) – se existirem suplementos no envio, a funcionalidade Enviar Mais Tarde estará indisponível.

Além disso, não é recomendado que chame item.close() o processador de eventos no envio, uma vez que fechar o item deve ocorrer automaticamente após a conclusão do evento.

Limitações de tipo/modo de caixa de correio

A funcionalidade de envio só é suportada para caixas de correio de utilizador no Outlook na Web, Windows (novo e clássico) e Mac. Para além das situações em que os suplementos não são ativados conforme indicado na secção Itens da Caixa de Correio disponíveis para suplementos da página de descrição geral dos suplementos do Outlook, a funcionalidade não é atualmente suportada para o modo offline onde esse modo está disponível.

Nos casos em que os suplementos do Outlook não são ativados, o suplemento no envio não será executado e a mensagem será enviada.

No entanto, se a funcionalidade de envio estiver ativada e disponível, mas o cenário da caixa de correio não for suportado, o Outlook não permitirá o envio.

Vários suplementos Ao enviar

Se vários suplementos Ao enviar estiverem instalados, os suplementos serão executados na ordem em que são recebidos das APIs getAppManifestCall ou getExtensibilityContext. Se o primeiro suplemento permitir envio, o segundo suplemento poderá alterar algo que faria o primeiro bloquear o envio. No entanto, o primeiro suplemento não será executado novamente se todos os suplementos instalados tiverem permissão de envio.

Por exemplo, o Suplemento1 e o Suplemento2 usam o recurso Ao enviar. O Suplemento1 é instalado primeiro e o Suplemento2 é instalado depois. O Suplemento1 verifica se a palavra Fabrikam aparece na mensagem como uma condição para o suplemento permitir o envio. No entanto, o Suplemento2 remove as ocorrências da palavra Fabrikam. A mensagem será enviada com todas as instâncias de Fabrikam removidas (devido à ordem de instalação do Suplemento1 e do Suplemento2).

Implantar suplementos do Outlook que usam Ao enviar

Recomendamos que os administradores implantem suplementos do Outlook que usam o recurso Ao enviar. Os administradores precisam garantir que o suplemento Ao enviar:

• Esteja sempre presente a qualquer momento que um item de redigir é aberto (para email: novo, responder ou encaminhar).
• Não pode ser fechado ou desabilitado pelo usuário.

Instalar suplementos do Outlook que usam Ao enviar

O recurso Ao enviar no Outlook exige que os suplementos sejam configurados para os tipos de eventos de envio. Selecione a plataforma que você deseja configurar.

$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

Cenários do recurso Ao enviar

Veja a seguir os cenários com suporte e sem suporte para suplementos que usam o recurso Ao enviar.

Os processadores de eventos são definidos dinamicamente

Os processadores de eventos do suplemento têm de ser definidos até ao momento Office.initialize ou Office.onReady() são chamados (para obter mais informações, consulte o artigo Arranque de um suplemento do Outlook e Inicializar o seu Suplemento do Office). Se o código do processador for definido dinamicamente por determinadas circunstâncias durante a inicialização, tem de criar uma função stub para chamar o processador assim que estiver completamente definido. A função stub tem de ser referenciada no <atributo do elemento Evento> do seu manifesto.FunctionName Esta solução garante que o processador está definido e pronto para ser referenciado uma vez Office.initialize ou Office.onReady() executado.

Se o processador não estiver definido depois de o suplemento ser inicializado, o remetente será notificado de que "A função de chamada de retorno está inacessível" através de uma barra de informações no item de correio.

A caixa de correio do usuário tem o recurso de suplemento Ao enviar habilitado, mas nenhum suplemento está instalado

Neste cenário, o utilizador poderá enviar mensagens e itens de reunião sem a execução de quaisquer suplementos.

A caixa de correio do usuário tem o recurso de suplemento Ao enviar habilitado, e os suplementos compatíveis com Ao enviar estão instalados e habilitados

Os suplementos serão executados durante o evento de envio, que em seguida permitirão ou impedirão o usuário de enviar.

Delegação de caixa de correio, onde a caixa de correio 1 tem permissões de acesso total à caixa de correio 2

Navegador da Web (Outlook clássico)

Navegador da Web (Outlook moderno), Windows, Mac

Para impor o Ao enviar, os administradores devem garantir que a política tenha sido habilitada nas duas caixas de correio. Para saber como suportar o acesso delegado num suplemento, consulte Ativar pastas partilhadas e cenários de caixa de correio partilhada.

Caixa de correio do usuário com recurso/política de suplemento Ao enviar habilitado, os suplementos com suporte à funcionalidade Ao enviar estão instalados e habilitados e o modo offline está habilitado

Os suplementos Ao enviar serão executados de acordo com o estado online do usuário, o back-end do suplemento e o Exchange.

Estado do usuário

Os suplementos Ao enviar serão executados durante o envio se o usuário estiver online. Se o usuário estiver offline, os suplementos Ao enviar não serão executados e o item de mensagem ou de reunião não será enviado.

Estado do back-end do suplemento

Um suplemento Ao enviar será executado se o seu back-end estiver online e acessível. Se o back-end estiver offline, ao enviar será desabilitado.

Estado do Exchange

Os suplementos Ao enviar serão executados durante o envio se o servidor do Exchange estiver online e acessível. Se o suplemento Ao enviar não puder alcançar o Exchange e a política ou cmdlet aplicável estiverem ativados, o envio será desabilitado.

O utilizador pode editar o item enquanto os suplementos no envio estão a trabalhar no mesmo

Enquanto os suplementos no envio estão a processar um item, o utilizador pode editar o item ao adicionar, por exemplo, texto ou anexos inadequados. Se quiser impedir que o utilizador edite o item enquanto o suplemento está a ser processado durante o envio, pode implementar uma solução através de uma caixa de diálogo. Esta solução pode ser utilizada no Outlook na Web (clássico), Windows (clássico) e Mac.

No processador no envio:

1. Chame displayDialogAsync para abrir uma caixa de diálogo para que os cliques do rato e os batimentos de tecla sejam desativados.

   Importante

   Para obter este comportamento no Outlook clássico na Web, deve definir a propriedade displayInIframe como true no options parâmetro da displayDialogAsync chamada.

2. Implemente o processamento do item.

3. Feche a caixa de diálogo. Além disso, processe o que acontece se o utilizador fechar a caixa de diálogo.

Exemplos de código

Os seguintes exemplos de código mostram como criar um suplemento simples Ao enviar. Para baixar o exemplo de código em que esses exemplos se baseiam, consulte Outlook-Add-in-On-Send.

Manifesto, versão de substituição e evento

Um exemplo de código Outlook-Add-in-On-Send inclui dois manifestos:

• Contoso Message Body Checker.xml – Mostra como verificar o corpo de uma mensagem quanto a palavras restritas ou informações confidenciais no envio.

• Contoso Subject and CC Checker.xml – Mostra como adicionar um destinatário à linha CC e verificar se a mensagem inclui uma linha de assunto no envio.

No arquivo de manifesto Contoso Message Body Checker.xml, inclua o arquivo de função e o nome da função que deve ser chamada no evento ItemSend. A operação é executada de maneira síncrona.

<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>

Para o arquivo de manifesto Contoso Subject and CC Checker.xml, o exemplo a seguir mostra o arquivo de função e o nome da função para chamar o evento de envio de mensagem.

<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>

A API Ao enviar requer VersionOverrides v1_1. Veja a seguir como adicionar o nó VersionOverrides em seu manifesto.

 <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>

Objetos Event e item, e os métodos body.getAsync e body.setAsync

Para acessar o item de mensagem ou de reunião selecionado no momento (neste exemplo, a mensagem redigida recentemente), use o namespace Office.context.mailbox.item. O ItemSend evento é transmitido automaticamente pela funcionalidade on-send para a função especificada no manifesto — neste exemplo, a validateBody função .

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

A validateBody função obtém o corpo atual no formato especificado (HTML) e transmite o ItemSend objeto de evento ao qual o código quer aceder na função de chamada de retorno. Além do método getAsync, o objeto Body também fornece um método setAsync que você pode usar para substituir o corpo pelo texto especificado.

Objeto NotificationMessages e método event.completed

A função checkBodyOnlyOnSendCallBack usa uma expressão regular para determinar se o corpo da mensagem contém palavras bloqueadas. Se ela encontrar uma correspondência com uma matriz de palavras restritas, bloqueará os emails de serem enviados e notificará o remetente pela barra de informações. Para tal, utiliza a notificationMessages propriedade do Item objeto para devolver um objeto NotificationMessages . Ele, em seguida, adiciona uma notificação ao item chamando o método addAsync, como mostrado no exemplo a seguir.

// 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 });
}

Seguem-se os parâmetros do addAsync método .

• NoSend – uma cadeia de carateres que é uma chave especificada pelo programador para referenciar uma mensagem de notificação. Você pode usá-la para modificar esta mensagem mais tarde. A chave não pode ter mais de 32 carateres.
• type – uma das propriedades do parâmetro de objeto JSON. Representa o tipo de uma mensagem; os tipos correspondem aos valores da enumeração Office.MailboxEnums.ItemNotificationMessageType. Os valores possíveis são indicador de progresso, mensagem informativa ou mensagem de erro. Neste exemplo, type é uma mensagem de erro.
• message – uma das propriedades do parâmetro de objeto JSON. Neste exemplo, message é o texto da mensagem de notificação.

Para sinalizar que o suplemento terminou o processamento do ItemSend evento acionado pela operação de envio, chame o método event.completed({allowEvent:Boolean} ). A propriedade allowEvent é um Booliano. Se for definido como true, o envio será permitido. Se definido como false, a mensagem de email será impedida de ser enviada.

Métodos replaceAsync, removeAsync e getAllAsync

Além do método addAsync, o objeto NotificationMessages também inclui os métodos replaceAsync, removeAsync e getAllAsync. Esses métodos não são usados neste exemplo de código. Para saber mais, veja NotificationMessages.

Código do Assunto e do verificador de CC

O exemplo de código a seguir mostra como adicionar um destinatário à linha CC e verifica se a mensagem inclui um assunto ao enviar. Este exemplo usa o recurso Ao enviar para permitir ou proibir o envio de um email.

// 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 });
            }
        });
}

Para saber mais sobre como adicionar um destinatário à linha CC e verificar se a mensagem de e-mail inclui uma linha de assunto ao enviar e para ver as APIs que você pode usar, consulte o exemplo Outlook-Add-in-On-Send. O código é bem comentado.

Depurar suplementos do Outlook que utilizam no envio

Para obter instruções sobre como depurar o seu suplemento no envio, veja Depurar comandos da função nos suplementos do Outlook.

Confira também

• Visão geral da arquitetura e dos recursos de suplementos do Outlook
• Suplemento do Outlook para demonstração de comando de suplemento