Calendar

El componente Calendar te permite interactuar con tu calendario de Outlook directamente desde el dashboard de Nappai. Con él puedes crear nuevos eventos, buscar eventos existentes, actualizar o eliminar eventos y gestionar los propios calendarios. Todo se hace a través de la API de Microsoft Graph, usando la credencial que hayas configurado previamente.

¿Cómo funciona?

Cuando activas el componente, Nappai envía peticiones a la API de Microsoft Graph con los datos que ingreses. La credencial de tipo Microsoft Outlook contiene el token OAuth necesario para autenticarte y autorizar las acciones. El componente admite dos modos de operación:

• Modo Simplificado: Usa valores por defecto y opciones básicas.
• Modo Avanzado: Permite configurar cada parámetro con mayor detalle.

Si habilitas Mapping Mode, el componente puede procesar varios registros a la vez, lo que es útil para flujos de trabajo en lote.

Operaciones

Este componente ofrece varias operaciones que puedes seleccionar según lo que necesites hacer. Solo puedes usar una operación a la vez:

• Get Calendar Events: Recupera eventos dentro de un rango de fechas o con una búsqueda específica.
• Create Event: Crea un nuevo evento en el calendario seleccionado.
• Update Event: Modifica los detalles de un evento existente.
• Delete Event: Elimina un evento por su ID.
• Get Event by ID: Obtiene la información de un evento concreto.
• Get Calendars: Lista todos los calendarios disponibles en la cuenta.
• Create Calendar: Crea un nuevo calendario.
• Update Calendar: Actualiza el nombre o la configuración de un calendario.
• Delete Calendar: Elimina un calendario por su ID.
• Get Calendar by ID: Obtiene los detalles de un calendario específico.

Para usar el componente, primero selecciona la operación que necesitas en el campo Operation (Operación).

Entradas

Modo de Mapeo (Mapping Mode)

Este componente cuenta con un modo especial llamado “Mapping Mode” (Modo de Mapeo). Cuando activas este modo mediante el interruptor, se habilita una entrada adicional llamada Mapping Data y cada campo de entrada te ofrece tres formas diferentes de proporcionar datos:

• Fixed (Fijo): Escribes el valor directamente en el campo.
• Mapped (Mapeado): Conectas la salida de otro componente para usar su resultado como valor.
• Javascript: Escribes código Javascript para calcular el valor dinámicamente.

Esta flexibilidad te permite crear flujos de trabajo más dinámicos y conectados.

Credencial

Para usar este componente, primero debes configurar una credencial Microsoft Outlook en la sección de credenciales de Nappai y luego seleccionarla en el campo Credential del componente. La credencial requiere:

• Client ID
• Client Secret
• Tenant ID
• Microsoft Outlook Access

Puedes crearla en el Microsoft Azure Portal registrando una aplicación y otorgándole los permisos necesarios para acceder a Outlook.

Campos de Entrada

• Operation: Selecciona la operación que deseas ejecutar.

  • Visible en: Get Calendar Events, Create Event, Update Event, Delete Event, Get Event by ID, Get Calendars, Create Calendar, Update Calendar, Delete Calendar, Get Calendar by ID

• Calendar: Outlook Calendar to use.

  • Visible en: Get Calendar Events, Create Event, Update Event, Delete Event, Get Event by ID

• Calendar ID: Unique identifier of the calendar.

  • Visible en: Update Calendar, Delete Calendar, Get Calendar by ID

• Calendar Name: Name of the calendar.

  • Visible en: Create Calendar, Update Calendar

• Event ID: Unique identifier of the calendar event.

  • Visible en: Update Event, Delete Event, Get Event by ID

• Event Subject: Subject/title of the calendar event.

  • Visible en: Create Event, Update Event

• Event Body: Event description or body content.

  • Visible en: Create Event, Update Event

• Location: Event location or meeting place.

  • Visible en: Create Event, Update Event

• Attendees: Email addresses of attendees (comma‑separated).

  • Visible en: Create Event

• Is Online Meeting: Mark event as online meeting.

  • Visible en: Create Event

• Event Type: Choose the type of Calendar Event you want to create between regular Events or Online Meetings.

  • Visible en: Create Event

• Time Zone: Time zone for the event (e.g., ‘UTC’, ‘America/New_York’).

  • Visible en: Create Event, Update Event

• Search Start Time: Start time range for searching events.

  • Visible en: Get Calendar Events, Create Event, Update Event

• Search End Time: End time range for searching events.

  • Visible en: Get Calendar Events, Create Event, Update Event

• Search Query: Search term to filter events by subject or content.

  • Visible en: Get Calendar Events

• Mode: Choose between a simplified setup with default options or full control with advanced settings.

  • Visible en: Get Calendar Events, Create Event, Update Event, Get Calendar by ID

• Mapping Mode: Enable mapping mode to process multiple data records in batch.

  • Visible en: Get Calendar Events, Create Event, Update Event, Delete Event, Get Event by ID, Get Calendars, Create Calendar, Update Calendar, Delete Calendar, Get Calendar by ID

• Tool Name: The name of the tool that will be used when this component is connected as a tool.

  • Visible en: Get Calendar Events, Create Event, Update Event, Delete Event, Get Event by ID, Get Calendars, Create Calendar, Update Calendar, Delete Calendar, Get Calendar by ID

• Tool Description: A detailed description of what this tool does.

  • Visible en: Get Calendar Events, Create Event, Update Event, Delete Event, Get Event by ID, Get Calendars, Create Calendar, Update Calendar, Delete Calendar, Get Calendar by ID

• Tools arguments metadata: Defines the arguments metadata for the tools.

  • Visible en: Get Calendar Events, Create Event, Update Event, Delete Event, Get Event by ID, Get Calendars, Create Calendar, Update Calendar, Delete Calendar, Get Calendar by ID

Salidas

• Data: Devuelve los datos obtenidos o confirmación de la operación (método: perform_action).
• Tool: Devuelve la configuración del tool para que el agente lo utilice (método: to_toolkit).

Ejemplo de Uso

Crear un evento

1. Selecciona la operación Create Event.
2. Elige el calendario en el campo Calendar.
3. Rellena Event Subject, Event Body, Location, Attendees, Time Zone y selecciona Event Type (por ejemplo, Online Meeting).
4. Marca Is Online Meeting si corresponde.
5. Haz clic en Run.
   El componente creará el evento y devolverá la información del mismo en la salida Data.

Obtener eventos de un rango

1. Selecciona la operación Get Calendar Events.
2. Elige el calendario en Calendar.
3. Define Search Start Time y Search End Time (por ejemplo, 2024-10-01T08:00:00Z y 2024-10-01T18:00:00Z).
4. Opcionalmente, añade un Search Query para filtrar por asunto.
5. Haz clic en Run.
   El componente devolverá la lista de eventos dentro del rango especificado.

Componentes Relacionados

• OutlookCalendarComponent: Este mismo componente que permite gestionar eventos y calendarios en Outlook.

Consejos y Mejores Prácticas

• Usa Mapping Mode cuando necesites procesar varios eventos a la vez, lo que ahorra tiempo y reduce llamadas a la API.
• Verifica que la credencial tenga los permisos necesarios (Calendario, Calendario.ReadWrite) antes de ejecutar operaciones.
• Cuando crees eventos en línea, selecciona Event Type como Online Meeting y marca Is Online Meeting para que se genere automáticamente el enlace de reunión.
• Utiliza Search Query para filtrar eventos por palabras clave y reducir la cantidad de datos devueltos.
• Asegúrate de que la zona horaria (Time Zone) coincida con la zona de tu calendario para evitar confusiones de horario.

Consideraciones de Seguridad

• La credencial Microsoft Outlook contiene tokens sensibles; guárdala en un lugar seguro y evita compartirla.
• Los tokens de acceso tienen un tiempo de vida limitado; si la operación falla por expiración, actualiza la credencial.
• Concede solo los permisos mínimos necesarios (por ejemplo, Calendars.ReadWrite) para limitar el alcance de la aplicación.
• Revisa los logs de Nappai para detectar accesos inesperados o anomalías en las llamadas a la API.