Manipulating XML files with XPath strings in IBM UrbanCode Deploy

XML XPath

I’m learning that people really want to manipulate XML files with their IBM UrbanCode Deploy servers! We get so many questions about the Update XML With XPath automation step (both through the forum and through direct contact) that I wrote an article about some common things that come up when people want to edit XML files as part of their deployment automation: Using the Update XML with Xpath step.

… and we still get a ton of XPath questions!

The most common use case seems to be a server configuration that needs an edit when a new application or version of an application gets deployed. However, this step can edit just about any XML file, though there are some gotchas and idiosyncrasies that are listed in the article. (I might go into some detail about those in a later post.)

The basics are pretty simple: first, you give the step the name and location of an XML file or files. Then you give it some rules for changes to make in the XML file. To tell the step to change some text, for example, you give it an XPath string that points to the text, then a little text “arrow” (->), and then the new text.

For example, here’s some sample XML from the article:

<?xml version="1.0" encoding="UTF-8"?>
<testFile>
  <myData>
    <data name="filePath" value="/opt/sampleDirectory"/>
    <data name="textData">Here is some text.</data>
    <data att1="one" att2="two" name="attributes" value="something"/>
  </myData>
</testFile>

To change an attribute value, you use an XPath string that points to that attribute, and then you put in the new text. For example, to change the “/opt/sampleDirectory” to “/usr/otherDirectory”, put this in the Replace with text field:

//testFile/myData/data[@value]/@value->/usr/otherDirectory

To change the text of a node, refer to it as “text()”, for example:

//testFile/myData/data[@name='textData']/text()->Some new text content.

Run both of those operations and the XML looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<testFile>
  <myData>
    <data name="filePath" value="/usr/otherDirectory"/>
    <data name="textData">Some new text content.</data>
    <data att1="one" att2="two" name="attributes" value="something"/>
  </myData>
</testFile>

There are also steps to add and remove XML nodes.

Got an unusual file that you need to make changes to as part of your deployment automation? Keep the XPath questions coming in the forum and we’ll answer as many as we can.

Using the Update XML with Xpath step

Overview

We get a lot of forum questions about the use of the Update XML with Xpath step of the File Utils plugin, so I figured I’d post some examples to help people along. It’s a very useful step because it can update XML files on the fly, which is great for changing configurations on a deployment.

To use this step, make sure you’ve got the File Utils automation plugin installed. You can use this step in any component process or generic process.

To use this step, you’ll need a basic knowledge of XPath, which is how you specify where to add, remove, or change the XML code. There are lots of resources out there for learning XPath, but here’s a good one: http://www.w3schools.com/xpath/

For full details on the File Utils plugin and the Update XML with XPath step, see its documentation page. In short, this step has several fields in which you can specify changes to XML files:

Insert XML: This field adds XML nodes to the document. You specify one or more XPath expression -> content pairs, separated by newlines. The XPath expression points to the parent node, and the content is inserted under that node.
Remove: This field removes elements or attributes to remove. You specify one or more XPath expressions and the step removes the matching elements.
Replace with text: This field replaces the content of text nodes or attributes with new text. You specify one or more XPath expression -> content pairs, separated by newlines. The XPath expression points to the parent node or attribute, and the content is inserted in that node or attribute.
Set Attributes: This field updates the attributes that you specify, similar to the Replace with text field. You specify one or more expression -> content pairs, separated by newlines. The XPath expression points to one or more attributes, and the content becomes the new value of that attribute.

Here’s a picture of the step properties, which include each of the above fields. To use it, open a component process or generic process and drag the Update XML with Xpath step to the process.

Use cases

Here are some common use cases of the step. I’ll use the following example XML file in these use cases:

<?xml version="1.0" encoding="UTF-8"?>
<testFile>
<myData>
<data name="filePath" value="/opt/sampleDirectory"/>
<data name="textData">Here is some text.</data>
<data att1="one" att2="two" name="attributes" value="something"/>
</myData>
</testFile>

Use case 1: Inserting XML nodes

To insert XML nodes, specify the parent of the new node with XPath code. For example, to add a new <data> node next to the existing nodes, I specify the parent of the <data> nodes. The Insert XML field of the Update XML File with XPath step looks like this:

//testFile/myData-><data name="myNewData"/>

The updated file has the new <data> node:

<?xml version="1.0" encoding="UTF-8"?><testFile>
<myData>
<data name="filePath" value="/opt/sampleDirectory"/>
<data name="textData">Here is some text.</data>
<data att1="one" att2="two" name="attributes" value="something"/>
<data name="myNewData"/>
</myData>
</testFile>

The step can also accept more complicated XPath expressions. For example, you can use an XPath predicate to specify a node with a certain attribute. The following code inserts a node under the <data> node that has the attribute name="filePath":

//testFile/myData/data[@name='filePath']-><info/>