Jobs [Distributed Scheduler] API docs, pt.1

daprdocs/content/en/concepts/building-blocks-concept.md

@@ -29,4 +29,5 @@ Dapr provides the following building blocks:
 | [**Secrets**]({{< ref "secrets-overview.md" >}}) | `/v1.0/secrets` | Dapr provides a secrets building block API and integrates with secret stores such as public cloud stores, local stores and Kubernetes to store the secrets. Services can call the secrets API to retrieve secrets, for example to get a connection string to a database.
 | [**Configuration**]({{< ref "configuration-api-overview.md" >}}) | `/v1.0/configuration` | The Configuration API enables you to retrieve and subscribe to application configuration items for supported configuration stores. This enables an application to retrieve specific configuration information, for example, at start up or when configuration changes are made in the store. 
 | [**Distributed lock**]({{< ref "distributed-lock-api-overview.md" >}}) | `/v1.0-alpha1/lock` | The distributed lock API enables you to take a lock on a resource so that multiple instances of an application can access the resource without conflicts and provide consistency guarantees.  
-| [**Cryptography**]({{< ref "cryptography-overview.md" >}}) | `/v1.0-alpha1/crypto` | The Cryptography API enables you to perform cryptographic operations, such as encrypting and decrypting messages, without exposing keys to your application.
+| [**Cryptography**]({{< ref "cryptography-overview.md" >}}) | `/v1.0-alpha1/crypto` | The Cryptography API enables you to perform cryptographic operations, such as encrypting and decrypting messages, without exposing keys to your application.
+| [**Jobs**]({{< ref "jobs-overview.md" >}}) | `/v1.0-alpha1/jobs` | The Jobs API enables you to schedule and orchestrate jobs. Example scenarios include: <ul><li>Schedule batch processing jobs to run every business day</li><li>Schedule various maintenance scripts to perform clean-ups</li><li>Schedule ETL jobs to run at specific times (hourly, daily) to fetch new data, process it, and update the data warehouse with the latest information.</li></ul>

daprdocs/content/en/concepts/dapr-services/scheduler.md

@@ -0,0 +1,24 @@
+---
+type: docs
+title: "Dapr Scheduler control plane service overview"
+linkTitle: "Scheduler"
+description: "Overview of the Dapr scheduler service"
+---
+
+The Dapr Scheduler service is used to schedule jobs, running in [self-hosted mode]({{< ref self-hosted >}}) or on [Kubernetes]({{< ref kubernetes >}}).  
+
+The diagram below shows how the Scheduler service is used via the jobs API when called from your application. All the jobs that are tracked by the Scheduler service are stored in an embedded Etcd database. 
+
+<img src="/images/scheduler/scheduler-architecture.png" alt="Diagram showing the Scheduler control plane service and the jobs API">
+
+## Self-hosted mode
+
+The Scheduler service Docker container is started automatically as part of `dapr init`. It can also be run manually as a process if you are running in [slim-init mode]({{< ref self-hosted-no-docker.md >}}).
+
+## Kubernetes mode
+
+The Scheduler service is deployed as part of `dapr init -k`, or via the Dapr Helm charts. For more information on running Dapr on Kubernetes, visit the [Kubernetes hosting page]({{< ref kubernetes >}}).
+
+## Related links
+
+[Learn more about the Jobs API.]({{< ref jobs_api.md >}})

daprdocs/content/en/concepts/overview.md

@@ -54,6 +54,7 @@ Each of these building block APIs is independent, meaning that you can use any n
 | [**Configuration**]({{< ref "configuration-api-overview.md" >}})  | The configuration API enables you to retrieve and subscribe to application configuration items from configuration stores. 
 | [**Distributed lock**]({{< ref "distributed-lock-api-overview.md" >}})  | The distributed lock API enables your application to acquire a lock for any resource that gives it exclusive access until either the lock is released by the application, or a lease timeout occurs. 
 | [**Cryptography**]({{< ref "cryptography-overview.md" >}}) | The cryptography API provides an abstraction layer on top of security infrastructure such as key vaults. It contains APIs that allow you to perform cryptographic operations, such as encrypting and decrypting messages, without exposing keys to your applications.
