.. Document meta

:orphan:

.. |antsibull-internal-nbsp| unicode:: 0xA0
    :trim:

.. role:: ansible-attribute-support-label
.. role:: ansible-attribute-support-property
.. role:: ansible-attribute-support-full
.. role:: ansible-attribute-support-partial
.. role:: ansible-attribute-support-none
.. role:: ansible-attribute-support-na
.. role:: ansible-option-type
.. role:: ansible-option-elements
.. role:: ansible-option-required
.. role:: ansible-option-versionadded
.. role:: ansible-option-aliases
.. role:: ansible-option-choices
.. role:: ansible-option-choices-default-mark
.. role:: ansible-option-default-bold
.. role:: ansible-option-configuration
.. role:: ansible-option-returned-bold
.. role:: ansible-option-sample-bold

.. Anchors

.. _ansible_collections.middleware_automation.common.xml_module:

.. Anchors: short name for ansible.builtin

.. Title

xml -- Manage bits and pieces of XML files or strings
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. Collection note

.. note::
    This module is part of the `middleware_automation.common collection <https://galaxy.ansible.com/middleware_automation/common>`_.

    To install it, use: :code:`ansible-galaxy collection install middleware\_automation.common`.
    You need further requirements to be able to use this module,
    see :ref:`Requirements <ansible_collections.middleware_automation.common.xml_module_requirements>` for details.

    To use it in a playbook, specify: :code:`middleware_automation.common.xml`.

.. version_added


.. contents::
   :local:
   :depth: 1

.. Deprecated


Synopsis
--------

.. Description

- A customized version of community.general.xml dedicated to runtimes configuration xpath/xslt.


.. Aliases


.. Requirements

.. _ansible_collections.middleware_automation.common.xml_module_requirements:

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

- lxml \>= 3.0.0






.. Options

Parameters
----------

.. rst-class:: ansible-option-table

.. list-table::
  :width: 100%
  :widths: auto
  :header-rows: 1

  * - Parameter
    - Comments

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-add_children"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-add_children:

      .. rst-class:: ansible-option-title

      **add_children**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-add_children" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`list` / :ansible-option-elements:`elements=any`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Add additional child-element(s) to a selected element for a given \ :emphasis:`xpath`\ .

      Child elements must be given in a list and each item may be either a string (eg. \ :literal:`children=ansible`\  to add an empty \ :literal:`\<ansible/\>`\  child element), or a hash where the key is an element name and the value is the element value.

      This parameter requires \ :emphasis:`xpath`\  to be set.


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-attribute"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-attribute:

      .. rst-class:: ansible-option-title

      **attribute**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-attribute" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`any`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      The attribute to select when using parameter \ :emphasis:`value`\ .

      This is a string, not prepended with \ :literal:`@`\ .


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-backup"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-backup:

      .. rst-class:: ansible-option-title

      **backup**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-backup" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`boolean`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.


      .. rst-class:: ansible-option-line

      :ansible-option-choices:`Choices:`

      - :ansible-option-choices-entry-default:`false` :ansible-option-choices-default-mark:`← (default)`
      - :ansible-option-choices-entry:`true`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-content"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-content:

      .. rst-class:: ansible-option-title

      **content**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-content" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`string`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Search for a given \ :emphasis:`xpath`\  and get content.

      This parameter requires \ :emphasis:`xpath`\  to be set.


      .. rst-class:: ansible-option-line

      :ansible-option-choices:`Choices:`

      - :ansible-option-choices-entry:`"attribute"`
      - :ansible-option-choices-entry:`"text"`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-count"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-count:

      .. rst-class:: ansible-option-title

      **count**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-count" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`boolean`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Search for a given \ :emphasis:`xpath`\  and provide the count of any matches.

      This parameter requires \ :emphasis:`xpath`\  to be set.


      .. rst-class:: ansible-option-line

      :ansible-option-choices:`Choices:`

      - :ansible-option-choices-entry-default:`false` :ansible-option-choices-default-mark:`← (default)`
      - :ansible-option-choices-entry:`true`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-input_type"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-input_type:

      .. rst-class:: ansible-option-title

      **input_type**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-input_type" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`string`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Type of input for \ :emphasis:`add\_children`\  and \ :emphasis:`set\_children`\ .


      .. rst-class:: ansible-option-line

      :ansible-option-choices:`Choices:`

      - :ansible-option-choices-entry:`"xml"`
      - :ansible-option-choices-entry-default:`"yaml"` :ansible-option-choices-default-mark:`← (default)`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-insertafter"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-insertafter:

      .. rst-class:: ansible-option-title

      **insertafter**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-insertafter" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`boolean`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Add additional child-element(s) after the last selected element for a given \ :emphasis:`xpath`\ .

      Child elements must be given in a list and each item may be either a string (eg. \ :literal:`children=ansible`\  to add an empty \ :literal:`\<ansible/\>`\  child element), or a hash where the key is an element name and the value is the element value.

      This parameter requires \ :emphasis:`xpath`\  to be set.


      .. rst-class:: ansible-option-line

      :ansible-option-choices:`Choices:`

      - :ansible-option-choices-entry-default:`false` :ansible-option-choices-default-mark:`← (default)`
      - :ansible-option-choices-entry:`true`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-insertbefore"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-insertbefore:

      .. rst-class:: ansible-option-title

      **insertbefore**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-insertbefore" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`boolean`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Add additional child-element(s) before the first selected element for a given \ :emphasis:`xpath`\ .

      Child elements must be given in a list and each item may be either a string (eg. \ :literal:`children=ansible`\  to add an empty \ :literal:`\<ansible/\>`\  child element), or a hash where the key is an element name and the value is the element value.

      This parameter requires \ :emphasis:`xpath`\  to be set.


      .. rst-class:: ansible-option-line

      :ansible-option-choices:`Choices:`

      - :ansible-option-choices-entry-default:`false` :ansible-option-choices-default-mark:`← (default)`
      - :ansible-option-choices-entry:`true`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-namespaces"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-namespaces:

      .. rst-class:: ansible-option-title

      **namespaces**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-namespaces" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`dictionary`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      The namespace \ :literal:`prefix:uri`\  mapping for the XPath expression.

      Needs to be a \ :literal:`dict`\ , not a \ :literal:`list`\  of items.


      .. rst-class:: ansible-option-line

      :ansible-option-default-bold:`Default:` :ansible-option-default:`{}`

      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-path"></div>
        <div class="ansibleOptionAnchor" id="parameter-dest"></div>
        <div class="ansibleOptionAnchor" id="parameter-file"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-dest:
      .. _ansible_collections.middleware_automation.common.xml_module__parameter-file:
      .. _ansible_collections.middleware_automation.common.xml_module__parameter-path:

      .. rst-class:: ansible-option-title

      **path**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-path" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-aliases:`aliases: dest, file`

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`path`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Path to the file to operate on.

      This file must exist ahead of time.

      This parameter is required, unless \ :emphasis:`xmlstring`\  is given.


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-pretty_print"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-pretty_print:

      .. rst-class:: ansible-option-title

      **pretty_print**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-pretty_print" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`boolean`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Pretty print XML output.


      .. rst-class:: ansible-option-line

      :ansible-option-choices:`Choices:`

      - :ansible-option-choices-entry-default:`false` :ansible-option-choices-default-mark:`← (default)`
      - :ansible-option-choices-entry:`true`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-print_match"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-print_match:

      .. rst-class:: ansible-option-title

      **print_match**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-print_match" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`boolean`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Search for a given \ :emphasis:`xpath`\  and print out any matches.

      This parameter requires \ :emphasis:`xpath`\  to be set.


      .. rst-class:: ansible-option-line

      :ansible-option-choices:`Choices:`

      - :ansible-option-choices-entry-default:`false` :ansible-option-choices-default-mark:`← (default)`
      - :ansible-option-choices-entry:`true`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-set_children"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-set_children:

      .. rst-class:: ansible-option-title

      **set_children**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-set_children" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`list` / :ansible-option-elements:`elements=any`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Set the child-element(s) of a selected element for a given \ :emphasis:`xpath`\ .

      Removes any existing children.

      Child elements must be specified as in \ :emphasis:`add\_children`\ .

      This parameter requires \ :emphasis:`xpath`\  to be set.


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-state"></div>
        <div class="ansibleOptionAnchor" id="parameter-ensure"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-ensure:
      .. _ansible_collections.middleware_automation.common.xml_module__parameter-state:

      .. rst-class:: ansible-option-title

      **state**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-state" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-aliases:`aliases: ensure`

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`string`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

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


      .. rst-class:: ansible-option-line

      :ansible-option-choices:`Choices:`

      - :ansible-option-choices-entry:`"absent"`
      - :ansible-option-choices-entry-default:`"present"` :ansible-option-choices-default-mark:`← (default)`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-strip_cdata_tags"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-strip_cdata_tags:

      .. rst-class:: ansible-option-title

      **strip_cdata_tags**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-strip_cdata_tags" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`boolean`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      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.


      .. rst-class:: ansible-option-line

      :ansible-option-choices:`Choices:`

      - :ansible-option-choices-entry-default:`false` :ansible-option-choices-default-mark:`← (default)`
      - :ansible-option-choices-entry:`true`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-validate"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-validate:

      .. rst-class:: ansible-option-title

      **validate**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-validate" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`boolean`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Perform schema validation of the XML input.

      This parameter requires \ :emphasis:`xsd\_path`\  to be set.


      .. rst-class:: ansible-option-line

      :ansible-option-choices:`Choices:`

      - :ansible-option-choices-entry-default:`false` :ansible-option-choices-default-mark:`← (default)`
      - :ansible-option-choices-entry:`true`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-value"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-value:

      .. rst-class:: ansible-option-title

      **value**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-value" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`any`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Desired state of the selected attribute.

      Either a string, or to unset a value, the Python \ :literal:`None`\  keyword (YAML Equivalent, \ :literal:`null`\ ).

      Elements default to no value (but present).

      Attributes default to an empty string.


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-xmlstring"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-xmlstring:

      .. rst-class:: ansible-option-title

      **xmlstring**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-xmlstring" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`string`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      A string containing XML on which to operate.

      This parameter is required, unless \ :emphasis:`path`\  is given.


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-xpath"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-xpath:

      .. rst-class:: ansible-option-title

      **xpath**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-xpath" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`string`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      A valid XPath expression describing the item(s) you want to manipulate.

      Operates on the document root, \ :literal:`/`\ , by default.


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-xsd_path"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__parameter-xsd_path:

      .. rst-class:: ansible-option-title

      **xsd_path**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-xsd_path" title="Permalink to this option"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`path`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Path to the xsd schema file to perform xml validation

      This file must exist ahead of time.

      This parameter is required when \ :emphasis:`validate`\  is true.


      .. raw:: html

        </div>


.. Attributes


.. Notes

Notes
-----

.. note::
   - Use the \ :literal:`--check`\  and \ :literal:`--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 \ :emphasis:`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.

.. Seealso

See Also
--------

.. seealso::

   `Introduction to XPath <https://www.w3schools.com/xml/xpath_intro.asp>`_
       A brief tutorial on XPath (w3schools.com).
   `XPath Reference document <https://developer.mozilla.org/en-US/docs/Web/XPath>`_
       The reference documentation on XSLT/XPath (developer.mozilla.org).

.. Examples

Examples
--------

.. code-block:: yaml+jinja

    
    # 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
      middleware_automation.common.xml:
        path: /foo/bar.xml
        xpath: /business/rating/@subjective
        state: absent

    - name: Set the rating to '11'
      middleware_automation.common.xml:
        path: /foo/bar.xml
        xpath: /business/rating
        value: 11

    # Retrieve and display the number of nodes
    - name: Get count of 'beers' nodes
      middleware_automation.common.xml:
        path: /foo/bar.xml
        xpath: /business/beers/beer
        count: true
      register: hits

    - ansible.builtin.debug:
        var: hits.count

    # Example where parent XML nodes are created automatically
    - name: Add a 'phonenumber' element to the 'business' element
      middleware_automation.common.xml:
        path: /foo/bar.xml
        xpath: /business/phonenumber
        value: 555-555-1234

    - name: Add several more beers to the 'beers' element
      middleware_automation.common.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
      middleware_automation.common.xml:
        path: /foo/bar.xml
        xpath: '/business/beers/beer[text()="Rochefort 10"]'
        insertbefore: true
        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
      middleware_automation.common.xml:
        path: /foo/bar.xml
        xpath: /business/website/validxhtml

    - name: Add an empty 'validatedon' attribute to the 'validxhtml' element
      middleware_automation.common.xml:
        path: /foo/bar.xml
        xpath: /business/website/validxhtml/@validatedon

    - name: Add or modify an attribute, add element if needed
      middleware_automation.common.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
      middleware_automation.common.xml:
        path: /foo/bar.xml
        xpath: /business/website/validxhtml
        content: attribute
      register: xmlresp

    - name: Show an attribute value
      ansible.builtin.debug:
        var: xmlresp.matches[0].validxhtml.validatedon

    - name: Remove all children from the 'website' element (option 1)
      middleware_automation.common.xml:
        path: /foo/bar.xml
        xpath: /business/website/*
        state: absent

    - name: Remove all children from the 'website' element (option 2)
      middleware_automation.common.xml:
        path: /foo/bar.xml
        xpath: /business/website
        set_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'
      middleware_automation.common.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'

    - name: Adding building nodes with floor subnodes from a YAML variable
      middleware_automation.common.xml:
        path: /foo/bar.xml
        xpath: /business
        add_children:
          - building:
              # Attributes
              name: Scumm bar
              location: Monkey island
              # Subnodes
              _:
                - floor: Pirate hall
                - floor: Grog storage
                - construction_date: "1990"  # Only strings are valid
          - building: Grog factory

    # Consider this XML for following example -
    #
    # <config>
    #   <element name="test1">
    #     <text>part to remove</text>
    #   </element>
    #   <element name="test2">
    #     <text>part to keep</text>
    #   </element>
    # </config>

    - name: Delete element node based upon attribute
      middleware_automation.common.xml:
        path: bar.xml
        xpath: /config/element[@name='test1']
        state: absent




.. Facts


.. Return values

Return Values
-------------
Common return values are documented :ref:`here <common_return_values>`, the following are the fields unique to this module:

.. rst-class:: ansible-option-table

.. list-table::
  :width: 100%
  :widths: auto
  :header-rows: 1

  * - Key
    - Description

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="return-actions"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__return-actions:

      .. rst-class:: ansible-option-title

      **actions**

      .. raw:: html

        <a class="ansibleOptionLink" href="#return-actions" title="Permalink to this return value"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`dictionary`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      A dictionary with the original xpath, namespaces and state.


      .. rst-class:: ansible-option-line

      :ansible-option-returned-bold:`Returned:` success

      .. rst-class:: ansible-option-line
      .. rst-class:: ansible-option-sample

      :ansible-option-sample-bold:`Sample:` :ansible-rv-sample-value:`{"namespaces": ["namespace1", "namespace2"], "state=present": null, "xpath": "xpath"}`


      .. raw:: html

        </div>


  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="return-backup_file"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__return-backup_file:

      .. rst-class:: ansible-option-title

      **backup_file**

      .. raw:: html

        <a class="ansibleOptionLink" href="#return-backup_file" title="Permalink to this return value"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`string`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      The name of the backup file that was created


      .. rst-class:: ansible-option-line

      :ansible-option-returned-bold:`Returned:` when \ :emphasis:`backup=true`\ 

      .. rst-class:: ansible-option-line
      .. rst-class:: ansible-option-sample

      :ansible-option-sample-bold:`Sample:` :ansible-rv-sample-value:`"/path/to/file.xml.1942.2017-08-24@14:16:01~"`


      .. raw:: html

        </div>


  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="return-count"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__return-count:

      .. rst-class:: ansible-option-title

      **count**

      .. raw:: html

        <a class="ansibleOptionLink" href="#return-count" title="Permalink to this return value"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`integer`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      The count of xpath matches.


      .. rst-class:: ansible-option-line

      :ansible-option-returned-bold:`Returned:` when parameter 'count' is set

      .. rst-class:: ansible-option-line
      .. rst-class:: ansible-option-sample

      :ansible-option-sample-bold:`Sample:` :ansible-rv-sample-value:`2`


      .. raw:: html

        </div>


  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="return-matches"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__return-matches:

      .. rst-class:: ansible-option-title

      **matches**

      .. raw:: html

        <a class="ansibleOptionLink" href="#return-matches" title="Permalink to this return value"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`list` / :ansible-option-elements:`elements=string`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      The xpath matches found.


      .. rst-class:: ansible-option-line

      :ansible-option-returned-bold:`Returned:` when parameter 'print\_match' is set


      .. raw:: html

        </div>


  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="return-msg"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__return-msg:

      .. rst-class:: ansible-option-title

      **msg**

      .. raw:: html

        <a class="ansibleOptionLink" href="#return-msg" title="Permalink to this return value"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`string`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      A message related to the performed action(s).


      .. rst-class:: ansible-option-line

      :ansible-option-returned-bold:`Returned:` always


      .. raw:: html

        </div>


  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="return-xmlstring"></div>

      .. _ansible_collections.middleware_automation.common.xml_module__return-xmlstring:

      .. rst-class:: ansible-option-title

      **xmlstring**

      .. raw:: html

        <a class="ansibleOptionLink" href="#return-xmlstring" title="Permalink to this return value"></a>

      .. rst-class:: ansible-option-type-line

      :ansible-option-type:`string`

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      An XML string of the resulting output.


      .. rst-class:: ansible-option-line

      :ansible-option-returned-bold:`Returned:` when parameter 'xmlstring' is set


      .. raw:: html

        </div>



..  Status (Presently only deprecated)


.. Authors

Authors
~~~~~~~

- Tim Bielawa (@tbielawa)
- Magnus Hedemark (@magnus919)
- Dag Wieers (@dagwieers)
- Guido Grazioli (@ggraziol)



.. Extra links


.. Parsing errors