Skip to main content

Using Conditional Logic in a Job

Using Conditional Logic in a Job

Generally Available in Runbook Automation 6.3.0

Conditional Logic steps are Generally Available and enabled by default starting in Runbook Automation 6.3.0.

Overview

Conditional Logic steps enable workflows to make decisions during execution based on runtime conditions. Instead of creating multiple jobs for different scenarios or writing complex scripts with if/then logic, you can use Conditional Logic steps to branch your workflow based on:

  • Job options (environment, configuration values)
  • Prior step outputs (status, state, IDs, or counts exposed by earlier steps)
  • Node attributes (OS family, hostname, tags)
  • Job context (project name, job name, execution user)
  • Data captured from previous steps

This guide provides hands-on examples to help you understand how to use conditional logic effectively.

Prerequisites

  1. Runbook Automation 6.3.0+ (Conditional Logic is enabled by default). On versions 5.20.0 through 6.2.x, enable the feature flag in rundeck-config.properties:
    rundeck.feature.earlyAccessJobConditional.enabled=true
  2. Basic understanding of job workflows and job options
  3. Workflow strategy set to Sequential, Parallel, or Node First (Ruleset is not supported)

New to Rundeck?

If you're new to Rundeck, we recommend completing the Getting Started Tutorial first. This guide assumes familiarity with creating jobs, adding steps, and using job options.

Understanding Conditional Logic

Conditional Logic steps come in two types:

  • Node Conditional Logic: Evaluates conditions independently on each node based on node attributes
  • Workflow Conditional Logic: Evaluates conditions once per job execution in a global context

Both types support:

  • Multiple conditions with AND logic (all must be true)
  • Multiple condition sets with OR logic (any set can be true)
  • Eight comparison operators: equals, not equals, greater than, greater than or equal, less than, less than or equal, contains, and matches (regex)

Hands-On Examples

The following examples demonstrate conditional logic in action. Import these jobs to see how conditions work, then run them with different option values to observe the behavior.

Simple Conditional Example

Simple Conditional: Version Check

This example demonstrates a basic conditional step that executes only when a specific version is selected.

Use Case: Run deployment steps only for version 5.20

What This Job Does:

  1. Accepts a version option as input
  2. Uses a Node Conditional Logic step to check if version equals "5.20"
  3. If the condition is true, executes an echo command
  4. If the condition is false, skips the substep

Condition Structure:

  • Field: ${option.version}
  • Operator: equals
  • Value: 5.20

Job Definition (JSON):

[ {
  "defaultTab" : "nodes",
  "description" : "Simple example showing a single condition checking a job option value.",
  "executionEnabled" : true,
  "loglevel" : "INFO",
  "name" : "Simple Conditional Example",
  "nodeFilterEditable" : false,
  "nodefilters" : {
    "dispatch" : {
      "excludePrecedence" : true,
      "keepgoing" : false,
      "rankOrder" : "ascending",
      "successOnEmptyNodeFilter" : false,
      "threadcount" : "1"
    },
    "filter" : ".*"
  },
  "nodesSelectedByDefault" : true,
  "options" : [ {
    "name" : "version",
    "label" : "Version",
    "description" : "Enter a version number (try 5.20 or 5.19)",
    "type" : "text",
    "required" : true
  } ],
  "scheduleEnabled" : true,
  "schedules" : [ ],
  "sequence" : {
    "commands" : [ {
      "conditionGroups" : [ [ {
        "key" : "${option.version}",
        "operator" : "==",
        "value" : "5.20"
      } ] ],
      "description" : "Check if version is 5.20",
      "nodeStep" : true,
      "subSteps" : [ {
        "exec" : "echo 'Running deployment for version 5.20'"
      } ],
      "type" : "conditional"
    } ],
    "keepgoing" : false,
    "strategy" : "sequential"
  }
} ]

How to Use This Example:

  1. Copy the JSON above and save it as simple-conditional-example.json
  2. Import the job into your Rundeck project:
    • Navigate to the Jobs page
    • Click the gear icon and select "Import Job"
    • Upload the JSON file
  3. Run the job and enter 5.20 for the version option
    • The conditional step will evaluate to true
    • The echo command will execute
  4. Run the job again and enter 5.19 for the version option
    • The conditional step will evaluate to false
    • The substep will be skipped
    • Check the execution log to see the skip message

What to Observe:

  • In the Job Editor, expand the conditional step to see the condition configuration
  • In execution logs when condition is true: You'll see the echo output
  • In execution logs when condition is false: You'll see a message like "Conditional step skipped"
  • Enable Debug logging to see detailed condition evaluation

Key Takeaways:

  • Fields must use ${} syntax to reference variables
  • The operator == is equivalent to "equals"
  • Substeps only execute when the condition evaluates to true
  • Simple conditionals are perfect for single-criteria decisions

Real-World Use Cases

Environment-Based Workflows

Use conditionals to run different steps based on environment:

Workflow Conditional Logic: ${option.environment} equals "production"
├─ Substep: Send approval notification
├─ Substep: Backup database
└─ Substep: Enable maintenance mode

OS-Specific Commands

Target specific operating systems without changing node filters:

Node Conditional Logic: ${node.osFamily} equals "unix"
└─ Substep: Run Linux-specific commands

Node Conditional Logic: ${node.osFamily} equals "windows"
└─ Substep: Run Windows-specific commands

Version-Aware Deployments

Skip or include steps based on application versions:

Workflow Conditional Logic: ${option.version} greater than "5.0"
└─ Substep: Use new API endpoints

Tag-Based Node Targeting

Execute steps only on nodes with specific tags:

Node Conditional Logic: ${node.tags} contains "database"
└─ Substep: Database maintenance commands

Building Your Own Conditional Jobs

Step-by-Step Guide

  1. Plan Your Conditions

    • Identify what should trigger different behavior
    • Determine if you need Node or Workflow conditional logic
    • Map out your AND/OR logic requirements

  2. Create Job Options

    • Add options for values you'll check in conditions
    • Use enforced values for dropdown choices
    • Make options required if conditions depend on them

  3. Add Conditional Step

    • In the Job Editor, click "Add a step"
    • Select Node Conditional Logic or Workflow Conditional Logic
    • Give the step a descriptive name (a default Step Name is pre-filled automatically)

  4. Configure Conditions

    • Add your first condition (Field, Operator, Value)
    • Click "Add" to add more conditions to the same set (AND logic)
    • Click "Add Condition Set" to create alternate conditions (OR logic)

  5. Add Substeps

    • Click "+ Add Condition Step"
    • Select and configure steps that run when conditions are met
    • Add multiple substeps as needed

  6. Test Thoroughly

    • Run with different option values
    • Enable Debug logging to see condition evaluation
    • Verify substeps execute only when expected

Tips for Effective Conditionals

Condition Design

  • Keep it simple: Prefer multiple simple conditions over complex regex
  • Use descriptive names: Help others understand what the conditional does
  • Test with debug mode: Always verify conditions evaluate as expected
  • Document your logic: Add notes in the job description

Common Patterns

Multiple Environments:

Set 1: ${option.environment} equals "dev"
OR
Set 2: ${option.environment} equals "staging"

OS + Tag Combination:

Set 1: ${node.osFamily} equals "unix" AND ${node.tags} contains "web"
OR
Set 2: ${node.osFamily} equals "windows" AND ${node.tags} contains "iis"

Exclude Specific Cases:

${option.environment} not equals "production"

Troubleshooting

Conditions not evaluating correctly?

  • Enable Debug logging when running the job
  • Verify option names match exactly (case-sensitive)
  • Ensure context variable fields use ${} syntax (${option.name} not option.name), or select prior step outputs from the Prior Steps tab
  • Check that node attributes exist on target nodes

Substeps not appearing?

  • Verify substeps match parent type (Node substeps for Node Conditional, Workflow substeps for Workflow Conditional)
  • Check that at least one condition is defined
  • Ensure all required fields are filled

Cannot import job?

  • Conditional Logic requires JSON or YAML format (XML is not supported)
  • Verify the feature flag is not disabled before importing

Advanced Scenarios

Using Outputs from Previous Steps

Conditional Logic can evaluate outputs from earlier steps in two ways:

1. Built-in Prior Step Outputs (6.3.0+): Many bundled step plugins (such as PagerDuty, ServiceNow, Jira, Datadog, AWS, Sensu, and Job State Conditional) expose their outcomes directly in the condition editor:

  1. Give the earlier step a unique Step Name (e.g., Get Incident)
  2. In your Conditional Logic step, click the Field input and select the Prior Steps tab
  3. Choose the exposed output (e.g., pd_incident_status [steps.['Get Incident'].pd_incident_status])

Parallel strategy and prior-step outputs

The Parallel strategy starts top-level steps concurrently. Use Sequential or Node First when a conditional depends on an earlier step's output so that the earlier step finishes before the condition evaluates.

2. Capturing Output with Log Filters: For Command, Script, or custom steps, capture output using log filters:

  1. Add a step with a Log Filter (e.g., Key Value Data) to capture output
  2. In a later conditional step, reference the captured data: ${data.variableName}

Example:

Step 1: Command with Key Value Data log filter capturing "status"
Step 2: Workflow Conditional Logic: ${data.status} equals "ready"
  └─ Substep: Proceed with deployment

Nested Conditional Logic

You can place a Conditional Logic step one level inside another Conditional Logic step:

  1. Add a parent Conditional Logic step and define its conditions
  2. Add another Conditional Logic step as a substep
  3. Configure the nested conditional's conditions and add regular substeps
  4. When the parent condition is met, the nested conditional evaluates independently

The nested conditional cannot contain another conditional. Use a Job Reference substep when deeper or reusable branching is required.

Combining with Workflow Strategies

Conditional Logic works with Sequential, Parallel, and Node First strategies (not Ruleset):

  • Sequential Strategy (Step First): Evaluates each conditional step across nodes before moving to the next step
  • Parallel Strategy: Evaluates conditionals concurrently across nodes
  • Node First Strategy: Runs the full workflow on each node before the next node, evaluating conditions as the workflow progresses on that node

Next Steps

Now that you understand conditional logic basics:

  1. Experiment with the example jobs - modify conditions and observe behavior
  2. Combine conditionals with other features like prior step outputs, log filters, and job references
  3. Build your own conditional workflows for your specific use cases
Privacy Policy |