Java Workflow client naming inconsistent with other Workflow SDKs.

[msfussell]

The Java SDK Workflow naming is inconsistent with the other SDKs.

For example Currently the Workflow SDK has schedule for Java
String instanceId = client.scheduleNewWorkflow(DemoWorkflow.class, "input data");

when the other SDKs have start. For example .NET
StartWorkflowResponse startResponse = await daprClient.StartWorkflowAsync(orderId, workflowComponent, workflowName, input, workflowOptions);

and Python

start_resp = d.start_workflow(instance_id=instanceId, workflow_component=workflowComponent,
                        workflow_name=workflowName, input=inputData, workflow_options=workflowOptions)

Hence
scheduleNewWorkflow should be renamed to startWorkflow

As another example Java SDK uses 'instance' everywhere and this is inconsistent with using 'workflow' in other SDKs.

 // Get status information on the workflow
      WorkflowInstanceStatus workflowMetadata = client.getInstanceState(instanceId, true);

as opposed to .NET

// Get information on the workflow. This response contains information such as the status of the workflow, when it started, and more!
GetWorkflowResponse getResponse = await daprClient.GetWorkflowAsync(orderId, workflowComponent, eventName);

and Python

# Get info on the workflow
getResponse = d.get_workflow(instance_id=instanceId, workflow_component=workflowComponent)

The docs in both the Java SDK and the Doc repo here https://docs.dapr.io/developing-applications/building-blocks/workflow/howto-manage-workflow/ will also need to be updated with this change

[cgillum]

@msfussell I think you're actually comparing two separate things: the Dapr Workflow SDK (in the Java example) and the Dapr SDK APIs for workflow management (your .NET and Python examples). I understand where this confusion is coming from and I'll try to explain.

For each language, we effectively have two SDKs for managing workflows.

1. The Dapr client, which defines workflow management APIs
2. The Dapr Workflow client, which defines both management and authoring APIs.

The reason we have this duplication is because at the start of this project, we were aiming to support multiple workflow engines. That's why, for example, the workflow management APIs on the Dapr Client take a "component name" parameter. These APIs had to be generic for all possible workflow engines. As it turns out, we decided to only support one workflow engine, the "dapr" workflow engine.

The reason we also have Dapr Workflow APIs is because we wanted a way to expose the specific features of Dapr Workflow to developers which may not be applicable for other, external workflow engines. For example, the Dapr Workflow engine has the capability to schedule workflows to start running in the future. This is why, for example, the Dapr Workflow API is called "ScheduleNewWorkflowXXX" whereas the Dapr client API for interfacing with external workflow engines is simply "StartWorkflow".

Going back to the point about consistency, I did a quick audit and it looks like we are being consistent in terms of naming for the respective SDK type across all languages that support workflow.

Language	Dapr client	Dapr Workflow client
.NET	StartWorkflowAsync	ScheduleNewWorkflowAsync
Java	n/a	scheduleNewWorkflow
Python	start_workflow	schedule_new_workflow
JavaScript	start	scheduleNewWorkflow
Go	StartWorkflowBeta1	ScheduleNewWorkflow

What I want to do is actually deprecate or at least deemphasize the "Dapr client" workflow APIs because they're less useful than the Dapr Workflow variants. However, I recognize that we'd need to go through the formal proposal process for this and make a decision as a larger group. In the meantime, I've been trying to ask contributors to use the Dapr Workflow APIs in the samples, but it looks like that work hasn't been done yet, which is why you discovered these inconsistencies.

[msfussell]

@cgillum - Thanks for the clarification. Then should the word "instance" be in the public API for Java when it is not in the other client Workflow APIs? That seems inconsistent.

Also this implies the workflow API doc here is needs changing https://v1-13.docs.dapr.io/reference/api/workflow_api/
and the management samples in docs (like the SDK samples) will need changing https://v1-13.docs.dapr.io/developing-applications/building-blocks/workflow/howto-manage-workflow/

And whilst we are changing the samples, can we consider having the same name for the workflow, since currently every SDK sample is different.

I see this as a "must do" issue for the v1.14 timeframe.