win_xml – Manages XML file content on Windows hosts — Ansible Documentation

- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# win_xml – Manages XML file content on Windows hosts

New in version 2.7.

- Synopsis
- Parameters
- Notes
- See Also
- Examples
- Return Values
- Status

## 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 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 added in 2.9 | 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 added in 2.9 | 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

xml – Manage bits and pieces of XML files or strings
  XML manipulation for Posix hosts.
w3shools XPath tutorial
  A useful tutorial on XPath

## Examples

    - name: Apply our filter to Tomcat web.xml
      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
      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
      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
      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
      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 | 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

## Status

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

### Authors

- Richard Levenberg (@richardcs)
- Jon Hawkesworth (@jhawkesworth)

Hint

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