Customizing the Cognos 8 Welcome Page

Proven Practice

Customizing the IBM Cognos 8 Welcome Page

Product(s): IBM Cognos 8

Area of Interest: Infrastructure


2

Cognos Proprietary Information

Copyright

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 www.cognos.com

This document is maintained by the Best Practices, Product and Technology team. You can send comments, suggestions, and additions to [email protected] .


3


Contents

1 INTRODUCTION ............................................................................................ 4

2 CUSTOMIZATION OPTIONS .......................................................................... 4

3 CREATE OR USE YOUR OWN CUSTOM WELCOME PAGE ............................... 8

4 LOCALIZATION AND STYLES....................................................................... 12

5 MODIFYING THE ORDER AND ADDING CUSTOM SECTIONS TO THE

WELCOME PAGE...................................................................................................... 12

6 APPENDIX – REFERENCE THE REQUIRED GROUPS OR ROLES IN THE

SYSTEM.XML FILE................................................................................................... 15


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” style:


5


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


6


Files Used

<install-location>/c8/webcontent/skins/corporate/portal/default.css

<install-location>/c8/templates/ps/messages/portal_en.xml

<install-location>/c8/webcontent/corporate/fonts.css

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.

.welcomePageFull { background-color: #ffffff; padding: 0%; }

Controls the outer-most border and the blue vertical lines on the right hand side of the page.

.welcomeContentPanel { border-style: solid; border-width: 0px; border-color: #000000; padding:0px; background-image: url(../branding/welcome_back.gif); }

Controls the image used at the top of the Welcome Page

.welcomeLogoContainer { height: 55px; width: 225px; background-image:url(../branding/bank.gif); background-repeat: no-repeat; }

Controls the text color of the user that’s logged in.

.welcomeUserNameContainer { padding-right:8px; color: #333300;

padding-bottom: 5px; font-weight: bold; white-space:nowrap; }

Controls the left-hand “Welcome Panel”

.welcomeLeftPanel { background-color: #c5c58a;

height: 100%; margin-right:1px; text-align: middle; vertical-align:top; } .welcomeTitle { color: #333300; text-align: left; border-bottom: 3px solid #666633;


7


width:100%; white-space:nowrap; 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. .welcomeToolPanel { height:100%; background-color: #eeeecf; margin-left:1px; padding-top: 15px; padding-left: 15px; padding-right: 15px; }

.welcomeToolHeading { font-size: 70%; font-weight: bold; color: #333300; padding-bottom:3px;

} .welcomeToolDescription { font-size: 70%; color: #333300; }

Change the color of the hyperlinks

a { color: #333399; }

Controls the “Show this page in the future”

.welcomeHideShowText { padding-left:5px; font-size: 70%; color: #333300; }

Controls the Quick Tour button

.welcomeQTContainer { margin-top:15px; float:right; background-color: #e4e4c5; border:1px solid #333300; padding: 1px; } .welcomeQTButton { background-color: #e4e4c5; cursor:pointer; color: #333300; font-size: 70%; padding:5px; font-weight: bold; white-space:nowrap; } .welcomeLegalNotice {


8


margin-top:20px; font-size: 70%; color: #ffffff; } .welcomeSlogan { font-size: 50%; color:#ffffff;

white-space:nowrap; }

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 language.

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.


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.

<param

name=“welcomeURLOverride”>http://server/cognos8/customwelcomepage.html”</par

am>

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:

http://server-name/cognos8/cgi-bin/cognos.cgi?b_action=xts.run&m=portal/welcome/welcome.xts&basewelcome=yes&wtarget=top

B. Modify the default.css (of your style) to change background colors of the main section of the welcome page. .welcomeToolPanel

{ height:100%; background-color: #ffffff; margin-left:1px; 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:


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 name=“welcomeURLOverride”>http://server/cognos8/customwelcomepage.html”</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).

Examples:

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

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


11


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”

URL links to other reports, studios, and pages


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. custom_welcome/en/classic custom_welcome/en/contemporary custom_welcome/en/corporate custom_welcome/en/modern custom_welcome/en/presentation

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">

http://server-

name/cognos8/custom_welcome/%LOCLAE%/%STYLE%/customwel.htm

<param>

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:

/cognos8/custom_welcome/FR/CLASSIC/customwel.htm

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 groups.

Modifying the Order of Tools


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="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="welcome.xsd"> <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" /> </welcome

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

capabilities).

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


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="http://www.google.com" 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="http://www.google.com" onmouseover="window.status='';return true;" onmouseout="window.status='';return true;">Google</a> pour rechercher la substance sur l'enchaînement.</body> </tool>

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 English:

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”.


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

sensitive.

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>

</param> 3. Save the system.xml file. Restart the IBM Cognos 8 service.


16


Documents

Customizing the Cognos 8 Welcome Page