By Ian Withrow
SOAP APIs, or Web Services, frequently form the backbone of private enterprise to enterprise communication. Companies use these APIs to integrate value chains, share information, and integrate applications that depend on partners. While RESTful APIs may be taking the technology world by storm, SOAP still has an established place in private enterprise communications. Even as organizations migrate from dedicated physical resources to private and public clouds, SOAP APIs are likely to continue to play a role for now. As a result, web applications often depend on the information delivered by a SOAP API. As such if the API is slow then so too shall the application be. Thus it makes sense for businesses serious about performance to monitor their partner APIs, whether they are SOAP or otherwise.
In this post I will show you how to easily create an advanced SOAP script using the new enhanced functionality available in KITE 4.1, topics covered here include:
- Step 1: Create a basic web services script
- Step 2: Techniques for iterative development
- Step 3: Advanced script editing
- Putting your script to work with a Keynote monitoring agent
Note that I discuss how to script RESTful APIs in another post.
Step 1: Create a basic web services script
Public SOAP APIs are rare these days, most are private and require authorization. For the purposes of this demonstration I will utilize the free, public Holiday Web Service API which supplies holiday dates for a small selection of countries.
To get started you’ll need KITE 4.1 or newer. If you don’t have KITE a copy can be obtained for free here. Launch KITE, and in the top left corner there should be a button that looks like a big red record button. Click the bottom half of this button which opens a drop down menu and then select ‘Create Web Service Script’ as shown below.
You will be asked to select a service type, go ahead and select SOAP.
After clicking ok a Wizard will pop-up on your screen. This wizard will automatically generate an advanced script for you that will make a properly formatted SOAP request, parse the results into a log, and capture errors. First, load the WSDL file for your API. Next you select the function you want to call; in this case I want a list of supported countries. A sharp eye might to detect what seems to be a duplicate list of functions. In fact there are multiple versions of SOAP and you will see duplicates when the WSDL specifies the same method for multiple versions. For Keynote monitoring purposes they work the same.
When you are ready, click ok and you’ll see a new action added for you in the Script Viewer.
The best practice suggests that at this time you should rename the action something logical by clicking on [Action] and editing the Script Property shown below.
Now we are ready to view our completed script, you can do this by clicking on ‘SOAP Script’ on the left, note that this too can be renamed. When you do you’ll get a new window, called Advanced Scripting. Please note if you have a lot of windows open in your KITE instance you may need to close or resize some to get the expansive view that I have below. We’ll explore the different elements of this script later but for now the key portion is shown below from row 36 to 53, this is the SOAP query that you’ve just created. You can now double check and edit it manually using JavaScript. Note that the RequestXML variable contains just the SOAP envelope body if you are comparing it to a reference example. If you needed to add login and authentication information this is the section of the code to do so, either be adding an additional KNWeb.AddHeader command or by including it in the RequestXML string.
Once done, you click the ‘run’ button as normal to test out the script and see what results you get. If everything works you’ll get a screen like the below shaded in green.
For comparison here is what failure looks like, in this case I deliberately messed up the envelope by deleting a tag.
Step 2: Iterative Development
In addition to the Wizard we’ve added three great tools for iterative development, which we’ll examine in turn within this section:
- Advanced script log
- HTTP request/response header payload viewer
- Using saved variables in subsequent actions
Advanced Script Log
After you run a script, the Advanced Script Log will be automatically updated and added to your screen as shown below. The log displays the request made as well as any error response details received. If the response was a successful, then the results are store into variables. For example, country code GBSCT is saved in the variable:
[GetCountriesAvailableResponse.GetCountriesAvailableResult.diffgr:diffgram.NewDataSet.Countries.Code]
I’ll show you more on how to use this in a second.
HTTP Request/Response Header Payload Viewer
Sometimes I find it helps to see the exact request and response payloads. Now there is an easy way to do this. In the Transaction Performance Details window, which is typically right below the Advanced Script Log, right click the step or object that you are interested in and select View HTTP Payload from the context menu.
Back on top you’ll get the below screen which shows you the exact headers and payloads, up to a character limit.
Using Variables in Subsequent Steps
Retrieving the list of supported countries is nice, but next let’s try to get some real information like a list of holiday’s for one of those countries. In this way our script can behave much like a real program on whose behalf we are monitoring performance. We know, from the parsing of the WSDL, that there is a GetHolidaysAvailable function. Let’s add a step using that method together with a saved variable from our first step. This would require the country code shown in the previous section from the Advanced Script Log: GBSCT.
Next we need to add a new step. This is done, as normal in KITE, by right clicking the script name in the Script Viewer window and selecting a new SOAP action as shown below.
We are at the Web Services Wizard again. This time we click on the ‘GetHolidaysAvailable’ function and a second popup is displayed asking us for input parameters. In this screen we will use the saved parameter as the input variable as shown below. Be sure to include the brackets then proceed as before by clicking ok.
Now when we check the results of our new script we see that the code generated is retrieving our saved variable. This could also be done manually, as sharp readers will no doubt guess, but this way saves a lot of time and effort.
We can now run this two-step script and check the HTTP Payload of the second object to confirm we got the results we expected, in this case by double checking the countryCode. As we’ll explore in in the next section, it is possible to extend the script to add your own custom validation logic on elements like this and throw errors depending on the results.
The script is now done so we can save and upload it to Keynote for deployment to a monitoring agent.
Step 3: Advanced Script Editing
As I alluded to earlier, it’s entirely possible to manually rewrite the script created by the wizard and even modify the template itself. First though let me explain the organization of the built-in script template. Each script, both REST and SOAP, is organized into three logical sections as shown below. The red section is the parser which takes the results and saves them in variables. By default the script will usually only save one version of a variable, i.e. if you have multiple countryCode’s it will save only one, the last. This is fine in most cases, however there may be times when you want to enhance this behavior and that can be done here. The blue section is where the actual query is built, this code block will obviously be pretty different between REST and SOAP but the organization is the same. Finally, the purple section is where error handling is done. The built in error handling can catch HTTP as well as API errors; however you may wish to extend this functionality further. As mentioned previously, all of this is done in JavaScript.
Let’s say you find yourself frequently updating the built in script functionality and want to make a global change. This can be done by modifying the files named wsdl.template and rest.template. These files are found in your application data folder under …/Keynote/Record/Config/. So for example in Windows 7 this would be username/AppData/Roaming/Keynote/Recorder/Config/. I encourage you to back up the originals before experimenting with this though.
Putting Your Script to Work with a Keynote Monitoring Agent
Now that you have created a brand new SOAP script you’ll need to setup some agents to run it. Since most SOAP APIs involve private application to application communication, Keynote’s Cloud Application Perspective (CApP) product is the ideal tool for the job. CApP is your very own Keynote agent which you can deploy in your own private or public cloud and even within an important business partner’s network. In this way you can monitor the SOAP API from where it is actually queried in order to get an accurate picture of performance.
