nautobot 2.4.0b1__py3-none-any.whl → 2.4.1__py3-none-any.whl

nautobot/project-static/docs/development/jobs/index.html

@@ -18,7 +18,7 @@
       
       
       <link rel="icon" href="../../assets/favicon.ico">
-      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.5.46">
+      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.5.49">
     
     
       
@@ -2112,6 +2112,27 @@
 
               
             
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../user-guide/feature-guides/wireless-networks-and-controllers.html" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Wireless Networks and Controllers
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
           </ul>
         </nav>
       
@@ -5131,6 +5152,27 @@
   
   
   
+    <li class="md-nav__item">
+      <a href="../../user-guide/platform-functionality/jobs/kubernetes-job-support.html" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Kubernetes Job Support
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
     <li class="md-nav__item">
       <a href="../../user-guide/platform-functionality/jobs/jobbutton.html" class="md-nav__link">
         
@@ -8062,11 +8104,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../core/local-k8s.html" class="md-nav__link">
+      <a href="../core/minikube-dev-environment-for-k8s-jobs.html" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Local Kubernetes Cluster
+    Minikube Dev Environment for K8s Jobs
   </span>
   
 
@@ -9010,6 +9052,15 @@
     <nav class="md-nav" aria-label="Writing Jobs">
       <ul class="md-nav__list">
         
+          <li class="md-nav__item">
+  <a href="#introduction-to-writing-jobs" class="md-nav__link">
+    <span class="md-ellipsis">
+      Introduction to Writing Jobs
+    </span>
+  </a>
+  
+</li>
+        
           <li class="md-nav__item">
   <a href="#job-registration" class="md-nav__link">
     <span class="md-ellipsis">
@@ -9147,6 +9198,15 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#is_singleton" class="md-nav__link">
+    <span class="md-ellipsis">
+      is_singleton
+    </span>
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
@@ -9471,11 +9531,11 @@
         <li class="md-nav__item">
   <a href="#debugging-job-performance" class="md-nav__link">
     <span class="md-ellipsis">
-      Debugging job performance
+      Debugging Job Performance
     </span>
   </a>
   
-    <nav class="md-nav" aria-label="Debugging job performance">
+    <nav class="md-nav" aria-label="Debugging Job Performance">
       <ul class="md-nav__list">
         
           <li class="md-nav__item">
@@ -9502,6 +9562,15 @@
     <nav class="md-nav" aria-label="Example Jobs">
       <ul class="md-nav__list">
         
+          <li class="md-nav__item">
+  <a href="#example-everything-job" class="md-nav__link">
+    <span class="md-ellipsis">
+      Example "Everything" Job
+    </span>
+  </a>
+  
+</li>
+        
           <li class="md-nav__item">
   <a href="#creating-objects-for-a-planned-location" class="md-nav__link">
     <span class="md-ellipsis">
@@ -9620,30 +9689,24 @@
 
 <h1 id="jobs">Jobs<a class="headerlink" href="#jobs" title="Permanent link">&para;</a></h1>
 <p>Familiarity with the basic concepts of <a href="../../user-guide/platform-functionality/jobs/index.html">Jobs</a>, especially the distinction between Job classes (Python code) and Job records (Nautobot database records), is recommended before authoring your first Job.</p>
-<div class="admonition tip">
-<p class="admonition-title">Tip</p>
+<details class="tip">
+<summary>More about Job class source code loading</summary>
 <p>From a development standpoint, it's especially important to understand that the Job database record never stores the Job class code. It only describes the <strong>existence</strong> of a Job class. The actual Job class source code is loaded into memory only.</p>
-</div>
-<div class="admonition info">
-<p class="admonition-title">Info</p>
 <p>As an implementation detail in Nautobot 2.2.3 and later, all known Job <strong>classes</strong> are cached in the <a href="../core/application-registry.html#jobs">application registry</a>, which is refreshed at various times including Nautobot application startup and immediately prior to actually executing any given Job by a worker. This implementation detail should not be relied on directly; instead you should always use the <code>get_job()</code> and/or <code>get_jobs()</code> APIs to obtain a Job class when needed.</p>
-</div>
-<h2 id="migrating-jobs-from-v1-to-v2">Migrating Jobs from v1 to v2<a class="headerlink" href="#migrating-jobs-from-v1-to-v2" title="Permanent link">&para;</a></h2>
-<details class="version-changed">
-<summary>Changed in version 2.0.0</summary>
-<p>See <a href="migration/from-v1.html">Migrating Jobs From Nautobot v1</a> for more information on how to migrate your existing jobs to Nautobot v2.</p>
 </details>
+<h2 id="migrating-jobs-from-v1-to-v2">Migrating Jobs from v1 to v2<a class="headerlink" href="#migrating-jobs-from-v1-to-v2" title="Permanent link">&para;</a></h2>
+<p>See <a href="migration/from-v1.html">Migrating Jobs From Nautobot v1</a> for more information on how to migrate your existing Jobs to Nautobot v2.</p>
 <h2 id="installing-jobs">Installing Jobs<a class="headerlink" href="#installing-jobs" title="Permanent link">&para;</a></h2>
 <p>Jobs may be installed in one of three ways:</p>
 <ul>
 <li>Manually installed as files in the <a href="../../user-guide/administration/configuration/settings.html#jobs_root"><code>JOBS_ROOT</code></a> path (which defaults to <code>$NAUTOBOT_ROOT/jobs/</code>).<ul>
-<li>Python files and subdirectories containing Python files will be dynamically loaded at Nautobot startup in order to discover and register available Job classes. For example, a job class named <code>MyJobClass</code> in <code>$JOBS_ROOT/my_job.py</code> will be loaded into Nautobot as <code>my_job.MyJobClass</code>.</li>
+<li>Python files and subdirectories containing Python files will be dynamically loaded at Nautobot startup in order to discover and register available Job classes. For example, a Job class named <code>MyJobClass</code> in <code>$JOBS_ROOT/my_job.py</code> will be loaded into Nautobot as <code>my_job.MyJobClass</code>.</li>
 <li>All Python modules in this directory are imported by Nautobot and all worker processes at startup. If you have a <code>custom_jobs.py</code> and a <code>custom_jobs_module/__init__.py</code> file in your <code>JOBS_ROOT</code>, both of these files will be imported at startup.</li>
 </ul>
 </li>
 <li>Imported from an external <a href="../../user-guide/platform-functionality/gitrepository.html#jobs">Git repository</a>.<ul>
-<li>Git repositories are loaded into the module namespace of the <code>GitRepository.slug</code> value at startup. For example, if your <code>slug</code> value is <code>my_git_jobs</code> your jobs will be loaded into Python as <code>my_git_jobs.jobs.MyJobClass</code>.</li>
-<li>All git repositories providing jobs must include a <code>__init__.py</code> file at the root of the repository.</li>
+<li>Git repositories are loaded into the module namespace of the <code>GitRepository.slug</code> value at startup. For example, if your <code>slug</code> value is <code>my_git_jobs</code> your Jobs will be loaded into Python as <code>my_git_jobs.jobs.MyJobClass</code>.</li>
+<li>All git repositories providing Jobs must include a <code>__init__.py</code> file at the root of the repository.</li>
 <li>Nautobot and all worker processes will import the git repository's <code>jobs</code> module at startup so a <code>jobs.py</code> or <code>jobs/__init__.py</code> file must exist in the root of the repository.</li>
 </ul>
 </li>
@@ -9652,50 +9715,59 @@
 </ul>
 </li>
 </ul>
-<p>In any case, each module holds one or more Job classes (Python classes), each of which serves a specific purpose. The logic of each job can be split into a number of distinct methods, each of which performs a discrete portion of the overall job logic.</p>
-<p>For example, we can create a module named <code>devices.py</code> 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 <code>nautobot.apps.jobs.Job</code>, which provides the base functionality needed to accept user input and log activity.</p>
+<p>In any case, each module holds one or more Job classes (Python classes), each of which serves a specific purpose. The logic of each Job can be split into a number of distinct methods, each of which performs a discrete portion of the overall Job logic.</p>
+<p>For example, we can create a module named <code>device_jobs.py</code> 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 <code>nautobot.apps.jobs.Job</code>, which provides the base functionality needed to accept user input and log activity.</p>
 <details class="version-changed">
-<summary>Changed in version 2.0.0</summary>
-<p>All job classes that are intended to be runnable must now be registered by a call to <code>nautobot.apps.jobs.register_jobs()</code> on module import. This allows for a module to, if desired, define "abstract" base Job classes that are defined in code but are not registered (and therefore are not runnable in Nautobot). The <code>register_jobs</code> method accepts one or more job classes as arguments.</p>
+<summary>Changed in version 2.0.0 — <code>register_jobs()</code> must be called</summary>
+<p>All Job classes that are intended to be runnable must now be registered by a call to <code>nautobot.apps.jobs.register_jobs()</code> on module import. This allows for a module to, if desired, define "abstract" base Job classes that are defined in code but are not registered (and therefore are not runnable in Nautobot). The <code>register_jobs</code> method accepts one or more Job classes as arguments.</p>
 </details>
 <h2 id="writing-jobs">Writing Jobs<a class="headerlink" href="#writing-jobs" title="Permanent link">&para;</a></h2>
+<h3 id="introduction-to-writing-jobs">Introduction to Writing Jobs<a class="headerlink" href="#introduction-to-writing-jobs" title="Permanent link">&para;</a></h3>
 <div class="admonition warning">
 <p class="admonition-title">Warning</p>
-<p>Make sure your Job subclasses inherit from <code>nautobot.apps.Job</code> and <em>not</em> from <code>nautobot.extras.models.Job</code> instead; if you mistakenly inherit from the latter, Django will think you want to define a new database model.</p>
+<p>Make sure your Job subclasses inherit from <code>nautobot.apps.jobs.Job</code> and <em>not</em> from <code>nautobot.extras.models.Job</code> instead; if you mistakenly inherit from the latter, Django will think you want to define a new database model!</p>
 </div>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span> <span class="nn">nautobot.apps.jobs</span> <span class="kn">import</span> <span class="n">Job</span><span class="p">,</span> <span class="n">register_jobs</span>
+<p>The most basic structure of a Python file providing one or more Jobs is as follows:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span> <span class="nn">nautobot.apps</span> <span class="kn">import</span> <span class="n">jobs</span>
 <a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="k">class</span> <span class="nc">CreateDevices</span><span class="p">(</span><span class="n">Job</span><span class="p">):</span>
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>    <span class="o">...</span>
-<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>
-<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="k">class</span> <span class="nc">DeviceConnectionsReport</span><span class="p">(</span><span class="n">Job</span><span class="p">):</span>
-<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>    <span class="o">...</span>
-<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>
-<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a><span class="k">class</span> <span class="nc">DeviceIPsReport</span><span class="p">(</span><span class="n">Job</span><span class="p">):</span>
-<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>    <span class="o">...</span>
-<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>
-<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a><span class="n">register_jobs</span><span class="p">(</span><span class="n">CreateDevices</span><span class="p">,</span> <span class="n">DeviceConnectionsReport</span><span class="p">,</span> <span class="n">DeviceIPsReport</span><span class="p">)</span>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="n">name</span> <span class="o">=</span> <span class="s2">&quot;My Group Of Jobs&quot;</span>  <span class="c1"># optional, but recommended to define a grouping name</span>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="k">class</span> <span class="nc">MyNewJob</span><span class="p">(</span><span class="n">jobs</span><span class="o">.</span><span class="n">Job</span><span class="p">):</span>
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>    <span class="k">class</span> <span class="nc">Meta</span><span class="p">:</span>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>        <span class="c1"># metadata attributes go here</span>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>        <span class="n">name</span> <span class="o">=</span> <span class="s2">&quot;My New Job&quot;</span>
+<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>        <span class="c1"># ... etc.</span>
+<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>
+<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>    <span class="c1"># input variable definitions go here</span>
+<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>    <span class="n">some_text_input</span> <span class="o">=</span> <span class="n">jobs</span><span class="o">.</span><span class="n">StringVar</span><span class="p">(</span><span class="o">...</span><span class="p">)</span>
+<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="c1"># ... etc.</span>
+<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>
+<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>    <span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">some_text_input</span><span class="p">,</span> <span class="o">...</span><span class="p">):</span>
+<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>        <span class="c1"># code to execute when the Job is run goes here</span>
+<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>        <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s2">&quot;some_text_input: </span><span class="si">%s</span><span class="s2">&quot;</span><span class="p">,</span> <span class="n">some_text_input</span><span class="p">)</span>
+<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>
+<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a><span class="n">jobs</span><span class="o">.</span><span class="n">register_jobs</span><span class="p">(</span><span class="n">MyNewJob</span><span class="p">)</span>
 </code></pre></div>
-<p>Each job class will implement some or all of the following components:</p>
+<p>Each Job class will implement some or all of the following components:</p>
 <ul>
-<li>Module and class attributes, providing for default behavior, documentation and discoverability</li>
-<li>a set of variables for user input via the Nautobot UI (if your job requires any user inputs)</li>
-<li>a <code>run()</code> method, which is the only required attribute on a Job class and receives the user input values, if any, as keyword arguments.</li>
-<li>Optionally, any of the special methods <code>before_start()</code>, <code>on_success()</code>, <code>on_failure()</code>, and/or <code>after_return()</code> (more on these later).</li>
+<li><a href="#module-metadata-attributes">Module</a> and class <a href="#class-metadata-attributes">metadata attributes</a>, configuring the system-level behavior of the Job and providing for documentation and discoverability by users.</li>
+<li>A set of <a href="#variables">variables</a> for user input via the Nautobot UI or API.</li>
+<li>The <a href="#the-run-method"><code>run()</code> method</a>, which is the only <strong>required</strong> attribute on a Job class and receives the user input values as keyword arguments.</li>
+<li>Optionally, any of the special methods <a href="#the-before_start-method"><code>before_start()</code></a>, <a href="#the-on_success-method"><code>on_success()</code></a>, <a href="#the-on_failure-method"><code>on_failure()</code></a>, and/or <a href="#the-after_return-method"><code>after_return()</code></a>.</li>
 </ul>
-<p>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 <a href="../../user-guide/platform-functionality/jobs/models.html#job-results"><code>JobResult</code></a> records and creating <a href="../../user-guide/platform-functionality/jobs/models.html#job-log-entry"><code>JobLogEntry</code></a> records.</p>
+<p>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 <a href="../../user-guide/platform-functionality/jobs/models.html#job-results"><code>JobResult</code></a> records and creating <a href="../../user-guide/platform-functionality/jobs/models.html#job-log-entry"><code>JobLogEntry</code></a> records.</p>
 <div class="admonition note">
-<p class="admonition-title">Note</p>
+<p class="admonition-title">About detection of changes while developing a Job</p>
 <p>When actively developing a Job utilizing a development environment it's important to understand that the "automatically reload when code changes are detected" debugging functionality provided by <code>nautobot-server runserver</code> does <strong>not</strong> automatically restart the Celery <code>worker</code> process when code changes are made; therefore, it is required to restart the <code>worker</code> after each update to your Job source code or else it will continue to run the version of the Job code that was present when it first started. In the Nautobot core development environment, we use <code>watchmedo auto-restart</code> as a helper tool to auto-restart the workers as well on code changes; you may wish to configure your local development environment similarly for convenience.</p>
 <p>Additionally, as of Nautobot 1.3, the Job database records corresponding to installed Jobs are <em>not</em> automatically refreshed when the development server auto-restarts. If you make changes to any of the class and module metadata attributes described in the following sections, the database will be refreshed to reflect these changes only after running <code>nautobot-server migrate</code> or <code>nautobot-server post_upgrade</code> (recommended) or if you manually edit a Job database record to force it to be refreshed. The exception here is Git-repository-provided Jobs; resyncing the Git repository through Nautobot will also trigger a refresh of the Job records corresponding to this repository's contents.</p>
 </div>
 <h3 id="job-registration">Job Registration<a class="headerlink" href="#job-registration" title="Permanent link">&para;</a></h3>
 <details class="version-changed">
-<summary>Changed in version 2.0.0</summary>
+<summary>Changed in version 2.0.0 — <code>register_jobs()</code> is now required</summary>
 </details>
-<p>All Job classes, including <code>JobHookReceiver</code> and <code>JobButtonReceiver</code> classes must be registered at <strong>import time</strong> using the <code>nautobot.apps.jobs.register_jobs</code> method. This method accepts one or more job classes as arguments. You must account for how your jobs are imported when deciding where to call this method.</p>
+<p>All Job classes, including <code>JobHookReceiver</code> and <code>JobButtonReceiver</code> classes must be registered at <strong>import time</strong> using the <code>nautobot.apps.jobs.register_jobs</code> method. This method accepts one or more Job classes as arguments. You must account for how your Jobs are imported when deciding where to call this method.</p>
 <h4 id="registering-jobs-in-jobs_root-or-git-repositories">Registering Jobs in <code>JOBS_ROOT</code> or Git Repositories<a class="headerlink" href="#registering-jobs-in-jobs_root-or-git-repositories" title="Permanent link">&para;</a></h4>
-<p>Only top level module names within <code>JOBS_ROOT</code> are imported by Nautobot at runtime. This means that if you're using submodules, you need to ensure that your jobs are either registered in your top level <code>__init__.py</code> or that this file imports your submodules where the jobs are registered:</p>
+<p>Only top level module names within <code>JOBS_ROOT</code> are imported by Nautobot at runtime. This means that if you're using submodules, you need to ensure that your Jobs are either registered in your top level <code>__init__.py</code> or that this file imports your submodules where the Jobs are registered:</p>
 <div class="highlight"><span class="filename">$JOBS_ROOT/my_jobs/__init__.py</span><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="kn">from</span> <span class="nn">.</span> <span class="kn">import</span> <span class="n">my_job_module</span>
 </code></pre></div>
 <div class="highlight"><span class="filename">$JOBS_ROOT/my_jobs/my_job_module.py</span><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="kn">from</span> <span class="nn">nautobot.apps.jobs</span> <span class="kn">import</span> <span class="n">Job</span><span class="p">,</span> <span class="n">register_jobs</span>
@@ -9705,12 +9777,12 @@
 <a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a>
 <a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a><span class="n">register_jobs</span><span class="p">(</span><span class="n">MyJob</span><span class="p">)</span>
 </code></pre></div>
-<p>Similarly, only the <code>jobs</code> module is loaded from Git repositories. If you're using submodules, you need to ensure that your jobs are either registered in the repository's <code>jobs/__init__.py</code> or that this file imports your submodules where the jobs are registered.</p>
-<p>If not using submodules, you should register your job in the file where your job is defined.</p>
-<p>Examples of the different directory structures when registering jobs in Git repositories:</p>
+<p>Similarly, only the <code>jobs</code> module is loaded from Git repositories. If you're using submodules, you need to ensure that your Jobs are either registered in the repository's <code>jobs/__init__.py</code> or that this file imports your submodules where the Jobs are registered.</p>
+<p>If not using submodules, you should register your Job in the file where it is defined.</p>
+<p>Examples of the different directory structures when registering Jobs in Git repositories:</p>
 <div class="admonition note">
-<p class="admonition-title">Note</p>
-<p>Take note of the <code>__init__.py</code> at the root of the repository.  This is required to register jobs in a Git repository.</p>
+<p class="admonition-title"><code>__init__.py</code></p>
+<p>Take note of the <code>__init__.py</code> at the root of the repository.  This is required to register Jobs in a Git repository.</p>
 </div>
 <div class="highlight"><span class="filename">jobs.py</span><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>.
 <a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a>├── __init__.py
@@ -9723,14 +9795,14 @@
 <a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a>    └── my_job_module.py
 </code></pre></div>
 <h4 id="registering-jobs-in-an-app">Registering Jobs in an App<a class="headerlink" href="#registering-jobs-in-an-app" title="Permanent link">&para;</a></h4>
-<p>Apps should register jobs in the module defined in their <a href="../apps/api/nautobot-app-config.html#nautobotappconfig-code-location-attributes"><code>NautobotAppConfig.jobs</code></a> property. This defaults to the <code>jobs</code> module of the App.</p>
+<p>Apps should register Jobs in the module defined in their <a href="../apps/api/nautobot-app-config.html#nautobotappconfig-code-location-attributes"><code>NautobotAppConfig.jobs</code></a> property. This defaults to the <code>jobs</code> module of the App.</p>
 <h3 id="reserved-attribute-names">Reserved Attribute Names<a class="headerlink" href="#reserved-attribute-names" title="Permanent link">&para;</a></h3>
 <p>There are many attributes and methods of the Job class that serve as reserved names. You must be careful when implementing custom methods or defining the user input <a href="#variables">variables</a> for your Job that you do not inadvertently "step on" one of these reserved attributes causing unexpected behavior or errors.</p>
 <div class="admonition example">
 <p class="admonition-title">Example</p>
 <p>One classic pitfall here is the the reserved <code>name</code> metadata attribute - if you attempt to redefine <code>name</code> as a user input variable, your Job will not work.</p>
 </div>
-<p>As of Nautobot 2.2.3, the current list of reserved names (not including low-level Python built-ins such as <code>__dict__</code> or <code>__str__</code> includes:</p>
+<p>As of Nautobot 2.4.0, the current list of reserved names (not including low-level Python built-ins such as <code>__dict__</code> or <code>__str__</code> includes:</p>
 <table>
 <thead>
 <tr>
@@ -9816,6 +9888,10 @@
 <td><a href="#hidden">metadata property</a></td>
 </tr>
 <tr>
+<td><code>is_singleton</code></td>
+<td><a href="#is_singleton">metadata property</a></td>
+</tr>
+<tr>
 <td><code>job_model</code></td>
 <td>property</td>
 </tr>
@@ -9903,21 +9979,21 @@
 </table>
 <h3 id="module-metadata-attributes">Module Metadata Attributes<a class="headerlink" href="#module-metadata-attributes" title="Permanent link">&para;</a></h3>
 <h4 id="name-grouping"><code>name</code> (Grouping)<a class="headerlink" href="#name-grouping" title="Permanent link">&para;</a></h4>
-<p>You can define a global constant called <code>name</code> within a job module (the Python file which contains one or more job classes) to set the default grouping under which jobs in this module will be displayed in the Nautobot UI. If this value is not defined, the module's file name will be used. This "grouping" value may also be defined or overridden when editing Job records in the database.</p>
+<p>You can define a global constant called <code>name</code> within a job module (the Python file which contains one or more Job classes) to set the default grouping under which the Jobs in this module will be displayed in the Nautobot UI. If this value is not defined, the module's file name will be used. This "grouping" value may also be defined or overridden when editing Job records in the database.</p>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
 <p>In some UI elements and API endpoints, the module file name is displayed in addition to or in place of this attribute, so even if defining this attribute, you should still choose an appropriately explanatory file name as well.</p>
 </div>
 <h3 id="class-metadata-attributes">Class Metadata Attributes<a class="headerlink" href="#class-metadata-attributes" title="Permanent link">&para;</a></h3>
-<p>Job-specific attributes may be defined under a class named <code>Meta</code> within each job class you implement. All of these are optional, but encouraged.</p>
+<p>Job-specific attributes may be defined under a class named <code>Meta</code> within each Job class you implement. All of these are optional, but encouraged.</p>
 <h4 id="name"><code>name</code><a class="headerlink" href="#name" title="Permanent link">&para;</a></h4>
-<p>This is the human-friendly name of your job, as will be displayed in the Nautobot UI. If not set, the class name will be used.</p>
+<p>This is the human-friendly name of your Job, as will be displayed in the Nautobot UI. If not set, the class name will be used.</p>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
 <p>In some UI elements and API endpoints, the class name is displayed in addition to or in place of this attribute, so even if defining this attribute, you should still choose an appropriately explanatory class name as well.</p>
 </div>
 <h4 id="description"><code>description</code><a class="headerlink" href="#description" title="Permanent link">&para;</a></h4>
-<p>An optional human-friendly description of what this job does.
+<p>An optional human-friendly description of what this Job does.
 This can accept either plain text, Markdown-formatted text, or <a href="../../user-guide/platform-functionality/template-filters.html#render_markdown">a limited subset of HTML</a>. It can also be multiple lines:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="k">class</span> <span class="nc">ExampleJob</span><span class="p">(</span><span class="n">Job</span><span class="p">):</span>
 <a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a>    <span class="k">class</span> <span class="nc">Meta</span><span class="p">:</span>
@@ -9929,63 +10005,79 @@ This can accept either plain text, Markdown-formatted text, or <a href="../../us
 <a id="__codelineno-5-8" name="__codelineno-5-8" href="#__codelineno-5-8"></a><span class="s2">             3. It&#39;s a floor wax *and* a dessert topping</span>
 <a id="__codelineno-5-9" name="__codelineno-5-9" href="#__codelineno-5-9"></a><span class="s2">        &quot;&quot;&quot;</span>
 </code></pre></div>
-<p>If you code a multi-line description, the first line only will be used in the description column of the jobs list, while the full description will be rendered in the job detail view, submission, approval, and results pages.</p>
+<p>If you code a multi-line description, the first line only will be used in the description column of the Jobs list, while the full description will be rendered in the Job detail view, submission, approval, and results pages.</p>
 <h4 id="approval_required"><code>approval_required</code><a class="headerlink" href="#approval_required" title="Permanent link">&para;</a></h4>
 <p>Default: <code>False</code></p>
-<p>A boolean that will mark this job as requiring approval from another user to be run. For more details on approvals, <a href="../../user-guide/platform-functionality/jobs/job-scheduling-and-approvals.html">please refer to the section on scheduling and approvals</a>.</p>
+<p>A boolean that will mark this Job as requiring approval from another user to be run. For more details on approvals, <a href="../../user-guide/platform-functionality/jobs/job-scheduling-and-approvals.html">please refer to the section on scheduling and approvals</a>.</p>
 <h4 id="dryrun_default"><code>dryrun_default</code><a class="headerlink" href="#dryrun_default" title="Permanent link">&para;</a></h4>
 <details class="version-changed">
-<summary>Changed in version 2.0.0</summary>
-<p>The <code>commit_default</code> field was renamed to <code>dryrun_default</code> and the default value was changed from <code>True</code> to <code>False</code>. The <code>commit</code> functionality that provided an automatic rollback of database changes if the job failed was removed. The <code>dryrun</code> functionality was added to provide a way to bypass job approval if a job implements a <a href="#dryrunvar"><code>DryRunVar</code></a>.</p>
+<summary>Changed in version 2.0.0 — Replacement for <code>commit_default</code></summary>
+<p>The <code>commit_default</code> field was renamed to <code>dryrun_default</code> and the default value was changed from <code>True</code> to <code>False</code>. The <code>commit</code> functionality that provided an automatic rollback of database changes if the Job failed was removed.</p>
 </details>
 <p>Default: <code>False</code></p>
-<p>The checkbox to enable dryrun when executing a job is unchecked by default in the Nautobot UI. You can set <code>dryrun_default</code> to <code>True</code> under the <code>Meta</code> class if you want this option to instead be checked by default.</p>
+<p>If the Job implements a <a href="#dryrunvar"><code>DryRunVar</code></a>, what its default value should be.
+The checkbox to enable dryrun when executing a Job is unchecked by default in the Nautobot UI. You can set <code>dryrun_default</code> to <code>True</code> under the <code>Meta</code> class if you want this option to instead be checked by default.</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a><span class="k">class</span> <span class="nc">MyJob</span><span class="p">(</span><span class="n">Job</span><span class="p">):</span>
 <a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a>    <span class="k">class</span> <span class="nc">Meta</span><span class="p">:</span>
 <a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a>        <span class="n">dryrun_default</span> <span class="o">=</span> <span class="kc">True</span>
 </code></pre></div>
 <h4 id="field_order"><code>field_order</code><a class="headerlink" href="#field_order" title="Permanent link">&para;</a></h4>
 <p>Default: <code>[]</code></p>
-<p>A list of strings (field names) representing the order your job <a href="#variables">variables</a> should be rendered as form fields in the job submission UI. If not defined, the variables will be listed in order of their definition in the code. If variables are defined on a parent class and no field order is defined, the parent class variables will appear before the subclass variables.</p>
+<p>A list of strings (field names) representing the order your Job <a href="#variables">variables</a> should be rendered as form fields in the Job submission UI. If not defined, the variables will be listed in order of their definition in the code. If variables are defined on a parent class and no field order is defined, the parent class variables will appear before the subclass variables.</p>
 <h4 id="has_sensitive_variables"><code>has_sensitive_variables</code><a class="headerlink" href="#has_sensitive_variables" title="Permanent link">&para;</a></h4>
 <details class="version-added">
 <summary>Added in version 1.3.10</summary>
 </details>
 <p>Default: <code>True</code></p>
-<p>Unless set to False, it prevents the job's input parameters from being saved to the database. This defaults to True so as to protect against inadvertent database exposure of input parameters that may include sensitive data such as passwords or other user credentials. Review whether each job's inputs contain any such variables before setting this to False; if a job <em>does</em> contain sensitive inputs, if possible you should consider whether the job could be re-implemented using Nautobot's <a href="../../user-guide/platform-functionality/secret.html"><code>Secrets</code></a> feature as a way to ensure that the sensitive data is not directly provided as a job variable at all.</p>
-<p>Important notes about jobs with sensitive variables:</p>
+<p>Unless set to False, it prevents the Job's input parameters from being saved to the database. This defaults to True so as to protect against inadvertent database exposure of input parameters that may include sensitive data such as passwords or other user credentials. Review whether each Job's inputs contain any such variables before setting this to False; if a Job <em>does</em> contain sensitive inputs, if possible you should consider whether the Job could be re-implemented using Nautobot's <a href="../../user-guide/platform-functionality/secret.html"><code>Secrets</code></a> feature as a way to ensure that the sensitive data is not directly provided as a Job variable at all.</p>
+<p>Important notes about Jobs with sensitive variables:</p>
 <ul>
-<li>Such jobs cannot be scheduled to run in the future or on a recurring schedule (as scheduled jobs must by necessity store their variables in the database for future reference).</li>
-<li>Jobs with sensitive variables cannot be marked as requiring approval (as jobs pending approval must store their variables in the database until approved).</li>
+<li>Such Jobs cannot be scheduled to run in the future or on a recurring schedule (as Scheduled Jobs must by necessity store their variables in the database for future reference).</li>
+<li>Jobs with sensitive variables cannot be marked as requiring approval (as Jobs pending approval must store their variables in the database until approved).</li>
 </ul>
 <h4 id="hidden"><code>hidden</code><a class="headerlink" href="#hidden" title="Permanent link">&para;</a></h4>
 <p>Default: <code>False</code></p>
-<p>A Boolean that if set to <code>True</code> prevents the job from being displayed by default in the list of Jobs in the Nautobot UI.</p>
-<p>Since the jobs execution framework is designed to be generic, there may be several technical jobs defined by users which interact with or are invoked by external systems. In such cases, these jobs are not meant to be executed by a human and likely do not make sense to expose to end users for execution, and thus having them exposed in the UI at all is extraneous.</p>
-<p>Important notes about hidden jobs:</p>
+<p>A Boolean that if set to <code>True</code> prevents the Job from being displayed by default in the list of Jobs in the Nautobot UI.</p>
+<p>Since the Job execution framework is designed to be generic, there may be several technical Jobs defined by users which interact with or are invoked by external systems. In such cases, these Jobs are not meant to be executed by a human and likely do not make sense to expose to end users for execution, and thus having them exposed in the UI at all is extraneous.</p>
+<p>Important notes about hidden Jobs:</p>
 <ul>
 <li>This is merely hiding them by default from the web interface. It is NOT a security feature.</li>
-<li>In the Jobs list view it is possible to filter to "Hidden: (no selection)" or even "Hidden: Yes" to list the hidden jobs.</li>
-<li>All Job UI and REST API endpoints still exist for hidden jobs and can be accessed by any user who is aware of their existence.</li>
-<li>Hidden jobs can still be executed through the UI or the REST API given the appropriate URL.</li>
-<li>Results for hidden jobs will still appear in the Job Results list after they are run.</li>
+<li>In the Jobs list view it is possible to filter to "Hidden: (no selection)" or even "Hidden: Yes" to list the hidden Jobs.</li>
+<li>All Job UI and REST API endpoints still exist for hidden Jobs and can be accessed by any user who is aware of their existence.</li>
+<li>Hidden Jobs can still be executed through the UI or the REST API given the appropriate URL.</li>
+<li>Results for hidden Jobs will still appear in the Job Results list after they are run.</li>
+</ul>
+<h4 id="is_singleton"><code>is_singleton</code><a class="headerlink" href="#is_singleton" title="Permanent link">&para;</a></h4>
+<details class="version-added">
+<summary>Added in version 2.4.0</summary>
+</details>
+<p>Default: <code>False</code>
+A Boolean that if set to <code>True</code> prevents the job from running twice simultaneously.</p>
+<p>Any duplicate job instances will error out with a singleton-specific error message.</p>
+<p>Important notes about singleton jobs:</p>
+<ul>
+<li>The singleton functionality is implemented with a Redis key set to timeout either on the hard time out of the job or whenever the job terminates.<ul>
+<li>Therefore, a restart of Redis will wipe the singleton locks</li>
+</ul>
+</li>
+<li>A checkbox on the job run form makes it possible to force the singleton lock to be overridden. This makes it possible to recover from failure scenarios such as the original singleton job being stopped before it can unset the lock.</li>
 </ul>
 <h4 id="read_only"><code>read_only</code><a class="headerlink" href="#read_only" title="Permanent link">&para;</a></h4>
 <details class="version-added">
 <summary>Added in version 1.1.0</summary>
 </details>
 <details class="version-changed">
-<summary>Changed in version 2.0.0</summary>
-<p>The <code>read_only</code> 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.</p>
+<summary>Changed in version 2.0.0 — No automatic functionality</summary>
+<p>The <code>read_only</code> 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.</p>
 </details>
 <p>Default: <code>False</code></p>
-<p>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.</p>
+<p>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.</p>
 <h4 id="soft_time_limit"><code>soft_time_limit</code><a class="headerlink" href="#soft_time_limit" title="Permanent link">&para;</a></h4>
 <details class="version-added">
 <summary>Added in version 1.3.0</summary>
 </details>
-<p>An int or float value, in seconds, which can be used to override the default <a href="../../user-guide/administration/configuration/settings.html#celery_task_soft_time_limit">soft time limit</a> for a job task to complete.</p>
-<p>The <code>celery.exceptions.SoftTimeLimitExceeded</code> exception will be raised when this soft time limit is exceeded. The job task can catch this to clean up before the <a href="../../user-guide/administration/configuration/settings.html#celery_task_time_limit">hard time limit</a> (10 minutes by default) is reached:</p>
+<p>An int or float value, in seconds, which can be used to override the default <a href="../../user-guide/administration/configuration/settings.html#celery_task_soft_time_limit">soft time limit</a> for a Job task to complete.</p>
+<p>The <code>celery.exceptions.SoftTimeLimitExceeded</code> exception will be raised when this soft time limit is exceeded. The Job task can catch this to clean up before the <a href="../../user-guide/administration/configuration/settings.html#celery_task_time_limit">hard time limit</a> (10 minutes by default) is reached:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a><span class="kn">from</span> <span class="nn">celery.exceptions</span> <span class="kn">import</span> <span class="n">SoftTimeLimitExceeded</span>
 <a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a><span class="kn">from</span> <span class="nn">nautobot.apps.jobs</span> <span class="kn">import</span> <span class="n">Job</span>
 <a id="__codelineno-7-3" name="__codelineno-7-3" href="#__codelineno-7-3"></a>
@@ -10008,20 +10100,20 @@ This can accept either plain text, Markdown-formatted text, or <a href="../../us
 <summary>Added in version 1.5.0</summary>
 </details>
 <p>Default: <code>[]</code></p>
-<p>A list of Job Queue names that the job can be routed to. An empty list will default to only allowing the user to select the <a href="../../user-guide/administration/configuration/settings.html#celery_task_default_queue">default Celery queue</a> (<code>default</code> unless changed by an administrator). The queue specified in the job's <code>default_job_queue</code> will be used if a queue is not specified in a job run API call.</p>
+<p>A list of Job Queue names that the Job can be routed to. An empty list will default to only allowing the user to select the <a href="../../user-guide/administration/configuration/settings.html#celery_task_default_queue">default Celery queue</a> (<code>default</code> unless changed by an administrator). The queue specified in the Job's <code>default_job_queue</code> will be used if a queue is not specified in a Job run API call.</p>
 <details class="version-changed">
 <summary>Changed in version 2.4.0 — Changed default queue selection</summary>
 <p>As a result of the addition of Job Queues, the default queue when running a Job without explicitly selecting a queue is now the job queue specified in the <code>default_job_queue</code> field on the Job model. <code>default_job_queue</code> fields for any existing Job instances are automatically populated with the name of the first entry in <code>task_queues</code> list of the Job class. When <code>task_queues</code> list on the Job class is empty, the corresponding Job instance's <code>default_job_queue</code> will be the job queue with the name provided by <code>settings.CELERY_TASK_DEFAULT_QUEUE</code>. You can also override the initial <code>default_job_queue</code> by setting <code>default_job_queue_override</code> to True and assign the field with a different Job Queue instance.</p>
 </details>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
-<p>A worker must be listening on the requested queue or the job will not run. See the documentation on <a href="../../user-guide/administration/guides/celery-queues.html">task queues</a> for more information.</p>
+<p>A worker must be listening on the requested queue or the Job will not run. See the documentation on <a href="../../user-guide/administration/guides/celery-queues.html">task queues</a> for more information.</p>
 </div>
 <h4 id="template_name"><code>template_name</code><a class="headerlink" href="#template_name" title="Permanent link">&para;</a></h4>
 <details class="version-added">
 <summary>Added in version 1.4.0</summary>
 </details>
-<p>A path relative to the job source code containing a Django template which provides additional code to customize the Job's submission form. This template should extend the existing job template, <code>extras/job.html</code>, otherwise the base form and functionality may not be available.</p>
+<p>A path relative to the Job source code containing a Django template which provides additional code to customize the Job's submission form. This template should extend the existing Job template, <code>extras/job.html</code>, otherwise the base form and functionality may not be available.</p>
 <p>A template can provide additional JavaScript, CSS, or even display HTML. A good starting template would be:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a>{% extends &#39;extras/job.html&#39; %}
 <a id="__codelineno-8-2" name="__codelineno-8-2" href="#__codelineno-8-2"></a>
@@ -10039,7 +10131,7 @@ This can accept either plain text, Markdown-formatted text, or <a href="../../us
 <a id="__codelineno-8-14" name="__codelineno-8-14" href="#__codelineno-8-14"></a>{% endblock javascript %}
 </code></pre></div>
 <details class="version-added">
-<summary>Added in version 2.2.0</summary>
+<summary>Added in version 2.2.0 — Additional blocks</summary>
 <p>Added the <code>job_form</code> and <code>schedule_form</code> sub-blocks to <code>extras/job.html</code>, for use by Jobs that just want to override the rendered forms without replacing all of <code>{% block content %}</code>.</p>
 </details>
 <p>For another example checkout <a href="https://github.com/nautobot/nautobot/blob/main/examples/example_app/example_app/templates/example_app/example_with_custom_template.html">the template used in the Example App</a> in the GitHub repo.</p>
@@ -10048,7 +10140,7 @@ This can accept either plain text, Markdown-formatted text, or <a href="../../us
 <summary>Added in version 1.3.0</summary>
 </details>
 <p>An int or float value, in seconds, which can be used to override the
-default <a href="../../user-guide/administration/configuration/settings.html#celery_task_time_limit">hard time limit</a> (10 minutes by default) for a job task to complete.</p>
+default <a href="../../user-guide/administration/configuration/settings.html#celery_task_time_limit">hard time limit</a> (10 minutes by default) for a Job task to complete.</p>
 <p>Unlike the <code>soft_time_limit</code> above, no exceptions are raised when a <code>time_limit</code> is exceeded. The task will just terminate silently:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a><span class="kn">from</span> <span class="nn">nautobot.apps.jobs</span> <span class="kn">import</span> <span class="n">Job</span>
 <a id="__codelineno-9-2" name="__codelineno-9-2" href="#__codelineno-9-2"></a>
@@ -10064,11 +10156,11 @@ default <a href="../../user-guide/administration/configuration/settings.html#cel
 <a id="__codelineno-9-12" name="__codelineno-9-12" href="#__codelineno-9-12"></a>        <span class="n">job_code</span><span class="p">()</span>
 </code></pre></div>
 <div class="admonition note">
-<p class="admonition-title">Note</p>
-<p>If the <code>time_limit</code> is set to a value less than or equal to the <code>soft_time_limit</code>, a warning log is generated to inform the user that this job will fail silently after the <code>time_limit</code> as the <code>soft_time_limit</code> will never be reached.</p>
+<p class="admonition-title"><code>time_limit</code> versus <code>soft_time_limit</code></p>
+<p>If the <code>time_limit</code> is set to a value less than or equal to the <code>soft_time_limit</code>, a warning log is generated to inform the user that this Job will fail silently after the <code>time_limit</code> as the <code>soft_time_limit</code> will never be reached.</p>
 </div>
 <h3 id="variables">Variables<a class="headerlink" href="#variables" title="Permanent link">&para;</a></h3>
-<p>Variables allow your job to accept user input via the Nautobot UI, but they are optional; if your job does not require any user input, there is no need to define any variables. Conversely, if you are making use of user input in your job, you <em>must</em> also implement the <code>run()</code> method, as it is the only entry point to your job that has visibility into the variable values provided by the user.</p>
+<p>Variables allow your Job to accept user input via the Nautobot UI, but they are optional; if your Job does not require any user input, there is no need to define any variables. Conversely, if you are making use of user input in your Job, you <em>must</em> also implement the <code>run()</code> method, as it is the only entry point to your Job that has visibility into the variable values provided by the user.</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="kn">from</span> <span class="nn">nautobot.apps.jobs</span> <span class="kn">import</span> <span class="n">Job</span><span class="p">,</span> <span class="n">StringVar</span><span class="p">,</span> <span class="n">IntegerVar</span><span class="p">,</span> <span class="n">ObjectVar</span>
 <a id="__codelineno-10-2" name="__codelineno-10-2" href="#__codelineno-10-2"></a>
 <a id="__codelineno-10-3" name="__codelineno-10-3" href="#__codelineno-10-3"></a><span class="k">class</span> <span class="nc">CreateDevices</span><span class="p">(</span><span class="n">Job</span><span class="p">):</span>
@@ -10081,7 +10173,7 @@ default <a href="../../user-guide/administration/configuration/settings.html#cel
 </code></pre></div>
 <p>The remainder of this section documents the various supported variable types and how to make use of them.</p>
 <h4 id="default-variable-options">Default Variable Options<a class="headerlink" href="#default-variable-options" title="Permanent link">&para;</a></h4>
-<p>All job variables support the following default options:</p>
+<p>All Job variables support the following default options:</p>
 <ul>
 <li><code>default</code> - The field's default value</li>
 <li><code>description</code> - A brief user-friendly description of the field</li>
@@ -10103,7 +10195,7 @@ default <a href="../../user-guide/administration/configuration/settings.html#cel
 <details class="version-added">
 <summary>Added in version 2.1.0</summary>
 </details>
-<p>Accepts JSON-formatted data of any length. Renders as a multi-line text input field. The variable passed to <code>run()</code> method on the job has been serialized to the appropriate Python objects.</p>
+<p>Accepts JSON-formatted data of any length. Renders as a multi-line text input field. The variable passed to <code>run()</code> method on the Job has been serialized to the appropriate Python objects.</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a><span class="k">class</span> <span class="nc">ExampleJSONVarJob</span><span class="p">(</span><span class="n">Job</span><span class="p">):</span>
 <a id="__codelineno-11-2" name="__codelineno-11-2" href="#__codelineno-11-2"></a>    <span class="n">var1</span> <span class="o">=</span> <span class="n">JSONVar</span><span class="p">()</span>
 <a id="__codelineno-11-3" name="__codelineno-11-3" href="#__codelineno-11-3"></a>
@@ -10111,7 +10203,7 @@ default <a href="../../user-guide/administration/configuration/settings.html#cel
 <a id="__codelineno-11-5" name="__codelineno-11-5" href="#__codelineno-11-5"></a>        <span class="c1"># var1 form data equals &#39;{&quot;key1&quot;: &quot;value1&quot;}&#39;</span>
 <a id="__codelineno-11-6" name="__codelineno-11-6" href="#__codelineno-11-6"></a>        <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s2">&quot;The value of key1 is: </span><span class="si">%s</span><span class="s2">&quot;</span><span class="p">,</span> <span class="n">var1</span><span class="p">[</span><span class="s2">&quot;key1&quot;</span><span class="p">])</span>
 </code></pre></div>
-<p>In the above example <code>{"key1": "value1"}</code> is provided to the job form, on submission first the field is validated to be JSON-formatted data then is serialized and passed to the <code>run()</code> method as a dictionary without any need for the job developer to post-process the variable into a Python dictionary.</p>
+<p>In the above example <code>{"key1": "value1"}</code> is provided to the Job form, on submission first the field is validated to be JSON-formatted data then is serialized and passed to the <code>run()</code> method as a dictionary without any need for the Job developer to post-process the variable into a Python dictionary.</p>
 <h4 id="integervar"><code>IntegerVar</code><a class="headerlink" href="#integervar" title="Permanent link">&para;</a></h4>
 <p>Stores a numeric integer. Options include:</p>
 <ul>
@@ -10121,7 +10213,7 @@ default <a href="../../user-guide/administration/configuration/settings.html#cel
 <h4 id="booleanvar"><code>BooleanVar</code><a class="headerlink" href="#booleanvar" title="Permanent link">&para;</a></h4>
 <p>A true/false flag. This field has no options beyond the defaults listed above.</p>
 <h4 id="dryrunvar"><code>DryRunVar</code><a class="headerlink" href="#dryrunvar" title="Permanent link">&para;</a></h4>
-<p>A true/false flag with special handling for jobs that require approval. If <code>dryrun = DryRunVar()</code> is declared on a job class, approval may be bypassed if <code>dryrun</code> is set to <code>True</code> on job execution.</p>
+<p>A true/false flag with special handling for Jobs that require approval. If <code>dryrun = DryRunVar()</code> is declared on a Job class, approval may be bypassed if <code>dryrun</code> is set to <code>True</code> on Job execution.</p>
 <h4 id="choicevar"><code>ChoiceVar</code><a class="headerlink" href="#choicevar" title="Permanent link">&para;</a></h4>
 <p>A set of choices from which the user can select one.</p>
 <ul>
@@ -10198,7 +10290,7 @@ Another example of using the nested reference would be to access <a href="../../
 <h4 id="multiobjectvar"><code>MultiObjectVar</code><a class="headerlink" href="#multiobjectvar" title="Permanent link">&para;</a></h4>
 <p>Similar to <code>ObjectVar</code>, but allows for the selection of multiple objects.</p>
 <h4 id="filevar"><code>FileVar</code><a class="headerlink" href="#filevar" title="Permanent link">&para;</a></h4>
-<p>An uploaded file. Note that uploaded files are present in memory only for the duration of the job's execution: They will not be automatically saved for future use. The job is responsible for writing file contents to disk where necessary.</p>
+<p>An uploaded file. Note that uploaded files are present in memory only for the duration of the Job's execution: They will not be automatically saved for future use. The Job is responsible for writing file contents to disk where necessary.</p>
 <h4 id="ipaddressvar"><code>IPAddressVar</code><a class="headerlink" href="#ipaddressvar" title="Permanent link">&para;</a></h4>
 <p>An IPv4 or IPv6 address, without a mask. Returns a <code>netaddr.IPAddress</code> object.</p>
 <h4 id="ipaddresswithmaskvar"><code>IPAddressWithMaskVar</code><a class="headerlink" href="#ipaddresswithmaskvar" title="Permanent link">&para;</a></h4>
@@ -10213,14 +10305,14 @@ Another example of using the nested reference would be to access <a href="../../
 <p>Nautobot Jobs when executed will be instantiated by Nautobot, then Nautobot will call in order the special API methods <code>before_start()</code>, <code>run()</code>, <code>on_success()</code>/<code>on_failure()</code>, and <code>after_return()</code>. You must implement the <code>run()</code> method; the other methods have default implementations that do nothing.</p>
 <p>As Jobs are Python classes, you are of course free to define any number of other helper methods or functions that you call yourself from within any of the above special methods, but the above are the only ones that will be automatically called.</p>
 <details class="version-removed">
-<summary>Removed in version 2.0.0</summary>
+<summary>Removed in version 2.0.0 — Removal of <code>test</code> and <code>post_run</code> special methods</summary>
 <p>The NetBox backwards compatible <code>test_*()</code> and <code>post_run()</code> special methods have been removed.</p>
 </details>
 <h4 id="the-before_start-method">The <code>before_start()</code> Method<a class="headerlink" href="#the-before_start-method" title="Permanent link">&para;</a></h4>
 <p>The <code>before_start()</code> method may optionally be implemented to perform any appropriate Job-specific setup before the <code>run()</code> method is called. It has the signature <code>before_start(self, task_id, args, kwargs)</code> for historical reasons; the <code>task_id</code> parameter will always be identical to <code>self.request.id</code>, the <code>args</code> parameter will generally be empty, and any user-specified variables passed into the Job execution will be present in the <code>kwargs</code> parameter.</p>
 <p>The return value from <code>before_start()</code> is ignored, but if it raises any exception, the Job execution will be marked as a failure and <code>run()</code> will not be called.</p>
 <h4 id="the-run-method">The <code>run()</code> Method<a class="headerlink" href="#the-run-method" title="Permanent link">&para;</a></h4>
-<p>The <code>run()</code> method is the primary worker of any Job, and must be implemented. After the <code>self</code> argument, it should accept keyword arguments for any variables defined on the job:</p>
+<p>The <code>run()</code> method is the primary worker of any Job, and must be implemented. After the <code>self</code> argument, it should accept keyword arguments for any variables defined on the Job:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-18-1" name="__codelineno-18-1" href="#__codelineno-18-1"></a><span class="kn">from</span> <span class="nn">nautobot.apps.jobs</span> <span class="kn">import</span> <span class="n">Job</span><span class="p">,</span> <span class="n">StringVar</span><span class="p">,</span> <span class="n">IntegerVar</span><span class="p">,</span> <span class="n">ObjectVar</span>
 <a id="__codelineno-18-2" name="__codelineno-18-2" href="#__codelineno-18-2"></a>
 <a id="__codelineno-18-3" name="__codelineno-18-3" href="#__codelineno-18-3"></a><span class="k">class</span> <span class="nc">CreateDevices</span><span class="p">(</span><span class="n">Job</span><span class="p">):</span>
@@ -10231,13 +10323,13 @@ Another example of using the nested reference would be to access <a href="../../
 <a id="__codelineno-18-8" name="__codelineno-18-8" href="#__codelineno-18-8"></a>    <span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">var1</span><span class="p">,</span> <span class="n">var2</span><span class="p">,</span> <span class="n">var3</span><span class="p">):</span>
 <a id="__codelineno-18-9" name="__codelineno-18-9" href="#__codelineno-18-9"></a>        <span class="o">...</span>
 </code></pre></div>
-<p>Again, defining user variables is totally optional; you may create a job with a <code>run()</code> method with only the <code>self</code> argument if no user input is needed.</p>
+<p>Again, defining user variables is totally optional; you may create a Job with a <code>run()</code> method with only the <code>self</code> argument if no user input is needed.</p>
 <div class="admonition warning">
-<p class="admonition-title">Warning</p>
+<p class="admonition-title">Use <code>validated_save()</code> where applicable</p>
 <p>When writing Jobs that create and manipulate data it is recommended to make use of the <code>validated_save()</code> convenience method which exists on all core models. This method saves the instance data but first enforces model validation logic. Simply calling <code>save()</code> on the model instance <strong>does not</strong> enforce validation automatically and may lead to bad data. See the development <a href="../core/best-practices.html">best practices</a>.</p>
 </div>
 <div class="admonition warning">
-<p class="admonition-title">Warning</p>
+<p class="admonition-title">Be cautious around bulk operations</p>
 <p>The Django ORM provides methods to create/edit many objects at once, namely <code>bulk_create()</code> and <code>update()</code>. 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.</p>
 </div>
 <p>If <code>run()</code> returns any value (even the implicit <code>None</code>), the Job execution will be marked as a success and the returned value will be stored in the associated JobResult database record. Conversely, if <code>run()</code> raises any exception, the Job execution will be marked as a failure and the traceback will be stored in the JobResult.</p>
@@ -10251,8 +10343,8 @@ Another example of using the nested reference would be to access <a href="../../
 <details class="version-changed">
 <summary>Changed in version 2.0.0</summary>
 </details>
-<p>Messages logged from a job's logger will be stored in <a href="../../user-guide/platform-functionality/jobs/models.html#job-log-entry"><code>JobLogEntry</code></a> records associated with the current <a href="../../user-guide/platform-functionality/jobs/models.html#job-results"><code>JobResult</code></a>.</p>
-<p>The logger can be accessed either by using the <code>logger</code> property on the job class or <code>nautobot.extras.jobs.get_task_logger(__name__)</code>. Both will return the same logger instance. For more information on the standard Python logging module, see the <a href="https://docs.python.org/3/library/logging.html">Python documentation</a>.</p>
+<p>Messages logged from a Job's logger will be stored in <a href="../../user-guide/platform-functionality/jobs/models.html#job-log-entry"><code>JobLogEntry</code></a> records associated with the current <a href="../../user-guide/platform-functionality/jobs/models.html#job-results"><code>JobResult</code></a>.</p>
+<p>The logger can be accessed either by using the <code>logger</code> property on the Job class or <code>nautobot.extras.jobs.get_task_logger(__name__)</code>. Both will return the same logger instance. For more information on the standard Python logging module, see the <a href="https://docs.python.org/3/library/logging.html">Python documentation</a>.</p>
 <p>The logger accepts an <code>extra</code> kwarg that you can optionally set for the following features:</p>
 <ul>
 <li><code>grouping</code>- Replaces the <code>active_test</code> Job property in Nautobot v1.X</li>
@@ -10281,16 +10373,16 @@ Another example of using the nested reference would be to access <a href="../../
 </div>
 <p>Markdown rendering is supported for log messages, as well as <a href="../../user-guide/platform-functionality/template-filters.html#render_markdown">a limited subset of HTML</a>.</p>
 <details class="version-changed">
-<summary>Changed in version 1.3.4</summary>
-<p>As a security measure, the <code>message</code> passed to any of these methods will be passed through the <code>nautobot.core.utils.logging.sanitize()</code> 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 <code>sanitize()</code> function can be configured as <a href="../../user-guide/administration/configuration/settings.html#sanitizer_patterns">settings.SANITIZER_PATTERNS</a>.</p>
+<summary>Changed in version 1.3.4 — Log entry sanitization</summary>
+<p>As a security measure, the <code>message</code> passed to any of these methods will be passed through the <code>nautobot.core.utils.logging.sanitize()</code> 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 <code>sanitize()</code> function can be configured as <a href="../../user-guide/administration/configuration/settings.html#sanitizer_patterns"><code>settings.SANITIZER_PATTERNS</code></a>.</p>
 </details>
 <details class="version-changed">
-<summary>Changed in version 2.0.0</summary>
-<p>The Job class logging functions (example: <code>self.log(message)</code>, <code>self.log_success(obj=None, message=message)</code>, etc) have been removed. Also, the convenience method to mark a job as failed, <code>log_failure()</code>, has been removed. To replace the functionality of this method, you can log an error message with <code>self.logger.error()</code> 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.</p>
+<summary>Changed in version 2.0.0 — Significant API changes</summary>
+<p>The Job class logging functions (example: <code>self.log(message)</code>, <code>self.log_success(obj=None, message=message)</code>, etc) have been removed. Also, the convenience method to mark a Job as failed, <code>log_failure()</code>, has been removed. To replace the functionality of this method, you can log an error message with <code>self.logger.error()</code> 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.</p>
 </details>
 <details class="version-changed">
 <summary>Changed in version 2.0.0</summary>
-<p>The <code>AbortTransaction</code> class was moved from the <code>nautobot.utilities.exceptions</code> module to <code>nautobot.core.exceptions</code>.</p>
+<p>The <code>AbortTransaction</code> class was moved from the <code>nautobot.utilities.exceptions</code> module to <code>nautobot.core.exceptions</code>. Jobs should generally import it from <code>nautobot.apps.exceptions</code> if needed.</p>
 </details>
 <details class="version-added">
 <summary>Added in version 2.4.0</summary>
@@ -10311,8 +10403,8 @@ Another example of using the nested reference would be to access <a href="../../
 <p>The above Job when run will create two files, "greeting.txt" and "farewell.txt", that will be made available for download from the JobResult detail view's "Advanced" tab and via the REST API. These files will persist indefinitely, but can automatically be deleted if the JobResult itself is deleted; they can also be deleted manually by an administrator via the "File Proxies" link in the Admin UI.</p>
 <p>The maximum size of any single created file (or in other words, the maximum number of bytes that can be passed to <code>self.create_file()</code>) is controlled by the <a href="../../user-guide/administration/configuration/settings.html#job_create_file_max_size"><code>JOB_CREATE_FILE_MAX_SIZE</code></a> system setting. A <code>ValueError</code> exception will be raised if <code>create_file()</code> is called with an overly large <code>content</code> value.</p>
 <h3 id="marking-a-job-as-failed">Marking a Job as Failed<a class="headerlink" href="#marking-a-job-as-failed" title="Permanent link">&para;</a></h3>
-<p>To mark a job as failed, raise an exception from within the <code>run()</code> method. The exception message will be logged to the traceback of the job result. The job result status will be set to <code>failed</code>. To output a job log message you can use the <code>self.logger.error()</code> method.</p>
-<p>As an example, the following job will fail if the user does not put the word "Taco" in <code>var1</code>:</p>
+<p>To mark a Job as failed, raise an exception from within the <code>run()</code> method. The exception message will be logged to the traceback of the Job Result. The Job Result status will be set to <code>failed</code>. To output a Job log message you can use the <code>self.logger.error()</code> method.</p>
+<p>As an example, the following Job will fail if the user does not put the word "Taco" in <code>var1</code>:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-22-1" name="__codelineno-22-1" href="#__codelineno-22-1"></a><span class="kn">from</span> <span class="nn">nautobot.apps.jobs</span> <span class="kn">import</span> <span class="n">Job</span><span class="p">,</span> <span class="n">StringVar</span>
 <a id="__codelineno-22-2" name="__codelineno-22-2" href="#__codelineno-22-2"></a>
 <a id="__codelineno-22-3" name="__codelineno-22-3" href="#__codelineno-22-3"></a><span class="k">class</span> <span class="nc">MyJob</span><span class="p">(</span><span class="n">Job</span><span class="p">):</span>
@@ -10325,10 +10417,10 @@ Another example of using the nested reference would be to access <a href="../../
 </code></pre></div>
 <h3 id="accessing-user-and-job-result">Accessing User and Job Result<a class="headerlink" href="#accessing-user-and-job-result" title="Permanent link">&para;</a></h3>
 <details class="version-changed">
-<summary>Changed in version 2.0.0</summary>
+<summary>Changed in version 2.0.0 — Significant API change</summary>
 <p>The <code>request</code> property has been changed to a Celery request instead of a Django web request and no longer includes the information from the web request that initiated the Job. The <code>user</code> object is now available as <code>self.user</code> instead of <code>self.request.user</code>.</p>
 </details>
-<p>The user that initiated the job and the job result associated to the job can be accessed through properties on the job class:</p>
+<p>The user that initiated the Job and the Job Result associated to the Job can be accessed through properties on the Job class:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-23-1" name="__codelineno-23-1" href="#__codelineno-23-1"></a><span class="n">username</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">user</span><span class="o">.</span><span class="n">username</span>
 <a id="__codelineno-23-2" name="__codelineno-23-2" href="#__codelineno-23-2"></a><span class="n">job_result_id</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">job_result</span><span class="o">.</span><span class="n">id</span>
 <a id="__codelineno-23-3" name="__codelineno-23-3" href="#__codelineno-23-3"></a><span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s2">&quot;Job </span><span class="si">%s</span><span class="s2"> initiated by user </span><span class="si">%s</span><span class="s2"> is running.&quot;</span><span class="p">,</span> <span class="n">job_result_id</span><span class="p">,</span> <span class="n">username</span><span class="p">)</span>
@@ -10350,7 +10442,7 @@ However the import paths used in the examples requires 1.5.2 and newer.</p>
 </details>
 <p>The simplest way to test the entire execution of Jobs is via calling the <code>nautobot.apps.testing.run_job_for_testing()</code> method, which is a helper wrapper around the <code>JobResult.enqueue_job</code> function used to execute a Job via Nautobot's Celery worker process.</p>
 <p>Because of the way <code>run_job_for_testing</code> and more specifically Celery tasks work, which is somewhat complex behind the scenes, you need to inherit from <code>nautobot.apps.testing.TransactionTestCase</code> instead of <code>django.test.TestCase</code> (Refer to the <a href="https://docs.djangoproject.com/en/stable/topics/testing/tools/#provided-test-case-classes">Django documentation</a> if you're interested in the differences between these classes - <code>TransactionTestCase</code> from Nautobot is a small wrapper around Django's <code>TransactionTestCase</code>).</p>
-<p>When using <code>TransactionTestCase</code> (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 <code>run_job_for_testing</code> handles for us.</p>
+<p>When using <code>TransactionTestCase</code> (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 <code>run_job_for_testing</code> handles for us.</p>
 <p>A simple example of a Job test case might look like the following:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-24-1" name="__codelineno-24-1" href="#__codelineno-24-1"></a><span class="kn">from</span> <span class="nn">nautobot.apps.testing</span> <span class="kn">import</span> <span class="n">run_job_for_testing</span><span class="p">,</span> <span class="n">TransactionTestCase</span>
 <a id="__codelineno-24-2" name="__codelineno-24-2" href="#__codelineno-24-2"></a><span class="kn">from</span> <span class="nn">nautobot.extras.models</span> <span class="kn">import</span> <span class="n">Job</span><span class="p">,</span> <span class="n">JobLogEntry</span>
@@ -10372,15 +10464,15 @@ However the import paths used in the examples requires 1.5.2 and newer.</p>
 <p class="admonition-title">Tip</p>
 <p>For more advanced examples refer to the Nautobot source code, specifically <code>nautobot/extras/tests/test_jobs.py</code>.</p>
 </div>
-<h2 id="debugging-job-performance">Debugging job performance<a class="headerlink" href="#debugging-job-performance" title="Permanent link">&para;</a></h2>
+<h2 id="debugging-job-performance">Debugging Job Performance<a class="headerlink" href="#debugging-job-performance" title="Permanent link">&para;</a></h2>
 <details class="version-added">
 <summary>Added in version 1.5.17</summary>
 </details>
-<p>Debugging the performance of Nautobot jobs can be tricky, because they are executed in the worker context. In order to gain extra visibility, <a href="https://docs.python.org/3/library/profile.html">cProfile</a> can be used to profile the job execution.</p>
-<p>The 'profile' form field on jobs is automatically available when the <code>DEBUG</code> settings is <code>True</code>. 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 <code>nautobot-server runjob</code> command with <code>--local</code>, 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.</p>
+<p>Debugging the performance of Nautobot Jobs can be tricky, because they are executed in the worker context. In order to gain extra visibility, <a href="https://docs.python.org/3/library/profile.html">cProfile</a> can be used to profile the Job execution.</p>
+<p>The 'profile' form field on Jobs is automatically available when the <code>DEBUG</code> settings is <code>True</code>. 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 <code>nautobot-server runjob</code> command with <code>--local</code>, 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.</p>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
-<p>If you need to run this in an environment where <code>DEBUG</code> is <code>False</code>, you have the option of using <code>nautobot-server runjob</code> with the <code>--profile</code> flag. According to the docs, <code>cProfile</code> should have minimal impact on the performance of the job; still, proceed with caution when using this in a production environment.</p>
+<p>If you need to run this in an environment where <code>DEBUG</code> is <code>False</code>, you have the option of using <code>nautobot-server runjob</code> with the <code>--profile</code> flag. According to the docs, <code>cProfile</code> should have minimal impact on the performance of the Job; still, proceed with caution when using this in a production environment.</p>
 </div>
 <h3 id="reading-profiling-reports">Reading profiling reports<a class="headerlink" href="#reading-profiling-reports" title="Permanent link">&para;</a></h3>
 <p>A full description on how to deal with the output of <code>cProfile</code> can be found in the <a href="https://docs.python.org/3/library/profile.html#instant-user-s-manual">Instant User's Manual</a>, but here is something to get you started:</p>
@@ -10389,16 +10481,18 @@ However the import paths used in the examples requires 1.5.2 and newer.</p>
 <a id="__codelineno-25-3" name="__codelineno-25-3" href="#__codelineno-25-3"></a><span class="n">stats</span> <span class="o">=</span> <span class="n">pstats</span><span class="o">.</span><span class="n">Stats</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;/tmp/nautobot-jobresult-</span><span class="si">{</span><span class="n">job_result_uuid</span><span class="si">}</span><span class="s2">.pstats&quot;</span><span class="p">)</span>
 <a id="__codelineno-25-4" name="__codelineno-25-4" href="#__codelineno-25-4"></a><span class="n">stats</span><span class="o">.</span><span class="n">sort_stats</span><span class="p">(</span><span class="n">pstats</span><span class="o">.</span><span class="n">SortKey</span><span class="o">.</span><span class="n">CUMULATIVE</span><span class="p">)</span><span class="o">.</span><span class="n">print_stats</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
 </code></pre></div>
-<p>This will print the 10 functions that the job execution spent the most time in - adapt this to your needs!</p>
+<p>This will print the 10 functions that the Job execution spent the most time in - adapt this to your needs!</p>
 <h2 id="example-jobs">Example Jobs<a class="headerlink" href="#example-jobs" title="Permanent link">&para;</a></h2>
+<h3 id="example-everything-job">Example "Everything" Job<a class="headerlink" href="#example-everything-job" title="Permanent link">&para;</a></h3>
+<p>The "Example App" included with the Nautobot source code <a href="https://github.com/nautobot/nautobot/blob/main/examples/example_app/example_app/jobs.py">includes a number of simple sample Jobs</a>, including an <code>ExampleEverythingJob</code> class that demonstrates and documents the usage of the various metadata attributes, input variable types, and magic methods that a Job can support. As Job functionality will continue to evolve over time, if using this file as a reference, please make sure that you're viewing the version of this Job that corresponds to your target Nautobot version.</p>
 <h3 id="creating-objects-for-a-planned-location">Creating objects for a planned location<a class="headerlink" href="#creating-objects-for-a-planned-location" title="Permanent link">&para;</a></h3>
-<p>This job prompts the user for three variables:</p>
+<p>This Job prompts the user for three variables:</p>
 <ul>
 <li>The name of the new location</li>
 <li>The device model (a filtered list of defined device types)</li>
 <li>The number of access switches to create</li>
 </ul>
-<p>These variables are presented as a web form to be completed by the user. Once submitted, the job's <code>run()</code> method is called to create the appropriate objects, and it returns simple CSV output to the user summarizing the created objects.</p>
+<p>These variables are presented as a web form to be completed by the user. Once submitted, the Job's <code>run()</code> method is called to create the appropriate objects, and it returns simple CSV output to the user summarizing the created objects.</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-26-1" name="__codelineno-26-1" href="#__codelineno-26-1"></a><span class="kn">from</span> <span class="nn">django.contrib.contenttypes.models</span> <span class="kn">import</span> <span class="n">ContentType</span>
 <a id="__codelineno-26-2" name="__codelineno-26-2" href="#__codelineno-26-2"></a>
 <a id="__codelineno-26-3" name="__codelineno-26-3" href="#__codelineno-26-3"></a><span class="kn">from</span> <span class="nn">nautobot.apps.jobs</span> <span class="kn">import</span> <span class="n">Job</span><span class="p">,</span> <span class="n">StringVar</span><span class="p">,</span> <span class="n">IntegerVar</span><span class="p">,</span> <span class="n">ObjectVar</span><span class="p">,</span> <span class="n">register_jobs</span>
@@ -10458,7 +10552,7 @@ However the import paths used in the examples requires 1.5.2 and newer.</p>
 <a id="__codelineno-26-57" name="__codelineno-26-57" href="#__codelineno-26-57"></a><span class="n">register_jobs</span><span class="p">(</span><span class="n">NewBranch</span><span class="p">)</span>
 </code></pre></div>
 <h3 id="device-validation">Device validation<a class="headerlink" href="#device-validation" title="Permanent link">&para;</a></h3>
-<p>A job to perform various validation of Device data in Nautobot. As this job does not require any user input, it does not define any variables.</p>
+<p>A Job to perform various validation of Device data in Nautobot. As this Job does not require any user input, it does not define any variables.</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-27-1" name="__codelineno-27-1" href="#__codelineno-27-1"></a><span class="kn">from</span> <span class="nn">nautobot.apps.jobs</span> <span class="kn">import</span> <span class="n">Job</span><span class="p">,</span> <span class="n">register_jobs</span>
 <a id="__codelineno-27-2" name="__codelineno-27-2" href="#__codelineno-27-2"></a><span class="kn">from</span> <span class="nn">nautobot.dcim.models</span> <span class="kn">import</span> <span class="n">ConsolePort</span><span class="p">,</span> <span class="n">Device</span><span class="p">,</span> <span class="n">PowerPort</span>
 <a id="__codelineno-27-3" name="__codelineno-27-3" href="#__codelineno-27-3"></a><span class="kn">from</span> <span class="nn">nautobot.extras.models</span> <span class="kn">import</span> <span class="n">Status</span>
@@ -10511,9 +10605,9 @@ However the import paths used in the examples requires 1.5.2 and newer.</p>
 <a id="__codelineno-27-50" name="__codelineno-27-50" href="#__codelineno-27-50"></a><span class="n">register_jobs</span><span class="p">(</span><span class="n">DeviceConnectionsReport</span><span class="p">)</span>
 </code></pre></div>
 <h2 id="job-button-receivers">Job Button Receivers<a class="headerlink" href="#job-button-receivers" title="Permanent link">&para;</a></h2>
-<p>Job Buttons are only able to initiate a specific type of job called a <strong>Job Button Receiver</strong>. These are jobs that subclass the <code>nautobot.apps.jobs.JobButtonReceiver</code> class. Job Button Receivers are similar to normal jobs except they are hard coded to accept only <code>object_pk</code> and <code>object_model_name</code> <a href="#variables">variables</a>. Job Button Receivers are hidden from the jobs listing UI by default but otherwise function similarly to other jobs. The <code>JobButtonReceiver</code> class only implements one method called <code>receive_job_button</code>.</p>
+<p>Job Buttons are only able to initiate a specific type of Job called a <strong>Job Button Receiver</strong>. These are Jobs that subclass the <code>nautobot.apps.jobs.JobButtonReceiver</code> class. Job Button Receivers are similar to normal Jobs except they are hard coded to accept only <code>object_pk</code> and <code>object_model_name</code> <a href="#variables">variables</a>. The <code>JobButtonReceiver</code> class only implements one method called <code>receive_job_button</code>.</p>
 <div class="admonition note">
-<p class="admonition-title">Note</p>
+<p class="admonition-title">Disabled by default just like other Jobs</p>
 <p>Job Button Receivers still need to be <a href="../../user-guide/platform-functionality/jobs/index.html#enabling-jobs-for-running">enabled through the web UI</a> before they can be used just like other Jobs.</p>
 </div>
 <h3 id="the-receive_job_button-method">The <code>receive_job_button()</code> Method<a class="headerlink" href="#the-receive_job_button-method" title="Permanent link">&para;</a></h3>
@@ -10576,14 +10670,14 @@ However the import paths used in the examples requires 1.5.2 and newer.</p>
 <a id="__codelineno-29-36" name="__codelineno-29-36" href="#__codelineno-29-36"></a><span class="n">register_jobs</span><span class="p">(</span><span class="n">ExampleComplexJobButtonReceiver</span><span class="p">)</span>
 </code></pre></div>
 <h2 id="job-hook-receivers">Job Hook Receivers<a class="headerlink" href="#job-hook-receivers" title="Permanent link">&para;</a></h2>
-<p>Job Hooks are only able to initiate a specific type of job called a <strong>Job Hook Receiver</strong>. These are jobs that subclass the <code>nautobot.apps.jobs.JobHookReceiver</code> class. Job hook receivers are similar to normal jobs except they are hard coded to accept only an <code>object_change</code> <a href="#variables">variable</a>. Job Hook Receivers are hidden from the jobs listing UI by default but otherwise function similarly to other jobs. The <code>JobHookReceiver</code> class only implements one method called <code>receive_job_hook</code>.</p>
+<p>Job Hooks are only able to initiate a specific type of Job called a <strong>Job Hook Receiver</strong>. These are Jobs that subclass the <code>nautobot.apps.jobs.JobHookReceiver</code> class. Job Hook Receivers are similar to normal Jobs except they are hard coded to accept only an <code>object_change</code> <a href="#variables">variable</a>. The <code>JobHookReceiver</code> class only implements one method called <code>receive_job_hook</code>.</p>
 <div class="admonition warning">
-<p class="admonition-title">Warning</p>
+<p class="admonition-title">No support for <code>approval_required</code> at this time</p>
 <p>Requiring approval for execution of Job Hooks by setting the <code>Meta.approval_required</code> attribute to <code>True</code> on your <code>JobHookReceiver</code> 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.</p>
 </div>
 <div class="admonition important">
-<p class="admonition-title">Important</p>
-<p>To prevent negatively impacting system performance through an infinite loop, a change that was made by a <code>JobHookReceiver</code> job will not trigger another <code>JobHookReceiver</code> job to run.</p>
+<p class="admonition-title">No recursive JobHookReceivers</p>
+<p>To prevent negatively impacting system performance through an infinite loop, a change that was made by a <code>JobHookReceiver</code> Job will not trigger another <code>JobHookReceiver</code> Job to run.</p>
 </div>
 <h3 id="example-job-hook-receiver">Example Job Hook Receiver<a class="headerlink" href="#example-job-hook-receiver" title="Permanent link">&para;</a></h3>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-30-1" name="__codelineno-30-1" href="#__codelineno-30-1"></a><span class="kn">from</span> <span class="nn">nautobot.apps.jobs</span> <span class="kn">import</span> <span class="n">JobHookReceiver</span><span class="p">,</span> <span class="n">register_jobs</span>
@@ -10774,7 +10868,7 @@ However the import paths used in the examples requires 1.5.2 and newer.</p>
     <script id="__config" type="application/json">{"base": "../..", "features": ["content.code.annotate", "content.code.copy", "content.tabs.link", "navigation.footer", "navigation.tabs", "navigation.tabs.sticky", "navigation.tracking", "search.highlight", "search.share", "search.suggest"], "search": "../../assets/javascripts/workers/search.6ce7567c.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script>
     
     
-      <script src="../../assets/javascripts/bundle.83f73b43.min.js"></script>
+      <script src="../../assets/javascripts/bundle.88dd0f4e.min.js"></script>
       
         <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>