Introduction

With the release of WebSphere Business Monitor 6.1, greater functionality and user-enablement is now a standard. The 6.1 release exposed Monitor's data services through a publicly documented API using REST services. REST stands for REpresentational State Transfer and is a method of applying standard data creation and modification methods over simple HTTP methods -- GET, POST, PUT, & DELETE. A Monitor user can now access their business data from any endpoint with an internet connection, no longer requiring a browser. Previously, KPI was only accessible via dashboards and was read-only, as the user could not take any action on this data. Now, with the deployment of REST services, the user can access this data on the go, and also modify this data in the same application. One can create, update, and delete KPIs with the new Monitor 6.1 REST services. The prerequisites for this article are the following:

1. WebSphere Business Monitor 6.1.X
2. Deployment of the MortgageLendingBAM Monitor Model Sample, packaged with WBM 6.1.X
3. Google Desktop for Windows V5.7.0802.22438 or later
4. Google Desktop SDK

The scope of this article is to demonstrate the new Monitor 6.1 REST services capabilities. Other APIs will be referenced (such as Google Desktop Gadgets), but may not be fully explained. This is up to the user, as the amount of platforms which can consume Monitor's REST data is limitless. The zip file contained with this article has a fully functioning KPI gadget included with it. The sample utilizes other APIs, such as user preferences and options that are not covered in this article. The sample can be used as a reference guide, and the documented gadget API links can be used a the definitive resource.

Application Flow

The flow of our KPI gadget will be the following:

1. On load, get list of models data from URI /models with a GET request
2. On a successful response from step 1, parse the JSON object and update dropdown box
3. On selection of a model, get list of defined KPIs in model from URI /models/model_id/versions/version_number/kpis
4. On a successful response from step 3, parse the JSON object and update second dropdown box.
5. On a selection of a KPI, get current KPI value from URI /models/model_id/versions/version_number/kpis/kpi_id
6. On double-click of KPI gauge, populate and display a KPI details view

This flow will also be the course of this article.

Creating a new gadget

To get started, open up the Google Desktop Gadget Designer and create a new gadget. This can be done from the File menu or by using Ctrl + Shift + N. The gadget will be referenced in this article as MonitorKPIs, but you may name your gadget whatever you choose. You will want to set the gadget's name by opening en/strings.xml and set the GADGET_NAME element to MonitorKpis or whatever you will be referring to your gadget as. Once the new gadget is displayed, switch to the Source view and copy & paste the XML below.

<view height="250" width="250" onopen="view_onOpen()">
  <img height="250" src="stock_images\background.png"/>
  <label height="16" name="label1" width="34" x="17" y="22">Model:
  </label>
  <label height="16" name="label2" width="40" x="20" y="51">KPI:
  </label>
  <div height="27" name="div1" width="173" x="58" y="14" background="#000000"/>
  <combobox height="100" name="combobox1" width="171" x="59" y="15" background="#FFFFFF"
    itemSeparator="true" itemHeight="25" onchange="getKpisForModelAndVersion()"
   />
  <div height="27" name="div2" width="173" x="58" y="46" background="#000000"/>
  <combobox height="100" name="combobox2" width="171" x="59" y="47" background="#FFFFFF"
    itemSeparator="true" itemHeight="25" onchange="getKpiData()"
   />
  <label height="35" name="labelKpiName" width="204" x="18" y="80" font="Arial Bold"
    size="10" wordwrap="true"/>
  <div height="118" name="divGauge" width="208" x="18" y="115" background="#FFFFFF"/>
  <script src="main.js" />
</view>

Now that our main view has been established, we need to start handling data with XMLHttpRequests. To do so, we need to tell the gadget where to connect with Monitor. Expand the en folder and open the strings.xml file. Add the following data below and update it to reflect your environment.

<!-- This value should be either http or https -->
<MONITOR_PROTOCOL>http</MONITOR_PROTOCOL>

<MONITOR_HOST>monitorserver.yourcompany.com</MONITOR_HOST>

<!-- This value would be of 9080-variety for http or 9443-variety for https -->
<MONITOR_PORT>9080</MONITOR_PORT>

<MONITOR_USER>admin</MONITOR_USER>

We now need to download our JSON parsing library from json.org. Download and save json2.js and save it under the MonitorKPIs gadget directory. Now switch to the source view inside the Google Desktop Gadget Designer and add the following line before the closing <view> tag: <script src="json2.js" />.

Our gadget has initially been setup and we will now move on to getting alerts data from the REST services.

Selecting a model & KPI

We will use the pre-existing view_onOpen function to handle our view initilization. The first step we need to take is for the user to select which model they would like to view a KPI from. We will then query the REST service for all KPIs in that model. But first we must call the /monitor/models REST service. Update main.js to reflect the function below:

function view_onOpen() {
  var xhr_ = new XMLHttpRequest();
  try {		
    var url = MONITOR_PROTOCOL + "://" + MONITOR_HOST +":" + MONITOR_PORT;
    url += "/rest/bpm/monitor/models/";

    xhr_.open("GET", url, true);	
    xhr_.onreadystatechange = function() {
    if (xhr_.readyState==4){
        if(xhr_.status==200) {
          updateModelComboBox(JSON.parse(xhr_.responseText));
          xhr_ = null;
        }
      }
    };
    xhr_.send();
  } catch (e) {
    gadget.debug.error("ERROR:  "+JSON.stringify(e));		
  }
}

This function requests the list of monitor models currently deployed on the Monitor server. The service returns an array of models, with each element in the array containing another array of versions for each model. We only need to know the latest version of each model, and will deal with in the callback function of updateModelComboBox. The XMLHttpRequest contacts the Monitor located at address specified in en/strings.xml, and upon a successful communication, passes along the JSON response string as a Javascript object to the updateModelComboBox method. Below we display the updateModelsComboBox method.

var GAUGE_LAYOUT = { "x":104, "y":110};

function updateModelComboBox(/*Object*/ data){
  var model;
  var item;
  var label;
	for(model in data){
		var modelInfo = {id: "", version: ""};
		modelInfo.id = data[model]["Model ID"];

		data[model]["Versions"] = data[model]["Versions"].sort(sortVersions);
		var len = data[model]["Versions"].length;
		modelInfo.version = data[model]["Versions"][len-1]["Version"];
		modelInfo.display = data[model]["Versions"][len-1]["Model Display Name"];

		item = combobox1.appendElement("<item name=\""+modelInfo.id
							+"::"+modelInfo.version+"\" />");
		label = item.appendElement("<label />");
		label.innerText = modelInfo.display;
	}
}

function sortVersions(a,b){
	return a["Version"] - b["Version"];
}

Now the gadget simulates a dumb terminal and waits for the user to select a model from the dropdown box. Once the selects a model, we have set an onchange handler to call the function getKpisForModelAndVersion. This function takes the selected model ID and version number, and queries the REST server for all KPIs in the latest version of this model. Once the REST service returns data, we update the KPI combobox and then wait for the user to select a KPI to display.

function getKpisForModelAndVersion(){	
  var str = combobox1.selectedItem.name;
  var bits = str.split("::");

  var xhr_ = new XMLHttpRequest();
	try {		
	  var url = MONITOR_PROTOCOL + "://" + MONITOR_HOST +":" + MONITOR_PORT;
      url += "/rest/bpm/monitor/models/";
      url += bits[0];
      url += "/versions/";
      url += bits[1];
      url += "/kpis?locale=";
      url += framework.system.languageCode();

		xhr_.open("GET", url, true);	
		xhr_.onreadystatechange = function() {
			if (xhr_.readyState==4) {
				if(xhr_.status==200) {
					updateKpiComboBox(JSON.parse(xhr_.responseText));
				  xhr_ = null;
        }
			} 
		}
		xhr_.send();
	} catch (e) {
		gadget.debug.error("ERROR:  "+JSON.stringify(e));
	}
}


