cron.xml Reference for App Engine SDK-Based Tooling

Use the cron.xml file to define scheduled tasks for your application.

To learn more about scheduling tasks, including how to test, deploy, or delete Cron jobs, see Scheduling Tasks with Cron.

Example

The following is an example cron.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<cronentries>
  <cron>
    <url>/recache</url>
    <description>Repopulate the cache every 2 minutes</description>
    <schedule>every 2 minutes</schedule>
  </cron>
  <cron>
    <url>/weeklyreport</url>
    <description>Mail out a weekly report</description>
    <schedule>every monday 08:30</schedule>
    <timezone>America/New_York</timezone>
  </cron>
  <cron>
    <url>/weeklyreport</url>
    <description>Mail out a weekly report</description>
    <schedule>every monday 08:30</schedule>
    <timezone>America/New_York</timezone>
    <target>version-2</target>
  </cron>
</cronentries>

For an XSD describing the format, check the file docs/cron.xsd in the SDK.

Syntax

The cron.xml file should reside in the WEB-INF directory of your application alongside appengine-web.xml : cron.xml configures scheduled tasks for your Java 8 application.

Cron job definitions

Element Description
<description> Optional. The description is visible in the Cloud Console and the development server's admin interface.
<retry-parameters> Optional. If a cron job's request handler returns a HTTP status code that is not in the range 200–299 (inclusive) App Engine considers the job to have failed. By default, failed jobs are not retried. You can cause failed jobs to be retried by including a retry-parameters block in your configuration file.

See the Cron retries section for more information.

<schedule> Required. Defines the schedule of when the cron job runs, see the syntax below.
<target>

The target string is prepended to your app's hostname. It is usually the name of a service. The cron job will be routed to the version of the named service that is configured for traffic.

If the service name that is specified for target is not found, then the Cron request is routed to either the default service, or to the version of your app that is configured to receive traffic.For more information about routing, see How Requests are Routed.

<timezone> The timezone should be the name of a standard zoneinfo time zone name. If you don't specify a timezone, jobs run in UTC (also known as GMT).
<url> Required. The <url> field is just a URL in your application. If the <url> element contains the special XML characters &, <, >, ', or ", you should escape them.

Defining the cron job schedule

Cron jobs are scheduled on reoccurring intervals and are specified using a simple English-like format. You can define a schedule so that your job runs multiple times a day, or runs on specific days and months.

Sub-daily intervals

Use a sub-daily interval to run a job multiple times a day on a repetitive schedule. You can define either an end-time interval, or a start-time interval:

  • End-time interval: Defines the time between the "end time" of a job and when the next job starts, where the "end time" is either the time at which the job completes or times out . The Cron service runs jobs in this type of interval throughout the 24 hour day, starting at 00:00, and waits for the specified duration of time between each job.

    Example: For the every 5 minutes schedule, the job is run daily using a 5-minute interval. If one instance of a job that is running on this schedule complete at 02:01, then the next job waits 5 minute and starts again at 02:06.

  • Start-time interval: Defines a regular time interval for the Cron service to start each job. Unlike the end-time interval, the start-time interval runs each job independent of when the prior job completes or times-out. You can set a time range within which you want your job to run, or run jobs 24 hours a day, starting at 00:00.

    Because the start time of a job is strict, if an instance of a job runs longer than the defined time interval, then the Cron service can skip a job. An individual start time in the interval can be skipped if the prior job has not completed or times out .

    Example: For the every 5 minutes from 10:00 to 14:00 schedule, the first job starts running at 10:00, and then every 5 minutes thereafter. If that first job runs for 7 minutes, then the 10:05 job is skipped, and therefore, the Cron service does not run another instance of this job until 10:10.

Custom interval

You can use a custom interval to define a schedule where your job can run once per day on one or more select days, and in one or more select months. Jobs that run on a custom schedule run year-round, only at the specific time on the select days and months.

Example: For the 1,2,3 of month 07:00 schedule, the job runs one time at 07:00 on the first three days of each month.

Important considerations for schedule:

  • You must decide if you want to use either a sub-daily interval or a custom interval. You cannot mix and use elements from the various interval types. The following is an example of an invalid schedule definition: <schedule>every 6 hours mon,wed,fri</schedule>.
  • Only a single instance of a job should run at any time. The Cron service is designed to provide "at least once" delivery; that is, if a job is scheduled, App Engine sends the job request at least one time. In some rare circumstances, it is possible for multiple instances of the same job to be requested, therefore, your request handler should be idempotent, and your code should ensure that there are no harmful side-effects if this occurs.

Formatting the schedule

To specify when your job runs, you must define the schedule element using the following syntax:

<schedule>[TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]</schedule>

Choose an interval type to define your schedule element:

End-time interval
  • [TYPE]: Daily intervals must include the every prefix.

    Example: <schedule>every 12 hours</schedule>

  • [INTERVAL_VALUE]: An integer value and the corresponding unit of time. Valid values for the unit of time:
    • minutes or mins
    • hours
  • [INTERVAL_SCOPE]: Not applicable. To set a specific start time or range within which you want your jobs to run, see the syntax for either the Start-time interval or Custom interval.
End-time interval examples
Use the following examples to help you understand how to define job schedules that use an end-time interval:
  • Starts running every day at 00:00 and waits 5 minutes in between each job. After each job ends, the Cron service waits 5 minutes before running the next job: 
    <schedule>every 5 minutes</schedule>
  • Starts running every day at 00:00 and waits 30 minute in between each job. After each job ends, the Cron service waits 30 minutes before running the next job: 
    <schedule>every 30 mins</schedule>
Start-time interval
  • [TYPE]: Daily intervals must include the every prefix.

    Example: <schedule>every 12 hours</schedule>

  • [INTERVAL_VALUE]: An integer value and the corresponding unit of time. Valid values for the unit of time:
    • minutes or mins
    • hours
  • [INTERVAL_SCOPE] Specifies a clause that corresponds with the [INTERVAL_VALUE]. You can define a custom time range or use the 24 hr synchronized option.
    • Include the from [HH:MM] to [HH:MM] clause to define a specific start time and range within which you want to run jobs.

      You must specify the time values in the 24 hour format, HH:MM, where:

      • HH are integers from 00 to 23.
      • MM are integers from 00 to 59.
    • Use synchronized to specify a 24 hour time range (from 00:00 to 23:59) that is evenly divided by the [INTERVAL_VALUE] value.

      Important: The [INTERVAL_VALUE] must divide 24 into an integer, otherwise the an error occurs. Valid values for [INTERVAL_VALUE] include: 1, 2, 3, 4, 6, 8, 12, or 24.

Start-time interval examples
Use the following examples to help you understand how to define job schedules that use a start-time interval:
  • Runs every 5 minutes from 10:00 to 14:00, every day: 
    <schedule>every 5 minutes from 10:00 to 14:00</schedule>
  • Runs once every hour from 08:00 to 16:00, every day: 
    <schedule>every 1 hours from 08:00 to 16:00</schedule>
  • Runs once every two hours, every day starting at 00:00: 
    <schedule>every 2 hours synchronized</schedule>
Custom interval
  • [TYPE]: Custom intervals can include the every prefix to define a repetitive interval, or you can define a specific list of days in a month:
    • To define a repetitive interval you can use the every prefix.

      Examples: 

      <schedule>every day 00:00</schedule>
<schedule>every monday 09:00</schedule>

    • To define specific days, you must use ordinal numbers. Valid values are from the 1st day of a month, through to the maximum number of days in that month, for example:
      • 1st or first
      • 2nd or second
      • 3rd or third
      • And up to: 31st or thirtyfirst

      Example: 

      <schedule>1st,3rd tuesday</schedule>
<schedule>2nd,third wednesday of month 09:00</schedule>

  • [INTERVAL_VALUE]: Custom intervals include a list of the specific days that you want the job to run. The list must be defined in a comma-separated list and can include either of the following values:
    • The integer value of the day in the month through to a maximum of 31 days, for example:
      • 1
      • 2
      • 3
      • And up to: 31
    • The name of the day in a mix of any of the following long or abbreviated values:
      • monday or mon
      • tuesday or tue
      • wednesday or wed
      • thursday or thu
      • friday or fri
      • saturday or sat
      • sunday or sun
      • Use day to specify all days of the week.

    Examples: 

    <schedule>2nd monday,thu</schedule>
<schedule>1,8,15,22 of month 09:00</schedule>
<schedule>1st mon,wednesday,thu of sep,oct,nov 17:00</schedule>

  • [INTERVAL_SCOPE]: Specifies a clause that corresponds with the specified [INTERVAL_VALUE]. Custom intervals can include the of [MONTH] clause, which specifies a single month in a year, or a comma-separated list of multiple months. You must also define a specific time for when you want the job to run, for example: of [MONTH] [HH:MM].

    By default, if the of clause is excluded, the custom interval is run every month.

    • [MONTH]: You must specify the months in a comma-separated list and can include a mix of the following long or abbreviated values:
      • january or jan
      • february or feb
      • march or mar
      • april or apr
      • may
      • june or jun
      • july or jul
      • august or aug
      • september or sep
      • october or oct
      • november or nov
      • december or dec
      • Use month to specify all months in the year.
    • [HH:MM]: You must specify the time values in the 24 hour format, HH:MM, where:
      • HH are integers from 00 to 23.
      • MM are integers from 00 to 59.

      • Example: 

      <schedule>1st monday of sep,oct,nov 09:00</schedule>
<schedule>1 of jan,april,july,oct 00:00</schedule>

