Scheduling Events in ColdFusion

The ColdFusion server maintains a list of events or tasks that can be scheduled to run periodically. Scheduling events in ColdFusion is similar to using the Unix operating system's cron table or Windows' AT command. Each event corresponds to a ColdFusion template file that gets executed according to the parameters set in the schedule.

The execution mechanism in ColdFusion is restricted to HTTP calls. A <cfhttp> agent calls the scheduled template and runs the file at the designated time. Any template that can be run by a Web browser can be executed using the scheduler, thereby covering just about everything you might want ColdFusion to achieve.

<cfhttp> and HTTP agents are covered in Chapter 42, "Other Internet Protocols."

Scheduling a Task

You can schedule individual tasks by using the Web-based ColdFusion Administrator application, or programmatically by using the <cfschedule> tag. Schedule information is loaded into the ColdFusion server memory. The active schedule list is also reloaded when the ColdFusion service is cycled.

ColdFusion Administrator provides an easy-to-use interface for maintaining, creating, and deleting schedules through a Web browser. All the features of scheduling are available through a series of form inputs, including a very convenient list of currently active schedules. However, you need access to Administrator to view these options. Access may not be available in many hosting environments, especially those maintained by ISPs and commercial ColdFusion hosting partners.

<cfschedule> provides you with access to all the features of ColdFusion Administrator. You can update, run, or delete individual schedules according to the chosen ACTION. The tag attributes are intuitive and correspond directly to the form fields in Administrator. However, you cannot use <cfschedule> to display a listing of currently active schedules.

For example, the Crazy Date schedule that follows should run for three years, firing off every day and running the tasks/partydate.cfm application page with a time-out of 300 seconds:

 <!--- Set up the Crazy Date schedule ---> <cfschedule action="UPDATE"             task="crazy date"             operation="HTTPRequest"             url="http://127.0.0.1/tasks/partydate.cfm"             startdate="12/12/00"             starttime="03:45 AM"             enddate="12/12/03"             interval="Daily"             requesttimeout="300"> 

The scheduler's refresh interval defaults to 15 minutes and can be modified through ColdFusion Administrator. This interval determines how often the scheduler checks the saved scheduled task list for new tasks. Valid intervals are:

• once

• daily

• weekly

• monthly

• Number of seconds (the minimum is 60)

Upon refresh, the scheduler updates the active task list as required. The list is then regularly inspected to determine which tasks are ready to be run.

CAUTION

Scheduled events correspond to an application page that must necessarily reside on a mapped area of the Web server. The schedule agent uses <cfhttp> to execute the task pages on the Web server, just like any other pages in the Web application.

The agent is not sophisticated enough to log in to an application with session management, so the application page is essentially exposed to anyone with a Web browser. Depending on the type of task you are scheduling, it may not be appropriate for everybody using a browser to be able to execute the event page.

A good practice is to secure a nominated "tasks" directory to allow only the local ColdFusion server access to run pages. Using the Web server security for virtual directories, you can restrict access to the Web server's own IP address or 127.0.0.1 for the tasks directory. Alternatively, you can include code like the following at the beginning of the event application page to check the HTTP agent for appropriate CGI variables:

 <cfif CGI.remote_host NEQ "127.0.0.1">  <cfabort showerror="Go away, bad person!"> </cfif> 

Publishing to Static Pages

ColdFusion applications serve dynamic content, which is generated upon each request. Sometimes it may be preferable to save static versions of the content, the advantage being that they'll perform better, but the cost is that they won't always be up to date.

You can use scheduled events to publish static Web pages. Normally, a scheduled event is executed, performs some task, and doesn't bother about output to the screen because no one is there to see it work. However, <cfschedule> can be instructed to save the results of the event page output and write them to the file system, as follows:

 <!--- Publish static HTML for the wind section ---> <cfschedule action="update"             task="Orchestral"             operation="HTTPRequest"             url="http://127.0.0.1/tasks/flautist.cfm"             startdate="8/7/99"             starttime="01:30 AM"             interval="3600"             resolveurl="Yes"             publish="Yes"             file="theflute.htm"             path="c:\inetpub\wwwroot\windup"             requesttimeout="600"> 

Setting publish="Yes", with appropriate directory path and file attributes, directs the scheduled event to save the resulting output of its application template to disk. resolveurl behaves similarly to the attribute in <cfhttp>. For example, publishing using a scheduled task is ideal for building long-running reports that can be executed during quiet server periods. In addition, dynamic content that is updated infrequently can be published periodically using <cfschedule> to save hits on the database.

<cfhttp> and HTTP agents will be covered in Chapter 43, "Other Internet Protocols."

Running a Scheduled Event

Scheduled events usually run when they are scheduled to, as you'd expect. If need be, ColdFusion allows you to trigger a scheduled event so that it runs on demand. To execute a scheduled event, use action="run", as seen here:

 <!--- Run now ---> <cfschedule action="run"             task="Orchestral"> 

Deleting a Scheduled Event

Scheduled tasks may be deleted by using ColdFusion Administrator, or with <cfschedule> and action="delete", as seen here:

 <!--- delete it ---> <cfschedule action="delete"             task="orchestral"> 

Logging Scheduled Events

The scheduled event's task name, time stamp, and success or failure status are written to log files for future reference.

For example, a log entry for the Orchestral task mentioned earlier might reveal the following:

[View full width]
 "Information","TID=960","12/04/00","03:30:00","Scheduled action Orchestral, template http: //127.0.0.1/tasks/flautist.cfm submitted successfully." 

Unfortunately, the log is not terribly informative about telling you whether the event was executed successfully. If a task failed and generated a ColdFusion run-time error, you would expect to see the details of the error indicated in the ColdFusion application.log.