Basic troubleshooting

When a report is viewed in PDF or Excel formats, map images are uploaded to EM4C Server. The image files are temporarily written to disk in the location specified by the IMAGE_TEMP_FOLDER property in <em4c_location>\webapps\em4c\WEB-INF\web.xml. By default, the temporary image folder location is <em4c_location>\webapps\em4c\temp\images.

The first thing to verify when troubleshooting issues with viewing maps in PDF or Excel formats is whether the map images have been uploaded to the temporary image folder on EM4C Server. If the images are not uploaded, verify that EM4C Server is running and that the temporary image folder is writable.

If the map images have successfully uploaded to EM4C Server but the map is still not appearing in the PDF or Excel report, it is likely a configuration problem, either with IBM Cognos or with Esri Maps for IBM Cognos. You can determine whether the cause of the issue is your IBM Cognos configuration or your Esri Maps for IBM Cognos configuration by creating and testing a report with only a static image. The image must be located on the IBM Cognos Gateway (for example, <cognos_gateway_machine>\ibmcognos\em4c\images\move_down.gif) and must be referenced using a relative URL (for example, ..\em4c\images\move_down.gif). If the image does not appear when you view the report in PDF and Excel formats, there is a problem with your IBM Cognos configuration.

If the image does appear in the test report, there may be a problem with your Esri Maps for IBM Cognos configuration. To begin troubleshooting, verify that the following requirements have been met:

• The EM4C Gateway URI (server name, port, and IBM Cognos virtual directory) and the IBM Cognos Gateway URI must be the same.
• In configurations that include the Secure Sockets Layer (SSL) security protocol, the IBM Cognos Dispatcher downloads the map images through the IBM Cognos Gateway. This means that the following must be true:
  • The web server must allow the Dispatcher process to make HTTP or HTTPS calls to \<ibmcognos>\em4c\cgi-bin\em4c.cgi.
  • The IBM Cognos Dispatcher must be able to trust the SSL certificate. Review the IBM Cognos documentation and Images are not being displayed when report run as PDF to learn more about this configuration issue. For additional information, see knowledge base article 000012432.
  • If there is a firewall between the IBM Cognos Gateway and the IBM Cognos Dispatcher, a firewall rule allowing the Dispatcher to access \<ibmcognos>\em4c\cgi-bin\em4c.cgi must be created.

Fonts do not display correctly

When a map is viewed or printed from Internet Explorer, some characters may be missing in the map image if EM4C Server does not have a TrueType font installed that supports the characters displayed on the map. In such cases, you must locate a TrueType font that supports the necessary characters and either install it as system font or put a copy of the font into the \fonts\fallback folder on EM4C Server. After installing or placing the new font, the EM4C service must be restarted for the changes to take effect.

Reports with multiple pages and maps only show one map

When rendering a map in PDF or Excel format, Esri Maps for IBM Cognos generates an image of the map as it is displayed in HTML. To generate the map image, Esri Maps for IBM Cognos requires that the map be rendered when the PDF or Excel format is chosen.

For this reason, if a report has maps on multiple pages, only the maps on the currently displayed HTML page are rendered in the PDF or Excel output document. If you want to print all of the maps in a multipage report, you must print each page individually to properly display the image snapshot of each map in the printed output. For each page containing a map, browse to the HTML page you want to print, choose the desired output format, and find and print the page in the output document.

A white box appears in place of the map

When a white box appears in place of the map in a report viewed in PDF or Excel 2007 format, one of the following might be the cause:

• If the EM4C Gateway URI (server name, port, and so on) does not match the IBM Cognos Gateway URI, or if other errors are made when configuring EM4C Gateway, the map will not be displayed. Ensure that the host name portion of the URI for both the EM4C Gateway and the IBM Cognos Gateway is changed from localhost to an IP address or a network host name. For more information, see Configure EM4C Gateway.
• When map-enabled reports are viewed in PDF and Excel 2007 formats, an image of the map is generated and saved to EM4C Server. The location where the map image is stored is specified using a relative URL to enable content to be saved and accessed if the report is moved to an environment configured with a different IBM Cognos virtual directory. Some versions of IBM Cognos have a known defect that prevents the loading of images using relative URLs through HTTP requests. This issue can be resolved by upgrading to a version of IBM Cognos that includes a fix for the defect or by manually editing affected reports to use an absolute path for the map image URL. For more information, see knowledge base article 000013621.
• In configurations that include the Secure Sockets Layer (SSL) security protocol, this issue may be caused by an incomplete or missing chain of trust for SSL within the IBM Cognos keystore. In this scenario, when viewing a map-enabled report in PDF or Excel 2007 format, the IBM Cognos Gateway is unable to access the map images on the web server because a chain of trust for SSL has not been established between the web server and IBM Cognos Application Tier components.

  To set up trust between the web server and IBM Cognos, the IBM Cognos administrator must import the SSL certificate chain of trust into the IBM Cognos CA keystore. For more information, see knowledge base article 000012432.

The report is not generated after selecting a report format

After selecting a report format while viewing a map-enabled report in HTML, a spinning mouse pointer may appear over the map while you wait for the report to generate. This issue can occur when using Mozilla Firefox or Google Chrome in a system environment in which Internet Information Services (IIS) is used as the web server for the EM4C Gateway. For more information and steps to resolve this issue, see knowledge base article 000012227.