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.
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.
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 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
<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
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,
- 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.
- 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
- 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
- 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
- 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
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