In this article, we’re going to explore two of the property types that allow UrbanCode Deploy to fetch property values from external data sources.
UrbanCode Deploy provides a couple of value types for properties to be able to select from an external data source. These are Http Select and Http Multi-Select. NOTE: They are only available with property definitions and process properties.
These allow you to have a pick-list of values that can be retrieved via a REST call to either a JSON or XML data source.
For the early examples, I’m going to use a public internet data source as it makes getting the basics right a bit easier and will allow you to explore the possibilities of this capability.
Now, scroll down the dialogue and we’ll fill in the interesting bits.
Give your property a name, description and decide if it’s a required property or not.
Here you can see that I’ve completed the URL and selected the data format for the data source as JSON. The website jsonplaceholder.typicode.com is a free REST end point that provides services to return JSON data sets of various types and lengths. I picked the users list for this example. The website doesn’t require authentication so we can ignore that for now.
Further down in the dialogue, we see these additional fields.
The Base Path tells UCD where to start looking in a complex structured data set for information you’re after. UCD can pick values out of an array of objects and present them to the user for selection.
The Value Path tells UCD which field to pick to use as the actual value that UCD will use while the Label Path tells UCD which field to use to present to the user to make their selection. So, for example, I could provide a list of names to the UCD user but have UCD record the ID of the selected user as the property value.
Before we explore those further, there is a useful trick to make sure that you’ve got everything right so far. If you click on the drop arrow in the Default Value field at this point, if everything is set up correctly, UCD will show us some of the data set
Now I can see what the fields are. I have a simple array of objects and the fields in that object are id, name, email, address.
If I got something wrong so far then I’d see the rather less helpful:
But at this point in this example it can only be something to do with the URL or access to it.
Returning to the Base Path. In this case the array we want to extract from is not buried in a structure so we can leave that blank. If it was, then for JSON you need to provide a dot separated list of the attributes you need to traverse through the structure to get to the place the array is located.
For Label Path I’m going to choose the name attribute and for the Value Path I’m going to choose the id attribute.
If I click on the down arrow in the Default Value field I now see a list of names to pick from retrieved from the external data source.
I can now pick a default value for the field if I want one. I will pick one in this example to illustrate the difference between Value and Label fields. I’ll pick Patricia from the list.
I can now pick a default value for the field if I want one. I will pick one in this example to illustrate the difference between Value and Label fields. I’ll pick Patricia from the list. If you look back in the examples, you will see that Patricia has an ID of 4. When I now save my property and see the default value in the list of properties, I see the value is 4, not Patricia. 4 is the value UCD will present to steps as the value of the selection.
If you wanted the actual name of the user, then you’d set both Value Path and Label Path fields to name.
Data Source Credentials
The above example provides an easy way in to getting to grips with http select fields, but in the real world we often need to authenticate to the end point in order to be able to retrieve data.
Looking back in the property form we have several fields that deal with authentication:
- Use Bearer Authorisation Header
Let’s start with the simple case, this is a valid user ID and password issued by the external data source. These values could be personal to the user interacting with UCD and indeed the value sets returned might depend on the identify of the user ID you present to the external data source. So, whether you fill these fields or if they need to be prompted for may influence how you use them.
The User Bearer Authorisation Header is a way to provide a token to the external system to avoid using a user id and password. If that is selected, you will see this.
So now we can provide a token instead of a user id/password if your external data source supports this.
Enter the token issued to you. You can verify if the credentials are successful by selecting the drop down in the default value field.
NOTE: Despite the greyed out UCD_BEARER_AUTHORISATION_TOKEN value in the Username field, this is not a UCD token. Bearer tokens are an Oauth2 concept and isn’t what UCD uses for its tokens.
Using UCD as an External Data Source
You may never have tried it, but you can use UCD itself as an external data source. We can call the UCD REST API to get lists of information that we can use to inform or direct our automation processes. For example, I might want a list of applications to select from in an automation script. Typically, you would use these with process properties. For example, if I look in the UCD API documentation I find that the REST end point URI for the list of applications is as shown here
Here I enter id and name for the values of Value Path and Label Path respectively. Clicking the default value drop-down shows me:
If I were to use a different user, I will only see the applications that user can interact with.
One word of caution. UCD expects that the external end point has a signed certificate if using https. So, if you are trying to do this in a Proof of Concept system that is using the default UCD self-signed certificate you will get the ‘an error occurred’ message.
I hope you have found this little tutorial useful and will be encouraged to use it in your own automation processes.
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.