Using Scheduler

Scheduler enhancements in ColdFusion 10 let you schedule tasks in a granular, scalable, and organized way. The enhancements include:

Quartz scheduling service: For details, see http://www.quartz-scheduler.org/.
Grouping:Arrange tasks in to different groups as shown here:

<cfschedule
action=update
task=t1 url="www.adobe.com"
group="G1"/>

You can club tasks into groups so that later on, you can resume or pause all the tasks in a same group rather than repeat for individual tasks.
Application-specific tasks:Apart from scheduling tasks at server level, you can schedule tasks at application level, visible only to the application, as shown here:

<cfschedule
action=update
task=t1
url="www.adobe.com"
group="G1"
mode="application"/>

The default mode is server.
Event Handling: Attach listeners to scheduled tasks.For example, you can write a listener CFC that does the following:
On completion of the task, sends a mail to all stakeholders (onTaskEnd)
Decide if the task should execute (onTaskStart)
In the case of exception, refires the task (onError)

Executes the code provided inside a method instead of invoking the URL (execute)

<cfcomponent implements="CFIDE.scheduler.ITaskEventHandler">
<cffunction name="onTaskStart" returntype="boolean">
<cfargument name="context" type="struct"/>
<cfmail from="a@adobe.com" subject="Scheduler_Scenario_Testing" to="a@adobe.com">
The Report is about to be generated.
</cfmail>
<cfreturn true>
</cffunction>
<cffunction name="onMisfire" returntype="void">
<cfargument name="context" type="struct" required="false"/>
<cfmail from="a@adobe.com" subject="Scheduler_Scenario_Testing" to="a@adobe.com">
The Report generation task has misfired.
</cfmail>
</cffunction>
<cffunction name="onTaskEnd" access="public" returntype="void">
<cfargument name="context" type="struct" required="false"/>
<cfmail from="a@adobe.com" subject="Scheduler_Scenario_Testing" to="a@adobe.com">
The Report generation task has Completed.
</cfmail>
</cffunction>
<cffunction name="onError" returntype="void">
<cfargument name="context" type="struct" required="false"/>
<cfmail from="a@adobe.com" subject="Scheduler_Scenario_Testing" to="a@adobe.com">
The Report generation task has errored out.
</cfmail>
</cffunction>
<cffunction name="execute" returntype="void">
<cffile action="append" file="#Expandpath('.')#/log.txt" output="<br><b>In Execute</b><br>">
</cffunction>
</cfcomponent>

Note: The listener has to extend CFIDE.scheduler.ITaskEventHandler.cfc.

Note: The context argument of Event Handling functions is a struct and contains the following keys. For functions, onMisfire, onTaskEnd , and onTaskStart, the keys are group, mode, and task. For the onError function, the keys are exceptionMessage, group, mode, and task

Chaining:Lets you define dependent tasks. If the parent task is executed, all dependent tasks are also executed.

<cfschedule
action=update
task=t1
url="www.adobe.com"
group="G1"
mode="application"
onComplete="t2:DEFAULT:application">

In this example, the value of onComplete must be provided in the following format: <task>:<group>:<mode>

Note: You cannot chain an application-specific task after a server-specific task.

Cluster: You can run scheduler in cluster setups. Currently clustering works only with JDBC job store. Features include load-balancing and job fail-over. A single application can have both clustered as well as non-clustered setup. So tasks can go to either of the setups.The system time of all clustered servers have to be same. To enable cluster setup, use the ColdFusion Administrator. For details, see Scheduled Tasks.
Cron commands: You can trigger a scheduled task using cron commands. Cron-Expressions are strings made up of seven sub-expressions (Seconds, Minutes, Hours, Day-of-Mont}}h, {{Month, Day-of-Week, and Year (optional field)), that describe individual details of the schedule.Sub-expression are separated with white-space.For example, "0 */2 3-10,21-23 * * ?" the task should be executed every 2 minutes from 3:00 AM to 10:00 AM and 9:00 PM to 11:58 PM daily.For details, see http://www.quartz-scheduler.org/docs/tutorial/TutorialLesson06.html .
Prioritize tasks: You can set priorities for the tasks. Assume that you have 50 tasks that have to start at the same time. But there are only 10 worker threads currently available. Then, the first 10 tasks with the highest priority start before others. Priority can be any integer value. The default value is 5.
Exclude dates: You can exclude dates from the scheduling process.For example, you can set to execute a job from September 1 to December 30, except on December 25.For exclusion, you can specify a comma-separated list of dates, date, or date range. For example,

<cfschedule .... exclude="date1 TO date2" .../>

All the dates from date1 to date2 (inclusive) are excluded from scheduling. You can provide an array of date strings or an array of date objects.

In case of error:You can specify the action to be taken.

<cfschedule task="job1" onException="REFIRE,PAUSE,INVOKEHANDLER" ....>

That is, if an error occurs while running the job, you can decide if to refire the task, pause the job, or invoke onError method of the attached eventhandler.

If task misfires: You can specify the action to be taken.That is, if to refire, reschedule, or invoke onMisfiremethod of the attached eventhandler.

A misfire occurs if a persistent trigger misses the firing time because the scheduler was shutdown, or because there are no available threads in thread pool to execute the job. The threshold value for a task to be considered as misfired is 60 seconds.

Note: All misfired tasks are logged in scheduler.log available in cf_root\WEB-INF\cfusion\logs\scheduler.log file on J2EE configurations, or the cf_root\logs\scheduler.log file on server configurations.

Pause and resume/Pause all and resume all:Pause or resume the tasks of whole group as follows:

<cfschedule group="group1" action="pause" .......>

This can be specified at the server-level or application level as follows:

List tasks:Lists all scheduled tasks at the server level or application level:

<cfschedule action="list" mode="application" result ="res" />

Retry:If running a job results in an exception, you can preset to continue re-firing, till retry count is over, as follows:

<cfschedule task="job1" onException="REFIRE" retryCount="3" ....>

Repeat: Specify the number of times a given schedule has to repeat.For example, run Job1at 2 pm today and repeat it 20 times at the interval of 10 minutes.In this case, you need not specify the end time of the schedule.

<cfschedule task="task1" repeat="20" interval="60" ....>

Customize quartz: Advanced users can customize Quartz using quartz.properties available in cfusion\lib\quartz. The current version of Quartz being shipped with ColdFusion is 2.02.

When you are using the Scheduler, output can be saved only as .log or .txt files. The same restriction is applicable for validation queries on databases.

Also, for the <cfinclude> tag, this restriction is applicable. By default, you can include only CFM files. However, you can modify allowedextinclude key in neoruntime.xml file to add your own file type.

Using Scheduler

Applies to