Invocación de un complemento de Outlook desde un mensaje accionable

  • Artículo

Los mensajes accionables permiten al usuario realizar acciones rápidas en un correo electrónico o una tarjeta de conector, mientras que los complementos de Outlook permiten ampliar el potencial de Outlook mediante nuevas características e interacciones posibles. Ahora, con el tipo de acción Action.InvokeAddInCommand, puede combinar estos dos tipos de integraciones para crear experiencias más atractivas y eficaces. Por ejemplo, puede:

  • Enviar un mensaje de bienvenida como un mensaje de correo electrónico accionable a los nuevos usuarios después de suscribirse a su servicio, con una acción que les permita instalar y empezar a usar el complemento rápidamente.
  • Utilizar un complemento para las acciones más complejas (como presentar un formulario al usuario) en los escenarios donde una acción simple no sería suficiente.
  • Rellenar los elementos de la interfaz de usuario del complemento antes de presentarla al usuario.

Las acciones Action.InvokeAddInCommand pueden funcionar tanto con complementos que el usuario ya haya instalado como con aquellos que aún no estén instalados. Si el complemento requerido no está instalado, se pedirá al usuario que lo instale con un solo clic.

Nota:

Solo se admite la instalación con un solo clic del complemento necesario si el complemento se publica en AppSource.

En el ejemplo siguiente se muestra la solicitud que se envía al usuario si el complemento no está instalado.

Captura de pantalla del símbolo del sistema para instalar un complemento cuando se invoca desde un mensaje accionable.

Invocación del complemento

Los mensajes que requieren acción invocan complementos especificando una acción Action.InvokeAddInCommand en el mensaje. Esta acción especifica el complemento que se invocará junto con el identificador del botón de complemento que abre el panel de tareas correspondiente.

La información necesaria se encuentra en el manifiesto del complemento. En primer lugar, necesita el identificador del complemento, que se especifica en el id. de elemento.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OfficeApp
  xmlns="http://schemas.microsoft.com/office/appforoffice/1.1"
  xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
  xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0"
  xsi:type="MailApp">
  <Id>527104a1-f1a5-475a-9199-7a968161c870</Id>
  <Version>1.0.0.0</Version>
  ...
</OfficeApp>

El identificador de este complemento es 527104a1-f1a5-475a-9199-7a968161c870.

A continuación, necesitará el atributo id del elemento de control que define el botón de complemento para abrir el panel de tareas correspondiente. Tenga en cuenta que el elemento Control DEBE:

<ExtensionPoint xsi:type="MessageReadCommandSurface">
  <OfficeTab id="TabDefault">
    <Group id="msgReadCmdGroup">
      <Label resid="groupLabel"/>
      <Control xsi:type="Button" id="showInitContext">
        <Label resid="readButtonLabel"/>
        <Supertip>
          <Title resid="readButtonTitle"/>
          <Description resid="readButtonDesc"/>
        </Supertip>
        <Icon>
          <bt:Image size="16" resid="icon-16"/>
          <bt:Image size="32" resid="icon-32"/>
          <bt:Image size="80" resid="icon-80"/>
        </Icon>
        <Action xsi:type="ShowTaskpane">
          <SourceLocation resid="readPaneUrl"/>
          <SupportsPinning>true</SupportsPinning>
        </Action>
      </Control>
    </Group>
  </OfficeTab>
</ExtensionPoint>

El identificador de este botón de complemento es showInitContext.

Con estos dos fragmentos de información, podemos crear una acción Action.InvokeAddInCommand básica como esta:

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "Invoking an add-in command from an Actionable Message card",
      "size": "large"
    }
  ],
  "actions": [
    {
      "type": "Action.InvokeAddInCommand",
      "title": "Invoke \"View Initialization Context\"",
      "addInId": "527104a1-f1a5-475a-9199-7a968161c870",
      "desktopCommandId": "showInitContext"
    }
  ]
}

Pasar datos de inicialización al complemento

La acción Action.InvokeAddInCommand también puede proporcionar contexto adicional al complemento para que pueda realizar más acciones, además de activarse. Por ejemplo, la acción podría proporcionar los valores iniciales para un formulario o información que permita que el complemento cree un "vínculo profundo" a un elemento específico de su servicio de back-end.

Para pasar los datos de inicialización, incluya una propiedad initializationContext en la acción Action.InvokeAddInCommand. No hay ningún esquema establecido para la propiedad initializationContext, por lo que puede incluir cualquier objeto JSON válido.

Por ejemplo, para extender la acción de ejemplo anterior, es posible modificar la acción de este modo:

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "Invoking an add-in command from an Actionable Message card",
      "size": "large"
    }
  ],
  "actions": [
    {
      "type": "Action.InvokeAddInCommand",
      "title": "Invoke \"View Initialization Context\"",
      "addInId": "527104a1-f1a5-475a-9199-7a968161c870",
      "desktopCommandId": "showInitContext",
      "initializationContext": {
        "property1": "Hello world",
        "property2": 5,
        "property3": true
      }
    }
  ]
}

Recepción de datos de inicialización en el complemento

Si la acción pasa datos de inicialización, el complemento debe estar preparado para recibirlos. Los complementos pueden recuperar datos de inicialización llamando al método Office.context.mailbox.item.getInitializationContextAsync. Esto debe hacerse siempre que el panel de tareas se abre o carga un nuevo mensaje.

// Get the initialization context (if present).
Office.context.mailbox.item.getInitializationContextAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    if (asyncResult.value.length > 0) {
      // The value is a string, parse to an object.
      const context = JSON.parse(asyncResult.value);
      // Do something with context.
    } else {
      // Empty context, treat as no context.
    }
  } else {
    // Handle the error.
  }
});

Recursos