NeoAnd/netbox
1
0
Fork 0
mirror of https://github.com/netbox-community/netbox.git synced 2025-07-30 04:16:24 -06:00
Code Issues Actions 10 Packages Projects Releases Wiki Activity

Update documentation

Browse Source
This commit is contained in:
Jeremy Stretch 2024-10-30 14:56:58 -04:00
parent 6b192c9ae8
commit 89a976f5b8
1 changed files with 10 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
docs/plugins/development/background-jobs.md
View File

@ -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. 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 !!! 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 ### 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` #### `name`
This is the human-friendly names of your background job. If omitted, the class name will be used. 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 ### 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()`. 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 ### 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. 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.
!!! 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.
#### Example #### Example
```python title="jobs.py" ```python title="jobs.py"
from core.choices import JobIntervalChoices from core.choices import JobIntervalChoices
from netbox.jobs import JobRunner from netbox.jobs import JobRunner, system_job
from .models import MyModel 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 MyHousekeepingJob(JobRunner):
class Meta: class Meta:
name = "My Housekeeping Job" name = "My Housekeeping Job"
system_interval = JobIntervalChoices.INTERVAL_HOURLY # or integer for n minutes
def run(self, *args, **kwargs): def run(self, *args, **kwargs):
MyModel.objects.filter(foo='bar').delete() 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 ## Task queues
Three task queues of differing priority are defined by default: Three task queues of differing priority are defined by default: