RG064 – Webservices for fun and profit, part 2

By Max Ranzau


In the first part of this article, we created a simple service to engage a public SOAP web service and we demonstrated how to pull resulting data into RES Automation Manager.

RESGURU000That’s all well and fine, however that’s where the buck stopped. If you pulled down the AM Buildingblocks from the previous article, you may have noticed that there was a disabled console message task embedded into the modules. I usually put something like that in for debugging purposes. Either way, that’s not going to help anyone except the AM console operator – which is why we continue the work in this article.

While the AM modules did a fine job of interacting with the weather SOAP service, the values didn’t go any further into any workflow. Today are going to use the RES IT Store to accomplish this. The goal here is to build a web-accessible service, which can prompt the requesting user for the two necessary inputs (City and Country) and then subsequently reporting the weather data back to the person requesting the service.

RESGURU001Rigging up the AM plumbing: Before we get into defining an ITS service, we need to connect all parts of the Automation Manager parameter plumbing. IT Store only allows you to invoke Runbooks from within a service workflow. If you ever wondered about why you can’t hook into a regular AM module or project, it’s because only the Runbook object offers the workflow designer to execute job components across multiple target computers. For example, if you are creating users, the AD account creation needs to address a Domain Controller, the homedrive is done on a file-server, and the mailbox needs to be created on Exchange etc. We need to understand the concept of parameter linking and setting initial values vs getting final value. If you’ve ever written software in any high-level language you should already be familiar with the concept of functions(). The module is in this case just a function. It takes two input values and returns about a dozen others that contains the return data from the weather report. The Runbook in this case just serves as a pass-through conduit between the module and the IT store. All you have to make sure is that the blue arrows point the right way. Inbound values point to the right, outbound values point to the left. There is a third value for bi-directional values, but that’s not important for today’s example.

During training classes,RESGURU002 I teach my students the following best practice: Step 1 – Make sure to agree on a naming convention for everything. This includes modules, runbooks, parameters, service attibutes and everything else. and then Step 2: Stick to it! This is why I prefix all my parameters going into the runbook as in.* and those returned named as out.*

RESGURU003Service properties, qualifications and triggers: This section covers the basics of the ITS service we are going to create. The service is pretty harmless, so you can safely give it to all users; RESGURU004just leave the qualification tab set to Everyone qualifies. Also, on the properties tab there is no point in requesting this service on anyone’s behalf, so there is no need to show it in service panel. As for subscriptions, we want that since we are talking to AM.

RESGURU005NRESGURU006ext up are the Triggers. We are doing a simple query, so on the Workflow|Delivery tab, the trigger should be when people request the service and the Workflow|Return trigger should be set to when the service has been delivered. This will allow the users to call the weather service again and again.

Providing the input: The thing we need to deal with in the service workflow is that the requesting user has to provide two parameters to the underlying AM job. The challenge is that one is dependent upon the other. Specifically, the selection of cities is dependent on the country the user selects first. As I’m quite sure there is no city by the name of Chicago in Sweden and there’s no city of Copenhagen in America (yes, I checked! ;), it would serve little point in allowing those invalid combinations to the provided by the requesting users. The end result that we can provide looks a little something like this:


In the ideal world (hint hint Product Mgmt :-), IT Store should be able to render a dynamic dropdown list, based on a SQL query something along the lines of:

SELECT city FROM country_cities_table WHERE country = '#Service[user selected country]'

However, the above statement is not possible to implement at the moment as dropdown lists presented to IT Store users can only be based on either static values or the Organization structure. The latter does however allow us to exploit a method to select two values in a round-about way. The following is the only way I found so far to solve this current challenge. If you have a better way, please make yourself known in the comments below.

IRESGURU007 created a static organizational context RESGURU010(folder) called WeatherCities. Under this I created a folder for each City I wanted to provide, using the naming convention “Countryabreviation – CityName”, such as ‘US – San Francisco’, ‘SE – Stockholm’ etc. This will ensure that the cities are organized by country, as the list is sorted alphabetically by ITS. As there is no meaningful way to break up the country/city part of the individual context folders name, I added two organizational attributes to each folder. You guessed it, one for the city and one for the country value, and filled them out accordingly.

RESGURU019Once the organizational source of the dropdown with the underlying values are in place, we need to add a bit more meat to our weather service. The first thing we need to do is create a service attribute, which can be assigned a value from the WeatherCities organization structure. This is a prerequisite to be able to prompt the user. Configure it like shown here on the right.

RESGURU012While we’re at it, we might as well create some additional attributes for storing the return values (temperature, air-pressure etc) coming back from the weather-report Runbook. Some of you might go “hey, waitaminute! ITS can auto-create service attributes so there’s no need to do that!” Actually there is: Apparently nobody thought of auto-creating service attributes for return values for Runbooks. In other words, auto-creation currently only works for values going into the Runbook, and since the majority of values are return values here, you might as well get crackin’ and create them all.

Yes, that's a brainfart I suppose...Update: Having slept on it, I think I may have had a potential brainfart just above. Rather than editing the original blog, and try to pass it off like it never happened, I better come clean :) While the ITS console can’t autocreate service attributes for Runbook results, it might actually be possible to create all these by publishing the runbook as a service from the AM console. I’ll have to take that one back to the Batcave and see if it works as I think it does, but I wanted to make sure you had this information up front.

RESGURU013The Workflow: The last part to this exercise is creating a delivery workflow that will get the input values from the user, shove them down the gullet of the Runbook and finally display the return values in a consistent manner back to the requesting user. Providing the input is a no-brainer, as it’s just a matter of asking for the input of the City value, presented to the requester as a drop-down of all the values in the WeatherCities org.structure (remember the “countrycode – city” list described above).

RESGURU014Next we got a somewhat tricky maneuver in the workflow. We need to change the organizational context of the user. I’ll get to the reasoning in a bit. Now before you panic about the org change; don’t worry – An ITS person can have multiple organizational contexts assigned (think role, groups, location, etc). So all we are doing here is really just telling ITS where user need his weather report from, nothing else. Whatever department, etc. the user otherwise belongs to, will not be affected. The reason we have to do this is that the only way to pull out an an organizational sub-context (the selected org’s citry+country values), is when it’s assigned to a person. In this example we refer to these subcontexts as #Subscriber.WeatherCities[<City>||<Country>]

RESGURU015Once theRESGURU016 city+country values are assigned to the Runbook, IT Store’s transaction server will take care of getting the Runbook executed and the all the rt.* service attributes will be allocated with the Runbook results as we have configured. As mentioned previously, there’s currently no way in ITS FR2 to auto-create service attributes for return values so in that regard you are SOL and have to create those yourself. I’ve added an exception handler to the Runbook invocation workflow to display an error if the Runbook fails. This is due to the web-service we are using, sometimes times out when it’s being overloaded. Nothing we can do about that except deal with it.

Getting the message out: The last part of the workflow is to return all the rt.* service attributes to the user in a message, in a meaningful manner. This is just a matter of getting rid of the default “the foo service has been delivered to bar” and replacing it with something that is readable and uses the service attributes.

The report that I’ve concocted reads like this: “Weather report from: #Service[rt.location]. Today, #Service[rt.time], temperature is #Service[rt.temperature] and humidity is at #Service[rt.relativehumidity]. Wind #Service[rt.wind], with skies #Service[rt.skyconditions] and visibility is #Service[rt.visibility]. Barometric pressure reads #Service[rt.pressure]. Have a nice day!”. Presented by IT Store, it looks like this.


This is almost good enough to have read aloud through a text-to-speech converter, but that’s a project for another rainy day – and mind you, we don’t get an awful lot of those here in California! :-) One gripe I have is the ‘letterbox’ default view that IT Store presents all it’s information in. It seems an awful waste of screen space, that messages and user input has to take place in this enveloped shaped white area.

conc The conclusion: I hope you’ve been able to enjoy this example as much as I did creating and sharing it. You might think “gee, that’s an awful lot of hoops to jump through to get a weather report”. We have to look at it through a wider lens as this is an example workflow applicable to much more complex things in the world of business workflow automation. This methodology is applicable to pretty much any schenario, where interaction with a web-service or pretty much anything else is required. The example also illustrates how to work around some of ITS’s shortcomings and still present the users with a somewhat meaningful interface.

As per usual, please find an example building-block for download, to get you started on creating your own ITS services, interacting with Runbooks and WebServices.

Click the brick to download the IT Store buildingblock: legobrick-cropped

Remember, RESguru Consulting Services is here to help. Reach out to us when you find yourself in need of expert advice and real-life working experience with these kind of workflow/automation solutions. We look forward to working with you!


No Comments

No comments yet.

RSS feed for comments on this post. TrackBack URI

Leave a comment

Comments are welcome as always. Just do the math below. * Time limit is exhausted. Please reload the CAPTCHA.