Guide / Share and move
Refactoring across the project
Rename a variable, message, job type, decision or process in the diagrams, forms, templates, config, tests and code at once, with a preview of every edit first.
What it does
A name often lives in many places: a message in two diagrams and a worker, a job type in a diagram, a template and the code. Refactoring changes all of them in one step. It always shows the plan first, and it applies exactly the plan it showed.
Rename
penstock refactor rename <kind> <old> <new>
The kind is one of: variable, message, signal, error, escalation, job-type, topic, decision, form, process. The last one is the process id, which is the called element of a call activity. The rename covers the BPMN, DMN and form files, the element templates, the application yaml and properties, the test cases and the code.
The command prints every edit with its file, line and before and after. It also prints every place it refuses to touch, and why: a script, a computed name, a filter or binding that hides the variable, an expression that does not parse, a link, a file outside the project, a file too large.
| Option | What it does |
|---|---|
| (none) | A preview only. Nothing is written. |
--apply | Writes the plan it has just shown. |
--force | Allows applying when the git tree has uncommitted changes. Without it the command refuses. |
--acknowledge | Allows applying when refused places remain. Without it the command refuses. |
--format json | Prints the same plan for a pipeline. |
It also refuses when the new name already exists or is not a valid name for that kind.
Everything or nothing
--apply writes only the plan it has just shown. Every file is written whole and atomically, and only when it still reads as it did. If a write fails, all the files are put back. It follows no link and edits nothing outside the project root.
A single rename is free, with no time limit.
Bulk renames
Pro Team in a pipeline
penstock refactor bulk <mapping-file>
The mapping file is JSON with a renames list of kind, from and to, or lines of kind,old,new. The renames are applied in order, each on the result of the one before, with one plan and one atomic write.
Extract a subprocess
Pro Team in a pipeline
penstock refactor extract <file.bpmn> <ids> <new-process-id>
It moves one embedded subprocess, or a group of elements with exactly one way in and one way out, into a new process file next to the diagram, and puts a call activity in its place. The call is wired through variable mappings: zeebe:ioMapping on Camunda 8, camunda:in and camunda:out on Camunda 7. The drawing is moved, and the messages, signals, errors and escalations it references are copied.
It refuses, with the reason: a selection with several entries or exits, a condition on the way out, a boundary event without its task, compensation, a link event, a data object, a message flow or association across the edge, an expression it cannot read, a variable read by a computed name, a name that is already taken, and any result that would be less valid than the diagram was.
In the editors
Refactor… is in the More menu and the command palette of the BPMN, DMN and form editors in Penstock Web and Desktop. The plugins reach it through the same web editor. The dialog takes the kind, the old and the new name, or a list of renames, or a diagram, element ids and a new process id. It previews every edit by file and line and every place left alone, asks you to acknowledge the refused places, offers a way to apply over a dirty git tree, and then writes.
For an AI agent
The MCP tool refactor_rename is free. refactor_bulk and refactor_extract are Pro. Without apply they return the plan, and applying needs the planId of that preview, so an agent cannot write what it has not shown. They stay inside the project root of the client. See The MCP server.
Common problems
- It refuses because the git tree has changes.
- Commit or stash them, so the rename is one clean commit, or pass
--force. - It lists places it will not touch.
- Check each one by hand, then pass
--acknowledgeto apply the rest.