xml - Manage bits and pieces of XML files or strings

New in version 2.4.

Synopsis

A CRUD-like interface to managing bits of XML files.
You might also be interested in a brief tutorial from http://www.w3schools.com/xpath/ and https://developer.mozilla.org/en-US/docs/Web/XPath.

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

Docs

Docs4dev

Title here