Skip to main content

Build an email subscription Workflow with Temporal and Java

Last updated on
Tags:

Temporal Java SDK

Introduction​

In this tutorial, you'll build an email subscription web application using Temporal and Java. You'll create a web server using the Spring Boot framework to handle requests and use Temporal Workflows, Activities, and Queries to build the core of the application. Your server will handle requests from end users and interact with a Temporal Workflow to manage the email subscription process. Since you're building the business logic with Temporal's Workflows and Activities, you'll be able to use Temporal to manage each subscription rather than relying on a separate database or Task Queue. This reduces the complexity of the code you have to write and support.

You'll create an endpoint for users to provide their email address and create a new Workflow execution using that email address. This will simulate sending an email message at certain intervals. The user can check on the status of their subscription, which you'll handle using a Query. They can end the subscription at any time by unsubscribing. You'll handle this by cancelling the Workflow Execution. You can view the user's entire process through Temporal's Web UI. By the end of this tutorial, you'll have a clear understand how to use Temporal to create and manage long-running Workflows within a web application.

note

This tutorial simulates sending emails. You can adapt this example to call a live email service.

Find the code for this tutorial on GitHub at the email-subscription-project-java repository.

Prerequisites​

Before starting this tutorial:

  • Set up a local development environment for Temporal and Java.
  • Complete the Hello World tutorial to ensure you understand the basics of creating Workflows and Activities with Temporal.
  • This application uses Gradle build automation. Make sure you have installed Gradle.
  • You'll use Spring Initializer to generate a project with a build.gradle file for Java. Add Spring Web and Lombok dependencies before generating the project. After creating the build.gradle file, add your temporal-sdk and temporal-spring-boot dependencies.

Set up​

Your build.gradle dependencies section should look like this:

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
    implementation "io.temporal:temporal-spring-boot-starter-alpha:$javaSDKVersion"
}

Create settings.gradle in the root of your directory with the following line:

rootProject.name = 'email-subscription'

With the Gradle configurations complete, you're ready to code a Spring Boot web application.

Build your file structure​

A Workflow defines a sequence of steps defined by writing code, known as a Workflow Definition. These steps are carried out by running that code, which results in a Workflow Execution.

The Temporal Java SDK recommends the use of a single class for parameters and return types. This lets you add class field members without breaking compatibility.

Before writing the Workflow Definition, you'll define classes used by your Workflow Definitions. You'll also define a shared utility class to hold the Task Queue name you'll use when starting Workflows and a data class to hold a message that Spring Boot can return in json format through your web service.

Create a new package called subscription in the src/main/java directory. This package contains the code used for this application. Update the group variable in your build.gradle to 'subscription'.

Your complete project will look like this:

src
├── main
│   ├── java
│   │   └── subscription
│   │       ├── Controller.java
│   │       ├── Starter.java
│   │       ├── activities
│   │       │   ├── SendEmailActivities.java
│   │       │   └── SendEmailActivitiesImpl.java
│   │       ├── model
│   │       │   ├── Constants.java
│   │       │   ├── EmailDetails.java
│   │       │   ├── Message.java
│   │       │   └── WorkflowData.java
│   │       └── workflows
│   │           ├── SendEmailWorkflow.java
│   │           └── SendEmailWorkflowImpl.java
│   └── resources
│       └── application.yaml
└── test
    └── java
        └── StarterTest.java

Create the intermediate package directories. With your project structure mocked up, you're ready to start adding content.

Build your model content​

In this sections, you'll populate the model directory. You'll create a shared string constant class and you'll use lombok to create getters, setters, and constructors for three data classes:

  • messages
  • email details
  • Workflow details

Create Constants.java for shared string constants​

Define a public string variable TASK_QUEUE_NAME in Constants.java. Set it to "email_subscription".

src/main/java/subscription/model/Constants.java

package subscription.model;

public class Constants {

    public static final String TASK_QUEUE_NAME = "email_subscription";
}

Create a message data class​

