# Run custom JavaScript in a workflow

> Use the Run Custom Code action to calculate, reshape or check values with your own JavaScript, test it with real data, and pass the results to later steps.

Source: https://tadabase.com/docs/workflows/running-custom-javascript  
Status: Verified Nov 17, 2026. Checked against the current product

The **Run Custom Code** action runs your own JavaScript as a workflow step. Use it when no built-in action does the job: a calculation with several rules, text to clean up or format, a value to check before saving, or a call to another service. The code runs in a separate, locked-down runner, not on your app's server.

## When to use it, and when not to

A built-in action is easier to read and change later. Reach for code only when none of these fits:

| You want to | Use this instead |
| --- | --- |
| Count, total, average or find the highest value in a list of records | The **Aggregate** action |
| Rename, remove or reshape fields in JSON, such as a webhook payload | The **Transform JSON** action |
| Find records that match filters | The **Find Records** action. See [Find records and use them in later steps](https://tadabase.com/docs/workflows/find-records-in-a-workflow). |
| Keep a calculated value on every record, everywhere in the app | An equation field. See [Equation](https://tadabase.com/docs/data/equation). |

## Add a Run Custom Code step

1. **Add the action** In the workflow editor, click **Add Step**, then **Add Action**, and under **Utilities** choose **Run Custom Code**.
2. **Keep the language** **Language** starts as **JavaScript**. You can switch to **Python**; see the last section of this page.
3. **Add the data your code needs** Under **Data to use in the code**, click **+ Add Input**. Type a **Variable name**, then choose where the value comes from. Add one input for each value.
4. **Write the code** Click the **Code** box (**Click to write code**). The **Code Mapping** window opens with the editor on the right and your inputs on the left.
5. **Run it** Click **Run** (or press `Ctrl+Enter`, `Cmd+Enter` on a Mac) and check the result under **Response** and **Console**.
6. **Save the workflow** Click **Close**, then **Save**. Code changes are kept with the workflow, but nothing is saved until you click **Save**.

![The Code Mapping window with inputs on the left, JavaScript in the editor and the Response tab showing the result of a test run](https://tadabase.com/docs-shots/workflows-custom-code-editor.webp)

## Inputs: the values your code receives

Each input becomes a variable in your code with a `$` in front of its name: an input named `qty` is read as `$qty`. It is also available as `params["qty"]`. An input's value can come from any of these sources:

| Source | What it gives the code |
| --- | --- |
| **Custom Value**, **Blank Value**, **Custom**, **Conditional** | A value you type, an empty value, text built from several values, or a value chosen by rules. |
| **Record Value (Source)**, **Source Record (Full Object)** | One field of the workflow's record, or the whole record. |
| **Action Record Value**, **Action Record (Full Object)**, **Action Response Value** | A record or a result from an earlier step. Offered only when an earlier step has one. |
| **Connected Value**, **Connected Record (Full Object)** | Values from records connected to the workflow's record. |
| **Logged-in User Field**, **Logged-in User (Full Object)** | The person who started the run, when there is one. |
| **Current Date**, **Current Time**, **Current Date & Time** | The moment the step runs. |

Names must start with a letter, `_` or `$`, and can then use letters, numbers, `_` and `$` (the pattern `^[A-Za-z_$][A-Za-z0-9_$]*$`). `record`, `loggedUser` and `currentItem` (in any capitals) and names that start with `__` are taken by the system.

| Name | Allowed? | Why |
| --- | --- | --- |
| `customer_email` | Yes | Letters and an underscore. |
| `email2` | Yes | Numbers are fine after the first character. |
| `2nd_email` | No | Cannot start with a number. |
| `customer email` | No | No spaces. |
| `customer-email` | No | Only letters, numbers and underscores. |
| `record` | No | Reserved by the system. |

The editor will not save a step with a name it cannot use. It shows the reason under the input and a **Rename to …** button that fixes the name for you.

## What else the code can read

| In the code | What it is |
| --- | --- |
| `$record` | The workflow's record, by field slug: `$record.field_slug`. Empty when the workflow has no table. |
| `$currentItem` | Inside a **Loop / Bulk Action**, the item the loop is on. `$record` stays the workflow's own record. |
| `$loggedUser` or `getLoggedInUser()` | The logged-in user's record. Empty when nobody is logged in, for example in a scheduled run. |
| `getAppDetails()` | Details of the app, such as its name and time zone. |
| `getAppVariable("slug")` | The value of an app variable, or `undefined` if there is none. It takes no default value, so write `getAppVariable("slug") \|\| "fallback"` when you need one. |
| `getAppSecret("NAME")` | The value of an app secret. See the section on secrets below. |

Click **?** (**Code reference**) in the editor toolbar for this list, the helper functions and the keyboard shortcuts. Click **Insert** to add a variable at the cursor, or press `Ctrl+Space` for suggestions, including the fields of a loaded sample record.

> **Record IDs are encoded:** Any key named `id`, `record_id` or ending in `_id` reaches your code as an encoded ID (letters and numbers, not a plain number). Pass it on as it is; Tadabase reads encoded IDs everywhere it expects a record ID.

## Pass results to later steps

Call `returnData("key", value)` once for each value a later step needs:

```javascript
const qty = Number($qty || 0);
const rate = Number($rate || 0);
const subtotal = qty * rate;

returnData("subtotal", subtotal);
returnData("total", Math.round(subtotal * 1.0875 * 100) / 100);
```

In a later step, open the value picker, choose **Step Data**, pick the Run Custom Code step and choose the key. The picker finds keys by reading your `returnData` calls, so write the key as quoted text: `returnData("total", x)` is offered, `returnData(name, x)` is not.

A `return` at the top level of the code also becomes the step's result, but its keys are not offered in the picker. If you forget to return anything, the editor shows a reminder under the code.

## Stop with an error

Call `fail("message")` to stop the step with your own error. The message appears in the run's history.

```javascript
if (!$email) {
  fail("The customer has no email address.");
}
returnData("email", String($email).trim().toLowerCase());
```

When the step fails, from `fail()` or from an error in your code, the next steps still run. To stop the whole run instead, open the step's **Advanced** tab and turn on **Abort workflow if this step fails**.

## Keep API keys out of your code

Never type an API key or password into the code or into a **Custom Value** input: both are saved with the workflow and shown to everyone who can open it. Save the key as an app secret and read it with `getAppSecret`:

```javascript
const key = getAppSecret("WEATHER_KEY");
if (!key) fail("Add the WEATHER_KEY app secret first.");
```

- The secret's value is sent to the code runner only for this step, and only when the code calls `getAppSecret` with the name written as quoted text. `getAppSecret(name)` with a variable returns `undefined`.
- If the value shows up in a log line, an error or the result, it is masked: dots and the last four characters.
- App secrets are a plan feature. See [Keep API keys and passwords in app secrets](https://tadabase.com/docs/settings/app-secrets).
- App variables (`getAppVariable`) are for values that are safe to show, such as a base URL or a tax rate.

## Test your code

In the **Code Mapping** window, click **Run**. The panel at the bottom shows **Success** or **Error**, how long the code took, and three tabs:

| Tab | Shows |
| --- | --- |
| **Response** | What the code returned, as a tree (**Pretty**) or as text (**Raw**). |
| **Console** | Every `console.log`, `console.warn` and `console.error` line, in order. |
| **Sample Data** | The test data the code ran with: **Source Record**, **Loop Item** (inside a loop), **Logged-in User** and **Parameters**. Click **Choose Record** or **Choose User** to run with a different record or user. |

> **Run is a real run of your code:** Clicking **Run** executes the code for real. If it calls another service with `fetch`, that call is made. Records are not changed by the code itself, but a service you call may act on the request.

Values that come from an earlier step's result stay blank in a test, because no earlier step has run. Check those in a real run's history; see [Check workflow runs, history and errors](https://tadabase.com/docs/workflows/workflow-history-and-logs).

## Get help from the AI Code Builder

Click the wand icon (**AI Code Builder**) in the editor toolbar to open a chat beside the code. Describe what the step should do; the assistant knows your inputs, the sample record and the current code, and you can put its code into the editor with one click. Read the code and click **Run** before you save. The chat counts toward your account's daily AI allowance and stops for the day when the allowance runs out.

## Limits

- Each run of the code gets 30 seconds, including any `fetch` calls. Code that takes longer stops with a time-out error.
- The code cannot read your app's database or files directly. Give it what it needs through inputs, and write results back with a later step, such as **Update Record**.
- In a **Dry run** started from the workflow editor, Run Custom Code steps do not run; the history marks them as simulated.
- If the code runner cannot be reached, the step fails with `The code runner could not be reached or did not respond. Try again in a minute.`

## Starter template

Add one input named `name` (a **Custom Value** or a **Record Value (Source)**), paste this into the editor and click **Run**:

```javascript
// Inputs are $name. The workflow's record is $record.
// returnData("key", value) passes a value to later steps.

const who = $name || ($record && $record.first_name) || "friend";
const greeting = `Hello, ${who}!`;

console.log("Built greeting:", greeting);
returnData("greeting", greeting);
```

## Common problems

| What you see | Likely cause | Fix |
| --- | --- | --- |
| `$foo` is `undefined` | There is no input named `foo`, or its source was empty when the step ran. | Check the input's name and source. Use the eye icon on the input in **Code Mapping** to preview its value. |
| `$record` is empty | The workflow has no table, or no sample record is loaded in the test. | In a test, open **Sample Data**, then **Source Record**, and click **Choose Record**. |
| A later step does not offer your key | The key in `returnData` is not quoted text, or the key comes from a top-level `return`. | Write `returnData("total", value)` with the key in quotes. |
| The step stops after 30 seconds | A slow loop or a slow service. | Do less in one step, or have the other service answer faster. |
| `getAppSecret` returns `undefined` | The name is not quoted text, does not match the secret's **Name**, or the plan has no App Secrets. | Call `getAppSecret("EXACT_NAME")` and check **Settings** > **App Secrets**. |
| An ID looks like random letters | Record IDs reach the code encoded. | Pass the ID on unchanged. |
| The next steps ran even though the code failed | That is the default. | Turn on **Abort workflow if this step fails** on the step's **Advanced** tab. |

## Writing the step in Python

Set **Language** to **Python** to write Python 3 with the standard library. The helper names are the same (`returnData`, `getAppVariable`, `getAppSecret`, `fail`), but variables have no `$`: an input named `qty` is `qty`, and the record is `record["field_slug"]`. `print()` writes to the **Console** tab. If you switch language with code already in the editor, the code is kept but will not run until you rewrite it.

## Snippet library

Copy-and-adapt examples, grouped by task:

- [Strings and names](https://tadabase.com/docs/workflows/string-snippets)
- [Numbers, math and money](https://tadabase.com/docs/workflows/numbers-math-money-snippets)
- [Dates and times](https://tadabase.com/docs/workflows/dates-times-snippets)
- [Arrays and lists](https://tadabase.com/docs/workflows/arrays-lists-snippets)
- [Validation and sanitization](https://tadabase.com/docs/workflows/validation-sanitization-snippets)
- [Branching and status](https://tadabase.com/docs/workflows/branching-status-snippets)
- [Identifiers and tokens](https://tadabase.com/docs/workflows/identifiers-tokens-snippets)
- [External APIs](https://tadabase.com/docs/workflows/external-api-snippets)
- [Connected records](https://tadabase.com/docs/workflows/connected-records-snippets)
- [Logged-in user and app context](https://tadabase.com/docs/workflows/logged-in-user-app-context-snippets)
- [Client-side UX](https://tadabase.com/docs/workflows/client-side-ux-snippets)
