Scheduled Jobs

Your scripts can be executed on a recurring schedule by creating a scheduled job using the popular CRON schedule syntax. The scheduler runs every 5 minutes and checks for any scheduled jobs that need to run. When a job is found, it will enqueue the job for execution and execute the script attached to the job.

To create a scheduled job, you can use the “Add a Scheduled Job…” link on the right-side action panel or you can navigate to the Scheduled Jobs tab on the left and click on the “New Job” button.

When creating a new scheduled job, you will be presented with the following modal window:

The following fields are available for defining a scheduled job:

• Name
  This is the friendly name of the scheduled job. It’s a good idea to use this field to be descriptive about your schedule so it’s easy to identify it’s behavior.

• Time Zone
  Set this if it makes sense to execute your script according to a specific time zone (particularly if you define the “hour” schedule component), otherwise UTC will be used.

• Schedule Components

  • Minute
    Use a specified minute unit, based on the CRON schedule format. You can enter an asterisk to indicate every minute of the hour (for example, *), a specific minute of the hour (for example, 0 would happen at the top of the hour), a hyphenated range for every minute within the range (for example, 0-15 would occur within the first 15 minutes of the hour), a comma-separated list of numbers to indicate specific minutes of the hour (for example, 0,30 would occur at the top of the hour and at half the hour), or a forward slash to indicate step-values (for example, */15 would occur every 15 minutes of the hour).

  • Hour

    Use a specified hour unit, based on the CRON schedule format. You can enter an asterisk to indicate every hour of the day (for example, *), a specific hour of the day (for example, 17 would happen at 5 PM each day - note the 24-hour time format), a hyphenated range for every hour within the range (for example, 8-17 would occur between 8 AM and 5 PM of the day), a comma-separated list of numbers to indicate specific hours of the day (for example, 0,6,12,18 would occur at midnight, 6 AM, noon, and 6 PM of the day), or a forward slash to indicate step-values (for example, */4 would occur every 4 hours of the day).

  • Day
    Use a specified day unit, based on the CRON schedule format. You can enter an asterisk to indicate every day of the month (for example, *), a specific day of the month (for example, 1 for the first day of the month. You can also use L to indicate the last day of the month), a hyphenated range for every day within the range (for example, 1-14 would occur within the first 14 days of the month), a comma-separated list of numbers to indicate specific days of the month (for example, 15,L would occur on the 15th and the last day of the month), or a forward slash to indicate step-values (for example, */2 would occur every other day).

  • Month
    Use a specified month unit, based on the CRON schedule format. You can enter an asterisk to indicate every month of the year (for example, *), a specific month of the year (for example, JAN would happen in January), a hyphenated range for every month within the range (for example, JAN-MAR would occur January through March), a comma-separated list to indicate specific months of the year (for example, JAN,APR,JUL,OCT would occur each quarter-starting month), or a forward slash to indicate step-values (for example, */3 would occur every third month).

  • Weekday
    Use a specified weekday unit, based on the CRON schedule format. You can enter an asterisk to indicate every day of the week (for example, *), a specific day of the week (for example, FRI would happen on Fridays), a hyphenated range for each day of the week within the range (for example, MON-FRI would occur Monday through Friday of the week), or a comma-separated list to indicate specific days of the week (for example, SAT,SUN would occur on Saturday and Sunday of the week).

VERY IMPORTANT!

Because the scheduler only checks the schedule every 5 minutes, it’s important to only use increments of 5 within the minute schedule component. If your minute component is not an asterisk, or does not end with a 0 or 5 (including ranges, separated values, or step values), your schedule will never enqueue and your script will not get executed.

You can use the Verify Schedule button to view a list of upcoming scheduled events to help you verify that you’ve configured your schedule the way that you want it.

Scheduled Job Use Cases

Below are some use cases on how to apply a job schedule to scripts in a variety of scenarios.

Execute a script every hour

Scenario: You have a script that creates a comment in upcoming tasks to help notify their assignees that they are due soon. You would like to execute this script every hour.

CRON schedule: Minute: 0, Hour: *, Day: *, Month: *, Weekday: *

Execute a script every day

Scenario: You have a script that you would like to execute every day at 7 AM.

CRON schedule: Minute: 0, Hour: 7, Day: *, Month: *, Weekday: *

Execute a script only during working days and working hours

Scenario: You have a script that creates comments on tasks that are late to notify their assignees that you would like to execute every hour, 5 minutes after the hour, but only during work days, and only during work hours.

CRON schedule: Minute: 5, Hour: 9-17, Day: *, Month: *, Weekday: MON-FRI

Execute a script once a week on Sunday

Scenario: You have a script that makes matters inactive that haven’t had any projects in the last 3 months that you would like executed once a week on Sunday at 8 PM.

CRON schedule: Minute: 0, Hour: 20, Day: *, Month: *, Weekday: SUN

Execute once a month

Scenario: You have a script that creates a project that you would like executed once a month at 8 AM on the 1st.

CRON schedule: Minute: 0, Hour: 8, Day: 1, Month: *, Weekday: *

Execute twice a month

Scenario: You have a billing script that you would like to execute twice a month at 10 PM. Once on the 15th, and once again on the last day of the month.

CRON schedule: Minute: 0, Hour: 22, Day: 15,L, Month: *, Weekday: *

Execute once a quarter

Scenario: You have a script that syncs contacts that you would like to execute once a quarter at 5 AM.

CRON schedule: Minute: 0, Hour: 5, Day: 1, Month: JAN,APR,JUL,OCT, Weekday: *

Timeout Concerns

If you have a script that will run longer than 60 seconds on a scheduled job, the script will timeout, and only some of your data may have been updated. You can deal with the timeout restrictions by creating staggered job schedules. For example, a daily script that needs to run in the morning across many records could have multiple job schedules where the minute component could be defined with an asterisk so the script runs every 5 minutes of the specified hour, or if it doesn’t need to run that long, a ranged set of minutes (such as 0-15 to have the script execute 4 times within the hour). If the script leverages filtering techniques to only retrieve the data that it needs to iterate and update, this could get around the timeout restriction elegantly enough. If you have more robust needs and filtering won’t quite work, you could create a series of scripts that can act on specific records within their time constraints (such as only retrieving a specific list of matters based on a range of matter ids for each script).