The message class stores message data to return via Spring Boot web service:

src/main/java/subscription/model/Message.java

package subscription.model;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@NoArgsConstructor
@AllArgsConstructor
@Data
public class Message {

    private String message;
}

Create a subscription data class​

The email data class stores several members:

  • email: as a string to pass a user's email
  • message: as a string to pass a message to the user
  • count: as an integer to track the number of emails sent
  • subscribed: as a boolean to track whether the user is currently subscribed

src/main/java/subscription/model/EmailDetails.java

package subscription.model;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@NoArgsConstructor
@AllArgsConstructor
@Data
public class EmailDetails {

    private String email;
    private String message;
    private int count;
    private boolean subscribed;

    public void increment() {
        count++;
    }
}

When you query your Workflow to retrieve the current Workflow status, you'll use the EmailDetails class.

Create a Workflow initialization data class​

The Workflow data class stores the information needed to create a new subscription. For this sample, it stores one data field member:

  • email: a string to pass the user's email

src/main/java/subscription/model/WorkflowData.java

package subscription.model;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@NoArgsConstructor
@AllArgsConstructor
@Data
public class WorkflowData {

    private String email;
}

With the Task Queue and the data classes defined, you're ready to write your subscription Workflow Definition.

Create a Workflow Definition​

With your model data classes ready, develop your Workflow Definition by following the steps in this section.

Setup​

Create a new package directory in src/main/java/subscription called workflows. Build two new file called SendEmailWorkflow.java and SendEmailWorkflowImpl.java. These file provide the interface and implementation for your Workflow methods. Add the following code to SendEmailWorkflow.java to define your Workflow:

Workflow Interface​

The interface SendEmailWorkflow, annotated with @WorkflowInterface, defines the run() method entry point for the Workflow. The run() method, annotated with @WorkflowMethod, accepts the email address as an argument:

src/main/java/subscription/workflows/SendEmailWorkflow.java

@WorkflowInterface
public interface SendEmailWorkflow {

    @WorkflowMethod
    public void run(WorkflowData data);

    @QueryMethod
    public EmailDetails details();
}

Workflow Implementation​

Add your SendEmailWorkflow implementation to SendEmailWorkflowImpl.java.

src/main/java/subscription/workflows/SendEmailWorkflowImpl.java

@WorkflowImpl(workers = "send-email-worker")
public class SendEmailWorkflowImpl implements SendEmailWorkflow {

    private EmailDetails emailDetails = new EmailDetails();

    private final ActivityOptions options =
            ActivityOptions.newBuilder()
                    .setStartToCloseTimeout(Duration.ofSeconds(10))
                    .build();

    private final SendEmailActivities activities =
            Workflow.newActivityStub(SendEmailActivities.class, options);

    @Override
    public void run(WorkflowData data) {

        int duration = 12;
        emailDetails.setEmail(data.getEmail());
        emailDetails.setMessage("Welcome to our Subscription Workflow!");
        emailDetails.setSubscribed(true);
        emailDetails.setCount(0);

        while (emailDetails.isSubscribed()) {

            emailDetails.increment();
            if (emailDetails.getCount() > 1) {
                emailDetails.setMessage("Thank you for staying subscribed!");
            }

            try {
                activities.sendEmail(emailDetails);
                Workflow.sleep(Duration.ofSeconds(duration));
            }
            catch (CanceledFailure e) {
                emailDetails.setSubscribed(false);
                emailDetails.setMessage("Sorry to see you go");
                CancellationScope sendGoodbye =
                        Workflow.newDetachedCancellationScope(() -> activities.sendEmail(emailDetails));
                sendGoodbye.run();

                throw e;
            }
        }
    }

    @Override
    public EmailDetails details() {

        return emailDetails;
    }
}

The run() method initializes the email, message, subscribed, and count attributes of the private variable emailDetails for a SendEmailWorkflowImpl instance. The SendEmailWorkflowImpl class uses a loop to checks if the subscription is still active by checking if emailDetails.isSubscribed() is True. If so, it starts the sendEmail() Activity.

The while loop increments emailDetails's count attribute and calls the sendEmail() Activity with the current EmailDetails object. The loop continues as long as emailDetails's subscribed attribute is true.

The code uses the SendEmailActivities object activities to call the activity method sendEmail(). The activities variable is initialized with the SendEmailActivities definition and ActivityOptions. The options specify a start to close timeout of 10 seconds. This tells the Temporal Server to time out the Activity 10 seconds from when the Activity starts.

The loop also includes a Workflow.sleep() statement that causes the Workflow to pause for a set amount of time between email. You can define this in seconds, days, months, or even years, depending on your business logic.

If there's a cancellation request, the request throws a CanceledFailure error which you can catch and respond.

In this application, you use cancellation requests to unsubscribe users. By using a Detached Cancellation Scope, the workflow can call the sendEmail() Activity to send one last email when users unsubscribe, before completing the Workflow Execution.

The user's email address is set to the Workflow Id. Attempting to subscribe with the same email address twice results in a Workflow Execution already started error. This prevents the Workflow Execution from spawning again.

Only one running Workflow Execution per email address can exist within the associated Namespace. This ensures that the user won't receive multiple email subscriptions. This also helps reduce the complexity of the code you have to write and maintain.

With this Workflow Definition in place, you can now develop an Activity to send emails.

Develop an Activity​

You'll need an Activity to send the email to the subscriber so you can handle failures. Create a new package directory in the src/main/java/subscription directory called activities. There, create an interface/implementation source pair called SendEmailActivities.java and SendEmailActivitiesImpl.java.

Create the Activity interface​

Add the following code to SendEmailActivities.java:

src/main/java/subscription/activities/SendEmailActivities.java

@ActivityInterface
public interface SendEmailActivities {

    @ActivityMethod
    public String sendEmail(EmailDetails details);
}

Create the Activity implementation​

Add the following code to SendEmailActivitiesImpl.java:

src/main/java/subscription/activities/SendEmailActivitiesImpl.java

package subscription.activities;
@Component
@ActivityImpl(workers = "send-email-worker")
public class SendEmailActivitiesImpl implements SendEmailActivities {

    @Override
    public String sendEmail(EmailDetails details) {

        System.out.println( "Sending email to " + details.getEmail() +
                            " with message: " + details.getMessage() +
                            ", count: " + details.getCount());

        return "success";
    }
}

This implementation only prints a message, but you could replace the implementation with one that uses an email API. Each iteration of the Workflow loop will execute this Activity, which simulates sending a message to the user.

Now that you have the Activity Definition and Workflow Definition, it's time to write the Worker process.

Create your Temporal Worker​

Gradle and Temporal's' Java SDK Spring Boot integration package let you can write a Worker process for your Workflows and Activities without a dedicated Worker class. This simplifies the steps needed to run your Temporal Spring Boot application. Your Worker will start automatically by running your Spring Boot application. Create a new file in the src/main/resources directory called application.yml and provide the specifications of your application.

application.yaml

spring:
  application:
    name: email-subscription
  temporal:
    namespace: default
    connection:
      target: 127.0.0.1:7233
    workers:
      - name: send-email-worker
        task-queue: email_subscription
    workersAutoDiscovery:
      packages:
        - subscription.workflows
        - subscription.activities

You must specify rootProject.name = 'email-subscription in settings.gradle to link the application.yml file. The task-queue: string must be identical to the TASK_QUEUE_NAME in Constants.java. Both the Workflows and Activities packages must be specified separately under packages:.

For a Spring-integrated Worker to run your Workflows and Activities, you must use the @WorkflowImpl(workers = "send-email-worker") and @ActivityImpl(workers = "send-email-worker") decorations in your Workflow and Activity implementation classes.

Now that you've written the logic to execute the Workflow and Activity Definitions, you can build the gateway and your subscriber endpoints.

Build the API server​

