Queue Page

The Queue page provides a centralized view of all asynchronous jobs processed by the custom queue system, with powerful filtering, search, and detailed inspection capabilities.

Overview

Navigate to Queue in the WordPress admin menu to view and monitor jobs from the rm_queue table. This includes inventory sync jobs, product webhook processing, PayArc dispute processing, and any other queued tasks.

Key Features:

• 📊 Unified View - See all queue jobs across all sites in one place
• 🔍 Advanced Filtering - Filter by status, job type, and site
• 🔎 Quick Search - Search by job type, error message, or reference ID
• 📄 Pagination - 20 jobs per page for fast loading
• 👁️ Job Details - View full payload, timestamps, and error messages in modal
• ▶️ Process Individual Jobs - Manually trigger processing of pending or failed jobs
• 🎨 Status Badges - Color-coded status and priority indicators

Interface Elements

Filter Bar

The top filter bar provides multiple ways to narrow down your job list:

Search Field

• Search for specific jobs by:
  • Job type (e.g., inventory_sync, product_webhook)
  • Error message text
  • Reference ID (idempotency key)
• Press Enter or click Search button to apply

Status Filter

• All Statuses - Show all jobs
• Pending - Jobs waiting to be processed
• Processing - Jobs currently being worked on
• Completed - Successfully finished jobs
• Failed - Jobs that encountered errors

Job Type Filter

• Dynamically populated from available job types in the database
• Examples: inventory_sync, product_webhook, process_payarc_dispute

Site Filter

• All Sites - View jobs from all stores
• Specific Site - Filter by individual store (shows site ID and name)
• Dropdown populated from active sites

Queue Table

The main table displays 20 jobs per page with the following columns:

Column	Description
ID	Unique queue job identifier
Job Type	Type of job (displayed as code)
Site	Store name (from rm_sites join)
Priority	Color-coded priority badge (1-10, higher = more important)
Status	Color-coded badge: Pending/Processing/Completed/Failed
Attempts	Number of processing attempts
Created	When the job was enqueued
Scheduled	When the job is scheduled for next processing
Error	Truncated error message (hover for full text)
Actions	View button to open details modal; Process button for pending/failed jobs

Status Badges

Jobs display colored status badges:

• 🟡 Pending (Amber) - Waiting to be processed
• 🔵 Processing (Cyan) - Currently being worked on
• 🟢 Completed (Green) - Successfully finished
• 🔴 Failed (Red) - Encountered an error

Priority Badges

Priority values are color-coded:

• 🔴 8-10 (Red) - High priority (e.g., dispute processing)
• 🟡 5-7 (Amber) - Medium priority (e.g., inventory sync)
• 🟢 1-4 (Green) - Low priority

Pagination Controls

Bottom controls for navigating through job pages:

• Previous button - Go to previous page
• Page X of Y - Current page indicator
• Next button - Go to next page
• Showing X of Y jobs - Total job count

Job Details Modal

Click View on any job to open the detailed job information modal.

Job Details Card

Displays core job information:

• Job ID
• Job type (as code)
• Site name
• Reference ID (idempotency key)
• Status badge
• Priority badge
• Attempt count

Timestamps Card

Shows all lifecycle timestamps:

• Created at
• Scheduled at
• Started at
• Completed at
• Failed at

Error Message Section

If the job has an error, it's displayed in a red-bordered box with monospace formatting for easy reading.

Payload Section

