community.general.xml module – Manage bits and pieces of XML files or strings
Note
This module is part of the community.general collection (version 8.6.4).
You might already have this collection installed if you are using the ansible
package.
It is not included in ansible-core
.
To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install community.general
.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.general.xml
.
Synopsis
A CRUD-like interface to managing bits of XML files.
Aliases: files.xml
Requirements
The below requirements are needed on the host that executes this module.
lxml >= 2.3.0
Parameters
Parameter |
Comments |
---|---|
Add additional child-element(s) to a selected element for a given Child elements must be given in a list and each item may be either a string (for example This parameter requires |
|
The attribute to select when using parameter This is a string, not prepended with |
|
Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. Choices:
|
|
Add additional child-element(s) after the last selected element for a given Child elements must be given in a list and each item may be either a string (for example This parameter requires Choices:
|
|
Add additional child-element(s) before the first selected element for a given Child elements must be given in a list and each item may be either a string (for example This parameter requires Choices:
|
|
The namespace Needs to be a Default: |
|
Path to the file to operate on. This file must exist ahead of time. This parameter is required, unless |
|
Pretty print XML output. Choices:
|
|
Set the child-element(s) of a selected element for a given Removes any existing children. Child elements must be specified as in This parameter requires |
|
Set or remove an xpath selection (node(s), attribute(s)). Choices:
|
|
Remove CDATA tags surrounding text values. Note that this might break your XML file if text values contain characters that could be interpreted as XML. Choices:
|
|
Desired state of the selected attribute. Either a string, or to unset a value, the Python Elements default to no value (but present). Attributes default to an empty string. |
|
A string containing XML on which to operate. This parameter is required, unless |
|
A valid XPath expression describing the item(s) you want to manipulate. Operates on the document root, |
Attributes
Attribute |
Support |
Description |
---|---|---|
Support: full |
Can run in |
|
Support: full |
Will return details on what has changed (or possibly needs changing in |
Notes
Note
Use the
--check
and--diff
options when testing your expressions.The diff output is automatically pretty-printed, so may not reflect the actual file content, only the file structure.
This module does not handle complicated xpath expressions, so limit xpath selectors to simple expressions.
Beware that in case your XML elements are namespaced, you need to use the
namespaces
parameter, see the examples.Namespaces prefix should be used for all children of an element where namespace is defined, unless another namespace is defined for them.
See Also
See also
- Xml module development community wiki
More information related to the development of this xml module.
- Introduction to XPath
A brief tutorial on XPath (w3schools.com).
- XPath Reference document
The reference documentation on XSLT/XPath (developer.mozilla.org).
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: true
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: true
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
set_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:
Key |
Description |
---|---|
A dictionary with the original xpath, namespaces and state. Returned: success Sample: |
|
The name of the backup file that was created Returned: when Sample: |
|
The count of xpath matches. Returned: when parameter ‘count’ is set Sample: |
|
The xpath matches found. Returned: when parameter ‘print_match’ is set |
|
A message related to the performed action(s). Returned: always |
|
An XML string of the resulting output. Returned: when parameter ‘xmlstring’ is set |