Compartilhar via

Atualize automaticamente sua assinatura ao alternar entre contas do Exchange

  • Artigo

A aplicação da assinatura correta às mensagens ao usar várias contas do Exchange agora é facilitada com a adição dos OnMessageFromChanged eventos e OnAppointmentFromChanged ao recurso de ativação baseado em eventos . O OnMessageFromChanged evento ocorre quando a conta no campo De uma mensagem que está sendo composta é alterada, enquanto o OnAppointmentFromChanged evento ocorre quando o organizador de uma reunião que está sendo composta é alterado. Esses eventos estendem ainda mais os recursos dos suplementos de assinatura e permitem que eles:

  • Forneça aos usuários a conveniência de aplicar assinaturas personalizadas para cada uma de suas contas.
  • Habilite os delegados da caixa de correio para gerenciar com mais precisão e eficiência as mensagens de saída e as solicitações de reunião de várias caixas de correio.
  • Verifique se as mensagens e compromissos dos usuários atendem às políticas de comunicação e marketing de sua organização.

As seções a seguir orientam como desenvolver um suplemento baseado em evento que manipula o OnMessageFromChanged evento para atualizar automaticamente a assinatura de uma mensagem quando a conta de email no campo De for alterada.

Observação

Os OnMessageFromChanged eventos e OnAppointmentFromChanged foram introduzidos no conjunto de requisitos 1.13. Para obter informações sobre o suporte ao cliente para esses eventos, consulte Clientes e plataformas com suporte.

Clientes e plataformas com suporte

As tabelas a seguir listam combinações cliente-servidor que dão suporte aos OnMessageFromChanged eventos e OnAppointmentFromChanged . Selecione a guia para o evento aplicável.

Cliente Exchange Online Exchange 2019 local (Atualização Cumulativa 12 ou posterior) Exchange 2016 local (Atualização Cumulativa 22 ou posterior)
Navegador da Web (interface do usuário moderna)

novo Outlook no Windows (versão prévia)		 Com suporte Não aplicável Não aplicável
Windows (clássico)
Versão 2304 (Build 16327.20248) ou posterior		 Com suporte Com suporte Com suporte
Mac
Versão 16.77.816.0 ou posterior		 Com suporte Não aplicável Não aplicável
iOS Não aplicável Não aplicável Não aplicável
Android Não aplicável Não aplicável Não aplicável

Pré-requisitos

Para testar o passo a passo, você deve ter pelo menos duas contas do Exchange.

Configurar seu ambiente

Conclua o início rápido do Outlook, que cria um projeto de suplemento com o gerador Yeoman para suplementos do Office.

Configurar o manifesto

  1. Abra o arquivo manifest.json .

  2. Adicione o objeto a seguir à matriz "extensions.runtimes". Observe o seguinte sobre esta marcação.

    • A "minVersion" do conjunto de requisitos da caixa de correio é configurada como "1.13" porque esta é a versão mais baixa do conjunto de requisitos que dá suporte ao OnMessageFromChanged evento. Para obter mais informações, confira a tabela "Eventos com suporte" em Configurar seu suplemento do Outlook para ativação baseada em eventos.

    • A "id" do runtime é definida como um nome descritivo, "autorun_runtime".

    • A propriedade "code" tem uma propriedade filho "page" definida como um arquivo HTML e uma propriedade filho "script" definida como um arquivo JavaScript. Você criará ou editará esses arquivos em etapas posteriores. O Office usa um desses valores dependendo da plataforma.

      • O Outlook clássico no Windows executa o manipulador de eventos em um runtime somente JavaScript, que carrega um arquivo JavaScript diretamente.
      • Outlook na Web e no Mac e o novo Outlook no Windows (versão prévia) executam o manipulador em um runtime do navegador, que carrega um arquivo HTML. O arquivo HTML contém uma <script> marca que carrega o arquivo JavaScript.

      Para obter mais informações, consulte Runtimes em Suplementos do Office.

    • A propriedade "lifetime" é definida como "curta". Isso significa que o runtime é iniciado quando o evento ocorre e é desligado quando o manipulador é concluído.

    • Há "ações" para executar manipuladores para os OnMessageFromChanged eventos e OnNewMessageCompose . Você criará os manipuladores em uma etapa posterior.

    {
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.13"
            }
        ]
    },
    "id": "autorun_runtime",
    "type": "general",
    "code": {
        "page": "https://localhost:3000/commands.html",
        "script": "https://localhost:3000/launchevent.js"
    },
    "lifetime": "short",
    "actions": [
        {
            "id": "onMessageFromChangedHandler",
            "type": "executeFunction",
            "displayName": "onMessageFromChangedHandler"
        },
        {
            "id": "onNewMessageComposeHandler",
            "type": "executeFunction",
            "displayName": "onNewMessageComposeHandler"
        }
    ]
}

  3. Adicione uma matriz "autoRunEvents" como uma propriedade do objeto na matriz "extensões". A matriz "autoRunEvents" contém um objeto com as propriedades da chave a seguir.

    • A propriedade "eventos" atribui manipuladores aos OnMessageFromChanged eventos e OnNewMessageCompose . Para obter informações sobre nomes de eventos usados no manifesto unificado, consulte a tabela "Eventos com suporte" em Configurar o suplemento do Outlook para ativação baseada em eventos.
    • O nome da função fornecido em "actionId" deve corresponder à propriedade "id" de seu objeto correspondente na matriz "actions" configurada anteriormente.
    "autoRunEvents": [
    {
        "requirements": {
            "capabilities": [
                {
                    "name": "Mailbox",
                    "minVersion": "1.13"
                }
            ],
            "scopes": [
                "mail"
            ]
        },
        "events": [
            {
                "type": "messageFromChanged",
                "actionId": "onMessageFromChangedHandler"
            },
            {
                "type": "newMessageComposeCreated",
                "actionId": "onNewMessageComposeHandler"
            }
        ]
    }
]

Dica

Implementar os manipuladores de eventos

Os manipuladores de eventos devem ser configurados para os OnNewMessageCompose eventos e OnMessageFromChanged . A onNewMessageComposeHandler função adiciona uma assinatura a uma mensagem recém-criada se uma padrão ainda não estiver configurada na conta atual. Quando a conta no campo De é alterada, a onMessageFromChangedHandler função atualiza a assinatura com base nessa conta recém-selecionada.

  1. No mesmo projeto de início rápido, navegue até o diretório ./src e crie uma nova pasta chamada launchevent.

  2. Na pasta ./src/launchevent , crie um novo arquivo chamado launchevent.js.

  3. Abra o arquivo ./src/launchevent/launchevent.js no editor de código e adicione o código JavaScript a seguir.

    /*
 * Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 * See LICENSE in the project root for license information.
 */

// The OnNewMessageCompose event handler that adds a signature to a new message.
function onNewMessageComposeHandler(event) {
    const item = Office.context.mailbox.item;

    // Check if a default Outlook signature is already configured.
    item.isClientSignatureEnabledAsync({ asyncContext: event }, (result) => {
        if (result.status === Office.AsyncResultStatus.Failed) {
            console.log(result.error.message);
            return;
        }

        // Add a signature if there's no default Outlook signature configured.
        if (result.value === false) {
            item.body.setSignatureAsync(
                "<i>This is a sample signature.</i>",
                { asyncContext: result.asyncContext, coercionType: Office.CoercionType.Html },
                addSignatureCallback
            );
        }
    });
}

