Apex Commands

A suite of commands, built on top of Apex.

Scheduler

The scheduler module exposes System.schedule and System.abortJob functionality to the command line. It includes low-level commands to start, stop, or export all scheduled jobs and a manage command that is optimized for execution in CI pipelines.

Export Scheduled Jobs

A fancy wrapper and formatter around a basic SOQL. It exports all currently active scheduled jobs on your target org to human readable table or JSON. Running it is straight-forward.

sf jsc apex schedule export -o MyTargetOrg

Exporting to a manage config is planned.

Manage Scheduled Apex

The manage command is designed with continuous integration in mind. It reads job definitions and command options from a config file, that should be put under version control. Before it executes, existing jobs on the org are analyzed. New jobs are only started when necessary. If it is executed subsequently (with the same config), existing jobs are not changed.

💡 When you first experiment with the manage command, I recommend to export all jobs first.

The config follows a simple syntax:

options:
  stop_other_jobs: true
jobs:
  Name of job:
    class: ApexClassThatImplementsSchedulable
    expression: '0 0 1 * * ?'

You can use the class name to name the job. If you do, you can omit the class key. Remember, that you can only schedule a class once by this name (as the job name must be unique).

jobs:
  ApexClassThatImplementsSchedulable:
    expression: '0 0 1 * * ?'

Now you can assess, how many jobs this config would start and stop:

sf jsc apex schedule manage -f my-jobs-definition.yaml -o TargetOrg --dry-run

Options

At the moment, the following options are supported. They must be placed within the optional options map.

• stop_other_jobs: When set to true, all scheduled jobs that are not present in jobs will be stopped. See below to understand, how new jobs are matched with existing ones.

Further Reading

More details on how the commands behave and some important limitations.

Validation of Apex Classes and Cron Expressions

All job configuration (job name, apex class, and cron expression) is validated at runtime, when the engine tries to start the job (more precisely, when System.schedule is executed). This means, that invalid input may only be caught in the middle of execution. This can result in partial success (especially when jobs were stopped).

At the moment, there is no way to reliably validate cron expressions before executing them. Pre-validating apex classes is planned.

How Jobs are Identified and Matched

The name of the job must be unique. Therefore, the manage command uses it as the primary identifier for jobs in the YAML config. Jobs are considered identical, if all three inputs are matched case sensitive: Job Name, Apex Class, and Cron Expression.

If stop_other_jobs is false, existing jobs that do not match a job in the config are not stopped. The only exception is a job that matches by only Apex Class and Job Name (but not Cron Expression). This is considered an update, and the existing job is stopped & the updated version is started.

If one of them is changed, the engine will consider the running job obsolete (and stop it, if stop_other_jobs is true). Then, the new job will be started.