Queue Management

The Woo-NetSuite integration uses a robust queue system to handle background synchronization tasks. This ensures your site remains fast and responsive while processing potentially hundreds of sync operations.

Queue System Overview

The queue system provides:

• Asynchronous Processing: Sync jobs run in background without blocking user actions
• Automatic Retry: Failed jobs automatically retry with exponential backoff
• Priority Management: Critical tasks processed first
• Error Handling: Comprehensive error logging and recovery
• Rate Limiting: Prevents API throttling with intelligent request pacing
• Manual Control: Admin interface to manage queue jobs
• Monitoring: Real-time queue status and performance metrics

How the Queue Works

1. Job Creation: Action triggers a sync need (e.g., new order placed)
2. Queue Job: Job added to queue database table with metadata
3. Cron Pickup: WordPress cron picks up pending jobs
4. Job Processing: Worker processes job (API call to NetSuite)
5. Result Handling:
   • Success: Job marked complete, removed from queue
   • Failure: Job marked failed, scheduled for retry
6. Retry Logic: Failed jobs retry up to max attempts
7. Final State: Job either completes or reaches max retries

Queue Job Types

Different types of jobs with different priorities:

Job Type	Priority	Description	Typical Volume
Order Sync	High	Sync new/updated orders to NetSuite	Frequent
Customer Sync	High	Create/update customer records	Moderate
Fulfillment Check	Medium	Check for order fulfillments	Frequent
Inventory Sync	Medium	Update product stock levels	High (bulk)
Refund Sync	High	Create credit memos for refunds	Low
Status Update	Low	Sync status changes between systems	Moderate

Queue Configuration

Queue Settings

Configure queue behavior:

Setting	Default	Description
Enable Queue	Yes	Use background queue vs. immediate processing
Batch Size	10	Jobs processed per batch
Max Retry Attempts	3	How many times to retry failed jobs
Retry Delay	300 seconds	Initial delay before first retry
Retry Backoff Multiplier	2	Multiply delay by this each retry (exponential backoff)
Job Timeout	60 seconds	Max time for single job execution
Concurrent Workers	1	Number of parallel queue processors
Failed Job Retention	30 days	How long to keep failed job records

Configure in: Settings > Advanced > Queue Settings

Priority Configuration

Customize job priorities:

1. Navigate to Settings > Advanced > Queue Priorities
2. Drag and drop job types to reorder priority
3. Higher position = higher priority
4. Save changes

Queue Dashboard

Monitor and manage the queue:

1. Navigate to WooCommerce > NetSuite > Queue
2. View queue overview dashboard

Dashboard Sections

Queue Statistics:

• Total pending jobs
• Jobs processing currently
• Failed jobs (last 24 hours)
• Average processing time
• Queue health status

Recent Jobs:

• Last 50 queue jobs
• Job type, status, created time
• Processing time
• Error messages (if failed)

Quick Actions:

• Process Queue Now
• Retry All Failed Jobs
• Clear Completed Jobs
• Pause Queue Processing

Managing Queue Jobs

View Job Details

1. In Queue Dashboard, click on any job
2. View detailed information:
   • Job ID and type
   • Priority level
   • Created date/time
   • Scheduled processing time
   • Attempt count
   • Job payload (data being processed)
   • Error messages (if failed)
   • API request/response (if debug logging enabled)

Individual Job Actions

Available actions for each job:

Action	Description	When to Use
Process Now	Immediately execute this job	Urgent job stuck in queue
Retry	Retry failed job (resets attempt count)	Temporary issue resolved
Delete	Remove job from queue	Invalid job or duplicate
View Log	See detailed execution log	Debugging failed job
Edit Priority	Change job priority	Increase/decrease urgency

Bulk Actions

Perform actions on multiple jobs:

1. In Queue Dashboard, filter jobs (by type, status, date)
2. Select multiple jobs using checkboxes
3. Choose bulk action:
   • Process Selected
   • Retry Selected
   • Delete Selected
   • Change Priority
4. Click Apply

Failed Jobs

Viewing Failed Jobs

1. Navigate to Queue Dashboard
2. Click Failed Jobs tab
3. View all jobs that reached max retry attempts
4. Filter by date, job type

Common Failure Reasons

Error Type	Cause	Resolution
Authentication Failed	Invalid NetSuite credentials	Verify credentials in settings, test connection
Record Not Found	NetSuite record doesn’t exist	Verify record ID, may need to recreate
Validation Error	Required field missing or invalid	Check data in WooCommerce, ensure required fields present
Rate Limit Exceeded	Too many API requests	Reduce batch size or increase delays
Timeout	Job took too long	Increase job timeout setting
Network Error	Connection to NetSuite failed	Temporary issue, retry job

Retry Failed Jobs

Options for retrying failed jobs:

1. Retry Individual Job: Click Retry button on specific job
2. Retry All Failed: Click “Retry All Failed Jobs” in dashboard
3. Auto-Retry: Enable automatic retry of failed jobs after X hours

Failed Job Notifications

Get notified of job failures:

1. Go to Settings > Advanced > Queue Notifications
2. Enable Failed Job Notifications
3. Enter email address(es) to notify
4. Configure threshold (e.g., notify after 5 failures)
5. Save settings

