Creación de un complemento de Outlook para un proveedor de reuniones en línea
La configuración de una reunión en línea es una experiencia básica para un usuario de Outlook y es fácil crear una reunión de Teams con Outlook. Sin embargo, crear una reunión en línea en Outlook con un servicio que no sea de Microsoft puede ser complicado. Al implementar esta característica, los proveedores de servicios pueden simplificar la experiencia de creación y unión de reuniones en línea para sus usuarios de complementos de Outlook.
Importante
Esta característica se admite en Outlook en la Web, Windows (nuevo y clásico), Mac, Android e iOS con una suscripción a Microsoft 365.
En este artículo, aprenderá a configurar el complemento de Outlook para permitir que los usuarios organicen y se unan a una reunión mediante el servicio de reuniones en línea. A lo largo de este artículo, usaremos un proveedor ficticio de servicios de reuniones en línea, "Contoso".
Configurar el entorno
Complete el inicio rápido de Outlook en el que crea un proyecto de complemento con el generador de Yeoman para complementos de Office.
Configuración del manifiesto
Los pasos para configurar el manifiesto dependen del tipo de manifiesto seleccionado en el inicio rápido.
Abra el archivo manifest.json .
Busque el primer objeto de la matriz "authorization.permissions.resourceSpecific" y establezca su propiedad "name" en "MailboxItem.ReadWrite.User". Debería parecerse a esto cuando haya terminado.
{ "name": "MailboxItem.ReadWrite.User", "type": "Delegated" }En la matriz "validDomains", cambie la dirección URL a
"https://contoso.com", que es la dirección URL del proveedor de reuniones en línea ficticio. La matriz debería tener este aspecto cuando haya terminado."validDomains": [ "https://contoso.com" ],Agregue el siguiente objeto a la matriz "extensions.runtimes". Tenga en cuenta lo siguiente sobre este código.
- La "minVersion" del conjunto de requisitos de buzón se establece en "1.3", por lo que el tiempo de ejecución no se iniciará en plataformas y versiones de Office en las que no se admite esta característica.
- El "id" del runtime se establece en el nombre descriptivo "online_meeting_runtime".
- La propiedad "code.page" se establece en la dirección URL del archivo HTML sin interfaz de usuario que cargará el comando de función.
- La propiedad "lifetime" se establece en "short", lo que significa que el tiempo de ejecución se inicia cuando se selecciona el botón de comando de función y se cierra cuando se completa la función. (En algunos casos poco frecuentes, el tiempo de ejecución se cierra antes de que se complete el controlador. Consulte Tiempos de ejecución en complementos de Office).
- Hay una acción para ejecutar una función denominada "insertContosoMeeting". Creará esta función en un paso posterior.
{ "requirements": { "capabilities": [ { "name": "Mailbox", "minVersion": "1.3" } ], "formFactors": [ "desktop" ] }, "id": "online_meeting_runtime", "type": "general", "code": { "page": "https://contoso.com/commands.html" }, "lifetime": "short", "actions": [ { "id": "insertContosoMeeting", "type": "executeFunction", "displayName": "insertContosoMeeting" } ] }Reemplace la matriz "extensions.ribbons" por lo siguiente. Tenga en cuenta lo siguiente sobre este marcado.
- La "minVersion" del conjunto de requisitos de buzón se establece en "1.3", por lo que las personalizaciones de la cinta de opciones no aparecerán en las plataformas ni en las versiones de Office en las que no se admite esta característica.
- La matriz "contexts" especifica que la cinta de opciones solo está disponible en la ventana organizadora de detalles de la reunión.
- Habrá un grupo de control personalizado en la pestaña predeterminada de la cinta de opciones (de la ventana del organizador de detalles de la reunión) con la etiqueta Contoso meeting.
- El grupo tendrá un botón con la etiqueta Agregar reunión.
- El valor "actionId" del botón se ha establecido en "insertContosoMeeting", que coincide con el "id" de la acción que creó en el paso anterior.
"ribbons": [ { "requirements": { "capabilities": [ { "name": "Mailbox", "minVersion": "1.3" } ], "scopes": [ "mail" ], "formFactors": [ "desktop" ] }, "contexts": [ "meetingDetailsOrganizer" ], "tabs": [ { "builtInTabId": "TabDefault", "groups": [ { "id": "apptComposeGroup", "label": "Contoso meeting", "controls": [ { "id": "insertMeetingButton", "type": "button", "label": "Add meeting", "icons": [ { "size": 16, "url": "icon-16.png" }, { "size": 32, "url": "icon-32.png" }, { "size": 64, "url": "icon-64_02.png" }, { "size": 80, "url": "icon-80.png" } ], "supertip": { "title": "Add a Contoso meeting", "description": "Add a Contoso meeting to this appointment." }, "actionId": "insertContosoMeeting", } ] } ] } ] } ]
Incorporación de compatibilidad con dispositivos móviles
Abra el archivo manifest.json .
En la matriz "extensions.ribbons.requirements.formFactors", agregue "mobile" como elemento. Cuando haya terminado, la matriz debería tener un aspecto similar al siguiente.
"formFactors": [
"desktop",
"mobile"
]
- En la matriz "extensions.ribbons.contexts", agregue
onlineMeetingDetailsOrganizercomo elemento. Cuando haya terminado, la matriz debería tener un aspecto similar al siguiente.
"contexts": [
"meetingDetailsOrganizer",
"onlineMeetingDetailsOrganizer"
],
- En la matriz "extensions.ribbons.tabs", busque la pestaña con "builtInTabId" de "TabDefault". Agregue una matriz secundaria "customMobileRibbonGroups" (como un elemento del mismo nivel de la propiedad "groups" existente). Cuando haya terminado, la matriz "tabs" debe tener un aspecto similar al siguiente:
"tabs": [
{
"builtInTabId": "TabDefault",
"groups": [
<-- non-mobile group objects omitted -->
],
"customMobileRibbonGroups": [
{
"id": "mobileApptComposeGroup",
"label": "Contoso Meeting",
"controls": [
{
"id": "mobileInsertMeetingButton",
"label": "Add meeting",
"type": "mobileButton",
"actionId": "insertContosoMeeting",
"icons": [
{
"scale": 1,
"size": 25,
"url": "https://contoso.com/assets/icon-25.png"
},
{
"scale": 1,
"size": 32,
"url": "https://contoso.com/assets/icon-32.png"
},
{
"scale": 1,
"size": 48,
"url": "https://contoso.com/assets/icon-48.png"
},
{
"scale": 2,
"size": 25,
"url": "https://contoso.com/assets/icon-25.png"
},
{
"scale": 2,
"size": 32,
"url": "https://contoso.com/assets/icon-32.png"
},
{
"scale": 2,
"size": 48,
"url": "https://contoso.com/assets/icon-48.png"
},
{
"scale": 3,
"size": 25,
"url": "https://contoso.com/assets/icon-25.png"
},
{
"scale": 3,
"size": 32,
"url": "https://contoso.com/assets/icon-32.png"
},
{
"scale": 3,
"size": 48,
"url": "https://contoso.com/assets/icon-48.png"
}
]
}
]
}
]
}
]
Sugerencia
Para obtener más información sobre los manifiestos para complementos de Outlook, vea Manifiestos de complementos de Office y Agregar compatibilidad con comandos de complemento en Outlook en dispositivos móviles.
Implementación de la adición de detalles de reuniones en línea
En esta sección, obtenga información sobre cómo el script del complemento puede actualizar la reunión de un usuario para incluir los detalles de la reunión en línea. Lo siguiente se aplica a todas las plataformas admitidas.
Desde el mismo proyecto de inicio rápido, abra el archivo ./src/commands/commands.js en el editor de código.
Reemplace todo el contenido del archivo commands.js por el siguiente JavaScript.
// 1. How to construct online meeting details. // Not shown: How to get the meeting organizer's ID and other details from your service. const newBody = '<br>' + '<a href="https://contoso.com/meeting?id=123456789" target="_blank">Join Contoso meeting</a>' + '<br><br>' + 'Phone Dial-in: +1(123)456-7890' + '<br><br>' + 'Meeting ID: 123 456 789' + '<br><br>' + 'Want to test your video connection?' + '<br><br>' + '<a href="https://contoso.com/testmeeting" target="_blank">Join test meeting</a>' + '<br><br>'; let mailboxItem; // Office is ready. Office.onReady(function () { mailboxItem = Office.context.mailbox.item; } ); // 2. How to define and register a function command named `insertContosoMeeting` (referenced in the manifest) // to update the meeting body with the online meeting details. function insertContosoMeeting(event) { // Get HTML body from the client. mailboxItem.body.getAsync("html", { asyncContext: event }, function (getBodyResult) { if (getBodyResult.status === Office.AsyncResultStatus.Succeeded) { updateBody(getBodyResult.asyncContext, getBodyResult.value); } else { console.error("Failed to get HTML body."); getBodyResult.asyncContext.completed({ allowEvent: false }); } } ); } // Register the function. Office.actions.associate("insertContosoMeeting", insertContosoMeeting); // 3. How to implement a supporting function `updateBody` // that appends the online meeting details to the current body of the meeting. function updateBody(event, existingBody) { // Append new body to the existing body. mailboxItem.body.setAsync(existingBody + newBody, { asyncContext: event, coercionType: "html" }, function (setBodyResult) { if (setBodyResult.status === Office.AsyncResultStatus.Succeeded) { setBodyResult.asyncContext.completed({ allowEvent: true }); } else { console.error("Failed to set HTML body."); setBodyResult.asyncContext.completed({ allowEvent: false }); } } ); }
Pruebas y validación
Siga las instrucciones habituales para probar y validar el complemento y, a continuación, transferir localmente el manifiesto en Outlook en la Web, en Windows (nuevo o clásico) o en Mac. Si el complemento también admite dispositivos móviles, reinicie Outlook en el dispositivo Android o iOS después de realizar la instalación local. Una vez que el complemento se haya cargado de forma local, cree una nueva reunión y compruebe que el botón de alternancia de Microsoft Teams o Skype se reemplace por el suyo propio.
Creación de una interfaz de usuario de reunión
Como organizador de reuniones, debería ver pantallas similares a las tres imágenes siguientes al crear una reunión.
Unirse a la interfaz de usuario de reunión
Como asistente a la reunión, debería ver una pantalla similar a la siguiente imagen al ver la reunión.
Importante
El botón Unirse solo se admite en Outlook en la Web, en Mac, en Android, en iOS y en el nuevo Outlook en Windows. Si solo ve un vínculo de reunión, pero no ve el botón Unirse en un cliente compatible, puede ser que la plantilla de reunión en línea para el servicio no esté registrada en nuestros servidores. Consulte la sección Registrar la plantilla de reunión en línea para obtener más información.
Registro de la plantilla de reunión en línea
El registro del complemento de reunión en línea es opcional. Solo se aplica si desea exponer el botón Unirse en reuniones, además del vínculo de reunión. Una vez que haya publicado el complemento de reunión en línea y desee registrarlo, cree un problema de GitHub con las siguientes instrucciones. Nos pondremos en contacto con usted para coordinar una escala de tiempo de registro.
Importante
- El botón Unirse solo se admite en Outlook en la Web, en Mac, en Android, en iOS y en el nuevo Outlook en Windows.
- Solo se pueden registrar los complementos de reunión en línea publicados en AppSource. No se admiten complementos de línea de negocio.
- El botón Combinar se basa en la tecnología utilizada por los complementos contextuales de Outlook basados en entidades. Dado que esta tecnología se retirará a finales de junio de 2024, actualmente se está desarrollando una implementación alternativa del botón Join . Durante la transición a esta implementación, es posible que el botón Combinar no esté visible al usar un complemento de reunión en línea. Como solución alternativa, debe seleccionar el vínculo de reunión en el cuerpo de la invitación a la reunión para unirse directamente a la reunión. Para obtener más información sobre la retirada de complementos contextuales basados en entidades, vea Retirada de complementos contextuales de Outlook basados en entidades.
- Cree un nuevo problema de GitHub.
- Establezca el título del nuevo problema en "Outlook: Registrar la plantilla de reunión en línea para my-service", reemplazando
my-servicepor el nombre del servicio. - En el cuerpo del problema, reemplace el texto existente por lo siguiente:
- Identificador de recurso del complemento publicado.
- Cadena establecida en la
newBodyvariable o similar de la sección Implementar agregar detalles de reunión en línea anteriormente en este artículo.
- Haga clic en Enviar nuevo problema.
API disponibles
Las siguientes API están disponibles para esta característica.
- API del organizador de citas
- Office.context.mailbox.item.body (Body.getAsync, Body.setAsync)
- Office.context.mailbox.item.end (Hora)
- Office.context.mailbox.item.loadCustomPropertiesAsync (CustomProperties)
- Office.context.mailbox.item.location (Ubicación)
- Office.context.mailbox.item.optionalAttendees (Destinatarios)
- Office.context.mailbox.item.requiredAttendees (Destinatarios)
- Office.context.mailbox.item.start (Hora)
- Office.context.mailbox.item.subject (Asunto)
- Office.context.roamingSettings (RoamingSettings)
- Controlar el flujo de autenticación
Restricciones
Se aplican varias restricciones.
- Solo se aplica a los proveedores de servicios de reuniones en línea.
- Solo aparecerán complementos instalados por el administrador en la pantalla de redacción de la reunión, reemplazando la opción predeterminada de Teams o Skype. Los complementos instalados por el usuario no se activarán.
- El icono del complemento debe estar en escala de grises mediante código
#919191hexadecimal o su equivalente en otros formatos de color. - Solo se admite un comando de función en el modo Organizador de citas (redacción).
- El complemento debe actualizar los detalles de la reunión en el formulario de cita dentro del período de tiempo de espera de un minuto. Sin embargo, cualquier tiempo dedicado en un cuadro de diálogo al complemento abierto para la autenticación, por ejemplo, se excluye del período de tiempo de espera.