Dynamically creating a property

There are times in a deployment process that you may want to create a property dynamically and use it in a later process step.  Fortunately, Urbancode Deploy provides a mechanism to do this.

Let’s use the following scenario.  As part of your process, you want to create a tar file backup of a directory structure.  You wish to create a tar filename that includes a date stamp.  You therefore have to get the current date and time and format it to your liking. Here is how to do it.

First, create a Groovy process step.  There is a Groovy plugin that allows you to create Groovy scripts and have them executed as a process step.   We will use a simple script like below to grab the date and time and format it.

import java.text.SimpleDateFormat
def today = new Date()
def formattedDate = new SimpleDateFormat("ddMMyyyy, Ka").format(today)

The Groovy step will look like this:


Notice the name of the Groovy step as we will use it later.

Also, notice the last line of the Groovy script. This exports the formattedDate as a property.  We can now use that property in subsequent steps.

To reference this property, use the following syntax:


“set-date” is the name of the step that set the property and “date” is the property name.  You can now use this variable to create your tar file, maybe like this:

tar cvf /tmp/${p:set-date/date}.tar .


Updating a plugin – the upgrade.xml file

When updating a plugin, the update process that the uDeploy server goes through is to scan every process that has been created on the server (component and generic) and upgrade any step that is provided by the plugin that you are upgrading.  The upgrade.xml file tells the uDeploy server how to update a step or a property.


Included at the bottom is the XSD file that defines the upgrade.xml file.

1.  Update a script – if there are no changes to the plugin.xml file (no API changes) but you simply want to update one of the scripts that are run that implement the logic of a step, no change is required to any of the plugin configuration files.  You can simply reload the plugin zip file and the scripts will be replaced.
Note:  Probably not a good practice to follow.  If you are updating your “official” plugin, update the revision number.

2. Propagating a step to the next version – any time you upgrade a plugin, you must include a <migrate-command> element for every step that you want to include in the new version.

<migrate to-version="7">
    <migrate-command name="Step Name"/>

3.  Deleting a step – if you want to delete a step, then simply don’t include a <migrate-command> element for that step.

4.  Adding a step – you don’t need to do anything in the upgrade.xml file for this new step as there is nothing to upgrade.  The process of applying the new plugin will add the new step.

5.  Rename a step – the <migrate-command> element provides a way to rename a step by including an “old” attribute.

<migrate to-version="7">
    <migrate-command name="New Step Name" old="Old Step Name"/>

6.  Adding a step property – there a few situations here that need to be taken into consideration.

a.  if you are adding a new property that does not have a default value, then obviously your script will have to take that into account.  In this situation, you don’t need to do anything special to the upgrade.xml file as long as you have a <migrate-command> element for the property’s step.  All existing process steps will get the new property but since there is no default value there is no need to migrate any existing properties.   If the new property is required, you will be asked to enter a value when the process is requested.

b.  If you are adding a new property that does have a default value, required or not, then you should add a <migrate-properties> element as follows.  This will insure that the properties of any existing use of the step will get migrated and the default value of the property will get assigned to the new property.  If you don’t include the <migrate-properties> element, the default value will not be applied to the property as no property migration will occur.  This will be a problem if your script assumes a default value.

<migrate to-version="7">
   <migrate-command name="Step Name">
         <migrate-property name="New Property Name" default="New Property Default Value" />

7.  Deleting a step property – nothing needs to be done in the upgrade.xml if you are deleting a step property.  The process of upgrading the plugin will remove the property as long as you have a <migrate-command> element to migrate the step.

8.  Renaming a step property – a capability similar to renaming a step exists to rename a step property using the <migrate-properties> element.

<migrate to-version="7">
   <migrate-command name="Step Name">
         <migrate-property name="New Property Name" old="Old Property Name" />

9.  Changing a step property’s default value – the <migrate-property> element is also used to change its default value.

<migrate to-version="7">
   <migrate-command name="Step Name">
         <migrate-property name="Property Name" default="New Default Value" />

10.  Steps 9 and 10 can be combined if you are both renaming a property and re-defining its default value.

<migrate to-version="7">
   <migrate-command name="Step Name">
         <migrate-property name="New Property Name" old="Old Property Name" default="New Default Value" />


A New Plugin – Send an Email in a Process Step

I was asked by a customer if Urbancode Deploy could send a generic email as part of the deploy process.  Urbancode Deploy has notification capabilities but it relies on the notification schemes that are built in.  You can’t simply add a step in a process to send an email.

