This tag is unsupported in CFFiddle.
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.
Category
Syntax
<cfschedule action = "create|modify|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" 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="create" task = "task name"> OR <cfschedule action = "modify" task = "task name"> OR <cfschedule action = "delete" task = "task name"> OR <cfschedule action = "run" task = "task name"> OR <cfschedule action = "pauseAll" group=groupname > OR <cfschedule action = "pauseAll" > OR <cfschedule action = "resumeAll" mode = "server|application" > OR <cfschedule action = "resumeAll" group=groupname > OR <cfschedule action = "resumeAll" > OR <cfschedule action = "list" mode = "server|application" result = "res">
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 (2018 release) Update 2: Introduced the actions Create and Modify.
ColdFusion (2018 release): The attribute requestimeout is removed.
Also in the 2018 release, cfschedule action=pauseall and resumeall no longer require group or mode.
For example,
If you run <cfschedule action=" pauseall " from app1, all server and application tasks of app1 are paused.
It will not pause/ resumeall tasks of app2.
However, application boundaries still exist. App1 cannot pause/ resumeall tasks of app2 and vice-versa.
But any application can pause/ resumeall all the server level tasks.
In addition, the fire_now attribute is renamed to firenow in the 2018 release of ColdFusion.
ColdFusion (2016 release) Update 8: The following columns with an underscore are removed from the output.
- LAST_FIRE
- CHAINED_TASK
- REMAINING_COUNT
- RESOLVE_URL
- RETRY_COUNT
- PROXY_SERVER
- PROXY_PORT
- PROXY_USER
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.
If you are using databases that are registered using Other as driver in ColdFusion Administrator, you must add these two properties in quartz_cluster.properties file which is located in <cfinstance>/lib/quartz:
- org.quartz.dataSource.<datasourcename>.connectionProvider.class=coldfusion.scheduling.ConnectionProviderImpl
- org.quartz.jobStore.dataSource=<datasourcename>
Replace <datasourcename> with the name of the datasource that is registered with ColdFusion Administrator.
Also, while registering the datasource with ColdFusion, ensure that the driver name is either MySQL/Microsoft SQL Server/Oracle, or Others.
Attributes
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 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.
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.chainedtask | 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.lastfire | 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.proxyport | states the port number of the proxy server |
| result_name.proxyserver | states the hostname or IP address of the proxy server |
| result_name.proxyuser | states the username provided to the proxy server |
| result_name.publish | specifies whether the task results are saved to a file |
| result_name.remainingcount | 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.resolveurl | specifies whether the links in the task output page point to absolute references |
| result_name.retrycount | 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) |
Example 1
<!--- 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" >
Example 2
handler.cfc
component implements="cfide.scheduler.ITaskEventHandler"
{
public boolean function onTaskStart(Struct context){
myvar="onTaskStart";
cffile (action="append", file="#Expandpath('./')#log.txt", output="fireInstancedId:#context.fireinstanceID#, myvar: #myvar#<br>");
return true;
}
public void function Execute(Struct context){
myvar= myvar & "Execute";
cffile (action="append", file="#Expandpath('./')#log.txt", output="fireInstancedId:#context.fireinstanceID#, myvar: #myvar#<br>");
}
public void function onTaskEnd(Struct context){
myvar=myvar & "onMisfire";
cffile (action="append", file="#Expandpath('./')#log.txt", output="fireInstancedId:#context.fireinstanceID#, myvar: #myvar#<br>");
}
public void function onMisfire(Struct context){
//FireInstance-Id would not be passed to onMisfire
}
public void function onError( Struct context){
myvar= myvar & "onError";
cffile (action="append", file="#Expandpath('./')#log.txt", output="fireInstancedId:#context.fireinstanceID#,myvar: #myvar#<br>");
}
}
index.cfm
<!--- Creating Task --->
<cfschedule action="update"
task="fireInstanceEx"
eventhandler="schedulerTest.handler"
interval="once">
Reading log files<br/>
<cfset sleep(18000)>
<cffile action="read" file="#Expandpath('./')#log.txt" variable="res" >
<cfoutput>#res#</cfoutput>
Example 3
<cfscript>
cfschedule (action="create", task="myTask", group="bugTesting" ,mode="Server", url="http://google.com", startDate="24/12/2017", startTime="12:00 AM", interval ="daily")
cfschedule(action="modify", task="myTask",group="bugTesting" ,interval="3600",startDate="25/12/2017", startTime="1:00 AM", publish="yes",path="#ExpandPath('./')#",file="task.log")
cfschedule(action="list",task="myTask1",group="bugTesting",result="taskQuery")
writeoutput ("Name:" & #taskQuery.task# & " Group:" & #taskQuery.task# & " mode:" & #taskQuery.mode# & " url:" & #taskQuery.Url# & " startDate:" & #taskQuery.startDate# & " startTime:" & #taskQuery.startTime# & " interval:" & #taskQuery.interval# & " publish:" & #taskQuery.publish# & " file:" & #taskQuery.file# & "<br>");
</cfscript>