Repository navigation
automation
An automation is a rule of the form "when this happens, if this holds, do that", edited in a visual editor under Automation (sidebar, or 6).
Seventeen: thirteen covering a download's lifecycle, three for the whole queue, and one for a time.
| Trigger | Fires when |
|---|---|
| Links arrived | Something reached the LinkGrabber |
| Download resolved | A link was resolved to a downloadable address |
| Download started | |
| Download finished | A file finished downloading — once per file, not again after it was unpacked |
| Download failed | |
| Package finished | A package's state changed to finished — once per outcome |
| Package failed | A package's state changed to failed — once per outcome |
| Unpacking finished | |
| Script finished | |
| Upload finished | |
| Storage threshold | A storage root fell below its free-space reserve — or, named in the condition, had room again |
| Subscription item | A subscription accepted an item |
| Usenet download beyond repair | A Usenet download was stopped because more PAR2 blocks are missing than its volumes can repair (Usenet) |
| Queue paused | The whole queue paused |
| Queue resumed | That pause ended |
| Queue finished | Nothing waits, downloads or is post-processed any more |
| At a time | The schedule says so |
Package finished and Package failed run once for each real change of the package's state. Reordering a package, renaming it, a post-processing stage or the same state saved again runs nothing. An outcome still runs when the package was restarted or removed by the time the rule is evaluated.
A storage root is blocked when its free space falls below its reserve, and released once
there is room again. The condition field Storage change tells the two apart — blocked or
released. A storage rule whose condition does not name it runs only when storage is
blocked; to act when there is room again, add the condition Storage change equals
released. The editor says so under the trigger.
Each block and each release concerns one storage root: two roots running out in the same moment are two runs. To act for one root only, add the condition Storage target equals that root. The editor offers your storage roots by name, and the download directory as Download directory; it keeps the root itself, not its name, so a root you happen to call Downloads never stands in for the download directory.
Queue paused runs when the whole queue pauses, whatever paused it. The condition field
Source names the cause: manual (by hand), automation, schedule, stop_mark or
game_mode; for one cause only, add the condition Source equals that cause. Queue resumed
runs when the pause ends, Queue finished when the queue has run empty.
Each runs once per change: a second pause on top of the first, or a queue that stays empty, runs nothing more. The whole queue names no package, so the package actions are not offered with these three.
The trigger At a time runs an automation on a schedule instead of on an event:
- Every few minutes — every N Minutes, counted from midnight (1 to 1440): 60 runs on the hour, 1440 once a day at midnight.
-
Cron expression — five fields, minute hour day month weekday, for example
0 6 * * 1-5for weekdays at six.
Times are read in the service's time zone. A missed time is not caught up: a time the service missed by more than two minutes — because it was off or restarting — is skipped, and a time is run only once even when the service restarts within those two minutes. A schedule names no package, so the package actions below are not offered with it.
Two of them make a download window for the whole queue: Pause queue at 0 6 * * * and
Start queue at 0 22 * * *. A bandwidth profile that pauses downloads does the same with more
care — it lets downloads that cannot resume finish, and lets single packages through; see
Downloading only at certain times.
Conditions reuse the routing-rule vocabulary: source, domain, extension, name, category,
state, failure code, size, kind, and for the storage threshold the storage change and the storage
target — combined with all, any and not, nested as deeply as you
need.
An invalid condition is refused while you write it, not at trigger time. The operator list
narrows with the field, so a size compared with contains cannot be built at all.
Up to ten per automation:
| Action | Does |
|---|---|
| Call webhook | Calls a configured webhook |
| Run script | Runs a script from the post-processing scripts directory |
| Move to category | Moves the package and its files to a category — after any unpacking |
| Pause package / Resume package | Pauses or resumes the package |
| Set priority | Sets the package's priority: Low, Normal or High |
| Extract package | Unpacks the package |
| Pause queue | Pauses the whole queue as Pause all does, until a Start queue — by hand or from another automation — ends it |
| Start queue | Ends a pause of the whole queue |
| Notify | Sends a Message of your own (1–500 characters) through a notification target |
| Add links | Adds Links, one per line — to the LinkGrabber, where routing rules and the online check apply, or straight to the Downloads (HTTP(S) links only, each a package of its own) |
The package actions need a trigger that names a package.
Move to category moves the package's files into the category's folder, also for a category not shown in the selection. While the package is post-processed or unpacked, or still due to be, the move waits and happens once that has ended. A category you change in the downloads list waits the same way; see Moving a package to another category.
An action cannot name a path or a secret. It picks from what is already configured; the only addresses an automation names are the links of Add links, and those go through the ordinary intake. Because they run unattended, they keep the rule for links from your own intake: an address in your own network is fine, but never this machine — in the LinkGrabber such a link is marked and not checked, and the downloads refuse it. Add links into the LinkGrabber on the trigger Links arrived is refused, since it would start the automation again.
Nested all/any/not is shown in reading order.
Duplicate on an automation creates a switched-off copy under a free name and opens it in the editor, for a rule that differs from an existing one in a detail.
A dry run evaluates the automation as it stands in the form — saved or not, switched on or not — against a real package, and reports whether the trigger matches and whether the condition holds, without changing anything. It lists the actions a match would run and, for a schedule, when it runs next. Use it before saving a rule or switching it on.
- Every save writes a new version, and a run holds the version it started under. Editing a rule never changes what an in-flight run is judged by.
- The version history opens from the clock button on an automation's row: every saved version, newest first, with its date, trigger, condition and actions, and a changed mark on what it changed against the version before. Restore puts an older version's trigger, condition and actions back in force by saving them as a new version — name and on/off switch stay as they are, and the versions in between stay in the history.
- Reset versions, at the foot of the version history, empties it: every version but the current one is deleted together with its runs, and the current one becomes version 1 with its own runs. The confirmation says how many versions and runs go; it cannot be undone. While a run of an older version is still queued, running or waiting for a retry, the reset is refused — wait until it has finished.
- The same event starts the same automation at most once.
- A run interrupted by a restart is picked up again.
- Failures back off and end as a recorded failure, visible in the run history.
A webhook that was delivered but interrupted while answering is retried, so a receiver can see the same call twice and should use the idempotency key to drop the repeat. The alternative would be losing actions to a badly timed restart.
A failing automation cannot affect the download that triggered it.
Automations can be written to a file and read back on another installation, with all their actions. The file references categories and targets by name and carries no credentials.
- Notifications — the webhook targets an action can call
- Storage, categories and rules — the condition vocabulary
- Post-processing — the scripts directory an action runs from
- The download queue