Merge pull request #4243 from hhunter-ms/issue_3915-3

Jobs API docs, pt 3

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

@@ -0,0 +1,149 @@
+---
+type: docs
+title: "How-To: Schedule and handle triggered jobs"
+linkTitle: "How-To: Schedule and handle triggered jobs"
+weight: 2000
+description: "Learn how to use the jobs API to schedule and handle triggered 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 jobs for a database backup application and handles them at trigger time, also known as the time the job was sent back to the application because it reached it's dueTime.
+
+<!-- 
+Include a diagram or image, if possible. 
+-->
+
+## Start the Scheduler service
+
+When you [run `dapr init` in either self-hosted mode or on Kubernetes]({{< ref install-dapr-selfhost.md >}}), the Dapr Scheduler service is started.
+
+## Set up the Jobs API
+
+In your code, set up and schedule jobs within your application.
+
+{{< tabs "Go" >}}
+
+{{% codetab %}}
+
+<!--go-->
+
+The following Go SDK code sample schedules the job named `prod-db-backup`. Job data is housed in a backup database (`"my-prod-db"`) and is scheduled with `ScheduleJobAlpha1`. This provides the `jobData`, which includes:
+- The backup `Task` name
+- The backup task's `Metadata`, including:
+  - The database name (`DBName`)
+  - The database location (`BackupLocation`)
+
+
+```go
+package main
+
+import (
+    //...
+
+	daprc "github.com/dapr/go-sdk/client"
+	"github.com/dapr/go-sdk/examples/dist-scheduler/api"
+	"github.com/dapr/go-sdk/service/common"
+	daprs "github.com/dapr/go-sdk/service/grpc"
+)
+
+func main() {
+    // Initialize the server
+	server, err := daprs.NewService(":50070")
+    // ...
+
+	if err = server.AddJobEventHandler("prod-db-backup", prodDBBackupHandler); err != nil {
+		log.Fatalf("failed to register job event handler: %v", err)
+	}
+
+	log.Println("starting server")
+	go func() {
+		if err = server.Start(); err != nil {
+			log.Fatalf("failed to start server: %v", err)
+		}
+	}()
+    // ...
+
+    // Set up backup location
+	jobData, err := json.Marshal(&api.DBBackup{
+		Task: "db-backup",
+		Metadata: api.Metadata{
+			DBName:         "my-prod-db",
+			BackupLocation: "/backup-dir",
+		},
+	},
+	)
+	// ...
+}
+```
+
+The job is scheduled with a `Schedule` set and the amount of `Repeats` desired. These settings determine a max amount of times the job should be triggered and sent back to the app. 
+
+In this example, at trigger time, which is `@every 1s` according to the `Schedule`, this job is triggered and sent back to the application up to the max `Repeats` (`10`). 
+
+```go	
+    // ...
+    // Set up the job
+	job := daprc.Job{
+		Name:     "prod-db-backup",
+		Schedule: "@every 1s",
+		Repeats:  10,
+		Data: &anypb.Any{
+			Value: jobData,
+		},
+	}
+```
+
+At the trigger time, the `prodDBBackupHandler` function is called, executing the desired business logic for this job at trigger time. For example:
+
+```go
+// ...
+
+// At job trigger time this function is called
+func prodDBBackupHandler(ctx context.Context, job *common.JobEvent) error {
+	var jobData common.Job
+	if err := json.Unmarshal(job.Data, &jobData); err != nil {
+		// ...
+	}
+	decodedPayload, err := base64.StdEncoding.DecodeString(jobData.Value)
+	// ...
+
+	var jobPayload api.DBBackup
+	if err := json.Unmarshal(decodedPayload, &jobPayload); err != nil {
+		// ...
+	}
+	fmt.Printf("job %d received:\n type: %v \n typeurl: %v\n value: %v\n extracted payload: %v\n", jobCount, job.JobType, jobData.TypeURL, jobData.Value, jobPayload)
+	jobCount++
+	return nil
+}
+```
+
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+## Run the Dapr sidecar 
+
+Once you've set up the Jobs API in your application, in a terminal window run the Dapr sidecar with the following command. 
+
+{{< tabs "Go" >}}
+
+{{% codetab %}}
+
+```bash
+dapr run --app-id=distributed-scheduler \
+                --metrics-port=9091 \
+                --dapr-grpc-port 50001 \
+                --app-port 50070 \
+                --app-protocol grpc \
+                --log-level debug \
+                go run ./main.go
+```
+
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+
+## 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/howto-schedule-jobs.md

@@ -1,35 +0,0 @@
----
-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 jobs for a **TBD** application.
-
-<!--
-Include a diagram or image, if possible.
--->
-
-## Set up the Scheduler service
-
-{{% alert title="Warning" color="warning" %}}
-By default, job data is not resilient to [Scheduler]({{< ref scheduler.md >}}) service restarts.
-A persistent volume must be provided to Scheduler to ensure job data is not lost in either [Kubernetes]({{< ref kubernetes-persisting-scheduler.md >}}) or [Self-Hosted]({{< ref self-hosted-persisting-scheduler.md >}}) mode.
-{{% /alert %}}
-
-When you run `dapr init` in either self-hosted mode or on Kubernetes, the Dapr scheduler service is started.
-
-## Run the Dapr sidecar
-
-Run the Dapr sidecar alongside your application.
-
-```bash
-dapr run --app-id=jobs --app-port 50070 --app-protocol grpc --log-level debug -- go run main.go
-```
-
-## 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

@@ -70,10 +70,10 @@ Actors have actor reminders, but present some limitations involving scalability
 
 ## 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 >}}).
+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-and-handle-triggered-jobs.md >}}).
 
 ## Next steps
 
-- [Learn how to use the jobs API]({{< ref howto-schedule-jobs.md >}})
+- [Learn how to use the jobs API]({{< ref howto-schedule-and-handle-triggered-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

@@ -95,28 +95,11 @@ dapr init
 
 **Expected output:**
 
-```
+<img src="/images/install-dapr-selfhost/dapr-init-output.png" style=
-⌛  Making the jump to hyperspace...
+"padding-bottom: 5px" >
-✅  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
@@ -138,7 +121,7 @@ docker ps
 
 **Output:**  
 
-<img src="/images/install-dapr-selfhost/docker-containers.png" width=800>
+<img src="/images/install-dapr-selfhost/docker-containers.png">
 
 ### Step 5: Verify components directory has been initialized
 
@@ -189,5 +172,14 @@ explorer "%USERPROFILE%\.dapr"
 
 <br>
 
+### 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
+```
+
+
 {{< button text="Next step: Use the Dapr API >>" page="getting-started/get-started-api.md" >}}
 

daprdocs/content/en/reference/cli/dapr-uninstall.md

@@ -24,10 +24,10 @@ dapr uninstall [flags]
 
 | Name                 | Environment Variable | Default       | Description                                                                                                                                         |
 | -------------------- | -------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--all`              |                      | `false`       | Remove Redis, Zipkin containers in addition to the scheduler service and the actor placement container. Remove default dapr dir located at `$HOME/.dapr or %USERPROFILE%\.dapr\`. |
+| `--all`              |                      | `false`       | Remove Redis, Zipkin containers in addition to the Scheduler service and the actor Placement service containers. Remove default Dapr dir located at `$HOME/.dapr or %USERPROFILE%\.dapr\`. |
 | `--help`, `-h`       |                      |               | Print this help message                                                                                                                             |
 | `--kubernetes`, `-k` |                      | `false`       | Uninstall Dapr from a Kubernetes cluster                                                                                                            |
-| `--namespace`, `-n`  |                      | `dapr-system` | The Kubernetes namespace to uninstall Dapr from                                                                                                     |
+| `--namespace`, `-n`  |                      | `dapr-system` | The Kubernetes namespace from which Dapr is uninstalled                                                                                                     |
 |  `--container-runtime`  |              |    `docker`      | Used to pass in a different container runtime other than Docker. Supported container runtimes are: `docker`, `podman` |
 
 ### Examples