community.windows.win_xml module – Manages XML file content on Windows hosts

Note

This module is part of the community.windows collection (version 2.4.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.windows.

To use it in a playbook, specify: community.windows.win_xml.

Synopsis

  • Manages XML nodes, attributes and text, using xpath to select which xml nodes need to be managed.

  • XML fragments, formatted as strings, are used to specify the desired state of a part or parts of XML files on remote Windows servers.

  • For non-Windows targets, use the community.general.xml module instead.

Parameters

Parameter

Comments

attribute

string

The attribute name if the type is ‘attribute’.

Required if type=attribute.

backup

boolean

Determine whether a backup should be created.

When set to yes, create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.

Choices:

  • false ← (default)

  • true

count

boolean

When set to yes, return the number of nodes matched by xpath.

Choices:

  • false ← (default)

  • true

fragment

aliases: xmlstring

string

The string representation of the XML fragment expected at xpath. Since ansible 2.9 not required when state=absent, or when count=yes.

path

aliases: dest, file

path / required

Path to the file to operate on.

state

string

Set or remove the nodes (or attributes) matched by xpath.

Choices:

  • "present" ← (default)

  • "absent"

type

string

The type of XML node you are working with.

Choices:

  • "attribute"

  • "element" ← (default)

  • "text"

xpath

string / required

Xpath to select the node or nodes to operate on.

Notes

Note

  • Only supports operating on xml elements, attributes and text.

  • Namespace, processing-instruction, command and document node types cannot be modified with this module.

See Also

See also

community.general.xml

XML manipulation for Posix hosts.

w3shools XPath tutorial

A useful tutorial on XPath

Examples

- name: Apply our filter to Tomcat web.xml
  community.windows.win_xml:
    path: C:\apache-tomcat\webapps\myapp\WEB-INF\web.xml
    fragment: '<filter><filter-name>MyFilter</filter-name><filter-class>com.example.MyFilter</filter-class></filter>'
    xpath: '/*'

- name: Apply sslEnabledProtocols to Tomcat's server.xml
  community.windows.win_xml:
    path: C:\Tomcat\conf\server.xml
    xpath: '//Server/Service[@name="Catalina"]/Connector[@port="9443"]'
    attribute: 'sslEnabledProtocols'
    fragment: 'TLSv1,TLSv1.1,TLSv1.2'
    type: attribute

- name: remove debug configuration nodes from nlog.conf
  community.windows.win_xml:
    path: C:\IISApplication\nlog.conf
    xpath: /nlog/rules/logger[@name="debug"]/descendant::*
    state: absent

- name: count configured connectors in Tomcat's server.xml
  community.windows.win_xml:
    path: C:\Tomcat\conf\server.xml
    xpath: //Server/Service/Connector
    count: true
  register: connector_count

- name: show connector count
  ansible.builtin.debug:
    msg: Connector count is {{ connector_count.count }}

- name: ensure all lang=en attributes to lang=nl
  community.windows.win_xml:
    path: C:\Data\Books.xml
    xpath: //@[lang="en"]
    attribute: lang
    fragment: nl
    type: attribute

Return Values

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

Key

Description

backup_file

string

Name of the backup file that was created.

Returned: if backup=yes

Sample: "C:\\Path\\To\\File.txt.11540.20150212-220915.bak"

count

integer

Number of nodes matched by xpath.

Returned: if count=yes

Sample: 33

err

list / elements=string

XML comparison exceptions.

Returned: always, for type element and -vvv or more

Sample: ["attribute mismatch for actual=string"]

msg

string

What was done.

Returned: always

Sample: "xml added"

Authors

  • Richard Levenberg (@richardcs)

  • Jon Hawkesworth (@jhawkesworth)