>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3633763. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !733 >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>When a step fails for good, the workflow author has no say in what happens next. A fatal failure, or a retryable one that has used up its attempts, is handled in <code>WorkflowExecutor::handleAdvanceFailure()</code> by the site-wide <em>When a step fails for good</em> setting (<code>on_unrecoverable_failure</code>): the branch halts on an incident and waits for an operator, or the whole instance fails. The author cannot draw "if this step fails, notify the requester and close the request" in the model.</p> <p>Three task types already route their own failures, each with its own setting, but nothing does it for every step:</p> <ul> <li>The <code>action</code> task, given a <code>payload_variable</code>, catches a failing action and sets the variable to <code>failure</code>.</li> <li>The <code>subprocess</code> task, given a <code>state_variable</code>, resumes the parent when the child fails or is canceled, with <code>__subprocess_failed__</code> or <code>__subprocess_canceled__</code> in that variable.</li> <li>The payment <code>settle</code> task throws an <code>OutcomeException</code> with <code>declined</code> from its own code.</li> </ul> <p>Every other step type turns a failure (an action that cannot run on the content it was given, a remote system that cannot be reached) into operator work, even when the process already knows what to do about it.</p> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>Make the site-wide choice a per-step one, and add a third answer. A new node feature, <strong>When this step fails for good</strong>, on every step that runs a task, the start excepted:</p> <ul> <li><strong>Site default</strong> (the default): what <code>on_unrecoverable_failure</code> says, so every existing workflow behaves as it does today.</li> <li><strong>Raise an incident</strong>: the branch halts for an operator, the other branches go on.</li> <li><strong>Fail the instance</strong>: the whole instance fails.</li> <li><strong>Go on with a failure outcome</strong>: the engine writes <code>failed</code> to the step's payload variable, or to a failure variable the feature names, writes the exception message to a <strong>failure message variable</strong> when the step names one (opt-in, because an exception message is written for developers and may name parts of the site; without one it stays in the log and the audit trail), and sends the token down the step's outgoing flows, whose conditions decide. This is what the engine already does for an <code>OutcomeException</code>, so authors route on it with an ordinary <code>comparison</code> condition.</li> </ul> <p>"Fails for good" keeps its meaning: a fatal or unclassified exception at once, a retryable one after the step's retry policy is exhausted. Retries still happen first. The site-wide setting keeps only <code>incident</code> and <code>fail</code>: routing every step's failure by default would send failed tokens down flows with no condition across every workflow.</p> <p>How it is built:</p> <ul> <li>One place decides what a step that failed for good does, for a task that throws and for a child that ended without completing alike. For a task that throws, the failed advance has been rolled back by the time it decides, including a join that fired before the task ran. So routing advances the step again, join included, with the failure outcome in place of the task, as the queue's retry already runs the join again after a rollback.</li> <li>The routed branch starts from the state before the step ran: what the task wrote before it failed is gone, and the message is what it carries.</li> <li>A failure variable the step names is emptied when the step goes on without failing, and only if it holds something, so a workflow looping back to the step reads the failure of its own pass only. The variables are read once for the flow conditions anyway, so the usual pass costs no query and no write.</li> <li>Saving refuses the failure outcome on a step that has neither a payload variable nor a failure variable, whichever modeler saves it. Both modelers warn when such a step has an outgoing flow with no condition, which would carry a failed token on: when they open the workflow, and the Complete Modeler again when it saves it.</li> <li>If no flow's condition holds, the dead-end incident fires as it does for any outcome, and it carries the original error message so the operator still sees why the step failed.</li> <li>The failure stays visible though nobody had to resolve it: the failure variable reads <code>failed</code> in the instance's variables, with the message in the failure message variable when the step names one, and the log and the audit trail record that the step failed and went on. The trace shows the step's token as it shows any token that left its step; a marker of its own there is a possible follow-up.</li> </ul> <p>The two task-specific settings fold into it:</p> <ul> <li>The <code>action</code> task stops catching a failing action. It still writes <code>success</code> to its outcome variable; a failure goes through the step's choice, and a routed one reads <code>failed</code>.</li> <li>The <code>subprocess</code> task loses its <code>state_variable</code>. A child that does not complete, once its relaunch budget is used up, is the parent's step failing for good, and goes through the same failure handling as any other step: the parent's choice, or the site default, which a subprocess today ignores. A routed failed child writes <code>failed</code>, and a canceled child <code>canceled</code>, because a canceled child is not a broken step and authors route the two apart today.</li> </ul> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Engine and node feature, in queued and synchronous instances.</li> <li>Modeler and Complete Modeler fields, the refusal and the warning.</li> <li>Fold the <code>action</code> catch and the <code>subprocess</code> <code>state_variable</code>, and update the shipped examples that use them.</li> <li>Documentation: incidents, actions, subprocesses.</li> <li>Tests.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>A <em>When this step fails for good</em> choice, a failure variable and a failure message variable on every step that runs a task, the start excepted, in both modelers. A new <em>Failed, and went on with its failure outcome</em> event in the audit trail settings.</p> <h3 id="summary-api-changes">API changes</h3> <p>No change to the <code>TaskType</code> contract: a task keeps signaling failures by the exceptions it throws. The <code>action</code> task no longer catches a failing action, and its routed failure reads <code>failed</code> instead of <code>failure</code>. The <code>subprocess</code> and remote subprocess tasks lose <code>state_variable</code>.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>A node gains an <code>on_failure</code> feature: the choice, an optional failure variable and an optional failure message variable. No new flow type.</p> <p>AI-Generated: Yes (Claude Code was used to help draft this issue summary. I reviewed it.)</p>