-
Notifications
You must be signed in to change notification settings - Fork 206
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Java Workflow client naming inconsistent with other Workflow SDKs. #1012
Comments
@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.
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.
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. |
@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 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. |
@cgillum @msfussell I am happy to take that issue, but I need to admit that I am confused and I am not sure about if a decision has been made about the naming yet. As a workflow user I am used to have access to the workflow instance, so I didn't saw anything wrong there when using the API, but I agree that looking at your examples it is inconsistent. I need to dig deeper to what @cgillum has mentioned, I do understand there are two APIs to do different things, so we need to make sure that those are also consistent between each other. If you can help me to make a decision on naming I am happy to get this done. |
Thanks @salaboy for offering to help with this! Regarding the deprecation of generic DaprClient APIs for workflows, a decision has been made to go ahead and remove them, and some of that work has been completed for 1.15. We need to confirm that this work is being done for all SDKs, but that should resolve the first naming inconsistency. Regarding "instance", I don't have a strong opinion, nor am I immediately familiar with the full set of inconsistencies. I suppose one specific term we can consider is "workflow ID" vs. "[workflow] instance ID". I think there are potential ambiguities with both but would be supportive of picking one and using it consistently. @msfussell would love to get your opinion here. |
WorkflowID is usually the ID that makes reference to a workflow definition, we should be able to identify that with an unique identifier, while each instance of that definition should have its own instance ID. |
The Java SDK Workflow naming is inconsistent with the other SDKs.
For example Currently the Workflow SDK has
schedule
for JavaString instanceId = client.scheduleNewWorkflow(DemoWorkflow.class, "input data");
when the other SDKs have
start
. For example .NETStartWorkflowResponse startResponse = await daprClient.StartWorkflowAsync(orderId, workflowComponent, workflowName, input, workflowOptions);
and Python
Hence
scheduleNewWorkflow
should be renamed tostartWorkflow
As another example Java SDK uses 'instance' everywhere and this is inconsistent with using 'workflow' in other SDKs.
as opposed to .NET
and Python
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
The text was updated successfully, but these errors were encountered: