ansible-xml

This is an Ansible module designed to work with XML files and strings. It is currently being developed and will be part of Ansible version 2.4.0, expected to be released in mid-September. For any issues, please report them on the Ansible GitHub page.

Installation

• To use this module, you need Python bindings for libxml version 2.3 or higher, often found in a package called python-lxml. You can install it using apt-get install python-lxml, yum install python-lxml, or pip install lxml.
• This module is NOT available in Ansible versions 2.3 and lower. You can install it via git clone https://github.com/cmprescott/ansible-xml.git or with ansible-galaxy install cmprescott.xml. It can be installed to the playbook's library directory, the playbook's roles directory, or Ansible's modules path.

Notes

• The original module was created by @github_rhinception.
• On May 5, 2015, the project was passed from @tbielawa to @cmprescott to handle issue #16.
• The module was merged into the main Ansible code on August 8, 2017.
• This software is licensed under GPLv3.
• We have unit tests available!

What is XPath?

XPath lets you use path expressions to choose nodes or groups of nodes in an XML document. This means you can find specific elements or attributes in an XML file easily.

Learn more about XPath here.

Unittests

This repository includes unittests. Check these and the Travis-CI configuration for more examples.

Examples

Using the following sample XML:

<?xml version='1.0' encoding='UTF-8'?>
<business type="bar">
    <name>Tasty Beverage Co.</name>
    <beers>
        <beer>Rochefort 10</beer>
        <beer>St. Bernardus Abbot 12</beer>
        <beer>Schlitz</beer>
    </beers>
    <rating subjective="true">10</rating>
    <website>
        <mobilefriendly />
        <address>http://tastybeverageco.com</address>
    </website>
</business>

Here are some operations you can perform:

1. To remove the subjective attribute from the rating element:

xml:
  path: /foo/bar.xml
  xpath: /business/rating/@subjective
  state: absent

2. To set the rating to 11:

xml:
  path: /foo/bar.xml
  xpath: /business/rating
  value: 11

3. To count the number of beer nodes:

xml:
  path: /foo/bar.xml
  xpath: /business/beers/beer
  count: yes
register: hits

debug:
  var: hits.count

4. To add a phonenumber element to the business element (creates missing parent nodes):

xml:
  path: /foo/bar.xml
  xpath: /business/phonenumber
  value: 555-555-1234

5. To add several new beers:

Assuming you have a vars.yaml file with:

new_beers:
    - beer: "Old Rasputin"
    - beer: "Old Motor Oil"
    - beer: "Old Curmudgeon"

Your playbook would look like this:

xml:
  path: /foo/bar.xml
  xpath: /business/beers
  add_children: '{{ new_beers }}'

Or add them inline:

xml:
  path: /foo/bar.xml
  xpath: /business/beers
  add_children:
      - beer: "Old Rasputin"
      - beer: "Old Motor Oil"
      - beer: "Old Curmudgeon"

6. To add a validxhtml element in the website. By default, state is set to present and value is null:

xml:
  path: /foo/bar.xml
  xpath: /business/website/validxhtml

7. To add an empty validatedon attribute to the validxhtml element:

xml:
  path: /foo/bar.xml
  xpath: /business/website/validxhtml/@validatedon

8. To remove all children from the website element, you can do it in two ways:

Option 1:

xml:
  path: /foo/bar.xml
  xpath: /business/website/*
  state: absent

Option 2:

xml:
  path: /foo/bar.xml
  xpath: /business/website
  children: []

9. If you have <beers><child01 /><child02 /></beers> and you do this:

xml:
  path: /foo/bar.xml
  xpath: /beers

The default value would remove the children elements.