Scheduling Jobs

This topic provides instructions for managing jobs in Pivotal Scheduler.

Manage Jobs

You can use Pivotal Scheduler to schedule execution of tasks on the Pivotal Platform, including database migrations, emails, and batch jobs. See the following sections to learn more about creating, running, and scheduling jobs and viewing job history.

Note: Pivotal Scheduler does not take into account the outcome of previously run jobs. It assumes that scheduled jobs are idempotent and can be re-run. Jobs that are not idempotent may cause unintended consequences even if they complete successfully.

To use the Cloud Foundry Command Line Interface (cf CLI) for managing jobs, you must install the Pivotal Scheduler CLI plugin on your local machine. This plugin is packaged with the Pivotal Scheduler tile on Pivotal Network. For more information, see the Prerequisites section of the Using Pivotal Scheduler topic.

Create a Job

To execute a task related to an app, create a job by running the cf create-job APP-NAME JOB-NAME COMMAND command, where:

  • APP-NAME is the app you want to execute a task against.
  • JOB-NAME is the name for your job.
  • COMMAND is the command you want to execute.

See the following example:

 $ cf create-job my-app my-job "pwd"
Creating job my-job for my-app with command pwd in org my-org / space my-space as user@example.com... Job Name App Name Command my-job my-app pwd OK

Execute a Job

You can execute a job manually. This is often useful to test the configuration of a job prior to scheduling it for recurring execution.

Run cf run-job JOB-NAME. See the following example:

$ cf run-job my-job
Enqueuing job my-job for app my-app in org my-org / space my-space as user@example.com... OK

Schedule a Job

You can schedule a job to execute at any time using a schedule expression. Pivotal Scheduler requires Quartz cron expressions in the MIN HOUR DAY-OF-MONTH MONTH DAY-OF-WEEK format. For more information on how to use this syntax, see Scheduler Cron Syntax.

For example, to execute a job at noon every day, run the following command:

$ cf schedule-job my-job "0 12 ? * * "

A single job can have multiple schedules. Each schedule has a GUID to distinguish it from similar schedules.

Note: Scheduler for PCF does not support cron expressions with seconds or years.

Note: Scheduled jobs automatically execute in UTC.

View Jobs

You can use the cf CLI to list all jobs in a space by running cf jobs. See the following example:

$ cf jobs
Listing jobs for org my-org / space my-space as user@example.com... Job Name App Name Command my-job my-app pwd OK

View Schedules for Jobs

You can review schedules for all jobs in a space by running cf job-schedules. See the following example:

$ cf job-schedules
Getting scheduled jobs for org my-org / space my-space as user@example.com... App Name: my-app my-job pwd 2b69e0c2-9664-46bb-4817-54afcedbb65d 0 12 ? * * OK

View Job History

You can review job history by running cf job-history JOB-NAME. See the following example:

$ cf job-history my-job
Getting scheduled job history for my-job in org my-org / space my-space as user@example.com... 1 - 1 of 1 Total Results Execution GUID Execution State Scheduled Time Execution Start Time Execution End Time Exit Message 8a7e808a5b883a25015b89b4a12c0001 SUCCEEDED Mon, 10 Apr 2017 13:00:00 UTC Mon, 10 Apr 2017 13:00:00 UTC Mon, 10 Apr 2017 13:00:01 UTC 202 - Cloud Controller Accepted Task

View Logs

You can view logs for jobs by running cf logs APP-NAME --recent. See the following example:

$ cf logs my-app --recent
Connected, dumping recent logs for app my-app in org my-org / space my-space as user@example.com... [...] 2017-04-19T23:04:13.79-0600 [APP/TASK/cc6fab7f-32a9-4404-4574-b0c430a96cd9 -|- 0d30f4f0-11a4-4d6a-7e77-5e1cdc1aa5ec/0]OUT Creating container 2017-04-19T23:04:14.01-0600 [APP/TASK/cc6fab7f-32a9-4404-4574-b0c430a96cd9 -|- 0d30f4f0-11a4-4d6a-7e77-5e1cdc1aa5ec/0]OUT Successfully created container 2017-04-19T23:04:14.22-0600 [APP/TASK/cc6fab7f-32a9-4404-4574-b0c430a96cd9 -|- 0d30f4f0-11a4-4d6a-7e77-5e1cdc1aa5ec/0]OUT bin 2017-04-19T23:04:14.22-0600 [APP/TASK/cc6fab7f-32a9-4404-4574-b0c430a96cd9 -|- 0d30f4f0-11a4-4d6a-7e77-5e1cdc1aa5ec/0]OUT db 2017-04-19T23:04:14.23-0600 [APP/TASK/cc6fab7f-32a9-4404-4574-b0c430a96cd9 -|- 0d30f4f0-11a4-4d6a-7e77-5e1cdc1aa5ec/0]OUT Exit status 0 2017-04-19T23:04:14.24-0600 [APP/TASK/cc6fab7f-32a9-4404-4574-b0c430a96cd9 -|- 0d30f4f0-11a4-4d6a-7e77-5e1cdc1aa5ec/0]OUT Destroying container 2017-04-19T23:04:14.55-0600 [APP/TASK/cc6fab7f-32a9-4404-4574-b0c430a96cd9 -|- 0d30f4f0-11a4-4d6a-7e77-5e1cdc1aa5ec/0]OUT Successfully destroyed container [...]

Note: Pivotal Scheduler jobs are executed as CF Tasks.

Delete a Job

You can delete a job by running cf delete-job JOB-NAME. See the following example:

$ cf delete-job my-job
Really delete the job my-job with command pwd and all associated schedules and history?> [yN]:y OK

Delete a Job Schedule

You can delete a specific schedule by running cf delete-job-schedule JOB-NAME SCHEDULE-GUID, where JOB-NAME is the name of the job and SCHEDULE-GUID is the GUID found in the output of the cf job-schedules command. See the following example:

$ cf delete-job-schedule my-job 2b69e0c2-9664-46bb-4817-54afcedbb65d
Really delete the schedule 2b69e0c2-9664-46bb-4817-54afcedbb65d / 0 12 ? * * and all associated history?> [yN]: y Deleting schedule 2b69e0c2-9664-46bb-4817-54afcedbb65d for job my-job in org test / space scheduler as admin OK