Factorial HR Component

The Factorial HR Component lets you connect your Nappai dashboard to Factorial, a popular HR and payroll platform. With this component you can list, retrieve, create, or update any HR resource—such as employees, contracts, payroll, or time‑off requests—directly from your automation workflows.

How it Works

When you add the component to a workflow, it first asks for a Factorial API Key. This key is stored securely in Nappai’s credential system, so you never type it into the component itself.
Once the key is set, the component uses the Factorial API to perform the requested action. The API call is made asynchronously, so your workflow can keep running while the request is processed. The result is returned as a Message object that can be passed to other components or used by an AI agent.

Inputs

Mapping Mode

This component has a special mode called Mapping Mode. When you enable this mode using the toggle switch, an additional input called Mapping Data is activated, and each input field offers you three different ways to provide data:

Fixed: You type the value directly into the field.
Mapped: You connect the output of another component to use its result as the value.
Javascript: You write Javascript code to dynamically calculate the value.

This flexibility allows you to create more dynamic and connected workflows.

Input Fields

The following fields are available to configure this component. Each field may be visible in different operations:

Mapping Mode: Toggle to enable batch processing of multiple records at once.
Resource: Choose the type of HR data you want to work with (e.g., Employees, Contracts, Payroll, etc.).
Operation: Select the action you want to perform on the chosen resource (e.g., List all, Get employee, Create with contracts).
Tool Name: When the component is used as a tool for an AI agent, this is the name that will appear in the agent’s tool list.
Tool Description: A detailed description of what the tool does, helping the agent decide when to use it.
Tools arguments metadata: Defines the arguments that the tool expects, so the agent can pass the correct data.

Credential
This component requires a Factorial Task API credential.

First, create the credential in the Credentials section of Nappai.

Then, select that credential in the component’s Credential field.
The API key is stored securely and is not shown in the input list.

Outputs

Response: A Message object containing the raw response from Factorial. This can be used to feed data into other components or to display results.
Tool: A Tool object that can be passed to an AI agent, enabling the agent to call this component as a tool.

Usage Example

Create a new workflow and add the Factorial HR Component.
Enable Mapping Mode if you want to process many records at once.
Select a Resource (e.g., Employees) and an Operation (e.g., List all).
Choose your Factorial credential from the dropdown.
Connect the output of the component to a Print or Store component to see the list of employees.
Run the workflow. The component will call Factorial’s API and return the employee data in the Response output.

Nappai Base Component – The foundational class that all Nappai components inherit from.
Factorial HR Component – The main integration point for all Factorial HR resources.

Tips and Best Practices

Use Mapping Mode for bulk operations (e.g., updating many employees at once).
Keep your API key secure by storing it in Nappai’s credential store and never hard‑coding it in workflows.
Validate responses before passing them to downstream components to avoid errors.
Leverage the Tool outputs when building AI‑powered assistants; the tool name and description help the agent choose the right action.

Security Considerations

The Factorial API key is stored in Nappai’s encrypted credential store.
Only users with permission to view credentials can see the key.
When sharing workflows, the key is not exposed; only the credential reference is shared.