Skip to main content

GetProcessDefinitionByIdQuery

Overview​

Retrieves a single process definition by ID with complete details.

Purpose​

Gets comprehensive information about a specific process definition including BPMN XML, metadata, statistics, and configuration.

Command Type​

CB.Administration.Api.Commands.BPM.Process.GetProcessDefinitiionByIdQuery

Request​

{
  "cmd": "GetProcessDefinitiionByIdQuery",
  "data": {
    "id": 456,
    "includeXml": true,
    "includeStatistics": true
  }
}

Request Fields (data object)​

FieldTypeRequiredDefaultDescription
idlongYes-ID of process definition to retrieve
includeXmlbooleanNofalseInclude full BPMN XML in response
includeStatisticsbooleanNofalseInclude instance count statistics

Response​

{
  "isSuccessful": true,
  "statusCode": "00",
  "data": {
    "id": 456,
    "name": "Loan Approval Workflow",
    "description": "Multi-stage loan approval process with credit checks",
    "category": "Lending",
    "version": 2,
    "isActive": true,
    "createdDate": "2026-01-06T10:30:00Z",
    "updatedDate": "2026-01-10T15:45:00Z",
    "createdBy": "admin@bank.com",
    "updatedBy": "manager@bank.com",
    "triggerEvents": ["OnLoanCreation"],
    "contextLoaderType": "LoanApplicationContext",
    "schedulingEnabled": false,
    "bpmnXml": "<?xml version=\"1.0\"...>",
    "statistics": {
      "totalInstances": 150,
      "activeInstances": 12,
      "completedInstances": 135,
      "failedInstances": 3,
      "averageDurationMinutes": 180,
      "successRate": 0.98
    },
    "elementCounts": {
      "totalElements": 15,
      "startEvents": 1,
      "endEvents": 2,
      "userTasks": 5,
      "serviceTasks": 3,
      "scriptTasks": 2,
      "gateways": 2,
      "subprocesses": 0,
      "callActivities": 1
    },
    "metadata": {
      "version": "2.0",
      "author": "Process Team",
      "tags": ["lending", "approval", "automated"],
      "changelog": "Added automated fraud detection"
    }
  }
}

Response Fields​

Core Fields​

FieldTypeDescription
idlongUnique identifier
namestringProcess definition name
descriptionstringDetailed description
categorystringLogical category
versionintCurrent version number
isActivebooleanWhether process can be instantiated

Timestamps & Audit​

FieldTypeDescription
createdDatedatetimeWhen process was created
updatedDatedatetimeLast update timestamp
createdBystringUser who created the process
updatedBystringUser who last updated the process

Configuration​

FieldTypeDescription
triggerEventsarraySystem events that auto-start this process
contextLoaderTypestringType of context loader for variable initialization
schedulingEnabledbooleanWhether scheduled execution is configured
bpmnXmlstringFull BPMN 2.0 XML (only if includeXml=true)

Statistics (only if includeStatistics=true)​

FieldTypeDescription
totalInstancesintTotal process instances created
activeInstancesintCurrently running instances
completedInstancesintSuccessfully completed instances
failedInstancesintFailed instances
averageDurationMinutesintAverage completion time in minutes
successRatedecimalCompletion success rate (0-1)

Element Counts​

FieldTypeDescription
totalElementsintTotal BPMN elements
startEventsintNumber of start events
endEventsintNumber of end events
userTasksintNumber of user tasks
serviceTasksintNumber of service tasks
scriptTasksintNumber of script tasks
gatewaysintNumber of gateways (all types)
subprocessesintNumber of embedded subprocesses
callActivitiesintNumber of call activities

Error Responses​

Process Not Found​

{
  "isSuccessful": false,
  "message": "Process definition with ID 456 not found",
  "statusCode": "404"
}

Usage Scenarios​

1. View Process Details (Basic)​

{
  "id": 456
}

Use Case: Quick view of process information without heavy data.

2. Export Process Definition​

{
  "id": 456,
  "includeXml": true
}

Use Case: Backup, migration, or documentation generation.

3. Analyze Process Performance​

{
  "id": 456,
  "includeStatistics": true
}

Use Case: Performance monitoring, optimization decisions.

4. Complete Process Audit​

{
  "id": 456,
  "includeXml": true,
  "includeStatistics": true
}

Use Case: Comprehensive audit, troubleshooting, documentation.

Response Size Considerations​

Without Optional Fields​

  • Size: ~2-5 KB
  • Use For: UI display, quick lookups

With XML Only​

  • Size: ~10-50 KB (depends on BPMN complexity)
  • Use For: Export, backup, migration

With Statistics Only​

  • Size: ~3-7 KB
  • Use For: Dashboards, reporting

With Both XML & Statistics​

  • Size: ~15-60 KB
  • Use For: Complete documentation, deep analysis

Example: Process Health Check​

// Get process with statistics
const response = await getProcessDefinitionById({
  cmd: "GetProcessDefinitiionByIdQuery",
  data: {
    id: 456,
    includeStatistics: true
  }
});

const stats = response.data.statistics;

// Analyze health
if (stats.successRate < 0.90) {
  console.warn(`⚠️ Low success rate: ${stats.successRate * 100}%`);
}

if (stats.activeInstances > 50) {
  console.warn(`⚠️ High active instance count: ${stats.activeInstances}`);
}

if (stats.averageDurationMinutes > 300) {
  console.warn(`⚠️ Long average duration: ${stats.averageDurationMinutes} minutes`);
}

// Health check passed
console.log(`✅ Process ${response.data.name} is healthy`);

Example: Process Comparison​

// Compare two versions of a process
const v1 = await getProcessDefinitionById({
  cmd: "GetProcessDefinitiionByIdQuery",
  data: {
    id: 456, 
    includeXml: true,
    includeStatistics: true
  }
});

const v2 = await getProcessDefinitionById({
  cmd: "GetProcessDefinitiionByIdQuery",
  data: {
    id: 789,
    includeXml: true,
    includeStatistics: true
  }
});

console.log(`
Version Comparison:
------------------
V1 (${v1.data.version}):
  - Elements: ${v1.data.elementCounts.totalElements}
  - Avg Duration: ${v1.data.statistics.averageDurationMinutes} min
  - Success Rate: ${v1.data.statistics.successRate * 100}%

V2 (${v2.data.version}):
  - Elements: ${v2.data.elementCounts.totalElements}
  - Avg Duration: ${v2.data.statistics.averageDurationMinutes} min
  - Success Rate: ${v2.data.statistics.successRate * 100}%

Improvement: ${v1.data.statistics.averageDurationMinutes - v2.data.statistics.averageDurationMinutes} min faster
`);

Example: Export for Backup​

// Export process definition with full details
const backup = await getProcessDefinitionById({
  cmd: "GetProcessDefinitiionByIdQuery",
  data: {
    id: 456,
    includeXml: true
  }
});

// Save to file
const backupData = {
  exportDate: new Date().toISOString(),
  process: {
    name: backup.data.name,
    description: backup.data.description,
    category: backup.data.category,
    bpmnXml: backup.data.bpmnXml,
    triggerEvents: backup.data.triggerEvents,
    contextLoaderType: backup.data.contextLoaderType,
    metadata: backup.data.metadata
  }
};

fs.writeFileSync(
  `process_backup_${backup.data.id}_${Date.now()}.json`,
  JSON.stringify(backupData, null, 2)
);

console.log(`✅ Backed up process: ${backup.data.name}`);

Integration with Other Commands​

Pre-Update Check​

// Before updating, check current state
const current = await getProcessDefinitionById({
  id: 456,
  includeXml: true,
  includeStatistics: true
});

if (current.data.statistics.activeInstances > 0) {
  console.warn(`⚠️ ${current.data.statistics.activeInstances} active instances`);
  console.log('Consider waiting for completion or handle gracefully');
}

// Proceed with update
await updateProcessDefinition({
  id: 456,
  bpmnXml: newBpmnXml
});

Pre-Delete Validation​

// Check before deletion
const process = await getProcessDefinitionById({
  id: 456,
  includeStatistics: true
});

if (process.data.statistics.activeInstances > 0) {
  throw new Error(`Cannot delete: ${process.data.statistics.activeInstances} active instances`);
}

if (process.data.triggerEvents.length > 0) {
  console.warn(`⚠️ Process has trigger events: ${process.data.triggerEvents.join(', ')}`);
}

// Safe to delete
await deleteProcessDefinition({ id: 456 });

Best Practices​

✅ Do's​

  1. Use Minimal Fields for UI Display

    // Dashboard/list view
    { "id": 456 }  // No optional fields needed

  2. Include Statistics for Monitoring

    // Performance dashboard
    { "id": 456, "includeStatistics": true }

  3. Include XML for Export/Backup

    // Backup process
    { "id": 456, "includeXml": true }

  4. Cache Results Appropriately

    // Process definition changes infrequently
    // Cache for 5-10 minutes
    const cached = cache.get(`process_${id}`);
    if (!cached) {
      cached = await getProcessDefinitionById({ id });
      cache.set(`process_${id}`, cached, 600); // 10 min TTL
    }

  5. Check Active Status Before Starting Instances

    const process = await getProcessDefinitionById({ id: 456 });
    if (!process.data.isActive) {
      throw new Error('Process is not active');
    }

❌ Don'ts​

  1. Don't always include XML - Only when needed (large payload)
  2. Don't poll statistics frequently - Use for periodic reports only
  3. Don't fetch without checking cache - Avoid unnecessary database hits
  4. Don't ignore isActive flag - Check before starting instances

Performance Considerations​

Database Queries​

Fields RequestedQuery ComplexityResponse Time
Basic info onlySimple SELECT~10-20ms
+ XMLJoin + CLOB read~50-100ms
+ StatisticsComplex aggregation~100-200ms
+ BothMultiple queries~150-300ms

Caching Strategy​

// Recommended caching
const CACHE_TTL = {
  basicInfo: 600,      // 10 minutes (changes infrequently)
  withXml: 1800,       // 30 minutes (rarely changes)
  withStats: 60        // 1 minute (changes frequently)
};

Last Updated: January 6, 2026