community.general.xml – Manage bits and pieces of XML files or strings

• Synopsis
• Requirements
• Parameters
• Notes
• See Also
• Examples
• Return Values

Synopsis

• A CRUD-like interface to managing bits of XML files.

Requirements

The below requirements are needed on the host that executes this module.

• lxml >= 2.3.0

Parameters

Notes

See Also

Examples

# Consider the following XML file:
#
# <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>

- name: Remove the 'subjective' attribute of the 'rating' element
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/rating/@subjective
    state: absent

- name: Set the rating to '11'
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/rating
    value: 11

# Retrieve and display the number of nodes
- name: Get count of 'beers' nodes
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/beers/beer
    count: yes
  register: hits

- ansible.builtin.debug:
    var: hits.count

# Example where parent XML nodes are created automatically
- name: Add a 'phonenumber' element to the 'business' element
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/phonenumber
    value: 555-555-1234

- name: Add several more beers to the 'beers' element
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/beers
    add_children:
    - beer: Old Rasputin
    - beer: Old Motor Oil
    - beer: Old Curmudgeon

- name: Add several more beers to the 'beers' element and add them before the 'Rochefort 10' element
  community.general.xml:
    path: /foo/bar.xml
    xpath: '/business/beers/beer[text()="Rochefort 10"]'
    insertbefore: yes
    add_children:
    - beer: Old Rasputin
    - beer: Old Motor Oil
    - beer: Old Curmudgeon

# NOTE: The 'state' defaults to 'present' and 'value' defaults to 'null' for elements
- name: Add a 'validxhtml' element to the 'website' element
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/website/validxhtml

- name: Add an empty 'validatedon' attribute to the 'validxhtml' element
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/website/validxhtml/@validatedon

- name: Add or modify an attribute, add element if needed
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/website/validxhtml
    attribute: validatedon
    value: 1976-08-05

# How to read an attribute value and access it in Ansible
- name: Read an element's attribute values
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/website/validxhtml
    content: attribute
  register: xmlresp

- name: Show an attribute value
  ansible.builtin.debug:
    var: xmlresp.matches[0].validxhtml.validatedon

- name: Remove all children from the 'website' element (option 1)
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/website/*
    state: absent

- name: Remove all children from the 'website' element (option 2)
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business/website
    children: []

# In case of namespaces, like in below XML, they have to be explicitly stated.
#
# <foo xmlns="http://x.test" xmlns:attr="http://z.test">
#   <bar>
#     <baz xmlns="http://y.test" attr:my_namespaced_attribute="true" />
#   </bar>
# </foo>

# NOTE: There is the prefix 'x' in front of the 'bar' element, too.
- name: Set namespaced '/x:foo/x:bar/y:baz/@z:my_namespaced_attribute' to 'false'
  community.general.xml:
    path: foo.xml
    xpath: /x:foo/x:bar/y:baz
    namespaces:
      x: http://x.test
      y: http://y.test
      z: http://z.test
    attribute: z:my_namespaced_attribute
    value: 'false'

- name: Adding building nodes with floor subnodes from a YAML variable
  community.general.xml:
    path: /foo/bar.xml
    xpath: /business
    add_children:
      - building:
          # Attributes
          name: Scumm bar
          location: Monkey island
          # Subnodes
          _:
            - floor: Pirate hall
            - floor: Grog storage
            - construction_date: "1990"  # Only strings are valid
      - building: Grog factory

# Consider this XML for following example -
#
# <config>
#   <element name="test1">
#     <text>part to remove</text>
#   </element>
#   <element name="test2">
#     <text>part to keep</text>
#   </element>
# </config>

- name: Delete element node based upon attribute
  community.general.xml:
    path: bar.xml
    xpath: /config/element[@name='test1']
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Authors

• Tim Bielawa (@tbielawa)
• Magnus Hedemark (@magnus919)
• Dag Wieers (@dagwieers)