Preparar ou acrescentar conteúdo a um corpo de mensagem ou compromisso no envio

  • Artigo

Os recursos prepend-on-send e append-on-send permitem que o suplemento do Outlook insira conteúdo no corpo de uma mensagem ou compromisso quando o item de email é enviado. Esses recursos aumentam ainda mais a produtividade e a segurança dos usuários, permitindo que eles:

  • Adicione rótulos de confidencialidade e classificação às mensagens e compromissos para facilitar a identificação e a organização do item.
  • Insira avisos de isenção de responsabilidade para fins legais.
  • Adicione cabeçalhos padronizados para fins de marketing e comunicação.

Neste passo a passo, você desenvolverá um suplemento que prepara um cabeçalho e acrescenta um aviso de isenção de responsabilidade quando uma mensagem é enviada.

Observação

O suporte para o recurso append-on-send foi introduzido no conjunto de requisitos 1.9, enquanto o suporte para o recurso prepend-on-send foi introduzido no conjunto de requisitos 1.13. Consulte clientes e plataformas que dão suporte a esses conjuntos de requisitos.

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

Para configurar o manifesto, selecione a guia para o tipo de manifesto que você usará.

O seguinte mostra como configurar o manifesto unificado para habilitar os recursos de pré-envio e acrescentação em envio.

  1. Abra o arquivo manifest.json .

  2. Adicione o objeto a seguir à matriz "extensions.runtimes". Observe o seguinte sobre este código.

    • A "minVersion" do conjunto de requisitos da caixa de correio é definida como "1.13", portanto, o suplemento não pode ser instalado em plataformas e versões do Office em que esse recurso não tem suporte.
    • A "id" do runtime é definida como o nome descritivo , "function_command_runtime".
    • A propriedade "code.page" é definida como a URL do arquivo HTML sem interface do usuário que carregará o comando de função.
    • A propriedade "lifetime" é definida como "curta", o que significa que o runtime é iniciado quando o botão de comando da função é selecionado e é desligado quando a função é concluída. (Em certos casos raros, o runtime é desligado antes da conclusão do manipulador. Consulte Runtimes em Suplementos do Office.)
    • Há ações especificadas para executar as funções "prependHeaderOnSend" e "appendDisclaimerOnSend". Você criará essas funções em uma etapa posterior.
    {
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.13"
            }
        ],
        "formFactors": [
            "desktop"
        ]
    },
    "id": "function_command_runtime",
    "type": "general",
    "code": {
        "page": "https://localhost:3000/commands.html"
    },
    "lifetime": "short",
    "actions": [
        {
            "id": "prependHeaderOnSend",
            "type": "executeFunction",
            "displayName": "prependHeaderOnSend"
        },
        {
            "id": "appendDisclaimerOnSend",
            "type": "executeFunction",
            "displayName": "appendDisclaimerOnSend"
        }
    ]
}

  3. Adicione o objeto a seguir à matriz "extensions.ribbons". Observe o seguinte sobre este código.

    • O valor "mailCompose" é adicionado à matriz "contextos" para exibir os botões prepend-on-send e append-on-send em uma janela de composição.
    • Os objetos "controles" criam e configuram os botões para as funções prepend-on-send e append-on-send. A propriedade "actionId" de cada objeto deve refletir o mesmo valor especificado na propriedade "actions.id" aplicável do objeto "extensions.runtimes".
    {
    "contexts": [
        "mailCompose"
    ],
    "tabs": [
        {
            "builtInTabId": "TabDefault",
            "groups": [
                {
                    "id": "msgComposeGroup",
                    "label": "Contoso Add-in",
                    "icons": [
                        {
                            "size": 16,
                            "url" "https://localhost:3000/assets/icon-16.png"
                        },
                        {
                            "size": 32,
                            "url" "https://localhost:3000/assets/icon-32.png"
                        },
                        {
                            "size": 80,
                            "url" "https://localhost:3000/assets/icon-80.png"
                        }
                    ],
                    "controls": [
                        {
                            "id": "PrependButton",
                            "type": "button",
                            "label": "Prepend header on send",
                            "icons": [
                                {
                                    "size": 16,
                                    "url" "https://localhost:3000/assets/icon-16.png"
                                },
                                {
                                    "size": 32,
                                    "url" "https://localhost:3000/assets/icon-32.png"
                                },
                                {
                                    "size": 80,
                                    "url" "https://localhost:3000/assets/icon-80.png"
                                }
                            ],
                            "supertip": {
                                "title": "Prepend header on send",
                                "description": "Prepend the Contoso header on send."
                            },
                            "actionId": "prependHeaderOnSend"
                        },
                        {
                            "id": "AppendButton",
                            "type": "button",
                            "label": "Append disclaimer on send",
                            "icons": [
                                {
                                    "size": 16,
                                    "url" "https://localhost:3000/assets/icon-16.png"
                                },
                                {
                                    "size": 32,
                                    "url" "https://localhost:3000/assets/icon-32.png"
                                },
                                {
                                    "size": 80,
                                    "url" "https://localhost:3000/assets/icon-80.png"
                                }
                            ],
                            "supertip": {
                                "title": "Append disclaimer on send",
                                "description": "Append the Contoso disclaimer on send."
                            },
                            "actionId": "appendDisclaimerOnSend"
                        }
                    ]
                }
            ]
        }
    ]
}

  4. Na matriz "authorization.permissions.resourceSpecific", adicione o objeto a seguir. Certifique-se de que ele está separado de outros objetos na matriz com uma vírgula.

    {
  "name": "Mailbox.AppendOnSend.User",
  "type": "Delegated"
}

  5. Salve suas alterações.

Dica

  • Os recursos prepend-on-send e append-on-send devem ser ativados pelo usuário por meio de um painel de tarefas ou botão de comando de função. Se você quiser que o conteúdo seja pré-acrescentado ou acrescentado no envio sem ação adicional do usuário, você poderá implementar esses recursos em um suplemento de ativação baseado em evento.
  • Para saber mais sobre manifestos para suplementos do Outlook, confira Manifestos de suplementos do Office.

Implementar o manipulador prepend-on-send

Nesta seção, você implementará o código JavaScript para preparar um cabeçalho da empresa de exemplo para um item de email quando ele for enviado.

  1. Navegue até a pasta ./src/commands do seu projeto e abra o arquivo commands.js .

  2. Insira a função a seguir no final do arquivo.

    function prependHeaderOnSend(event) {
  // It's recommended to call the getTypeAsync method and pass its returned value to the options.coercionType parameter of the prependOnSendAsync call.
  Office.context.mailbox.item.body.getTypeAsync(
    {
      asyncContext: event
    },
    (asyncResult) => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
      }

      // Sets the header to be prepended to the body of the message on send.
      const bodyFormat = asyncResult.value;
      // Because of the various ways in which HTML text can be formatted, the content may render differently when it's prepended to the mail item body.
      // In this scenario, a <br> tag is added to the end of the HTML string to preserve its format.
      const header = '<div style="border:3px solid #000;padding:15px;"><h1 style="text-align:center;">Contoso Limited</h1></div><br>';

      Office.context.mailbox.item.body.prependOnSendAsync(
        header,
        {
          asyncContext: asyncResult.asyncContext,
          coercionType: bodyFormat
        },
        (asyncResult) => {
          if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            console.log(asyncResult.error.message);
            return;
          }

          console.log("The header will be prepended when the mail item is sent.");
          asyncResult.asyncContext.completed();
        }
      );
  });
}

  3. Salve suas alterações.

Implementar o manipulador de anexos em envio

Nesta seção, você implementará o código JavaScript para acrescentar uma isenção de responsabilidade da empresa de exemplo a um item de email quando ele for enviado.

  1. No mesmo arquivocommands.js , insira a função a seguir após a prependHeaderOnSend função.

    function appendDisclaimerOnSend(event) { 
  // Calls the getTypeAsync method and passes its returned value to the options.coercionType parameter of the appendOnSendAsync call.
  Office.context.mailbox.item.body.getTypeAsync(
    {
      asyncContext: event
    }, 
    (asyncResult) => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
    }

    // Sets the disclaimer to be appended to the body of the message on send.
    const bodyFormat = asyncResult.value;
    const disclaimer =
      '<p style = "color:blue"> <i>This and subsequent emails on the same topic are for discussion and information purposes only. Only those matters set out in a fully executed agreement are legally binding. This email may contain confidential information and should not be shared with any third party without the prior written agreement of Contoso. If you are not the intended recipient, take no action and contact the sender immediately.<br><br>Contoso Limited (company number 01624297) is a company registered in England and Wales whose registered office is at Contoso Campus, Thames Valley Park, Reading RG6 1WG</i></p>';  

    Office.context.mailbox.item.body.appendOnSendAsync(
      disclaimer,
      {
        asyncContext: asyncResult.asyncContext,
        coercionType: bodyFormat
      },
      (asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
          console.log(asyncResult.error.message);
          return;
        }

        console.log("The disclaimer will be appended when the mail item is sent.");
        asyncResult.asyncContext.completed();
      }
    );
  });
}

  2. Salve suas alterações.

