EDU-3236: Update-with-Start

[stephanos]

What does this PR do?

Adds documentation for the Update-with-Start feature as well as its Go SDK usage.

[fairlydurable]

Confirmed correct.

[fairlydurable]

This needs to be updated to Public Preview. We do not release docs (as a rule) before then, so it should reflect the status when this material is ready for going live.

[fairlydurable]

Consider "Minimum Temporal Server version" unless there's a compelling reason otherwise to be less restrictive.

[fairlydurable]

Suggested change

	Therefore, provide a context with a timeout to limit the time the client waits for a response.
	Setting a timeout with a context provides a hard limit on how long a client will wait for a response.

[fairlydurable]

Suggested change

	This parameter controls what stage the update must reach before a handle is returned to the caller.
	This parameter controls the stage the update must reach before returning a handle to the caller:
	- If `WaitForStage` is set to `WorkflowUpdateStageCompleted`, the handle is returned after the Update completes.
	- If `WaitForStage` is set to `WorkflowUpdateStageAccepted`, the handle is returned after the Update is accepted and the Validator is run, if it's defined.
	Note: You cannot send Updates to other Workflow Executions.
	The following sample demonstrates how to create a context with timeout for sending an `Update` to the Workflow:

Or you might consider putting the note into an admonition if important enough.

[fairlydurable]

Suggestion:

[Update-with-Start](/encyclopedia/workflow-message-passing#update-with-start) lets you send an Update that checks whether an already-running Workflow with that ID exists:

- If the Workflow exists, the Update is processed.
- If the Workflow does not exist, a new Workflow Execution starts with the given ID, and the Update is processed immediately after.

[fairlydurable]

Suggested change

	The Workflow Id is optional - but when it is specified, it must match the one in `StartWorkflowOptions`.
	The Workflow Id is optional.
	When specified, the Id must match the one used in `StartWorkflowOptions`.

[fairlydurable]

Suggested change

	It is invalid to set the Run ID since there might not be running Workflow Execution.
	Since a running Workflow Execution may not already exist, you can't set a Run Id.

[fairlydurable]

Suggested change

	Use the `WithStartOperation` option to attach an Update Operation to the [`Client.ExecuteWorkflow`](https://pkg.go.dev/go.temporal.io/sdk/client#Client.ExecuteWorkflow) API call.
	Use the `WithStartOperation` option to attach an Update Operation to the [`Client.ExecuteWorkflow`](https://pkg.go.dev/go.temporal.io/sdk/client#Client.ExecuteWorkflow) API call.
	Not all `ExecuteWorkflow` options are allowed with Update-With-Start.
	For example, specifying a Cron Schedule will result in an error.
	For more details, refer to the [API documentation](https://pkg.go.dev/go.temporal.io/sdk/internal#StartWorkflowOptions).

[fairlydurable]

Suggested change

	Choose [Workflow Id Conflict Policy](#workflow-id-conflict-policy) "Use Existing" coupled with an indempotent Update handler by default to allow the code to be executed again, in case of client failure.
	By default, choose the [Workflow Id Conflict Policy](#workflow-id-conflict-policy) "Use Existing" and use an idempotent Update handler.
	This ensures your code can be executed again in case of a Client failure.

[fairlydurable]

Suggested change

	You need a [`WorkflowUpdateHandle`](https://pkg.go.dev/go.temporal.io/sdk/client#WorkflowUpdateHandle) to retrieve a result.
	Use [`WorkflowUpdateHandle`](https://pkg.go.dev/go.temporal.io/sdk/client#WorkflowUpdateHandle) to retrieve a result from the Update.

[fairlydurable]

Nice.

[fairlydurable]

Also, very nice.

[fairlydurable]

Suggested change

	Update-With-Start lets you send an Update that checks whether an already-running Workflow with that ID exists.
	Update-With-Start sends an Update that checks whether an already-running Workflow with that ID exists.

[fairlydurable]

Suggested change

	Upon starting a new Workflow, it immediately processes the Update.
	When starting a new Workflow, it immediately processes the Update.

[fairlydurable]

Suggested change

	Update-With-Start is great for latency-sensitive use cases, including the following examples:
	Update-With-Start is great for latency-sensitive use cases:

[fairlydurable]

Suggested change

	Add or remove an item with an Update.
	Updates let you add and remove items from the cart.

[fairlydurable]

Suggested change

	Update-With-Start ensures the cart (the Workflow Execution) is created first before applying the Update (state change of items within the cart).
	Update-With-Start lets the customer start shopping, whether the cart already exists or they've just started shopping.
	It ensures the cart, modeled by a Workflow Execution, is created before applying any Update that changes the state of items within the cart.

[fairlydurable]

Suggested change

	For example, a payment process can be modelled using Update-With-Start.
	For example, you might model a payment process using Update-With-Start.

[fairlydurable]

Suggested change

	You can send the result of payment validation back to the client synchronously, while continuing to complete or rollback the transaction asynchronously.
	Whether the payment completes or rolls back, you can send the payment validation results back to the client synchronously, while attempting the transaction asynchronously.

Close?

[fairlydurable]

I love this admonition.

[fairlydurable]

Suggested change

	If the Update cannot be delivered, for example, when no Worker is running, the Workflow Execution is still started.
	If the Update can't be delivered, for example, say that there's no running Worker available, a new Workflow Execution will still start.