IF var THEN

Runs the ops nested underneath it when one stash value matches one piece of text exactly. That is the whole op: one variable, one literal, character-for-character equality.

It is the cheapest branch in the palette and the most limited. There is no case folding, no numeric comparison, no list membership and no ${var} expansion in either field. The moment you need any of those, move to IF var condition THEN, which offers the same test plus fifteen more. For the opposite test see IF var ne value THEN, and for several accepted values at once see IF var in LIST THEN.

Fields

Variable

The name of the stash value to read, written on its own with no ${} wrapper: status, not ${status}.

Dots walk into nested values, so topic.title reads the title out of a loaded topic. Square brackets index into a list, so changesets[0] is its first entry and changesets[0].name the name of that entry. A dotted step onto a list does not work; use brackets.

A path that does not resolve produces nothing, with no error and no warning in the log. That matters more than it sounds, because nothing compares equal to an empty Value. See the traps below.

The field is a monospace box several lines tall, so it is easy to leave a stray newline or a trailing space in it. Either one becomes part of the name you are asking for, and the lookup then fails quietly.

Value

The text to match against, taken literally. Nothing in this field expands: ${project} here is eight characters, not the project name. Nothing is trimmed either, so a trailing space or newline left in the box is part of the value being compared.

Leave it blank and you are asking whether the variable is empty or absent. That test does work, but IF var condition THEN with IS EMPTY says it out loud and does not fire on a typo in the variable name.

How the comparison behaves

The match is text, exact, and case sensitive. PROD does not equal prod.

Numbers are compared as text too. 1.0 does not equal 1, 007 does not equal 7, and a counter that arrived as 10 does not equal a Value of 10.0. When the value came out of arithmetic, use IF var condition THEN with the Numeric option ticked.

When the variable holds a list or a hash rather than a single value, the comparison is against an internal handle for that structure, which never equals anything you could type. The branch is never taken. To test membership of a list in the stash, use HAS in IF var condition THEN.

Traps

Blank Variable and blank Value make the condition true, and the block runs every time. So does a Variable that is misspelled or was never set, paired with a blank Value. If you are using this op as an emptiness check, make sure the variable name is one that really exists somewhere in the rule.

The reverse trap is the common one: a correct value that never matches because of case, a trailing space pasted in with the text, or a number formatted differently from how it was stored.

What it does at run time

The op appears in the job log as a step under whatever you named it, and it is one of the points at which a cancel request on the job is noticed. Renaming it to something like is this a PROD deploy? makes the log readable at no cost.

It puts no result into the stash.

Its Options tab is shorter than the one on other ops. A branch op hides the result, rollback, trapping, timeout, semaphore and parallel settings, leaving Enabled and Debug Mode. Unticking Enabled drops the test and everything nested under it out of the rule. To trap an error or to keep part of a branch off the rollback pass, set those options on the ops inside the block, or wrap the block in TRY statement.

An ELSE or ELSIF condition THEN placed directly after it takes the other side of the branch. They bind to the op immediately above them at the same level, so keep them adjacent.

On a rollback pass the rule runs again from the top and the comparison is made again against the stash as it stands then, which may not be the answer you got on the way out.

Combining with other ops

Load first, branch second. The services that fetch topics, changesets or user records leave their results in the stash, and this op reads whatever they left. Branching on a path like topic.status before anything has loaded a topic gives you the blank-Value trap described above.

SET VAR is the usual partner for the normalisation this op cannot do itself: lowercase the value into a second stash key, then compare against that.

Nest FAIL inside the block to stop the job when the match means trouble, or LOG Message to leave a trail of which branch was taken.

Examples

Run a block only for one environment code.

Variable   bl
Value      PROD

Act on a topic category, having loaded the topic earlier in the rule.

Variable   topic.category
Value      incident

Guard a block that only makes sense when a previous op stored a flag.

Variable   del_files
Value      1