SuiteCRM Scheduler & Cron Job Setup: The Complete Guide to Automated Tasks

The SuiteCRM Scheduler is the engine that powers everything automated in your CRM — workflow execution, inbound email checking, campaign email sending, search indexing, database maintenance, email reminders, and bounce processing. Without a properly configured Scheduler, your CRM is a static database instead of an active automation platform.

Yet “scheduler not running” is the single most common support question in SuiteCRM community forums. The fix is almost always the same: the cron job isn’t set up correctly. This guide covers everything — from initial crontab setup to managing built-in jobs, creating custom schedulers, and troubleshooting every common issue.

How the SuiteCRM Scheduler Works

SuiteCRM’s Scheduler system works in two layers:

Layer 1: The operating system cron job. Your server’s crontab runs SuiteCRM’s cron.php file every minute. This is a system-level configuration that has nothing to do with SuiteCRM’s admin interface — it’s configured in Linux’s crontab.

Layer 2: SuiteCRM’s internal Scheduler. When cron.php executes, it checks the Scheduler jobs defined in Admin → Schedulers. Each job has its own schedule (every minute, hourly, daily, weekly, monthly) and active/inactive status. SuiteCRM decides which jobs are due to run and executes them.

Both layers must work correctly. If the cron job isn’t running, nothing in the Scheduler executes — no workflows fire, no emails send, no search indexes update. If the cron job runs but individual Scheduler jobs are inactive, those specific functions don’t execute.

Setting Up the Cron Job (Linux)

Step 1: Identify Your Web Server User

The cron job must run as the same user that your web server runs under. This prevents file permission conflicts between web requests and cron-triggered processes. Common web server users are www-data (Ubuntu/Debian with Apache), apache or httpd (CentOS/RHEL), nginx (if using Nginx with PHP-FPM), and nobody (some hosting configurations).

To find your web server user, check your Apache config or run a command like “ps aux” and look for the Apache or PHP-FPM processes.

Step 2: Edit the Crontab

Open the crontab for your web server user. On Ubuntu/Debian, the command is: sudo crontab -e -u www-data. On CentOS/RHEL: sudo crontab -e -u apache. Add the following line at the end of the crontab file:

The crontab entry should run every minute (represented by five asterisks), change to your SuiteCRM directory, and execute cron.php using the PHP CLI, redirecting all output to /dev/null to prevent cron email spam.

The five asterisks mean “every minute of every hour of every day of every month of every day of the week.” SuiteCRM’s internal Scheduler then determines which specific jobs actually run at each one-minute interval based on their individual schedules.

Step 3: Verify the Cron Job

After saving the crontab, verify it’s registered by listing the crontab contents for the web server user. Wait 2–3 minutes, then check Admin → Schedulers in SuiteCRM. The “Last Ran Successfully” column should show a recent timestamp. If it does, your cron is working.

SuiteCRM 8 Cron Path

For SuiteCRM 8 installations, the cron.php file is in the legacy directory. The crontab entry should point to your-suitecrm-8-path/public/legacy/cron.php instead of the root directory. This is the #1 reason cron fails after upgrading to SuiteCRM 8 — the path changes.

Allowed Cron Users

SuiteCRM verifies that the user executing cron.php is in the allowed_cron_users list in config.php. If you see the error “running as is not allowed in allowed_cron_users,” add your web server user to this array in config.php. The array should include your web server username (e.g., ‘www-data’).

Managing Scheduler Jobs

Navigate to Admin → Schedulers to view and manage all scheduled tasks. Each job shows its name and description, schedule (cron expression format), status (Active or Inactive), last successful run timestamp, and date created/modified.

Essential Scheduler Jobs

These jobs should be Active in every SuiteCRM deployment:

Run Workflow Tasks — Executes all workflow automations. Without this, no workflow rules fire. Set to run every minute or every 5 minutes.

Check Inbound Mailboxes — Polls configured IMAP accounts for new emails. Required for email-to-case creation, email archiving, and inbound email processing. Run every 2–5 minutes.

Run Nightly Process Bounced Campaign Emails — Processes bounce notifications from email campaigns. Run daily or after each campaign send.

Perform Lucene Index — Updates the full-text search index. Without this, search results become stale. Run every 15–30 minutes.

Send Email Reminders — Sends meeting and call reminder notifications to assigned users. Run every minute.

Prune Database on 1st of Month — Removes soft-deleted records from the database. Critical for performance — without this, deleted records accumulate and slow queries.

Prune SuiteCRM Feed Tables — Cleans activity feed data. Run monthly.

Prune Tracker Tables — Removes old tracking data. Run monthly.

Jobs You Can Safely Deactivate

Disable Scheduler jobs you don’t use — each active job consumes resources on every cron execution. Common candidates for deactivation include Google Calendar Sync (if you don’t use Google Calendar integration), Publish Approved Articles (if you don’t use the Knowledge Base), and Run Report Generation Scheduled Tasks (if you don’t have scheduled reports).

