Isaac_Aracena/fulgencio-alertas-sheets-glm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
6 Commits 1 Branch 0 Tags
main
T
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE

README.md

Fulgencio Alertas Sheets - GLM

Workflow n8n que revisa semanalmente el Banco de Propuestas de Fulgencio, detecta campos vacíos, pendientes o inconsistentes, envía una alerta resumida a Google Chat y guarda el detalle en un Sheet de reporte para revisión operativa.

INFORMACIÓN GENERAL

Campo Detalle
Proyecto Fulgencio Alertas Sheets - GLM
Área CDC
Estado Producción
Developer Principal Isaac Aracena
IT Manager Luis Matos
Product Owner Máximo Gómez
Ciclo Shape Up CDC Fulgencio V2.0
Repositorio Gitea fulgencio-alertas-sheets-glm
Workflow n8n Fulgencio Alertas Sheets - GLM
Estado del workflow Activo
Zona horaria America/Santo_Domingo

OBJETIVO

Problema que resuelve

El Banco de Propuestas de Fulgencio depende de información estructurada para que el asistente pueda responder correctamente sobre propuestas, clientes, marcas, países, canales, enlaces y descripciones.

Cuando una propuesta queda con campos vacíos, valores PENDIENTE, SIN PAIS DEFINIDO, OTRO, N/A, NULL, UNDEFINED o datos ubicados en columnas incorrectas, Fulgencio puede perder precisión en sus respuestas o dejar de encontrar propuestas relevantes.

Antes de este flujo, la revisión de esos pendientes dependía de inspección manual del Google Sheet, lo que podía provocar retrasos, errores no detectados y acumulación de datos incompletos.

Solución implementada

Este workflow automatiza la revisión semanal del Banco de Propuestas de Fulgencio.

El flujo:

  • Lee el Google Sheet del Banco de Propuestas.
  • Revisa columnas clave de negocio.
  • Detecta campos vacíos, pendientes o inválidos.
  • Agrupa los pendientes por fila y por columna.
  • Envía una alerta resumida al Google Chat de alertas.
  • Guarda el detalle completo en un Sheet de reporte.
  • Permite al equipo CDC / IT revisar y corregir los datos pendientes.

Usuarios / Beneficiarios

Usuario Beneficio
Equipo CDC Identifica propuestas con datos incompletos o pendientes.
Equipo IT Monitorea la calidad de datos que alimenta Fulgencio.
Usuarios de Fulgencio Obtienen mejores respuestas gracias a datos más completos.

ARQUITECTURA

Diagrama de flujo

[Schedule Trigger semanal]
        ↓
[Sheets - Leer propuestas]
        ↓
[Code - Detectar pendientes]
        ↓
[IF - Hay pendientes]
        ├── true → [HTTP Request - Enviar alerta]
        │
        └── true → [Code - Expandir reporte pendientes]
                    ↓
                  [Sheets - Guardar detalle pendientes]

Stack tecnológico

Componente Tecnología Propósito
Automatización n8n Orquestación del flujo
Fuente principal Google Sheets Banco de Propuestas de Fulgencio
Reporte operativo Google Sheets Registro detallado de pendientes
Alertas Google Chat Webhook Envío de tarjeta/resumen al chat de alertas
Versionado Gitea Backup del workflow y documentación

Integraciones externas

Sistema Tipo de integración Datos que fluyen
Banco de Propuestas de Fulgencio Google Sheets OAuth Lectura de propuestas y metadata
Fulgencio - Reporte de Pendientes Google Sheets OAuth Escritura del detalle de pendientes
Google Chat Webhook / HTTP Request Envío de alerta resumida
n8n Executions Interno n8n Logs, errores y auditoría de ejecución
Gitea Git / backup Export del workflow y README

FUENTES DE DATOS

Google Sheet leído

Campo Detalle
Documento BANCO DE PROPUESTAS DE CDC PARA FULGENCIO FUMADO
Hoja propuestas
Uso Fuente principal que se revisa para detectar campos pendientes

Google Sheet de reporte

Campo Detalle
Documento Fulgencio - Reporte de Pendientes
Hoja pendientes_revision
Uso Guarda el detalle fila por fila y campo por campo de los pendientes encontrados

REGLAS DE NEGOCIO

Columnas validadas

El flujo valida las siguientes columnas del Banco de Propuestas:

  • NOMBRE
  • TIPO DE ACCION
  • CLIENTE
  • MARCA
  • PAIS
  • CANAL
  • ETIQUETAS
  • AÑO
  • Enlace a la propuesta
  • Descripcion

Columnas no validadas

La columna APROBADA no se valida en este flujo porque el equipo puede completarla manualmente más adelante.

Valores considerados pendientes o inválidos

Un campo se considera pendiente cuando:

  • Está vacío.

  • Tiene valor PENDIENTE.

  • Tiene valor UNDEFINED.

  • Tiene valor NULL.

  • Tiene valor N/A.

  • Tiene valor SIN PAIS DEFINIDO.

  • Contiene OTRO.

  • Tiene un valor de aprobación en una columna incorrecta, por ejemplo:

    • APROBADA
    • NO APROBADA
    • PENDIENTE DE APROBACION

Reglas de alerta

  • Si no hay pendientes, el flujo devuelve un mensaje interno de éxito y no envía alerta de revisión.
  • Si hay pendientes, envía una tarjeta resumida al Google Chat configurado.
  • Si hay más de 40 filas pendientes, la alerta muestra solo las primeras 40 filas prioritarias.
  • El detalle completo se guarda en el Sheet de reporte.
  • Las filas prioritarias se ordenan por cantidad de campos pendientes.
  • El resumen de columnas muestra las columnas con más pendientes.

Reglas de seguridad

  • No commitear credenciales, tokens ni URLs privadas de webhooks en documentación pública.
  • El webhook de Google Chat debe gestionarse desde n8n o desde el vault interno.
  • Si se rota el webhook, actualizar el nodo en n8n y exportar nuevamente el workflow.
  • No exponer tokens de Google Chat en README, tickets públicos ni capturas compartidas.

CONFIGURACIÓN Y SETUP

Prerrequisitos

  • Acceso a n8n en el entorno GLM.
  • Acceso al Google Sheet BANCO DE PROPUESTAS DE CDC PARA FULGENCIO FUMADO.
  • Acceso al Google Sheet Fulgencio - Reporte de Pendientes.
  • Credencial Google Sheets account 2 configurada en n8n.
  • Webhook de Google Chat configurado en el nodo HTTP Request - Enviar alerta.
  • Permisos para importar/exportar workflows en n8n.
  • Acceso al repositorio Gitea fulgencio-alertas-sheets-glm.

Credenciales / variables

Credencial / Variable Descripción Dónde se obtiene
Google Sheets OAuth Permite leer y escribir en los Sheets del flujo n8n Credentials
Google Chat Webhook Permite enviar alertas al espacio de Google Chat Google Chat / n8n
SHEET_URL Link del Banco de Propuestas usado en el botón de la alerta Google Sheets
N8N_WORKFLOW_ID ID interno del workflow en n8n n8n
ERROR_WORKFLOW_ID Workflow de error configurado para fallos n8n

Nunca commitear credenciales al repo. Todas las keys, tokens y webhooks deben mantenerse en n8n Credentials, variables seguras o vault interno GLM.

Esquema de base de datos

No aplica.

Este flujo no usa Supabase/Postgres. El almacenamiento del detalle de pendientes se realiza en Google Sheets.

Instalación / Deploy

git clone https://git.digitalcompass.agency/Isaac_Aracena/fulgencio-alertas-sheets-glm.git

# En n8n:
# 1. Abrir n8n.
# 2. Importar el JSON del workflow.
# 3. Revisar credencial de Google Sheets.
# 4. Revisar webhook de Google Chat.
# 5. Ejecutar prueba manual.
# 6. Validar que lea el Banco de Propuestas.
# 7. Validar que escriba en Fulgencio - Reporte de Pendientes.
# 8. Activar el workflow.

CÓMO FUNCIONA

Flujo paso a paso

  1. Schedule Trigger

    • Ejecuta el flujo automáticamente cada viernes a las 9:30 AM, hora de República Dominicana.

  2. Sheets - Leer propuestas

    • Lee todas las filas de la hoja propuestas del Banco de Propuestas de Fulgencio.

  3. Code - Detectar pendientes

    • Revisa las columnas clave.
    • Detecta valores vacíos, pendientes o inválidos.
    • Agrupa pendientes por fila y por columna.
    • Construye el payload para Google Chat.
    • Prepara las filas que se guardarán en el reporte de pendientes.

  4. IF - Hay pendientes

    • Si hay_pendientes = true, continúa con alerta y guardado de detalle.
    • Si hay_pendientes = false, el flujo termina sin enviar alerta.

  5. HTTP Request - Enviar alerta

    • Envía una tarjeta al Google Chat de alertas con:

      • Fecha de revisión.
      • Total de campos pendientes.
      • Columnas con más pendientes.
      • Primeras filas prioritarias.
      • Botón para abrir el Banco de Propuestas.

  6. Code - Expandir reporte pendientes

    • Convierte el arreglo de pendientes en items individuales para poder guardarlos en Google Sheets.

  7. Sheets - Guardar detalle pendientes

    • Guarda cada pendiente en la hoja pendientes_revision.

Schedule / Trigger

Trigger Frecuencia Descripción
Schedule Trigger Semanal, viernes 9:30 AM Revisa el Banco de Propuestas y alerta si hay datos pendientes
Ejecución manual Bajo demanda Permite probar el flujo desde n8n

OUTPUTS

Alerta en Google Chat

Cuando hay pendientes, el flujo envía una tarjeta con:

  • Título: Datos Pendientes - Fulgencio
  • Fecha de revisión.
  • Cantidad de campos pendientes.
  • Columnas con más pendientes.
  • Filas prioritarias.
  • Botón para abrir el Banco de Propuestas.

Reporte en Google Sheets

Cada pendiente se guarda con estos campos:

Campo Descripción
fecha_revision Fecha visible de revisión
fecha_revision_iso Fecha ISO de revisión
fila_origen Fila original en el Banco de Propuestas
propuesta Nombre de la propuesta o archivo
campo Campo pendiente
valor_actual Valor encontrado
motivo Motivo por el que se considera pendiente
enlace_propuesta Link de la propuesta si existe

TESTING

Casos de prueba mínimos

Caso Input Output esperado Estado
Sin pendientes Banco completo y limpio No envía alerta de revisión A completar
Campos vacíos Fila con MARCA, PAIS o Descripcion vacíos Envía alerta y guarda detalle A completar
Valor PENDIENTE Campo con texto PENDIENTE Detecta pendiente A completar
Valor SIN PAIS DEFINIDO Campo PAIS con ese valor Detecta pendiente A completar
Valor OTRO Campo con opción OTRO Detecta revisión necesaria A completar
Valor aprobación en columna incorrecta Campo distinto de APROBADA con APROBADA Detecta inconsistencia A completar
Reporte Sheets Hay pendientes válidos Agrega filas en pendientes_revision A completar
Chat alerta Hay pendientes válidos Envía tarjeta a Google Chat A completar
Error de permisos Sheet sin acceso Error visible en n8n Executions A completar

Checklist de prueba rápida

  • Ejecutar workflow manualmente.
  • Confirmar lectura del Banco de Propuestas.
  • Confirmar detección correcta de pendientes.
  • Confirmar que APROBADA no se valide.
  • Confirmar envío de tarjeta a Google Chat.
  • Confirmar escritura en pendientes_revision.
  • Revisar n8n Executions.
  • Exportar JSON actualizado.
  • Commit en Gitea.

ERRORES CONOCIDOS Y TROUBLESHOOTING

Error Causa probable Solución
401 Unauthorized Credencial de Google Sheets vencida Renovar credencial en n8n
403 Forbidden La cuenta de n8n no tiene acceso al Sheet Compartir el Sheet con la cuenta correcta
Error en Google Chat Webhook inválido o rotado Actualizar webhook en el nodo HTTP
No se guarda detalle Permisos insuficientes en Sheet de reporte Validar acceso al documento Fulgencio - Reporte de Pendientes
Alerta no llega URL de webhook incorrecta o espacio eliminado Revisar configuración del Google Chat Webhook
Demasiadas alertas Muchos campos pendientes o data sin limpiar Revisar Banco de Propuestas y corregir datos
Output vacío No hay pendientes o no hay filas válidas Revisar que el banco tenga datos en columnas clave
Error por columna renombrada Cambió el encabezado del Sheet Actualizar columnasAValidar en el Code node
Duplicados en reporte El flujo se ejecutó varias veces sin limpieza previa Filtrar por fecha o limpiar duplicados manualmente si aplica

MONITOREO

  • Revisar n8n Executions después de cada ejecución programada.
  • Verde = flujo correcto.
  • Rojo = fallo que requiere revisión.
  • Revisar el Google Chat de alertas cada viernes.
  • Revisar el Sheet Fulgencio - Reporte de Pendientes.
  • Validar si el número de pendientes baja luego de correcciones.
  • Si el flujo falla, revisar el workflow de error configurado en n8n.
  • Mantener el export actualizado en Gitea.

