IF ANY nature THEN

Runs the ops nested underneath it when the current project has changed items belonging to at least one of the natures you pick. It is a yes or no test and nothing more: it reads no paths, sets no values and leaves the stash exactly as it found it.

Use it as a guard. When the block needs the actual file paths of the matching items, use IF EXISTS nature THEN instead, which handles one nature and hands the block a list of paths to work with.

Two things have to be true before it can ever match. It has to sit inside FOR projects with changes DO, because the question is asked about the project the loop is currently on. And Load Nature Items has to have run earlier in the rule, because that is what works out which items belong to which nature.

The first of those is not a soft requirement. Placed anywhere outside the project loop, the op stops the rule from compiling with an error about an undeclared project variable, and the job fails before its first op runs. Nesting depth inside the loop does not matter.

Fields

Natures

The only control on the form. Entries stack up in the box as tags, each with its own remove button, and there is no limit on how many you add. The block runs when any one of them was detected for the project the loop is on. There is no way to require all of them, so build that from nested IF EXISTS nature THEN ops instead.

The picker lists nature resources and, mixed in with them, global variables. Do not pick a variable here. This field stores whatever you chose and compares it as written, without resolving anything, so a variable picked from the list turns into a check for a nature literally named ${your_variable}. It never matches, the block never runs, and nothing in the log points at the cause. The sister op IF EXISTS nature THEN does resolve variables in its picker, which is what makes this easy to get wrong.

Leaving the field empty is accepted by the form and produces a condition that is always false. An op with no natures picked is a block that never runs.

Scope of the test

The question is asked about one project, the one the surrounding loop is currently on. In a job that spans several projects the answer changes from one pass of the loop to the next, which is the point of putting it there. A nature that was detected in another project of the same job does not make this block run.

Detection is about changed items, not about what a nature could match in principle. A project whose changeset contains no file matching the nature's rules does not count, even though the nature resource exists and is active.

What it does at run time

The op records its name as a step marker in the job log at debug level, so it shows up only when you are reading the log with debug lines turned on. It is also one of the points at which a pending cancel request on the job is noticed, which ends the job right there. Beyond those it logs nothing. The lines naming each detected nature come from Load Nature Items earlier in the run, and that is where to look when you are trying to work out why this test came back false.

It writes nothing into the stash, so the ops inside the block have no more information than the ops outside it.

ELSE and ELSIF condition THEN attach directly after it, at the same level of the tree, and cover the projects that carry none of the natures you picked. Four settings on the op's Options tab break that pairing: Parallel Mode, Error Handling, a Needs Rollback? value with a Needs Rollback Key of its own, and unticking either Run Forward or Run Rollback. Each of those wraps the test in a block of its own, and the rule then refuses to compile while the ELSE is still attached.

On a rollback pass the test is evaluated again. The detected natures are usually still the same, so the same branch is normally taken both ways.

Combining with other ops

IF EXISTS nature THEN nested inside this op is a common shape: the outer test keeps the whole section out of the way for projects that have nothing of interest, and the inner ops deal with one nature each and get the paths.

APPLY NATURE is the other way to get at a nature. It runs one nature's patterns over the job's item list and leaves the matching items in the stash, and it works on its own: it needs neither the project loop nor Load Nature Items.

Examples

Skip a whole deployment section for projects with no database changes.

Natures   sql-scripts

-> Run the database deployment ops

Run a shared preparation step when a project carries any of three natures, then handle each one separately.

Natures   java-sources, web-assets, sql-scripts

-> Prepare the staging directory
-> IF EXISTS nature THEN   java-sources
-> IF EXISTS nature THEN   web-assets
-> IF EXISTS nature THEN   sql-scripts