function updateKpiComboBox(/*Object*/ data){

    combobox2.removeAllElements();
    combobox2.selectedIndex = -1;
    combobox2.value = "";

	for(kpi in data){
		var item = combobox2.appendElement("<item name=\""+
							data[kpi]["KPI ID"]+"\" />");
		var label = item.appendElement("<label />");
		label.innerText = data[kpi]["KPI Display Name"];
		label.tooltip = "Name:  "+data[kpi]["KPI Display Name"];
		label.width="100%"
	}
}
		

Once the user has selected a KPI, we have gathered all the necessary information needed to be able to display the KPI gauge to the user. The onchange handler on the KPI combobox, getKpiData, will then query the REST service for the actual value of the KPI with all the current data and meta-data returned. With this data, which includes range information, current value, target, and all the pieces of data which make of the KPI definition, we can now construct the gauge inside of our main display.

Due to the fact that there is not a native Java™script graphics context, we will need to utilize existing images to create our gauges. This is simple enough though, as we simply stack and rotate the necessary number of ranges and then we can apply the already specified range colors to the rotated images. This pattern has no different appearance than a gauge generated in the dashboards or using a graphics language directly. The first step is getting the KPI data with getKpiData.

	
function getKpiData(){

var bits = combobox1.selectedItem.name.split("::");
var model = bits[0];
var version = bits[1]
var kpi = combobox2.selectedItem.name;

var url = MONITOR_PROTOCOL + "://" + MONITOR_HOST +":" + MONITOR_PORT;
    url += "/rest/bpm/monitor/models/";
    url += bits[0];
    url += "/versions/";
    url += bits[1];
    url += "/kpis/value/";
    url += kpi;
    url += "?locale=";
    url += framework.system.languageCode();

    var xhr_ = new XMLHttpRequest();
    try {			
      xhr_.open("GET", url, true);	
      xhr_.onreadystatechange = function() {
        if (xhr_.readyState==4){
          if(xhr_.status==200) {
            kpiData = JSON.parse(xhr_.responseText);
            divGauge.removeAllElements();
						
            labelKpiName.innerText = kpiData["KPI Display Name"];
            if(kpiData["KPI Description"]!="" && kpiData["KPI Description"]!=null) {
              labelKpiName.tooltip = kpiData["KPI Description"];
            }
						
            var extrema = getExtrema(kpiData);
            buildRanges(extrema, kpiData);
            if(extrema!=null && kpiData["Target"]!=null) {
              createTargetArrow(extrema, kpiData); 
            } 
            if(extrema!=null && kpiData["KPI Value"]!=null) {
              createValueArrow(extrema, kpiData);
            }
            if(extrema!=null) addBulletImage();
            xhr_ = null;
          } 
        }
      };
      xhr_.send();
    } catch (e) {
      gadget.debug.error("ERROR:  "+JSON.stringify(e));
    }
}

The bulk of our code comes into play here, during the callback phase of the successful KPI data REST request. Stepping through our getKpiData code above, after a successful REST service response, we do the following:

1. Parse the JSON string into a Javascript object
2. Remove all previously added elements from the divGauge object, which acts as our drawing canvas
3. Update a label which displays the KPI 's name and description
4. We calculate the maximum and minimum range values available for the KPI
5. We draw the ranges onto the divGauge canvas, using the calculated minimum and maximum values.
6. We next use the extrema that buildRanges returns to calculate the necessary rotation for the KPI's target arrow, if a target value currently exists.
7. We then do the same for the KPI's current value
8. Finally, we finish off our canvas drawing with a piece of polish by placing a button over the central rotation point of the gauge.

There is a lot of code here and we will walk through all of it in our next section. For now, we have successfully queried Monitor's REST services to provide us with functional monitor models data. We will now begin to work with the KPI REST services and their returned data.

Displaying a KPI gauge

Our first function that starts to work with actual KPI data is the buildRanges function. This function will append, rotate, and colorize all of the available ranges to the divGauge object. As a by-product of doing these calculations, we also have the minimum and maximum ranges value. These values are important so that we can calculate the rotation necessary for the value and target arrows. The rotation of these arrows are based on a scale of 0 - 180, with 0 degrees of rotation being equal to the KPI's lowest range start value, where as 180 degrees of rotation is equal to the KPI's greatest range end value. From here we can scale the value of the KPI's current value and target to achieve the desired visualization.

To start, let's define the getExtrema and buildRanges functions below. We first check to see if any ranges are defined, as they are not required for KPIs. If there are no ranges defined for the given KPI, we will create a default range so that we can have a minimal visualization. Once we determine that there is at least one range, we sort the ranges in ascending order. After this, we determine the smallest starting value for any given range, and we determine the largest ending value for any given range. This two values will determine the range of our gauge, with the minimum value correlating to 0 degress and the maximum values correlating to 180 degress.

				  
function getExtrema(/*Object*/ kpi){
	var extrema = { min: 0, max: 0};
	var ranges = kpi["KPI Range Array"];

	if(!ranges || ranges.length==0){
		ranges = createSingleRangeFromKpi(kpi);
		if(ranges.length==0){
			//an array of length 0 here means there is no value, no target,
			//and no ranges, since we can't display anything, we stop.
			return null;
		}
	} else {
			ranges.sort(
			  function(range1, range2) {
			    return range1["KPI Range Start Value"]
			         - range2["KPI Range Start Value"];
			  }
			);
	}

	for(each in ranges){
		var range = ranges[each];
		var start = range["KPI Range Start Value"];
		var stop = range["KPI Range End Value"];
		
		extrema.min = Math.min(extrema.min, start);
		extrema.max = Math.max(extrema.max, stop);
	}
	return extrema;
}

In this case where there are no pre-existing ranges, we need to define one for display purposes. To do this, we need to have a number to base this range off of. We prefer the KPI's current value over the current target, so we first check for an existing value, then an existing target. If neither of these exist, we return an empty array which will stop all of our display processing. Once we determine our sentinel value, we can generate our extrema. If the sentinel value is less than zero, we want the maximum to be zero and the minimum to be 25% lower than the sentinel value. If the number is greater than zero, we set the minimum to zero and the maximum to 25% higher than the sentinel value. These numbers can be adjusted as needed, but are sufficient for our display purposes. We then set a default color for the range and set other required properties and return an array containing our single range.

				  
function createSingleRangeFromKpi(/*Object*/ kpi){
  var value = kpi["KPI Value"];
  var target = kpi["Target"];
  var sentinel;
  var range = {};

  if(value!=null && target!=null){
    sentinel = Math.max(value, target);
  } else if(value!=null){
    sentinel = value;
  } else if(target!=null){
    sentinel = target;
  } else {
    gadget.debug.trace("Value, Target, & Ranges non-existent");
    return [];
  }

  if(sentinel==0){
    return [];
  }

  range["KPI Range ID"] = "AutoGeneratedRange";
  range["KPI Range Display Name"] = "Auto-Generated Range";
  range["KPI Range Start Value"] = Math.min(0, 1.25*sentinel);
  range["KPI Range Start Value Localized"] = range["KPI Range Start Value"];
  range["KPI Range End Value"] = Math.max(0, 1.25*sentinel);
  range["KPI Range End Value Localized"] = range["KPI Range End Value"];
  range["KPI Range Color"] = "#4444CC";
  return [range];
}

Our most important function is the buildRanges function, as it is the function which changes the display the most. We first define a set of default colors for our ranges, in case ranges are defined but have not had colors set using the KPI Manager widget. Next, the array of ranges is iterated over and an image is added, rotated, and colorized during each iteration. The pinX and pinY properties that we set for our image determine the point inside the bounds of the image which we want to rotate around. Our half-gauge image has a width of 200 pixels and a height of 100 pixels. Our desired point of rotation is the center point of the semi-circle, thus making our pinX equal to half the width (100) and our pinY equal to the height of the image.

We base our rotation of the range's image on the starting value, scaled against the maximum range value. As the range values increase, so will the value of the rotation. To allow for a tooltip to display the start and stop values, we need to add another transparent image (which contains a gradient) on top of the colorized images. This is needed because if we use one overlay image for the whole gauge, we will not have access to the individual range images. Once our we complete our range images, we need to add a footer image to cover the extra gauges that are unneccesarily shown. We can now move on to adding our value and target arrows.

				  
function buildRanges(/*Object*/ extrema, /*Object*/ kpi){
  var DEFAULT_COLORS = [ "#002c58", "#014085", "#0050a8", 
                         "#4070e8", "#6098c8", "#98b8e8", "#c5d6f0"];
  var image;
  var index = 0;
  var ranges = kpi["KPI Range Array"];
  
  if(!ranges || ranges.length==0){
    ranges = createSingleRangeFromKpi(kpi);
  }
  
  for(each in ranges){
    var range = ranges[each];
    var start = range["KPI Range Start Value"];
    var stop = range["KPI Range End Value"];

	//Flat Colorized Image
    image = divGauge.appendElement("<img />");
    image.x = GAUGE_LAYOUT.x;
    image.y = GAUGE_LAYOUT.y;
    image.pinX = 100;
    image.pinY = 100;
    image.src = "Images/halfgauge.png";
    image.rotation = (start/extrema.max)*180;

    if(range["KPI Range Color"]!="" && range["KPI Range Color"]!=null){
      var color = range["KPI Range Color"];
      if(color.substring(1,0)!="#") color = "#"+color;
      image.colorMultiply = color;
    } else {
      image.colorMultiply = DEFAULT_COLORS[ (index++ % DEFAULT_COLORS.length)];
    }
		    	          
    //Transparent Gradient Overlay Image
    image = divGauge.appendElement("<img />");
    image.x = GAUGE_LAYOUT.x;
    image.y = GAUGE_LAYOUT.y;
    image.pinX = 100;
    image.pinY = 100;
    image.src = "Images/halfgauge_overlay.png";
    image.rotation = (start/extrema.max)*180;
    image.tooltip = range["KPI Range Display Name"] + "\r\n" + 
		                "Range: "+range["KPI Range Start Value Localized"] 
		                + " - "+range["KPI Range End Value Localized"];
  }

  image = divGauge.appendElement("<img />");
  image.src = "Images/bottomOverlayWhite.png";
  image.x = 0;
  image.y = GAUGE_LAYOUT.y;
  image.width=220;
}			

Now we can add the current value and target arrows to the range display. We again use the minimum and maximum values of the ranges to define the maximum and minimum allowable rotation values for our arrow. If the KPI's current value is less then the minimum range value, we simply set rotation to zero. If the KPI's value is greater than the maximum range value, than we set the rotation to 180. Otherwise, the rotation value is calculated against the maximum value and then rotated. We apply the same principle of finding the rotation point of the arrow (which is the middle of the bottom), by using the full width of image as its pinX value and half its height as its pinY value. We then add a tooltip using the localized value of the KPI. This allows for currency symbols, decimal precision, and other text-based markups to the KPI value to be displayed to the user, instead of the strict number.

				  
function createValueArrow(/*Object*/ extrema, /*Object*/ kpi){	
  var value = kpi["KPI Value"];
  var rotation = Math.min(value,extrema.max);
  rotation = Math.max(value, extrema.min);
  rotation = (rotation/extrema.max)*180;

  imageValueArrow = divGauge.appendElement("<img />");
  imageValueArrow.x = GAUGE_LAYOUT.x;
  imageValueArrow.y = GAUGE_LAYOUT.y;
  imageValueArrow.pinX = 100;
  imageValueArrow.pinY = 5;
  imageValueArrow.rotation = rotation;
  imageValueArrow.src = "Images/KPIGauge_value.gif";
  imageValueArrow.tooltip = "KPI Value:  "+kpi["KPI Value Localized"];
}

We apply the same pattern below for the KPI's target value, as we did above with the KPI's current value. Notice that we need to change the value of the pinY property, as the KPIGauge_target.gif image is not as wide as the KPIGauge_value. Both the value and target arrows are only added if the value exists. If the KPI REST service returns null or empty values, an arrow is not placed on the gauge, as there would be no value to display.

	
function createTargetArrow(/*Object*/ extrema, /*Object*/ kpi){
  var target = kpi["Target"];
  var rotation = Math.min(target,extrema.max);
  rotation = Math.max(target, extrema.min);
  rotation = (rotation/extrema.max)*180;

  imageTargetArrow = divGauge.appendElement("<img />");
  imageTargetArrow.x = GAUGE_LAYOUT.x;
  imageTargetArrow.y = GAUGE_LAYOUT.y;
  imageTargetArrow.pinX = 100;
  imageTargetArrow.pinY = 2;
  imageTargetArrow.rotation = end;
  imageTargetArrow.src = "Images/KPIGauge_target.gif";
  imageTargetArrow.tooltip = "Target:  "+kpi["Target Localized"];
}

Finally, we have processed all of our KPI data and now we just need to finish cleaning up our display. To finalize this, we add a bullet image over the point of rotation over the top of all of our other images. Notice our bullet needs a negative offset from the rest of our images' x and y coordinates. You have now completed your very own Monitor KPI REST service-consuming gadget.

				  
function addBulletImage(){
  var image = divGauge.appendElement("<img />");
  image.x = GAUGE_LAYOUT.x - 5;
  image.y = GAUGE_LAYOUT.y - 5;
  image.src = "Images/KPIGauge_circle.gif";
}

Conclusion

The gadget documented here is a very simple and straight-forward gadget. There are multiple extensions that could be made to improve the functionality. Some of these include:

1. A KPI details view. The same pattern applied to our Alerts gadget's details view can be applied here.
2. More labels can be applied to the face of the gadget to display the current range the KPI's value falls into, as well as the current range icon.
3. As this gadget is only read-only for KPI data, one can extend it to use the write-enabled KPI REST services and update KPI properties, including description, range colors, range icons, etc

Packaged with this article is a zip file which contains a working copy of the gadget documented here, as well as a more-fully developed KPI subscriber gadget. The patterns and use-cases documented in this article are just a small sample of what can be done with Monitor 6.1's REST services. Other possible platforms that can consume these new services would be any gadget/widget platform and the new iPhone 2.0 OS. Namely, any platform which can make an HTTP request is now able to access all of your Monitor data. With this ubiquotus data service, there is no part of your organization or enterprise that is without access to business-critical information.

Back to top

Download

Information about download methods

Resources

Learn

• Monitor 6.1 InfoCenter REST Services API
  
  
• Google Desktop Gadget Reference
  
  
• Google Desktop Article: Using the Options Dialog
  
  
• Google Desktop Article: Interacting With The Web: The XMLHttpRequest Object
  
  
• In the Architecture area on developerWorks, get the resources you need to advance your skills in the architecture arena.
  
  
• Browse the technology bookstore for books on these and other technical topics.
  
  

Get products and technologies

• Download the latest Google Desktop
  
  
• Download Google Desktop SDK
  
  

Discuss

• Participate in the discussion forum.
  
  
• Check out developerWorks blogs and get involved in the developerWorks community.
  
  

About the author

Rick Osowski has worked with IBM WebSphere Business Monitor for more than four years. Rick graduated from Penn State University with a degree in computer science. Rick employs his previous IBM WebSphere Application Server and UNIX experience on a daily basis while installing, deploying, developing, and testing WebSphere Business Monitor, along with the rest of the IBM WebSphere Business Process Management suite of products.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Application Flow
• Creating a new gadget
• Selecting a model & KPI
• Displaying a KPI gauge
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

Spring, JRuby, and Ajax development is easier with WebSphere Application Server - a smart Java 5 and J2EE Web services-based application server.

---

• Try: The no-charge WebSphere Application Server Community Edition is a pre-integrated, lightweight Java 5 application server built on Apache Tomcat and other best-of-breed open source software such as OpenEJB, Apache Axis, and Apache Derby.
• Article: The article leverage the Spring Framework and the WebSphere Application Server to improve your J2EE project productivity.
• Tutorial: See how the free WebSphere Application Server and XML can improve the efficiency of your JRuby on Rails and Ajax development.
• Buy: WebSphere Application Server - Express

My developerWorks community