Guide / Draw and edit

Editing a diagram

The window around the canvas: the toolbar, the palette, the sidebar, the XML one tab away, and every action that edits a diagram.

Free

What the editor is

Penstock draws your diagram with bpmn-js in a browser built into your tool. The modelling surface is the familiar one. What Penstock adds is the tool around it: a toolbar you arrange, a command palette over every action, a sidebar with tabs for the properties, scenarios, problems, comments, Monitor and code, and the raw XML never more than one click away.

Add an element

1. Drag an element from the palette beside the canvas and drop it where you want it.
2. Type to give it a name. Double-click the element to rename it later.
3. To connect it to another element, select the first one and drag from the arrow icon of the small pad beside it onto the second.

Or let Penstock add the next element for you: select an element and use the pad beside it. The pad appends the element you choose, already connected. Its Create element catalogue lists every element by what it is for. See BPMN elements.

Change an element into another

1. Select the element.
2. Press the wrench on its pad.
3. Pick what it should become. A task can become a service task, a start event a message start event, an exclusive gateway a parallel one.

The name, the connections and the properties that still apply are kept.

The tools at the top of the palette

The canvas and the palette

Which modeller is built depends on the engine profile: Camunda 7, Camunda 8, Operaton and CIB seven get the matching Camunda modeler, which carries that platform's own extensions, properties and element templates, and Classic BPMN gets plain bpmn-js with the standard ones. All of them load task resizing, token simulation and the minimap, the colour picker in the context pad, and the grid with snapping. See Engines.

The palette is a floating island beside the canvas, not a strip of the window: sixteen pixels from the left edge, vertically centred, rounded, and never more than three quarters of the height of the canvas, so a palette with more entries scrolls inside it. A canvas with a palette beside it is inset, so nothing sits under it, and a diagram is fitted into that inset when it opens.

A diagram opens fitted into the canvas at 100% at most, rather than cut off at the edge. Opening a panel over a fitted diagram fits it again, unless you have moved or zoomed it yourself. The Fit diagram action does it on demand, and it has a shortcut in every tool that has one. Switching your tool's theme keeps your zoom, your pan and your selection.

Undo and redo

Undo and Redo are the first two buttons on the toolbar. They step through every change in the order you made it, through the modeller's own command stack. While a token simulation runs they refuse to run, so a preview cannot change your file.

Copy and paste

Copy and paste use the clipboard of your system or tool, not a clipboard private to one diagram. So you can copy a pool from one diagram and paste it into another open diagram. Copy and Paste are in the More menu. Pasting from the toolbar has no mouse position, so the elements land in the middle of the view.

To get the diagram itself as a picture, use Copy in the export dialog. It is free. See Export.

Scripts and conditions

Under Camunda 7, Operaton and CIB seven, a field that holds a script is a small code editor with colours, and Edit in new tab opens it in a code editor of your tool as a real file. See Scripts in their own tab.

Transaction boundaries

Transaction boundaries, under View in the More menu, draws a bar wherever the engine commits a transaction. It is for Camunda 7, Operaton and CIB seven and is free. See Transaction boundaries.

The XML one tab away

The diagram editor is registered ahead of your tool's own editor rather than in place of it, so the plain XML editor stays available as a second tab on the same file, called Text. A diagram that cannot be read opens a screen of its own instead of an empty canvas: what the parser objected to and on which line, that the file was not changed, and buttons to open the XML in the Text tab at that line and to Reload.

Edits round-trip in both directions. Every change on the canvas re-serialises the diagram and writes the whole file: the content goes to a temporary file beside the target, which is moved over it atomically and refreshed, so the Text tab and version control see the new content at once and a folder that does not exist yet is created.

The other direction is watched rather than merged. Penstock tracks the file's modification stamp and ignores its own writes. When something else changes the file, the Text tab, a Git checkout or a formatter, the editor asks whether to reload. Reloading takes the external content and discards unsaved canvas edits; declining keeps you editing, and your next change overwrites the external one. Renames are handled silently.

Follow a path

Select a task, a gateway or an event and press the trace icon on its pad, or choose Trace paths in the More menu. Every path that runs through the step stays in colour and the rest of the diagram is dimmed. It lives on the canvas only: it adds nothing to the undo history and nothing to the file. See Trace paths.

Leave a note on an element

Select an element and open the Comments tab of the sidebar. A comment is kept in the file, inside the element, and a small number on the element's corner says how many are still open. See Comments.

Shortcuts

The Keyboard shortcuts action, or the ? key, opens the sheet of every shortcut the editor binds, with a search field. See The toolbar and the More menu.

Token simulation

Simulate switches the canvas into simulation mode: it is framed in green, every start event gains a play button, and the speed controls sit at the bottom. The button stays pressed until you switch it off. The simulation blocks dragging, the context pad, popup menus and direct editing, and Penstock blocks the rest: Undo, Redo, Copy, Paste, Delete and Auto layout refuse to run and say Stop Token Simulation before editing the diagram. Otherwise an edit made during what looks like a read-only preview would be written to the file like any other. Free. See Token simulation.

Export and the diagram diff

Export… opens a dialog with the whole diagram centred in the preview and the settings beside it, and copies the diagram to the clipboard as a picture. See Export. Penstock also registers a diff with your tool, so any two-sided comparison where one side is a BPMN file is shown as two diagrams rather than two blocks of XML. See Diagram diff.

The minimap

Open More and choose Minimap. A small overview of the whole diagram appears. It helps on large diagrams.

Right-click

The context menu of the canvas holds Reload, Undo, Redo, Copy, Paste, Delete and Export…. The context menu of an element holds the editing actions, the change-element menu, and, when they apply, an entry that goes to the code that runs the element, and the Pro actions that link to your code. See Code links.

Go to the class of a task

A task can name a Java class: a Camunda 7 camunda:class, a delegate expression that unwraps to a full class name, or a listener that names a class. Right-click it and the menu offers to go to that class. Penstock finds the class by name and package in your own sources. A delegate expression that holds a bean name, such as ${checkStockDelegate}, names no class, so nothing is offered. Pro's code links handle beans.

Hover

Rest the pointer on an element and a card shows its id, type, name and flows. On a service task it also shows the implementation. On a user task it shows the assignee and candidates.

What you see

• The new element is on the canvas, connected where you dropped it.
• Every change is already in the file.

Common problems

I cannot drag or delete anything.

Token simulation is on. Press Simulate again to stop it.

Paste does nothing.

Copy something first. Select one or more elements, open More and choose Copy.

The entry that goes to the class is missing.

The task names no class, or the class lives in a library instead of your own sources, or your tool has no source view.

The diagram opens cut off at the edge.

Press Fit diagram.

The file changed and my edits are gone.

Something outside the editor wrote the file while you were editing, and you chose to reload. Reloading takes the file on disk. See above.

I dropped an element in the wrong place.

Press Undo. Or, if you already did other things, drag it back.