Server Settings - Scheduled Tasks

Create, manage, and monitor automated tasks for ColdFusion operations

Overview

The Scheduled Tasks page in ColdFusion Administrator enables you to automate recurring operations such as generating reports, clearing caches, processing batch jobs, calling APIs, and maintaining data. Scheduled tasks provide cron-like functionality within ColdFusion, allowing you to execute ColdFusion pages or HTTP requests at specified intervals without manual intervention.

This powerful feature eliminates the need for external cron jobs or Windows Task Scheduler for many automation scenarios. Tasks can be scheduled to run once, daily, weekly, monthly, or on custom intervals, or with cron expressions. ColdFusion logs task execution to scheduler.log and provides tools for monitoring and troubleshooting scheduled operations.

Sources: Adobe: Use the ColdFusion Administrator and Adobe: Using Scheduler.

Creating Scheduled Tasks

Task Name

  • Purpose: Unique identifier for the scheduled task
  • Requirements: The combination of task name and group must be unique
  • Best Practice: Use descriptive names that indicate purpose (e.g., "DailyReportGeneration", "HourlyDataSync")
  • Naming Convention: Consider prefixes for categorization (REPORT_, MAINT_, SYNC_)
  • Character Restrictions: Avoid special characters; use alphanumeric and underscores

Task Type

  • URL (HTTP request): ColdFusion requests a URL over HTTP when the task fires (most common)
  • Event Handler CFC: A CFC implementing CFIDE.scheduler.ITaskEventHandler whose execute method runs instead of invoking a URL
  • URL Advantages: Can include query parameters, authentication, test externally
  • Event Handler Advantages: No HTTP overhead, and the task code does not need a web-accessible URL
  • Note: There is no task type that runs a CFM file directly from a file path; "File" in the task form refers to the Publish output file

URL

  • URL Format: Full URL including protocol (http://localhost/tasks/daily-report.cfm)
  • Query Parameters: Include parameters for task configuration (url?mode=full&type=pdf)
  • Localhost Preference: Use localhost URLs to avoid external network dependencies
  • Testing: Verify the URL is accessible before creating task
  • Authentication: Consider username/password if URL requires authentication

Username and Password

  • Purpose: HTTP authentication credentials for protected URLs
  • When Needed: Only when the page you want to execute is in a secure location
  • Security Risk: Credentials are saved in the server's scheduler configuration; protect access to it
  • Best Practice: Use task-specific accounts with minimal permissions
  • Alternative: Use IP-based authentication or secret tokens in URL
  • Audit: Regularly review and rotate task credentials

Port

  • Custom Ports: Specify if running on non-standard port
  • Recommendation: Use standard ports unless specific requirement exists

Proxy Server

  • Purpose: Route task requests through proxy server
  • Format: proxyhost:proxyport
  • Use Case: Required when server must use proxy for external URLs
  • Internal Tasks: Usually not needed for localhost URLs

Schedule Types

One-Time Execution

  • Purpose: Run task once at specific date and time
  • Use Cases: Scheduled maintenance, one-time migration, event-triggered action
  • Configuration: Specify exact date and time for execution
  • Timing: Adobe advises setting a one-time task at least 15 minutes in the future
  • Verification: Check scheduler.log to confirm execution
  • Best Practice: Delete or archive completed one-time tasks

Recurring - Daily

  • Purpose: Execute task every day at the specified time
  • Single Time: Run once per day (e.g., 2:00 AM)
  • Multiple Times: Use Daily every (an interval) or a Crontime expression to run several times a day
  • Use Cases: Daily reports, nightly backups, end-of-day processing
  • Time Zone: Uses server time zone; document for multi-region deployments

Recurring - Weekly

  • Purpose: Execute task once a week
  • Time: Runs weekly at the specified time
  • Specific or Multiple Days: Use a Crontime (cron expression) schedule to control which weekdays the task runs
  • Use Cases: Weekly reports, weekend maintenance, mid-week updates
  • Best Practice: Avoid scheduling resource-intensive tasks during business hours

Recurring - Monthly

  • Purpose: Execute task once a month
  • Time: Runs monthly at the specified time
  • Multiple Days or Complex Schedules: Use a Crontime (cron expression) schedule, for example to run on the 1st and 15th
  • Month-End Consideration: Test schedules that target days 29-31 (not all months have these days)
  • Use Cases: Monthly reports, billing processes, monthly maintenance

Daily Every (Interval)

  • Purpose: Repeat the task during a day
  • Configuration: Set the interval in hours, minutes and seconds (e.g., every 30 minutes)
  • Start Time: When the repeating window begins each day
  • End Time: When the repeating window ends each day
  • Use Cases: Data synchronization, cache warming, health checks
  • Performance Impact: Frequent intervals can impact server performance
  • Recommendation: Use minimum interval of 5 minutes unless specifically required

Task Configuration Options

Start Date and Time

  • Purpose: When task execution should begin
  • Past Start Time: A recurring task with a start time in the past runs at the next interval in the future; a one-time task in the past that has not run misfires and runs immediately
  • Future Date: Schedule task to start at future date
  • Use Case: Deploy task now but activate later
  • Best Practice: Set start date for new production tasks to control activation

End Date and Time

  • Purpose: When task execution should stop
  • Optional: Leave blank for indefinite execution
  • Use Cases: Temporary data collection, limited-time processing, phased deprecation
  • Cleanup: Review and remove tasks after end date passes

Request Timeout

  • Purpose: Timeout field in the task form; helps prevent requests from stalling
  • cfschedule: The requestTimeout attribute was removed in ColdFusion (2025 release)
  • Recommendation: Set based on expected task duration plus buffer
  • Long-Running Tasks: Increase timeout for batch processing, reports
  • Safety Net: Prevents runaway tasks from consuming resources indefinitely
  • Monitoring: Tasks timing out indicate performance issues or insufficient timeout
  • Typical Values: 300 seconds (5 min) for reports, 3600 (1 hour) for batch jobs

Publish

  • Purpose: Save task output to a file
  • File Path: Specify absolute path for output file
  • Use Cases: Save generated reports, archive output, enable retrieval
  • Overwrite: Select Overwrite to replace the existing output file; leave it clear to create a new output file each time the task runs
  • File Extensions: By default the output file can only have a .txt or .log extension (more can be added in neo-cron.xml)
  • Permissions: Ensure ColdFusion has write permissions to output directory

Additional Settings

  • Crontime: Schedule with a cron expression for complex schedules
  • Group: Organize related tasks so they can be managed together
  • Priority: Integer; when more tasks are due than worker threads are free, higher-priority tasks start first (default 5)
  • Exclude: Dates on which the task should not run
  • On Misfire: What to do when a scheduled run was missed, such as fire now or invoke the handler
  • On Exception: Refire (with a retry count), Pause, or Invoke Handler when the task fails
  • On Complete: Task to run after this task completes
  • Event Handler: CFC implementing CFIDE.scheduler.ITaskEventHandler

Resolve URL

  • Purpose: Resolve internal relative URLs in published output to absolute URLs so links in the saved file work
  • Applies To: Only matters when Publish is used to save task output to a file
  • Not Redirects: This setting does not control whether HTTP redirects are followed

Chain Tasks

  • Purpose: Execute another task after this task completes
  • Chaining: Create dependencies between tasks
  • Use Case: Sequential processing (process data, then generate report)
  • Format: task:group:mode, comma-separated for several tasks
  • Restriction: You cannot chain an application-specific task after a server-specific task
  • Alternative: Consider single task that calls multiple operations

Task Management

Pausing and Resuming Tasks

  • Pause: Stop scheduled execution without deleting configuration
  • Resume: Return a paused task to its schedule
  • Use Cases: Troubleshooting, maintenance, testing
  • Where: Pause and Resume actions are in the task list
  • Best Practice: Pause tasks before making changes

Editing Tasks

  • Modification: Use the Edit icon in the task list Actions column
  • Application Tasks: Application-level tasks cannot be created or edited in the Administrator, only paused, resumed or deleted
  • Testing: Test changes in development before production
  • Documentation: Maintain change log for task modifications

Deleting Tasks

  • Permanent: Removes task and all configuration
  • Best Practice: Pause first, then delete after verification period
  • Backup: Back up neo-cron.xml before deleting tasks

Run Now

  • Purpose: Execute task immediately regardless of schedule
  • Use Cases: Testing, manual trigger, recovery from failures
  • Where: The Run icon in the task list Actions column
  • Best Practice: Use for testing before relying on schedule

Task History and Logging

Execution History

  • Administrator: The task list shows details such as last run and next run, not a per-execution history
  • History: Use scheduler.log for a record of past executions
  • Output: Use Publish to save each run's output to a file

Log Files

  • Location: ColdFusion logs directory (cfusion/logs/scheduler.log)
  • Information: Whether task submission was initiated and succeeded, the scheduled page URL, the date and time, and a task ID; misfired tasks are also logged
  • Format: Standard CF log format with timestamp and severity
  • Monitoring: Parse logs for automated alerting
  • Rotation: Logs rotate based on server logging settings

Application Logging

  • Task Code: Use cflog within scheduled task for custom logging
  • Log File: Write to dedicated log file for task operations
  • Error Tracking: Log errors with context for troubleshooting
  • Metrics: Log processing counts, durations, results

Error Handling and Notifications

Built-in Error Handling

  • Logging: scheduler.log records task submissions and misfires; log failures inside your task code for detail
  • Event Handler: An onError method in the task's event handler CFC runs when the task errors (with On Exception set to Invoke Handler)
  • Retry: Set On Exception to Refire with a retry count, or to Pause or Invoke Handler; otherwise the task runs again at its next scheduled time

Custom Error Handling

  • Try/Catch: Implement error handling in task code
  • Logging: Log errors with stack traces for debugging
  • Notifications: Send email/alerts on critical errors
  • Graceful Degradation: Handle partial failures appropriately
  • Return Codes: Use HTTP status codes to indicate success/failure

Email Notifications

  • Implementation: Add email code to task for failures
  • Threshold: Alert after consecutive failures to reduce noise
  • Information: Include error details, timestamp, task name
  • Recipients: Send to appropriate support team or monitoring system

Integration with Monitoring

  • External Monitoring: Configure health check to verify task execution
  • Dead Man's Switch: Alert if task hasn't run in expected timeframe
  • Log Monitoring: Parse scheduler.log for error patterns
  • APM Integration: Use FusionReactor or similar to track task performance

Best Practices

Production Environment

  • Use descriptive task names that clearly indicate purpose
  • Set appropriate request timeouts with reasonable buffers
  • Implement error handling and logging in all task code
  • Configure email notifications for critical task failures
  • Schedule resource-intensive tasks during off-peak hours
  • Use localhost URLs to avoid external network dependencies
  • Document all scheduled tasks including purpose and dependencies
  • Review scheduler.log regularly to identify failures or performance issues
  • Set end dates for temporary tasks to prevent orphaned jobs
  • Maintain inventory of all scheduled tasks across servers

Development and Testing

  • Test tasks using "Run Now" before relying on schedule
  • Verify task execution manually before deploying to production
  • Use different task names or schedules in dev/staging/production
  • Disable production-like schedules in development environments
  • Test error handling and timeout scenarios
  • Verify task output and logging before production deployment

Security Considerations

  • Secure task URLs with authentication or IP restrictions
  • Use task-specific accounts with minimal required permissions
  • Avoid storing sensitive credentials in task configuration
  • Consider secret tokens in URLs instead of username/password
  • Restrict access to scheduled task administration
  • Regularly audit task configurations and credentials
  • Use HTTPS for task URLs when possible
  • Implement IP whitelisting for task endpoints
  • Log all task executions for security auditing

Performance and Monitoring

  • Monitor task execution duration to identify performance degradation
  • Avoid overlapping executions of same task (use adequate intervals)
  • Use minimum 5-minute intervals for frequent tasks
  • Implement locking mechanisms for tasks that shouldn't run concurrently
  • Review server logs for task-related errors or warnings
  • Track task execution metrics (duration, records processed, success rate)
  • Set up alerts for consecutive task failures
  • Use external monitoring to verify critical tasks are running

Maintenance and Documentation

  • Document each task's purpose, schedule, and dependencies
  • Maintain change log for task configuration modifications
  • Review and clean up obsolete tasks quarterly
  • Export task configurations for backup and disaster recovery
  • Include scheduled tasks in application documentation
  • Plan for task migration during server upgrades

Common Issues and Troubleshooting

Tasks Not Running at Scheduled Time

  • Symptom: Task doesn't execute at expected time
  • Causes: Task paused, server time incorrect, ColdFusion service stopped
  • Verification: Check task is not paused, verify server time, check CF service status
  • Logs: Review scheduler.log for execution records or errors
  • Testing: Use "Run Now" to verify task can execute
  • Time Zone: Ensure server time zone matches expected schedule

Tasks Timing Out

  • Symptom: Timeout errors logged for the task
  • Cause: Task execution exceeds configured timeout
  • Solution: Increase request timeout or optimize task code
  • Investigation: Review task code for performance bottlenecks
  • Database Queries: Check for slow queries or missing indexes
  • External Calls: Verify external services are responsive

Authentication Errors

  • Symptom: 401 or 403 HTTP errors logged for the task
  • Cause: Incorrect credentials or insufficient permissions
  • Solution: Verify username/password or use alternative authentication
  • IP Restrictions: Whitelist server IP for task URLs
  • Session Issues: Ensure task URL doesn't require session state

Tasks Running Multiple Times

  • Symptom: Task executes more than once at scheduled time
  • Cause: Previous execution hasn't completed when next is triggered
  • Solution: Increase execution interval or optimize task performance
  • Locking: Implement named locks to prevent concurrent executions
  • Detection: Check scheduler.log for overlapping executions

Connection Refused Errors

  • Symptom: Task fails with connection refused error
  • Cause: Web server not running or URL incorrect
  • Verification: Test URL in browser or curl from CF server
  • Localhost: Ensure localhost resolves and web server listens on specified port
  • Firewall: Verify no firewall blocking localhost connections

Tasks Not Appearing After Server Restart

  • Symptom: Scheduled tasks missing after CF restart
  • Cause: Configuration file corruption or migration issue
  • Location: Tasks stored in neo-cron.xml (cfusion/lib directory)
  • Recovery: Restore from backup or recreate tasks
  • Prevention: Regularly backup neo-cron.xml file

Output File Not Created

  • Symptom: Publish enabled but file not written
  • Cause: Permission errors or invalid path
  • Solution: Verify CF has write permissions to output directory
  • Path: Ensure absolute path is correct and directory exists
  • Testing: Use simple test task to verify publish functionality

Programmatic Task Management

Use the cfschedule tag to create, manage, and execute scheduled tasks programmatically.

Creating Tasks Programmatically

Creating and Managing Scheduled Tasks
// Create or update a scheduled task
schedule action="update"
  task="MyScheduledTask"
  operation="HTTPRequest"
  url="http://localhost/tasks/my-task.cfm"
  startDate="01/01/2025"
  startTime="2:00 AM"
  interval="daily";

// Run existing task immediately
schedule action="run" task="MyScheduledTask";

// Delete task
schedule action="delete" task="MyScheduledTask";
<!--- Create or update a scheduled task --->
<cfschedule
  action="update"
  task="MyScheduledTask"
  operation="HTTPRequest"
  url="http://localhost/tasks/my-task.cfm"
  startDate="01/01/2025"
  startTime="2:00 AM"
  interval="daily">

<!--- Run existing task immediately --->
<cfschedule
  action="run"
  task="MyScheduledTask">

<!--- Delete task --->
<cfschedule
  action="delete"
  task="MyScheduledTask">

Listing All Tasks

List All Scheduled Tasks
// Get list of all scheduled tasks
schedule action="list" result="tasks";

// Display task information
writeDump(tasks);

// Loop through tasks (result is a query)
for (i = 1; i <= tasks.recordCount; i++) {
  writeOutput("Task: #tasks.task[i]# - Status: #tasks.status[i]#<br>");
}
<!--- Get list of all scheduled tasks --->
<cfschedule
  action="list"
  result="tasks">

<!--- Display task information --->
<cfdump var="#tasks#">

<!--- Loop through tasks --->
<cfloop query="tasks">
  <cfoutput>Task: #tasks.task# - Status: #tasks.status#<br></cfoutput>
</cfloop>

Advanced Patterns

Distributed Task Management

  • Tasks are stored per instance (neo-cron.xml); a task defined on every node runs on every node
  • The scheduler's Cluster option (a JDBC job store in a shared data source, set up on the Scheduled Tasks page) provides load balancing and fail-over; clustered servers must have the same system time. Clustering is a ColdFusion Enterprise feature (also in the Developer and Trial editions, not Standard) (Source: Charlie Arehart)
  • Without it, use database flags to ensure single execution across cluster
  • Implement leader election for critical tasks
  • Consider centralized scheduler for complex orchestration

Task Coordination

  • Use database tables to track task status and prevent conflicts
  • Implement named locks for tasks that modify shared resources
  • Create task dependencies using database flags or file markers
  • Use message queues for complex task workflows

Health Monitoring

  • Create heartbeat tasks that update database timestamps
  • Monitor last execution time to detect stuck or failing tasks
  • Implement watchdog tasks that verify other tasks are running
  • Use external monitoring to alert on task failures

Related Resources

Server Settings - Scheduled Tasks | ColdFusion Administrator | CFGuide