Saltearse al contenido
Nappai Documentation

Factorial HR Component

El Factorial HR Component te permite interactuar con la API de Factorial para gestionar recursos de recursos humanos como empleados, contratos, nóminas y más. Con él puedes listar, obtener o crear datos directamente desde tu dashboard de Nappai, sin necesidad de escribir código.

¿Cómo funciona?

Cuando configuras el componente, introduces tu Factorial API Key a través de la credencial “Factorial Task API”. El componente crea una instancia de FactorialApi y, según el recurso y la operación seleccionados, llama a la función correspondiente (por ejemplo, factorial_employees_execute para empleados). La respuesta se devuelve como un objeto Message que puedes usar en otros nodos o como salida de un agente.

El componente también puede funcionar como una herramienta (tool) para agentes de IA. En ese caso, los campos “Tool Name”, “Tool Description” y “Tools arguments metadata” definen cómo el agente verá y usará la herramienta.

Entradas

Modo de Mapeo (Mapping Mode)

Este componente cuenta con un modo especial llamado “Mapping Mode”. 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 de Factorial que quieres gestionar (por ejemplo, Employees, Contracts, Payroll, etc.).
  • Operation: Define la acción a realizar sobre el recurso seleccionado (por ejemplo, List all, Get employee, Create with contracts).
  • Tool Name: El nombre de la herramienta que se mostrará al agente cuando el componente se use como herramienta.
  • Tool Description: Una descripción detallada de lo que hace la herramienta, para que el agente sepa cuándo usarla.
  • Tools arguments metadata: Metadatos que describen los argumentos que la herramienta acepta.

Credencial
Este componente necesita una credencial de tipo Factorial Task API.

  1. Ve a la sección de credenciales de Nappai y crea una nueva credencial “Factorial Task API”.
  2. En el panel de configuración del componente, selecciona esa credencial en el campo “Credential”.
  3. La credencial debe contener tu Factorial Api Key (puedes obtenerla en Factorial).

Salidas

  • Response: Devuelve la respuesta de la API como un objeto Message. Puedes usarla para visualizar datos, pasarla a otro nodo o procesarla con lógica adicional.
  • Tool: Si el componente se usa como herramienta, esta salida contiene la definición de la herramienta que el agente puede invocar.

Ejemplo de Uso

  1. Objetivo: Obtener la lista de todos los empleados de una empresa.
  2. Configuración:
    • Resource: Employees
    • Operation: List all
    • Tool Name: List Employees
    • Tool Description: Returns a list of all employees in the Factorial account.
    • Tools arguments metadata: {} (no argumentos adicionales)
  3. Resultado: El nodo devuelve un Message con la lista de empleados, que puedes conectar a un nodo de visualización o a un agente que necesite esa información.

Componentes Relacionados

  • Factorial HR Component – La única pieza central para interactuar con la API de Factorial dentro de Nappai.
  • Nappai Base Component – Base sobre la que se construyen todos los componentes de Nappai, proporcionando funcionalidades comunes como manejo de credenciales y ejecución asíncrona.

Consejos y Mejores Prácticas

  • Usa Mapping Mode cuando necesites procesar varios registros a la vez; evita ejecutar el mismo nodo repetidamente.
  • Define nombres claros para “Tool Name” y “Tool Description” para que los agentes comprendan rápidamente la utilidad de la herramienta.
  • Limita la exposición de datos sensibles: no compartas la API Key en logs ni en salidas visibles.
  • Prueba cada operación con un conjunto pequeño de datos antes de usarla en producción para asegurarte de que la respuesta es la esperada.

Consideraciones de Seguridad

  • La Factorial API Key debe mantenerse en secreto; solo se almacena en la credencial y no se muestra en la interfaz de usuario.
  • Cuando habilites Mapping Mode, revisa que los datos que se pasan a través de “Mapped” o “Javascript” no expongan información sensible.
  • Si el componente se usa como herramienta, asegúrate de que el agente no pueda ejecutar operaciones que modifiquen datos críticos sin autorización explícita.