Queue Performance

Processing Speed

Factors affecting queue processing speed:

• Batch Size: Larger batches = faster overall, but longer per batch
• API Limits: NetSuite rate limits constrain maximum speed
• Job Complexity: Orders with many line items take longer
• Server Resources: CPU and memory affect processing
• Network Latency: Distance to NetSuite servers

Optimizing Queue Performance

Optimization	How to Implement	Impact
Increase Batch Size	Settings > Queue > Batch Size (try 20-50)	Process more jobs per cycle
Enable Caching	Settings > Advanced > Enable Caching	Reduce duplicate API calls
Optimize Cron	Use real cron instead of WP-Cron	More reliable processing
Concurrent Workers	Settings > Queue > Concurrent Workers (2-3)	Parallel processing (advanced)
Schedule Off-Peak	Process bulk jobs during low-traffic hours	Avoid site slowdown

Monitoring Performance

Track queue performance metrics:

1. Navigate to Queue Dashboard > Performance tab
2. View charts:
   • Jobs processed per hour
   • Average processing time
   • Success vs. failure rate
   • Queue backlog over time
3. Identify bottlenecks and trends

WP-CLI Queue Commands

Manage queue via command line:

# View queue status
wp woons queue status

# Process pending jobs
wp woons queue process

# Process specific number of jobs
wp woons queue process --limit=50

# Process jobs of specific type
wp woons queue process --type=order

# View failed jobs
wp woons queue failed

# Retry all failed jobs
wp woons queue retry

# Clear completed jobs
wp woons queue clear --status=completed

# Clear all jobs (use with caution!)
wp woons queue clear --all

# View queue statistics
wp woons queue stats

Real Cron vs. WP-Cron

WP-Cron (Default)

Pros:

• No server configuration needed
• Works on shared hosting
• Automatic setup

Cons:

• Requires site visitors to trigger
• Inconsistent timing
• Can miss scheduled tasks on low-traffic sites

Real Cron (Recommended)

Pros:

• Reliable, consistent execution
• Precise timing
• Independent of site traffic
• Better for high-volume syncing

Setup:

1. Disable WP-Cron in wp-config.php:

   define('DISABLE_WP_CRON', true);

2. Add system cron job:

   */5 * * * * wget -q -O - https://yoursite.com/wp-cron.php?doing_wp_cron >/dev/null 2>&1

3. This runs every 5 minutes (adjust as needed)

Queue Database

Queue Table Structure

Jobs stored in custom database table:

Column	Type	Description
id	BIGINT	Unique job ID
job_type	VARCHAR	Type of job (order, customer, etc)
priority	INT	Job priority (1=highest)
status	VARCHAR	pending, processing, completed, failed
payload	LONGTEXT	Job data (JSON)
attempts	INT	Number of processing attempts
created_at	DATETIME	Job creation time
scheduled_at	DATETIME	When to process
completed_at	DATETIME	Completion time
error_message	TEXT	Error details (if failed)

Queue Maintenance

Automatic maintenance tasks:

• Cleanup Completed: Remove completed jobs older than 7 days
• Archive Failed: Move failed jobs to archive table after 30 days
• Reset Stale: Reset “processing” jobs stuck for >1 hour
• Optimize Table: Weekly database table optimization

Configure in: Settings > Advanced > Queue Maintenance

Troubleshooting Queue Issues

Issue	Cause	Solution
Queue Not Processing	WP-Cron not running	Switch to real cron, check cron events
Jobs Stuck in Processing	Job timeout or crash	Reset stale jobs, increase timeout
Huge Queue Backlog	Processing too slow	Increase batch size, add workers
High Failure Rate	API or data issues	Check logs, fix root cause
Duplicate Jobs	Multiple job creation	Check for duplicate hooks/actions

Advanced Queue Features

Custom Job Types

// Add custom job type
add_filter('woons_queue_job_types', function($types) {
    $types['custom_sync'] = [
        'label' => 'Custom Sync',
        'priority' => 5,
        'callback' => 'my_custom_sync_handler',
    ];
    return $types;
});

// Handler function
function my_custom_sync_handler($job) {
    $data = $job['payload'];
    // Your custom sync logic
    return ['success' => true];
}

// Create custom job
do_action('woons_queue_add_job', [
    'job_type' => 'custom_sync',
    'payload' => ['custom_data' => 'value'],
    'priority' => 5,
]);

Job Hooks

// Before job processing
add_action('woons_before_job_process', function($job) {
    // Log, send notification, etc.
}, 10, 1);

// After job processing
add_action('woons_after_job_process', function($job, $result) {
    // Update external system, send webhook, etc.
}, 10, 2);

// On job failure
add_action('woons_job_failed', function($job, $error) {
    // Custom error handling, alerting, etc.
}, 10, 2);

Best Practices

• Use Real Cron: For reliable, consistent processing
• Monitor Daily: Check queue dashboard for issues
• Set Notifications: Get alerted to problems early
• Optimize Batch Size: Balance speed vs. resource usage
• Clean Regularly: Remove old completed/failed jobs
• Review Failed Jobs: Identify and fix recurring issues
• Test Retry Logic: Ensure failed jobs retry properly
• Document Custom Jobs: If adding custom job types