Skip to main content

Execute script action

Run your own JavaScript in an automation. Call web services, read records through the Tape API, and save results in variables for later actions.

Written by Leo

Execute script is an action that runs JavaScript code when your automation reaches it (the code can use values from the record, call other services, and save results in variables). It's meant to help you do things that the other actions don't cover, such as parsing a response, calculating with lists, or reading records in a way that needs more control.

You can use this action for many things, including:

  • Reading the response of an external service and saving the values you need for the next action.

  • Building a list of lines for an email from several records.

Adding the Execute script action in an Expenses automation. The editor shows the example code, and the action saves output in Script output 1 and Script output 2

Note:

  • Scripts run in a sandbox with limits. A run can take up to three minutes, memory and CPU limits apply, and the number of parallel asynchronous operations is limited. Run web requests one after another instead of all at once.

  • Tape doesn't check your code for mistakes when you save. It only checks that the record values you inserted still exist. The editor underlines some mistakes while you type, but a script with a mistake still saves, and the error only shows when the automation runs. Test with a simulated run first.

  • A script can change real data. Calls to the Tape API inside a script work on real records in a real run.

Who can use the Execute script action?

  • Automations are available on the Free, Plus, and Premium plans. The number of automation actions per month depends on your plan. See the limits for your plan on our pricing page.

  • To add or change this action, you need to be a workspace admin of the workspace the database app is in. You also need full access to every database the automation uses.

Add the Execute script action

To run a script in an automation:

  1. Open the database app on desktop or web and click the automations icon in the top bar (tooltip Create and view automations).

  2. Open an automation, or select New automation and choose a trigger.

  3. Select Add action → Execute script. In the list, it reads Execute JavaScript code and save the output in variables for later use.

  4. Write your code in the editor. A new script starts with examples that you can change or delete.

  5. Select Create automation for a new automation, or Save changes for an existing one.

The action Execute a script and save output in Script output 1, Script output 2, with the example code in the editor

Execute script settings

The action reads Execute a script and save output in Script output 1, Script output 2. Below it is the code editor. A new script starts with two outputs when the trigger is set to a database app, and with one output when it isn't.

  • The code editor: where you write JavaScript. It has autocompletion and shows which variables and functions are available, with their types. Start typing, then press enter to accept a suggestion. The editor is built on Monaco, the editor behind VS Code, so many VS Code habits work here. You'll find the same editor in Perform calculation and in script filters, and the editor shortcuts below work there too.

  • Script output 1, Script output 2: the variables that hold the results of your script. Select + after the outputs to add another one. Select an output to see Rename and Remove. Outputs don't have a type. They hold whatever your code assigns.

  • Open in fullscreen: opens the editor in full screen. Use cmd/ctrl + enter to open and close it.

The action menu ••• has Continue on error and Deactivate under Settings, then Turn into, Duplicate, and Remove. Learn more about action settings →

Save results in variables

To pass a result to later actions, assign it to the variable of an output. The variable name starts with var_ and uses the name of the output in lower case, with every character other than letters, numbers, _, and $ replaced by _. Script output 1 becomes var_script_output_1, and Invoice total becomes var_invoice_total.

const result = await http.get('https://example.com/api/rates');
var_script_output_1 = result.data;

Later actions can insert the output like any other variable. Type @ to open the list of variables. Outputs are only available after the action that makes them. If two outputs have the same name, the later one overwrites the earlier one. Learn more about record values and variables →

Use record values

Field values of the record are available as variables in the script. The editor suggests their names as you type, for example:

console.info('The estimate was ' + task_field_estimation_days_decimal_value + ' days');

Field values are named after the record name of the database and the field, for example lead_field_email_email for an email field or, for a number field, task_field_estimation_days_decimal_value. The ID of the record is in current_record_id. The editor suggests the exact names as you type.

Call web services

The script can use an HTTP client to call other services. It has http.get, http.post, http.put, http.patch, http.delete, http.upload, and http.postFormData. The call returns the response data and headers.

const { data, headers } = await http.get('https://example.com/api/orders');
console.info(JSON.stringify(headers));
var_script_output_1 = data;

To send a file, use http.upload. Learn more about sending HTTP requests →

Use the Tape API in a script

The script can use the Tape API client, for example to read records:

const { data } = await tape.Record.getManyFiltered({ appId: 18, limit: 2 });
var_script_output_1 = data.records;

You don't need to handle authentication. The automation uses its own token while it runs. Use the client for things that don't have an action yet, or when you need more control. The editor shows the available functions and their options as you type.

Use libraries

These libraries are available in scripts. Use the name in the list:

  • lodash or _: utility functions for lists, objects, and text.

  • moment: parse, check, and format dates and times.

  • date_fns: date functions.

  • date_fns_tz: time zone support for date_fns.

  • uuid: create unique IDs.

  • cheerio: read and change HTML.

  • striptags: remove HTML tags from text.

  • minimatch: match text against patterns such as *.pdf.

  • jsonata: search and reshape JSON.

Need another library? Submit a feature request in the Tape community → and tell us what it's for.

Debug with console.info

Use console.log or console.info to print values while the script runs. The output appears in the run's steps in the Runs panel. Select the run, then the script step.

console.info(JSON.stringify(result.data.records, null, 2));

Stop the run with an error

Throw an error to fail the run on purpose. The message is logged, and the actions after the script don't run, unless Continue on error is turned on for the action.

if (!task_field_estimation_days_decimal_value) {
throw new Error('The task has no estimate');
}

Let's look at an example

Let's say your sales team wants the first line of every new lead's notes, in capital letters, in the subject of a task. Here's how:

  1. Set the trigger to When a record is created in the Leads database app.

  2. Select Add action → Execute script.

  3. Replace the example code with the script below.

  4. Rename Script output 1 to Notes headline.

  5. Select Add action → Create record, and insert Notes headline into the title of the task.

  6. Select Create automation.

const firstLine = (lead_field_notes_unformatted_value || '').split('\n')[0].trim();
var_notes_headline = firstLine.toUpperCase();

The next time a lead is created, you should see a task with the headline in its title. If Notes is a multi-line text field, its plain text is in lead_field_notes_unformatted_value.

For more ready-to-use snippets, see Automation script examples →.

Execute script and the run

  • Time zones: automations run in UTC. A date you create in code is read as UTC. Convert it with date_fns_tz before you save it to a date field. Learn more about dates and time zones →

  • Simulated runs: a simulated run changes no data. Calls to the Tape API that would change data, such as updating or creating a record, return sample data. You can check whether a run is simulated with the variable current_workflow_is_simulation, for example to skip a call to an external service.

  • Wait inside a script: use await delay(1000) to wait one second.

  • Other system variables: current_workflow_id, current_workflow_name, current_workflow_timezone, current_date, current_datetime, and current_time are available in scripts.

  • Silent and other settings: the Tape API client has options such as silent changes and triggering other automations. The editor shows them as you type.

Execute script errors

  • Syntax errors: a script with a syntax error still saves, so the error only shows in the run. Open the run, select the script step, and read the message.

  • await is only allowed in this action. Perform calculation runs synchronous code only. Use Execute script when you need await.

  • Limit errors: if a run fails with a limit message, the script took too long (three minutes in total) or used too much memory. Split the work, or avoid heavy computing. Learn more about limits and throttling →

  • Permission errors: a call to the Tape API fails if the automation isn't allowed to do it. Calls to the Tape API run as the automation itself.

  • Request errors: if another service doesn't answer in time, the request fails and the step fails with it.

Test, pause, or edit the Execute script action

  • Manual run runs the automation once. Next to Run on, choose the records, then select Start run. If you have unsaved changes, the button reads Save and start run. Calls in your script act on real data.

  • Use Simulated run first. It skips the trigger filter and doesn't change data. Learn more about testing automations →

  • To change the code, open the automation, edit it in the code editor, then select Save changes.

  • Editor shortcuts: cmd/ctrl + F searches, F2 renames a variable in the script, option/alt + up or down moves lines, and option/alt + click adds another cursor.

Learn more

FAQs

Which language can I use in scripts?

JavaScript. Execute script supports asynchronous code with async and await. Perform calculation supports synchronous code only.

What's the difference between Execute script and Perform calculation?

Perform calculation is for short code that returns one value. Execute script is for longer code with several steps, web requests, and Tape API calls, and it can save more than one output. Learn more about Perform calculation →

Can I save more than one result?

Yes, a new script starts with one or two outputs, such as Script output 1. Select + to add more, and assign a value to each variable in your code.

Can I use any library from the internet?

No, you can only use the libraries in the list above. If you need another one, submit a feature request in the Tape community →.

Why does my script do nothing?

Check these causes:

  • The script has a syntax error. Open the run and read the message of the script step.

  • The output variable name doesn't match the name of the output. Script output 1 is var_script_output_1.

  • The action is deactivated. Open its menu ••• and check Deactivate.

Are you a developer using the Tape API for automations?

The automation API has its own documentation for developers. Full reference: custom_code in the developer docs →

Still have questions? Find answers and get help from community experts in the Tape community →

Did this answer your question?