IBM Support

How to create a Gateway server (to allow 'Classic' client to use 'controller' (formely known as 't=controller') parameter) when using Cognos Analytics

How To


Summary

Customer would like to configure their architecture so that user's IBM Cognos Controller 'classic' clients (the program CCR.EXE) do not connect directly to the main IBM Cognos Controller application server. Instead they connect to a separate 'gateway' server.
- In other words, they want to achieve something similar to what is described inside separate IBM technote #386373.

How can they achieve this, when using Cognos Analytics?

Objective

The IBM Cognos Controller classic client (CCR.EXE) is the software client that looks like this:
image 5484
  
When customers install the classic client, they type in a value of WSS Url, for example:
image 5487
  • WSS Url defines which website the IBM Cognos Controller client connects to.
In the above example, it shows the default setting which means that the IBM Cognos Controller client connects to this website: http://servername/ibmcognos/controllerserver/ccrws.asmx
  •  By default, the classic client connects directly to the IIS webserver of the 'main' IBM Cognos Controller application server (in the above example it is called 'servername').
However, this technote specifically relates to the scenario where the customer would like to instead have their 'classic' client connect to a different 'gateway' server (not the 'main' server):
image 5475
  • This is so that all classic client <=> server communication travels via the Cognos Analytics 'gateway' server (which acts as a 'relay'/'proxy').

Environment

This technote is based on the following software versions:
  • IBM Cognos Controller 10.4.x
  • Cognos Analytics 11.0.13 +
For instructions using older versions of IBM Cognos Controller (which use Cognos BI, not Cognos Analytics) see separate IBM technote #6257771.

Steps

Assumptions:
The following instructions assume that:
  • There is already a fully-tested/working 'main' IBM Cognos Controller application server and 'main' Cognos Analytics (CA) server (existing on the secure LAN).
    • To make it simple, the instructions assume that both the IBM Cognos Controller and CA server software are installed on the same physical Windows box.
  • The customer simply wants to install a separate dedicated CA-gateway-only server (perhaps in their DMZ) to add to their existing (working) IBM Cognos Controller/CA main server
  • All IIS webservers are using the default HTTP over TCP port 80 (not HTTPS over 443, for example).
    • If you want to use SSL then use the instructions, only once you have http working properly,  inside separate IBM technote #372873.
  • The system is configured to use ISAPI (not CGI)
  • Servers based on Windows 2019.
  
Steps:
To make it easier to follow, this has been split into sections.
  • Each section contains parts to perform on the "Gateway" server (which you may have placed inside the DMZ), and parts to be done on the 'main' IBM Cognos Controller application server (which will be inside the secure LAN)
  • These are clearly labelled with " <gateway>" and "<appserver>" headings

====================================================
(A) Basic preparation
<gateway>
Install/configure Microsoft IIS Web Server including:
  • Application Development - "ISAPI Extensions"
  • Application Development - "ISAPI Filters":
image 5507
  • Increase IIS timeout to at least 60 minutes
TIP: If the reader is unfamiliar with how to perform these, then see Best Practice installation documentation, which is available inside technote #213339.

Next, install the relevant CA gateway component files on the server:
  • Navigate to the Cognos Analytics installation media, and launch the installation wizard (for example double-click on "ca_server_var_win64_11.0.13.exe")
image 5496
  • At the screen 'Component Selection' choose/select only the 'Gateway Components', and then complete the wizard
Next, install the relevant IBM Cognos Controller gateway component files on the server:  
  • Navigate to the IBM Cognos Controller installation media, and launch the installation wizard server, and launch the installation wizard
  • At the screen 'Component Selection' for most customers you should only choose/select the 'Gateway Components':
image 5508
Afterward, apply the relevant IBM Cognos Controller Interim Fix patch (if required) to upgrade the IBM Cognos Controller files to the later/correct patch level.
 
  
<appserver>
====================================================
(B) Firewall configuration
Assuming your gateway/appserver devices are on different networks (DMZ/LAN) than ask your network administrator to modify the firewall (between the LAN and the DMZ) to:
(1) Allow internet users access to <gateway> via TCP port 80 
  • Open the firewall to allow TCP traffic on port 80 between the external client devices (on the Internet) and the gateway server's external IP address (in the DMZ)
(2) Allow communication between <gateway> and <appserver> on TCP ports 80 and 9300 
  • Open the firewall to allow TCP traffic on port 80 between the gateway server's IP address (which may be an 'internal' LAN IP address or an 'external' DMZ IP address - it all depends on your DMZ/firewall configuration) and the application server's (internal/LAN) IP address.

====================================================
(C) IIS configuration

(1) Gateway:
Create the relevant gateway-related IIS virtual directories on this server.
The easiest method to achieve this is to:
1. Use the 'automated' instructions (see separate IBM technote 293905) to create the SSO-related IIS directories:
  • ibmcognos
  • ibmcognos\sso
~~~~~~~~~~~~~~~~~~~~~~~~
TIP: To summarise those separate instructions, you need to:
  • Install IIS Application Request Routing (ARR) 3 (including the URL Rewrite associated module)
  • Download "CA_IIS_config.bat"
  • Edit that file (for example in NOTEPAD) with the correct settings. For example, typically would change the 'dispatcher' name line to something similar to:    set disp[1].name=<appserver>
image 5943
  • Finally, run the modified CA_IIS_config.bat.
~~~~~~~~~~~~~~~~~~~~~~~~
IMPORTANT:  This manual step is crucial for this proxy configuration to work.  This rule will allow for the session to be routed back to IBM Cognos Controller during and after CAM authentication:
  • Add a rewrite rule on /ibmcognos/bi and name it the same as the parameter user on the WSS URL (in this document, we called it 'controller')
    • v1/controller
    • image 12124
    • Ensure that this rewrite rule is BEFORE the existing Reverse Proxy and any SSO (enabled or not) rules
    • image 12125
~~~~~~~~~~~~~~~~~~~~~~~~
2. Inside 'Internet Information Services' open 'Connections' section
  • Highlight your server
  • Double-click  ‘ISAPI and CGI restrictions’ (in the right pane)
  • Check that there is an entry 'IBM Cognos Analytics Isapi':
image 5515
3. Right-click 'ibmcognos' and choose 'Add Virtual Directory' to create the following IIS virtual directory:
  • ibmcognos\cgi-bin
image 5513
4. Increase the value of 'Maximum allowed content length' for the CGI-BIN virtual directory by doing the following:
  • Launch IIS Mananger/administration tool
  • Browse to find the following website: <default web site>\ibmcognos\cgi-bin
  • Open section 'Request Filtering'
  • Click 'Edit Feature Settings'
  • Click 'Rules'
  • Change this to: 3145728000
image 5519
   
5. Configure "Handler Mappings" by doing the following:
  • Highlight/select the virtual directory cgi-bin 
  • Double-click ‘Handler Mappings’ (in the right-hand pane)
image 5520
  • Click ‘Add Module Mapping’
  • Enter the values similar to the following (modify the path as appropriate for where you have installed it):
    • Request path: cognosisapi.dll
    • Module: IsapiModule
    • Executable (optional): C:\Program Files\ibm\cognos\analytics\cgi-bin\cognosisapi.dll
    • Name: ISAPI-cognos
 image 5521
  • Click OK.
  
6. Configure "allowPathInfo="true" by doing the following:
  • Using Windows Explorer, browse to here: C:\Program Files\ibm\cognos\analytics\cgi-bin
  • Edit the following file (inside NOTEPAD):   web.config
  • In the row for 'ISAPI-cognos' add the following text after the entry resourceType="File":  allowPathInfo="true"
TIP: The file will now look similar to:
image 5530
 
TIP: For most servers, the above is enough to solve the problem. However, in some environments the file contains the phrase: types="CgiModule"       (instead of:    modules="CgiModule"    )
  • In this situation, you will need to change the file to say: modules="CgiModule"
====================================================
(D) Cognos software configuration
 
(1) <gateway> server
Because we are using the IBM Cognos Controller client 'controller' parameter, we must also explicitly configure Cognos Analytics's ControllerURI setting, to use the CCRWS.ASMX location, as follows:
1. Launch Cognos Configuration
2. Inside the 'environment' section modify the following:
3. Dispatcher URI's for gateway: http://<appserver>:9300/p2pd/servlet/dispatch/ext (In some cases the following url worked best:  http://<appserver>:9300/bi/v1/disp)
4. Controller URI for gateway: http://<appserver>:80/ibmcognos/controllerserver/ccrws.asmx
5. Save changes.
 
(2) <appserver> server
Launch Controller Configuration and modify the 'Report Server' setting to be the Gateway server's IIS gateway URL, for example: http://<gateway>/ibmcognos/bi/v1/disp
image 5974
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
OPTIONAL: If you want all users (even those on the LAN) to utilise the DMZ gateway server, then you must now inform the 'main' (LAN) Application server where the Cognos Analytics gateway server is by doing the following:
1. Launch Cognos Configuration
2. Inside the 'environment' section modify the following (under 'Gateway Settings'):
3. Gateway URI:      http://<gateway>:80/ibmcognos/bi/v1/disp
image 5810
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
(3) Client device
Configure each user's classic client to use the 'relay/proxy' functionality of the gateway (not connect directly to the main IBM Cognos Controller application server) by using the 'controller' parameter.
New classic client installs:
During the installation wizard, choose the WSS Url to be similar to:
  • http://gateway.domain.com/ibmcognos/bi/v1/controller"
Existing classic client installs:
On the client device:
  • Browse to the installation folder (TIP: By default: C:\Program Files\IBM\IBM Cognos Controller Local Client)
  • Open the following file in NOTEPAD: CCR.exe.config
  • Locate the setting similar to:
            <add key="WSSUrl" value="http://mainserver/ibmcognos/controllerserver"/> 
  • Modify it to something similar to:
            <add key="WSSUrl" value="http://gateway/ibmcognos/bi/v1/controller"/>
image 12102
  • Save changes and test.
====================================================
Appendices:
 
Appendix (A) Classic client 'Web download' method
It is extremely rare for customers to deploy Controller classic client using the legacy 'web download' method.
  • TIP: For an explanation of what this method is, see separate IBM technote #123099.
In this rare scenario, you need to modify the Client Distribution Server settings:
1. Launch Controller Configuration
2. Open the section 'Controller Client Distribution Server'
3. Modify the CASUrl: http://<gateway>/ibmcognos/controllerbin
4. Modify the WSSUrl: http://<gateway>/ibmcognos/bi/v1/controller
  

Document Location

Worldwide

[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SS9S6B","label":"IBM Cognos Controller"},"ARM Category":[{"code":"a8m0z0000000AxnAAE","label":"Documentation"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"10.4.x","Line of Business":{"code":"LOB10","label":"Data and AI"}}]

Document Information

Modified date:
18 April 2022

UID

ibm16257779

Page Feedback