Holded Team Component

El Holded Team Component te permite interactuar con la API de Holded para gestionar recursos relacionados con el equipo, como empleados y su registro de tiempo. Con él puedes listar, crear o obtener información de estos recursos directamente desde tu dashboard de Nappai.

¿Cómo funciona?

El componente se conecta a la API de Holded mediante una clave API que el usuario debe haber configurado previamente como credencial Holded Task API. Cuando se ejecuta, el componente determina el recurso seleccionado (empleados o seguimiento de tiempo) y la operación (List, Create o Get). Luego llama a la función correspondiente de la API y devuelve la respuesta en formato Message. Si el componente se usa como herramienta, también expone un objeto Tool que el agente puede invocar.

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

• Mapping Mode: Activa el modo de mapeo para procesar múltiples registros de datos en lote.
• Resource: Selecciona el tipo de recurso de Holded que deseas gestionar, como empleados o el seguimiento de tiempo de los empleados.
• Operation: Elige la acción que quieres realizar sobre el recurso seleccionado: List, Create o Get.
• Tool Name: Nombre del instrumento que se mostrará al agente cuando el componente se use como herramienta.
• Tool Description: Descripción detallada del propósito del instrumento para que el agente lo entienda.
• Tools arguments metadata: Metadatos que describen los argumentos que el instrumento aceptará.

Credencial requerida
Este componente necesita una credencial de tipo Holded Task API.

1. Configura primero la credencial en la sección de credenciales de Nappai.
2. Luego selecciona esa credencial en el campo Credential del componente.
   La credencial requiere una Holded Api Key que puedes obtener en https://app.holded.com/account/setup#settings:/api.

Salidas

• Response: Respuesta de la API de Holded en formato Message, que contiene los datos solicitados.
• Tool: Objeto Tool que permite que el componente se utilice como herramienta en el agente.

Ejemplo de Uso

1. Listar empleados

   • Selecciona Resource: Employees
   • Selecciona Operation: List
   • Configura la credencial Holded Task API
   • Ejecuta el componente. La salida Response mostrará la lista de empleados en formato JSON dentro de un objeto Message.

2. Obtener registro de tiempo de un empleado

   • Selecciona Resource: Employees’ Time-tracking
   • Selecciona Operation: Get
   • Proporciona el ID del empleado en la entrada correspondiente (puedes usar Mapping Mode para procesar varios IDs).
   • Ejecuta el componente y revisa la salida Response.

Componentes Relacionados

• Holded Employees Component – Gestiona empleados sin la funcionalidad de seguimiento de tiempo.
• Holded Employees Time Tracking Component – Se centra exclusivamente en el seguimiento de tiempo de los empleados.

Consejos y Mejores Prácticas

• Usa Mapping Mode cuando necesites procesar listas de IDs o datos en lote; evita ejecutar el componente repetidamente para cada registro.
• Define Tool Name y Tool Description claros para que el agente comprenda rápidamente cuándo usar el componente.
• Revisa la respuesta antes de pasarla a otros componentes; la estructura JSON puede variar según la operación.
• Mantén la credencial actualizada; las claves API de Holded tienen límites de uso y pueden caducar.

Consideraciones de Seguridad

• La clave API de Holded debe guardarse como credencial y nunca exponerse en el código fuente ni en los logs.
• Asegúrate de que solo los usuarios autorizados tengan acceso a la sección de credenciales en Nappai.
• Si el componente se usa como herramienta, limita su uso a agentes de confianza para evitar exfiltración accidental de datos sensibles.