Merge branch 'v1.12' into issue_3749

Author: hhunter-ms

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

@@ -28,5 +28,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.  
-| [**Workflows**]({{< ref "workflow-overview.md" >}}) | `/v1.0-alpha1/workflow` | The Workflow API enables you to define long running, persistent processes or data flows that span multiple microservices using Dapr workflows or workflow components. The Workflow API can be combined with other Dapr API building blocks. For example, a workflow can call another service with service invocation or retrieve secrets, providing flexibility and portability. 
+| [**Workflows**]({{< ref "workflow-overview.md" >}}) | `/v1.0-beta1/workflow` | The Workflow API enables you to define long running, persistent processes or data flows that span multiple microservices using Dapr workflows or workflow components. The Workflow API can be combined with other Dapr API building blocks. For example, a workflow can call another service with service invocation or retrieve secrets, providing flexibility and portability. 
 | [**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.

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

@@ -17,7 +17,7 @@ The placement service is deployed as part of `dapr init -k`, or via the Dapr Hel
 
 ## Placement tables
 
-There is an HTTP API `/placement/state` for placement service that exposes placement table information. The API is exposed on the sidecar on the same port as the healthz. This is an unauthenticated endpoint, and is disabled by default. You need to set `DAPR_PLACEMENT_METADATA_ENABLED` environment or `metadata-enabled` command line args to true to enable it. If you are using helm you just need to set `dapr_placement.metadataEnabled` to true.
+There is an [HTTP API `/placement/state` for placement service]({{< ref placement_api.md >}}) that exposes placement table information. The API is exposed on the sidecar on the same port as the healthz. This is an unauthenticated endpoint, and is disabled by default. You need to set `DAPR_PLACEMENT_METADATA_ENABLED` environment or `metadata-enabled` command line args to true to enable it. If you are using helm you just need to set `dapr_placement.metadataEnabled` to true.
 
 ### Usecase:
 The placement table API can be used for retrieving the current placement table, which contains all the actors registered. This can be helpful for debugging and allows tools to extract and present information about actors.
@@ -83,3 +83,7 @@ updatedAt | timestamp | Timestamp of the actor registered/updated.
 	"tableVersion": 1
 }
 ```
+
+## Related links
+
+[Learn more about the Placement API.]({{< ref placement_api.md >}})

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

@@ -96,6 +96,10 @@ For more information on message routing, read [Dapr pub/sub API reference]({{< r
 
 Sometimes, messages can't be processed because of a variety of possible issues, such as erroneous conditions within the producer or consumer application or an unexpected state change that causes an issue with your application code. Dapr allows developers to set dead letter topics to deal with messages that cannot be delivered to an application. This feature is available on all pub/sub components and prevents consumer applications from endlessly retrying a failed message. For more information, read about [dead letter topics]({{< ref "pubsub-deadletter.md">}})
 
+### Enabling the outbox pattern
+
+Dapr enables developers to use the outbox pattern for achieving a single transaction across a transactional state store and any message broker. For more information, read [How to enable transactional outbox messaging]({{< ref howto-outbox.md >}})
+
 ### Namespace consumer groups
 
 Dapr solves multi-tenancy at-scale with [namespaces for consumer groups]({{< ref howto-namespace >}}). Simply include the `"{namespace}"` value in your component metadata for consumer groups to allow multiple namespaces with applications of the same `app-id` to publish and subscribe to the same message broker.

daprdocs/content/en/developing-applications/building-blocks/state-management/howto-outbox.md

@@ -0,0 +1,112 @@
+---
+type: docs
+title: "How-To: Enable the transactional outbox pattern"
+linkTitle: "How-To: Enable the transactional outbox pattern"
+weight: 400
+description: "Commit a single transaction across a state store and pub/sub message broker"
+---
+
+The transactional outbox pattern is a well known design pattern for sending notifications regarding changes in an application's state. The transactional outbox pattern uses a single transaction that spans across the database and the message broker delivering the notification. 
+
+Developers are faced with many difficult technical challenges when trying to implement this pattern on their own, which often involves writing error-prone central coordination managers that, at most, support a combination of one or two databases and message brokers.
+
+For example, you can use the outbox pattern to:  
+1. Write a new user record to an account database. 
+1. Send a notification message that the account was successfully created. 
+
+With Dapr's outbox support, you can notify subscribers when an application's state is created or updated when calling Dapr's [transactions API]({{< ref "state_api.md#state-transactions" >}}).
+
+The diagram below is an overview of how the outbox feature works:
+
+1) Service A saves/updates state to the state store using a transaction.
+2) A message is written to the broker under the same transaction. When the message is successfully delivered to the message broker, the transaction completes, ensuring the state and message are transacted together.
+3) The message broker delivers the message topic to any subscribers - in this case, Service B.
+
+<img src="/images/state-management-outbox.png" width=800 alt="Diagram showing the steps of the outbox pattern">
+
+## Requirements
+
+The outbox feature can be used with using any [transactional state store]({{< ref supported-state-stores >}}) supported by Dapr. All [pub/sub brokers]({{< ref supported-pubsub >}}) are supported with the outbox feature.
+
+{{% alert title="Note" color="primary" %}} 
+Message brokers that work with the competing consumer pattern (for example, [Apache Kafka]({{< ref setup-apache-kafka>}}) are encouraged to reduce the chances of duplicate events.
+{{% /alert %}}
+
+## Usage
+
+To enable the outbox feature, add the following required and optional fields on a state store component:
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+  name: mysql-outbox
+spec:
+  type: state.mysql
+  version: v1
+  metadata:
+  - name: connectionString
+    value: "<CONNECTION STRING>"
+  - name: outboxPublishPubsub # Required
+    value: "mypubsub"
+  - name: outboxPublishTopic # Required
+    value: "newOrder"
+  - name: outboxPubsub # Optional
+    value: "myOutboxPubsub"
+  - name: outboxDiscardWhenMissingState #Optional. Defaults to false
+    value: false
+```
+
+### Metadata fields
+
+| Name                | Required    | Default Value | Description                                            |
+| --------------------|-------------|---------------|------------------------------------------------------- |
+| outboxPublishPubsub | Yes         | N/A           | Sets the name of the pub/sub component to deliver the notifications when publishing state changes
+| outboxPublishTopic  | Yes         | N/A           | Sets the topic that receives the state changes on the pub/sub configured with `outboxPublishPubsub`. The message body will be a state transaction item for an `insert` or `update` operation
+| outboxPubsub        | No          | `outboxPublishPubsub`           | Sets the pub/sub component used by Dapr to coordinate the state and pub/sub transactions. If not set, the pub/sub component configured with `outboxPublishPubsub` is used. This is useful if you want to separate the pub/sub component used to send the notification state changes from the one used to coordinate the transaction
+| outboxDiscardWhenMissingState  | No         | `false`           | By setting `outboxDiscardWhenMissingState` to `true`, Dapr discards the transaction if it cannot find the state in the database and does not retry. This setting can be useful if the state store data has been deleted for any reason before Dapr was able to deliver the message and you would like Dapr to drop the items from the pub/sub and stop retrying to fetch the state
+
+### Combining outbox and non-outbox messages on the same state store
+
+If you want to use the same state store for sending both outbox and non-outbox messages, simply define two state store components that connect to the same state store, where one has the outbox feature and the other does not.
+
+#### MySQL state store without outbox
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+  name: mysql
+spec:
+  type: state.mysql
+  version: v1
+  metadata:
+  - name: connectionString
+    value: "<CONNECTION STRING>"
+```
+
+#### MySQL state store with outbox
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+  name: mysql-outbox
+spec:
+  type: state.mysql
+  version: v1
+  metadata:
+  - name: connectionString
+    value: "<CONNECTION STRING>"
+  - name: outboxPublishPubsub # Required
+    value: "mypubsub"
+  - name: outboxPublishTopic # Required
+    value: "newOrder"
+```
+
+## Demo
+
+Watch [this video for an overview of the outbox pattern](https://youtu.be/rTovKpG0rhY?t=1338):
+
+<div class="embed-responsive embed-responsive-16by9">
+<iframe width="360" height="315" src="https://youtu.be/rTovKpG0rhY?t=1338" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

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

@@ -116,6 +116,10 @@ Dapr enables states to be:
 
 For more details read [How-To: Share state between applications]({{< ref howto-share-state.md >}}),
 
+### Enabling the outbox pattern
+
+Dapr enables developers to use the outbox pattern for achieving a single transaction across a transactional state store and any message broker. For more information, read [How to enable transactional outbox messaging]({{< ref howto-outbox.md >}})
+
 ### Querying state
 
 There are two ways to query the state: