Invocación de un complemento de Outlook desde un mensaje accionable
Los mensajes accionables permiten al usuario realizar acciones rápidas en un mensaje de correo electrónico y los complementos de Outlook le permiten ampliar Outlook para agregar nuevas características e interacciones. 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.
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:
- Definirse dentro de un punto de extensión MessageReadCommandSurface
- Tener el atributo
xsi:typeestablecido enButton - Contener un elemento Action del tipo
ShowTaskpane
<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.
}
});