Calendar Event

Bienvenido al componente Calendar Event. Este nodo funciona como un puente seguro entre tu flujo de automatización en Nappai y tu Google Calendar. Su objetivo principal es ayudarte a gestionar tus eventos de forma rápida y visual, sin necesidad de escribir código ni manejar protocolos complejos.

¿Cómo funciona?

Cuando configuraste este componente y ejecutas tu flujo, este se conecta de forma segura con los servidores de Google para realizar la acción que hayas elegido. El sistema se encarga de todo el trabajo de fondo: valida los datos que ingresas, envía la solicitud a Google Calendar y devuelve la respuesta en un formato que puedes usar en los siguientes pasos de tu automatización. En términos sencillos, tú decides qué quieres hacer (crear, buscar, editar o borrar) y Nappai se encarga de la comunicación segura con tu calendario.

Conexión y Credenciales

Este componente requiere configurar previamente una credencial en el panel de Nappai para poder interactuar con el servicio externo:

Dirígete a la sección de Credenciales en tu panel de Nappai.
Crea una nueva credencial del tipo Google Calendar y guarda los campos requeridos (Proyecto, Client Id, Client Secret, acceso al calendario).
En tu flujo de trabajo, selecciona la credencial guardada en el campo de entrada Credential de este nodo.

Operaciones

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

Create: Crea un nuevo evento en tu calendario con la información que proporciones.
Get: Consulta y devuelve eventos de tu calendario según los filtros que definas.
Update: Modifica la información de un evento que ya existe en tu calendario.
Delete: Elimina un evento específico de tu calendario.

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.

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente. Cada campo puede estar visible en diferentes operaciones:

End: Selecciona la hora de finalización del evento. Debe ser posterior a la hora de inicio.
- Visible en: Create, Update
Start: Selecciona la hora de inicio del evento. Debe ser anterior a la hora de finalización.
- Visible en: Create, Update
Operation: Permite elegir qué acción principal deseas realizar con el componente.
- Visible en: Create, Get, Update, Delete
Attendees: Correo electrónico de los participantes que deseas invitar al evento.
- Visible en: Create, Update
Calendar Id: Identificador único del calendario. Si lo dejas vacío, se usará automáticamente el calendario principal.
- Visible en: Create, Get
Calendar Selection: Elige el calendario de Google que quieres usar para la operación.
- Visible en: Create, Get
Create Meet: Activa esta opción para generar automáticamente una reunión de Google Meet dentro del evento.
- Visible en: Create, Update
Description: Breve descripción del contenido, agenda o propósito del evento.
- Visible en: Create, Update
Event ID: Identificador único del evento. En la operación Get, si se proporciona, se ignorarán otros filtros y se devolverá solo ese evento.
- Visible en: Get, Update, Delete
Input Type: Define cómo se proporcionará el ID del calendario: mediante texto directo o como una selección de tu lista de calendarios.
- Visible en: Create, Get
Location: Ubicación física o enlace virtual donde se llevará a cabo el evento.
- Visible en: Create, Update
Mapping Mode: Habilita el procesamiento por lotes para manejar múltiples registros de datos en una sola ejecución.
- Visible en: Create, Get, Update, Delete
Summary: Título o nombre que se mostrará para el evento en el calendario.
- Visible en: Create, Update
Tool Name: Nombre de la herramienta que se mostrará al agente de IA cuando este seleccione opciones para usar.
- Visible en: Create, Get, Update, Delete
Tool Description: Descripción detallada de lo que hace esta herramienta para ayudar al agente a entender cuándo y cómo usarla.
- Visible en: Create, Get, Update, Delete
Tools arguments metadata: Define los metadatos de los argumentos que utiliza la herramienta para operar correctamente.
- Visible en: Create, Get, Update, Delete
Max Results: Establece el número máximo de eventos que se devolverán en la respuesta.
- Visible en: Create, Get, Update, Delete
Query Filter: Texto para filtrar eventos. El sistema buscará coincidencias en el título, descripción, ubicación o correos de asistentes/organizador. Si no se proporciona, se devolverán todos los eventos.
- Visible en: Create, Get, Update, Delete

Salidas

Al ejecutar este nodo, se generan dos tipos de salida principales:

Data: Contiene la información completa del evento procesado (título, horarios, ubicaciones, asistentes, estados, etc.) en formato estructurado. Puedes usarla para mostrar detalles en otros nodos o almacenarla.
Tool: Expone la funcionalidad del componente para que agentes de IA (como Langgraph) puedan invocarlo automáticamente en decisiones futuras dentro del flujo.

Ejemplo de Respuesta JSON

Cuando el componente ejecuta correctamente una operación (por ejemplo, Create o Get), devuelve datos en este formato. Puedes mapear cualquiera de estos campos en los siguientes nodos de tu automatización: json { “id”: “abc123xyz_event_id”, “htmlLink”: “https://calendar.google.com/calendar/event?eid=abc123xyz”, “summary”: “Reunión de equipo semanal”, “description”: “Discusión de avances del proyecto Q4”, “location”: “Sala de juntas principal / Google Meet”, “start”: { “dateTime”: “2024-11-15T10:00:00”, “timeZone”: “America/Mexico_City” }, “end”: { “dateTime”: “2024-11-15T11:00:00”, “timeZone”: “America/Mexico_City” }, “attendees”: [ { “email”: “juan@empresa.com”, “responseStatus”: “accepted” }, { “email”: “maria@empresa.com”, “responseStatus”: “tentative” } ], “status”: “confirmed”, “creator”: { “email”: “tu@email.com”, “self”: true }, “updated”: “2024-11-10T14:30:00.000Z” }

Conectividad

Este componente está diseñado para fluir naturalmente dentro de un ecosistema de automatización inteligente. Usualmente, sus salidas se conectan a:

LanggraphReactAgent: Para que el agente de IA analice los eventos devueltos o tome decisiones basadas en los datos del calendario (ej. “reprogramar si hay conflicto”).
ParseData: Para extraer, limpiar o transformar los datos crudos del evento antes de enviarlos a reportes o bases de datos.
TextInput: Para permitir que un usuario o flujo ingrese manualmente información adicional (como notas o recordatorios) que se vincule con el evento creado.

Esta disposición lógica permite que los datos del calendario alimenten directamente la lógica de IA y el procesamiento de información, manteniendo el flujo ordenado y eficiente.

Ejemplo de Uso

Escenario: Programar una reunión de lanzamiento de producto

Arrastra el nodo Calendar Event a tu lienzo y selecciona Operation → Create.
Completa los campos:
- Start y End: Define la fecha y hora.
- Summary: Escribe “Lanzamiento Producto X”.
- Attendees: Ingresa los correos del equipo de marketing y desarrollo.
- Create Meet: Actívalo para generar un enlace de Google Meet automáticamente.
Conecta la salida Data de este nodo a un nodo LanggraphReactAgent para que verifique si hay conflictos de horario con otras reuniones.
Conecta la salida a un ParseData para formatear el evento y enviarlo por email al equipo.
Ejecuta el flujo y verifica cómo se crea automáticamente la reunión en tu calendario con el enlace de Meet y las invitaciones enviadas.

Notas Importantes

🔒 Protege tu token OAuth 🔴 El componente almacena y transmite un token de acceso OAuth. Mantén este token en confianza y evita compartirlo, ya que otorga acceso completo de lectura y escritura a tus eventos de Google Calendar.

⚠️ Límites de llamadas a la API de Google 🟡 La API de Google Calendar impone límites (por ejemplo, 1.000 solicitudes cada 100 segundos por usuario). Si superas estos límites, el componente puede devolver errores o bloquearse temporalmente. Planifica flujos de alta frecuencia con pausas o lotes pequeños.

⚠️ Sin soporte para eliminación por lotes 🟢 El componente elimina eventos uno por uno. Si necesitas borrar muchos eventos, ejecuta el componente repetidamente o utiliza una rutina de procesamiento por lotes separada.

📋 Credenciales de API de Google necesarias 🔴 Para usar este componente debes tener un proyecto de Google Cloud con la API de Calendar habilitada y credenciales OAuth 2.0 configuradas. Sin un token válido, el componente no podrá acceder a tus datos de calendario.

ℹ️ Eventos recurrentes devuelven solo la próxima ocurrencia 🟢 Al consultar eventos, las series recurrentes pueden devolverse como una única instancia (la próxima que ocurra). Si necesitas todas las instancias, habilita la expansión de recurrencia en la consulta.

💡 Especifica rangos de fecha para reducir llamadas a la API 🟢 Limita la consulta a un rango de fecha específico (inicio y fin). Esto reduce la cantidad de datos transferidos y acelera la ejecución del componente.

💡 Usa fechas con información de zona horaria 🟢 Al crear o actualizar eventos, incluye información de zona horaria para evitar confusiones con los horarios de inicio y fin en diferentes regiones.

⚙️ Configura el ID del calendario correcto 🟢 Si deseas acceder a un calendario distinto al principal, proporciona el ID del calendario. Si lo dejas vacío, el sistema usará automáticamente el calendario principal.

⚙️ Asegura la conectividad de red 🟢 El componente requiere una conexión a internet activa para comunicarse con los servidores de Google. Verifica tu conexión antes de ejecutar el flujo.

Consejos y Mejores Prácticas

Siempre define un rango de fechas al usar la operación Get para evitar devolver miles de eventos innecesarios y mejorar el rendimiento.
Revisa el campo status en las salidas para confirmar si el evento se creó, actualizó o eliminó correctamente antes de continuar el flujo.
Usa el Mapping Mode cuando necesites procesar listas de eventos o asistirentes en lote; conecta los datos desde un ParseData o base de datos para automatizar masivamente.
Mantén un registro local de los Event ID que generas, ya que serán necesarios para operaciones posteriores de Update o Delete.
Configura la zona horaria correctamente en Start y End si tu equipo trabaja en múltiples regiones para evitar malentendidos en los horarios.

Consideraciones de Seguridad

La integración utiliza OAuth 2.0, lo que garantiza que solo se acceda a los datos del calendario con el permiso explícito del usuario.
No almacenes credenciales sensibles dentro de los flujos de automatización; utilízalas únicamente a través del panel de credenciales de Nappai.
Activa la autenticación de dos factores (2FA) en tu cuenta de Google para reforzar la seguridad del token de acceso.
Revisa regularmente los permisos de aplicación en tu cuenta de Google para revocar accesos a flujos que ya no necesites.