IBM Business Analytics Proven Practices: Images in IBM Cognos BI Reports and Analyses

Product(s): IBM Cognos BI; Area of Interest: Infrastructure; Version: 1.1 (01/03/14)

This document replaces the outdated "Resolution of Images" by providing updated information, additional detail and troubleshooting techniques for issues regarding images not showing up in supported report output formats.


Business Analytics Proven Practices Team, Business Analytics Proven Practices Team, IBM

Business Analytics Proven Practices Team

31 January 2014 (First published 07 January 2014)

Also available in Russian


Purpose of Document

This document provides detailed background information and skills to troubleshoot missing images in report outputs of any supported format.


The information provided herein applies to IBM Cognos BI versions 8.4.1, 10.1 and 10.2 including all refresh packs and fix packs on all supported platforms.

Exclusions and Exceptions

IBM Cognos BI 10.2.1 has a defect which prevents the loading of images using relative URL through HTTP requests. This issue is described in APAR PM92524 and fixes are available. Please contact IBM Cognos Support for details. The issue is fixed in IBM Cognos BI (IBM Cognos 10.2 Refresh Pack 1 Fixpack 1) as well.


The reader is expected to have administrator level access to the IBM Cognos BI environment.

Images in BI reports and analyses

IBM Cognos BI allows the embedding of images of two different types into reports and analyses. For the remainder of this document the term report will be used to refer to both IBM Cognos BI reports and analyses. The two image types are:

  • Static images
    Explicitly defined by a reference to a web resource, contained in an <image> element in the report specification. Static images can be included in reports as stand-alone objects, into other objects such as tables and blocks, or as a background image for other objects. The only image formats supported are GIF and JPG.
  • Dynamic (implicit) images
    These are images which get rendered at run-time by one of the charting engines in IBM Cognos BI and is in the form of a chart or diagram based on queried report data.

While dynamic images can be added to a report from any of the IBM Cognos BI Studios except Event Studio, static images can only be added to reports in Report Studio or Business Insight Advanced. Dynamic images are added to reports as chart objects which at run-time get rendered by one of the available charting engines. Static images get added as direct references or calculations which evaluate to references inside an <image> object in the report specification. At run-time IBM Cognos BI renders the report as defined by the report specification into one of the supported output formats. All output formats with the exception of CSV and XML can contain images.

The HTML output format stands out amongst the supported output formats because it is considered to be a non-binary format. The HTML output format is the only one which is rendered in the client browser (as opposed to the binary formats which are rendered by IBM Cognos BI) and therefore the job of retrieving images is left to the client browser as well. Client applications retrieving HTML output format will need to request images through explicit HTTP GET requests.

For charts and diagrams, requests for images will go to whatever component of IBM Cognos BI holds the readily rendered chart. Once rendered by the charting engine, the now static chart image will be a transient file which is cached by some internal IBM Cognos BI component until it's fetched by a client. Essentially this means dynamic images are provided by IBM Cognos BI.

Static images however are not provided by IBM Cognos BI and therefore will need to be retrieved from some external location by an explicit HTTP GET request to a web server which provides the image. The web server reference to the static image is constructed based on configuration and the image references specified in the report specification. While the image reference for HTML must eventually point to some web server provided resource, this does not necessarily apply for other output formats.

For the so-called binary output formats (formats other than HTML or CSV), things are handled differently. For those formats, the output file is completely rendered by IBM Cognos BI and is retrieved by the client through the Report Viewer component after being signaled that the output is ready. The main component involved with rendering binary output formats is the Report Server (RSVP) component. The RSVP component is contained within the BiBusTKServerMain executable which is managed by the IBM Cognos BI Dispatcher as part of the Report Service.

This method of handling binary output formats applies to both classic query mode (CQM) and, as of IBM Cognos BI 10.2, dynamic query mode (DQM). Although the actual data retrieval and processing for DQM happens in a separate process called the Query Service, the rendering of output is still managed by RSVP. Whenever a DQM report is run, it passes through RSVP to DQM and once all the required data has been collected, RSVP puts it all together to create the desired output format. This explains why a Report Server can either operate in 32-bit mode or 64-bit mode. In 32-bit mode, CQM and RSVP not only create the output formats but they handle the data processing as well. For 64-bit mode, the data processing is passed off to DQM. There is no side-by-side support for this which means one has to decide on the operating mode for the Report Server(s).

In a nutshell we can say that RSVP is responsible for embedding all image resources in binary output formats for both CQM and DQM. A binary output format must contain all resources whether they are dynamically generated ones (charts) or static ones (images) before the output is made available to the client application that will eventually display the output. When rendering binary output formats, the RSVP component will retrieve the rendered charts from the charting engine directly and embed them in the binary output. The same approach applies to static images where RSVP will need to retrieve the static images from external locations and embed them into the binary output.

It should now be clear as to why some issues regarding missing images only manifest in certain output formats. In HTML the client (browser) retrieves static images while for binary output formats the images are retrieved and embedded by RSVP, which runs as a process on the box the Application Tier components have been installed to rather than on the client side.

RSVP's Approach to Locating Static Images

The previous section explained the general concept of RSVP rendering binary output formats and thus requires access to the external static image resources. However, RSVP is not limited to web based requests only - it will try several types of access depending on the syntax of the static image reference as specified in the report specification.

Any static image reference is expected to be a URL. This URL can be typed in, constructed as a result of a calculation or be inserted through the Browse for image functionality in Report Studio.

The URL provided can be relative or absolute:

  • Relative URLs are relative to an existing context (location) and thus depend on base information implicitly provided by a path component. That path can either be absolute or relative. Absolute paths start with “//” to indicate a network location or with “/” to replace the existing path on the current file system. Relative paths in turn start by “.” and “..” to replace parts of the current path context in the file system. In Windows environments, “\\” and “\” are used in file system paths.
    Example 1: /pictures/company_logo.gif (absolute path)
    Example 2: ./ci/company_logo.gif (relative path)
    Example 3: ../images/company_logo.gif (relative path)
    Example 4: company_logo.gif (relative path)
    Example 5: C:\\images\company_logo.gif (absolute path)
    Example 6: \\NAS\ci\company_logo.gif (absolute path)
  • Absolute URLs generally start with a scheme, provide an authority and a path which give us all the information required to locate a given resource by that scheme. IBM Cognos BI supports the HTTP, HTTPS, and FTP schemes which map to the corresponding protocols and therefore imply that authority is an optional single user credential (not used for Cognos BI) followed by a mandatory server name and an optional port number. The path consists of several elements and locates the resource on the given server.
    Example 7:
    Example 8: https://myserver/ci/company_logo.gif

The challenge with relative URLs is that one needs to be absolutely clear about the base context - in other words, which base location they refer to. Considering the difference between HTML and binary output formats it becomes clear that relative image URLs will be interpreted differently while absolute URLs to images will generally work regardless of output format since the given network connectivity to reach a UNC path or web server is provided.

For HTML output format, relative URLs must resolve to a web server resource which can usually be assumed to be accessible for an HTML client such as a browser. For binary output, additional resolutions such as relative URLs referring to a remote file system might be required. This is based on the fact that RSVP runs as a process in the IBM Cognos BI Application Tier and might not have connectivity to a web server in the Web Tier due to firewalls and/or security policies. However, static images need to work for all output formats. RSVP, therefore, tries loading static images from the local file system first by mapping the image URLs to the local file system. If RSVP is unable to load the image locally, it will fall back to a web request.

Below is a detailed description of how RSVP resolves images in two phases. The following placeholders are used in the description:

  • <resource_url> is the string specified for the URL property of a static image in Report Studio
  • <COG_ROOT> is the install directory of IBM Cognos BI Application Tier components
  • <effective_url> is the URL that RSVP is trying to access

Phase 1 – Mapping to Local File System

