xml - Manage bits and pieces of XML files or strings

New in version 2.4.

Synopsis

Requirements (on host that executes module)

  • lxml >= 2.3.0

Options

parameter required default choices comments
add_children
 no
Add additional child-element(s) to a selected element for a given xpath.
Child elements must be given in a list and each item may be either a string (eg. children=ansible to add an empty <ansible/> child element), or a hash where the key is an element name and the value is the element value.
This parameter requires xpath to be set.
attribute
 no
The attribute to select when using parameter value.
This is a string, not prepended with @.
backup
 no no
  • yes
  • no
Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
content
 no
  • attribute
  • text
Search for a given xpath and get content.
This parameter requires xpath to be set.
count
 no no
  • yes
  • no
Search for a given xpath and provide the count of any matches.
This parameter requires xpath to be set.
input_type
 no yaml
  • xml
  • yaml
Type of input for add_children and set_children.
namespaces
 no
The namespace prefix:uri mapping for the XPath expression.
Needs to be a dict, not a list of items.
path
 yes
Path to the file to operate on. File must exist ahead of time.
This parameter is required, unless xmlstring is given.
aliases: dest, file
pretty_print
 no no
  • yes
  • no
Pretty print XML output.
print_match
 no no
  • yes
  • no
Search for a given xpath and print out any matches.
This parameter requires xpath to be set.
set_children
 no
Set the child-element(s) of a selected element for a given xpath.
Removes any existing children.
Child elements must be specified as in add_children.
This parameter requires xpath to be set.
state
 no present
  • absent
  • present
Set or remove an xpath selection (node(s), attribute(s)).
aliases: ensure
value
 no
Desired state of the selected attribute.
Either a string, or to unset a value, the Python None keyword (YAML Equivalent, null).
Elements default to no value (but present).
Attributes default to an empty string.
xmlstring
 yes
A string containing XML on which to operate.
This parameter is required, unless path is given.
xpath
 no /
A valid XPath expression describing the item(s) you want to manipulate.
Operates on the document root, /, by default.

Examples

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

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

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

- debug:
    var: hits.count

- name: Add a phonenumber element to the business element
  xml:
    path: /foo/bar.xml
    xpath: /business/phonenumber
    value: 555-555-1234

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

- name: Add a validxhtml element to the website element
  xml:
    path: /foo/bar.xml
    xpath: /business/website/validxhtml

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

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

# How to read an attrribute value and access it in Ansible
- name: Read attribute value
  xml:
    path: /foo/bar.xml
    xpath: /business/website/validxhtml
    content: attribute
    attribute: validatedon
  register: xmlresp

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

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

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

# In case of namespaces, like in below XML, they have to be explicitely stated
# NOTE: there's the prefix "x" in front of the "bar", too
#<?xml version='1.0' encoding='UTF-8'?>
#<foo xmlns="http://x.test" xmlns:attr="http://z.test">
#  <bar>
#    <baz xmlns="http://y.test" attr:my_namespaced_attribute="true" />
#  </bar>
#</foo>

- name: Set namespaced '/x:foo/x:bar/y:baz/@z:my_namespaced_attribute' to 'false'
  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'

Return Values

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

name description returned type sample
actions
A dictionary with the original xpath, namespaces and state.
 success dict {'xpath': 'xpath', 'state=present': None, 'namespaces': ['namespace1', 'namespace2']}
backup_file
The name of the backup file that was created
 when backup=yes str /path/to/file.xml.1942.2017-08-24@14:16:01~
count
The count of xpath matches.
 when parameter 'count' is set int 2
matches
The xpath matches found.
 when parameter 'print_match' is set list
msg
A message related to the performed action(s).
 always string
xmlstring
An XML string of the resulting output.
 when parameter 'xmlstring' is set string

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.
  • Namespaces prefix should be used for all children of an element where namespace is defined, unless another namespace is defined for them.
  • More information about this module is available from the community wiki at https://github.com/ansible/community/wiki/Module:-xml

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.4/xml_module.html