The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.

For a list of other such plugins, see the Pipeline Steps Reference page.

XML Editor

View this plugin on the Plugins site

xmlEditBuilder: Edit XML file

Applies a list of operations to an XML file, to all files matching a pattern, or to XML text. Only the modified nodes change: formatting, comments, quotes, attribute order, encoding, byte order mark and line endings are preserved byte for byte. If any operation fails (on any file), nothing is written. The result includes the previous values of what was changed. Environment variables such as $VERSION are expanded in all fields.
  • file : String
    Path of the XML file to edit, relative to the current directory of the workspace (it cannot point outside the workspace). Use exactly one of file or files: setting both is an error.
  • operations
    Operations applied in order: setText, upsert, setAttribute, removeAttribute, addElement, remove. Each one sees the result of the previous ones.
      Array / List of Nested Choice of Objects
    • addElement
      Inserts an XML fragment relative to the selected elements, indented like its new siblings.
      • xpath : String
        XPath 1.0 expression.
      • fragment : String
        Well-formed XML: one or more elements, comments or text. A fragment written on one line is laid out like the document; a multi-line fragment keeps its own relative indentation. Unprefixed elements belong to the namespace in scope at the insertion point.
      • expected : String (optional)
        How many nodes the XPath must match: AT_LEAST_ONE (default), ONE, ANY (zero is fine) or an exact number such as 2. If the count does not match, the step fails and the file is not written.
      • position : String (optional)
        LAST_CHILD (default), FIRST_CHILD, BEFORE or AFTER the selected element.
    • removeAttribute
      Removes an attribute from the selected elements, when present.
      • xpath : String
        XPath 1.0 expression.
      • name : String
        Name of the attribute to remove.
      • expected : String (optional)
        How many nodes the XPath must match: AT_LEAST_ONE (default), ONE, ANY (zero is fine) or an exact number such as 2. If the count does not match, the step fails and the file is not written.
    • remove
      Removes the selected elements, attributes, comments or text nodes. A node alone on its line is removed together with its line. The root element cannot be removed.
      • xpath : String
        XPath 1.0 expression.
      • expected : String (optional)
        How many nodes the XPath must match: AT_LEAST_ONE (default), ONE, ANY (zero is fine) or an exact number such as 2. If the count does not match, the step fails and the file is not written.
    • setAttribute
      Adds or updates an attribute on the selected elements. Existing attributes keep their quotes and position; new ones follow the layout of the existing attributes.
      • xpath : String
        XPath 1.0 expression.
      • name : String
        Attribute name, optionally prefixed with a namespace prefix declared in the document.
      • value : String
        Attribute value (escaped for you).
      • expected : String (optional)
        How many nodes the XPath must match: AT_LEAST_ONE (default), ONE, ANY (zero is fine) or an exact number such as 2. If the count does not match, the step fails and the file is not written.
    • setText
      Sets the text of the selected elements (which must not contain child elements), the value of selected attributes, or replaces selected text nodes. Values are escaped automatically.
      • xpath : String
        XPath 1.0 expression.
      • value : String
        New text. Characters like < and & are escaped for you.
      • expected : String (optional)
        How many nodes the XPath must match: AT_LEAST_ONE (default), ONE, ANY (zero is fine) or an exact number such as 2. If the count does not match, the step fails and the file is not written.
    • upsert
      Sets the value of the selected elements, attributes or text nodes like Set text; when the XPath matches nothing, creates the missing elements (and the final attribute) under the deepest existing element. To create nodes the XPath must be an absolute path of element names such as /Project/PropertyGroup/Version, optionally with [@attribute='value'] predicates (the attributes are created too) and a final /@attribute step. The root element is never created.
      • xpath : String
        XPath of the node to update, e.g. /project/properties/revision or /configuration/appSettings/add[@key='Env']/@value.
      • value : String
        New value (escaped for you).
      • expected : String (optional)
        How many nodes the XPath must match. Default for upsert: ANY (zero means "create"). Other values: ONE, AT_LEAST_ONE or an exact number.
  • dryRun : boolean (optional)
    Run all operations and show the diff, but do not write any file.
  • excludes : String (optional)
    Ant pattern(s) of files to leave out when using files.
  • files : String (optional)
    Ant pattern(s), comma separated, selecting several files to edit with the same operations, e.g. **/*.csproj. All files are edited in memory first: if an operation fails on any file, no file is written. expected is checked for each file. Use exactly one of file or files: setting both is an error.
  • maxSizeMb : int (optional)
    Files larger than this are refused (default 50 MB).
  • namespaces : String (optional)
    Namespace prefixes for XPath, one per line, e.g. m=http://maven.apache.org/POM/4.0.0. Prefixes declared in the document can be used without configuration. Binding a prefix to the default namespace of the document switches to standard XPath rules.
  • outputFile : String (optional)
    Write the result to this file (relative to the workspace) and leave the original untouched.
  • showDiff : boolean (optional)
    Print a unified diff of the changes in the build log. Disable it if the file contains secrets.
  • strictNamespaces : boolean (optional)
    By default the default namespace of the document is transparent: /project/version works on a Maven POM even though it declares xmlns="http://maven.apache.org/POM/4.0.0". Enable this option to apply standard XPath 1.0 rules; elements in the default namespace then need a prefix declared with namespaces. Binding a prefix to the default namespace URI with namespaces enables standard rules automatically.

xmlValidateBuilder: Validate XML file

Fails the build when the XML file is malformed or does not conform to the XSD.
  • file : String
    Path of the XML file, relative to the current directory of the workspace (it cannot point outside the workspace). The file is read and processed on the agent that holds it.
  • maxSizeMb : int (optional)
    Files larger than this are refused (default 50 MB).
  • schema : String (optional)
    XSD file in the workspace. xs:include/xs:import are resolved only from files inside the workspace; remote locations are refused.

xmlEdit: Edit XML files (lossless)

Applies a list of operations to an XML file, to all files matching a pattern, or to XML text. Only the modified nodes change: formatting, comments, quotes, attribute order, encoding, byte order mark and line endings are preserved byte for byte. If any operation fails (on any file), nothing is written. The result includes the previous values of what was changed.
  • operations
    Operations applied in order: setText, upsert, setAttribute, removeAttribute, addElement, remove. Each one sees the result of the previous ones.
      Array / List of Nested Choice of Objects
    • addElement
      Inserts an XML fragment relative to the selected elements, indented like its new siblings.
      • xpath : String
        XPath 1.0 expression.
      • fragment : String
        Well-formed XML: one or more elements, comments or text. A fragment written on one line is laid out like the document; a multi-line fragment keeps its own relative indentation. Unprefixed elements belong to the namespace in scope at the insertion point.
      • expected : String (optional)
        How many nodes the XPath must match: AT_LEAST_ONE (default), ONE, ANY (zero is fine) or an exact number such as 2. If the count does not match, the step fails and the file is not written.
      • position : String (optional)
        LAST_CHILD (default), FIRST_CHILD, BEFORE or AFTER the selected element.
    • removeAttribute
      Removes an attribute from the selected elements, when present.
      • xpath : String
        XPath 1.0 expression.
      • name : String
        Name of the attribute to remove.
      • expected : String (optional)
        How many nodes the XPath must match: AT_LEAST_ONE (default), ONE, ANY (zero is fine) or an exact number such as 2. If the count does not match, the step fails and the file is not written.
    • remove
      Removes the selected elements, attributes, comments or text nodes. A node alone on its line is removed together with its line. The root element cannot be removed.
      • xpath : String
        XPath 1.0 expression.
      • expected : String (optional)
        How many nodes the XPath must match: AT_LEAST_ONE (default), ONE, ANY (zero is fine) or an exact number such as 2. If the count does not match, the step fails and the file is not written.
    • setAttribute
      Adds or updates an attribute on the selected elements. Existing attributes keep their quotes and position; new ones follow the layout of the existing attributes.
      • xpath : String
        XPath 1.0 expression.
      • name : String
        Attribute name, optionally prefixed with a namespace prefix declared in the document.
      • value : String
        Attribute value (escaped for you).
      • expected : String (optional)
        How many nodes the XPath must match: AT_LEAST_ONE (default), ONE, ANY (zero is fine) or an exact number such as 2. If the count does not match, the step fails and the file is not written.
    • setText
      Sets the text of the selected elements (which must not contain child elements), the value of selected attributes, or replaces selected text nodes. Values are escaped automatically.
      • xpath : String
        XPath 1.0 expression.
      • value : String
        New text. Characters like < and & are escaped for you.
      • expected : String (optional)
        How many nodes the XPath must match: AT_LEAST_ONE (default), ONE, ANY (zero is fine) or an exact number such as 2. If the count does not match, the step fails and the file is not written.
    • upsert
      Sets the value of the selected elements, attributes or text nodes like Set text; when the XPath matches nothing, creates the missing elements (and the final attribute) under the deepest existing element. To create nodes the XPath must be an absolute path of element names such as /Project/PropertyGroup/Version, optionally with [@attribute='value'] predicates (the attributes are created too) and a final /@attribute step. The root element is never created.
      • xpath : String
        XPath of the node to update, e.g. /project/properties/revision or /configuration/appSettings/add[@key='Env']/@value.
      • value : String
        New value (escaped for you).
      • expected : String (optional)
        How many nodes the XPath must match. Default for upsert: ANY (zero means "create"). Other values: ONE, AT_LEAST_ONE or an exact number.
  • dryRun : boolean (optional)
    Run all operations and show the diff, but do not write any file.
  • excludes : String (optional)
    Ant pattern(s) of files to leave out when using files.
  • file : String (optional)
    Path of the XML file to edit, relative to the current directory of the workspace (it cannot point outside the workspace). Use exactly one of file, files or text: setting more than one is an error.
  • files : String (optional)
    Ant pattern(s), comma separated, selecting several files to edit with the same operations, e.g. **/*.csproj. All files are edited in memory first: if an operation fails on any file, no file is written. expected is checked for each file. Use exactly one of file, files or text: setting more than one is an error.
  • maxSizeMb : int (optional)
    Files larger than this are refused (default 50 MB).
  • namespaces (optional)
    Additional namespace prefixes for XPath, e.g. namespaces: [m: 'http://maven.apache.org/POM/4.0.0']. Prefixes declared in the document can be used without configuration.
    • Type: java.util.Map<java.lang.String, java.lang.String>
  • outputFile : String (optional)
    Write the result to this file (relative to the workspace) and leave the original untouched.
  • showDiff : boolean (optional)
    Print a unified diff of the changes in the build log. Disable it if the file contains secrets.
  • strictNamespaces : boolean (optional)
    By default the default namespace of the document is transparent: /project/version works on a Maven POM even though it declares xmlns="http://maven.apache.org/POM/4.0.0". Enable this option to apply standard XPath 1.0 rules; elements in the default namespace then need a prefix declared with namespaces. Binding a prefix to the default namespace URI with namespaces enables standard rules automatically.
  • text : String (optional)
    XML text to edit in memory instead of a file (no workspace needed). The edited XML is returned as text in the result map: def r = xmlEdit text: xml, operations: [...]; echo r.text. Use exactly one of file, files or text: setting more than one is an error.

xmlQuery: Query an XML file with XPath

Evaluates an XPath expression on an XML file and returns its value. Example: def v = xmlQuery file: 'pom.xml', xpath: '/project/version'
  • xpath : String
    XPath 1.0 expression, e.g. /project/version, //dependency/artifactId or count(//testcase[failure]).
  • defaultValue : String (optional)
    With STRING, the value returned when the XPath matches nothing, instead of failing. It takes precedence over failIfNotFound.
  • failIfNotFound : boolean (optional)
    With STRING, fail when nothing matches (default). When disabled the step returns null.
  • file : String (optional)
    Path of the XML file, relative to the current directory of the workspace (it cannot point outside the workspace). The file is read and processed on the agent that holds it. Use exactly one of file or text: setting both is an error.
  • maxSizeMb : int (optional)
    Files larger than this are refused (default 50 MB).
  • namespaces (optional)
    Additional namespace prefixes for XPath, e.g. namespaces: [m: 'http://maven.apache.org/POM/4.0.0']. Prefixes declared in the document can be used without configuration.
    • Type: java.util.Map<java.lang.String, java.lang.String>
  • returnType : String (optional)
    STRING (value of the first node, default), LIST (values of all nodes), NUMBER or BOOLEAN.
  • strictNamespaces : boolean (optional)
    By default the default namespace of the document is transparent: /project/version works on a Maven POM even though it declares xmlns="http://maven.apache.org/POM/4.0.0". Enable this option to apply standard XPath 1.0 rules; elements in the default namespace then need a prefix declared with namespaces. Binding a prefix to the default namespace URI with namespaces enables standard rules automatically.
  • text : String (optional)
    XML given as text instead of a file. Use exactly one of file or text: setting both is an error.

xmlRead: Read an XML file into maps and lists

Reads an XML file into maps and lists: elements with only text become strings, attributes use the key @name, repeated elements become lists. Example: def pom = xmlRead file: 'pom.xml'; echo pom.version
  • file : String (optional)
    Path of the XML file, relative to the current directory of the workspace (it cannot point outside the workspace). The file is read and processed on the agent that holds it. Use exactly one of file or text: setting both is an error.
  • maxSizeMb : int (optional)
    Files larger than this are refused (default 50 MB).
  • namespaces (optional)
    Additional namespace prefixes for XPath, e.g. namespaces: [m: 'http://maven.apache.org/POM/4.0.0']. Prefixes declared in the document can be used without configuration.
    • Type: java.util.Map<java.lang.String, java.lang.String>
  • strictNamespaces : boolean (optional)
    By default the default namespace of the document is transparent: /project/version works on a Maven POM even though it declares xmlns="http://maven.apache.org/POM/4.0.0". Enable this option to apply standard XPath 1.0 rules; elements in the default namespace then need a prefix declared with namespaces. Binding a prefix to the default namespace URI with namespaces enables standard rules automatically.
  • text : String (optional)
    XML given as text instead of a file. Use exactly one of file or text: setting both is an error.
  • xpath : String (optional)
    Optional XPath selecting the element to convert (the first match). By default the root element is converted.

xmlValidate: Validate an XML file (well-formedness, XSD)

Checks that an XML file is well-formed and, when a schema is given, valid against an XSD. Returns [valid: ..., errors: [[line:, column:, severity:, message:]]].
  • failOnError : boolean (optional)
    Fail the build when the file is not valid (default). When disabled, inspect the returned map.
  • file : String (optional)
    Path of the XML file, relative to the current directory of the workspace (it cannot point outside the workspace). The file is read and processed on the agent that holds it. Use exactly one of file or text: setting both is an error.
  • maxSizeMb : int (optional)
    Files larger than this are refused (default 50 MB).
  • schema : String (optional)
    XSD file in the workspace. xs:include/xs:import are resolved only from files inside the workspace; remote locations are refused.
  • text : String (optional)
    XML given as text instead of a file. Use exactly one of file or text: setting both is an error.

Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

    


See existing feedback here.