REST Service Call Task WorkItemHandler

The Enhanced REST Service Call Task WorkItemHandler enables secure, authenticated REST API calls from BPMN workflows. The library provides a solution for integrating external REST services into your workflows with enhanced security and configuration capabilities.

You do not need to add the library to your project, because it is already included in all BAMOE workflow Accelerators. For more information about the Accelerators, see Using Accelerators. The library is automatically configured and available for use in your workflows by org.kie.kogito:kogito-rest-workitem dependency included in BAMOE BOM. You can access the handler through BPMN Editor task palette without adding any additional dependencies.

To deploy the REST Service Call Task WorkItemHandler, you can use the standard BAMOE deployment process or no handler-specific deployment steps.

REST Service Call Task is a new custom BPMN task following Gen AI and AI Agent Tasks design patterns. The REST Service Call Task is configured in the BPMN Editor task palette and the configuration is available in the dedicated properties panel. For more information about the BPMN Editor, see Authoring Workflows with BPMN.

REST Service Call Task uses standard constructs such as ioSpecification, dataInput, and dataOutput. The task supports process variable interpolation syntax #{expression}, and provides real-time validation with development-time feedback. It also includes authoring-time testing capabilities and supports HTTP methods with dynamic headers and query parameters.

The REST Service Call Task is designed to be a single source of truth, with automatic BPMN model serialization and no need for .wid files.

Configuring REST WorkItemHandler

The REST WorkItemHandler supports multiple configuration approaches to accommodate different deployment scenarios, security requirements, and operational preferences. To configure, you can use one of the following methods:

  • REST endpoint URL,

  • HTTP Method,

  • Headers and query parameters,

  • One of the following token acquisition strategies:

    • propagated uses access token from current thread (user-initiated workflows)

    • configured uses pre-configured token from application properties (system-triggered processes)

    • none with no authentication for public APIs

  • Request payload,

  • Access tokens or OIDC security.

Configuration can be provided at the following layers:

  • BPMN Model Configuration (Design-time)

  • Application Properties Configuration (Deployment-time)

  • Environment Variables Configuration (Runtime)

BPMN Model Configuration (Design-time)

BPMN Model Configuration is embedded directly in the BPMN process definition through the REST Service Call Task properties panel. Values except test token are stored in the BPMN XML file. Test token is only for testing and not stored in the file. Values are visible to anyone with access to the process definition.

See the following example for reference:

Url: https://api.example.com/users
Method: GET
AccessTokenAcquisitionStrategy: none

Use the BPMN Model Configuration when public API endpoints are used and no security is required. Do not use this configuration for sensitive data or environment-specific URLs.

Application Properties Configuration (Deployment-time)

Application Properties Configuration is a configuration provided in application.properties. Values are read at application startup and can be different per environment. Supports property placeholders for environment variables. Requires application restart to take effect. This approach is recommended for environment-specific configuration.

See the following example for reference:

# Quarkus (application.properties)

# Access token for configured strategy
kogito.processes.user-lookup.FindUserRestCall.access_token=${USER_MGMT_TOKEN}

# Base URL for REST endpoints
api.base.url=https://api.staging.example.com

# Timeout configuration
kogito.rest.default.timeout=30000

# Debug logging
quarkus.log.category."org.kogito.workitem.rest".level=DEBUG

Environment Variables Configuration (Runtime)

Environment Variables Configuration is a configuration provided through operating system environment variables or container orchestration platforms. This approach is most secure for sensitive data like API keys and passwords. Requires application restart to take effect. This approach is recommended for environment-specific configuration.

See the following example for reference:

# Docker Compose
version: '3.8'
services:
  bamoe-business-service:
    environment:
      - KOGITO_PROCESSES_USER_LOOKUP_FINDUSERRESTCALL_ACCESS_TOKEN=${USER_MGMT_TOKEN}
      - API_BASE_URL=https://api.production.example.com

Token Configuration for REST Service Call Task WorkItemHandler

REST Service Call Task WorkItemHandler introduces the following configuration properties:

  • Access Token Configuration (Configured Strategy),

  • Debug Logging.

Access Token Configuration

This configuration specifies the access token to use when AccessTokenAcquisitionStrategy is set to configured. This property is required for system-triggered processes that cannot rely on user authentication context. It is a string property that can be set in the application properties file or as an environment variable.

Use the following property format:

kogito.processes.{processId}.{RestServiceCallTaskId}.access_token

See the following example for reference:

# Quarkus
kogito.processes.user-lookup.FindUserRestCall.access_token=${USER_MGMT_TOKEN}

You can also set the property using an environment variable:

KOGITO_PROCESSES_{PROCESSID}_{RESTSERVICECALLTASKID}_ACCESS_TOKEN

See the following example for reference:

export KOGITO_PROCESSES_USER_LOOKUP_FINDUSERRESTCALL_ACCESS_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Debug Logging

This configuration enables detailed logging for the REST WorkItemHandler, including request/response details, authentication flow, and error diagnostics. You can use it for debugging and monitoring REST calls in production environments. It is a string property that can be set in the application properties file or as an environment variable. The default value is INFO, and the supported log levels are TRACE, DEBUG, INFO, WARN, and ERROR. It is not required for system-triggered processes that cannot rely on user authentication context.

Use the following property format:

quarkus.log.category."org.kogito.workitem.rest".level
quarkus.log.category."org.kie.kogito.process.workitems".level

See the following example for reference:

# Quarkus
quarkus.log.category."org.kogito.workitem.rest".level=DEBUG
quarkus.log.category."org.kie.kogito.process.workitems".level=DEBUG

# Spring Boot (application.yml)
logging:
  level:
    org.kogito.workitem.rest: DEBUG
    org.kie.kogito.process.workitems: DEBUG

Using REST Service Call Task WorkItemHandler

This section provides step-by-step guidance on how to effectively use the REST Service Call Task and configure the REST Service Call Task WorkItemHandler in your BAMOE project.

For Business Service Developers

Configure your BAMOE application to support REST WorkItemHandler:

  1. Verify that org.kie.kogito:kogito-rest-workitem dependency is included.

    The dependency is automatically included in BAMOE BOM and all workflow accelerators. No manual dependency addition is required. For more information, see org.kie.kogito:kogito-rest-workitem.

  2. If you are using configured authentication method, configure Access Tokens.

    Set up the following access tokens in your application properties:

    kogito.processes.<processId>.<RestServiceCallTaskId>.access_token=${ACCESS_TOKEN}

    Add the following environment variable:

    export ACCESS_TOKEN=<add generated token>

  3. Enable detailed logging to diagnose REST call issues:

    quarkus.log.category."org.kogito.workitem.rest".level=DEBUG
quarkus.log.category."org.kie.kogito.process.workitems".level=DEBUG

  4. Deploy your application using the standard BAMOE deployment processes.

For BPMN Workflow Authors

Follow these steps to integrate REST API calls into your workflows:

  1. Add the Task to Your Workflow.

    1. Open your workflow in BPMN Editor in BAMOE Canvas or Developer Tools for VS Code.

    2. Locate REST Service Call Task in the task palette, drag it to the canvas and connect it to your workflow sequence flow.

  2. Configure Basic REST Parameters. Set the following properties in the task properties panel:

    Method: GET, POST, PUT, DELETE, or PATCH
Url: https://api.example.com/users/#{userId}
RequestTimeout: 60000 (milliseconds, optional)

    You can use process variable interpolation syntax #{variableName} to make URLs dynamic.

  3. Select authentication strategy. Choose one of the following authentication methods based on your use case:

    • propagated - Use when the workflow is triggered by a user and you want to forward their authentication token to the REST API.

    • configured - Use for system-triggered workflows that need a pre-configured service account token, requires RestServiceCallTaskId.

    • none - Use for public APIs that don’t require authentication.

  4. Optional: Add headers and query parameters. Configure the following HTTP headers and query parameters as needed:

    HEADER_Content-Type: application/json