During the first phase, RSVP probes the <resource_url> for being relative and tries mapping it to the file system. The mapping depends on whether the path is relative or absolute.

  1. If the <resource_url> starts with "..", it's considered to be a relative URL using a relative path.
    It will be transformed into a path relative to <COG_ROOT>/bin by appending the <resource_url> except its first two characters,which in this case are "..", to "../webcontent.
    Thus the <resource_url> is split up into the prefix ".." and a remainder where only the latter is used for building the <effective_url>. To stay inline with the notation introduced a dummy path element is entered, which will effectively compensate the ".." prefix of the <resource_url>.
    The effective URL becomes:
    This applies to Example 3 and resolves to
    If the <resource_url> does not start with ".." and does not start with one of the a supported protocol schemes of http://, https:// or ftp://, it's considered to be a relative URL using an absolute or relative path and is mapped to the file system as is:
    <effective_url>:=<resource_url> Applies this to the following examples from above that have absolute paths,
    Example 1, <effective_url>=/pictures/company_logo.gif
    Example 5, <effective_url>=C:\\images\company_logo.gif
    Example 6, <effective_url>=\\NAS\ci\company_logo.gif
    Be aware that there is no syntax check enforced by Report Studio for the image URL property when the URL has been entered, so RSVP simply uses the string as is and expects it to be a valid file system path, even including UNC paths which are covered by the absolute path definition.
    If the path is relative it will resolve relative to the current working directory, which is the <COG_ROOT>/bin or <COG_ROOT>/bin64 directory, depending on which Report Server execution mode is configured.
    This applies to Example 2 where <effective_url>=./ci/company_logo.gif in a Report Server running in 32-bit mode will resolve to <COG_ROOT>/bin/ci/company_logo.gif.
    This also applies to Example 4 where <effective_url>=company_logo.gif in a Report Server running in 64-bit mode will resolve to <COG_ROOT>/bin64/company_logo.gif.
    An attempt is made to open the file specified in <effective_url> from the file system, if successful, the image has been located, otherwise proceed to next step.
  2. If the image has not been found yet, relative URLs using a relative path (the ones starting with “..”) are re-considered but this time the path portion is cut out and the file name is mapped to the current directory.
    The <resource_URL> is investigated for the first occurrence of “/” (forward slash) from the right. If present, everything to the left of that slash and the slash itself is removed from the resource URL thus only leaving the file name. Finally, the effective path is set to the current working directory, which is the <COG_ROOT>/bin or <COG_ROOT>/bin64 directory plus the file name. An attempt is made to open the file specified in <effective_url> from the file system. If successful, the image has been located, otherwise proceed to Phase 2 which will try to locate the image using a web request. Applying this procedure using Example 3 above, we get <effective_url>=<COG_ROOT>/bin/company_logo.gif. The <resource_URL> of ../images/company_logo.gif is investigated for the first occurrence of forward slash from the right. Then everything to the left of the found slash is deleted leaving us with company_logo.gif, which gives us an <effective_URL> of <COG_ROOT>/bin/company_logo.gif.

To recap Phase 1, resources specified using relative URLs will be mapped to local file system first, while for absolute URLs no local file system access is attempted at all. For locating resources using relative URLs and relative path there does exist a fall-back even to load them from the current working directory.

Phase 2 – Web Request

If the image could not be loaded from the local file system, RSVP now tries to fetch the image through a request using either HTTP, HTTPS or FTP protocol. For this an absolute URL is required. If the <resource_URL> is not already an absolute URL, RSVP will attempt to build one from it using the Gateway URL specified in IBM Cognos Configuration for the installed instance of the IBM Cognos BI Application Tier component. Since the Gateway URL only allows using HTTP or HTTPS protocol, any resource URLs aiming to use the FTP protocol must be provided as absolute URLs. Also be aware that if different instances of IBM Cognos BI Application Tier use different Gateway URLs, the constructed URLs may differ depending on which instance actually executes the report.

For relative URLs only the following substitutions are applied:

  1. If <resource_URL> starts with “..”, the relative <resource_URL> will be prefixed with the protocol, host, port and path of the Gateway URL where one element of the Gateway URL path has been removed for each occurrence of “../” in the <resource_URL>.
    Once again, consider the URL from Example 3 above where the <resource_url> is ../images/company_logo.gif. Let's assume a configured Gateway URL of The protocol, host, port and path components of the Gateway URL are Since there is an occurrence of “../” in the <resource_URL>, the Gateway URL will be shortened to The “..\” is stripped from the <resource_URL> leaving images/company_logo.gif and this will be appended to the shortened Gateway URL resulting in an <effective_URL> of
  2. If the <resource_URL> starts with “/”, the path is absolute and the effective URL will be constructed by only prefixing the protocol host and port of the configured Gateway URL only.
    Assuming the same Gateway URL from above, consider Example 1 again. The <resource_url> of /pictures/company_logo.gif would generate an <effective_URL> of
  3. If the <resource_URL> starts with neither “/” or “../”, the <effective_URL> is simply set to the <resource_URL>.

At this point, the <effective_URL> is set to an absolute URL using any of the supported schemes. It will be encoded to be compliant with HTTP(S)/FTP encoding (for example, replace spaces by “%20”) and depending on the scheme, either an HTTP GET request to the <effective_URL> is sent using a built-in HTTP client implementation (CCLURL) or the Xerces library is used to retrieve the resource using FTP.

If the image was found it is put into a local cache to prevent loading the same image resource more than once for a single report. If the image was not found, the image will be replaced by a black border in the binary output. Errors in locating image resources will ONLY be logged upon request with a special trace.


The two phased approach has RSVP attempting to load images from the local file system first and only try a web request after that. Logically this makes a web request a fall-back rather than an intended feature but actually this allows for the support of scenarios where the IBM Cognos BI Application Tier cannot access the images through an HTTP(S) or FTP request. The attempt to locate resources from the file system first allows for temporary workarounds and for server environments where reaching out to remote servers is not allowed. As a best practice the images should be placed into a path relative to <COG_ROOT>/webcontent. However, when running multiple instances of Application Tier components, the image files must be locally available on each instance. Using a network share is possible, however it should be mapped at the operating system level and accessed through absolute path of a relative URL.

Providing images from a central web server, which could be a different one than the web server hosting the IBM Cognos BI Gateway, is another possibility but requires using absolute URLs for resource URLs. The advantage here is that a single location can serve many installations and systems and if images need to be updated, they only need to be updated in one location. The use of Secure Socket Layer (SSL) protocol for encrypting the communication is fully supported.

Tracing PDF Image Rendering

This trace works by disabling the automatic administration of the BiBusTKServerMain executable by the IBM Cognos BI Dispatcher. Once in manual mode, Dispatcher will not be able to spawn additional instances of the BiBusTKServerMain executable and instead expects a single instance to be running and listening on a specific port. As a result, this trace can not be used during production. The trace applies to both CQM and DQM reports.

In a distributed install, perform the following steps on a single instance of IBM Cognos BI Application Tier components only. Leave one instance of the Report Service running but shut down all other instances of the Report Service. This will simplify the test.

Part 1 – Enable XferWebResource Logging for RSVP

  • Stop the IBM Cognos BI Application Tier.
  • Optionally wipe the contents of <COG_ROOT>/logs directory to get a fresh set of accompanying logs.
  • In <COG_ROOT>/configuration rename the file rsvpproperties.xml.sample to rsvpproperties.xml to signal IBM Cognos BI to read it and pick up the settings. It is possible that the rename has already been done. If this is the case, continue on to the next step.
  • Open the <COG_ROOT>/configuration/rsvpproperties.xml file in a text editor such as Notepad or vi.
  • Search for the structure element containing the XferWebResourceInfo property. Use a search string of “XferWeb”.
  • The XferWebResourceInfo property which is disabled by default. To enable it, simply remove the comment tags by editing the structure entry from this,
        <!-- Turning this flag ON will display console debugging infomation for
                               1=ON; 0=OFF (default) --> 
                        <value type="long">1</value>--> 

    to this,
        <!-- Turning this flag ON will display console debugging infomation for 
                               1=ON; 0=OFF (default) --> 
                        <value type="long">1</value>
  • Save the edited rsvpproperties.xml file.

Part 2 – Switch BiBusTKServerMain Management to Manual Mode

  • In <COG_ROOT>/webapps/p2pd/WEB-INF/services disable read-only access to the file reportservice.xml if applicable.
  • Open the file reportservice.xml in a text editor and find the parameter named report_server_port.
  • Change the parameter value from 0, which means automatic management, to the number of a free TCP port of your choosing. We'll use 5555 in this example.
  • Save the edited reportservice.xml file.

Part 3 – Start BiBusTKServerMain

  • Open a shell on Linux or a Command Prompt on Windows. Make sure your scroll buffer and window layout is big enough to not lose some of the output due to scrolling.
  • Change directory to folder <COG_ROOT>/bin for installs configured to 32-bit Report Server mode or to folder <COG_ROOT>/bin64 for installs configured to use 64-bit Report Server mode.
  • Start the BiBusTKServerMain executable by issuing one of the following commands:
    • For IBM Cognos BI 8.4.1 and IBM Cognos BI 10.1.x
      Windows: BiBusTKServerMain.exe port=5555
      Linux/UNIX: BiBusTKServerMain port=5555
    • For IBM Cognos BI 10.2.x
      Windows: BiBusTKServerMain.exe port=5555 lightThreads=10
      Linux/UNIX: BiBusTKServerMain port=5555 lightThreads=10
      The BiBusTKServerMain executable will be started and the port and process ID (PID) being used will be written to the console a shown in Illustration 1.
      Illustration 1: Windows Command Prompt showing the BiBusTKServerMain executable's output of port umber and PID in use
      Illustration 1: Windows Command Prompt showing the BiBusTKServerMain executable's output of port umber and PID in use

Part 4 – Run the test

  • Start IBM Cognos BI Application Tier.
  • Run the test case, such as running a report where the images are missing in the PDF output format. Note that if an error occurs on the first attempt to run a report, simply click the browser's Back button and retry. This is a known glitch which has no negative impacts and only occurs when using this particular trace. The second and all subsequent attempts to run reports will be passed down to RSVP without issues and the expected output will be starting to appear in the log.

Part 5 – Interpreting the Output

Once the test case has been run, the console will show RSVP's attempts to locate the image resources. The loading of each resource is logged by a block of single lines starting with the text XferWebResource. The first line in the block will state the resource url and the last line in the block will state a return status.

Illustration 2: Windows Command Prompt window showing several lines of log output for locating the requested image resource
Illustration 2: Windows Command Prompt window showing several lines of log output for locating the requested image resource

In the example depicted by Illustration 2, one can see the first line which states the resource URL for this image resource. This resource URL is taken directly from the report specification and reflects the syntax used in the report to reference the image resource. In this example, the image resource is referenced by an absolute URL which includes the HTTP protocol scheme, server and path.

The next line prints out the effective URL derived in Phase 1 processing which RSVP would use to open the resource from the local file system if that effective URL were found to be relative. This line is only important to determine whether or not the effective URL is appended to <COG_ROOT>/webcontent correctly for local file system access. It does not indicate local file system access yet - this would be noted in subsequent lines. In this example, the effective URL is an absolute URL which in turn means no file system access will be attempted and RSVP will invoke Phase 2 processing to look for the image using a web request. Consequently the next line states going to the web to indicate that RSVP is now trying to locate the image resource by an HTTP(S) request.

The next line prints out the basePath and safeUrl. Those two strings would get concatenated for image resources using relative path to form a web safe URL for the image resource. The basePath represents the configured Gateway URL while the safeURL would be the resource URL but encoded to make sure all special and reserved characters get transmitted properly by the HTTP protocol. For this example, the basePath is empty because relative references are not used. The safeURL value is the web-safe encoded resource URL. The concatenated string, labelled webURL is printed out on the succeeding line. This is the URL used eventually to access the web resource via HTTP.

The next line states the component used to send the request. Either this is CCLURL for HTTP(S) requests or Xerces for FTP URLs.

Finally, the last line in the block states a return status of true or false depending on whether or not the resource has been located. Any errors for the HTTP request (untrusted certificates, host unreachable, HTTP errors, etc) would be logged and clearly visible here. Illustration 3 displays an example for a failed request to an image resource referenced by a relative path.

Illustration 3: Windows Command Prompt displaying XferWebResource log lines for a failed resource request
Illustration 3: Windows Command Prompt displaying XferWebResource log lines for a failed resource request

Based on this information and careful validation of the URLs, one should be able to tell why an image resource is not available in PDF/Excel 2007 output formats.

Part 5 – Disable Trace Again

Now that the trace information has been collected it's time to revert the changes and restore normal operation.

  • At the shell/command prompt, press CTRL-C to stop the BiBusTKServerMain executable.
  • Open <COG_ROOT>/webapps/p2pd/WEB-INF/services/reportservice.xml in a text editor such as Notepad or vi and find the parameter report_server_port.
  • Change the parameter value from the non-zero value back to 0 (zero)
  • Save the file.
  • Open the <COG_ROOT>/configuration/rsvpproperties.xml file in a text editor such as Notepad or vi.
  • Search for the structure element containing the XferWebResourceInfo property. Use a search string of “XferWeb”.
  • Reset the XferWebResourceInfo property to disable the logging. This is done by setting the property value to 0 (zero).
        <!-- Turning this flag ON will display console debugging infomation for 
                               1=ON; 0=OFF (default) --> 
                        <value type="long">0</value>
  • Save the edited rsvpproperties.xml file.

Appendix A – Sophisticated BIBus Tracing

The trace used for troubleshooting the rendering of images in PDF or Excel 2007 format uses the approach of running a single instance of the BIBusTKServerMain executable on a fixed port. Thereby, it's possible to manually start the single instance of BiBusTKServerMain in a shell and monitor the output. However, there are times when more sophisticated logging or control of the BiBusTKServerMain executable is desired. Below are some steps on how to achieve this on LINUX/UNIX platforms easily. The same approach does not work on Windows platforms easily, which is why we consider LINUX/UNIX only.

The approach is to replace the BiBusTKServerMain executable with a shell script which could do things such as,

  • Invoke the BiBusTKServerMain executable under the control of the adb or strace debugging tools.
  • Redirect stdout and stderr outputs to files rather than logging to console.
  • Invoke other tools first prior to starting the BiBusTKServerMain executable.

The following example will start the BiBusTKServerMain executable with all outputs redirected to a single file,

  • In the <COG_ROOT>/bin folder, rename the file BIBusTKServerMain file to something different such as BIBUS.
  • Open a text editor such as vi and create a new empty text file.
  • Add the following text to the new text file
    ./BIBUS 1>&2 2>../logs/BIBusTKServerMain_err.log
  • Save the file as <COG_ROOT>/bin/BIBusTkServerMain, making sure of the case sensitivity. This will replace the executable for the Report Server by a script which calls the renamed executable but redirects the output of stderr and stdout into a file.
  • Start at least one instance of IBM Cognos Content Manager and the instance of IBM Cognos Application Tier components.
  • Reproduce the issue.
  • Stop IBM Cognos BI.
  • Rename the BIBusTkServerMain script to BIBusTkServerMain_script.
  • Rename BIBUS back to BIBusTkServerMain, making sure of the case sensitivity.

The <COG_ROOT>/logs folder now contains the file BiBusTkServerMain_err.log which shows which accesses have been attempted by Report Server and what might have gone wrong.


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

Zone=Big data and analytics
ArticleTitle=IBM Business Analytics Proven Practices: Images in IBM Cognos BI Reports and Analyses