Introduction

So you've installed WebSphere Business Monitor (hereafter called Monitor) and now you want to customize the appearance of your dashboards to match your company’s intranet branding and style? This article show shows you how easy that is to do. You'll learn how to:

• Create custom banners and background images
• Change page background colors and use themes
• Customize the colors used in key performance indicator (KPI) bar graphs and gauges
• Change the titles of the views on the dashboards to better reflect their business content.

This article extends the "Clips and Tacks: Getting started with the IBM business process management (BPM) suite of products" tutorial, which is based on a fictional office supply company called Clips and Tacks. In this article, you'll learn how to customize the appearance of the Clips and Tacks business dashboards created in that tutorial. That Clips and Tacks tutorial shows you how to model and implement Clips and Tacks’ business processes, create a monitoring model, and deploy the Monitor dashboards that we'll customize in this article. You can complete the tutorial to build the Clips and Tacks project yourself, or download the finished project and dashboards and simply install them. (See Resources to download the Clips and Tacks project file.)

This articles focuses on the Web dashboard, rather than the Portal dashboard. Portal dashboard customization uses well-known portal techniques. We'll use Mozilla Firefox® as the internet browser.

Back to top

Install custom banners, colors, and themes

As you customize your dashboard’s appearance in this article, you'll create a set of artifacts that are used to override the default values supplied by Monitor. Monitor provides an easy way to install these customizations. We’ll cover that first.

Whenever a user logs in to a Monitor dashboard, the server looks for the environment variable WBM_WEB_DASHBOARD_EXT_DIR. You need to set this environment variable to the file path of your customizations directory on the Monitor server on which your customized artifacts are located.

If this variable is defined, Monitor copies any files it finds in that customizations directory to the installed themes directory. The customization then takes effect for all subsequent page views. Note that most customization done in this manner applies to all users and all dashboards.

To set the WBM_WEB_DASHBOARD_EXT_DIR environment variable, open the Monitor administration console and do the following:.

• Select Servers > Application Servers > server1 (or your server name).
• Under Server Infrastructure, expand the Java and Process Management section and select Process Definition.
• Under Additional Properties select Environment Entries, and click New.
• In the configuration dialog, fill in the values for WBM_WEB_DASHBOARD_EXT_DIR, as shown in Figure 1. Note that part of the variable name is not visible because of the width of the entry field.
• Click OK.
• Click Save to save your changes.

When the next user logs on to Monitor, the server will copy all the files found at c:\CustomThemes into its installed themes directory and the new theme will take effect.

Back to top

Uninstall customizations

In the Monitor V6.1, you can uninstall custom themes by simply deleting them from the themes directory. If you used the default WBMonSrv_wps profile, the themes directory is located at: monitorhome\WBMonSrv_wps\installedApps\WBMonSrv_wps_Cell\ IBM_WBM_WEB_DASHBOARD.ear\WBMDashboardWeb.war\themes.

Back to top

Customize the business dashboard banner

First, we'll create a customized banner. You can use any banner you like, but we've provided a sample called ClipsTacks(banner).jpg, shown in FIgure 2.

In addition to a banner, you may want to include a background image on your business dashboard log-in page. We’ll use the image ClipsTacksBkgd.gif, shown in FIgure 3.

Once you’ve prepared your banner and background images, you need to create a file called banner.html that points to your new image. To do this, copy the code in Listing 1 or use the supplied sample. The background color and the locators for the images are in bold. Only the code in bold needs to be updated.

                
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <title>Untitled Document</title>
  <style type="text/css">
  
  body {
  	background-color: #FFFFCC;
  	background-repeat: no-repeat;
  	margin-left: 0px;
  	margin-top: 0px;
  	background-image: url(themes/ClipsTacksBkgd.gif);
  }
  .style1 {
  	font-family: Verdana, Arial, Helvetica, sans-serif;
  	font-size: x-small;
  }

</style></head>
<body>
  <table width="100%" border="0" cellspacing="0" cellpadding="0">
        <tbody>
        	<tr>
                <td width="110px">
