From e86c7ec65a65a1b8d73c5981ca8636aee49f496b Mon Sep 17 00:00:00 2001 From: Javier Aliaga Date: Wed, 7 May 2025 15:51:52 +0200 Subject: [PATCH 1/8] docs: add jobs overwrite flag Signed-off-by: Javier Aliaga --- .../building-blocks/jobs/jobs-features-concepts.md | 4 ++-- daprdocs/content/en/reference/api/jobs_api.md | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md index 0d528f2c03b..4a5b766906b 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md +++ b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md @@ -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 will result in an error. However, if the `overwrite` flag is set to `true`, the new job will overwrite the existing job with the same name. ## Scheduling Jobs A job can be scheduled using any of the following mechanisms: @@ -115,6 +114,7 @@ POST request to the endpoint `/job/`. 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 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 diff --git a/daprdocs/content/en/reference/api/jobs_api.md b/daprdocs/content/en/reference/api/jobs_api.md index bb635e3c759..b514584299e 100644 --- a/daprdocs/content/en/reference/api/jobs_api.md +++ b/daprdocs/content/en/reference/api/jobs_api.md @@ -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 it the job can overwrite an existing one. Default value is `false` #### schedule `schedule` accepts both systemd timer-style cron expressions, as well as human readable '@' prefixed period strings, as defined below. From 0dd287e7eabca28a3b016dde7e6082abf5964277 Mon Sep 17 00:00:00 2001 From: Javier Aliaga Date: Thu, 15 May 2025 12:16:22 +0200 Subject: [PATCH 2/8] Update daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md Co-authored-by: Mark Fussell Signed-off-by: Javier Aliaga --- .../building-blocks/jobs/jobs-features-concepts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md index 4a5b766906b..6902af1c39c 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md +++ b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md @@ -19,7 +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. By default, any attempt to create a new job using the same name as an existing job will result in an error. However, if the `overwrite` flag is set to `true`, the new job will overwrite the existing job with the same name. +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: From ad484cf737478be8db1e0090c3c89e0fa1f28feb Mon Sep 17 00:00:00 2001 From: Javier Aliaga Date: Thu, 15 May 2025 12:16:29 +0200 Subject: [PATCH 3/8] Update daprdocs/content/en/reference/api/jobs_api.md Co-authored-by: Mark Fussell Signed-off-by: Javier Aliaga --- daprdocs/content/en/reference/api/jobs_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/api/jobs_api.md b/daprdocs/content/en/reference/api/jobs_api.md index b514584299e..5412a1fba1a 100644 --- a/daprdocs/content/en/reference/api/jobs_api.md +++ b/daprdocs/content/en/reference/api/jobs_api.md @@ -37,7 +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 it the job can overwrite an existing one. Default value is `false` +`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. From ed6cdb4f00404619a3715e0fc902e3f7c235a07e Mon Sep 17 00:00:00 2001 From: Javier Aliaga Date: Thu, 15 May 2025 12:38:57 +0200 Subject: [PATCH 4/8] docs: Rewrite job-overview features Signed-off-by: Javier Aliaga --- .../building-blocks/jobs/jobs-overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md index 688b30b0420..a598cc99052 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md @@ -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. From f2badfad9ba7022c32f098eefdc612372de4bcda Mon Sep 17 00:00:00 2001 From: Javier Aliaga Date: Tue, 20 May 2025 10:03:32 +0200 Subject: [PATCH 5/8] Update daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md Co-authored-by: Josh van Leeuwen Signed-off-by: Javier Aliaga --- .../building-blocks/jobs/jobs-features-concepts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md index 6902af1c39c..fbdac273eea 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md +++ b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md @@ -114,7 +114,7 @@ POST request to the endpoint `/job/`. 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 +- `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 From 7d5f18a41fdcf05abbe864ee72aac84f43720d65 Mon Sep 17 00:00:00 2001 From: Javier Aliaga Date: Wed, 21 May 2025 10:31:15 +0200 Subject: [PATCH 6/8] Update daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md Co-authored-by: Cassie Coyle Signed-off-by: Javier Aliaga --- .../building-blocks/jobs/jobs-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md index a598cc99052..506765423e5 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md @@ -53,7 +53,7 @@ Dapr's jobs API ensures the tasks represented in these scenarios are performed c ## Features -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. +The main functionality of the 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 to `true`. This ensures that existing jobs are not accidentally modified or overwritten. ### Schedule jobs across multiple replicas From 00e789f67f2add6df00b83b903726de38e25e6da Mon Sep 17 00:00:00 2001 From: Javier Aliaga Date: Wed, 21 May 2025 10:31:35 +0200 Subject: [PATCH 7/8] Update daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md Co-authored-by: Cassie Coyle Signed-off-by: Javier Aliaga --- .../building-blocks/jobs/jobs-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md index 506765423e5..ae2ed0890db 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md @@ -57,7 +57,7 @@ The main functionality of the Jobs API allows you to create, retrieve, and delet ### Schedule jobs across multiple replicas -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. +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. From 8209b93a59291f7de227be1b01f794090a5e96d5 Mon Sep 17 00:00:00 2001 From: Mark Fussell Date: Fri, 23 May 2025 22:16:37 -0700 Subject: [PATCH 8/8] Update daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md Signed-off-by: Mark Fussell --- .../building-blocks/jobs/jobs-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md index ae2ed0890db..a48623ecf99 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md @@ -53,7 +53,7 @@ Dapr's jobs API ensures the tasks represented in these scenarios are performed c ## Features -The main functionality of the 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 to `true`. This ensures that existing jobs are not accidentally modified or overwritten. +The main functionality of the 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 fails unless you explicitly set the `overwrite` flag to `true`. This ensures that existing jobs are not accidentally modified or overwritten. ### Schedule jobs across multiple replicas