You are on page 1of 16

Proven Practice

Customizing the IBM Cognos 8

Welcome Page
Product(s): IBM Cognos 8
Area of Interest: Infrastructure
Customizing the IBM Cognos 8 Welcome 2

Copyright © 2008 Cognos ULC (formerly Cognos Incorporated). Cognos ULC
is an IBM Company. While every attempt has been made to ensure that the
information in this document is accurate and complete, some typographical
errors or technical inaccuracies may exist. Cognos does not accept
responsibility for any kind of loss resulting from the use of information
contained in this document. This document shows the publication date. The
information contained in this document is subject to change without notice.
Any improvements or changes to the information contained in this document
will be documented in subsequent editions. This document contains
proprietary information of Cognos. All rights are reserved. No part of this
document may be copied, photocopied, reproduced, stored in a retrieval
system, transmitted in any form or by any means, or translated into another
language without the prior written consent of Cognos. Cognos and the
Cognos logo are trademarks of Cognos ULC (formerly Cognos Incorporated)
in the United States and/or other countries. IBM and the IBM logo are
trademarks of International Business Machines Corporation in the United
States, or other countries, or both. All other names are trademarks or
registered trademarks of their respective companies. Information about
Cognos products can be found at
This document is maintained by the Best Practices, Product and Technology
team. You can send comments, suggestions, and additions to .

Cognos Proprietary Information

Customizing the IBM Cognos 8 Welcome 3

1 INTRODUCTION ............................................................................................ 4
2 CUSTOMIZATION OPTIONS .......................................................................... 4
3 CREATE OR USE YOUR OWN CUSTOM WELCOME PAGE ............................... 8
4 LOCALIZATION AND STYLES....................................................................... 12
WELCOME PAGE...................................................................................................... 12
SYSTEM.XML FILE................................................................................................... 15

Cognos Proprietary Information

Customizing the IBM Cognos 8 Welcome 4

1 Introduction

IBM Cognos 8 has a predefined Welcome page that all users are directed to
when they first login. This Welcome page varies on the user’s style.
Although the Welcome page provides a good starting point into IBM Cognos
products, most customers will inevitably want to customize this page or
bypass it altogether.

In IBM Cognos 8, users and administrators have the capability to set any
view as their home or Welcome page. An administrator can customize the
existing Welcome page, use their own custom HTML page, or use a hybrid of
their custom Welcome page and sections of the existing Welcome Page.
Furthermore, users can choose to set any portal tab as their home page.
This document provides technical details on how this can be done as well as
details on how this can be localized.

2 Customization Options

Administrators can customize the Welcome Page in the following ways:

Change the colors, fonts, and text of the existing Welcome Page.
Set their own HTML page as their default Welcome Page. Using this
approach, administrators can still embed the “links” and “text” of the default
Welcome Page within their own custom page.
Set any portal tab as their default start page.

Customizing the existing Welcome Page

Here is a look at the default IBM Cognos 8 Welcome Page for the “Corporate”

Cognos Proprietary Information

Customizing the IBM Cognos 8 Welcome 5

This page can be customized to use its own colors, text, and fonts to match
your corporate branding.

Cognos Proprietary Information

Customizing the IBM Cognos 8 Welcome 6

Files Used

Modifying the Colors of the Welcome Page

The default.css file controls the colors used in the existing Welcome Page.
The following parameters can be modified to customize this Welcome Page:

Controls the outer blue background on the Welcome page.

background-color: #ffffff;
padding: 0%;
Controls the outer-most border and the blue vertical lines on the right hand side of the page.
border-style: solid;
border-width: 0px;
border-color: #000000;
background-image: url(../branding/welcome_back.gif);
Controls the image used at the top of the Welcome Page
height: 55px;
width: 225px;
background-repeat: no-repeat;
Controls the text color of the user that’s logged in.
color: #333300;
padding-bottom: 5px;
font-weight: bold;
Controls the left-hand “Welcome Panel”
background-color: #c5c58a;
height: 100%;
text-align: middle;
color: #333300;
text-align: left;
border-bottom: 3px solid #666633;

Cognos Proprietary Information

Customizing the IBM Cognos 8 Welcome 7

font-weight: bold;
padding-left: 10px;
padding-right: 10px;
padding-top: 10px;
font-size: 120%;

Controls the background and text color in the main section of the page.
background-color: #eeeecf;
padding-top: 15px;
padding-left: 15px;
padding-right: 15px;
font-size: 70%;
font-weight: bold;
color: #333300;
font-size: 70%;
color: #333300;
Change the color of the hyperlinks
color: #333399;
Controls the “Show this page in the future”
font-size: 70%;
color: #333300;
Controls the Quick Tour button
background-color: #e4e4c5;
border:1px solid #333300;
padding: 1px;
background-color: #e4e4c5;
color: #333300;
font-size: 70%;
font-weight: bold;

Cognos Proprietary Information

Customizing the IBM Cognos 8 Welcome 8

font-size: 70%;
color: #ffffff;
font-size: 50%;

End Result

Changing the Default Text on the Welcome Page

