REST Component in jBPM – Complete Guide with Examples

 Modern business processes often require calling external services—microservices, third-party APIs, or internal REST endpoints.

In jBPM, this is made possible using the REST Work Item Handler (REST WIH), commonly called the REST Component.

In this article, you’ll learn:

• What the REST component is

• How to configure it

• How to call REST APIs (GET/POST/PUT/PATCH)

• How to pass headers, parameters, and body

• How to store and use responses in the workflow

• Best practices and optional advanced tips

---

🔹 What Is the REST Component in jBPM?

The REST Work Item Handler allows your BPMN process to make external REST API calls.

A REST Work Item can:

✔ Call any REST endpoint
✔ Support GET, POST, PUT, DELETE, PATCH
✔ Pass JSON/XML bodies
✔ Attach HTTP headers
✔ Capture response codes and response bodies
✔ Store the response into process variables

It is mostly used inside a Service Task.

---

🔧 Configuring REST Work Item Handler

Add the REST WIH dependency in your pom.xml:

<dependency>
    <groupId>org.jbpm</groupId>
    <artifactId>jbpm-workitems-rest</artifactId>
    <version>7.74.1.Final</version>
</dependency>

Register the handler in WorkItemHandlerConfig:

kmodule.registerWorkItemHandler("Rest",
       new org.jbpm.process.workitem.rest.RESTWorkItemHandler());

Now your jBPM process can use the REST Service Task.

---

🔹 Example BPMN Structure

Your BPMN process will look like this:

Start → Service Task (REST call) → Script Task → End

Inside the Service Task:

• Work Item Name: Rest

• Parameters:

  • Method: POST

  • Url: https://api.example.com/items

  • ContentType: application/json

  • Body: {"id":1,"name":"Phone"}

---

📤 Example 1: REST POST Call (Simple JSON)

Step 1: Input parameters in Service Task

Parameter	Value
Method	POST
Url	https://api.restful-api.dev/objects
ContentType	application/json
Body	{"name":"Laptop","price":999}

Step 2: Using response in Script Task

The REST WIH returns:

• result → Response body as string

• status → HTTP status code

String apiResponse = (String) kcontext.getVariable("result");
Integer status = (Integer) kcontext.getVariable("status");

System.out.println("API Status: " + status);
System.out.println("API Response: " + apiResponse);

---

⛳Example 2: REST GET Call

Parameter	Value
Method	GET
Url	https://api.restful-api.dev/objects/100
ContentType	application/json

Use returned JSON in next tasks.

---

📤  Example 3: REST PUT Call

{
  "name": "Updated Product",
  "price": 1200
}

Work Item Parameters:

• Method: PUT

• Url: https://api.restful-api.dev/objects/100

• Body: JSON Body

---

✏️ Example 4: REST PATCH Call

Parameter	Value
✏️ Method	PATCH
Url	https://api.restful-api.dev/objects/100
Body	{"price": 1500}

---

🗑️ Example 5: REST DELETE Call

Parameter	Value
🗑️ Method	DELETE
Url	https://api.restful-api.dev/objects/100

📌 Example 4: Pass Headers (Authorization, API Key)

headers:
{
  "Authorization": "Bearer 12345",
  "x-api-key": "ABC-XYZ"
}

In the Service Task Parameters:

Name	Value
Headers	Authorization=Bearer 12345,x-api-key=ABC-XYZ

---

📌 Example 5: Dynamic URL Using Process Variables

In URL:

https://api.example.com/items/#{itemId}

jBPM replaces #{itemId} with actual process value.

---

🎯 Best Practices for REST in jBPM

✔ Keep API URLs and tokens as global env variables
✔ Implement retries for unstable endpoints
✔ Use a Script Task to validate the response
✔ Avoid putting huge JSON directly inside BPMN
✔ Use Jackson to convert response to Java POJO

Example:

ObjectMapper mapper = new ObjectMapper();
MyResponse obj = mapper.readValue(apiResponse, MyResponse.class);

👉 Watch “REST Component in jBPM  7” in Action:

A live demo showing how rest component works with process.
🎬 YouTube: Learn IT with Shikha

👉 Source code: Branches : RESTComponent

LearnITWithShikha/customWorkItemItemHanlder at RESTComponent

---

📘 When to Use REST Work Item?

Use REST WIH when:

• You want no Java code (declarative BPM)

• You want API call defined inside BPMN

• You want business users to see external integrations

Use Java Service Tasks + custom code when:

• Complex authentication

• Large workflows

• Error-handling logic needed

---

✅ Summary

Feature	REST Work Item
API calls	✔ Yes
JSON/XML support	✔
Headers	✔
Path params	✔
Capture response	✔
Easy to configure	✔

The REST Component in jBPM provides a powerful, lightweight way to integrate external services directly inside your process models.

💼 Professional Support Available

If you are facing issues in real projects related to enterprise backend development or workflow automation, I provide paid consulting, production debugging, project support, and focused trainings.

Technologies covered include Java, Spring Boot, PL/SQL, Azure, and workflow automation (jBPM, Camunda BPM, RHPAM).

📧 Contact: ishikhanirankari@gmail.com | info@realtechnologiesindia.com

🌐 Website: IT Trainings | Digital metal podium