IBM Cognos Proven Practices: How to Install the IBM Cognos Controller 8.5 Client on a User's PC

Nature of Document: Guideline; Product(s): IBM Cognos Controller 8.5; Area of Interest: Infrastructure

This document demonstrates how to install the Controller 8.5 client on an end-user's PC, inside a typical environment. By following these "best practices" the intention is to make client deployment as easy as possible, with the minimum of errors or issues. Later, this document gives best practices for Citrix server client installation.

Share:

Richard Collins, IBM Cognos Customer Support, IBM

Richard Collins is an IBM Cognos Customer Support person. Richard’s focus has been on the technical side for IBM Cognos Controller, especially on configuring, performance and installing of IBM Cognos Controller in different environments.



21 June 2010

Also available in Chinese Spanish

Introduction

Purpose

Develop skills on this topic

This content is part of a progressive knowledge path for advancing your skills. See Introduction to IBM Cognos Business Intelligence V10.01

This document demonstrates how to install the Controller 8.5 client on an end-user's PC, inside a typical environment. By following these "best practices" the intention is to make client deployment as easy as possible, with the minimum of errors or issues. Later, this document gives best practices for Citrix server client installation.

Earlier versions of Controller:

This document is based on Controller 8.5. However, the method demonstrated should be correct for older releases of Controller which also uses .NET 2.0 (SP1), for example Controller 8.2, 8.3 and 8.4.

NOTE: Controller 8.1.x releases use .NET 1.1SP1 technology, so you cannot use this document as a guide for the older (8.1.x) generation of Controller.

Applicability

IBM Cognos Controller 8.5 and .Net 2.0 (SP1).

NOTE: Controller 8.1.x releases use .NET 1.1SP1 technology, so you cannot use this document as a guide for the older (8.1.x) generation of Controller

Exclusions and Exceptions

Although this document demonstrates proven practices suitable for most environments, it is not necessarily perfect for all environments.

There are an infinite variety of possible customer Information Technology environments, many different ways to install/configure IBM Cognos Controller 8.5, and therefore the direction in this document may have to be modified by the customer to fit in with their needs/environment. Your IBM Cognos technical consultant (who installed your IBM Cognos Controller server(s)) will often be the best person to advise on any extra necessary changes.

Using the IBM Technotes / knowledgebase

Many of the author’s tips and recommendations refer to our excellent knowledge base, which contain our IBM "Technotes" (previously known as "KB articles"). This can be found here:

http://www.ibm.com/software/data/cognos/products/cognos-8-controller/support/search.html

It is important that the reader uses this knowledge base resource, since it is an invaluable help for almost all issues.

In addition, all public Proven Practice documents can be found here:

http://www.ibm.com/developerworks/data/library/cognos/cognosprovenpractices.html

FAP Installation and Configuration

IBM Cognos Controller 8.5 contains a new function, called Financial Analytics Publish (FAP). This requires a new and separate IBM Cognos Controller client to be installed and configured on the relevant client computer.

Please note that this document intentionally does not relate to FAP.

For more information on FAP, you can:

  • Read Installing & Configuring IBM Cognos Controller 8.5 server
  • Read the official document (ctrl_fap_ug.pdf) which comes with the product installation
  • Search the IBM tech notes knowledge base

Client Installation

Summary of IBM Cognos Controller Client Install

Assuming that certain prerequisites have been met, installing the IBM Cognos Controller client takes only a few minutes. However, it is important to take the time and effort to ensure that the prerequisites are met, in order that your deployment is successful.

There are many different ways to install the IBM Cognos Controller client, and this Proven Practice document aims to give the most efficient and successful installation method. To summarise this method, the Information technology administrator would perform the following steps:

  • Add the end user to the local group 'Administrators' on the client PC
  • Log on to Windows as the end user (who will therefore now be an administrator)
  • Then perform the following:

