Temporal Spring Boot Integration Demo

Links

• Temporal Java SDK
• Spring Boot Integration package

Intro

This demo showcases Temporal Java SDK integration with Spring Boot. It uses the Java SDK Spring Boot AutoConfig.

Shown features:

• Connection Setup
• Workflows and Activities auto-discovery
• Integration with Metrics (Prometheus)
• Integration with Tracing (Jaeger)
• Testing
• mTLS / Temporal Cloud Support

Run Demo

Option 1: Local Temporal Server (Default)

1. First we need to set up Temporal Server. Let's start a local server.

temporal server start-dev

NOTE: The metrics and tracing capabilities will be updated in the next PR

To showcase the metrics and tracing capabilities it's easiest to use this repo which has it all built in and ready to go. If you already have Temporal server running on Docker locally you can clean and prune and then run:

git clone https://github.com/tsurdilo/my-temporal-dockercompose
cd my-temporal-dockercompose
docker network create temporal-network
docker compose -f docker-compose-postgres.yml -f docker-compose-services.yml up

2. Now lets build and start the demo (the web UI is now embedded in the project)

git clone git@github.com:tsurdilo/temporal-springboot-demo.git
cd temporal-springboot-demo
mvn clean install spring-boot:run

Option 2: Temporal Cloud

To connect to Temporal Cloud instead of a local server:

1. Set up your Temporal Cloud namespace and obtain mTLS certificates
2. Configure environment variables:

export TEMPORAL_ADDRESS="your-namespace.tmprl.cloud:7233"
export TEMPORAL_NAMESPACE="your-namespace.account-id"
export TEMPORAL_CERT_PATH="/path/to/client.pem"
export TEMPORAL_KEY_PATH="/path/to/client.key"

3. Run with the cloud profile:

mvn spring-boot:run -Dspring-boot.run.profiles=cloud

📖 For detailed Temporal Cloud setup instructions, see TEMPORAL_CLOUD_SETUP.md

Worker Management

Important: With Spring Boot Temporal integration, the Worker is automatically started when you run the application. There's no need to start a separate Worker process.

When you execute mvn spring-boot:run, the application will:

1. Start the Spring Boot web server (port 3030)
2. Automatically discover and register Workflows and Activities via @WorkflowImpl and @ActivityImpl annotations
3. Automatically start Worker(s) configured in application.yml under spring.temporal.workers

You'll see log output like this when the Worker starts:

Creating a worker with default settings for a task queue 'DemoTaskQueue'...
Registering auto-discovered workflow class DemoWorkflowImpl...
Registering auto-discovered activity bean 'demoActivitiesImpl'...

Worker Configuration

Workers are configured in src/main/resources/application.yml:

spring:
  temporal:
    workers:
      - task-queue: DemoTaskQueue
        capacity:
          max-concurrent-workflow-task-pollers: 5
          max-concurrent-activity-task-pollers: 5

For more details on worker configuration options, see the Spring Boot AutoConfig documentation.

Use Demo

Once your demo has started up you can access the ui via localhost:3030

The web UI provides custom Thymeleaf tags for Temporal workflow management:

• <temporal:shownav/> - Navigation bar with links to monitoring tools
• <temporal:clusterinfo/> - Display Temporal cluster information
• <temporal:startworkflow/> - Form to start workflow executions
• <temporal:listworkflows/> - List all workflow executions with management actions

Configuration

You can configure external monitoring tool URLs in application.yml:

temporal:
  ui:
    grafana:
      url: http://localhost:8085
    jaeger:
      url: http://localhost:16686
    webui:
      url: http://localhost:8081

Start new Execution

Click on "Show/Hide" in the "Start Workflow Execution" module to expand it. This will let us start a new workflow exec.

Our workflow type is "DemoWorkflow" and its running as we specified via annotations on the "DemoTaskQueue" task queue. You can set whichever workflow id you wish. The input of our workflow execution must be in CloudEvents format as that is what our custom data converter expects. Here is sample that you can use:

{
  "id": "123",
  "source": "localhost:3030",
  "type": "io.temporal.demo",
  "data": {
   "first": "john",
   "last": "doe"
  }
}

Click on "Start Exec" to start a new workflow execution:

Signal Execution

Our execution is in "Running" status, as it is waiting on the next CloudEvent sent to it to continue. It is going to wait until we do that, so let's send it. Click on the "Signal Workflow" button in the "Actions" column:

Fill in "addEvent" as the signal name, as that is what our demo workflow defines as the signal method. Enter in a different CloudEvent in the signal payload, you can use:

 {
   "id": "124",
   "source": "localhost:3030",
   "type": "io.temporal.demo",
   "data": {
     "first": "marry",
     "last": "doe"
   }
 }

And click the "Signal" button.

You should see that our workflow execution is now in the "Completed" status.

Query Execution

With Temporal you can query completed workflow executions (up to the configured retention period on the namespace). So let's try to query it. The query will give us the last event sent to the workflow, so we should get the same event as what we just signalled.

For this click on the "Query Workflow" button in "Actions", set the query name to "getLastEvent" as that is what our workflow definition defines as the query name, then click "Query Workflow" button:

Get Execution Result

Next lets see what our workflow execution results are. Again you can get results of completed executions up to configured retention period on the namespace.

For this click on the "Get Result" button in "Actions", then click on "Get Result" button. You should see the results which is also a CloudEvent that includes all the ids of the so far sent signals. For our demo that should be "123" and "124", the ids of the event that we sent as workflow data input and then the one that we signalled the workflow execution earlier:

See Metrics and Tracing Info

For metrics, in the navbar on top of the page click on "Grafana" and browse the SDK and Server dashboards that come out of the box for you.

For tracing, in the navbar on top of the page click on "Jaeger". For service select "temporal-demo", and then in the Operation dropdown select "RunWorkflow:DemoWorkflow", then click "Find Traces".

In the result select the http post trace which is the one the UI used to start our workflow execution: