IBM Support

How to upgrade Controller 10.3.1.x to a later Interim Fix (IF) Fix Pack (patch) level



Customer has a working Controller 10.3.1.x application server. Customer would like to patch this 10.3.1 server to a later version of 10.3.1. How do they do this?


For reference, here are the version numbers of Controller 10.3.1 which this Technote relates to:

  • 10.3.1 RTM = 10.3.1100.156
  • 10.3.1 IF1 = 10.3.1100.159
  • 10.3.1 IF2 = 10.3.1100.166
  • 10.3.1 IF3 (GA = generally available, original release - released 1st May 2018) = 10.3.1100.176
  • 10.3.1 IF3 (GA = generally available, updated version - released 16th May 2018) = 10.3.1100.177
  • 10.3.1 IF4 (GA = generally available) = 10.3.1100.183
  • 10.3.1 IF5 = 10.3.1100.186
  • 10.3.1 IF6 = 10.3.1100.186 (Also!)
  • 10.3.1 IF7 = 10.3.1100.190
  • 10.3.1 IF8 = 10.3.1100.193
  • 10.3.1 IF11 (GA = generally available) = 10.3.1100.198
  • 10.3.1 IF12 (GA = generally available) = 10.3.1100.206
  • 10.3.1 IF13 (GA = generally available) = 10.3.1100.219
  • 10.3.1 IF14 = 10.3.1100.219 (Also!)


This Technote describes the process of how to upgrade from any version listed above, to any later version also displayed above.

  • For example, a customer may want to upgrade from Controller 10.3.1100.156 (also known as 10.3.1 RTM) to 10.3.1100.166 (also known as 10.3.1 Interim Fix 2).


It is possible to patch an existing 10.3.1 Controller application server *without* having to perform a full uninstall/re-install of the Controller application server software. However, care needs to be taken (during the patching process) to ensure that all Controller-related services/systems/components are stopped.

IMPORTANT: All patches are cumulative.
Therefore, there is no need to apply/install any other patches (apart from the one that you wish you upgrade your system to).

  • Example: If you wish to upgrade from Controller 10.3.1 RTM (10.3.1100.156) to 10.3.1 IF2, then there is no need to also install Controller 10.3.1 IF1 in between.



Customer's environment currently running any version of Controller 10.3.1 (for example 10.3.1100.156) and would like to patch it to a later 10.3.1 version (for example 10.3.1100.166).

Diagnosing The Problem

To check which version of Controller you are currently using, click "Help - System Info" (inside the Controller client) and check the value of the first/top line.

Resolving The Problem

IMPORTANT: In an ideal world, you should get an experienced IBM Technical Consultant onsite to help you perform these tasks.

  • However, assuming they have actioned all the precautions listed in the document, then a customer may feel confident to perform these tasks themselves (without any outside assistance).

To upgrade the Controller application server, perform the following tasks:

1. Download a copy of the patch (either a Fix Pack or Interim Fix).


  • Fix Packs (FP) are freely available from IBM Fix Central (link below). Therefore you do not need to log a support call (PMR) to obtain these.
  • However, to obtain a copy of most interim fix (IF) patches you must log a support call with IBM Support
  • The exceptions are any 'GA' (generally available) patches. These are freely available from IBM Fix Central (link below) - there is no need to log a support call (PMR) to download GA fixes.

2. Obtain downtime (no users on system)

3. As a precaution, perform the following tasks:
(a) Backup all Controller-related databases (application repositories, ContentStore and FAP)

  • As an extra precaution, you could also perform a 'full deployment export' of the content store. For instructions on how to do this, see separate IBM Technote #1985447.

(b) Launch "Cognos Configuration" and create a backup of all the settings

  • Typically this means click "File - Export As" and save the settings as an XML file (in a safe place)

  • As an extra precaution, you could also create a Word document with printscreens of all the current settings

(c) Launch "Controller Configuration" and create a backup of all the settings

  • e.g. create a Word document with printscreens of all the current settings

(d) If using virtual servers (for example ESX) then create a backup image of the virtual server(s)

  • In other words, ask your ESX administrator to create a virtual snapshot backup of any server (for example Controller application server) before you make any changes.

4. VITAL: Shut down all Controller-related Windows services (running on the application server(s))

Specifically, stop the following Windows services:

  • IBM Cognos
  • IBM Cognos Controller Batch Service
  • IBM Cognos Controller Consolidation
  • IBM Cognos Controller Java Proxy
  • IBM Cognos Controller User Manager
  • IBM Cognos Controller Web
  • IBM Cognos FAP Service

5. VITAL: Shut down other Controller-related subsystems (running on the application server(s))


  • Launch the "Internet Information Services (IIS) Manager" tool
  • Highlight the Default Web Site.
  • Click "Stop":

  • Launch the "Components Services" tool
  • Right-click the "IBM Cognos Controller Consolidation" COM+ application and choose "Shut down":

6. As a precaution, now take a backup copy of the entire ccr_64 folder (e.g. compress inside a backup ZIP file):

[This process helps make it easier to revert back to the older version of Controller if necessary later].

7. If the Controller application server has a Controller client installed, then uninstall the Controller client first before proceeding:

8. Install patch onto the application server(s) by doing the following:

  • Extract the compressed patch file
  • Double-click on installer file issetup.exe (inside subfolder winx64h)
  • Navigate through the installation wizard (in general by accepting all the default options).
  • TIP: Ensure that you choose the installation folder to be the same folder as the current installed version
  • If you have multiple Controller application servers, apply the patch for all remaining Controller application servers.

9. After the patch has finished installing, launch "IBM Cognos Configuration". Click the buttons (near the top-left corner of the screen) to:

  • Save the current configuration
  • Start the IBM Cognos service:

10. Afterwards, launch "Controller Configuration" and open the section 'Database Connections'. Click on each database connection, and click on the green 'play' button.

  • Check to see if the 'Current Version' is set to be the same as the 'Upgrade to' version:

Sometimes (depending on the old/new versions of Controller) the "Upgrade to" will have increased (because of the patch). If so, then you must press 'Upgrade' to upgrade your Controller application databases (to the latest version).

11. Inside Controller Configuration, check that all the other settings look *exactly* the same as before the upgrade.

  • Most importantly (in particular) check 'Report Server'.

TIP: Refer to the printscreens that you took earlier (in step 3 - before the upgrade) to make sure that the settings look the same as before.

12. If you used "ISAPI" before the upgrade, then:

  • change "Report Server" to mention cognosisapi.dll instead of cognos.cgi
  • modify the files "default.htm" and "index.html" (located in webcontent folder) to refer to cognosisapi.dll instead of cognos.cgi

13. Inside the IIS Manager, highlight the "Default Web Site" and click "Start"

14. You must perform this step if all of the following are true:
  • You are patching from Controller 10.3.1 IF7 (or earlier) to IF8 (or later)
  • You are using the optional 'Controller Web' functionality
  • You are using Microsoft SQL to host your Controller databases.
If all of the above are true, then you must:
(a) Right-click on the ‘Start’ menu, and choose ‘Command Prompt (Admin)’
(b) Type a command similar to:  cd C:\Program Files\IBM\cognos\ccr_64\fcmweb
•If you have installed Controller to a non-default location, then modify this accordingly.
(c) Type the following command:   SyncDBConf.bat ..\Data wlp\usr\shared\config\datasources
  • The reason (that this step is necessary) is because the datasources.xml file (...\ccr_64\fcmweb\wlp\usr\shared\config\datasources\datasources.xml) must have its parameter sendStringParametersAsUnicode changed to "false" for all of the relevant/corresponding database connections
  • In the highly unlikely event that you have previously customised your Controller Web to use advanced parameters (for example SSL - see separate Technote #1998458) by manually editing the "datasources.xml" file, then you will need to re-do those additional changes (to the datasources.xml file). This is because the SyncDBConf tool will erase the custom changes (it will modify them back to the default settings).

15. Afterwards, reboot Controller application server(s) (to make sure that all changes have been 100% registered)

16. Upgrade client software on each-and-every end-user's client device (see below).

Simplified instructions for how to upgrade *Client* software on each-and-every end-user's client device:
1. Logon to the client device as the SAME Windows administrator which originally installed the Controller client.
2. Launch "Add/Remove Programs" and remove the Controller client (for example "IBM Cognos Controller Local Client"):

3. Download the new version of the Controller client from the application server

4. Double-click on the client installation file (for example "CCRLocalClient64.msi")
5. Follow the installation wizard

  • TIP: Below is an example of a completed WSS and Help Url section:

TIP: If you are unsure what values to use (for example WSSUrl) then open the file %APPDATA%\Cognos\CCR\ccr.config (inside NOTEPAD) and read the values from there.

6. If the client device does not have access to the internet (e.g. most Citrix/Terminal servers) then modify the file "ccr.exe.config" (inside C:\Program Files\IBM\IBM Cognos Controller Local Client\) as explained inside separate Technote #1441779.

[{"Product":{"code":"SS9S6B","label":"IBM Cognos Controller"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"Controller","Platform":[{"code":"PF033","label":"Windows"}],"Version":"10.3.1","Edition":"","Line of Business":{"code":"LOB10","label":"Data and AI"}}]

Document Information

Modified date:
03 April 2020