xml – Manage bits and pieces of XML files or strings

From Get docs
Ansible/docs/2.8/modules/xml module


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.

Requirements

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

  • lxml >= 2.3.0

Parameters

Parameter Choices/Defaults Comments

add_children

list

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

raw

The attribute to select when using parameter value.

This is a string, not prepended with @.

backup

boolean

  • 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

string

  • attribute
  • text

Search for a given xpath and get content.

This parameter requires xpath to be set.

count

boolean

  • no

  • yes

Search for a given xpath and provide the count of any matches.

This parameter requires xpath to be set.

input_type

string

  • xml
  • yaml

Type of input for add_children and set_children.

insertafter

boolean

added in 2.8

  • no

  • yes

Add additional child-element(s) after the last 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.

insertbefore

boolean

added in 2.8

  • no

  • yes

Add additional child-element(s) before the first 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.

namespaces

dictionary

The namespace prefix:uri mapping for the XPath expression.

Needs to be a dict, not a list of items.

path

path / required

Path to the file to operate on.

This file must exist ahead of time.

This parameter is required, unless xmlstring is given.


aliases: dest, file

pretty_print

boolean

  • no

  • yes

Pretty print XML output.

print_match

boolean

  • no

  • yes

Search for a given xpath and print out any matches.

This parameter requires xpath to be set.

set_children

list

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

string

  • absent
  • present

Set or remove an xpath selection (node(s), attribute(s)).


aliases: ensure

strip_cdata_tags

boolean

added in 2.7

  • 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

raw

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

string / required

A string containing XML on which to operate.

This parameter is required, unless path is given.

xpath

string

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, 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
  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

# Example where parent XML nodes are created automatically
- 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 several more beers to the 'beers' element and add them before the 'Rochefort 10' element
  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
  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 an element's attribute values
  xml:
    path: /foo/bar.xml
    xpath: /business/website/validxhtml
    content: attribute
  register: xmlresp

- name: Show an 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 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'
  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

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.


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