HEADER_Accept: application/json
QUERY_page: 1
QUERY_limit: 50
    Note
    		 Prefix header names with HEADER_ and query parameters with QUERY_.

  5. Configure Request Payload for POST, PUT, and PATCH.

    1. Map a process variable to the ContentData input parameter.

    2. The handler automatically serializes your data to JSON.

    3. See Request Payload Configuration for more information.

  6. Map the Response to Process Variables.

    1. Configure the Result output mapping in the properties panel.

    2. Access response data in subsequent tasks using #{result.propertyName}.

      The response is automatically deserialized from JSON.

  7. Test your configuration.

    1. Use the built-in testing capability in the BPMN Editor.

    2. Verify the REST call succeeds with test data.

    3. Check response mapping works as expected.

Request Payload Configuration

Request payloads for POST, PUT, and PATCH operations are provided through the ContentData parameter. You can configure request payloads by using one of the following methods:

  • Direct process variable mapping.

  • Expression-based mapping.

  • Literal string value.

Direct Process Variable Mapping

To use the direct process variable mapping method, do the following steps:

  1. Create process variable. See the following example for reference:

    // In process initialization or previous task
Map<String, Object> employeeData = new HashMap<>();
employeeData.put("firstName", "John");
employeeData.put("lastName", "Doe");
employeeData.put("email", "john.doe@example.com");
employeeData.put("department", "Engineering");

  2. Map to ContentData in BPMN. See the following example for reference:

    <bpmn2:dataInput id="ContentData" name="ContentData"/>
<bpmn2:dataInputAssociation>
  <bpmn2:sourceRef>employeeData</bpmn2:sourceRef>
  <bpmn2:targetRef>ContentData</bpmn2:targetRef>
</bpmn2:dataInputAssociation>

  3. Assign the employeeData process variable to the request body. The REST WorkItemHandler handles JSON serialization automatically when sending POST, PUT, or PATCH requests.

Expression-Based Mapping

To configure request payloads by using expression-based mapping, in BPMN Editor properties panel add the following property:

ContentData: #{employeeData}

Literal String Value

You can configure simple payloads by using literal string value method. In BPMN Editor properties panel add the following property:

ContentData: {"status":"active","priority":"high"}
Note
 This method is not flexible and not recommended for dynamic data.

Payload Validation Requirements

The REST WorkItemHandler enforces the following validation rules to ensure correct payload configuration:

HTTP Method Validation

Rule

ContentData is only allowed for methods that support request bodies.

Allowed Methods

POST, PUT, PATCH

Disallowed Methods

GET, DELETE, HEAD, OPTIONS

Validation Message

ContentData parameter is not supported for GET requests. Use POST, PUT, or PATCH methods to send request payloads.

Content-Type Header Validation

Rule

When ContentData contains structured objects/maps, HEADER_Content-Type should be configured

Recommended Value

application/json

Validation Message

When sending structured data in ContentData, configure HEADER_Content-Type header (e.g., application/json).

Payload Type Validation

Rule

ContentData must be a valid JSON object or string.

Supported Types

JSON objects, raw strings, process variable references

Unsupported Types

XML, multipart/form-data, file uploads

Validation Message

XML payloads are not supported. Use JSON format.

Validation Message

Multipart form data is not supported.

Validation Message

File uploads are not supported as ContentData.

Semantic Consistency Validation

Rule

Payload configuration must be semantically consistent with HTTP method.

Validation Message

Request payload (ContentData) is configured but HTTP method is GET. Change method to POST, PUT, or PATCH, or remove ContentData.

Example (incorrect usage)

GET method with ContentData configured