Output esperado normal

El flujo debe:

  • Ejecutarse semanalmente.
  • Leer correctamente el Banco de Propuestas.
  • Enviar alerta solo si existen pendientes.
  • Guardar detalle de pendientes cuando existan.
  • Terminar sin errores.
  • Mantener registro en n8n Executions.

ESTRUCTURA DEL REPOSITORIO

/fulgencio-alertas-sheets-glm
|-- README.md
|-- fulgencio-alertas-sheets-glm.json
|-- /docs
|   └-- [capturas o documentación adicional si aplica]
|-- CHANGELOG.md
└-- DECISIONS.md

Si el repo solo contiene README.md y el JSON del workflow, mantener esta estructura simple. Si el proyecto crece, agregar /docs, CHANGELOG.md y DECISIONS.md.

CHANGELOG

2026-06 — v1.0

  • Creación del workflow Fulgencio Alertas Sheets - GLM.
  • Lectura del Banco de Propuestas.
  • Detección de campos pendientes.
  • Envío de alerta a Google Chat.
  • Registro del detalle en Fulgencio - Reporte de Pendientes.
  • Backup del workflow en Gitea.
  • Documentación inicial del README.

DECISIONS LOG

DEC-001 — Usar revisión programada semanal

  • Fecha: 2026-06
  • Contexto: El Banco de Propuestas requiere revisión periódica de calidad de datos.
  • Opciones consideradas: Revisión manual vs revisión automatizada.
  • Decisión: Ejecutar revisión semanal automatizada.
  • Razón: Reduce trabajo manual y mantiene visibilidad constante sobre pendientes.

DEC-002 — No validar la columna APROBADA

  • Fecha: 2026-06
  • Contexto: La aprobación puede completarse manualmente después del registro inicial.
  • Opciones consideradas: Validar APROBADA como obligatoria vs excluirla.
  • Decisión: Excluir APROBADA de la validación.
  • Razón: Evita alertas innecesarias sobre un campo que el equipo completa posteriormente.

DEC-003 — Guardar detalle completo en Sheet separado

  • Fecha: 2026-06
  • Contexto: Una alerta de chat puede saturarse si contiene demasiados pendientes.
  • Opciones consideradas: Enviar todo por chat vs guardar detalle en Sheet.
  • Decisión: Enviar resumen por Chat y guardar detalle completo en Google Sheets.
  • Razón: Mantiene el mensaje limpio y permite análisis posterior.

DEC-004 — Mostrar solo filas prioritarias en el chat

  • Fecha: 2026-06
  • Contexto: Puede haber muchas filas con pendientes.
  • Decisión: Mostrar hasta 40 filas prioritarias.
  • Razón: Evita mensajes excesivamente largos y facilita revisión inicial.

CONTACTOS DEL PROYECTO

Rol Nombre
Product Owner Máximo Gómez
IT Manager Luis Matos
Developer Isaac Aracena

DEFINITION OF DONE

  • Workflow activo en n8n.
  • Schedule semanal validado.
  • Lectura del Banco de Propuestas validada.
  • Validación de columnas correcta.
  • Columna APROBADA excluida de la validación.
  • Alerta de Google Chat probada.
  • Registro en Fulgencio - Reporte de Pendientes probado.
  • Casos de prueba básicos ejecutados.
  • Errores visibles en n8n Executions.
  • Workflow exportado y subido a Gitea.
  • README completo y actualizado.
  • Link del repo agregado al Kan.bn de CDC Fulgencio V2.0.
  • Validado por IT.
  • Validado por responsable del proceso si aplica.

NOTAS OPERATIVAS

  • Este repositorio contiene el backup/documentación del workflow n8n.
  • No debe contener credenciales ni tokens.
  • Si se cambia el Google Sheet principal, actualizar el nodo Sheets - Leer propuestas.
  • Si se cambia el Sheet de reporte, actualizar el nodo Sheets - Guardar detalle pendientes.
  • Si se cambia el espacio de Google Chat, actualizar el nodo HTTP Request - Enviar alerta.
  • Si se agregan nuevas columnas obligatorias al Banco de Propuestas, actualizar columnasAValidar.
  • Si un encabezado del Sheet cambia, el flujo puede dejar de detectar correctamente ese campo.
Reference in New Issue View Git Blame Copy Permalink
S
Description
Backup público automático del workflow n8n: Fulgencio Alertas Sheets - GLM
Readme 63 KiB