Summary
Add a Code Link feature that bridges BPMN process diagrams and their source code implementations. When a developer hovers over a service task in the diagram, a clickable overlay appears that navigates directly to the implementing source file in the editor.
Motivation
Developers working with BPMN processes frequently need to jump between the process diagram and the source code that implements each task. Currently this requires manually searching for the class name or topic in the workspace. Code Link eliminates this friction by automatically resolving implementation references and providing one-click navigation.
Supported Implementation Types
The feature supports both Camunda 7 and Camunda 8 across serviceTask, sendTask, and businessRuleTask elements:
| Engine |
XML Pattern |
Kind |
Example |
| C7 |
camunda:class |
Java Class |
com.example.MyDelegate |
| C7 |
camunda:delegateExpression |
Delegate Expression |
${myBean} |
| C7 |
camunda:expression |
Expression |
${svc.run()} |
| C7 |
camunda:type="external" + camunda:topic |
External Task |
payment-topic |
| C8 |
<zeebe:taskDefinition type="..."/> |
Job Type |
payment-service |
How It Works
1. Resolution (on every BPMN sync)
- Parse BPMN XML and extract implementation references from all supported task types
- Resolve each reference to a workspace file path using type-specific strategies:
- Java Class — FQCN converted to glob pattern (e.g.
com.example.Foo → **/com/example/Foo.{java,kt,groovy,scala})
- Delegate/Expression — Bean name extracted, capitalized, searched as class name; falls back to content search
- External Task / Job Type — Content-based search across workspace files for the string literal
- Send resulting lookup map (
activityId → {label, resolved}) to the webview
2. Navigation (on user click)
- Webview renders a clickable overlay on hover
- Click sends
NavigateToImplementationCommand(activityId) to the extension host
- Extension host looks up the resolved file path and opens it in the editor
3. Persistence
- The in-memory map is persisted as a JSON file at
<configFolder>/implementation-map/<bpmnFileName>.json (debounced at 2s)
- Enables external tooling (AI agents, custom skills) to understand process-to-code mappings without running the extension
- On editor open, existing persisted map is loaded as warm cache to avoid cold-start re-resolution
4. File System Watching
- Watchers on directories containing resolved files keep overlays in sync when files are created, renamed, or deleted
Architecture
Follows the existing layered architecture:
- Domain (
implementation.ts, persistedMap.ts) — Pure value types and builders
- Service (
ImplementationMapService.ts) — Orchestrates parsing, resolution, watching, persistence, and webview communication
- Infrastructure (
VsCodeFileResolver.ts, VsCodeMapPersistence.ts) — VS Code API adapters
- Parser (
bpmnXmlParser.ts) — Pure XML extraction functions
- Webview module (
libs/implementation-link/) — diagram-js injectable service for hover overlays
Message Protocol
| Message |
Direction |
Payload |
ImplementationMapQuery |
Extension → Webview |
Record<activityId, {label, resolved}> |
NavigateToImplementationCommand |
Webview → Extension |
activityId |
The webview only receives the display label and resolution status — file paths stay on the extension host side.
Open Items
References
- Detailed design:
docs/code-link.md
Summary
Add a Code Link feature that bridges BPMN process diagrams and their source code implementations. When a developer hovers over a service task in the diagram, a clickable overlay appears that navigates directly to the implementing source file in the editor.
Motivation
Developers working with BPMN processes frequently need to jump between the process diagram and the source code that implements each task. Currently this requires manually searching for the class name or topic in the workspace. Code Link eliminates this friction by automatically resolving implementation references and providing one-click navigation.
Supported Implementation Types
The feature supports both Camunda 7 and Camunda 8 across
serviceTask,sendTask, andbusinessRuleTaskelements:camunda:classcom.example.MyDelegatecamunda:delegateExpression${myBean}camunda:expression${svc.run()}camunda:type="external"+camunda:topicpayment-topic<zeebe:taskDefinition type="..."/>payment-serviceHow It Works
1. Resolution (on every BPMN sync)
com.example.Foo→**/com/example/Foo.{java,kt,groovy,scala})activityId → {label, resolved}) to the webview2. Navigation (on user click)
NavigateToImplementationCommand(activityId)to the extension host3. Persistence
<configFolder>/implementation-map/<bpmnFileName>.json(debounced at 2s)4. File System Watching
Architecture
Follows the existing layered architecture:
implementation.ts,persistedMap.ts) — Pure value types and buildersImplementationMapService.ts) — Orchestrates parsing, resolution, watching, persistence, and webview communicationVsCodeFileResolver.ts,VsCodeMapPersistence.ts) — VS Code API adaptersbpmnXmlParser.ts) — Pure XML extraction functionslibs/implementation-link/) — diagram-js injectable service for hover overlaysMessage Protocol
ImplementationMapQueryRecord<activityId, {label, resolved}>NavigateToImplementationCommandactivityIdThe webview only receives the display label and resolution status — file paths stay on the extension host side.
Open Items
References
docs/code-link.md