Journey Monitoring API¶

The Journey Monitoring API provides endpoints for tracing end-to-end business journeys and analyzing common execution patterns.

Base Path: /journey

Required Permission: journey_analysis_data

Endpoints¶

Trace Business Journey¶

This is the primary endpoint for tracing a complete business journey. It recursively discovers all related process instances based on a business key or a starting instance ID.

GET /api/trace

Query Parameters:

Parameter	Type	Required	Description
`instance_id`	string	Either	A process instance ID that is part of the journey
`business_key`	string	Either	The business key that links the journey's process instances

Note

You must provide either instance_id or business_key, but not both.

Response: 200 OK

A JSON object containing the full journey structure and related metadata.

{
  "journey_tree": {
    "instance_id": "root-instance-123",
    "process_key": "order-process",
    "process_name": "Order Fulfillment",
    "start_time": "2025-10-28T09:00:00Z",
    "end_time": "2025-10-28T09:30:00Z",
    "duration_ms": 1800000,
    "state": "COMPLETED",
    "business_key": "ORD-123",
    "children": [
      {
        "calling_activity_id": "CallPaymentActivity",
        "call_time": "2025-10-28T09:05:00Z",
        "wait_time_ms": 500,
        "journey_node": {
          "instance_id": "child-instance-456",
          "process_key": "payment-process",
          "process_name": "Payment Processing",
          "start_time": "2025-10-28T09:05:00.5Z",
          "end_time": "2025-10-28T09:07:00Z",
          "duration_ms": 119500,
          "state": "COMPLETED",
          "children": []
        }
      }
    ]
  },
  "metadata": {
    "total_roots": 1,
    "total_instances": 3,
    "business_key_search": "ORD-123",
    "total_events": 150,
    "has_incidents": true,
    "is_active": false,
    "total_duration_ms": 1800000,
    "unique_processes": ["order-process", "payment-process", "shipping-process"]
  },
  "incidents": [
    {
      "proc_inst_id_": "child-instance-456",
      "incident_type_": "failedJob",
      "activity_id_": "ChargeCreditCard",
      "incident_msg_": "Connection timed out",
      "create_time_": "2025-10-28T09:06:00Z"
    }
  ],
  "timeline": [
    {
      "timestamp": "2025-10-28T09:00:00Z",
      "event_type": "process_start",
      "instance_id": "root-instance-123",
      "process_key": "order-process"
    },
    {
      "timestamp": "2025-10-28T09:05:00Z",
      "event_type": "call_activity",
      "instance_id": "root-instance-123",
      "target_instance_id": "child-instance-456",
      "activity_id": "CallPaymentActivity"
    }
  ]
}

Response Fields:

Field	Type	Description
`journey_tree`	object	Recursive tree structure of the journey
`journey_tree.instance_id`	string	Process instance ID
`journey_tree.process_key`	string	Process definition key
`journey_tree.duration_ms`	integer	Process execution duration in milliseconds
`journey_tree.children`	array	Child process calls
`children[].wait_time_ms`	integer	Time between parent task end and child process start
`metadata.total_instances`	integer	Total number of process instances in the journey
`metadata.has_incidents`	boolean	Whether any incidents occurred in the journey
`incidents`	array	Consolidated list of all incidents in the journey
`timeline`	array	Chronological list of major events

Analyze Journey Patterns¶

Analyze completed instances of a process to discover the most common end-to-end journey patterns.

GET /api/patterns

Query Parameters:

Parameter	Type	Required	Description
`process_key`	string	Yes	The root process key to analyze patterns for
`version`	integer	No	Optional specific version to analyze
`limit`	integer	No	Maximum number of patterns to return (default: 10)
`min_count`	integer	No	Minimum pattern occurrence count (default: 2)

Response: 200 OK

