xml – Manage bits and pieces of XML files or strings¶

New in version 2.4.

Synopsis
Requirements
Parameters
Notes
Examples
Return Values
Status

Synopsis ¶

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

Requirements ¶

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

lxml >= 2.3.0

Parameters ¶

Parameter	Choices/Defaults	Comments
add_children -		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 -		The attribute to select when using parameter `value`. This is a string, not prepended with `@`.
backup boolean	Choices: no ← yes	Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
content -	Choices: attribute text	Search for a given `xpath` and get content. This parameter requires `xpath` to be set.
count boolean	Choices: no ← yes	Search for a given `xpath` and provide the count of any matches. This parameter requires `xpath` to be set.
input_type -	Choices: xml yaml ←	Type of input for `add_children` and `set_children`.
namespaces -		The namespace `prefix:uri` mapping for the XPath expression. Needs to be a `dict`, not a `list` of items.
path - / required		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 boolean	Choices: no ← yes	Pretty print XML output.
print_match boolean	Choices: no ← yes	Search for a given `xpath` and print out any matches. This parameter requires `xpath` to be set.
set_children -		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 -	Choices: absent present ←	Set or remove an xpath selection (node(s), attribute(s)). aliases: ensure
strip_cdata_tags boolean added in 2.7	Choices: no ← yes	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.
value -		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 - / required		A string containing XML on which to operate. This parameter is required, unless `path` is given.
xpath -		A valid XPath expression describing the item(s) you want to manipulate. Operates on the document root, `/`, by default.

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

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 attribute 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, the following are the fields unique to this module:

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

Status ¶

This module is not guaranteed to have a backwards compatible interface. [preview]
This module is maintained by the Ansible Community. [community]

Authors¶

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

Hint

If you notice any issues in this documentation you can edit this document to improve it.

xml – Manage bits and pieces of XML files or strings¶

Synopsis¶

Requirements¶

Parameters¶

Notes¶

Examples¶

Return Values¶

Status¶