IBM Cognos Proven Practices: Customizing IBM Cognos 10 Login

Nature of Document: Proven Practice; Product(s): IBM Cognos 10.1; Area of Interest: Infrastructure, Security

This document is meant to supplement the Security and Administration Guide of IBM Cognos 10 by providing sophisticated examples for customizing the login page.

Share:

Antonio Marziano, Senior Technical Support Specialist, IBM

Antonio Marziano is a Senior Technical Support Specialist who has been with IBM Cognos for 10 years. His current role is technical support and escalation engineering with IBM Cognos BI Products. Specialist areas include Infrastructure and Security. He's a visionary and innovator with interests in working to improve internal IBM systems technologies for 'Smarter Working'.



Andreas Weber, Senior Support Analyst, IBM

Andreas Weber is a Senior Problem Resolution Analyst in IBM Cognos Support and has been working with IBM Cognos for 9 years. He specialized in Installation, Configuration, Security and IBM Cognos Software Development Kit.



Chris Shepherd, Technical Analyst , IBM

Chris Shepherd is a Problem Resolution Analyst in IBM Cognos Support and has been working with IBM Cognos for 2 years. Chris specializes in Unix and Linux systems and the IBM Blue Stack products.



06 January 2011

Also available in Chinese

Introduction

Purpose

This document is meant to supplement the Security and Administration Guide of IBM Cognos 10 by providing sophisticated examples for customizing the login page. The examples provided shall support the understanding of the possibilities and flexibility this great new feature offers.

Applicability

The examples have been built and tested against IBM Cognos 10 (build 10.1.4707.541) using IBM WebServer 7 (IHS7) and Mozilla 3.0.7 and Microsoft Internet Explorer 7.0.6001.

The feature of customizing the login and logoff behavior of IBM Cognos was introduced with IBM Cognos 10 and does not apply to earlier versions.

Exclusions and Exceptions

The document does expect the reader to be familiar with HTML 3.0 tags, AJAX and CSS and web development.

It is expected that the reader is familiar with the Customizing the IBM Cognos Connection Login Page section in Chapter 35 of the Administration and Security Guide.

Technical concept

The customization is a three step process. Once the browser requests the login page, the IBM Cognos 10 server will provide the prepared basic content (refer 1. in Figure 1 below). Next the browser will retrieve a JavaScript file and the style sheets from the Cognos Gateway (refer 2. in Figure 1 below). In the third step, the browser uses AJAX to request the customized template which is then processed by the JavaScript logic to eventually assemble the complete customized Login page.

Figure 1 - Sequence of generating the customized Login Page
Figure 1 - Sequence of generating the customized Login Page

Example 1: Leveraging AJAX

