Monitoring ProcessMaker BPM with Vigilmon

ProcessMaker is one of the most widely used open source business process management (BPM) platforms — a PHP-based workflow automation tool that lets HR, finance, IT, and legal teams build and run approval workflows without writing code. When you self-host ProcessMaker, you're running a Laravel/PHP application backed by MySQL, a Redis-powered queue worker (Laravel Horizon) for async task processing, and a web server (Nginx/Apache + PHP-FPM) to serve the BPM interface. If the queue worker goes down, tasks stop being processed and workflows stall silently. If MySQL fails, all case data is unavailable. If PHP-FPM pools fill up, the entire BPM interface becomes unresponsive. Vigilmon gives you monitoring across every layer so you catch these failures before they impact your business processes.

What You'll Set Up

• HTTP uptime monitor for the ProcessMaker web application
• MySQL database connectivity and slow query monitor
• Laravel Horizon queue worker health via cron heartbeat
• Redis connectivity monitor
• Active case count anomaly alert
• Task completion rate and overdue task alert
• Scheduled process trigger health check
• PHP-FPM pool utilization monitor
• Form submission API success monitor
• ProcessMaker version currency check

Prerequisites

• ProcessMaker 4.x (Spark/Laravel) instance running
• MySQL accessible (default port 3306)
• Redis accessible (default port 6379)
• PHP-FPM running (typically on a Unix socket or port 9000)
• A free Vigilmon account

Step 1: Monitor the ProcessMaker Web Application

The ProcessMaker web interface is what your users access to manage workflows, submit forms, and track cases. An uptime monitor on the application root catches crashes, misconfigurations, and deployment failures.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the application URL: https://bpm.yourdomain.com (or http://your-server-ip).
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Under Keyword check, enter ProcessMaker to verify the login page loads correctly.
7. Enable Monitor SSL certificate and set the expiry alert to 21 days.
8. Click Save.

For a deeper application health signal, add a /api/1.0/health check (ProcessMaker 4.x exposes health via API):

1. Add a second monitor with URL: https://bpm.yourdomain.com/api/1.0/health.
2. Expected HTTP status: 200
3. Keyword check: healthy

Step 2: Monitor MySQL Database Health

MySQL stores all ProcessMaker data — BPMN process definitions, case (process instance) data, form submissions, user accounts, and audit logs. A MySQL outage halts the entire BPM platform.

Add a TCP monitor for MySQL connectivity:

1. Click Add Monitor → TCP Port.
2. Host: your-server-ip.
3. Port: 3306 (MySQL default).
4. Check interval: 1 minute.
5. Click Save.

For a richer check that verifies ProcessMaker can query the database, add a health endpoint to the Laravel app:

// routes/api.php — add to ProcessMaker's API routes
Route::get('/monitoring/db-health', function () {
    try {
        DB::statement('SELECT 1');
        $caseCount = DB::table('PROCESS_INSTANCES')->count();
        return response()->json([
            'status' => 'healthy',
            'active_cases' => $caseCount,
        ]);
    } catch (\Exception $e) {
        return response()->json(['status' => 'unhealthy', 'error' => $e->getMessage()], 503);
    }
});

Step 3: Monitor Laravel Horizon Queue Workers

Laravel Horizon powers ProcessMaker's async task processing — sending notifications, executing scheduled workflow triggers, and processing webhook deliveries. If Horizon stops, tasks accumulate in the queue unprocessed and workflows appear to stall.

Add a cron heartbeat that verifies Horizon is running and the queue depth is healthy:

1. In Vigilmon, click Add Monitor → Cron / Heartbeat.
2. Name: ProcessMaker Horizon Queue Worker
3. Set Expected interval to 2 minutes.
4. Copy the heartbeat URL.

Script:

#!/bin/bash
# /opt/processmaker/scripts/horizon-health-check.sh

cd /opt/processmaker

# Check Horizon status via artisan
HORIZON_STATUS=$(php artisan horizon:status 2>/dev/null | grep -i "running\|paused\|inactive")

if echo "$HORIZON_STATUS" | grep -qi "running"; then
  # Check queue depth — alert if more than 500 jobs pending
  QUEUE_DEPTH=$(php artisan queue:monitor default --max=500 2>/dev/null | grep -c "OK" || echo "0")

  curl -fsS "https://vigilmon.online/api/push/YOUR_HORIZON_TOKEN"
else
  echo "Horizon not running: $HORIZON_STATUS"
fi

* * * * * /opt/processmaker/scripts/horizon-health-check.sh

Alternatively, use the Horizon API endpoint directly if you have the dashboard enabled:

# Horizon exposes status via API
STATUS=$(curl -sf "http://localhost/horizon/api/stats" | jq -r '.status')
[ "$STATUS" = "running" ] && curl -fsS "https://vigilmon.online/api/push/YOUR_HORIZON_TOKEN"

Step 4: Monitor Redis Health

Redis backs Laravel Horizon's queue system in ProcessMaker. If Redis goes down, Horizon can't pick up jobs, which means task notifications stop, scheduled triggers don't fire, and webhooks aren't delivered.

1. Click Add Monitor → TCP Port.
2. Host: your-server-ip.
3. Port: 6379 (Redis default).
4. Check interval: 1 minute.
5. Click Save.

For a richer Redis check using the PING command:

#!/bin/bash
RESULT=$(redis-cli ping 2>/dev/null)
if [ "$RESULT" = "PONG" ]; then
  curl -fsS "https://vigilmon.online/api/push/YOUR_REDIS_TOKEN"
fi

Step 5: Monitor Active Case Count

An unusually low active case count during business hours may indicate that new process submissions are failing or that users are experiencing login issues. Monitor it via a database query heartbeat:

-- Active cases (running process instances) in ProcessMaker
SELECT COUNT(*) AS active_cases
FROM PROCESS_INSTANCES
WHERE STATUS = 'TO_DO'
   OR STATUS = 'DRAFT';

Script that pings Vigilmon when the case count is within expected bounds:

#!/bin/bash
# /opt/processmaker/scripts/case-count-check.sh

CASE_COUNT=$(mysql -u processmaker -p"$DB_PASSWORD" processmaker \
  -e "SELECT COUNT(*) FROM process_requests WHERE status IN ('ACTIVE', 'ERROR');" \
  --skip-column-names -s 2>/dev/null)

# Alert if more than 5000 active cases (possible runaway process trigger)
if [ -n "$CASE_COUNT" ] && [ "$CASE_COUNT" -lt 5000 ]; then
  curl -fsS "https://vigilmon.online/api/push/YOUR_CASE_COUNT_TOKEN"
fi

Step 6: Monitor Overdue Tasks

Overdue tasks represent SLA breaches in your business processes. ProcessMaker tracks task due dates — query for overdue counts and alert when they exceed your threshold:

-- Overdue tasks in ProcessMaker
SELECT COUNT(*) AS overdue_tasks
FROM TASK_USER
WHERE TASK_DUE_DATE < NOW()
  AND STATUS = 'ASSIGNED';

#!/bin/bash
OVERDUE=$(mysql -u processmaker -p"$DB_PASSWORD" processmaker \
  --skip-column-names -s \
  -e "SELECT COUNT(*) FROM process_request_tokens WHERE due_at < NOW() AND status = 'ACTIVE';" 2>/dev/null)

# Ping heartbeat only if overdue count is within SLA (e.g., <10 overdue)
if [ -n "$OVERDUE" ] && [ "$OVERDUE" -lt 10 ]; then
  curl -fsS "https://vigilmon.online/api/push/YOUR_OVERDUE_TOKEN"
fi

Step 7: Monitor Scheduled Process Triggers

ProcessMaker supports scheduled start events (time-based process triggers) that launch workflows automatically — daily report generation, weekly compliance checks, monthly invoice runs. A missed trigger means business processes don't start on schedule.

