Script automations

A script automation is a short JavaScript script that Atlas runs on its servers for your workspace. It runs on a schedule in your time zone, each time a matching change is recorded in the workspace, or when another system calls its webhook address. The script reads what started it as trigger and the tasks in the workspace with await atlas.tasks.list(), and what it returns is kept with the run. For the common cases, a workspace rule needs no code and is the better place to start; a script is for the cases a rule cannot express.

• Three triggers: a schedule (every weekday morning, every hour, or any cron expression) in the time zone you choose, a change in the workspace (any change to a task, project, comment or goal, or a pattern of your own), and a webhook another system calls
• A test run with a sample payload that stands in for a webhook body or an event, followed on the page until it finishes, with its result, logs and error
• A run history for every automation: when it ran, what started it, whether it succeeded, how long it took, and its result and logs
• A webhook address and secret shown once, with a way to generate a new secret that stops the old one at once
• A sandbox for trying JavaScript or Python in your browser, and Save as automation to carry working JavaScript into a new automation
• Turn an automation off to stop it running on its trigger, and on again, without losing its script or its history

• Only a workspace owner or admin can create, change, run or turn off a script automation, because it runs code on the server. Anybody else sees only the automations they own, read only.
• Server automations run JavaScript. Python runs only in the browser sandbox; an older automation written in Python cannot run on the server and says so.
• A webhook secret is shown once, when it is made. Atlas keeps it where no screen or API response returns it again. If you lose it, generate a new one; the old one stops working at once.
• Send the secret in the X-Atlas-Webhook-Secret header. The secret query parameter still works for systems that cannot set a header, but an address is often written to logs.
• A script stops after its time limit, 30 seconds by default, and cannot reach the network or the file system. It reads tasks through atlas.tasks.list() and nothing else in the workspace.
• An automation that fails several times in a row is turned off, and its owner is told why.

1. 1Open Automations, then Script automations, and choose New automation.
2. 2Name it and choose when it runs: on a schedule, when something changes in the workspace, or when another system calls it.
3. 3Write the script. Read what started the run from trigger and the tasks from await atlas.tasks.list(), and return what you want to see in the run.
4. 4Choose Create automation. For a webhook automation, copy the address and the secret now; the secret is not shown again.
5. 5On the automation page, choose Run test under Test run with a sample payload, and read the result when the run finishes.
6. 6Choose Turn off to stop it running on its trigger. Its script and run history are kept, and Turn on starts it again.

Should I write a script or a workspace rule?

Start with a workspace rule in Settings, Automations. Rules need no code and cover setting a field, applying a label, notifying a person and calling a webhook when something changes. Write a script when you need logic a rule cannot express.

What time zone does a schedule use?

The zone shown under the schedule, which is your own when you create the automation. The schedule keeps its local time across daylight-saving changes. A time that does not exist on the day the clocks go forward runs just after the change, and a time that happens twice when they go back runs once.

I lost the webhook secret. Can I see it again?

No. Open the automation and choose Generate a new secret, then give the new secret to the system that calls it. The old secret stops working as soon as the new one is made.

Can I run a Python script on a schedule?

No. Python runs only in the browser sandbox. Rewrite the script in JavaScript and save it as an automation from the sandbox.