+| [**Jobs**]({{< ref "jobs-overview.md" >}}) | The jobs API enables you to schedule jobs at specific times or intervals.
 
 ### Cross-cutting APIs
 

daprdocs/content/en/developing-applications/building-blocks/jobs/_index.md

@@ -0,0 +1,7 @@
+---
+type: docs
+title: "Jobs"
+linkTitle: "Jobs"
+weight: 120
+description: "Manage the scheduling and orchestration of jobs"
+---

daprdocs/content/en/developing-applications/building-blocks/jobs/howto-schedule-jobs.md

@@ -0,0 +1,30 @@
+---
+type: docs
+title: "How-To: Schedule jobs"
+linkTitle: "How-To: Schedule jobs"
+weight: 2000
+description: "Learn how to use the jobs API to schedule jobs"
+---
+
+Now that you've learned what the [jobs building block]({{< ref jobs-overview.md >}}) provides, let's look at an example of how to use the API. The code example below describes an application that schedules and orchestrates ***TBD***.
+
+<!-- 
+Include a diagram or image, if possible. 
+-->
+
+<!-- 
+Make sure the how-to includes examples for multiple programming languages, OS, or deployment targets, if applicable. 
+-->
+
+## Configure jobs
+
+
+<!-- 
+Each H2 step should start with a verb/action word.
+-->
+
+
+## Next steps
+
+- [Learn more about the Scheduler control plane service]({{< ref "concepts/dapr-services/scheduler.md" >}})
+- [Jobs API reference]({{< ref jobs_api.md >}})

daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md

@@ -0,0 +1,62 @@
+---
+type: docs
+title: "Jobs overview"
+linkTitle: "Overview"
+weight: 1000
+description: "Overview of the jobs API building block"
+---
+
+Many applications require job scheduling, the need to take an action in the future. The jobs API is an orchestrator for scheduling these jobs in the future, either at a specific time or a specific interval. 
+Some typically example scenarios include;
+- **Automated Database Backups**: Ensure a database is backed up daily to prevent data loss. Schedule a backup script to run every night at 2 AM, which will create a backup of the database and store it in a secure location.
+- **Regular Data Processing and ETL (Extract, Transform, Load)**: Process and transform raw data from various sources and load it into a data warehouse. Schedule ETL jobs to run at specific times (for example: hourly, daily) to fetch new data, process it, and update the data warehouse with the latest information.
+**Email Notifications and Reports**: Receive daily sales reports and weekly performance summaries via email. Schedule a job that generates the required reports and sends them via email at 6 AM every day for daily reports and 8 AM every Monday for weekly summaries.
+**Maintenance Tasks and System Updates**: Perform regular maintenance tasks such as clearing temporary files, updating software, and checking system health. Schedule various maintenance scripts to run at off-peak hours, such as weekends or late nights, to minimize disruption to users.
+**Batch Processing for Financial Transactions**: Processes a large number of transactions that need to be batched and settled at the end of each business day. Schedule batch processing jobs to run at 5 PM every business day, aggregating the day’s transactions and performing necessary settlements and reconciliations.
+Using the jobs API in these scenarios ensures that tasks are performed consistently and reliably without manual intervention, improving efficiency and reducing the risk of errors. The jobs API helps you with scheduling jobs, and internally it is also used by Dapr to schedule actor reminders. 
+
+### Delayed pub/sub
+
+Use jobs to delay your pub/sub messaging. You can publish a message in a future specific time -- for example, a week from today, or a specific UTC date/time.
+
+### Scheduled service invocation
+
+Use jobs with [service invocation]({{< ref service-invocation-overview.md >}}) to schedules method calls between applications.
+
+
+
+Jobs consist of:
+- The jobs API building block
+- [The Scheduler control plane service]({{< ref "concepts/dapr-services/scheduler.md" >}})
+
+<img src="/images/scheduler/scheduler-architecture.png" alt="Diagram showing the Scheduler control plane service and the jobs API">
+
+## How it works
+
+The jobs API is a job scheduler, not the executor which runs the job. The design guarantees *at least once* job execution with a bias towards durability and horizontal scaling over precision. This means:
+- **Guaranteed:** A job is never invoked *before* the schedule time is due.
+- **Not guaranteed:** A ceiling time on when the job is invoked *after* the due time is reached.
+
+All job details and user-associated data for scheduled jobs are stored in an embedded Etcd database in the Scheduler service. 
+
+## Features
+
+The jobs API provides several features to make it easy for you to schedule jobs.
+
+### Schedule jobs across multiple replicas
+
+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.
+
+### Actor reminders
+
+Actors have actor reminders, but present some limitations involving scalability using the Placement service implementation. You can make reminders more scalable by using [`SchedulerReminders`]({{< ref support-preview-features.md >}}).  This is set in the configuration for your actor application. 
+
+## Try out the jobs API
+
+You can try out the jobs API in your application. After [Dapr is installed]({{< ref install-dapr-cli.md >}}), you can begin using the jobs API, starting with [the How-to: Schedule jobs guide]({{< ref howto-schedule-jobs.md >}}).
+
+## Next steps
+
+- [Learn how to use the jobs API]({{< ref howto-schedule-jobs.md >}})
+- [Learn more about the Scheduler control plane service]({{< ref "concepts/dapr-services/scheduler.md" >}})
+- [Jobs API reference]({{< ref jobs_api.md >}})

daprdocs/content/en/getting-started/install-dapr-selfhost.md

@@ -21,9 +21,10 @@ Dapr initialization includes:
 1. Running a **Zipkin container instance** for observability.
 1. Creating a **default components folder** with component definitions for the above.
 1. Running a **Dapr placement service container instance** for local actor support.
+1. Running a **Dapr scheduler service container instance** for job scheduling.
 
 {{% alert title="Kubernetes Development Environment" color="primary" %}}
-To initialize Dapr in your local or remote **Kubernetes** cluster for development (including the Redis and Zipkin containers listed above), see [how to initialize Dapr for development on Kubernetes]({{<ref "kubernetes-deploy.md#install-dapr-from-the-official-dapr-helm-chart-with-development-flag">}})
+To initialize Dapr in your local or remote **Kubernetes** cluster for development (including the Redis and Zipkin containers listed above), see [how to initialize Dapr for development on Kubernetes]({{<ref "kubernetes-deploy.md#install-dapr-from-the-official-dapr-helm-chart-with-development-flag" >}})
 {{% /alert %}}
 
 {{% alert title="Docker" color="primary" %}}
@@ -68,7 +69,13 @@ Install the latest Dapr runtime binaries:
 dapr init
 ```
 
-**If you are installing on Mac OS Silicon with Docker,** you may need to perform the following workaround to enable `dapr init` to talk to Docker without using Kubernetes.
+If you run your Docker cmds with sudo, you need to use:
+
+```bash
+sudo dapr init
+```
+
+If you are installing on **Mac OS Silicon** with Docker, you may need to perform the following workaround to enable `dapr init` to talk to Docker without using Kubernetes.
 1. Navigate to **Docker Desktop** > **Settings** > **Advanced**.
 1. Select the **Allow the default Docker socket to be used (requires password)** checkbox.
 
@@ -86,8 +93,30 @@ dapr init
 
 {{< /tabs >}}
 
+**Expected output:**
+
+```
+⌛  Making the jump to hyperspace...
+✅  Downloaded binaries and completed components set up.
+ℹ️  daprd binary has been installed to  $HOME/.dapr/bin.
+ℹ️  dapr_placement container is running.
+ℹ️  dapr_scheduler container is running.
+ℹ️  dapr_redis container is running.
+ℹ️  dapr_zipkin container is running.
+ℹ️  Use `docker ps` to check running containers.
+✅  Success! Dapr is up and running. To get started, go here: https://aka.ms/dapr-getting-started
+```
+
 [See the troubleshooting guide if you encounter any error messages regarding Docker not being installed or running.]({{< ref "common_issues.md#dapr-cant-connect-to-docker-when-installing-the-dapr-cli" >}})
 
+#### Slim init
+
+To install the CLI without any default configuration files or Docker containers, use the `--slim` flag. [Learn more about the `init` command and its flags.]({{< ref dapr-init.md >}})
+
+```bash
+dapr init --slim
+```
+
 ### Step 3: Verify Dapr version
 
 ```bash

daprdocs/content/en/operations/support/alpha-beta-apis.md

@@ -15,6 +15,7 @@ description: "List of current alpha and beta APIs"
 | Bulk Publish    | [Bulk publish proto](https://github.com/dapr/dapr/blob/5aba3c9aa4ea9b3f388df125f9c66495b43c5c9e/dapr/proto/runtime/v1/dapr.proto#L59)     | `v1.0-alpha1/publish/bulk` | The bulk publish API allows you to publish multiple messages to a topic in a single request. | [Bulk Publish and Subscribe API]({{< ref "pubsub-bulk.md" >}}) | v1.10 |
 | Bulk Subscribe   | [Bulk subscribe proto](https://github.com/dapr/dapr/blob/5aba3c9aa4ea9b3f388df125f9c66495b43c5c9e/dapr/proto/runtime/v1/appcallback.proto#L57)     | N/A | The bulk subscribe application callback receives multiple messages from a topic in a single call. | [Bulk Publish and Subscribe API]({{< ref "pubsub-bulk.md" >}}) | v1.10 |
 | Cryptography    |  [Crypto proto](https://github.com/dapr/dapr/blob/5aba3c9aa4ea9b3f388df125f9c66495b43c5c9e/dapr/proto/runtime/v1/dapr.proto#L118)    | `v1.0-alpha1/crypto` | The cryptography API enables you to perform **high level** cryptography operations for encrypting and decrypting messages. | [Cryptography API]({{< ref "cryptography-overview.md" >}}) | v1.11 |
+| Jobs    |  [Jobs proto](https://github.com/dapr/dapr/blob/master/dapr/proto/runtime/v1/dapr.proto#L198-L204)    | `v1.0-alpha1/jobs` | The jobs API enables you to schedule and orchestrate jobs. | [Jobs API]({{< ref "jobs-overview.md" >}}) | v1.14 |
 
 ## Beta APIs
 

daprdocs/content/en/operations/support/support-preview-features.md

@@ -22,5 +22,6 @@ For CLI there is no explicit opt-in, just the version that this was first made a
 | **Service invocation for non-Dapr endpoints** | Allow the invocation of non-Dapr endpoints by Dapr using the [Service invocation API]({{< ref service_invocation_api.md >}}). Read ["How-To: Invoke Non-Dapr Endpoints using HTTP"]({{< ref howto-invoke-non-dapr-endpoints.md >}}) for more information. | N/A | [Service invocation API]({{< ref service_invocation_api.md >}}) | v1.11  |
 | **Actor State TTL** | Allow actors to save records to state stores with Time To Live (TTL) set to automatically clean up old data. In its current implementation, actor state with TTL may not be reflected correctly by clients, read [Actor State Transactions]({{< ref actors_api.md >}}) for more information. | `ActorStateTTL` | [Actor State Transactions]({{< ref actors_api.md >}}) | v1.11  |
 | **Transactional Outbox** | Allows state operations for inserts and updates to be published to a configured pub/sub topic using a single transaction across the state store and the pub/sub | N/A | [Transactional Outbox Feature]({{< ref howto-outbox.md >}}) | v1.12  |
-| **Component Hot Reloading** | Allows for Dapr-loaded components to be "hot reloaded". A component spec is reloaded either when it is created/updated/deleted in Kubernetes, or on file in self-hosted mode. Ignores changes to actor state stores and workflow backends. | `HotReload`| [Hot Reloading]({{< ref components-concept.md >}}) | v1.13  |
+| **Component Hot Reloading** | Allows for Dapr-loaded components to be "hot reloaded". A component spec is reloaded when it is created/updated/deleted in Kubernetes or on file when running in self-hosted mode. Ignores changes to actor state stores and workflow backends. | `HotReload`| [Hot Reloading]({{< ref components-concept.md >}}) | v1.13  |
 | **Subscription Hot Reloading** | Allows for declarative subscriptions to be "hot reloaded". A subscription is reloaded either when it is created/updated/deleted in Kubernetes, or on file in self-hosted mode. In-flight messages are unaffected when reloading. | `HotReload`| [Hot Reloading]({{< ref "subscription-methods.md#declarative-subscriptions" >}}) | v1.14  |
+| **Job actor reminders** | Whilst the [Scheduler service]({{< ref "concepts/dapr-services/scheduler.md" >}}) is deployed by default, job actor reminders (used for scheduling actor reminders) are enabled through a preview feature and needs a feature flag. | `SchedulerReminders`| [Job actor reminders]({{< ref "jobs-overview.md#actor-reminders" >}}) | v1.14  |

daprdocs/content/en/reference/api/jobs_api.md

@@ -0,0 +1,144 @@
+---
+type: docs
+title: "Jobs API reference"
+linkTitle: "Jobs API"
+description: "Detailed documentation on the jobs API"
+weight: 1300
+---
+
+{{% alert title="Note" color="primary" %}}
+The jobs API is currently in alpha.
+{{% /alert %}}
+
+With the jobs API, you can schedule jobs and tasks in the future.
+
+## Schedule a job
+
+Schedule a job with a name.
+
+```
+POST http://localhost:3500/v1.0-alpha1/jobs/<name>
+```
+
+### URL parameters
+
+Parameter | Description
+--------- | -----------
+`name` | Name of the job you're scheduling
+`data` | A string value and can be any related content. Content is returned when the reminder expires. For example, this may be useful for returning a URL or anything related to the content.
+`dueTime` | Specifies the time after which this job is invoked. Its format should be [time.ParseDuration](https://pkg.go.dev/time#ParseDuration)
+
+### Request body
+
+```json
+{
+  "job": {
+      "data": {
+          "@type": "type.googleapis.com/google.type.Expr",
+          "expression": "<expression>"
+      },
+      "dueTime": "30s"
+  }
+}
+```
+
+### HTTP response codes
+
+Code | Description
+---- | -----------
+`202`  | Accepted
+`400`  | Request was malformed
+`500`  | Request formatted correctly, error in dapr code or Scheduler control plane service
+
+### Response content
+
+The following example curl command creates a job, naming the job `jobforjabba` and specifying the `dueTime` and the `data`.
+
+```bash
+$ curl -X POST \
+  http://localhost:3500/v1.0-alpha1/jobs/jobforjabba \
+  -H "Content-Type: application/json" 
+  -d '{
+        "job": {
+            "data": {
+                "HanSolo": "Running spice"
+            },
+            "dueTime": "30s"
+        }
+    }'
+```
+
+
+## Get job data
+
+Get a job from its name.
+
+```
+GET http://localhost:3500/v1.0-alpha1/jobs/<name>
+```
+
+### URL parameters
+
+Parameter | Description
+--------- | -----------
+`name` | Name of the scheduled job you're retrieving
+
+### HTTP response codes
+
+Code | Description
+---- | -----------
+`202`  | Accepted
+`400`  | Request was malformed
+`500`  | Request formatted correctly, error in dapr code or Scheduler control plane service
+
+### Response content
+
+After running the following example curl command, the returned response is JSON containing the `name` of the job, the `dueTime`, and the `data`.
+
+```bash
+$ curl -X GET http://localhost:3500/v1.0-alpha1/jobs/jobforjabba -H "Content-Type: application/json" 
+```
+
+```json
+{
+  "name":"test1",
+  "dueTime":"30s",
+  "data": {
+     "HanSolo": "Running spice"
+   }
+}                                    
+```
+## Delete a job
+
+Delete a named job.
+
+```
+DELETE http://localhost:3500/v1.0-alpha1/jobs/<name> 
+```
+
+### URL parameters
+
+Parameter | Description
+--------- | -----------
+`name` | Name of the job you're deleting
+
+### HTTP response codes
+
+Code | Description
+---- | -----------
+`202`  | Accepted
+`400`  | Request was malformed
+`500`  | Request formatted correctly, error in dapr code or Scheduler control plane service
+
+### Response content
+
+In the following example curl command, the job named `test1` with app-id `sub` will be deleted
+
+```bash
+$ curl -X DELETE http://localhost:3500/v1.0-alpha1/jobs/jobforjabba -H "Content-Type: application/json" 
+```
+
+
+## Next steps
+
+[Jobs API overview]({{< ref jobs-overview.md >}})