<img src="themes/ClipsTacks(banner).jpg" 
width="1010" height="47" />
</td>
            </tr>
        </tbody>
        </table>
</body>
</html>

Notes:

• You may also need to adjust the width and height values for the banner image to achieve the layout you want.
• The syntax for the file name is case-sensitive. MyBanner.GIF is not the same as mybanner.GIF or MyBanner.gif.

If you're adding a log-in page background image, you'll want to remove the default wave image that is provided by Monitor on the log-in page.

The wave image is actually three images referenced in Login.jsp. Again assuming that you're using the default WBMonSrv_wps profile, the Login.jsp is found at: monitorhome\WBMonSrv_wps\installedApps\ WBMonSrv_wps_Cell\IBM_WBM_WEB_DASHBOARD.ear\WBMDashboardWeb.war).

First, make a back-up copy of Login.jsp. Then, to remove the wave images from your log-in screen, edit the Login.jsp file and delete the xml attributes and elements shown in Listing 2.

                
<table width="100%" border="0" cellspacing="0" cellpadding="0">
<tr>
<td width="541px" height="154px" background="img/LoginScreen_left.gif"/>
<% if (WSSecurityHelper.isServerSecurityEnabled()) { %>
<form id="secure_login_form" name="login-form" method="post" action="j_security_check">
	<table cellspacing=0 cellpadding=0 border=0 style="padding-left:90px">
	<tbody>
	<tr>
	<td><span class="loginText" id="user_id"></span></td>
	</tr>
	<tr><td height='5px'><img src='img/blank.gif'></img></td></tr>
	<tr>
	<td><input id="j_username" class="login-field" type="text" required="true" 
		name="j_username"></input></td>
	</tr>
	<tr><td height='10px'><img src='img/blank.gif'></img></td></tr>
	<tr>
	<td><span class="loginText" id="password"></span></td>
	</tr>
	<tr><td height='5px'><img src='img/blank.gif'></img></td></tr>
	<tr>
	<td><input name="j_password"id="j_password" type="password" class="login-field" 
		required="true"></input></td>
	</tr>
	<tr><td height='15px'><img src='img/blank.gif'></img></td></tr>
	<tr>
	<td><input id="log_in" class ="btn" type="submit" name="save" value="" 
		onClick="return validate();"></input></td>
	</tr>
	</tbody>
	</table>
</form>
<% } else { %>
<form id="unsecure_form_login" method="post" action="DashboardLogin">
	<table cellspacing=0 cellpadding=0 border=0 style="padding-left:90px">
	<tbody>
	<tr>
	<td><span class="loginText" id="user_id"></span></td>
	</tr>
	<tr><td height='5px'><img src='img/blank.gif'></img></td></tr>
	<tr>
	<td><input id="username" class="login-field" type="text" name="username">
	</input></td>
	</tr>
	<tr><td height='15px'><img src='img/blank.gif'></img></td></tr>
	<tr>
	<td><input id="log_in" class ="btn" type="submit" name="save" value="" 
		onClick="return validateUser();"></input></td>
	</tr>
	</tbody>
	</table>
</form>
<% } %>
</td>
<td background="img/LoginScreen_1pixel.gif">
	&nbsp; 
</td>
<td width="117px" background="img/LoginScreen_right.gif" />
	&nbsp;
</td>
</tr>
</table>

The final step is to copy your customized banner.html, banner image, and background image files to your custom themes directory. The next time you log on, Monitor will copy these files to its installed themes directory and replace the defaults with your images. Log on to verify that your new banner is displayed on the Monitor log in-screen.

We've provided a simple log-in page for this example, but the layout and design are completely at your discretion. The main requirement is to pass the correct authentication credentials when security is enabled. You can see the credentials specification in the form element for the condition if (WSSecurityHelper.isServerSecurityEnabled()).

Back to top

Customize background colors

