Concepts, terminology, and entities in Azure Scheduler
Important
Azure Logic Apps is replacing Azure Scheduler, which is being retired. To continue working with the jobs that you set up in Scheduler, please migrate to Azure Logic Apps as soon as possible.
Scheduler is no longer available in the Azure portal, but the REST API and Azure Scheduler PowerShell cmdlets remain available at this time so that you can manage your jobs and job collections.
Entity hierarchy
The Azure Scheduler REST API exposes and uses these main entities, or resources:
| Entity | Description |
|---|---|
| Job | Defines a single recurring action with simple or complex strategies for execution. Actions might include HTTP, Storage queue, Service Bus queue, or Service Bus topic requests. |
| Job collection | Contains a group of jobs and maintains settings, quotas, and throttles that are shared by jobs in the collection. As an Azure subscription owner, you can create job collections and group jobs together based on their usage or application boundaries. A job collection has these attributes: - Constrained to one region. |
| Job history | Describes details for a job execution, for example, status and any response details. |
Entity management
At a high-level, the Scheduler REST API exposes these operations for managing entities.
Job management
Supports operations for creating and editing jobs. All jobs must belong to an existing job collection, so there's no implicit creation. For more information, see Scheduler REST API - Jobs. Here's the URI address for these operations:
https://management.azure.com/subscriptions/{subscriptionID}/resourceGroups/{resourceGroupName}/providers/Microsoft.Scheduler/jobCollections/{jobCollectionName}/jobs/{jobName}
Job collection management
Supports operations for creating and editing jobs and job collections, which map to quotas and shared settings. For example, quotas specify the maximum number of jobs and smallest recurrence interval. For more information, see Scheduler REST API - Job Collections. Here's the URI address for these operations:
https://management.azure.com/subscriptions/{subscriptionID}/resourceGroups/{resourceGroupName}/providers/Microsoft.Scheduler/jobCollections/{jobCollectionName}
Job history management
Supports the GET operation for fetching 60 days of job execution history, for example, job elapsed time and job execution results. Includes query string parameter support for filtering based on state and status. For more information, see Scheduler REST API - Jobs - List Job History. Here's the URI address for this operation:
https://management.azure.com/subscriptions/{subscriptionID}/resourceGroups/{resourceGroupName}/providers/Microsoft.Scheduler/jobCollections/{jobCollectionName}/jobs/{jobName}/history
Job types
Azure Scheduler supports multiple job types:
- HTTP jobs, including HTTPS jobs that support TLS, for when you have the endpoint for an existing service or workload
- Storage queue jobs for workloads that use Storage queues, such as posting messages to Storage queues
- Service Bus queue jobs for workloads that use Service Bus queues
- Service Bus topic jobs for workloads that use Service Bus topics
Job definition
At the high level, a Scheduler job has these basic parts:
- The action that runs when the job timer fires
- Optional: The time to run the job
- Optional: When and how often to repeat the job
- Optional: An error action that runs if the primary action fails
The job also includes system-provided data such as the job's next scheduled run time. The job's code definition is an object in JavaScript Object Notation (JSON) format, which has these elements:
| Element | Required | Description |
|---|---|---|
| startTime | No | The start time for the job with a time zone offset in ISO 8601 format |
| action | Yes | The details for the primary action, which can include an errorAction object |
| errorAction | No | The details for the secondary action that runs if the primary action fails |
| recurrence | No | The details such as frequency and interval for a recurring job |
| retryPolicy | No | The details for how often to retry an action |
| state | Yes | The details for the job's current state |
| status | Yes | The details for the job's current status, which is controlled by the service |
Here's an example that shows a comprehensive job definition for an HTTP action with fuller element details described in later sections:
"properties": {
"startTime": "2012-08-04T00:00Z",
"action": {
"type": "Http",
"request": {
"uri": "http://contoso.com/some-method",
"method": "PUT",
"body": "Posting from a timer",
"headers": {
"Content-Type": "application/json"
},
"retryPolicy": {
"retryType": "None"
},
},
"errorAction": {
"type": "Http",
"request": {
"uri": "http://contoso.com/notifyError",
"method": "POST"
}
}
},
"recurrence": {
"frequency": "Week",
"interval": 1,
"schedule": {
"weekDays": ["Monday", "Wednesday", "Friday"],
"hours": [10, 22]
},
"count": 10,
"endTime": "2012-11-04"
},
"state": "Disabled",
"status": {
"lastExecutionTime": "2007-03-01T13:00:00Z",
"nextExecutionTime": "2007-03-01T14:00:00Z ",
"executionCount": 3,
"failureCount": 0,
"faultedCount": 0
}
}
startTime
In the startTime object, you can specify the start time and a time zone offset in ISO 8601 format.
action
Your Scheduler job runs a primary action based on the specified schedule. Scheduler supports HTTP, Storage queue, Service Bus queue, and Service Bus topic actions. If the primary action fails, Scheduler can run a secondary errorAction that handles the error. The action object describes these elements:
- The action's service type
- The action's details
- An alternative errorAction
The previous example describes an HTTP action. Here's an example for a Storage queue action:
"action": {
"type": "storageQueue",
"queueMessage": {
"storageAccount": "myStorageAccount",
"queueName": "myqueue",
"sasToken": "TOKEN",
"message": "My message body"
}
}
Here's an example for a Service Bus queue action:
"action": {
"type": "serviceBusQueue",
"serviceBusQueueMessage": {
"queueName": "q1",
"namespace": "mySBNamespace",
"transportType": "netMessaging", // Either netMessaging or AMQP
"authentication": {
"sasKeyName": "QPolicy",
"type": "sharedAccessKey"
},
"message": "Some message",
"brokeredMessageProperties": {},
"customMessageProperties": {
"appname": "FromScheduler"
}
}
},
Here's an example for a Service Bus topic action:
"action": {
"type": "serviceBusTopic",
"serviceBusTopicMessage": {
"topicPath": "t1",
"namespace": "mySBNamespace",
"transportType": "netMessaging", // Either netMessaging or AMQP
"authentication": {
"sasKeyName": "QPolicy",
"type": "sharedAccessKey"
},
"message": "Some message",
"brokeredMessageProperties": {},
"customMessageProperties": {
"appname": "FromScheduler"
}
}
},
For more information about Shared Access Signature (SAS) tokens, see Authorize with Shared Access Signatures.
errorAction
If your job's primary action fails, Scheduler can run an errorAction that handles the error. In the primary action, you can specify an errorAction object so Scheduler can call an error-handling endpoint or send a user notification.
For example, if a disaster happens at the primary endpoint, you can use errorAction for calling a secondary endpoint, or for notifying an error handling endpoint.
Just like the primary action, you can have the error action use simple or composite logic based on other actions.
recurrence
A job recurs if the job's JSON definition includes the recurrence object, for example:
"recurrence": {
"frequency": "Week",
"interval": 1,
"schedule": {
"hours": [10, 22],
"minutes": [0, 30],
"weekDays": ["Monday", "Wednesday", "Friday"]
},
"count": 10,
"endTime": "2012-11-04"
},
| Property | Required | Value | Description |
|---|---|---|---|
| frequency | Yes, when recurrence is used | "Minute", "Hour", "Day", "Week", "Month", "Year" | The time unit between occurrences |
| interval | No | 1 to 1000 inclusively | A positive integer that determines the number of time units between each occurrence based on frequency |
| schedule | No | Varies | The details for more complex and advanced schedules. See hours, minutes, weekDays, months, and monthDays |
| hours | No | 1 to 24 | An array with the hour marks for when to run the job |
| minutes | No | 0 to 59 | An array with the minute marks for when to run the job |
| months | No | 1 to 12 | An array with the months for when to run the job |
| monthDays | No | Varies | An array with the days of the month for when to run the job |
| weekDays | No | "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" | An array with days of the week for when to run the job |
| count | No | <none> | The number of recurrences. The default is to recur infinitely. You can't use both count and endTime, but the rule that finishes first is honored. |
| endTime | No | <none> | The date and time for when to stop the recurrence. The default is to recur infinitely. You can't use both count and endTime, but the rule that finishes first is honored. |
For more information about these elements, see Build complex schedules and advanced recurrences.
retryPolicy
For the case when a Scheduler job might fail, you can set up a retry policy, which determines whether and how Scheduler retries the action. By default, Scheduler retries the job four more times at 30-second intervals. You can make this policy more or less aggressive, for example, this policy retries an action two times per day:
"retryPolicy": {
"retryType": "Fixed",
"retryInterval": "PT1D",
"retryCount": 2
},
| Property | Required | Value | Description |
|---|---|---|---|
| retryType | Yes | Fixed, None | Determines whether you specify a retry policy (fixed) or not (none). |
| retryInterval | No | PT30S | Specifies the interval and frequency between retry attempts in ISO 8601 format. The minimum value is 15 seconds, while the maximum value is 18 months. |
| retryCount | No | 4 | Specifies the number of retry attempts. The maximum value is 20. |
For more information, see High availability and reliability.
state
A job's state is either Enabled, Disabled, Completed, or Faulted, for example:
"state": "Disabled"
To change jobs to Enabled or Disabled state, you can use the PUT or PATCH operation on those jobs. However, if a job has Completed or Faulted state, you can't update the state, although you can perform the DELETE operation on the job. Scheduler deletes completed and faulted jobs after 60 days.
status
After a job starts, Scheduler returns information about the job's status through the status object, which only Scheduler controls. However, you can find the status object inside the job object. Here's the information that a job's status includes:
- Time for the previous execution, if any
- Time for the next scheduled execution for jobs in progress
- The number of job executions
- The number of failures, if any
- The number of faults, if any
For example:
"status": {
"lastExecutionTime": "2007-03-01T13:00:00Z",
"nextExecutionTime": "2007-03-01T14:00:00Z ",
"executionCount": 3,
"failureCount": 0,
"faultedCount": 0
}