Share via

Actualizar automáticamente la firma al cambiar entre cuentas de Exchange

  • Artículo

Ahora se facilita la aplicación de la firma correcta a los mensajes al usar varias cuentas de Exchange con la adición de los OnMessageFromChanged eventos y OnAppointmentFromChanged a la característica de activación basada en eventos . El OnMessageFromChanged evento se produce cuando se cambia la cuenta en el campo From de un mensaje que se va a componer, mientras que el OnAppointmentFromChanged evento se produce cuando se cambia el organizador de una reunión que se va a componer. Estos eventos amplían aún más las funcionalidades de los complementos de firma y les permiten:

  • Proporcione a los usuarios la comodidad de aplicar firmas personalizadas para cada una de sus cuentas.
  • Permitir que los delegados de buzón administren de forma más precisa y eficaz los mensajes salientes y las solicitudes de reunión de varios buzones.
  • Asegúrese de que los mensajes y citas de los usuarios cumplen las directivas de comunicación y marketing de su organización.

En las secciones siguientes se explica cómo desarrollar un complemento basado en eventos que controla el OnMessageFromChanged evento para actualizar automáticamente la firma de un mensaje cuando se cambia la cuenta de correo en el campo Desde .

Nota:

Los OnMessageFromChanged eventos y OnAppointmentFromChanged se introdujeron en el conjunto de requisitos 1.13. Para obtener información sobre la compatibilidad con clientes para estos eventos, consulte Clientes y plataformas compatibles.

Plataformas y clientes admitidos

En las tablas siguientes se enumeran las combinaciones cliente-servidor que admiten los OnMessageFromChanged eventos y OnAppointmentFromChanged . Seleccione la pestaña para el evento aplicable.

Cliente Exchange Online Exchange 2019 local (actualización acumulativa 12 o posterior) Exchange 2016 local (actualización acumulativa 22 o posterior)
Explorador web (interfaz de usuario moderna)

nuevo Outlook en Windows (versión preliminar)		 Compatible No aplicable No aplicable
Windows (clásico)
Versión 2304 (compilación 16327.20248) o posterior		 Compatible Compatible Compatible
Mac
Versión 16.77.816.0 o posterior		 Compatible No aplicable No aplicable
iOS No aplicable No aplicable No aplicable
Android No aplicable No aplicable No aplicable

Requisitos previos

Para probar el tutorial, debe tener al menos dos cuentas de Exchange.

Configurar el entorno

Complete el inicio rápido de Outlook, que crea un proyecto de complemento con el generador de Yeoman para complementos de Office.

Configuración del manifiesto

  1. Abra el archivo manifest.json .

  2. Agregue el siguiente objeto a la matriz "extensions.runtimes". Tenga en cuenta lo siguiente sobre este marcado.

    • La "minVersion" del conjunto de requisitos de Buzón se configura como "1.13" porque es la versión más baja del conjunto de requisitos que admite el OnMessageFromChanged evento. Para obtener más información, vea la tabla "Eventos admitidos" en Configurar el complemento de Outlook para la activación basada en eventos.

    • El "id" del runtime se establece en un nombre descriptivo, "autorun_runtime".

    • La propiedad "code" tiene una propiedad "page" secundaria establecida en un archivo HTML y una propiedad "script" secundaria establecida en un archivo JavaScript. Creará o editará estos archivos en pasos posteriores. Office usa uno de estos valores en función de la plataforma.

      • Outlook clásico en Windows ejecuta el controlador de eventos en un entorno de ejecución solo de JavaScript, que carga un archivo JavaScript directamente.
      • Outlook en la Web y en Mac, y el nuevo Outlook en Windows (versión preliminar) ejecuta el controlador en un entorno de ejecución del explorador, que carga un archivo HTML. El archivo HTML contiene una <script> etiqueta que carga el archivo JavaScript.

      Para obtener más información, vea Runtimes in Office Add-ins.

    • La propiedad "lifetime" se establece en "short". Esto significa que el tiempo de ejecución se inicia cuando se produce el evento y se apaga cuando se completa el controlador.

    • Hay "acciones" para ejecutar controladores para los OnMessageFromChanged eventos y OnNewMessageCompose . Creará los controladores en un paso 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. Agregue una matriz "autoRunEvents" como propiedad del objeto en la matriz "extensiones". La matriz "autoRunEvents" contiene un objeto con las siguientes propiedades clave.

    • La propiedad "events" asigna controladores a los OnMessageFromChanged eventos y OnNewMessageCompose . Para obtener información sobre los nombres de eventos usados en el manifiesto unificado, vea la tabla "Eventos admitidos" en Configuración del complemento de Outlook para la activación basada en eventos.
    • El nombre de función proporcionado en "actionId" debe coincidir con la propiedad "id" de su objeto correspondiente en la matriz "actions" configurada anteriormente.
    "autoRunEvents": [
    {
        "requirements": {
            "capabilities": [
                {
                    "name": "Mailbox",
                    "minVersion": "1.13"
                }
            ],
            "scopes": [
                "mail"
            ]
        },
        "events": [
            {
                "type": "messageFromChanged",
                "actionId": "onMessageFromChangedHandler"
            },
            {
                "type": "newMessageComposeCreated",
                "actionId": "onNewMessageComposeHandler"
            }
        ]
    }
]

Sugerencia

Implementación de los controladores de eventos

Los controladores de eventos deben configurarse para los OnNewMessageCompose eventos y OnMessageFromChanged . La onNewMessageComposeHandler función agrega una firma a un mensaje recién creado si aún no se ha configurado uno predeterminado en la cuenta actual. Cuando se cambia la cuenta del campo Desde , la onMessageFromChangedHandler función actualiza la firma en función de esta cuenta recién seleccionada.

  1. Desde el mismo proyecto de inicio rápido, vaya al directorio ./src y cree una nueva carpeta denominada launchevent.

  2. En la carpeta ./src/launchevent , cree un nuevo archivo denominado launchevent.js.

  3. Abra el archivo ./src/launchevent/launchevent.js en el editor de código y agregue el siguiente código JavaScript.

    /*
 * 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: en la actualidad, las importaciones no se admiten en el archivo JavaScript donde se implementa el control para la activación basada en eventos.

Sugerencia

Los complementos basados en eventos que se ejecutan en Outlook en Windows no ejecutan código incluido en las Office.onReady() funciones y Office.initialize . Se recomienda agregar la lógica de inicio del complemento, como comprobar la versión de Outlook del usuario, a los controladores de eventos en su lugar.

Actualizar el archivo HTML de comandos

  1. En la carpeta ./src/commands , abra commands.html.

  2. Agregue el código siguiente debajo de la etiqueta de script existente.

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

  3. Guarde los cambios.

Actualizar los valores de configuración de webpack

  1. En el directorio raíz del proyecto, abra el archivo webpack.config.js .

  2. Busque la plugins matriz dentro del config objeto y agregue el siguiente nuevo objeto al principio de la matriz.

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

  3. Guarde los cambios.

Pruébelo

  1. Ejecute los siguientes comandos en el directorio raíz del proyecto. Al ejecutar npm start, se iniciará el servidor web local (si aún no se está ejecutando) y el complemento se transferirá de forma local.

    npm run build

    npm start

    Nota:

    Si el complemento no se ha descargado de forma local automáticamente, siga las instrucciones de Transferencia local de complementos de Outlook para realizar pruebas para transferir manualmente el complemento en Outlook.

  2. En el cliente de Outlook que prefiera, cree un mensaje. Si no tiene configurada una firma de Outlook predeterminada, el complemento agrega una al mensaje recién creado.

    Una firma de ejemplo agregada a un mensaje recién compuesto cuando no se configura una firma predeterminada de Outlook en la cuenta.

  3. Habilite el campo Desde , si procede. Para obtener instrucciones sobre cómo habilitarlo, consulte la sección "¿Por qué falta el botón De?" de Cambiar la cuenta usada para enviar mensajes de correo electrónico.

  4. Seleccione Desde y, a continuación, elija una cuenta de Exchange diferente. Como alternativa, escriba manualmente la dirección de correo electrónico de Exchange; para ello, seleccione Desde>otra dirección Email. Se agrega una firma actualizada al mensaje, reemplazando la anterior.

    Muestra de una firma actualizada con un logotipo cuando se cambia la cuenta en el campo Desde.

Solución de problemas del complemento

Para obtener instrucciones sobre cómo solucionar problemas de los complementos de activación basados en eventos, consulte Solución de problemas de complementos de informes de correo no deseado y basados en eventos.

Implementación en usuarios

De forma similar a otros complementos basados en eventos, los complementos que usan los OnMessageFromChanged eventos y OnAppointmentFromChanged deben ser implementados por el administrador de una organización. Para obtener instrucciones sobre cómo implementar el complemento a través de la Centro de administración de Microsoft 365, vea la sección "Implementar en los usuarios" de Configuración del complemento de Outlook para la activación basada en eventos.

Comportamiento y limitaciones de eventos

Dado que los OnMessageFromChanged eventos y OnAppointmentFromChanged se admiten a través de la característica de activación basada en eventos, se aplican el mismo comportamiento y limitaciones a los complementos que se activan como resultado de este evento. Para obtener una descripción detallada, consulte Comportamiento y limitaciones de la activación basada en eventos.

Además de estas características, los siguientes aspectos también se aplican cuando se activa un complemento en estos eventos.

  • El OnMessageFromChanged evento solo se admite en el modo de redacción de mensajes, mientras que el evento solo se admite en el OnAppointmentFromChanged modo de redacción de citas.
  • En Outlook en Windows, solo se admite el OnMessageFromChanged evento .
  • Los OnMessageFromChanged eventos y OnAppointmentFromChanged solo admiten cuentas de Exchange. En los mensajes que se componen, la cuenta de Exchange se selecciona en la lista desplegable Del campo o se escribe manualmente en el campo. En las citas que se componen, la cuenta de Exchange se selecciona en la lista desplegable del campo organizador. Si un usuario cambia a una cuenta que no es de Exchange en el campo Desde o organizador, el cliente de Outlook borra automáticamente la firma establecida por la cuenta seleccionada anteriormente.
  • Se admiten escenarios de delegación y buzón compartido.
  • El OnAppointmentFromChanged evento no se admite en los calendarios de grupo de Microsoft 365. Si un usuario cambia de su cuenta de Exchange a una cuenta de calendario de grupo de Microsoft 365 en el campo organizador, el cliente de Outlook borra automáticamente la firma establecida por la cuenta de Exchange.
  • Al cambiar a otra cuenta de Exchange en el campo Desde o organizador, los complementos de la cuenta seleccionada anteriormente, si los hay, finalizan y los complementos asociados a la cuenta recién seleccionada se cargan antes de iniciar el OnMessageFromChanged evento o OnAppointmentFromChanged .
  • Email se admiten alias de cuenta. Cuando se selecciona un alias para la cuenta actual en el campo Desde o organizador, el OnMessageFromChanged evento o OnAppointmentFromChanged se produce sin volver a cargar los complementos de la cuenta.
  • Cuando la lista desplegable del campo Desde o organizador se abre por error o se vuelve a seleccionar la misma cuenta que aparece en el campo Desde o organizador, se produce el OnMessageFromChanged evento o OnAppointmentFromChanged , pero los complementos de la cuenta no se terminan ni se recargan.

Consulte también