<commit_before>Conditionals
============

.. contents:: Topics


Often the result of a play may depend on the value of a variable, fact (something learned about the remote system), 
or previous task result.  In some cases, the values of variables may depend on other variables.  
Further, additional groups can be created to manage hosts based on
whether the hosts match other criteria.   There are many options to control execution flow in Ansible.

Let's dig into what they are.

.. _the_when_statement:

The When Statement
``````````````````

Sometimes you will want to skip a particular step on a particular host.  This could be something
as simple as not installing a certain package if the operating system is a particular version,
or it could be something like performing some cleanup steps if a filesystem is getting full.

This is easy to do in Ansible, with the `when` clause, which contains a Jinja2 expression (see :doc:`playbooks_variables`).
It's actually pretty simple::

    tasks:
      - name: "shutdown Debian flavored systems"
        command: /sbin/shutdown -t now
        when: ansible_os_family == "Debian"

You can also use parentheses to group conditions::

    tasks:
      - name: "shutdown CentOS 6 and Debian 7 systems"
        command: /sbin/shutdown -t now
        when: (ansible_distribution == "CentOS" and ansible_distribution_major_version == "6") or
              (ansible_distribution == "Debian" and ansible_distribution_major_version == "7")

A number of Jinja2 "filters" can also be used in when statements, some of which are unique
and provided by Ansible.  Suppose we want to ignore the error of one statement and then
decide to do something conditionally based on success or failure::

    tasks:
      - command: /bin/false
        register: result
        ignore_errors: True
      - command: /bin/something
        when: result|failed
      - command: /bin/something_else
        when: result|succeeded
      - command: /bin/still/something_else
        when: result|skipped

Note that was a little bit of foreshadowing on the 'register' statement.  We'll get to it a bit later in this chapter.

As a reminder, to see what facts are available on a particular system, you can do::

    ansible hostname.example.com -m setup

Tip: Sometimes you'll get back a variable that's a string and you'll want to do a math operation comparison on it.  You can do this like so::

    tasks:
      - shell: echo "only on Red Hat 6, derivatives, and later"
        when: ansible_os_family == "RedHat" and ansible_lsb.major_release|int >= 6

.. note:: the above example requires the lsb_release package on the target host in order to return the ansible_lsb.major_release fact.<commit_msg>added clarification on results tests naming<commit_after>Conditionals
============

.. contents:: Topics


Often the result of a play may depend on the value of a variable, fact (something learned about the remote system), 
or previous task result.  In some cases, the values of variables may depend on other variables.  
Further, additional groups can be created to manage hosts based on
whether the hosts match other criteria.   There are many options to control execution flow in Ansible.

Let's dig into what they are.

.. _the_when_statement:

The When Statement
``````````````````

Sometimes you will want to skip a particular step on a particular host.  This could be something
as simple as not installing a certain package if the operating system is a particular version,
or it could be something like performing some cleanup steps if a filesystem is getting full.

This is easy to do in Ansible, with the `when` clause, which contains a Jinja2 expression (see :doc:`playbooks_variables`).
It's actually pretty simple::

    tasks:
      - name: "shutdown Debian flavored systems"
        command: /sbin/shutdown -t now
        when: ansible_os_family == "Debian"

You can also use parentheses to group conditions::

    tasks:
      - name: "shutdown CentOS 6 and Debian 7 systems"
        command: /sbin/shutdown -t now
        when: (ansible_distribution == "CentOS" and ansible_distribution_major_version == "6") or
              (ansible_distribution == "Debian" and ansible_distribution_major_version == "7")

A number of Jinja2 "filters" can also be used in when statements, some of which are unique
and provided by Ansible.  Suppose we want to ignore the error of one statement and then
decide to do something conditionally based on success or failure::

    tasks:
      - command: /bin/false
        register: result
        ignore_errors: True

      - command: /bin/something
        when: result|failed

      # In older versions of ansible use |success, now both are valid but succedded uses the correct tense.
      - command: /bin/something_else
        when: result|succeeded

      - command: /bin/still/something_else
        when: result|skipped


.. note:: the filters have been updated in 2.1 so both `success` and `succeded` work (`fail`/`failed`, etc).

Note that was a little bit of foreshadowing on the 'register' statement.  We'll get to it a bit later in this chapter.

As a reminder, to see what facts are available on a particular system, you can do::

    ansible hostname.example.com -m setup

Tip: Sometimes you'll get back a variable that's a string and you'll want to do a math operation comparison on it.  You can do this like so::

    tasks:
      - shell: echo "only on Red Hat 6, derivatives, and later"
        when: ansible_os_family == "RedHat" and ansible_lsb.major_release|int >= 6

.. note:: the above example requires the lsb_release package on the target host in order to return the ansible_lsb.major_release fact.
{'fraction_non_alphanumeric': 0.069971870604782, 'fraction_numerical': 0.0031645569620253164, 'mean_word_length': 3.451486697965571, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4213578', 'n_tokens_mistral': 1571, 'n_tokens_neox': 1474, 'n_words': 759}