How to: Author and manage Dapr Workflow in the Java SDK

How to get up and running with workflows using the Dapr Java SDK

Note

Dapr Workflow is currently in beta. See known limitations for 1.12.0.

Let’s create a Dapr workflow and invoke it using the console. With the provided workflow example, you will:

This example uses the default configuration from dapr init in self-hosted mode.

Prerequisites

Set up the environment

Clone the Java SDK repo and navigate into it.

  1. git clone https://github.com/dapr/java-sdk.git
  2. cd java-sdk

Run the following command to install the requirements for running this workflow sample with the Dapr Java SDK.

  1. mvn clean install

From the Java SDK root directory, navigate to the Dapr Workflow example.

  1. cd examples

Run the DemoWorkflowWorker

The DemoWorkflowWorker class registers an implementation of DemoWorkflow in Dapr’s workflow runtime engine. In the DemoWorkflowWorker.java file, you can find the DemoWorkflowWorker class and the main method:

  1. public class DemoWorkflowWorker {
  3.   public static void main(String[] args) throws Exception {
  4.     // Register the Workflow with the runtime.
  5.     WorkflowRuntime.getInstance().registerWorkflow(DemoWorkflow.class);
  6.     System.out.println("Start workflow runtime");
  7.     WorkflowRuntime.getInstance().startAndBlock();
  8.     System.exit(0);
  9.   }
  10. }

In the code above:

  • WorkflowRuntime.getInstance().registerWorkflow() registers DemoWorkflow as a workflow in the Dapr Workflow runtime.
  • WorkflowRuntime.getInstance().start() builds and starts the engine within the Dapr Workflow runtime.

In the terminal, execute the following command to kick off the DemoWorkflowWorker:

  1. dapr run --app-id demoworkflowworker --resources-path ./components/workflows --dapr-grpc-port 50001 -- java -jar target/dapr-java-sdk-examples-exec.jar io.dapr.examples.workflows.DemoWorkflowWorker

Expected output

  1. You're up and running! Both Dapr and your app logs will appear here.
  3. ...
  5. == APP == Start workflow runtime
  6. == APP == Sep 13, 2023 9:02:03 AM com.microsoft.durabletask.DurableTaskGrpcWorker startAndBlock
  7. == APP == INFO: Durable Task worker is connecting to sidecar at 127.0.0.1:50001.