So I set out to write a plugin to accomplish this.  Whenever I tackle a new “programming” exercise, I always resort to two principles.  1)  Google to find what others have already done.  And 2)  reuse anything you already have at your disposal.

Urbancode Deploy already takes advantage of an SMTP server to be able to send emails, and you specify the SMTP settings on the System Settings page.


So the first problem to solve is how to get at these values.  Here is where reuse comes in. There is an existing Urbancode plugin that accomplishes this.  The Udeploy-System plugin has a task that gets all of the System Configuration information, which includes the SMTP server values.  So the first step is to tear apart this plugin and learn how it gets the information.  It turns out there is a Rest Client jar file that implements a call to get the Urbancode Deploy system configuration.  So I copied most of the Udeploy-System plugin contents into my plugin so I could reuse it.

The second problem then is how to send an email.  A quick Google search for “Groovy script to send email” produced numerous results that I could easily steal re-use.  And to actually carry out the sending of the email, I had to go and grab JavaMail mail.jar and its corresponding activation.jar and put them in the lib directory of the plugin.

The resulting plugin works great.  There are three parameters that the step takes, the recipient list, the email subject, and the email body.


Here is the resulting Groovy script that I came up with.  Note that this version does not deal with authentication as most SMTP servers don’t require it, but I am sure it is an easy addition.



The above link is the code content in a Word doc.

Give it a try.

Using the Chrome developer tools to view uDeploy REST API

As I mentioned in my previous post, a good way to interrogate the REST API for IBM Urbancode Deploy is to observe the network traffic between the Urbancode Deploy GUI and server.  This can be done using the Chrome browser developer tools.

In your Urbancode Deploy tab in Chrome, open the developer tools console via the Chrome menu, select Tools -> Developer tools

10-7-2013 10-43-42 AM

You now get the console at the bottom of your window.  Select the Network tab.  At the bottom you can clear the collected events.

10-7-2013 10-47-40 AM

Now, exercise the Urbancode Deploy web interface and the Chrome developer tools will capture all network traffic between Chrome and the Urbancode Deploy server.  In this example, I changed one of the source config parameters of a component.  You see the first entry in the Network tab shows the REST PUT call.

10-7-2013 10-50-40 AM

By clicking on the row, you can get both the request and return json payloads and can examine their content.

10-7-2013 10-52-54 AM

This is a quick and dirty way to learn the available REST API calls in Urbancode Deploy.


The uDeploy REST API

If you use IBM Urbancode Deploy (as uDeploy is now called) at all, you will notice its simplicity.  And rightly so as a deployment automation tool should not re-invent the way deployment automation is done.  Urbancode Deploy simply organizes and collects deployment processes and steps.  Once a deployment is successful, any good deployment automation solution should be able to repeat that deployment over and over again with no trouble.

On the other hand, the integrations with other tools, both as a consumer and a producer, provide the real value.  And a valuable part of Urbancode Deploy’s integration capabilities is its REST API.  There are 3 ways to get information about the API.

1) The documentation – this is unfortunately not your best bet.  It is out of date and lacks a lot of necessary detail.

2) The Application WADL file – it does exists in the uDeploy server folder structure.  But it is hard to decipher and also leaves out the json details.

3)  Browser development tools – This is the method that has been the most successful for me.  I use Chrome and its developer tools allow you to see the network traffic occuring as  you navigate the uDeploy web pages.  The uDeploy user interface heavily utilizes the REST API.  But capturing the network traffic as you navigate, you can see the specific rest calls that are occuring and examine the json payload both in and out.


I sought to build something that exercises the uDeploy REST API.  What I came up with is an example of how you can solve a common uDeploy requirement.  The process of onboarding an application to uDeploy involves many mouse clicks and an understanding of how to navigate the user interface.  As I said above, the concepts are easy once you understand them, but to onboard thousands of applications does not scale if you use the user interface.  Plus you must train people on how to get their applications into uDeploy.

So I built a small website that captures some basic information about an application, its components, and its environments, and does the bulk of the setup work in uDeploy via the REST APIs.   I wanted to be able to capture the information in a way that a development team would understand yet not need to know anything about uDeploy and its structure.

You can see a demo of this sample application at this link:  http://www.youtube.com/watch?v=qr3bdCJykEk.

10-3-2013 2-53-54 PM

I would welcome any feedback.