Penstock

Guide / Test and run

Debug a process

Debug runs a copy of the open process on a local or test engine, stops at the breakpoints you set on the canvas, and lets you read and change the variables before it goes on. The copy and its instances are removed when the session ends.

Pro An engine on this machine, or one marked deployment.forTests: true

What it is

A breakpoint on the diagram, as in a debugger for code: the process runs, stops before the step you marked, shows you the variables, and waits. You change a value if you want, then continue, or step to the next element. It works on Camunda 7, Camunda 8, Operaton and CIB seven.

It is not the other tools that look similar:

Real work

The copy runs the real tasks of your process. A worker or a delegate on the engine that picks up one of its jobs does real work. So use an engine you can break.

Before you begin

  1. Connect an engine. Debug uses the engine of the profile in force. See Engines.
  2. The engine has to be one Penstock may run tests on: deployment.forTests: true in penstock.yaml, or an engine on this machine that you confirm once. Every other engine is refused. See Security and privacy.
  3. Without an engine, the Debug tab says No engine to debug on. and offers Set up connection….

Set breakpoints

  1. Select a step.
  2. Press Toggle breakpoint on selection in the Debug tab, or choose Toggle breakpoint in the More menu. A dot appears on the corner of the step.
  3. To remove one, click its dot, or press Remove in the list of breakpoints in the Debug tab. A click on a row of the list selects the step.

A breakpoint can sit on a task, a sub-process, a transaction, a call activity, a gateway and an intermediate catch or throw event. A start event, an end event and a boundary event cannot have one. Breakpoints are kept for the file, so they are there when you open it again. A breakpoint on a step that is gone is dropped when you start.

Run it

  1. Open the Debug tab of the sidebar, or choose Debug process in the More menu.
  2. If the file has several processes, choose one under Process.
  3. Type the Start variables (JSON): an object such as {"amount": 5}. Leave {} to start with none.
  4. Press Start debugging to run to the first breakpoint, or Start and step to stop before the first step.
  5. If the engine is not marked for tests, Penstock asks Debug on this engine? first and says what it will do: deploy the copy as <process id>__debug, start an instance of it, and remove the copy when you stop. Press Debug.

The tab says what goes on: Deploying the copy, Running, Paused, Finished, Failed or Stopped, and the address of the engine.

When it stops

The tab says Paused at a breakpoint, or Paused by a step when you stepped, and names the step. The step on the canvas carries a Paused here badge, and the canvas scrolls to it, into a sub-process if that is where it is. A click on the name in the tab selects it.

VariablesEvery variable of the instance, as a name and a JSON value. Change a value, add a variable with Add variable, and the change is set before the process goes on. A value should be valid JSON, so text needs quotes.
ContinueRuns on to the next breakpoint, or to the end.
StepRuns to the next element and stops there.
StopEnds the session: the instance is cancelled and the copy is removed.

While the process runs, the tab counts Steps passed so far. When it reaches a task that something outside the debugger has to do, a worker, a timer, a message or a user task, it says Waiting for something outside the debugger and goes on when that happens. If the instance gets an incident the session ends with The instance has an incident and the reason.

The copy

The debug copy is a separate definition named <process id>__debug. Your deployed process is never touched, so what runs on the engine is not changed by a debug session. Penstock puts a small pause of its own in front of each step that has a breakpoint and answers it itself, so the pause is not a task for your workers. The copy starts at one plain start event: the other start events, the ones with a message, a timer or another trigger, are left out of the copy. If every start event has a trigger, the first loses its trigger.

When the session ends, Penstock cancels the instance and removes the copy, and the tab says The debug copy … was removed from the engine. If the engine cannot do it, the tab says The debug copy could not be removed, names what was left on the engine and why, and tries again when you open the tab or when you press Try again.

What you see

Common problems

"No engine to debug on."
The profile in force has no address, or the engine is neither on this machine nor marked deployment.forTests: true. See penstock.yaml.
The process does not stop.
The breakpoint is on a step the process does not reach, or on one that cannot have a breakpoint. Look at the dots on the canvas, or start with Start and step.
It stops at a task and says Waiting for something outside the debugger.
The task needs a worker, a timer, a message or a person, as it does when the process runs for real. Start the worker, or give the process what it waits for.
"The engine did not report the debug copy after deploying it."
The deployment did not arrive. Check the address and the user of the profile, then start again.
A debug copy is left on my engine.
Open the Debug tab. Penstock tries again to remove it, and Try again asks at once.