The sample template described in this example will use Asynchronous JavaScript and XML – AJAX (http://en.wikipedia.org/wiki/Ajax_%28programming%29) to request content from an arbitrary URL and display it on the login page. The technique leverages the customize() JavaScript function which allows you to call your own JavaScript functions after the template engine applied all other customization as described in the Administration and Security Guide.

The assumed use case is to have custom text maintained by the IT Department to show in the Login screen to inform the user about maintenance downtimes or other important information. The advantage is that updating the text is completely independent from the IBM Cognos 10 system and does not require recycling the servers or any downtime.

Of course this is just a simple use case. Leveraging AJAX enables a wide spectrum of possible uses and adoption should be straightforward with this example.

In this example we will name the template ibm1.xhtml and the file we load with AJAX will be on the same web server called customText_en.txt. The template will render a page using several tables and fetch text to be rendered in a table cell from a separate file by AJAX. In addition some <DIV> element containing a footnote will be appended to the HTML by AJAX as well.

The XHTML file

Below is the content of the ibm1.xhtml file used for this example. It contains some CSS, the JavaScript functions and the HTML section for the login page layout.

	<style type="text/css">
	img.logo {
		margin-top:50px; margin-bottom:50px; opacity:0.5; filter:alpha(opacity=50)
	}
	.footnote { font-size:60%; color:#000000; }
	body {
		background-color: #FFFFFF;
	}
</style>
<table width="100%" cellspacing="0" cellpadding="0" border="0">
	<tr><td width="100%"/><td nowrap="nowrap"><a style="color:#3399cc;
		 font-weight:bold; font-size:70%" href="#"
		 onclick="javascript:executeHelpCommand();">Help</a></td></tr>
</table>
<table width="100%" cellspacing="0" cellpadding="0" border="0">
	<tr>
		<td width="30%"/>
		<td width="40%">
			<img src="../samples/images/cover2.jpg"/ class="logo">
			<div id="customUsers"></div>
			<div id="%CL_PROMPT%"></div>
			<input type="submit" value="Login"
				 onclick="javascript:executeOKCommand();" />
			<input type="button" value="Cancel"
				 onclick="javascript:executeCancelCommand();" />
		</td>
		<td id="customTXT" width="30%"/>
	</tr>
</table>
<div id="%CL_PROMPT_namespace_label%">Namespace</div>
<div id="%CL_PROMPT_username_label%">User Name:</div>
<div id="%CL_PROMPT_password_label%">Password:</div>
<div id="%CL_PROMPT_oldPassword_label%">Old Password:</div>
<div id="%CL_PROMPT_newPassword_label%">New password:</div>
<div id="%CL_PROMPT_newPasswordConfirm_label%">Confirm old password:
	<img style="vertical-align:middle"
		 src="../ps/portal/images/state_warning_lrg.gif"/>
</div>
<div id="%CL_PROMPT_selectNamespace_caption%">
	<span style="color:gray">Please select a namespace.</span>
</div>
<div id="%CL_PROMPT_enterCredentials_caption%">
	<span style="color:gray;">Enter your credentials. </span>
</div>
<div id="%CL_PROMPT_badCredentialsEntered_caption%">
	<span style="color:red">The username or password you entered are not valid.</span>
</div>
<div id="%CL_PROMPT_passwordExpiry_caption%">
	<span style="color:red">Your password has expired.</span>
</div>
<div id="%CL_PROMPT_general_caption%">
	<span style="color:red">Authentication</span>
</div>
<script type="text/javascript">
	var xhr;
	var xhr2;
	function customize() {
		initCustom();
	}
	function initCustom(){
		xhr = loadAJAX();
		xhr.open("GET", "../ps/login/customText_en.txt", true);
		xhr.onreadystatechange = renderCustomText;
		xhr.send(null);
		var msgen = "<p>Our documentation includes user guides, getting started 
guides, new features guides, readmes, and other materials to meet the needs of our varied 
audience. The following documents contain related information and may be referred to in 
this document.</p>";
		var div = document.createElement("div");
		div.style.marginTop = "100px";
		div.innerHTML = "<span class=\"footnote\">" + msgen + "</span>";
		document.body.appendChild(div);
	}
	function loadAJAX() {
		var http;
		if (window.XMLHttpRequest) {
			http = new XMLHttpRequest();
		} else if (window.ActiveXObject) {
			try {
				http = new ActiveXObject('Msxml2.XMLHTTP');
			} catch (e) {
				try {
					http = new ActiveXObject('Microsoft.XMLHTTP');
				} catch (e) {
					alert("Cannot load XMLHttpRequest\r\n"
							 + e.description);
				}
			}
		}
		return http;
	}
	function renderCustomText(){
		if(xhr.readyState == 4){
			var ret = xhr.responseText;	
			var cstm = document.getElementById("customTXT");
			cstm.innerHTML = ret;
		}
	}
</script>

Note the place holder “<td id="customTXT" width="30%"/>” in the HTML. This will be used to show the custom text.

The JavaScript contains the following functions:

customize()
This function is called automatically when the page is loaded. Refer to the section Customizing the IBM Cognos Connection Login Page in Chapter 35 of the Administration and Security Guide.

InitCustom()
This function is starting the AJAX request and adding an DIV Block with some more text. As soon as the AJAX request has completed the function renderCustomText() is called.

renderCustomText()
This function is reading the text response to the AJAX request into a variable and adding the text into our login page by changing the DOM.

Install the example

To install this example

  • Save the provided code to a file called ibm1.xhtml in the ./webcontent/ps/login folder on the desired IBM Cognos 10 Gateway install.
  • Follow the steps outlined in the documentation (Security and Administration Guide, Chapter 35, “Customizing the IBM Cognos Connection Login Page”) to enable customized Login in the system.xml file, use the base-template-name of “ibm1”.
  • Create a text file customText_en.txt in the ./webcontent/ps/login folder and add some text to be displayed on the login page.
  • Recycle IBM Cognos 10 and access the IBM Cognos 10 Gateway URI to see the new login page.
Figure 2 - Screenshot showing the AJAX based customized login page
Figure 2 - Screenshot showing the AJAX based customized login page

Example 2: Multi-Language

The customized logon page feature has built-in support for locales. The template engine parsing the templates will try to load template files which have a suffix corresponding to the submitted browser locale. In this example we'll show a very basic application of this functionality by providing both an English and French logon page based on the browser locale.

Assuming the template is called login and the browser locale is EN the way this works is that IBM Cognos 10 will first check for a custom login page named login_en.xhtml. If this does not exist it will fall back to the default of login.xhtml. Since the fall-back file will contain English text this is what will be returned to any non-French browser. If the browser locale were FR the template login_fr.xhtml would have been loaded first. Since the customization reflects the entire displayed webpage, each locale is able to have its own custom logon page. Be aware that locale specific login pages are independent from the system locale and the locale specified for the IBM Cognos 10 system.

These examples are simple and create a page that is similar to the default IBM Cognos 10 login page.

The login.XHTML file

<style type="text/css">
.customWelcome { font-weight: bold; font-family: sans-serif; font-size: 14pt; }
</style>
<div id="loginBoxWithShadow">
<div id="loginBox" style="width:260px"> 
        <div id="loginBoxInner"> 
                <span class="customWelcome">Welcome to Cognos 10</span><br /><br />
                <div id="%CL_PROMPT%"></div><br />
                <input type="submit" value="Log In"
                 onclick="javascript:executeOKCommand();" />
                <input type="button" value="Cancel"
                 onclick="javascript:executeCancelCommand();" />
                <br />
                <br />

                <div id="%CL_PROMPT_namespace_label%">Namespace</div>
                <div id="%CL_PROMPT_username_label%">User Name: </div>
                <div id="%CL_PROMPT_password_label%">Password: </div>
                <div id="%CL_PROMPT_oldPassword_label%">Old Password:</div>
                <div id="%CL_PROMPT_newPassword_label%">New password:</div>
                <div id="%CL_PROMPT_newPasswordConfirm_label%">Confirm old password:
                <img style="vertical-align:middle"
                 src="../ps/portal/images/state_warning_lrg.gif"/>
                </div>
                <div id="%CL_PROMPT_selectNamespace_caption%">
                        <span style="color:gray">Please select a namespace.</span>
                </div>
                <div id="%CL_PROMPT_enterCredentials_caption%">
                        <span style="color:gray;">Enter your credentials.</span>
                </div>
                <div id="%CL_PROMPT_badCredentialsEntered_caption%">
                        <span style="color:red">The username or password
                                 you entered are not valid.</span>
                </div>
                <div id="%CL_PROMPT_passwordExpiry_caption%">
                        <span style="color:red">Your password has expired.</span>
                </div>
                <div id="%CL_PROMPT_general_caption%">
                        <span style="color:red">Authentication</span>
                </div>
        </div>
</div></div>

The login_fr.XHTML file

<style type="text/css">
.customWelcome { font-weight: bold; font-family: sans-serif; font-size: 14pt; }
</style>

<div id="loginBoxWithShadow">
<div id="loginBox" style="width:260px"> 
    <div id="loginBoxInner"> 
    <span class="customWelcome">Bienvenue a Cognos 10</span><br /><br />
    <div id="%CL_PROMPT%"></div><br />
        <input type="submit" value="Log In"
                 onclick="javascript:executeOKCommand();" />
        <input type="button" value="Cancel" 
                 onclick="javascript:executeCancelCommand();" />
        <br />
        <br />

        <div id="%CL_PROMPT_namespace_label%">Espace-noms:</div>
        <div id="%CL_PROMPT_username_label%">Code d'utilisateur: </div>
        <div id="%CL_PROMPT_password_label%">Mot de passe: </div>
        <div id="%CL_PROMPT_oldPassword_label%">Mot de passe: </div>
        <div id="%CL_PROMPT_newPassword_label%">Nouveau mot de passe:</div>
        <div id="%CL_PROMPT_newPasswordConfirm_label%">Confirmer le mot de passe:
        <img style="vertical-align:middle" 
                 src="../ps/portal/images/state_warning_lrg.gif"/>
     </div>
    <div id="%CL_PROMPT_selectNamespace_caption%">
         <span style="color:gray">Please select a namespace.</span></div>
    <div id="%CL_PROMPT_enterCredentials_caption%">
         <span style="color:gray;">Enter your credentials. </span></div>
    <div id="%CL_PROMPT_badCredentialsEntered_caption%">
         <span style="color:red">The username or password 
                                 you entered are not valid.</span></div>
    <div id="%CL_PROMPT_passwordExpiry_caption%">
         <span style="color:red">Your password has expired.</span></div>
    <div id="%CL_PROMPT_general_caption%">
        <span style="color:red">Authentication</span></div>
</div></div>

Install the example

To install this example

  • Save the provided code to files named login.xthml and login_fr.xhtml in the ./webcontent/ps/login folder on the desired IBM Cognos 10 Gateway install.
  • Follow the steps outlined in the documentation (Security and Administration Guide, Chapter 35, “Customizing the IBM Cognos Connection Login Page”) to enable the customized login in the system.xml file, use the base-template-name of “login”.
  • Recycle IBM Cognos 10 and access the IBM Cognos 10 Gateway URI to try it with a browser set to EN locale. You should see the English version of the login page.
  • Switch your browser locale to FR and access the IBM Cognos 10 Gateway URI Gateway again to see the French version of the login page.

With these two simple template examples in place, by default all French users will see an alternate copy of the logon page with French primary dialog text and English error messages.

Users who are not using a French browser or language configuration will be presented with an all-English login page.


Example 3: Marquee in an IFRAME

This example shows to post a scrolling message within the login page to warn or advise users of important announcements. Here the login page presents users with a scrolling marquee that displays an announcement telling them that the system will be unavailable after 5 PM due to a reboot. This is one way to send out a global message without flooding the network with additional traffic.

Here is what it looks like, showing direction of the scrolling marquee (red arrow),

Figure 3 - Screenshot showing the customized login page using a marquee
Figure 3 - Screenshot showing the customized login page using a marquee

The process is as follows:

  1. Add the following section of HTML code in your customized template. This HTML code contains an <IFRAME> element that displays a URL to a static html page containing the message that dynamically appears within the marquee.
    <table border="0" cellpadding="3" cellspacing="0" width="100%" ><tbody><tr><td>
    <iframe src="http://<server>/<C10_ALIAS>/ps/login/alerts.html" width="100%"
       height="40%" frameborder="no" scrolling="no"></iframe>
    </td></tr></tbody></table>
    Note: The <server> used in the URL for the <IFRAME> content must be added to the trusted hosts and domains in IBM Cognos Configuration. <C10_ALIAS> is whatever was used for the virtual directory alias to reach the IBM Cognos 10 Gateway, for example /c10.
  2. The text of the message to scroll across the screen is put into a separate HTML file which should contain the following HTML and JavaScript code:
    <html>
    <head>
    <script type="text/JavaScript">
    <!--
    function timedRefresh(timeoutPeriod) {
    	setTimeout("location.reload(true);",timeoutPeriod);
    }
    //   -->
    </script>
    </head>
    <body onload="JavaScript:timedRefresh(10000);">
    <div align="center"><FONT color="#ffffff" size="+1">
    <MARQUEE bgcolor="#000080" transparency=100 direction="left" loop="20" width="75%">
    <STRONG>Announcement! System will be unavailable after 5pm due to a reboot.</STRONG>
    </MARQUEE>
    </FONT></DIV>
    </body>
    </html>

    Save above HTML code to a file called “alerts.html” in the ./webcontent/ps/login folder.
    Here the <MARQUEE> tag contains the message that will be scrolled across the screen. In this example, the message will be 'Announcement! System will be unavailable after 5pm due to a reboot'. In addition, the following JavaScript code sets the refresh of the HTML page to accommodate the changes to the message at anytime and will refresh within 10 seconds.
    <script type="text/JavaScript">
    <!--
    function timedRefresh(timeoutPeriod) {
    	setTimeout("location.reload(true);",timeoutPeriod);
    }
  3. When the <IFRAME> is rendered by the browser, the <body onload= tag will tell the browser to call the function which refreshes the page and the <IFRAME> will display the scrolling the message 'Announcement! System will be unavailable after 5pm due to a reboot.' across the screen.

Appendix A

Enabling customization to work on Microsoft IIS7

When using the Microsoft IIS7 web server the AJAX requests to load the customization templates will fail and the customization won't show up. Instead one will always see the default login page.

The reason for this is that IIS7 by default doesn't know how to handle files with .xhtml extension and blocks them. The fix is to add a MIME-type mapping for .xhtml as text/xml.

In Internet Information Services Manager (IISM), select the Features View of your IBM Cognos 10 web alias, for example /c10.

Double-Click MIME-Types.

Figure 4 - Features View of /c10 alias in IISM
Figure 4 - Features View of /c10 alias in IISM

Next, select Add... in the upper right.

Add a new MIME type for the .xhtml extension to text/xml.

Figure 5 - Add new MIME Type for xhtml extension in IISM
Figure 5 - Add new MIME Type for xhtml extension in IISM

Press OK to save and try accessing the Login Page again.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Big data and analytics on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Big data and analytics, Information Management
ArticleID=604304
ArticleTitle=IBM Cognos Proven Practices: Customizing IBM Cognos 10 Login
publish-date=01062011