This tutorial uses the Spring Boot web framework to build a web server. The server is the entry point for initiating Workflow Execution and communicating with the subscribe, get-details, and unsubscribe routes. It handles HTTP requests and performs the appropriate operations with the Workflow. Create Controller.java in Subscriptions. Add the necessary headers:

src/main/java/subscription/Controller.java

package subscription;

import io.temporal.client.WorkflowClient;
import io.temporal.client.WorkflowOptions;
import io.temporal.client.WorkflowStub;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import subscription.model.*;
import subscription.workflows.SendEmailWorkflow;

This code registers the Temporal Client to run before the first request to this instance of the application. A Temporal Client enables you to communicate with the Temporal Service. Communication with a Temporal Service includes, but isn't limited to, the following:

  • Starting Workflow Executions
  • Sending Queries to Workflow Executions
  • Getting the results of a Workflow Execution

src/main/java/subscription/Controller.java

@RestController
public class Controller {

    @Autowired
    WorkflowClient client;

The WorkflowClient private variable client is initialized using Spring's @Autowired annotation which gets the Temporal WorkflowClient from the specifications in application.yml. Each endpoint uses the client to handle starting, querying, and cancelling the Workflow.

Build subscribe​

Now that your connection to the Temporal Server is open, define a /subscribe endpoint as function, so that users can subscribe to the emails.

src/main/java/subscription/Controller.java

