Skip to content

Job Scheduling and Approvals

Oftentimes jobs will need to be run at a later date or periodically, or require approval from someone before they can be started. To this end, Nautobot offers facilities for scheduling and approving jobs.

Job Scheduling

Jobs can be scheduled to be run immediately, at some point in the future, or at an interval.

Jobs can be scheduled through the UI or the API.

Warning

A Job must be enabled and cannot have has_sensitive_variables set to True in order to be scheduled. If these requirements are not met, a warning banner will appear on the run Job view with the reason why Job Scheduling is not an option.

Scheduling via the UI

The Job Scheduling views can be accessed via the navigation at Jobs > Jobs, selecting a Job as appropriate.

The UI allows you to select a scheduling type. Further fields will be displayed as appropriate for that schedule type.

If Recurring custom is chosen, you can schedule the recurrence in the Crontab field in crontab syntax.

If the job requires no approval, it will then be added to the queue of scheduled jobs or run immediately. Otherwise, the job will be added to the approval queue where it can be approved by other users.

Once a job has been scheduled, the schedule can be deleted by navigating to Jobs > Scheduled Jobs, selecting the schedule name and clicking the Delete button. You can also select multiple schedules and click the Delete Selected button to delete them all at once.

Assuming Ownership of a Scheduled Job

Each scheduled job is owned by, and runs as, the user that created it. If that user is removed, the schedule can no longer run and is automatically disabled the next time it would have fired; a failed JobResult is also recorded.

Ownership of a scheduled job can be transferred at any time via the Assume Ownership button on the Scheduled Job detail view. Clicking it reassigns the schedule to the current user. If the scheduled job was previously disabled due to a failure, the button also re-enables it.

The button is hidden when the requester is already the current owner, and is only visible to users that meet all of the following criteria:

  • They are not the current owner of the scheduled job.
  • They have the extras.change_scheduledjob permission.
  • They have the extras.run_job permission for the specific Job that the schedule runs (object-level permissions on the Job are honored).

The most common reason to use this action is to recover a scheduled job whose original owner was removed, but it can also be used to hand off a recurring schedule to another administrator.

Scheduling via the API

Jobs can also be scheduled via the REST API. The endpoint used for this is the regular job endpoint; specifying the optional schedule parameter will act just as scheduling in the UI.

curl -X POST \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json; version=1.3; indent=4" \
http://nautobot/api/extras/jobs/$JOB_ID/run/ \
--data '{"schedule": {"name": "test", "interval": "future", "start_time": "2030-01-01T01:00:00.000Z"}}'

For custom interval, a crontab parameter must be added.

start_time becomes optional when interval is set to custom.

--data '{"schedule": {"name": "test", "interval": "custom", "start_time": "2030-01-01T01:00:00.000Z", "crontab": "*/15 * * * *"}}'

You may delete a scheduled job via the API by issuing a DELETE request to the /api/extras/scheduled-jobs/<uuid>/ endpoint, or by issuing a DELETE request to the /api/extras/scheduled-jobs/ endpoint with a list of UUIDs of the scheduled jobs to be deleted.

Job Approvals

Jobs that have approval_required set to True on their Meta object require another user to approve a scheduled job.

Warning

Requiring approval for execution of Job Hooks by setting the Meta.approval_required attribute to True on your JobHookReceiver subclass is not supported. The value of this attribute will be ignored. Support for requiring approval of Job Hooks will be added in a future release.

Scheduled jobs can be approved or denied via the UI and API by any user that has the extras.approve_job permission for the job in question, as well as the appropriate extras.change_scheduledjob and/or extras.delete_scheduledjob permissions.

Note

Jobs that are past their scheduled run date can still be approved, but the approver will be asked to confirm the operation.

Approval via the UI

The queue of jobs that need approval can be found under Jobs > Job Approval Queue. This view lists all currently requested jobs that need approval before they are run. To approve a job, select it and click the button to approve. Please note that you will be asked for confirmation if a job is being approved that is past its scheduled date and time.

If the approver is unsure what a job would do, a dry run can also be started via that same view.

Approval via the API

Approvals can also be given via the REST API. The endpoints to approve, deny, and dry run a scheduled job are found on the scheduled job endpoint under approve, deny, and dry-run, respectively.

curl -X POST \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json; version=1.3; indent=4" \
http://nautobot/api/extras/scheduled-jobs/$JOB_ID/approve?force=true

The approval endpoint additionally provides a force query parameter that needs to be set if a job is past its scheduled datetime. This mimics the confirmation dialog in the UI.