Scheduling Jobs

Scheduling jobs allows you to create routine workflows to simplify data transfers between Agents. You can create jobs that run automatically in sequence by using the API to set job frequency, failure behavior, and priority.

Overview

When generating a job using the REST API, you can include Schedule job arguments that set when and how often a job runs.

Each Schedule attribute sets how the job processes:

  • Schedule.timezone - which time zone to use for the scheduled job in tz format
  • Schedule._sp_frequency - how often the job runs (See Job Frequency)
  • Schedule._sp_start_at - when the job should start running in YYYY/MM/DD HH:MM:SS format
  • Schedule._sp_interrupt_on_failure - sets the job’s failure state (See Job Failure)
  • Schedule.priority - sets job priority (See Job Priority)
  • Schedule.finishBefore - sets granular job priority order (See Job Priority)

Include specific Schedule arguments within the jobArgs object within the call body. For example, the following job will start in the America/Toronto time zone on May 20, 2019, at 7:10 AM. It will run daily at 7:10 AM:

    "jobArgs" : {
                    "ObjectUploader.Schedule.timezone":      "America/Toronto",
                    "ObjectUploader.Schedule._sp_start_at":  "2019/05/20 07:10:00",
                    "ObjectUploader.Schedule._sp_frequency": "DAILY",
                    "ObjectUploader.Schedule._sp_interrupt_on_failure": "no",
                    "ObjectUploader.Schedule.priority": "",
                    "ObjectUploader.Schedule.finishBefore": "",
                    ...
                }

Job Frequency

Jobs can be configured to run at a specified time and frequency to automate data transfers between Agents. Job runs use Schedule._sp_frequency and Schedule._sp_start_at job arguments to determine a job’s first run and any subsequent runs.

Frequency Description
NONE Job requires manual execution (Job status is DORMANT)
MANUAL Job requires manual execution (Job status is DORMANT)
ONCE Job executes one time at the scheduled date and time
HOURLY Job executes every hour from the start time
DAILY Job executes every day at the start time
WEEKLY Job executes once a week on the same weekday and time
MONTHLY Job executes once a month on the same day and time
MONTHEND Job executes on the last day of the month at the specified time
YEARLY Job executes once a year on the specified date and time

Ordinals

You can specify jobs to run on a particular weekday within a specific month, such as the second Thursday or the last Friday of a month:

    "jobArgs" : {
                    ...
                    "ObjectUploader.Schedule._sp_frequency": "SECOND MONDAY",

                    ...
                }

You can set Schedule._sp_frequency to use:

  • FIRST / 1ST
  • SECOND/2ND
  • THIRD/3RD
  • FOURTH/4TH
  • LAST

Intervals

You can specify that jobs run at specified intervals, such as every five hours, or every two weeks:

    "jobArgs" : {
                    ...
                    "ObjectUploader.Schedule._sp_frequency": "2 WEEKS",

                    ...
                }

You can set Schedule._sp_frequency to use:

  • MONTHS / M
  • MINUTES / MI
  • HOURS / H
  • DAYS / D
  • WEEKS / W
  • YEARS / Y

Job Failure

You can specify how a job behaves if it encounters an error or fails to complete using the Schedule._sp_interrupt_on_failure option.

Setting Schedule._sp_interrupt_on_failure to yes sets the job status to INTERRUPTED and will not continue to transfer files until resumed by an operator.

Setting Schedule._sp_interrupt_on_failure to no will end a job when it fails and display FAILED status.

Job Priority

Agents using concurrency resource controls limit the number of jobs running at a time. To schedule jobs in sequence, the Schedule.priority and Schedule.finishBefore arguments determine how to order the jobs.

The Schedule.priority argument sets a job’s overall priority level in order to place it in sequence.

You can set Schedule.priority to use:

  • LOW / 1
  • MEDIUM / 2
  • HIGH / 3
  • CRITICAL / 4
  • IMMEDIATE / 5

The Schedule.finishBefore argument determines how to queue jobs that have the same priority level, but may need to run in a specific sequence, or sooner than a previously queued job.

Set finishBefore using a date and time in YYYY/MM/DD HH:MM:SS format.

Example

As an example, two jobs are sent to the same resource controlled Agent:

    "jobName" : "example one - without a finishBefore set"
    "jobArgs" : {
                    ...
                    "ObjectUploader.Schedule.priority": "MEDIUM",
                    "ObjectUploader.Schedule.finishBefore": "",
                    ...
                }

        "jobName" : "example two - with a finishBefore set"
        "jobArgs" : {
                    ...
                    "ObjectUploader.Schedule.priority": "MEDIUM",
                    "ObjectUploader.Schedule.finishBefore": "2019/05/21 07:10:00",
                    ...
                }

If both jobs are sent to the Manager, example two will be queued by the Manager first. It has a Schedule.finishBefore set, and so will take priority over the other job.