UrbanCode Deploy

UrbanCode Deploy 10 Minute Tips: When the UCD REST Client Meets Version Import

You may have noticed that there is no documented way of adding files to a UCD Component version.  The only ways open to you seem to be either the udclient or using source plugins to import your component version assets.

But there must be a way right? The udclient does it – so how can I do that from my own script?

If you remember back to my two-part article on leveraging the UCD REST Client, the client contains classes to do some of the heavy lifting for you around invoking the UCD REST API.  There are dedicated classes to help you invoke the API’s of many UCD objects.

Well as it happens there are methods in the VersionClient class of the UCD REST Client library that allows you to add files to a component version (and also a load of other stuff).  So let’s look at how we might do that.

First, create a groovy script like this one.  This is pretty minimalist, but it does enough to prove the method.

import java.io.IOException;
import com.urbancode.ud.client.VersionClient;
import java.nio.charset.Charset;
import java.net.URI;

	String url="https://localhost:8443"
	String userName = "admin"
	String password = "admin"
	String myComponent= "myComponent"	// Name of pre existing component to create a new version in
	String myVersion = "1.0"		// name of currently non existant component version
	String myFilesDir = "base-dir"		// Directory that contains the file to be added to the version
	File filesDir = new File (myFilesDir)
	Boolean isImportingComplete = true  	// Boolean to tell ucd if the add files is complete in a single request
	String offset = "." 			// Optional. Target path offset (the directory in the version files to which these files should be added)

	String[] includes =["**/*"]		// Pattern(s) to describe which files should be included 
	String[] excludes= [""]			// Pattern(s) to describe which files should be excluded
	Boolean saveExecuteBits = true		// Whether or not the execute bits on the imported files should be preserved by UCD
	Boolean verbose = true			// Set true to display files uploaded
	Charset charsetUTF8 = Charset.forName("UTF-8"); // Character set files encoded as
	String[] extensions =[""]		// Charset extensions

	VersionClient myVersionClient = new VersionClient(new URI(url), userName , password, true);
	myVersionClient.createVersion(myComponent, myVersion, "description of my component", isImportingComplete)

	myVersionClient.addVersionFiles(myComponent, myVersion, filesDir, offset, includes, excludes, saveExecuteBits, verbose, charsetUTF8,  extensions)

I would invoke the script using this command like this:

/opt/ibm-ucd/agent/opt/groovy-2.4.15/bin/groovy -cp uDeployRestClient.jar:udclient.jar addVersionFiles.groovy

Here I’m using the groovy interpreter provided with a UCD agent and I’m including the two jar files that contain the UCD REST client and the libraries it depends on.  When I run it I seem something like this:

[root@localhost leverageREST]# 
Uploading file base-dir/a
Uploading file base-dir/b
Uploading file base-dir/c

I get output because I asked the UCD REST client to do verbose output.   This can be suppressed in the script if desired.

The UCD REST VersionClient also contains a number of other methods that you might also find useful.

OK, so where do I get these libraries from?  Well, they are contained in each of the UrbanCode plugins that provide UrbanCode services.  So just download one of those, open the zip and they are there in the lib subdirectory.


Alan Murphy is an IBM services consultant who has worked with clients to help them adopt new tools and processes for the last 20 years. UrbanCode Deploy and DevOps has been his focus for the last 5+ years. He also develops tools to assist clients in tool adoption and blogs on an occasional basis.

Tags: