Apex Commands

Apex commands help you execute and manage apex-related functionality in your CI/CD pipeline.

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.

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.

The config follows a simple syntax:

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

You can also name the job identical to the apex class that is executed. In that case, 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/stop:

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

Options

At the moment, the following options are supported. The 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 jobs are matched.

Further Reading

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

Runtime validation of Apex Classes and Cron Expressions

All job configuration (job name, apex class, and cron expression) are validated at runtime, when the engine tries to start the job (more precisely, when System.schedule is called). This means, that invalid input is only caught in the middle of execution.

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

By definition, the name of the job must be unique. Therefore, the job name is the primary identifier that is configure jobs in the YAML config. Jobs are considered identical, if all three inputs are identical (matching is case sensitive): Job Name, Apex Class, and Cron Expression.

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.