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.

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

As of Nautobot 1.3, each Job class installed in Nautobot is represented by a corresponding Job data record in the Nautobot database. These data records are refreshed when the nautobot-server migrate or nautobot-server post_upgrade command is run, or (for Jobs from a Git repository) when a Git repository is enabled or re-synced in Nautobot. These data records make it possible for an administrative user (or other user with appropriate access privileges) to exert a level of administrative control over the Jobs created and updated by Job authors.

Enabling Jobs for Running

When a new Job record is created for a newly discovered Job class, it defaults to enabled = False, which prevents the Job from being run by any user. This is intended to provide a level of security and oversight regarding the installation of new Jobs into Nautobot.

Important

One exception to this default is when upgrading from a Nautobot release before 1.3 to Nautobot 1.3.0 or later. In this case, at the time of the upgrade, any Job class that shows evidence of having been run or scheduled under the older Nautobot version (that is, there is at least one JobResult and/or ScheduledJob record that references this Job class) will result in the creation of a Job database record with enabled = True. The reasoning for this feature is the assertion that because the Job has been run or scheduled previously, it has presumably already undergone appropriate review at that time, and so it should remain possible to run it as it was possible before the upgrade.

An administrator or user with extras.change_job permission can edit the Job to change it to enabled = True, permitting running of the Job, when they have completed any appropriate review of the new Job to ensure that it meets their standards. Similarly, an obsolete or no-longer-used Job can be prevented from inadvertent execution by changing it back to enabled = False.

By default when a Job is installed into Nautobot it is installed in a disabled state. In order to enable a Job:

• Navigate to Jobs > Jobs menu
• Select a job that has been installed
• Select Edit button
• In the second section titled Job, select the Enabled checkbox
• Select Update button at the bottom

Enabling Job Hooks

Job hooks are enabled in a similar fashion, but by using the default filters when navigating to the Jobs page the Job Hooks will not be visible. To enable job hooks:

• Navigate to Jobs > Jobs menu
• Select the Filter button to bring up the Filter Jobs context
• Look for Is job hook receiver and change the drop down to Yes
• Select Apply button
• Select a job that has been installed
• Select Edit button
• In the second section titled Job, select the Enabled checkbox
• Select Update button at the bottom

Overriding Metadata

An administrator or user with extras.change_job permission can also edit a Job database record to optionally override any or all of the following metadata attributes defined by the Job module or class:

• grouping
• name
• description
• approval_required
• dryrun_default
• has_sensitive_variables
• hidden
• soft_time_limit
• time_limit
• task_queues

This is done by setting the corresponding "override" flag (grouping_override, name_override, etc.) to True then providing a new value for the attribute in question. An overridden attribute will remain set to its overridden value even if the underlying Job class definition changes and nautobot-server <migrate|post_upgrade> gets run again. Conversely, clearing the "override" flag for an attribute and saving the database record will revert the attribute to the underlying value defined within the Job class source code.

Deleting Jobs

When a previously installed Job class is removed, after running nautobot-server <migrate|post_upgrade> or refreshing the providing Git repository, the Job database record will not be automatically deleted, but will be flagged as installed = False and can no longer be run or scheduled.

An administrator or user with extras.delete_job permissions may delete such a Job database record if desired, but be aware that doing so will result in any existing JobResult or ScheduledJob records that originated from this Job losing their association to the Job; this association will not be automatically restored even if the Job is later reinstalled or reintroduced.

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.

Jobs and class_path

Changed in version 2.0.0

The class_path concept has been simplified compared to Nautobot 1.x.

It is a key concept to understand the 2 class_path elements:

• module_name: which is the importable Python path to the job definition (with . in place of / in the directory path, and not including the .py file extension, as per Python syntax standards).
  • For an App-provided job, this might be something like my_app_name.jobs.my_job_filename or nautobot_golden_config.jobs
  • For a locally installed job, this would match the file name, such as my_job_filename
  • For a Git-provided job, this includes the repository's defined slug, such as my_repository.jobs.my_job_filename
• JobClassName: which is the name of the class inheriting from nautobot.extras.jobs.Job contained in the above file.

The class_path is often represented as a string in the format of <module_name>.<JobClassName>, such as example.MyJobWithNoVars or nautobot_golden_config.jobs.BackupJob. Understanding the definitions of these elements will be important in running jobs programmatically.

Changed in version 1.3.0

With the addition of Job database models, it is now generally possible and preferable to refer to a job by its UUID primary key, similar to other Nautobot database models, rather than its class_path.

Changed in version 2.0.0

The Job database model name field is now enforced to be globally unique and so is also an option for uniquely identifying Job records.

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.

Added in version 1.3.10

The --data and --local parameters were added.

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.