Compartir a través de

Microsoft Office

Exploración de la API de JavaScript para Office: aplicaciones de correo

Angela Chu-Hatoun

Descargar el ejemplo de código

Este artículo es la cuarta parte del análisis exhaustivo sobre la API de JavaScript para Office y se enfoca en la porción de la API disponible para las aplicaciones de correo electrónico compatibles con Outlook y Outlook Web App. Doy por entendido que usted cuenta con conocimientos generales sobre las aplicaciones para Office. Si tiene dudas, la página de documentación del Centro de desarrollo “Información general sobre las aplicaciones para Office” (bit.ly/12nBWHG), le permitirá encaminarse. La primera parte de esta serie, “Exploración de la nueva API de JavaScript para Office” (msdn.microsoft.com/magazine/jj891051), proporciona información general a grandes rasgos sobre el modelo de objetos que tiene como raíz al objeto Office. El objeto Mailbox, que cuelga de Office.context, ofrece un punto de entrada para la mayoría de las funciones específicas de aplicaciones de correo en el modelo de objetos y será el punto donde retomaré el análisis.

Lo principal de este artículo es lo que usted, como desarrollador, puede hacer con la API de JavaScript para Office en las aplicaciones de correo. También entregué un artículo complementario en línea en el que analizo una aplicación de correo de muestra, con el código fuente que se encuentra en msdn.microsoft.com/magazine/dn205107. Ahora analizaré varias características de la API de JavaScript para Office, comenzando con algunas de las técnicas más básicas y usadas para luego pasar a conceptos más avanzados.

Características fundamentales de la API de JavaScript para Office

El objeto Mailbox proporciona acceso al perfil de usuario, al elemento que seleccionó el usuario, los formularios para mostrar el elemento y un subconjunto de los servicios Web Exchange (EWS), para manipular los elementos y carpetas en el buzón. El objeto Item representa al elemento de mensaje o cita seleccionado. A través de ese objeto podemos obtener un mayor acceso a las propiedades integradas y personalizadas, y a los archivos adjuntos de ese elemento.

Control de la activación según el tipo de elemento Podemos definir las reglas en el manifiesto para determinar cuándo activar una aplicación de correo. El elemento que seleccionó el usuario actualmente y que especificó Mailbox.item puede ser un objeto Message (como convocatorias de reunión, respuestas y cancelaciones) o Appointment. Según la situación, podemos restringir la aplicación de correo para que se active solo para un tipo de elemento específico. El siguiente ejemplo XML muestra una regla de activación ItemIs, que restringe la activación de la aplicación de correo solo para los mensajes:

<Rule xsi:type="ItemIs" ItemType="Message" />

Con la API de JavaScript para Office podemos usar la propiedad itemType para comprobar el tipo del elemento seleccionado:

Office.context.mailbox.item.itemType

Acceso y propiedades del elemento Una función básica que ofrecen las aplicaciones de correo es el acceso al elemento seleccionado actualmente y a sus propiedades integradas.

El siguiente ejemplo de JavaScript muestra cómo acceder al elemento seleccionado y a su propiedad integrada, subject:

// The initialize function is required for all apps.
Office.initialize = function () {
  // Check for the DOM to load.
  $(document).ready(function () {
    var item = Office.context.mailbox.item;
    var subject = item.subject;
    // Continue processing the subject.
  });
}

Entidades reconocidas Exchange Server reconoce ciertas entidades que están disponibles, sin importar si empleamos entidades o no para activar la aplicación de correo. Outlook y Outlook Web App extraen estas entidades si se encuentran en el sujeto o en el cuerpo del elemento seleccionado y las ponen a disposición a través de los siguientes métodos de la API de JavaScript:

  • método getEntities
  • método getEntitiesByType(entityType)
  • método getFilteredEntitiesByName(name)

Algunas de las entidades aceptadas son dirección, contacto, dirección de correo electrónico, entre otras.

Observe que Outlook y Outlook Web Apps solo extraen las cadenas en inglés, sin considerar la configuración regional que se especifica en el manifiesto de la aplicación. No pueden extraer entidades de la carpeta Mensajes enviados. Y pueden extraer sugerencias de reuniones de los mensajes, pero no de las citas.

Obtención de concordancias que resulten en una activación contextual Podemos especificar reglas de activación que dependan de concordancias de expresión regular (reglas de ItemHasRegularExpressionMatch) o de concordancias de entidad (reglas de ItemHasKnownEntity) en el elemento seleccionado. Podemos usar los siguientes métodos para obtener concordancias de expresión regular. Estos métodos están disponibles en el objeto Item principal, que puede ser un mensaje o una cita:

  • método getRegExMatches
  • método getRegExMatchesByName(name)

Podemos usar los métodos que se mencionan en la sección de Entidades reconocidas para obtener concordancias de entidad específicas. Tenga en cuenta que podemos usar estos métodos para obtener cualquier concordancia de entidad, sin importar el tipo de regla de activación que empleamos en la aplicación de correo.

Ejemplos El siguiente ejemplo es una regla ItemHasRegularExpressionMatch, denominada VideoURL, que activa la aplicación de correo si el elemento seleccionado es un mensaje cuyo cuerpo contiene una URL para un vídeo en YouTube:

<Rule xsi:type="RuleCollection" Mode="And">
  <Rule xsi:type="ItemIs" ItemType="Message"/>
  <Rule xsi:type="ItemHasRegularExpressionMatch"
    RegExName="VideoURL"
    RegExValue="http://www\.youtube\.com/watch\?v=[a-zA-Z0-9_-]{11}"
    PropertyName="Body"/>
</Rule>

El siguiente ejemplo de código de JavaScript muestra cómo usar el método Item.getRegExMatches para obtener las concordancias de la expresión regular VideoURL anterior:

Office.initialize = function () {
  // Check for the DOM to load.
  $(document).ready(function () {
    // Get an array of string matches for the regular expression VideoURL,
    // as specified in the manifest.
    var matches = Office.context.mailbox.item.getRegExMatches().VideoURL;
    // Continue processing the matches for the regular expression.
    });
}

El siguiente ejemplo es una regla ItemHasKnownEntity que activa la aplicación de correo cuando el tema o el cuerpo del mensaje contiene una dirección:

<Rule xsi:type="RuleCollection" Mode="And">
  <Rule xsi:type="ItemIs" ItemType="Message"/>
  <Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />
</Rule>

El siguiente ejemplo de código de JavaScript muestra cómo usar el método getEntitiesByType para obtener una matriz de cadenas que son direcciones postales en el tema o cuerpo del mensaje seleccionado actualmente:

Office.initialize = function () {
  // Check for the DOM to load.
  $(document).ready(function () {
    var item = Office.context.mailbox.item;
    // Get an array of strings that represent postal
    // addresses in the current item.
    var addresses = item.getEntitiesByType(
      Office.MailboxEnums.EntityType.Address);
    // Continue processing the array of addresses.
  });
}

Activar una aplicación de correo según los contextos (en especial las concordancias de expresión regular o la existencia de entidades reconocidas) es eficaz y podría resultar difícil de depurar. Consulte el artículo de MSDN Library “Solución de problemas de la activación de aplicaciones de correo” en bit.ly/11C0H30, donde encontrará consejos sobre cómo depurar los problemas de activación.

Almacenamiento de datos por elemento y por aplicación El objeto CustomProperties permite almacenar datos específicos del elemento a los que solo puede acceder nuestra propia aplicación de correo, en forma de propiedad personalizada del elemento en una sesión posterior. Estos datos se representan como pares clave-valor. Si el diseño de la aplicación permite que se ejecute en varios clientes y formatos de Outlook, entonces las propiedades personalizadas se desplazan con el cliente y formato de Outlook pertinente.

Las propiedades personalizadas de un elemento están disponibles a través del método Item.loadCustomPropertiesAysnc. Es un método asincrónico que recibe un método de devolución de llamada como parámetro. Cuando las propiedades personalizadas se cargan, estas quedan disponibles mediante la propiedad asyncResult.value, que se pasa al método de devolución de llamada como parámetro de entrada. La Figura 1 muestra cómo cargar, obtener, establecer y guardar propiedades personalizadas para el elemento actual.

Figura 1 Trabajo con propiedades personalizadas para el elemento actual

Office.initialize = function () {
  var mailbox = Office.context.mailbox;
  mailbox.item.loadCustomPropertiesAsync(customPropsCallback);
}
function customPropsCallback(asyncResult) {
  if (asyncResult.status == Office.AsyncResultStatus.Succeeded) {
    var customProps = asyncResult.value;
    var myProp = customProps.get("myProp");
    customProps.set("otherProp", "value");
    customProps.saveAsync(saveCallback);
  }
  else {
    write (asyncResult.error.message);
  }
}
function saveCallback(asyncResult) {
  // Callback method to save custom properties.
}

Almacenamiento de datos según buzón y aplicación El objeto RoamingSettings permite almacenar datos personalizados, a los que podría acceder la aplicación de correo para el mismo buzón, sin importar si la aplicación de correo se ejecuta en un equipo de escritorio, una tableta o un smartphone. El siguiente ejemplo de JavaScript muestra cómo obtener datos propios del buzón en el controlador del evento initialize de la aplicación de correo:

var _mailbox;
var _settings;
Office.initialize = function () {
  // Check for the DOM to load using the jQuery ready function.
  $(document).ready(function () {
    // Initialize instance variables to access API objects.
    _mailbox = Office.context.mailbox;
    _settings = Office.context.roamingSettings;
    // Continue with app-specific code.
  });
}

Perfil de usuario Podemos acceder al perfil de usuario mediante la propiedad Office.context.mailbox.userProfile. Con el objeto UserProfile, podemos obtener el nombre para mostrar, la dirección SMTP y la zona horaria local del usuario que inició sesión. El siguiente ejemplo de código JavaScript muestra cómo acceder a la propiedad UserProfile.emailAddress del usuario que actualmente inició sesión en Outlook o Outlook Web App:

Office.initialize = function () {
  // Check for the DOM to load.
  $(document).ready(function () {
    var userProfile = Office.context.mailbox.userProfile;
    var SMTPAddress = userProfile.emailAddress;
    // Continue with processing the user's SMTP address. 
  });
}

Visualización de formularios de Outlook En Outlook, el usuario puede especificar formularios para mostrar citas y mensajes de manera predeterminada. Al usar los siguientes métodos en la API de JavaScript para Office, una aplicación de correo puede mostrar una cita y un mensaje respectivamente, con los mismos formularios que usa Outlook:

  • Mailbox.displayAppointmentForm(itemId)
  • Mailbox.displayMessageForm(itemId)

El código que vemos en la Figura 2 comprueba si el usuario seleccionó una cita y luego la muestra en el formulario de citas predeterminado de Outlook.

Figura 2 Comprobar si el usuario seleccionó una cita

var myOm;
var myItem;
Office.initialize = function () {
  $(document).ready(function () {
    myOm = Office.context.mailbox;
    // Get the selected item.
    myItem = myOm.item;
    // Display the selected appointment.
    displaySelectedAppointment();
  });
}
function displaySelectedAppointment() {
  // Display selected item only if the item is an appointment.
  if (myitem.itemType == Office.MailboxEnums.ItemType.Appointment)
  {
    myOm.displayAppointmentForm(myItem.itemId);
  }
  else
  {
    // Handle condition as appropriate.
  }
}

El método Mailbox.displayNewAppointmentForm nos permite asignar valores a ciertos campos del formulario de citas para agregar una nueva reunión, y luego muestra el formulario para que el usuario rellene la cita. Al llamar a este método, debemos especificar estos campos como una lista de pares cadena-valor, tal como se aprecia en la Figura 3.

Figura 3 Asignación de valores a campos específicos en un nuevo formulario de citas

var myOm;
Office.initialize = function () {
  $(document).ready(function () {
    myOm = Office.context.mailbox;
    // After the DOM is loaded, can display the
    // pre-populated new appointment form.
    displayFormForNewAppointment();
  });
}
function displayFormForNewAppointment(){
  var formParameters =
  {
    "requiredAttendees" : ["wendy@contoso.com", "derek@contoso.com"],
    "optionalAttendees" : ["shane@contoso.com", "michael@contoso.com"],
    "start" : new Date("September 27, 2012 11:15:00"),
    "end" : new Date("("September 27, 2012 12:30:00"),
    "location" : "Conf room 200",
    "resources" : ['sound', 'lighting', 'recording'],
    "subject" : "Next rehearsal",
    "body" : "This is about the next rehearsal."
  }
  // Display a form to create an appointment with
  // the specified fields in the form.
  myOm.displayNewAppointmentForm(formParameters);
}

Los métodos que muestran formularios de respuesta a una cita o mensaje son los que ofrecen más margen para la personalización:

  • método Appointment.displayReplyAllForm(htmlBody)
  • método Appointment.displayReplyForm(htmlBody)
  • método Message.displayReplyAllForm(htmlBody)
  • método Message.displayReplyForm(htmlBody)

Para cada uno de estos métodos podemos proporcionar una cadena HTML que representa el cuerpo del formulario de respuesta. El ejemplo de la Figura 4 muestra el formulario Responder a todos para un mensaje.

Figura 4 Especificación del HTML para un formulario Responder a todos en un elemento de mensaje

var myOm;
var myItem;
Office.initialize = function () {
  // Check for the DOM to load.
  $(document).ready(function () {
    myOm = Office.context.mailbox;
    // Get the selected item.
    myItem = myOm.item;
    // After the DOM is loaded, display
    // the reply form.
    displayReply();
  });
}
function displayReply(){
  // Display a reply form to the sender and recipients only
  // if the selected item is a message.
  if (myitem.itemType == Office.MailboxEnums.ItemType.Message) {
      myItem.displayReplyAllForm
      ("<html><head><head><body>This is the body of " +
       "the email reply.</body></html>");
  }
}

Conceptos avanzados

Obtención de datos adjuntos del elemento Una aplicación de correo puede usar la API de JavaScript para Office junto con los tokens de devolución de llamada de EWS para acceder a los datos adjuntos del mensaje o cita actualmente que actualmente está seleccionado en el buzón del usuario. El uso del token de devolución de llamada permite que el código back-end del lado servidor de la aplicación de correo (o servicios web de terceros) llamen la operación GetAttachment de EWS para obtener los datos adjuntos puntuales.

A continuación se describe cómo una aplicación de correo obtiene los datos adjuntos (este proceso también se ilustra en la Figura 5):

  1. Una aplicación de correo usa Mailbox.getCallbackTokenAsync para solicitar un token de devolución de llamada, usa Item.attachments para obtener los metadatos de los datos adjuntos de la cita o mensaje seleccionado (inclusive los identificadores de los mismos) y usa Mailbox.ewsUrl para obtener la URL del extremo EWS, para la cuenta de correo electrónico actual.
  2. La aplicación de correo pasa el token de devolución de llamada, los identificadores de los datos adjuntos y la URL del extremo EWS al código del lado servidor.
  3. El código del lado servidor llama la operación GetAttachment de EWS para obtener los datos adjuntos propiamente tales de ese almacén de Exchange.

Mail Apps Accessing Attachments from an Exchange Server
Figura 5 Aplicaciones de correo que acceden a los datos adjuntos de un servidor Exchange

Tenga en cuenta que para acceder a EWS, el código del lado servidor debería crear las solicitudes EWS directamente. No podemos usar el método Mailbox.makeEws­RequestAsync para acceder a la operación GetAttachment. A la fecha de este artículo, se puede acceder a los datos adjuntos si la aplicación de correo se ejecuta en Outlook Web App. La característica no está disponible si la aplicación de correo se ejecuta en Outlook.

Consulte el ejemplo de código MSDN, “Aplicaciones de correo para Office: obtención datos adjuntos de un servidor Exchange” (bit.ly/11dG9fS) para ver un ejemplo sobre cómo acceder a los datos adjuntos en una aplicación de correo.

Token de usuario para el inicio de sesión único Nuestra aplicación de correo puede usar técnicas de autenticación web comunes para autenticar y autorizar a los usuarios. Si deseamos permitir la autenticación de inicio de sesión única para los usuarios a través de Outlook y Outlook Web App, podemos usar tokens de identidad de Exchange al llamar el método Mailbox.getUserIdentityTokenAsync.

El inicio de sesión único se basa en un servidor Exchange y asigna un token de identidad de Exchange a la cuenta de correo electrónico del usuario en ese servidor Exchange. Un token de identidad de Exchange contiene varios campos, entre ellos una firma para validar el token y un identificador único que representa la cuenta de correo electrónico de Exchange.

En general, las aplicaciones de correo que autentican a los usuarios son capaces de interactuar con un servicio web (que podría ser código del lado servidor de la aplicación de correo) o con un servicio web de terceros que emplea su propio proveedor de identidades (IdP) para validar la identidad del usuario en un sistema de identidad federada. La clave para el inicio de sesión único es la asignación que mantiene el servicio web entre el identificador único (del token de identidad de Exchange) y la identidad del usuario (reconocida por el IdP).

La Figura 6 proporciona una descripción a grandes rasgos sobre el uso de tokens de identidad de Exchange para la autenticación.

El siguiente es un resumen del proceso:

  1. La aplicación de correo llama Mailbox.getUserIdentityTokenAsync para solicitar un token de identidad de Exchange destinado al usuario, especificando un método de devolución de llamada que se ejecuta al completarse la operación asincrónica get.
  2. La función de devolución de llamada obtiene el token de identidad de Exchange y lo pasa al servicio web para su autenticación.
  3. El servicio web obtiene una clave pública del servidor Exchange para validar el token.
  4. Dependiendo de si el usuario ya inició sesión previamente, el servicio web procede de la siguiente manera:
    1. Si es la primera vez que el usuario inicia sesión en la aplicación de correo, no existirán asignaciones anteriores para esa cuenta y, como respuesta a la aplicación de correo, el servicio web solicitará las credenciales al usuario. Tras recibir las credenciales, la aplicación de correo las pasa al servicio web.
    2. Luego, el servicio crea una asignación entre el identificador único que proporciona el token y la identidad de usuario de las credenciales reconocidas por el IdP. Con las credenciales, el servicio puede iniciar sesión para el usuario.
    3. Posteriormente: cuando el usuario abra la aplicación de correo en Outlook o Outlook Web App desde un equipo de escritorio, tableta o explorador de un smartphone, se producirán los siguientes pasos:
      1. La aplicación de correo llama a getUserIdentityTokenAsync y obtiene el mismo identificador exclusivo en el token.
      2. La aplicación de correo pasa el token al servicio web.
      3. El servicio web valida el token.
      4. Luego, el servicio web consulta la tabla de asignación, encuentra al usuario y autoriza el acceso.

Authentication Using Exchange Identity Tokens
Figura 6 Autenticación a través de tokens de identidad de Exchange

Una vez que validamos el token, podemos mantener abierta la sesión del usuario, incluso cuando este abra la aplicación de correo desde otra aplicación host o dispositivo.

Los detalles de la autenticación y validación son bastante complejos. Podemos usar una biblioteca de validación de API administrada por EWS para simplificar el proceso. Al usar esa biblioteca de validación, un servicio web crearía un objeto, extraería y ubicaría el token en dicho objeto, comprobaría si la firma tiene validez y, de ser así, dejaría el identificador único en la base de datos de asignación.

Para obtener más información sobre el uso de tokens de identidad de Exchange para la autenticación, consulte la siguiente documentación en el Centro de desarrollo:

  • “Autenticar una aplicación de correo con los tokens de identidad de Exchange” (bit.ly/ZYaZ9v)
  • “Contenido del token de identidad de Exchange” (bit.ly/ZxRogq)
  • “Procedimiento para llamar a un servicio con un token de identidad en Exchange” (bit.ly/12jqxcU)
  • “Procedimiento para usar la biblioteca de validación de tokens de Exchange” (bit.ly/11akmEg)
  • “Procedimiento para validar un token de identidad de Exchange” (bit.ly/15im6SO)
  • “Procedimiento para autenticar un usuario con un token de identidad para Exchange” (bit.ly/13gZ36T)

Para ver ejemplos de código:

  • Puede referirse al ejemplo “Aplicaciones de correo para Outlook: uso de un token de identidad de cliente” en C# para Visual Studio 2012 (bit.ly/ZxS85b) con un ejemplo en C# de una aplicación de correo y de un servicio web que usan tokens de identidad de Exchange para la autenticación.
  • Consulte “Aplicaciones de correo para Outlook: validación de un token de identidad de cliente mediante .NET Framework” (bit.ly/17j9FSZ) para ver un ejemplo sobre cómo usar .NET Framework para validar tokens de identidad de Exchange de clientes.

Acceso a un subconjunto de EWS Con el método Mailbox.makeEwsRequestAsync, las aplicaciones de correo pueden acceder a un subconjunto de las operaciones EWS para crear, encontrar, obtener, actualizar, desplazar o enviar un elemento o carpeta. Podemos usar, por ejemplo, la operación CreateItem para crear una cita, mensaje o contacto. Podemos usar la operación FindItem para buscar elementos en un buzón. Y podemos usar la operación SendItem para enviar un mensaje o una invitación para una reunión. El subconjunto de operaciones disponibles corresponde solo al buzón del usuario. Las otras operaciones de EWS que corresponden a toda una organización, como el acceso a la Lista global de direcciones o la iteración por cada persona dentro de la organización, están fuera del alcance de las aplicaciones de correo. Además, como el subconjunto de operaciones disponibles es poderoso, las aplicaciones de correo deben solicitar permisos de lectura y escritura en el manifiesto de la aplicación y solo los administradores pueden instalar aplicaciones de correo que requieran de dicho permiso.

Cuando llamamos el método Mailbox.makeEwsRequestAsync, solicitamos los EWS en el servidor Exchange que hospeda al buzón del usuario. Antes de llamar makeEwsRequestAsync, debemos especificar los argumentos de entrada para los siguientes parámetros:

  • Parámetro de datos: crear una solicitud SOAP XML para la operación de EWS que pretendemos llamar.
  • Parámetro callback: un método de devolución de llamada que controlará la respuesta de la operación.
  • Parámetro userContext: cualquier dato de entrada para el método de devolución de llamada.

Al finalizar la operación, el marco de aplicaciones para Office llama el método de devolución de llamada con un argumento, que es un objeto AsyncResult similar a los métodos asincrónicos que vimos en la primera parte de esta serie. El método de devolución de llamada puede acceder a la propiedad Async­Result.value para obtener la respuesta XML de SOAP que contiene los datos pertinentes a la operación. Este método también puede acceder a la propiedad AsyncResult.asyncContext para obtener acceso a cualquier otro parámetro de entrada que se pase mediante el parámetro userContext. Luego, el método de devolución de llamada analiza el XML de la respuesta SOAP para obtener los datos pertinentes a sus fines.

Para ver un listado completo de las operaciones de EWS disponibles, junto a otra información detallada, consulte la documentación del Centro de desarrollo “Llamar a servicios web desde una aplicación de correo en Outlook” (bit.ly/12jtH0z).

Para ver el ejemplo de una aplicación de correo que demuestra la llamada a la operación GetItem, consulte el ejemplo “Aplicaciones de correo para Outlook: realizar una solicitud de EWS” en C# para Visual Studio 2012 (bit.ly/Zv3hEQ).

En resumen

Esto resume mi análisis sobre la creación de aplicaciones de correo y la exploración en cuatro partes de la API de JavaScript para Office. Para ver las entregas anteriores de esta serie y el artículo complementario en línea para esta entrega, consulte:

Angela Chu-Hatoun comenzó como desarrolladora de software y luego cambió a la escritura, debido a su mayor interés en explicar cómo funciona el software. Se ha desempeñado como escritora de programación en la división de Office durante 12 años y escribe para desarrolladores sobre la creación de aplicaciones para Office y para otras soluciones de Outlook. Le gusta leer sobre la actualidad, jardinería, viajes, comida y moda.

Gracias a los siguientes expertos técnicos por su ayuda en la revisión de este artículo: Andrew Salamatov (Microsoft) y Tim Wan (Microsoft)
Tim Wan se graduó de Caltech el año 2003 y ostenta un título en Ingeniería y ciencias aplicadas. Ha sido desarrollador de software en Outlook durante los últimos nueve años. Ha trabajado exhaustivamente en la característica de aplicaciones de correo de Outlook 2013, así como en el modelo de objetos de Outlook de las versiones anteriores. Espera proporcionar nuevas características y mejoras para los clientes de todo el mundo.