nautobot 2.0.0a3__py3-none-any.whl → 2.0.0b1__py3-none-any.whl

nautobot/docs/additional-features/jobs.md

@@ -11,8 +11,11 @@ Jobs are a way for users to execute custom logic on demand from within the Nauto
 
 ...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.
 
++/- 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". Jobs are backwards-compatible for now with the `Script` and `Report` class APIs, but you are urged to move to the new `Job` class API described below. Jobs may be optionally marked as [read-only](#read_only) which equates to the `Report` functionally, but in all cases, user input is supported via [job variables](#variables).
+    Jobs unify and supersede the functionality previously provided in NetBox by "custom scripts" and "reports". User input is supported via [job variables](#variables).
 
 ## Writing Jobs
 
@@ -31,10 +34,14 @@ In any case, each module holds one or more Jobs (Python classes), each of which
 
 For example, we can create a module named `devices.py` to hold all of our jobs which pertain to devices in Nautobot. Within that module, we might define several jobs. Each job is defined as a Python class inheriting from `extras.jobs.Job`, which provides the base functionality needed to accept user input and log activity.
 
++/- 2.0.0
+    All job classes must now be registered with `nautobot.core.celery.register_jobs` on module import. For plugins providing jobs, the module containing the jobs must be imported by the plugin's `__init__.py` and the `register_jobs` method called at import time. The `register_jobs` method accepts one or more job classes as arguments.
+
 !!! warning
     Make sure you are *not* inheriting `extras.jobs.models.Job` instead, otherwise Django will think you want to define a new database model.
 
 ```python
+from nautobot.core.celery import register_jobs
 from nautobot.extras.jobs import Job
 
 class CreateDevices(Job):
@@ -45,20 +52,15 @@ class DeviceConnectionsReport(Job):
 
 class DeviceIPsReport(Job):
     ...
+
+register_jobs(CreateDevices, DeviceConnectionsReport, DeviceIPsReport)
 ```
 
 Each job class will implement some or all of the following components:
 
 * Module and class attributes, providing for default behavior, documentation and discoverability
 * a set of variables for user input via the Nautobot UI (if your job requires any user inputs)
-* a `run()` method, which is executed first and receives the user input values, if any
-* any number of `test_*()` methods, which will be invoked next in order of declaration. Log messages generated by the job will be grouped together by the test method they were invoked from.
-* a `post_run()` method, which is executed last and can be used to handle any necessary cleanup or final events (such as sending an email or triggering a webhook). The status of the overall job is available at this time as `self.failed` and the `JobResult` data object is available as `self.result`.
-
-You can implement the entire job within the `run()` function, but for more complex jobs, you may want to provide more granularity in the output and logging of activity. For this purpose, you can implement portions of the logic as `test_*()` methods (i.e., methods whose name begins with `test_*`) and/or a `post_run()` method. Log messages generated by the job logging APIs (more below on this topic) will be grouped together according to their base method (`run`, `test_a`, `test_b`, ..., `post_run`) which can aid in understanding the operation of the job.
-
-!!! note
-    Your job can of course define additional Python methods to compartmentalize and reuse logic as required; however the `run`, `test_*`, and `post_run` methods are the only ones that will be automatically invoked by Nautobot.
+* a `run()` method, which is the only required attribute on a Job class and receives the user input values, if any
 
 It's important to understand that jobs execute on the server asynchronously as background tasks; they log messages and report their status to the database by updating [`JobResult`](../models/extras/jobresult.md) records and creating [`JobLogEntry`](../models/extras/joblogentry.md) records.
 
@@ -112,16 +114,19 @@ Default: `False`
 
 A boolean that will mark this job as requiring approval from another user to be run. For more details on approvals, [please refer to the section on scheduling and approvals](./job-scheduling-and-approvals.md).
 
-#### `commit_default`
+#### `dryrun_default`
 
-Default: `True`
++/- 2.0.0
+    The `commit_default` field was renamed to `dryrun_default` and the default value was changed from `True` to `False`. The `commit` functionality that provided an automatic rollback of database changes if the job failed was removed. The `dryrun` functionality was added to provide a way to bypass job approval if a job implements a [`DryRunVar`](#dryrunvar).
+
+Default: `False`
 
-The checkbox to commit database changes when executing a job is checked by default in the Nautobot UI. You can set `commit_default` to `False` under the `Meta` class if you want this option to instead be unchecked by default.
+The checkbox to enable dryrun when executing a job is unchecked by default in the Nautobot UI. You can set `dryrun_default` to `True` under the `Meta` class if you want this option to instead be checked by default.
 
 ```python
 class MyJob(Job):
     class Meta:
-        commit_default = False
+        dryrun_default = True
 ```
 
 #### `field_order`
@@ -163,9 +168,12 @@ Important notes about hidden jobs:
 
 +++ 1.1.0
 
++/- 2.0.0
+    The `read_only` flag no longer changes the behavior of Nautobot core and is up to the job author to decide whether their job should be considered read only.
+
 Default: `False`
 
-A boolean that designates whether the job is able to make changes to data in the database. The value defaults to `False` but when set to `True`, any data modifications executed from the job's code will be automatically aborted at the end of the job. The job input form is also modified to remove the `commit` checkbox as it is irrelevant for read-only jobs. When a job is marked as read-only, log messages that are normally automatically emitted about the DB transaction state are not included because no changes to data are allowed. Note that user input may still be optionally collected with read-only jobs via job variables, as described below.
+A boolean that can be set by the job author to indicate that the job does not make any changes to the environment. What behavior makes each job "read only" is up to the individual job author to decide. Note that user input may still be optionally collected with read-only jobs via job variables, as described below.
 
 #### `soft_time_limit`
 
@@ -185,7 +193,7 @@ class ExampleJobWithSoftTimeLimit(Job):
         description = "Set a soft time limit of 10 seconds`"
         soft_time_limit = 10
 
-    def run(self, data, commit):
+    def run(self):
         try:
             # code which might take longer than 10 seconds to run
             job_code()
@@ -250,7 +258,7 @@ class ExampleJobWithHardTimeLimit(Job):
         description = "Set a hard time limit of 10 seconds`"
         time_limit = 10
 
-    def run(self, data, commit):
+    def run(self):
         # code which might take longer than 10 seconds to run
         # this code will fail silently if the time_limit is exceeded
         job_code()
@@ -271,7 +279,7 @@ class CreateDevices(Job):
     var2 = IntegerVar(...)
     var3 = ObjectVar(...)
 
-    def run(self, data, commit):
+    def run(self, var1, var2, var3):
         ...
 ```
 
@@ -312,6 +320,10 @@ Stores a numeric integer. Options include:
 
 A true/false flag. This field has no options beyond the defaults listed above.
 
+#### `DryRunVar`
+
+A true/false flag with special handling for jobs that require approval. If `dryrun = DryRunVar()` is declared on a job class, approval may be bypassed if `dryrun` is set to `True` on job execution.
+
 #### `ChoiceVar`
 
 A set of choices from which the user can select one.
@@ -364,20 +376,20 @@ device = ObjectVar(
 )
 ```
 
-Multiple values can be specified by assigning a list to the dictionary key. It is also possible to reference the value of other fields in the form by prepending a dollar sign (`$`) to the variable's name. The keys you can use in this dictionary are the same ones that are available in the REST API - as an example it is also possible to filter the `Site` `ObjectVar` for its `tenant_group`.
+Multiple values can be specified by assigning a list to the dictionary key. It is also possible to reference the value of other fields in the form by prepending a dollar sign (`$`) to the variable's name. The keys you can use in this dictionary are the same ones that are available in the REST API - as an example it is also possible to filter the `Location` `ObjectVar` for its `location_type` and `tenant_group`.
 
 ```python
-region = ObjectVar(
-    model=Region
+location_type = ObjectVar(
+    model=LocationType
 )
 tenant_group = ObjectVar(
     model=TenantGroup
 )
-site = ObjectVar(
-    model=Site,
+location = ObjectVar(
+    model=Location,
     query_params={
-        'region': '$region',
-        'tenant_group': '$tenant_group'
+        "location_type": "$location_type",
+        "tenant_group": "$tenant_group"
     }
 )
 ```
@@ -407,10 +419,7 @@ An IPv4 or IPv6 network with a mask. Returns a `netaddr.IPNetwork` object. Two a
 
 ### The `run()` Method
 
-The `run()` method, if you choose to implement it, should accept two arguments:
-
-1. `data` - A dictionary which will contain all of the variable data passed in by the user (via the web UI or REST API)
-2. `commit` - A boolean indicating whether database changes should be committed. If this is `False`, even if your Job attempts to make database changes, they will be automatically rolled back when the Job completes.
+The `run()` method must be implemented. After the `self` argument, it should accept keyword arguments for any variables defined on the job:
 
 ```python
 from nautobot.extras.jobs import Job, StringVar, IntegerVar, ObjectVar
@@ -420,20 +429,11 @@ class CreateDevices(Job):
     var2 = IntegerVar(...)
     var3 = ObjectVar(...)
 
-    def run(self, data, commit):
+    def run(self, var1, var2, var3):
         ...
 ```
 
-Again, defining user variables is totally optional; you may create a job with just a `run()` method if no user input is needed, in which case `data` will be an empty dictionary.
-
-!!! note
-    The `test_*()` and `post_run()` methods do not accept any arguments; if you need to access user `data` or the `commit` flag, your `run()` method is responsible for storing these values in the job instance, such as:
-
-    ```
-    def run(self, data, commit):
-        self.data = data
-        self.commit = commit
-    ```
+Again, defining user variables is totally optional; you may create a job with a `run()` method with only the `self` argument if no user input is needed.
 
 !!! warning
     When writing Jobs that create and manipulate data it is recommended to make use of the `validated_save()` convenience method which exists on all core models. This method saves the instance data but first enforces model validation logic. Simply calling `save()` on the model instance **does not** enforce validation automatically and may lead to bad data. See the development [best practices](../development/best-practices.md).
@@ -441,54 +441,82 @@ Again, defining user variables is totally optional; you may create a job with ju
 !!! warning
     The Django ORM provides methods to create/edit many objects at once, namely `bulk_create()` and `update()`. These are best avoided in most cases as they bypass a model's built-in validation and can easily lead to database corruption if not used carefully.
 
-### The `test_*()` Methods
+--- 2.0.0
+    The NetBox backwards compatible `test_*()` and `post_run()` methods have been removed.
+
+### Logging
 
-If your job class defines any number of methods whose names begin with `test_`, these will be automatically invoked after the `run()` method (if any) completes. These methods must take no arguments (other than `self`).
++/- 2.0.0
 
-Log messages generated by any of these methods will be automatically grouped together by the test method they were invoked from, which can be helpful for readability.
+Messages logged from a job's logger will be stored in [`JobLogEntry`](../models/extras/joblogentry.md) records associated with the current [`JobResult`](../models/extras/jobresult.md).
 
-### The `post_run()` Method
+The logger can be accessed either by using the `logger` property on the job class or `nautobot.extras.jobs.get_task_logger(__name__)`. Both will return the same logger instance. For more information on the standard Python logging module, see the [Python documentation](https://docs.python.org/3/library/logging.html).
 
-If your job class implements a `post_run()` method (which must take no arguments other than `self`), this method will be automatically invoked after the `run()` and `test_*()` methods (if any). It will be called even if one of the other methods raises an exception, so this method can be used to handle any necessary cleanup or final events (such as sending an email or triggering a webhook). The status of the overall job is available at this time as `self.failed` and the associated [`JobResult`](../models/extras/jobresult.md) `data` field is available as `self.results`.
+An optional `grouping` and/or `object` may be provided in log messages by passing them in the log function call's `extra` kwarg. If a `grouping` is not provided it will default to the function name that logged the message. The `object` will default to `None`.
 
-### Logging
+!!! example
+    ```py
+    from nautobot.extras.jobs import BaseJob
 
-The following instance methods are available to log results from an executing job to be stored into [`JobLogEntry`](../models/extras/joblogentry.md) records associated with the current [`JobResult`](../models/extras/jobresult.md):
+    class MyJob(BaseJob):
+        def run(self):
+            logger.info("This job is running!", extra={"grouping": "myjobisrunning", "object": self.job_result})
+    ```
 
-* `self.log(message)`
-* `self.log_debug(message)`
-* `self.log_success(obj=None, message=None)`
-* `self.log_info(obj=None, message=None)`
-* `self.log_warning(obj=None, message=None)`
-* `self.log_failure(obj=None, message=None)`
+To skip writing a log entry to the database, set the `skip_db_logging` key in the "extra" kwarg to `True` when calling the log function. The output will still be written to the console.
 
-Messages recorded with `log()` or `log_debug()` will appear in a job's results but are never associated with a particular object; the other `log_*` functions may be invoked with or without a provided object to associate the message with.
+!!! example
+    ```py
+    from nautobot.extras.jobs import BaseJob
 
-It is advised to log a message for each object that is evaluated so that the results will reflect how many objects are being manipulated or reported on.
+    class MyJob(BaseJob):
+        def run(self):
+            logger.info("This job is running!", extra={"skip_db_logging": True})
+    ```
 
 Markdown rendering is supported for log messages.
 
 +/- 1.3.4
     As a security measure, the `message` passed to any of these methods will be passed through the `nautobot.core.utils.logging.sanitize()` function in an attempt to strip out information such as usernames/passwords that should not be saved to the logs. This is of course best-effort only, and Job authors should take pains to ensure that such information is not passed to the logging APIs in the first place. The set of redaction rules used by the `sanitize()` function can be configured as [settings.SANITIZER_PATTERNS](../configuration/optional-settings.md#sanitizer_patterns).
 
-!!! note
-    Using `self.log_failure()`, in addition to recording a log message, will flag the overall job as failed, but it will **not** stop the execution of the job, nor will it result in an automatic rollback of any database changes made by the job. To end a job early, you can use a Python `raise` or `return` as appropriate. Raising any exception (e.g. `ValueError` for malformed input values) will ensure that any database changes are rolled back as part of the process of ending the job. `AbortTransaction` from Nautobot, which was recommended in past versions of the docs, should explicitly **not** be used, as it is only intended for use by Nautobot's internal job handling.
++/- 2.0.0
+    The Job class logging functions (example: `self.log(message)`, `self.log_success(obj=None, message=message)`, etc) have been removed. Also, the convenience method to mark a job as failed, `log_failure()`, has been removed. To replace the functionality of this method, you can log an error message with `self.logger.error()` and then raise an exception to fail the job. Note that it is no longer possible to manually set the job result status as failed without raising an exception in the job.
 
 +/- 2.0.0
     The `AbortTransaction` class was moved from the `nautobot.utilities.exceptions` module to `nautobot.core.exceptions`.
 
-### Accessing Request Data
+### Marking a Job as Failed
+
+To mark a job as failed, raise an exception from within the `run()` method. The exception message will be logged to the traceback of the job result. The job result status will be set to `failed`. To output a job log message you can use the `self.logger.error()` method.
+
+```python
 
-Details of the current HTTP request (the one being made to execute the job) are available as the instance attribute `self.request`. This can be used to infer, for example, the user executing the job and their client IP address:
+As an example, the following job will fail if the user does not put the word "Taco" in `var1`:
 
 ```python
-username = self.request.user.username
-ip_address = self.request.META.get('HTTP_X_FORWARDED_FOR') or \
-    self.request.META.get('REMOTE_ADDR')
-self.log_info(f"Running as user {username} (IP: {ip_address})...")
+from nautobot.extras.jobs import Job, StringVar
+
+class MyJob(Job):
+    var1 = StringVar(...)
+
+    def run(self, var1):
+        if var1 != "Taco":
+            self.logger.error("var1 must be 'Taco'")
+            raise Exception("Argument input validation failed.")
 ```
 
-For a complete list of available request parameters, please see the [Django documentation](https://docs.djangoproject.com/en/stable/ref/request-response/).
+### Accessing User and Job Result
+
++/- 2.0.0
+    The web request is no longer accessible to running jobs.
+
+The user that initiated the job and the job result associated to the job can be accessed through properties on the job class:
+
+```py
+username = self.user.username
+job_result_id = self.job_result.id
+self.logger.info("Job %s initiated by user %s is running.", job_result_id, username)
+```
 
 ### Reading Data from Files
 
@@ -520,10 +548,9 @@ An administrator or user with `extras.change_job` permission can also edit a Job
 * `name`
 * `description`
 * `approval_required`
-* `commit_default`
+* `dryrun_default`
 * `has_sensitive_variables`
 * `hidden`
-* `read_only`
 * `soft_time_limit`
 * `time_limit`
 * `task_queues`
@@ -568,9 +595,12 @@ Once a job has been run, the latest [`JobResult`](../models/extras/jobresult.md)
 
 ### Via the API
 
-To run a job via the REST API, issue a POST request to the job's endpoint `/api/extras/jobs/<uuid>/run/`. You can optionally provide JSON data to set the `commit` flag, specify any required user input `data`, optional `task_queue`, and/or provide optional scheduling information as described in [the section on scheduling and approvals](./job-scheduling-and-approvals.md).
+--- 2.0.0
+    The `commit` parameter was removed. All job input should be provided via the `data` parameter.
 
-For example, to run a job with no user inputs and without committing any anything to the database:
+To run a job via the REST API, issue a POST request to the job's endpoint `/api/extras/jobs/<uuid>/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](./job-scheduling-and-approvals.md).
+
+For example, to run a job with no user inputs:
 
 ```no-highlight
 curl -X POST \
@@ -580,7 +610,7 @@ curl -X POST \
 http://nautobot/api/extras/jobs/$JOB_ID/run/
 ```
 
-Or to run a job that expects user inputs, and commit changes to the database:
+Or to run a job that expects user inputs:
 
 ```no-highlight
 curl -X POST \
@@ -588,7 +618,7 @@ curl -X POST \
 -H "Content-Type: application/json" \
 -H "Accept: application/json; version=1.3; indent=4" \
 http://nautobot/api/extras/jobs/$JOB_ID/run/ \
---data '{"data": {"string_variable": "somevalue", "integer_variable": 123}, "commit": true}'
+--data '{"data": {"string_variable": "somevalue", "integer_variable": 123}}'
 ```
 
 When providing input data, it is possible to specify complex values contained in `ObjectVar`s, `MultiObjectVar`s, and `IPAddressVar`s.
@@ -599,7 +629,7 @@ When providing input data, it is possible to specify complex values contained in
 
 #### 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 `commit`, `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.
+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:
 
@@ -609,7 +639,6 @@ curl -X POST \
 -H 'Content-Type: multipart/form-data' \
 -H "Accept: application/json; version=1.3; indent=4" \
 'http://nautobot/api/extras/jobs/$JOB_ID/run/' \
--F '_commit="true"' \
 -F '_schedule_interval="immediately"' \
 -F '_schedule_start_time="2022-10-18T17:31:23.698Z"' \
 -F 'interval="3"' \
@@ -621,7 +650,7 @@ curl -X POST \
 Jobs can be run from the CLI by invoking the management command:
 
 ```no-highlight
-nautobot-server runjob [--username <username>] [--commit] [--local] [--data <data>] <class_path>
+nautobot-server runjob [--username <username>] [--local] [--data <data>] <class_path>
 ```
 
 !!! note
@@ -639,7 +668,7 @@ nautobot-server runjob --username myusername local/example/MyJobWithNoVars
 ```
 
 !!! warning
-    The `--username <username>` parameter can be used to specify the user that will be identified as the requester of the job. It is optional if the job will not be modifying the database, but is mandatory if you are running with `--commit`, as the specified user will own any resulting database changes.
+    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.
 
@@ -651,12 +680,12 @@ While individual methods within your Job can and should be tested in isolation,
 
 ### Nautobot 1.3.3 and later
 
-The simplest way to test the entire execution of Jobs from 1.3.3 on is via calling the `nautobot.core.testing.run_job_for_testing()` method, which is a helper wrapper around the `run_job` function used to execute a Job via Nautobot's Celery worker process.
+The simplest way to test the entire execution of Jobs from 1.3.3 on is via calling the `nautobot.core.testing.run_job_for_testing()` method, which is a helper wrapper around the `JobResult.enqueue_job` function used to execute a Job via Nautobot's Celery worker process.
 
 +/- 2.0.0
     `run_job_for_testing` was moved from the `nautobot.utilities.testing` module to `nautobot.core.testing`.
 
-Because of the way `run_job_for_testing` and more specifically `run_job()` works, which is somewhat complex behind the scenes, you need to inherit from `nautobot.core.testing.TransactionTestCase` instead of `django.test.TestCase` (Refer to the [Django documentation](https://docs.djangoproject.com/en/stable/topics/testing/tools/#provided-test-case-classes) if you're interested in the differences between these classes - `TransactionTestCase` from Nautobot is a small wrapper around Django's `TransactionTestCase`).
+Because of the way `run_job_for_testing` and more specifically Celery tasks work, which is somewhat complex behind the scenes, you need to inherit from `nautobot.core.testing.TransactionTestCase` instead of `django.test.TestCase` (Refer to the [Django documentation](https://docs.djangoproject.com/en/stable/topics/testing/tools/#provided-test-case-classes) if you're interested in the differences between these classes - `TransactionTestCase` from Nautobot is a small wrapper around Django's `TransactionTestCase`).
 
 When using `TransactionTestCase` (whether from Django or from Nautobot) each tests runs on a completely empty database. Furthermore, Nautobot requires new jobs to be enabled before they can run. Therefore, we need to make sure the job is enabled before each run which `run_job_for_testing` handles for us.
 
@@ -672,85 +701,48 @@ class MyJobTestCase(TransactionTestCase):
         # Testing of Job "MyJob" in file "my_job_file.py" in $JOBS_ROOT
         job = Job.objects.get(job_class_name="MyJob", module_name="my_job_file", source="local")
         # or, job = Job.objects.get_for_class_path("local/my_job_file/MyJob")
-        job_result = run_job_for_testing(job, data={}, commit=False)
+        job_result = run_job_for_testing(job, var1="abc", var2=123)
 
-        # Since we ran with commit=False, any database changes made by the job won't persist,
-        # but we can still inspect the logs created by running the job
+        # Inspect the logs created by running the job
         log_entries = JobLogEntry.objects.filter(job_result=job_result)
         for log_entry in log_entries:
             self.assertEqual(log_entry.message, "...")
 ```
 
 !!! tip
-    For more advanced examples (such as testing jobs executed with `commit=True`, for example) refer to the Nautobot source code, specifically `nautobot/extras/tests/test_jobs.py`.
-
-### Nautobot 1.3.2 and earlier (including 1.2)
+    For more advanced examples refer to the Nautobot source code, specifically `nautobot/extras/tests/test_jobs.py`.
 
-If your test case needs to be backwards-compatible with test execution against Nautobot 1.3.2 and/or earlier, you need to handle a couple more things manually:
+## Debugging job performance
 
-Set up the `"job_logs"` database correctly for testing:
++++ 1.5.17
 
-```python
-from django.conf import settings
-
-if "job_logs" in settings.DATABASES:
-    settings.DATABASES["job_logs"] = settings.DATABASES["job_logs"].copy()
-    settings.DATABASES["job_logs"]["TEST"] = {"MIRROR": "default"}
-```
+Debugging the performance of Nautobot jobs can be tricky, because they are executed in the worker context. In order to gain extra visibility, [cProfile](https://docs.python.org/3/library/profile.html) can be used to profile the job execution.
 
-Replicate the behavior of `run_job_for_testing` manually so that your test execution most closely resembles the way the celery worker would run the test:
+The 'profile' form field on jobs is automatically available when the `DEBUG` settings is `True`. When you select that checkbox, a profiling report in the pstats format will be written to the file system of the environment where the job runs. Normally, this is on the file system of the worker process, but if you are using the `nautobot-server runjob` command with `--local`, it will end up in the file system of the web application itself. The path of the written file will be logged in the job.
 
-```python
-import uuid
-from django.contrib.auth import get_user_model
-from django.contrib.contenttypes.models import ContentType
+!!! note
+    If you need to run this in an environment where `DEBUG` is `False`, you have the option of using `nautobot-server runjob` with the `--profile` flag. According to the docs, `cProfile` should have minimal impact on the performance of the job; still, proceed with caution when using this in a production environment.
 
-from nautobot.extras.context_managers import web_request_context
-from nautobot.extras.jobs import run_job
-from nautobot.extras.models import JobResult, Job
-
-def run_job_for_testing(job, data=None, commit=True, username="test-user"):
-    if data is None:
-        data = {}
-    user_model = get_user_model()
-    user, _ = user_model.objects.get_or_create(username=username, is_superuser=True, password="password")
-    job_result = JobResult.objects.create(
-        name=job.class_path,
-        obj_type=ContentType.objects.get_for_model(Job),
-        user=user,
-        task_id=uuid.uuid4(),
-    )
-    with web_request_context(user=user) as request:
-        run_job(data=data, request=request, commit=commit, job_result_pk=job_result.pk)
-    return job_result
-```
+### Reading profiling reports
 
-Setup the `databases` field on the test class correctly, and re-create the default Statuses on `setUp` in your test classes, because `django.test.TransactionTestCase` truncates them on every `tearDown`:
+A full description on how to deal with the output of `cProfile` can be found in the [Instant User's Manual](https://docs.python.org/3/library/profile.html#instant-user-s-manual), but here is something to get you started:
 
 ```python
-from django.apps import apps
-from django.conf import settings
-from django.test import TransactionTestCase
-
-from nautobot.extras.management import populate_status_choices
-
-class MyJobTestCase(TransactionTestCase):
-    # 'job_logs' is a proxy connection to the same (default) database that's used exclusively for Job logging
-    if "job_logs" in settings.DATABASES:
-        databases = ("default", "job_logs")
-
-    def setUp(self):
-        super().setUp()
-        populate_status_choices(apps, None)
+import pstats
+job_result_uuid = "66b70231-002f-412b-8cc4-1cc9609c2c9b"
+stats = pstats.Stats(f"/tmp/job-result-{job_result_uuid}.pstats")
+stats.sort_stats(pstats.SortKey.CUMULATIVE).print_stats(10)
 ```
 
+This will print the 10 functions that the job execution spent the most time in - adapt this to your needs!
+
 ## Example Jobs
 
-### Creating objects for a planned site
+### Creating objects for a planned location
 
 This job prompts the user for three variables:
 
-* The name of the new site
+* The name of the new location
 * The device model (a filtered list of defined device types)
 * The number of access switches to create
 
@@ -758,78 +750,60 @@ These variables are presented as a web form to be completed by the user. Once su
 
 ```python
 from django.contrib.contenttypes.models import ContentType
-from django.utils.text import slugify
 
-from nautobot.dcim.models import Device, DeviceType, Manufacturer, Site
-from nautobot.extras.models import Role, Status
-from nautobot.extras.jobs import *
+from nautobot.dcim.models import Location, LocationType, Device, Manufacturer, DeviceType
+from nautobot.extras.models import Status, Role
+from nautobot.extras.jobs import Job, StringVar, IntegerVar, ObjectVar
 
 
 class NewBranch(Job):
-
     class Meta:
         name = "New Branch"
-        description = "Provision a new branch site"
-        field_order = ['site_name', 'switch_count', 'switch_model']
+        description = "Provision a new branch location"
+        field_order = ["location_name", "switch_count", "switch_model"]
 
-    site_name = StringVar(
-        description="Name of the new site"
-    )
-    switch_count = IntegerVar(
-        description="Number of access switches to create"
-    )
-    manufacturer = ObjectVar(
-        model=Manufacturer,
-        required=False
-    )
+    location_name = StringVar(description="Name of the new location")
+    switch_count = IntegerVar(description="Number of access switches to create")
+    manufacturer = ObjectVar(model=Manufacturer, required=False)
     switch_model = ObjectVar(
-        description="Access switch model",
-        model=DeviceType,
-        query_params={
-            'manufacturer_id': '$manufacturer'
-        }
+        description="Access switch model", model=DeviceType, query_params={"manufacturer_id": "$manufacturer"}
     )
 
-    def run(self, data, commit):
-        STATUS_PLANNED = Status.objects.get(name='Planned')
+    def run(self, location_name, switch_count, switch_model):
+        STATUS_PLANNED = Status.objects.get(name="Planned")
 
-        # Create the new site
-        site = Site(
-            name=data['site_name'],
-            slug=slugify(data['site_name']),
+        # Create the new location
+        root_type = LocationType.objects.get_or_create(name="Campus")
+        location = Location(
+            name=location_name,
+            location_type=root_type,
             status=STATUS_PLANNED,
         )
-        site.validated_save()
-        self.log_success(obj=site, message="Created new site")
+        location.validated_save()
+        self.logger.info("Created new location", extra={"object": location})
 
         # Create access switches
         device_ct = ContentType.objects.get_for_model(Device)
-        switch_role = Role.objects.get(name='Access Switch')
+        switch_role = Role.objects.get(name="Access Switch")
         switch_role.content_types.add(device_ct)
-        for i in range(1, data['switch_count'] + 1):
+        for i in range(1, switch_count + 1):
             switch = Device(
-                device_type=data['switch_model'],
-                name=f'{site.slug}-switch{i}',
-                site=site,
+                device_type=switch_model,
+                name=f"{location.name}-switch{i}",
+                location=location,
                 status=STATUS_PLANNED,
-                role=switch_role
+                role=switch_role,
             )
             switch.validated_save()
-            self.log_success(obj=switch, message="Created new switch")
+            self.logger.info("Created new switch", extra={"object": switch})
 
         # Generate a CSV table of new devices
-        output = [
-            'name,make,model'
-        ]
-        for switch in Device.objects.filter(site=site):
-            attrs = [
-                switch.name,
-                switch.device_type.manufacturer.name,
-                switch.device_type.model
-            ]
-            output.append(','.join(attrs))
-
-        return '\n'.join(output)
+        output = ["name,make,model"]
+        for switch in Device.objects.filter(location=location):
+            attrs = [switch.name, switch.device_type.manufacturer.name, switch.device_type.model]
+            output.append(",".join(attrs))
+
+        return "\n".join(output)
 ```
 
 ### Device validation
@@ -849,19 +823,25 @@ class DeviceConnectionsReport(Job):
         STATUS_ACTIVE = Status.objects.get(name='Active')
 
         # Check that every console port for every active device has a connection defined.
-        for console_port in ConsolePort.objects.prefetch_related('device').filter(device__status=STATUS_ACTIVE):
+        for console_port in ConsolePort.objects.select_related('device').filter(device__status=STATUS_ACTIVE):
             if console_port.connected_endpoint is None:
-                self.log_failure(
-                    obj=console_port.device,
-                    message="No console connection defined for {}".format(console_port.name)
+                self.logger.error(
+                    "No console connection defined for %s",
+                    console_port.name,
+                    extra={"object": console_port.device},
                 )
             elif not console_port.connection_status:
-                self.log_warning(
-                    obj=console_port.device,
-                    message="Console connection for {} marked as planned".format(console_port.name)
+                self.logger.warning(
+                    "Console connection for %s marked as planned",
+                    console_port.name,
+                    extra={"object": console_port.device},
                 )
             else:
-                self.log_success(obj=console_port.device)
+                self.logger.info(
+                    "Console port %s has a connection defined",
+                    console_port.name,
+                    extra={"object": console_port.device},
+                )
 
     def test_power_connections(self):
         STATUS_ACTIVE = Status.objects.get(name='Active')
@@ -873,15 +853,17 @@ class DeviceConnectionsReport(Job):
                 if power_port.connected_endpoint is not None:
                     connected_ports += 1
                     if not power_port.connection_status:
-                        self.log_warning(
-                            obj=device,
-                            message="Power connection for {} marked as planned".format(power_port.name)
+                        self.logger.warning(
+                            "Power connection for %s marked as planned",
+                            power_port.name,
+                            extra={"object": device},
                         )
             if connected_ports < 2:
-                self.log_failure(
-                    obj=device,
-                    message="{} connected power supplies found (2 needed)".format(connected_ports)
+                self.logger.error(
+                    "%s connected power supplies found (2 needed)",
+                    connected_ports,
+                    extra={"object": device},
                 )
             else:
-                self.log_success(obj=device)
+                self.logger.info("At least two connected power supplies found", extra={"object": device})
 ```