Custom interval examples
Use the following examples to help you understand how to define job schedules that use a custom interval:
  • Runs every day at 00:00: 
    <schedule>every day 00:00</schedule>
  • Runs every Monday at 09:00: 
    <schedule>every monday 09:00</schedule>
  • Runs one time on the second Wednesday in March at 17:00: 
    <schedule>2nd wednesday of march 17:00</schedule>
  • Runs six times in May. During the first two weeks, it runs one time on each Monday, Wednesday, and Friday at 10:00: 
    <schedule>1st,second mon,wed,fri of may 10:00</schedule>
  • Runs once a week. Every seven days starting of the first day of every month, it runs once at 09:00: 
    <schedule>1,8,15,22 of month 09:00</schedule>
  • Runs every other week. On the first and third Monday every month, it runs one time at 04:00: 
    <schedule>1st,third monday of month 04:00</schedule>
  • Runs three times each year. On the first Monday of September, October, and November, it runs one time at 09:00: 
    <schedule>1st monday of sep,oct,nov 09:00</schedule>
  • Runs one time each quarter. On the first day of January, April, July, and October, it runs one time at 00:00: 
    <schedule>1 of jan,april,july,oct 00:00</schedule>

Cron retries

If a cron job's request handler returns a status code that is not in the range 200–299 (inclusive) App Engine considers the job to have failed. By default, failed jobs are not retried. You can cause failed jobs to be retried by including a <retry-parameters> block in your configuration file.

Here is a sample cron.xml file that contains a single cron job configured to retry up to five times (the default) with a starting backoff of 2.5 seconds that doubles each time.

<cronentries>
  <cron>
    <url>/retry</url>
    <description>Retry on jsdk</description>
    <schedule>every 10 minutes</schedule>
    <retry-parameters>
      <min-backoff-seconds>2.5</min-backoff-seconds>
      <max-doublings>5</max-doublings>
    </retry-parameters>
  </cron>
</cronentries>

Cron retries syntax

The retry parameters are described in the table below.

Element Description
<job-retry-limit> The maximum number of retry attempts for a failed cron job not to exceed 5. If specified with <job-age-limit>, App Engine retries the cron job until both limits are reached. When omitted from the parameters, the limit is set to 5 by default.
<job-age-limit> The time limit for retrying a failed cron job, measured from when the cron job was first run. The value is a number followed by a unit of time, where the unit is s for seconds, m for minutes, h for hours, or d for days. For example, the value 5d specifies a limit of five days after the cron job's first execution attempt. If specified with <job-retry-limit>, App Engine retries the cron job until both limits are reached.
<min-backoff-seconds> The minimum number of seconds to wait before retrying a cron job after it fails.
<max-backoff-seconds> The maximum number of seconds to wait before retrying a cron job after it fails.
<max-doublings> The maximum number of times that the interval between failed cron job retries will be doubled before the increase becomes constant. The constant is: 2**(max_doublings - 1) * min_backoff.

Cron requests

Request headers

Requests from the Cron Service will contain a HTTP header:

X-Appengine-Cron: true

This and other headers are set internally by App Engine. If a client sends these headers, they are removed from the request. The exception being requests from logged in administrators of legacy apps, who are allowed to set the header for testing purposes.

Originating IP address

App Engine issues Cron requests from the IP address 0.1.0.1.

Deadlines

The cron timeout deadline depends on the instance class and scaling type that are configured for your app:

Automatic scaling
Timeout is about 10 minutes.
Basic scaling and manual scaling
Timeout can be up to 24 hours.

For more information, see How instances are managed.

Limits

Free applications can have up to 20 scheduled tasks. Paid applications can have up to 250 scheduled tasks.

Cron support in the development server

The development server doesn't automatically run your cron jobs. You can use your local desktop's cron or scheduled tasks interface to trigger the URLs of your jobs with curl or a similar tool.

Deploying cron jobs

You can use the appcfg.sh tool to deploy your cron jobs to App Engine.

Option 1: Upload your whole application

To upload your whole application, which also updates the Cron Service with the entries from your cron.xml file, run the following command:

./appengine-java-sdk/bin/appcfg.sh -A your-app-id -V app-version update [YOUR_APP_DIR]
Option 2: Upload only your cron updates

To update just the cron configuration without uploading the rest of the application, run the following command:

./appengine-java-sdk/bin/appcfg.sh -A your-app-id -V app-version update_cron [YOUR_APP_DIR]

Deleting all cron jobs

To delete all cron jobs:

  1. Edit the contents of the cron.xml file to: 

    <?xml version="1.0" encoding="UTF-8"?>
<cronentries/>

  2. Deploy the cron.xml file to App Engine.

Cron support in the Cloud Console

The Cloud Console Task queues page has a tab that shows the tasks that are running cron jobs.

You can also visit the Logs page to see when cron jobs were added or removed.