Spring Boot Workflow API Incompatibility: Inconsistent Experience with Dapr Workflow API

[cicoyle]

When using the Dapr Workflow API directly in a Spring Boot application, the workflow fails with a NullPointerException when attempting to start a workflow via the standard Dapr Workflow API endpoint. This creates an inconsistent experience compared to other Dapr users who can start workflows with a simple curl command. This issue was confirmed with the /start, but likely applies to all workflow API endpoints.

Error:

io.dapr.durabletask - The orchestrator failed with an unhandled exception: java.lang.NullPointerException: Cannot invoke "io.dapr.durabletask.TaskOrchestrationFactory.create()" because "factory" is null

Current Behavior

• Users must implement custom REST controllers as a workaround
• The @EnableDaprWorkflows annotation does not resolve the issue
• No clear documentation or standalone examples exist for Spring Boot workflows integration
• All workflow operations (not just starting workflows) are affected by this issue

Expected Behavior

• Spring Boot applications should be able to use the Dapr Workflow API directly, just like any other Dapr application
• A simple curl command should work to start workflows
• The experience should be consistent across all Dapr users

Architectural Incompatibility

The issue stems from timing and lifecycle management differences between Spring Boot and Dapr Workflow API:

1. Lifecycle Management

   • Dapr Workflow API: Assumes workflow registration is complete before API operations are called
   • Spring Boot: Initializes components during context startup
   • No mechanism exists to know when the runtime is ready to handle operations

2. Registration Timing

   • Dapr Workflow API: Requires workflows to be registered before any operations
   • Spring Boot: Registers workflows during context initialization
   • API calls may occur before registration is complete

3. Context Dependencies

   • Dapr Workflow API: Expects a fully initialized workflow runtime
   • Spring Boot: Initializes components during context startup
   • The workflow runtime may not be ready when API calls are made

Current Workaround

Users must implement a custom REST controller to start workflows:

@RestController
public class WorkflowController {
    @Autowired
    private DaprWorkflowClient workflowClient;

    @PostMapping("/start")
    public ResponseEntity<String> startWorkflow(@RequestBody String requestBody) {
        String instanceId = workflowClient.scheduleNewWorkflow(
            LoanApplicationProcessing.class,
            requestBody
        );
        return ResponseEntity.ok(instanceId);
    }
}

Impact

• This architectural incompatibility affects all Spring Boot applications using Dapr Workflows
• Forces developers to implement workarounds instead of using standard Dapr patterns
• Increases maintenance complexity and reduces code clarity
• Creates inconsistency in how workflows are started across different Java applications
• No clear documentation or examples exist in the Dapr Java SDK
• Requires custom implementations for all workflow operations (start, terminate, get status, raise events, etc.)

This affects the ability to use Dapr Workflows in a standard way across different Java applications

Proposed Solutions

1. Add clear documentation about this incompatibility
2. Provide working Spring Boot workflow examples in the Dapr Java SDK
3. Update Dapr documentation to clarify Spring Boot integration requirements
4. Implement proper integration between Dapr Workflows API and Spring Boot apps
5. Ensure consistent behavior across all Dapr APIs in Spring Boot

Related Documentation

• Current Dapr Workflow documentation does not adequately address Spring Boot integration
• No clear/standalone examples exist in the Dapr Java SDK for Spring Boot workflow implementation

[salaboy]

@cicoyle can you please create a reproducer for the exception and push it to a GitHub repository so I can review?

[salaboy]

As reference links that might help:

• https://docs.dapr.io/developing-applications/sdks/java/spring-boot/ <- Current Dapr Workflow documentation does not adequately address Spring Boot integration
• https://github.com/dapr/java-sdk/tree/master/spring-boot-examples <- No clear/standalone examples exist in the Dapr Java SDK for Spring Boot workflow implementation .

[salaboy]

I am closing this issue after creating #1378 as suggested by @cicoyle
Regarding docs there is also this PR open with Workflow examples: #1377