Característica de envío para complementos de Outlook

La característica de envío para complementos de Outlook proporciona una manera de controlar un mensaje o elemento de reunión, o bloquear a los usuarios de determinadas acciones, y permite que un complemento establezca ciertas propiedades en el envío.

Por ejemplo, use la característica de envío a:

• Evitar que un usuario envíe información confidencial o deje la línea del asunto en blanco.
• Agregue un destinatario específico a la línea CC de mensajes o a la línea de destinatarios opcionales en las reuniones.

La característica de envío se activa mediante la función ItemSend tipo de evento y no tiene interfaz de usuario.

Para obtener información sobre las limitaciones relacionadas con la característica de envío, vea Limitaciones posteriormente en este artículo.

Plataformas y clientes admitidos

En la tabla siguiente se muestran las combinaciones de cliente y servidor admitidas para la característica de envío, incluida la actualización acumulativa mínima necesaria cuando corresponda. No se admiten combinaciones excluidas.

¿Cómo funciona la característica de envío?

Puede usar la característica de envío para crear un complemento de Outlook que integre el evento sincrónico ItemSend. Este evento detecta que el usuario pulsa el botón Enviar (o el botón Enviar actualización para las reuniones existentes) y se puede usar para bloquear el envío del elemento si se produce un error de validación. Por ejemplo, cuando un usuario desencadena un evento de envío de mensajes, un complemento de Outlook que use la característica de envío puede:

• Lea y valide el contenido del mensaje de correo electrónico.
• Compruebe que el mensaje incluye una línea de asunto.
• Establezca un destinatario predeterminado.

La validación se realiza en el lado cliente en Outlook cuando se desencadena el evento de envío y el complemento tiene hasta 5 minutos antes de que se agote el tiempo de espera. Si se produce un error en la validación, se bloquea el envío del elemento y se muestra un mensaje de error en una barra de información que pide al usuario que realice una acción.

En la siguiente captura de pantalla se muestra una barra de información que notifica al remitente que agregue un asunto.

En la siguiente captura de pantalla se muestra una barra de información que notifica al remitente que se han detectado palabras bloqueadas.

Limitaciones

En estos momentos, la característica de envío tiene las siguientes limitaciones:

• Característica append-on-send : si llama a item.body.AppendOnSendAsync en el controlador de envío, se devuelve un error.

• AppSource : no puede publicar complementos de Outlook que usen la característica de envío a AppSource , ya que producirán un error en la validación de AppSource. Los complementos que usan la característica de envío deben ser implementados por los administradores. Si desea que la opción publique el complemento en AppSource, considere la posibilidad de usar alertas inteligentes en su lugar, que es una versión más reciente de la característica de envío. Para obtener más información sobre las alertas inteligentes y cómo implementar estos complementos, consulte Usar alertas inteligentes y los eventos OnMessageSend y OnAppointmentSend en el complemento de Outlook y las opciones de lista de AppSource para el complemento de Outlook basado en eventos.

  Importante

  Al ejecutar npm run validate para validar el manifiesto del complemento, recibirá el error "El complemento de buzón que contiene el evento ItemSend no es válido. El manifiesto de complemento de buzón contiene un evento ItemSend en VersionOverrides que no está permitido". Este mensaje aparece porque los complementos que usan el ItemSend evento, que es necesario para esta versión de la característica de envío, no se pueden publicar en AppSource. Seguirá siendo capaz de transferir localmente y ejecutar el complemento, siempre que no se encuentren otros errores de validación.

• Manifiesto : solo se admite un ItemSend evento por complemento. Si tiene dos o más eventos ItemSend en un manifiesto, el manifiesto producirá un error en la validación.

• Rendimiento : varios recorridos de ida y vuelta al servidor web que hospeda el complemento pueden afectar al rendimiento del complemento. Tenga en cuenta los efectos en el rendimiento al crear complementos que requieren varias operaciones basadas en mensajes o reuniones.

• Enviar más tarde (solo Mac): si hay complementos de envío, la característica Enviar posterior no estará disponible.

Además, no se recomienda llamar al item.close() controlador de eventos al enviar, ya que el cierre del elemento debe producirse automáticamente una vez completado el evento.

Limitaciones del modo o tipo de buzón

La funcionalidad de envío solo se admite para buzones de usuario en Outlook en la Web, Windows (nuevo y clásico) y Mac. Además de las situaciones en las que los complementos no se activan como se indica en la sección Elementos de buzón disponibles para complementos de la página de información general de complementos de Outlook, la funcionalidad no se admite actualmente para el modo sin conexión donde ese modo está disponible.

En los casos en los que los complementos de Outlook no se activan, el complemento de envío no se ejecutará y se enviará el mensaje.

Sin embargo, si la característica de envío está habilitada y disponible, pero el escenario de buzón no es compatible, Outlook no permitirá el envío.

Varios complementos de envío

Si se han instalado múltiples complementos de envío, los complementos se ejecutarán en el orden en que se reciben desde las API getAppManifestCall o getExtensibilityContext. Si el primer complemento permite el envío, el segundo complemento puede cambiar algo que haría que el primero bloqueara el envío. En cambio, el primer complemento no se ejecutará de nuevo si todos los complementos instalados han permitido el envío.

Por ejemplo, Complemento1 y Complemento2 usan la característica de envío. Complemento1 se instala primero y Complemento2 se instala después. Complemento1 comprueba que la palabra Fabrikam aparezca en el mensaje como una condición para que el complemento permita el envío. En cambio, Complemento2 quita cualquier aparición de la palabra Fabrikam. El mensaje se enviará con todas las instancias de Fabrikam quitadas (debido al orden de instalación de Complemento1 y Complemento2).

Implementar complementos de Outlook que usan la característica de envío

Recomendamos que los administradores implementen los complementos de Outlook que usen la característica de envío. Los administradores tienen que asegurarse de que el complemento de envío:

• Esté siempre presente cuando se abra un elemento de redacción (para el correo electrónico: nuevo, responder o reenviar).
• No puede ser cerrado ni deshabilitado por el usuario.

Instalar complementos de Outlook que usan la característica de envío

La característica de envío en Outlook requiere que los complementos estén configurados para los tipos de evento de envío. Seleccione la plataforma que desea 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

Escenarios de la característica de envío

A continuación, se muestran los escenarios admitidos y no admitidos para los complementos que usan la característica de envío.

Los controladores de eventos se definen dinámicamente

Los controladores de eventos del complemento deben definirse en el momento Office.initialize o Office.onReady() se llama a (para obtener más información, vea Inicio de un complemento de Outlook e Inicialización del complemento de Office). Si el código del controlador se define dinámicamente por determinadas circunstancias durante la inicialización, debe crear una función de código auxiliar para llamar al controlador una vez que esté completamente definido. Se debe hacer referencia a la función stub en el <atributo del elemento Event> del FunctionName manifiesto. Esta solución alternativa garantiza que el controlador esté definido y listo para que se haga referencia una vez Office.initialize o Office.onReady() se ejecute.

Si el controlador no se define una vez inicializado el complemento, se notificará al remitente que "La función de devolución de llamada no es accesible" a través de una barra de información del elemento de correo.

El buzón de usuario tiene la característica del complemento de envío habilitada pero los complementos no están instalados

En este escenario, el usuario podrá enviar mensajes y elementos de reunión sin que se ejecute ningún complemento.

El buzón de usuario tiene la característica del complemento de envío habilitada y los complementos que admiten el envío están instalados y habilitados

Los complementos se ejecutarán durante el evento de envío, que permitirá o impedirá que el usuario realice el envío.

Delegación de buzones, donde el buzón 1 tiene permisos de acceso completo al buzón 2

Navegador web - Outlook clásico

Navegador web (Outlook moderno), Windows, Mac

Para aplicarla al envío, los administradores deben asegurarse de que la Directiva se haya habilitado en ambos buzones. Para obtener información sobre cómo admitir el acceso delegado en un complemento, consulte Habilitar carpetas compartidas y escenarios de buzón compartido.

El buzón de usuario con la directiva del complemento de envío habilitada, los complementos que admiten el envío están instalados y habilitados, y el modo sin conexión está habilitado

Los complementos de envío se ejecutarán según el estado de conexión del usuario, el back-end de complementos y Exchange.

Estado del usuario

Los complementos de envío se ejecutarán durante el envío si el usuario está en línea. Si el usuario está desconectado, los complementos de envío no se ejecutarán durante el envío y el elemento de reunión o mensaje no se enviará.

Estado de back-end del complemento

Un complemento de envío se ejecutará si su servidor está en línea y se puede acceder a él. Si el servidor está sin conexión, el envío se deshabilita.

Estado de Exchange

Los complementos de envío se ejecutarán durante el envío si el servidor de Exchange está en línea y accesible. Si el complemento de envío no puede acceder a Exchange y la directiva o cmdlet aplicables están activados, el envío se deshabilita.

El usuario puede editar el elemento mientras los complementos de envío están trabajando en él.

Mientras los complementos de envío procesan un elemento, el usuario puede editarlo agregando, por ejemplo, texto o datos adjuntos inadecuados. Si desea evitar que el usuario edite el elemento mientras el complemento se está procesando durante el envío, puede implementar una solución alternativa mediante un cuadro de diálogo. Esta solución alternativa se puede usar en Outlook en la Web (clásico), Windows (clásico) y Mac.

En el controlador de envío:

1. Llame a displayDialogAsync para abrir un cuadro de diálogo de modo que se deshabiliten los clics del mouse y las pulsaciones de tecla.

   Importante

   Para obtener este comportamiento en la Outlook en la Web clásica, debe establecer la propiedad truedisplayInIframe en en el options parámetro de la displayDialogAsync llamada.

2. Implemente el procesamiento del elemento.

3. Cierre el cuadro de diálogo. Además, controle lo que sucede si el usuario cierra el cuadro de diálogo.

Ejemplos de código

Los siguientes ejemplos de código le muestran cómo crear un complemento de envío sencillo. Para descargar el ejemplo de código en el que se basan estos ejemplos, vea Outlook-Add-in-On-Send.

Manifiesto, reemplazo de versión y evento

El ejemplo de código Outlook-Add-in-On-Send incluye dos manifiestos:

• Contoso Message Body Checker.xml : muestra cómo comprobar el cuerpo de un mensaje en busca de palabras restringidas o información confidencial en el envío.

• Contoso Subject and CC Checker.xml : muestra cómo agregar un destinatario a la línea CC y comprobar que el mensaje incluye una línea de asunto en el envío.

En el archivo de manifiesto Contoso Message Body Checker.xml, incluya el archivo de función y el nombre de la función a la que debe llamarse en el evento ItemSend. La operación se ejecuta de manera sincrónica.

<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 el archivo de manifiesto Contoso Subject and CC Checker.xml, en el ejemplo siguiente se muestra el archivo de función y el nombre de la función a la que se llamará en el evento de envío del mensaje.

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

La API de envío requiere VersionOverrides v1_1. A continuación se muestra cómo agregar el nodo VersionOverrides a su manifiesto.

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

Los objetos Event y item, y los métodos body.getAsync y body.setAsync

Para tener acceso al elemento de reunión o mensaje seleccionado actualmente (en este ejemplo, el mensaje recién redactado), use el espacio de nombres Office.context.mailbox.item. La ItemSend característica de envío pasa automáticamente el evento a la función especificada en el manifiesto, en este ejemplo, la validateBody función .

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 función obtiene el cuerpo actual en el formato especificado (HTML) y pasa el objeto de ItemSend evento al que el código quiere tener acceso en la función de devolución de llamada. Además del método getAsync, el objeto Body también proporciona un método setAsync que puede usar para reemplazar el cuerpo por el texto especificado.

Objeto NotificationMessages y método event.completed

La función checkBodyOnlyOnSendCallBack usa una expresión regular para determinar si el cuerpo del mensaje contiene palabras bloqueadas. Si detecta una coincidencia en una matriz de palabras restringidas, impide que el correo electrónico se envíe y lo notifica al remitente mediante la barra de información. Para ello, usa la notificationMessages propiedad del Item objeto para devolver un objeto NotificationMessages . Después, agrega una notificación al elemento llamando al método addAsync, como se muestra en el siguiente ejemplo.

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

A continuación se muestran los parámetros del addAsync método .

• NoSend : cadena que es una clave especificada por el desarrollador para hacer referencia a un mensaje de notificación. Puede usarla para modificar este mensaje posteriormente. La clave no puede tener más de 32 caracteres.
• type : una de las propiedades del parámetro de objeto JSON. Representa el tipo de un mensaje; los tipos corresponden a los valores de la enumeración Office.MailboxEnums.ItemNotificationMessageType. Los valores posibles son el indicador de progreso, el mensaje de información o el mensaje de error. En este ejemplo, type es un mensaje de error.
• message : una de las propiedades del parámetro de objeto JSON. En este ejemplo, message es el texto del mensaje de notificación.

Para indicar que el complemento ha terminado de procesar el ItemSend evento desencadenado por la operación de envío, llame al método event.completed({allowEvent:Boolean}). La propiedad allowEvent es booleana. Si se establece en true, el envío está permitido. Si se establece en false, el mensaje de correo electrónico no se puede enviar.

Métodos replaceAsync, removeAsync y getAllAsync

Además del método addAsync, el objeto NotificationMessages también incluye los métodos replaceAsync, removeAsync y getAllAsync. Estos métodos no se usan en este ejemplo de código. Para obtener más información, vea NotificationMessages.

Asunto y comprobador de CC

El siguiente ejemplo de código le muestra cómo agregar un destinatario a la línea CC y comprobar que el mensaje incluye un asunto en el envío. Este ejemplo usa la característica de envío para permitir o no permitir el envío de un correo electrónico.

// 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 obtener más información sobre cómo agregar un destinatario a la línea CC y comprobar que el mensaje de correo electrónico incluye una línea de asunto en el envío, y para ver las API que puede usar, vea el ejemplo Outlook-Add-in-On-Send. Este código está debidamente comentado.

Depuración de complementos de Outlook que usan el envío

Para obtener instrucciones sobre cómo depurar el complemento al enviar, vea Depurar comandos de función en complementos de Outlook.

Vea también

• Información general sobre las características y la arquitectura de los complementos de Outlook
• Complemento de Outlook “Add-in Command Demo”