Apex Scheduler

Implementing the Schedulable Interface

To schedule an Apex class to run at regular intervals, first write an Apex class that implements the Salesforce-provided interface Schedulable.

The scheduler runs as system: all classes are executed, whether the user has permission to execute the class or not. For more information on setting class permissions, see “Apex Class Security Overview” in the Salesforce online help.

To monitor or stop the execution of a scheduled Apex job using the Salesforce user interface, click Your Name | Setup | Monitoring | Scheduled Jobs. For more information, see “Monitoring Scheduled Jobs” in the Salesforce online help.

global void execute(SchedulableContext sc){}

Use this method to instantiate the class you want to schedule.

Tip

Though it's possible to do additional processing in the execute method, we recommend that all processing take place in a separate class.

The following example implements the Schedulable interface for a class called mergeNumbers:

global class scheduledMerge implements Schedulable{
   global void execute(SchedulableContext SC) {
      mergeNumbers M = new mergeNumbers(); 
   }
}

The following example uses the System.Schedule method to implement the above class.

scheduledMerge m = new scheduledMerge();
        String sch = '20 30 8 10 2 ?';
        system.schedule('Merge Job', sch, m);

You can also use the Schedulable interface with batch Apex classes. The following example implements the Schedulable interface for a batch Apex class called batchable:

global class scheduledBatchable implements Schedulable{
   global void execute(SchedulableContext sc) {
      batchable b = new batchable(); 
      database.executebatch(b);
   }
}

Use the SchedulableContext object to keep track of the scheduled job once it's scheduled. The SchedulableContext method getTriggerID returns the Id of the CronTrigger object associated with this scheduled job as a string. Use this method to track the progress of the scheduled job.

To stop execution of a job that was scheduled, use the System.abortJob method with the ID returned by the.getTriggerID method.

Testing the Apex Scheduler

The following is an example of how to test using the Apex scheduler.

global class TestScheduledApexFromTestMethod implements Schedulable {

// This test runs a scheduled job at midnight Sept. 3rd. 2022 
    

   public static String CRON_EXP = '0 0 0 3 9 ? 2022';
   
   global void execute(SchedulableContext ctx) {
      CronTrigger ct = [SELECT Id, CronExpression, TimesTriggered, NextFireTime
                FROM CronTrigger WHERE Id = :ctx.getTriggerId()];

      System.assertEquals(CRON_EXP, ct.CronExpression);
      System.assertEquals(0, ct.TimesTriggered);
      System.assertEquals('2022-09-03 00:00:00', String.valueOf(ct.NextFireTime));

      Account a = [SELECT Id, Name FROM Account WHERE Name = 
                  'testScheduledApexFromTestMethod'];
      a.name = 'testScheduledApexFromTestMethodUpdated';
      update a;
   }   
}

@istest

class TestClass {

   static testmethod void test() {
   Test.startTest();

      Account a = new Account();
      a.Name = 'testScheduledApexFromTestMethod';
      insert a;

   // Schedule the test job 
    

      String jobId = System.schedule('testBasicScheduledApex',
      TestScheduledApexFromTestMethod.CRON_EXP, 
         new TestScheduledApexFromTestMethod());
   // Get the information from the CronTrigger API object 
    

      CronTrigger ct = [SELECT Id, CronExpression, TimesTriggered, 
         NextFireTime
         FROM CronTrigger WHERE id = :jobId];

   // Verify the expressions are the same 
    
      System.assertEquals(TestScheduledApexFromTestMethod.CRON_EXP, 
         ct.CronExpression);

   // Verify the job has not run 
    
      System.assertEquals(0, ct.TimesTriggered);

   // Verify the next time the job will run 
    
      System.assertEquals('2022-09-03 00:00:00', 
         String.valueOf(ct.NextFireTime));
      System.assertNotEquals('testScheduledApexFromTestMethodUpdated',
         [SELECT id, name FROM account WHERE id = :a.id].name);

   Test.stopTest();

   System.assertEquals('testScheduledApexFromTestMethodUpdated',
   [SELECT Id, Name FROM Account WHERE Id = :a.Id].Name);

   }
}

Using the System.Schedule Method

After you implement a class with the Schedulable interface, use the System.Schedule method to execute it. The scheduler runs as system: all classes are executed, whether the user has permission to execute the class or not.

Note

Use extreme care if you are planning to schedule a class from a trigger. You must be able to guarantee that the trigger will not add more scheduled classes than the 25 that are allowed. In particular, consider API bulk updates, import wizards, mass record changes through the user interface, and all cases where more than one record can be updated at a time.

The System.Schedule method takes three arguments: a name for the job, an expression used to represent the time and date the job is scheduled to run, and the name of the class. This expression has the following syntax:

SecondsMinutesHoursDay_of_monthMonthDay_of_weekoptional_year

Note

Salesforce only adds the process to the queue at the scheduled time. Actual execution may be delayed based on service availability.

The System.Schedule method uses the user's timezone for the basis of all schedules.

The following are the values for the expression:

The special characters are defined as follows:

Special Character	Description
,	Delimits values. For example, use JAN, MAR, APR to specify more than one month.
-	Specifies a range. For example, use JAN-MAR to specify more than one month.
*	Specifies all values. For example, if Month is specified as *, the job is scheduled for every month.
?	Specifies no specific value. This is only available for Day_of_month and Day_of_week, and is generally used when specifying a value for one and not the other.
/	Specifies increments. The number before the slash specifies when the intervals will begin, and the number after the slash is the interval amount. For example, if you specify 1/5 for Day_of_month, the Apex class runs every fifth day of the month, starting on the first of the month.
L	Specifies the end of a range (last). This is only available for Day_of_month and Day_of_week. When used with Day of month, L always means the last day of the month, such as January 31, February 28 for leap years, and so on. When used with Day_of_week by itself, it always means 7 or SAT. When used with a Day_of_week value, it means the last of that type of day in the month. For example, if you specify 2L, you are specifying the last Monday of the month. Do not use a range of values with L as the results might be unexpected.
W	Specifies the nearest weekday (Monday-Friday) of the given day. This is only available for Day_of_month. For example, if you specify 20W, and the 20th is a Saturday, the class runs on the 19th. If you specify 1W, and the first is a Saturday, the class does not run in the previous month, but on the third, which is the following Monday. Tip Use the L and W together to specify the last weekday of the month.
#	Specifies the nth day of the month, in the format weekday#day_of_month. This is only available for Day_of_week. The number before the # specifies weekday (SUN-SAT). The number after the # specifies the day of the month. For example, specifying 2#2 means the class runs on the second Monday of every month.

The following are some examples of how to use the expression.

In the following example, the class proschedule implements the Schedulable interface. The class is scheduled to run at 8 AM, on the 13th of February.

proschedule p = new proschedule();
        String sch = '0 0 8 13 2 ?';
        system.schedule('One Time Pro', sch, p);

Apex Scheduler Best Practices and Limits

• Salesforce only adds the process to the queue at the scheduled time. Actual execution may be delayed based on service availability.
• Use extreme care if you are planning to schedule a class from a trigger. You must be able to guarantee that the trigger will not add more scheduled classes than the 25 that are allowed. In particular, consider API bulk updates, import wizards, mass record changes through the user interface, and all cases where more than one record can be updated at a time.
• Though it's possible to do additional processing in the execute method, we recommend that all processing take place in a separate class.

• You can only have 25 classes scheduled at one time. You can evaluate your current count by viewing the Scheduled Jobs page in Salesforce or programmatically using the Force.com Web services API to query the CronTrigger object.

• You can't use the getContent and getContentAsPDFPageReference methods in scheduled Apex.