If necessary (if client PC does not already have installed/configured)

  1. Double-click AdbeRdr812_en_US.exe
  2. Apply latest Micro Office service pack file
  3. Ensure that the end-user’s Excel Macro Security setting is set to Medium or lower
  4. Configure Internet Explorer to bypass proxy
  5. Configure Internet Explorer's trusted zone security zone to be Medium (or lower) for IE6, and Medium-low (or lower) for IE7

Mandatory:

  1. Run Trusted_Zone_add_Controller_APP_Server.vbs
  2. Run NetFx20SP2_x86.exe
  3. Run dotNET2.0_trust_<servername>.bat
  4. Run caspol_disable2.bat
  5. Run Check_CRL_certificate_disable.reg
  6. Copy the file Excel.exe.config into the same location as your Microsoft Excel.EXE file
  7. Run ControllerClient.MSI
  8. Copy the file Controller 8.5.URL to the end user’s desktop (inside their profile), so that they can easily launch the client
  9. Test as Administrator
  10. Remove end user from the Local Administrators’ group, then test as the end user

Note:

As you can see, each of the above steps are very simple/straightforward, but they all do need to be performed in order to get IBM Cognos Controller working correctly.

Most of this document is devoted to simply describing how to create the files (referred to above).


Pre-requisites – Client and Server

Client PC Software pre-requisites

The current official supported environments of Controller 8.5 are listed here:

http://www.ibm.com/support/docview.wss?rs=3450&uid=swg27017475

To summarise the official web page, the most important sections are that your client PC should:

  • be running Windows XP Service pack 3 or Vista SP1
    • Other operating systems and service packs are supported, but the most actively tested, and therefore recommended, client environments are Windows XP SP3 and Vista SP1.
  • Have Microsoft Internet Explorer 7 installed
    • IE6 is also supported, but the most ‘actively tested, and therefore recommended is IE7.
  • Have Micro Excel XP (2002), 2003 or 2007 installed, with the latest service pack applied plus (see later) required hotfix(es)

IMPORTANT:

  • It is important that you also install the latest Microsoft Office service pack on each client PC to ensure best performance/stability.
  • This is important for Excel XP (2002) and Excel 2007 where there are known issues with Controller unless Office XP SP3 / Office 2007 SP2 and required hotfixes are installed

Application server – Disable Automatic Excel link Client install

By default the setting InstallExcelLink is set to True, in Client Distribution Server Configuration.

This will mean that, if the end-user does not have a file %appdata%\Cognos\ccr\ccr.config inside their Windows profile, the Controller website will automatically attempt to install ControllerClient.MSI to their PC.

This is a good idea if the end user is a local administrator, but often this is not the case (normally users are not local administrators on their PCs) and it will certainly not be true for deployment using Citrix.

Therefore, as a best practice for most environments, please ensure that InstallExcelLink is set to False on your application server before continuing, because this document shall assume that all client software will be deployed *manually*. If you do not do this, you will find problems later, especially if using Citrix.

Server Naming Conventions

Later in this document, we talk about configurations that refer to the <servername> of your Controller server. This may be the NetBIOS name, or the FQDN (Fully Qualified Domain Name) of the server, or even something else (for example a virtual DNS name, for Disaster Recovery purposes).

You must use the correct version of your server name at all times.

The correct naming convention version that you must use is the one that is configured on your application server, inside the section Client Distribution Server Configuration inside Cognos Controller Configuration:

Figure 1 shows the Controller configuration and client distribution server configuration
Figure 1 shows the Controller configuration and client distribution server configuration

In the above example, it is the NetBIOS name "SERVERNAME".

Remember, this is different from the ‘FQDN’ name (for example ‘SERVERNAME.domainname.com’ ):

Figure 2 shows the Cognos Controller configuration and client distribution server configuration with language settings being emphasized
Figure 2 shows the Cognos Controller configuration and client distribution server configuration with language settings being emphasized

Creating a Software 'Repository' Share

As a best practice, to make future client installs easier we shall create and populate a IBM Cognos Controller software repository share, from which to install the software in the future.

The intention here is to:

  • invest 20 minutes of extra time now creating and populating the share
  • this will make installing the client easier and result in saving 5 to 10 minutes per client PC

Creating a share "client_share" on your Application Server

Create a share (for example \\controllerserver\client_share) on your IBM Cognos Controller server and give the group "Everyone" read permissions for both "share" and "NTFS" security (i.e. both the "sharing" and the "security" tabs below):

Figure 3 shows the Client_share properties and the permissions being granted to the users
Figure 3 shows the Client_share properties and the permissions being granted to the users

Populate share with the required IBM Cognos Controller client software

Into this folder, we shall copy the following required software and scripts (see later in this section for an explanation of each file):

  • .NET Framework 2.0 SP2 client ("NetFx20SP2_x86.exe")
  • .NET Internet certificate check disable (batch file "caspol_disable2.bat")
  • .NET 2.0 trust (batch file "dotNET2.0_trust_<SERVERNAME>.bat")
  • Microsoft Internet Explorer trusted zone addition (batch file "Trusted_Zone_add_Controller_APP_Server.vbs")
  • Microsoft Internet Explorer Certificate Check Disable (file "Check_CRL_certificate_disable.reg")
  • EXCEL.EXE.config
  • ControllerClient.MSI
  • URL shortcut to IBM Cognos Controller

Plus:

  • Adobe Reader 8.1.2 (e.g. AdbeRdr812_en_US.exe)
  • Latest Microsoft Office Service Pack (e.g. Office XP SP3 = OfficeXpSp3-kb832671-fullfile-enu.exe)

.Net Framework 2.0 SP2 Client

  • .NET 2.0 Framework SP2 (or SP1 if preferred) (IBM Technote #1371440)

WARNING: It is vital that you do not install the original .NET 2.0 RTM release. Instead, you must install NET 2.0 SP1 or later since it contains a number of fixes, plus can increase the performance of Controller considerably (some IBM Cognos Controller tasks run 3 times quicker).

TIP:

.NET Internet Certificate Check Disable (Batch File "CASPOL Disable2.BAT")

  • The job of this script is to speed up the execution of the Controller client in some environments.
  • To create this batch file, launch NOTEPAD.EXE and copy and paste the following text:
REM @echo off
REM Batch file created by 
REM last updated - 28th March 2007
REM
REM Following lines add a .NET 2.0 trust
REM 
REM Make sure that you change the "servername"...
REM ...to your Controller application server's name...
REM ...which may be NETBIOS or FQDN as appropriate
REM 
REM Modify "Controller_servername" and "Controller_description"
REM if required (optional)
c:
cd %windir%\Microsoft.NET\Framework\v2.0.50727 
caspol -q -m -ag "All_Code" -url http://SERVERNAME/* FullTrust 
 -name "Controller_servername" -d "Controller_description"

Important: Modify the value of "servername" (Bold face) to match the exact value (NetBIOS or FQDN) of your server name inside ‘Controller Configuration’ (see earlier section 3.3)

  • Save this file as "dotNET2.0_trust_<SERVERNAME>.bat"

TIP: Afterwards, you will have to change that the file extension, since Notepad will save it as " dotNET2.0_trust_SERVERNAME.bat.txt"

Micros Internet Explorer Trusted Zone Addition (Batch File "Trusted Zone add Controller APP Server.vbs")

  • To create this registry file, open NOTEPAD.EXE and copy and paste the following text:
' This script written 18th Dec 2007
' By Name
' to create an entry for http://controllersvr
' inside the 'trusted zone' for Internet Explorer'
' [specifically for MS IE 6
'  but may work on other versions]
' Tested on Windows XP Pro only
'=====================================================
'ALWAYS examine VBS files before running them
'If you choose to use this, you do so at your own risk
'=====================================================
'Declare and Set Windows Scripting Host Shell Object
DIM WshShell
SET WSHShell = WScript.CreateObject("WScript.Shell")

'Bypass Errors
On Error Resume Next
'uncomment out the next line if you want to change citrix to install mode
'wshshell.run "change user /install",1,True
' THE NEXT LINES should be modified
' so that controllersvr = <name_of_your_controller_server>
wshShell.RegWrite "HKCU\Software\Microsoft\Windows\CurrentVersion
 \Internet Settings\ZoneMap\Domains\controllersvr\http", "2", "REG_DWORD"
'uncomment out the next line if you want to change citrix to normal mode
'wshshell.run "change user /execute",1,True
'End of Script

Important: Modify the value of <controllersvr> (Bold face) to match the exact value (NetBIOS or FQDN) of your server name inside ‘Controller Configuration’ (see earlier).

  • Save this file as "Trusted_Zone_add_Controller_APP_Server.vbs"

TIP: Afterwards, remember to change the filename’s extension as appropriate.

MS Internet Explorer Certificate Check Disable (file "Check_CRL_certificate_disable.reg")

To create this batch file (for more info, see KB 1034825), launch NOTEPAD.EXE and copy and paste the following text:

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\
 WinTrust\Trust Providers\Software Publishing]
"State"=dword:00023e00

Save this file as "Check_CRL_certificate_disable.reg".

TIP: Afterwards, remember to change the filename’s extension as appropriate.

EXCEL.EXE.config

To create this file, launch NOTEPAD.EXE and copy and paste the following text:

<configuration>
   <startup>
      <supportedRuntime version="v2.0.50727"/>
   </startup>
</configuration>

Save this file as "EXCEL.EXE.config".

TIP: Afterwards, remember to change the filename’s extension as appropriate.

ControllerClient.MSI

This file is located inside C:\Program Files\Cognos\c8\webcontent\CCR on the Controller application server.

Adobe Reader 8 or later (e.g. AdbeRdr812_en_US.exe)

This (AdbeRdr812_en_US.exe) is downloadable from www.adobe.com.

Latest Microsoft Office Service Pack For your User's Microsoft Version

(E.G. Office XP SP3 = OfficeXPSP3-kb832671-fullfile-enu.exe)

These can be downloaded from www.microsoft.com

IMPORTANT: If using Excel 2007, then you must also download and install office2007sp2- kb953195-fullfile-en-us.exe on each end user’s PC. (See Technote 1394945)

URL Shortcut Controller

Create a URL shortcut file, with a URL link destination similar to the following:

Figure 4 shows the IBM Cognos Controller URL and the creation of the shortcut
Figure 4 shows the IBM Cognos Controller URL and the creation of the shortcut

For instance, http://servername/cognos8/controllerbin/ccr.exe

As a result of all the work (above), you should now have a share that looks similar to the following:

Figure 5 shows the files under the client_share directory
Figure 5 shows the files under the client_share directory

Install Client Software on User's PC

Overview, plus extra requirements for Microsoft Vista

Many of the installation steps require administrative permissions.

  • In many customer environments, you can install the IBM Cognos Controller client whilst logged onto the end user’s PC using any ‘administrative’ Windows user account.
  • However, to be sure that all settings are correctly configured (for the end-user’s profile) it would be ideal to:
    • Temporarily add the end user’s Windows user account to the local ‘administrators’ group
    • Perform the following steps (below)
    • Launch IBM Cognos Controller and conduct a briefly test

Afterwards, remove the end user’s Windows user account to the local ‘administrators’ group.

IMPORTANT: If you are using Windows Vista, there are some extra considerations / requirements:

  • Before starting the installation, click Start > Control Panel > User Accounts
  • In the User Accounts dialog box, turn off the user account control option.
    • If you do not turn the user account control option off, during later deployment/testing the user will receive a message stating that the configuration parameters have changed.
  • After the installation has finished the ‘user account control option’ can be switched on again.

TIP: If you cannot turn off the user account control, then a workaround is described inside the author’s separate document '(KB#1031830) Supplement Guide for installing IBM Cognos Controller 8.3 client on Microsoft Vista’ which is available inside the Technote #1365772.

Update third-party software

If necessary, upgrade Adobe Acrobat Reader and Microsoft Office.