Registrar as funções JavaScript

  1. No mesmo arquivocommands.js , insira o seguinte após a appendDisclaimerOnSend função. Essas chamadas mapeiam o nome da função especificado no manifesto para seu equivalente JavaScript. O local do nome da função no manifesto varia dependendo do tipo de manifesto que seu suplemento usa.

  • Manifesto XML: o nome da função especificado no <elemento FunctionName> .

  • Manifesto unificado para o Microsoft 365: o nome da função especificado na propriedade "id" dos objetos na matriz "extensions.runtimes.actions".

    Office.actions.associate("prependHeaderOnSend", prependHeaderOnSend);
Office.actions.associate("appendDisclaimerOnSend", appendDisclaimerOnSend);
  1. Salve suas alterações.

Experimente

  1. Execute o seguinte comando no diretório raiz do seu projeto. Quando você executar esse comando, o servidor Web local será iniciado se ele ainda não estiver em execução e seu suplemento for sideload.

    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. Crie uma nova mensagem e adicione-se à linha To .

  3. (Opcional) Insira texto no corpo da mensagem.

  4. No menu faixa de opções ou estouro, selecione Cabeçalho Prepend.

  5. No menu faixa de opções ou estouro, selecione Aviso de adição de acréscimo.

  6. Envie a mensagem e abra-a na caixa de entrada ou na pasta Itens Enviados para exibir o conteúdo inserido.

    Um exemplo de uma mensagem enviada com o cabeçalho Contoso pré-acrescentado e o aviso de isenção de responsabilidade acrescentado ao seu corpo.

    Dica

    Como o conteúdo só é pré-acrescentado ou acrescentado quando a mensagem é enviada, o remetente só poderá exibir o conteúdo adicionado da pasta Caixa de Entrada ou Itens Enviados . Se você exigir que o remetente exiba o conteúdo adicionado antes do envio da mensagem, consulte Inserir dados no corpo ao compor um compromisso ou mensagem no Outlook.

Examinar o comportamento e as limitações do recurso

Ao implementar prepend-on-send e append-on-send em seu suplemento, tenha o seguinte em mente.

  • O prepend-on-send e o append-on-send só têm suporte no modo de composição.

  • A cadeia de caracteres a ser pré-acrescentada ou acrescentada não deve exceder 5.000 caracteres.

  • HTML não pode ser pré-acrescentado ou acrescentado a um corpo de texto simples de uma mensagem ou compromisso. No entanto, o texto simples pode ser adicionado a um corpo formatado por HTML de uma mensagem ou compromisso.

  • Qualquer formatação aplicada ao conteúdo pré-acrescentado ou acrescentado não afeta o estilo do restante do corpo do item de email.

  • Prepend-on-send e append-on-send não podem ser implementados no mesmo suplemento que implementa o recurso de envio. Como alternativa, considere implementar alertas inteligentes .

  • Ao implementar alertas inteligentes no mesmo suplemento, as operações prepend-on-send e append-on-send ocorrem antes das operações do OnMessageSend manipulador de eventos e OnAppointmentSend .

  • Se vários suplementos ativos usarem prepend-on-send ou append-on-send, a ordem do conteúdo a ser inserido dependerá da ordem na qual o suplemento foi executado. Para prepend-on-send, o conteúdo do suplemento que é executado por último aparece na parte superior do corpo do item de email antes do conteúdo previamente pré-configurado. Para anexo-em-envio, o conteúdo do suplemento que é executado por último aparece na parte inferior do corpo do item de email após o conteúdo acrescentado anteriormente.

  • Há suporte para cenários de delegação e caixa de correio compartilhada, desde que o suplemento que implementa prepend-on-send ou append-on-send esteja habilitado na caixa de correio compartilhada ou na conta do proprietário.

Solucionar problemas do suplemento

Se você encontrar um erro ao implementar os recursos prepend-on-send e append-on-send, consulte a tabela a seguir para obter diretrizes.

Erro Descrição Solução
DataExceedsMaximumSize O conteúdo a ser acrescentado ou pré-acrescentado é maior que 5.000 caracteres. Encurte a cadeia de caracteres que você passa para o data parâmetro de sua prependOnSendAsync chamada ou appendOnSendAsync .
InvalidFormatError O corpo da mensagem ou nomeação está em formato de texto simples, mas o coercionType passado para o prependOnSendAsync método ou appendOnSendAsync é definido como Office.CoercionType.Html. Somente texto simples pode ser inserido em um corpo de texto simples de uma mensagem ou compromisso. Para verificar o formato do item de email que está sendo composto, chame Office.context.mailbox.item.body.getTypeAsync, em seguida, passe o valor retornado para sua prependOnSendAsync ou appendOnSendAsync chamada.

Confira também