Add a Vigilmon heartbeat that your scheduled trigger pings after each successful execution:

1. Create a Cron / Heartbeat monitor named ProcessMaker Scheduled Triggers with an interval matching your most critical scheduled process (e.g., 25 hours for daily triggers).
2. Copy the heartbeat URL.

Add the Vigilmon ping to your ProcessMaker automation script or hook:

// In your custom ProcessMaker Script Task or PHP integration:
// After successful scheduled process launch:
file_get_contents('https://vigilmon.online/api/push/YOUR_TRIGGER_TOKEN');

Step 8: Monitor PHP-FPM Pool Utilization

PHP-FPM runs the ProcessMaker PHP application. When the pool is saturated (>90% of workers busy), new HTTP requests queue or reject — users see slow page loads or 502 errors from nginx.

#!/bin/bash
# /opt/processmaker/scripts/phpfpm-health-check.sh

# Get PHP-FPM status via status page (must be enabled in pool config)
FPM_STATUS=$(curl -sf "http://127.0.0.1/php-fpm-status?json" 2>/dev/null)

if [ -z "$FPM_STATUS" ]; then
  echo "PHP-FPM status page not reachable"
  exit 1
fi

ACTIVE=$(echo "$FPM_STATUS" | jq '.["active processes"]')
TOTAL=$(echo "$FPM_STATUS" | jq '.["total processes"]')

if [ "$TOTAL" -gt 0 ]; then
  UTILIZATION=$((ACTIVE * 100 / TOTAL))
  if [ "$UTILIZATION" -lt 90 ]; then
    curl -fsS "https://vigilmon.online/api/push/YOUR_PHPFPM_TOKEN"
  else
    echo "PHP-FPM pool at ${UTILIZATION}% — alert threshold exceeded"
  fi
fi

Enable the PHP-FPM status page in your pool config (/etc/php/8.x/fpm/pool.d/www.conf):

pm.status_path = /php-fpm-status

And add a restricted nginx location:

location /php-fpm-status {
    allow 127.0.0.1;
    deny all;
    fastcgi_pass unix:/run/php/php8.x-fpm.sock;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

Step 9: Configure Alerting

With monitors set up, configure alert escalation in Vigilmon:

1. Go to Alert Channels → Add Channel.
2. Add your primary ops channel (email, Slack, PagerDuty).
3. Add a business-process channel for BPM owners (Slack #bpm-ops or email to process managers).

Recommended alert thresholds:

| Monitor | Threshold | Channel | |---|---|---| | ProcessMaker HTTP | Any failure | Primary on-call | | MySQL TCP | Any failure | Primary on-call | | Redis TCP | Any failure | Primary on-call | | Horizon heartbeat miss | Heartbeat miss | DevOps | | PHP-FPM >90% | Heartbeat miss | DevOps | | Active cases anomaly | Heartbeat miss | BPM Ops | | Overdue tasks >10 | Heartbeat miss | Process Managers | | Scheduled triggers | Heartbeat miss | Process Managers |

Use 2-failure confirmation for active case count and overdue task monitors — these can fluctuate legitimately during off-hours. Use immediate for MySQL, Redis, and HTTP monitors.

Conclusion

ProcessMaker's PHP/Laravel/Horizon stack has multiple independent failure modes. The queue worker can stop while the web interface stays up. Redis can fail silently and kill all async processing. PHP-FPM can saturate during a workflow spike and make the app unresponsive. Scheduled triggers can silently miss their fire time. And overdue tasks can accumulate to SLA-breaching levels without any visible alarm.

The monitoring setup above covers every layer: user-facing availability (web app, form submissions), infrastructure health (MySQL, Redis, PHP-FPM), and business process integrity (active cases, task SLAs, scheduled triggers, queue worker). With Vigilmon running across all these monitors, you'll catch ProcessMaker failures before they cascade into missed deadlines and stalled approvals.