Saltearse al contenido
Nappai Documentation

Google Calendar Component

El Google Calendar Component es una herramienta esencial en Nappai que te permite conectar y gestionar tus calendarios de Google de forma automatizada. Funciona como un puente seguro entre Nappai y tu cuenta de Google, facilitando la lectura y escritura de información del calendario para integrarla en tus flujos de trabajo. Ya sea que necesites consultar eventos, crear nuevas reuniones o eliminar entradas, este componente te ayuda a hacerlo de manera rápida y segura.

¿Cómo funciona?

Este componente actúa como un enlace directo entre Nappai y la API de Google Calendar. Cuando lo utilizas, Nappai envía instrucciones seguras a Google para realizar acciones específicas, como leer tus eventos, crear reuniones o modificar datos.

Internamente, el componente utiliza credenciales OAuth para garantizar que solo se acceda a tu calendario con tu permiso explícito. Tras recibir la respuesta de Google, procesa la información y te devuelve los datos estructurados o confirmaciones de la acción, los cuales puedes usar en los siguientes pasos de tu automatización.

Conexión y Credenciales

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

  1. Dirígete a la sección de Credenciales en tu panel de Nappai.
  2. Crea una nueva credencial del tipo Google Calendar y guarda los campos requeridos: Select Project, Client Id, Client Secret y Google Calendar access.
  3. En tu flujo de trabajo, selecciona la credencial que acabas de configurar en el campo de entrada Credential de este componente.

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: Permite crear un nuevo calendario o evento en tu Google Calendar.
  • Get: Obtiene datos de calendarios o eventos existentes para consultarlos.
  • Update: Modifica la información de un calendario o evento que ya existe.
  • Delete: Elimina un calendario o evento seleccionado de forma permanente.

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:

  • Operation: Selecciona la acción que deseas realizar (Crear, Obtener, Actualizar o Eliminar).
    • Visible en: Create, Get, Update, Delete
  • Calendar Id: Introduce el ID del calendario al que deseas acceder. Si no se proporciona en la operación Get, se devolverán todos los calendarios.
    • Visible en: Get, Update, Delete
  • Calendar Selection: Selecciona el calendario desde tu Google Calendar mediante una lista desplegable.
    • Visible en: Get, Update, Delete
  • Description: Una breve descripción del calendario. Útil para definir el propósito del calendario.
    • Visible en: Create, Update
  • Input Type: Define el tipo de entrada a usar. Si seleccionas ‘Id’, la entrada será el ID del calendario. Si seleccionas ‘Selection’, la entrada será una selección del calendario.
    • Visible en: Get, Update, Delete
  • Mapping Mode: Habilita el modo de mapeo para procesar múltiples registros en lote.
    • Visible en: Create, Get, Update, Delete
  • Summary: El resumen que determina el nombre del calendario.
    • Visible en: Create, Update
  • Tool Name: El nombre de la herramienta que se mostrará al agente de IA cuando este componente se use como herramienta.
    • Visible en: Create, Get, Update, Delete
  • Tool Description: Una descripción detallada de lo que hace esta herramienta, ayudando 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 para las herramientas.
    • Visible en: Create, Get, Update, Delete

Salidas

El componente produce las siguientes salidas que puedes conectar a otros nodos de tu flujo:

  • Data: Contiene la información estructurada devuelta por Google Calendar. Dependiendo de la operación, esto puede ser una lista de calendarios, los detalles de un evento específico o una lista de eventos filtrados. Es ideal para mapear datos en pasos posteriores.
  • Tool: Expone el componente como una herramienta disponible para el agente de IA de Nappai, permitiendo que el agente interactúe con el calendario de forma autónoma.

Ejemplo de Respuesta JSON

A continuación se muestra un ejemplo realista de lo que devuelve este componente al realizar una operación Get exitosa. Puedes mapear estos campos en nodos posteriores: json { “kind”: “calendarList”, “etag”: ""p31ao7d384e0c000"", “items”: [ { “kind”: “calendarListEntry”, “etag”: ""etiqueta123"", “id”: “usuario@group.calendar.google.com”, “summary”: “Calendario Principal”, “description”: “Calendario por defecto de Google”, “primary”: true, “backgroundColor”: “#3f51b5”, “foregroundColor”: “#ffffff”, “timeZone”: “America/Mexico_City” }, { “kind”: “calendarListEntry”, “id”: “es.mexican#holidays@group.v.calendar.google.com”, “summary”: “Días festivos en México”, “selected”: true, “accessRole”: “reader” } ] }

Conectividad

Es común conectar las salidas de este componente a nodos que requieran información de fechas o eventos, como un correo electrónico, un mensaje de chat o un filtro de datos. Por ejemplo:

  • Conectar Data a un nodo de Crear Correo Electrónico para enviar recordatorios de eventos.
  • Conectar Data a un nodo de Filtro para procesar solo los eventos de una fecha específica.
  • Utilizar Tool dentro de flujos de Agente de IA para permitir que el agente gestione tu calendario de forma natural.

Ejemplo de Uso

Imagina que quieres automatizar la revisión de tus reuniones del día.

  1. Agrega el Google Calendar Component a tu flujo.
  2. Selecciona la operación Get.
  3. En Calendar Id, ingresa el ID de tu calendario o usa Calendar Selection para elegirlo.
  4. Conecta la salida Data a un nodo de Enviar Notificación o Crear Documento.
  5. El flujo recuperará tus eventos y los enviará a donde tú decidas, ahorrándote la tarea de revisar el calendario manualmente.

Notas Importantes

🔒 Protect Your Credentials 🔴 Keep your OAuth tokens and API keys secure. Never expose them in public scripts or version control. Store them in a protected environment variable or secret manager.

⚠️ Only Google Calendar Supported 🟡 This component works exclusively with Google Calendar. It cannot read or write to other calendar services such as Outlook or Apple Calendar.

📋 Google Account and OAuth Setup 🔴 To use this component you must have a Google account and grant the necessary OAuth permissions. Set up your Google API credentials before connecting the component.

💡 Filter by Date Range 🟢 When querying events, specify a start and end date to limit the amount of data retrieved. This improves performance and reduces network traffic.

⚙️ API Scopes and Permissions 🟡 Ensure the OAuth scope includes at least calendar.readonly for reading events. If you need to modify calendars, add calendar.modify scope. Using the minimal scope improves security.

ℹ️ Time Zone Handling 🟢 Event times are returned in the time zone configured in the Google Calendar settings. If your application expects UTC, convert the times accordingly to avoid confusion.

Consejos y Mejores Prácticas

  • Usa el Modo de Mapeo si necesitas procesar múltiples calendarios o eventos en un solo flujo para ahorrar tiempo.
  • Siempre verifica que la zona horaria de tu Google Calendar coincida con la de tu aplicación para evitar malentendidos en las fechas.
  • Al utilizar operaciones de lectura, aplica filtros por rango de fechas para obtener resultados más rápidos y relevantes.
  • Revisa los permisos de OAuth en la configuración de credenciales; otorga solo los permisos necesarios para mantener tu cuenta segura.

Consideraciones de Seguridad

  • Credenciales Seguras: Nunca compartas tu Client Secret o claves API. Mantén las credenciales almacenadas en el gestor de secretos de Nappai y evita hardcodearlas en tus flujos.
  • Permisos OAuth: Configura el componente con las credenciales que tengan el alcance mínimo necesario (por ejemplo, calendar.readonly solo para lectura) para reducir el riesgo de acceso no autorizado.
  • Validación de Entradas: Asegúrate de que los IDs de calendario y las fechas proporcionadas sean válidas para evitar errores de flujo o accesos no deseados.
  • Gestión de Errores: El componente devuelve códigos de estado y mensajes de error; utiliza estos datos en tu flujo para manejar fallos de manera adecuada y notificar al usuario si algo falla.