Функция проверки при отправке для надстроек Outlook

Функция при отправке для надстроек Outlook позволяет обрабатывать сообщение или элемент собрания, а также блокировать пользователей от определенных действий, а надстройка может задавать определенные свойства при отправке.

Например, используйте функцию при отправке, чтобы:

• запретить пользователю отправлять конфиденциальную информацию или оставлять строку темы пустой;
• добавить определенного получателя в строку "Копия" в сообщениях или в строку "Необязательные получатели" в собраниях.

Функция проверки при отправке не использует пользовательский интерфейс и активируется событием типа ItemSend.

Сведения об ограничениях, связанных с функцией проверки при отправке, см. в разделе Ограничения далее в этой статье.

Поддерживаемые клиенты и платформы

В следующей таблице показаны поддерживаемые сочетания клиента и сервера для функции при отправке, включая минимальное требуемое накопительное обновление, если применимо. Исключенные сочетания не поддерживаются.

Как работает функция проверки при отправке?

С помощью функции проверки при отправке вы можете создать надстройку Outlook, задействующую синхронное событие ItemSend. Это событие возникает, когда пользователь нажимает кнопку Отправить (или Отправить обновление для существующих собраний). С его помощью можно блокировать отправку элемента, не прошедшего проверку. Например, когда пользователь вызывает событие отправки сообщения, надстройка Outlook благодаря функции проверки при отправке может следующее:

• Чтение и проверка содержимого сообщения электронной почты.
• Убедитесь, что сообщение содержит строку темы.
• Задайте предопределенного получателя.

Проверка выполняется на стороне клиента в Outlook при активации события отправки, а время ожидания надстройки составляет до 5 минут. Если проверка завершается ошибкой, отправка элемента блокируется, а сообщение об ошибке отображается на панели сведений, которая предлагает пользователю принять меры.

На приведенном ниже снимке экрана показана панель информации, в которой пользователю предлагается добавить тему.

На приведенном ниже снимке экрана показана панель информации, уведомляющая отправителя о том, что обнаружены слова, подлежащие блокировке.

Ограничения

В настоящее время на функцию проверки при отправке действуют перечисленные ниже ограничения.

• Функция добавления при отправке — при вызове item.body.AppendOnSendAsync в обработчике при отправке возвращается ошибка.

• AppSource — вы не можете опубликовать надстройки Outlook, использующие функцию отправки, в AppSource , так как они не пройдут проверку AppSource. Надстройки, использующие функцию проверки при отправке, должны разворачиваться администраторами. Если вы хотите опубликовать надстройку в AppSource, рассмотрите возможность использования смарт-оповещений, которая является более новой версией функции при отправке. Дополнительные сведения о смарт-оповещениях и развертывании этих надстроек см. в разделах Использование смарт-оповещений и событий OnMessageSend и OnAppointmentSend в надстройке Outlook и параметров описания AppSource для надстройки Outlook на основе событий.

  Важно!

  При запуске npm run validate для проверки манифеста надстройки вы получите сообщение об ошибке "Надстройка почтового ящика, содержащая событие ItemSend, является недопустимым. Манифест надстройки почтового ящика содержит событие ItemSend в VersionOverrides, которое запрещено". Это сообщение появляется, так как надстройки, использующие ItemSend событие, необходимое для этой версии функции при отправке, не могут быть опубликованы в AppSource. Вы по-прежнему сможете загрузить и запустить надстройку при условии, что другие ошибки проверки не найдены.

• Манифест — для каждой надстройки поддерживается только одно ItemSend событие. Если манифест содержит несколько событий ItemSend, он не пройдет проверку.

• Производительность . Несколько циклов на веб-сервер, на котором размещена надстройка, могут повлиять на производительность надстройки. Рассмотрите влияние на производительность при создании надстроек, для которых требуется несколько операций на основе сообщений или собраний.

• Отправить позже (только для Mac) — если есть надстройки при отправке, функция Отправить позже будет недоступна.

Кроме того, не рекомендуется вызывать item.close() в обработчике событий при отправке, так как закрытие элемента должно происходить автоматически после завершения события.

Ограничения на типы и режимы почтовых ящиков

Функциональность при отправке поддерживается только для почтовых ящиков пользователей в Outlook в Интернете, Windows (новая и классическая версия) и Mac. В дополнение к ситуациям, когда надстройки не активируются, как указано в разделе Элементы почтовых ящиков, доступные для надстроек на странице обзора надстроек Outlook, эта функция в настоящее время не поддерживается для автономного режима, где этот режим доступен.

В случаях, когда надстройки Outlook не активируются, надстройка при отправке не запускается и сообщение будет отправлено.

Однако если функция при отправке включена и доступна, но сценарий почтового ящика не поддерживается, Outlook не разрешит отправку.

Несколько надстроек, поддерживающих проверку сообщений при отправке

Если установлено несколько надстроек, поддерживающих проверку сообщений при отправке, они будут запускаться в том порядке, в котором были получены из API getAppManifestCall или getExtensibilityContext. Если первая надстройка разрешает отправку сообщения, то вторая может внести изменения, на которые первая отреагировала бы запретом отправки. Однако первая надстройка не будет запускаться снова, если все установленные надстройки разрешат отправку.

Допустим, надстройка 1 и надстройка 2 используют функцию проверки при отправке. Сначала устанавливается надстройка 1, а затем — надстройка 2. Надстройка 1 находит в сообщении слово Fabrikam, что является условием для разрешения отправки. Однако надстройка 2 удаляет все вхождения слова Fabrikam. Сообщение будет отправлено без единого слова Fabrikam (в связи с порядком установки надстроек 1 и 2).

Развертывание надстроек Outlook, использующих функцию проверки при отправке

Рекомендуем, чтобы развертывание надстроек Outlook, использующих функцию проверки при отправке, выполняли администраторы. Администратор должен убедиться, что такая надстройка:

• всегда присутствует при открытии создаваемого элемента (для электронной почты: создание сообщений, ответ и пересылка);
• не может быть закрыта или отключена пользователем.

Установка надстроек Outlook, использующих функцию проверки при отправке

Чтобы использовать функцию проверки при отправке в Outlook, надстройки должны быть настроены для типов событий отправки. Выберите платформу, которую нужно настроить.

$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

Сценарии проверки при отправке

Ниже представлены поддерживаемые и неподдерживаемые сценарии для надстроек, использующих функцию проверки при отправке.

Обработчики событий определяются динамически

Обработчики событий надстройки должны быть определены по времени Office.initialize или Office.onReady() вызову (дополнительные сведения см. в разделах Запуск надстройки Outlook и Инициализация надстройки Office). Если код обработчика динамически определяется определенными обстоятельствами во время инициализации, необходимо создать функцию-заглушку для вызова обработчика после его полного определения. На функцию-заглушку необходимо ссылаться в <атрибуте элемента Event> манифеста FunctionName . Это решение гарантирует, что обработчик определен и готов к ссылке один раз Office.initialize или Office.onReady() выполняется.

Если обработчик не определен после инициализации надстройки, отправитель получит уведомление о том, что функция обратного вызова недоступна, через информационную панель в почтовом элементе.

В почтовом ящике пользователя включена функция проверки при отправке, но не установлено ни одной надстройки

В этом сценарии пользователь сможет отправлять сообщения и элементы собрания без выполнения надстроек.

В почтовом ящике пользователя включена функция проверки при отправке, а также установлены и включены надстройки, поддерживающие эту функцию

При отправке будут запускаться надстройки, которые разрешат или заблокируют отправку.

Делегирование для почтовых ящиков, при котором у почтового ящика 1 есть разрешения на полный доступ к почтовому ящику 2

Веб-браузер (классическая версия Outlook)

Веб-браузер (современная версия Outlook), Windows, Mac

Чтобы внедрить функцию проверки при отправке, администраторы должны включить политику для обоих почтовых ящиков. Сведения о поддержке делегирования доступа в надстройке см. в статье Включение общих папок и сценариев общих почтовых ящиков.

Включен почтовый ящик пользователя с функцией или политикой проверки при отправке, установлены и включены надстройки, поддерживающие эту функцию, а также включен автономный режим

Надстройки, поддерживающие проверку при отправке, запускаются в соответствии с сетевым состоянием пользователя, внутреннего сервера надстройки и Exchange.

Состояние пользователя

Надстройки, поддерживающие проверку сообщений при отправке, будут запускаться при отправке, если пользователь в сети. В автономном режиме такие надстройки не будут запускаться при отправке, а сообщение или элемент собрания не будет отправлен.

Состояние внутреннего сервера надстройки

Надстройка, поддерживающая проверку при отправке, будет запускаться, если ее внутренний сервер подключен к сети и доступен. Если внутренний сервер находится в автономном режиме, отправка отключена.

Состояние Exchange

Надстройки, поддерживающие проверку сообщений при отправке, будут запускаться при отправке, если сервер Exchange подключен к сети и доступен. Если надстройке с функцией проверки при отправке недоступна служба Exchange и включена соответствующая политика или командлет, отправка отключена.

Пользователь может редактировать элемент, пока над ним работают надстройки при отправке

Пока надстройки при отправке обрабатывают элемент, пользователь может изменить его, добавив, например, недопустимый текст или вложения. Если вы хотите запретить пользователю редактировать элемент во время обработки надстройки при отправке, можно реализовать обходной путь с помощью диалогового окна. Это решение можно использовать в Outlook в Интернете (классическая версия), Windows (классическая версия) и Mac.

В обработчике при отправке:

1. Вызовите displayDialogAsync , чтобы открыть диалоговое окно, чтобы отключать щелчки мышью и нажатия клавиш.

   Важно!

   Чтобы получить такое поведение в классической Outlook в Интернете, необходимо задать для свойства displayInIframe значениеtrue в options параметре displayDialogAsync вызова.

2. Реализуйте обработку элемента.

3. Закройте диалоговое окно. Кроме того, обработайте, что происходит, если пользователь закроет диалоговое окно.

Примеры кода

В приведенных ниже примерах кода показано, как создать простую надстройку, поддерживающую проверку сообщений при отправке. Скачать код, на котором основаны эти примеры, можно на странице Outlook-Add-in-On-Send.

Манифест, переопределение версии и событие

Пример кода Outlook-Add-in-On-Send включает два манифеста:

• Contoso Message Body Checker.xml— показывает, как проверка текст сообщения для слов с ограниченным доступом или конфиденциальной информации при отправке.

• Contoso Subject and CC Checker.xml — Показывает, как добавить получателя в строку cc и убедиться, что сообщение содержит строку темы при отправке.

В файле манифеста Contoso Message Body Checker.xml указываются файл и имя функции, которую следует вызывать при возникновении события ItemSend. Операция выполняется синхронно.

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

Для файла манифеста Contoso Subject and CC Checker.xml в приведенном ниже примере показаны файл и имя функции, вызываемой при возникновении события отправки.

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

Для API проверки при отправке требуется узел VersionOverrides v1_1. Ниже показано, как добавить узел VersionOverrides в манифест.

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

Объекты Event и item, методы body.getAsync и body.setAsync

Чтобы получить доступ к выбранному в данный момент сообщению или элементу собрания (в этом примере — к новому сообщению), используйте пространство имен Office.context.mailbox.item. Событие ItemSend автоматически передается функцией при отправке в функцию, указанную в манифесте validateBody , — в этом примере функция.

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

Функция validateBody получает текущий текст в указанном формате (HTML) и передает ItemSend объект события, к которому код хочет получить доступ в функции обратного вызова. Помимо метода getAsync, объект Body также предоставляет метод setAsync, с помощью которого вы можете заменить текст сообщения на указанный.

Объект NotificationMessages и метод event.completed

Функция checkBodyOnlyOnSendCallBack использует регулярное выражение, чтобы определить, содержит ли текст сообщения слова, подлежащие блокировке. Если она обнаруживает слово, совпадающие с каким-либо элементом из массива запрещенных слов, отправка сообщения блокируется, а отправитель получает уведомление на панели информации. Для этого он использует notificationMessages свойство объекта для Item возврата объекта NotificationMessages . После этого она добавляет уведомление к элементу, вызывая метод addAsync, как показано в следующем примере.

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

Ниже приведены параметры метода addAsync .

• NoSend — строка, которая является ключом, заданным разработчиком, для ссылки на сообщение уведомления. С его помощью вы сможете изменить это сообщение позже. Значение клавиши не может превышать 32 символа.
• type — одно из свойств параметра объекта JSON. Представляет тип сообщения. Типы соответствуют значениям перечисления Office.MailboxEnums.ItemNotificationMessageType. Допустимые значения: индикатор хода выполнения, информационное сообщение и сообщение об ошибке. В этом примере в свойстве type указано сообщение об ошибке.
• message — одно из свойств параметра объекта JSON. В этом примере message — это текст сообщения уведомления.

Чтобы сообщить о том, что надстройка завершила обработку ItemSend события, вызванного операцией отправки, вызовите метод event.completed({allowEvent:Boolean}). Свойство allowEvent относится к логическому типу. Если задано значение true, отправка разрешается. Если задано значение false, отправка письма блокируется.

Методы replaceAsync, removeAsync и getAllAsync

Помимо метода addAsync, объект NotificationMessages также включает методы replaceAsync, removeAsync и getAllAsync. Эти методы не используются в данном примере кода. Дополнительные сведения см. в статье NotificationMessages.

Код проверки строк "Тема" и "Копия"

В приведенном ниже примере кода показано, как при отправке сообщения добавить получателя в строку "Копия" и проверить, включает ли сообщение тему. В этом примере функция проверки при отправке используется, чтобы разрешить или запретить отправку сообщения.

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

Дополнительные сведения о том, как добавить получателя в строку cc и убедиться, что сообщение электронной почты содержит строку темы при отправке, а также просмотреть API, которые можно использовать, см. в примере Outlook-Add-in-On-Send. Код хорошо прокомментирован.

Отладка надстроек Outlook, использующих при отправке

Инструкции по отладке надстройки при отправке см . в разделе Отладка команд функций в надстройках Outlook.

См. также

• Обзор архитектуры и функций надстроек Outlook
• Надстройка Outlook "Демонстрация команд надстройки"