IBM UrbanCode Deploy Automation Plugin Development

IBM UrbanCode Deploy provides us with two types of plugins: source plugins and automation plugins. These plugins allow us to integrate with a wide variety of tools such as middleware tools, databases, and servers. Both plugin types are made up of one or more steps that are executed by IBM UrbanCode Deploy to perform a certain unit of functionality. Source plugins are used to import artifacts and to create component versions; they only have a single step called the Import Version. Automation plugins, on the other hand, are the building blocks of any deployment process. IBM UrbanCode Deploy ships with many prebuilt automation steps and plugins allow us to create our own. In this article, you will find everything you need to know in order to create your own automation plugins.

Creating a Plugin 

In order to create an automation plugin, you will need to create three XML configuration files: a plugin.xml, info.xml, and upgrade.xml. You will most likely create a script file containing your plugin logic, but we will get to that. Let's first have a look at these three main files.

1. Info.XML

The info.xml contains the release version, release notes, and other properties that describe the plugin. There are three required elements: <author>, <integration>, and <release-notes>. The author describes the author’s info like name, email, etc. Integration determines the type of plugin and has four possible options: Source (source configuration plugins), Artifact (plugins retrieving artifacts from a repository), Deploy (plugins that deploy to a server), Automation (plugins for other automation tasks).

The Release notes element should contain notes for the current and previous version of the plugin.

The <release-version> element is for display only, whereas the release note’s plugin-version attribute must match the version specified in the plugin.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<pluginInfo>
    <author name="Jaco Botha">
        <organization/>
        <email/>
        <website/>
        <bio/>
    </author>
    <integration type="Automation"/>
    <release-version>0.1</release-version>
    <release-notes>
        <release-note plugin-version="1">
            Initial Release
        </release-note>
    </release-notes>
</pluginInfo>

2. Plugin.XML

The plugin.xml consists of two main parts the <header> and one or more <step-type> elements.

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://www.urbancode.com/PluginXMLSchema_v1"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <header>
        <identifier id="plugin_id" version="version_number" name="Plug-in Name"/>
        <description/>
        <tag>Plugin type/Plugin subtype/Plugin name</tag>
    </header>
    <step-type name="Step_Name">
        <description/>
        <properties>
            <property name="property_name" required="true">
                <property-ui type="textBox" label="Property Name"
                             description="Property Name"
                             default-value="Property Name"/>
            </property>
        </properties>
        <command program="${path_to_tool}">
            <arg value="${parameters_passed_to_tool}"/>
            <arg path="${path_parameters_passed_to_tool}"/>
            <arg file="${command_to_run}"/>
            <arg file="${PLUGIN_INPUT_PROPS}"/>
            <arg file="${PLUGIN_OUTPUT_PROPS}"/>
        </command>
        <post-processing>
            <![CDATA[
                if (properties.get("exitCode") != 0) {
                    properties.put(new java.lang.String("Status"),
                        new java.lang.String("Failure"));
                } else {
                    properties.put("Status", "Success");
                }
            ]]>
        </post-processing>
    </step-type>
</plugin>

Header Element

The <header> element has three main child elements: <identifier>, <description>, and <tag>. The identifier specifies the plugin ID, name, and version. The description describes the plugin and is visible in IBM UrbanCode Deploy. As for the tag, it defines the plugin location within the process editor.

Step Type Element

A basic <step-type> element consists of a step name and four child elements; <description>, <properties>, <command> and <post-processing>. You can create multiple steps for each plugin, each will be available in IBM UrbanCode Deploy process editor.

• Description: The description provides a description in the IBM UrbanCode Deploy process editor. You can customize the icon of your step, by starting your description with one of the following keywords as mentioned in the documentation.
• Properties: A property tag has a mandatory name attribute, optional required attribute and two possible child elements <property-ui>and <value>. The <property-ui> element is used to define the property label, description, default-value, and type. There are five available types; textBox, textAreaBox, secureBox, checkBox, and selectBox.

When using the selectBox type, you have to specify one or more <value> elements, within the property. These elements require a mandatory label attribute, used for display purposes as well as a value.

• Command: The <command> element is where you define the actual executable. There is one mandatory attribute program, and multiple child <arg> elements. The program attribute can be any tool or interpreter installed on the host. The three available types of arg’s are value, path and file. Within one of the file args, you will specify the "${PLUGIN_INPUT_PROPS}", which is a file containing all the property values, captures in the process editor.
• Post-Processing: The post-processing script is run after the command in order of the steps output properties and to provide error handling. Unlike the command that will accept a script written in any language, the post-processing script needs to be valid JavaScript 1.7.

There's a number of objects that can be leveraged by the script worth mentioning. The properties object (which contains all the input properties), the scanner object (which allows you to read content from the steps output log), as well as the commandOut object that allows you to write to the log.

Within the post-processing script, you must set the Status property; if the property is set to Success, the step will be indicated as successfully completed. The exitCode property is often examined to determine the status.

3. Upgrade.XML

The Upgrade XML file is only needed when you update the signature of a step after the plugin has been deployed to IBM UrbanCode Deploy. If you make changes to the info.xml or any of your custom scripts, the upgrade.xml is not needed; simply re-zip your plugin and upload it. Consider the following scenario: in v1 of the plugin.xml, your step was called MyStep. You then update the step name to a more meaningful one MyUpdatedStep, IBM UrbanCode Deploy then needs a way of updating the existing instances of your plugin to instead use the new name of your step, this is where the upgrade.xml comes in.

For every change to the plugin.xml (API changes), you will also have to increment the version.

There are three elements worth mentioning, <migrate>, <migrate-command>, and <migrate-property>. The migrate element requires a two-version attribute whereas the migrate command and migrate property elements both have two attributes; name and old to allow you to rename the step or property.

<?xml version="1.0" encoding="UTF-8"?>
<plugin-upgrade
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="http://www.urbancode.com/UpgradeXMLSchema_v1">
    <migrate to-version="New plugin.xml Version">
        <migrate-command name="New Step Name" old="Old Step Name">
            <migrate-properties>
                <migrate-property name="New Property Name" old="Old Property Name" />
            </migrate-properties>
        </migrate-command>
    </migrate>
</plugin-upgrade>

Example Plugin

This article is more in the form of documentation than a step-by-step guide. That is why I thought it'd be best to include an example project. In the example, I kept it simple, only printing out the properties given to the plugin. The example consists of the above-mentioned three XML files as well as a groovy script printing the values.

Here is a link to the project source.