Skip to content

IF ROLLBACK

Runs the ops nested underneath it only during the rollback pass of a job, or only during the forward pass, depending on how you set it. Use it when a whole group of ops belongs to one pass and not the other: undo scripts, notification of a failed release, cleanup that should not happen while things are still going well.

For a single op, the Run Forward and Run Rollback checkboxes on that op's Options tab do the same job with less tree, though they are stricter: an op with Run Forward cleared and a Needs Rollback Key filled in also waits for that key to be registered, where an IF ROLLBACK block only looks at the flag. Reach for IF ROLLBACK when you have several ops to gate at once, or when you want an ELSE branch for the other pass.

forward pass job steps run, the flag is 0 rollback: 0 block runs here a step failed rollback pass the steps that need undoing run again, the flag is 1 rollback: 1 block runs here

Fields

This op has no config form. Its Config tab shows a data editor holding a single entry.

rollback

The value the job's rollback flag has to match for the block to run. It arrives set to 1, which means the block runs during the rollback pass and is skipped on the way forward. Change it to 0 to get the opposite.

The comparison is a plain text match against a flag that, inside a job, is only ever 0 or 1. Any other value matches nothing and the block never runs, with no warning. Delete the entry altogether and the op behaves as if it were set to 1.

An empty value is the odd one out. It compares against an absent flag rather than against 0 or 1, so inside a job the block never runs, and in a rule that is not a job the block runs on every pass. Neither outcome is likely to be what you wanted.

The value is not variable-expanded. Typing ${something} here gives you a block that never runs.

When the rollback pass happens at all

A job only gets a rollback pass when an op that already ran registered the need for one. Without that registration, a failure takes the job straight to ERROR and no second pass follows, so an IF ROLLBACK block set to 1 never runs no matter how badly the job went. This is the most common reason a rollback block looks dead.

Registration comes from the Needs Rollback? setting on the Options tab of the earlier op, and the four choices do not behave alike:

Needs Rollback? Registers on
No Rollback Necessary nothing, on any op
Rollback Needed Always any op, as soon as the rule reaches it
Rollback Needed Before only the ops that run scripts or ship files, before the work starts
Rollback Needed After only the ops that run scripts or ship files, once the work succeeded

Put Rollback Needed Before or Rollback Needed After on anything else and it registers nothing at all. When you want a plain "this job is now undoable" marker on an arbitrary op, use Rollback Needed Always.

During the rollback pass the job walks the steps that were registered and runs the same rule again from the top with the flag set. Your block is evaluated once per step that is replayed, not once per job.

Outside a job the flag does not exist at all. In a form rule, an event rule or a web service rule, neither 1 nor 0 matches, so the block is skipped in both directions. There is no useful setting for this op outside a pipeline.

A failure inside the rollback pass ends the rollback where it stands, logs that the environments are inconsistent and need manual intervention, and leaves the job half undone. Keep the ops in a rollback block tolerant.

Options tab

Being a branch, this op hides most of the Options tab. What is left is Enabled and Debug Mode. Return Key, Needs Rollback?, Needs Rollback Key, Run Forward, Run Rollback, Timeout, Semaphore Key, Parallel Mode, Error Handling and the trap settings are all absent on the IF ROLLBACK op itself, so put those on the ops nested inside it. Name sits on the Config tab above the data editor. The full list is described in Rule Palette.

ELSE and ELSIF condition THEN may follow this op and bind to it, as long as they sit immediately after it in the tree.

Combining with other ops

The stash also carries job_mode, which reads forward or rollback. Testing that with IF var condition THEN gives you the same branch plus the rest of that op's condition rows, which helps when the rollback check is only one of several things you care about. Background on the pass itself is in Rollback.

FAIL inside a rollback block aborts the rollback. That is occasionally what you want, when the undo cannot proceed and a person has to be told, but make it a deliberate choice.

Put a LOG Message at the top of a rollback block. Job logs of rolled-back releases get read under pressure, and a line saying which block took over saves the reader a trip through the rule.

Examples

Undo work only while rolling back, and say so in the log.

rollback: 1
  LOG                     Rolling back the myapp release
  Run remote              undo script on myapp
  Change status           topic back to In Progress

Do the forward-only half of a step, with the rollback half right after it.

rollback: 0
  Ship file               artifact to myapp
ELSE
  Run remote              remove the shipped artifact from myapp

Notify only when the job is being undone.

rollback: 1
  Send notification       release ${jobname} was rolled back