For example

  1. Double-click "AdbeRdr812_en_US.exe"
  2. And then the appropriate MS Office service pack file (for example "OfficeXpSp3-kb832671-fullfile-enu.exe")
  3. plus also install MS Office hotfix, if using Office 2007 (see earlier).

Internet Explorer – bypass your Proxy Server

For IBM Cognos Controller to work properly, you should bypass your proxy server for all Controller communication.

  1. Open Internet Explorer
  2. Click Tools > Internet Options > Connections

In an ideal world, all the check boxes Automatically detect settings, Use automatic configuration script and Use a proxy server… should be clear (see below):

Figure 6 shows internet options for privacy and connections
Figure 6 shows internet options for privacy and connections

However, if your company uses a proxy server, then you need to "bypass" it to Controller:

  • Click LAN Settings
  • Add an entry for the <servername> inside the section Do not use proxy server for addresses beginning with

TIP: In my screenshot below, I have added a second entry so that both the NetBIOS name and the FQDN name are listed, just in case there is a change regarding the server name convention:

Figure 7 proxy settings and LAN settings
Figure 7 proxy settings and LAN settings

Internet Explorer – Trust Controller application server, to download code automatically

You must ensure that the client PC trusts the Controller server so that it can download the .NET code. The easiest way is to simply:

  • Double-click Trusted_Zone_add_Controller_APP_Server.vbs

Alternatively, you can perform this step manually – see Appendix 2.

Configure "Trusted Zone" security zone to be "medium (or lower) for IE6, and "medium-low" (or lower) for IE7)

The "trusted zone" security zone must be "medium" (or lower) for IE6, and "medium-low" (or lower) for IE7.

Figure 8 If you are not sure, you can reset the "trusted sites" zone security level to "low" (settings of the trusted sites)
Figure 8 If you are not sure, you can reset the

.NET Framework 2.0 SP2 client, .NET trust and disabling .NET certificate checking via internet

  • Double-click NetFx20SP2_x86.exe and accept all of the defaults
  • Double-click dotNET2.0_trust_<servername>.bat
  • Double-click caspol_disable2.bat

To avoid very slow client performance if your client PC does not have internet access, then:

  • Easy method: Double-click Check_CRL_certificate_disable.reg

Alternatively, you can perform this same step via the manual method in Appendix 3.

Ensure Microsoft Excel uses .NET 2.0 for all of its add-ins

Copy the file Excel.exe.config into the same location as where Microsoft Excel.EXE has been installed.

  • For example, the default location for Office 2003 is:
    C:\Program Files\Microsoft Office\OFFICE11

Installing Controller Excel add-in

  • Copy the file Excel.exe.config into the same location as where Microsoft Excel.EXE has been installed.

TIP: There are 3 different types of Controller clients that you can install. The recommendation in 99% of circumstances, you use the ControllerClient.MSI version.

  • See Appendix 1 for details on the alternative clients.
  • Ensure that the end-user’s Excel Macro Security setting is set to Medium.
    • For more information, see IBM Technote #1346175 ("Excel error message The macro 'cc.DoDataEntry' cannot be found appears")
  • Double-click ControllerClient.MSI.

Give end-user the URL shortcut

Copy the file IBM Cognos Controller 8.5.URL from the share to the end user’s desktop (inside their profile), so that they can easily launch the client.

Overall Summary of client install process

Once you have performed one client installation, you will be familiar with the process. Therefore, as an overall summary for the future client installations simply remember to open client share (\\servername\client_share) and then:

  1. If necessary double-click AdbeRdr812_en_US.exe
  2. If necessary apply the latest Microsoft Office service pack file (for example "OfficeXpSp3-kb832671-fullfile-enu.exe") and required hotfix "office2007sp2-kb953195-fullfile-enus.exe" (for Office 2007)
  3. If necessary configure Internet Explorer to bypass proxy
  4. Run Trusted_Zone_add_Controller_APP_Server.vbs
  5. If necessary configure IE’s "trusted zone" security zone to be "medium" (or lower) for IE6, and "medium-low" (or lower) for IE7
  6. Run "NetFx20SP2_x86.exe"
  7. Run "dotNET2.0_trust_<servername>.bat"
  8. Run "caspol_disable2.bat"
  9. Run "Check_CRL_certificate_disable.reg"
  10. Copy the file "Excel.exe.config" into the same location as where Microsoft Excel.EXE has been installed
  11. (If necessary) Ensure that the end-user’s Excel "Macro Security" setting is set to "medium" or lower
  12. Run "ControllerClient.MSI"
  13. Copy the file "Controller 8.5.URL" to the end user’s desktop (inside their profile), so that they can easily launch the client

Testing

Ideally, to make sure that everything is working correctly, you should:

  • First – launch IBM Cognos Controller as the Administrative user (the one that you installed the software with)
  • Second - after the initial testing, log off and log on as the "normal" end-user and test as him/herself.

Main IBM cognos Controller Program

Launch IBM Cognos Controller from URL and log in. Click Help > About Controller and ensure that the IBM Cognos Controller version matches what you expect.

Excel Link

Launch Excel. Click Help > About Controller link and ensure that the IBM Cognos Controller link version matches what you expect.


Installing on a Citrix (or Terminal Services) server

Scenario

Deployment of IBM Cognos Controller on Microsoft (Windows 2000/2003) Terminal Services is exactly the same concept as deployment on Citrix. Therefore, for the sake of simplicity, this document shall refer to both scenarios simply as "Citrix".

Deploying IBM Cognos Controller via Citrix is extremely common – it is probably that the majority of customers do this. It is very straightforward, and should present no difficulty.

One of the main reasons for deployment via Citrix is that remote WAN users may have poor network connections to the central system. As a guide, Controller typically requires 256kbps – 512kbps bandwidth per concurrent user (and a network latency of less than 80-100ms) in order to have good performance. Utilising Citrix allows deployment of IBM Cogno Controller to remote users whose network connections are poorer than this (e.g. as poor as approximately 30kbs and up to 250-300ms round-trip network latency).

Overview

Installing IBM Cogno Controller on a Citrix server is almost exactly the same as installing on a "normal" client PC.

However, when installing any software on a Citrix server, the following precautions should always be taken:

  • Ensure that no other users have a session on the Citrix server
  • Log on to the "console" session, for example:
    • Walk up physically to the Citrix server to log on there
    • Or remotely log on to the ‘console session’ via "mstsc.exe /console"
    • Or remotely log on via proxy software such as VNC
  • In general, software should always be installed when inside "install mode", for example by doing the following:
    • Install everything via ‘Add/Remove Programs’
    • or (alternatively) use the DOS command "change user /install" before installing software, and use the command "change user /execute" when the software has finished installing

TIP: Make sure that the Citrix server is in ‘install mode’ for these BOLDFACE sections.

Preparing the Citrix Server:

  • Disable Data Execution Prevention
    Citrix XP does not run the ‘iexplore.exe’ process on Citrix XP when the server has Microsoft’s DEP enabled. To fix this there are 2 options:
    • Disable DEP on the server
    • Remove the following key on the server: HKLM\Software\Citrix\CtxHook\AppInit_DLLS\speedscreen\iexplore.exe
    • Disable Automatic Excel link client install (step performed on the APP server)

VITAL: As recommended inside section 3.2 of this document, for Citrix server it is VITAL that you ensure that the setting "InstallExcelLink" is set to "false", inside "Client Distribution Server Config". If you do not do this, then when new users log on to the Citrix server, the system will try to re-install the ControllerClient.MSI client software

IBM Cognos Controller Client Installation

After doing the above pre-requisite steps, you perform exactly the same tasks as you would for a ‘normal’ (non-Citrix) client install. In other words, you follow the same steps as described inside section 5 of this document. If you require more details whilst performing this section, please refer back to that section (5).

IMPORTANT: Remember, the following should be done to ensure Citrix server is configured correctly.

Note: Check pre-requisites are already installed.

  • Windows 2003 Service Pack 2
  • Microsoft Office with latest service pack
  • If using Office 2007, ensure have installed hotfix office2007sp2-kb953195-fullfile-en-us.exe
  • Internet Explorer 7
  • Microsoft .NET 2.0 Service Pack 2
  • Ensure Adobe Acrobat Reader 8.12 is installed
  • Install/upgrade if necessary

TIP: Afterwards, launch Adobe Reader at least once (to ensure that the license agreement is ‘accepted’) to avoid problems later.

  • Check Internet Explorer settings:
Figure 9 IMPORTANT: Ensure that the Internet Explorer Enhanced Security Configuration check box is clear.
Figure 9 IMPORTANT: Ensure that the Internet Explorer Enhanced Security Configuration check box is clear.
    • Ensure that Internet Explorer does not have a proxy server configured
      • If necessary, bypass your Proxy Server for the Controller website
    • Add Controller website to trusted zone, and check zone security settings
    • Configure Microsoft .NET 2.0 SP2:
      • Install "NetFx20SP2_x86.exe" (unless already installed)
      • Run "dotNET2.0_trust_<servername>.bat"
      • Run "caspol_disable2.bat"
      • Run "Check_CRL_certificate_disable.reg"
    • Copy ‘Excel.exe.config’ file to EXCEL.EXE location
    • Check Excel "Macro Security" setting. If necessary:
      • change to ‘Medium or lower’ and select "trust all add-ins and templates…"
  • Run “ControllerClient.MSI”
  • Test Controller, by launching it whilst still logged on as an administrator:
  • Launch Controller program http://controllerserver/cognos8/controllerbin/ccr.exe
    • Log in and click Help > About Controller
    • Ensure that the IBM Cognos Controller version matches what you expect.
  • Launch Excel
    • Click Help > About Controller link
    • Ensure that the Controller link version matches what you expect
  • Create a new Citrix Published application to the Controller 8.5.URL
    • for example http://controllerserver/cognos8/controllerbin/ccr.exe
  • Test the published application as an administrator
    • TIP: when Controller has launched, click on the "Excel" shortcut (on the menu bar) to launch Excel, so you can check the Excel link
  • Finally, test the Citrix published application as a "normal" (non-administrative) user

Additional tips for Citrix / Terminal Server Deployments

Stability:

  • Request that there is a weekly period of downtime for an automated Citrix server reboot (for example, every Sunday morning at 5am), as a proactive measure to clear out any potential ‘memory leaks’

Installation to non-default folder location

By default, ControllerClient.MSI will install the “Excel link” files in the directory C:\Program Files\Cognos\ccr. This location is taken from the %programfiles% variable.

  • If required, you can manually force it to install to a different folder, for example:
    "msiexec /i controllerclient.Msi COGNOSDIR=d:\myinstallfolder DOTNETDIR=d:\myinstallfolder"

NOTE: If this fails, or has an error, you can diagnose this by using the following command:

msiexec /i controllerclient.msi /log error.txt

This will output the installation activity and information to a text file, which we can use to diagnose the problem.

Mandatory Profiles - Manually Registering Excel link

Figure 10 The IBM Cognos Controller link is registered inside Excel via the following registry key
Figure 10 The IBM Cognos Controller link is registered inside Excel via the following registry key

For example, for Office XP/2002, this is:

[HKEY_CURRENT_USER\Software\Microsoft\Office\10.0\Excel\Options]
  "OPEN"="/R \"C:\\Program Files\\Cognos\\ccr\\ControllerXL.xll\""

From IBM Cognos Controller 8.1MR1 onwards, it will automatically add this entry when Excel is launched from the main IBM Cognos Controller program itself. Therefore, for most environments, there is no more that you need to do.

However, in certain environments (for example, where there are "mandatory" Windows profiles in use), you may need to ask the I.T. administrator to ensure that this registry key is added during log on (for example, via USRLOGON.CMD).

Printing Optimisation

The default setting for a published application is "Start this application without waiting for printers to be created". However, we have seen occasional problems with this. Therefore, we recommend that you clear this check box for IBM Cognos Controller.

Profile management - Problem with large profiles?

The Cognos Controller 8 client uses the Windows profile location for storing personal settings, cache files and some .NET technology business logic files.

  • The client personal settings are stored by default in:
    c:\Documents and Settings \%username%\Application Data\Cognos\ccr\ccr.config
  • Client cache files are located in:
    c:\Documents and Settings \%username%\Application Data\Cognos\ccr\*.dss en *.dsd
  • .NET assembly cache:
    C:\Documents and Settings\%username%\Local Settings\Application Data\assembly\dl2\*.*

For TS/Citrix servers this would mean that a profile would need considerable space available. When space is limited for profile sizes, Cognos advises to redirect the profile location for TS/Citrix users onto a larger drive using the directions mentioned in http://support.microsoft.com/kb/322014/en-us. If profile size management is needed, a logoff script can be used to clean the users Client cache and assembly cache directory.

In addition, consider installing "UPHClean" - UPHClean-Setup.msi. This Microsoft tool causes Citrix/Terminal Servers to handle profiles (and file locks) in a different (typically improved) way.

By default, Controller will store some cache files (e.g. *.rs) inside the folder %APPDATA%\Cognos\Controller.

Workaround #1: It is possible to assign logoff cleanup scripts (e.g. see http://www.microsoft.com/windows2000/en/advanced/help/default.asp?url=/windows2000/en/advanced/help/gptext_logoffscripts.htm)

Workaround #2: Alternatively you can try using the unsupported ‘local preference’: clearcacheonexit … true

[This will clear the local cache, but obviously the cache is there for a reason – to speed up user’s sessions].

Miscellaneous Tip

If (for whatever reason) you find that there is a process (e.g. Access Manager’s common logon) which is not cleanly exiting when a user logs off from Citrix, then you can kill any process (at logoff when using Citrix) with the following key (this sample kills the "common logon" process, but can be modified):

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Citrix\wfshell\TWI
LogoffCheckSysModules REG_SZ = WinLogonServer.exe

Appendices

Appendix 1 – Alternative for IBM Cognos Controller Client Types

IBM Cognos Controller 8.5 has 3 different types of client installation MSI:

  • ControllerClient.Msi
  • ClientAdmin.Msi
  • CCRLocalClient.Msi

Full details of the differences between these three are discussed inside IBM Technote #1371088.

For example, in some environments it may be best to deploy the CCRLocalClient.Msi client. Typically this is at a very locked-down environment (for example, some Citrix environments, and also some non-Citrix environments where the end user’s Internet Explorer is heavily ‘locked down’).

Important

If you choose to not use the ‘ControllerClient.MSI’ file, then it is important that you disable ‘Automatic Excel link Client install’

TIP: If you deploy the ‘CCRLocalClient.Msi’ client, then you will be asked for the WSS and HELP URL locations when installing. By default, these are

http://[servername]/cognos8/controllerserver

http://[servername]/cognos8/controllerhelp

Appendix 2 – Manual Method of configuring Microso Internet Explorer trusted sites

To perform this step manually, do the following:

  • Open Internet Explorer
  • Tools > Internet Options > Security
  • Select Trusted sites and click Sites
Figure 11 shows the internet options and security settings
Figure 11 shows the internet options and security settings
  • Clear the check box Require server verification (https:) for all sites in this zone
  • Add the site http://servername to the list
  • Click Close

Appendix 3 – Manual Method of configuring Microso Internet Explorer Publisher's Certificate revocation

Launch Internet Explorer

  1. Click Tools > Internet Options
  2. Click the Advanced tab
  3. Scroll down to the Security section
  4. Clear the check box next to Check for publisher's certificate revocation

Comments

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


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Big data and analytics, Information Management
ArticleID=497138
ArticleTitle=IBM Cognos Proven Practices: How to Install the IBM Cognos Controller 8.5 Client on a User's PC
publish-date=06212010