    @PostMapping(value = "/subscribe", produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseBody
    public Message startSubscription(@RequestBody WorkflowData data) {

        WorkflowOptions options = WorkflowOptions.newBuilder()
                .setWorkflowId(data.getEmail())
                .setTaskQueue(Constants.TASK_QUEUE_NAME)
                .build();

        SendEmailWorkflow workflow = client.newWorkflowStub(SendEmailWorkflow.class, options);
        WorkflowClient.start(workflow::run,data);

        return new Message("Resource created successfully");
    }

In the startSubscription() function, use the WorkflowClient to start our Workflow Execution asynchronously. The WorkflowData object is used to pass the email address given by the user to the Workflow Execution and sets the Workflow ID in our WorkflowOptions. This ensures that the email is unique across all Workflows so that the user can't sign up multiple times, only receive the emails they've subscribed to, and when they cancel; they cancel the Workflow run. With this endpoint in place, you can now send a POST request to /subscribe with an email address in the request body to start a new Workflow that sends an email to that address. But how would you get details about the subscription?

In the next section, you'll query your Workflow to get back information on the state of things in the next section.

Add a Query​

A Query method let users get information about their subscription details. Queries can be used even after the Workflow completes, which is useful for when the user unsubscribes but still wants to retrieve information about their subscription. Queries should never mutate anything in the Workflow.

This method is declared using the @QueryMethod annotation in the Workflow interface.

    @QueryMethod
    public EmailDetails details();

The details() Query method allows users to retrieve information about their subscription details:

    @Override
    public EmailDetails details() {

        return emailDetails;
    }

The emailDetails object is an instance of EmailDetails.

private EmailDetails emailDetails = new EmailDetails();

Now that you've added the ability to Query your Workflow, add the ability to initiate your Query from the Spring Boot application.

Add a details endpoint​

To enable users to query the Workflow from the Spring Boot application, add a new endpoint called /get_details to the Controller.java file. Use the client.newWorkflowStub() function to return a SendEmailWorkflow object by a Workflow Id.

src/main/java/subscription/Controller.java

    @GetMapping(value = "/get_details", produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseBody
    public EmailDetails getQuery(@RequestParam String email) {

        SendEmailWorkflow workflow = client.newWorkflowStub(SendEmailWorkflow.class, email);
        return workflow.details();
    }

Using client.newWorkflowStub() retrieves a SendEmailWorkflow object that can be have the Query method called on it to get the value of the its variables.

This object enables you to return all the information about the user's email subscription that's declared in the Workflow.

Now that users can subscribe and view the details of their subscription, you need to provide them with a way to unsubscribe.

Add an unsubscribe option​

Users will want to unsubscribe from the email list at some point, so give them a way to do that. You cancel a Workflow by sending a cancellation request to the Workflow Execution. Your Workflow code can respond to this cancellation and perform additional operations in response. This is how you will handle unsubscribe requests.

With the Controller.java file open, add a new endpoint called /unsubscribe to the Spring Boot application. To send a cancellation notice to an endpoint, use the HTTP DELETE method on the unsubscribe endpoint to instruct a given email's workflow to be cancelled.

src/main/java/subscription/Controller.java

    @DeleteMapping(value = "/unsubscribe", produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseBody
    public Message endSubscription(@RequestBody WorkflowData data) {

        SendEmailWorkflow workflow = client.newWorkflowStub(SendEmailWorkflow.class, data.getEmail());
        WorkflowStub workflowStub = WorkflowStub.fromTyped(workflow);
        workflowStub.cancel();

        return new Message("Requesting cancellation");
    }

The workflowStub.cancel() method sends a cancellation request to the Workflow Execution that was started with the /subscribe endpoint.

When the Temporal Service receives the cancellation request, it will cancel the Workflow Execution and throw a CanceledFailure error to the Workflow Execution, which your Workflow Definition already handles in the try/catch block.

Here's the relevant section as a reminder:

            try {
                activities.sendEmail(emailDetails);
                Workflow.sleep(Duration.ofSeconds(duration));
            }
            catch (CanceledFailure e) {
                emailDetails.setSubscribed(false);
                emailDetails.setMessage("Sorry to see you go");
                CancellationScope sendGoodbye =
                        Workflow.newDetachedCancellationScope(() -> activities.sendEmail(emailDetails));
                sendGoodbye.run();

                throw e;
            }

With this endpoint in place, users can send a DELETE request to /unsubscribe with an email address in the request body to cancel the Workflow associated with that email address. This allows users to unsubscribe from the email list and prevent any further emails from sending.

Now that you've added the ability to unsubscribe from the email list, your API server is complete, and you only need to add a class to run the server.

Build the server app​

Create Starter.java in the subscription directory. It will run your SpringBoot app:

src/main/java/subscription/Starter.java

package subscription;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class Starter {

    public static void main(String[] args) {

        SpringApplication.run(Starter.class, args);
    }
}

Next, test your application code to ensure it works as expected.

Create an integration test​

Integration testing is an essential part of software development that helps ensure that different components of an application work together correctly. The Temporal Java SDK includes classes and methods that help you test your Workflow Executions. Workflow testing can be done in an integration test fashion against a test server or from a given Client.

In this section, you'll write an integration test using the Temporal Java SDK to test the cancellation of a Workflow. Now, you can add tests to the application to ensure the Cancellation works as expected.

To set up the test environment, create a file in the src/test/java directory called StarterTest.java The Temporal Java SDK includes classes and methods that help you test your Workflow Executions. In this section, you will import the necessary modules and classes to test the cancellation of a Workflow.

In this code, you are defining two test functions testCreateEmail() and testCancelWorkflow() that use the Temporal SDK to create and cancel a Workflow Execution.

src/test/java/StarterTest.java

import subscription.activities.SendEmailActivitiesImpl;
import subscription.workflows.SendEmailWorkflow;
import subscription.workflows.SendEmailWorkflowImpl;
import subscription.model.WorkflowData;
import io.temporal.api.common.v1.WorkflowExecution;
import io.temporal.api.enums.v1.WorkflowExecutionStatus;
import io.temporal.api.workflowservice.v1.DescribeWorkflowExecutionRequest;
import io.temporal.api.workflowservice.v1.DescribeWorkflowExecutionResponse;
import io.temporal.client.WorkflowClient;
import io.temporal.client.WorkflowStub;
import io.temporal.testing.TestWorkflowEnvironment;
import io.temporal.testing.TestWorkflowExtension;
import io.temporal.worker.Worker;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.RegisterExtension;
import static org.junit.jupiter.api.Assertions.assertEquals;


public class StarterTest {

    @RegisterExtension
    public static final TestWorkflowExtension testWorkflowExtension =
            TestWorkflowExtension.newBuilder()
                    .setWorkflowTypes(SendEmailWorkflowImpl.class)
                    .setDoNotStart(true)
                    .build();

    @Test
    public void testCreateEmail(TestWorkflowEnvironment testEnv, Worker worker, SendEmailWorkflow workflow) {

        WorkflowClient client = testEnv.getWorkflowClient();
        worker.registerActivitiesImplementations(new SendEmailActivitiesImpl());
        testEnv.start();

        WorkflowData data = new WorkflowData("test@example.com");

        WorkflowExecution execution = WorkflowClient.start(workflow::run,data);

        DescribeWorkflowExecutionResponse response = client.getWorkflowServiceStubs().blockingStub().describeWorkflowExecution(
                DescribeWorkflowExecutionRequest.newBuilder()
                        .setNamespace(testEnv.getNamespace())
                        .setExecution(execution)
                        .build()
        );

        WorkflowExecutionStatus status = response.getWorkflowExecutionInfo().getStatus();

        assertEquals(WorkflowExecutionStatus.WORKFLOW_EXECUTION_STATUS_RUNNING, status);
        testEnv.close();
    }

    @Test
    public void testCancelWorkflow (TestWorkflowEnvironment testEnv, Worker worker, SendEmailWorkflow workflow) {

        WorkflowClient client = testEnv.getWorkflowClient();
        worker.registerActivitiesImplementations(new SendEmailActivitiesImpl());
        testEnv.start();

        WorkflowData data = new WorkflowData("test@example.com");

        WorkflowExecution execution = WorkflowClient.start(workflow::run,data);

        WorkflowStub workflowStub = client.newUntypedWorkflowStub(execution.getWorkflowId());
        workflowStub.cancel();

        DescribeWorkflowExecutionResponse response;
        WorkflowExecutionStatus status;
        do {
             response = client.getWorkflowServiceStubs().blockingStub().describeWorkflowExecution(
                    DescribeWorkflowExecutionRequest.newBuilder()
                            .setNamespace(testEnv.getNamespace())
                            .setExecution(execution)
                            .build()
            );

             status = response.getWorkflowExecutionInfo().getStatus();
        }
        while (status != WorkflowExecutionStatus.WORKFLOW_EXECUTION_STATUS_CANCELED);

        assertEquals(WorkflowExecutionStatus.WORKFLOW_EXECUTION_STATUS_CANCELED, status);
        testEnv.close();
    }
}

The testCreateEmail() function creates a Workflow Execution by starting the SendEmailWorkflow with some test data. The function then asserts that the status of the Workflow Execution is RUNNING. The testCancelWorkflow() function also starts a Workflow Execution, but it then immediately cancels it using the cancel() method on the WorkflowStub. It then enters a while loop to repeatedly get the status of the Workflow Execution until the status is returned as CANCELED.

Now that you've created a test function for the Workflow Cancellation, run the test to see if that works. Run ./gradlew test --info from the command line to execute your tests and view the info on your test's execution.

Gradle will automatically run your tests without displaying execution information every time you run gradle build. You can use this command as an alternative if you are only interested in the successful result of the tests.

Congratulations! You've successfully written, executed, and passed a Cancellation Workflow test, just as you would any other code written in Java. Temporal's Java SDK provides a number of classes and methods that help you test your Workflow Executions. By following the best practices for testing your code, you can be confident that your Workflows are reliable and performant.

Conclusion​

This tutorial demonstrated how to build an email subscription web application using Temporal, Java, Spring Boot, and Gradle. By leveraging Temporal's Workflows, Activities, and Queries, the tutorial showed how to create a web server that interacts with Temporal to manage the email subscription process. With this knowledge, you will be able to take on more complex Workflows and Activities to create even stronger applications.

Tags:
Last updated on