Use case: Purge process instances selected by incidents

[grafvonb]

Use case: Purge process instances selected by incidents

Status

• Implemented
• Implemented command: c8volt ops purge process-instances-with-incidents

Proposed command

c8volt ops purge process-instances-with-incidents [flags]

Aliases:

c8volt ops purge pi-with-incidents [flags]
c8volt ops purge piwi [flags]

Operator goal

• Delete process-instance families selected from incident criteria.
• Discover candidate incidents, freeze candidate process-instance keys, reuse existing process-instance delete planning, and report exactly what was selected, skipped, planned, and deleted.

When to use

• Environment / prerequisite: configured Camunda profile, reachable Camunda cluster, incident service and process-instance service available
• Trigger: cleanup of failed test data, incident-driven maintenance, deleting process-instance families affected by known incident types
• User role / audience: Camunda operators, support engineers, maintainers, CI cleanup automation

Manual workflow today

c8volt get incident <incident-filters> --pi-keys-only
c8volt delete pi -

Desired high-level workflow

1. Search or fetch candidate incidents using incident filters.
2. Extract process-instance keys from matching incidents.
3. Skip incidents that do not provide a process-instance key.
4. Deduplicate candidate process-instance keys.
5. Freeze the candidate process-instance set.
6. Build the shared process-instance delete plan.
7. Resolve roots, affected family keys, duplicate roots, final-state items, non-final blockers, and missing ancestors.
8. If --dry-run is supplied, report the plan and mutate nothing.
9. If non-final affected instances exist, refuse mutation unless --force is supplied.
10. Confirm interactively, or proceed through --auto-confirm / --automation.
11. Delete resolved root process-instance trees through the existing delete service.
12. Write an audit report when requested.

Inputs and filters

• Required inputs: none beyond active profile/config
• Optional incident selectors: --key, --state, --error-type, --error-message, --bpmn-process-id, --pd-key, --pi-key, --root-key, --flow-node-id, --fni-key, --creation-time-after, --creation-time-before
• Count / limit / batch / worker controls: --batch-size, --limit, --workers, --no-worker-limit, --fail-fast
• Execution controls: --dry-run, --force, --no-wait, --auto-confirm, --automation, --json
• Report controls: --report-file, --report-format markdown|json
• Tenant/profile/config considerations: use active --config, --profile, and --tenant behavior consistently with existing commands

Guardrails

• Dry run expectations: discover candidate incidents, extract candidate process-instance keys, run delete planning, and mutate nothing
• Report expectations: support --report-file and --report-format markdown|json
• Confirmation behavior: prompt before deletion unless implicitly confirmed
• --auto-confirm behavior: allows deletion without prompts
• --automation --json behavior: deterministic JSON stdout; logs/progress on stderr or suppressed according to existing patterns
• Force behavior: non-final affected process instances block deletion unless --force is supplied
• Sensitive data handling: reports should include incident/process-instance operational metadata, not unrelated variables or sensitive config details

Success criteria

• Candidate incidents are discovered from supplied filters.
• Candidate process-instance keys are extracted and deduplicated.
• Duplicate incidents for the same process instance do not cause duplicate deletion submissions.
• Incidents missing process-instance keys are skipped and reported.
• Delete planning resolves roots and affected family scope.
• Dry run reports the exact planned scope without mutation.
• Real execution deletes resolved roots only after confirmation or automation.
• Final outcome is reported.

Failure behavior

• Fail before mutation for invalid incident state, invalid key flags, invalid date filters, invalid --batch-size, invalid --limit, or invalid --workers.
• If no incidents match, submit no delete request and report planned/no changes.
• If non-final affected process instances are in scope and --force is not supplied, fail before mutation.
• Report failed or partial deletion if the lower-level process-instance deletion service fails after submission.
• Preserve existing report files unless the run is already confirmed for mutation.

Output and report shape

• Human output should show: selection filters, candidate incident count, candidate process-instance count, duplicate candidate count, skipped incident count, delete-plan scope, non-final blockers, deletion status, final outcome
• JSON output should include: structured discovery, delete plan, deletion result, notices, errors, and outcome
• Audit report should include: timestamps, dry-run flag, c8volt version, Camunda version, tenant, profile identity, incident filters, incident keys, candidate process-instance keys, duplicate candidates, skipped incidents, resolved root keys, affected keys, missing ancestors, non-final affected items, deletion items, flags, notices, errors, final outcome

Open questions

Notes / gotchas

• --key means incident key, not process-instance key.
• The command defaults to --state active.
• Matching an incident is only the discovery step; deletion still operates on the resolved process-instance family scope.
• The workflow should reuse existing services and command facades, not shell out to c8volt commands.