Files

T

Isaac_Aracena 9435ae5354 Actualizar README con validación TASK 3 BambooHR API

2026-06-22 18:19:38 +00:00

20 KiB

Raw Blame History

BambooHR Agent

Agente conversacional que permite al equipo de RRHH consultar, modificar y reportar data de empleados en BambooHR mediante lenguaje natural, eliminando errores de nomina y reduciendo tiempo operativo.

Informacion General

Campo	Detalle
Proyecto	BambooHR Agent
Area	RRHH
Estado	En Progreso
Developer Principal	Isaac Aracena
IT Manager	Luis Matos
Fecha de Inicio	Junio 8, 2026
Fecha de Cierre Estimada	Julio 19, 2026
Ciclo Shape Up	Ciclo #1 — Semana 1 de 6
Board de Ejecucion	https://pmit.digitalcompass.agency/boards/4inodhfrgx0h
PRD del Proyecto	[https://docs.google.com/document/d/1OHn7v3nZeVh94-Gm0COQ1yjkX6HrRTqWhwamH4_gOgc/edit?usp=drive_link

Objetivo

Problema que resuelve

El equipo de RRHH (13-20 personas) gestiona toda la data de empleados entrando manualmente a BambooHR. Editar salarios, agregar empleados, desvincular, subir archivos, consultar informacion y generar reportes toma entre 5-15 minutos por operacion. Cuando hay multiples cambios pendientes, el equipo los pospone. Esos cambios olvidados llegan a nomina con datos incorrectos, generando errores que afectan al empleado, a RRHH y al area administrativa y de nomina.

Solucion implementada

Agente conversacional conectado a BambooHR via API que recibe instrucciones en lenguaje natural por chat y las ejecuta directamente. Opera en tres modos: accion (edita, agrega, desvincula, sube archivos), consulta (responde preguntas sobre data de empleados) y reporte (genera reportes estandar y personalizados). Cada operacion queda registrada en un log de auditoria.

Usuarios / Beneficiarios

Operan el agente: Equipo de RRHH (13-20 personas) y equipo IT
Acceso admin (settings de BambooHR): Solo Maximo Gomez
Se benefician del output: Equipo administrativo, nomina y empleados GLM en 14 paises

Arquitectura

Diagrama de flujo

Usuario envia instruccion por chat
        |
        v
Agente valida identidad y permisos del usuario
        |
        v
Agente interpreta instruccion en lenguaje natural
        |
        +---> Modo accion  --> Ejecuta cambio en BambooHR API
        |
        +---> Modo consulta --> Extrae data de BambooHR API --> Responde en chat
        |
        +---> Modo reporte  --> Genera reporte estandar o personalizado --> Entrega en chat
        |
        v
Registro en log de auditoria (quien, que, cuando)
        |
        v
Confirmacion al usuario

Stack tecnologico

Componente	Tecnologia	Proposito
Agente IA	Claude / Gemini	Interpretacion de lenguaje natural y ejecucion
Automatizacion	n8n / Python	Orquestacion del flujo
Interfaz de chat	A definir por Luis Matos (WhatsApp / Google Chat)	Canal de comunicacion con el agente
Autenticacion	A definir por IT	Validar identidad y permisos del usuario
Log de auditoria	A definir por IT (Supabase / Google Sheets)	Registro de cambios
Infraestructura	Google Cloud / Servidor Virtual	Hosting y ejecucion

Integraciones externas

Sistema	Tipo de integracion	Datos que fluyen
BambooHR	API REST (full access)	Lectura, escritura y reportes de data de empleados
Google Workspace	OAuth	Autenticacion de usuarios GLM
WhatsApp / Google Chat	API	Instrucciones entrantes y respuestas salientes
Supabase / Google Sheets	API	Log de auditoria de cambios

Configuracion y Setup

Prerequisitos

API key de BambooHR configurada (plan con full access confirmado)
Canal de chat definido y configurado (WhatsApp o Google Chat — pendiente decision de Luis Matos)
Sistema de autenticacion configurado (pendiente definicion de IT)
Variable de entorno BAMBOOHR_API_KEY configurada
Variable de entorno BAMBOOHR_SUBDOMAIN configurada
Almacenamiento del log de auditoria configurado (pendiente Supabase o Google Sheets)

Variables de entorno

Variable	Descripcion	Donde se obtiene
BAMBOOHR_API_KEY	API Key de BambooHR	BambooHR -> Admin -> API Keys
BAMBOOHR_SUBDOMAIN	Subdominio de la cuenta GLM en BambooHR	URL de BambooHR (ej. glm.bamboohr.com)
CHAT_CHANNEL	Canal de chat activo (whatsapp / google_chat)	A definir por Luis Matos
AUTH_SECRET	Secret del sistema de autenticacion	A definir por IT
LOG_STORAGE_URL	URL del almacenamiento del log	Supabase o Google Sheets — a definir
ADMIN_USER_ID	ID del usuario con acceso a settings (Maximo Gomez)	A definir al configurar autenticacion

NUNCA commitear credenciales al repo. Todas las keys van en el vault de credenciales GLM.

Instalacion / Deploy

# Clonar el repo
git clone https://gitea.glm.com/glm-it/bamboohr-agent

# Instalar dependencias
pip install -r requirements.txt

# Configurar variables de entorno
cp .env.example .env
# Editar .env con las credenciales reales

# Correr en local
python main.py

Como funciona

Flujo paso a paso

Trigger: El usuario envia un mensaje de texto al canal de chat definido (WhatsApp o Google Chat)
Autenticacion: El sistema valida la identidad del usuario y sus permisos antes de procesar la instruccion
Interpretacion: El agente (Claude o Gemini) analiza el mensaje y determina el modo de operacion — accion, consulta o reporte
Ejecucion:
- Modo accion: Llama a los endpoints correspondientes de BambooHR API para ejecutar el cambio. Si la accion es destructiva (ej. desvincular empleado), el agente pide confirmacion antes de ejecutar
- Modo consulta: Consulta BambooHR API, extrae la data solicitada y la formatea en lenguaje natural
- Modo reporte: Genera el reporte solicitado (estandar o personalizado) a partir de la data de BambooHR
Log: Cada operacion se registra automaticamente en el log de auditoria con usuario, accion, empleado afectado y timestamp
Confirmacion: El agente responde al usuario en el chat con el resultado de la operacion

Triggers

Trigger	Frecuencia	Descripcion
Mensaje entrante en canal de chat	On demand	Usuario envia instruccion o consulta en lenguaje natural

TASK 2 — Mapeo de endpoints BambooHR API

Estado: Completada Documento de entrega: TASK 2 — Mapeo de endpoints BambooHR API

Se revisó la documentación de BambooHR API y se mapearon los endpoints relevantes para construir el BambooHR Agent como producto final. El mapeo cubre los tres modos principales del agente: acción, consulta y reporte.

Categorías de endpoints identificadas

Categoría	Uso dentro del agente
Metadata	Validar conexión, campos, tablas y listas disponibles
Empleados	Buscar, listar y consultar empleados
Tablas históricas	Consultar o modificar `jobInfo`, `compensation`, `employmentStatus`, bonos y comisiones
Acciones	Crear empleados, actualizar datos básicos y agregar filas históricas
Archivos	Listar, subir, descargar o eliminar documentos de empleados
Reportes	Ejecutar reportes guardados y reportes personalizados
Datasets	Consultas avanzadas para reportería dinámica
Webhooks / cambios	Monitorear cambios en empleados y tablas
Time Off	Consultar tipos y balances de vacaciones/licencias

Endpoints principales documentados

GET  /api/v1/company_information
GET  /api/v1/meta/fields
GET  /api/v1/meta/tables
GET  /api/v1/meta/lists

GET  /api/v1/employees
GET  /api/v1/employees/directory
GET  /api/v1/employees/{id}
GET  /api/v1/employees/{id}/tables/{table}

POST /api/v1/employees
POST /api/v1/employees/{id}
POST /api/v1/employees/{id}/tables/{table}
POST /api/v1/employees/{id}/tables/{table}/{rowId}

GET  /api/v1/employees/{id}/files/view
POST /api/v1/employees/{id}/files
GET  /api/v1/employees/{id}/files/{fileId}
DELETE /api/v1/employees/{id}/files/{fileId}

GET  /api/v1/reports/{reportId}
POST /api/v1/reports/custom

GET  /api/v1_2/datasets
GET  /api/v1_2/datasets/{datasetName}/fields
POST /api/v1_2/datasets/{datasetName}/field-options
POST /api/v1_2/datasets/{datasetName}/data

GET  /api/v1/employees/changed
GET  /api/v1/employees/changed/tables/{table}
GET  /api/v1/webhooks
GET  /api/v1/meta/time_off/types

TASK 3 — Integración base con BambooHR API

Estado: Validada técnicamente en n8n.

Se construyó un workflow de validación base para probar la integración real con BambooHR API usando HTTP Request en n8n. La prueba se realizó con API Key real de GLM, autenticación Basic Auth y subdominio glm.bamboohr.com.

Validaciones realizadas

Conexión correcta con BambooHR API.
API Key real configurada en credencial segura de n8n.
Subdominio real confirmado: glm.bamboohr.com.
Lectura de metadata: company_information, meta/fields, meta/tables y meta/lists.
Lectura de directorio de empleados.
Identificación de empleado de prueba existente:
- ID: 40557
- Nombre API: Bruce Wayne
- Nombre preferido: Batman
- Correo: psmaxg1@gmail.com
Lectura de empleado por ID.
Escritura básica sobre empleado de prueba mediante POST /api/v1/employees/{id}.
Confirmación de escritura básica actualizando workPhoneExtension.
Escritura en tabla histórica jobInfo mediante POST /api/v1/employees/{id}/tables/jobInfo.
Confirmación por GET /api/v1/employees/{id}/tables/jobInfo.

Decisiones de prueba

No se creó un empleado nuevo con POST /api/v1/employees, porque RRHH ya contaba con un empleado de prueba existente. Esto evita generar una licencia adicional innecesaria.

Las escrituras en compensation y employmentStatus no se ejecutaron en esta tarea por tratarse de datos sensibles relacionados con nómina y estatus laboral. Quedan pendientes para una prueba controlada posterior con autorización explícita de RRHH/IT.

Resultado

La integración base conecta correctamente con BambooHR, lee información real y escribe datos sobre un empleado de prueba sin errores. La TASK 3 queda validada a nivel técnico para continuar con la siguiente capa del producto.

Testing

Como probar el sistema

# Test unitario
python -m pytest tests/

# Test de integracion con BambooHR API
python tests/integration_test.py

# Test manual del agente
# Enviar mensaje de prueba al canal de chat configurado

Casos de prueba minimos

Caso	Input	Output esperado	Estado
Editar salario	"Actualiza el salario de [empleado] a $X"	Confirmacion + cambio ejecutado en BambooHR	Pendiente
Agregar empleado	"Agrega nuevo empleado [datos]"	Confirmacion + empleado creado en BambooHR	Pendiente
Desvincular empleado	"Desvincula a [empleado] desde hoy"	Solicitud de confirmacion + ejecucion tras confirmar	Pendiente
Subir archivo	"Sube este contrato al perfil de [empleado]"	Archivo subido al perfil en BambooHR	Pendiente
Consulta de data	"Cuantos dias de vacaciones tiene [empleado]?"	Respuesta con dato correcto extraido de BambooHR	Pendiente
Reporte estandar	"Dame el headcount por pais"	Reporte generado y entregado en el chat	Pendiente
Reporte personalizado	"Lista empleados con salario no actualizado en 6 meses"	Reporte personalizado generado	Pendiente
Acceso a settings sin permiso	Usuario no-admin intenta modificar configuracion	Acceso denegado, sin ejecucion	Pendiente
Acceso a settings con permiso	Maximo Gomez modifica configuracion	Cambio ejecutado correctamente	Pendiente
Log de auditoria	Cualquier accion ejecutada	Entrada registrada en log con todos los campos	Pendiente

Errores conocidos y troubleshooting

Error	Causa probable	Solucion
401 Unauthorized en BambooHR	API Key vencida o incorrecta	Renovar key en BambooHR -> Admin -> API Keys y actualizar .env
Acceso denegado a settings	Usuario no tiene permisos de admin	Verificar ADMIN_USER_ID en variables de entorno
Agente no interpreta la instruccion	Instruccion muy ambigua o incompleta	El agente debe solicitar aclaracion al usuario antes de ejecutar
Log no registra la accion	Conexion con almacenamiento del log fallida	Verificar LOG_STORAGE_URL y credenciales de acceso
Canal de chat no recibe mensajes	Webhook no configurado correctamente	Revisar configuracion del canal en la plataforma correspondiente

Monitoreo

Como saber si el sistema esta funcionando

Log de auditoria: Revisar que las acciones ejecutadas esten siendo registradas correctamente
Canal de chat: Enviar un mensaje de prueba y verificar que el agente responda
BambooHR: Verificar aleatoriamente que los cambios ejecutados por el agente se reflejen correctamente
Alertas: A definir por IT — el sistema debe enviar alerta a Luis Matos si falla una ejecucion critica

Estructura del repositorio

/bamboohr-agent
├── README.md                  <- Este archivo
├── .env.example               <- Variables de entorno de ejemplo (sin valores reales)
├── main.py                    <- Punto de entrada principal
├── /src
│   ├── agent.py               <- Logica del agente — interpretacion de instrucciones
│   ├── bamboohr_client.py     <- Integracion con BambooHR API
│   ├── auth.py                <- Sistema de autenticacion y permisos
│   ├── audit_log.py           <- Registro de auditoria
│   └── chat_interface.py      <- Integracion con canal de chat
├── /tests
│   ├── test_agent.py          <- Tests del agente
│   ├── test_bamboohr.py       <- Tests de integracion con BambooHR API
│   └── integration_test.py    <- Tests de integracion completos
├── /docs
│   └── architecture.png       <- Diagrama de arquitectura (pendiente)
├── CHANGELOG.md               <- Historial de cambios
└── DECISIONS.md               <- Log de decisiones tecnicas

CHANGELOG

[Junio 8, 2026] v0.1 — Inicio del ciclo. Repo creado.
[Junio 15, 2026] TASK 2 — Endpoints BambooHR API mapeados y documentados para acciones, consultas y reportes del producto final.

DECISIONS LOG

DEC-001 — Canal de chat

Fecha: Junio 2026
Contexto: El agente necesita un canal de comunicación para recibir instrucciones y responder al equipo de RRHH. GLM opera dentro de Google Workspace y el proyecto manejará acciones sensibles sobre información de empleados en BambooHR.
Opciones consideradas: WhatsApp API vs Google Chat API
Decisión: Usar Google Chat como canal principal para la primera versión del BambooHR Agent.
Razón: Google Chat permite trabajar con identidad corporativa de Google Workspace, usuarios internos, mejor trazabilidad y menor riesgo de suplantación que WhatsApp para acciones sensibles de RRHH.
Impacto: WhatsApp queda como posible canal futuro para notificaciones, recordatorios, alertas o consultas simples de bajo riesgo, pero no como canal principal para ejecutar acciones críticas en BambooHR.

DEC-002 — Sistema de autenticación

Fecha: Junio 2026
Contexto: Se necesita validar la identidad de cada usuario antes de permitir consultas, modificaciones, reportes o acciones sobre BambooHR.
Opciones consideradas: Google Workspace / OAuth vs sistema propio de usuarios vs autenticación por número de WhatsApp
Decisión: Usar Google Workspace como proveedor de identidad.
Razón: Evita crear usuarios y contraseñas propias, aprovecha las cuentas corporativas existentes y permite auditar cada solicitud por correo corporativo.
Impacto: Solo usuarios corporativos autorizados podrán interactuar con el agente. Antes de procesar cualquier instrucción, el sistema deberá validar identidad, rol y permisos del usuario.

DEC-003 — Modelo de autorización y permisos

Fecha: Junio 2026
Contexto: No basta con saber que el usuario pertenece a GLM. El agente debe validar que el usuario tenga permiso para ejecutar una acción específica según rol, país/área permitida, sensibilidad del dato y nivel de riesgo de la operación.
Opciones consideradas: Google Sheets vs Supabase/Postgres vs Neo4j
Decisión: Usar Neo4j como grafo de autorización y relaciones.
Razón: Neo4j permite modelar relaciones complejas entre usuarios, roles, países, áreas, acciones, campos sensibles, confirmaciones y aprobaciones.
Impacto: Neo4j guardará metadata de permisos y relaciones. No almacenará salarios reales, documentos, datos personales sensibles completos ni historial completo de BambooHR.

DEC-004 — Almacenamiento del log de auditoría

Fecha: Junio 2026
Contexto: Cada acción relevante debe quedar registrada con usuario, acción, empleado afectado si aplica, timestamp, resultado de autorización y resultado de ejecución.
Opciones consideradas: Supabase/Postgres vs Google Sheets
Decisión: Usar Supabase/Postgres como almacenamiento principal del log de auditoría.
Razón: Supabase/Postgres ofrece mayor control, estructura, trazabilidad, seguridad y escalabilidad que Google Sheets para un proyecto con datos sensibles de RRHH.
Impacto: Google Sheets podrá usarse solo como herramienta auxiliar de visualización o exporte, pero no como log principal de auditoría.

DEC-005 — Separación de responsabilidades entre n8n y Python Service

Fecha: Junio 2026
Contexto: n8n es ideal para orquestar flujos, recibir mensajes, llamar servicios externos y responder al usuario. Sin embargo, las reglas críticas de permisos, autorización, ejecución contra BambooHR y auditoría deben mantenerse centralizadas, versionadas y auditables.
Opciones consideradas: Hacer toda la lógica en n8n vs separar la lógica crítica en un Python Service
Decisión: Usar n8n como orquestador del flujo y un Python Service como capa de lógica crítica.
Razón: Separar la lógica crítica evita que reglas sensibles de RRHH queden dispersas en múltiples nodos visuales. El Python Service permite validar permisos, consultar Neo4j, ejecutar BambooHR API y registrar auditoría de forma más controlada y fácil de probar.
Impacto: n8n recibirá el mensaje, coordinará el flujo y responderá al usuario. El Python Service validará permisos, consultará Neo4j, ejecutará acciones autorizadas en BambooHR API y registrará auditoría en Supabase/Postgres.

DEC-006 — Política de seguridad para acciones sensibles

Fecha: Junio 2026
Contexto: El agente podrá ejecutar acciones que impactan datos sensibles de empleados, nómina y procesos de RRHH. Una instrucción mal interpretada no debe ejecutarse automáticamente si representa riesgo alto.
Opciones consideradas: Ejecutar acciones directamente vs solicitar confirmación/aprobación según riesgo
Decisión: Requerir confirmación explícita para acciones sensibles y aprobación cuando aplique según política interna.
Razón: Cambios de salario, desvinculaciones, creación de empleados, cambios de manager, cambios de fechas críticas y acciones que impacten nómina requieren control adicional antes de ejecutarse.
Impacto: Las acciones sensibles no se ejecutarán directamente después de ser interpretadas. El agente deberá pedir confirmación y registrar la operación en auditoría. Los settings de BambooHR quedan bloqueados para todos excepto Máximo Gómez.

Contactos del proyecto

Rol	Nombre	Contacto
Product Owner	Maximo Gomez	[completar]
IT Manager	Luis Matos	[completar]
Developer	Isaac Aracena	[completar]

Definition of Done

Agente ejecuta los 3 modos: accion, consulta y reporte
95% de acciones ejecutadas correctamente en pruebas reales
Tiempo por operacion menor a 30 segundos
Sistema de permisos funcionando — settings bloqueados para no-admins
Log de auditoria registrando todas las operaciones
Todos los casos de prueba en estado OK
Codigo commiteado y pusheado a Gitea
README completo y actualizado
Variables de entorno documentadas en .env.example
Probado en ambiente real con equipo de RRHH
Luis Matos valido el output
Maximo aprobo el resultado final

Documento mantenido por el equipo GLM IT - Ultima actualizacion: Junio 8, 2026

20 KiB Raw Blame History