IBM Business Analytics Proven Practices: IBM Cognos 10 BI SDK Application To Merge Reports

Nature of Document: Proven Practice; Product(s): IBM Cognos 10 BI; Area of Interest: Development

A IBM Cognos 10 SDK application that will merge reports created in Report Studio. This application will work with IBM Cognos 10 BI versions 10.1.x and 10.2.

Jurgen Hoogerboord, Principal Solutions Architect, IBM

Jurgen Hoogerboord has worked for IBM Cognos since 2002 in a variety of roles in Support, Services and Pre Sales and has worked with the Cognos SDK since it was launched as part of Cognos ReportNet. Currently Jurgen is a Principal Solutions Architect in the European Products and Technology Experts Team.



Aakash Sharma, Systems Software Engineer, IBM

Aakash SharmaAakash Sharma is a Systems Software Engineer with IBM Business Analytics Group in India. His primary role consists of bridging the gap between various development teams, IBM Cognos Support organization and the customer base. Aakash has been involved for last 3 years in various capacities. His main focus throughout has always been customer's delight.



04 February 2013

Also available in Portuguese Spanish

Introduction

Purpose

This document and the accompanying IBM Cognos 10 SDK application provide the ability to merge several IBM Cognos 10 BI reports that were created in Report Studio into a single report. This is useful for creating a report booklet that is made up of various reports. An example of a report booklet would be a monthly statement package sent to individuals by a financial institution that contains a checking account statement, an investment account statement and a credit card statement.

Applicability

This application works with IBM Cognos 10 BI 10.1.x and 10.2 reports that have been created with Report Studio.

Usage, support and feedback

This application is provided on a strictly “as is” basis and IBM Cognos Support is not able to offer any support for it. If you have questions or comments, use the developerWorks comments facility at the bottom of this page.


Installation

The application is deployed as a WAR (Web ARchive) file that can be used with a servlet container such as Tomcat or an application server such as IBM WebSphere. You must first build the WAR file within your IBM Cognos 10 installation using the supplied scripts and then deploy the WAR file to your server.

The procedures outlined in this document cover deploying the application into the Tomcat servlet container that is normally installed with an IBM Cognos 10 Dispatcher. Consult the documentation of the specific servlet container or application server for instructions on deploying a WAR file into alternative destinations.

The process for installation is as follows,

  • Unpack the installation to an IBM Cognos 10 server
  • Configure properties files
  • Build the WAR file
  • Deploy the WAR file to an application server or servlet container

Unpack files

Unpack the ZIP file containing the c10MergeReports application to a suitable temporary location on a machine that has an existing installation of an IBM Cognos 10 Dispatcher. Take the war/c10MergeReports directory and place it in the IBM Cognos 10 installation directory under <c10_install>/war.

Configure properties files

At this point, you can configure the application before building the WAR file. The default settings should be fine in most instances but if you need to make any changes to the configuration settings in the c10MergeReports.properties file or the logging settings in the log4j.properties file, the files are located in the <c10_install>/war/c10MergeReports/classes directory.

In the c10MergeReports.properties file there are five properties that can be modified,

c10.url - Used by the c10MergeReports application to connect to IBM Cognos 10. The default value is http://localhost:9300/p2pd/servlet/dispatch. The value to use is the External Dispatcher URI of the IBM Cognos 10 machine that will handle the requests from the c10MergeReports application. The External Dispatcher URI can be found using the IBM Cognos Configuration tool.

C10.imagebase - Used by the c10MergeReports application to retrieve the IBM Cognos 10 images and stylesheets. The default value is http://localhost:80/cognos10. The value to use is the URI of an IBM Cognos 10 gateway.

debug.flag - Regardless of log4j detail settings, most logging is switched off unless this property is set to true. This property should only be set to true for troubleshooting purposes and should always be set to false in a production environment.

log.location - Location of log file created by log4j as specified in the file WEB-INF/classes/log4j.properties. Please note that any directory name must have a trailing slash.

stylesheet.main - Contains the name of the stylesheet that is used to generate the pages for the IBM Cognos 10 BI Merge Reports wizard.

In the log4j.properties file, the settings should not need to be changed if the WAR file is deployed to the Tomcat servlet container that is installed with an IBM Cognos 10 Dispatcher.

Build and deploy the WAR file

Build the WAR file by running the <c10_install>/war/c10MergeReports/build.bat (Windows) or <c10_install>/war/c10MergeReports/build.sh (UNIX/Linux) script. This will create the WAR file <c10_install>/war/c10MergeReports/c10MergeReports.war. Place this file in the <c10_install>/webapps directory. After a short time, the IBM Cognos 10 Tomcat server will automatically unpack the WAR file.

Setting up authentication

The application does not provide any method of authentication and relies on single signon with IBM Cognos Connection.

Copy the file c10MergeReports.xml to <c10_install>/templates/ps.

Edit the file <c10_install>/templates/ps/c10MergeReports.xml and for the line that reads <CRNenv c_cmd="http://localhost:9300/c10MergeReports/Manager"> change localhost:9300 to the server and port number of the servlet container or application server that is hosting the c10MergeReports application.

Considerations for deploying into standalone environment

If installing into a heavily used production environment, you should consider installing into another servlet container. This could be a standalone Tomcat instance or a full application server such as the IBM WebSphere Application Server. Generally, the procedure is as simple as deploying any web application – in the case of Tomcat, you can just drop the WAR file into the webapps directory as you would with IBM Cognos 10.

If installing into a standalone servlet container or application server, it will likely be necessary to change the path to the log file in WEB-INF/classes/log4j.properties. By default, the log file name is specified using the relative path ../logs/c10MergeReports.log. While this works when the application is installed alongside IBM Cognos 10, you may need to change this to either a different relative path or a fully qualified path such as C:/logs/c10MergeReports.log.

Another alternative configuration is to install into a dedicated IBM Cognos 10 installation. As the c10MergeReports application can communicate with multiple IBM Cognos 10 servers and not just the one it is installed in, you could have a dedicated IBM Cognos 10 instance for running this application . Verify your licensing to determine is this is a viable alternative.


Using The Application

About the merge process

Uniqueness

Any Report Studio report can be merged with any other Report Studio report, including reports that contain prompts, variables or conditional formatting. Any pages, prompt pages, variables, queries will be renamed with a preceding number to avoid duplicates. For example,

  • 'Query1' of the first report will be renamed to '1_Query1'
  • 'Page1' of the first report will be renamed to '1_Page1'

Common prompt pages

When merging reports with prompt pages, the application will not check if the reports to be merged have any prompt parameters in common. Prompt pages and prompt parameters will be merged as they are. The report author can remove the prompt pages afterwards in Report Studio and if desired, link all report pages with one prompt page/ parameter. For example,

  • A Savings account statement report that contains a
    • Date prompt page
    • Statement page
  • A Checking account statement report that contains a
    • Date prompt page
    • Statement page
  • Merging these reports will result in a single Savings and Checking account statement report that contains a,
    • Date prompt page from the Savings account statement report
    • Date prompt page from the Checking account statement report
    • Statement page from the Savings account statement report
    • Statement page from the Checking account statement report

Accessing the application

The c10MergeReports application can be activated from a browser using the following URL to an IBM Cognos 10 gateway,

  • http://gatewayName/vdirName/cgi-bin/cognos.cgi?b_action=xts.run&m=portal/bridge.xts&c_env=c10MergeReports.xml&c_mode=post
    • Change gatewayName to the name of the server running an IBM Cognos 10 gateway
    • Change the vdirName to the virtual directory name that was specified when installing the IBM Cognos 10 gateway (default = ibmcognos10)

Running the Merge Report Wizard

When you open the URL in a browser you should see the a set of screens similar to the following. Please note that there may be an intermediate logon page if the user is not already logged on to IBM Cognos 10. Clicking the Cancel button on any of the Merge Report Wizard screens will attempt to close the browser window.

  1. From the Select a package screen (Figure 1), select the package that contains the reports you want to merge from the dropdown list.
    Figure 1: The Select a package screen where the user selects the package that contains the reports to be merged
    Figure 1: The Select a package screen where the user selects the package that contains the reports to be merged
  2. Select and order the reports to be merged in the Select the reports screen as shown in Figure 2.
    Figure 2: The Select the reports screen that allows the user to select two or more reports to merge
    Figure 2: The Select the reports screen that allows the user to select two or more reports to merge
  3. In the Specify a name and description screen (Figure 3), use the Name: field to provide the merged report a name, the Description: field to provide a description of the report and the Screen Tip: field to provide a screen tip that will appear in a yellow box when the mouse is held over the report name. The description and screen tip are optional. Click Next.
    Figure 3: The Specify name and description screen where the user gives the merged report a name and an optional description and screen tip
    Figure 3: The Specify name and description screen where the user gives the merged report a name and an optional description and screen tip
  4. The Review the summary page (Figure 4) lets you verify that the chosen reports are the right ones and the name of the report is correct. Click the Finish button to merge the reports and save the merged report into the Content Store as a child of the selected package.
    Figure 4: The Review the summary screen where the user can verify the inputs from the previous screens before merging and saving the report
    Figure 4: The Review the summary screen where the user can verify the inputs from the previous screens before merging and saving the report

Resources

For information on IBM Cognos 10 and IBM WebSphere,
IBM Cognos 10 BI - http://www-142.ibm.com/software/products/us/en/subcategory/SWQ20
IBM WebSphere - http://www.ibm.com/software/websphere

For information on technologies used in this application,
Tomcat - http://tomcat.apache.org
log4j 1.2 - http://logging.apache.org/log4j/1.2


Download

DescriptionNameSize
Code samplec10MergeReportsPublicPackage.zip44KB

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
ArticleID=856822
ArticleTitle=IBM Business Analytics Proven Practices: IBM Cognos 10 BI SDK Application To Merge Reports
publish-date=02042013