This document is intended to provide a troubleshooting methodology which incorporates publicly available utilities to diagnose and resolve an issue identified within a specific use case. The use case will be presented as a scenario where an IBM Cognos Support Analyst is working with a client to diagnose and solve a particular issue.
The utilities mentioned in this document can be found at,
Although the troubleshooting approach outlined is not IBM Cognos BI version specific, some of the diagnostic utilities used are. The version of the utility to be downloaded will be specific to the IBM Cognos BI version that is experiencing the issue.
Use Case Description
In this scenario, a support analyst is asked by a client how to easily and quickly update an image path found in several reports. The client indicates that they have several reports that incorporate their company logo, a GIF image that is retrieved through a relative path on each of their IBM Cognos BI Report Servers. Due to this relative path, the images must be located in that path on each report server to satisfy generated Portable Document Format (PDF) reports.
They would like to put the company logo image on a web server and change the path to the image to use a URL. This allows them to have one central location to maintain their images rather than having to keep and maintain the images on each IBM Cognos BI Report Server. They specify they want to change the path from,
Gathering Information for this Use Case
The support analyst asks the client which version of IBM Cognos BI they are using. The client indicates that they are using version 8.4.1. Based on this information, the support analyst informs the customer of a supported utility called the Dynamic Report Specification Updater Diagnostic. There is a version of this utility for IBM Cognos BI versions 8.3, 8.4, and 10.1. Since the client’s environment falls into the supported category, the support analyst indicates that the utility can help them quickly batch update their reports.
The Dynamic Report Specification Updater Diagnostic is a powerful global find and replace tool which allows a user to search for any XML elements of IBM Cognos Report Studio, IBM Cognos Query Studio, IBM Cognos Analysis Studio and IBM Cognos PowerPlay 8 report specifications and update them with a new XML element.
The support analyst asks the client to download the 8.4 version of the utility located at the following URL,
Once downloaded, the support analyst assists the client in configuring the application by editing the runme.bat file to point to a supported local Java Runtime Environment (JRE).
Indicating Considerations and Precautions
The support analyst explains to the client that it is important to back up the individual reports that are to be altered by creating a deployment archive containing the reports. Customers can also use a third party tool sold by IBM Cognos partners to select and archive the reports. If unsure where all the reports reside, the entire IBM Cognos BI content store can be backed up through a deployment archive.
The support analyst also indicates that the batch update should be performed on a development or test environment and the affected reports thoroughly tested before being deployed to the production environment.
Batch Updating the Report Specifications
The support analyst explains to the client that the process of updating the report specifications involves:
- creating a transformation XML file that contains the search and replace syntax for the report
- launching the Dynamic Report Specification Updater Diagnostic utility and connecting to the IBM Cognos BI content store
- loading the transformation file into the utility
- selecting the portion of the IBM Cognos BI content store to update
- updating the report specifications
Based on the path information provided earlier in the PMR process, the support analyst works with the client to create an appropriate transformation file which appears as shown below.
<?xml version="1.0" encoding="UTF-8"?> <Transformations> <Transformation id="Image URL Replace"> <Search><![CDATA[..\\samples\\images\\logo_great_outdoors.gif]]></Search> <Replace><![CDATA[http://www.mycorpimages.com/images/logo_great_outdoors.gif]]></Replace> </Transformation> </Transformations>
The support analyst informs the client that in certain scenarios where special characters are present in the regular expressions being used to transform the XML report specifications, they may need to escape those characters. In this scenario, the backslash character is escaped with another backslash character, which is why the original path of
..\samples\images\logo_great_outdoors.gif has two backslashes instead of one in the transformation file.
Once the support analyst is sure the client has backed up his development environment’s IBM Cognos BI content store, they load the transformation file into the utility and before batch updating all the required reports, they use the search feature to see how many reports will actually be updated. With the log results in hand, they see that there are 236 reports that will be altered.
The support analyst and clients first select a single report to perform the translation on. With the success of this test, they are comfortable to proceed with the batch update of the remaining reports.
After the client tests all the reports and is satisfied with the results, he deploys the content to the production environment and asks to close the PMR.