Camunda provides a Spring Boot Starter for the External Task Client. This allows you to easily add the External Task Client to your Spring Boot application by adding the following Maven dependency to your pom.xml file:

<dependency>
  <groupId>org.camunda.bpm.springboot</groupId>
  <artifactId>camunda-bpm-spring-boot-starter-external-task-client</artifactId>
  <version>7.22.0-cibseven</version>
</dependency>

Please check Camunda External Task Client Spring Boot Starter Examples.

The Client can subscribe to one or more topic names that are defined in your BPMN process model. When the execution waits in an External Task, the Client executes your custom business logic. For instance, the customer’s credit score is checked, and if successful, the External Task can be marked as completed and the execution proceeds.

Requirements

External Task Client Spring Boot Starter requires Java 17.

Topic Subscription

The interface which allows implementing the custom business logic and interacting with the Engine is called ExternalTaskHandler. A subscription is identified by a topic name and configured with a reference to the ExternalTaskHandler bean.

You can subscribe the Client to the topic name creditScoreChecker by defining a bean with the return type ExternalTaskHandler and annotate this bean with:

@ExternalTaskSubscription("creditScoreChecker")

The annotation requires at least the topic name. However, you can apply more configuration options by either referencing the topic name in your application.yml file:

camunda.bpm.client:
  base-url: http://localhost:8080/engine-rest
  subscriptions:
    creditScoreChecker:
        process-definition-key: loan_process
        include-extension-properties: true
        variable-names: defaultScore

Or, by defining configuration attributes in the annotation:

@ExternalTaskSubscription(
  topicName = "creditScoreChecker",
  processDefinitionKey = "loan_process",
  includeExtensionProperties = true,
  variableNames = "defaultScore"
)

Please find the complete list of attributes in the Javadocs .

Please Note: A property defined in the application.yml file always overrides the respective attribute defined programmatically via annotation.

Handler Configuration Example

Please consider the following complete handler bean example:

@Configuration
@ExternalTaskSubscription("creditScoreChecker")
public class CreditScoreCheckerHandler implements ExternalTaskHandler {

  @Override
  public void execute(ExternalTask externalTask, 
                      ExternalTaskService externalTaskService) {
    // add your business logic here
  }

}

If you want to define multiple handler beans within one configuration class, you can do it as follows:

@Configuration
public class HandlerConfiguration {

  @Bean
  @ExternalTaskSubscription("creditScoreChecker")
  public ExternalTaskHandler creditScoreCheckerHandler() {
    return (externalTask, externalTaskService) -> {
      // add your business logic here
      externalTaskService.complete(externalTask);
    };
  }

  @Bean
  @ExternalTaskSubscription("loanGranter")
  public ExternalTaskHandler loanGranterHandler() {
    return (externalTask, externalTaskService) -> {
      // add your business logic here
      externalTaskService.complete(externalTask);
    };
  }

}

Open/close a Topic Subscription

When not further configured, a topic subscription is automatically opened when the Spring Boot application starts, meaning the Client starts immediately to fetch External Tasks related to the topic name.

There might be situations in which a topic subscription should not be opened immediately when the application starts. You can control this via the auto-open flag.

The interface SpringTopicSubscription allows you to open or close a topic programmatically as soon as the subscription has been initialized. The initialization process is triggered as soon as the application is started.

When the subscription has been initialized, a SubscriptionInitializedEvent is emitted, and the topic subscription can be opened or closed:

@Configuration
public class SubscriptionInitializedListener 
    implements ApplicationListener<SubscriptionInitializedEvent> {

  @Override
  public void onApplicationEvent(SubscriptionInitializedEvent event) {

    SpringTopicSubscription topicSubscription = event.getSource();

    String topicName = topicSubscription.getTopicName();
    boolean isOpen = topicSubscription.isOpen();
    if ("creditScoreChecker".equals(topicName)) {

      if(!isOpen) {
        // Start fetching for External Tasks
        topicSubscription.open();

      } else {
        // Stop fetching for External Tasks
        topicSubscription.close();

      }
    }
  }

}

Configuration

application.yml file

The central configuration point is the application.yml file.

Client Bootstrapping

Please make sure to configure the properties together with the prefix: camunda.bpm.client

An example configuration could look as follows:

camunda.bpm.client:
  base-url: http://localhost:8080/engine-rest
  worker-id: spring-boot-worker
  basic-auth:
    username: admin
    password: admin

Available properties:

Topic Subscription

The properties for topic subscriptions go under: camunda.bpm.client.subscriptions

The configuration properties can be applied for each topic name as follows:

camunda.bpm.client:
  # ADD CLIENT CONFIGURATION HERE
  subscriptions:
    creditScoreChecker:
        process-definition-key: loan_process
        include-extension-properties: true
        variable-names: defaultScore
    loanGranter:
        process-definition-key: loan_process

Available properties:

Logging

To log the Client’s internal workings, you can set the level of the logger org.camunda.bpm.client.spring to DEBUG.

You can set the log level in your application.yml file as follows:

logging.level.org.camunda.bpm.client.spring: DEBUG

For debugging, it might be helpful to increase the level of the logger org.camunda.bpm.client as well.

Request Interceptor

A request interceptor is called whenever the Client performs an HTTP request. You can use this extension point, for example, to implement a custom authentication strategy like OAuth 2.0.

You can register one or more request interceptors by defining beans of type ClientRequestInterceptor:

@Configuration
public class RequestInterceptorConfiguration implements ClientRequestInterceptor {
  // ...
}

Backoff Strategy

By default, the Client uses an exponential backoff strategy. You can replace it with a custom strategy by defining a bean of type BackoffStrategy:

@Configuration
public class BackoffStrategyConfiguration implements BackoffStrategy {
  // ...
}

Resolving Properties

String-based Client configuration properties can be resolved from a custom properties file by defining a bean of type PropertySourcesPlaceholderConfigurer:

@Configuration
public class PropertyPlaceholderConfiguration 
    extends PropertySourcesPlaceholderConfigurer {

  public PropertyPlaceholderConfiguration() {
    // Specify the *.properties file name that contains the property placeholders
    Resource location = new ClassPathResource("client.properties");
    setLocation(location);
  }

}

When using the example shown above, the Client tries to resolve string-based properties from a client.properties file as follows:

client.baseUrl=http://localhost:8080/engine-rest
client.workerId=spring-boot-worker
client.dateFormat=yyyy-MM-dd'T'HH:mm:ss.SSSZ
client.serializationFormat=application/json

Make sure to reference the respective placeholders defined above in your application.yml file:

camunda.bpm.client:
  base-url: ${client.baseUrl}
  worker-id: ${client.workerId}
  date-format: ${client.dateFormat}
  default-serialization-format: ${client.serializationFormat}

Custom Client

You can bootstrap the Client programmatically, which skips the internal creation of the Client:

@Configuration
public class CustomClientConfiguration { 

  @Bean
  public ExternalTaskClient customClient() {
    return ExternalTaskClient.create()
        .baseUrl("http://localhost:8080/engine-rest")
        .build();
  }

}

Beans

You can define handler beans, but more beans are defined internally, and they are beyond your control. However, these beans can be accessed via auto wiring.

Client Bean

When not already defined by the user (see Custom Client), a bean with the name externalTaskClient of type ExternalTaskClient is constructed.

Subscription Bean

Based on a handler bean annotated with @ExternalTaskSubscription, a subscription bean of type SpringTopicSubscription is constructed. The bean name is composed of:

handler bean name + "Subscription"

For instance, the following handler bean definition:

@Bean
@ExternalTaskSubscription("creditScoreChecker")
public ExternalTaskHandler creditScoreCheckerHandler() {
  // ...
}

Will result in the subscription bean name:

creditScoreCheckerHandlerSubscription

Spring-only Module

If you want to use Spring instead of Spring Boot, you can add the following Maven dependency to your pom.xml file:

<dependency>
  <groupId>org.camunda.bpm</groupId>
  <artifactId>camunda-external-task-client-spring</artifactId>
  <version>7.22.0-cibseven</version>
</dependency>

To bootstrap the Client, use the class annotation @EnableExternalTaskClient. You can find all configuration attributes in the Javadocs .