How to Track Versions of DataPower Services

A version traceability mechanism should allow us to see versions of all our application components. An applications with UI front-end could have a "help/about" page or use other ways to show its version to an end user or to a developer. On the back-end, the version might be embedded into a manifest file or an application-specific property/configuration file. The version is typically associated with a code baseline stored in a version control repository.

How do we achieve the version traceablity for the services and objects deployed to a DataPower appliance? One way of doing it is to use "comments" field available for most DataPower objects and services. Conveniently, the comments field also shows up on the application domain status page in WebGUI.

In the majority of cases, a domain represents a unit of release. A domain could be built/assembled in a development environment and then promoted to test and other environments. We set the version information in the "comments" field of our services when we build or assemble our deployable domain from the DataPower configuration files stored under version control. We can use Git commit hash, Subversion revision or similar properties to tie our artifacts to the version control history. If the build is run from Jenkins, all these properties (and more) are available as Jenkins variables.

When importing configuration using DPBuddy, the version information could be easily set by the transform tag. The "comments" field is actually named "UserSummary" in DataPower configuration files, so we just need to override the value of this field. For better traceability, we can also specify the timestamp of the build ("DSTAMP" and "TSTAMP" are built-in Ant properties that can be used for this purpose):

<dp:transform id="transform.firewall">
    <delete xpath="//XMLFirewallService/UserSummary" matchRequired="false"/>
    <add xpath="//XMLFirewallService" >
        <UserSummary>Version: ${version.info}. Build: ${DSTAMP} ${TSTAMP}</UserSummary>
    </add>
</dp:transform>

Once the domain is built, it should be exported and saved in an artifact repository or it could be preserved as a build artifact in Jenkins. We can then promote the domain by importing it to the target environment. Using Jenkins, the promotion could be implemented using downstream builds in conjunction with the build pipeline/delivery pipeline. When we import the domain, we should specify its version (which could be the build number of another property provided to the import script) as the domain's comment.

DPBuddy has direct support for updating domain comments as part of import:

<dp:import file="${domain.file}" save="true" 
        domainComments="Version: ${dp.release.info}. Deployed: ${DSTAMP} ${TSTAMP}"/>

We can then view the versions of all our domains by logging in to the default domain and opening the "Application Domains" WebUI screen:

We can also find versions of individual services by looking at their comments fields in WebGUI. For example, for XML firewalls, the comment field can be accessed from the "General" tab.

If you're interested in automating the rest of your DataPower deployment and administration tasks, download DPBuddy and give it a try.