// The OnMessageFromChanged event handler that updates the signature when the email address in the From field is changed.
function onMessageFromChangedHandler(event) {
    const item = Office.context.mailbox.item;
    const signatureIcon =
    "iVBORw0KGgoAAAANSUhEUgAAACcAAAAnCAMAAAC7faEHAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAzUExURQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAKMFRskAAAAQdFJOUwAQIDBAUGBwgI+fr7/P3+8jGoKKAAAACXBIWXMAAA7DAAAOwwHHb6hkAAABT0lEQVQ4T7XT2ZalIAwF0DAJhMH+/6+tJOQqot6X6joPiouNBo3w9/Hd6+hrYnUt6vhLcjEAJevVW0zJxABSlcunhERpjY+UKoNN5+ZgDGu2onNz0OngjP2FM1VdyBW1LtvGeYrBLs7U5I1PTXZt+zifcS3Icw2GcS3vxRY3Vn/iqx31hUyTnV515kdTfbaNhZLI30AceqDiIo4tyKEmJpKdP5M4um+nUwfDWxAXdzqMNKQ14jLdL5ntXzxcRF440mhS6yu882Kxa30RZcUIjTCJg7lscsR4VsMjfX9Q0Vuv/Wd3YosD1J4LuSRtaL7bzXGN1wx2cytUdncDuhA3fu6HPTiCvpQUIjZ3sCcHVbvLtbNTHlysx2w9/s27m9gEb+7CTri6hR1wcTf2gVf3wBRe3CMbcHYvTODkXhnD0+178K/pZ9+n/C1ru/2HAPwAo7YM1X4+tLMAAAAASUVORK5CYII=";

    // Get the currently selected From account.
    item.from.getAsync({ asyncContext: event }, (result) => {
        if (result.status === Office.AsyncResultStatus.Failed) {
            console.log(result.error.message);
            return;
        }

        // Create a signature based on the currently selected From account.
        const name = result.value.displayName;
        const options = { asyncContext: { event: result.asyncContext, name: name }, isInline: true };
        item.addFileAttachmentFromBase64Async(signatureIcon, "signatureIcon.png", options, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                console.log(result.error.message);
                return;
            }

            // Add the created signature to the mail item.
            const signature = "<img src='cid:signatureIcon.png'>" + result.asyncContext.name;
            item.body.setSignatureAsync(
                signature,
                { asyncContext: result.asyncContext.event, coercionType: Office.CoercionType.Html },
                addSignatureCallback
            );
        });
    });
}

// Callback function to add a signature to the mail item.
function addSignatureCallback(result) {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.log(result.error.message);
        return;
    }

    console.log("Successfully added signature.");
    result.asyncContext.completed();
}

// IMPORTANT: To ensure your add-in is supported in the Outlook client on Windows, remember to 
// map the event handler name specified in the manifest's LaunchEvent element (with the XML manifest)
// or the "autoRunEvents.events.actionId" property (with the unified manifest for Microsoft 365)
// to its JavaScript counterpart.
if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
    Office.actions.associate("onNewMessageComposeHandler", onNewMessageComposeHandler);
    Office.actions.associate("onMessageFromChangedHandler", onMessageFromChangedHandler);
}

Importante

Windows: no momento, as importações não têm suporte no arquivo JavaScript em que você implementa o tratamento para ativação baseada em eventos.

Dica

Os suplementos baseados em eventos em execução no Outlook no Windows não executam o código incluído nas Office.onReady() funções e Office.initialize . Recomendamos adicionar sua lógica de inicialização de suplemento, como verificar a versão do Outlook do usuário, aos manipuladores de eventos.

Atualizar o arquivo HTML de comandos

  1. Na pasta ./src/commands , abra commands.html.

  2. Adicione o código a seguir abaixo da marca de script existente.

    <script type="text/javascript" src="../launchevent/launchevent.js"></script>

  3. Salve suas alterações.

Atualizar as configurações webpack config

  1. No diretório raiz do projeto, abra o arquivo webpack.config.js .

  2. Localize a plugins matriz dentro do config objeto e adicione o novo objeto a seguir ao início da matriz.

    new CopyWebpackPlugin({
  patterns: [
    {
      from: "./src/launchevent/launchevent.js",
      to: "launchevent.js",
    },
  ],
}),

  3. Salve suas alterações.

Experimente

  1. Execute os comandos a seguir no diretório raiz do seu projeto. Quando você executar npm start, o servidor Web local será iniciado (se ainda não estiver em execução) e o suplemento será sideload.

    npm run build

    npm start

    Observação

    Se o suplemento não tiver sido carregado automaticamente, siga as instruções nos suplementos do Sideload Outlook para testar para carregar manualmente o suplemento no Outlook.

  2. No cliente preferido do Outlook, crie uma nova mensagem. Se você não tiver uma assinatura padrão do Outlook configurada, o suplemento adicionará uma à mensagem recém-criada.

    Uma assinatura de exemplo adicionada a uma mensagem recém-composta quando uma assinatura padrão do Outlook não está configurada na conta.

  3. Habilite o campo De , se aplicável. Para obter diretrizes sobre como habilitá-lo, consulte a seção "Por que o botão De está ausente?" de Alterar a conta usada para enviar mensagens de email.

  4. Selecione Entre e escolha uma conta do Exchange diferente. Como alternativa, insira manualmente o endereço de email do Exchange selecionando De>Outros Email Endereço. Uma assinatura atualizada é adicionada à mensagem, substituindo a anterior.

    Um exemplo de uma assinatura atualizada com um logotipo quando a conta no campo De é alterada.

Solucionar problemas do suplemento

Para obter diretrizes sobre como solucionar problemas do suplemento de ativação baseado em evento, consulte Solucionar problemas de suplementos baseados em eventos e de relatório de spam.

Implantar em usuários

Semelhante a outros suplementos baseados em eventos, os suplementos que usam os OnMessageFromChanged eventos e OnAppointmentFromChanged devem ser implantados pelo administrador de uma organização. Para obter diretrizes sobre como implantar seu suplemento por meio do Centro de administração do Microsoft 365, consulte a seção "Implantar para usuários" de Configurar seu suplemento do Outlook para ativação baseada em eventos.

Comportamento e limitações de evento

Como os OnMessageFromChanged eventos e OnAppointmentFromChanged têm suporte por meio do recurso de ativação baseado em evento, o mesmo comportamento e limitações se aplicam a suplementos que são ativados como resultado desse evento. Para obter uma descrição detalhada, consulte Comportamento e limitações de ativação baseados em eventos.

Além dessas características, os seguintes aspectos também se aplicam quando um suplemento é ativado nesses eventos.

  • O OnMessageFromChanged evento só tem suporte no modo de composição de mensagens, enquanto o OnAppointmentFromChanged evento só tem suporte no modo de composição de compromisso.
  • No Outlook no Windows, há suporte apenas para o OnMessageFromChanged evento.
  • Os OnMessageFromChanged eventos e OnAppointmentFromChanged dão suporte apenas a contas do Exchange. Nas mensagens que estão sendo compostas, a conta do Exchange é selecionada na lista suspensa Do campo ou inserida manualmente no campo. Em compromissos que estão sendo compostos, a conta do Exchange é selecionada na lista suspensa do campo organizador. Se um usuário alternar para uma conta que não seja exchange no campo De ou organizador, o cliente do Outlook limpará automaticamente a assinatura definida pela conta selecionada anteriormente.
  • Há suporte para cenários de delegação e caixa de correio compartilhada.
  • O OnAppointmentFromChanged evento não tem suporte em calendários de grupo do Microsoft 365. Se um usuário mudar de sua conta do Exchange para uma conta de calendário de grupo do Microsoft 365 no campo organizador, o cliente do Outlook limpará automaticamente a assinatura definida pela conta do Exchange.
  • Ao alternar para outra conta do Exchange no campo De ou organizador, os suplementos da conta selecionada anteriormente, se houver, são encerrados e os suplementos associados à conta recém-selecionada são carregados antes do OnMessageFromChanged evento ou OnAppointmentFromChanged ser iniciado.
  • Email aliases de conta têm suporte. Quando um alias para a conta atual é selecionado no campo De ou organizador, o OnMessageFromChanged evento ou OnAppointmentFromChanged ocorre sem recarregar os suplementos da conta.
  • Quando a lista suspensa Do ou do campo organizador é aberta por engano ou a mesma conta que aparece no campo De ou organizador é reelecionada, o OnMessageFromChanged evento ou OnAppointmentFromChanged ocorre, mas os suplementos da conta não são encerrados ou recarregados.

Confira também