Knowledge base Best practice Recommended
Keep a service running instead of shortening its interval
In shortThe scheduler starts a service at most once a minute and counts the interval from the end of the previous run, so "00:01:00" means one to two minutes between runs. When work must be picked up within seconds, let the run stay: do the work, sleep a few seconds, look again, and stop well before TimeOut.
Applies to ServicesServices.jsonSchedulesIntervalsTimeOutdocly.sleep
-
What you'll see
A scheduled service handles work that arrives at any time, such as a queue of form submissions or tickets to answer, and someone is waiting for the result. With
"Intervals": ["00:01:00"]the work waits one to two minutes before the service even looks, and work that needs several runs waits that long every time. A shorter interval does not help. -
What's actually happening
How the scheduler decides when an interval is due:
- It checks for due services once a minute. A service cannot start more often than that, whatever the interval says.
- The interval counts from when the previous run finished, not from when it started. With
"00:01:00", a run that finishes just after a check is due again just after the next check, so it starts at the check after that. In practice the runs come every one to two minutes, and after a run that did real work, usually two. - The same task never runs twice at the same time. Two different tasks in the same
Services.jsonrun side by side, each in its own background job. TimeOutis the limit for the run, measured in wall-clock time from the start. Without it the limit is one minute.docly.setExecutionTimeout()only raises the limit when the site owner is a Docly administrator, so set it inServices.json.- The limit is checked between statements. A call that waits for a remote server, such as an AI call or an HTTP request, finishes first, and the next statement then stops the run. Whatever the script had done but not yet saved is lost, and the next run starts that step again.
-
What to do
Let the run stay and look for work itself, and stop with a good margin before
TimeOut:{ "Schedules": [ { "Name": "Queue worker", "Intervals": [ "00:01:00" ], "Task": { "Path": "worker.js", "TimeOut": "00:10:00" } } ] }// TimeOut is 10 minutes: no new step after 7, so the step in progress has room to finish const BUDGET_MS = 7 * 60 * 1000; const POLL_MS = 5000; export default () => { let started = Date.now(); let handled = 0; while (Date.now() - started < BUDGET_MS) { let done = processWaitingItems(started); // checks the budget before every step handled += done; if (!done) docly.sleep(POLL_MS); // nothing to do: look again in 5 seconds } return "Handled " + handled; };- Check the budget before every step, not only between rounds. The margin must cover the longest single step.
docly.sleep()also forgets the file lookups the run has made, sogetFileandgetFilesafter the sleep see files that other requests have written in the meantime.- Make every step safe to repeat. A run can still be stopped in the middle of a step, by the time limit or a server restart, and the next run then does the step again. Save progress after each step, and keep anything that cannot be undone, such as sending an e-mail, as the last thing in the step.
- Do not log on every idle look, and do not retry a failing item every five seconds: remember it for the rest of the run. Otherwise the console buffer fills up with the same lines.
- Read your settings again after a sleep if the run should stop when someone turns the feature off.
- Scripts have no lock between tasks. If two tasks can pick up the same item, let one of them own it, or the item is handled twice.
- To react to a file within seconds instead, use file events. See Run a service when a file changes. The event queue is held in memory, so keep a scheduled run as well.
Last reviewed 18 Nov 2026