Description

Provides a programmatic interface to the ColdFusion scheduling engine. Can run a CFML page at scheduled intervals, with the option to write the page output to a static HTML page. This feature enables you to schedule pages that publish data, such as reports, without waiting while a database transaction is performed to populate the page.

ColdFusion does not invoke Application.cfc methods, when invoking a task's event handler methods.

Note:

The requestTimeOut attribute is deprecated.

Category

Syntax

<cfschedule 
action = "run|update|pause|resume|delete|pauseall|resumeall|list" 
task = "task name" 
endDate = "date" 
endTime = "time" 
file = "filename" 
interval = "seconds" 
operation = "HTTPRequest" 
password = "password" 
path = "path to file" 
port = "port number" 
proxyPassword = "password" 
proxyPort = "port number" 
proxyServer = "host name" 
proxyUser = "user name" 
publish = "yes|no" 
requestTimeOut = "seconds" 
resolveURL = "yes|no" 
isDaily = "yes|no" 
overwrite = "yes|no" 
startDate = "date" 
startTime = "time" 
url = "URL" 
username = "user name"> 
group="group1" 
oncomplete="how to handle exception" 
eventhandler="path_to_event_handler" 
onException="refire|pause|invokeHandler" 
cronTime="time" 
repeat="number" 
priority="integer" 
exclude="date|date_range|comma-separated_dates" 
onMisfire = "" 
cluster="yes|no 
mode="server|application" 
retryCount="number" 

OR 
<cfschedule 
action = "delete" 
task = "task name"> 

OR 

<cfschedule 
action = "run" 
task = "task name"> 

OR 

<cfschedule 
action = "pauseAll" 
mode = "server|application"> 

OR 

<cfschedule 
action = "resumeAll" 
mode = "server|application"> 

OR 

<cfschedule 
action = "list" 
mode = "server|application" 
result = "res">

Note:

You can specify this tag's attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag's attribute names as structure keys.

See also

History

ColdFusion 10: Added the actions list, pauseall, and resumeall. Also, added the attributes group, onComplete, eventHandler, onException, cronTime, repeat, result, priority, exclude, onMisfire, cluster, mode, isDaily, overwrite, and retryCount.

ColdFusion MX 6.1: Changed the way intervals are calculated. The day length now reflects changes between standard and daylight saving times. The month length is now the calendar month length, not four weeks. The scheduler handles leap years correctly.

Attributes

 

Attribute

Req/Opt

Default

Description

action

Required

 

  • delete: Deletes the specified task.
  • update: Updates an existing task or creates a task, if one with the name specified by the task attribute does not exist.
  • run: Executes the specified task.
  • pause: Pauses the specified task.
  • resume: Continues executing the specified task.
  • list: Lists all the scheduled tasks.
  • pauseAll: Pauses all scheduled tasks for a particular application.
  • resumeAll: Resumes all scheduled tasks for a particular application.

task

Required

 

Name of the task.

endDate

Optional

 

Date when scheduled task ends. The default date format is mm/dd/yy.

endTime

Optional

 

Time when scheduled task ends (seconds).

file

Required if publish = "Yes"

 

Name of the file in which to store the published output of the scheduled task. The file can only have a .txt or .log extension by default. You can add more extensions in cfusion\lib\neo-cron xml.

interval

 

 

Interval at which task is scheduled:

  • number of seconds
  • once
  • daily
  • weekly
  • monthly

operation

Optional

HTTPRequest

Operation that the scheduler performs.

overwrite true If false, results in the creation of new output files every time the task executes. If true, instead of creating new outputfiles, the existing one is overwritten.  

password

Optional

 

Password, if URL is protected.

path

Required if publish = "Yes"

 

Path to the directory in which to put the published file.

port

Optional

80

Port to use on the server that is specified by the url parameter. If resolveURL = "yes", retrieved document URLs that specify a port number are automatically resolved, to preserve links in the retrieved document. A port value in the url attribute overrides this value.

proxyPassword

Opt

 

Password to provide to the proxy server.

proxyPort

Optional

80

Port number to use on the proxy server.

proxyServer

Optional

 

Host name or IP address of a proxy server.

proxyUser

Opt

 

User name to provide to the proxy server.

publish

Optional

no

  • yes: saves the result to a file.
  • no

requestTimeOut

Optional

 

(Deprecated) Can be used to extend the default time-out period.

resolveURL

Optional

no

  • yes: resolves links in the output page to absolute references.
  • no

result

Required for the list action.    Name for the query in which cfschedule returns the result variables.

startDate

 

 

Date on which to first run the scheduled task. The default date format is mm/dd/yy.

startTime

 

 

Time at which to run the scheduled task.

url

Required if action = "update"

 

URL of the page to execute.

username

Optional

 

User name, if URL is protected.

group

Optional

default

The group to which the scheduled task belongs.

onComplete

Optional

invokeHandler

The action to be performed after the completion of current task. Used when chaining scheduled tasks. For details, see Using Scheduler.

eventHandler

Optional

 

A CFC file whose pre-defined methods are invoked for various events while running the task. The CFC must be implementing CFIDE.scheduler.ITaskEventHandler. The path you specify can be relative to webroot for example, schedulerdemo.eventhandler, or use a ColdFusion mapping.

onException

Optional

invokeHandler, if eventHandler is specified

Specify what to do if a task results in error. If unspecified, then no action is taken. The options are:

  • refire: Tries to run the task immediately.
  • pause: Stops the task from executing further.
  • invokeHandler: Invokes onError method of the event handler as defined by the user.

cronTime

Optional

 

Specifying task scheduling time in cron job syntax.

repeat

Optional

-1

The number of times a task has to be repeated.

priority

Optional

5

An integer that indicates the priority.

exclude

Optional

 

Comma-separated list of dates or date range for exclusion in the schedule period.

onMisfire

Optional

invokeHandler if eventHandler is specified

Specify what to do if a task misfires. If unspecified, then no action is taken. The options are:

  • fire_now: Tries to run the task immediately.
  • invokeHandler: Invokes onMisfire method of the event handler as defined by the user.

cluster

Optional

no

If yes, the task can be executed in cluster setup.

mode

Optional

server

If the task is server-specific or application specific.

retryCount

Optional

3

The number of reattempts if the task fails. The value must be greater than or equal to 0 and less than or equal to 3.

Note:

ColdFusion does not invoke Application.cfc methods, when invoking a task's event handler methods.

Usage

This tag and the ColdFusion Administrator Scheduled task page schedule ColdFusion tasks. Tasks that you add or change using this tag are visible in the Administrator. You can disable this tag in the Administrator Sandbox/Resource security page. This tag's success or failure status is written to the schedule.log file in the cf_root/cfusion/logs directory (or the logs directory of another instance you may have created with the ColdFusion Enterprise Instance Manager).

When you create a task, you specify the URL of the ColdFusion page to execute, the date, time and frequency of execution, and whether to publish the task output to an HTML file. If the output is published, you specify the output file path and file.

If you schedule a job to run monthly on any date in the range 28-31, the scheduler does the following:

  • If you schedule a monthly job to run on the last day of a month, the scheduled job will run on the last day of each month. For example, if you schedule a monthly job to start on January 31, it will run on January 31, February 28 or 29, March 31, April 30, and so on.
  • If you schedule a monthly job to run on the 29th or 30th of the month, the job will run on the specified day of each month for 30 or 31-day months, and the last day of February. For example, if you schedule a monthly job to start on January 30, the job will run on January 30, February 28 or 29, March 30, April 30, and so on.

If you have a task that is scheduled to run every day with defined start and end times (for example, 12 PM to 4 PM), along with a fixed interval (for example, every 1 minute), you can create the task from the administrator in the following manner:

On the ColdFusion Administrator, click Server Settings > Scheduled Tasks, and click Schedule New Task.

Create a schedule
Create a schedule

If you want to create a task that runs through the night, you can write a cron expression. For example, if your task needs to execute between 1800-0400 hours on the first of every month, use the expression, 

0 0 18-4 1 * ? *

If you schedule a job to run once, the starting time is in the past, and the task has not yet run, it misfires and runs immediately.

If you schedule a recurring job with a start time in the past, ColdFusion schedules the job to run on the next closest interval in the future.The Scheduler configuration file, cf_root\lib\neo-cron.xml contains all scheduled events, as individual entries (except the clustered tasks).

The cfschedule tag also returns the following result variables in a query. You can access these variables with a prefix of the name you specified in the result attribute. For example, if you assign the name myResult to the result attribute, you can retrieve the status of the second retrieved task by accessing #myResult.status[2]#. The result attribute provides a way for functions or CFCs that are called from multiple pages, possibly at the same time, to avoid overwriting results of one call with another.

Variable name Description
result_name.chained_task states whether it is a chained task
result_name.clustered states whether the task is running in cluster mode
result_name.crontime states the cron start time of the task
result_name.enddate states the end date of the task
result_name.endtime states the end time of the task
result_name.eventhandler specifies the event handler associated with the task
result_name.exclude specifies the date or time range excluded from the task
result_name.file states the name of the file where the published output of task is stored
result_name.group specifies the group to which the task belongs
result_name.interval specifies the interval at which the task is scheduled
result_name.last_fire states the last time the task was executed
result_name.mode states whether the task is server-specific or application-specific
result_name.oncomplete states the action to be taken after the task is completed. Used in chained tasks
result_name.onexception states the action to be taken if the task ends in error
result_name.onmisfire states the action to be taken if the task misfires
result_name.overwrite specifies whether the output files are overwritten every time the task executes
result_name.path specifies the location of the published file where the task output is stored
result_name.priority indicates the priority of the task
result_name.proxy_port states the port number of the proxy server
result_name.proxy_server states the hostname or IP address of the proxy server
result_name.proxy_user states the username provided to the proxy server
result_name.publish specifies whether the task results are saved to a file
result_name.remaining_count states the number of times the task is yet to run
result_name.repeat states the number of times a task is repeated
result_name.resolve_url specifies whether the links in the task output page point to absolute references
result_name.retry_count states the number of times the task was attempted
result_name.startdate date on which the task was first scheduled
result_name.starttime time the task is scheduled to run
result_name.status status of the task
result_name.task states the name of the task
result_name.timeout specifies the task timeout time in seconds
result_name.url states the url of the page that is executed
result_name.username specifies the user name (in case the url of the page is protected)

cfschedule example

<!--- This read-only example schedules a task. 
To run the example, remove the comments around the code 
and change the startDate, startTime, url, file, and path attributes 
to appropriate values. ---> 
<cfschedule action = "update" 
task = "TaskName" 
operation = "HTTPRequest" 
url = "http://127.0.0.1/playpen/history.cfm" 
startDate = "8/17/09" 
startTime = "12:25 PM" 
interval = "3600" 
resolveURL = "Yes" 
publish = "Yes" 
file = "sample.html" 
path = "c:\inetpub\wwwroot\playpen" 
requestTimeOut = "600"> 

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy