IBM Cognos Proven Practices: Embed IBM Cognos Now! Dashboard Objects and Reports in Custom Web Applications

Nature of Document: Tip or Technique; Product(s): IBM Cognos Now!; Area of Interest: Development

This write-up will help IBM Cognos Now! users in understanding how they can embed IBM Cognos Now! dashboard objects and reports in their external HTML applications and web pages.


Prakash Dewan, Business Analytics Professional, IBM

photo of Prakash DewanPrakash Dewan holds a masters degree in Computer Applications and has 5 years of experience in testing enterprise level products. As a member of IBM Cognos engineering team at IBM Software Labs, he works on the verification and validation of various features and functions of the product. He has deep skills in developing test automation frameworks using tools like IBM Rational Functional Tester, Mercury Quicktest Professional and WinRunner.

10 December 2010

Also available in Chinese



This write-up will help IBM Cognos Now! users in understanding how they can include/embed IBM Cognos Now! dashboard objects and reports in their external HTML applications and web pages.


  • The technique described in this write-up applies to both appliance and software/OEM offerings of IBM Cognos Now! version 4.3 and onwards.
  • With software/OEM offering, the option of embedding Query and Report Studio reports will not apply as there is no integrated IBM Cognos BI
  • This technique will only work in Internet Explorer version 6 or higher

Exclusions and Exceptions

This write-up assumes that IBM Cognos Now! is installed and fully operational.

What’s the need?

IBM Cognos Now! provides support for showing dashboard objects as portlets on all major portal servers including WebSphere, WebLogic and JBoss. However there are scenarios when users have requirements to show specific IBM Cognos Now! dashboard objects and/or reports in their existing web applications. This could be a web interface to their existing system/software or a simple web page.


Forming the URL

Embedding Dashboard Objects can be accomplished by making use of the /dashboard/doreader.htm resource of IBM Cognos Now! server which takes the following parameters in the URL.

  • <sessionID> - Valid session ID of the user who will login
  • <refreshinterval> - applies to dashboard objects, refresh interval (In seconds)
  • <reportrefreshinterval> - applicable to Report/Query studio reports, refresh interval (In minutes)
  • <do> - Fully qualified name of the Dashboard Object or Report to be displayed. For example dashboard object “do1” in folder “f1” should be passed in as “f1.do1”.
  • <type> - Required in case of Query/Report studio reports

URL syntax for Dashboard Object


URL syntax for Query Studio Reports


URL syntax for Report Studio Reports


Obtaining a valid session ID

A valid session ID for the IBM Cognos Now! server can be obtained by hitting the server’s /Controller/UserAction/Login action with an XML request as shown below,


The following JavaScript code demonstrates logging on to the IBM Cognos Now! Server:

var strServerURL = “http://cognos-now-server:port/cognos/now”      
var strUser = “xyzUser”
var strPassword = “xyzPassword”
var xml = new ActiveXObject("Microsoft.XMLDOM");
xml.documentElement.selectSingleNode("/login/user").text = strUser;
xml.documentElement.selectSingleNode("/login/password").text = strPassword;
var sURL = strServerURL + "/Controller/UserAction/Login";
var xmlhttp = new ActiveXObject("Microsoft.XMLHTTP")

If user authentication is successful a sessionID is returned. This can be extracted from the response XML as shown in code listing below. In case of an exception on the server, e.g. Authentication failure, the code also notifies the user with an appropriate message.

try {"POST", sURL, false);
    } catch(e) {
      alert("Make sure a valid server URL is entered.");
      return null;
if(xmlhttp.responseXML.documentElement.tagName.match("structuredException")) {
 alert("Error logging in. Please check your user name and password.");
 return null;} 
else {
 return xmlhttp.responseXML.selectSingleNode("/loginResp").getAttribute("sessionid");

The included sample uses the same implementation to obtain a valid sessionID as shown above. The sample then constructs an URL to the report via the following code:

if(dashboardName.value.replace(/(^\s*)|(\s*$)/g, "") != '') {
if(objecttype.value == "DO"){ //For Dashboard Object
url = txtServerURL.value + "/dashboard/doreader.htm?sessionID="+sessionID+"
else{ //In case of Report/Query Studio Report
url = txtServerURL.value + "/dashboard/doreader.htm?sessionID="+sessionID+"

Encoding the Dashboard Object or Report Name

In order to avoid broken URLs, encoded fully-qualified names of Dashboard Objects should be used. The sample included with this article uses the Javascript encodeURIComponent() method to encode the dashboard object or Report name as demonstrated below:


The above function not only escapes special characters but it also replaces single occurrences of double quotes (“) with back to back double quotes (“”), so that any Dashboard Object or Report having a double quote in it's name can be discovered successfully.

Embed Dashboard Object URL in Web page

Once we have constructed an URL with valid session ID, it can be embedded into the web application or a web page in a variety of ways.

As a source to <IFRAME>

txtURL = txtServerURL.value + "/dashboard/doreader.htm?sessionID="+sessionID+"
document.write(“<IFRAME src=” & txtURL & “width=400 height=300>”);

As a source to <FRAME>

txtURL = txtServerURL.value + "/dashboard/doreader.htm?sessionID="+sessionID+"
document.write(“<FRAME src=” & txtURL & “>”);

As a Masked Link

txtURL = txtServerURL.value + "/dashboard/doreader.htm?sessionID="+sessionID+"
document.write(“<a href=” & txtURL & “>Business Metrics</a>”);

The examples above are only demonstrate a few possibilities. The URL to the IBM Cognos Now! Dashboard Object or Reports can be used by the web application developer in which ever way best fits into an web application.

Other Tips

  1. Similar to Login action, one can implement Logout action as well by hitting Cognos Now server’s /Controller/UserAction/Logout action with an XML of following schema in request.

    Below is the implementation of logout(), which is part of the sample web page as well,
    var xml = new ActiveXObject("Microsoft.XMLDOM");
    xml.documentElement.selectSingleNode("/logout/user").text = currentLoggedInUser;
    var sURL = currentUserServerURL + "/Controller/UserAction/Logout";
    var xmlhttp = new ActiveXObject("Microsoft.XMLHTTP")
     try {
 "POST", sURL, false);
    			alert("You are logged out successfully!");
         } catch(e) {}
  2. A Click on dashboard object’s title in the web page will open up its detailed view in IBM Cognos Now! dashboard application in another browser window for further analysis and monitoring requirements.

Samples - Explained

JavaScript Sample

The sample html web page DoinIFRAME.html that implements the technique defined in this write-up is included. The example is written to embed/show IBM Cognos Now! Dashboard Object or Query/Report studio reports in an IFRAME. The sample is written with the IBM Cognos Now! Appliance in mind, i.e. Integrated Report and Query studios and therefore it project options to embed Dashboard Object, Query Studio Report and Report Studio Report.

NOTE: Users with Software/OEM install of IBM Cognos Now! can refer this sample for Dashboard Objects only as software/OEM installs will not have integrated reporting, i.e. Report and Query studios.

HTML Form Fields

Figure 1 - HTML Form Fields
Figure 1 - HTML Form Fields

Below are details of HTML form fields of the sample web page,

  • Server URL: IBM Cognos Now! Server URL, i.e. http://<server-name>:<port>/<server-context>, e.g.
  • User name: User who you want to log into IBM Cognos Now!
  • Password: Password for the concerned user
  • Object Type: Dashboard Object OR Query Studio Report OR Report Studio Report
  • Dashboard Object/Report: Fully Qualified Name of the object which you want to show in IFRAME
  • Refresh Interval: Time interval at which you want to refresh the object shown in IFRAME. Unit of time for Dashboard Object is seconds whereas for Reports, it is minutes

Once the user fills out the html form and clicks the Submit button the requested Dashboard Object/Report shows up in an IFRAME. In addition to this a label URL for reference appears along with a Logout link (as shown below):

Figure 2 - Reference URL
Figure 2 - Reference URL

Dashboard Object in IFRAME

Figure 3 - Object in IFRAME
Figure 3 - Object in IFRAME

Query Studio Report in IFRAME

Figure 4 - Query Studio Object in IFRAME
Figure 4 - Query Studio Object in IFRAME

Report Studio Report in IFRAME

Figure 5 - Report Studio Object in IFRAME
Figure 5 - Report Studio Object in IFRAME

JSP Sample

An additional Java Server Page (JSP) sample FormDoUrl.jsp is also shipped with this article for your reference. This JSP implements similar logic as the HTML/JavaScript Sample.


Article contained in ZIP fileEmbed_IBM_Cognos_Now_Dashboard_Objects_and_Reports_in_Custom_Web_Applications.zip331KB


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

  • Bluemix Developers Community

    Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.

  • Big data and analytics

    Crazy about Big data and analytics? Sign up for our monthly newsletter and the latest Big data and analytics news.

  • DevOps Services

    Software development in the cloud. Register today to create a project.

  • IBM evaluation software

    Evaluate IBM software and solutions, and transform challenges into opportunities.

Zone=Big data and analytics, Information Management
ArticleTitle=IBM Cognos Proven Practices: Embed IBM Cognos Now! Dashboard Objects and Reports in Custom Web Applications