tutorial

Monitoring Bonita BPM with Vigilmon

Bonita is an open source BPM and low-code platform — here's how to monitor the Bonita Engine, active cases, human task queues, the Portal, SLA compliance, REST API error rates, database persistence, and connector health with Vigilmon.

Bonita (formerly Bonita BPM, now Bonita Platform) is an open source business process management and low-code application platform developed by Bonitasoft. When you self-host Bonita, you're running the Bonita Engine (a BPMN 2.0 Java execution engine), the Bonita Portal (the web interface for operators and users to manage tasks and cases), and a relational database (PostgreSQL in Community Edition) for all case data and user assignments. Process automation in Bonita revolves around "cases" (process instances) — and when the engine fails, cases stall; when the database is unavailable, case state is lost; when the Portal is down, users can't complete their human tasks. Vigilmon gives you comprehensive monitoring of every layer in the Bonita stack.

What You'll Set Up

  • Bonita Engine health monitor via REST API
  • Active case count monitor with backlog alerting
  • Human task pending count monitor with SLA threshold
  • Bonita Portal availability monitor
  • Case SLA overdue count monitor
  • Bonita REST API error rate check
  • Database persistence health monitor
  • Connector execution error rate monitor
  • Bonita log error rate via heartbeat
  • JVM heap and GC health monitor

Prerequisites

  • Bonita 7.x or 2022+ Community or Enterprise Edition deployed on Tomcat
  • Bonita accessible on its HTTP port (default 8080)
  • A free Vigilmon account

Step 1: Monitor Bonita Engine Health

The Bonita Engine is the core of your Bonita deployment. It executes BPMN processes, handles connector calls, manages timer events, and persists case state to the database. Monitor the platform health REST endpoint:

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. URL: http://your-bonita-server:8080/bonita/API/system/session/unusedid
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 401 — the Bonita API returns 401 for unauthenticated requests, confirming the API is up and the engine is running.
  6. Click Save.

A 500 or a timeout on this endpoint means the Bonita Engine failed to initialize or the Tomcat container is unresponsive. The 401 response pattern is a reliable liveness signal that requires no credentials.

Alternatively, if you have API access, authenticate and check the platform state endpoint:

GET /bonita/API/system/tenant/1
Authorization: Bearer <session-token>

A healthy tenant returns "state":"ACTIVATED" in the JSON response.

Step 2: Monitor Active Case Count

In Bonita, process instances are called cases. A healthy deployment has a predictable number of active cases at any time, based on your business volume. A sudden spike indicates a backlog: cases are entering the system faster than they're completing, typically because human tasks are unattended or a connector is failing.

Expose active case count via a lightweight health endpoint in your application layer:

// Using the Bonita Java API in a custom Bonita extension or REST API extension
ProcessAPI processAPI = TenantAPIAccessor.getProcessAPI(apiSession);
long activeCases = processAPI.getNumberOfProcessInstances();

// Expose via Bonita REST API extension
JSONObject result = new JSONObject();
result.put("activeCases", activeCases);
result.put("status", activeCases < 5000 ? "ok" : "warning");
return result;
  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-bonita-server:8080/bonita/API/extension/activeCaseCount
  3. Expected status: 200
  4. Keyword check: "status":"ok"
  5. Check interval: 2 minutes
  6. Click Save.

Step 3: Monitor Human Task Pending Count

Human tasks are BPMN user activities that require an operator or end user to complete a form before the case advances. A growing pending task queue means real work is accumulating — SLA deadlines approach, cases stall, and users are left waiting.

Query the Bonita REST API for pending tasks (requires authenticated session):

# Count all pending human tasks
GET /bonita/API/bpm/humanTask?p=0&c=0&f=state=ready

For Vigilmon monitoring, wrap this in a REST API extension:

// Bonita REST API extension
long pendingTasks = humanTasksAPI.getNumberOfAssignedHumanTaskInstances(userId);
long readyTasks = humanTasksAPI.getNumberOfHumanTaskInstances(
    Arrays.asList(TaskPriority.NORMAL), HumanTaskInstanceSearchDescriptor.STATE_NAME, "ready"
);
long total = pendingTasks + readyTasks;

JSONObject result = new JSONObject();
result.put("pendingTasks", total);
result.put("status", total < 500 ? "ok" : "degraded");
  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-bonita-server:8080/bonita/API/extension/taskQueueHealth
  3. Expected status: 200
  4. Keyword check: "status":"ok"
  5. Check interval: 2 minutes
  6. Click Save.

Notify your process operations team — not just engineering — when this alert fires, because a deep task queue is a business operations issue.

Step 4: Monitor Bonita Portal Health

The Bonita Portal is the web interface where process operators manage cases, where end users complete their human task forms, and where administrators configure the platform. Portal unavailability blocks all manual work — users cannot complete tasks, cases cannot progress past human activities, and operators cannot intervene in failing cases.

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-bonita-server:8080/bonita/login.jsp
  3. Expected status: 200
  4. Keyword check: Bonita (appears in the portal page title and logo text)
  5. Check interval: 1 minute
  6. Enable Monitor SSL certificate if the portal is HTTPS-exposed, with expiry alert at 21 days.
  7. Click Save.

The login page is a good health proxy — it exercises the Bonita Portal servlet, the underlying Spring context, and the database session layer. A timeout or 500 at the login page means the portal is down for all users.

Step 5: Monitor Case SLA Compliance

Bonita processes often carry SLA requirements — a case must complete within 48 hours, a task must be claimed within 2 hours. When cases breach their SLA, it's a compliance and customer satisfaction issue that requires immediate escalation.

Expose overdue case count from a Bonita REST API extension:

// Find cases started more than 48 hours ago that are still active
Date slaDeadline = new Date(System.currentTimeMillis() - (48 * 60 * 60 * 1000));
SearchOptionsBuilder searchOptions = new SearchOptionsBuilder(0, 0);
searchOptions.filter(ProcessInstanceSearchDescriptor.STATE_ID, ProcessInstance.STATE_STARTED);
searchOptions.lessThan(ProcessInstanceSearchDescriptor.START_DATE, slaDeadline.getTime());

long overdueCases = processAPI.searchProcessInstances(searchOptions.done()).getCount();

JSONObject result = new JSONObject();
result.put("overdueCases", overdueCases);
result.put("status", overdueCases == 0 ? "ok" : "breached");
  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-bonita-server:8080/bonita/API/extension/slaHealth
  3. Expected status: 200
  4. Keyword check: "status":"ok"
  5. Check interval: 5 minutes
  6. Click Save.

Route this alert to both your engineering on-call and the business process owners.

Step 6: Monitor Bonita REST API Error Rate

Client applications integrate with Bonita via its comprehensive REST API — starting cases, completing tasks, querying case data. A spike in 4xx or 5xx errors from the Bonita REST API signals that integrations are breaking, which can cause cases to stall mid-execution.

Monitor the API availability with a representative endpoint:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-bonita-server:8080/bonita/API/system/session/unusedid
  3. Expected status: 401
  4. Check interval: 1 minute
  5. Click Save.

For error rate monitoring, add access log tracking in Tomcat's server.xml and expose error counts via a custom health endpoint:

<!-- Tomcat AccessLogValve for Bonita API error tracking -->
<Valve className="org.apache.catalina.valves.AccessLogValve"
       directory="logs"
       prefix="bonita_api_access_log."
       pattern="%h %l %u %t &quot;%r&quot; %s %b %D"
       resolveHosts="false" />

Aggregate error counts in your monitoring layer and expose via a health endpoint with "status":"ok" when the 5-minute 5xx rate is below your threshold.

Step 7: Monitor Database Persistence

Bonita stores all case data, task assignments, case variables, and process definitions in the database. A lost database connection causes immediate and complete failure of the Bonita Engine — no new cases can start, no tasks can be completed, and in-flight case state changes are rolled back.

Spring Boot's actuator health/db endpoint covers the connection pool automatically if you've embedded Bonita's database pool:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-bonita-server:8080/bonita/actuator/health/db
  3. Expected status: 200
  4. Keyword check: "status":"UP"
  5. Check interval: 1 minute
  6. Click Save.

If Bonita is deployed as a standalone Tomcat application without Spring Boot actuator, add a lightweight database probe servlet:

@WebServlet("/health/db")
public class DatabaseHealthServlet extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        try (Connection conn = dataSource.getConnection();
             PreparedStatement ps = conn.prepareStatement("SELECT 1")) {
            ps.execute();
            resp.setStatus(200);
            resp.getWriter().write("{\"status\":\"UP\"}");
        } catch (SQLException e) {
            resp.setStatus(503);
            resp.getWriter().write("{\"status\":\"DOWN\",\"error\":\"" + e.getMessage() + "\"}");
        }
    }
}

Set Alert after: 1 failure — database loss is immediately critical.

Step 8: Monitor Connector Execution Health

Bonita connectors integrate your BPMN processes with external systems — REST APIs, databases, email servers, LDAP directories, and enterprise systems like SAP or Salesforce. A connector failure causes the BPMN service task to fail, typically stalling or aborting the case.

Expose connector error rate from Bonita's event API or log monitoring:

// Bonita Connector event listener
public class ConnectorHealthListener extends ConnectorEventListenerExtension {
    private final AtomicLong connectorErrors = new AtomicLong(0);
    
    @Override
    public void onConnectorError(ConnectorEvent event) {
        connectorErrors.incrementAndGet();
        // Track per connector type
    }
}

Expose the error count via a health endpoint:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-bonita-server:8080/bonita/API/extension/connectorHealth
  3. Expected status: 200
  4. Keyword check: "status":"ok"
  5. Check interval: 2 minutes
  6. Click Save.

A connector failing repeatedly in a loop (retry on failure is enabled in the process definition) will produce a high connector error rate before the case itself aborts. Catching this early lets you fix the external system before the case reaches its retry limit.

Step 9: Monitor Bonita Log Error Rate

Bonita logs to the Tomcat server log files. A spike in ERROR log entries is a leading indicator of problems not yet visible in the REST API — database timeouts, connector failures, process compilation errors, or JVM garbage collection pressure.

Add a log file monitoring health endpoint using a log watcher:

// Tail the Bonita log and count ERROR lines in a rolling 5-minute window
@Scheduled(fixedDelay = 60000)
public void checkLogErrors() {
    long errorCount = logTailService.countRecentErrors(Duration.ofMinutes(5));
    this.recentErrors.set(errorCount);
}

@ReadOperation
public Health logErrorHealth() {
    long errors = recentErrors.get();
    return errors < 10
        ? Health.up().withDetail("recentErrors5m", errors).build()
        : Health.down().withDetail("recentErrors5m", errors).build();
}
  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-bonita-server:8080/bonita/actuator/health/logErrors
  3. Expected status: 200
  4. Keyword check: "status":"UP"
  5. Check interval: 2 minutes
  6. Click Save.

Step 10: Monitor JVM Heap and GC

Bonita runs on Tomcat/JVM. Large numbers of active cases, complex BPMN process definitions, and accumulated Bonita history data can all push heap usage above safe limits. A java.lang.OutOfMemoryError kills Tomcat instantly, dropping all in-flight case operations.

Add a heap health indicator:

@Component
public class HeapHealthIndicator implements HealthIndicator {
    
    @Override
    public Health health() {
        MemoryMXBean memBean = ManagementFactory.getMemoryMXBean();
        long used = memBean.getHeapMemoryUsage().getUsed();
        long max = memBean.getHeapMemoryUsage().getMax();
        double pct = (double) used / max * 100;
        
        if (pct > 85) {
            return Health.down()
                .withDetail("heapUsedPct", String.format("%.1f%%", pct))
                .withDetail("recommendation", "increase -Xmx or investigate memory leak")
                .build();
        }
        return Health.up().withDetail("heapUsedPct", String.format("%.1f%%", pct)).build();
    }
}
  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-bonita-server:8080/bonita/actuator/health/heapHealth
  3. Expected status: 200
  4. Keyword check: "status":"UP"
  5. Check interval: 1 minute
  6. Click Save.

Alerting Configuration

Configure alert channels and thresholds to match business impact:

Engine health (401 probe) — alert immediately on 1 failure. The entire platform is down.

Database persistence — alert immediately on 1 failure. No recovery possible until reconnected.

Portal availability — alert after 2 consecutive failures to your on-call engineer and business ops team.

Active case count / task queue — alert after 2 consecutive threshold breaches; notify process operations team.

SLA violations — alert every breach; notify both engineering and business process owners.

Connector errors — alert after 2 consecutive failures; identify which connector type is failing from the error detail.

JVM heap — alert above 85% heap; include a runbook link for emergency heap dump and restart.

Log error rate — alert when sustained above threshold; treat as a leading indicator for triage, not an emergency.

Conclusion

Self-hosted Bonita Platform is a reliable BPMN automation tool, but its self-managed nature means monitoring falls entirely on you. With Vigilmon's HTTP monitors covering the Engine, Portal, database, and connectors, and a heartbeat covering your Quartz-equivalent scheduler, you get immediate notification when any layer of the Bonita stack degrades. The combination of runtime health checks and business-level metrics (case counts, task queues, SLA compliance) gives you visibility at both the infrastructure level and the process operations level.

Start with the free Vigilmon account and add your first Bonita Engine monitor in under five minutes.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles