Sync Jobs

PBSSyncJob is a NetBox JobRunner subclass that calls the proxbox-api /pbs/sync/<resource> HTTP endpoint for each requested scope and persists the results.

Job parameters

Parameter	Value
RQ queue	RQ_QUEUE_DEFAULT (NetBox default queue)
Job timeout	7200 seconds (2 hours)
HTTP timeout	connect 5 s / read 300 s per scope call
Default scope	full

Sync scopes

Scope	Effect
full	Refresh servers, datastores, snapshots, and jobs end-to-end
datastores	Refresh datastores only
snapshots	Refresh snapshots only
jobs	Refresh PBS job records only
node	Refresh the parent node metadata only

Pass one or more scopes to PBSSyncJob.enqueue(resources=[...]). Passing nothing (or None) defaults to ["full"].

Per-scope error isolation

Each scope is called in sequence. If one scope call raises a PBSBackendError or ValueError, the error is logged and recorded in the job's data field (pbs_sync.response.stages), but remaining scopes continue to run. After all scopes are attempted, if any scope failed the job raises RuntimeError so the NetBox job UI marks it failed.

Example job data shape:

{
  "pbs_sync": {
    "params": {"resources": ["datastores", "snapshots"]},
    "runtime_seconds": 4.217,
    "response": {
      "stages": [
        {"resource": "datastores", "status": "ok", "runtime_seconds": 2.1, "response": {}},
        {"resource": "snapshots", "status": "error", "runtime_seconds": 2.1, "error": "..."}
      ]
    }
  }
}

NetBox branching integration

When PBSPluginSettings.branching_enabled = True (requires the netbox-branching plugin to be installed and active), each PBSSyncJob run:

1. Creates a new NetBox branch named <branch_name_prefix>-<job_pk>-<unix_timestamp>.
2. Passes netbox_branch_schema_id to every proxbox-api sync call so writes land in the branch schema.
3. On success, merges the branch using the configured branch_on_conflict policy (fail or acknowledge).
4. On error (any scope fails), leaves the branch open and logs a warning — the branch can be inspected or discarded manually.

Enqueuing manually

From the NetBox shell or any Django management context:

from netbox_pbs.jobs import PBSSyncJob

# Sync all scopes (default)
PBSSyncJob.enqueue()

# Sync datastores and snapshots only
PBSSyncJob.enqueue(resources=["datastores", "snapshots"])

The sync can also be triggered from the PBSServer detail page using the Run sync button in the NetBox UI.