Skip to main content

Crontab Generator

The Crontab Generator is a centralized tool for generating and managing all external cron entries required by the plugin.

Overview​

Navigate to GSM Middleware → Tools → Crontab Generator to access the tool.

All GSM Middleware scheduled tasks run via external cron (server crontab), not WordPress cron. This ensures reliable, precise execution regardless of site traffic.

Key Features:

  • Generates complete crontab for all plugin tasks (orders, inventory, tracking, reports)
  • Configurable intervals and time windows
  • Automatic site distribution across time slots
  • Change detection alerts when crontab needs regeneration
  • Copy-to-clipboard for easy server installation

Permission Required: manage_options

Why External Cron?​

WordPress cron (wp-cron.php) only fires on page loads. For a middleware that must sync on precise schedules, this is unreliable:

FeatureWordPress CronExternal Cron
Execution timingOn next page load after scheduleExact minute
ReliabilityDepends on trafficAlways runs
MonitoringLimitedServer-level alerts
Load distributionNot possibleSites spread across slots

Settings​

PHP Binary Path​

Full path to the PHP executable on your server. Required for generating crontab entries.

Common paths:

  • /usr/bin/php — Default on most Linux servers
  • /usr/bin/php8.2 — Specific PHP version
  • /usr/local/bin/php — Some hosting providers

Click Auto-Detect to attempt automatic detection.

Order Export Interval​

How often order sync runs, in minutes.

  • Default: 60 minutes
  • Range: 5–1440 minutes
  • Sites are spread across minutes within the interval (Site 1 at :00, Site 2 at :01, etc.)

Inventory Import Interval​

How often inventory sync runs, in minutes.

  • Default: 60 minutes
  • Range: 5–1440 minutes
  • Same site distribution pattern as order exports

Tracking Import Window​

Tracking sync runs once per 24 hours during an overnight maintenance window.

  • Start Hour: 22:00 (default) — Military time
  • End Hour: 05:00 (default) — Military time
  • Sites spread evenly across the window (e.g., 3 sites over 7 hours = ~2.3 hours apart)

Schedule Timezone​

Version Added: 1.15.4

Select the server timezone for all schedule calculations:

  • US Timezones: Eastern, Central, Mountain, Pacific, Alaska, Hawaii
  • UTC — Universal Coordinated Time
  • Default: America/Chicago (Central Time)

All user-entered times (tracking window, report schedules, cleanup hour) are converted to UTC for the server crontab. The generated crontab header displays the configured timezone for reference.

BC Insert/Verify Items Intervals​

SettingDefaultDescription
BC Insert Items Interval10 minutesHow often to push orders to Business Central
BC Verify Items Interval10 minutesHow often to verify BC processing status
Queue Processor Interval5 minutesHow often to process async queue jobs

BV Metafield Sync Hour​

Version Added: 1.18.37

Configurable daily run hour for the BazaarVoice Metafield Sync cron. Only generates entries for sites with bv_metafield_sync enabled (distinct from the BV Discovery filter).

Generating the Crontab​

Step 1: Configure Settings​

  1. Set the PHP binary path
  2. Adjust intervals if needed (defaults work for most setups)
  3. Click Save Settings

Step 2: Generate​

Click Generate Crontab to produce the complete crontab output.

The generator creates entries for:

  • Order Exports — One entry per active site with order sync enabled
  • Inventory Imports — One entry per active site with inventory sync enabled
  • Tracking Imports — One entry per active site with tracking sync enabled
  • BazaarVoice Discovery Sync — One entry per site with BV Discovery enabled (configurable interval)
  • BazaarVoice SFTP Sync — One entry per site with BV SFTP sync enabled (typically daily)
  • BazaarVoice Metafield Sync — One entry per site with BV Metafield Sync enabled (daily)
  • BC Insert Items — Every 10 minutes (configurable), pushes orders to Business Central
  • BC Verify Items — Every 10 minutes (configurable), verifies BC processing status
  • Email Reports — One entry per enabled report based on its schedule
  • Queue Processor — Every 5 minutes, processes webhook jobs, inventory sync jobs, PayArc dispute jobs, and queue maintenance
  • Log Cleanup — Daily at 3 AM

Step 3: Install on Server​

  1. Copy the generated output (click Copy to Clipboard)
  2. SSH into your server
  3. Run crontab -e
  4. Paste the entries
  5. Save and exit

Step 4: Confirm Installation​

Click Mark as Installed to record that the current crontab has been applied to the server. This enables change detection.

Change Detection​

The tool tracks two MD5 hashes:

  • Settings Hash — Hash of current cron settings
  • Installed Hash — Hash of last crontab confirmed as installed

When settings change (new sites added, intervals modified, reports updated), a yellow notification banner appears:

⚠️ Crontab settings have changed since last installation. Please regenerate and update your server crontab.

This alerts you to regenerate and reinstall the crontab.

Generated Output Format​

The crontab output includes comments for clarity:

# ============================================
# GSM Middleware Crontab
# Generated: 2026-04-09 14:30:00
# Timezone: America/Chicago (Central Time)
# ============================================

# --- Order Exports (every 60 minutes) ---
# Site 1 - Main Store
0 * * * * /usr/bin/php8.2 /var/www/html/wp-content/plugins/gsm-middleware/cron-order-export.php site_id=1
# Site 2 - Secondary Store
1 * * * * /usr/bin/php8.2 /var/www/html/wp-content/plugins/gsm-middleware/cron-order-export.php site_id=2

# --- Inventory Imports (every 60 minutes) ---
# Site 1 - Main Store
0 * * * * /usr/bin/php8.2 /var/www/html/wp-content/plugins/gsm-middleware/cron-inventory-import.php site_id=1
# Site 2 - Secondary Store
1 * * * * /usr/bin/php8.2 /var/www/html/wp-content/plugins/gsm-middleware/cron-inventory-import.php site_id=2

# --- Tracking Imports (overnight window 22:00 - 05:00) ---
# Site 1 - Main Store (22:00)
0 22 * * * /usr/bin/php8.2 /var/www/html/wp-content/plugins/gsm-middleware/cron-tracking-import.php site_id=1
# Site 2 - Secondary Store (00:40)
40 0 * * * /usr/bin/php8.2 /var/www/html/wp-content/plugins/gsm-middleware/cron-tracking-import.php site_id=2

# --- BazaarVoice Discovery Sync (every 24 hours) ---
# Site 1 - Main Store
0 6 * * * /usr/bin/php8.2 /var/www/html/wp-content/plugins/gsm-middleware/cron/bv-discovery-sync.php --site=1

# --- BazaarVoice SFTP Sync (daily) ---
# Site 1 - Main Store
0 7 * * * /usr/bin/php8.2 /var/www/html/wp-content/plugins/gsm-middleware/cron/bv-sftp-sync.php --site=1

# --- BazaarVoice Metafield Sync (daily) ---
# Site 1 - Main Store
0 9 * * * /usr/bin/php8.2 /var/www/html/wp-content/plugins/gsm-middleware/cron/bv-metafield-sync.php --site=1

# --- BC Insert Items (every 10 minutes) ---
*/10 * * * * /usr/bin/php8.2 /var/www/html/wp-content/plugins/gsm-middleware/cron/bc-insert-items.php

# --- BC Verify Items (every 10 minutes) ---
*/10 * * * * /usr/bin/php8.2 /var/www/html/wp-content/plugins/gsm-middleware/cron/bc-verify-items.php

# --- Email Reports ---
# Expedited Shipping (daily at 08:00)
0 8 * * * /usr/bin/php8.2 /var/www/html/wp-content/plugins/gsm-middleware/cron/reports.php report=expedited_shipping

# --- Queue Processor (every 5 minutes) ---
*/5 * * * * /usr/bin/php8.2 /var/www/html/wp-content/plugins/gsm-middleware/cron/process-queue.php

# --- Log Cleanup (daily at 03:00) ---
0 3 * * * /usr/bin/php8.2 /var/www/html/wp-content/plugins/gsm-middleware/cron/cleanup-logs.php

Site Distribution​

Sites are automatically distributed across time slots to prevent overloading:

Order and Inventory Sync​

With a 60-minute interval and 5 sites:

  • Site 1: minute 0 (e.g., 1:00, 2:00, 3:00…)
  • Site 2: minute 1 (e.g., 1:01, 2:01, 3:01…)
  • Site 3: minute 2
  • Site 4: minute 3
  • Site 5: minute 4

Tracking Sync​

Spread evenly across the overnight window:

  • 3 sites over 7 hours (22:00–05:00) = ~2.3 hours apart
  • Site 1: 22:00
  • Site 2: 00:20
  • Site 3: 02:40

Filtering​

The generator only includes:

  • Active sites (is_active = 1)
  • Sites with the specific sync type enabled (checks sync_settings JSON field)

Inactive sites or sites with a sync type disabled are excluded from the corresponding section.

Troubleshooting​

"PHP Path Not Set"​

Set the PHP binary path in the settings form. Use which php on your server to find the correct path.

Crontab Not Running​

  1. Verify crontab is installed: crontab -l
  2. Check PHP path is correct and executable
  3. Verify plugin directory path in generated entries
  4. Check server cron log: grep CRON /var/log/syslog

Sites Missing from Output​

  • Verify the site is active in the Sites page
  • Check that the specific sync type is enabled in the site's sync settings tab