Scheduler Frequency Best Practices

Not all jobs need to run every minute. Stagger heavy jobs to avoid resource spikes: workflows every 1–5 minutes, email checking every 5 minutes, search indexing every 15 minutes, database cleanup monthly, and report generation during off-peak hours (overnight).

Creating Custom Scheduler Jobs

SuiteCRM lets you create custom scheduled tasks — useful for periodic data cleanup, external API synchronization, automated report generation, or any recurring process.

Method 1: Using the Extension Framework

Create a file in with any descriptive filename (e.g., myCustomJob.php). Define a function that SuiteCRM will call on schedule. The function receives no parameters and should return true on success or false on failure.

Create a corresponding language file in _us/ that defines a label for your job. The language key follows the pattern LBL_UPPERFUNCTIONNAME.

After creating both files, run Admin → Repair → Quick Repair and Rebuild. Your custom job appears in Admin → Schedulers → Create Scheduler, where you can set its schedule and activate it.

Method 2: Using Job Queue for One-Off Tasks

For tasks that should run once (not recurring), create a SchedulersJob bean in your Logic Hook or custom code. Set the job’s target, data, and execute_time. The Scheduler picks it up on the next cron execution. This is useful for background processing of heavy operations — like sending an API call after a record save without slowing down the user’s save experience.

Troubleshooting: “Scheduler Not Running”

This is the most common SuiteCRM support issue. Here’s a systematic diagnostic approach:

Check 1: Is the Cron Job Configured?

List the crontab for your web server user and verify the SuiteCRM cron entry exists. If it’s missing, add it following the setup steps above.

Check 2: Is the Cron Daemon Running?

On Linux, verify the cron service is active using systemctl status cron (Ubuntu) or systemctl status crond (CentOS). If it’s not running, start it and enable it to start on boot.

Check 3: Is the Path Correct?

The crontab entry must point to the correct SuiteCRM directory. For SuiteCRM 7, this is the root installation directory. For SuiteCRM 8, it’s the public/legacy subdirectory. A wrong path means cron.php never executes.

Check 4: Is the PHP Path Correct?

The crontab should use the CLI version of PHP, not the web server module. Run “which php” to find the correct path. On some servers, the PHP CLI binary is at /usr/bin/php; on others it’s at /usr/local/bin/php or a version-specific path like /usr/bin/php8.1.

Check 5: Are There Permission Issues?

If the cron job runs as a different user than the web server, file permission conflicts occur. SuiteCRM writes to cache/, upload/, and log files during cron execution. If these directories are owned by a different user, cron fails silently. Fix by ensuring the cron user matches the web server user, or by setting proper group permissions.

Check 6: Is the Cron User Allowed?

Check config.php for the allowed_cron_users array. If your web server user isn’t listed, SuiteCRM rejects the cron execution. The suitecrm.log file will show the error message “running as is not allowed.”

Check 7: Check the SuiteCRM Log

Open suitecrm.log and search for cron-related entries. Errors like “cron.php is CLI only” mean you’re trying to run cron via a web request instead of the command line. Errors about specific Scheduler jobs indicate the cron itself is working but individual jobs are failing.

Check 8: PHP CLI Configuration

The PHP CLI may use a different php.ini than the web server PHP. Ensure the CLI php.ini has adequate memory_limit (512M), max_execution_time (0 or 600 for CLI), and all required SuiteCRM PHP extensions loaded (especially imap, curl, and mysql).

Monitoring Scheduler Health

Don’t wait for users to report that workflows aren’t firing — monitor proactively.

Check “Last Ran Successfully” regularly. Navigate to Admin → Schedulers and verify timestamps are current. If any essential job shows an old timestamp, investigate immediately.

Set up external monitoring. Use a monitoring tool (UptimeRobot, Cronitor, or Healthchecks.io) to verify cron execution. Have cron.php trigger a heartbeat ping after each run — if the ping stops, you receive an alert.

Review suitecrm.log weekly. Search for errors, warnings, and failed job entries. Patterns in log errors often reveal underlying issues before they become visible to users.

Scheduler in Docker Environments

Running SuiteCRM in Docker requires special attention for cron. Docker containers don’t run cron by default. Two approaches work: install and run cron inside the application container (add crontab configuration to your Dockerfile and start the cron daemon alongside Apache/PHP-FPM), or use a sidecar container that executes cron.php on a timer using a lightweight scheduler like supercronic or a simple shell loop. The sidecar approach is cleaner for production — it separates web serving from background task execution.

When to Get Professional Help

Scheduler issues can cascade — a non-running cron means no workflows, no email processing, no search updates, and no database maintenance. If basic troubleshooting doesn’t resolve the issue, professional SuiteCRM support saves hours of debugging. Common escalation scenarios include cron running but specific jobs failing silently, permission conflicts after server migration or upgrade, custom Scheduler jobs not executing despite correct code, and performance degradation caused by too many concurrent Scheduler jobs.