Simplify the update-wth-start API

[shizambles]

Is your feature request related to a problem? Please describe.

The new, experimental update-with-start API provides a confusing API. Looking at the integration test code, it appears that the way to update-wth-start an already running workflow is to call Client.ExecuteWorkflow() twice.

1. The first call to ExecuteWorkflow, needs a StartWorkflowOptions with WorkflowIDConflictPolicy set to WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING. The documentation of this policy states -

// Don't start a new workflow; instead return a workflow handle for the running workflow.
WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING WorkflowIdConflictPolicy = 2

2. The second call to ExecuteWorkflow, needs a StartWorkflowOptions with WithStartOperation set to a NewUpdateWithStartWorkflowOperation value like below.

client.NewUpdateWithStartWorkflowOperation(
		client.UpdateWorkflowOptions{
			UpdateName:   "update",
			Args:         ....,
			WaitForStage: client.WorkflowUpdateStageCompleted,
		})

The documentation of WithStartOperation states -

// WithStartOperation - Operation to execute with Workflow Start.
// For example, see NewUpdateWithStartWorkflowOperation to perform Update-with-Start. Note that if the workflow is
// already running and WorkflowIDConflictPolicy is set to UseExisting, the start is skipped and only the
// operation is executed.

Needing two consecutive calls to ExecuteWorkflow to exercise the update-with-start functionality is confusing and in my opinion violates the principle of least surprise. The developer is now having to drill down into the documentation to realize that despite the documentation for ExecuteWorkflow stating that ExecuteWorkflow starts a workflow execution and returns a WorkflowRun instance or error, it many not actually start a workflow depending on what options are passed in.

Describe the solution you'd like

The API could be simplified by providing a single suitably named function - say client.UpdateWithStartWorkflow that hides the above details and does the needful.

[dandavison]

Hi @shizambles, we're in the process of rolling out Update-With-Start across all languages and we are indeed planning to make an API change here. I'll update this ticket with details when the relevant PRs are merged, but what we're planning is similar to what you suggest.

That said, your interpretation of the current API isn't quite right. Update-With-Start requires only one call to ExecuteWorkflow, for example, see the sample here: https://github.com/temporalio/samples-go/blob/main/early-return/starter/main.go

The integration test you point to calls ExecuteWorkflow twice -- once to start a workflow, and a second time to confirm that an Update-With-Start can be sent to an already-running workflow. To test this style of usage of Update-With-Start, the second call has to pass the USE_EXISTING workflow ID conflict policy. This style of UwS usage is intended for situations where you have a relatively long-running workflow (e.g. an e-commerce shopping cart, or an "entity" workflow acting as a service of some sort), and you want to send an update to the workflow, starting it if necessary.

The other style of Update-With-Start usage involves using the (default) FAIL conflict policy. This is for when you want to start a workflow and at the same time send an update in the first workflow task, and you want the operation to fail if the workflow already exists (i.e. you demand that a workflow is started). This style is what is shown in the sample.

It's important to understand that the concept of the workflow ID conflict policy is not specifically tied to Update-With-Start: it's available whenever you start a workflow, allowing you to control what happens when the workflow ID you supply corresponds to an already-running workflow. In other words, it's already the case, across all SDKs, that the start-workflow API can be used in an idempotent style that will succeed without actually starting a workflow, if it exists already. So it isn't specifically related to Update-With-Start, but understanding that option is central to understanding the two usage modes of Update-With-Start.

I'll ping this ticket when we make the planned changes!