UrbanCode Deploy

10 Minute Tips: Leveraging the UrbanCode Deploy REST Client Libraries

There are times when you need to write some code to automate IBM UrbanCode Deploy, but how to do that easily?







UrbanCode Deploy provides an extensive API that can be accessed either through the UCD command line tool udclient or through a REST API.

The udclient is handy for those occasions where you want to do a couple of requests but the overhead of starting the udclient from a script quickly adds up and scripts that make a lot of calls can take much longer to execute than using the REST interface direct.

If you’re writing say a shell script, then a tool like curl makes it relatively easy to make the REST requests but then you are faced in many cases with having to process a JSON response which is not so easy.

There are tools like JQ (https://stedolan.github.io/jq/) which is a freely available JSON query tool that allows you to process the JSON documents returned by the REST API.  However, your scripts can get quite complex if you have a lot of processing to do.

If you want to write your own program to make use of the REST API, there can be a lot of code that you need to write in order to authenticate / setup request headers and so on before you can make the appropriate calls to the UCD Server.

Enter the UCD REST Client libraries (https://github.com/UrbanCode/uDeployRestClient).  These libraries also form part of many UrbanCode plugins that automate UCD itself.  You’ll find them in the lib directory of plugins like IBM UrbanCode Deploy Environments (https://www.urbancode.com/plugin/ibm-urbancode-deploy-environments).

This git project hasn’t seen any update for several years so its possible that its not up to date with the shipping versions of the uDeployRestClient library.

The UDRESTClient consists of several client libraries that provide access to some of the UCD API’s.  There are clients for the following categories of UCD Objects:

  1. Agent
  2. Application
  3. Component
  4. Environment
  5. Process
  6. Property
  7. Resource
  8. System
  9. Version

To find out exactly what methods these clients make available, we can write a little bit of groovy script to list them out.

import java.lang.reflect.Method;
import com.urbancode.ud.client.AgentClient;
AgentClient client = new AgentClient( new URI(“https://localhost:8443”),
“adminUser”, “adminPassword”);
Class clientClass = client.getClass();
Method[] methods = clientClass.getMethods();
for (int i = 0; i < methods.length; i++) {
println(“public method: ” + methods[i]);

To use this, put the script above and the uDeployRestClient.jar library in the same directory.  I called my script listPublic.groovy.  You can get a copy of the UDeployRestClient.jar file by downloading any of the UCD plugins that automate some UCD function, unzip it and extract the library.

We can run this using the groovy script language which is part of every agents install.  So lets run this and see what output we get

/opt/ibm-ucd/agent/opt/groovy-2.4.15/bin/groovy -cp uDeployRestClient.jar listPublic.groovy

This is the sort of thing you see.  I’ve removed most of the output for the sake of brevity and also so we can look at the more interesting methods.

public method: public org.codehaus.jettison.json.JSONObject com.urbancode.ud.client.AgentClient.getAgent(java.lang.String) throws java.io.IOException,org.codehaus.jettison.json.JSONException

public method: public void com.urbancode.ud.client.AgentClient.installAgent(java.lang.String,java.lang.String, java.lang.String,java.lang.String,java.lang.String,java.lang.String,java.lang.String, java.lang.String, java.lang.String,java.lang.String,java.lang.String,java.lang.String, java.lang.String) throws java.io.IOException

public method: public void com.urbancode.ud.client.AgentClient.deleteAgent(java.lang.String) throws java.io.IOException

public method: public java.lang.String com.urbancode.ud.client.AgentClient.setAgentProperty(java.lang.String, java.lang.String,java.lang.String,boolean) throws java.io.IOException

public method: public java.lang.String com.urbancode.ud.client.AgentClient.getAgentProperty(java.lang.String, java.lang.String) throws java.io.IOException

So now if I want to get a property of an agent, I have a much simpler task.  Something like this would do the trick:

import com.urbancode.ud.client.AgentClient;
AgentClient client = new AgentClient( new
URI(“https://localhost:8443”), “admin”, “admin”);
String propertyValue = client.getAgentProperty(“agent-carter”, “JAVA_HOME”)
println (“Property value is: ${propertyValue}”)

So when we run this new script, we get

/opt/ibm-ucd/agent/opt/groovy-2.4.15/bin/groovy -cp uDeployRestClient.jar getAgentProperty.groovy

Property value is: /opt/ibm-java-x86_64-80/jre

It’s a simple example but its enough to give you the idea.  Each of the 9 clients defined in the libraries gives you easy access to many REST API’s.  As we’re writing in groovy (or java if you prefer) processing the JSON responses and building the JSON to send in some requests is now a lot easier.   In many cases, the method builds / extracts information the JSON for you, so you don’t even need to worry about that.

But, and there is always a but.  These libraries don’t give you 100% coverage of the UCD REST API. 

On the plus side, there are some things in these libraries that aren’t in the API spec.
Have you ever wanted to upload version files using the API?
You won’t find a published API to do this but the VersionClient library has a method for it.

So what if I want to call an API that’s not covered by one of these libraries?  Well that as they say, is a story for another day.  Look out for more 10-minute tips.

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.