Skip to content

docs: add jobs overwrite flag #4646

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: v1.16
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,7 @@ All jobs are registered with a case-sensitive job name. These names are intended
interfacing with the Dapr runtime. The name is used as an identifier when creating and modifying the job as well as
to indicate which job a triggered invocation is associated with.

Only one job can be associated with a name at any given time. Any attempt to create a new job using the same name
as an existing job will result in an overwrite of this existing job.
Only one job can be associated with a name at any given time. By default, any attempt to create a new job using the same name as an existing job results in an error. However, if the `overwrite` flag is set to `true`, the new job overwrites the existing job with the same name.

## Scheduling Jobs
A job can be scheduled using any of the following mechanisms:
Expand Down Expand Up @@ -115,6 +114,7 @@ POST request to the endpoint `/job/<job-name>`. The body includes the following
or the not-before time from which the schedule should take effect
- `Ttl`: An optional value indicating when the job should expire
- `Payload`: A collection of bytes containing data originally stored when the job was scheduled
- `Overwrite`: An optional flag to allow the job to overwrite an existing job with the same name
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: the API is not an optional || pointer in the API.

Suggested change
- `Overwrite`: An optional flag to allow the job to overwrite an existing job with the same name
- `Overwrite`: A flag to allow the requested job to overwrite an existing job with the same name, if it already exists.


The `DueTime` and `Ttl` fields will reflect an RC3339 timestamp value reflective of the time zone provided when the job was
originally scheduled. If no time zone was provided, these values indicate the time zone used by the server running
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -53,11 +53,11 @@ Dapr's jobs API ensures the tasks represented in these scenarios are performed c

## Features

The jobs API provides several features to make it easy for you to schedule jobs.
The main functionality of jobs API allows you to create, retrieve, and delete scheduled jobs. By default, when you create a job with a name that already exists, the operation will fail unless you explicitly set the 'overwrite' flag. This ensures that existing jobs are not accidentally modified or overwritten.

### Schedule jobs across multiple replicas

When you create a job, it replaces any existing job with the same name. This means that every time a job is created, it resets the count and only keeps 1 record in the embedded etcd for that job. Therefore, you don't need to worry about multiple jobs being created and firing off — only the most recent job is recorded and executed, even if all your apps schedule the same job on startup.
When you create a job, it does not replace an existing job with the same name, unless you explicitly set the 'overwrite' flag. This means that every time a job is created, it resets the count and only keeps 1 record in the embedded etcd for that job. Therefore, you don't need to worry about multiple jobs being created and firing off — only the most recent job is recorded and executed, even if all your apps schedule the same job on startup.

The Scheduler service enables the scheduling of jobs to scale across multiple replicas, while guaranteeing that a job is only triggered by 1 Scheduler service instance.

Expand Down
1 change: 1 addition & 0 deletions daprdocs/content/en/reference/api/jobs_api.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ Parameter | Description
`dueTime` | An optional time at which the job should be active, or the "one shot" time, if other scheduling type fields are not provided. Accepts a "point in time" string in the format of RFC3339, Go duration string (calculated from creation time), or non-repeating ISO8601.
`repeats` | An optional number of times in which the job should be triggered. If not set, the job runs indefinitely or until expiration.
`ttl` | An optional time to live or expiration of the job. Accepts a "point in time" string in the format of RFC3339, Go duration string (calculated from job creation time), or non-repeating ISO8601.
`overwrite` | A boolean value to specify if the job can overwrite an existing one with the same name. Default value is `false`

#### schedule
`schedule` accepts both systemd timer-style cron expressions, as well as human readable '@' prefixed period strings, as defined below.
Expand Down