Run the `DemoWorkflowClient

The DemoWorkflowClient starts instances of workflows that have been registered with Dapr.

  1. public class DemoWorkflowClient {
  3.   // ...
  4.   public static void main(String[] args) throws InterruptedException {
  5.     DaprWorkflowClient client = new DaprWorkflowClient();
  7.     try (client) {
  8.       String separatorStr = "*******";
  9.       System.out.println(separatorStr);
  10.       String instanceId = client.scheduleNewWorkflow(DemoWorkflow.class, "input data");
  11.       System.out.printf("Started new workflow instance with random ID: %s%n", instanceId);
  13.       System.out.println(separatorStr);
  14.       System.out.println("**GetInstanceMetadata:Running Workflow**");
  15.       WorkflowInstanceStatus workflowMetadata = client.getInstanceState(instanceId, true);
  16.       System.out.printf("Result: %s%n", workflowMetadata);
  18.       System.out.println(separatorStr);
  19.       System.out.println("**WaitForInstanceStart**");
  20.       try {
  21.         WorkflowInstanceStatus waitForInstanceStartResult =
  22.             client.waitForInstanceStart(instanceId, Duration.ofSeconds(60), true);
  23.         System.out.printf("Result: %s%n", waitForInstanceStartResult);
  24.       } catch (TimeoutException ex) {
  25.         System.out.printf("waitForInstanceStart has an exception:%s%n", ex);
  26.       }
  28.       System.out.println(separatorStr);
  29.       System.out.println("**SendExternalMessage**");
  30.       client.raiseEvent(instanceId, "TestEvent", "TestEventPayload");
  32.       System.out.println(separatorStr);
  33.       System.out.println("** Registering parallel Events to be captured by allOf(t1,t2,t3) **");
  34.       client.raiseEvent(instanceId, "event1", "TestEvent 1 Payload");
  35.       client.raiseEvent(instanceId, "event2", "TestEvent 2 Payload");
  36.       client.raiseEvent(instanceId, "event3", "TestEvent 3 Payload");
  37.       System.out.printf("Events raised for workflow with instanceId: %s\n", instanceId);
  39.       System.out.println(separatorStr);
  40.       System.out.println("** Registering Event to be captured by anyOf(t1,t2,t3) **");
  41.       client.raiseEvent(instanceId, "e2", "event 2 Payload");
  42.       System.out.printf("Event raised for workflow with instanceId: %s\n", instanceId);
  45.       System.out.println(separatorStr);
  46.       System.out.println("**WaitForInstanceCompletion**");
  47.       try {
  48.         WorkflowInstanceStatus waitForInstanceCompletionResult =
  49.             client.waitForInstanceCompletion(instanceId, Duration.ofSeconds(60), true);
  50.         System.out.printf("Result: %s%n", waitForInstanceCompletionResult);
  51.       } catch (TimeoutException ex) {
  52.         System.out.printf("waitForInstanceCompletion has an exception:%s%n", ex);
  53.       }
  55.       System.out.println(separatorStr);
  56.       System.out.println("**purgeInstance**");
  57.       boolean purgeResult = client.purgeInstance(instanceId);
  58.       System.out.printf("purgeResult: %s%n", purgeResult);
  60.       System.out.println(separatorStr);
  61.       System.out.println("**raiseEvent**");
  63.       String eventInstanceId = client.scheduleNewWorkflow(DemoWorkflow.class);
  64.       System.out.printf("Started new workflow instance with random ID: %s%n", eventInstanceId);
  65.       client.raiseEvent(eventInstanceId, "TestException", null);
  66.       System.out.printf("Event raised for workflow with instanceId: %s\n", eventInstanceId);
  68.       System.out.println(separatorStr);
  69.       String instanceToTerminateId = "terminateMe";
  70.       client.scheduleNewWorkflow(DemoWorkflow.class, null, instanceToTerminateId);
  71.       System.out.printf("Started new workflow instance with specified ID: %s%n", instanceToTerminateId);
  73.       TimeUnit.SECONDS.sleep(5);
  74.       System.out.println("Terminate this workflow instance manually before the timeout is reached");
  75.       client.terminateWorkflow(instanceToTerminateId, null);
  76.       System.out.println(separatorStr);
  78.       String restartingInstanceId = "restarting";
  79.       client.scheduleNewWorkflow(DemoWorkflow.class, null, restartingInstanceId);
  80.       System.out.printf("Started new  workflow instance with ID: %s%n", restartingInstanceId);
  81.       System.out.println("Sleeping 30 seconds to restart the workflow");
  82.       TimeUnit.SECONDS.sleep(30);
  84.       System.out.println("**SendExternalMessage: RestartEvent**");
  85.       client.raiseEvent(restartingInstanceId, "RestartEvent", "RestartEventPayload");
  87.       System.out.println("Sleeping 30 seconds to terminate the eternal workflow");
  88.       TimeUnit.SECONDS.sleep(30);
  89.       client.terminateWorkflow(restartingInstanceId, null);
  90.     }
  92.     System.out.println("Exiting DemoWorkflowClient.");
  93.     System.exit(0);
  94.   }
  95. }

In a second terminal window, start the workflow by running the following command:

  1. java -jar target/dapr-java-sdk-examples-exec.jar io.dapr.examples.workflows.DemoWorkflowClient

Expected output

  1. *******
  2. Started new workflow instance with random ID: 0b4cc0d5-413a-4c1c-816a-a71fa24740d4
  3. *******
  4. **GetInstanceMetadata:Running Workflow**
  5. Result: [Name: 'io.dapr.examples.workflows.DemoWorkflow', ID: '0b4cc0d5-413a-4c1c-816a-a71fa24740d4', RuntimeStatus: RUNNING, CreatedAt: 2023-09-13T13:02:30.547Z, LastUpdatedAt: 2023-09-13T13:02:30.699Z, Input: '"input data"', Output: '']
  6. *******
  7. **WaitForInstanceStart**
  8. Result: [Name: 'io.dapr.examples.workflows.DemoWorkflow', ID: '0b4cc0d5-413a-4c1c-816a-a71fa24740d4', RuntimeStatus: RUNNING, CreatedAt: 2023-09-13T13:02:30.547Z, LastUpdatedAt: 2023-09-13T13:02:30.699Z, Input: '"input data"', Output: '']
  9. *******
  10. **SendExternalMessage**
  11. *******
  12. ** Registering parallel Events to be captured by allOf(t1,t2,t3) **
  13. Events raised for workflow with instanceId: 0b4cc0d5-413a-4c1c-816a-a71fa24740d4
  14. *******
  15. ** Registering Event to be captured by anyOf(t1,t2,t3) **
  16. Event raised for workflow with instanceId: 0b4cc0d5-413a-4c1c-816a-a71fa24740d4
  17. *******
  18. **WaitForInstanceCompletion**
  19. Result: [Name: 'io.dapr.examples.workflows.DemoWorkflow', ID: '0b4cc0d5-413a-4c1c-816a-a71fa24740d4', RuntimeStatus: FAILED, CreatedAt: 2023-09-13T13:02:30.547Z, LastUpdatedAt: 2023-09-13T13:02:55.054Z, Input: '"input data"', Output: '']
  20. *******
  21. **purgeInstance**
  22. purgeResult: true
  23. *******
  24. **raiseEvent**
  25. Started new workflow instance with random ID: 7707d141-ebd0-4e54-816e-703cb7a52747
  26. Event raised for workflow with instanceId: 7707d141-ebd0-4e54-816e-703cb7a52747
  27. *******
  28. Started new workflow instance with specified ID: terminateMe
  29. Terminate this workflow instance manually before the timeout is reached
  30. *******
  31. Started new  workflow instance with ID: restarting
  32. Sleeping 30 seconds to restart the workflow
  33. **SendExternalMessage: RestartEvent**
  34. Sleeping 30 seconds to terminate the eternal workflow
  35. Exiting DemoWorkflowClient.

What happened?

  1. When you ran dapr run, the workflow worker registered the workflow (DemoWorkflow) and its actvities to the Dapr Workflow engine.
  2. When you ran java, the workflow client started the workflow instance with the following activities. You can follow along with the output in the terminal where you ran dapr run.
    1. The workflow is started, raises three parallel tasks, and waits for them to complete.
    2. The workflow client calls the activity and sends the “Hello Activity” message to the console.
    3. The workflow times out and is purged.
    4. The workflow client starts a new workflow instance with a random ID, uses another workflow instance called terminateMe to terminate it, and restarts it with the workflow called restarting.
    5. The worfklow client is then exited.

Next steps