xml – Manage bits and pieces of XML files or strings

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


xml – Manage bits and pieces of XML files or strings

New in version 2.4.


Synopsis

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

  • 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

-

  • 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

-

  • 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

  • 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

-

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

-

  • 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

-

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

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.7/modules/xml_module.html