Google Forms

El componente Google Forms te permite crear, leer, actualizar y consultar respuestas de formularios de Google directamente desde tu flujo de trabajo en Nappai. Con él puedes automatizar la generación de formularios, recopilar datos de usuarios y procesar las respuestas sin salir de la plataforma.

¿Cómo funciona?

El componente se conecta a la API de Google Forms mediante una credencial de tipo Google Forms API que debes configurar previamente en Nappai. Cuando seleccionas una operación, el componente envía la solicitud correspondiente a la API y devuelve los resultados. Si activas el Mapping Mode, puedes procesar varios registros a la vez, enviando datos en lote y recibiendo respuestas en paralelo.

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 Formularies: Crea un nuevo formulario o añade preguntas a un formulario existente.
Get Formularies: Obtiene la lista de formularios disponibles o la información de un formulario específico.
Update Formularies: Modifica el título, la descripción o las preguntas de un formulario existente.
Get Answers: Recupera las respuestas enviadas a un formulario, con opciones de filtrado y paginación.

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:

Formularies File: Selecciona el archivo de Google Forms que usarás. En la operación Create, si está vacío, se creará un nuevo formulario.
- Visible en: Create Formularies, Get Formularies, Update Formularies, Get Answers
Questions to add to the form: Lista de preguntas que se añadirán al formulario. Cada pregunta es un diccionario con los campos title, type, options, paragraph y choice_type.
- Visible en: Create Formularies, Update Formularies
Operation: Selecciona la operación que deseas ejecutar.
- Visible en: Create Formularies, Get Formularies, Update Formularies, Get Answers
Description of the form: Breve descripción del propósito del formulario.
- Visible en: Create Formularies, Update Formularies
Filter: Filtro para aplicar a la lista de respuestas. Soporta timestamp > N y timestamp >= N con formato RFC3339 UTC.
- Visible en: Get Answers
Form ID: Identificador del formulario de Google Forms. En la operación Create, si está vacío, se creará un nuevo formulario.
- Visible en: Create Formularies, Get Formularies, Update Formularies, Get Answers
Mapping Mode: Habilita el modo de mapeo para procesar múltiples registros en lote.
- Visible en: Create Formularies, Get Formularies, Update Formularies, Get Answers
Mode of Input: Modo de entrada a usar. Puede ser By Id, By Selection o By Url. En la operación Create, el formulario dado se usará como plantilla.
- Visible en: Create Formularies, Get Formularies, Update Formularies, Get Answers
Page Size: Número de respuestas a devolver. El rango permitido es de 1 a 1000.
- Visible en: Get Answers
Response ID: ID de la respuesta a recuperar. Si no se proporciona, se devolverán todas las respuestas.
- Visible en: Get Answers
Title of the form: Título que se usará para el formulario.
- Visible en: Create Formularies, Update Formularies
Tool Name: Nombre del tool que se mostrará al agente cuando el componente esté conectado como herramienta.
- Visible en: Create Formularies, Get Formularies, Update Formularies, Get Answers
Tool Description: Descripción detallada de lo que hace esta herramienta.
- Visible en: Create Formularies, Get Formularies, Update Formularies, Get Answers
Tools arguments metadata: Define los metadatos de los argumentos para las herramientas.
- Visible en: Create Formularies, Get Formularies, Update Formularies, Get Answers

Nota: Este componente requiere una credencial de tipo Google Forms API. Configúrala primero en la sección de credenciales de Nappai y luego selecciónala en el campo “Credential” del componente.

Salidas

Data: Resultado de la operación (por ejemplo, la lista de formularios, la respuesta de creación o las respuestas de un formulario). Se devuelve como un objeto de datos que puedes usar en pasos posteriores.
Tool: Representación de la herramienta que el agente puede usar cuando el componente está conectado como herramienta. Incluye el nombre, la descripción y los argumentos necesarios.

Ejemplo de Uso

Crear un nuevo formulario con preguntas

Selecciona la operación: Create Formularies.
Desactiva Mapping Mode (o déjalo desactivado si solo creas un formulario).

Completa los campos:

Title of the form: Encuesta de satisfacción.
Description of the form: Encuesta para recoger feedback de los clientes.

Questions to add to the form:

[
  {
    "title": "¿Cómo calificaría nuestro servicio?",
    "type": "choiceQuestion",
    "options": ["Excelente", "Bueno", "Regular", "Malo"],
    "choice_type": "RADIO"
  },
  {
    "title": "Comentarios adicionales",
    "type": "textQuestion",
    "paragraph": true
  }
]

Ejecuta el flujo. El componente devolverá en la salida Data el ID del nuevo formulario y en Tool la información necesaria para que un agente lo invoque.

Obtener respuestas filtradas

Selecciona la operación: Get Answers.
Activa Mapping Mode si quieres procesar respuestas de varios formularios a la vez.
Completa los campos:
- Form ID: 1a2b3c4d5e6f7g8h9i0j.
- Filter: timestamp > 2024-01-01T00:00:00Z.
- Page Size: 100.
Ejecuta. La salida Data contendrá la lista de respuestas que cumplen el filtro.

Componentes Relacionados

GoogleFormsCustom: Base que maneja la lógica de conexión y mapeo de datos.
Google Forms API: Credencial que permite la autenticación con Google.

Consejos y Mejores Prácticas

Usa el Modo de Mapeo cuando necesites procesar varios formularios o respuestas en lote; evita llamadas individuales innecesarias.
Limita el Page Size a 1000 respuestas como máximo para no sobrecargar la API.
Aplica filtros siempre que sea posible para reducir la cantidad de datos transferidos.
Guarda el ID del formulario en una variable para reutilizarlo en operaciones posteriores (por ejemplo, actualizar o obtener respuestas).

Consideraciones de Seguridad

La credencial Google Forms API debe guardarse con privilegios mínimos; solo otorga acceso a los servicios de Google Forms necesarios.
Evita exponer el ID del formulario en logs públicos; úsalo solo dentro de flujos internos.
Si compartes el flujo con otros usuarios, asegúrate de que tengan acceso a la credencial configurada.