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

Note

This plugin is part of the community.windows collection (version 1.3.0).

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	Choices/Defaults	Comments
attribute string		The attribute name if the type is 'attribute'. Required if type=attribute.
backup boolean	Choices: no ← yes	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.
count boolean	Choices: no ← yes	When set to yes, return the number of nodes matched by xpath.
fragment string		The string representation of the XML fragment expected at xpath. Since ansible 2.9 not required when state=absent, or when count=yes. aliases: xmlstring
path path / required		Path to the file to operate on. aliases: dest, file
state string	Choices: present ← absent	Set or remove the nodes (or attributes) matched by xpath.
type string / required	Choices: attribute element ← text	The type of XML node you are working with.
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: yes
  register: connector_count

- name: show connector count
  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	Returned	Description
backup_file string	if backup=yes	Name of the backup file that was created. Sample: C:\Path\To\File.txt.11540.20150212-220915.bak
count integer	if count=yes	Number of nodes matched by xpath. Sample: 33
err list / elements=string	always, for type element and -vvv or more	XML comparison exceptions. Sample: attribute mismatch for actual=string
msg string	always	What was done. Sample: xml added

Authors

• Richard Levenberg (@richardcs)

• Jon Hawkesworth (@jhawkesworth)