Run services on a schedule
Run services on an interval or at a specific time.
The scheduler invokes your services on an interval or at a specific time. Jobs are created in the Dashboard or from Python and no service code changes are needed for a service to become a scheduled one.
For a step-by-step introduction, see the Python scheduler tutorial.
Invoke services on an interval
To create a job, go to Scheduler > Config in the Dashboard, click Create a new job and fill in the form:
- Name: Nightly Sync
- Service: the service the scheduler invokes on each run
- Every: how often to run it, e.g. every 30 minutes
- Click OK

The service is invoked each time the job fires, and any extra data provided in the job's definition is available to the service as text in self.request.input:
# -*- coding: utf-8 -*-
# Zato
from zato.server.service import Service
class MyService(Service):
def handle(self):
self.logger.info('Message received: %s', self.request.input)
Schedule one-time jobs in Python
To run a service once, at a specific time, call self.schedule.onetime. The example below schedules another service for a specific moment - the prefix parameter makes the job easy to find in the Dashboard and logs:
# -*- coding: utf-8 -*-
# Zato
from zato.server.service import Service
class MyTarget(Service):
def handle(self):
self.logger.warn('I was invoked with %s', self.request.input)
class Scheduler(Service):
def handle(self):
# This can be used to make it easier to understand which scheduled job is which
prefix = 'user@example.com'
# This is what the target service is going to receive on input
data = {
'my.key': 'my.value'
}
# This is when the job should start, note that the time must be in UTC
start_date = '2027-07-29 11:35:49'
# This is the call that schedules the job
self.schedule.onetime(self, MyTarget, prefix=prefix, start_date=start_date, data=data)
Schedule interval-based jobs in Python
To create interval-based jobs from code, invoke the built-in zato.scheduler.job.create service:
# stdlib
from datetime import datetime
# Zato
from zato.server.service import Service
class MyService(Service):
def handle(self):
#
# We schedule a job here that will run once per hour
#
request = {
'name': 'my-job-1',
'is_active': True,
'service': 'zato.ping',
'job_type': 'interval_based',
'start_date': datetime.utcnow().isoformat(), # Always in UTC
'hours': 1
}
self.invoke('zato.scheduler.job.create', request)
Run jobs in an active-passive pair
In an active-passive pair, two containers run against the same PostgreSQL pub/sub database, and the server that started last is the active one. Each run of a job takes place on exactly one server of the pair, as follows:
- Both containers start their scheduler with
Zato_Start_Schedulerset totrue, and both import the same jobs. - Before a server invokes the service of a job, it claims the run in the common database, which is the pub/sub database of the pair.
- A run that the other server has already claimed ends with the outcome
skipped_already_run. - A run on a server that another server has replaced, or on a server that cannot reach the database, ends with the outcome
skipped_not_active.
Both outcomes are listed in the history of each job in the Dashboard, next to the other outcomes of its runs.
The number of runs of a job and the time of its latest run are kept in the common database, so after a switch, the new active server continues each job from where the previous one stopped:
- A job with a limited number of runs runs only the runs that remain.
- A one-time job that has already run does not run again, and a one-time job that was due while neither server was active runs once when the new server starts.
- A job whose runs fell into the time between the two servers runs once when the new server starts, in place of the latest of these runs.
While the database is unavailable, the active server ends each run that falls due with the outcome skipped_not_active and invokes no service. Once the database is back, the jobs continue with their next runs, and the runs that fell into the outage do not take place.
start_date. A job without one counts its runs from the time of its import, which differs between the two containers, so the runs of the two servers fall at different times.See also
| Feature | What it does |
|---|---|
| IMAP | Poll mailboxes on a schedule with an auto-created job |
| Config files | Keep a job's settings outside code |
| SMTP | Send email from scheduled services |