Get started with the IBM Cognos Mashup Service

Fast application development for Cognos BI report content

The IBM® Cognos® Mashup Service (CMS) allows you to easily extract Cognos Business Intelligence report content and integrate it into applications such as Google Maps, Google Earth, Yahoo desktop widgets, Adobe Flex, IBM Lotus Notes, and other third party Flash or charting engines. This article introduces CMS and includes several examples showing what you can accomplish using this new Web service.

Cynthia D. Sleigh (Cynthia.Sleigh@ca.ibm.com), Senior Software Developer, IBM

Author Photo: Cynthia SleighCynthia Sleigh is a senior member of the IBM Cognos SDK and Diagnostic Team. She specializes in Cognos Mashup Services and the Cognos Software Development Kit.



Iman Johari (iman.johari@ca.ibm.com), Software Developer, IBM  

Iman Johari photoIman Johari is a member of the IBM Cognos SDK and Diagnostic Team. He specializes in Cognos Mashup Services, the Cognos Software Development Kit, and diagnostic tools.



07 January 2010

Also available in Portuguese Spanish

Introduction

IBM DB2 e-kit for Database Professionals

Learn how easy it is to get trained and certified for DB2 for Linux, UNIX, and Windows with the IBM DB2 e-kit for Database Professionals. Register now, and expand your skills portfolio, or extend your DBMS vendor support to include DB2.

Cognos Mashup Service (CMS) is a new Web service that is included as part of the IBM Cognos Software Development Kit. This article introduces CMS and explains its two different interfaces: REST and SOAP. The article shows you some of what you can accomplish with CMS by providing sample code and highlighting some of the samples that are installed with the Cognos Mashup Service. To get the most out of this article, you should have basic knowledge of IBM Cognos 8 Business Intelligence (BI) and a basic understanding of programming languages and Web technologies.

System prerequisites

In order to execute the examples in this article, you need the following:

  • IBM Cognos 8.4.1 BI
  • IBM Cognos 8.4.1 Software Development Kit

What can you accomplish with CMS?

The IBM Cognos Mashup Service provides a way for you to integrate Cognos reports with other applications. You can use either of two interfaces to accomplish this integration:

  • Representational State Transfer (REST). This interface uses basic HTTP requests.
  • Simple Object Access Protocol (SOAP). This interface can be used to programmatically access the CMS API.

The example below demonstrates a complete CMS integration. Figure 1 shows a portion of a sample IBM Cognos 8.4.1 Report Studio report. The report contains sales revenue data for a fictitious company. The data is broken down according to the location of each of the company's offices. Figure 2 shows the result when the report is integrated with a Google Earth map. The sales figures for each office are overlaid on the map according to the office's location. This is accomplished using the Google Maps API along with the CMS REST interface.

Note: This article is geared towards an introductory walk-through of CMS and does not cover the specifics of how to use the Google Maps API.

Figure 1. Sample IBM Cognos report results in HTML format
Sample Cognos sales data report showing address and sales revenue for a company's central European office
Figure 2. IBM Cognos report results overlaid on Google Earth using IBM Cognos Mashup Service
Google Earth map of Europe with the sales results from Figure 1 overlaying the map according to the address of each sales office.

How is CMS different from the Cognos Software Development Kit (SDK)?

Table 1 compares and contrasts the Cognos SDK with CMS.

Table 1. Cognos SDK compared with CMS
SDKCMS
Report authoringSupports authoringDoes not support authoring
Programming languagesJava®, .NET Languages, VBJava, .Net Languages, REST interface
Output formatsCSV, HTML, HTML Fragment, MHT, PDF, single XLS, spreadsheet ML, XHTML, XLS, XLWA, XMLLDX, XML, HTML, HTML Fragment, JSON
Note: LDX stands for Layout Data XML. It is a new format.
Major functionalityAlmost everything that can be done with Cognos Connection, in addition to automating operationsRun and get the report outputs and enable access to report output elements to the smallest granular level possible
AuthenticationYesYes - via SDK or own authentication service, for REST you can also use Cognos 8 logon.
APIJava: Jar files available in sdk folder, Microsoft® .Net: .dll files available in sdk folderUse of WSDL files to consume available functionality through Web services

Using the CMS

The examples in this section illustrate how to use the REST and SOAP interfaces to extract different components of a Cognos report.

REST interface

The generic URL for a REST request is:

http://webservername:portnumber/cognos8/cgi-bin/cognos.cgi/rds/resource_type/source_type/source_id?option1=val1&option2=val2...

Table 2 shows the main building components of the REST API.

Table 2. Main building components of REST API
Resource typesSource typesOptions
auth/logonconversationIDasync
auth/logoffpathburstID
atomreportburstKey
promptPagesearchPathcontextId
reportDatadirection

For more information, including additional options, refer to the Mashup Services Developer Guide (see the Resources section for details on where to find the guide).

REST example 1:

This first REST API example demonstrates how to get all the charts available in a report that contains a combination of a list and charts. The example returns all the charts from the report in Layout Data XML (LDX) format.

The following parameters are used to build the URL for the example:

  • Resource type: reportData
  • Source type: report
  • Resource_id: report store id; for example, iE0CDFEF149F8408F96F1C27DCFFA6BCB
  • Options: fmt=layoutDataXML, xpath=//chart

The URL itself looks like this:

http://localhost/c841/cgi-bin/cognos.cgi/rds/reportData/report/iE0CDFEF149F8408F96F1C27DCFFA6BCB?fmt=layoutDataXML&xpath=//chart

Listing 1 shows the resulting LDX.

Listing 1. LDX resulting from the sample REST call
 <filterResultSet xmlns="http://www.ibm.com/xmlns/prod/cognos/layoutData/200904">
  <filterResult>
  <filterType>XPATH</filterType>
  <filterValue>//chart</filterValue>
   <reportElement>
    <chart>
     <palette>
      <paletteItem>
       <pattern>
        <type>ePatternSolid</type>
         <fgColor>
         <red>51</red>
         <green>51</green>
            .
            .
            .
		 
   </reportElement>
  </filterResult>
 </filterResultSet>

REST example 2:

This example accesses data from the same report as the first example. It returns a single chart from the report as an HTML Fragment.

The following parameters are used to build the URL for the example:

  • Resource type: reportData
  • Source type: report
  • Resource_id: report store id; for example, iE0CDFEF149F8408F96F1C27DCFFA6BCB
  • Options: fmt=HTMLFragment, selection=Chart1

The URL itself looks like this:

http://localhost/c841/cgi-bin/cognos.cgi/rds/reportData/report/iE0CDFEF149F8408F96F1C27DCFFA6BCB?fmt=HTMLFragment&selection=Chart1

Figure 3 shows the resulting chart generated from the returned HTML Fragment.

Figure 3. Chart generated from IBM Cognos Mashup Service
Screenshot of a sample chart showing revenue by city.

Before this operation is feasible, the user must be authenticated with IBM Cognos 8. One method to authenticate is to use the CMS authentication service logon method described in the Mashup Services Developer Guide (see the Resources section for details on where to find the guide).

REST example 3:

This example shows how to run a report in HTML format with a maximum of three rows of data returned on each page.

The following parameters are used to build the URL for the example:

  • Resource type: reportData
  • Source type: report
  • Resource_id: report store id; for example, i6243D3E1A36A4E0FAF9D90652C171FC2
  • Options: fmt=HTML, selection=List1, rowLimit=3

The URL itself looks like this:

http://localhost/c841/cgi-bin/cognos.cgi/rds/reportData/report/i6243D3E1A36A4E0FAF9D90652C171FC2?fmt=HTML&selection=List1&rowLimit=3

Figure 4 shows the resulting table generated from the returned HTML.

Figure 4. Limited output in HTML format using IBM Cognos Mashup Service
Screenshot of an HTML table with one column and three rows

SOAP interface

Table 3 shows a few of the generic methods of the SOAP API interface.

Table 3. SOAP methods
MethodDescription
drill Use this secondary method to drill up or down in an existing report session.
getOutput Use this method to retrieve the output of a report.
getPromptAnswers Use this method after a getPromptPage request to retrieve the answers associated with a prompt page.
getPromptContent Use this method to retrieve the content of a report.
getReportData Use this method to retrieve the content of a report in a specified format.

For more information, including additional options, refer to the Mashup Services Developer Guide (see the Resources section for details on where to find the guide).

SOAP example using Java API:

This example demonstrates how to extract a list that accesses all the report elements from a report that includes a list and a graph.

Sample Java code
  ReportDataServicePortProxy proxy = new ReportDataServicePortProxy();
  //The endpoint will be the gateway URL for your server
  proxy.setEndpoint(url);
  
  ReportDataServicePort mashupService = proxy.getReportDataServicePort();
  
  GetReportDataRequest request = new GetReportDataRequest();
  //This sets the cm searchPath as the source of the report, you 
  //could alternatively use the storeId
  request.setSourceID("/content/folder[@name='Samples']/folder[@name='Models']
  /package[@name='GO Data Warehouse (analysis)']/folder[@name='Query Studio
  Report Samples']/query[@name='Returns by Product Type']");
  
  //This identifies that the sourceID refers to a CM search path
  request.setSourceType(SourceTypeEnum.searchPath);
  //This creates an object id filter to only return the List1 element, 
  OBJECT_ID is the type of filter that
  //filters based on element id.
  Filter[] filters = {new Filter("List1", FilterTypeEnum.OBJECT_ID, null)};
  request.setFilters(filters);
  
  GetOutputResponse response = mashupService.getReportData(request);
  GetOutputRequest outputRequest = new GetOutputRequest();
  
  /*
  * This loop is necessary when running asynchronously
  */
  while(response.getSession().getStatus() == SessionTypeStatus.working)
  {
  outputRequest.setSession(response.getSession());
  response = mashupService.getOutput(outputRequest);
  }
  
  /*
  * This block of code goes through the list contents and outputs them to the console
  */
  ListFrame list1 = response.getOutput().getLDXOutput()
  .getFilterResultSet().getFilterResult()[0]
  .getReportElement()[0].getLst();
  Row[] rows = list1.getGroup().getRow();
  
  System.out.println();
  System.out.print("Product type");
  int spaceOfCell=25-("Product type".length());
  for (int n=0;n<spaceOfCell;n++)
    {	System.out.print(" ");}
    
    System.out.print("Base product");
    spaceOfCell=35-("Base product".length());
    for (int n=0;n<spaceOfCell;n++)
    {	System.out.print(" ");}
    
    System.out.print("Lost revenue");
    spaceOfCell=20-("Lost revenue".length());
    for (int n=0;n<spaceOfCell;n++)
      {	System.out.print(" ");}
      
      System.out.println();
      System.out.println();
      
      for(int i = 0; i < rows.length; i++)
      {
      Cell[] cells = rows[i].getCell();
      
      System.out.print(cells[0].getItem(0).getTxt().getFmtVal());
      spaceOfCell=25-(cells[0].getItem(0).getTxt().getFmtVal().length());
      for(int j=0;j<spaceOfCell;j++)
        {   System.out.print(" ");}
        
        System.out.print(cells[1].getItem(0).getTxt().getFmtVal());
        spaceOfCell=35-cells[1].getItem(0).getTxt().getFmtVal().length();
        for(int j=0;j<spaceOfCell;j++)
        {  	System.out.print(" ");}
        
        System.out.print(cells[5].getItem(0).getTxt().getFmtVal());
        spaceOfCell=20-cells[5].getItem(0).getTxt().getFmtVal().length();
        for(int j=0;j<spaceOfCell;j++)
          {   System.out.print(" ");}
          
          System.out.println();
          }

Figure 5 shows an example of what the output generated by the above sample code would look like:

Figure 5. Results from Java example
Screenshot of sample code output showing a table with three columns: Product type, Base product, and Lost revenue

Sample applications

Currently, CMS includes several samples. The samples are installed by default as part of the IBM Cognos Software Development Kit.

The REST samples are written in HTML and JavaScript. These samples can be run from a Web server and are installed in the following directory:

<c8_install>/webcontent/samples/sdk/cms

The SOAP API samples are written in C# and Java. These samples are installed in the following directory:

<c8_install>/sdk/cms

For more information on the samples, refer to the Mashup Services Developer Guide (see the Resources section for details on where to find the guide).

Figure 6 shows a screenshot of the main menu of the JavaScript samples to give you an idea of what they contain. The samples are not meant to be end-user applications; they only demonstrate what you can accomplish with CMS.

Figure 6. Sample programs
Screenshot with a list of links to the CMS JavaScript samples.

Summary

Thank you for your interest in this introductory article to IBM Cognos Mashup Services. The purpose of the article was to give you an idea of what can be accomplished with CMS as well as how to perform some basic tasks using the two different interfaces.

Resources

Learn

  • The Mashup Services Developer Guide is included with the installation of IBM Cognos software. After installing Cognos, you can find the English version of the guide here:
    IBM Cognos installation directory\webcontent\documentation\en\dg_cms.pdf
  • "IBM Cognos Mashup Service Product description and demo"
  • "IBM Cognos SDK Validation Tool" (developerWorks, August 2008), provides information about the Cognos SDK validation tool that you can use to run a complete validation check of all the reports in the Content Store.

Discuss

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. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. 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 Business analytics on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Business analytics, Information Management
ArticleID=460341
ArticleTitle=Get started with the IBM Cognos Mashup Service
publish-date=01072010