Skip to content

Jobs

Jobs are a way for users to execute custom logic on demand from within the Nautobot UI. Jobs can interact directly with Nautobot data to accomplish various data creation, modification, and validation tasks, such as:

  • Automatically populate new devices and cables in preparation for a new location deployment
  • Create a range of new reserved prefixes or IP addresses
  • Fetch data from an external source and import it to Nautobot
  • Check and report whether all top-of-rack switches have a console connection
  • Check and report whether every router has a loopback interface with an assigned IP address
  • Check and report whether all IP addresses have a parent prefix

...and so on. Jobs are Python code and exist outside of the official Nautobot code base, so they can be updated and changed without interfering with the core Nautobot installation. And because they're completely customizable, there's practically no limit to what a job can accomplish.

The following pages provide detailed guides for managing and running Jobs:

Changed in version 2.0.0

Backwards compatibility with NetBox scripts and reports has been removed. This includes removal of automatic calls to the post_run() and test_*() methods.

Note

Jobs unify and supersede the functionality previously provided in NetBox by "custom scripts" and "reports". User input is supported via job variables.

Managing Jobs

Each installed Job class has an associated database record controlling its availability and metadata.

To enable or disable Jobs, override metadata, or remove obsolete Job records, see Managing Jobs.

Running Jobs

Note

To run any job, a user must be assigned the extras.run_job permission. This is achieved by assigning the user (or group) a permission on the extras > job object and specifying the run action in the admin UI as shown below.

Similarly, to approve a job request by another user, a user must be assigned the extras.approve_job permission via the same process. Job approvers also need the extras.change_scheduledjob and/or extras.delete_scheduledjob permissions as job approvals are implemented via the ScheduledJob data model.

Adding the run action to a permission Admin → Users → (Select user or group) → Object permissions → Add object permission

Via the Web UI

Jobs can be run via the web UI by navigating to the job, completing any required form data (if any), and clicking the "Run Job" button.

Once a job has been run, the latest JobResult for that job will be summarized in the job list view.

Via the REST API

Removed in version 2.0.0

The commit parameter was removed. All job input should be provided via the data parameter.

To run a job via the REST API, issue a POST request to the job's endpoint /api/extras/jobs/<uuid>/run/ or /api/extras/jobs/<name>/run/. You can optionally provide JSON data to specify any required user input data, optional task_queue, and/or provide optional scheduling information as described in the section on scheduling and approvals.

Added in version 2.0.0

The /api/extras/jobs/<name>/ REST API endpoints were added as an alternative to /api/extras/jobs/<uuid>/.

For example, to run a job, by UUID, with no user inputs:

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/

Or to run a job, by name, that expects user inputs:

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_NAME/run/ \
--data '{"data": {"string_variable": "somevalue", "integer_variable": 123}}'

When providing input data, it is possible to specify complex values contained in ObjectVars, MultiObjectVars, and IPAddressVars.

  • ObjectVars can be specified by either using their primary key directly as the value, or as a dictionary containing a more complicated query that gets passed into the Django ORM as keyword arguments.
  • MultiObjectVars can be specified as a list of primary keys.
  • IPAddressVars can be provided as strings in CIDR notation.

Jobs with Files

To run a job that contains FileVar inputs via the REST API, you must use multipart/form-data content type requests instead of application/json. This also requires a slightly different request payload than the example above. The task_queue and schedule data are flattened and prefixed with underscore to differentiate them from job-specific data. Job specific data is also flattened and not located under the top-level data dictionary key.

An example of running a job with both FileVar (named myfile) and StringVar (named interval) input:

curl -X POST \
-H 'Authorization: Token $TOKEN' \
-H 'Content-Type: multipart/form-data' \
-H "Accept: application/json; version=1.3; indent=4" \
'http://nautobot/api/extras/jobs/$JOB_NAME/run/' \
-F '_schedule_interval="immediately"' \
-F '_schedule_start_time="2022-10-18T17:31:23.698Z"' \
-F 'interval="3"' \
-F 'myfile=@"/path/to/my/file.txt"' \

Via the CLI

Jobs can be run from the CLI by invoking the management command:

nautobot-server runjob [--username <username>] [--local] [--data <data>] <class_path>

Note

See above for class_path definitions.

The --data parameter must be a JSON string, e.g. --data='{"string_variable": "somevalue", "integer_variable": 123}'

Using the same example shown in the API:

nautobot-server runjob --username myusername example.MyJobWithNoVars

Warning

The --username <username> must be supplied to specify the user that will be identified as the requester of the job.

Note that nautobot-server commands, like all management commands and other direct interactions with the Django database, are not gated by the usual Nautobot user authentication flow. It is possible to specify any existing --username with the nautobot-server runjob command in order to impersonate any defined user in Nautobot. Use this power wisely and be cautious who you allow to access it.