It's also easy to change the cascading style sheet (CSS) parameters used in the dashboards. You can change these parameters by creating a monitor.js file in your custom themes directory. The contents of this file will override the defaults in the business dashboards.

We've provided a sample monitor.js file, shown in Listing 3, that changes font colors with this article. Note that the BODY tag changes the font color in Internet Explorer, and the body tag makes the same change for Firefox. If both browsers are used in your organization, make sure to include both.

                
                {
    "BODY":
    {
        "color": "#0569c7"
    },
    "body":
    {
        "color": "#0569c7"
    }
 }
            

In our example, we want to change font colors because the default white font for the labels on the fields on the log-in screen is difficult to see against the yellow background image we’re using.

This monitor.js file requires a JSON formatted version of CSS syntax. Listing 4 shows the CSS equivalent.

                
body { 	color: #0569C7; }

Details about JSON are outside the scope of this article, but the key changes from CSS to JSON are:

• Enclosure of each parameter in double quotes.
• Replacement of the semi-colon terminators at the end of the name/value pairs with commas.
• Enclosure of the entire file in an additional set of braces (in bold in Listing 3).

This color attribute sets the font color using RGB (RedGreenBlue) syntax. For example, #0000FF is equivalent to blue. For a good starting point for understanding colors in CSS, see section 4.3.6 Colors in the CSS specification.

You can the free downloadable tool Hex Color Finder from NZ Software to experiment with the RGB values of colors and to test existing Web sites to determine the exact RGB value of colors used.

A second sample monitor.js file is also provided; it includes the JSON representation of all the style entries. This sample is called complete_monitor.js. You can use this file to experiment with changing other look-and-feel parameters. Rename it to monitor.js and copy it to your custom themes directory and Monitor will use it when the next user logs in.

Back to top

Customize themes

Another way to tailor the appearance of Monitor business dashboards is to use themes. Like the monitor.js file we talked about in the previous section, theme files are JSON representations of CSS attributes. Listing 5 shows a sample theme file called Clips.js.

                
{ 
"priority":		 0,
"key":			 "Clips Theme",
"top_left": { "width":  2, "height":  2, "src": "themes/clips/top_lef.gif"  },
"top_middle":    { "width":  1, "height":  2, "src": "themes/clips/top_mid.gif"       },
"top_right":     { "width":  3, "height":  2, "src": "themes/clips/top_rig.gif"       },
"title_left":    { "width":  2, "height": 22, "src": "themes/clips/title_lef.gif"     },
"title_middle":  { "width":  1, "height": 22, "src": "themes/clips/title.bmp"         },
"title_arrow":   { "width": 16, "height": 16, "src": "themes/clips/top_mid_arrow.gif" },
"title_right":   { "width":  3, "height": 22, "src": "themes/clips/title_rig.gif"     },
"center_left":   { "width":  2, "height":  1, "src": "themes/clips/cen_lef.gif"       },
"center_right":  { "width":  3, "height":  1, "src": "themes/clips/cen_rig.gif"       },
"bottom_left":   { "width":  2, "height":  3, "src": "themes/clips/bot_lef.gif"       },
"bottom_middle": { "width":  1, "height":  3, "src": "themes/clips/bot_mid.gif"       },
"bottom_right":  { "width":  3, "height":  3, "src": "themes/clips/bot_rig.gif"       },
"backgroundColor": "#ffffd7"
}

Unlike the monitor.js file, theme files aren't applied globally. In fact, themes don’t affect anything until a user selects a theme for a dashboard. Our sample theme is Clips Theme, which is what the user will see when selecting this theme for a dashboard page.

You can use themes to control the colors of borders around the elements on a dashboard. The coloring is provided by the gif files pointed to in the theme file. As you can see above, the gif files are located in the themes/clips directory, where they won't overwrite the product default files. You can use a gif file editor, such as the free IrfanView, to edit the files to change the colors. For this example, you don't need to edit the files, just copy them to the themes/clips directory.

The backgroundColor attribute controls an additional layer of background color in the dashboards. You can also use themes to control other attributes, such as fonts.

Back to top

Customize the colors for KPI ranges

When you display KPIs on your dashboard as gauges or bar charts, you may want to change the default color scheme assigned to the range values you’ve defined. For example, in the Clips and Tacks tutorial, we defined a KPI called Average Process Duration that tracks the average duration of the Order Handling process. We defined two ranges for this KPI: "Duration is Acceptable", and "Duration too Long." The default gauge view of this KPI uses a blue gradient as shown in FIgure 5.

Let’s change the colors for the gauge so that the range "Duration is Acceptable" is green and the range "Duration too Long" is red. To do this:

1. Click on the face of the gauge, and then click Go to properties in the pop-up dialog.
2. Select the Range tab in the KPI Properties dialog, as shown in Figure 6.
3. In the Color column, click on the color block for each range to select the new color, then click OK.
4. You can also select icons for the range in the Icon column. These icons are be displayed for the status in the KPI Table view.
   
   Figure 6. KPI Properties dialog
   
   
   
5. When you're done, click Apply, and then click OK.

Your KPI represented as a gauge should look like Figure 7.

Back to top

Update dashboard titles

One really easy way to customize dashboards is to change the default titles of the various views to customized titles. For example, if you have a view of process instances for an Order Handling process on your dashboard, the default title for the Instances view is "Instances", as shown in Figure 8:

You can click on the Instances title to change it to another title, such as "Current Order Handling Processes", as shown in Figure 9. Enter the new title and click Save.

If you've added filters to the Instances view, you might want to extend the title to reflect the filter content, such as "Completed Order Handling Processes for 2008."

Back to top

Putting it all together

Let’s look at the results of all our customization. Figure 10 shows the custom log-in screen.

Figure 11 shows the dashboard with the theme and title changes.

Figure 12 shows the additional theme effects and the new KPI range colors.

You've now learned how easy it is to customize the appearance of your Monitor dashboards to reflect your company's style or preferences.

Back to top

About the sample files

The following sample files are provided, which illustrate the techniques described in this article.

• Banner.html - uses the banner and background files
• ClipsTacks(banner).jpg - the banner image
• ClipsTacksBkgd.gif - the background image
• monitor.js - used to change the page background color
• Clips.js - theme file, and the image files it references
• Login.jsp - removes the wave image.
• Complete_monitor.js

Back to top

Download

Information about download methods

Resources

Learn

• Clips and Tacks tutorial. You can access the Clips and Tacks tutorial and other online samples from WebSphere Integration Developer by doing the following:
  • Select Help => Samples / Tutorials (WebSphere Integration Developer).
  • Select Retrieve next to Online Samples to get a list of available samples.
  
  
• WebSphere business process management zone: Get the latest technical resources for WebSphere BPM solutions, including articles, tutorials, events, downloads, and more.
  
  
• IBM WebSphere Business Process Management Version 6.1 Information Center: Get complete product documentation for BPM products.
  
  
• Business Process Management enabled by SOA: Get complete product information on IBM BPM software, including features and benefits, downloads, and more.
  
  
• Cascading Style Sheet Specification: Read the full W3C CSS specification.
  
  

Get products and technologies

• IrfanView: Download the tool
  
  
• Hex Color Finder: Download the tool.
  
  

About the authors

Michael Snare is an IT product specialist with twelve years experience supporting IBM customers in adopting business process management and monitoring tools in service-oriented architectures.

Billy Rowe is a Senior Software Developer for the On Demand Software Development team. Billy has held various positions within IBM as a developer, architect, and consultant, with his primary focus on developing reusable, object-oriented technologies and frameworks. You can contact Billy at browe@us.ibm.com.

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Install custom banners, colors, and themes
• Uninstall customizations
• Customize the business dashboard banner
• Customize background colors
• Customize themes
• Customize the colors for KPI ranges
• Update dashboard titles
• Putting it all together
• About the sample files
• Download
• Resources
• About the authors
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers