Obtener y establecer metadatos de un complemento de Outlook

  • Artículo

Puede administrar datos personalizados del complemento de Outlook si usa uno de los métodos siguientes:

  • Configuración de itinerancia, que administra datos personalizados en el buzón de un usuario.
  • Propiedades personalizadas, que administran datos personalizados para un elemento en el buzón de un usuario.

Ambos proporcionan acceso a datos personalizados a los que solo puede acceder el complemento de Outlook, pero cada método almacena los datos por separado del otro. Es decir, los datos almacenados a través de la configuración de itinerancia no son accesibles para las propiedades personalizadas y viceversa. La configuración de itinerancia se almacena en el buzón del usuario mientras que las propiedades personalizadas se almacenan en un mensaje o cita. Los datos almacenados son accesibles en sesiones posteriores de Outlook en todos los factores de forma que admite el complemento.

Datos personalizados por buzón: opciones de movilidad

Puede especificar los datos específicos del buzón de Exchange de un usuario mediante el objeto RoamingSettings. Los datos personales y las preferencias del usuario son ejemplos de estos datos. El complemento de correo puede obtener acceso a la configuración de movilidad cuando se mueve en cualquier dispositivo en el que pueda ejecutarse por diseño (escritorio, tableta o smartphone).

Los cambios en estos datos se almacenan en una copia en memoria de los parámetros de la sesión actual de Outlook. Debe guardar explícitamente todas las opciones de itinerancia después de actualizarlas para que estén disponibles la próxima vez que el usuario abra el complemento, en el mismo dispositivo o en cualquier otro dispositivo compatible.

Formato de las configuraciones de movilidad

Los datos de un objeto RoamingSettings se almacenan como una cadena serializada de notación de objetos JavaScript (JSON).

A continuación se muestra un ejemplo de la estructura, suponiendo que hay tres configuraciones de itinerancia definidas denominadas add-in_setting_name_0, add-in_setting_name_1y add-in_setting_name_2.

{
  "add-in_setting_name_0": "add-in_setting_value_0",
  "add-in_setting_name_1": "add-in_setting_value_1",
  "add-in_setting_name_2": "add-in_setting_value_2"
}

Carga de la configuración de movilidad

Normalmente, un complemento de correo carga la configuración de movilidad del controlador de eventos Office.initialize. En el siguiente ejemplo de código de JavaScript se muestra cómo cargar la configuración de itinerancia existente y obtener los valores de dos configuraciones, customerName y customerBalance.

let _mailbox;
let _settings;
let _customerName;
let _customerBalance;

// The initialize function is required for all add-ins.
Office.initialize = function () {
  // Initialize instance variables to access API objects.
  _mailbox = Office.context.mailbox;
  _settings = Office.context.roamingSettings;
  _customerName = _settings.get("customerName");
  _customerBalance = _settings.get("customerBalance");
}

Creación o asignación de una configuración de movilidad

Continuando con el ejemplo anterior, la siguiente función de JavaScript, setAddInSetting, muestra cómo usar el método RoamingSettings.set para establecer una configuración denominada cookie con la fecha de hoy y conservar los datos mediante el método RoamingSettings.saveAsync para guardar toda la configuración de itinerancia en el buzón del usuario.

El set método crea la configuración si la configuración aún no existe y asigna la configuración al valor especificado. El saveAsync método guarda la configuración de itinerancia de forma asincrónica. Este ejemplo de código pasa una función de devolución de llamada, saveMyAddInSettingsCallback, a saveAsync. Cuando finaliza la llamada asincrónica, saveMyAddInSettingsCallback se llama a mediante un parámetro, asyncResult. Este parámetro es un objeto AsyncResult que contiene el resultado de la llamada asíncrona y los detalles de la misma. Si lo desea, puede usar el parámetro opcional userContext para pasar la información de estado de la llamada asincrónica a la función de devolución de llamada.

// Set a roaming setting.
function setAddInSetting() {
  _settings.set("cookie", Date());
  // Save roaming settings to the mailbox, so that they'll be available in the next session.
  _settings.saveAsync(saveMyAddInSettingsCallback);
}

// Callback function after saving custom roaming settings.
function saveMyAddInSettingsCallback(asyncResult) {
  if (asyncResult.status == Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
}

Supresión de la configuración de movilidad

Al ampliar también los ejemplos anteriores, la siguiente función de JavaScript, removeAddInSetting, muestra cómo usar el método RoamingSettings.remove para quitar la cookie configuración y guardar toda la configuración de itinerancia en el buzón.

// Remove an add-in setting.
function removeAddInSetting()
{
  _settings.remove("cookie");
  // Save changes to the roaming settings for the mailbox, so that they'll be available in the next session.
  _settings.saveAsync(saveMyAddInSettingsCallback);
}

Datos personalizados por cada elemento en un buzón de correo: propiedades personalizadas

Puede especificar datos concretos en un elemento en el buzón del usuario mediante el objeto CustomProperties . Por ejemplo, el complemento de correo podría clasificar determinados mensajes y anotar la categoría mediante una propiedad personalizada messageCategory. O bien, si el complemento de correo crea citas a partir de sugerencias de reunión en un mensaje, se puede usar una propiedad personalizada para realizar un seguimiento de cada una de las citas. Esto garantiza que si el usuario vuelve a abrir el mensaje, el complemento de correo no ofrece crear la cita una segunda vez.

Tal como ocurre con la configuración de movilidad, los cambios en las propiedades personalizadas se almacenan en las copias en la memoria de las propiedades para la sesión actual de Outlook. Para asegurarse de que estas propiedades personalizadas estarán disponibles en la siguiente sesión, use CustomProperties.saveAsync.

Solo se puede acceder a estas propiedades personalizadas específicas del complemento, específicas del elemento, mediante el CustomProperties objeto . Estas propiedades son diferentes de las userProperties personalizadas basadas en MAPI en el modelo de objetos de Outlook y las propiedades extendidas en Exchange Web Services (EWS). No se puede acceder CustomProperties directamente mediante el modelo de objetos de Outlook, EWS o REST. Para obtener información sobre cómo acceder CustomProperties mediante EWS o REST, consulte la sección Obtención de propiedades personalizadas mediante EWS o REST.

Nota:

Las propiedades personalizadas solo están disponibles para el complemento que las creó y solo a través del elemento de correo en el que se guardaron. Por este motivo, las propiedades establecidas mientras están en modo de redacción no se transmiten a los destinatarios del elemento de correo. Cuando se envía un mensaje o una cita con propiedades personalizadas, se puede acceder a sus propiedades desde el elemento de la carpeta Elementos enviados . Para permitir que los destinatarios reciban los datos personalizados de los conjuntos de complementos, considere la posibilidad de usar InternetHeaders en su lugar.

Usar propiedades personalizadas

Para poder usar propiedades personalizadas, debe cargarlas llamando al método loadCustomPropertiesAsync. Después de crear el contenedor de propiedades, puede usar los métodos set y get para agregar y recuperar propiedades personalizadas. Debe utilizar el método saveAsync para guardar los cambios que realice en el contenedor de propiedades.

Nota:

Al usar propiedades personalizadas en complementos de Outlook, tenga en cuenta lo siguiente:

  • Outlook en Mac no almacena en caché las propiedades personalizadas. Si la red del usuario deja de funcionar, los complementos de Outlook en Mac no podrán acceder a sus propiedades personalizadas.
  • En Outlook en Windows, las propiedades personalizadas guardadas mientras están en modo de redacción solo se conservan después de que se cierre el elemento que se va a componer o después Office.context.mailbox.item.saveAsync de que se llame a .

Ejemplo de propiedades personalizadas

En el ejemplo siguiente se muestra un conjunto simplificado de funciones y métodos para un complemento de Outlook que usa propiedades personalizadas. Puede usar este ejemplo como punto de partida de su complemento que usa propiedades personalizadas.

En este ejemplo se incluyen las siguientes funciones y métodos.

  • Office.initialize: inicializa el complemento y carga el contenedor de propiedades personalizadas desde el Exchange Server.

  • customPropsCallback : obtiene el contenedor de propiedades personalizado que se devuelve del servidor y lo guarda localmente para su uso posterior.

  • updateProperty : establece o actualiza una propiedad específica y, a continuación, guarda el cambio en el contenedor de propiedades local.

  • removeProperty : quita una propiedad específica del contenedor de propiedades y, a continuación, guarda estos cambios.

let _mailbox;
let _customProps;

// The initialize function is required for all add-ins.
Office.initialize = function () {
  _mailbox = Office.context.mailbox;
  _mailbox.item.loadCustomPropertiesAsync(customPropsCallback);
}

// Callback function from loading custom properties.
function customPropsCallback(asyncResult) {
  if (asyncResult.status == Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
  else {
    // Successfully loaded custom properties,
    // can get them from the asyncResult argument.
    _customProps = asyncResult.value;
  }
}

// Get individual custom property.
function getProperty() {
  const myProp = _customProps.get("myProp");
}

// Set individual custom property.
function updateProperty(name, value) {
  _customProps.set(name, value);
  // Save all custom properties to the mail item.
  _customProps.saveAsync(saveCallback);
}

// Remove a custom property.
function removeProperty(name) {
  _customProps.remove(name);
  // Save all custom properties to the mail item.
  _customProps.saveAsync(saveCallback);
}

// Callback function from saving custom properties.
function saveCallback() {
  if (asyncResult.status == Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
}

Obtener las propiedades personalizadas con EWS o REST

Para obtener CustomProperties con EWS o REST, primero debe determinar el nombre de su propiedad extendida basada en MAPI. Luego, puede obtener dicha propiedad de la misma manera que obtendría cualquier propiedad extendida basada en MAPI.

¿Cómo se almacenan las propiedades personalizadas en un elemento?

Las propiedades personalizadas establecidas por un complemento no son equivalentes a las propiedades normales basadas en MAPI. Las API de complemento serializan todos los complementos CustomProperties como una carga JSON y, a continuación, los guardan en una única propiedad extendida basada en MAPI cuyo nombre es cecp-<app-guid> ( es el<app-guid> identificador del complemento) y el GUID del conjunto de propiedades es {00020329-0000-0000-C000-000000000046}. Para más información sobre este objeto, vea Propiedades personalizadas de aplicación de correo MS-OXCEXT 2.2.5. Luego, puede usar EWS o REST para obtener esta propiedad basada en MAPI.

Obtener las propiedades personalizadas con EWS

El complemento de correo puede obtener la CustomProperties propiedad extendida basada en MAPI mediante la operación GetItem de EWS. Acceda GetItem al servidor mediante un token de devolución de llamada o en el lado cliente mediante el método mailbox.makeEwsRequestAsync . En la GetItem solicitud, especifique la CustomProperties propiedad basada en MAPI en su conjunto de propiedades mediante los detalles proporcionados en la sección anterior Cómo se almacenan las propiedades personalizadas en un elemento.

El siguiente ejemplo muestra cómo obtener un elemento y sus propiedades personalizadas.

Importante

En el ejemplo siguiente, reemplace <app-guid> con el Id. del complemento.

let request_str =
    '<?xml version="1.0" encoding="utf-8"?>' +
    '<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"' +
                   'xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"' +
                   'xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"' +
                   'xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">' +
        '<soap:Header xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"' +
                     'xmlns:wsa="http://www.w3.org/2005/08/addressing">' +
            '<t:RequestServerVersion Version="Exchange2010_SP1"/>' +
        '</soap:Header>' +
        '<soap:Body>' +
            '<m:GetItem>' +
                '<m:ItemShape>' +
                    '<t:BaseShape>AllProperties</t:BaseShape>' +
                    '<t:IncludeMimeContent>true</t:IncludeMimeContent>' +
                    '<t:AdditionalProperties>' +
                        '<t:ExtendedFieldURI ' +
                          'DistinguishedPropertySetId="PublicStrings" ' +
                          'PropertyName="cecp-<app-guid>"' +
                          'PropertyType="String" ' +
                        '/>' +
                    '</t:AdditionalProperties>' +
                '</m:ItemShape>' +
                '<m:ItemIds>' +
                    '<t:ItemId Id="' +
                      Office.context.mailbox.item.itemId +
                    '"/>' +
                '</m:ItemIds>' +
            '</m:GetItem>' +
        '</soap:Body>' +
    '</soap:Envelope>';

Office.context.mailbox.makeEwsRequestAsync(
    request_str,
    function(asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
            console.log(asyncResult.value);
        }
        else {
            console.log(JSON.stringify(asyncResult));
        }
    }
);

También puede obtener más propiedades personalizadas si las especifica en la cadena de solicitud como otros elementos ExtendedFieldURI.

Obtener las propiedades personalizadas con REST

En el complemento, puede crear la consulta de REST para mensajes y eventos para obtener los que ya tienen propiedades personalizadas. En la consulta, especifique la propiedad CustomProperties basada en MAPI y su conjunto de propiedades con los detalles proporcionados en la sección Cómo se almacenan las propiedades personalizadas en un elemento.

El siguiente ejemplo muestra cómo obtener todos los eventos que tienen propiedades personalizadas establecidas por el complemento y garantiza que la respuesta incluya el valor de la propiedad para que pueda aplicar más lógica de filtrado.

Importante

En el ejemplo siguiente, reemplace <app-guid> con el Id. del complemento

GET https://outlook.office.com/api/v2.0/Me/Events?$filter=SingleValueExtendedProperties/Any
  (ep: ep/PropertyId eq 'String {00020329-0000-0000-C000-000000000046}
  Name cecp-<app-guid>' and ep/Value ne null)
  &$expand=SingleValueExtendedProperties($filter=PropertyId eq 'String
  {00020329-0000-0000-C000-000000000046} Name cecp-<app-guid>')

Para ver otros ejemplos que usan REST para obtener las propiedades extendidas de valor único basadas en MAPI, vea Obtener singleValueExtendedProperty.

El siguiente ejemplo muestra cómo obtener un elemento y sus propiedades personalizadas. En la función de devolución de llamada del método done, item.SingleValueExtendedProperties contiene una lista de las propiedades personalizadas solicitadas.

Importante

En el ejemplo siguiente, reemplace <app-guid> con el Id. del complemento.

Office.context.mailbox.getCallbackTokenAsync(
    {
        isRest: true
    },
    function (asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Succeeded
            && asyncResult.value !== "") {
            let item_rest_id = Office.context.mailbox.convertToRestId(
                Office.context.mailbox.item.itemId,
                Office.MailboxEnums.RestVersion.v2_0);
            let rest_url = Office.context.mailbox.restUrl +
                           "/v2.0/me/messages('" +
                           item_rest_id +
                           "')";
            rest_url += "?$expand=SingleValueExtendedProperties($filter=PropertyId eq 'String {00020329-0000-0000-C000-000000000046} Name cecp-<app-guid>')";

            let auth_token = asyncResult.value;
            $.ajax(
                {
                    url: rest_url,
                    dataType: 'json',
                    headers:
                        {
                            "Authorization":"Bearer " + auth_token
                        }
                }
                ).done(
                    function (item) {
                        console.log(JSON.stringify(item));
                    }
                ).fail(
                    function (error) {
                        console.log(JSON.stringify(error));
                    }
                );
        } else {
            console.log(JSON.stringify(asyncResult));
        }
    }
);

Comportamiento de la plataforma en los mensajes

En la tabla siguiente se resume el comportamiento de las propiedades personalizadas guardadas en mensajes para varios clientes de Outlook.

Escenario Outlook en la Web y en el nuevo cliente de Windows (versión preliminar) Outlook clásico en Windows Outlook en Mac
Redacción nueva nulo nulo nulo
Responder, responder todo nulo nulo nulo
Reenviar nulo Carga las propiedades del elemento primario nulo
Elemento enviado desde la nueva redacción nulo nulo nulo
Elemento enviado de respuesta o respuesta a todos nulo nulo nulo
Elemento enviado desde adelante nulo Quita las propiedades del elemento primario si no se guarda nulo

Para controlar la situación en Outlook en Windows:

  1. Compruebe si hay propiedades existentes al inicializar el complemento y guárdalas o borrelas según sea necesario.
  2. Al establecer propiedades personalizadas, incluya una propiedad adicional para indicar si las propiedades personalizadas se agregaron en modo de lectura. Esto le ayudará a diferenciar si la propiedad se creó en modo de redacción o se heredó del elemento primario.
  3. Para comprobar si el usuario está reenviando o respondiendo a un mensaje, puede usar item.getComposeTypeAsync (disponible en el conjunto de requisitos 1.10).

Vea también