Skip to content
Nappai Documentation

JS Code

JS Code lets you solve with a few lines of JavaScript whatever no other component does exactly the way you need: calculate a value, reshape a list, combine data from several steps or call a web service. Whatever you send back with return is the component’s result.

It can also become a tool for an agent: the agent decides when to use it and with which data, and your code does the work.

When to use it

  • Calculate totals, discounts or due dates from an order’s data.
  • Change the shape of a list before sending it to another system.
  • Call a supplier’s API that has no dedicated component.
  • Give an agent a tool of your own, for example “calculate the shipping price from the weight and destination”.

Configuration

FieldWhat it does
Input DataThe data your code receives. It can be a message, a record or a list. Inside the code it is in $data.
JavaScript CodeThe code that runs. End it with return followed by the result. The field comes with commented examples of everything you can use.

Inside the code you have:

NameWhat it is for
$dataThe data from Input Data.
$argsThe data the agent sends when the component is used as a tool.
$componentsThe results of other components in the flow, by name, when the component works as a step of the flow.
$envThe variables of the environment linked to the flow, for example $env.URL_API_PEDIDOS. Empty if the flow has no environment.
$fetch(url, options)Sends a request to a web service and returns its answer: whether it went well, the status code and the content.
$tools["name"](data)Uses a tool connected in Tools.
$models["name"](text)Sends a text to a model connected in Model and returns its answer.
$wait(milliseconds)Waits for the given time before continuing.
$log(...)Writes a message to the run log, useful to check what happened.

$tools and $models always return a result with two parts: result with the answer and error if something went wrong.

Advanced options

FieldWhat it does
Enable Tools InputAdds the Tools connector so the code can use tools. Off by default.
Enable Models InputAdds the Model connector so the code can query language models. Off by default.

Tool tab

These fields are used when you connect the Tool output to an agent.

FieldWhat it does
Tool NameThe name the agent sees for the tool. Default: js_tool.
Tool DescriptionTells the agent what the tool does and when to use it. The clearer it is, the better the agent uses it.
Tool Input SchemaThe data the agent must send when using the tool, with name and type. It reaches the code in $args.
Allow update agent stateLets the code change the state of the agent that uses it. Off by default.

Output

  • Processed Data: what your code returns with return. Connect it to the next step of the flow.
  • Tool: the component as a tool, to connect to an agent.

You use one output or the other: when you connect one, the other is hidden.

Example

A shop wants to calculate each order’s total including VAT before creating the invoice.

  1. Connect the order to Input Data.

  2. In JavaScript Code, type:

    const base = $data.lines.reduce((sum, l) => sum + l.price * l.quantity, 0);
    return { order: $data.id, base, total: Math.round(base * 1.21 * 100) / 100 };

  3. Connect Processed Data to the component that creates the invoice.

Good practices

  • Start with return $data; to see what the component receives, and write your code from there.
  • To try the connected tools, return $tools: you will see which ones are available and what data they expect. With return $env; you see the environment variables.
  • Do not type tokens or passwords in the code: store them as secret environment variables and read them with $env.
  • There is a limit on web service, tool and model calls per run, and a maximum run time.