Process Analysis API

Process Analysis API

The Process Analysis API provides detailed activity-level metrics, bottleneck detection, outlier identification, and duration analysis for individual process definitions.

Base Path: /process-analysis

Endpoints

GET /process-analysis/activity

Returns activity-level statistics for a process.

Purpose: Get execution statistics for each activity in a process, including average duration, execution count, min/max durations.

Parameters:

Parameter Type Required Description
processKey string Yes Process definition key
version string Yes Process version
startDate string No Start date (ISO 8601)
endDate string No End date (ISO 8601)

Response Example:

{
  "successFullInstances": 1205,
  "averageInstanceDuration": 3600000,
  "activityInstances": [
    {
      "activityId": "Task_1",
      "activityCount": 1205,
      "minDuration": 120000,
      "maxDuration": 1200000,
      "averageDuration": 300000
    },
    {
      "activityId": "Task_2",
      "activityCount": 1205,
      "minDuration": 60000,
      "maxDuration": 600000,
      "averageDuration": 150000
    }
  ]
}

Response Fields:

Field Type Description
successFullInstances int Number of successful process instances
averageInstanceDuration long Average process instance duration (ms)
activityInstances array List of activity statistics
activityInstances[].activityId string BPMN activity identifier
activityInstances[].activityCount int Number of times activity executed
activityInstances[].minDuration long Minimum duration (ms)
activityInstances[].maxDuration long Maximum duration (ms)
activityInstances[].averageDuration long Average duration (ms)

GET /process-analysis/activity-duration

Returns duration between two specific activities.

Purpose: Calculate the average time elapsed between a start activity and an end activity within process instances.

Parameters:

Parameter Type Required Description
processKey string Yes Process definition key
version string Yes Process version
startActivityId string Yes Start activity BPMN ID
endActivityId string Yes End activity BPMN ID
startDate string No Start date (ISO 8601)
endDate string No End date (ISO 8601)

Response Example:

{
  "startActivityId": "Task_1",
  "endActivityId": "Task_5",
  "averageDuration": 2100000
}

Response Fields:

Field Type Description
startActivityId string Start activity identifier
endActivityId string End activity identifier
averageDuration long Average duration between activities (ms)

GET /process-analysis/outliers

Returns outlier process instances based on duration thresholds.

Purpose: Identify process instances that took significantly longer or shorter than normal, useful for finding problem instances.

Parameters:

Parameter Type Required Description
processKey string Yes Process definition key
version string Yes Process version
lowerThresholdIqr long Yes Lower threshold for outliers (ms)
upperThresholdIqr long Yes Upper threshold for outliers (ms)
minResults int Yes Minimum number of results to return
maxResults int Yes Maximum number of results to return
startDate string No Start date (ISO 8601)
endDate string No End date (ISO 8601)

Response Example:

[
  {
    "procInstId": "pi-12345",
    "startTime": 1704067200000,
    "procDuration": 7200000,
    "diffFromMean": 3600000,
    "longestActivity": "Task_3",
    "activityDuration": 3000000
  },
  {
    "procInstId": "pi-12346",
    "startTime": 1704070800000,
    "procDuration": 9000000,
    "diffFromMean": 5400000,
    "longestActivity": "Task_2",
    "activityDuration": 4500000
  }
]

Response Fields:

Field Type Description
procInstId string Process instance ID
startTime long Instance start time (ms, Unix epoch)
procDuration long Total process duration (ms)
diffFromMean long Difference from mean duration (ms)
longestActivity string Activity with longest duration
activityDuration long Duration of longest activity (ms)

GET /process-analysis/duration

Returns duration distribution for process instances.

Purpose: Get histogram-style data showing the distribution of process instance durations.

Parameters:

Parameter Type Required Description
processKey string Yes Process definition key
version string Yes Process version
startDate string No Start date (ISO 8601)
endDate string No End date (ISO 8601)

Response Example:

[
  {
    "date": 1800000,
    "totalInstances": 120
  },
  {
    "date": 3600000,
    "totalInstances": 850
  },
  {
    "date": 5400000,
    "totalInstances": 200
  },
  {
    "date": 7200000,
    "totalInstances": 35
  }
]

Response Fields:

Field Type Description
date long Duration bucket (ms)
totalInstances int Number of instances in this duration range

GET /process-analysis/thresholds

Returns calculated threshold values for outlier detection.

Purpose: Get the lower and upper threshold values based on statistical analysis (typically using IQR method).

Parameters:

Parameter Type Required Description
processKey string Yes Process definition key
version string Yes Process version
startDate string No Start date (ISO 8601)
endDate string No End date (ISO 8601)

Response Example:

{
  "lowerThreshold": 1200000,
  "upperThreshold": 5400000
}

Response Fields:

Field Type Description
lowerThreshold long Lower duration threshold (ms)
upperThreshold long Upper duration threshold (ms)

GET /process-analysis/version-duration

Returns duration statistics grouped by process version.

Purpose: Compare performance across different versions of the same process.

Parameters:

Parameter Type Required Description
processKey string Yes Process definition key
startDate string No Start date (ISO 8601)
endDate string No End date (ISO 8601)

Response Example:

[
  {
    "version": 1,
    "avgDurationMs": 3600000,
    "minDurationMs": 1200000,
    "maxDurationMs": 7200000,
    "totalInstances": 500
  },
  {
    "version": 2,
    "avgDurationMs": 3000000,
    "minDurationMs": 1000000,
    "maxDurationMs": 6000000,
    "totalInstances": 705
  }
]

Response Fields:

Field Type Description
version int Process version number
avgDurationMs long Average duration (ms)
minDurationMs long Minimum duration (ms)
maxDurationMs long Maximum duration (ms)
totalInstances int Total instances for this version

Usage Examples

Get Activity Statistics

curl -X GET "http://localhost:8899/process-analysis/activity?processKey=invoice-process&version=1"

Get Duration Between Activities

curl -X GET "http://localhost:8899/process-analysis/activity-duration?processKey=invoice-process&version=1&startActivityId=Task_1&endActivityId=Task_5"

Get Outliers

curl -X GET "http://localhost:8899/process-analysis/outliers?processKey=invoice-process&version=1&lowerThresholdIqr=1000000&upperThresholdIqr=5000000&minResults=5&maxResults=50"

Get Duration Distribution

curl -X GET "http://localhost:8899/process-analysis/duration?processKey=invoice-process&version=1&startDate=2025-01-01T00:00:00Z&endDate=2025-01-31T23:59:59Z"

Get Version Comparison

curl -X GET "http://localhost:8899/process-analysis/version-duration?processKey=invoice-process&startDate=2025-01-01T00:00:00Z&endDate=2025-01-31T23:59:59Z"

Notes

  • All duration values are in milliseconds
  • The processKey and version parameters are required for most endpoints
  • Thresholds are typically calculated using the IQR (Interquartile Range) method
  • Activity IDs correspond to BPMN element IDs in the process definition
  • Returns empty array or null if no matching process is found

On this Page: