Saltearse al contenido
Nappai Documentation

Holded Projects Component

El Holded Projects Component permite a los usuarios de Nappai interactuar con la API de Holded para administrar proyectos, tareas y el seguimiento de tiempo. Con una interfaz sencilla, puedes listar, crear o obtener información de estos recursos sin salir del dashboard de Nappai.

¿Cómo funciona?

Cuando configuras el componente, seleccionas el recurso que quieres manejar (Projects, Tasks o Time Tracking) y la operación que deseas realizar (List, Create o Get). El componente usa la clave API de Holded que has guardado en la sección de credenciales de Nappai. Internamente, envía una solicitud HTTP a la API de Holded y devuelve la respuesta como un objeto Message que puede ser usado en el flujo de trabajo o convertido en un Tool para que un agente de IA lo invoque.

El proceso es el siguiente:

  1. Selección de recurso y operación – El usuario elige en los menús desplegables.
  2. Autenticación – El componente recupera la clave API desde la credencial configurada.
  3. Ejecución – Se llama a la función correspondiente (holded_projects_execute, holded_tasks_execute o holded_time_tracking_execute) que hace la petición a la API de Holded.
  4. Respuesta – La respuesta se devuelve como un mensaje que puede ser conectado a otros componentes o usado por un agente.

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: Habilita el modo de mapeo para procesar múltiples registros en lote.
  • Resource: Selecciona el tipo de recurso que quieres gestionar (Projects, Tasks o Time Tracking).
  • Operation: Define la acción a realizar sobre el recurso seleccionado (List, Create o Get).
  • Tool Name: El nombre que aparecerá cuando el componente se utilice como herramienta en un agente.
  • Tool Description: Descripción detallada de la herramienta para que el agente entienda cuándo usarla.
  • Tools arguments metadata: Metadatos que describen los argumentos que la herramienta aceptará.

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

  1. Ve a la sección de credenciales de Nappai y crea una nueva credencial llamada Holded Task API.
  2. En el panel de configuración del componente, selecciona esa credencial en el campo Credential.
  3. La credencial debe contener la clave API de Holded, que puedes obtener en https://app.holded.com/account/setup#settings:/api.

Salidas

  • Response: Devuelve la respuesta de la API como un objeto Message. Puedes usarlo directamente en el flujo o pasar el contenido a otro componente.
  • Tool: Convierte la operación en una herramienta que un agente de IA puede invocar. Se crea a partir de los datos de entrada y la configuración de la herramienta.

Ejemplo de Uso

  1. Listar proyectos

    • Selecciona Resource = Projects y Operation = List.
    • Conecta la salida Response a un componente de visualización (por ejemplo, un cuadro de texto) para mostrar la lista de proyectos.

  2. Crear una tarea

    • Selecciona Resource = Tasks y Operation = Create.
    • Proporciona los campos necesarios (por ejemplo, nombre de la tarea, ID del proyecto) mediante entradas fijas o mapeadas.
    • La salida Response contendrá los detalles de la tarea recién creada.

Componentes Relacionados

  • Holded Tasks Component – Gestiona tareas de forma independiente.
  • Holded Time Tracking Component – Registra y consulta el tiempo dedicado a tareas.
  • Nappai Base Component – Base común para todos los componentes de Nappai.

Consejos y Mejores Prácticas

  • Usa Mapping Mode cuando necesites procesar listas de proyectos o tareas en lote; evita hacer llamadas individuales para cada registro.
  • Define Tool Name y Tool Description claramente para que los agentes de IA comprendan rápidamente la utilidad de la herramienta.
  • Maneja la respuesta JSON con cuidado; si solo necesitas un campo específico, utiliza la opción output_key para extraerlo.
  • Prueba cada operación en el modo de depuración antes de integrarla en flujos complejos.

Consideraciones de Seguridad

  • La clave API de Holded se almacena en la credencial Holded Task API y no aparece en la interfaz de usuario.
  • Asegúrate de que solo usuarios autorizados tengan acceso a la sección de credenciales.
  • Evita exponer la respuesta de la API en logs públicos; si la respuesta contiene datos sensibles, considera filtrarlos antes de mostrarlos.