Dashboard API¶

Comprehensive process intelligence analytics with lazy-loaded dashboard sections for optimal performance.

Overview¶

The Dashboard API provides deep-dive analytics for individual process definitions using an intelligent lazy-loading architecture. Instead of loading all data upfront, the dashboard shell renders instantly, and each analytical section is fetched on-demand as users interact with the interface.

Base Path: /dashboard

Required Permission: extended_dashboard_data

Lazy-Loading Architecture¶

The dashboard employs a two-phase loading strategy:

Phase 1 - Shell Load : Renders the empty dashboard UI with tabs and placeholders
Phase 2 - Section Load (on-demand): Fetches data only when user clicks a tab or scrolls to a section

This approach provides: * ⚡ Instant page load - Dashboard appears in <500ms * 🔧 Reduced server load - Only requested data is fetched * 📊 Better UX - Progressive data enhancement * 🎯 Targeted analytics - Users get exactly what they need

Endpoints¶

Get Dashboard Shell¶

Renders the dashboard UI shell with minimal overhead.

GET /dashboard/<process_key>/<v1>/<v2>

Path Parameters:

Parameter	Type	Required	Description
`process_key`	string	Yes	Process definition key
`v1`	integer	Yes	Primary version to analyze
`v2`	integer	Yes	Secondary version (use `0` for single version)

Response: HTML page with lazy-loading dashboard

Example:

# Single version analysis
GET /dashboard/order-to-cash/3/0

# Version comparison
GET /dashboard/order-to-cash/2/3

Get Dashboard Section¶

Fetch individual dashboard sections for lazy loading.

GET /api/dashboard/section/<section_name>

Query Parameters:

Parameter	Type	Required	Description
`process_key`	string	Yes	Process definition key
`v1`	integer	Yes	Primary version
`v2`	integer	Yes	Secondary version (0 for single)

Available Sections:

Section Name	Description
`overview-kpis`	High-level KPIs and health metrics
`incidents-analysis`	Open incidents and error patterns
`failed-jobs`	Dead-letter jobs analysis
`incident-correlation`	Variables correlated with incidents
`activity-hotspots`	Top 20 slowest activities
`performance-analytics`	Comprehensive performance data
`granular-performance`	Activity-level P50/P95/P99
`job-performance`	Async job execution metrics
`user-tasks`	User task analysis
`user-workload`	Assignee workload distribution
`user-task-funnel`	Task funnel conversion
`perf-metrics`	Advanced performance percentiles
`historical-data`	Historical trend analysis
`instance-trends`	Instance creation trends chart
`process-flow-heatmap`	Activity execution heatmap
`dmn-analytics`	DMN execution statistics
`variable-comparison`	Variable schema changes (v1 vs v2)
`impact-assessment`	Migration impact assessment
`variable-analytics`	Variable quality and security
`error-patterns`	Common error patterns
`deployment-info`	Deployment comparison
`interaction-map`	Cross-process dependencies
`health-scores`	Process health score calculation
`anomaly-detection`	Automated anomaly detection
`stuck-instances`	Long-running instance detection

Response Format:

{
  "timestamp": "2025-01-15T10:30:00.123456",
  "<section_data_key>": [...]
}

Example:

cURLPythonJavaScript

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:8088/api/dashboard/section/incidents-analysis?process_key=order-to-cash&v1=3&v2=0"

import requests

headers = {'Authorization': f'Bearer {token}'}
params = {
    'process_key': 'order-to-cash',
    'v1': 3,
    'v2': 0
}

response = requests.get(
    'http://localhost:8088/api/dashboard/section/incidents-analysis',
    headers=headers,
    params=params
)

data = response.json()
incidents = data['incidents']
print(f"Found {len(incidents)} incident types")

const params = new URLSearchParams({
  process_key: 'order-to-cash',
  v1: 3,
  v2: 0
});

const response = await fetch(
  `http://localhost:8088/api/dashboard/section/incidents-analysis?${params}`,
  {
    headers: { 'Authorization': `Bearer ${token}` }
  }
);

const data = await response.json();
console.log(`Found ${data.incidents.length} incident types`);

Get Experimental Analytics¶

Access experimental and advanced analytics features.

GET /api/dashboard/experimental/<analysis_type>

Query Parameters: Same as section endpoint

Available Analysis Types:

Type	Description
`api-patterns`	External API call patterns and performance
`script-performance`	Script task execution metrics
`listener-performance`	Execution listener performance
`form-analytics`	Form field usage statistics
`rework-detection`	Rework loop identification
`variant-analysis`	Process variant analysis
`bottlenecks`	Bottleneck detection algorithm
`concurrent-execution`	Concurrency analysis
`peak-load`	Peak load time identification
`incident-correlation`	Advanced incident correlation
`database-locks`	Database lock analysis
`cross-process-deps`	Cross-process call activities

Example:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:8088/api/dashboard/experimental/rework-detection?process_key=order-to-cash&v1=3&v2=0"

Response:

{
  "timestamp": "2025-01-15T10:30:00",
  "rework_detection": [
    {
      "activity_name": "Review Application",
      "rework_count": 45,
      "avg_rework_cycles": 2.3,
      "max_rework_cycles": 7,
      "affected_instances": 45
    }
  ]
}

Get Recommendations¶

Generate strategic recommendations based on process analytics.

GET /api/dashboard/section/recommendations

Query Parameters: Same as section endpoint

Response:

{
  "recommendations": [
    {
      "priority": "CRITICAL",
      "category": "Incidents",
      "message": "Resolve 15 open incidents before considering any major changes.",
      "action": "Review the Operations Command Center for details."
    },
    {
      "priority": "HIGH",
      "category": "Security",
      "message": "Review 3 variables containing potentially sensitive data (PII, Credit Cards/SSN).",
      "action": "Review the Quality & Compliance tab for details."
    }
  ],
  "timestamp": "2025-01-15T10:30:00"
}

Get Instance Trace¶

Trace a single process instance with complete execution history.

GET /api/dashboard/instance-trace/<proc_inst_id>

Response:

{
  "instance_id": "abc-123",
  "process_key": "order-to-cash",
  "version": 3,
  "parent_instance": null,
  "called_by_activity": null,
  "child_instances": [
    {
      "instance_id": "def-456",
      "process_key": "credit-check",
      "calling_activity": "Check Credit"
    }
  ]
}

Get Instance History¶

Get detailed execution history timeline for a process instance.

GET /api/instance-history/<instance_id>

Response:

{
  "instance_id": "abc-123",
  "events": [
    {
      "timestamp": "2025-01-15T10:00:00",
      "event_type": "Activity",
      "detail_1": "serviceTask",
      "detail_2": "Call Credit Service",
      "duration_ms": 1500
    },
    {
      "timestamp": "2025-01-15T10:00:02",
      "event_type": "Incident",
      "detail_1": "failedJob",
      "detail_2": "Connection timeout"
    }
  ]
}

Get Variable Details¶

Sample variable values for a specific variable across versions.

GET /api/variable-details

Query Parameters:

Parameter	Type	Required	Description
`process_key`	string	Yes	Process definition key
`variable_name`	string	Yes	Variable name to sample
`v1`	integer	Yes	Version 1
`v2`	integer	Yes	Version 2

Response:

{
  "v1_samples": [
    {"instance_id": "abc-123", "value": "EUR", "type": "string"},
    {"instance_id": "def-456", "value": "USD", "type": "string"}
  ],
  "v2_samples": [
    {"instance_id": "ghi-789", "value": "EUR", "type": "string"}
  ]
}

Get Error Pattern Instances¶

Get list of instance IDs affected by a specific error pattern.

GET /api/error-pattern-instances

Query Parameters:

Parameter	Type	Required
`process_key`	string	Yes
`version`	integer	Yes
`activity_id`	string	Yes
`incident_type`	string	Yes
`error_message`	string	No

Response:

[
  {
    "instance_id": "abc-123",
    "start_time": "2025-01-15T10:00:00",
    "incident_time": "2025-01-15T10:05:00",
    "error_message": "Connection timeout"
  }
]

Get Similar Error Patterns¶

Find similar error patterns using fuzzy matching.

GET /api/similar-error-patterns

Query Parameters:

Parameter	Type	Required
`process_key`	string	Yes
`version`	integer	No
`error_message`	string	Yes
`incident_type`	string	No

Response:

[
  {
    "process_key": "order-to-cash",
    "version": 2,
    "activity_id": "callCreditService",
    "incident_type": "failedJob",
    "error_message": "Connection timed out",
    "similarity_score": 0.95,
    "incident_count": 12
  }
]

Performance Considerations¶

Response Time Optimization¶

Use Lazy Loading: Load only what users view
Cache Section Data: Cache frequently accessed sections (5-min TTL)
Parallel Requests: Fetch multiple sections in parallel
Selective Depth: Use lighter sections first, heavier on-demand

Example: Optimized Dashboard Load¶

// Load critical sections first
const criticalSections = ['overview-kpis', 'incidents-analysis', 'health-scores'];
const deferredSections = ['granular-performance', 'dmn-analytics'];

// Load critical in parallel
await Promise.all(
  criticalSections.map(section => loadSection(section))
);

// Load deferred sections only when tab is clicked
tabElement.addEventListener('click', () => {
  if (!sections[tabName]) {
    loadSection(tabName);
  }
});

Error Handling¶

Common Errors¶

No Data Available:

{
  "incidents": [],
  "timestamp": "2025-01-15T10:30:00"
}

Invalid Version:

{
  "error": "Version not found for process key",
  "status_code": 404
}

Database Error:

{
  "error": "Failed to execute query",
  "status_code": 500
}

Best Practices¶

1. Implement Loading States¶

Show spinners while data loads:

<div x-show="loading.incidents">
  <div class="spinner">Loading incidents...</div>
</div>
<div x-show="!loading.incidents && sections.incidents">
  <!-- Display incident data -->
</div>

2. Handle Empty States¶

Gracefully handle processes with no data:

if (data.incidents.length === 0) {
  showEmptyState('No incidents found for this process');
}

3. Cache Strategically¶

Cache expensive sections locally:

const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function getCachedSection(sectionName, params) {
  const key = `${sectionName}:${JSON.stringify(params)}`;
  const cached = cache.get(key);

  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const data = await fetchSection(sectionName, params);
  cache.set(key, { data, timestamp: Date.now() });
  return data;
}

Next Steps¶

Portfolio API - Portfolio-level analytics
Health Monitoring API - Cluster health
AI Analysis API - AI-powered insights

Support¶

For dashboard API questions:

Email: info@champa-bpmn.com
Documentation: https://champa-bpmn.com/docs