The full JSON payload is displayed in a dark-themed code block (#1e1e1e background) with syntax-friendly formatting. The payload is automatically pretty-printed if it's valid JSON.

Common Workflows

Monitoring Failed Jobs

1. Set Status filter to Failed
2. Review error messages in the table
3. Click View to inspect the full payload and error
4. Check attempt count to see how many retries occurred
5. Click Process to retry the job immediately

Processing Individual Jobs

You can manually trigger processing for any pending or failed job:

1. Find the job in the queue table (use filters to narrow down)
2. Click the Process button in the row — or open the job detail modal and click Process Now
3. The button shows a busy spinner while the job is being processed
4. On completion, the table automatically refreshes to show updated status
5. If the job fails, the error message is displayed and the attempt count increases

note

Only jobs in Pending or Failed status can be processed. Completed and currently-processing jobs do not show the Process button.

Checking Job Processing Status

1. Set Status filter to Processing
2. View which jobs are currently being worked on
3. Verify the started_at timestamp is recent (jobs processing for > 30 minutes may be stuck)

Investigating Specific Job Types

1. Select a specific job type from the Job Type filter
2. View all jobs of that type across all sites
3. Useful for debugging specific sync issues

Finding Jobs by Reference ID

1. Enter the reference ID (event ID / idempotency key) in the search field
2. Press Enter to find the matching job
3. Useful for tracking a specific webhook through the queue

Queue System Details

The queue system provides reliable asynchronous job processing:

• Priority-based processing - Higher priority jobs (1-10) are processed first
• Exponential backoff - Failed jobs retry with increasing delays (2^n minutes)
• Stuck job detection - Jobs processing for > 30 minutes are automatically reset
• Automatic cleanup - Completed jobs are retained for 7 days

Job Types

Job Type	Priority	Description
product_webhook	8	Process BigCommerce/WooCommerce product webhooks
inventory_sync	5	Full inventory sync for a site
process_payarc_dispute	5	Process PayArc dispute webhook

Processing

Queue jobs are processed by external cron running cron/process-queue.php every 5 minutes (configurable via Crontab Generator). Individual jobs can also be processed on-demand from the Queue admin page via the Process button.

REST API

The Queue page is powered by the following REST API endpoints:

GET /gsm-middleware/v1/queue

Returns a paginated list of queue jobs.

Parameters:

• page (integer, default: 1) - Page number
• per_page (integer, default: 20) - Items per page
• search (string) - Search by job type, error message, or reference ID
• status (string) - Filter by status: pending, processing, completed, failed
• job_type (string) - Filter by job type
• site_id (integer) - Filter by site ID

Response:

{
  "items": [],
  "total": 150,
  "job_types": ["inventory_sync", "product_webhook", "process_payarc_dispute"]
}

GET /gsm-middleware/v1/queue/{id}

Returns a single queue job with full payload.

Response:

{
  "id": 42,
  "job_type": "inventory_sync",
  "payload": "...",
  "priority": 5,
  "site_id": 1,
  "site_name": "Main Store",
  "reference_id": "evt_abc123",
  "status": "completed",
  "attempts": 1,
  "error_message": null,
  "created_at": "2026-04-09 12:00:00",
  "scheduled_at": null,
  "started_at": "2026-04-09 12:01:00",
  "completed_at": "2026-04-09 12:01:05",
  "failed_at": null
}

POST /gsm-middleware/v1/queue/{id}/process

Process a single queue job on-demand. Only jobs in pending or failed status can be processed.

The endpoint routes to the correct handler based on job_type:

• product_webhook → Product_Webhook_Handler::process_webhook_job()
• process_payarc_dispute → Dispute_Processor::process_from_queue_job()
• inventory_sync → Inventory_Sync_Coordinator::run_site_sync()

Success Response (200):

{
  "success": true,
  "message": "Job #42 processed successfully.",
  "status": "completed"
}

Failure Response (200):

{
  "success": false,
  "message": "Job #42 failed: Connection timeout",
  "status": "failed",
  "error": "Connection timeout"
}

Error Response (422) — not processable:

{
  "code": "gsm_queue_job_not_processable",
  "message": "Job cannot be processed. Current status: completed. Only pending or failed jobs can be processed."
}

DELETE /gsm-middleware/v1/queue/{id}

Delete a single queue job. Jobs currently in processing status cannot be deleted.

Success Response (200):

{
  "success": true,
  "message": "Job #42 deleted successfully."
}

Error Response (422) — currently processing:

{
  "code": "gsm_queue_job_processing",
  "message": "Cannot delete a job that is currently processing."
}

Technical Details

Files

File	Purpose
src/Admin/Queue_Page.php	Admin page class (enqueue scripts, render div)
src/API/Queue_REST_Controller.php	REST API controller for queue data
assets/js/queue.jsx	React entry point
assets/js/components/QueueViewer.jsx	Main React component
build/queue.js	Compiled bundle
build/queue.asset.php	WordPress asset manifest