{
  "process_key": "order-process",
  "version": null,
  "total_instances": 150,
  "analysis_period": {
    "start": "2025-09-28T00:00:00Z",
    "end": "2025-10-28T23:59:59Z"
  },
  "patterns": [
    {
      "pattern": "order-process → payment-process → shipping-process",
      "count": 120,
      "percentage": 80.0,
      "total_duration": {
        "avg": 1800000,
        "min": 900000,
        "max": 3600000,
        "p50": 1750000,
        "p95": 3200000
      },
      "step_metrics": {
        "order-process": {
          "avg": 600000,
          "p95": 1200000
        },
        "payment-process": {
          "avg": 120000,
          "p95": 250000
        },
        "shipping-process": {
          "avg": 1080000,
          "p95": 2000000
        }
      },
      "wait_metrics": {
        "order-process → payment-process": {
          "avg": 500,
          "p95": 2000
        },
        "payment-process → shipping-process": {
          "avg": 300,
          "p95": 1500
        }
      },
      "example_instances": ["root-instance-123", "root-instance-456"]
    },
    {
      "pattern": "order-process → manual-approval → payment-process → shipping-process",
      "count": 30,
      "percentage": 20.0,
      "total_duration": {
        "avg": 86400000,
        "min": 43200000,
        "max": 172800000,
        "p50": 82800000,
        "p95": 165000000
      },
      "step_metrics": {
        "order-process": {
          "avg": 600000,
          "p95": 1200000
        },
        "manual-approval": {
          "avg": 82800000,
          "p95": 160000000
        },
        "payment-process": {
          "avg": 120000,
          "p95": 250000
        },
        "shipping-process": {
          "avg": 2880000,
          "p95": 5000000
        }
      },
      "wait_metrics": {
        "order-process → manual-approval": {
          "avg": 1000,
          "p95": 3000
        }
      },
      "example_instances": ["root-instance-789"]
    }
  ]
}

Response Fields:

Field	Type	Description
`patterns[].pattern`	string	Signature representing the process sequence
`patterns[].count`	integer	Number of instances following this pattern
`patterns[].percentage`	float	Percentage of total instances
`patterns[].total_duration`	object	End-to-end journey duration statistics
`patterns[].step_metrics`	object	Average duration per process in the pattern
`patterns[].wait_metrics`	object	Average wait time between processes
`patterns[].example_instances`	array	Sample instance IDs following this pattern

Usage Examples¶

Trace Journey by Business Key (cURL)¶

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://champa.example.com/journey/api/trace?business_key=ORD-123"

Trace Journey by Instance ID (Python)¶

import requests

API_TOKEN = "your_api_token"
BASE_URL = "https://champa.example.com"

headers = {
    "Authorization": f"Bearer {API_TOKEN}"
}

response = requests.get(
    f"{BASE_URL}/journey/api/trace",
    headers=headers,
    params={"instance_id": "root-instance-123"}
)

journey = response.json()
print(f"Total instances: {journey['metadata']['total_instances']}")
print(f"Has incidents: {journey['metadata']['has_incidents']}")

Analyze Patterns (JavaScript)¶

const API_TOKEN = 'your_api_token';
const BASE_URL = 'https://champa.example.com';

async function analyzePatterns(processKey) {
  const response = await fetch(
    `${BASE_URL}/journey/api/patterns?process_key=${processKey}`,
    {
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`
      }
    }
  );

  const data = await response.json();

  console.log(`Found ${data.patterns.length} patterns`);
  data.patterns.forEach(pattern => {
    console.log(`${pattern.pattern}: ${pattern.percentage}%`);
  });

  return data;
}

Error Responses¶

400 Bad Request¶

Invalid request parameters:

{
  "error": "Invalid request",
  "message": "Either instance_id or business_key must be provided, but not both"
}

404 Not Found¶

No journey found:

{
  "error": "Journey not found",
  "message": "No process instances found with business key 'ORD-123'"
}

401 Unauthorized¶

{
  "error": "Authentication required",
  "message": "Valid API token or session required"
}

403 Forbidden¶

{
  "error": "Permission denied",
  "message": "journey_analysis_data permission required"
}

Understanding Journey Metrics¶

Wait Time¶

wait_time_ms represents the latency between when a parent process completes a call activity task and when the child process actually starts. This can indicate:

Message queue delays
System resource constraints
Network latency
Database transaction overhead

Example:

Parent Task End: 09:05:00.000
Child Start:     09:05:00.500
Wait Time:       500ms

Duration Metrics¶

All duration metrics include standard statistical measures:

avg: Mean duration
min: Minimum observed duration
max: Maximum observed duration
p50: Median (50th percentile)
p95: 95th percentile (useful for SLA analysis)

Pattern Signatures¶

Pattern signatures use the arrow notation (→) to show the sequence of process calls:

order-process → payment-process → shipping-process

This indicates the order process calls the payment process, which then calls the shipping process.

Best Practices¶

Journey Tracing¶

Use Business Keys: Always set meaningful business keys on your root process instances to enable easy journey tracing.
Handle Active Journeys: Active (running) journeys will have incomplete data. Check metadata.is_active to determine if the journey is complete.
Incident Analysis: Always review the incidents array to understand failures in the journey context.

Pattern Analysis¶

Sample Size: Ensure you have at least 50-100 completed instances for meaningful pattern analysis.
Version Specificity: Use the version parameter to analyze patterns for specific process versions after deployments.
Performance Trending: Run pattern analysis weekly or monthly to track performance changes over time.
Outlier Investigation: Use the example_instances from patterns to investigate specific cases.