The text that appears on the Welcome Page comes from message files. In
particular, the text for the Welcome Page is located in the <install-
location>/c8/templates/ps/messages/portal_language.xml file. To modify the
English text used in the Welcome page, you would need to modify the
portal_en.xml file. All other languages have a prefix to specify their

To modify the text, search for the appropriate text string you wish to modify
and modify it directly within this file. Please note that the IBM Cognos 8
service needs to be restarted for these changes to take effect.

3 Create or Use your Own Custom Welcome Page

In many instances, administrators may wish to have a Welcome Page that
matches a very specific style or they may want their users to enter IBM
Cognos through another web site. Instead of using the existing Welcome
Page, you can create your own custom Welcome Page using any standard
HTML page.

Cognos Proprietary Information

Customizing the IBM Cognos 8 Welcome 9

To configure IBM Cognos 8 to use its own Welcome Page:

1. Edit the <install-location>/c8/templates/ps/portal/system.xml file
2. Enter the following parameter in this file.


Make sure that this parameter is entered inside the <system> node and
outside of the <param> node.
3. Restart the IBM Cognos 8 service.

When you launch IBM Cognos 8, this new Welcome Page will be used.
Additionally, the link through Help > Go to Welcome Page will point to this
new Welcome Page as well.

Any standard HTML page can be used as your new Welcome Page. However,
as an administrator, you may wish to also place the appropriate links and
login parameters to IBM Cognos 8. There are a few different techniques that
you can be used to do this.

Using “Links-Only” to the Welcome page

Administrators can embed only the links from the standard Welcome Page
into their own custom Welcome page. With this approach, only the links and
text of the main section of the Welcome Page will appear, without the extra
colors and banners used in the standard Welcome Page. This approach is
especially beneficial as it allows you to embed the Welcome Page within a
frame of any HTML page while preserving capabilities. To do this:
A. Place the following URL within a frame of your HTML page:
B. Modify the default.css (of your style) to change background colors of
the main section of the welcome page.
background-color: #ffffff;
padding-top: 15px;
padding-left: 15px;
padding-right: 15px;

C. Once the URL is placed with a frame of an HTML page, the result may
look as follows:

Cognos Proprietary Information

Customizing the IBM Cognos 8 Welcome 10

With this approach, all capabilities and permissions are preserved – assuring
that the user will only view those links that they are entitled to see.

Use a Custom Welcome Page and Link to IBM Cognos through URLs
Administrators can define a completely generic HTML page can be used with
hard-coded URL links to IBM Cognos. In this case, all that is required is to
place the following parameter in the system.xml file; <param
tml”</param>. Note: With this approach, the user is not authenticated –
meaning that the user will need to login when entering IBM Cognos
Connection and the text on this new Welcome Page will be hard-coded (and
not controls by capabilities).

• Custom Welcome Page with a banner that links to IBM
Cognos Connection

• Using a Report or a Portal Page as the Welcome Page

Cognos Proprietary Information

Customizing the IBM Cognos 8 Welcome 11

URL links to other reports,

studios, and pages

With this approach, the user will be prompted for their credentials when this
page is invoked.

1. User Defined Start Page

Users can browse to any portal page and set this page as their home page –
by clicking on Home > Set View as Home. Note: This start page is user
specific and the administrator cannot override or control this start page for
users or for groups of users.

For more information about customizing the Welcome Page, refer to the
“Customization” section of the “Cognos 8 Administration & Security Guide”

Cognos Proprietary Information

Customizing the IBM Cognos 8 Welcome 12

4 Localization and Styles

Administrators can localize their Welcome pages and make them skin
sensitive. To do this, the administrator will need to create a separate custom
welcome page for each language and/or skin. However to reference this
locale and skin sensitive Welcome page, the page must be placed in the
appropriate skin and/or language directory. For example, suppose that you
wish to support English, French, German, and Japanese for all the out-of-the-
box styles. In this case, you would need to create the following directory
structure (where your custom Welcome page resides) and place the
appropriate custom pages within each directory.

For IBM Cognos 8 to use these skin and/or language sensitive custom
Welcome page, parameters need to be placed with the URL to specify the
appropriate skin and/or language. In the system.xml file, wildcards can be
used within the URLs: %LOCALE% and %SKIN%, where %LOCALE%
denotes the product locale and %STYLE% is the user’s currently selected
skin. To make the Welcome page both skin and language sensitive, the
following parameters would be added to the systeml.xml file.
<param name= "welcomeURLOverride">

In this case, if a user who’s product locate was set to French and skin set to
Classic, the welcome screen url would be calculated as:

5 Modifying the Order and Adding Custom Sections to the

Welcome Page

Administrators can change the order of the tools and links shown on the
Welcome Page. They can choose to show tools to certain groups/roles or
add new custom section. The order of the tools and the tools shown on the
welcome page are governed in the following file: <install
directory>/templates/ps/portal/welcome/welcome.xml. Modifying this file will
change the order and which tools are shown in the welcome page. Adding a
show attribute will restrict the visibility of the tool to certain roles, users or

Modifying the Order of Tools

Cognos Proprietary Information

Customizing the IBM Cognos 8 Welcome 13

The order that the tools show up in the welcome page is defined by the order
of the tool tags. For example, this order can be modified to change the
order in which the tools appear:

<welcome xmlns:xsi=""
<tool name="ViewCognosContent" type="cognos"/>
<tool name="AnalysisStudio" type="cognos"/>
<tool name="EventStudio" type="cognos"/>
<tool name="Planning" type="cognos"/>
<tool name="Controller" type="cognos"/>
<tool name="MetricsManager" type="cognos"/>
<tool name="QueryStudio" type="cognos"/>
<tool name="ReportStudio" type="cognos"/>
<tool name="ManageCognosContent" type="cognos" />

The tools in the Welcome page will then appear in this order:

Hiding Tools

Tools can be permanently hidden be removing the relevant tool tag from the
welcome.xml file. If a tool is not present in the welcome.xml file, it will not
show up as a link in the welcome page (even with the appropriate

Tools can be restricted to be used by user, group or role by adding a “show”

attribute to the tool tag. The show attribute can take on any of the following
predefined values: Administrators, QSUsers, RSUsers, Consumers, or
Anonymous or a value in the system.xml can be defined using the ui_groups
tag (see Appendix for more information on adding ui_groups). For example,
show=”Consumers” will restrict the tool to only users in the Consumers
group. show=”Consumers, Anonymous” will show the tool to both users in
the Consumer group and anonymous users. Leaving the show attribute out
of the tool tag means show the tool to all users

Cognos Proprietary Information

Customizing the IBM Cognos 8 Welcome 14

Adding Custom Sections

Custom links can be added to point to virtually any destination by adding a

tool tag with the type “custom”. These tools follow the same rules as the
default “tool” tags. Their order is governed by their order in the welcome.xml
file and the “show” attribute restricts access to the tool. For example, if we
want to add a custom tool:
<tool name="search" type="custom" >
<heading xml:lang="en">Search For Stuff</heading>
<heading xml:lang="fr">Recherche de substance</heading>
<body xml:lang="en">Use <a href=""
onmouseover="window.status='';return true;" onmouseout="window.status='';return
true;">Google</a> to search for things on the web.</body>
<body xml:lang="fr">Utilisateur <a href=""
onmouseover="window.status='';return true;" onmouseout="window.status='';return
true;">Google</a> pour rechercher la substance sur l'enchaînement.</body>

This example shows a link in the Welcome Page to Google. The “heading”
tag is the text that appears as the title of the tool and the “body“ tag appears
as the description section. Both tags can contain any well-formed HTML.
Since these sections can contain translatable elements, an xml:lang attribute
is used to show which language the heading or body is meant for. When IBM
Cognos Connection renders the Welcome page, it uses the heading and body
tags where the xml:lang tags is set to the user’s product locale. For example,
the above modifications will render the following if the product locale is set to

But render the following, if the product locale is set to French:

For users who have there product locale set to German, the link will not show
up at all since there is no heading or body with the xml:attribute = “de”.

Cognos Proprietary Information

Customizing the IBM Cognos 8 Welcome 15

6 Appendix – Reference the Required Groups or Roles in the

system.xml File

Before you start implementing the customization changes in the IBM Cognos
Connection user interface, you must identify the groups or roles on which
your customizations will be based.

Add a reference about the groups or roles you want to use to the portal
system.xml file. Modify this file by adding the ui_groups parameter and
listing all required groups and roles within this parameter. Each group or role
is represented by the group element that must contain a unique id attribute.
The value of the id attribute is specified in the group or role search path in
IBM Cognos Connection. Include only the groups and roles you want to use
for the purpose of hiding or adding user interface elements. The groups and
roles must already exist in IBM Cognos 8 and can be associated with any
namespace configured for your IBM Cognos 8 environment.

To reference a group:
1. Open the c8_location/templates/ps/portal/system.xml file in a text editor.
2. Add a parameter named ui_groups and then do the following:
A. Add the group element for each group or role you want.
B. Specify a unique id attribute for each group or role. The IDs are case
C. For the custom groups or roles, the IDs cannot contain more than two
characters, and cannot contain spaces. For example, the following IDs
can be used: a1, b2, Ab, AB. The following IDs cannot be used: abc, A 1,
a bc.
D. Specify a value for the id attribute for each group element.
Tip: To find the ID in IBM Cognos Connection, open the group or role
properties page and, on the General tab, click the View the search path
and ID link.

The following example shows the syntax of the ui_groups parameter.

<param name="ui_groups">
<group id="g1">xOm5ldyBncm91cHM6dWlHMV9lbg_</group>
<group id="g2">xOm5ldyBncm91cHM6dWlfUjI_</group>
<group id="55">xOf5ldyBnc4htcHM6dAlfUjI_</group>
3. Save the system.xml file. Restart the IBM Cognos 8 service.

Cognos Proprietary Information

Customizing the IBM Cognos 8 Welcome 16

Cognos Proprietary Information