diff --git a/docs/plugins/development/background-jobs.md b/docs/plugins/development/background-jobs.md index 3921661c0..d51981b9e 100644 --- a/docs/plugins/development/background-jobs.md +++ b/docs/plugins/development/background-jobs.md @@ -30,20 +30,16 @@ class MyTestJob(JobRunner): You can schedule the background job from within your code (e.g. from a model's `save()` method or a view) by calling `MyTestJob.enqueue()`. This method passes through all arguments to `Job.enqueue()`. However, no `name` argument must be passed, as the background job name will be used instead. !!! tip - A set of predefined intervals can be used from `core.choices.JobIntervalChoices`. + A set of predefined intervals is available at `core.choices.JobIntervalChoices` for convenience. ### Attributes -`JobRunner` attributes are defined under a class named `Meta` within the job. These are optional (unless specified otherwise), but encouraged. +`JobRunner` attributes are defined under a class named `Meta` within the job. These are optional, but encouraged. #### `name` This is the human-friendly names of your background job. If omitted, the class name will be used. -#### `system_interval` *(required for system jobs)* - -When the `JobRunner` is defined as [system job](#system-jobs), this attribute controls the interval of the scheduled job. If the interval evaluates to `False` (i.e. set to `0` or `None`), the job won't be scheduled. - ### Scheduled Jobs As described above, jobs can be scheduled for immediate execution or at any later time using the `enqueue()` method. However, for management purposes, the `enqueue_once()` method allows a job to be scheduled exactly once avoiding duplicates. If a job is already scheduled for a particular instance, a second one won't be scheduled, respecting thread safety. An example use case would be to schedule a periodic task that is bound to an instance in general, but not to any event of that instance (such as updates). The parameters of the `enqueue_once()` method are identical to those of `enqueue()`. @@ -73,22 +69,21 @@ class MyModel(NetBoxModel): ### System Jobs -Some plugins may implement background jobs that are decoupled from any object and the request-response cycle. Typical use cases would be housekeeping tasks or synchronization jobs. These can be created using *system jobs*. The `JobRunner` class has everything included to provide this type of job as well. Just add the appropriate metadata to let NetBox schedule all background jobs automatically. - -!!! info - All system jobs are automatically scheduled just before the `./manage.py rqworker` command is started and the job queue is processed. The schedules are also checked at each restart of this process. +Some plugins may implement background jobs that are decoupled from the request/response cycle. Typical use cases would be housekeeping tasks or synchronization jobs. These can be registered as _system jobs_ using the `system_job()` decorator. The job interval must be passed as an integer (in minutes) when registering a system job. System jobs are scheduled automatically when the RQ worker (`manage.py rqworker`) is run. #### Example ```python title="jobs.py" from core.choices import JobIntervalChoices -from netbox.jobs import JobRunner +from netbox.jobs import JobRunner, system_job from .models import MyModel +# Specify a predefined choice or an integer indicating +# the number of minutes between job executions +@system_job(interval=JobIntervalChoices.INTERVAL_HOURLY) class MyHousekeepingJob(JobRunner): class Meta: name = "My Housekeeping Job" - system_interval = JobIntervalChoices.INTERVAL_HOURLY # or integer for n minutes def run(self, *args, **kwargs): MyModel.objects.filter(foo='bar').delete() @@ -98,6 +93,9 @@ system_jobs = ( ) ``` +!!! note + Ensure that any system jobs are imported on initialization. Otherwise, they won't be registered. This can be achieved by extending the PluginConfig's `ready()` method. + ## Task queues Three task queues of differing priority are defined by default: