IBM Cognos 8

ADMINISTRATION AND SECURITY GUIDE

Product Information
This document applies to IBM Cognos 8 Version 8.4 and may also apply to subsequent releases. To check for newer versions of this document, visit the IBM Cognos Resource Center (http://www.ibm.com/software/data/support/cognos_crc.html).

Copyright
Copyright 2008 Cognos ULC (formerly Cognos Incorporated). Cognos ULC is an IBM Company. Portions of Cognos ULC software products are protected by one or more of the following U.S. Patents: 6,609,123 B1; 6,611,838 B1; 6,662,188 B1; 6,728,697 B2; 6,741,982 B2; 6,763,520 B1; 6,768,995 B2; 6,782,378 B2; 6,847,973 B2; 6,907,428 B2; 6,853,375 B2; 6,986,135 B2; 6,995,768 B2; 7,062,479 B2; 7,072,822 B2; 7,111,007 B2; 7,130,822 B1; 7,155,398 B2; 7,171,425 B2; 7,185,016 B1; 7,213,199 B2; 7,243,106 B2; 7,257,612 B2; 7,275,211 B2; 7,281,047 B2; 7,293,008 B2; 7,296,040 B2; 7,318,058 B2; 7,325,003 B2; 7,333,995 B2. 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. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Other company, product, or service names may be trademarks or service marks of others. 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. U.S. Government Restricted Rights. The software and accompanying materials are provided with Restricted Rights. Use, duplication, or disclosure by the Government is subject to the restrictions in subparagraph (C)(1)(ii) of the Rights in Technical Data and Computer clause at DFARS 252.227-7013, or subparagraphs (C)(1) and (2) of the Commercial Computer Software - Restricted Rights at 48CFR52.227 as applicable. The Contractor is Cognos Corporation, 15 Wayside Road, Burlington, MA 01803. 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.

Table of Contents
Introduction

27 31

Chapter 1: Whats New?

New Features in Version 8.4 31 Additional Language Support 31 Support for IBM Metadata Workbench as a Lineage Solution 32 Access to IBM WebSphere Business Glossary 32 Managing Comments Using Cognos Viewer 32 Adding Application Context to Dynamic SQL 32 Support for New Data Sources 32 Support for New Portal Versions 32 Hiding Entries 32 Updating Published PowerCubes 33 Object Capabilities 33 Schedule Credentials 33 Save History Details for Job Steps 33 Viewing Lineage Information 33 Enhanced Drill-through Capabilities 33 Metric Studio Content in Portal Pages 34 Changed Features in Version 8.4 34 Composite Information Server is Replaced By IBM Cognos 8 Virtual View Manager 34 IBM Cognos 8 Portal Services 34 Deprecated Features in Version 8.4 34 IBM Cognos 8 PowerCube Connection Utility and cubeswap 34 New Features in Version 8.3 35 Improved User Interface for Administrators 35 Access to More Documentation 35 More Granular Administrative Capabilities 35 Access to System Statistics 35 Snapshot of System Health 35 Managing Queues 36 Reducing Deployment Details 36 Setting Priority on Schedules 36 Better Control of Interactive Features in Reports 36 New Sample Audit Reports 36 Publishing and Managing Packages in Non-root Folders 36 Enabling Report Studio Authoring Modes 37 Server Administration 37 Transformer Integrated into IBM Cognos 8 37 My Activities and Schedules 37 My Watch Items 38 Report Alerts 38 Watch Rules 38 Drilling Through on Multiple Values 38

Administration and Security Guide 3

Table of Contents Go Directly to Target Report When Only One Target Report Exists 39 Support for Microsoft Excel 2007 39 Saving Report Outputs to a File System 39 Resubmitting Failed Jobs and Reports 40 Resubmitting Failed Agent Tasks 40 Default Actions for Agent Items 40 Tabbed Portal Pages 40 Global Filters and Enhanced Portal Interactivity 40 Metric Studio Content in Portal Pages 41 Support for Microsoft SharePoint Portal 2003 and 2007 41 Changed Features in Version 8.3 41 Updated IBM Cognos Connection Look 41 More Information in the Go To Page 41 Cognos Watchlist Portlet 42 Replaced Capability 42 Part 1: IBM Cognos 8 Administration Chapter 2: IBM Cognos 8 Administration

43

IBM Cognos Administration 43 Automating Tasks 44 Setting up a Multilingual Reporting Environment 46 Configuring Your Database For Multilingual Reporting 47 Installing Fonts 47 IBM Cognos 8 Default Font 48 Report Studio Fonts 48 Set Up Printers 48 Configuring Web Browsers 50 Allow User Access to Series 7 Reports from IBM Cognos Connection 52 Restricting Access to IBM Cognos 8 53 Chapter 3: Building IBM Cognos 8 Applications Chapter 4: Samples

55

57

The Great Outdoors Company Samples 57 The Great Outdoors Group of Companies 58 Employees 60 Sales and Marketing 60 Great Outdoors Database, Models, and Packages 61 Setting Up the Samples 63 Restore Backup Files for the Samples Databases 64 Create Data Source Connections to the Samples Databases 67 Set Up Microsoft Analysis Services Cube Samples 68 Set Up the Essbase Cube Sample 69 Create Data Source Connections to OLAP Data Sources 70 Set Up the Metric Studio Sample 73 Import the Samples 74 Sample Database Models 76 Example - Running the Sample ELM Returns Agent Against Changed Data 76 Remove the Samples Databases from IBM Cognos 8 78

Table of Contents Chapter 5: Setting up Logging

79

Log Messages 80 Logging Levels 80 Set Logging Levels 82 Audit Reports 82 Setting Up Audit Reporting 83 Sample Audit Model and Audit Reports 83 View Full Details for Secure Error Messages 88 Disable the Creation of Core Dump Files 89 Part 2: System Administration Chapter 6: System Performance Metrics

91

How Metric Data is Gathered 91 System Metrics 92 Panes on the Status System Page 99 Assess System Performance 100 View Attributes for Metric Scores 101 Set Metric Threshold Values 101 Reset Metrics 103 Reset Metrics for the System 103 Chapter 7: Server Administration

105

Dispatchers and Services 105 Stop and Start Dispatchers and Services 108 Activate a Content Manager Service 110 Remove Dispatchers from the Environment 111 Group Dispatchers in Configuration Folders 112 Specify Advanced Dispatcher Routing 113 Specify Gateway Mappings for Series 7 PowerPlay Data 116 Rename Dispatchers 116 Test Dispatchers 117 Administering Failover for Multiple Dispatchers 118 Securing Dispatchers 120 Content Manager Computers 121 Managing Database Connection Pool Settings for Content Manager 121 Sorting Entries for Non-English Locales 122 Managing Content Manager Synchronization 123 Control Browsing of External Namespaces 123 Set Advanced Content Manager Parameters 123 Override the (Default) Locale Processing in the Prompt Cache 124 Maintain the Content Store 125 Migrating PowerPlay Reports Published to IBM Cognos 8 127 Tune Server Performance 127 Set Server Group Names for Advanced Dispatcher Routing 128 Balance Requests Among Dispatchers 129 Use Cluster Compatible Mode for Dispatchers 129 Set Usage Peak Periods 130 Set the Maximum Number of Processes and Connections 131 Specify Queue Time Limits 133 Administration and Security Guide 5

Table of Contents PDF File Settings 134 Set Maximum Execution Time 137 Specify How Long to Keep Watch List Report Output 138 Limit Hotspots That are Generated in an Analysis Studio or Report Studio Chart 139 Set Compression for Email Attachments 140 Set the Report Size Limit for the Report Data Service 141 Set Parameters for Concurrent Query Execution 141 Set Query Prioritization 143 Disable Session Caching 145 Add Application Context to Dynamic SQL 147 Saved Report Output 148 Set File Location to Save a Copy of Report Output Outside of IBM Cognos 8 149 Set File Location to Save Copy of Report Output in IBM Cognos 8 149 Configure the Lineage Solution 151 Configure the IBM WebSphere Business Glossary URI 152 Enable Job, SMTP, and Task Queue Metrics 153 Part 3: Data Management Chapter 8: Data Sources and Connections

155

DB2 156 IBM Cognos Cubes 157 IBM Cognos Finance 157 IBM Cognos Now! Cube 158 IBM Cognos Planning - Contributor 158 IBM Cognos Planning - Series 7 159 IBM Cognos PowerCubes 159 IBM DB2 OLAP and Hyperion Essbase Data Source 164 Configure Scenario Dimensions 165 Specify Balanced Hierarchies 165 Specify Measure Formats 166 Specify the Attributes of a Dimension 167 IBM Infosphere Warehouse Cubing Services 168 Informix Data Sources 169 Microsoft Analysis Services Data Sources 169 Microsoft SQL Server Data Sources 171 ODBC Data Sources 173 Oracle Data Sources 176 SAP Business Information Warehouse (SAP BW) Data Sources 176 TM1 Data Sources 178 XML Data Sources 179 Create a Data Source 180 Add or Modify a Data Source Connection 183 Manage Data Source Connections 184 Create or Modify a Data Source Signon 186 Specifying Isolation Levels 188 Using Database Commands for Oracle, DB2, and Microsoft SQL Server 190 Example - Open Connection Command Block 191 Example - Close Connection Command Block 191 Add Command Blocks While Creating a Data Source 191 6

Table of Contents Add or Modify Command Blocks for a Connection 191 Command Block Examples 192 Securing Data Sources 195 Chapter 9: Back Up Data

197 199

Chapter 10: Data Movement Entries

Run a Data Movement Entry 199 Change Default Data Movement Entry Properties 200 Part 4: Security Administration Chapter 11: Security Model

201

Authentication Providers 201 Deleting or Restoring Unconfigured Namespaces 202 Authorization 203 Cognos Namespace 203 IBM Cognos Application Firewall 204 Data Validation and Protection 204 Logging and Monitoring 205 Chapter 12: Users, Groups, and Roles

207

Users 207 User Locales 208 Groups and Roles 208 Create an Cognos Group or Role 210 Add or Remove Members of an Cognos Group or Role 211 Chapter 13: Access Permissions

213

Set Access Permissions for an Entry 216 Trusted Credentials 218 Create Trusted Credentials 218 Chapter 14: Secured Functions and Features

221

Set Access to a Secured Function or Feature 225 Set Access to the Report Studio User Interface Profiles 227 Chapter 15: Object Capabilities

229

Set Up Object Capabilities for a Package 231 Chapter 16: Initial Security

233

Built-in Entries 233 Predefined Entries 234 Specify Security Settings After Installation 236 Securing the Content Store 237 Part 5: Content Administration in IBM Cognos Connection Chapter 17: IBM Cognos Connection Log On 239 Log Off 239 Create a Shortcut 240 Create a URL 241 Administration and Security Guide 7

239

Table of Contents Bookmark an Entry 242 Models and Packages 243 Entry Properties 243 General Properties 243 Permissions 246 Report, Query, Analysis, and PowerPlay Report Properties 247 Job Properties 248 Agent Properties 249 Page Properties 249 Rule Properties 250 Organizing Entries 251 Copy an Entry 251 Move an Entry 252 Rename an Entry 253 Disable an Entry 253 Hide an Entry 254 Select a Link for an Entry 256 Delete an Entry 257 Specify the Order of Entries 257 Create a Folder 258 Specify an Alternative Icon for an Entry 259 Search for an Entry 259 Personalize the Portal 260 My Watch Items 263 View Watch Items 264 Remove Yourself from an Alert List 264 Edit a Watch Rule 264 Chapter 18: Pages and Dashboards

267

Create a Page 269 Edit a Page 270 Share a Page 270 Modify a Portlet 271 Enable Communication Between Cognos Portlets 271 Portal Tabs 273 Add a Tab 273 Delete a Tab 274 Reorder the Tabs 275 Change Your Home Page 275 Create a Dashboard with Multiple Tabs 275 Adding Interactivity to Pages and Dashboards 278 Defining Global Filters 278 Enable Sharing of Drill-up and Drill-down Actions 283 Enable Sharing of Drill-through Actions 283 Chapter 19: Activities Management

285

Manage Current Activities 285 Manage Past Activities 287 Manage Upcoming Activities for a Specific Day 289 Manage Scheduled Activities 291 8

Table of Contents Manage Entry Run Priority 293 View the Run History for Entries 294 Specify How Long to Keep Run Histories 296 Rerun a Failed Entry Task 297 Chapter 20: Schedule Management

299

Schedule an Entry 300 Example - Schedule an Entry on the Last Day of the Month 301 Use Jobs to Schedule Multiple Entries 301 Trigger-based Entry Scheduling 304 Setting Up Trigger-based Scheduling 304 Schedule an Entry Based on an Occurrence 305 Chapter 21: Deployment

307

Deployment Specifications 307 Deployment Archives 308 Deployment Planning 308 Security and Deployment 308 Deploying the Entire Content Store 309 Deploying Selected Public Folders and Directory Content 311 Deployment Rules When Importing 315 Rules For Deploying the Entire Content Store 316 Rules For Partial Deployment 320 Deploying IBM Cognos 8 Entries 324 Create an Export Deployment Specification 325 Move the Deployment Archive 328 Import to a Target Environment 328 Include Configuration Objects in Import of Entire Content Store 331 Testing Deployed Applications 332 Upgrade Report Specifications 332 Chapter 22: Administering Packages

335

Data Trees 335 Configure or Reconfigure a Package 336 Set Permissions for Package Configuration 336 Remove a Package Configuration 337 Chapter 23: Managing User Profiles

339

Edit the Default User Profile 339 Delete a User Profile 340 Copy a User Profile 340 View or Change a User Profile 341 Chapter 24: Administering Microsoft Office Documents

343

Deploying IBM Cognos 8 Go! Office Client 343 Set Macro Security Level for Microsoft Office XP 344 Install the CA Certificate for the HTTPS Interface to Series 7 PowerPlay 344 Download a Microsoft Office Document 344

Administration and Security Guide 9

Table of Contents Part 6: Report, Agent, and Metric Administration Chapter 25: Reports and Cubes

347

View, Run, or Open a Report 348 Set Default Report Options 348 Set Report Options for the Current Run 350 Set Advanced Report Options for the Current Run 351 Create a Report 353 Creating a Query Studio Report Without Using Actual Data 354 Create a Report View 354 View Lineage Information for a Data Item 355 Access the IBM WebSphere Business Glossary 356 Edit a Report 356 Report Formats 357 HTML Formats 358 XML Format 358 PDF Format 358 Excel Formats 359 CSV Format 360 Report Languages 360 Add Multilingual Properties 361 Specify the Default Language for a Report 362 Specify the Default Prompt Values for a Report 362 Save Report Output 363 View Report Output Versions 364 Specify How Long to Keep Report Output 365 Enable an Alert List for a Report 365 Add Yourself to or Remove Yourself from the Alert List for a Report 366 Watch Rules in Saved Reports 366 Enable Watch Rules for a Report 367 Create a Watch Rule for a Report 367 Modify or Delete a Watch Rule in Cognos Viewer 368 Comments in Saved Reports 369 Enable Comments in Saved Output Versions 369 Add Comments to a Report Version in Cognos Viewer 370 View, Modify or Delete Comments in Cognos Viewer 370 Disable Selection-based Interactivity 371 Exclude Blank Pages in PDF Reports 372 Distributing Reports 372 Saving a Report 373 Sending a Report by Email 373 Sending a Report to your Mobile Device 373 Printing a Report 373 Distributing a Report by Bursting 374 Create Distribution Lists and Contacts 374 Drilling to View Related Data 375 Drill Up or Drill Down 376 Drill Through to Another Target 376 Drill Through to Another Target Passing Multiple Values 377

10

Table of Contents Data Sources With Named Sets May Produce Unpredictable Results 378 Series 7 Reports in IBM Cognos Connection 378 Series 7 PowerPlay Reports and Cubes 379 Single Signon 380 Run or Open a Series 7 PowerPlay Report 380 Change the Defaults for a Series 7 PowerPlay Report 381 Open a Series 7 Cube 382 Multilingual Properties for Series 7 Reports and Cubes 382 Chapter 26: Agents

383

Run an Agent 383 Change Default Agent Properties 384 Create an Agent View 385 Open or Create an Agent from IBM Cognos Connection 385 Enable an Alert List for an Agent 386 Add Yourself to or Remove Yourself from an Alert List for an Agent 386 Remove All Users from the Alert List for an Agent 387 Receive News Item Headlines 387 View the Most Recent Event List 387 Chapter 27: Metric Studio Metrics

391

Create a Metric Package 391 Change the Default Action for Packages 392 Run a Metric Task 392 Delete a Metric Task 393 Modify a Metric Task 393 Metric Import Tasks 394 Create New Metric Import Task 394 Edit Metric Import Task Properties 395 Metric Maintenance Tasks 395 New Metric Maintenance 396 Edit Metric Maintenance Properties 396 Metric Export Tasks 397 Change Metric Export Properties 399 Chapter 28: Drill-through Access

401

Understanding Drill-through Concepts 402 Drill-through Paths 402 Selection Contexts 402 Drilling Through to Different Report Formats 403 Drilling Through Between Packages 403 Bookmark References 404 Members and Values 404 Member Unique Names 405 Conformed Dimensions 406 Business Keys 407 Scope 407 Mapped Parameters 407 Drilling Through on Dates Between PowerCubes and Relational Packages 408 Set Up Drill-through Access in Packages 408

Administration and Security Guide 11

Table of Contents Set Up Parameters for a Drill-Through Report 411 Set Up Parameters for a Drill-through Target in Analysis Studio 412 Example - Drill Through Between OLAP Reports in the Same Package 413 Example - Drill Through from an OLAP Report to a DMR Report 416 Debugging a Drill-through Definition 419 Access the Drill-through Assistant 420 Example - Debugging a Drill-through Definition 421 Set Up Drill-through Access in a Report 422 Example - Drill Through to a Hidden Report from a Report Studio Report 423 Specify the Drill-through Text 425 Setting Up Drill-through Access from IBM Cognos Visualizer 426 Setting Up Drill-through Access from PowerPlay Web 426 Create and Test the Target for a Series 7 Report 426 Part 7: Portal Services Administration Chapter 29: Managing Portlets and Styles

429

Portlets 429 Cognos Portlets 429 Other Portlets 432 Import Portlets 432 Control Access to Portlets 433 Configure the Portlet Cache 434 Modify a Portlet 435 Display the HTML Code From the Source RSS Feed in RSS Viewer and Cognos Navigator 436 Styles 437 Add a New Style 438 Control Access to Styles 439 Modify a Style 440 Chapter 30: Deploying Cognos Portlets to Other Portals

441

Deploying Cognos Portlets to WebSphere Portal 5.0, 5.1, 6.0, and 6.1 441 Install the Portlet Applications File 442 Configure the Portlet Applications 443 Configure the Portlet Cache 444 Customize the Content of Cognos Portlets 444 Deploying Cognos Portlets to SAP Enterprise Portal 6.0, 6.4, and 7.0 445 Install the IBM Cognos Business Package 446 Edit Properties for the iViews 447 Set the Default iView Content and Appearance for All Users 448 Deploying Cognos Portlets to ALUI 6.1 and 6.5 Portal 449 Start the Remote Server 449 Import the Cognos Portlet Package File 452 Connect to the Remote Server 453 Customize the Content of Cognos Portlets 454 Deploying Cognos Portlets to Microsoft SharePoint Portal Server 2003 and 2007 454 Set up Virtual Directories and Change the Gateway URIs 455 Copy the Cognos Web Parts Resources to the IIS HTTP Root Directory 456 Set Up the IBM Cognos Security Trust File 457

12

Table of Contents Modify the .NET Framework web.config File 458 Edit the Cognos Web Parts Catalog Files 461 Restart IIS 461 Add Cognos Web Parts to a SharePoint Page 462 Customize the Content of Cognos Web Parts 463 Migrating Cognos Portlets from IBM Cognos ReportNet 1.1 to IBM Cognos 8 464 Change the Root Name of File Paths in Cognos Portlets 464 Disable the Transfer of the IBM Cognos 8 Passport ID as a URL Parameter 465 Set Portal Services Protocol Scheme 467 Configuring Security for Portal Services 467 Disable Anonymous Access to IBM Cognos 8 Components 468 Enable Single Signon Using Shared Secret 468 Enable Single Signon for SAP EP with the SAP Logon Ticket 474 Enable Single Signon for SAP EP with User Mapping 474 Enable Secure Communication Between SAP EP and IBM Cognos 8 Components 475 Enable Single Signon for WebSphere Portal Using the Application Server 476 Enable Single Signon for BEA ALUI Portal Using Basic Authentication 476 Enable Single Signon for BEA ALUI Portal Using SiteMinder 477 Part 8: Customization Chapter 31: Customizing the Appearance of IBM Cognos 8

479

Making Global Changes to all Components 479 Customizing Styles 479 Rebranding the IBM Cognos 8 Interface 481 Changing IBM Cognos 8 Fonts 482 Changing the Global IBM Cognos 8 Style Sheet 482 Migrating Changes to Future Releases 483 Modifying the Appearance of IBM Cognos Connection 484 Example - Customize the Default Welcome Page 484 Example - Change the Branding Details in the IBM Cognos Connection Main Header 484 Example - Change the Background Color in the IBM Cognos Connection Main Header 485 Example - Change the Portal Graphics 486 Example - Change the Default Fonts for Page Titles and Instructions 486 Modifying the Report Studio Style Sheets 486 Example - Change the Fonts Used in Report Studio 487 Example - Change the Colors Used in Report Studio Menus 487 Example - Change the Report Studio Graphics 488 Modifying the Query Studio Style Sheets 488 Example - Change the Colors Used in Query Studio Menus 489 Example - Change the Query Studio Graphics 489 Customize the Query Studio Toolbar and Menus 490 Modifying the Appearance of Cognos Viewer 492 Modifying the Cognos Viewer Style Sheets 493 Example - Change the Language of the Cognos Viewer User Interface 493 Modifying the Prompt Page Style Sheets 494 Adding Custom Report Templates for Report Studio 495 Create a Report Specification for a Custom Report Template 495 Add a Custom Report Template to the templates.xml File 497 Provide an Icon for the Custom Report Template 497 Administration and Security Guide 13

Table of Contents Add the Custom Template Information to the Resources.xml File 497 Chapter 32: Customizing the Functionality of IBM Cognos 8

501

Upgrade the ReportNet system.xml Files to IBM Cognos 8 501 Customizing IBM Cognos Connection 502 Add or Hide User Interface Elements Based on Groups and Roles 503 Hide and Disable the New URL Button 508 Limit the Number of Entries That Users Can Cut, Copy, and Paste 509 Customizing Object Actions 509 Restrict Content Browsing 513 Implementing a Custom Welcome Page 514 Customize Report Output Formats in IBM Cognos Connection and Cognos Viewer 517 Configure the Document Lookup Table 519 Start Query Studio in Preview Mode 520 Customizing Data Formats for Query Studio 520 Modify the cogformat.xml File 521 Change the Order of Data Formats 521 Change the Text Strings 522 Remove Data Formats 523 Add a Data Format to a Locale 524 Add Data Formats for a New Locale 525 Change the Default Query Studio Template 525 Modify Properties for the CSV Output Format 526 CSV Properties and Values 527 Supported Encoding Values 528 Modify Properties for the Batch Report Service and Report Service 529 Batch Report Service and Report Service Properties and Values 529 Customize Error-Handling on the SMTP Mail Server 530 Disable Report Attachments in Email Messages 534 Show Attachments in IBM Lotus Notes 534 Disable Support for Trigger-based Scheduling 535 Set Up a Trigger Occurrence on a Server 535 Hide History Summary Counts 537 Change the Suppression Functionality in Analysis Studio 538 Part 9: Troubleshooting Chapter 33: Troubleshooting Resources

539

Error Messages 539 Log Files 539 Core Dump Files 542 Metric Dump File 543 Windows Event Viewer 544 Samples 544 Example - Testing Report Studio 545 View the Report Definition in Query Studio 545 Call IBM Cognos Resource Center 545 IBM Cognos Diagnostic Tools 546

14

Table of Contents Chapter 34: Problems Using Documentation

547

Problems When Printing a PDF Manual 547 Unable to Launch a Web Browser When Accessing Help 547 Text Does Not Appear Properly in Quick Tours 548 Chapter 35: Installation and Configuration Problems

549

Problems Starting IBM Cognos 8 549 CFG-ERR-0106 Error When Starting the IBM Cognos 8 Service in IBM Cognos Configuration 549 Cryptographic Error When Starting IBM Cognos 8 551 Unable to Start the IBM Cognos 8 Service Because the Port is Used by Another Process 551 IBM Cognos 8 Service Does Not Start or Fails After Starting 552 IBM Cognos 8 Server Fails to Start and Gives No Error Message 552 IBM Cognos BI Server Not Available When Starting IBM Cognos 8 553 Cannot Log On to a Namespace When Using IBM Cognos Connection 556 IBM Cognos 8 Services Fail to Restart After a Network Outage 557 No Warning That Installing a Later Version of IBM Cognos 8 Will Automatically Update the Earlier Version of the Content Store 557 Download of Resource Fails 557 DB2 Returns SQL1224N Error When Connecting from AIX 558 Content Manager Error When Starting IBM Cognos 8 558 DPR-ERR-2014 Error Appears in Log File on Content Manager Computer 558 Non-ASCII Characters in Installation Directory Cause Run-time Errors 558 Cannot Open an MS Cube or PowerCube 559 Cannot Open an OLAP Data Source 560 The Page Cannot Be Found When Starting IBM Cognos 8 in Windows 2003 560 The Page Is Not Shown When Opening a Portal After Installing IBM Cognos 8 560 DPR-ERR-2058 Error Appears in Web Browser When Starting IBM Cognos 8 560 EBA-090034 Error When Starting WebLogic 8 562 Report Studio Does Not Start 563 DPR-ERR-2022 Error Appears in Web Browser When Starting IBM Cognos 8 563 Unable to Download the cognos.xts File 563 Application Server Startup Script Fails 564 Issues with IBM WebSphere 6.0 on AIX 5.3 564 IBM Cognos 8 Running under WebLogic Application Server on AIX Fails 564 Deploying IBM Cognos 8 to an Oracle Application Server or IBM WebSphere Application Server Fails 564 Microsoft Excel 2000 Multipage Report Type Does Not Work 565 Unable to Deserialize Context Attribute Error When Deploying the p2pd.war File to WebLogic 565 Error Appears After Upgrading IBM Cognos 8 on a WebLogic Application Server 566 Chinese, Japanese, or Korean Characters Are Different After Upgrade 566 Accented or Double-Byte Characters May Not Display Correctly When Installing IBM Cognos 8 on Linux 567 RSV-SRV-0066 A soap fault has been returned or RQP-DEF-0114 The user cancelled the request Errors Appear in High User Load Environments 567 Problems Configuring IBM Cognos 8 567 Configuration Tool cogconfig.sh Return Values Are Not Compliant with Conventional UNIX Return Values 567

Administration and Security Guide 15

Table of Contents Run Database Cleanup Scripts 568 Error Trying to Encrypt Information When Saving Your Configuration 570 Problems Generating Cryptographic Keys in IBM Cognos Configuration 570 CAM-CRP-1315 Error When Saving Configuration 571 Manually Changing the Installation Directory Name Affects Installations Running Under an Application Server 571 Configuration Data is Locked by Another Instance of IBM Cognos Configuration 572 Unable to Exit a Tab Sequence When Using Keyboard-only Navigation in IBM Cognos Configuration 572 Unable to Save Your Configuration 572 Java Error When Starting IBM Cognos Configuration 573 Cryptographic Error When Starting IBM Cognos Configuration 573 Current Configuration Settings Are Not Applied to Your Computer 574 CM-CFG-029 Error When Trying to Save a Configuration That Specifies a SQL Server Content Store 574 DPR-ERR-2079 When Content Manager Configured For Failover 574 Importing a Large Content Store in Solaris using JRE 1.5 Fails 575 Users are Prompted for Active Directory Credentials 575 Font on UNIX Not Found When Starting IBM Cognos Configuration 575 Unable to Load Essbase/DB2 OLAP Library in Framework Manager 576 Group Membership is Missing From Active Directory Namespace 576 Deploying IBM Cognos 8 to an Oracle Application Server or IBM WebSphere Application Server 577 Errors Displayed Deploying to Oracle 10G Application Server 578 Page Cannot be Found Error Running Reports using IBM Cognos 8 Go! Office 578 Error Initializing Oracle Content Store After Upgrade from ReportNet 578 CGI Timeout Error While Connected to IBM Cognos 8 Components Through a Web Browser 579 Servlet Class Fails to Load in WebLogic 579 Desktop Icons or IBM Cognos Configuration Window Flicker on Windows 580 Chapter 36: Security Problems

581

Problems Setting Up Security 581 Access to Entries is Denied During Deployment 581 Prompt to Change Passwords When Logging On to an Active Directory Security Source 581 Unable to Log On 581 Certificate Authority Error When Logging On to IBM Cognos Connection 582 HTTPS DRP-ERR-2068 Error In Log File When No Error is Reported During a Switch to HTTPS 582 Entries Do Not Appear in IBM Cognos Connection for a Member of a Newly Created Group 582 Problems Logging On to Cognos Portlets 583 Existing Passwords May not Work in an SAP Namespace 584 Users Are Repeatedly Prompted for Credentials When Trying to Log On to an SAP Namespace 585 Problems Using Authentication Providers 585 CAM-AAA-0096 Unable to Authenticate User When Using an IBM Cognos Series 7 Namespace 585 Expired Password Error Appears When Using Active Directory Server 586

16

Table of Contents Single Signon Is Not Working When Using Active Directory Server 586 Unable to Authenticate User for Cognos Portlets 587 Unable to Identify SAP Permissions Required 587 Unable to Access IBM Cognos Administration When an NTLM Namespace Is Used and Single Signon Is Enabled 587 Chapter 37: Report and Server Administration Problems

589

Database Connection Problems 589 Unable to Select ODBC as the Type of Data Source Connection 589 Cannot Connect to an SQL Server Database Using an OLE DB Connection 590 Intermittent Problems Connecting to a SQL Server Database 590 Cannot Access IBM Cognos Series 7 Reports from IBM Cognos Connection 590 Series 7 Namespaces Do Not Initialize When Services are Started 591 Content Manager Connection Problem in Oracle (Error CM-CFG-5036) 591 Cannot Connect to an OLAP Data Source 592 Error When Creating a Data Source Connection to a PowerCube 592 Not Yet Optimized IBM Cognos PowerCubes May Open Slowly in IBM Cognos 8 592 Other Administration Problems 593 Restarting Servers After Solving Content Store Problems 593 An Update or Delete Request Fails 594 BI Bus Server Processes Remain in Memory After a Shutdown 594 Higher Logging Levels Negatively Affect Performance 594 Problems Accessing Cognos Portlets 595 Unable to Edit Object Properties in ALUI 6.1 and 6.5 Portal 596 Only the Administrator Can See Cognos Portlets 597 Locale Mismatch in Cognos Navigator Portlet 597 Properties Pages in Cognos Portlets Are not Displayed Properly 598 Problems Displaying HTML Reports in a Multi-tab Dashboard 598 Unable to Identify SAP BW Version and Corrections 599 SBW-ERR-0020 Error When Running Reports Based on SAP BW Data Sources 599 Links to Referenced Content Objects are Broken Following Deployment 599 Table or View Does not Exist for Sample Database 600 Chapter 38: Problems When Using Framework Manager

601

Measures Not Added After Initial Import in an Upgraded Model 601 Unable to View the Result Set of a Stored Procedure 601 Unable to Compare Two CLOBs in Oracle 601 An Out of Memory Error with ERWin Imported Metadata 602 Calculation Fails Testing 602 Framework Manager Cannot Access the Gateway URI 602 Object Names Appear in the Wrong Language 603 Full Outer Joins in Oracle Return Incorrect Results 603 Error When Testing Query Subjects in a Model Imported from Teradata 603 Error for Type-In SQL Query Subject 603 Function Name Not Recognized 604 QE-DEF-0259 Error 604 QE-DEF-0260 Parsing Error 605 Externalized Key Figures Dimension Retains Old Prompt Value 605 Older IBM Cognos 8 Models Display Level Object Security 605

Administration and Security Guide 17

Table of Contents Exporting a Framework Manager Model to a CWM File Fails With Error MILOG.TXT was not found 605 Difference in SQL for Inner Joins After Upgrading to IBM Cognos 8.3 606 Publishing a Large Package Results in a CCLOutOfMemory Error 606 Full Outer Joins Not Sent to Oracle 9i and 10GR1 606 Review Governors When Upgrading Models 606 File Creation from Framework Manager fails with Error QE-DEF-0178 607 Chapter 39: Problems When Using Transformer

609

Known Issues When Modeling in IBM Cognos Transformer 609 BAPI Error Occurs After the Prompt Specification File Edited Manually 609 Unable to Access an IQD Data Source using a Sybase Database Connection 609 Importing Time Dimensions from IBM Cognos 8 Packages Not Supported 610 Data in Multiple Languages Does Not Display Properly 610 Unable to Use an IQD Created in Framework Manager That Contains an Oracle Stored Procedure 610 Preventing Errors When Model Calculations Use Double Quotation Marks 611 Framework Manager and Transformer may Display Different Locale Session Parameters for Some Languages 611 Regular Columns cannot be Converted to Calculated Columns and Vice Versa 611 Transformer Takes a Long Time to Retrieve Data from an SAP-based Data Source 612 Categories Missing When Creating a Transformer Model Based on an SAP Query Containing a Manually Created SAP Structure 612 Error Occurs When Creating a PowerCube Containing an SAP Unbalanced Hierarchy 612 Rebuilding a PowerCube Soon After Publishing Produces a TR0787 Error 612 Known Issues Using Cubes in the IBM Cognos 8 Studios 613 Not Yet Optimized IBM Cognos PowerCubes May Open Slowly in IBM Cognos 8 613 Analysis Studio Shows the Wrong Currency Symbol 614 Changes to Decimals in Currency Formats 615 Ragged or Unbalanced Hierarchies Result in Unexpected Behavior 615 Error Opening Saved Reports After PowerCube Refresh 616 Unable to Open Sample Model, Great Outdoors Sales.mdl, and Generate Cubes 616 Data Records that Support External Rollup Measure Data are Not Always Created 617 Chapter 40: Problems Authoring Reports

619

Problems Creating Reports 619 Chart Labels Overwrite One Another 619 Chart Shows Only Every Second Label 619 Chart Gradient Backgrounds Appear Gray 619 Division by Zero Operation Appears Differently in Lists and Crosstabs 620 Application Error Appears When Upgrading a Report 620 Nested List Report Containing a Data Item That is Grouped More Than Once Does Not Run After Upgrade 620 Background Color in Template Does not Appear 621 Subtotals in Grouped Lists 621 Metadata Change in Essbase Not Reflected in Reports and in the Studios 621 Relationships Not Maintained in a Report With Overlapping Set Levels 621 Creating Sections on Reports That Access SAP BW Data Sources 622 Error Characters (--) Appear in Reports 622 Descendants Function Unreliable with Sets 623 18

Table of Contents Columns, Rows, or Data Disappear With SSAS 2005 Cubes 623 Unexpected Cell Formatting in Reports 624 Report Differences Between TM1 Executive Viewer and IBM Cognos 8 with TM1 Data Sources 624 Order of Metadata Tree Differs for TM1 Data Sources 624 Problems Calculating Data 625 Count Summaries in Query Calculations Include Nulls with SAP BW Data Sources 625 Unexpected Summary Values in Nested Sets 625 Incorrect Results with IBM Cognos PowerCubes and Time Measures 626 Problems Filtering Data 626 HRESULT= DB_E_CANTCONVERTVALUE Error When Filtering on a _make_timestamp Column 626 Problems Distributing Reports 627 A Report Link in an Email Notification Does Not Work 627 Report Contains No Data 627 Hyperlinks in Email Messages Are Stripped Out When the Agent is Saved 627 CNC-ASV-0001 The Following Agent Service General Error Occurred: java.lang.StackOverflowError 628 Cannot Call the SDK from Event Studio 628 Saving a Report Takes a Long Time 628 Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses

629

Problems Running Reports and Analyses 629 Summaries in Report Do not Correspond to the Visible Members 629 Unexpected Results for Analysis Studio Reports Using Suppression and Nested Rows 630 Unexpected Results May Occur When Using Items from the Same Hierarchy on Multiple Crosstab Edges 631 Defining Languages for OLAP Data Sources 631 Crosstab Shows Percentage But Chart Shows Values 631 Cube Refresh in Data Analysis Studio Uses UTC/GMT Time 631 Cannot Drill when Caption Represents a Blank or a Zero-length String 632 DPR-ERR-2082 The Complete Error Has Been Logged by CAF With SecureErrorID 632 Query Studio Does Not Generate a SELECT DISTINCT statement if a Column is Aliased Without Using the Actual Column Name 632 Cannot Find the Database in the Content Store (Error QE-DEF-0288) 632 Parse Errors When Opening or Running an Upgraded Report 633 Overflow Error Occurs When a Value in a Crosstab Is More Than 19 Characters 633 IBM Cognos 8 Runs Out of TEMP Space 633 A Report Does Not Run as Expected 633 Performance Issues when Showing Multiple Attributes Using Dimensionally Modeled Relational Data Sources 634 Analysis Studio Shows the Wrong Currency Symbol 634 Error Occurs in Japanese Internet Explorer 7 When Running an Excel Report in Analysis Studio 635 The ORA-00907 Error Appears When Running a Report 635 Drilling Through to IBM Cognos 8 from an IBM Cognos Series 7 Product Results in Firewall Error 635 Scheduled Reports Fail 636 The Table or View Was Not Found in the Dictionary 636

Administration and Security Guide 19

Table of Contents Mixed Languages Are Displayed in IBM Cognos Connection When Using Samples 636 Unable to Select Multiple Report Formats When Running a Report 637 A Report Does Not Run as Scheduled 637 A Report or Analysis Does Not Run Because of Missing Items 637 Cannot View Burst Report 638 PCA-ERR-0057 Recursive Evaluation Error 639 Arithmetic Overflow Error When Running a Report in PDF Format 639 Performance Problems When Running Reports 639 CGI Timeout Error While Transferring Data to IBM Cognos 8 Components 639 Slow Server Performance 640 The BAP-ERR-0002 BAPI Error 641 The Out of Memory Error Appears in HP-UX 641 A Query Is Slow When Filtering Non-ASCII Text 641 Query Studio Output Takes a Long Time to Run 641 Problems Viewing Reports 641 A Report Upgraded from ReportNet Does Not Retain its Original Look 641 Drill-through Links Not Active in the Safari Browser 642 A Running Total in Grouped Reports Gives Unexpected Results 642 The Page Cannot Be Found Error Appears When Viewing Report Outputs from Email Links 642 Non-English Characters Appear as Placeholders 642 Cannot Drill Between PowerCubes Because MUNs Do Not Match 643 Unexpected or Empty Results When Drilling Through 643 Cannot Drill From a Relational Source to a Cube 644 Charts Do Not Appear in HTML reports 644 Portal Problems 645 Cannot Connect to a SQL Server Database Using an ODBC Driver 645 The My Folders Tab Does Not Appear After Logging On to IBM Cognos Connection 646 Icon Graphics Are Not Working in Portlets 646 Styles Used in the Previous Installation Still Appear 647 Unable to Click Links 647 Missing Images in a PDF Report 648 Charts in PDF Output Show Unexpected Results 648 Problems Printing Reports 648 Unable to Print PDF Reports 648 A Printed HTML Report is Unsatisfactory 649 Chapter 42: Problems When Using Map Manager Problems Importing Files 651 Error Importing Translated Text File 651 Chapter 43: Problems With Metrics

651

653

Metric Studio Log Files 653 Metric Studio Support Bundle 654 Known Issues When Using Metric Studio 654 Metric Studio Reports Fail Because of an Oracle Internal Error 654 Metric Studio Errors Occur When Loading Data into an Oracle Database 655 Oracle Errors Occur When Using the cmm_uninstall Script 655 Error When Attempting to Run Metric Studio on SQL Server 2005 655 Data from a Relational Database Source or a Flat File Data Source Does Not Appear 656 20

Table of Contents A Metric Maintenance Task Fails to Run 657 You Do Not Have Permission to Access This Metric Package. Contact Your System Administrator. 657 Failed to Check the Metrics Store Install Status Error When Using DB2 8.2.3 657 Errors Occur When Importing Tab-delimited Files into a DB2 Metric Store 657 Required User Permissions for the Metric Store Database (MS SQL Server) 658 Error When Viewing a History Chart or Diagram on a DB2 Server with the 8.2 JDBC Driver 658 Oracle 9.2 Package Initialization Error if NLS_LANG Environment Variable is Not Set Appropriately Before Starting Up IBM Cognos 8 Tomcat Server 658 Known Issues When Using Metric Designer 658 Adding Multiple IQD Files to an Import Source 658 Previewed Scorecard Hierarchy Shows Blanks 659 Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service

661

Configuration Issues 661 The IBM Cognos 8 for Microsoft Office Interface Fails to Initialize in Microsoft Office 661 IBM Cognos 8 Go! Office Does Not Start in Microsoft Word 661 IBM Cognos 8 for Microsoft Office Fails to Initialize in Microsoft Internet Explorer 662 bo:heap Buffer Overflow Error 662 Microsoft Office Does Not Open a Microsoft Office Document Published from IBM Cognos 8 for Microsoft Office 662 Unable to Open Published Microsoft Office Documents from IBM Cognos Connection 663 Error Messages, the .NET shortcut, or the .NET Console Are Not in the Language of the .NET Framework 2.0 That Was Installed 664 Workbook Closes Unexpectedly if the Name Contains a Square Bracket 664 The server committed a protocol violation. Section=ResponseHeader Detail=CR must be followed by LF 664 Reports Unavailable in IBM Cognos Connection Jobs after Using Save As Command in Report Studio 665 Unable to Correctly Display East Asian Characters 665 The Content of the Cell-based Report Shows #NAME? 665 Processing Issues 666 Cannot Render this Report 666 RDS Data Limit Exceeded When Importing from Large Report Outputs 666 RDS Server Unavailable 666 Imported Reports Are Missing Charts or Images 667 #ERROR Appears in Cells with Multiple Images in a Cell (Excel Only) 667 The Dispatcher Is Unable to Process the Request. The Request Is Directed to an Unknown Service Name: Content 667 Report Content is Not Imported 667 Incorrect Format for the Prompt Value in Prompted Reports 668 DPR-ERR-2079 Firewall Security Rejection 668 This item cannot be expanded. Microsoft Excel has reached the maximum number of rows or columns for this worksheet 669 Prompted to Log on for Each Imported Report 669 Object reference not set to an instance of an object 669 Error 0:RSV-BBP-0027 The Secondary Request Failed 669 Security Issues 669

Administration and Security Guide 21

Table of Contents IBM Cognos 8 for Microsoft Office Unable to Create Trust Relationship 670 Unable to View Reports After Clicking View Report 670 Report Data Service (RDS) Numbered Error Messages 670 RDS-ERR-1000 Report Data Service Could Not Process the Response from the Content Provider 670 RDS-ERR-1001 The PowerPlay Report Name Could Not Be Run. The Expected Response Was Not Returned by PowerPlay 671 RDS-ERR-1004 A Connection Could Not Be Established with IBM Cognos 8 671 RDS-ERR-1005 The Logon Requirements for IBM Cognos 8 Could Not Be Obtained. You May Already Be Logged into this Namespace, or the Target Namespace Does Not Exist 672 RDS-ERR-1012 IBM Cognos Content Service was Unable to Discover the Content Providers 672 RDS-ERR-1013 Report Data Service Was Unable to Query Content Manager 672 RDS-ERR-1014 Report Data Service Was Unable to Create the Document Object Object Name 672 RDS-ERR-1015 Report Data Service Was Unable to Create a New Document Version 672 RDS-ERR-1016 Report Data Service Was Unable to Create a New Document Content Object 672 RDS-ERR-1018 The IBM Cognos 8 Report Name Could Not Be Run. The Expected Response Was Not Returned by IBM Cognos 8 673 RDS-ERR-1019 IBM Cognos Content Service Was Unable to Retrieve the Portal Information from IBM Cognos Connection 673 RDS-ERR-1020 The Currently Provided Credentials are Invalid. Please Provide the Logon Credentials 673 RDS-ERR-1021 The IBM Cognos 8 Report Name Could Not be Run Because it Contains Unanswered Prompts. Please Provide the Prompt Answers, and Run the Report Again 674 RDS-ERR-1022 The Request Received by Report Data Service Is Not Valid 674 RDS-ERR-1023 The Report Name Could Not Be Run Because It Exceeds the Report Data Service Data Size Limit Set by the Administrator 674 RDS-ERR-1027 The Encoding for the PowerPlay Server Name Could Not Be Determined. ISO-8859-1 Will Be Used as the Encoding 674 RDS-ERR-1030 A Security Error Occurred While Trying to Establish a Connection with Name 674 RDS-ERR-1031 Report Data Service was unable to retrieve the metadata for Name 674 RDS-ERR-1033 Report Data Service Was Unable to Create the Report View Name 674 RDS-ERR-1034 The Report Specification for Name Could Not Be Retrieved From IBM Cognos 8 675 RDS-ERR-1039 The Request Could Not Be Cancelled. The Request is No Longer Running 675 RDS-ERR-1040 The Conversation With Conversation ID Has Been Cancelled 675 RDS-ERR-1044 The Output for the Requested Version for Object NameCould Not be Retrieved 675 RDS-ERR-1045 LayoutDataXML Output Was Not Generated for the Requested Version for Object [Name] 676 IBM Cognos 8 Go! Office Numbered Error Messages 676 COC-ERR-1003 Failed to Create Slide 676 COC-ERR-1302 There Is No Data Source Available 676

22

Table of Contents COC-ERR-2005 The Import Failed 676 COC-ERR-2006 Failed to Load the Portal Tree: Name 677 COC-ERR-2012 Failed to Render the List 677 COC-ERR-2013 This Is an Unsupported Office Application 677 COC-ERR-2014 Refresh Failed 677 COC-ERR-2015 Failed to Open the Import Wizard Dialog 677 COC-ERR-2019 Failed to Refresh an Image 678 COC-ERR-2301 Logon Failed 678 COC-ERR-2303 This Report Is Not Valid for Rendering 678 COC-ERR-2304 This Is a Prompted Report. It Is Not Currently Supported 678 COC-ERR-2305 Microsoft Excel Returned an Error. Ensure That Microsoft Excel is Not in Edit Mode, Then Try Again 679 COC-ERR-2308 Report Specification is Empty 679 COC-ERR-2603 You Must Add a Slide to the Presentation Before Importing Any Content 679 COC-ERR-2604 Cannot Render Empty List Object 679 COC-ERR-2607 Microsoft Office Message 679 COC-ERR-2609 The Custom property "Property_Name" does not exist 679 IBM Cognos 8 for Microsoft Office Numbered Error Messages 680 COI-ERR-2002 Block type is not valid 680 COI-ERR-2005 This Version of Microsoft Office Is Not Supported 680 COI-ERR-2006 This Microsoft Office Product Is Not Supported 680 COI-ERR-2008 Unable to Retrieve from Resources. Tried '{0}' 680 COI-ERR-2009 Unable to Perform This Operation Because Microsoft Excel is in Edit Mode 681 COI-ERR-2010 The Name {0} is Not Valid. A Name Must Not Contain Both a Quote (") Character and an Apostrophe (') Character 681 COI-ERR-2011 The server did not return the expected response. Check that the gateway is valid. 681 IBM Cognos 8 BI Analysis for Microsoft Excel Numbered Error Messages 681 COR-ERR-2002 Block Type is Not Valid 681 COR-ERR-2005 Block Specification is Not Valid or Missing "{0}" 681 COR-ERR-2006 Unexpected Type: [Stacked Block] 681 COR-ERR-2007 Error Retrieving from Resources. Tried '{0}' 682 COR-ERR-2009 Name Formula is Not Valid 682 COR-ERR-2010 Formula is Not Valid 682 COR-ERR-2011 Prompted Metadata Is Not Supported 682 COR-ERR-2012 Unable to Load Metadata 682 COR-ERR-2013 Exploration Cannot Be Converted to Formula Based Because at Least One Context Item Contains a Selection 682 COR-ERR-2014 Due to Excel worksheet limitations the results may be truncated 682 COR-ERR-2015 Exploration Cannot Be Converted to Formula Based Because There is a Default Measure and a Measure on Either Rows or Columns 683 COR-ERR-2016 Unable to Retrieve Package Name 683 COR-ERR-2017 The Current Selection Did Not Return Any Data 683 Part 10: Reference Material Appendix A: Round Trip Safety Configuration of Shift-JIS Characters Example: Safe Conversion of Shift-JIS 686 Administration and Security Guide 23

685

Table of Contents The Round Trip Safety Configuration Utility 686 Specify Conversions 687 Specify Substitutions 688 Apply the Conversions and Substitutions 689 Restore the Default Conversion Settings 689 Specify Conversions for Series 7 PowerPlay Web Reports 690 Appendix B: Initial Access Permissions

691

Content Manager Hierarchy of Objects 691 Appendix C: Localization of Samples Databases

703

One Column Per Language 703 One Row Per Language 704 Transliterations and Multiscript Extensions 705 Appendix D: User Interface Elements Reference List Elements You Can Hide 707 Elements You Can Add 714 Appendix E: User Reference Help for Portal Services Cognos Navigator 717 Cognos Search 719 Cognos Viewer (IBM Cognos Connection) 721 Cognos Viewer 724 Cognos Extended Applications 726 Metric List 726 Metric History Chart 728 Metrics Impact Diagram 730 Metrics Custom Diagram 731 Bookmarks Viewer 732 HTML Viewer 733 Image Viewer 734 RSS Viewer 735 HTML Source 737 Multi-page 738 Appendix F: Schema for Data Source Commands

707

717

741

commandBlock 742 Child Elements of commandBlock Element 742 Parent Elements of commandBlock Element 742 commands 742 Child Elements of commands Element 742 Parent Elements of commands Element 742 sessionStartCommand 742 Child Elements of sessionStartCommand Element 743 Parent Elements of sessionStartCommand Element 743 sessionEndCommand 743 Child Elements of sessionEndCommand Element 743 Parent Elements of sessionEndCommand Element 743 arguments 744 Child Elements of arguments Element 744 24

Table of Contents Parent Elements of arguments Element 744 argument 744 Child Elements of argument Element 744 Parent Elements of argument Element 744 setCommand 745 sqlCommand 745 Child Elements of sqlCommand Element 745 Parent Elements of sqlCommand Element 745 sql 745 Child Elements of sql Element 745 Parent Elements of sql Element 745 name 745 Child Elements of name Element 746 Parent Elements of name Element 746 value 746 Child Elements of value Element 746 Parent Elements of value Element 747 Appendix G: Data Schema for Log Messages

749

Table Definitions 749 Table Interactions 750 COGIPF_ACTION Table 752 COGIPF_USERLOGON Table 753 COGIPF_NATIVEQUERY Table 754 COGIPF_PARAMETER Table 755 COGIPF_RUNJOB Table 756 COGIPF_RUNJOBSTEP Table 757 COGIPF_RUNREPORT Table 759 COGIPF_EDITQUERY Table 761 COGIPF_VIEWREPORT Table 763 COGIPF_AGENTBUILD Table 764 COGIPF_AGENTRUN Table 766 COGIPF_THRESHOLD_VIOLATIONS Table 768 Appendix H: Performing Tasks in IBM Cognos 8 Using URLs

773

CGI Program and Alternative Gateways 773 URL Methods 774 Parameterized URL Method 774 cognosLaunch Method 775 Common Optional Parameters 776 URL Validation 776 Starting IBM Cognos 8 Components 777 Start Parameters 778 Starting Report Studio 778 Starting Query Studio 779 Starting Analysis Studio 781 Starting Metric Studio 782 Starting Event Studio 782 Starting Cognos Viewer 783 Starting IBM Cognos 8 Components in a Specified Browser Window 785 Administration and Security Guide 25

Table of Contents Access an IBM Cognos Connection Page 787 Preparing a Page for Standalone Access 788 Using Search Paths and Page IDs 788 Using a Page ID Instead of the Object Search Path 789 Glossary Index

791

799

26

Introduction
This document is intended for use with IBM Cognos 8. IBM Cognos 8 is a Web product with integrated reporting, analysis, scorecarding, and event management features. This document contains step-by-step procedures and background information to help you administer IBM Cognos 8.

Audience
To use this guide, you should be familiar with reporting and security concepts, and have experience using a Web browser.

Related Documentation
Our documentation includes user guides, getting started guides, new features guides, readmes, and other materials to meet the needs of our varied audience. The following documents contain related information and may be referred to in this document. Note: For online users of this document, a Web page such as The page cannot be found may appear when clicking individual links in the following table. Documents are made available for your particular installation and translation configuration. If a link is unavailable, you can access the document on the IBM Cognos Resource Center (http://www.ibm.com/software/data/support/cognos_crc.html).

Document
IBM Cognos Connection User Guide

Description
Using IBM Cognos Connection to publish, find, manage, organize, and view IBM Cognos content, such as scorecards, reports, analyses, and agents Creating self-service business intelligence reports Authoring reports that analyze corporate data according to specific needs

Query Studio User Guide Report Studio Professional Authoring User Guide

Report Studio Express Authoring User Guide Authoring financial reports that analyze corporate data according to specific needs Event Studio User Guide Creating and managing agents that monitor data and perform tasks when the data meets predefined thresholds Creating and publishing models using Framework Manager

Framework Manager User Guide

Administration and Security Guide 27

Introduction

Document
IBM Cognos PowerPlay Enterprise Server Guide

Description
Administering PowerPlay servers and deploying cubes and reports to PowerPlay users in Windows environments or on the Web Viewing, exploring, formatting, and distributing PowerPlay reports using a Web browser Viewing, finding, organizing, and sharing information in Upfront, the customizable interface used to publish IBM Cognos reports to the Web Authoring scorecard applications and monitoring the metrics within them Using IBM Cognos 8 Go! Office to retrieve content from IBM Cognos reporting products within Microsoft Office Exploring, analyzing, and comparing dimensional data Describing features that are new in this release Installing and using the Localization Development Kit to translate and customize the messages and user interface text in IBM Cognos products Installing and using Map Manager to import and manage maps that are used in map reports

IBM Cognos PowerPlay Web User Guide

IBM Cognos Web Portal User Guide

Metric Studio User Guide

IBM Cognos 8 Go! Office User Guide

Analysis Studio User Guide

IBM Cognos 8 New Features Localization Development Kit Installation and User Guide

Map Manager Installation and User Guide

IBM Cognos 8 Architecture and Deployment Understanding the IBM Cognos 8 architecture, Guide developing installation strategies, including security considerations, and optimizing performance IBM Cognos 8 Installation and Configuration Installing, upgrading, configuring, and testing IBM Guide Cognos 8, changing application servers, and setting up samples Custom Authentication Provider Developer Guide Creating a custom authentication provider or a trusted signon provider using the Custom Authentication Provider API Creating and publishing models using the Framework Manager API

Framework Manager Developer Guide

28

Introduction

Document
IBM Cognos Finance User Guide

Description
Creating and managing financial reports and administering the database Using the samples included with the IBM Cognos 8 SDK to learn how to automate IBM Cognos 8

IBM Cognos 8 Software Development Kit Getting Started

IBM Cognos 8 Migration Tools User Guide Moving metadata and applications from IBM Cognos Series 7 to IBM Cognos 8 IBM Cognos 8 Planning Installation and Configuration Guide Installing and Configuring IBM Cognos 8 Planning Products

Finding Information
Product documentation is available in online help from the Help menu or button in IBM Cognos products. To find the most current product documentation, including all localized documentation and knowledge base materials, access the IBM Cognos Resource Center (http://www.ibm.com/software/ data/support/cognos_crc.html). You can also read PDF versions of the product readme files and installation guides directly from IBM Cognos product CDs.

Using Quick Tours

Quick tours are short online tutorials that illustrate key features in IBM Cognos product components. To view a quick tour, start IBM Cognos Connection and click the Quick Tour link in the lowerright corner of the Welcome page.

Getting Help
For more information about using this product or for technical assistance, visit the IBM Cognos Resource Center (http://www.ibm.com/software/data/support/cognos_crc.html). This site provides information on support, professional services, and education.

Printing Copyright Material

You can print selected pages, a section, or the whole book. You are granted a non-exclusive, nontransferable license to use, copy, and reproduce the copyright materials, in printed or electronic format, solely for the purpose of operating, maintaining, and providing internal training on IBM Cognos software.

Administration and Security Guide 29

Introduction

30

Chapter 1: Whats New?

This section contains a list of new, changed, and deprecated features for this release. It also contains a cumulative list of similar information for previous releases. It will help you plan your upgrade and application deployment strategies and the training requirements for your users. For information about upgrading, see the Installation and Configuration Guide for your product. For information about other new features for this release, see the New Features Guide. For changes to previous versions, see: New Features in Version 8.3 Changed Features in Version 8.3

To review an up-to-date list of environments supported by IBM Cognos products, such as operating systems, patches, browsers, Web servers, directory servers, database servers, and application servers, visit the IBM Cognos Resource Center Web site (http://www.ibm.com/software/data/support/cognos_ crc.html).

New Features in Version 8.4

Listed below are new features since the last release. Links to directly-related topics are included.

Additional Language Support

In addition to Japanese, German, and French, the installation documentation and the user interface for the installation program and IBM Cognos Configuration are available in the following languages: Chinese (simplified) Chinese (traditional) Korean Italian Spanish Portuguese (Brazilian)

You can use the new product languages when personalizing your user interface in IBM Cognos 8 (p. 260). English product documentation is installed when you install the IBM Cognos 8 gateway component. The Installation and Configuration Guide, the Quick Start Installation and Configuration Guide, and the Readme are the exceptions, and are available in all supported languages. To access all other translated documentation, you must install the Supplementary Languages Documentation.

Administration and Security Guide 31

Chapter 1: Whats New?

Support for IBM Metadata Workbench as a Lineage Solution

You can now configure IBM Metadata Workbench as a lineage solution in IBM Cognos 8. For more information, see "View Lineage Information for a Data Item" (p. 355). Administrators can configure the lineage solution by specifying the lineage URI in IBM Cognos Administration (p. 151).

Access to IBM WebSphere Business Glossary

If you use the IBM WebSphere Business Glossary, you can now access the glossary from Cognos Viewer (p. 356). You can configure the IBM WebSphere Business Glossary URL in IBM Cognos Administration (p. 152).

Managing Comments Using Cognos Viewer

You can now add user-defined comments to saved HTML, PDF and XML reports using Cognos Viewer. For more information, see (p. 369).

Adding Application Context to Dynamic SQL

An administrator can now define a custom string including application context that is added as a comment marker within SQL generated by the application. For more information, see "Add Application Context to Dynamic SQL" (p. 147).

Support for New Data Sources

You can now use the following data sources in IBM Cognos 8: IBM Cognos Now! Cube (p. 158) IBM Infosphere Warehouse Cubing Services (p. 168) TM1 (p. 178)

Support for New Portal Versions

IBM Cognos 8 Portal Services now provide extended support IBM WebSphere 6.0 and 6.1, and BEA AquaLogic User Interaction 6.5 (ALUI 6.5) For more information, see "Deploying Cognos Portlets to Other Portals" (p. 441).

Hiding Entries
You can hide entries in IBM Cognos Connection and IBM Cognos Administration, such as reports, packages, pages, folders, jobs, data sources, portlets, and so on. This functionality is most often used with drill-through reports. Hiding an entry does not affect its security policies.

32

Chapter 1: Whats New? For more information, see "Hide an Entry" (p. 254).

Updating Published PowerCubes

You can now use the pcactivate command to make new versions of published PowerCubes available to users. For more information, see "Deploy Updated PowerCubes" (p. 163).

Object Capabilities
You can now specify capabilities for individual packages. For more information, see "Object Capabilities" (p. 229).

Schedule Credentials
When you choose to import schedules in the deployment, you can change the imported schedule credentials to your credentials. For more information, see "Including Schedules" (p. 313).

Save History Details for Job Steps

You can save history details for job steps when the run activity completes successfully. For more information, see "Job Properties" (p. 248).

Viewing Lineage Information

A data items lineage information traces the items metadata back through the package and the packages data sources. Viewing lineage information ensures that you add the correct data items to a report. For more information, see "View Lineage Information for a Data Item" (p. 355).

Enhanced Drill-through Capabilities

In earlier versions of IBM Cognos 8, model-based drill-through supported only reports created in Analysis Studio, Query Studio, or Report Studio as targets. Other types of drill-through targets are now supported. For example, you can drill through to PowerPlay Studio reports saved in the content store, or to a package that contains a PowerCube. In earlier versions of IBM Cognos 8, drill-through access required the existence of parameters in the target. IBM Cognos 8 now allows dynamic filtering of the data. In cases where more control is needed, you can continue to use the existing parameterized drill-through. You now also can restrict the availability of package drill-through definitions to measures as well as other data when you set the scope. If the source is based on a dimensional package, you can choose what property of the source metadata item to map to the target. For example, you can map the member caption of the source metadata item to a relational value in the target instead of using the business key. For more information, see "Drill-through Access" (p. 401).

Administration and Security Guide 33

Chapter 1: Whats New? The drill-through assistant contains improved debugging information (p. 419).

Metric Studio Content in Portal Pages

An IBM Cognos Connection page or a dashboard can now display metric impact diagrams and custom diagrams. This new content can be added by using the following new portlets: Metrics Impact Diagram Use to display impact diagrams associated with a metric. Metrics Custom Diagram Use to display custom diagrams associated with a scorecard. For more information, see "Pages and Dashboards" (p. 267).

Changed Features in Version 8.4

Listed below are changes to features since the last release. Links to directly-related topics are included.

Composite Information Server is Replaced By IBM Cognos 8 Virtual View Manager

Composite Information Server was available with earlier releases of IBM Cognos 8. In the current release, Composite Information Server is replaced by IBM Cognos 8 Virtual View Manager, which is an IBM proprietary product that is based on a new version of Composite Information Server. In this release, the default repository is changed, from Microsoft SQL Server to IBM Informix. If you have Composite data sources defined in IBM Cognos Connection, you must migrate the existing repository to the new default repository. For more information, see "ODBC Data Sources" (p. 173). For more information about migrating the repository, see the IBM Cognos 8 Virtual View Manager User Guide.

IBM Cognos 8 Portal Services

Plumtree portal is replaced by BEA AquaLogic User Interaction 6.1 (ALUI 6.1) portal. For more information, see "Deploying Cognos Portlets to ALUI 6.1 and 6.5 Portal" (p. 449).

Deprecated Features in Version 8.4

A deprecated feature is one that is being replaced by a newer version or a better implementation. The intention is to discontinue the use of the feature and provide recommendations for adapting to this change over multiple releases. Listed below are deprecated features, including links to related topics.

IBM Cognos 8 PowerCube Connection Utility and cubeswap

In the next release of IBM Cognos 8 Transformer, the PowerCube Connection Utility and cubeswap will be deprecated. The functionality provided by these utilities is no longer required when using

34

Chapter 1: Whats New? the automated copy and activate options on the Deployment tab of the PowerCube properties dialog box For more information about the PowerCube copy and activate options, see "Deploy Updated PowerCubes" (p. 163) or the Transformer User Guide.

New Features in Version 8.3

Listed below are new features since the last release. Links to directly-related topics are included.

Improved User Interface for Administrators

Administrative tasks are now located in one central management interface named IBM Cognos Administration. The new interface will help you make quicker, more informed decisions, and simplify the overall management of the IBM Cognos environment.

Access to More Documentation

You can access supplementary documentation from More Documentation on the Help menu of IBM Cognos Connection. This new link opens a dynamic IBM Cognos Documentation page that contains one or more readme files and additional guides, depending on the products you have installed and the language in which you installed them.

More Granular Administrative Capabilities

A more granular approach to securing administrative functions is now available. Administrators can be granted some administrative permissions, but not others. For example, an administrator can have access to tasks associated with managing data sources, but not to the tasks associated with maintaining the security namespaces. For more information, see "Secured Functions and Features" (p. 221).

Access to System Statistics

You can view metrics related to different servers, dispatchers, and services. The metrics provide you with insight into the status of the environment. For more information, see "System Performance Metrics" (p. 91).

Snapshot of System Health

You can get a snapshot of the status of all servers, server groups, dispatchers, and services in the IBM Cognos topology. All system metrics are found on the System tab in IBM Cognos Administration. When you see statistics in their proper context, you can make better decisions regarding performance, scheduling, and capacity planning. For more information, see "System Performance Metrics" (p. 91).

Administration and Security Guide 35

Chapter 1: Whats New?

Managing Queues
IBM Cognos Administration provides specific views and tools to identify the report, job, or application currently in the queue or being processed. These views also reveal who is running the item, regardless of whether it is a background or interactive task. You can better understand what is happening in your environment and take action to resolve issues. For example, you can cancel a job for a user. For more information, see (p. 285)

Reducing Deployment Details

An administrator can specify the level of deployment details logged to the content store. By default, the deployment history will contain only summarized information. This will save memory space, improve performance, and require less maintenance. For more information, see "Deploying Selected Public Folders and Directory Content " (p. 311). You can learn the current status of a deployment by viewing periodic updates in the Monitor Service (p. 285).

Setting Priority on Schedules

You can set a priority, from 1 to 5, on a schedule. Setting a priority ensures that if two reports are waiting in the queue to be run, the report with the higher priority is run first. You can override and reset the priority on any schedule. For more information, see "Manage Entry Run Priority" (p. 293).

Better Control of Interactive Features in Reports

You can now disable interactive features in addition to drill-up, drill-down, and package drill report options. Administrators can control access to all interactive features, including drill-up and drilldown, package drill, authored drill, Go! Search, and notifications. This feature gives you more control of interactive activities. Hiding these functions may reduce the need for user training in large deployments. The new capabilities are exposed as run options in IBM Cognos Connection (p. 348).

New Sample Audit Reports

Sample audit reports have been added for metric threshold exceptions, agents, failed reports, and presentation service. For more information, see "Setting up Logging" (p. 79).

Publishing and Managing Packages in Non-root Folders

You can now publish packages from Framework Manager into any folder in IBM Cognos Connection. In previous versions, packages could be published and maintained only in the single root folder. These packages can also be moved from the root folder to any folder in IBM Cognos Connection. In Framework Manager, any target folder can be used for publishing.

36

Chapter 1: Whats New? For more information, see "Models and Packages" (p. 243).

Enabling Report Studio Authoring Modes

Report Studio now accommodates two distinct types of report authors: Express This user can access the Report Studio Professional authoring mode and the Express authoring mode. Professional This user can access the Report Studio Express authoring mode for financial report authoring to create and maintain statement style reports. Financial authoring requires many, but not all, of the features that exist in Report Studio and interaction with live data. In IBM Cognos Administration, you can restrict users to have access to only the Express authoring mode in Report Studio. For more information, see "Set Access to the Report Studio User Interface Profiles" (p. 227).

Server Administration
Server administration is enhanced with new capabilities. You can now: set PDF file character encoding, font embedding, and compression types and levels set the maximum execution time limit hotspots that are generated in an Analysis Studio or Report Studio chart set watch list output retention time

Settings for the maximum number of processes and connections has been improved. For some services, you can now set the maximum number of processes and the maximum number of high affinity and low affinity connections that the dispatcher can open to handle requests. For other services, you can set the maximum number of connections. For more information, see "Server Administration" (p. 105).

Transformer Integrated into IBM Cognos 8

Transformer is now fully integrated into IBM Cognos 8 Business Intelligence. This includes the ability to leverage IBM Cognos 8 metadata, support for cube building on IBM Cognos 8 platforms, and integration with IBM Cognos 8 security. For more information, see the Transformer User Guide.

My Activities and Schedules

You can now manage IBM Cognos 8 activities from My Activities and Schedules in IBM Cognos Connection.

Administration and Security Guide 37

Chapter 1: Whats New? You can view a list of your activities that are current, past, upcoming on a specific day, or scheduled. You can filter the list so that only the entries that you want appear. A bar chart shows you an overview of activities. You can set run priority for entries. You can also view the run history for entries, specify how long to keep run histories, and rerun failed entries. For more information, see "Activities Management" (p. 285)

My Watch Items
Use the My Watch Items area of the portal to view and manage alerts for new report versions and rules that you have set for conditional report delivery (p. 263). The My Watch Items functionality enables end users to monitor and manage business information that is critical to them from a single location. As a report owner, you must allow report users to receive alerts and create watch rules for the reports. For information about how to enable these features for reports, see "Enable Watch Rules for a Report" (p. 367).

Report Alerts
By enabling an alert on a report, you can now be notified when a new version is available. Whenever a report is run and saved due to a scheduled or manual run, all subscribers receive an email that a new version is available. Subscriptions are saved to the Alerts tab of My Watch Items (p. 263) and can be maintained from that location. For information about how to subscribe to a report, see "Add Yourself to or Remove Yourself from the Alert List for a Report" (p. 366).

Watch Rules
A new watch rule action is available in Cognos Viewer. You can use watch rules to control when users are notified about the availability of new report versions. When a report is run and saved, a user-defined threshold condition is checked. If this condition satisfies a user's criteria, the report can be e-mailed. To create a watch rule (p. 367), a saved report must be viewable in HTML format. You can select the data to be monitored and enter the threshold condition that will trigger the delivery of the report. Watch rules are saved to the Rules tab of My Watch Items (p. 263), and can be maintained from that location. This feature lets users maintain their own report distribution preferences and avoid information overload.

Drilling Through on Multiple Values

Drilling through is now more powerful and flexible. You can pass multiple items, such as products or countries, to a target report (p. 377). You can now use this feature regardless of the type of drill-

38

Chapter 1: Whats New? through path that was created. Drilling through is automatically enabled when you select multiple values. In previous versions, passing multiple values was available only within drill-through paths created in IBM Cognos Connection.

Go Directly to Target Report When Only One Target Report Exists

When there is only one target report available, you can now go directly to the target report when you click the drill-through link in Cognos Viewer. If there are multiple target reports available, you see the Go To page. This behavior is automatic and works the same way whether the drill-through is defined in Report Studio or in a drill-through definition in IBM Cognos Connection. For more information, see "Drill Through to Another Target" (p. 376).

Support for Microsoft Excel 2007

IBM Cognos 8 supports Microsoft Excel 2007 native spreadsheets as a report format, in addition to the existing Microsoft Excel HTML formats. The Microsoft Excel 2007 XML format, also known as XLSX, provides a fast way to deliver native Excel spreadsheets to Microsoft Excel XP, Microsoft Excel 2003, and Microsoft Excel 2007. The use of a native Microsoft Excel format means that the spreadsheets are smaller and more usable. Because the new Office Open XML format is a recognized industry standard supported by ECMA International, the new format provides the added benefit of an open, documented integration format that extends an open systems solution. The new format appears in the run report user interface. Users of Microsoft Excel XP and Microsoft Excel 2003 must install the Microsoft Office Compatibility Pack, which provides file open and save capabilities for the new format. For more information about Excel format support, see "Excel Formats" (p. 359).

Saving Report Outputs to a File System

You can now export report results directly to a server file system using IBM Cognos Connection. You decide which formats to export, and select from a predefined set of directory locations. This feature makes it easy to integrate IBM Cognos content into other external applications. IBM Cognos 8 does not keep a record of the exported reports, but does prevent and resolve name conflicts that arise when the same file is saved multiple times to the same directory. You are responsible for managing the reports after export. An XML descriptor file with the same file name prefix is created, which can be used by an external application to locate and manage the exported reports. The export options appear as run options for a report, provided you were granted access to this feature. For more information, see "Save Report Output" (p. 363).

Administration and Security Guide 39

Chapter 1: Whats New?

Resubmitting Failed Jobs and Reports

You can resubmit a failed job or report (p. 297). For example, you discover that 20 reports in a job containing 1,000 reports fail due to an invalid signon. The problem is corrected and the job is resubmitted so that only the 20 failed reports are rerun. In previous versions, if you submitted a report and it failed, the run options associated with the report were lost. Now the report can be resubmitted without having to reset the run options. Failed reports, jobs, and agent tasks can be resubmitted from the run history, accessed from the Past activities page of IBM Cognos Administration, or accessed from the Actions page of the item.

Resubmitting Failed Agent Tasks

Failed agent tasks can now be resubmitted with their original data values (p. 297). In previous versions, if a task failed, the data passed to the task was lost. Rerunning the agent may not solve this problem if the task is set to process new events only.

Default Actions for Agent Items

You can now choose a default action to use when an agent item is selected in IBM Cognos Connection, rather than automatically opening the agent in Event Studio (p. 384). The new choices are: show the most recent event list run the agent open the agent in Event Studio

The default action is defined on the Agent tab of the item properties in IBM Cognos Connection.

Tabbed Portal Pages

You can now create pages with multiple tabs that are easy to navigate. The new type of pages is also referred to as dashboards. Dashboards are created by using a new portlet named Multi-page. For more information, "Create a Dashboard with Multiple Tabs" (p. 275).

Global Filters and Enhanced Portal Interactivity

You can select the dashboard context in the portal with one or more global filters. A global filter may be a prompt, a drill-up or drill-down action, or a report that is based on drill-through content. For example, you can add a prompt control to a portal page to automatically pass the selection to all reports on the page. When a prompt answer is changed, all related reports will refresh accordingly. So, if you answer a country prompt with Brazil, all related reports on the page will be filtered to show the data for Brazil. When these techniques are used on a tabbed dashboard, the context is passed to all corresponding sections of the dashboard. This functionality allows for a single selection to drive a number of reports at once. For more information, see "Adding Interactivity to Pages and Dashboards" (p. 278).

40

Chapter 1: Whats New?

Metric Studio Content in Portal Pages

An IBM Cognos Connection page or a dashboard can now display more types of Metric Studio metrics and a history chart. This new content can be added by using the following new portlets: Metric List Use to add a watchlist, an accountability list, a scorecard metric list, or a strategy metric list to the page. Metric History Chart Use to add a graphical chart that illustrates the historical performance of a metric to the page. For more information, see "Pages and Dashboards" (p. 267).

Support for Microsoft SharePoint Portal 2003 and 2007

SharePoint Portal 2003 and 2007 is now supported in IBM Cognos 8. You can use this portal with the Cognos Navigator, Cognos Search, Cognos Viewer, Metric List, Metric History Chart, and Cognos Extended Applications portlets. For more information, see "Deploying Cognos Portlets to Microsoft SharePoint Portal Server 2003 and 2007" (p. 454).

Changed Features in Version 8.3

Listed below are changes to features since the last release. Links to directly-related topics are included.

Updated IBM Cognos Connection Look

The IBM Cognos Connection user interface was changed to provide more space for reports and information that you care about, and use less space for toolbars and functions. The new features include: The Launch menu, which replaces the Tools menu. This menu lets you access the IBM Cognos 8 studios, Drill-through Definitions, and IBM Cognos Administration. The my area icon , which lets you access the My Watch Items, My Preferences, and My

Activities and Schedules areas in IBM Cognos Connection. The portal style named Business. The updated Welcome to IBM Cognos 8 page.

For more information, see "Personalize the Portal" (p. 260).

More Information in the Go To Page

Additional information was added to the Related Links page. Related Links, also known as the Go To page, is used to show users all of the drill-through paths available from a source report. The Administration and Security Guide 41

Chapter 1: Whats New? page now automatically shows more information, such as the target report and its location. This information helps you choose which drill-through path to use.

Cognos Watchlist Portlet

The Cognos Watchlist Portlet was replaced by the Metric List portlet. In the new portlet, the watchlist is now one of the selectable options "Pages and Dashboards" (p. 267).

Replaced Capability
The capability known as Directory in previous releases of IBM Cognos 8 was replaced by the following, more granular capabilities: Data Source Connections Set capabilities and manage UI profiles Users, Groups, and Roles

For more information, see "Secured Functions and Features" (p. 221).

42

Chapter 2: IBM Cognos 8 Administration

After IBM Cognos 8 is installed and configured, you can perform server administration, data management, security and content administration, activities management, and portal services administration. You can also perform the following IBM Cognos 8 administrative tasks: automating tasks (p. 44) setting up your environment (p. 46) and configuring your database (p. 47) for multilingual reporting installing fonts (p. 47) setting up printers (p. 48) configuring web browsers (p. 50) allowing user access to Series 7 reports from IBM Cognos Connection (p. 52) restricting access to IBM Cognos 8 (p. 53)

Aside from the typical administrative tasks, you can also customize the appearance (p. 479) and functionality (p. 501) of different IBM Cognos 8 components. For information about potential problems, see the Troubleshooting section in this guide.

IBM Cognos Administration

In IBM Cognos Connection, you access IBM Cognos Administration from the Launch menu. You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Administrative Area
Activities

Tab
Status

Use
To manage current, past, upcoming, and scheduled IBM Cognos 8 entries. To manage Content Manager computers. To perform content store maintenance tasks. To create and manage data sources connections

Content Manager computers Status Content store Data sources Configuration Configuration

Administration and Security Guide 43

Chapter 2: IBM Cognos 8 Administration

Administrative Area
Deployment

Tab
Configuration

Use
To deploy IBM Cognos 8, to export from a source environment and then import in a target environment. To manage dispatchers and services To create and manage distribution lists and contacts. To manage styles, Cognos portlets, and other portlets in IBM Cognos Connection. To create and manage printers. To control access to specific product functions, such as administration and reporting, and features within the functions, such as bursting and user defined SQL. To monitor system performance using system metrics and administer servers. To tune server performance. To create and manage users, groups, and roles.

Dispatchers and Services Distribution lists and contacts Portals

Status Configuration

Configuration

Printers Security

Configuration Security

System, dispatcher, server, and service administration Server tuning Users, groups, and roles

Status

Status Security

Automating Tasks
Virtually everything you can do with the product, you can achieve using the appropriate API, URL interface, or command line tool as illustrated in the table below.

Goal

Document

Automation User interface interface

BI Bus API IBM Cognos Report Studio

Begin basic reporting with the IBM Cognos 8 SDK Modify a model, or republish it to UNIX or Windows

IBM Cognos 8 Getting Started Guide Framework Manager Developer Guide and Framework Manager User Guide

Script Player Framework tool Manager

44

Chapter 2: IBM Cognos 8 Administration

Goal

Document

Automation User interface interface

Framework Manager

Modify an unpublished model using IBM Cognos 8 Developer BI Bus API Guide the updateMetadata and queryMetadata methods Retrieve the query items available in IBM Cognos 8 Developer BI Bus API the published package using the get- Guide Metadata method Grant capabilities to users IBM Cognos 8 Developer BI Bus API Guide

IBM Cognos Connection

IBM Cognos Connection Server Administration

Administer and implement security IBM Cognos 8 Developer BI Bus API by authenticating and managing users Guide

IBM Cognos Connection Server Administration

Run, view, and edit reports through IBM Cognos 8 Developer URL InterGuide a hyperlink in an HTML page face Using URLs to View, Edit, and Run Reports To manipulate objects in the content IBM Cognos 8 Developer BI Bus API Guide store Managing IBM Cognos 8 Content in the

Cognos Viewer Query Studio Report Studio

IBM Cognos Connection Query Studio Report Studio Framework Manager

Administer reports

IBM Cognos 8 Developer BI Bus API Guide

IBM Cognos Connection IBM Cognos Connection Server Administration

Administer servers and manage Dis- IBM Cognos 8 Developer BI Bus API Guide patchers

Administration and Security Guide 45

Chapter 2: IBM Cognos 8 Administration

Goal

Document

Automation User interface interface

Report Studio

Modify or author a report

IBM Cognos 8 Developer BI Bus API Guide and report specification IBM Cognos 8 Adminis- URL Intertration and Security face Guide

Modify the functionality of IBM Cognos 8 by hiding user Interface elements and restricting content browsing

IBM Cognos Connection Report Studio Query Studio

Setting up a Multilingual Reporting Environment

You can create reports that show data in more than one language and use different regional settings. This means that you can create a single report that can be used by report consumers anywhere in the world. The samples databases provided with IBM Cognos 8 store a selection of text fields, such as names and descriptions, in more than 25 languages to demonstrate a multilingual reporting environment. For information about how data is stored in the samples databases and how the samples databases are set up to use multilingual data, see the Administration and Security Guide. Here is the process for creating a multilingual reporting environment: Use multilingual metadata. The data source administrator can store multilingual data in either individual tables, rows, or columns. For more information about configuring your database for multilingual reporting, see the Administration and Security Guide. Create a multilingual model. Modelers use Framework Manager to add multilingual metadata to the model from any data source type except OLAP. They add multilingual metadata by defining which languages the model supports, translating text strings in the model for things such as object names and descriptions, and defining which languages are exported in each package. If the data source contains multilingual data, modelers can define queries that retrieve data in the default language for the report user. For more information, see the Framework Manager User Guide. Create multilingual maps. Administrators and modelers use a Windows utility named Map Manager to import maps and update labels for maps in Report Studio. For map features such as country and city names, administrators and modelers can define alternative names to provide multilingual versions of text that appears on the map.

46

Chapter 2: IBM Cognos 8 Administration For more information, see the Map Manager Installation and User Guide. Create a multilingual report. The report author uses Report Studio to create a report that can be viewed in different languages. For example, you can specify that text, such as the title, appears in German when the report is opened by a German user. You can also add translations for text objects, and create other language-dependent objects. For more information, see the Report Studio Professional Authoring User Guide. Specify the language in which a report is viewed. You can use IBM Cognos Connection to do the following: Define multilingual properties, such as a name, screen tip, and description, for each entry in the portal. Specify the default language to be used when a report is run. Tip: You can specify the default language on the run options page, in the report properties, or in your preferences. Specify a language, other than the default, to be used when a report is run.

For more information, see the IBM Cognos Connection User Guide. The data then appears in the language and with the regional settings specified in the user's Web browser options the run options the IBM Cognos Connection preferences

Any text that users or authors add appears in the language in which they typed it.

Configuring Your Database For Multilingual Reporting

IBM Cognos 8 is a Unicode product capable of querying data in many languages and encoding. IBM Cognos 8 typically queries the database using the native data encoding of the database (Latin1, Shift-JIS, Unicode, and so on). IBM Cognos 8 translates this data to Unicode as required. When querying databases with two or more data encodings, Report Studio requests the data in Unicode. Certain databases require specific configuration of the client or server software to enable this capability. For more information, see your database vendor documentation. Note: For information on round trip safety issues when characters are converted from Unicode to Shift-JIS and back, see the information on the Round Trip Safety Configuration utility in "Round Trip Safety Configuration of Shift-JIS Characters" (p. 685).

Installing Fonts
IBM Cognos 8 uses fonts

Administration and Security Guide 47

Chapter 2: IBM Cognos 8 Administration to display HTML reports and pages in browsers to render PDF reports on the IBM Cognos 8 server to render charts used in PDF and HTML reports

To display output correctly, fonts must be available where the report or chart is rendered. In the case of charts and PDF reports, the fonts must be installed on the IBM Cognos 8 server. For example, if a Report Studio user selects the Arial font for a report, Arial must be installed on the IBM Cognos 8 server to properly render charts and PDF files. If a requested font is not available, IBM Cognos 8 substitutes a different font. Because HTML reports are rendered on a browser, the required fonts must be installed on the personal computer of each IBM Cognos 8 user who will read the HTML report. If a requested font is not available, the browser substitutes a different font. When creating reports, you must select fonts that your IBM Cognos 8 server or users have installed. Microsoft delivers a broad selection of fonts with different language packs, so this will likely not be an issue in Windows. However, UNIX servers rarely have fonts installed. You should be prepared to purchase and install the fonts you need on both the server and browser clients. For information about PDF file settings, see (p. 134). For information on using PDF format in reports, see (p. 357). For information about configuring fonts and about mapping substitute fonts, see the IBM Cognos Configuration User Guide.

IBM Cognos 8 Default Font

If a requested font is not found, the IBM Cognos 8 server renders PDF files and charts using a default font. Andale WT, part of the sans serif font family, is the default font because of its wide support of Unicode characters. However, it is not necessarily complete for all languages and may not be considered as attractive as purchased fonts. Also, this font has no Glyph Substitution (GSUB) and Ligature support in most languages.

Report Studio Fonts

Report Studio is an HTML and JavaScript application that runs in a browser. Because of the browser design, Report Studio operates within the browser security sandbox and has no access to the list of fonts installed on the local computer. Instead, Report Studio uses fonts configured in the IBM Cognos 8 global configuration. For more information, see the IBM Cognos Configuration User Guide.

Set Up Printers
To make printers available to users when they distribute reports, you can create entries for printers and save them in the IBM Cognos 8 content store. When users want to print a report, they can select a printer that you set up without needing to know its network address details. When you create a printer entry, ensure that the printer you define is set up on the computer where IBM Cognos 8 is installed. If the printer is not set up, the users cannot use it.

48

Chapter 2: IBM Cognos 8 Administration To set up printers, You must have the required capabilities to access IBM Cognos Administration functionality. You must have write permissions for the Cognos namespace. See "Secured Functions and Features" (p. 221).

Printing Considerations
To avoid possible errors, ensure that the following conditions are met before you try printing: Ensure that Adobe Reader version 5.0.5 or later is installed on each computer where IBM Cognos 8 servers are installed. Ensure that the IBM Cognos 8 server is started using an account that has access to the network printer. Sometimes, system accounts may not have access to network printers. If IBM Cognos 8 is installed on UNIX, ensure that Adobe Reader is installed in the path of the user that starts IBM Cognos 8. If IBM Cognos 8 is installed on UNIX, ensure that the command lpstat -v, returns a configured printer and that a printer variable is defined. When you define the network address for the printer in IBM Cognos Connection, use the following syntax: For Windows, use \\server_name\printer_name. For UNIX, use printer_name. When you define the network address for the printer, try using the IP address of the printer instead of the computer name. Ensure that IBM Cognos 8 users have the correct access permissions to the printer. The role Directory Administrators must have all access permissions granted, and the group Everyone must have read, execute, and traverse permissions granted.

Steps
1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Printers. A list of printers appears. Tip: To remove a printer, select the check box for the printer and click the delete button. 3. On the toolbar, click the new printer button .

4. Type a name and, if you want, a description for the printer. Tip: Use a name that provides details about the printer, such as Color Printer - 4th Floor 5. Type the network address of the printer by using the format \\server_name\printer_name for a network printer on a Windows installation and printer_name for a UNIX installation or for a local printer on Windows. Administration and Security Guide 49

Chapter 2: IBM Cognos 8 Administration 6. Click Finish. Tip: To check or assign access permissions for a printer, in the Actions column, click the set properties button for the printer, and then click the Permissions tab.

Configuring Web Browsers

IBM Cognos 8 uses the default browser configurations provided by Microsoft, Netscape, and Firefox. For all browsers, you must ensure that settings are enabled for cookies and Java scripts. Additional required settings are specific to the browser. The following table shows the settings that must be enabled in the supported Web browsers.

Browser
Internet Explorer (settings for studios and portals)

Setting
Allow Cookies Active Scripting Allow META REFRESH

IBM Cognos component

IBM Cognos Connection IBM Cognos Administration Cognos Viewer Report Studio Query Studio Analysis Studio Event Studio Metric Studio

Internet Explorer (settings for some studios)

Run ActiveX controls and plug- Report Studio ins Query Studio Script ActiveX controls marked Analysis Studio safe for scripting Binary and script behaviors Allow programmatic clipboard access Report Studio

Internet Explorer (settings for a single studio)

Note: Report Studio and Query Studio use the native Microsoft Internet Explorer XML support, which is a component of the browser. ActiveX support must be enabled because Microsoft implements XML using ActiveX. IBM Cognos 8 does not provide or download ActiveX controls. Only the ActiveX controls that are installed as part of Internet Explorer are enabled through this configuration. IBM Cognos 8 uses the following cookies to store user information.

50

Chapter 2: IBM Cognos 8 Administration

Cookie
AS_TICKET

Type
Session temporary

Purpose
Created if IBM Cognos 8 is configured to use an IBM Cognos Series 7 namespace Contains security state information Stores a reference to a user session stored on the Content Manager server Holds session information that is specific to IBM Cognos Connection Holds information during edit operations, such as cut, copy, and paste Contains the content and product locale information, and is set for all IBM Cognos users Stores the choice that the user makes for the "view members folder" in Report Studio Stores the current folder path if local file access is used, and is updated after the Open or Save dialog box is used Stores session information that is specific to PowerPlay Studio Stores the settings that the user makes for user interface elements such as menus and toolbars Contains all capabilities and the signature for the current user

caf

Session temporary

Cam_passport

Session temporary

cc_session

Session temporary

cc_state

Session temporary

CRN

Session temporary

CRN_RS

Persistent

PAT_CURRENT_ FOLDER

Persistent

pp_session

Session temporary

qs

Persistent

userCapabilities

Session temporary

Administration and Security Guide 51

Chapter 2: IBM Cognos 8 Administration

Cookie
usersessionid

Type
Session temporary

Purpose
Contains a unique user session identifier, valid for the duration of the browser session.

After upgrading or installing new software, restart the Web browser and advise users to clear their browser cache.

Allow User Access to Series 7 Reports from IBM Cognos Connection

If IBM Cognos 8 is configured properly to use the IBM Cognos Series 7 namespace, you can allow users to access NewsIndexes and NewsBoxes of the Series 7 version of IBM Cognos Upfront from IBM Cognos Connection. We recommend that IBM Cognos Connection and Upfront use the same Web server if Upfront is set up to use relative URLs. If IBM Cognos Connection and Upfront use different Web servers, configure Series 7 to use fully qualified URL. This allows users to use the Web browser back button to navigate from Upfront back to IBM Cognos Connection. For information about configuring Series 7, see IBM Cognos Series 7 Configuration Manager User Guide. For information about running Series 7 reports, see "Series 7 Reports in IBM Cognos Connection" (p. 378). You may also want to see "Series 7 Users" (p. 207) and "Series 7 Roles" (p. 209).

Steps
1. In IBM Cognos Configuration, configure IBM Cognos 8 to use your IBM Cognos Series 7 namespace. For more information, see the Installation and Configuration Guide. 2. In the Properties window, under Cookie Settings, ensure that the Secure Flag Enabled property is set to false. 3. From the File menu, click Save and close IBM Cognos Configuration. 4. Ensure that the ticket server for IBM Cognos Series 7 namespace is running. 5. Ensure that the timeout value of the Series 7 ticket server is set to the same value or to a higher value than the IBM Cognos 8 passport timeout value. 6. On the computer where IBM Cognos 8 is installed, open the c8_location/templates/ps/portal/ system.xml file in an editor. Ensure that your editor supports saving files in UTF-8 format. 7. Find and edit (with an XML editor) the series7 parameter as follows:
<!-- Series 7 Integration parameters --> <param name="series7"> <enabled>true</enabled> <!-- character encoding used by series7 --> <encoding>series7_character_encoding</encoding> <!-- host and port to connect to Upfront server -->

52

Chapter 2: IBM Cognos 8 Administration

<host>Upfront_host_name</host> <port>Upfront_dispatcher_port_number</port> <!-- Upfront gateway location --> <gateway>Upfront_gateway_location</gateway> <!-- If required, specify the prefix for IBM Cognos 8 back URLs when linking to Series 7 content. (eg. http://Cognos8_computer) otherwise relative URL's will be used --> <back-prefix>http://Series 7_server</back-prefix> </param>

To view the character encoding used by Series 7, in Series 7 Configuration Manager, on the Properties tab, click IBM Cognos Shared, click Locale, and then click the Encoding property 8. Save the system.xml file in UTF-8 format. 9. Using IBM Cognos Configuration, stop and then restart IBM Cognos 8. For more information about stopping IBM Cognos 8, see the Installation and Configuration Guide.

Restricting Access to IBM Cognos 8

You may not want all users that exist in an authentication source to have access to IBM Cognos 8. To secure IBM Cognos 8, configure the product so that only users who belong to a specific group or role in your authentication source, or in the Cognos namespace, are allowed access. We recommend using the Cognos namespace because it contains preconfigured groups and roles that help you to secure IBM Cognos 8 quickly. One of the preconfigured groups is Everyone. By default, the group Everyone belongs to several built-in groups and roles in the Cognos namespace. If you decide to use the Cognos namespace, you must remove the Everyone group from all built-in groups and roles and replace it with groups, roles, or users authorized to access IBM Cognos 8. To restrict access to IBM Cognos 8, do the following: In IBM Cognos Configuration, enable the required properties to restrict access. For more information, see the Installation and Configuration Guide. In IBM Cognos Administration, remove the Everyone group from all built-in groups and roles. Replace it with groups, roles, or users that are authorized to access the different functional areas of IBM Cognos 8. For more information, see (p. 233) In IBM Cognos Connection, set up access permissions for individual entries, such as folders, packages, reports, pages, and so on (p. 213).

For more information about the security concepts implemented in IBM Cognos 8, see (p. 201).

Administration and Security Guide 53

Chapter 2: IBM Cognos 8 Administration

54

Chapter 3: Building IBM Cognos 8 Applications

The lifetime of an IBM Cognos 8 business intelligence application can be months, or even years. During that time, data may change and new requirements appear. As the underlying data changes, authors must modify existing content and develop new content. Administrators must also update models and data sources over time. For more information about using data sources, see the IBM Cognos 8 Administration and Security Guide and the Framework Manager User Guide. In a working application, the technical and security infrastructure and the portal are in place, as well as processes for change management, data control, and so on. For information about the workflow associated with creating IBM Cognos 8 content, see the IBM Cognos 8 Architecture and Deployment Guide. For additional information, see the IBM Cognos Solutions Implementation Methodology toolkit, which includes implementation roadmaps and supporting documents. Information about the toolkit is available on the IBM Cognos Resource Center (http://www.ibm. com/software/data/support/cognos_crc.html). The following graphic provides an overview for how to use IBM Cognos 8 to build applications across all of your IBM Cognos 8 components.

Locate and prepare data sources and models

Build and publish the content

Deliver the information

Locate and prepare data sources and models IBM Cognos 8 can report from a wide variety of data sources, both relational and dimensional. Database connections are created in the Web administration interface, and are used for modeling, for authoring, and for running the application. To use data for authoring and viewing, the business intelligence studios need a subset of a model of the metadata (called a package). The metadata may need extensive modeling in Framework Manager.

Build and publish the content Reports, scorecards, analysis, dashboards and more are created in the business intelligence studios of IBM Cognos 8. Which studio you use depends on the content, lifespan, and audience of the report, and whether the data is modeled dimensionally or relationally. Report Studio reports and scorecards are usually prepared for a wider audience, published to IBM Cognos Connection or another portal, and scheduled there for bursting, distribution, and so on. You can also use Report Studio to prepare templates for self-service reporting.

Deliver and view the information You deliver content from the IBM Cognos portal or other supported portals, and view information that has been saved to portals, or delivered by other mechanisms. You can also

Administration and Security Guide 55

Chapter 3: Building IBM Cognos 8 Applications run reports, analyses, scorecards, and more from within the business intelligence studio in which they were created. For information about tuning and performance, see the IBM Cognos 8 Administration and Security Guide and the IBM Cognos Resource Center (http://www.ibm.com/software/data/ support/cognos_crc.html).

56

Chapter 4: Samples
This section explains the purpose, content and location of IBM Cognos 8 samples. It also discusses the sample company, Great Outdoors, its structure, databases, model and packages. For information on how to set up the sample databases, see "Setting Up the Samples" (p. 63).

The Great Outdoors Company Samples

The Great Outdoors Company samples illustrate product features and technical and business best practices. You can also use them for experimenting with and sharing report design techniques and for troubleshooting. For examples related to different kinds of businesses, see the product blueprints at (http://www. ibm.com/software/data/support/cognos_crc.html). For information about specific installation choices and environments, see the Architecture and Deployment Guide, or the Proven Practices and the IBM Cognos Implementation Roadmaps on the IBM Cognos Resource Center (http://www.ibm. com/software/data/support/cognos_crc.html). For information about audit samples, see the Administration and Security Guide.

Where to Find the Samples

The samples are included with the product and the samples for each studio are described in the related user guide and online help. To use the samples, you must set up and configure them or contact your administrator to find out where they are installed. For instructions on how to set up and configure samples, see the Installation and Configuration Guide or the Administration and Security Guide.

What Samples Exist

The samples consist of two databases that contain all corporate data, the related sample models for query and analysis, and sample cubes, reports, queries, query templates, and dashboards a metrics database and the associated metrics, including a strategy map for the consolidated company Note: You must have Metric Studio installed to use the metrics database and associated metrics. interactive reports that let you hover over report features to learn how the features work and why they were included Note: These reports are stored in the Interactive Samples folder of the IBM Cognos 8 installation.

Administration and Security Guide 57

Chapter 4: Samples

Security
You can add security to the samples using an employee list included with the product. The list is in the form of an LDIF file that can be imported into any directory server, such as the Sun Java System Directory Server. Note: You can download a version of the Sun Java System Directory Server from the Sun Web site (http://www.sun.com/download/). For more information, see the Installation and Configuration Guide. For information about conformance, see the IBM Cognos Resource Center (http://www. ibm.com/software/data/support/cognos_crc.html).

The Great Outdoors Group of Companies

To make designing examples faster, especially financial examples, some general information about The Great Outdoors Company is useful. To look for samples that use particular product features, see the individual sample descriptions in this appendix. Revenue for The Great Outdoors Company comes from corporate stores and from franchise operations. The revenues are consolidated from the wholly-owned subsidiaries. There are six distinct organizations, each with its own departments and sales branches. Five of these are regionally-based companies. The sixth company, GO Accessories has its own collection of products, differentiated from the other GO companies by brand, name, price, color and size sells from a single branch to all regions and retailers functions both as an operating company based in Geneva, and as a part owner of the three GO subsidiaries in Europe.

The diagram below illustrates the consolidated corporate structure, including the percentage changes in ownership for GO Central Europe, and shows the reporting currency and GL prefix for each subsidiary.

58

Chapter 4: Samples

Great Outdoors Consolidated (holding company) USD

GO Americas (AMX 1099) USD

GO Asia Pacific (EAX 4199) YEN

GO Accessories (EUX 8199) EURO

Year 1 60% Year 3 50%

Year 1 40% Year 3 50%

GO Central Europe (CEU 6199) EURO

GO Southern Europe (SEU 7199) EURO

GO Northern Europe (NEU 5199) EURO

Each corporation has the same departmental structure and the same GL structure, shown in the table below. Divisions may not report in the same currencies. For example, the Americas subsidiary reports in US dollars, but the Corporate division local currency is Canadian dollars, and the Operations division local currency is pesos.

Division (GL)
Corporate (1700)

Department (GL)
Sales (1720) Marketing (1750) IS&T (1760) Human Resources (1730) Finance (1740) Procurement (1710)

Operations (1800)

Production and Distribution (1820) Customer Service (1820)

Each corporation has a complete chart of accounts. Most of the accounts, such as those under nonpersonnel expenses, are at the department level, and contain only summary amounts. For example, although each marketing department has expenses, the cost is unspecified at the transaction level where marketing promotions occur. Administration and Security Guide 59

Chapter 4: Samples

Employees
The Great Outdoors data contains a full list of employees in all divisions, departments, and locations. Data is available for reports about bonuses (Global Bonus report) and sales commissions (Sales Commissions for Central Europe report), training (Employee Training by Year report), and performance reviews and employee satisfaction surveys (Employee Satisfaction 2006). If you use Metric Studio, sample metrics for human resources are also available. In the GO Data Warehouse (analysis) package, groups of measures and the related dimensions are organized into folders. The employees are organized in hierarchies for region, manager, position or department, and organization, to make different kinds of aggregation easy to report on. Aggregation has been defined for the Employee Position Summary measures, so that Position count and Planned position count aggregate correctly at each level of time: monthly, quarterly, or yearly. For example, see the Planned Headcount report. The employees are also listed in a sample LDIF file (p. 58). This authentication directory is necessary for the Transformer 8 cubes and for IBM Cognos Planning samples. No other samples depend on security profiles. For more information, see the Installation and Configuration Guide.

Sales and Marketing

Data about sales and marketing is available for all of the companies in the Great Outdoors group. GO Accessories has richer details to support analysis examples. For example, see the Revenue vs % Gross Profit by Product Brand analysis, based on the Sales and Marketing cube. Marketing and sales campaigns are tied to the Great Outdoors regional companies. Overall, the GO companies have experienced solid growth across most product lines (Sales Growth Year Over Year), in all regions (Revenue by GO Subsidiary 2005), because of factors like an increase in repeat business and new or improved products, such as the high margin sunglasses product line. In the product lines sold by the five regional companies (all but GO Accessories) promotions have had mixed success (Promotion Success by Campaign, Bundle and Quarter). If you use Metric Studio, this can also be seen in the sample metrics.

Customer Surveys
The data also contains information from customer surveys. For example, the product line that includes bug spray, sun screen, and so on has not been successful (Product Satisfaction - Outdoor Protection 2005) and a source of retailer dissatisfaction may be the level of customer service rather than the returns (Customer Returns and Satisfaction). If you use Metric Studio, this information can also be monitored in metrics.

Sales Outlets
Revenue from the corporate outlets is available at the transaction level. Revenue from the franchise outlets is available at the consolidated level only (Sales and Marketing cube). Metrics about retailers show that the number of new retail outlets has dropped over the time period covered by this data. GO Accessories sells worldwide, and sells only accessories. Transaction data for GO Accessories is the primary source for analysis of product by brand, color and size. The other five subsidiaries in the group of companies are regional and sell all product lines for retailers in their region. For

60

Chapter 4: Samples example, the report Top 10 Retailers in 2005 uses sparklines and list data to review revenues at the retailer level.

Great Outdoors Database, Models, and Packages

The Great Outdoors models illustrate modeling techniques and support the samples. The models are based on the GO data warehouse and the GO sales transactional database and are the basis for the sample reports and queries. Each model contains two packages for publishing analysis (dimensional) and query views of the data. For a description of each sample report or query, see the user guide for the studio that you open the sample in. For more information about modeling techniques, see the Guidelines for Modeling Metadata, or the Framework Manager User Guide. You must have access to Framework Manager, the modeling tool in IBM Cognos 8, to look at the sample models. You may also need to set up the sample databases and connections. For instructions, see the Administration and Security Guide or the Installation and Configuration Guide.

GO Data Warehouse
The GO Data Warehouse model, great_outdoors_data_warehouse.cpf, is based on the database GOSALESDW. It contains data about human resources, sales and marketing, and finance, grouped into business areas. In the Database view, the three business areas are grouped into separate namespaces. The Database view contains a fourth namespace (GO Data) for the common information. The Database view is very similar to the structure of the underlying database. All tables (database query subjects) are unchanged. This enables IBM Cognos 8 to retrieve metadata directly from the package in most cases, instead of using a metadata call to the database. The following changes and additions have been made in the Database view: Joins have been added as necessary. To allow for aggregation at different levels of granularity, some model query subjects have been created. For example, see the relationships between Time and Sales or Sales fact. To allow single joins to be made between the lookup tables and each level in a dimension, lookup tables have been copied. For example, see the Products look up tables.

The Business view contains only model query subjects, with no joins. The following changes and additions have been made in the Business view: Calculations were added to the model query subjects. For example, the time dimension contains language calculations. Where the database has multiple hierarchies, new dimensions have been created to organize each hierarchy. For example, see the employee hierarchies, where employees are organized by manager, organization, region, and position.

Administration and Security Guide 61

Chapter 4: Samples

The GO Sales Transactional Database

The GO Sales model, great_outdoors_sales.cpf, is based on the GOSALES database, which is structured as a transactional database. It contains principally sales data. The Database view is very similar to the underlying database structure. The following changes and additions have been made in the Database view: To make it possible to join the fact tables to the time dimension, model query subjects and multipart joins have been used. Other joins have been added as necessary.

The Business view contains only model query subjects, with no joins. The following changes and additions have been made in the Business view: Calculations were added to the model query subjects. Model query subjects that were created in the Database view to enable joins on the time dimension have been linked as reference shortcuts. Where the database has multiple hierarchies, new dimensions have been created to organize each hierarchy. Sales Staff is a subset of the slowly changing Employee dimension.There is no unique Employee key in GO Sales, so a filter retrieves the current record only. This model does not use historical data.

62

Chapter 4: Samples

The Samples Cubes

The following cubes are delivered with the Great Outdoors samples in English, French, German, Japanese and Chinese: sales_and_marketing.mdc employee_expenses.mdc go_accessories.mdc go_americas.mdc go_asia_pacific.mdc great_outdoor_sales.mdc

The Samples Packages

The Great Outdoors samples include seven packages. Below is a brief description of each available package. Go Data Warehouse (analysis) is a dimensionally modeled view of the GOSALESDW database. This package can be used in all studios, including Analysis Studio. Using this package you can drill up and down. Go Sales (analysis) is a dimensionally modeled view of the GOSALES database. This package can be used in all studios, including Analysis Studio. Using this package you can drill up and down. Go Data Warehouse (query) is a non-dimensional view of the GOSALESDW database. This package can be used in all studios except Analysis Studio, and is useful for reporting when there is no need for drilling up and down. Go Sales (query) is a non-dimension view of the GOSALES database. This package can be used in all studios except Analysis Studio, and is useful for reporting when there is no need for drilling up and down. Sales and Marketing (conformed) is based on the GOSALESDW database. Dimensions are conformed with the dimensions found in the Sales and Marketing (cube) package, in order to enable drillthrough from the cube package to the dimensional package. Sales and Marketing (cube) is an OLAP package, based on the sales_and_marketing.mdc cube. Great Outdoor Sales (cube) is an OLAP package, based on the great_outdoor_sales.mdc cube. Note: The OLAP packages, Great Outdoor Sales (cube) and Sales and Marketing (cube), are not multilingual. The Cognos_PowerCube.zip archive contains five versions of each package; one in English, French, German, Japanese and Chinese.

Setting Up the Samples

You can use the IBM Cognos samples to learn how to use IBM Cognos 8, including Framework Manager, Metric Studio, Metric Designer, and Event Studio. IBM Cognos 8 provides sample databases that contain sales, marketing, and financial information for a fictional company named the Great Outdoors Company that sells sporting equipment.

Administration and Security Guide 63

Chapter 4: Samples Before you can use the sample databases, IBM Cognos 8 must be installed, configured, and running. For IBM Cognos 8 reports and analyses, Framework Manager should also be installed, configured, and running. To use the sample content for Metric Designer, the optional modeling tool for Metric Studio, Metric Designer must also be installed, configured, and running. To set up the samples, do the following: Restore the samples databases. Create the data source connections to the samples databases. If you plan to use OLAP data source samples, set up the sample cubes, if this is required, and create data source connections to the OLAP data sources you want to use. Setup tasks are required only for Microsoft Analysis Services cubes and Essbase cubes. If you plan to use the Metric Studio sample, set up the Metric Studio sample. If you plan to use the Metric Designer sample, set up a data source connection to it, set up the Metric Studio sample, and import the Cognos_Samples and GO_Metrics deployment archives. Import the samples content (packages) into the content store. If you want to test the sample agent ELM Returns Agent using Event Studio, run the sample agent against changed data.

After you complete these tasks, use IBM Cognos 8 to run the sample reports or scorecards. You can later remove the IBM Cognos 8 samples.

Restore Backup Files for the Samples Databases

To use the samples, you must restore backup files for the samples databases. This action re-creates multilingual versions of the Great Outdoors databases. The following sample databases and associated files are provided with IBM Cognos 8. For SQL Server and Oracle, each database is delivered as a Microsoft SQL Server backup file and an Oracle export file (.dmp). For DB2, the database schemas are delivered in a DB2 move file. The files are compressed, and you must extract them before you can restore the databases or schemas.

SQL Server Databases and Files Database or schema description

Great Outdoors sales Great Outdoors retailers Great Outdoors sales data warehouse Great Outdoors market research

File name
GOSALES.zip GOSALES.zip GOSALESDW. zip GOSALES.zip

64

Chapter 4: Samples

Database or schema description

Great Outdoors human resources

File name
GOSALES.zip

Oracle Databases and Files Database or schema description

Great Outdoors sales Great Outdoors retailers Great Outdoors sales data warehouse Great Outdoors market research Great Outdoors human resources

File name
GOSALES.dmp.gz GOSALESRT.dmp.gz GOSALESDW. dmp.gz GOSALESMR. dmp.gz GOSALESHR. dmp.gz

DB2 Databases and Files Database or schema description

Great Outdoors sales Great Outdoors retailers Great Outdoors sales data warehouse Great Outdoors market research Great Outdoors human resources

File name
GS_DB.tar.gz GS_DB.tar.gz GS_DB.tar.gz GS_DB.tar.gz GS_DB.tar.gz

When restoring the samples databases, ensure that you do the following: Give the restored databases the same names as the backup or export file names. The names are case-sensitive. Create users with select privileges for tables in multiple schemas. Setup for the GO Data Warehouse packages specifies a single connection object and user signon. This requires a single user named GOSALESDW with the select privilege to tables in a single schema named GOSALESDW. Setup for the GO Sales packages specifies a single connection object and user signon. This requires a single user named GOSALES with the select privilege to tables in four schemas: GOSALES, GOSALESHR, GOSALESMR, and GOSALESRT. Use the UTF-8 character set on the database server. Administration and Security Guide 65

Chapter 4: Samples Use the UTF-8 character set on the Windows computer that is the Oracle or DB2 client to see reports in multiple languages. For DB2, you must set the DB2CODEPAGE environment variable to a value of 1208. For Oracle, you must set the NLS_LANG environment variable to a value that is specific to a region. For example, set NLS_LANG for Americas to American_America.UTF8. Have sufficient disk space available in the target location. Reserve 150MB for the GO Sales data (four schemas) and 200MB for the GO Data Warehouse data (one schema).

Oracle Considerations
To create foreign key constraints in tables that reference different schemas, you must run gs_or_modify.sql, found in the same folder as the .dmp files.

SQL Server Considerations

If you restore the SQL Server backup files, you must use Microsoft SQL Server 2000 or Microsoft SQL Server 2005. Ensure that TCP/IP connectivity is used for the SQL server.

DB2 Considerations
Before you restore the Great Outdoors schemas contained in the DB2 move file on UNIX or Windows, extract the DB2 move file. On UNIX, extract the DB2 move file using the gnutar -xcvf
DB2_move_filename or tar -xcvf DB2_move_filename command. If you use WinZip to extract

the DB2 move file on Windows, ensure that the TAR file smart CR/LF conversion option is not selected. After extracting the DB2 move file, restore the schemas to a database named GS_DB. To add views, constraints, user privileges, and stored procedures to GS_DB, prepare and run the gs_db_modify files included with the samples in the following order: Update the user name and password at the top of the gs_db_modify.sql and save it. Execute gs_db_modify.bat

Steps
1. On the computer where IBM Cognos 8 is installed, go to the sql server, oracle, or db2 directory located in c8_location /webcontent/samples/datasources. 2. If required, copy the backup files for the samples databases to your database backup directory. To ensure the security and integrity of IBM Cognos 8, copy the files to a directory that is protected from unauthorized or inappropriate access. 3. Restore the samples databases using your database management tool. Tips: For SQL backup files, restore the database from a device, and ensure that the restore locations are correct for the .ldf and .mdf database files. For more information, see the Microsoft SQL Server documentation or the IBM Cognos Knowledge Base on the IBM Cognos Customer Service Center (http://www.ibm.com/software/data/support/cognos_crc.html).

66

Chapter 4: Samples For DB2, when you create the GS_DB database, create a buffer pool with a page size of 16 KB and an associated tablespace.

4. For each database, create at least one user who has select permissions for all the tables in the restored databases. You can now create the data source connections in the portal.

Create Data Source Connections to the Samples Databases

You must create data source connections to the samples databases that you restored. IBM Cognos 8 uses this information to connect to the samples databases and run the sample reports or use the sample package. The DB2 database name that you type must use uppercase letters. Also, in Framework Manager, the schema names that you type for the DB2 data sources must use uppercase letters. Before you create the data source connections, you must restore the backup files for the samples databases. Also, ensure that the IBM Cognos 8 service is running. To create data sources, you must have execute permissions for the Data Source Connections secured feature and traverse permissions for the Administration secured function.

Steps
1. Open IBM Cognos Connection by connecting to the IBM Cognos 8 portal and clicking IBM Cognos Content on the Welcome page. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. Click the Configuration tab. 4. Click the new data source button .

5. In the Name box, type great_outdoors_sales and then click Next. 6. In the connection page, click the type of database that you restored and want to connect to, select an isolation level, and then click Next. The connection string page for the selected database appears. Tip: The user specified in the great_outdoors_sales data source must have select privileges on the tables in each of the GOSALES, GOSALESRT, GOSALESMR, AND GOSALESHR schemas (p. 64). 7. Do one of the following: If you restored the samples databases in SQL Server, in the Server Name box, type the name of the server where the restored databases are located. In the Database name box, type GOSALES. IBM Cognos 8 samples require TCP/IP connectivity with SQL Server. Ensure the SQL Server Security is set to SQL Server and Windows, instead of Windows Only. The samples use SQL Server security for authentication.

Administration and Security Guide 67

Chapter 4: Samples If you restored the samples databases in Oracle, in the SQL*Net connect string box, type the Oracle connection string. If you restored the samples database in DB2, in the DB2 database name box, type GS_DB using uppercase letters. In the DB2 connect string box, type the DB2 connection string. 8. Under Signons, select the both Password and Create a signon that the Everyone group can use check boxes, type the user ID and password for the user that you created when you restored the databases, and then click Finish. Tip: To test whether the parameters are correct, click Test the connection.... 9. Click Finish. 10. Repeat steps 4 to 9 for the GOSALESDW samples database or schema, and type great_outdoors_ warehouse in step 5. 11. If the GOSALES model will be used by modelers in IBM Cognos 8 Transformer, the connection string must be manually added to the cs7g.ini file. For more information, see the Installation and Configuration Guide. The Great Outdoors data source connections appear as entries in Data Source Connections. You can now import the samples unless there is a syntax error in the connection string or an incorrect parameter.

Set Up Microsoft Analysis Services Cube Samples

IBM Cognos Connection or Framework Manager provides sample cubes for Microsoft Analysis Services (MSAS). For finance data, use the GO Finance Fact cube derived from the GOSALESDW database. This cube contains year-to-date and monthly financial data for all accounts so that you can create financial statements in Analysis Studio, Query Studio, and Report Studio. The data is in actual US dollars submissions for 2004, 2005, 2006, or 2007 (7 months actual data only). The MSAS2000 version of the finance cube and database is in the GOFinanceFact_XX.cab file. The MSAS2005 version is in the GOFinanceFact_XX.abf file. XX represents the language. For example, XX is replaced with EN which indicates English. For sales data, use the GOSalesFact cube derived from the GOSalesFact_XX Analysis Services database, based on the GOSALESDW SQLSERVER Database. The cube contains measures such as unit cost, unit price, quantity, and gross profit. Dimensions include Time, Product, and Retailers. The MSAS2000 version of the sales cube and database is archived in the GOSalesFact_XX.cab. The MSAS2005 version is in the GOSalesFact_XX.abf restorable backup file. The backup files are located in the c8_location/webcontent/samples/datasources/cubes/MSAS directory. The files must be restored to a Microsoft SQL Server database running the applicable Microsoft Analysis Services (p. 64). and hosting the GOSALESDW database.

68

Chapter 4: Samples Note: Both Microsoft XML 6.0 Parser and Microsoft SQL 2005 Analysis Services 9.00 OLEDB Provider must be installed on the local client to establish data source connections to MSAS cubes.

Steps
1. On the computer where IBM Cognos 8 is installed, go to the c8_location/webcontent/samples/ datasources/cubes/MSAS/en directory. 2. Copy the GOSALESDW.cab and GOSALESDW.abf files to a directory that you can access from the Analysis Manager console in the Analysis Servers of Microsoft SQL Server. 3. Use the Microsoft Analysis Services Analysis Manager to restore the database from the GOSALESDW.cab and GOSALESDW.abf files. You can now create the data source connections using either the GOSalesFact_XX or GOFinanceFact_XX cubes (p. 70).

Set Up the Essbase Cube Sample

To set up the Essbase cube sample, you must have Hyperion Essbase and Essbase Integration Services Console installed. Alternatively, you can set up the smaller Essbase cube GODBReduced.zip which is a filtered version of the full version, GODWENU. To set up the small version, unzip GODBReduced.zip, load the OTL and txt file in the Essbase environment, and perform the same steps shown below.

Steps
1. Go to the c8_location\webcontent\samples\datasources\cubes\Essbase\Outlines_and_Raw_Data directory. This directory contains zip files for the different languages, such as EN.zip or JA.zip for English and Japanese, respectively. 2. Unzip the file for your language. Each zip file contains the following two files: languageU_Data.txt, such as ENU_Data.txt or JAU_Data.txt. GODWlanguageU.otl, such as GODWENU.otl or GODWJAU.otl.

3. Using block storage in Essbase, create a Unicode application. 4. Within the application, create a new database. You can use GODWlanguageU, such as GODWENU or GODWJAU, as your database name, or use the name of your choice. 5. Copy and paste the GODWlanguageU.otl file in your database directory. 6. If the database name specified in step 4 is different than GODWlanguageU, rename the GODWlanguageU.otl file to match the database name that you created. Confirm that you want to overwrite the .otl file.

Administration and Security Guide 69

Chapter 4: Samples 7. In Essbase Administration Services console, open your database outline and save it. Confirm that you want to save the outline even if it was not changed. 8. Copy the languageU_Data.txt file and paste it in the same directory as the .otl file. 9. In Essbase Administration Services console, right-click the database you created and select Load Data. 10. Browse to the languageU_Data.txt file in your database directory, select the file, and click OK. 11. After the data loads successfully, right-click the database and select Execute Calculation. 12. Select the default calculation, and click OK. The calculation process may take up to 5 hours, depending on the computer where Essbase OLAP Server is installed. You can now create a data source connection to the cube.

Create Data Source Connections to OLAP Data Sources

IBM Cognos 8 provides the following OLAP samples: GO Sales Fact and GO Finance Fact Microsoft Analysis Services cubes Great Outdoors Company cube Great Outdoors DB2 cube

You must create data source connections to the cubes to use the samples. You must set up the Microsoft Analysis Services cube samples or set up the Essbase cube sample, if you are using them, before creating data source connections. You can increase the read cache size to improve query performance, although this setting has no effect on the initial time required to open a cube. To create data sources, you must have execute permissions for the Data Source Connections secured feature, and traverse permissions for the Administration secured function.

Steps for PowerCubes

1. Open IBM Cognos Connection by connecting to the IBM Cognos 8 portal and clicking IBM Cognos Content on the Welcome page. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Configuration tab, click Data Source Connections. 4. Click the new data source button. Note: You must add a data source connection for each cube. 5. To create a data source connection for the Sales and Marketing cube, type sales_and_marketing in the Name box, and then click Next. You can define a Windows path or a UNIX path.

70

Chapter 4: Samples If you define a UNIX path and you plan to use Framework Manager, you must also define the Windows path and ensure that the cube is also available in the Windows location. Framework Manager can access cubes only from Windows locations. 6. In the connection page, under Type click IBM Cognos PowerCube. The connection string page for the selected database appears. 7. In the Read cache size (MB) box, type the cache size of the cube in megabytes. If you leave this field blank or type 0, IBM Cognos Connection uses the default value in the ppds_cfg.xml file in the configuration folder. 8. In the Windows location box, type the location and name of the Sales_and_Marketing.mdc file for the data source connection. For example, type c8_location/webcontent/samples/datasources/cubes/PowerCubes/En/Sales_and_Marketing. mdc 9. To test whether the parameters are correct, click Test. 10. Click Finish. You can now import the sample package for the PowerCube to use this data source.

Steps for Essbase/DB2 Cubes

1. Open Framework Manager. 2. Click Create a new project. 3. In the New Project page, specify a name and location for the project. 4. In the Select Language page, click the design language for the project. 5. Click OK. The Metadata wizard appears. 6. In the connection page, under type click Hyperion Essbase/IBM DB2 OLAP Server, select an isolation level, and then click Next. The connection string page for the selected database appears. 7. In the Server name box, type the name of the server. 8. To test whether the parameters are correct, click Test. 9. Click Finish. To use this data source, you must create a package using this data source in Framework Manager, and then publish the package.

Steps for Microsoft Analysis Service Cubes

1. Open IBM Cognos Connection by connecting to the IBM Cognos 8 portal and clicking IBM Cognos Content on the Welcome page.

Administration and Security Guide 71

Chapter 4: Samples 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Configuration tab, click New Data Source. 4. In the Name box, type the name of the data source connection, and then click Next. For the GOFinanceFact cube, type GOFinanceFact_XX_MSAS2005. For the GOSalesFact cube, type GOSalesFact_XX_MSAS2005.

5. In the Specify Connection page of the New Datasource Wizard, click Microsoft Analysis Services 2005 or click Microsoft Analysis Services (via ODBO) as appropriate to the cube you are accessing. 6. Click Next. 7. In the Server Name box, type the name of the server where the restored databases are located. Back slashes are not required. 8. Under Signon, select the Password check box and then select the Create a signon that the Everyone group can use check box. Type the user ID and password for the MSAS database. For MSAS2005, this is a network login. 9. Click Test the connection, and then click the Test button. Click Close. 10. Click Finish. You are now prompted to create a package. Alternatively, you can deploy an existing package from a sample deployment archive. The names of the deployment archives match the datasource connection names specified in step 4 and contain sample reports that work with the associated cubes. In Content Administration on the Configuration tab in IBM Cognos Administration, click New Import. The New Import Wizard prompts you to select a deployment archive. When you select a deployment archive, it is important to click Edit and specify a target name for the package to prevent an existing package from being overwritten. 11. To create a package, check Create a Package and then click OK. 12. Specify a package name and then click OK. For the GO Finance Fact cube, type GOFinanceFact_XX_MSAS2005. For the GO Sales Fact cube, type GOSalesFact_XX_MSAS2005.

13. Specify the Analysis Services database you restored either GOFinanceFact_XX or GoSalesFact_XX: For either the GOFinanceFact cube or the GOSalesFact cubes, type GOSALESDW. For the GO Sales Fact cube, type GO Sales Fact.

14. Click the cube applicable to the database. 15. Click Finish.

72

Chapter 4: Samples

Set Up the Metric Studio Sample

To set up the Metric Studio sample, do the following: Create a metric store named GOMETRIC. For more information about creating a metric store, see the IBM Cognos 8 Installation and Configuration Guide. Create a new metric package named GO Metrics that uses the GOMETRIC metric store. For the data source name, type go_metrics. When prompted by the wizard, select the standard Gregorian calendar and accept the defaults for Years, Quarters, and Months. Select January 1, 2004 as the start date for a period that includes the current year. For example, if it is the year 2008, use a period of at least 5 years. For more information, see "Create a Metric Package" (p. 391). Set the import source. Import the metric data and files into the metric store.

Steps to Set the Import Source

1. Copy all text files from the appropriate folder to the folder c8_location/deployment/cmm: For SQL Server or Oracle, copy from c8_location/webcontent/samples/datasources/ metricsdata/GO_Metrics_Unicode For DB2, copy from c8_location/webcontent/samples/datasources/metricsdata/GOMetrics_UTF8

Tip: You may need to create the cmm folder. 2. In Public Folders, click GO Metrics. 3. In Metric Studio, in the Tools list, click Import Sources. 4. Click the Set Properties icon in the Actions column next to the Default Import Source. 5. Under Metric Deployment Location, click cmm folder. This is the default deployment location. 6. Click Include sub-directories. 7. In the File format box, click 8.4.2. 8. Under Character Set Encoding, select the appropriate encoding and click OK. For SQL Server or Oracle, select Unicode (UTF-16) For DB2, select Unicode (UTF-8)

You can now use the GO Metrics package in Metric Studio.

Steps to Import Metric Data and Files into the Metric Store
1. Choose whether to import the files into the metric store using IBM Cognos Connection or Metric Studio: Administration and Security Guide 73

Chapter 4: Samples To use IBM Cognos Connection, in Public Folders or My Folders, open the GO Metrics package by clicking the view metric package contents icon in the Actions column. Click Metric Maintenance. To use Metric Studio, in Metric Studio, in the Tools list, click Metric Maintenance.

2. Click the Import and transfer data from files into metric store metric task. Tip: If an error occurs, click Clear staging area rejected data logs, Clear metric history data only, and Clear metric history and calendar data. You can now use the GO Metrics package in Metric Studio.

Import the Samples

To use the sample package and other content, you must import them from the sample deployment archive. Before you import the Cognos_Samples.zip and Cognos_Metrics.zip deployment archives, you must restore the databases (p. 64). You must also create data source connections to the samples databases (p. 67). Before you import the Cognos_PowerCube.zip or Cognos_PowerCube_Financial.zip deployment archive, you must create a database connection to the appropriate PowerCube and select the language that you want to use. The language that you select must be supported by your locale. For more information about locales, see the IBM Cognos 8 Installation and Configuration Guide.

Steps
1. Copy the zip file from the c8_location/webcontent/samples/content directory to the directory where your deployment archives are saved. The default location is c8_location/deployment. The location is set in the configuration tool. For information about changing the location, see the configuration tool online help. 2. Open IBM Cognos Connection by connecting to the IBM Cognos 8 portal and clicking IBM Cognos Content on the Welcome page. 3. In the upper-right corner, click Launch, IBM Cognos Administration. 4. On the Configuration tab, click Content Administration. Note: To access this area in IBM Cognos Administration, you must have the required permissions for the Administration tasks secured feature. 5. On the toolbar, click the new import button. The New Import wizard appears. 6. In the Deployment Archive box, select Cognos_Samples, Cognos_PowerCube, Cognos_Metrics, or Cognos_Audit. 7. Click Next.

74

Chapter 4: Samples 8. Type a unique name and an optional description and screen tip for the deployment archive, select the folder where you want to save it, and then click Next. 9. In the Public Folders Content box, select the packages and folders that you want to import. The Cognos_Samples deployment archive has the following packages or folders: GO Data Warehouse (analysis), GO Data Warehouse (query), GO Sales (analysis), GO Sales (query), Sales and Marketing (conformed) Dashboard Folder, Dashboard Objects, Sample Template, Practical Examples

The Cognos_PowerCube deployment archive has packages or folders for the following languages: English French German Japanese Simplified Chinese

The GO_Metrics deployment archive has the following packages or folders: GO Metrics

10. Select the options you want, along with your conflict resolution choice for options that you select, and then click Next. 11. In the Specify the general options page, select whether to include access permissions and references to external namespaces, and who should own the entries after they are imported. 12. Click Next. The summary information appears. 13. Review the summary information and click Next. 14. Select the action that you want: To run once now or later, click Save and run once. Click Finish, specify the time and date for the run, then click Run. Review the run time and click OK. To schedule at a recurring time, click Save and schedule. Click Finish, and then select frequency and start and end dates. Click OK. Tip: To temporarily disable the schedule, select the Disable the schedule check box. To save without scheduling or running, click Save only and click Finish.

15. When the import is submitted, click Finish. You can now use the sample packages to create reports and analyses in Report Studio, Query Studio, and Analysis Studio, view extracts in Metric Designer, or create agents in Event Studio. You can also run the sample reports that are available on the Public Folders tab in the portal.

Administration and Security Guide 75

Chapter 4: Samples

Sample Database Models

The following sample models provide information for the fictional company, the Great Outdoors and are provided with IBM Cognos 8: great_outdoors_sales, which refers to the samples database GOSALES great_outdoors_warehouse, which refers to the database GOSALESDW gosales_scriptplayer, which refers to the samples databases GOSALES

You can use sample database models on different platforms. For information about moving models from one platform to another, see the Framework Manager User Guide. Note: Transformer 8 uses some of the reports in the GO Data warehouse (query) package and GO Sales (query) package as source data for various cubes. These reports are meant to be simple list reports with no formatting. The description information for the reports indicates if the report was developed to be source data for Transformer 8.

GO Sales Model
This model contains sales analysis information for the fictional company, The Great Outdoors. It also has the query items required by the Event Studio samples. The model accesses three schemas and has two packages. One package is based on the dimensional view and the other is baed on the query (relational) view.

GO Data Warehouse Model

This model contains financial, human resources, and sales and marketing information for the fictional company, The Great Outdoors. The model accesses a dimensional relational data source. The model has two packages. One package is based on the dimensional view, the other is based on the query (relational) view.

GO Sales Scriptplayer
These files can be used to run the action logs in sequence. This action generates a model named gosales_scriptplayer, and publishes a package to the content store.

Example - Running the Sample ELM Returns Agent Against Changed Data
You can change data in the GOSALES database if an Event Studio user wants to test the sample agent ELM Returns Agent. The Event Studio user can then run the sample agent twice and detect a new event. For more information, see the Event Studio User Guide. Running the sample agent against changed data involves the following steps: The Event Studio user runs the sample agent against the default data and then asks you to change the data. You simulate the occurrence of some initial events and then ask the Event Studio user to run the sample agent a second time. The Event Studio user runs the sample agent against the changed data. The Event Studio user informs you when the agent has completed running.

76

Chapter 4: Samples You simulate the passage of time and the resolution of some events and then ask the Event Studio user to run the sample agent a third time. The Event Studio user runs the sample agent for the final time. The Event Studio user informs you when the agent has completed running. You modify the data so that the ELM Returns Agent detects no events.

Example - Simulate the Occurrence of Initial Events

Run part of the Event_Studio_ELM_Agent_Modify_GOSALES.sql script to simulate the following data changes: change the date to the current date change the follow-up code to -1 in four records. A code of -1 indicates that follow-up is required.

Steps
1. In SQL Query Analyzer, from the File menu, click Open. 2. Go to c8_location/webcontent/samples/datasources/sqlserver and double-click the Event_Studio_ ELM_Agent_Modify_GOSALES.sql file. 3. In the toolbar, from the list of databases, click GOSALES. 4. In the Query window, under Part 1, select all sixteen lines of code. 5. From the Query menu, click Execute. The database is updated with the changes.

Example - Simulate the Passage of Time and the Resolution of Some Events
Run part of the Event_Studio_ELM_Agent_Modify_GOSALES.sql script to simulate data changes. First, change it so that two days elapsed since the ELM Returns Agent sample was last run. Second, for three of the four event instances found the last time that the ELM Returns Agent sample ran, change the follow-up code from -1 to +1. This indicates that only one of the these event instances still requires follow-up and the other instances are resolved.

Steps
1. In SQL Query Analyzer, from the File menu, click Open. 2. Go to c8_location/webcontent/samples/datasources/sqlserver and double-click the Event_Studio_ ELM_Agent_Modify_GOSALES.sql file. 3. On the toolbar, click GOSALES from the list of databases. 4. In the Query window, under Part 2, select all lines of code that appear after the comments. 5. From the Query menu, click Execute. The database is updated with the changes.

Administration and Security Guide 77

Chapter 4: Samples

Example - Modify the Data So That the ELM Returns Agent Detects No Events
When the Event Studio user finishes running the sample ELM Returns Agent against changed data, they should notify you. You can then modify the GOSALES database so that the agent no longer detects any event instances.

Step
Run the following sql commands: UPDATE GOSALES.RETURNED_ITEM SET FOLLOW_UP_CODE = 0 UPDATE GOSALES.RETURNED_ITEM SET ASSIGNED_TO = 0 UPDATE GOSALES.RETURNED_ITEM SET DATE_ADVISED = NULL The data is modified. The sample ELM Returns Agent is ready to be used by another Event Studio User.

Remove the Samples Databases from IBM Cognos 8

After you finish using the sample reports to learn about IBM Cognos 8, including Framework Manager, you can delete the packages on which the samples are based. This action permanently removes the samples from the content store.

Steps
1. Open IBM Cognos Connection by connecting to the IBM Cognos 8 portal and clicking IBM Cognos Content on the Welcome page. 2. Click the Public Folders tab. 3. Select the check box for the sample package you want to delete. 4. Click the delete button on the toolbar, and click OK. To use the samples again, you must set up the samples.

78

Chapter 5: Setting up Logging

Log messages are an important diagnostic tool for investigating the behavior of IBM Cognos 8. In addition to error messages, log messages provide information about the status of components and a high-level view of important events. For example, log messages can provide information about attempts to start and stop services, completion of processing requests, and indicators for fatal errors. Audit logs, which are available from a logging database, provide information about user and report activity. The IBM Cognos 8 services on each computer send information about errors and events to a local log server. A local log server is installed in the c8_location/logs folder on every IBM Cognos 8 computer that contains Content Manager or Application Tier Components. Because the log server uses a different port from the other IBM Cognos 8 components, it continues to process events even if other services on the local computer, such as the dispatcher, are disabled. The following workflow shows the tasks that are required to prepare for logging.

Set up logging Plan log message processing Configure logging

During planning, determine the logging configuration that is suitable for your environment. For example, evaluate various log message destinations, such as remote log servers and log files, such as the UNIX or Linux syslog or the Windows NT Event log, in addition to the local log file. You can also send only audit logging information to a database. Consider security, such as methods available for protecting log files from system failures and user tampering. For information about planning, see the Architecture and Deployment Guide. During configuration, define the startup properties for logging, such as connection settings for databases. You must also create a logging database if you plan to collect audit logs. If communication between a local log server and a remote log server must be secured, make the appropriate configuration changes on both IBM Cognos 8 computers. For information about configuring logging, see the Installation and Configuration Guide. When setting up logging, specify the level of detail to log to focus messages on the information that is relevant in your organization. Audit reports may also be set up to track user and report activity. For information about setting up logging, see the Administration and Security Guide.

For information about using log messages to solve problems and resolving logging-related issues, see the Troubleshooting section of the Administration and Security Guide. You can perform the following tasks to set up logging: set logging levels (p. 82) set up audit reporting (p. 82) view full details for secure error messages (p. 88) Administration and Security Guide 79

Chapter 5: Setting up Logging disable the creation of core dump files (p. 89)

Log Messages
You specify the location of the log messages and the size and number of log files, and configure the properties of the log server in the configuration tool. By default, log messages are saved to the cogserver.log file located in c8_location/logs. They can also be saved in a database. For more information, see the Installation and Configuration Guide. For more information about the log service, see "Dispatchers and Services" (p. 105).

Logging Levels
You set logging levels to specify the events and messages to record in the log file or in the log database. An event is an occurrence in your IBM Cognos 8 environment that is significant enough to be tracked, such as starting or stopping a service. You can set a different logging level for each dispatcher service. You can do this for each dispatcher or for all dispatchers in the same folder. By setting different logging levels for different services you can reduce the amount of irrelevant logging information. For example, if you must troubleshoot the batch report service, you can select a detailed logging level for just that service, keeping log messages to a minimum. The logging level for a service applies to all its components. Note: The log service does not have logging levels associated with it. The following table indicates the details that each logging level logs.

Details
System and service startup and shutdown, runtime errors User account management and runtime usage of IBM Cognos 8 Use requests Service requests and responses All requests to all components with their parameter values

Minimal

Basic

Request

Trace

Full

80

Chapter 5: Setting up Logging

Details
other queries to IBM Cognos 8 components (native query)

Minimal

Basic

Request

Trace

Full

You can maintain system performance by managing the amount of logging performed by the server. Since extensive logging affects server performance, increasing the logging level may negatively affect the performance of IBM Cognos 8. The default logging level is Minimal. Use Full logging level only for detailed troubleshooting purposes because it may significantly degrade server performance.

Report Validation Levels and Logging Levels

You can collect information about report validation levels by setting the corresponding logging level. Report validation messages can be included in system log messages. You can use the validation information in different ways. If the system is delivering a generally poor response, you can set logging to a higher level. The additional information can help you determine which reports are at fault and why. If you see warning messages in the logs, this may mean that users are receiving questionable results. You can alert the owners of the offending reports. There are four report validation levels and five logging levels. The following table shows the correspondence between them.

Report validation level

Error Warning Key Transformation Information

Logging level
Minimal, Basic Request Trace Full

The higher you set the logging level, the more it degrades system performance. Normally, you set the level to Minimal or Basic to collect errors, or to Request to collect errors and warnings. For information about reports and report validation, see the Report Studio Professional Authoring User Guide.

Native Query Logging

If you want to create audit reports (p. 82) that include the queries that are run against your reporting data source, you must enable native query logging. You can use native query logging to learn what kinds of information users want or whether a report is running efficiently.

Administration and Security Guide 81

Chapter 5: Setting up Logging Native query logging is part of Request level logging. However, if you are using audit reports, you can enable native query logging independently from Request level logging, as described in the following steps. For information on setting logging levels for audit reports, see "Audit Reports" (p. 82).

Set Logging Levels

You set logging levels to specify the events and messages to record in the log file or in the log database. An event is an occurrence in your IBM Cognos 8 environment that is significant enough to be tracked, such as starting or stopping a service. For more information, see "Logging Levels" (p. 80). Logging levels that you set for the system apply to all dispatchers and services. Logging levels that you set at the dispatcher level apply to all services that are associated with the dispatcher. Logging levels that you set for individual services apply to the service across all dispatchers. Logging levels that are set for dispatchers override logging levels that are set for the system level. Logging levels that are set for services override logging levels that are set for dispatchers or the system. You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper left corner of the Scorecard pane, click the arrow to view the Change view menu, and then click All servers, All server groups, All dispatchers, or Services, depending on where you want to set logging levels. 5. Click the arrow next to the item to view the Actions menu, and then click Set properties. For example, to set logging levels for the system, click the arrow next to the Actions menu. 6. Click the Settings tab. 7. From the Category menu, click Logging. 8. From the Value menu, select the logging level you want for the service. 9. If native query logging (p. 81) is available for the service and you want to use it, select the audit the native query check box. 10. Click OK.

Audit Reports
You use audit reports to view the information in a logging database about user and report activity.

82

Chapter 5: Setting up Logging The information in this section is intended to help you model the audit logging database in FrameWork Manager and create reports based on your logging data. First, you must set up audit reporting (p. 83). You may want to refer to the sample model and sample audit reports (p. 83) to help you create audit reports. For information on the database schema for audit reports, see "Data Schema for Log Messages" (p. 749).

Setting Up Audit Reporting

Before you can create audit reports or use the sample audit reports that come with IBM Cognos 8, you must set up audit reporting. Direct log messages to a database. Set up a logging database and configure log messages to be sent to the database. For information about configuring log messages, see the Installation and Configuration Guide. Important: The logging database must be separate from the Content Store database. Set the logging level for audit reports. Set the logging level to Basic or higher. Do not set the logging level to Full, which will log too much information. For more information, see "Set Logging Levels" (p. 82). Enable native query logging (p. 81).

Sample Audit Model and Audit Reports

IBM Cognos 8 includes a sample model and sample audit reports that you can use.

Sample Audit Model

IBM Cognos 8 includes a sample audit model in Framework Manager. The default location is c8_location/webcontent/samples/Models/Audit/Audit.cpf.

Sample Audit Reports

The following table lists the sample audit reports and describes the content of each report. Before you can use them, you must set up the sample audit reports (p. 87).

Audit report name

Agent execution history by user

Description
Lists agent execution history by user and date and time range and includes a bar chart. It also includes the total number of times each agent was executed and the total number of agents that were executed. You can select a date and time range.

Administration and Security Guide 83

Chapter 5: Setting up Logging

Audit report name

Description

Daily average and poor exceptions - Shows how to monitor daily average and poor exceptions all services of thresholds set in IBM Cognos Administration for all services using an agent. An email with attached report output is sent to the administrator when average and poor exceptions occur. To run this report properly, you must first set thresholds in IBM Cognos Administration (see "System Performance Metrics" (p. 91)). To receive an email, you must specify a mail server account. For more information, see the IBM Cognos 8 Installation and Configuration Guide For more information on setting thresholds in IBM Cognos Administration, see "System Performance Metrics" (p. 91). Daily metric exceptions Execute reports by package and report Lists daily metric exceptions for all services. Lists the reports that were run, by package. It also includes the user, timestamp, and execution time in milliseconds for each report. You can select a date and time range, one or more users, one or more packages, and one or more reports. Execute reports by user Lists the reports that were run, by user and by package. It also includes the timestamp and execution time in milliseconds for each report. You can select a date and time range, one or more users, one or more packages, and one or more reports. Execution history by user Lists the reports that were run alphabetically, along with the package and timestamp, by user, since the logging database was created. It includes the total number of reports each user ran and the total number of times each user ran each report. It also includes the total number of reports run by all users. You can select one or more users for the report. After you run the audit report, you can choose to view the statistics for a particular report or for all reports. Failed report executions - by package Lists report failure executions by package and includes a pie chart, which also shows the failed percentage of each package.

84

Chapter 5: Setting up Logging

Audit report name

Description

Failed service requests detect agent - Detects preset thresholds for service request failures that all services are exceeded. An email is sent to the administrator with service failure metrics information. The report Service requests metrics day report is run. To run this report properly, you must first set thresholds in IBM Cognos Administration (see"System Performance Metrics" (p. 91)). To receive an email, you must specify a mail server account. For more information, see the IBM Cognos 8 Installation and Configuration Guide. Logon operations by time stamp Shows logon and logoff timestamps and operations, by user. It also includes the total number of logons and the total number of logons for each user. You can select the time period and one or more users for the report. Logon operations by user name Shows logon and logoff timestamp by user, along with the type of logoff operation that occurred. It includes the total number of logons and the total number of logons for each user. You can select one or more users for the report. Migration exceptions Operations by selected object and users A list report shows exceptions for migration tasks. Shows the operations that are performed on target objects, by user. It includes the target object path, timestamp, and the status of the operation. You can select one or more objects, operations, or users for the report. Report execution history (detailed report) Lists reports alphabetically along with the associated package and the timestamp for each time the report was executed. It also shows the total number of times each report was executed and the total number of reports that were executed. It also includes a color-coded pie chart that gives an overview of how often the reports are used.

Administration and Security Guide 85

Chapter 5: Setting up Logging

Audit report name

Report execution history (summary report)

Description
Lists reports alphabetically along with the timestamp for each time the report was run since the logging database was created. Lists reports by frequency of use. For each report, it lists the user and the number of times it was run by the user since the logging database was created. This report can help you determine if there are any reports that are not being used. If so, you may want to remove them.

Report usage

Service requests metrics - day report Shows percentage of successful and failed requests for IBM Cognos services for the current day. Includes a bar chart. User session - abnormal termination Shows logon date and time of abnormally terminated user sessions. It also includes a total of session termination for all dates. You can select a date and time range. User session - details Shows user session details, including the logon time, logoff time, logoff operation, and session duration. It also includes the total amount of session time for each user and the total amount of session time for all users. You can select a date and time range and one or more users. User session - logon errors for past 30 days chart User session - summary This audit report shows a bar graph of logon failures for the past 30 days. This audit report shows the average session duration by user. It also shows the total average session duration by user. You can select a date and time range and one or more users. View reports by package and report This audit report lists users and timestamps for reports for the package that you select. You can select a date and time range, one or more users, and one or more reports.

86

Chapter 5: Setting up Logging

Setting Up the Sample Audit Reports

You must set up sample audit reports before you can use them. Before you begin, see "Setting Up Audit Reporting" (p. 83) Create a data source connection to the logging database. The logging database and data source in IBM Cognos Connection must be named Audit. Follow the procedure "Add or Modify a Data Source Connection" (p. 183). For the data source name and database name, enter the name Audit. Confirm that the connection is working. "Set Up the Sample Report Usage Audit Report" (p. 87) to create new data source named url_xml and using the URL as the connection string. This data source is only used by the Report Usage audit report. Import the sample audit reports. The file Cognos_Audit.zip is included with your installation and is located at c8_location/ webcontent/samples/content. Copy the file to c8_location/deployment, and then follow the procedure "Import the Samples" (p. 74) Cognos_Audit. In the public folders content list, select the check box for Audit. The audit reports reside in the Public Folders area of IBM Cognos Connection. Run the sample audit reports. Tip: In IBM Cognos Connection, click Public Folders, click Audit, and click the audit report that you want to run. Depending on the audit report that you select, you are prompted for report criteria.

Set Up the Sample Report Usage Audit Report

The Report Usage Audit Report lists reports by frequency of use. Before it can be used, it must be set up.

Steps
1. In a text editor, open the web.xml file located at c8_location/webapps/p2pd/web-inf, and add the following XML fragment:
<servlet> <servlet-name>DSServlet</servlet-name> <servlet-class>com.cognos.demo.DSServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>DSServlet</servlet-name> <url-pattern>/cognos/DSServlet.jsp</url-pattern> </servlet-mapping>

Note that the url-pattern value can be anything you choose. 2. If you do not have the following directory on your system, create it: c8_location/webapps/p2pd/ web-inf/classes/com/cognos/demo. 3. Copy the file build.bat for Windows or build.sh for UNIX located in c8_location/webapps/Audit to c8_location/webapps/p2pd/web-inf/classes/com/cognos/demo. Administration and Security Guide 87

Chapter 5: Setting up Logging Edit the build file to ensure the JAVA_HOME definition points to your JDK and ensure the CRN_HOME definition points to your IBM Cognos 8 location. 4. If it is not already there, copy the DSServlet.java file from the c8_location/webapps/Audit directory to c8_location/webapps/p2pd/web-inf/classes/com/cognos/demo. 5. Do one of the following in the DSServlet.java file: If you are allowing anonymous logon, comment out the following line:
binding.logon(...)

If you are not allowing anonymous logon, make sure that the username, password, and namespace are correct and uncomment the following line: binding.logon(...)

6. At a command prompt, run build.bat or build.sh from c8_location/webapps/p2pd/web-inf/ classes/com/cognos/demo. 7. Restart IBM Cognos 8 and open IBM Cognos Connection. 8. Create a data source connection to the XML data source by doing the following: In the upper-right corner, click Launch, IBM Cognos Administration. On the Configuration tab, click New Data Source. Under Name, type url_xml. Click Next. Under Type, select XML. Click Next. In the Connection string field, enter the connection string. If you used the defaults, the connection string is http://localhost:9300/p2pd/cognos/DSServlet.jsp. Click OK.

View Full Details for Secure Error Messages

Some IBM Cognos 8 error messages may contain sensitive information such as server names. By default, the IBM Cognos Application Firewall secure error messages option is enabled. Users are presented with information that indicates only that an error has taken place. For more information, see "Filtering of Error Messages" (p. 205). If you have the appropriate permissions, you can retrieve full error details, which may contain sensitive information. You may also want to see log messages (p. 80).

Steps to retrieve the full error details

1. Find the error code ID in the user error message. For example, the error number in the following message is secureErrorID:2004-05-25-15:44:11.296-#9:

88

Chapter 5: Setting up Logging An error has occurred. Please contact your administrator. The complete error has been logged by CAF with SecureErrorID:2004-05-25-15:44:11.296-#9 2. Open the cogserver.log file using a text editor. The file is located in c8_location/logs. 3. Search for the error code ID to locate the applicable error message.

Disable the Creation of Core Dump Files

Core dump files are created when there is a serious problem, such as an unhandled exception or when an IBM Cognos 8 process terminates abnormally. Since core dump files are big and a new one is created each time the problem recurs, you may want to disable them. You can enable core dump files again if you encounter problems that require it. If such a problem occurs, you receive the following error message: Report Server not responding. See the Troubleshooting section in the Administration and Security Guide immediately. You may also want to delete any existing core dump files from the \bin directory of the IBM Cognos 8 server installation, if they are not required for troubleshooting purposes. In a Windows environment, core dump files have a .dmp extension and the file name processID.dmp, such as BIBusTKServerMain_seh_3524_3208.dmp. In a UNIX environment, the files are named core. In a Linux environment, the files are named core.processID. In some IBM Cognos 8 hotsite builds, core file creation is automatically enabled. The configuration file that controls this is different for IBM Cognos 8.1 MR1 and later versions of the product. During an upgrade, configuration settings are not overwritten.

Steps to Turn Off Core File Creation for IBM Cognos 8.1 MR1
1. On the server where IBM Cognos 8 is installed, open the rsvpproperties.xml file from the c8_location\configuration directory. 2. Change the Win32StructuredExceptionHandling property to 0 (zero) so that it reads
<property>Win32StructuredExceptionHandling</property> <value type="long">0</value>

3. Save the file.

Steps to Turn Off Core File Creation for IBM Cognos 8.1 MR2 and Later Versions
1. On the server where IBM Cognos 8 is installed, open the cclWin32SEHConfig.xml file from the c8_location\configuration directory. 2. In the configuration element, change the value of the environment variable setting to 0 (zero) so that it reads
<env_var name="CCL_HWE_ABORT" value="0"/>

3. Save the file.

Administration and Security Guide 89

Chapter 5: Setting up Logging

90

Chapter 6: System Performance Metrics

You can monitor system performance using metrics in IBM Cognos Administration, which allows you to diagnose and fix problems quickly. For example, you may want to know if there are more than 50 items in a queue or if any item has been waiting in a queue for longer than a specified amount of time. You must have the required permissions to access IBM Cognos Administration functionality "Secured Functions and Features" (p. 221). You can assess the status of the system as a whole, along with the status of individual servers, dispatchers, and services (p. 92). You can view the attributes for each metric score, set the threshold values (p. 101) that are used to calculate metric scores (p. 101), and reset metrics (p. 103). You can also perform functions such as starting and stopping dispatchers or services (p. 108), and unregistering dispatchers (p. 111). You can use log files to analyze long-range performance and usage (p. 79). You can create a metric dump file for troubleshooting purposes "Metric Dump File" (p. 543).

How Metric Data is Gathered

Data for metrics is gathered differently depending on the metric change type, time scope, and gathering time associated with the metric. For more information on how these apply to individual metrics, see "System Metrics" (p. 92).

Metric Change Type

The value that is displayed for a metric depends on the change type, as shown in the following table.

Change Type
Counter

Description
The value is a sum that increases with each change. For example, number of requests is a counter change type. The value may increase or decrease over time, depending on events. For example, the number of processes running at any time is a gauge change type.

Gauge

Metric Time Scope

The interval over which a metric value is gathered differs by metric, as shown in the following table.

Administration and Security Guide 91

Chapter 6: System Performance Metrics

Time Scope
Point in time

Description
The value is gathered at a specific point in time, such as when you reset a metric group or restart a service The value is gathered over the interval since the last reset of the metric

Since reset

Metric Gathering Time

The time at which a metric value is gathered differs by metric, as shown in the following table.

Gathering Time
On change

Description
The value is collected when a change occurs, such as when the number of requests changes The value is gathered when you select a new item in the Scorecard pane (p. 99), or reset a metric group (p. 103) The gathering time is unknown

On demand

Unknown

System Metrics
There are a wide variety of metrics available to help you monitor the performance of your IBM Cognos 8 installation. They are listed in the following table with the type of entry they apply to, a description, and the associated change type, time scope, and gathering time (p. 91). Some metrics are reset when the service restarts. You can also reset some metrics manually (p. 103). At the system and server levels, the metrics include all associated dispatchers. At the dispatcher level, metrics include all associated services. For server groups, metrics are for all the dispatchers in the group.

Session Metrics
You can use session metrics to monitor user sessions. This is useful for monitoring system trends such as usage patterns by time of day and day of week. Session metrics are also useful for understanding the context of other metrics. For example, if the number of sessions is extraordinarily high, it could account for the queue length metrics (p. 93) being higher than normal.

Metric

Entry

Description

Change Type

Time Scope Gathering Time

Point in time On demand

Number of Sessions System

The number of currently active Gauge user sessions

92

Chapter 6: System Performance Metrics

Metric

Entry

Description

Change Type

Time Scope Gathering Time

Since reset On change

Number of sessions System high watermark

The maximum number of act- Gauge ive user sessions since the last reset The minimum number of active Gauge user sessions since the last reset

Number of sessions System low watermark

Since reset

On change

Queue Metrics
You can use queue metrics to determine if the system is keeping up with demand. For example, if requests spend too long in a queue, you may not have enough resources to meet demand. There are queue metrics for services that use queues: report service and report data service. There are also queue metrics at the system level for the following things: Job queue, which contains metrics related to the internal queue used by all event management services. Task queue, which contains metrics related to the internal queue used by all monitor services. This queue contains tasks until they are successfully completed. SMTP queue, which contains metrics related to the internal queue used by all delivery services. This queue contains emails until they are sent.

Some of the metrics available for these queue metric groups must be enabled to be displayed. For more information, see (p. 153).

Metric

Entry

Description

Change Time Scope Gathering Type Time

Since reset On change

Latency

System Server/Server group Service

The average amount of time that Gauge requests have spent in the queue (in seconds).

Number of queue requests

System Server/Server group Service

The number of requests that have passed through the queue

Counter Since reset

On change

Administration and Security Guide 93

Chapter 6: System Performance Metrics

Metric

Entry

Description

Change Time Scope Gathering Type Time

Gauge Point in time On demand

Queue length

System Server/Server group Service

The number of items currently in the queue

Queue length high System watermark Server/Server group Service Queue length low watermark System Server/Server group Service Time in queue System Server/Server group Service Time in queue high System watermark Server/Server group Service Time in queue low System watermark Server/Server group Service

The maximum number of items Gauge in the queue since the last reset

Since reset

On change

The minimum number of items Gauge in the queue since the last reset

Since reset

On change

The cumulative amount of time Counter Since reset that requests have spent in the queue (in days, hours, minutes, and seconds)

On change

The maximum length of time Gauge that a request waited in the queue (in days, hours, minutes, and seconds)

Since reset

On change

The minimum length of time Gauge that a request waited in the queue (in days, hours, minutes, and seconds)

Since reset

On change

JVM Metrics
You can use JVM metrics to monitor the Java Virtual Machine and associated heap size (the amount of memory that is currently in use). For example, if a dispatcher has been running for a long time and heap usage is high, you may want to restart it. The maximum heap size metric tells you if you have allocated a suitable amount of memory to the JVM based on the amount o hardware memory available. The current heap size, in relation to the maximum heap size, lets you know if available memory is being used. If current heap size is close to the maximum heap size, you may want to

94

Chapter 6: System Performance Metrics adjust tuning settings (p. 127) to reduce the load on a particular JVM. Keep in mind that current heap size may vary widely depending on the current load on the system.

Metric

Entry

Description

Change Type

Time Scope

Gathering Time

Current heap size (bytes) Initially requested heap size (bytes)

Dispatcher

The current size of the JVM heap Gauge (in bytes) The initial amount of memory that the JVM requests from the operating system during startup (in bytes) Gauge

Point in time On demand

Dispatcher

Point in time On demand

Maximum heap size (bytes)

Dispatcher

The maximum amount of Gauge memory that can be used by the JVM (in bytes) The length of time that the JVM Counter has been running (in days, hours, minutes, and seconds) At the system, server, and server group levels, this is the highest value from all associated dispatchers.

Point in time On demand

Up time

System Server/Server group Dispatcher

Point in time On demand

Request Metrics
You can use request metrics to monitor volume of requests, operational status of services, response times, and processing times. General request metrics include data for all services and are a consolidation of metrics for all dispatchers. Request metrics specific to a service include only data for that service. At the system, server, and server group levels, the metrics include data from all associated dispatchers. At the dispatcher level, metrics include all associated services.

Metric

Entry

Description

Change Type
Counter

Time Scope
Point in time

Gathering Time
On demand

Current time

Service

The current date and time used by the service to interpret time values. Used only if the service has no clock synchronization mechanism

Administration and Security Guide 95

Chapter 6: System Performance Metrics

Metric

Entry

Description

Change Type

Time Scope
Point in time

Gathering Time
On change

Last response time System Server/Server group Dispatcher Service Number of failed requests System Server/Server group Dispatcher Service Number of processed requests System Server/Server group Dispatcher Service Number of success- System ful requests Server/Server group Dispatcher Service Percentage of failed System requests Server/Server group Dispatcher Service Percentage of successful requests System Server/Server group Dispatcher Service

Processing time for the most Gauge recent successful or failed request (in days, hours, minutes, and seconds)

The number of service requests Counter that failed (a fault was returned)

Since reset On change

The number of processed requests Counter

Since reset On change

The number of service requests that succeeded (no fault was returned)

Counter

Since reset On change

The percentage of processed requests that failed

Gauge

Since reset On change

The percentage of processed requests that succeeded

Gauge

Since reset On change

96

Chapter 6: System Performance Metrics

Metric

Entry

Description

Change Type
Gauge

Time Scope

Gathering Time

Response time high System watermark Server/Server group Dispatcher Service Response time low System watermark Server/Server group Dispatcher Service Seconds per success- System ful request Server/Server group Dispatcher Service Service time System Server/Server group Dispatcher Service Service time failed requests System Server/Server group Dispatcher Service Service time success- System ful requests Server/Server group Dispatcher Service

The maximum length of time taken to process a successful or failed request (in days, hours, minutes, and seconds)

Since reset On change

The minimum length of time taken to process a successful or failed request (in days, hours, minutes, and seconds)

Gauge

Since reset On change

The average length of time taken Gauge to process a successful request (in seconds)

Since reset On change

The time taken to process all Counter requests (in days, hours, minutes, and seconds)

Since reset On change

The time taken to process all failed service requests (in days, hours, minutes, and seconds)

Counter

Since reset On change

The time taken to process all suc- Counter cessful service requests (in days, hours, minutes, and seconds)

Since reset On change

Administration and Security Guide 97

Chapter 6: System Performance Metrics

Metric

Entry

Description

Change Type

Time Scope

Gathering Time

Successful requests System per minute Server/Server group Dispatcher Service

The average number of successful Gauge requests processed in one minute

Since reset On change

Process Metrics for Report and Batch Report Service

The report service and batch report service have the unique metrics listed in the following table, which you can use to monitor report service processes.

Metric

Entry

Description

Change Type
Gauge

Time Scope
Point in time

Gathering Time
On demand

Number of processes

System Server/Server group Report service and Batch report service

The number of report service processes currently running

Number of processes high watermark

System

For system, server, and server group, the total of all Number Server/Server of processes high watermark group metrics for all associated Report service and resources Batch report serFor services, the maximum vice number of report service processes that ran at any one time since the last reset System

Gauge

Since reset On change

Number of processes low watermark

For system, server, and server Gauge group, the total of all Number Server/Server of processes low watermark group metrics for all associated Report service and resources Batch report serFor services, the minimum numvice ber of report service processes that ran at any one time since the last reset

Since reset On change

98

Chapter 6: System Performance Metrics

Panes on the Status System Page

The System page has three panes, which you use to evaluate system status: Scorecard, Metrics, and Settings. You can refresh each pane independently. You can sort some columns by clicking on the title. By default, columns are sorted in ascending order. To sort in ascending order, click once. To sort into descending order, click again. To return to default order, click a third time.

Scorecard Pane
The Scorecard pane lists entries: system, servers, server groups, dispatchers, and services. For each, it shows a metric score and operational status so that you can assess system performance (p. 100). Each metric score is represented by a symbol: a green circle for good a yellow diamond for average a red square for poor

You must set metric thresholds before metric scores appear (p. 101). If a service is disabled in IBM Cognos Configuration, it is not listed. The metric score for each entry is based on the performance of individual child entries. The status that is displayed for each entry is the lowest status of the child entries. For example, if all the metrics for a dispatcher are good but one service on that dispatcher has a poor metric, the metric score shown for the dispatcher is poor. Status is one of the following: Available if all components are available Partially available if at least one component is available and at least one component is unavailable or partially unavailable. Unavailable if all components are unavailable

The Toolbar actions menu lets you perform functions such as starting and stopping dispatchers or services (p. 108), unregistering dispatchers (p. 111), and testing dispatchers (p. 117). Each entry also has an Actions menu associated with it, which you access by clicking the arrow next to the entry. You use the Scorecard pane to navigate to the entry that you want to view. You can select the view that you want from the Change view menu in the upper-left corner. You can click on entries to select them and display the next level of entries. For example, click a server to see associated dispatchers or click a dispatcher to see associated services.

Administration and Security Guide 99

Chapter 6: System Performance Metrics

Consolidated Summary on Scorecard Pane

You can maximize the Scorecard pane to see a consolidated view of information that is displayed in the Scorecard pane and important metrics from the Metrics pane. It includes the following information: For servers and server groups, the following information is displayed: metric score, operational status, up time, service time, number of processed requests and percentage of successful requests. For dispatchers, the following information is displayed: metric score, operational status, number of processes, service time, current heap size (bytes), number of processed requests, and percentage of successful requests. For services, the information that is displayed depends on the service.

Metrics Pane
The Metrics pane shows the metrics for the selected entry. You can expand metric groups to see the individual metric scores and values. You can reset each metric group independently (p. 103) You can select the metrics that you want to display by clicking a check box at the top of the pane. By default, all are displayed. Metrics with no metric score include ones that you can not set thresholds for and ones that you have not yet set metric thresholds for. For the latter, you must display them by clicking the No metric score check box before you can set them.

Settings Pane
The Settings pane shows settings associated with the selected entry in view only mode. To change settings, click the set properties button .

For more information on the settings in the Settings pane, see "Server Administration" (p. 105).

Assess System Performance

To evaluate how IBM Cognos 8 is performing, you can view metric scores that are based on thresholds that you set. You can also view the operational status of system components. You must set metric thresholds before metric scores appear (p. 101). If dispatchers and services are not performing as they should, you can tune server performance (p. 127). For more information on logging settings, see "Setting up Logging" (p. 79).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. The metric score icon next to System shows overall system status. The metric score icon next to each server shows the status of that server. In the Metrics pane, individual metrics are listed. 4. In the upper left corner of the Scorecard pane, click the arrow to view the Change view menu, and then click the view that you want. 100

Chapter 6: System Performance Metrics If you choose All server groups, display dispatchers that are not grouped by server by clicking Default server group. 5. To view the metrics for a displayed item, click the icon to the left of the entry. 6. To view the children of a displayed entry, click the entry itself. Tip: You can refresh individual panes by clicking the refresh button in the pane. 7. To view or change the properties of an entry, click the actions menu button next to the entry, and then click Set properties. 8. To see the consolidated view, click the maximize button on the Scorecard pane. Tip: To return to the previous view, click the restore button.

View Attributes for Metric Scores

You can view the last time a metric was reset and updated. You can also view the current threshold setting for each metric score for which a threshold is set (p. 101). For metrics that are collected at regular intervals, you can also view the period of time to which the value applies.

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper left corner of the Scorecard pane, click the arrow to view the Change view menu, and then click the view that you want. 5. In the Metrics pane, expand the metric group that you want to view.

6. In the Value column of the Metrics pane, pause your pointer over the value for the metric that you want to view. The name of the metric is displayed. 7. To view more information about some metrics, click More.

Set Metric Threshold Values

You can set threshold values that are used for some metric scores. Acceptable threshold values depend on your operating environment. When a threshold is crossed, the state of the metric score changes. For example, you determine that the maximum acceptable queue length is 50 items. You select Low values are good. You set the upper value to 50 and the lower value to 40. If the queue remains below 40 items in length, the metric score is green (good). If the queue length goes above 40 items, the metric score is yellow (average). If the queue length goes above 50 items, the metric score is red (poor). Administration and Security Guide 101

Chapter 6: System Performance Metrics Or for percentage of successful requests, you select High values are good. You set the upper value to 98 and the lower value to 95. If the percentage of successful requests goes below 95 percent, the metric score is red (poor). If the percentage of successful requests is between 95 and 98 percent, the metric score is yellow (average). If the percentage of successful requests remains above 98, the metric score is green (good). Changes to thresholds are effective immediately. There are no threshold defaults. You must set thresholds for metric scores to display. If you want to be notified when thresholds are exceeded, you can create an agent (p. 383). Sample agents that monitor the audit database for threshold violations and perform common actions when violations are detected are included in the audit samples package. Log entries (p. 79) occur in the following circumstances: when metric thresholds are violated when enumerated metrics, such as operational status, change

Logs are not generated when metric values change but remain in the same range.

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper left corner of the Scorecard pane, click the arrow to view the Change view menu, and then click the view that you want. 5. To change the threshold for a metric, in the Metrics pane, click the Edit thresholds button next to the metric. 6. Click the performance pattern that you want: High values are good, Middle values are good, or Low values are good. 7. To specify a threshold value, click in the threshold box and enter the threshold number you want. 8. Click the arrow beside the threshold value to specify which range the value itself falls into. For example, if your maximum value is 50 and you want values of 50 to fall into the average category rather than the poor category, click the arrow to move the threshold value into the average category. 9. Click OK.

102

Chapter 6: System Performance Metrics

Reset Metrics
You can reset a group of metrics at any time. For example, for a server, you can reset the Queue Report service group of metrics. When you reset a group of metrics, all the metrics in the group are reset. Some metrics cannot be reset. For example, JVM metrics cannot be reset because they were re-calculated after the last reset.

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper left corner of the Scorecard pane, click the arrow to view the Change view menu, and then click the view that you want. 5. In the Metrics pane, click the reset button for the group of metrics that you want to reset.

Reset Metrics for the System

You can reset all metrics for the system at the same time. Some metrics cannot be reset. For example, JVM metrics cannot be reset because they were re-calculated after the last reset.

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the Scorecard pane, click Actions, Reset all metrics of the system.

Administration and Security Guide 103

Chapter 6: System Performance Metrics

104

Chapter 7: Server Administration

You can perform the following server administration tasks that help you manage and maintain your IBM Cognos 8 system and tune performance. You can perform the following server administration tasks: manage dispatchers and services manage Content Managers maintain the content store migrate PowerPlay reports published to IBM Cognos 8 tune server performance enable concurrent query execution set query prioritization disable session caching add application context to dynamic SQL save report output to a file location configure the lineage solution configure the IBM WebSphere Business Glossary URI enable job, task, and SMTP queue metrics

You should be familiar with the IBM Cognos 8 components and with how they are installed and configured. If you installed IBM Cognos 8 servers or components on more than one computer, all functionality can be controlled through system administration. For information about the IBM Cognos 8 environment, see the Installation and Configuration Guide and the Architecture and Deployment Guide. For some server administration tasks, you use IBM Cognos Administration and must have the required permissions to the access administration functionality "Secured Functions and Features" (p. 221).

Dispatchers and Services

The dispatcher is the entry point for IBM Cognos 8 service requests sent by a Web server gateway or other software. The dispatcher handles the routing requests and balances the load of user requests to the various IBM Cognos 8 services.

Administration and Security Guide 105

Chapter 7: Server Administration You can have more than one dispatcher in your IBM Cognos 8 environment. In such distributed installations one dispatcher is configured for every instance of the Content Manager or Application Tier Components that are installed and configured in your environment. After you install and configure IBM Cognos 8, one dispatcher is available on each computer by default. Each dispatcher has a set of associated services, listed in the following table.

IBM Cognos 8 Services

After you install and configure IBM Cognos 8, one dispatcher is available on each computer by default. Each dispatcher has a set of associated services, listed in the following table.

Service
Agent service

Purpose
Runs agents. If the conditions for an agent are met when the agent runs, the agent service asks the monitor service to run the tasks. Manages background requests to run reports and provides output on behalf of the monitor service. Performs object manipulation functions in the content store, such as add, query, update, delete, move, and copy Performs content store management functions, such as import and export

Batch report service

Content Manager service

Data movement service

Manages the execution of data movement tasks in IBM Cognos 8. Data movement tasks, such as Builds and JobStreams, are created in Data Manager Designer and published to IBM Cognos 8. Sends emails to an external SMTP server on behalf of other services, such as the report service, job service, agent service, or data integration service Creates, schedules, and manages event objects that represent reports, jobs, agents, content store maintenance, deployment imports and exports, and metrics Runs jobs by signaling the monitor service to run job steps in the background. Steps include reports, other jobs, import, exports, and so on.

Delivery service

Event management service

Job service

106

Chapter 7: Server Administration

Service
Log service

Purpose
Records log messages generated by the dispatcher and other services. The log service can be configured to record log information in a file, a database, a remote log server, Windows Event Viewer, or a UNIX system log. The log information can then be analyzed by customers or by Cognos Software Services, including: security events system and application error information selected diagnostic information

Metric Studio service

Provides the Metric Studio user interface for monitoring and entering performance information Manages the migration from IBM Cognos Series 7 to IBM Cognos 8. Manages the monitoring and execution of tasks that are scheduled, submitted for execution at a later time, or run as a background task Assigns a target service to handle a scheduled task. For example, the monitor service may ask the batch report service to run a report, the job service to run a job, or the agent service to run an agent. Creates history objects within the content manager and manages failover and recovery for executing entries

Migration service

Monitor service

Planning job service

Manages communications with the Planning Job Server subsystem. Manages communications with Contributor Web and Contributor Add-in for Excel users.

Planning web service

Planning administration console service Manages communication with the Contributor Administration Console. Planning data service Manages communications for real-time reporting from Contributor plan data in IBM Cognos 8.

Administration and Security Guide 107

Chapter 7: Server Administration

Service
Presentation service

Purpose
Transforms generic XML responses from another service into output format, such as HTML or PDF Provides display, navigation, and administration capabilities in IBM Cognos Connection

Report data service

Manages the transfer of report data between IBM Cognos 8 and applications that consume the data, such as IBM Cognos 8 Go! Office and IBM Cognos 8 Go! Mobile. Manages interactive requests to run reports and provides output for a user in IBM Cognos Connection or a studio Defines the Business Intelligence Bus API-compliant service used to obtain application-wide IBM Cognos 8 configuration parameters. It also provides methods that normalize and validate locale strings and map locale strings to locales supported by your application.

Report service

System service

You can perform the following maintenance on dispatchers and their associated services: start and stop dispatchers and services activate a Content Manager service remove dispatchers from the environment group dispatchers in configuration folders specify advanced dispatcher routing specify gateway mappings rename dispatchers test dispatchers administer failover for multiple dispatchers

Stop and Start Dispatchers and Services

You can stop and start dispatchers and services manually. If a service stops responding, you must stop and restart it. Each dispatcher and service can be started

108

Chapter 7: Server Administration stopped immediately and delete all the requests that are running or queued, without completing those requests stopped after running and queued requests are processed

You can stop or start all dispatchers and services in the IBM Cognos 8 environment at once. When you start IBM Cognos 8 using the configuration tool, all dispatchers and services start unless they are disabled in the configuration tool. For more information, see the Installation and Configuration Guide. By default, all services start when you restart the computer on which they are installed. Stopping a service also stops all its processes. When you stop a dispatcher, all its services are stopped. If the suspended dispatcher has an active Content Manager, all users except administrators are locked out. After a service is stopped, it has a suspended status "System Performance Metrics" (p. 91). You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu and find the dispatchers or services that you want. Click All servers, All server groups, or All dispatchers. To select a service, pause your pointer over Services and click the required service. 5. Click the arrow next to the dispatcher or service, and choose the action that you want to perform. Depending on the dispatcher or service, you can do the following:

Goal

Action

Start all dispatchers in system With all servers displayed, in the upper right corner of the Scorecard pane, click the arrow to view the Toolbar actions menu, and then click Start dispatchers. Tip: To apply a toolbar action to only some entries, select check boxes for one or more entries and then click the toolbar action that you want. Start all dispatchers for a server With all server groups displayed, click the arrow to view group the Actions menu next to the server group, and then click Start dispatchers.

Administration and Security Guide 109

Chapter 7: Server Administration

Goal

Action

Start all dispatchers for a server With all servers displayed, click the arrow to view the actions menu next to the server, and then click Start dispatchers. Start a specific dispatcher With all dispatchers displayed, click the arrow to view the Actions menu next to the dispatcher, and then click Start. Start a specific service With all services displayed, click the arrow to view the Actions menu next to the service, and then click Start. Stop all dispatchers in system With all servers displayed, in the upper right corner of the Scorecard pane, click the arrow to view the Toolbar actions menu, and then click Stop dispatchers immediately or Stop dispatchers after running and queue processed. Stop all dispatchers for a server With all server groups displayed, click the arrow to view group the Actions menu next to the server group, and then click Stop dispatchers immediately or Stop dispatchers after running and queue processed. Stop all dispatchers for a server With all servers displayed, click the arrow to view the Actions menu next to the server, and then click Stop dispatchers immediately or Stop dispatchers after running and queue processed. Stop a specific dispatcher With all dispatchers displayed, click the arrow to view the Actions menu next to the dispatcher, and then click Stop immediately or Stop after running and queue processed. Stop a specific service With all services displayed, click the arrow to view the Actions menu next to the service, and then click Stop immediately or Stop after running and queue processed. A dialog box appears and confirms the action. 6. Click Close.

Activate a Content Manager Service

One Content Manager service is designated to become active at startup. All other Content Manager services start up in standby mode. Only one Content Manager service can be active at any time.

110

Chapter 7: Server Administration You can manually activate a Content Manager service that is in standby mode. When you activate a service, any currently active service switches to standby mode. You can also specify a Content Manager service which is currently standby as the default active service at startup. You must have the required permissions to access IBM Cognos Administration. See "Secured Functions and Features" (p. 221).

Steps to Specify a Default Content Manager Service

1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click Services, and then click Content Manager. 5. Click the arrow for the Actions menu next to the Content Manager service and click Set as active by default. Tip: Only Content Manager services that are not already the default have Set as active by default displayed in the Actions menu.

Steps to Activate a Content Manager Service

1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Under Services, click Content Manager 5. C lick the arrow to view the Actions menu next to the Content Manager service, and then click Start.

Remove Dispatchers from the Environment

You can remove a dispatcher if you no longer need it in the IBM Cognos 8 environment. To remove a dispatcher, you must first uninstall the dispatcher from the computer where it is installed. You must then unregister it to remove it from the content store. You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration.

Administration and Security Guide 111

Chapter 7: Server Administration 3. Click the Status tab, and then click System. 4. Determine the dispatchers that you want to unregister. 5. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click All servers, All server groups, or All dispatchers.

Goal
Unregister all dispatchers in system

Action
With all dispatchers displayed, in the upper-right corner of the Scorecard pane, click the arrow to view the Toolbar actions menu, and then click Unregister dispatchers. Tip: To apply a toolbar action to only some entries, select check boxes for one or more entries and then click the toolbar action that you want.

Unregister all dispatchers for a With all servers displayed, click the arrow next to a server server to view the Actions menu, and then click Unregister dispatchers. Unregister all dispatchers for a With all server groups displayed, click the arrow next to server group a dispatcher to view the Actions menu, and then click Unregister dispatchers. Unregister a specific dispatcher With all dispatchers displayed, click the arrow next to a dispatcher to view the Actions menu, and then click Unregister. A dialog box appears to confirms the action. 6. Click OK. The dispatcher information is removed from the content store. You can now uninstall it. If you do not uninstall the dispatcher, it reregisters itself and restarts the next time that IBM Cognos 8 is restarted. For information about uninstalling, see the Installation and Configuration Guide.

Group Dispatchers in Configuration Folders

Configuration folders are useful to organize dispatchers if your installation includes many dispatchers. You can group dispatchers so that you can apply the same configuration settings once to all the dispatchers and services in the folder. When you add a dispatcher to a configuration folder, it automatically inherits the configuration settings of the folder. However, if you previously changed the default values of that dispatcher or service, the changed values are kept. When you change the configuration settings of a dispatcher or configuration folder, the services for the dispatcher and any child entries for the folder automatically acquire the new values. However, if you change the values of the services, the changed values are kept. 112

Chapter 7: Server Administration You can create a new configuration folder at the root of the Configuration area or in an existing configuration folder.

Tips
To view and edit the configuration properties of the parent of an entry shown in the path on the toolbar, click the set properties button . You can change and apply configuration settings for all the dispatchers and services in the Configuration area when you are in the root of the Configuration area. Use the path on the toolbar to explore the different levels of your configuration. The path starts with Configuration and, when the path becomes too long, it wraps.

You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Configuration tab, click Dispatchers and Services. 4. Click the new folder button. 5. Type a name and, if you want, a description, and specify where to save the configuration folder. 6. Click Finish. You can now add dispatchers to the configuration folder by cutting them from their original location and then pasting them inside the folder. You can also change settings at the configuration folder level. Tip: To move a dispatcher to another folder, click More next to the dispatcher and then click Move.

Specify Advanced Dispatcher Routing

Depending on how your system is set up, you may want to control how reports are distributed among servers. For example, you have different departments that maintain their own servers, or you have specific servers set up for specific data access, such as Windows servers for Microsoft SQL Server databases and Linux servers set up for DB2 access. You can set up IBM Cognos 8 so that report requests are processed by specific servers by applying routing rules. Affinity settings (p. 131) take precedence over advanced routing settings.

Server Groups
When you define the routing rules, you must select a server group. Server group names are a property of a dispatcher or the configuration folders into which the dispatchers are organized. See (p. 128) to set server group names.

Administration and Security Guide 113

Chapter 7: Server Administration To determine which server groups process certain reports, you must associate keywords with packages and user roles or groups, and then specify how the keywords are distributed among the dispatchers in your environment. The distribution is controlled by routing rules that you create for the routing keywords. The report request will be processed by a specific server depending on the keywords associated with the package from which the report was created and/or the user or group running the report. When you create the routing rules, you create conditions that determine the server groups by which the reports are to be processed. For example, you can set up routing rules so that reports from a Finance package made by a user in the Finance group are processed by Finance servers. Alternatively, you can set up routing rules so that reports by any Sales users, regardless of which package was used to create the report, are processed by Sales servers. In the first example, you would specify keywords for both user role or group and package, but in the second you would only specify a keyword for user role or group and leave the package keyword blank. You do not have to specify a keyword for both package and user role or group in your routing rules. You set up the routing keywords and the routing rules using IBM Cognos Connection. You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps to Set Routing Keywords for Packages

1. In IBM Cognos Connection, click the Public Folders tab. 2. Click the set properties button 3. Under Advanced routing, click Set. The Assign routing sets page appears. 4. Type a routing keyword for the package in Type routing sets, and click Add. 5. Repeat step 4 to add other routing keywords that you want to apply to the package. Separate each keyword with a semi-colon, for example, Red;Blue;Green; The order in which the routing keywords are added does not matter. 6. Click OK. The routing keywords are displayed under Advanced routing. 7. On the Set properties page, click OK. for a package.

Steps to Set Routing Keywords for User Roles or Groups

1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. Click the Security tab, and then click Users, Groups, and Roles. 4. Click the namespace to display the roles. 5. Click the set properties button for a role or group.

114

Chapter 7: Server Administration 6. Under Advanced routing, click Set. The Assign routing sets page appears. 7. Select a routing keyword for the users role or group in Select routing sets, or type it in Type Routing Sets, and click Add. If you are typing, separate each keyword with a semi-colon, for example, Red;Blue;Green;. 8. Repeat step 7 to add other routing keywords that you want to apply to the users role or group. The order in which the routing keywords are added does not matter. 9. Click OK. The routing keywords are displayed under Advanced routing. 10. On the Set properties page, click OK.

Steps to Set Routing Keywords for Server Groups

1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Configuration tab, click Dispatchers and Services. The dispatchers and any configuration folders that have been created are shown. Note: You can only apply routing rules to server groups. Server groups are a property of dispatchers or configuration folders, and must be set up before you can set routing keywords for server groups (p. 128). 4. Click the specify routing rules button .

The Specify the routing rules page appears. 5. Click Add a rule. 6. Select the Package routing set, Group routing set, Role routing set, and Server group that you want. 7. In the Actions column, click the View the members button to see an overview of the members. 8. To change the order of routing rules, click Modify the sequence, and then the item you want to move and click Up, Down, To top, or To bottom. Note: Unlike routing keywords, the order in which the routing rules are listed affects how they are applied. A rule is matched when properties associated with the package and/or the user or group involved in the request satisfy the criteria of the rule. The rules are evaluated in order until the first one is matched, and the request is routed to the server group named by the first rule that was matched. You can change the order of the rules by clicking Modify the sequence. 9. Click OK.

Administration and Security Guide 115

Chapter 7: Server Administration

Specify Gateway Mappings for Series 7 PowerPlay Data

IBM Cognos 8 Go! Office users may send requests to Report data service (RDS) for data that resides on a Series 7 PowerPlay server. Report data service (running on the IBM Cognos 8 application server) communicates with Series 7 PowerPlay through the Series 7 PowerPlay Enterprise Server gateway. If the network configuration prohibits application server access to the Web tier server that hosts the Series 7 PowerPlay Enterprise Server gateway, then a second internal Series 7 PowerPlay Enterprise Server gateway must be installed in the application server tier. In this type of configuration, you can specify the location of the Series 7 PowerPlay server by using the Gateway Mappings setting in Server Administration.

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click Services, and then click Report data. 5. Click the arrow next to reportDataService to view the Actions menu, and then click Set properties. 6. Click the Settings tab. 7. In the Value column, click Edit for Gateway mappings. 8. Click the check box Override the settings acquired from the parent entry. 9. Click Add a mapping. 10. For Application gateway (external), type the address of the Web server. 11. For Application gateway (internal), type the address of the Series 7 PowerPlay server. 12. Click OK.

Rename Dispatchers
As a security measure, you can rename dispatchers if you do not want to reveal the host computer name, port number, servlet, or path of the dispatcher (p. 120). Typically, server administrators can view and change the name of dispatchers. We recommend that when renaming a dispatcher, you do not use any information that reveals the host computer name or port, or other system or path information. However, it is important to remember where the dispatcher is installed, for monitoring purposes. Tip: If you rename a dispatcher and need to access the host, port, and path information, you can use the SDK methods to find this information in the dispatcherPath property of the Dispatcher Object. 116

Chapter 7: Server Administration You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click All dispatchers. 5. Click the arrow next to the dispatcher to view the Actions menu, and then click Set properties. 6. In the Name box, type the new name for the dispatcher. Use a meaningful name to help you distinguish dispatchers. Do not reveal system information in the name. 7. If you want, add a screen tip and description information. 8. Click OK.

Test Dispatchers
To evaluate how IBM Cognos 8 is performing, you can test the status of dispatchers. You can also ensure that the dispatchers are responding and view the uptime, which is the time in seconds during which the dispatchers are working without failure. You can also view the status of dispatchers and service and review log messages. When you test a dispatcher, you also test the services that belong to that dispatcher. You must have the required permissions to access IBM Cognos Administration(p. 221).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. Determine the dispatchers that you want to test then follow the instructions in this table. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu and then click the items you want to display.

Administration and Security Guide 117

Chapter 7: Server Administration

Goal
Test all dispatchers in system

Action
With all servers displayed, in the upper right corner of the Scorecard pane, click the arrow to view the Toolbar actions menu, and then click Test. Tip: To apply a toolbar action to only some entries, select check boxes for one or more entries and then click the toolbar action that you want.

Test all dispatchers for a server With all server groups displayed, in the upper right corner group of the Scorecard pane, click the arrow to view the Toolbar actions menu, and then click Test dispatchers. Test all dispatchers for a server With all servers displayed, click the arrow next to the server to view the Actions menu, and then click Test. Test a specific dispatcher With all dispatchers displayed, click the arrow next to the dispatcher to view the Actions menu, and then click Test. A dialog box appears and confirms the action. 5. Click OK. If dispatchers are not performing as they should, you can tune server performance by changing their configuration settings (p. 127).

Administering Failover for Multiple Dispatchers

In a distributed IBM Cognos 8 installation, you may choose to configure each of your gateway components to communicate with more than one dispatcher for failover purposes. The gateway components scan their associated dispatchers to ensure that requests are routed to dispatchers that are in service and responding correctly. You can set the frequency with which these scans are executed. For information about configuring multiple dispatcher, see the "Configuring Gateway Computers" topic in the Installation and Configuration Guide.

Set the Frequency of Dispatcher Status Scans

You can specify how often dispatchers are scanned to determine their current status for failover purposes.

118

Chapter 7: Server Administration

Parameter
ConnectionCheckingSleep Time

Purpose
The interval in seconds between scans for the state of dispatchers.

Valid Setting
1 to 2147483647 Settings less than 5 may consume too many resources (CPU time and network bandwidth). 1 to 2147483647

Default
30

ConnectionCheckingQuick SleepTime

The interval in seconds between scans when no operational dispatchers are found.

Settings less than 5 may consume too many resources (CPU time and This parameter must be less network bandwidth). than ConnectionCheckingSleepTime.

Steps
1. Copy the c8_location/cgi-bin/cognoscgi.conf.sample file to c8_location/bin and rename it cognoscgi.conf. 2. Open the cognoscgi.conf file in an editor that can save files in UTF-8 format. 3. Add the following lines to the file:
ConnectionCheckingSleepTime=time in seconds ConnectionCheckingQuickSleepTime=time in seconds

4. Save the cognoscgi.conf file in UTF-8 format.

Set the Frequency of Dispatcher Scans for a Servlet Gateway

If you have chosen to use Servlet Gateways, you can specify how often they scan dispatchers for their current status. Traffic is routed to another dispatcher if the first one fails. For information about gateways and URIs, see the Installation and Configuration Guide.

Parameter
pingPeriod

Purpose

Valid Setting

Default

The interval in seconds 1 to 2147483647 180 between scans for the state of Settings less than 5 may condispatchers. sume too many resources (CPU time and network bandwidth).

Administration and Security Guide 119

Chapter 7: Server Administration

Parameter
fileCheckPeriod

Purpose

Valid Setting

Default
30

The interval in seconds 1 to 2147483647 between startup configuration file checks for new dispatchers.

Steps
1. Open the Servlet Gateway web.xml file, located either in c8_location/war/gateway/ or in the deployment directory of the servlet, depending on which server you are using, in an editor that supports saving files in UTF-8 format. 2. Change the values for the parameters as required.
<!-- The number of seconds between pings to dispatcher --> <param-name>pingPeriod</param-name> <!-- A non-zero positive integer --> <param-value>180</param-value> </init-param> <init-param> <!-- The number of seconds between checking the startup file for changed dispatchers --> <param-name>fileCheckPeriod</param-name> <!-- A non-zero positive integer --> <param-value>30</param-value> </init-param>

3. Save the web.xml file in UTF-8 format.

Securing Dispatchers
Users of IBM Cognos 8 can enter XPath search paths in the address field of a Web browser, or in hyperlinks. The users can input any search path syntax against search path parameters in the user interface. IBM Cognos 8 relies on the Content Manager Access Control List to check the objects that are returned to the user. In some cases, malicious users could see the dispatcher name in IBM Cognos Connection by providing a crafted search path. This can pose a security risk, even though the users cannot click the object or perform any actions on the object. To avoid this type of security risk, administrators can: set the advanced parameter CM.SECURITYQUERYREQUIRESREAD to TRUE. For more information, see "Set Advanced Content Manager Parameters" (p. 123). change the default dispatcher name The default dispatcher name is computer_name:9300 and it can be changed to, for example, server1 to mask the port number and host name. For more information, see "Rename Dispatchers" (p. 116). For more information about other security technics used in IBM Cognos Connection, see the Architecture and Deployment Guide. 120

Chapter 7: Server Administration

Content Manager Computers

Your installation may include more than one Content Manager, each on a different computer. One Content Manager computer is active and one or more Content Manager computers are on standby. The standby Content Manager computers are for failover protection. If the active Content Manager computer is not available because of a software or hardware failure, a standby Content Manager computer becomes active and requests are directed to it. When the active Content Manager fails, unsaved session data is lost. When another Content Manager becomes active, users may be prompted to log on. Ensure that the clocks on each computer where Content Manager is installed are synchronized. If they are not, you may experience odd behavior if a failover occurs. For example, there may be a delay before the status of a newly disabled server is updated in IBM Cognos Administration. You can set advanced Content Manager parameters (p. 123) for the following: database connection pool settings (p. 121) sorted entries for non-English locales (p. 122) Content Manager synchronization (p. 123) control browsing of external namespaces (p. 123)

For more information about Content Manager, see the Installation and Configuration Guide. You must have the required permissions to access IBM Cognos Administration functionality (p. 221).

Managing Database Connection Pool Settings for Content Manager

Content Manager uses database connections to access the content store. You can change connection pool settings for Content Manager to increase performance. With pooled connections, Content Manager does not have to create and open connections for new requests. This provides faster response times. However, pooled connections reserve database resources, so idle connections should be closed if they are not needed. You can manage the number of connections to the content store by limiting the maximum number of connections and by specifying how long connections stay in the pool before they are automatically closed. The following table lists the available parameters.

Administration and Security Guide 121

Chapter 7: Server Administration

Parameter
CM.DbConnectPoolMax

Purpose
The maximum number of concurrent database connections that are allowed to the content store.

Valid Setting
-1, or 5 to 2147483647, or the database setting, whichever is less This setting applies only to Content Manager connection pool settings. If you have other services that access the same content store, there may be more concurrent database connections than specified in this parameter. -1 to 2147483627

Default
-1 (unlimited)

CM.DbConnectPoolTimeout

Maximum time in milliseconds that a thread waits for a connection to be available from the pool.

-1

A setting of 0 specifies that (unlimited) threads never wait for a connection if one is not available immediately. -1 to 2147483647 300000

CM.DbConnectPoolIdleTime

Minimum time in milliseconds that a connection stays idle in the pool. Only valid if the value of DbConnectPoolCleanUpPeriod setting is positive.

A setting of 0 or -1 specifies 5 min that idle connections are closed when Content Manager restarts.

CM.DbConnectPoolCleanUp Period

Time in milliseconds between -1 to 2147483647 300000 invocations of a cleanup A setting of 0 or -1 specifies 5 min thread that closes idle connec- no clean up thread. tions in the pool that exceed the setting of DbConnectPoolIdleTime.

Sorting Entries for Non-English Locales

If you use a locale other than English, entries in IBM Cognos Connection may not be sorted correctly. You can correct this problem for an Oracle or Microsoft SQL content store by using the CM.SortCollation setting. For example, to sort entries in an Oracle database using a Chinese phonetic collation, set CM.SortCollation parameter to SCHINESE_PINYIN_M. For information about supported collations, see the Oracle and SQL Server documentation. Setting the CM.SortCollation value has no effect on Content Manager running against DB2 or Sybase databases.

122

Chapter 7: Server Administration

Managing Content Manager Synchronization

If your installation includes standby Content Manager computers, you can set parameters that specify Content Manager standby activities. You can specify how often checks occur to ensure that the active dispatcher has not failed, how long it takes to determine which Content Manager is active when failover occurs and at startup, how often an active Content Manager sends a response when it is busy, and how long a short network interruption can be without causing a failover. The following table lists the available parameters.

Parameter

Purpose

Valid Setting

Default

CM.CMSync_Negotiation- Time in milliseconds that it takes 1 to 2000 Time to determine the active Content 9223372036854775807 Manager when a failover occurs. CM.CMSync_Negotiation- Time in milliseconds that it takes 1 to 60000 TimeForStartUp to determine the active Content 9223372036854775807 Manager at startup. CM.CMSync_CheckActive Time in milliseconds for an active Time Content Manager to become standby when another Content Manager becomes active. 10000

CM.CMSync_PingTimeout Time in milliseconds that a busy 1 to 120000 Content Manager sends a 9223372036854775807 response if it is running. CM.CMSync_ShortNetwork Time in milliseconds that a short 1 to 3000 InterruptionTime network interruption can occur 9223372036854775807 without causing a failover.

Control Browsing of External Namespaces

You can control whether users can browse external namespaces. When the CM.SecurityQueryRequiresRead setting is set to true, the Content Manager prevents browsing of external namespaces when the external namespace policy is updated to deny read permissions to users or groups. This setting controls whether the Content Manager forces a read permission filter for external namespace query results. The default is false.

Set Advanced Content Manager Parameters

You can set advanced Content Manager parameters. For information about parameters, see (p. 121).

Steps
1. Start IBM Cognos Connection.

Administration and Security Guide 123

Chapter 7: Server Administration 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click Services, and then click Content Manager. 5. Click the arrow next to ContentManagerService to display the Actions menu, and then click Set properties. 6. Click the Settings tab. 7. Click Edit next to Advanced Settings. 8. Select Override the settings acquired from the parent entry. 9. In the Parameter column, enter the parameter name. For example, enter CM.DbConnectPoolCleanUpPeriod. 10. In the Value column, enter the associated value for the setting. 11. Continue entering setting names and values as required. 12. Click OK. 13. On the Set properties page, click OK.

Override the (Default) Locale Processing in the Prompt Cache

You can override the locale processing in the prompt cache for all reports using the Report Service advanced parameter RSVP.PROMPTCACHE.LOCALE. When the RSVP.PROMPTCACHE.LOCALE parameter is set, the specified locale is used instead of the locale specified in the report whenever prompt cache data is created, updated, or used. This means that a single prompt cache is used for each report regardless of the report users locale.

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu, and then click Services and click Report. 5. Click the arrow next to ReportService to display the Actions menu and click Set properties. 6. Click the Settings tab. 7. Click Edit next to Advanced Settings. 8. Select Override the settings acquired from the parent entry.

124

Chapter 7: Server Administration 9. In the Parameter column, type RSVP.PROMPTCACHE.LOCALE. 10. In the Value column, enter the associated value for the setting. 11. Click OK. 12. On the Set properties page, click OK.

Maintain the Content Store

You can find and fix inconsistencies within the content store or between the content store and external namespaces. You can create content maintenance tasks and run content store maintenance on demand. You can run content maintenance tasks at a scheduled time or based on a trigger, such as a database refresh or an email (p. 304). You can schedule content maintenance tasks as part of a job (p. 301) or as part of an agent (p. 383). You can also view the run history of content maintenance tasks (p. 294). Content maintenance tasks can check for inconsistencies within the content store due to missing data or obsolete data or between the content store and external namespaces.

Internal Content Store Maintenance

Missing data within the content store may cause updates to fail. Obsolete data may prevent you from creating new objects. When a content store maintenance task fixes the content store, it adds default values for the missing data, which you can update later. It also permanently deletes any obsolete data. To ensure that you do not lose any data that you wanted to keep, we recommend that you choose the find mode first and check the results before fixing the content store. When you find and fix the data, the content store is not fixed while the content maintenance task is running. Instead, Content Manager fixes the inconsistencies in the content store the next time it starts up. Important: After you run a content maintenance task to find and fix the content store, back up your content store before you restart Content Manager. We recommend that you perform internal maintenance checks regularly, but it is particularly important to do so before you upgrade, to ensure the consistency of the content stores.

Content Store Maintenance on External Namespaces

When you delete users in your authentication provider, the user account information remains in the content store. You can use the IBM Cognos Administration to find user information that still exists in the content store and fix the content store by deleting any users that do not exist in your external namespaces. You can also delete individual user profiles from the content stores (p. 339). If you want to run a content maintenance task on more than one namespace, do one of the following: If you want to run the content maintenance task now, simply log on to the namespaces and create the content maintenance task. If you want to schedule a content maintenance task to run in the future or on a recurring basis, keep in mind that a scheduled content maintenance task runs against the namespaces that you select when you create the content maintenance task. Before you schedule a content maintenance Administration and Security Guide 125

Chapter 7: Server Administration task, ensure that your credentials contain logon information for each namespace by renewing the credentials after you log on to every namespace that you select to run the content maintenance task against. Tip: Click My Area, My Preferences, click the Personal tab, and then click Renew the credentials. You must have logon permission for each selected external namespace and read permission for all user accounts on each external namespace. If you do not have read permission for a user account on the external namespace, it is assumed that the user was deleted from the namespace. When you run a content maintenance job, the user information on the content store is either listed as inconsistent (for find) or automatically deleted (for find and fix). You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps to Create a Content Store Maintenance Task

1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Configuration tab, click Content Administration. 4. Click the arrow on the new content maintenance button New Consistency Check. 5. Type a name and, if you want, a description and screen tip and click Next. 6. Choose the consistency check that you want: To check the content store for inconsistencies, click Internal references. To run content maintenance on namespaces, click References to external namespaces and select the namespaces that you want. on the toolbar, and then click

7. Click Next. 8. Choose the action that you want: To run the task now or later, click Save and run once and click Finish. Specify a time and date for the run. Click Find only or Find and fix, and then click Run. Review the run time and click OK. To schedule the task at a recurring time, click Save and schedule and click Finish. Then, select frequency and start and end dates. Click Find only or Find and fix and click OK. Tip: To temporarily disable the schedule, select the Disable the schedule check box. To view the schedule status, see "Manage Scheduled Activities" (p. 291).

126

Chapter 7: Server Administration To save the task without scheduling or running, click Save only and click Finish.

Steps to Run a Content Store Maintenance Task

1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Configuration tab, click Content Administration. 4. Click Run with options next to the content maintenance task. 5. Select the Now check box to run the content maintenance task immediately or the Later check box to set a day and time. 6. Click Find or Find and fix. 7. Click Run.

Migrating PowerPlay Reports Published to IBM Cognos 8

You can migrate Series 7 PowerPlay reports published to IBM Cognos Connection to Report Studio or Analysis Studio, using the Open With Analysis Studio or Open With Report Studio functionality. The migration tools must already be installed. For information about migrating PowerPlay Reports or installing migration tools, see the IBM Cognos 8 Migration Tools User Guide.

Tune Server Performance

Regardless of the size of your organization, you should include performance tuning as a regular part of administering servers. By tuning the configuration settings of dispatcher and services, you can optimize the speed and efficiency of IBM Cognos 8. For users, optimal performance means that their reports run fast and without errors. For you, it means that IBM Cognos 8 is stable and that the users are happy. Ideally, you want to tune the servers to meet the user demand at the peak usage times. You may need to add dispatchers to your installation to meet the demands of users. Or, you may need to distribute your installation or upgrade the computer on which IBM Cognos 8 is installed. For more information, see the Installation and Configuration Guide and the Architecture and Deployment Guide. The level of logging (p. 82) can affect performance. When IBM Cognos 8 logs more detail, more resources are allocated to logging and fewer resources are then available to run reports. Before you change any settings, ensure that you tested dispatchers (p. 117), and reviewed the pertinent log messages (p. 80). You should also understand your performance requirements.

Administration and Security Guide 127

Chapter 7: Server Administration

Models
Ensure that your models are optimized for reporting. For more information, see the Framework Manager User Guide.

Operating Systems
How IBM Cognos 8 performs is tightly related to the performance of the operating system of the computer where IBM Cognos 8 is installed. Therefore, it is important to ensure that your operating system is tuned.

Tuning Process
Tuning IBM Cognos 8 includes setting server group names for advanced dispatcher routing balancing requests amongst dispatchers (processing capacity) using cluster compatible mode for dispatchers (load balancing) setting usage during peak periods setting the maximum number of processes and connections and affinity settings setting queue time limits setting PDF file character encoding, font embedding, and compression types and levels setting the maximum execution time limiting hotspots that are generated in and Analysis Studio or Report Studio chart setting retention time for watch list output setting compression for email attachments setting the report size limit for the report data service (governor limit)

Set Server Group Names for Advanced Dispatcher Routing

If you intend to define routing rules for reports (p. 113), you must set server group names for the dispatchers or configuration folders to which you want reports to be routed.

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click All dispatchers. Tip: You can also set the server group property at the system level. 5. Click the arrow for the Actions menu next to the dispatcher and click Set properties. 128

Chapter 7: Server Administration 6. Click the Settings tab. 7. Select Tuning from the Category list. 8. Type a name in the Value column for the Server Group property. 9. Click OK. You can use this server group name when you define routing rules.

Balance Requests Among Dispatchers

If your installation includes more than one dispatcher, you can specify the proportion of requests that each dispatcher handles by changing their processing capacity. This is commonly referred to as load balancing. You typically set the capacity for a dispatcher based on the CPU speed of the computer where it is installed. For example, a first dispatcher is installed on a 2 GHz computer and a second dispatcher on a 1 GHz computer. You set the processing capacity of the first dispatcher to 2.0 and the second to 1.0. The first dispatcher handles two-thirds of the requests while the second handles one-third of the requests. If you set the capacity of both dispatchers to 1.0, requests are sent to each dispatcher alternately. The default processing capacity for each dispatcher is 1.0. Affinity settings (p. 131) take precedence over balance request settings. You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. Click the arrow for the Actions menu next to System and click Set properties. Tip: You can also change the processing capacity setting at the dispatcher level. 5. Click the Settings tab. 6. Select Tuning from the Category list. 7. In the Value column, type a new value for the Processing capacity, and then click OK. The new value takes effect immediately.

Use Cluster Compatible Mode for Dispatchers

If your IBM Cognos 8 servers operate within a load balancing infrastructure, you can turn off the weighted round robin format of load-balancing for the dispatcher. Otherwise, load balancing may be duplicated by the cluster and by IBM Cognos 8, which can degrade performance.

Administration and Security Guide 129

Chapter 7: Server Administration You can set the dispatcher property named loadBalancingMode either to weightedRoundRobin or clusterCompatible. In weightedRoundRobin mode, the dispatcher sprays requests in a weighted round fashion, according to the configuration settings for the dispatcher (p. 129). This is the default mode. In clusterCompatible mode, non-affinity requests are processed locally if possible. If there is no service on the local dispatcher, the request fails. This ensures that IBM Cognos 8 respects any load balancing performed by your own load-balancing infrastructure. You can set the loadBalancingMode property for single dispatchers or for a group of dispatchers in a configuration folder (p. 112). Because it is an inherited property, you can move dispatchers to a configuration folder and set the loadBalancingMode property for the folder to quickly set the property for a group of dispatchers. You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. Click the arrow for the Actions menu next to System and click Set properties. Tip: You can also change the load balancing setting at the dispatcher level. 5. Click the Settings tab. 6. Select Tuning from the Category list. 7. In the Value column, select the value for the Load Balancing Mode, either Weighted Round Robin or Cluster Compatible, and then click OK. The new value takes effect immediately.

Set Usage Peak Periods

Most organizations have a period of peak demand. This period is usually during business hours when employees are at work and run interactive reports. You can determine the start and end hours of the peak demand period for your organization. During the peak period, you may want to set the number of connections and processes (p. 131) low enough so that jobs can run faster and system resources can process interactive requests from users. During the non-peak period, you can set the number of connections and processes higher because demands on the system are lower. The default peak period is from 07:00 to 18:00. The default number of connections for each service during the peak period and during the non-peak period is four.

130

Chapter 7: Server Administration You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click All dispatchers. 5. Click the arrow for the Actions menu next to the dispatcher and click Set properties. 6. Click the Settings tab. 7. Select Tuning from the Category list. 8. In the Value column, type new values for the following settings: Peak period start hour Non Peak period start hour

Tip: If you want to reset a configuration setting to its default value, select its check box and click Reset to default value. 9. Click OK.

Set the Maximum Number of Processes and Connections

For the report service, the batch report service, and the data movement service, you can set the maximum number of processes and the maximum number of high affinity and low affinity connections that the dispatcher can open to handle requests. For the agent, Content Manager, data movement, delivery, job, and report data services, you can set the maximum number of connections. There are separate settings for peak and non-peak hours (p. 130).

Maximum Number of Connections

There is a maximum of one of each of these services per dispatcher: agent, Content Manager, data movement, delivery, job, report data. Connections handle one request from one service at a time. You can specify the maximum number of connections for each service during peak periods and non-peak periods using the following settings: Maximum connections for<service_name> service during non-peak period Maximum connections for<service_name> service during peak period

The default number of connections is four.

Administration and Security Guide 131

Chapter 7: Server Administration

Maximum Number of Processes

There can be multiple report service, batch report service, and data movement processes on each dispatcher. You can specify the maximum number of processes during peak periods using the following settings: Maximum number of processes for the<service_name>during peak period Maximum number of processes for the <service_name>during non-peak period

The default number of processes for each service is two.

Affinity Connections
In addition, report servers accept low and high affinity connections to process requests from the batch report and report services. Servers also accept low and high affinity connections to process requests from the data movement service. Low affinity requests can be handled by any report server. Typically, low affinity requests are used when a report or data movement run is initially requested. High affinity requests are ideally handled by a specific report server. Typically, high affinity requests are for reports that were already requested and may include actions, such as going to the next page in a report. If the specific report server is not available or busy, then the report is rerun (low affinity request) on any report server and the next page (high affinity request) is directed to that server. Affinity settings take precedence over balance request settings (p. 129) and advanced routing settings (p. 113). If affinity settings are changed for a service while entries are running, the number of server processes could double. The number of processes may temporarily exceed the maximum setting while the change takes effect. This may cause problems if your system does not have enough memory for the interim period. For more information about affinity connections, see the Architecture and Deployment Guide. You can specify the number of low and high affinity connections for the report service, the batch report service, and the data movement service using the following settings: Number of high affinity connections for the<service_name> during peak period Number of high affinity connections for the <service_name> during non-peak period

For batch report service, the default number of low affinity connections is two. For the data movement service and report service, the default number of low affinity connections is four. The default number of high affinity connections for all services is one.

Prerequisites
You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 132

Chapter 7: Server Administration 3. On the Status tab, click System. 4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click Services and then click the service you want. 5. Click the arrow for the Actions menu next to the service and click Set properties. Tip: For report service and batch report service, you can also set some settings at the system or dispatcher level. 6. Click the Settings tab. 7. Select Tuning from the Category list. 8. In the Value column, type new values for the processes and connections that you want to change. Tip: If you want to reset a configuration setting to its default value, select its check box and click Reset to parent value. 9. Click OK.

Specify Queue Time Limits

You can specify the maximum number of seconds that interactive requests made by users wait in the queue for an available report service or data movement connection. If a request cannot be processed within the time limit, the request fails and users receive an error message. If your operating system has adequate resources and IBM Cognos 8 is properly configured, requests should not take longer than the time limit. When you specify a time limit, consider the maximum number of seconds that you want users to wait for a response. The default queue time limit is 240 seconds. Requests for the batch report service stay in the queue indefinitely. If you have a high user load (over 165 users) and interactive reports are running continuously in a distributed installation, increase the queue time limit to 360 to avoid getting error messages. You may also want to increase the asynchronous timeout setting to avoid getting error messages. For more information, see the IBM Cognos 8 Installation and Configuration Guide. You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. Click the arrow for the Actions menu next to System and click Set properties. Tip: You can also change the queue time limit settings at the dispatcher or service level. 5. Click the Settings tab.

Administration and Security Guide 133

Chapter 7: Server Administration 6. Select Tuning from the Category list. 7. In the Value column, type a new value for the Queue time limit of report service (seconds) or Queue time limit of data movement service (seconds) setting. Tip: If you want to reset a configuration setting to its default value, select its check box and click Reset to default value. 8. Click OK.

PDF File Settings

There are four settings for PDF files that together determine the speed at which PDF files are created and the size of PDF files. The ideal settings are different for different environments. For example, if you create PDF files as part of batch jobs overnight, you may not care about speed. You may choose settings that create small files that can be easily distributed but take longer to generate. If you create ad hoc PDF files or complex PDF files with many charts and graphics, you may care more about speed than file size. You can use different PDF file settings for report service and for batch report service.

PDF Character Encoding

PDF character encoding determines the character set that is used to create PDF files. You can choose to use Windows1252 encoding, the standard Windows single-byte encoding for Latin text in Western writing systems, or unicode (UTF-16) encoding. By default, PDF character encoding is determined automatically, based on the characters found in the file. The settings names are: PDF Character Encoding for report service PDF Character Encoding for batch report service.

Value
Windows1252

Purpose
If you know your files contain only Windows1252 characters, use this setting for faster PDF file creation. Any unicode (UTF-16) character without a Windows1252 equivalent is converted to an indeterminate Windows1252 character.

Font

If you know your files contain non-Windows1252 characters (for example, Chinese characters), use this setting for faster PDF generation than with the Auto setting. PDF built-in fonts are all Windows1252 character encoded. Almost all other fonts use the UTF-16 character set. This setting typically creates larger PDF files than the Windows1252 setting. It is possible for UTF-16 encoded files to gain better compression (see "Content Compression Type" (p. 136)).

134

Chapter 7: Server Administration

Value
Auto

Purpose
Use this setting to automatically determine if Windows1252 or UTF-16 should be used to encode the text in the document. If large bodies of text must be analyzed, this is the slowest of the three settings. If speed is a concern you may choose to try the other values with various reports to determine the best setting for your environment. This is the default.

Font Embedding
To ensure that the fonts that areused in a report are available to all readers, fonts can be embedded in PDF files. In IBM Cognos Configuration, there are two font embedding lists, one for the report service and one for the batch report service. Fonts can be specified as always embedded or never embedded. For example, fonts that you do not have a legal right to redistribute may be specified as never embedded. Fonts that are not available at your remote sales offices but are required to read PDF reports may be specified as always embedded. For more information about the font embedding lists, see the Installation and Configuration Guide. In IBM Cognos Administration, you can allow or disallow font embedding in report service and batch report service PDF files. You can also choose automatic font embedding. Keep in mind that files with embedded fonts are larger and take more time to generate. Embedding fonts can cause a strain on network resources. Fewer embedded fonts can reduce network resource consumption. The license for some fonts prohibits embedding. Ensure that you have permission from the vendor to embed licensed fonts. The settings names are: Option to allow the report service to embed fonts in generated PDF documents Option to allow the batch report service to embed fonts in generated PDF documents.

There are specialized fonts, such as bar-code fonts, that are always embedded when used. These settings do not control embedding of specialized fonts. PDF built-in fonts are never embedded.

Value
Allow

Purpose
If you know that your audience does not have all the fonts they need to view PDF reports, use this setting. Files are larger and PDF output is generated more slowly. Fonts that are in the never embed list in IBM Cognos Configuration are prevented from being embedded. This is the default.

Administration and Security Guide 135

Chapter 7: Server Administration

Value
Disallow

Purpose
If you know that your audience has all the fonts they need to view PDF reports, use this setting. Files are smaller and are generated faster. Fonts are not embedded unless theyre in the always embed list in IBM Cognos Configuraiton.

Auto

Automatically determines which fonts to embed. This setting takes the longest time to generate PDF reports. If the data contains only Windows1252 characters, both the always embed and the never embed list in IBM Cognos Configuration are used. If there is a conflict, the never embed list is used. Except for specialized fonts, unlisted fonts are usually embedded only if UTF-16 characters from that font are used in the file.

Content Compression Type

You can set the compression type to use when PDF reports are created. It takes longer to create PDF output for files with a higher compression type but the resulting files are smaller. The content compression type specifies which data is compressed. The "Content Compression Type" (p. 136) specifies how much the data is compressed. The combination of the two settings determines the final file size. The settings names are: The PDF compression type for PDF documents created by the report service The PDF compression type for PDF documents created by the batch report service.

The choices for this setting, from lowest to highest compression type, are: Classic, Basic, Improved, Advanced, and Full. Classic is the default. Compression type refers to the amount of data that is compressed within a PDF report. Typically, less compression means faster compression and a larger document. Versions of the Adobe PDF Acrobat Reader earlier than version 6.0 do not support compression types higher than Classic. There are rare cases where compression causes small files to become slightly larger.

Compression Algorithm Level

You can specify the compression algorithm level to use when PDF files are created. The content compression type specifies which data is compressed. The "Compression Algorithm Level" (p. 136) specifies how much the data is compressed. The combination of the two settings determines the final file size. The settings names are: Content Compression level for PDF documents created by the report service Content Compression level for PDF documents created by the batch report service

136

Chapter 7: Server Administration Valid choices for compression algorithm level are 0 (no compression) to 9 (maximum compression). The default is 9.

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click Service, and the service you want. 5. Click the arrow for the Actions menu next to the service and click Set properties. 6. Click the Settings tab. 7. Select Tuning from the Category list. 8. In the Value column, type the value that you want for each of the PDF file settings. Tip: If you want to reset a configuration setting to its default value, select its check box and click Reset to default value. 9. Click OK.

Set Maximum Execution Time

You can set the maximum execution time for the report service, batch report service, and data movement service. If the time limit is exceeded, the execution is canceled. For example, you may want to limit execution time if you know that there is something wrong if tasks take longer. You may also want to ensure that no one task monopolizes server time to the detriment of others. The default is zero, which specifies no limit on execution time. This setting has priority over the governor limit setting. See "Set the Report Size Limit for the Report Data Service" (p. 141). You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click Services and the service you want. Tip: You can also change the queue time limit settings at the dispatcher or service level.

Administration and Security Guide 137

Chapter 7: Server Administration 5. Click the arrow for the Actions menu next to the service and click Set properties. Tip: You can also set these service settings at the System level. 6. Click the Settings tab. 7. Select Tuning from the Category list. 8. In the Value column, type a new value for the Maximum execution time for the <service_name> (seconds) setting. 9. Click OK.

Specify How Long to Keep Watch List Report Output

You can keep watch list report output for a specific number of runs or for a specific number of days or months. For example, you can keep up to 10 versions or you can keep the report output versions for 2 days or 6 months. There are two settings: If you want to specify the maximum length of time to keep watch list report output, use the Periodical document version retention age setting. The default is 1 day. In the Settings pane, this appears as 1 Day(s). If you want to specify the maximum number of copies to keep, use the Periodical document version retention count setting. There is no default. If you specify both settings, whichever is reached first determines how many versions are kept. The settings that you choose depend on how often watch list report output is generated and your system resources. For example, if a report runs nightly to provide output during the day on demand via the portal and watch lists are updated on a weekly basis, you may only want to keep four version each month, but no more than 5 versions during that time. If a job is used to run reports and watch lists are updated only when the job is run, you may only want to keep 1 version each day. For more information on watch lists, see (p. 367). You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. Click the arrow for the Actions menu next to System and click Set properties. 5. Click the Settings tab. 6. Select Tuning from the Category list.

138

Chapter 7: Server Administration 7. In the Value column, type a new value for the Periodical document version retention age setting and select Day(s) or Month(s) from the drop-down menu. 8. In the Value column, type a new value for the Periodical document version retention count setting. 9. Click OK.

Limit Hotspots That are Generated in an Analysis Studio or Report Studio Chart
A hotspot in a chart appears when you pause a pointer over it. For example, a hotspot on a drilldown symbol or a tooltip gives details about the column, line, or pie slice. The browser response time increases with the number of hotspots. When charts with many members are generated, the hotspots can become an additional burden for the system resources, which can freeze the browser. To improve performance, limit the number of hotspots that are generated for Analysis Studio and Report Studio charts. When you limit the number of hotspots, priority is given to items such as axis labels and legend labels before individual graphical elements such as bars, pie slices, and so on. Depending on the number of items in a chart and the setting for maximum number of hotspots, some axis items may have hotspots while other axis items and all graphical elements do not, or all axis items and some graphical elements may have hotspots while other graphical elements do not. The maximum hotspot setting in Report Studio overrides this setting. For more information, see the Report Studio Professional AuthoringUser Guide. The default is an unlimited number of hotspots.

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. Click the arrow for the Actions menu next to System and click Set properties. Tip: You can also change the hotspot setting at the dispatcher or service level. 5. Click the Settings tab. 6. Select Tuning from the Category list. 7. Locate the Number of hotspots generated in a chart by the Batch report service or the Number of hotspots generated in a chart by the Report service setting. In the Value column, click the arrow next to Unlimited and then click <Number>. Type a new value for the maximum number of hotspots 8. Click OK.

Administration and Security Guide 139

Chapter 7: Server Administration

Set Compression for Email Attachments

In IBM Cognos 8, you can choose to compress email attachments above a specific size, or disable compression. By default, compression is disabled. If you want email attachments compressed, change the default behavior using the configuration setting, Maximum size of an uncompressed email attachment in MB. An email attachment must be at least 1MB to be compressed.

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Configuration tab, click Dispatcher and Services. 4. Click the dispatcher you want. 5. For DeliveryService, click the set properties button. 6. Click the Settings tab. 7. To filter the settings, in the Category box, click Tuning. 8. Specify a value for the Maximum size of an uncompressed email attachment in MB setting. The following settings that are available.

Goal
Disable compression Compress email attachments if the attachment is greater than n. N is the size of the attachment in MB.

Action
Type 0 (zero). This is the default setting. Type n, where n is the size of the attachment in MB.

9. Click OK. 10. Click the Configuration link in the path at the top of the page. You return to the list of dispatchers. 11. If you have more than one dispatcher configured, perform steps 4 to 10 for each remaining dispatcher. 12. Using IBM Cognos Configuration, stop and then restart IBM Cognos 8. For information about stopping IBM Cognos 8, see the Installation and Configuration Guide.

140

Chapter 7: Server Administration

Set the Report Size Limit for the Report Data Service
To limit the resources, such as memory, that are used by Report data service, IBM Cognos 8 restricts the size of the report data that can be sent out. If you receive errors in IBM Cognos 8 Go! Office that a report result is too large, you can increase the size limit for report data by changing the Governor limit setting. The maximum execution time setting (p. 137) has priority over this setting.

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click Services, and then click Report Data. 5. Click the arrow next to ReportDataService to view the Actions menu, and then click Set properties. 6. Click the Settings tab. 7. In the Value column, change the number for Governor limit (MB). 8. Click OK.

Set Parameters for Concurrent Query Execution

By default, IBM Cognos 8 executes queries in a report sequentially. Depending on your environment, you may be able to improve report run performance by enabling concurrent query execution. You can do this by setting advanced server properties for the report service, the batch report service, or both. When concurrent query execution is enabled, the report server determines which queries in the report can be run concurrently. The report author must specify the queries in a report that are candidates for concurrent execution. For more information, see the Report Studio Professional Authoring User Guide.

RSVP .CONCURRENTQUERY. NUMHELPERSPERPROCESS

Use this parameter to enable concurrent query execution and set the maximum number of query execution helpers for each report service or batch report service process. The default value is 0, meaning that the concurrent query execution disabled. Each query execution helper results in an additional data source connection. For example, a report service has four processes with two high affinity connections and two low affinity connections: If the maximum number of query execution helpers is set to 0 (disabled), the maximum number of data source connections created by the report service is 16 (two low affinity connections plus two high affinity connections plus zero query execution helpers times four processes).

Administration and Security Guide 141

Chapter 7: Server Administration If the maximum number of query execution helpers is set to 2, the maximum number of data source connections created by the report service is 24 (two low affinity connections plus two high affinity connections plus two query execution helpers times four processes).

RSVP .CONCURRENTQUERY. MAXNUMHELPERSPERREPORT

Use this parmater to specify the maximum number of query execution helpers for each report. This parameter is used to prevent a single report from consuming all available query execution helpers. For example, a report has eight queries that can run concurrently: If RSVP.CONCURRENTQUERY.NUMHEL PERSPERPROCESS and RSVP. CONCURRENTQUERY.MAXNUMHELPERSPER REPORT are both set to four, the report consumes all query helpers when executed. No other report is able to run queries concurrently until the report has finished executing. If RSVP.CONCURRENTQUERY.MAXNUM HELPERSPERREPORT is set to two instead, the report consumes two query helpers, leaving two for other reports to use.

The default value for this parameter is 1. This setting has no effect unless RSVP.CONCURRENTQUERY.NUMHELPERSPER PROCESS is set to greater than 0.

RSVP .CONCURRENTQUERY. ENABLEDFORINTERACTIVEOUTPUT

Use this parameter to enable concurrent query execution when the report service is producing interactive output. For interactive reports, if concurrent query execution is enabled, some queries may be unnecessarily executed because the results are not used. For example, all the queries for a multi-page report may execute with at least one query on each page, but the user may view only the first page. If you do not want to use resources for results that are not used in interactive reports, disable this parameter. Authored prompt pages are not interactive output and are not affected by this setting. The default value for this parameter is false, meaning disabled.

RSVP .PROMPT.EFFECTIVEPROMPTINFO.IGNORE
Use this parameter to disable the issuing of effectivePromptInfo attribute in metadata requests and effectively disable moving the prompt information from under the caption attribute of a level to the level itself. The default value for this parameter is false, meaning disabled. You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System.

142

Chapter 7: Server Administration 4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click Services, and then click (All). 5. Click the arrow for the Actions menu next to a Report or Batch report and click Set properties. 6. Click the Settings tab. 7. Click the set properties button 8. Click the Settings tab. 9. Click Edit next to Advanced Settings. 10. Select Override the settings acquired from the parent entry. 11. In the Parameter column, enter a parameter name. 12. In the Value column, enter the setting that you want to use. 13. Click OK. 14. On the Set properties page, click OK. for the report or the batch report service.

Set Query Prioritization

When you run a report with prompt controls defined, all parameter information is retrieved, including parameter information defined in the report, the model, and the data source. This is required for data typing and to align capabilities for prompt controls with those of its associated parameter. This operation can impact performance, especially when there are many or complex queries. From the user perspective, it can take too long to present the first prompt page or report page. To increase speed, report authors can set a query hint in Report Studio to give a query priority in determining parameter information. Queries are prioritized based on where they are used and whether they contain filters. A priority group is the set of queries sharing similar attributes, such as a filter. Instead of retrieving the parameters for all the queries at the same time, parameters for queries with author-defined priority are retrieved first, regardless of how automated query prioritization is set. For more information about parameters, filters, and prompt controls, see the Report Studio Professional AuthoringUser Guide. Queries are grouped by priority as shown in the following table. When a query group has subgroups, the first sub-group has priority over the second.

Query group

Priority

Queries with the Use for Parameter Info property set to Yes in Report Studio 1 Queries with defined filters that are not used to populate prompt controls First reference to such queries Subsequent references to such queries 2

Administration and Security Guide 143

Chapter 7: Server Administration

Query group
Queries with defined filters that are used to populate prompt controls First reference to such queries Subsequent references to such queries

Priority
3

Queries with no defined filters that are not used to populate prompt controls 4 First reference to such queries Subsequent references to such queries 5

Queries with no defined filters that are used to populate prompt controls First reference to such queries Subsequent references to such queries

To specify a system-wide configuration that defines how queries and query groups are processed, you can assign either a setting value or name to the report server advanced setting, RSVP.PROMPT. RECONCILIATION. This allows you to specify the degree of reconciliation between prompt control capabilities and data type to that of the associated parameter. The setting you choose determines whether reconciliation accuracy or speed is more important. For example, if the report author ensures that parameters are defined with the same datatype and capabilities (i.e., optionality, cardinality, and discreteness), across all queries, specifying CHUNKED or 3 would likely achieve the best performance in the widest variety of situations. RSVP.PROMPT.RECONCILIATION.CHUNKSIZE lets you specify chunk size. This setting is applicable when you use CHUNKED GROUPED and CHUNKED. The default chunk size is 5. The report server advanced properties and Report Studio query hints work cooperatively to provide the best performance. You can use the settings shown in the following table to configure RSVP.PROMPT.RECONCILIATION.

Setting
0

Name
COMPLETE

Purpose
All queries are sent at once. This is the slowest, most accurate form of reconciliation. This is the default setting.

GROUPED

Queries are sent by priority group. This setting works best for reports that have many unfiltered queries and few filtered queries. It provides medium speed and high reconciliation accuracy.

144

Chapter 7: Server Administration

Setting
2

Name
CHUNKED GROUPED

Purpose
Queries are sent by priority group with a maximum number per request. The queries do not span groups. This setting works best on reports that have many queries with similar filter expressions. It provides maximum speed and low reconciliation accuracy. Queries are sent by priority group with a maximum number per request. The queries can span groups.

CHUNKED

You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click Services, and then click (All). 5. Click the arrow for the Actions menu next to a Report or Batch report and click Set properties. 6. Click the Settings tab. 7. Click Edit next to Advanced Settings. 8. Select Override the settings acquired from the parent entry. 9. In the Parameter column, enter a parameter name. 10. In the Value column, enter the setting that you want to use. 11. Click OK. 12. On the Set properties page, click OK.

Disable Session Caching

In Report Studio, Query Studio, and Cognos Viewer the results for previous requests to the database are cached for the duration of a session when session caching is enabled. To increase performance, for subsequent queries, IBM Cognos 8 uses cached results for some actions rather than accessing the database. This applies when the same results can be used or when the new results are a subset of the cached results. You can enable session caching at the server level or at the package or report level.

Administration and Security Guide 145

Chapter 7: Server Administration Because performance may be affected, you may want to leave session caching disabled at the server level in the following situations: users expect up-to-date results directly from the database for every query, for example new records that were added to the database in the interim you want to limit the number of times the cache is accessed during a session

You may also want to leave session caching disabled for individual reports because of high resource consumption, for example, reports that use bursting. You can also enable and disable session caching for specific queries in reports in Report Studio (see the Report Studio Professional Authoring User Guide) and for models in Framework Manager (see the Framework Manager User Guide). Session caching for new models and reports is enabled by default. Existing packages and reports retain existing session caching settings.

Steps to Disable at Server Level

1. Copy the c8_location/configuration/CQEConfig.xml.sample file to c8_location/bin and rename it CQEConfig.xml. 2. Open the c8_location/bin/CQEConfig.xml in an editor. 3. Ensure that your editor supports saving files in UTF-8 format. 4. Find the queryReuse parameter and change the value to 0. 5. Save the CQEConfig.xml file. 6. Using IBM Cognos Configuration, stop and then restart IBM Cognos 8. For information about stopping IBM Cognos 8, see the Installation and Configuration Guide.

Steps to Disable at Package or Report Level

1. Copy the c8_location/configuration/CQEConfig.xml.sample file to c8_location/bin and rename it CQEConfig.xml. 2. Open the c8_location/bin/CQEConfig.xml in an editor. 3. Ensure that your editor supports saving files in UTF-8 format. 4. Find the queryReuse parameter and remove it. 5. Save the CQEConfig.xml file. 6. Using IBM Cognos Configuration, stop and then restart IBM Cognos 8. For information about stopping IBM Cognos 8, see the Installation and Configuration Guide. For information on disabling session caching at the package level, see the Framework Manager User Guide. For information on disabling session caching at the report level, see the Report Studio Professional Authoring User Guide.

146

Chapter 7: Server Administration

Add Application Context to Dynamic SQL

Database server administrators can log and analyze the dynamic SQL workload generated by IBM Cognos 8. As an IBM Cognos 8 administrator, you can define a custom string that includes application context that is added as a comment marker within SQL generated by the application. You can use literals, macros, and session variables, such as a user name, server name, qualified report path, and so on, to customize the comment generated by Cognos 8. By using the applicable session variables, you can configure the format of the string for specific tools and products that can extract comments from dynamic SQL. IBM Cognos 8 includes the comments within any dynamic SQL it generates to a Relational Database Management System (RDBMS) if the vendor supports this functionality. Use the CQEConfig.xml.sample file included with the product to customize the string specifications. The macro in this file shows the default entries that IBM Cognos 8 uses for generating the comments. However, you can add other entries as well. The following example shows kinds of session variables you can specify in the macro in the CQEConfig.xml.sample file:
<configuration company="Cognos" version="0.1" rendition="cer2"> <component name="CQE"> <section name="QueryEngine"> <entry name="GenerateCommentInNativeSQL" value="1"/> <!-- ( default(off)=0, on=1) --> <entry name="GenerateCommentInCognosSQL" value="1"/> <!-- ( default(off)=0, on=1) --> <!-- The content of the comments is controlled with two entries, their defaults are specified in the value attribute --> <entry name="NativeCommentMacro" value="# 'NC user=' + $account.defaultName + 'report=' + $report + 'start=' + $startTime + 'modelPath=' + $modelPath + 'reportPath=' + $reportPath + ' queryName=' + $queryName + ' REMOTE_ADDR=' + $REMOTE_ADDR + 'HTTP_HOST=' + $HTTP_HOST + 'SERVER_NAME=' + $SERVER_NAME +' requestID=' + $requestID + 'sessionID=' + $sessionID #"/> <entry name="CognosCommentMacro" value="# 'CC user=' + $account.defaultName + 'report=' + $report + 'start=' + $startTime + 'modelPath=' + $modelPath + 'reportPath=' + $reportPath + ' queryName=' + $queryName + ' REMOTE_ADDR=' + $REMOTE_ADDR + 'HTTP_HOST=' + $HTTP_HOST + 'SERVER_NAME=' + $SERVER_NAME +' requestID=' + $requestID + 'sessionID=' + $sessionID #"/> </section> </component> </configuration>

At run time, the macro used in the above example would add the following comment to the automatically-generated SQL, or native SQL:
/* CC user=Anonymous report=REPORT1 start=2008-08-28T01:59:35.403Z modelPath=/ content/package[@name='New Package']/model[@name='model']reportPath=/content/ package[@name='New Package']/report[@name='REPORT1'] queryName=Query1 REMOTE_ADDR=127.0.0.1 HTTP_HOST=localhost SERVER_NAME=localhost requestID=wq2lshM9jGhqdMj9h92MqlqvdMlhyMlGq9lyG9sq sessionID=010:0d159165-745a11dd-ac9f-b741aeca4631:2789499633 */ select distinct ALL_TIME.CALENDAR_WEEKDAY as CALENDAR_WEEKDAY from EAPPS..EAPPS.ALL_TIME ALL_TIME

Administration and Security Guide 147

Chapter 7: Server Administration Not all information in the generated comment is meaningful in all situations. The request and session ID information provides a link to the auditing facility, perfQFS performance information, and other traces in IBM Cognos 8.4. However, the name of a query in a report and the report itself may be meaningless, for example, when a user is performing an ad-hoc query or analysis as opposed to running a saved query, analysis or report. By default, an anonymous user cannot see all session variables in the generated comments.

Steps for Using the CQEConfig.xml.sample File

1. Copy the c8_location/configuration/CQEConfig.xml.sample file to c8_location/bin and rename it CQEConfig.xml. Note: If the CQEConfig.xml was used for other purposes, for example to disable session caching, it may already exist in the c8_location/bin directory. In this situation, use the existing CQEConfig.xml file to perform the remaining steps. 2. Open the c8_location/bin/CQEConfig.xml in an editor. Ensure that your editor supports saving files in UTF-8 format. 3. Locate and uncomment the lines of code that begin with:
entry name="GenerateCommentInNativeSQL"... entry name="GenerateCommentInCognosSQL"... entry name="NativeCommentMacro"... entry name="CognosCommentMacro"...

4. If you want, you can modify NativeCommentMacro and CognosCommentMacro by specifying the required parameter values and deleting the parameters that you do not need. If you leave a parameter value empty, the parameter will not appear in the generated comment. 5. Save the CQEConfig.xml file. 6. Restart the IBM Cognos 8 service.

Saved Report Output

By default, the report output files are saved in the content store. You have also have the following choices for saving report output files: You can save a copy in another file location outside of IBM Cognos 8 so that you can share it with external applications or people who dont have IBM Cognos 8 (p. 149). This is how most report output files are saved. You can save a copy in another file location inside IBM Cognos 8 so that it can be used again (p. 149). This may also be useful for archive purposes, since files that are saved in the Content Store may be deleted regularly due to retention rules.

A descriptor file with an _descr extension is also saved. Saved files are not managed by IBM Cognos 8.

148

Chapter 7: Server Administration

Set File Location to Save a Copy of Report Output Outside of IBM Cognos 8
You can specify that an additional copy of report output be saved in a file system outside of IBM Cognos 8. For example, users may want to share a report with an external application, such as a web site, and have it saved there every time it is updated so that current content is always available. Users may also want to save reports on a Local Area Network for people who do not have access to IBM Cognos 8. In IBM Cognos Connection, if users select Save to the file system as the report delivery method (p. 363) when they run or schedule a report, the files are saved in the specified location each time the report runs. There are two associated properties in IBM Cognos Configuration that must be set first: one enables saving file output to a file system, the other specifies the root directory for saving files. For more information, see the IBM Cognos 8 Installation and Configuration Guide. You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Configuration tab, click Dispatchers and Services. 4. On the toolbar, click the Define File System Locations button 5. Click New. 6. Enter a name, description, and screen tip. 7. In File systems location box, type the location where you want to save report output files. The location that you type is appended to the File system root location. 8. Click Finish. .

Set File Location to Save Copy of Report Output in IBM Cognos 8

By default, report output files are saved in the content store. For single-file report outputs, you can also save a copy of the output in a file location in IBM Cognos 8 so that you can use it again. This may also be useful for archive purposes, since files that are saved in the Content Store may be deleted regularly due to retention rules. The following formats can be saved: PDF, .csv, XML, Excel 2002, and HTML that does not have embedded graphics. You cannot save HTML fragment, XMTML, or Excel 2000 or 2007 single sheet formats. In IBM Cognos Connection, if users select Save to the file system as the report delivery method (p. 363) when they run or schedule a report, the files are saved in the specified location each time the report runs. The file location applies to saved output originating from the selected Content Manager service. Administration and Security Guide 149

Chapter 7: Server Administration

Report Output Descriptor File

When you save report outputs files to a file system in IBM Cognos 8, a report output descriptor file is also created. The descriptor file is an XML file that contains information about the report output, such as the name, locale, creation time, owner user name and authentication namespace, the associated report search path, burst key information, and the report version contact. The descriptor file takes the same name as the output file, with the suffix _descr added. For example, a saved PDF report with the name 158_1075940415360.pdf has a descriptor file with the name 158_1075940415360_desc.xml.

Post-processing Scripts
You can also specify a script so that you can run post-processing commands each time a report output is copied to the file system. For example, if your report output files are ultimately stored in an archiving system, you can use a script to perform this action.

Parameters
You can use the parameters that are listed in the following table.

Parameter
CM.OutputLocation

Purpose
The location where you want to store copies of report output files. Old report versions are not deleted when a new one is saved. You must manage the content of the output directory to keep the report versions you want.

CM.OutputScript

The location and name of a shell script, such as a .bat or .sh file, that runs after a report output is saved to the target directory. The full file names of the output file and descriptor are passed to the script. When report output is distributed by bursting, it is assigned a burst key. Specify whether to store output in a subdirectory with the same name as the burst key. Default: false (output not stored by burst key)

CM.OutputByBurstKey

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click Services, and then click Content Manager.

150

Chapter 7: Server Administration 5. Click the arrow next to ContentManagerService to display the Actions menu, and then click Set properties. 6. Click the Settings tab. 7. Click Edit next to Advanced Settings. 8. Select Override the settings acquired from the parent entry. 9. In the Parameter column, enter the parameter name. For example, enter CM.OutPutLocation. 10. In the Value column, enter the associated value for the setting. 11. Continue entering setting names and values as required. 12. Click OK. 13. On the Set properties page, click OK.

Configure the Lineage Solution

Lineage provides details about data in a report, such as the data source and calculation expressions. You can access lineage information in Cognos Viewer, Report Studio, Query Studio, and Analysis Studio. You can configure the default IBM Cognos 8 lineage solution, the IBM Metadata Workbench lineage tool, or a custom lineage solution. To use the default solution or IBM Metadata Workbench, ensure that the value for the Metadata Information Service URI parameter of the Environment category is configured as specified in the steps in this section. To implement a custom lineage solution, you must create a Web interface that translates the IBM Cognos 8 lineage request parameters and invokes the custom lineage solution. For more information, see the section about integrating a custom lineage solution in the SDK Developer Guide. change the value for the Metadata Information Service URI parameter of the Environment category to the URL of your lineage server.

To enable lineage, you must set up the Lineage capability. For more information, see "Secured Functions and Features" (p. 221), and "Object Capabilities" (p. 229).

Steps
1. In IBM Cognos Connection, click Launch, IBM Cognos Administration. 2. On the Status tab, click System. 3. Click the arrow next to System to display the Actions menu, and then click Set Properties. 4. Click the Settings tab.

Administration and Security Guide 151

Chapter 7: Server Administration 5. For the Environment category, Metadata Information Service URI, type one of the following values. If you want to configure the default IBM Cognos 8 lineage solution, type /lineageUIService. If this value is already specified, click Cancel at the bottom of the page. You do not need to change anything. If you want to configure IBM Metadata Workbench as your lineage solution, type /lineageUIService?iis=http://workbench_server_name:9080/workbench/autoLoad.do where http://workbench_server_name:9080/workbench/autoLoad.do is the URL where IBM Metadata Workbench can be accessed on the network. workbench_server_name represents the server name where IBM Metadata Workbench is installed. If you want to configure a custom lineage solution, replace the existing value with the URI that represents your lineage Web interface. For example, type http://mycompany.com/ourLineageService.cgi 6. Click OK.

Configure the IBM WebSphere Business Glossary URI

If your organization uses the IBM WebSphere Business Glossary, you can also access the Glossary in IBM Cognos 8 from Cognos Viewer (p. 356), and from the metadata tree in Report Studio, Query Studio, and Analysis Studio. To access IBM Business Glossary, you must specify the URI of the Glossary Web page. By default, the Glossary search results in IBM Cognos 8 return all terms that contain the keyword specified in the search. To access the Glossary, users must have permissions for the Glossary capability. For more information, see "Secured Functions and Features" (p. 221), and "Object Capabilities" (p. 229).

Steps
1. In IBM Cognos Connection, click Launch, IBM Cognos Administration. 2. On the Status tab, click System. 3. Click the arrow next to System to display the Actions menu, and then click Set Properties. 4. Click the Settings tab. 5. For the Environment category, IBM Business Glossary URI, type the following URI: http://server_name:port_number/bg/popup/popupSearch.do For example, type http://myserver:9080/bg/popup/popupSearch.do All terms that contain the keyword specified in the search are returned.

152

Chapter 7: Server Administration 6. Click OK.

Enable Job, SMTP and Task Queue Metrics ,

By default, only the queue length metric for job, task, and SMTP queue metrics is enabled. The following metrics are also available for each but are set to zero and do not appear in the user interface unless you enable them: Time in queue high water mark Time in queue low water mark Time in queue Number of queue requests Queue length high water mark Queue length low water mark

For more information about these metrics, see "System Performance Metrics" (p. 91). Note that enabling these settings may affect performance. You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. Click the arrow next to System to display the Actions menu, and then click Set Properties. 5. Click the Settings tab. 6. For the Environment category, next to Advanced settings, click the Edit link. 7. If it appears, select the Override the settings acquired from the parent entry check box. Otherwise, proceed to the next step. 8. In the Parameter column, type the following settings: enable.tide.metrics.smtpqueue, enable. tide.metrics.jobqueue, and enable.tide.metrics.taskqueue. 9. Beside each parameter, in the Value column, type True to enable the metric. 10. Click OK. 11. Open the c8_location/webapps/p2pd/WEB-INF/classes/iManage-metadata.xml file in a n editor. Ensure that your editor supports saving files in UTF-8 format. 12. Uncomment the sections that begin with <!-- These metrics have been explicitly
disabled. Please consult documentation on how to enable them. -->

Administration and Security Guide 153

Chapter 7: Server Administration 13. Save the file. 14. Using IBM Cognos Configuration, stop and then restart IBM Cognos 8. For information about stopping IBM Cognos 8, see the Installation and Configuration Guide.

154

Chapter 8: Data Sources and Connections

A data source is necessary to create models in Framework Manager, the IBM Cognos 8 modeling tool, and run reports or analyses from IBM Cognos 8. IBM Cognos 8 supports the following types of data sources: DB2 IBM Cognos Cubes IBM DB2 OLAP and Hyperion Essbase IBM Infosphere Warehouse Cubing Services Informix Microsoft SQL Server Microsoft Analysis Services ODBC Oracle SAP BW TM1 XML

A data source defines the physical connection to a database. The data source connection (p. 180) specifies the parameters needed to connect to the database, such as the location of the database and the timeout duration. A connection can include credential information and signons (p. 186). You can also add new connections to data source and modify existing connections (p. 183). You can make more than one data source connection available by combining them, along with other elements, in packages created and published using Framework Manager. When more than one data source is available in a package, users are prompted to select a data source connection and a signon when they run a report. For information about creating and publishing packages, see the Framework Manager User Guide. You can secure data sources using IBM Cognos 8 security. IBM Cognos 8 also respects any security that is defined within the data source (p. 195). You move data sources from one environment to another environment by deploying the entire content store (p. 307).

Administration and Security Guide 155

Chapter 8: Data Sources and Connections

DB2
IBM Cognos 8 supports DB2 data sources. DB2 connection types can be used to connect to DB2 Linux/UNIX/Windows, Db2 zOS, and DB2 i5OS.

DB2 Connection Parameters

You specify connection parameters when you create a data source (p. 180) or modify a data source connection (p. 183).

Parameter

Description

DB2 database name Enter the name (alias) of the DB2 database that was used when the DB2 client was configured. DB2 connect string Optional. Enter name/name value pairs that DB2 or ODBC vendors can accept. Enter the collation sequence to be included in the database connection string. Collation sequences are required only in rare cases where there may be sorting discrepancies between IBM Cognos 8 and a database. We recommend that you contact customer support before using a collation sequence. Open asynchronously Trusted context Select this check box to allow IBM Cognos 8 to attempt a trusted connection to an appropriately configured DB2 server. For more information, refer to the DBA/DB2 documentation. If you select this check box with a client or server that does not support the feature, you may get a connection error or a report execution error. Timeouts Specify the time in seconds within which you want the database to connect or wait for your reply before timing out. Valid entries are zero to 32,767. To have the database wait indefinitely, enter zero, which is the default. Not used.

Collation sequence

156

Chapter 8: Data Sources and Connections

Parameter
Signon

Description
For more information on signon, see "Securing Data Sources" (p. 195). If no authentication is required, click No authentication. If authentication is required, click Signons. If a user ID and password is required in the connection string, select the User ID check box. If a password is required, select the Password check box and enter the password in the Password and Confirm password boxes. To create a user ID and password that automatically connects to the data source, click Create a signon that the Everyone group can use. Enter the User ID and then enter the password in the Password and Confirm password boxes.

IBM Cognos Cubes

The IBM Cognos cubes that can be used as data sources in IBM Cognos 8 include IBM Cognos Finance IBM Cognos Now! Cube IBM Cognos Planning - Contributor IBM Cognos Planning - Series 7 IBM Cognos PowerCube

If you have problems creating data source connections to Cognos cubes, see the Troubleshooting section in this document. For information about integrating IBM Cognos Finance multidimensional cubes in your IBM Cognos 8 environment, see the IBM Cognos Finance User Guide. For information about connecting to the IBM Cognos Planning - Contributor unpublished (real-time) data, see the IBM Cognos Planning Installation Guide.

IBM Cognos Finance

IBM Cognos 8 supports IBM Cognos Finance as a data source. You can make an IBM Cognos PowerCube data source connection available by creating a connection to live Cognos Finance data. When you create a package, select a specific IBM Cognos Finance submission. This does not limit reporting to that single submission. IBM Cognos Finance submissions can have different hierarchies within each submission. Selecting a submission designates the reporting view of the hierarchy and does not affect how data is calculated within IBM Cognos Finance.

Administration and Security Guide 157

Chapter 8: Data Sources and Connections

IBM Cognos Finance Parameters

You specify connection parameters when you create a data source (p. 180) or modify a data source connection (p. 183).

Parameter
Server name Port number

Description
Enter the name of the IBM Cognos Finance server. Enter the port number of the IBM Cognos Finance server. Use the port number that is specified on the IBM Cognos Finance Server Configuration page. The default is 8800. Select the namespace to use for authentication.

Signon

IBM Cognos Now! Cube

IBM Cognos 8 supports IBM Cognos Now! cubes as data sources. Both IBM Cognos Now! cubes and view objects are supported. For cubes, use the parameters listed below. For views, you can download an ODBC driver from the Cognos Now! appliance under References and Downloads. Follow the instructions that come with the ODBC driver to set up your IBM Cognos 8 environment.

IBM Cognos Now! Cube Parameters

You specify connection parameters when you create a data source (p. 180) or modify a data source connection (p. 183).

Parameter
Server name Port number IBM Cognos Now! connection string:

Description
Enter the name of the server. Enter 80 as the port number. Enter /cognos/now/RelXMLAProvider.jsp

IBM Cognos Planning - Contributor

IBM Cognos 8 supports IBM Cognos Planning - Contributor as a data source. You can use IBM Cognos 8 to report on and analyze real-time Contributor data. You can create an IBM Cognos 8 Contributor package in one of the following ways: Using the Contributor Administration Console, you can create a package that contains all the cubes in the application. When a user opens the package in a studio, they are presented with metadata for all the cubes in the application and can choose from multiple cubes to create reports. However, users may be at risk of inadvertently building queries that attempt to use values from more than one cube, resulting in reports with no data. For more information, refer to the IBM Cognos 8 Planning - Contributor Administration Guide.

158

Chapter 8: Data Sources and Connections Using Framework Manager, you can determine how many cubes to expose in a package. By default, you get one cube in each package. However, this may result in a large number of packages in Cognos Connection, which could be difficult to manage. For more information, refer to the Framework Manager User Guide.

IBM Cognos Planning - Contributor Parameters

You specify connection parameters when you create a data source (p. 180) or modify a data source connection (p. 183).

Parameter

Description

External namespace Select the external namespace.

IBM Cognos Planning - Series 7

IBM Cognos 8 supports IBM Cognos Planning - Series 7 as a data source.

IBM Cognos Planning - Series 7 Parameters

You specify connection parameters when you create a data source (p. 180) or modify a data source connection (p. 183).

Parameter
Server name

Description
Enter the name of the server.

Planning Administra- If the cube was created using IBM Cognos Planning - Contributor version tion Domain (PAD 7.3, indicate the Planning Administration Domain (PAD ID). ID) Port number Enter the port number. The default is 8800.

External namespace Select the external namespace for authentication.

IBM Cognos PowerCubes

IBM Cognos 8 supports PowerCubes generated by Transformer 7.3 and later versions. You make a PowerCube available to end users by creating a package and publishing it from Transformer 8.x, Framework Manager, or IBM Cognos Administration. You create a data source connection to a PowerCube in Transformer or in Framework Manager while publishing the cube, or in IBM Cognos Administration after the cube is published. PowerCubes can be created in Linux and HPUX Itanium environments using Transformer 8.3. You can use IBM Cognos 8 security with these types of cubes, but not Series 7 security. However, you can deploy secured Series 7 PowerCubes to Linux and HPUX Itanium computers running as report servers in the IBM Cognos 8 environment if the Cognos 8 content store is running on a Series 7 compliant server. Administration and Security Guide 159

Chapter 8: Data Sources and Connections You cannot build cubes on Linux or HPUX Itanium if you are using Impromptu Query Definition (.iqd) files as data sources because the Series 7 IQD Bridge is not supported on those platforms. After a connection to a PowerCube is created, you can: create a package for a PowerCube (p. 162) deploy updated PowerCubes (p. 163)

For more information about PowerCubes, see the Transformer User Guide.

Securing PowerCubes
PowerCubes supported by IBM Cognos 8 can be secured using IBM Cognos 8 security namespaces. Security can be applied to an entire cube or to its custom views. Before accessing a cube secured against an IBM Cognos 8 namespace, you must log on to the applicable namespace. In production environments, IBM Cognos 8 supports only PowerCubes secured against a single namespace. Therefore, when you deploy PowerCubes for use in a production environment, you must select the signon option Restrict PowerCube authentication to a single namespace. Note: Instead of using IBM Cognos 8 security, you can add password protection to a PowerCube or decide not to use security.

Recommendation - Using PowerCubes in IBM Cognos 8

The following are some recommendations for using PowerCubes in IBM Cognos 8: When testing the migration of Series 7 PowerCubes to IBM Cognos 8, you can select the signon option to authenticate with All applicable namespaces. This option is only used for the migration of namespaces in Transformer models. It does not change the fact that multiple namespaces are not supported in a production environment. When you use Series 7 PowerCubes as data sources, we recommend that you optimize them for IBM Cognos 8. Optimized PowerCubes provide faster data retrieval at runtime. You optimize PowerCubes using a command line utility named pcoptimizer, which is supplied with IBM Cognos 8. For more information about optimizing PowerCubes, see the Troubleshooting section in this guide. When you publish a PowerCube to IBM Cognos Connection and the cube contains custom views, you must be authenticated in IBM Cognos 8 using a valid user ID and a password. Anonymous access is not supported in this situation.

PowerCube Connection Parameters

You specify connection parameters when you create a data source (p. 180) or modify a data source connection (p. 183).

160

Chapter 8: Data Sources and Connections

Parameter
Read cache size

Description
The default value for this parameter is 80 MB. You can set this parameter to a value between 1 MB and 1 GB, as required for optimal query performance. The optimal read cache size may be higher or lower than the default value of 80 MB. This is to be expected, as PowerCubes in production vary widely in type and query characteristics. Note that the read cache size has no effect on the initial time required to open a cube. The typical profile for query performance, or processing time, follows a pattern whereby performance increases with the read cache size and then levels off beyond the optimal setting. To determine the optimal setting, we recommend that you lower the default by 10 MB (or 5 MB, or 1 MB, depending on the level of fine tuning desired) and use the resulting query performance results as a guide for establishing whether further reductions, or increases, are required. The optimal read cache size will change as the cube grows and changes in the production environment. As a result, you should review the optimal read cache size when changes to the users query performance pattern, or changes in the PowerCube characteristics, occur.

Location

If all your report servers are installed on Windows computers, specify the Windows location. If all report servers are installed on UNIX computers, specify the Unix or Linux location. Type the full path and file name for the cube. For example, for a local cube type C:\cubes\Great Outdoors Company.mdc. For a network cube type \\servername\cubes\Great Outdoors Company.mdc For cubes that reside on UNIX computers, specify the correct UNIX location and type any characters in the Windows location because the Windows location cannot be empty. If the report servers are installed on Windows and UNIX computers, and you want the report server running a request to access the PowerCube in both environments, specify the Windows and UNIX locations. To ensure that the same data is returned regardless of the environment in which the report server accesses the cube, the same cube file must be saved in both locations.

Administration and Security Guide 161

Chapter 8: Data Sources and Connections

Parameter
Signon

Description
If you are using IBM Cognos 8 security, click Restrict PowerCube authentication to a single namespace, and select a namespace from the list. If you are connecting to a password-protected PowerCube, click Cube password, and type the password in the Password and Confirm password boxes. Select All applicable namespaces (including unsecured PowerCubes) only if you are migrating Series 7 PowerCubes to IBM Cognos 8 in your development or test environment. This setting can also be used for unsecured PowerCubes in a production environment. For more information, see "Securing PowerCubes" (p. 160). If a cube password is required, click Cube password, then enter the password in the Password and Confirm password boxes. To create a user ID and password that automatically connects to the data source, click Create a a signon that the Everyone group can use. For more information, see "Securing Data Sources" (p. 195).

Create a Package for a PowerCube

Before you can use a PowerCube data source in any of the IBM Cognos 8 studios, you must create a package. When you create a PowerCube data source in IBM Cognos Administration (p. 180), you are given the option to create a package using your new data source. Note: You can also create a package while publishing PowerCubes from Transformer 8.x. For more information, see the Transformer User Guide. To create a package for an existing PowerCube data source, follow the instructions below. To perform these tasks, you must have execute permissions for the Data Source Connections secured feature "Secured Functions and Features" (p. 221).

Steps
1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Data Source Connections. 3. Click More beside the data source with which you want to create a package. 4. Click Create a Package. The New Package Wizard appears. 5. Enter a name for the package, and click Next. 6. Select the null-suppression options you want to make available to the IBM Cognos 8 studio user. 162 Allow Null Suppression enables suppression.

Chapter 8: Data Sources and Connections Allow Multi-Edge Suppression allows the studio user to suppress values on more than one edge. Allow Access to Suppression Options allows the studio user to choose which types of values will be suppressed, such as zeros or missing values. By default, all null values are suppressed when suppression is enabled.

7. Click Finish.

Deploy Updated PowerCubes

After you rebuild or update a PowerCube, you can use various methods to deploy the cube to the production environment. To deploy an updated IBM Cognos 8 Transformer PowerCube, use the Copy and Activate method in IBM Cognos 8 Transformer (this is the recommended method), or copy the PowerCube yourself, and use the pcactivate command line utility. To deploy an updated Series 7 Transformer PowerCube, you must copy the PowerCube first. Then, use the pcactivate command line utility instead of the PPAdmin utility used in previous releases. For more information, see the section "Copy and Activate a Newer Version of a Published PowerCube" in the IBM Cognos 8 Transformer User Guide. We recommend using the new methods to deploy updated PowerCubes instead of the PowerCube Connection (PCConn) and CubeSwap utilities from previous releases of IBM Cognos 8. If you have PowerCube update scripts that use the CubeSwap or PCConn utility, you may continue to use these scripts in this release.

Steps to Run the pcactivate Command

1. Copy the Transformer PowerCube to the production environment. The name of the destination directory in the production environment must be the same as the PowerCube name. For example, if the cube is named production.mdc, the destination directory must be named "production". The destination directory must be located in the same directory as the PowerCube. For example, if the data source connection specifies that the PowerCube location is "D:\Cubes\ production.mdc", the destination directory, named "production", must be "D:\Cubes\ production".

For example, copy the PowerCube to "D:\Cubes\production\production.mdc". 2. At the command line prompt, type the pcativate command using the following syntax:
pcactivate cube_name.mdc destination_location destination_location

You can type more than one destination location. For example, type pcactivate TheCube.mdc d:\deploy\cubes pcactivate production.mdc D:\Cubes

Administration and Security Guide 163

Chapter 8: Data Sources and Connections pcactivate sales.mdc \\server_1\cubes \\server_2\cubes pcactivate "Production Cube.mdc" "d:\Program Files\cognos\c8\webcontent\cubes"

Note: If you include a path in the cube_name parameter, the path is removed and ignored.

IBM DB2 OLAP and Hyperion Essbase Data Source

IBM DB2 OLAP and Hyperion Essbase data sources are interchangeable and IBM Cognos 8 works with each of them in exactly the same way. For example, you can connect to an Essbase data source using a DB2 OLAP connection. Before connecting to a DB2 OLAP or Essbase data source, some configuration is required if the data source uses scenario dimensions (p. 165), balanced hierarchies (p. 165), or measures (p. 166).

Authentication
When a Hyperion Essbase System 9 Data Source is configured with an LDAP namespace, single signon is supported. The user ID and password used to log on to the LDAP namespace automatically connects to the data source. For more information about configuring an LDAP namespace for IBM DB2 OLAP and Hyperion Essbase Data Sources, see the IBM Cognos 8 Installation and Configuration Guide.

Connection Parameters
You specify connection parameters when you create a data source (p. 180) or modify a data source connection (p. 183).

Parameter
Server name

Description
Enter the name of the server where the database is located. For UNIX, this can be the TCP/IP address of the server.

164

Chapter 8: Data Sources and Connections

Parameter
Signon

Description
For more information on signon, see "Securing Data Sources" (p. 195). If no authentication is required, click No authentication. For Essbase Server System 9 and IBM Cognos 8.4, single signon is supported if your Essbase server is configured for an LDAP namespace. Select An external namespace and select LDAP from the list. The user ID and password used to log on to the LDAP namespace automatically connects to the data source.

If a user ID and password is required in the connection string, click Signons. If a password is required, select the Password check box and enter the password in the Password and Confirm password boxes. To create a user ID and password that automatically connects to the data source, click Create a a signon that the Everyone group can use. Enter the User ID and then enter the password in the Password and Confirm password boxes.

Configure Scenario Dimensions

If you connect to a Essbase/DB2 OLAP data source and it contains a scenario dimension, you must manually configure the scenario dimension so that IBM Cognos 8 recognizes it. Otherwise, IBM Cognos 8 treats the scenario dimension as a regular dimension. For information on how an attribute of a dimension is represented in a model and all associated packages, see "Specify the Attributes of a Dimension" (p. 167).

Step
In the Hyperion Solutions Essbase Administration Services tool, assign a User Defined Attribute (UDA) named COGNOS_SCENARIO_DIMENSION to the scenario dimension.

Specify Balanced Hierarchies

Essbase/DB2 OLAP Provider does not determine if a hierarchy is balanced or unbalanced. It considers all hierarchies as being unbalanced by default. In a balanced hierarchy, each path descends to the same depth while the branches in an unbalanced hierarchy descend to different levels.

Steps
1. In the Hyperion Solutions Essbase Administration Services tool, create a special User Defined Attribute (UDA) named COGNOS_HIERARCHY_BALANCED in the outline of the Essbase/DB2 OLAP database. The UDA is created for the root member of the corresponding dimension containing a balanced hierarchy.

Administration and Security Guide 165

Chapter 8: Data Sources and Connections 2. Set the attribute to 1.

Specify Measure Formats

To improve the readability of the values reported, you can specify an alternative format string for any measure. Define a UDA for the appropriate members in the Account dimension:
COGNOS_FORMAT=format_string

The format_string value can be any one of the predefined number formats listed in the table below. You can use a preset numeric format to show values as millions (M) or thousands (K). For example, 1,801,791 can be shown as 1.8M or 1,801.8K. The predefined format strings are as follows:

Format Option
General 0 #,##0 $0 $#,##0 0% %0 0E+000 0K #,##0K K0 K#,##0 $0K $#,##0K 0M #,##0M

Sample Value
1000000 1000000 1000000 1000000 1000000 1000000 1000000 1000000 1000000 1000000 1000000 1000000 1000000 1000000 1000000000 1000000000

Example
1000000 1000000 1,000,000 $1000000 $1,000,000 100000000% %100000000 1E+006 1000K 1,000K K1000 K1,000 $1000K $1,000K 1000M 1,000M

166

Chapter 8: Data Sources and Connections

Format Option
M0 M#,##0 $0M $#,##0M

Sample Value
1000000000 1000000000 1000000000 1000000000

Example
M1000 M1,000 $1000M $1,000M

With the exception of the General format string, you can also preset the number of decimal places to show, using the format_string ~n, where n is the number of decimal places. For example, 1,801,791 can be shown as $1,801,791.00 using the format string $#,##0~2. If you do not want any decimal places, end the format string with ~0. If your client application uses a different locale, you must replace the Currency ($), Thousands (,) and Decimal (.) symbols in the format_string value for the COGNOS_FORMAT UDA with the corresponding locale symbols in effect for the client application. If you do not specify the number of decimal places to show, or if the format string does not match one of the predefined values (including locale symbols), the General format string is used by default. You can apply a different format for each measure. The following illustrates some examples of how you can apply different formatting to different measures:

Measure
Measures (Account dimension) Units Costs Profits

Applied Format
COGNOS_FORMAT=#,##0 COGNOS_FORMAT=#,##K COGNOS_FORMAT=$#,### COGNOS_FORMAT=0%

Specify the Attributes of a Dimension

You can choose how an attribute of a dimension is represented in a model and all associated packages. An attribute of a dimension can be represented as a separate dimension or as a property (query item) of the dimension with which it is associated. You can set this behavior when creating a package using DB2 OLAP or Essbase data sources.

Steps
1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Data Source Connections.

Administration and Security Guide 167

Chapter 8: Data Sources and Connections 3. Click More beside the data source with which you want to create a package. 4. Click Create a Package. The New Package Wizard appears. 5. Enter a name for the package and click Next. 6. Select a catalogue and click Next. 7. Select a cube and click Next. 8. Assign a language specific alias table and click Next. 9. Choose a language for the alias table and click Next. 10. Choose how to present model attributes. Select Separate the Dimensions or Properties of the dimension they are associated with. The default selection is Properties of the dimension they are associated with. 11. Click Finish.

IBM Infosphere Warehouse Cubing Services

IBM Cognos 8 provides support for accessing the cubing services technology of IBM Infosphere Warehouse for version 9.5.2 and greater. No IBM Cognos 8 components need to be installed on the cubing services server.

IBM Infosphere Warehouse Cubing Services Connection Parameters

You specify connection parameters when you create a data source (p. 180) or modify a data source connection (p. 183).

Parameter
Server URL

Description
Enter the URL of the server in the format http://<hostname>:<cube server xmla port>/IBMXmlAnalysis/ or https://<hostname>:<cube server xmla port>/IBMXmlAnalysis/. An example of the <hostname>:<cube server xmla port> is wottcub1:80.

Open SSL Connection

To use secure sockets, select this check box. To use unsecure sockets, do not select it. The setting must be the same as the setting on the server.

Signon

If a user ID and password is required in the connection string, select the User ID check box. If a password is required, select the Password check box and enter the password in the Password and Confirm password boxes.

168

Chapter 8: Data Sources and Connections

Informix Data Sources

IBM Cognos 8 provides support for Informix data sources.

Informix Connection Parameters

You specify connection parameters when you create a data source (p. 180) or modify a data source connection (p. 183).

Parameter
Informix database name Host name Server name Collation sequence

Description
Enter the database name.

Enter the host name. Enter the server name. Enter the collation sequence to be included in the database connection string. Collation sequences are required only in rare cases where there may be sorting discrepancies between IBM Cognos 8 and a database. We recommend that you contact customer support before using a collation sequence.

Service

Select or enter the service name that the remote database server uses for incoming requests. For more information on signon, see "Securing Data Sources" (p. 195). If a user ID or password are required in the connection string, select the User ID check box. If a password is required, select the Password check box and enter the password in the Password and Confirm password boxes. To create a user ID and password that automatically connects to the data source, select Create a a signon that the Everyone group can use. Enter the User ID and then enter the password in the Password and Confirm password boxes.

Signon

Microsoft Analysis Services Data Sources

IBM Cognos 8 and PowerPlay Enterprise Server support connectivity to Microsoft Analysis Services only from a Windows platform, and both require the Microsoft Pivot Table client libraries. The following configuration is required: IBM Cognos 8 Service must run as a domain account, and this domain account must be trusted for delegation and impersonation because it presents the users credentials to Microsoft Analysis Services. Administration and Security Guide 169

Chapter 8: Data Sources and Connections The domain account should be added in local security settings in your Windows operating system administration tools. Note: You must restart your server after changing this property. The domain account should be a member of the OLAP Administrators group on the Microsoft Analysis Services computer. The OLE database for OLAP (ODBO) client must be installed. This is included in the Microsoft Analysis Services installation files.

Authentication Using an External Namespace

You can configure IBM Cognos 8 to use a Microsoft Active Directory namespace, where users are prompted for credentials as part of the IBM Cognos 8 logon process. You can configure IBM Cognos 8 to use the same credentials automatically when accessing the Microsoft Analysis Services data source. You must configure the data source connection for Microsoft Analysis Server for An external namespace and that namespace must be the Active Directory namespace. You can configure IBM Cognos 8 to use a Microsoft Active Directory namespace and to authenticate users for IBM Cognos 8 using Kerberos authentication and delegation. You can configure IBM Cognos 8 to automatically authenticate the user when accessing the Microsoft Analysis Services data source. The following configuration is required: The IBM Cognos 8 gateway must be installed on an IIS Web server that is configured for Windows Integrated Authentication. Content Manager must be installed on a Windows 2003 or Windows XP server. Content Manager, the report server (Application Tier Components), IIS Web server, and the data source server (Microsoft Analysis Server) must belong to the same Active Directory domain. The data source connection for Microsoft SQL Server must be configured for An external namespace and that namespace must be the Active Directory namespace. The report servers are trusted for delegation.

For more information about installation options for the gateway and Content Manager, as well as configuring the namespace and delegating trust, see the IBM Cognos 8 Installation and Configuration Guide.

Microsoft Analysis Services (via ODBO) and Microsoft Analysis Services 2005 Connection Parameters
You specify connection parameters when you create a data source (p. 180) or modify a data source connection (p. 183).

Parameter
Server Name

Description
Enter the server name where the databases are located.

170

Chapter 8: Data Sources and Connections

Parameter
Named instance

Description
Enter the named instance if one was specified during installation. This parameter is used only by Microsoft Analysis Services 2005.

Language

Select the language. This locale is used as a design locale by the report author and is used only for retrieving metadat from the cube to display in reports. Once the reports are created, they can be run in any locale.

Signon

For more information on signon, see "Securing Data Sources" (p. 195). Select IBM Cognos 8 service credentials to authenticate using a domain account. To use service credentials, ensure that IBM Cognos 8 is started as a service and that the service uses a valid domain account. The service account should be added to the local OLAP administrator group on the machine that runs Microsoft Analysis Services (MSAS). To use an external namespace, select An external namespace and select the Active Directory namespace. To create a user ID and password that automatically connects to the data source, select Create a a signon that the Everyone group can use. Enter the User ID and then enter the password in the Password and Confirm password boxes.

Microsoft SQL Server Data Sources

Depending on the types of Microsoft SQL Server data sources you are using, there are considerations you should keep in mind when defining some types of authentication. If you are using Microsoft SQL Server 2008, you can either select Microsoft SQL Server (OLE DB) or you can select Microsoft SQL Server (SQL 2005 Native Client) and modify the connection string. If you want to use new date and time data types supported by Microsoft SQL Server 2008, use the new SQL Server ODBC client. Microsoft SQL Server (OLE DB) may not support all new data types. For more information, see your Microsoft SQL Server 2008 documentation.

Authentication Using IBM Cognos 8 Service Credentials

When connecting to Microsoft SQL Server using OLE DB, you can select IBM Cognos 8 Service Credentials as the signon type for the data source connection. This property instructs IBM Cognos 8 to log on to the SQL Server database using the logon specified for the IBM Cognos 8 service. Users do not require individual database signons. However, all users will authenticate to the database with the same credentials and will have the same view of the data. For production environments, individual database signons are generally more appropriate. You should not use a Windows local system account for the IBM Cognos 8 server logon with a Microsoft SQL Server OLE DB data source.

Administration and Security Guide 171

Chapter 8: Data Sources and Connections

Authentication Using an External Namespace

You can configure IBM Cognos 8 to use a Microsoft Active Directory namespace, where users are prompted for credentials as part of the IBM Cognos 8 logon process. You can configure IBM Cognos 8 to use these same credentials automatically when accessing the Microsoft SQL Server data source. The data source connection for Microsoft SQL Server must be configured for An external namespace and that namespace must be the Active Directory namespace. You can configure IBM Cognos 8 to use a Microsoft Active Directory namespace and to authenticate users for IBM Cognos 8 using Kerberos authentication and delegation. You can configure IBM Cognos 8 to automatically authenticate the user when accessing the Microsoft SQL Server data source. The following configuration is required: The IBM Cognos 8 gateway must be installed on an IIS Web server that is configured for Windows Integrated Authentication. Content Manager must be installed on a Windows 2003 or Windows XP server. Content Manager, the report server (Application Tier Components), IIS Web server, and the data source server (Microsoft SQL Server) must belong to the same Active Directory domain. The data source connection for Microsoft SQL Server must be configured for An external namespace and that namespace must be the Active Directory namespace. The report servers are trusted for delegation.

For more information about installation options for the gateway and Content Manager, as well as configuring the namespace and delegating trust, see the IBM Cognos 8 Installation and Configuration Guide.

Microsoft SQL Server and Microsoft SQL Server (SQL 2005 Native Client) Connection Parameters
The following parameters are used by Microsoft SQL Server (OLE DB).

Parameter
Server name Database Name Application Name Collation Sequence

Description
Enter the server name. Enter the database name. Enter the application name. Enter the collation sequence to be included in the database connection string. Collation sequences are required only in rare cases where there may be sorting discrepancies between IBM Cognos 8 and a database. We recommend that you contact customer support before using a collation sequence.

172

Chapter 8: Data Sources and Connections

Parameter
MARS Connection

Description
Select the Multiple Active Results Set (MARS) connection. This parameter is used only by Microsoft SQL Server (SQL 2005 Native Client). Click Yes to allow applications to have more than one pending request per connection and more than one active default result set per connection.

Signon

For more information on signon, see "Securing Data Sources" (p. 195). If no authentication is required, select No authentication. For more information on IBM Cognos 8, see "Authentication Using IBM Cognos 8 Service Credentials" (p. 171). If you use a Microsoft Active Directory namespace and you want to support single signon, select An external namespace, and select the Active Directory namespace. For more information, see "Authentication Using an External Namespace" (p. 172). If authentication is required, select Signons. If a user ID and password is required in the connection string, select the User ID check box. If a password is required, select the Password check box and enter the password in the Password and Confirm password boxes.

You can include database commands in the connection information for this type of data source. For more information, see "Using Database Commands for Oracle, DB2, and Microsoft SQL Server" (p. 190). For information about Microsoft SQL Server (ODBC) connection parameters, see "ODBC Data Sources" (p. 173).

ODBC Data Sources

IBM Cognos 8 divides ODBC connections into two categories: vendor-specific ODBC data sources, which use driver-specific capabilities for query creation generic ODBC data sources, which use general capabilities

IBM Cognos 8 supports the ODBC data sources listed in the following table. The database code appears in the connection string, but can not be edited.

ODBC Data Source

Composite (ODBC)

Database code
CS Administration and Security Guide 173

Chapter 8: Data Sources and Connections

ODBC Data Source

IBM Cognos Virtual View Manager (ODBC) Microsoft SQL Server (ODBC) Progress OpenEdge (ODBC) Red Brick (ODBC) Teradata (ODBC)

Database code
VM SS PG RB TD

Any ODBC data source not listed should be created using the generic ODBC data source, database code OD.

Using Virtual View Manager to Retrieve Data

Virtual View Manager replaces Composite ODBC data source. However, Composite ODBC data sources are still supported for existing customers. Virtual View Manager is a data query application which provides access to distributed JDBC, LDAP, flat files and WSDL data sources. In addition to providing the functionality to model these data sources into homogeneous views, it allows the views to be modified via calculations, joins, and filters. IBM Cognos 8 is then used to access the views using the IBM Cognos Virtual View Manager ODBC driver.

ODBC Connection Parameters

You specify connection parameters when you create a data source (p. 180) or modify a data source connection (p. 183).

Parameter
ODBC data source

Description
Enter the data source name (DSN) as defined in the ODBC.ini file. For more information about the ODBC.ini file, see the IBM Cognos 8 Installation and Configuration Guide.

ODBC connect string

Enter any text that must be appended to the connection string. This parameter is typically left blank.

Collation sequence

Enter the collation sequence to be included in the database connection string. Collation sequences are required only in rare cases where there may be sorting discrepancies between IBM Cognos 8 and a database. We recommend that you contact customer support before using a collation sequence.

174

Chapter 8: Data Sources and Connections

Parameter
Open asynchronously

Description
Select if you want the connection to process requests independent of each other. Do not select if you want the connection to complete the current request before starting another one. Select if you want IBM Cognos 8 to the Unicode data standard to interpret data. Leave it unselected if you want IBM Cognos 8 to use ANSI to interpret data. This selection applies only to Composite, Virtual View Manager, Progress OpenEdge, Teradata, and generic ODBC data source connections.

Unicode ODBC

Timeouts

Specify the time in seconds within which you want the database to connect or wait for your reply before timing out. Valid entries are zero to 32,767. To have the database have wait indefinitely, enter zero, which is the default.

Signon

For more information on signon, see "Securing Data Sources" (p. 195). For Teradata, Composite, Virtual View Manager, and Microsoft SQL: If no authentication is required, select No authentication. If the credentials to the database match the credentials used to logon to the IBM Cognos 8 environment, for single signon, select An external namespace and select the appropriate namespace. If authentication is required, select Signons. If a password is required, select the Password check box and enter the password in the Password and Confirm password boxes. To create a user ID and password that automatically connects to the data source, select Create a a signon that the Everyone group can use. Enter the User ID and then enter the password in the Password and Confirm password boxes. For generic ODBC, RedBrick, and Progress OpenEdge: If a user ID and password are required in the connection string, select the User ID check box, then select the Password check box and enter the password in the Password and Confirm password boxes. To create a user ID and password that automatically connects to the data source, select Create a a signon that the Everyone group can use. Enter the User ID and then enter the password in the Password and Confirm password boxes.

Administration and Security Guide 175

Chapter 8: Data Sources and Connections

Oracle Data Sources

IBM Cognos 8 supports Oracle data sources.

Oracle Connection Parameters

You specify connection parameters when you create a data source (p. 180) or modify a data source connection (p. 183).

Parameter
SQL*Net connect string Collation sequence

Description
Enter the SQL*Net connect string.

Enter the collation sequence to be included in the database connection string. Collation sequences are required only in rare cases where there may be sorting discrepancies between IBM Cognos 8 and a database. We recommend that you contact customer support before using a collation sequence.

Signon

For more information on signon, see "Securing Data Sources" (p. 195). If a user ID or password are required in the connection string, select the User ID check box. If a password is required, select the Password check box and enter the password in the Password and Confirm password boxes. To create a user ID and password that automatically connects to the data source, select Create a a signon that the Everyone group can use. Enter the User ID and then enter the password in the Password and Confirm password boxes.

SAP Business Information Warehouse (SAP BW) Data Sources

IBM Cognos 8 supports access to SAP BW data sources.

SAP BW Connection Parameters

You specify connection parameters when you create a data source (p. 180) or modify a data source connection (p. 183).

Parameter
SAP logon type

Description
Select the logon type. The parameters change depending on the logon type you select.

176

Chapter 8: Data Sources and Connections

Parameter
Application server

Description
For SAP logon type Application server, enter the SAP application server name. For more information, contact your SAP system administrator.

System number

For SAP logon type Application server, enter the system number. For more information, contact your SAP system administrator.

Client number

For SAP logon type Application server, enter the client number. For more information, contact your SAP system administrator.

SAP server code page For SAP logon type Application server, select the SAP server code page. IBM Cognos 8 follows the SAP internationalization rules, providing a compatible application that supports multiple scripts and languages without modifying SAP BW in IBM Cognos 8. For more information, contact your SAP system administrator. SAP router string For SAP logon type Application server, enter the SAP router string. The router string describes the stations of a connection required between two hosts. For more information, contact your SAP system administrator. Destination For SAP logon type Destination, enter the location of the SAPRFC.ini file that is used to connect to the SAP BW server. For more information, contact your SAP system administrator. Client number For SAP logon types Destination and Message server, enter the client number. For more information, contact your SAP system administrator. SAP server code page For SAP logon types Destination and Message server, select the SAP server code page. IBM Cognos 8 follows the SAP internationalization rules, providing a compatible application that supports multiple scripts and languages without modifying SAP BW in IBM Cognos 8. To obtain the correct SAP server code page, contact your SAP system administrator. Message server For SAP logon type Message server, enter the SAP message server. For more information, contact your SAP system administrator.

Administration and Security Guide 177

Chapter 8: Data Sources and Connections

Parameter
System ID

Description
For SAP logon type Message server, enter the system ID of the SAP system that you want to connect to. For more information, contact your SAP system administrator.

Logon Group

For SAP logon type Message server, enter the SAP group. For more information, contact your SAP system administrator.

Client number

For SAP logon type Message server, enter the client number. For more information, contact your SAP system administrator.

Signon

For more information on signon, see "Securing Data Sources" (p. 195). If a trusted signon namespace is configured using IBM Cognos Configuration, you can select An external namespace and select the namespace you want to use. To create a user ID and password that automatically connects to the data source, select Create a a signon that the Everyone group can use. Enter the User ID and then enter the password in the Password and Confirm password boxes.

TM1 Data Sources

IBM Cognos 8 provides support for accessing TM1 servers and cubes. You must install the TM1 client on the same computer as the Cognos 8 installation. When you create a TM1 data source connection, consider how you would like to set up authentication.

Authentication
Your choice must meet the TM1 server authentication requirement. For example, if you do not create a user ID and password, but the TM1 server requires a log on, the user is prompted to log on. You can use an external namespace (third-party directory service provider) as an authentication method. The TM1 server must be configured to authenticate with IBM Cognos 8. For more information, see your TM1 documentation on Cognos Access Manager Authentication.

TM1Connection Parameters
You specify connection parameters when you create a data source (p. 180) or modify a data source connection (p. 183).

178

Chapter 8: Data Sources and Connections

Parameter
Administration Host

Description
Enter the name of a machine that can be identified by the network. For example, sottolapsrv1.ent.ad.cognos.com Enter the server name as configured in the TM1S.cfg file. For more information, see your TM1 documentation. For more information on signon, see "Securing Data Sources" (p. 195). If no authentication is required, select No authentication. If an external namespace is used, select An external namespace and then select the namespace. If authentication is required, select Signons. If a user ID is required in the connection string, select the User ID check box. If a password is required, select the Password check box and enter the password in the Password and Confirm password boxes. To create a user ID and password that automatically connects to the data source, select Create a a signon that the Everyone group can use. Enter the User ID and then enter the password in the Password and Confirm password boxes.

Server Name

Signon

XML Data Sources

When you create an XML data source, you must use XML as the type of connection and specify the location of the XML document in the connection string. You can specify the connection string for an XML data source as: an HTTP URL that identifies the content store required to connect to the XML document. An example is HTTP://xmltestserver.cognos.com/XML/country.xml. Ensure that you create a Web alias for the directory that contains the XML file and that you enable directory browsing. a file path A Windows file path example is \\servername\XML\country.xml. A UNIX file path example is /mount name/XML/country.xml. a local file An example is C:\XML\country.xml;VALIDATE=ON. To access a local file, use a file path that uses platform-specific syntax. To test an XML connection string, you must type the following code at the end of the string:
;VALIDATE=ON

Administration and Security Guide 179

Chapter 8: Data Sources and Connections The text of this code is not case sensitive.

Parameterized XML Connection Strings

In an HTTP URL connection string for an XML data source, you can use parameters to send additional information. You can embed a prompt definition string in the parameter component. If the prompt definition is specified in the report, that value is used. Otherwise, the user is prompted to supply a value. Prompting is not supported for other types of connection strings. An example of a URL component is addressing_scheme://network_location/path; parameters?query#fragment_identifier Encode the parameter component with the definition string in between two sets of question marks. A prompt cannot cross a component boundary. An example of a parameterized XML string is http://My_Network_Location/My_Path/myxml. asp?countrysid=??CanadaPrompt?? Parameterized XML connection strings have these restrictions: When a URL component is a prompt, it cannot contain other data. Prompts embedded in XML connection strings do not work in Framework Manager. You cannot import data from a parameterized XML connection string. When you set up a parameterized XML connection string in IBM Cognos Connection, the Test button does not work. Validation of the query specification in Report Studio does not work if you are connected to a parameterized XML connection string.

XML Data Source Connection Parameters

You specify connection parameters when you create a data source (p. 180) or modify a data source connection (p. 183).

Parameter
Connection string

Description
Enter the connection string.

Create a Data Source

A data source defines the physical connection to a database. A data source connection specifies the parameters needed to connect to a database, such as the location of the database and the timeout duration. These parameters form a connection string for the data source. You can create data sources in the portal or in Framework Manager. Because they are stored on the server, data sources appear in both places, regardless of where they were created. Existing data source connections can be edited only in the portal.

180

Chapter 8: Data Sources and Connections If you are an administrator, you can set up all required data sources before models are created in Framework Manager so that all connections are available in the Framework Manager Metadata wizard. Data sources are stored in the Cognos namespace and must have unique names. For example, you cannot use the same name for a data source and a group. You can include authentication information for the database in the data source connection by creating a signon (p. 186). Users need not enter database authentication information each time the connection is used because the authentication information is encrypted and stored on the server. The signon produced when you create a data source is available to the Everyone group. Later, you can modify who can use the signon or create more signons. For more information about data source security, see "Securing Data Sources" (p. 195). Before creating data sources, you must have write permissions to the folder where you want to save the data source and to the Cognos namespace. You must also have execute permissions for the Data Source Connections secured feature.

Recommendation - Use Network Paths For File-Based Data Sources

If you have a distributed installation with several servers, we recommend that you use network paths for all file-based data sources rather than local paths. This ensures that the data sources can be accessed by the services that require them, regardless of which server requires the data. When you create a connection to a file-based data source, such as a PowerCube, you enter a path and file name. To point to the file, use a local path, such as C:\cubes\Great Outdoors Company.mdc, or a network path, such as \\servername\cubes\Great Outdoors Company.mdc. In a distributed installation, where report servers are running on different computers, using a local path requires that the file and path be valid on each computer where a report server is running. Alternatively, if you use a network path to point to a file, each report server points to the same file on the network without having the file available locally. Also, to ensure that the file is always available, we recommend that you store it in a shared directory that can be accessed on your network. If you installed IBM Cognos 8 components on UNIX servers, we recommend that you also locate the file-based data source on a UNIX server. You should then use a UNIX path, such as /servername/cubes/Great Outdoors Company.mdc to access the file. If you have installed all components on a single computer, you can use local paths, but you must ensure that the services requesting the data have the appropriate access to the data files on the computer. For Windows distributed installations, we recommend that you use UNC paths to shared directories for any file based data source, such as PowerCubes or XML files.

Steps
1. In IBM Cognos Connection, in the upper-right corner, select Launch, IBM Cognos Administration. 2. On the Configuration tab, select Data Source Connections. Tip: To remove a data source, select the check box for the data source and select the delete button. Administration and Security Guide 181

Chapter 8: Data Sources and Connections

3. Select the new data source button

4. In the name and description page, type a unique name for the data source and, optionally, a description and screen tip, and then select Next. 5. In the connection page, from the Type drop-down list, select the type of data source that you want to create. If your data source is not listed, click Other type. 6. Specify the Isolation level. If the isolation level is unavailable, select Next. If the isolation level is available, select the default object gateway or specify a value, and then select Next. 7. Specify the connection parameters for the data source. For information about connection parameters for the type of data source that you are using, click the associated item in the following list: IBM Cognos Finance IBM Cognos Now! Cube IBM Cognos Planning - Contributor IBM Cognos Planning - Series 7 IBM Cognos PowerCube Composite (ODBC) IBM Cognos Virtual View Manager (ODBC) DB2 Hyperion Essbase/IBM DB2 OLAP Server IBM InfoSphere Warehouse Cubing Services Informix Microsoft SQL Server (ODBC) Microsoft SQL Server (OLE DB) Microsoft SQL Server (SQL 2005 Native Client) Microsoft Analysis Services (via ODBO) Microsoft Analysis Services 2005 ODBC Oracle

182

Chapter 8: Data Sources and Connections Progress OpenEdge Red Brick (ODBC) SAP BW Teradata (ODBC) TM1 XML

8. Select Test the connection, and then Test to test whether parameters are correct. In the Status column, you can see if the connection was successful. If it was unsuccessful, select Close, return to the previous steps, and verify your connection parameters. If it was successful, go to the next step. 9. Click Finish. If you selected a data source other than IBM Cognos PowerCube, the new data source appears in Data Source Connections on the Configuration tab, and can be selected when using the Metadata Wizard in Framework Manager. If you selected IBM Cognos PowerCube, go to the next step. 10. Click OK to return to Data Source Connections, or click Create a Package and OK, and follow the instructions in the new package wizard. Note: You can create a package with your new data source now or later. For more information, see Create a Package for a PowerCube Data Source. If you created a signon, you can now modify or add more signons (p. 186). You can also add more connections (p. 183).

Add or Modify a Data Source Connection

You can add new data source connections or edit string parameters for existing connections. You can also add multiple connections to an existing data source. For example, you want a data source to have two or more connections to the same database that have different properties, such as different timeout values or access permissions. You can also add connections to a data source that point to different databases, but the databases must contain the same schema. When you create a data source connection, you can create a signon that the Everyone group can use to access the database. Later, you can modify who can use this signon or create more signons. For example, you can control access to data by setting the permissions for each data source connection. For more information, see "Set Access Permissions for an Entry" (p. 216). To add or modify a data source connection, you must have access to the required capabilities to administer data sources (p. 221).

Administration and Security Guide 183

Chapter 8: Data Sources and Connections If you are creating an Oracle, DB2, or Microsoft SQL Server data source, you can include database commands in the connection information. For more information, see "Using Database Commands for Oracle, DB2, and Microsoft SQL Server" (p. 190). If you select Microsoft Analysis Services 2005 as the connection type, you can have more than one instance on the same server. For information about setting the maximum number of data source connections available to the report server, see "Manage Data Source Connections" (p. 184).

Steps to Create a New Connection

1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Data Source Connections. 3. Click the data source for which you want to add a new connection. Tip: To remove a data source connection, select its check box and click the delete button. 4. Click the new connection button .

5. In the name and description page, type a unique name for the connection and, optionally, a description and screen tip, and then click Next. 6. Proceed with steps 5 to 10 for creating a data source. If you created a signon, you can now modify or add more signons (p. 186).

Steps to Modify a Connection

1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Data Source Connections. 3. Click the data source for which you want to modify the connection. 4. Click the set properties button 5. Click the Connection tab. 6. If you want to change the data source type, click an item in the Type drop-down list. 7. Click the edit icon to modify the connection string. for the connection you want to modify.

8. Proceed with steps 5 to 10 for creating a data source.

Manage Data Source Connections

Each instance of the report server has an established pool of database connections. The connections are reused for new requests that match the database, user, and password. Entries remain in the pool

184

Chapter 8: Data Sources and Connections until they are idle for a timeout period and then are closed. Once a pool is full, no further connection are added. This results in a request failure.

PoolSize
Set the maximum number of data source connections available to the report server by modifying the PoolSize variable.

Timeout
Set the duration for retaining connections by modifying the Timeout variable. Connections are examined once per minute and any connection that has been inactive longer than the timeout value is removed. The default timeout value is 900 seconds.

Reusable Data Connections

Data source connections are reusable only when the database credentials of the connection match those of the new request. Inactive data source connections can be claimed by a new request. This occurs when the maximum number of connections has been reached and none of the inactive connections can be used by the new request. In this case, the oldest inactive connection is terminated and a new connection is created. When the maximum number of connections is reached, and all are active, then additional requests fail. The server must be configured to ensure that the concurrent report requests do not exceed the request pool size. For more information about report service requests, see "Set the Maximum Number of Processes and Connections" (p. 131).

Steps
1. On each computer where IBM Cognos 8 is installed, open the c8_location/configuration/ CQEConfig.xml.sample file in a text editor. Ensure that your editor supports saving files in UTF-8 format. 2. Find the Timeout and PoolSize parameter and edit them as follows:
<?xml version="1.0" encoding="UTF-8"?> <configuration company="Cognos" version="#.#" rendition="###"> <component name="CQE"> <section name="DBConnectionPool"> <!-- Description: Database connection timeout. Default is 900 seconds (15minutes) --> <entry name="Timeout" value="number_of_seconds"/> <!-- --> <!-- Description: Database connection pool size. --> <!-- Maximum number of connections managed by the report server. Default=50 --> <entry name="PoolSize" value="number_of_connections"/> </section> </component> </configuration>

3. Save the file as CQEConfig.xml to the c8_location/configuration directory. 4. Using IBM Cognos Configuration, stop and then restart the services.

Administration and Security Guide 185

Chapter 8: Data Sources and Connections For information about stopping services, see the IBM Cognos 8 Installation and Configuration Guide.

Create or Modify a Data Source Signon

You add signons to existing data source connections so that users do not have to enter database credentials when they run reports. When you create a signon, you specify the users and groups that can access the signon. The user ID and password that make up the signon must already be defined in the database. For information about creating groups, see "Users, Groups, and Roles" (p. 207). You can modify an existing signon if the credentials used to log on to the database change, or if you want to change who can use the signon.

Steps to Create a Signon

1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Data Source Connections. 3. Click the data source, and then click the connection to which you want to add a new signon. 4. Click the new signon button .

5. In the name and description page, type a unique name for the data source signon and, if you want, a description and screen tip, and then click Next. 6. Type the User ID and Password to connect to the database, and click Next. The Select the users page appears. 7. To add users and groups that can use the signon, and click Add. To choose from listed entries, click the appropriate namespace, and then select the check boxes next to the users, groups, or roles. To search for entries, click Search and in the Search string box, type the phrase you want to search for. For search options, click Edit. Find and click the entry you want. To type the name of entries you want to add, click Type and type the names of groups, roles, or users using the following format, where a semicolon (;) separates each entry: namespace/group_name;namespace/role_name;namespace/user_name; Here is an example: Cognos/Authors;LDAP/scarter; 8. Click the right-arrow button and when the entries you want appear in the Selected entries box, click OK.

186

Chapter 8: Data Sources and Connections Tips: To remove entries from the Selected entries list, select them and click Remove. To select all entries in a list, click the check box in the upper-left corner of the list. To make the user entries visible, click Show users in the list. 9. Click Finish. The new data source signon appears under the connection.

Steps to Modify a Signon

1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Data Source Connections. 3. Click the data source, and then click the connection for which you want to modify the signon. Tip: To remove a signon, select its check box and click the delete button. 4. Click the set properties button 5. Click the Signon tab. A list of users and groups that can use the signon appears. 6. If you want to change the user ID and password that make up the signon click Edit the signon, type the new credentials, and click OK. 7. If you want to add users or groups to the signon list, click Add, and choose how to select users and groups: To choose from listed entries, click the appropriate namespace, and then select the check boxes next to the users, groups, or roles. To search for entries, click Search and in the Search string box, type the phrase you want to search for. For search options, click Edit. Find and click the entry you want. To type the name of entries you want to add, click Type and type the names of groups, roles, or users using the following format, where a semicolon (;) separates each entry: namespace/group_name;namespace/role_name;namespace/user_name; Here is an example: Cognos/Authors;LDAP/scarter; 8. Click the right-arrow button and when the entries you want appear in the Selected entries box, click OK. Tips: To remove entries from the Selected entries list, select them and click Remove. To select all entries in a list, click the check box in the upper-left corner of the list. To make the user entries visible, click Show users in the list. 9. Click OK. for the signon you want to modify.

Administration and Security Guide 187

Chapter 8: Data Sources and Connections

Specifying Isolation Levels

The isolation level specifies how transactions that modify the database are handled. By default, the default object gateway is used. Not all types of databases support each isolation level. Some database vendors use different names for the isolation levels. If you need specific queries to run with different isolation levels, you must define different database connections. For OLAP data sources, including SAP BW, the isolation level is read-only. The following isolation levels are in increasing order of isolation: Read Uncommitted Changes made by other transactions are immediately available to a transaction.

Database type
Oracle DB2 MS SQL Server Sybase Adaptive Server Enterprise Informix

Equivalent isolation level

Not applicable Uncommitted read Read uncommitted Read uncommitted Dirty read

Read Committed A transaction can access only rows committed by other transactions.

Database type
Oracle DB2 MS SQL Server Sybase Adaptive Server Enterprise Informix

Equivalent isolation level

Read committed Read stability Read committed Read committed Committed read

Cursor Stability Other transactions cannot update the row in which a transaction is positioned.

188

Chapter 8: Data Sources and Connections

Database type
Oracle DB2 MS SQL Server Sybase Adaptive Server Enterprise Informix

Equivalent isolation level

Not applicable Cursor stability Not applicable Not applicable Cursor stability

Reproducible Read Rows selected or updated by a transaction cannot be changed by another transaction until the transaction is complete.

Database type
Oracle

Equivalent isolation level

Not applicable Execute the statement, "SET TRANSACTION READ ONLY," prior to starting a transaction

DB2 MS SQL Server Sybase Adaptive Server Enterprise Informix

Repeatable read Repeatable read Repeatable read Repeatable read

Phantom Protection A transaction cannot access rows inserted or deleted since the start of the transaction.

Database type
Oracle DB2 MS SQL Server Sybase Adaptive Server Enterprise Informix

Equivalent isolation level

Not applicable Not applicable Not applicable Not applicable Not applicable

Administration and Security Guide 189

Chapter 8: Data Sources and Connections Serializable A set of transactions executed concurrently produces the same result as if they were performed sequentially.

Database Type
Oracle DB2 MS SQL Server Sybase Adaptive Server Enterprise Informix

Equivalent isolation level

Serializable Not applicable Serializable Serializable Not applicable

Using Database Commands for Oracle, DB2, and Microsoft SQL Server
Use the connection wizard to specify database commands that run when an Oracle connection or session is opened or closed, or when a DB2 or Microsoft SQL Server session is opened. For example, you can use a database command to set the language when you open a connection to an Oracle database, or to set up proxy connections (p. 193) or virtual private databases (p. 194). For Oracle (OR), DB2 (D2), Microsoft SQL Server (SS), and Teradata (TD), you can use commands to run native SQL commands when you open a session, such as running a stored procedure. Database commands are included in command blocks which are formatted using XML.

Notes:
You cannot test the command blocks using the Test the connection link on the connection string page. If you have SDK installed, you can ensure that your XML code validates against the schema file named c8_location/webapps/p2pd/WEB-INF/classes/DataSource.xsd The command structure is the same for Oracle, DB2, and Microsoft SQL Server. However, the specific database commands can vary depending on which database you are using. For example, the above examples are Oracle commands. The commands in the blocks are vendor-specific and must be included in an <sqlCommand> tag, as used in the examples above.

Trusted Database Connections

A data source that is used for trusted applications connections should define open session blocks for any user-specific database state that must be defined prior to the proxy users queries being

190

Chapter 8: Data Sources and Connections issued. The associated Open Connection block is only executed once when the trusted connection is attempted, while Open Session blocks may execute many times for different users.

Example - Open Connection Command Block

The following sets French as the language for an Oracle connection:
<commandBlock> <commands> <sqlCommand> <sql>ALTER SESSION SET NLS_LANGUAGE = FRENCH</sql> </sqlCommand> </commands> </commandBlock>

Example - Close Connection Command Block

The following re-sets the language to English before disconnecting from an Oracle database:
<commandBlock> <commands> <sqlCommand> <sql>ALTER SESSION SET NLS_LANGUAGE = ENGLISH</sql> </sqlCommand> </commands> </commandBlock>

Add Command Blocks While Creating a Data Source

You add command blocks using the connection wizard. By default, connections acquire properties from the parent data source. You can modify this later.

Steps
1. Create a data source, choosing Oracle, DB2, or Microsoft SQL Server as the data source type. 2. Click Next. 3. In the specify commands page, click Set next to the command string that you want to specify. 4. In the set command page, add an XML command block, and click OK. Note: If you are using DB2 or Microsoft SQL Server, you can only add commands block for opening a session. 5. Continue adding command blocks, as required. 6. Click Finish.

Add or Modify Command Blocks for a Connection

Connections acquire properties from their parent data source. If you have added a command block for a data source, then that command block will be available to Oracle, DB2, or Microsoft SQL Server connections in that data source.

Administration and Security Guide 191

Chapter 8: Data Sources and Connections You can change a command block for a specific connection, and you can remove the command block if you do not want it used for the connection.

Steps
1. Create a connection or modify a connection (p. 184), choosing Oracle, DB2, or Microsoft SQL Server as the data source type. 2. Click Next. 3. Click Set or Edit next to the command block that you want to modify. The Acquired column shows Yes or No to indicate whether the connection acquires properties from its parent data source. 4. In the set command page, add or modify the XML code command block, and click OK. Tip: You can reset command blocks by selecting the check box next to the connections clicking Reset to parent value or Clear. Note: If you are using DB2 or Microsoft SQL Server, you can only add commands block for opening a session. 5. Continue adding or modifying command blocks, as required. 6. Click Finish.

Command Block Examples

The following diagram shows an example of the interaction between the four available command blocks, assuming that a connection to the database does not exist.

192

Chapter 8: Data Sources and Connections

Query for user 1 arrives

Run open connection command block

Run open session command block

Run query 1

User idle for specified period of time

Run close session command block

Mark connection as reusable for other users

Connection required by user 2

Connection idle for predefined period of time

Run close connection command block

Example - Using Command Blocks for Proxy Connections

If you are using proxy connections, you can use an existing idle connection with signons for proxy connections. The physical connection can be used by more than one user. Because the proxy connections run on top of the existing physical connection, fewer physical connections are required. To create a proxy connection, you create open session command blocks in XML. The following is a simple example of an open session command block that creates a proxy connection for User1 (Oracle) or switches to User1 (DB2). Note that the sessionStartCommand can only be used with Oracle and DB2.
<commandBlock> <commands> <sessionStartCommand> <arguments> <argument> <name>OCI_ATTR_USERNAME</name> <value>PROXY_USER1</value> </argument> </arguments> </sessionStartCommand> </commands> </commandBlock>

Administration and Security Guide 193

Chapter 8: Data Sources and Connections Another example is a macro that can be substituted if authentication userNames are equivalent to the proxy userid or trusted context user.
<commandBlock> <commands> <sessionStartCommand> <arguments> <argument> <name>OCI_ATTR_USERNAME</name> <value>#$account.personalInfo.userName# </value> </argument> </arguments> </sessionStartCommand> </commands> </commandBlock>

The following is a simple example of a close session command block for a proxy session. The current proxy connection is terminated. Note that sessionEndCommand ends an OCI_session in Oracle and switches the user back to the trusted context owner for DB2.
<commandBlock> <commands> <sessionEndCommand> <arguments/> </sessionEndCommand> </commands> </commandBlock>

Example - Using Command Blocks for Virtual Private Databases for Oracle
Typically, Oracle uses signons to determine the database information that users can access. A virtual private database determines which users can access which information, without further signon information required. You create a command block for the connection using macros that are substituted at run time for the logged on user. The macros identify the user so that the user need not re-enter signon information. If all users who access the database are defined as database users and user accounts are used for connections, you can set up the context automatically when the connection is established. For example, the macro can be substituted for the userName. The XML command block stores a series of commands that are run in the stated sequence. This may include the commands that are described in "Schema for Data Source Commands" (p. 741). The following example shows an XML command block for a virtual private database. This command block sets up a context (virtual private database) within the connection based on the passed parameter. The passed parameter is retrieved from the environment, which is related to the user's logon at the portal level. These variables can be modified in the configuration tool. Their values are user specific and obtained using the security control mechanism (CAM).
<commandBlock> <commands> <sqlCommand> <sql>BEGIN PKG_COUNTRY_CONTEXT.SP_SET_COUNTRY1 (#$account.parameters.var1#); END;</sql> </sqlCommand> </commands> </commandBlock>

194

Chapter 8: Data Sources and Connections This example shows account parameter substitution. You must specify account information as custom properties. For information about session properties, see the Framework Manager User Guide. Note: Command blocks for Oracle proxy connections and virtual private databases at the data source level apply to all connections to that data source.

Securing Data Sources

You can secure data sources using IBM Cognos 8 security or data source-specific security. The IBM Cognos 8 security for a data source does not override security policies that already exist for the data source. For example, for IBM Cognos cubes, the security may be set at the cube level. For Microsoft Analysis Server data sources, the security may be set using cube roles. Depending on the data source, one or more of the following authentication methods are available: no authentication IBM Cognos 8 logs on to the data source without providing any signon credentials. IBM Cognos 8 service credentials IBM Cognos 8 logs on to the data source using the logon specified for the IBM Cognos 8 service. Users do not require individual database signons. For production environments, however, individual database signons are generally more appropriate. external namespace IBM Cognos 8 logs on to the data source with the credentials used to authenticate to the specified authentication namespace. The namespace must be active, users must be logged on prior to accessing the data source, and the authentication credentials used for the namespace must be relevant for the data source authentication. All data sources also support data source signons defined for the Everyone group or for individual users, groups, or roles (p. 207). If the data source requires a signon, but you do not have access to a signon for this data source, you are prompted for authentication each time you access the data source.

Administration and Security Guide 195

Chapter 8: Data Sources and Connections

196

Chapter 9: Back Up Data

We recommend that you regularly back up your IBM Cognos 8 data and configuration settings, and your Framework Manager projects and models. This prevents the loss of your data should your computer be damaged or stolen. After your computer is operational, you can restore your data. Because backing up consumes system resources, if IBM Cognos 8 is running while the database is backed up, its performance will be affected. If you changed the location of the encryption and signing key settings from the default location, ensure that you back up the directory that contains them. Also, if the key stores are secured with passwords, ensure that you retain these passwords. Data you back up is meant to be restored to the same computer. For information about moving data from one computer to another, see "Deployment" (p. 307). For information about backing up data before you upgrade your software, see the upgrade topic in the IBM Cognos 8 Installation and Configuration Guide. If you use a source control system to store your Framework Manager projects, you do not need to back up your projects. If you customized any information in IBM Cognos Configuration or in the content store, ensure that it is backed up correctly.

Steps to Back Up the Content Store

1. Back up the content store. For more information, see your database documentation. 2. Copy the c8_location/configuration directory to the backup location. This directory contains the configuration settings. If you must ever restore the configuration settings, you can copy the backed-up directory to the correct location. For information about restoring the content store, see your database documentation.

Step to Back Up Framework Manager Projects and Models

Copy the Framework Manager project directory and its subdirectories to the backup location. By default, the projects and models are located in My Documents/My Projects. If you must ever restore the Framework Manager projects and models, you can copy the backedup directories to the correct location.

Administration and Security Guide 197

Chapter 9: Back Up Data

198

Chapter 10: Data Movement Entries

Data Manager is used to create and manage data warehouses and data repositories for reporting, analysis, and performance analysis. It can be used to populate data warehouse fact tables and dimension tables by extracting, merging, and transforming the operational data from multiple sources, before delivering it to coordinated data marts. Data movement tasks, such as Builds and JobStreams, are created in Data Manager Designer and can be published to IBM Cognos 8 for integrated execution. For more information, see the Data Manager User Guide. After a data movement entry is published to IBM Cognos 8, use IBM Cognos Connection to do the following: run the entry (p. 199) change default properties (p. 200).

You can schedule data movement entries to run at a specified time or based on a trigger, such as a database refresh or an email (p. 299). If you want to use an agent (p. 383) for a data movement entry, include the entry as part of a job (p. 301), and then include the job in an agent. You can view the run histories for data movement entries (p. 294)You can rerun failed data movement entries. See "Rerun a Failed Entry Task" (p. 297).

Run a Data Movement Entry

You can manually run a data movement entry at any time to perform the Data Manager tasks that it includes. You can also schedule data movement entries. For more information, see "Schedule Management" (p. 299). You must have the required permissions for the data movement entry. See "Secured Functions and Features" (p. 221).

Steps
1. In IBM Cognos Connection, click the run with options button to the data movement entry you want to run. on the actions toolbar next

2. Under Time, select Now to run the data movement entry now, or Later to specify a later date and time. 3. Click Run. The confirmation page appears. 4. Click OK.

Administration and Security Guide 199

Chapter 10: Data Movement Entries

Change Default Data Movement Entry Properties

You can change the defaults that are set for data movement entries in Data Manager, such as the owner and the language. You can run a data movement entry, schedule a data movement entry, and set the number of occurrences and duration of the run history. For more information, see "Schedule Management" (p. 299). You can disable the entry (p. 253). You can view the location of the entry in the portal and its ID (p. 243). You must have the required permissions for the data movement entry. See "Secured Functions and Features" (p. 221).

Steps
1. In IBM Cognos Connection, click the set properties button the data movement entry that you want to run. 2. Click the General tab. 3. If you want to make yourself the owner of the entry, click Make me the owner. 4. If you want to set a contact or an email address for the entry, click Set the contact and then click either Select the contact or Enter an email address. 5. If you want to change the icon associated with the entry, click Edit, specify the new icon for the entry, and click OK. 6. If you want to select a different language, select from the Language menu. 7. If you want, enter or change the Name, Description, and Screen tip for the data movement entry. 8. If you want to set Run history options, click Number of occurrences, and set the number of run repetitions, or click Duration, and set the number of days to run the entry. 9. Click OK. The next time the data movement entry runs, it uses these properties instead of the original defaults. on the actions toolbar next to

200

Chapter 11: Security Model

IBM Cognos 8 security is designed to meet the need for security in various situations. You can use it in everything from a proof of concept application where security is rarely enabled to a large scale enterprise deployment. The security model can be easily integrated with the existing security infrastructure in your organization. It is built on top of one or more authentication providers. You use the providers to define and maintain users, groups, and roles, and to control the authentication process. Each authentication provider known to IBM Cognos 8 is referred to as a namespace .

In addition to the namespaces that represent the authentication providers, IBM Cognos 8 has a built-in namespace called IBM Cognos. The Cognos namespace enhances your organization security policies and deployment ability of applications. Security in IBM Cognos 8 is optional. If security is not enabled it means that no authentication providers are configured, and therefore all user access is anonymous. Typically, anonymous users have limited, read-only access.

Authentication Providers
User authentication in IBM Cognos 8 is managed by authentication providers. Authentication providers define users, groups, and roles used for authentication. User names, IDs, passwords, regional settings, personal preferences are some examples of information stored in the providers. If you set up authentication for IBM Cognos 8, users must provide valid credentials, such as user ID and password, at logon time. In IBM Cognos 8 environment, authentication providers are also referred to as namespaces, and they are represented by namespace entries in the user interface.

IBM Cognos 8 does not replicate the users, groups, and roles defined in your authentication provider. However, you can reference them in IBM Cognos 8 when you set access permissions to reports and other content. They can also become members of Cognos groups and roles. The following authentication providers are supported in this release: Active Directory Server IBM Cognos Series 7 eTrust SiteMinder LDAP NTLM SAP

You configure authentication providers using IBM Cognos Configuration. For more information, see the Installation and Configuration Guide.

Administration and Security Guide 201

Chapter 11: Security Model

Multiple Namespaces
If multiple namespaces are configured for your system, at the start of a session you must select one namespace that you want to use. However, this does not prevent you from logging on to other namespaces later in the session. For example, if you set access permissions, you may want to reference entries from different namespaces. To log on to a different namespace, you do not have to log out of the namespace you are currently using. You can be logged on to multiple namespaces simultaneously. Your primary logon is the namespace and the credentials that you use to log on at the beginning of the session. The namespaces that you log on to later in the session and the credentials that you use become your secondary logons. When you delete one of the namespaces, you can log on using another namespace. If you delete all namespaces except for the Cognos namespace, you are not prompted to log on. If anonymous access is enabled, you are automatically logged on as an anonymous user. If anonymous access is not enabled, you cannot access the IBM Cognos Connection logon page. In this situation, use IBM Cognos Configuration to enable anonymous access.

Hiding Namespaces
You can hide namespaces from users during logon. This lets you have trusted signon namespaces without showing them on the namespace selection list that is presented when users log on. For example, you may want to integrate single signon across systems, but maintain the ability for customers to authenticate directly to IBM Cognos 8 without being prompted to choose a namespace. You can hide Custom Java Provider and eTrust SiteMinder namespaces that you configured. For more information, see the Installation and Configuration Guide.

Deleting or Restoring Unconfigured Namespaces

You can preserve namespaces and all their contents in the content store even if they are no longer configured for use in IBM Cognos 8. When a namespace is not configured, it is listed as inactive in the directory tool. An inactive namespace is one that was configured, but later deleted in IBM Cognos Configuration. The namespace can be deleted from the content store by members of the System Administrators role. You cannot log on to an inactive namespace. If a new version of IBM Cognos 8 detects a previously configured namespace that is no longer used, the namespace appears in the directory tool as inactive. You can configure the namespace again if you still require the data. If the namespace is not required, you can delete it. When you delete a namespace, you also delete all entries in My Folders that are associated with that namespace, and their contents. An active namespace cannot be deleted, but can be updated. To recreate a namespace in IBM Cognos Configuration, you must use the original ID of the namespace. For information about configuring and recreating namespaces, see the Installation and Configuration Guide.

202

Chapter 11: Security Model

Delete an Inactive Namespace

If a namespace was removed from IBM Cognos Configuration and is no longer required, a member of the System Administrators role can delete it permanently in the directory tool. Deleting a namespace also deletes all the entries in My Folders that are associated with the namespace. To access the directory administration tool, you must have execute permissions for the directory secured feature and traverse permissions for the administration secured function.

Steps
1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Security tab, click Users, Groups, and Roles. If the namespace you want to delete does not have a check mark in the Active column, it is inactive and can be deleted. 3. In the Actions column, click the delete button. If the namespace is active, the delete button is not available. The namespace is permanently deleted. To use the namespace again in IBM Cognos 8, you must add it using IBM Cognos Configuration.

Authorization
Authorization is the process of granting or denying access to data, and specifying the actions that can be performed on that data, based on a user identity. IBM Cognos 8 authorization assigns permissions to users, groups, and roles that allow them to perform actions, such as read or write, on content store objects, such as folders and reports. The content store can be viewed as a hierarchy of data objects. These objects include not only folders and reports, but packages for report creation, directories, and servers. When IBM Cognos 8 administrators distribute reports to users, they can set up folders in which reports and other objects can be stored. They can then secure those folders so that only authorized personnel can view, change, or perform other tasks using the folder contents. For information about setting access permissions to the IBM Cognos 8 entries, see "Access Permissions" (p. 213). For information about the Content Manager hierarchy of objects and the initial access permissions, see "Initial Access Permissions " (p. 691).

Cognos Namespace
The Cognos namespace is the IBM Cognos 8 built-in namespace. It contains the IBM Cognos objects, such as groups, roles, data sources, distribution lists, and contacts. During the content store initialization, built-in and predefined security entries are created in this namespace (p. 233). You must modify the initial security settings for those entries and for the Cognos namespace immediately after installing and configuring IBM Cognos 8 (p. 236).

Administration and Security Guide 203

Chapter 11: Security Model You can rename the Cognos namespace using IBM Cognos Configuration, but you cannot delete it. The namespace is always active. When you set security in IBM Cognos 8, you may want to use the Cognos namespace to create groups and roles that are specific to IBM Cognos 8. In this namespace, you can also create security policies that indirectly reference the security entries in authentication providers so that IBM Cognos 8 can be more easily deployed from one installation to another (p. 308). The Cognos namespace always exists in IBM Cognos 8, but the use of Cognos groups and roles it contains is optional. The groups and roles created in the Cognos namespace repackage the users, groups, and roles existing in the authentication providers to optimize their use in the IBM Cognos 8 environment. For example, in the Cognos namespace, you can create a group called HR Managers and add to it specific users and groups from your corporate IT and HR organizations defined in your authentication provider. Later, you can set access permissions for the HR Managers group to entries in IBM Cognos 8.

IBM Cognos Application Firewall

IBM Cognos Application Firewall (CAF) is a security tool used to supplement the existing IBM Cognos 8 security infrastructure at the application level. CAF analyzes, modifies, and validates HTTP and XML requests before the gateways or dispatchers process them, and before they are sent to the requesting client or service. It acts as a smart proxy for the IBM Cognos product gateways and dispatchers, and prevents the IBM Cognos 8 components from malicious data. The most common forms of malicious data are buffer overflows and cross-site scripting (XSS) attacks, either through script injection in valid pages or redirection to other Web sites. IBM Cognos Application Firewall (CAF) provides IBM Cognos 8 components with security features that include data validation and protection (p. 204), logging and monitoring (p. 205), and output protection. CAF is enabled by default, and should not be disabled. You can update CAF independently of the other IBM Cognos 8 components. For more information about CAF, see the Installation and Configuration Guide, and the Architecture and Deployment Guide.

Data Validation and Protection

Validation of input data ensures that the data is in the expected format, based on a set of pre-defined variable rules. HTML variables, XML data, cookie values, and parameters are checked against this set of rules. CAF performs positive validation of parameters instead of only searching for known script injection tags or common SQL injection signatures. Each parameter is validated against a rule that expects a certain data type in a certain format. If the data does not match the CAF rule, it is rejected. To provide even stronger validation, CAF matches regular expression patterns to protect data inputs that use complicated formats.

204

Chapter 11: Security Model

Valid Domain or Host List

A common type of attack is to trick a user into going to a harmful site by modifying the form parameters. The back button and error URL features of a product provide a prime target for this type of attack. CAF limits the list of hosts and domains that a back URL can access. CAF can be configured with a list of host names, including port numbers and domains. If a back URL contains a host or a domain that does not appear in the list, the request is rejected. By default, the host name of the dispatcher is added to the list. You can configure the list using IBM Cognos Configuration. For more information, see the Installation and Configuration Guide.

Logging and Monitoring

IBM Cognos Application Firewall (CAF) can monitor and log all access to IBM Cognos gateways and dispatchers. Use logging to track possible attacks or misuse of your IBM Cognos applications. You can configure CAF to log access to a specific file or to use IBM Cognos log application (IPF) logging. If logging is enabled, all requests that fail validation by CAF are logged. For more information, see the Installation and Configuration Guide. Tip: You can use the Web server request log to obtain detailed information about the IP address of the source client in a suspected attack.

Cross-Site Scripting (XSS) Encoding

Many customers use other applications, such as eTrust SiteMinder, to check for cross-site scripting vulnerabilities. These products block HTTP get requests that contain specific characters. CAF encodes characters in Cascading Style Sheets (CSS) with URLs to prevent other cross-site scripting tools from blocking the characters. The CAF XSS encoding feature applies only to customers who use the IBM Cognos Connection portal. CAF XSS encoding is disabled by default. To enable this feature, use IBM Cognos Configuration. For more information, see the Installation and Configuration Guide.

Filtering of Error Messages

Some error messages may contain sensitive information, such as server names. By default, error message details in IBM Cognos 8 are routed to IPF log files, and the secure error message option is enabled. The information presented to users indicates only the occurrence of an error, without any details. You can specify who can retrieve full error details that may include sensitive information by changing the Detailed Errors capability in IBM Cognos 8 administration. Typically, this capability is assigned to directory administrators, but you can assign it to other users as well. For more information, see "Secured Functions and Features" (p. 221). For information about retrieving full error details, see "View Full Details for Secure Error Messages" (p. 88).

Administration and Security Guide 205

Chapter 11: Security Model

Parameter Signing
Parameter signing protects parameter values against tampering when they are sent to a Web browser. CAF can sign parameters or specific parts of data. Signing is used only in specific situations. It is enabled when CAF is enabled.

206

Chapter 12: Users, Groups, and Roles

Users, groups, and roles are created for authentication and authorization purposes. You can use groups and roles created in IBM Cognos 8, and users, groups, and roles created in authentication providers. The groups and roles created in IBM Cognos 8 are referred to as Cognos groups and Cognos roles.

Users
A user entry is created and maintained in an authentication provider to uniquely identify a human or a computer account. You cannot create user entries in IBM Cognos 8.

Information about users, such as first and last names, passwords, IDs, locales, and email addresses, is stored in the providers. However, this may not be all the information required by IBM Cognos 8. For example, it does not specify the location of the users personal folders, or format preferences for viewing reports. This additional information about users is stored in IBM Cognos 8, but when addressed in IBM Cognos 8, the information appears as part of the external namespace.

Series 7 Users
If you configured the IBM Cognos Series 7 authentication provider (p. 201), a user from that namespace must belong to at least one Access Manager user class for the user to be usable in IBM Cognos 8. For example, if you create a new user in Series 7 Access Manager and assign the user to a user class, but then remove the user from that user class, you cannot log on as that user in IBM Cognos 8.

Deleting and Recreating Users

For Series 7 and NTLM authentication providers, you cannot maintain associated properties and items when you delete and re-create a user. For example, if a user creates an object in My Folders, and then that user is deleted, the My Folders objects are no longer associated with that user. If a user with the same name is re-created, the objects are not reinstated. If you use an LDAP server, the stability of My Folders objects depends on how you use the IDs. If the configuration of the LDAP provider uses the default attribute of dn for the Unique identifier parameter, a reinstated user with the same name keeps the My Folders objects of the original user. If you change the Unique identifier parameter to a unique attribute set by the LDAP server, for example, nsuniqueid for Sun Java System, the association of My Folders objects is lost for a deleted user and a new My Folders will be created for a user of the same name. You can delete, copy, and change user profiles. For more information, see "Managing User Profiles" (p. 339).

Administration and Security Guide 207

Chapter 12: Users, Groups, and Roles

User Locales
A locale specifies linguistic information and cultural conventions for character type, collation, format of date and time, currency unit, and messages. You can specify locales for individual products, content, servers, authors, and users in IBM Cognos 8. User locale refers to the product and content locales for each IBM Cognos 8 user. Requests from users arrive with an associated locale. IBM Cognos 8 must determine the language and locale preferences of users and enforce an appropriate response locale when you distribute reports in different languages. A user locale specifies the default settings that a user wants to use for formatting dates, times, currency, and numbers. IBM Cognos 8 uses this information to present data to the user. IBM Cognos 8 obtains a value for user locale by checking these sources, in the order listed: user preference settings If the user sets the user preference settings in IBM Cognos Connection, IBM Cognos 8 uses these settings for the users product and content locale and for default formatting options. The user preference settings override the values obtained from the authentication provider. authentication provider If the authentication provider has locale settings that are configured, IBM Cognos 8 uses these values for the users product and content locale. browser setting Anonymous and guest users cannot set user preference settings. For these users, IBM Cognos 8 obtains a user locale from the browser stored on the users computer.

Groups and Roles

Groups and roles represent collections of users that perform similar functions, or have a similar status in an organization. Examples of groups are Employees, Developers, or Sales Personnel. Members of groups can be users and other groups. When users log on, they cannot select a group they want to use for a session. They always log on with all the permissions associated with the groups to which they belong. Roles in IBM Cognos 8 have a similar function as groups. Members of roles can be users, groups, and other roles. The following diagram shows the structure of groups and roles.

Group

Role

User

Group

User

Group

Role

208

Chapter 12: Users, Groups, and Roles Users can become members of groups and roles defined in IBM Cognos 8, and groups and roles defined in authentication providers. A user can belong to one or more groups or roles. If users are members of more than one group, their access permissions are merged. You create Cognos groups and roles when you cannot create groups or roles in your authentication provider groups or roles are required that span multiple namespaces portable groups and roles are required that can be deployed Create the required groups and roles in your authentication provider, and add them to the appropriate Cognos groups and roles. you want to address specific needs of IBM Cognos 8 administration you want to avoid cluttering your organization security systems with information used only in IBM Cognos 8

Series 7 Roles
If you have configured the IBM Cognos Series 7 authentication provider (p. 201), user collections known as user classes in Series 7 appear as roles in IBM Cognos 8. You can access Series 7 and IBM Cognos 8 using a single logon. If you start your session by logging on to Series 7, and then access IBM Cognos 8, you automatically assume the roles that were in effect for you in Series 7 when you first logged on. You cannot assume different Series 7 roles. Users can assume different roles in Series 7 after they access IBM Cognos 8.

Roles Used to Run Reports and Jobs

The roles used to run reports and jobs are associated with the users who run the reports interactively (p. 348), who are the report owners, and whose credentials are used to run scheduled reports and jobs (p. 299). Depending on the options selected to run reports, different roles can be assumed by the process. When a report runs that has the run as the owner option selected, the process assumes all the roles associated with the report owner (p. 215). When a scheduled report or job runs, the session assumes all the roles associated with the user whose credentials were used to process the request (p. 218).

Distribution Lists as Members of Groups and Roles

In some namespaces, such as Microsoft Active Directory, a distribution list may appear on the Members tab of the Set properties page for a group or role. However, you cannot add distribution lists to a group or role membership, and you cannot use them to set access permissions for entries in the IBM Cognos 8 user interface. You can add an IBM Cognos distribution list to an Cognos group or role membership using the Software Development Kit (SDK). However, the SDK cannot be used to add an Active Directory distribution list to an Active Directory group. The Active Directory management tools must be used to do this.

Administration and Security Guide 209

Chapter 12: Users, Groups, and Roles

IBM Cognos Controller Groups and Roles

For IBM Cognos 8, use IBM Cognos Controller groups and roles to configure security. For information about using these groups and roles to configure security, see the IBM Cognos Controller Installation and Configuration Guide.

Create an Cognos Group or Role

The members of Cognos groups can be users or other groups. The members of Cognos roles can be users, groups, or other roles. You can add entries from multiple namespaces, created both in the authentication providers and in IBM Cognos 8, as members of Cognos groups. You can also create empty groups that do not have any members. If you plan to create groups or roles that reference entries from multiple namespaces, you must log on to each of those namespaces before you start your task. Otherwise, you will not have full administrative rights for the entries you want to reference. We recommend that you use the Cognos roles and roles when you set up access permissions to entries in IBM Cognos 8 because it simplifies the process of deployment (p. 308). When you delete an Cognos group or role, users access permissions based on it are no longer active. You cannot restore access permissions by creating a group or role with the same name. To administer users, groups, and roles, you must have execute permissions for the Users, Groups, and Roles secured feature, and traverse permissions for the Administration secured function (p. 693).

Steps
1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Security tab, click Users, Groups, and Roles. 3. Click the Cognos namespace. Tip: If you want to delete an Cognos group or role, select the check box next to it and click the delete button. 4. On the toolbar, click the new group or new role button.

5. In the Specify a name and description page, type a name and, if you want, a description for the new group or role, and then select a destination folder and click Next. 6. If you want to create a group without members, click Finish. 7. If you want to add members to the new group or role, click Add and choose how to select the users, groups, or roles: To choose from listed entries, click the appropriate namespace, and then select the check boxes next to the users, groups, or roles. To search for entries, click Search and in the Search string box, type the phrase you want to search for. For search options, click Edit. Find and click the entry you want.

210

Chapter 12: Users, Groups, and Roles To type the name of entries you want to add, click Type and type the names of groups, roles, or users using the following format, where a semicolon (;) separates each entry: namespace/group_name;namespace/role_name;namespace/user_name; Here is an example: Cognos/Authors;LDAP/scarter; 8. Click the right-arrow button and when the entries you want appear in the Selected entries box, click OK. Tips: To remove entries from the Selected entries list, select them and click Remove. To select all entries in a list, click the check box in the upper-left corner of the list. To make the user entries visible, click Show users in the list. 9. Click Finish.

Add or Remove Members of an Cognos Group or Role

You can modify the membership of an Cognos group or role by adding or removing members. When you remove users, groups, or roles from an Cognos group or role, you do not delete them from the authentication provider or from IBM Cognos 8. If you plan to modify groups or roles that reference entries from multiple namespaces, you must log on to each of those namespaces before you start your task. Otherwise, you will not have full administrative rights for the entries you want to modify. To administer users, groups, and roles, you must have execute permissions for the Users, Groups, and Roles secured feature, and traverse permissions for the Administration secured function (p. 693).

Steps
1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Security tab, click Users, Groups, and Roles. 3. Click the Cognos namespace. 4. In the Actions column, click the properties button for the group or role whose membership you want to modify. 5. Click the Members tab. 6. If you want to add members, click Add and choose how to select members: To choose from listed entries, click the appropriate namespace, and then select the check boxes next to the users, groups, or roles. To search for entries, click Search and in the Search string box, type the phrase you want to search for. For search options, click Edit. Find and click the entry you want. To type the name of entries you want to add, click Type and type the names of groups, roles, or users using the following format, where a semicolon (;) separates each entry: Administration and Security Guide 211

Chapter 12: Users, Groups, and Roles namespace/group_name;namespace/role_name;namespace/user_name; Here is an example: Cognos/Authors;LDAP/scarter; 7. Click the right-arrow button and when the entries you want appear in the Selected entries box, click OK. Tips: To remove entries from the Selected entries list, select them and click Remove. To select all entries in a list, click the check box in the upper-left corner of the list. To make the user entries visible, click Show users in the list. 8. To remove members from an Cognos group or role, in the Set Properties page, specify which users, groups, or roles to remove, and click Remove. 9. Click OK.

212

Chapter 13: Access Permissions

In IBM Cognos 8, you can secure your organizations data by setting access permissions for the entries. You specify which users and groups have access to a specific report or other content in IBM Cognos 8. You also specify the actions they can perform on the content. When you set access permissions, you can reference both authentication provider users, groups, and roles and Cognos groups and roles. However, if you plan to deploy your application in the future, we recommend that you use only the Cognos groups and roles to set up access to entries in IBM Cognos 8 to simplify the process (p. 216).

Permissions and Permitted Actions

You can grant or deny the following access permissions.

Permissions
Read

Icons

Permitted Actions
View all the properties of an entry, including the report specification, report output, and so on, which are properties of a report. Create a shortcut to an entry.

Write

Modify properties of an entry. Delete an entry. Create entries in a container, such as a package or a folder. Modify the report specification for reports created in Report Studio and Query Studio. Create new outputs for a report.

Administration and Security Guide 213

Chapter 13: Access Permissions

Permissions
Execute

Icons

Permitted Actions
Process an entry. For entries such as reports, agents, and metrics, the user can run the entry. For data sources, connections, and signons, the entries can be used to retrieve data from a data provider. The user cannot read the database information directly. The report server can access the database information on behalf of the user to process a request. IBM Cognos 8 verifies whether users have execute permissions for an entry before they can use the entry. For credentials, users can permit someone else to use their credentials.

Note: Users must have execute permissions for the account they use with the run as the owner report option. Set policy Read and modify the security settings for an entry.

Traverse

View the contents of a container entry, such as a package or a folder, and view general properties of the container itself without full access to the content. Note: Users can view the general properties of the entries for which they have any type of access. The general properties include name, description, creation date, and so on, which are common to all entries.

Access Permissions for Users

Users must have at least traverse permissions for the parent entries of the entries they want to access. The parent entries include container objects such as folders, packages, groups, roles, and namespaces. Permissions for users are based on permissions set for individual user accounts and for the namespaces, groups, and roles to which the users belong. Permissions are also affected by the membership and ownership properties of the entry. IBM Cognos 8 supports combined access permissions. When users who belong to more than one group log on, they have the combined permissions of all the groups to which they belong. This is important to remember, especially when you are denying access. Tip: To ensure that a user or group can run reports from a package, but not open the package in an IBM Cognos studio, grant the user or group execute and traverse permissions on the package. 214

Chapter 13: Access Permissions

Access Permissions Required for Actions

To perform specific actions, each user, group, or role needs the right combination of access permissions granted for the entry, its parent entry, and its source and target entry. The following table lists permissions required for specific actions.

Action
Add an entry Query the entry properties View the children of the entry Update an entry Delete an entry

Permissions required
Write permissions for a parent entry Read permissions for an entry Traverse permissions for an entry Write permissions for an entry Write permissions for an entry, and write permissions for a parent entry Read permissions for an entry and any child entries, traverse permissions for all of the children, and write and traverse permissions for the target parent entry Read and write permissions for an entry, write permissions for both the source parent entry and the target parent entry, and traverse permissions for the target parent entry

Copy an entry

Move an entry

Ownership of Entries
If the user is an owner of an entry, the user has full access rights for the entry. This ensures that users can always access and modify the entries they own. By default, the owner of the entry is the user who creates the entry. However, any other user who has set policy permissions for the entry can take ownership of the entry.

Granted and Denied Access

You can grant access or deny access to entries. An icon that represents the type of access appears next to the entry name on the Permissions tab. For example, when a group has execute permissions for a report, this icon appears next to the group name on the Permissions tab for the report. appears next to the group

When a group has execute permissions denied for a report, this icon name.

Denied access has precedence over granted access. When you deny specific users or groups access to an entry, you replace other security policies that grant access to the entry. If the grant and deny permissions are in conflict, access to the entry is always denied. For example, a user belongs to two groups. One group has access granted to a report and the other group has access denied to the same report. Access to this report is denied for the user.

Administration and Security Guide 215

Chapter 13: Access Permissions Deny access only when it is really required. Typically, it is a better administrative practice to grant permissions than to deny them.

Parent/Child Permissions
Access permissions are acquired from parent entries. If access permissions are not defined, the entry acquires permissions from its parent entry. You can replace parent permissions by defining permissions for the child entry. Objects that exist only as children of other objects always acquire permissions from their parents. Examples of such objects are report specifications and report outputs. They are visible through the SDK. You cannot set permissions specifically for those objects.

Permissions and Deployment

If you are an administrator who is deploying to a target environment, see "Deployment" (p. 307).

Capabilities Permissions
If you are an administrator, you set access to the secured functions and features by granting execute permissions for specified namespaces, users, groups, or roles. For more information, see "Secured Functions and Features" (p. 221).

Deleting Cognos Groups and Roles

When you delete an Cognos group or role, access permissions based on it are also deleted. You cannot restore them by creating a new group or role with the same name because this entry has a different internal ID. If your groups or roles are created by authentication providers, check how your authentication provider deals with such situations. Typically, you cannot recreate access permissions if they are based on IDs but you can if they are based on names.

Accessing Entries Associated with Data Sources Secured Against Multiple Namespaces
Data sources in IBM Cognos 8 can be secured against multiple namespaces. In some environments, the namespace used to secure the data source is not the primary namespace used for access to IBM Cognos Connection. When you try to access an entry, such as a report, a query, or an analysis, that is associated with a data source secured against multiple namespaces, and you are not logged on to all of the required namespaces, a prompt for authentication appears. You must log on to the namespace before you can access the entry. When single signon (SSO) is enabled, the prompt for authentication does not appear. You are automatically logged on to the namespace. This functionality applies to Cognos Viewer only. If a similar situation occurs in an IBM Cognos 8 studio, you must quit your task and log on to all the namespaces that you want to use in the current session.

Set Access Permissions for an Entry

Setting access permissions for an entry includes creating new permissions or updating existing permissions. You can specify access permissions for all entries in IBM Cognos 8. Some examples of 216

Chapter 13: Access Permissions such entries are reports, queries, analyses, packages, agents, metrics, namespaces, groups, users, or dispatchers. You can reference entries from different namespaces. If you plan to set permissions that reference multiple namespaces, you must log on to each of those namespaces before you start your task. Otherwise, you do not have full administrative rights for the entries you want to modify. To administer security, you must have set policy permissions.

Steps
1. In IBM Cognos Connection, locate the entry for which you want to set access permissions. 2. In the Actions column, click the set properties button 3. In the Set properties page, click the Permissions tab. 4. Choose whether to use the permissions of the parent entry or specify permissions specifically for the entry: To use the permissions of the parent entry, clear the Override the access permissions acquired from the parent entry check box, then click OK if you are prompted to use the parent permissions. Click OK. To set access permissions for the entry, select the Override the access permissions acquired from the parent entry check box, then proceed to step 5. 5. If you want to remove an entry from the list, select its check box and click Remove. Tip: If you want to select all entries, select the check box at the top of the list in the upper-left corner. Clear the check box to deselect all entries. 6. To specify the entries for which you want to grant or deny access, click Add, then choose how to select entries: To choose from listed entries, click the appropriate namespace, and then select the check boxes next to the users, groups, or roles. To search for entries, click Search and in the Search string box, type the phrase you want to search for. For search options, click Edit. Find and click the entry you want. To type the name of entries you want to add, click Type and type the names of groups, roles, or users using the following format, where a semicolon (;) separates each entry: namespace/group_name;namespace/role_name;namespace/user_name; Here is an example: Cognos/Authors;LDAP/scarter; 7. Click the right-arrow button and when the entries you want appear in the Selected entries box, click OK. Tips: To remove entries from the Selected entries list, select them and click Remove. To select all entries in a list, click the check box in the upper-left corner of the list. To make the user entries visible, click Show users in the list. Administration and Security Guide 217 for the entry.

Chapter 13: Access Permissions 8. For each entry in the list, in the box next to the list, select or clear check boxes to specify what type of access you want to grant or deny. 9. Click Apply. In the Permissions column, an icon appears next to the user, group, or role. This icon represents the type of access granted or denied to the entry. 10. If you want to replace the existing permissions of the child entries with the permissions you set for this entry, in the Option section, select the Delete the access permissions of all child entries check box. This option appears only with the entries that are containers. You can use it to restrict access to a hierarchy of entries. 11. Click OK.

Trusted Credentials
Trusted credentials are used for users who must perform a task or process, but do not have sufficient access permissions for entries that contain sensitive data, such as database signons and group memberships. Users with more extensive access permissions, who own the entries, can authorize a trusted user to use their credentials to access the entries. Trusted credentials are also used to run scheduled requests when users are not logged on to IBM Cognos 8, for example, overnight. When the request runs, a user session is created. The trusted credential is used to log on to IBM Cognos 8 as the user the trusted credential represents and the user's access permissions are used to run the report or the job. The credentials are stored as part of the account object in the namespace.

Create Trusted Credentials

You can create trusted credentials (p. 218) when you want to authorize other users to use your credentials when those users do not have sufficient access permissions to perform specific tasks. For users to use trusted credentials, traverse permissions must be granted for the namespace.

Steps
1. In IBM Cognos Connection, in the upper-right corner, click the my area button erences. 2. On the Personal tab, under Credentials, if you have not created credentials before, click Create the Credentials. 3. Select the users, groups, or roles you want to authorize to use your credentials. If you are prompted for your credentials, provide your user ID and password. 4. If you want to add entries, click Add then choose how to select entries: To choose from listed entries, click the appropriate namespace, and then select the check boxes next to the users, groups, or roles. , My Pref-

218

Chapter 13: Access Permissions To search for entries, click Search and in the Search string box, type the phrase you want to search for. For search options, click Edit. Find and click the entry you want. To type the name of entries you want to add, click Type and type the names of groups, roles, or users using the following format, where a semicolon (;) separates each entry: namespace/group_name;namespace/role_name;namespace/user_name; Here is an example: Cognos/Authors;LDAP/scarter; 5. Click the right-arrow button and when the entries you want appear in the Selected entries box, click OK. Tips: To remove entries from the Selected entries list, select them and click Remove. To select all entries in a list, click the check box in the upper-left corner of the list. To make the user entries visible, click Show users in the list. 6. If you want to remove an entry from the list, select the check box next to it and click Remove. 7. Ensure that the list contains only the users, groups, or roles that you want, and click OK.

Administration and Security Guide 219

Chapter 13: Access Permissions

220

Chapter 14: Secured Functions and Features

The secured functions and secured features capabilities within the functions, which are also referred to as

, control access to different administration tasks and different functional areas of

the user interface in IBM Cognos 8 (p. 221). Examples of the secured functions are Administration and Report Studio. Examples of the secured features are User Defined SQL and Bursting (p. 221). Content Manager reads the users permissions at logon time. Depending on the permissions for the secured functions and features, users can access specific components and perform specific tasks in IBM Cognos 8. When a content store is initialized, the initial permissions for the secured functions and features are created (p. 693). The permissions define which of the predefined and built-in Cognos groups and roles have access to which secured functions and features, and the type of access. The initial permissions grant unrestricted access to IBM Cognos 8 because the built-in role System Administrators includes the group Everyone in its membership. You must remove the group Everyone from the membership of System Administrators before you start setting access to capabilities. For more information, see "Initial Security" (p. 233). When running a report using the Run as the owner option, the capabilities of the owner are used for bursting and report layout properties in the HTML format. All other capabilities are based on the user who runs the report. Administrators can set up access to the secured functions and features using the Capabilities page on the Security tab in IBM Cognos Administration (p. 225). Users can see a list of the secured functions and features available to them in My Area the Capabilities section. The secured functions and features include the following. of the portal, in My Preferences, Personal,

Adaptive Analytics
This secured function controls access to the reports packaged using Adaptive Analytics.

Administration
This secured function contains the secured features that control access to the administration pages that you use to administer IBM Cognos 8. System administrators can use this capability to delegate administration tasks to different administrators. The secured features associated with this function are Adaptive Analytics Administration Users can access Adaptive Analytics to perform administrative tasks. Administration tasks Users can access Content Administration on the Configuration tab in IBM Cognos Administration to administer exports, imports, index updates, consistency checks, and report updates. Administration and Security Guide 221

Chapter 14: Secured Functions and Features Configure and manage the system Users can access System on the Status tab and Dispatchers and Services on the Configuration tab in IBM Cognos Administration to configure dispatchers and services, and to manage the system. Controller Administration Users can use the administrative functions of IBM Cognos 8 Controller. Data Source Connections Users can access Data Source Connections on the Configuration tab in IBM Cognos Administration to define data sources, connections, and signons. Distribution Lists and Contacts Users can access Distribution Lists and Contacts on the Configuration tab in IBM Cognos Administration to manage distribution lists and contacts. Metric Studio Administration Users can create new metric packages using the new metric package wizard in IBM Cognos Connection, and access the Tools menu in Metric Studio. Planning Administration Users can access IBM Cognos 8 Planning - Contributor Administration Console and IBM Cognos 8 Planning - Analyst to perform administration tasks. Printers Users can access Printers on the Configuration tab in IBM Cognos Administration to manage printers. Run activities and schedules Users can access Current Activities, Past Activities, Upcoming Activities and Schedules on the Status tab in IBM Cognos Administration to monitor the server activities and manage schedules. To grant access to the scheduling functionality independently from the monitoring functionality, use the Scheduling capability. Set capabilities and manage UI profiles Users can access Capabilities and User Interface Profiles on the Security tab in IBM Cognos Administration to manage the secured functions and features and the Report Studio user interface profiles. Styles and portlets Users can access Styles and Portlets on the Configuration tab in IBM Cognos Administration to manage styles and portlets. Users, Groups and Roles Users can access Users, Groups and Roles on the Security tab in IBM Cognos Administration to manage namespaces, users, groups, and roles.

222

Chapter 14: Secured Functions and Features

Analysis Studio
This secured function controls access to Analysis Studio.

Cognos Viewer
This secured function controls access to Cognos Viewer, which you use to view reports. The secured features associated with this function are Context Menu Users can use the context menu in Cognos Viewer. Note: To see the context menu, users must have access to both the Selection and Context Menu secured features. Run With Options Users can change the default run options. Selection Users can select text in lists and crosstabs. Toolbar Users can see the Cognos Viewer toolbar.

Controller Studio
This secured function controls access to IBM Cognos 8 Controller.

Data Manager
This secured function controls access to IBM Cognos 8 Data Manager.

Detailed Errors
This secured function controls access to viewing detailed error messages in the Web browser.

Drill Through Assistant

This secured function controls access to the drill-through debugging functionality in the drill-through Go To page. Users who have this capability see additional information in the Go To page for each drill-through target. This information can help to debug a drill-through definition, or can be forwarded to the Cognos Software Services representative.

Event Studio
This secured function controls access to Event Studio.

Glossary
This secured function controls access to the IBM WebSphere Business Glossary.

Hide Entries
This secured function specifies that a user can hide entries and view hidden entries in IBM Cognos 8.

Administration and Security Guide 223

Chapter 14: Secured Functions and Features The Hide this entry check box appears on the General tab of the entries properties pages. The Show hidden entries check box appears on the Preferences tab in user profiles, and on the General tab in My area , My Preferences.

Lineage
This secured function controls access to the Lineage action. Use this to view information about data or metadata items from Cognos Viewer, or from the source tree in Report Studio, Query Studio, and Analysis Studio.

Metric Studio
This secured function controls access to Metric Studio. The secured feature associated with this function is Edit View Use the edit features of Metric Studio to edit metric content.

Planning Contributor
This secured function controls access to IBM Cognos 8 Planning - Contributor and IBM Cognos 8 Planning - Analyst.

Query Studio
This secured function controls access to the Query Studio, which you use to create simple, ad hoc reports. The secured features associated with this function are Create Create new reports and use the Save as option for new reports and custom views. Advanced Use advanced authoring features, such as creating complex filters, formatting style, and multilingual support.

Report Studio
This secured function controls access to Report Studio, which you use to author professional reports. The secured features associated with this function are Bursting Users can author and run burst reports. Create/Delete Users can create new reports, use the Save as option for new reports and report views, and change models. HTML Items in Report

224

Chapter 14: Secured Functions and Features Users can use the button, HTMLItem, and hyperlink elements of the report specification when authoring reports. User Defined SQL Users can edit the SQL statements directly in the query specification and run the query specifications that contain the edited SQL statements. Note: Restrictions on who can use this feature are not enforced in Framework Manager. For example, a Framework Manager user who does not have User Defined SQL rights in IBM Cognos Administration can still create a query subject and use manually created SQL queries to search a database.

Scheduling
This secured function controls access to the scheduling functionality for items that can be run, such as reports. The secured feature associated with this function is Scheduling Priority Users can set up and change the processing priority of scheduled entries.

Set Entry-Specific Capabilities

This secured function specifies that a user can set up capabilities at an entry level. The Capabilities tab appears in the Set properties pages for packages and folders for users who have this capability and who have set policy permissions for the entry or who own the entry.

Specification Execution
This secured function specifies that a user or SDK application can use an inline specification. IBM Cognos 8 studios and some services use inline specifications internally to perform tasks. The service running the specification tests a number of capabilities to ensure that the user is entitled to use the inline specification. For more information, see the runSpecification method in the Developer Guide. This capability is required to author Data Manager tasks.

Use 'Full text and all fields' Search

Use the Full text and all fields option in the search.

Watch Rules
This secured function controls access to the Rules tab in My Watch Items in IBM Cognos Connection. Use this secured function to create and run watch rules.

Set Access to a Secured Function or Feature

You set access to the secured functions and features by granting execute permissions for them to specified namespaces, users, groups, or roles. If you set permissions for a secured feature, you Administration and Security Guide 225

Chapter 14: Secured Functions and Features must grant execute permissions for the feature and traverse permissions for its parent secured function. For example, to grant access to Report Studio and all its functionality, you grant execute permissions for the Report Studio secured function. If you want to grant access only to the Create/Delete secured feature within Report Studio, grant traverse permissions for the Report Studio secured function and execute permissions for the Create/Delete secured feature. You must have set policy permissions to administer secured functions and features. Typically, this is done by directory administrators. Before you start setting permissions on capabilities, ensure that the initial security settings are already changed.

Steps
1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Security tab, click Capabilities. A list of available secured functions appears. 3. Choose whether to set access for a function or for a feature: To set access for a function, click the actions button click Set properties. To set access for a feature, click the actions button next to the feature name, and click Set properties. Tip: Functions that have secured features have links. 4. Click the Permissions tab. 5. Choose whether to use the permissions of the parent entry or specify different permissions: To use the permissions of the parent entry, clear the Override the access permissions acquired from the parent entry check box, and click OK. To set access permissions explicitly for the entry, select the Override the access permissions acquired from the parent entry check box, and then perform the remaining steps. 6. If you want to remove an entry from the list, select its check box and click Remove. Tip: To select or deselect all entries in a page, click Select all or Deselect all at the bottom of the list. 7. If you want to add new entries to the list, click Add and choose how to select entries: To choose from listed entries, click the appropriate namespace, and then select the check boxes next to the users, groups, or roles. To search for entries, click Search and in the Search string box, type the phrase you want to search for. For search options, click Edit. Find and click the entry you want. next to the function name, and

226

Chapter 14: Secured Functions and Features To type the name of entries you want to add, click Type and type the names of groups, roles, or users using the following format, where a semicolon (;) separates each entry: namespace/group_name;namespace/role_name;namespace/user_name; Here is an example: Cognos/Authors;LDAP/scarter; 8. Click the right-arrow button and when the entries you want appear in the Selected entries box, click OK. Tips: To remove entries from the Selected entries list, select them and click Remove. To select all entries in a list, click the check box in the upper-left corner of the list. To make the user entries visible, click Show users in the list. 9. Select the check box next to the entry for which you want to set access to the function or feature. 10. In the box next to the list, select the proper check boxes to grant execute permissions the entry. 11. Click Apply. In the Permissions column, an icon that denotes the execute permissions granted appears next to the namespace, user, group, or role. 12. Repeat steps 8 to 10 for each entry. 13. Click OK. for

Set Access to the Report Studio User Interface Profiles

To meet the needs of both regular report authors and financial report authors, Report Studio provides distinct custom user interfaces that contain reporting features relevant to these roles. The following user interfaces are supported: Professional Authoring Mode The Professional authoring mode gives users access to the full range of Report Studio functionality. In this mode, you can create any report type, including charts, maps, lists, and repeaters, using any data source (relational or multi-dimensional). Express Authoring Mode The Express authoring mode provides a simplified and focused Report Studio interface. It is designed for non-technical users to create traditional financial and management statement reports. It only allows access to dimensionally-modeled data and uses a member-oriented data tree. This authoring mode supports only crosstab reports, for users who want a default financial layout, with indentation and single member insertion. A Windows-like toolbar offers buttons to easily style your reports rather than using property sheets.

Administration and Security Guide 227

Chapter 14: Secured Functions and Features In addition, a page section and context area (similar to Analysis Studio) allow you to easily create multi-page, filtered, and prompted crosstabs. To support the different authoring modes in Report Studio, IBM Cognos Administration provides two User Interface Profiles named Professional and Express. Use the Professional profile to set access to the Professional mode, and the Express profile to set access to the Express mode. If users have access to both the Professional and Express authoring modes, they can later switch between the two in Report Studio. For more information, see the Report Studio Professional Authoring User Guide.

Steps
1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Security tab, click User Interface Profiles. 3. Specify access permissions for the user interface profile you want To grant access to the Professional authoring mode, click the actions button Professional, and click Set properties. To grant access to the Express authoring mode, click the actions button next to Express, and click Set properties. The Permissions page appears. 4. Select the Override the access permissions acquired from the parent entry check box. 5. In the box on the left, select the check box next to the user, group, or role for which you want to grant access to this user interface profile. 6. In the box on the right, grant execute groups, or roles. No other permissions are required. 7. Click OK. For more detailed information about setting access permissions, see "Set Access Permissions for an Entry" (p. 216). and traverse permissions for the selected users, next to

228

Chapter 15: Object Capabilities

Object capabilities specify the secured functions and features (p. 221) that users, groups, or roles can use with different packages. For example, the capabilities define the studio to open a package and the studio features available while working with this package. The secured functions and their features, also referred to as global capabilities, control access to the different components and functionality in IBM Cognos 8. For object capabilities to work, you must combine them with applicable global capabilities. For example, when setting up object capabilities for a package that contains Report Studio and Query Studio reports, ensure that the user also has access to the Report Studio and Query Studio secured functions and their applicable secured features. Republishing an existing package from a client tool, such as Framework Manager, does not overwrite or modify object capabilities previously specified in IBM Cognos Connection. Control object capabilities with the Set Entry-Specific Capabilities secured function (p. 225). You can set up the following object capabilities for individual packages (p. 231).

Adaptive Analytics
This secured function controls access to the reports packaged using Adaptive Analytics.

Analysis Studio
This secured function controls access to Analysis Studio.

Administration
This secured function controls access to the administrative pages in IBM Cognos 8. You can specify object capabilities for the following secured features within Administration. Adaptive Analytics Administration Users can access Adaptive Analytics to perform administrative tasks. Planning Administration Users can access IBM Cognos 8 Planning - Contributor Administration Console and IBM Cognos 8 Planning - Analyst to perform administration tasks. Metric Studio Administration Users can create new metric packages using the new metric package wizard in IBM Cognos Connection, and access the Tools menu in Metric Studio.

Event Studio
This secured function controls access to Event Studio.

Administration and Security Guide 229

Chapter 15: Object Capabilities

Glossary
This secured function controls access to the IBM WebSphere Business Glossary.

Metric Studio
This secured function controls access to Metric Studio. The secured feature associated with this function is Edit View Use the edit features of Metric Studio to edit metric content.

Planning Contributor
This secured function controls access to IBM Cognos 8 Planning - Contributor and IBM Cognos 8 Planning - Analyst.

Query Studio
This secured function controls access to the Query Studio, which you use to create simple, ad hoc reports. The secured features associated with this function are Create Create new reports and use the Save as option for new reports and custom views. Advanced Use advanced authoring features, such as creating complex filters, formatting style, and multilingual support.

Report Studio
This secured function controls access to Report Studio, which you use to author professional reports. The secured features associated with this function are Bursting Users can author and run burst reports. Create/Delete Users can create new reports, use the Save as option for new reports and report views, and change models. HTML Items in Report Users can use the button, HTMLItem, and hyperlink elements of the report specification when authoring reports. User Defined SQL Users can edit the SQL statements directly in the query specification and run the query specifications that contain the edited SQL statements.

230

Chapter 15: Object Capabilities Note: Restrictions on who can use this feature are not enforced in Framework Manager. For example, a Framework Manager user who does not have User Defined SQL rights in IBM Cognos Administration can still create a query subject and use manually created SQL queries to search a database.

Lineage
This secured function controls access to the Lineage action. Use this to view information about data or metadata items from Cognos Viewer, or from the source tree in Report Studio, Query Studio, and Analysis Studio.

Specification Execution
This secured function specifies that a user or SDK application can use an inline specification. IBM Cognos 8 studios and some services use inline specifications internally to perform tasks. The service running the specification tests a number of capabilities to ensure that the user is entitled to use the inline specification. For more information, see the runSpecification method in the Developer Guide. This capability is required to author Data Manager tasks.

Watch Rules
This secured function controls access to the Rules tab in My Watch Items in IBM Cognos Connection. Use this secured function to create and run watch rules.

Set Up Object Capabilities for a Package

Use this functionality to specify the secured functions and features (p. 229) that users, groups, or roles can use with specific packages. You can specify object capabilities at the package level or, if the package is stored in a folder, at the folder level. Capabilities specified at the folder level apply only to packages in that folder and in its subfolders, and not to any other entries, including reports. For example, if a folder contains packages, reports and a subfolder that contains other packages and reports, only the packages in the folder and in the subfolder are affected by the capabilities settings. To use object capabilities, the users must have access to the secured functions and features associated with the package (p. 221) have access to the Object Capabilities secured function (p. 225) have set policy permissions for the package (p. 213) or own the package

Administration and Security Guide 231

Chapter 15: Object Capabilities When setting up object capabilities for the first time after installing IBM Cognos 8, we recommend that you start with Public Folders, and that the capabilities for Public Folders mirror the global capabilities. This provides an accurate baseline on which object capabilities can be further refined.

Steps
1. In IBM Cognos Connection, click the properties button the folder that contains the package. for the package that you want, or

Tip: When setting up object capabilities for Public Folders, click the properties button the product toolbar. 2. Click the Capabilities tab. 3. Select the Override the capabilities acquired from the parent entry check box.

in

4. In the box on the left, select the check box next to the user, group, or role for which you want to specify object capabilities. If the user, group, or role is not in the list, click Add. If you want to remove the user, group, or role from the list, select its check box, and click Remove. For more information about adding or removing entries from this list, see the steps in "Set Access Permissions for an Entry" (p. 216). 5. In the box on the right, select or clear the applicable check boxes to grant or deny the required object capabilities for users, groups, or roles. An icon that represents a granted or denied capability appears next to the name of the user, group, or role. When you deny access to a secured function, you automatically deny access to all its secured features. 6. If applicable, select the Delete the capabilities of all child entries check box. Use this option to specify object capabilities for a hierarchy of entries, for example, for all packages in a folder. 7. Click OK.

232

Chapter 16: Initial Security

When a content store is initialized, a set of security objects is created and stored in the Cognos namespace. They are designed to simplify the IBM Cognos 8 administration. The initial security policies grant unrestricted access to all objects in the content store to all users. The security administrator must modify the initial security settings to secure the content store (p. 236). To see a summary of the initial access permissions for the Content Manager objects, see "Initial Access Permissions " (p. 691).

Built-in Entries
The built-in entries include the Anonymous user account, the groups All Authenticated Users and Everyone, and the role System Administrators. You cannot delete the built-in entries. They appear in both secured and non-secured environments.

Anonymous
This entry represents a user account shared by members of the general public who can access IBM Cognos 8 without being prompted for authentication. For example, this type of access is useful when distributing an online catalog. Anonymous users can see only those entries for which access permissions are not set, or are set specifically for this account or for the Everyone group. You can disable the Anonymous user account by changing the configuration parameters in the configuration tool.

All Authenticated Users

This group represents users who are authenticated by authentication providers. The membership of this group is maintained by the product and cannot be viewed or altered. You cannot deploy this group (p. 313).

Everyone
This group represents all authenticated users and the Anonymous user account. The membership of this group is maintained by the product and cannot be viewed or altered. You can use the Everyone group to set default security quickly. For example, to secure a report, you grant read, write, or execute permissions to the report for the Everyone group. After this security is in place, you can grant access to the report to other users, groups, or roles, and remove the group Everyone from the security policy for this report. Then, only users, groups, and roles that you specified have access granted to the report. You can use the Everyone group to apply security during deployment (p. 308), but you cannot deploy the group itself (p. 313).

Administration and Security Guide 233

Chapter 16: Initial Security

System Administrators
This is a special role in IBM Cognos 8. Members of this role are considered root users or super users. They may access and modify any object in the content store, regardless of any security policies set for the object. Only members of the System Administrators role can modify the membership of this role. The System Administrators role cannot be empty. If you do not want to use System Administrators, you can create an empty group in the Cognos namespace or in your authentication provider, and add this group to the membership of the System Administrators role. When this role is created during the content store initialization, the group Everyone is included in its membership. This means that all users have unrestricted access to the content store. Immediately after installing and configuring IBM Cognos 8, you must modify the initial security settings for this role and remove the group Everyone from its membership (p. 236). You can deploy this role (p. 313).

Predefined Entries
The predefined entries include several Cognos roles (p. 208). Each of the roles has a specific set of access permissions, and can be used to secure different components and functions in IBM Cognos 8. You can use the predefined roles, or delete them. When the predefined roles are created during the content store initialization, the group Everyone is a member of some of them. Some of such roles are Consumers, Query Users, Analysis Users, and Authors. If you want to use the predefined roles, we recommend that you modify their initial membership immediately after installing and configuring IBM Cognos 8 (p. 236). The predefined roles include the following.

Role
Adaptive Analytics Administrators

Description
Members can administer reports packaged using Adaptive Analytics. Members can use reports packaged using Adaptive Analytics. Members have the same access permissions as Consumers. They can also use the IBM Cognos Analysis Studio. Members have the same access permissions as Query Users and Analysis Users. They can use Report Studio, Query Studio, and Analysis Studio, and save public content, such as reports and report outputs. Members can read and execute public content, such as reports.

Adaptive Analytics Users

Analysis Users

Authors

Consumers

234

Chapter 16: Initial Security

Role
Controller Administrators

Description
Members have full access to IBM Cognos Controller menus and can create individual IBM Cognos Controller users and define their limitations. Members have general access to IBM Cognos Controller menus. Members can use Data Manager to create data warehouses and data repositories for reporting, analysis, and performance management. Members can administer the contents of namespaces. In the Cognos namespace, they administer groups, accounts, contacts, distribution lists, data sources, and printers. Members can use the Report Studio Express user interface profile. Members can administer metric packages and tasks in IBM Cognos Connection. Members can create and edit scorecard applications in Metric Studio. Members can monitor performance in Metric Studio. Members can administer the Cognos portlets and other portlets in IBM Cognos Connection. This includes customizing portlets, defining portlet styles, and setting access permissions for portlets. Members can access the Contributor Web client, Contributor Add-in for Excel, or Analyst. Members can access Contributor Administration Console, Analyst, and all associated objects in the application. Members have the same access permissions as Consumers. They can also use the IBM Cognos Query Studio.

Controller Users

Data Manager Authors

Directory Administrators

Express Authors

Metrics Administrators

Metrics Authors

Metrics Users Portal Administrators

Planning Contributor Users

Planning Rights Administrators

Query Users

Administration and Security Guide 235

Chapter 16: Initial Security

Role
Readers

Description
Members have read-only access to IBM Cognos 8. They can navigate some portions of the content store, view saved report outputs in the portal, select cells in saved report outputs in Cognos Viewer, and use the Cognos Viewer context menu to perform actions, such as drillthrough. Members can administer the public content, for which they have full access. They can also use IBM Cognos Report Studio and IBM Cognos Query Studio. Members can administer servers, dispatchers, and jobs.

Report Administrators

Server Administrators

Specify Security Settings After Installation

When the initial security entries are created during the content store initialization, the group Everyone is a member of the System Administrators role. This means that all users have full access to the content store. To limit that access, you must add trusted users as members of this role, and then remove the group Everyone from its membership. You must also modify the initial security settings for the predefined roles that include the group Everyone in their initial membership, such as Consumers, Query Users, and Authors. Make similar modifications for them as you do for the System Administrators role. If you do not want to use the predefined roles, you can delete them. To secure the Cognos namespace, modify its initial access permissions by granting access for the users you want. When you set access permissions, you should not explicitly deny access to entries for the group Everyone. Denying access overrides any other security policies for the entry. If you denied access to the entry for Everyone, the entry would become unusable. Your IBM Cognos 8 installation must already be configured to use an authentication provider, which is documented in the Installation and Configuration Guide.

Steps for System Administrators and Predefined Roles

1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Security tab, click Users, Groups, and Roles. 3. Click the Cognos namespace. 4. For the role you want, in the Actions column, click the set properties button. 5. On the Members tab, modify the membership list:

236

Chapter 16: Initial Security Ensure that one or more users defined in your authentication provider are members. Remove the group Everyone.

6. Click OK. 7. On the Permissions tab, set access permissions for this role to prevent unauthorized users from creating, updating, or deleting the content, and then click OK. For each role, repeat steps 3 to 6.

Steps for the Cognos Namespace

1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Security tab, click Users, Groups, and Roles. 3. In the Actions column next to the Cognos namespace, click the set properties button. 4. On the Permissions tab, set access permissions for the Cognos namespace to prevent unauthorized users from creating, updating, or deleting the content. We recommend that you remove the group Everyone. However, you may leave it, depending on your requirements. 5. If you want, select the Delete the access permissions of all child entries check box. 6. Click OK.

Securing the Content Store

To ensure its security and integrity, the content store is accessed by the Content Manager service using single database signon specified in IBM Cognos Configuration. The database signon is encrypted according to your encryption standards. However, the content store security relies not only on the IBM Cognos 8 security but also on the native database security, operating system security, and network security. For securing your database, we recommend that you follow these guidelines: Secure the database and the database API using the mechanisms provided by the database, the network, and the operating system. Assign a limited number of users to maintain the database. Use your database native security to grant only minimum permissions to the user accounts that access the database, as follows: MS SQL Server Users must have create and drop table permissions for the database. Ensure that the user account is a member of the db_ddladmin, db_datareader, and db_datawriter roles, and the owner of their default schema. ORACLE Administration and Security Guide 237

Chapter 16: Initial Security Users must have permissions to connect to the database. Also, they must be able to create, alter, and drop tables, triggers, views, procedures, and sequences, as well as insert, update, and delete data in the database tables. The permissions must be granted to the user account directly, and not through a group or role membership. DB2 Users must have the create, drop table, CREATETAB, CONNECT and IMPLICITSCHEMA permissions for the database. Also, they must have USE permissions for the USER TEMPORARY tablespace and other appropriate tablespaces associated with the database. Sybase Adaptive Server Enterprise Users must have create, drop table, create default, create procedure, create rule, create table, and create view permissions for the database. Limit the number of users who have read or write access for the Content Manager tables. Follow other recommendations on securing the database. For information, see the database documentation.

238

Chapter 17: IBM Cognos Connection

IBM Cognos Connection is the portal to IBM Cognos 8, the Web-based reporting solution. IBM Cognos Connection provides a single access point to all corporate data available in IBM Cognos 8. You can use IBM Cognos Connection to work with entries such as reports, analyses, queries, agents, metrics, and packages. You can use IBM Cognos Connection to create shortcuts, URLs, and pages, and to organize entries. You can personalize IBM Cognos Connection for your own use. You can use IBM Cognos Connection to create and run reports and cubes (p. 347) and distribute reports (p. 372). You can also use it to create and run agents (p. 383) and schedule entries (p. 299). As an administrator, you can use IBM Cognos Connection to administer servers, optimize performance, and set access permissions (p. 213). You can also use it for entry administration, including such things as scheduling and distributing reports, agents, and metrics. If you use a customized user interface, you may not have access to all the features documented.

Log On
IBM Cognos 8 supports authenticated and anonymous user access. To use IBM Cognos 8 as an authenticated user, you must successfully log on. During the logon process, you must provide your credentials, such as user ID and password, as required by your organization. Anonymous users do not log on. Tip: If you want to see a summary of your logon information for the current session, in the portal, click My Area, My Preferences and then click the Personal tab. This is not available to anonymous users.

Steps
1. In the portal, click Log On. 2. If the namespace Logon page appears, in the Namespace box, click the namespace you want to use. 3. Click OK and type your user ID and password. 4. Click OK. Your session starts.

Log Off
You log off to end your session. Even if you used multiple namespaces in the session, you log off only once.

Administration and Security Guide 239

Chapter 17: IBM Cognos Connection If you close your Web browser without logging off, your session ends.

Steps
1. In the portal, click Log Off. You are now logged out of all the namespaces you were using. 2. Choose whether to log on again: If you do not want to log on again, close your Web browser. If you want to log on as an authenticated user, click Log on again. If you want to log on as an anonymous user, click Open a session as an anonymous user. This is available only if your administrator set it up.

Create a Shortcut
A shortcut is a pointer to another entry such as a report, report view, folder, job, agent, page, or URL. You can use shortcuts to organize information that you use regularly. For example, if you frequently use a report in Public Folders, you can create a shortcut in My Folders. If you want to make a new entry, it might be easier to make a copy of an existing entry (p. 251) and modify it. If you want to run an existing agent or report with some minor changes, create an agent view (p. 385) or a report view (p. 354). For example, to change the format, language, or delivery method of a report, create a report view. You cannot update the source entry by clicking the shortcut. Updating the source automatically updates all shortcuts to the entry. Tip: If the source entry was deleted or moved to another location, the shortcut icon to indicate a broken link. changes

You can change access permissions for a shortcut entry, but it does not change the access permissions for the source entry.

Steps
1. In IBM Cognos Connection, locate the entry you want to create a shortcut to. 2. Under Actions, click More and then click Create a shortcut to this entry 3. In the Name box, type the name of the shortcut. 4. If you want, in the Description and in the Screen tip box, you can type a description of the entry. The description appears in the portal when you set your preferences to use the details view (p. 260). The screen tip, which is limited to 100 characters, appears when you pause your pointer over the icon for the entry in the portal. .

240

Chapter 17: IBM Cognos Connection 5. If you do not want to use the target folder shown under Location, choose another location: Click Select another folder, select the target folder, and click OK. If the folder box is empty, go back one folder level using the path at the top of the dialog box. Click Select My Folders as the location.

6. Click Finish. In the portal, shortcut entries are identified by the shortcut icon .

Create a URL
A URL is a standard way of identifying the location for any external file or Web site. Create URLs to keep the files and Web sites you use most frequently at your fingertips. Clicking a URL opens the file or Web site in the browser. After opening a URL, click the back button in your browser to return to the portal. The URL must contain a valid server name that is included in the valid domains list, as specified by your administrator. Otherwise, you cannot create the URL. Administrators maintain the list of valid domains in IBM Cognos Configuration, in the IBM Cognos Application Firewall category, the Valid domains or host property. For more information, see the Installation and Configuration Guide.

Steps
1. In IBM Cognos Connection, go to the folder where you want to create the new URL. 2. Click the new URL button on the toolbar.

3. In the Name box, type the name of the new URL. 4. If you want, in the Description and in the Screen tip box, you can type a description of the entry. The description appears in the portal when you set your preferences to use the details view (p. 260). The screen tip, which is limited to 100 characters, appears when you pause your pointer over the icon for the entry in the portal. 5. In the URL box, type the URL location. If the URL points to a Web site address, the protocol must be included. For example, to create a URL for the IBM Cognos Web site, type http://www.cognos.com. 6. If you do not want to use the target folder shown under Location, choose another location: Click Select another folder, select the target folder, and click OK. If the folder box is empty, go back one folder level using the path at the top of the dialog box. Click Select My Folders as the location.

7. Click Finish.

Administration and Security Guide 241

Chapter 17: IBM Cognos Connection

In the portal, URL entries are identified by the URL icon

Bookmark an Entry
You can bookmark an IBM Cognos 8 entry in your Web browser so that later you can quickly perform the default action associated with the entry. For example, using a report bookmark, you can view the most recent report output, run the report, or open it in an authoring tool. For more information, see "Set Default Report Options" (p. 348). The bookmark saves the URL of the entry and its default action at the time when the bookmark was created. Some default actions are available only to users who have the required access permissions for the entries. have the required product components installed. have access to specific, secured functions and features. For example, the capabilities to use a specific IBM Cognos 8 studio. use specific Web browsers.

For example, to open an agent, users must have read and traverse permissions for the agent, have Event Studio installed and the permissions to use it, and use Internet Explorer as their Web browser.

Steps for Internet Explorer

1. In IBM Cognos Connection, locate the entry for which you want to create a bookmark. 2. In the Actions column, click More. 3. In the list of actions available for this entry, click Add to bookmarks The Internet Explorer box for adding favorites appears. 4. Create the bookmark as you normally do in Internet Explorer. .

Steps for All Web Browsers

1. In IBM Cognos Connection, locate the entry for which you want to create a bookmark. 2. In the Actions column, click the set properties button for the entry.

3. On the General tab, click View the search path, ID and URL. 4. Right-click the link that appears under Default action URL. The link shows the entry name and the action that will be performed. If the entry has no default actions, the link is replaced by None. The text below the link shows the URL used by the link. A menu box specific to your Web browser appears. 5. From the menu, click the option for creating bookmarks.

242

Chapter 17: IBM Cognos Connection For example, if you are using Internet Explorer, click Add to Favorites. If you are using Firefox, click Bookmark This Link. 6. Create the bookmark as you normally do in your Web browser.

Models and Packages

Models and packages use corporate business rules to define and group the data to be used for business reporting. A model is a data structure containing imported data from one or more data sources. IBM Cognos 8 users responsible for data modeling use Framework Manager to create models. The data modeler creates a package that defines a subset of data that is relevant to an intended group of users. For example, the data modeler may create a package that marketing managers use for information related to market research. The package can then be distributed to report authors by publishing it to the portal. When you run a report, the result set is defined by the data retrieval information defined in the package. In IBM Cognos Connection, you can manage packages the way you manage other entries. For example, you can organize packages in folders, create shortcuts to packages, and move or copy packages. You can also hide a package to prevent it from unnecessary use (p. 254). For more information about models and packages, see the Framework Manager User Guide.

Entry Properties
You can control the way an entry appears and behaves by modifying its properties. The properties for entries vary depending upon the type of entry selected and your privileges. For example, reports have properties to control run options while folders do not. If a property is not applicable to the type of entry you are customizing, it will not appear in the Set properties page.

General Properties
General properties appear on the General tab of the Set properties page.

Property
Type Owner

Description
The type of entry. The owner of the entry. By default, the owner is the person who created the entry. When the owner no longer exists in the namespace, or is from a different namespace than the current user, the owner shows as Unknown. If you have Set policy permissions, click Make me the owner to become the owner of the entry.

Administration and Security Guide 243

Chapter 17: IBM Cognos Connection

Property
Contact

Description
The person responsible for the entry. Click Set the contact and then click Select the contact to set the contact for the entry or click Enter an email address to enter the contacts email address.

Location

The location of the entry in the portal and its ID. Click View the search path, ID and URL to view the fully qualified location and the ID of the entry in the content store. Entries are assigned a unique identification (ID) number. For more information, see "Organizing Entries" (p. 251).

Created Modified Icon

The date the entry was created. The most recent date that the entry was modified. The icon for the entry. Click Edit to specify an alternative icon. For more information, see "Specify an Alternative Icon for an Entry" (p. 259) When selected, users that do not have write permissions for this entry cannot access it. The entry is no longer visible in the portal. If an entry is disabled and you have write access to it, the disabled icon appears next to the entry.

Disable this entry

Hide this entry

Select this property to hide reports, packages, pages, folders, jobs, and other entries. Hide an entry to prevent it from unnecessary use, or to organize your view. The hidden entry is still accessible to other entries. For example, a hidden report is accessible as a drill-through target. A hidden entry remains visible, but its icon is faded. If you clear the Show hidden entries check box in my area Preferences, the entry disappears from your view. You must have access to the Hide Entries capability granted by your administrator to see this property. , My

Language

A list of languages that are available for the entry name, screen tip, and description according to the configuration set up by your administrator. Click Remove values for this language to remove the entry name, screen tip, and description for a specified language.

244

Chapter 17: IBM Cognos Connection

Property
Name Screen tip

Description
The name of the entry for the selected language. An optional description of the entry. The screen tip appears when you pause your pointer over the icon for the entry in the portal. Up to 100 characters can be used for a screen tip. An optional description of the entry. It appears in the portal when you set your preferences to use the details view. Details view appears only in Public Folders and My Folders.

Description

Run history

The number of occurrences or period of time to retain run histories for the entry. The number of occurrences or period of time to keep report outputs. Setting this value to zero (0) saves an unlimited number of versions.

Report output versions

Package

The package that is associated with the entry. If the source package was moved or deleted, the text reads "Unavailable." Click Link to a package to link the entry to a different package. For more information, see "Select a Link for an Entry" (p. 256).

URL

A URL to either a file or Web site address. For more information, see "Create a URL" (p. 241). This field is visible only if you have read permissions for the entry. If you have write permissions without read permissions, this property is not visible.

Source report

A path to the source entry for a report view. If the source entry was moved or deleted, the text reads "Unavailable." Click Report Properties to view the properties of the source report. Click Link to a report to link the entry to a different package. For more information, see "Select a Link for an Entry" (p. 256).

Administration and Security Guide 245

Chapter 17: IBM Cognos Connection

Property
Source agent

Description
A path to the source entry for an agent view. If the source entry was moved or deleted, the text reads "Unavailable." Click Agent Properties to view the properties of the source report. Click Link to an agent to link the entry to a different package. For more information, see "Select a Link for an Entry" (p. 256).

Shortcut to

A path to the entry that the shortcut points to. If the referred entry no longer exists, the text reads "Source entry not found." Click Source Properties to view the properties of the source entry.

Advanced routing

A list of keywords used to direct requests by package, user group, or user role to dispatchers in identified server groups. Click Set to add routing keywords for packages, user roles, or user groups. The rules used to direct the requests are part of IBM Cognos Administration.

Gateway

The location of the web server where the originating IBM Cognos product resides. Applies only to Series 7 PowerPlay reports.

Permissions
Permissions appear on the Permissions tab of the Set properties page.

Property
Override the access permissions

Description
Whether to replace the permissions that are inherited from the parent entry. The permissions that are set for the entry. You can grant or deny read, write, execute, set policy, and traverse permissions. For more information, see "Access Permissions" (p. 213). Click Add to add more names to the list. Click Delete to delete names from the list.

Access permissions (Name, Type, Permissions)

Delete the access permissions of all Whether to remove the existing access permissions for all child entries child entries so that they will use the access permissions for this entry.

246

Chapter 17: IBM Cognos Connection

Report, Query, Analysis, and PowerPlay Report Properties

Report properties appear on the following tabs of the Set properties page: the Report tab for Report Studio reports the Query tab for Query Studio reports the Analysis tab for Analysis Studio reports the PowerPlay Report tab for Series 7 PowerPlay reports

You can select the available paper sizes. In IBM Cognos Connection, click IBM Cognos Administration and then click Configuration. Click Dispatchers and Services and then click the define paper sizes button . To add new paper sizes, click New. To delete paper sizes, click Delete.

Property
Default action Report options: Override the default values Format

Description
The default action when the report is run. Whether to override default run options for the report. When selected, the values that you can override appear. The default format, orientation, and paper size to use when the report runs. Appears only if Override the default values is selected.

Language

The default language to use for the report data when the report runs. Appears only if Override the default values is selected.

Prompt values

The values that are used to filter data when a report is run(p. 362). Whether to use the owner credentials (p. 218) when the report is run. Whether to open an HTML-format Series 7 PowerPlay report in design mode. The number of rows you want to appear per Web page in HTML reports

Run as the owner

HTML options: Open in design mode Number of rows per Web page in HTML reports

Administration and Security Guide 247

Chapter 17: IBM Cognos Connection

Property

Description

Enable selection-based interactivity Whether to enable the following in HTML reports that are in HTML reports viewed in Cognos Viewer: drill up and drill down, drill through, Cognos Search, watch rules, and agent notification. For more information, see (p. 371) Note that to have watch rules evaluated in saved report output, you must select the Enable enhanced user features in saved output versions check box. Enable alerts about new versions Whether to allow report consumers to receive alerts about new versions of a saved report. If this check box is cleared, you are prompted whether to remove all users from the alert list. Whether to create additional output formats so that watch rules can be evaluated and saved output versions can be imported into IBM Cognos 8 Go! Office. Note that to enable watch rules, you must select the Enable selection-based interactivity in HTML reports check box. Enable comments in saved output versions Whether to allow users to add comments to saved reports. For more information, see "Comments in Saved Reports" (p. 369). Create new cache data if none is available, when the report runs interactively. The number of days or months before the report cache data expires. To enable the cache duration, select the Refresh the report cache check box.

Enable enhanced user features in saved output versions

Refresh the report cache

Cache duration

Job Properties
Job properties appear on the Job tab of the Set properties page.

Property
Steps Submission of steps Defaults for all steps

Description
A list of steps in the job. Whether to run job tasks all at once or in sequence. Set default values at the job level. Click Set, then specify the defaults for all steps of the job. If no defaults are set, the defaults for the individual steps are used.

248

Chapter 17: IBM Cognos Connection

Property
Run history details level

Description
Click All to save the complete history details for the job steps when the run activity completes successfully. The complete history details for the job steps includes Name, Request time, Start time, Completion time, Status. Click Limited to save limited run history details for the job. The limited run history details include the job start time, completion time, status and messages. If the job run fails, the complete history details are saved. The default is All. The Run history details level setting for the job overrides the settings of the job steps.

Agent Properties
Agent properties appear on the Agent tab of the Set properties page.

Property
Tasks Default action Prompt values

Description
A list of tasks in the agent. The default action when the agent is run. The values that are used to filter data when an agent is run (p. 383). Whether to use the owner credentials (p. 218) when the agent is run. Whether to allow users to add themselves to the alert list for an agent.

Run as the owner

Alert list

Page Properties
Page properties appear on the Layout and Content and Page Style tabs of the Set properties page.

Property
Number of columns

Description
The number of columns used to organize the content of a page. Up to three columns can be used.

Administration and Security Guide 249

Chapter 17: IBM Cognos Connection

Property
Content

Description
Type of content added to a page. Use to add and remove portlets, distribute the portlets between the columns, change the order of columns and specify their width.

Language

The language in which the page title and instructions can be typed. It should match the product language. The page title. You can format the title by changing the font and character style, and the text alignment. To return to the default browser settings, click Return to default. To modify the default settings, click Custom. You can hide the title.

Title

Instructions

Additional information about the page. You can format the text of instructions by changing the font and character style, and the text alignment. To return to the default browser settings, click Return to default. To modify the default settings, click Custom. You can hide the instructions.

Portlet style

The way a portlet appears on a page. To avoid cluttering the page, you can hide the portlet borders, title bars, and the edit button on the title bar.

Rule Properties
Use the rule properties to define or modify a watch rule. You can access the rule properties from the My Watch Items, Rules tab by clicking the set properties icon for a watch rule entry. The properties are located on the Rule tab of the Set Properties page. The rule properties specify conditions in saved HTML report output so that when the report is saved and the conditions are satisfied, you are alerted. For information about creating watch rules, see (p. 367). The following table describes the rule properties that are available.

Property
Disable the rule

Description
Whether to disable the watch rule. When disabled, the watch rule is not applied when report output is generated.

250

Chapter 17: IBM Cognos Connection

Property
Send an alert when the report reportname contains:

Description
The name of the report and the rule defined for the watch rule. To edit the definition, click the existing filter condition, such as > (greater than) and in the list that appears, click a different condition. Specify a different value in the box.

For the selected context Alert type

The objects in the report to which the rule applies. The type of alert you receive when the rule is satisfied. You can be alerted by email or news item.

Organizing Entries
Organize entries such as reports, analyses, agents, and packages in a meaningful way so that you can easily find them. It is important to plan how you can best organize entries in the portal. Review the entries and attempt to group them in a logical way. Consider grouping the entries by type or frequency of use. You may decide to create a folder hierarchy by using nested folders. The folder structure should be logical and should support the chosen method of grouping. Use meaningful names and detailed descriptions to identify entries in the portal. You can copy, move, rename, or delete entries. You can create copies of entries and store them in multiple folders for easy access. You can disable entries and specify the order of entries. You can select a link for an entry. For example, if a report is deleted, you may want to link an associated report view to a different report. You can also hide an entry to prevent it from unnecessary use. Remember that an entry often refers to other entries such as packages, reports, analyses, or queries. In addition, there may be references to entries in job steps, agents tasks, drill-through targets, or metrics. Reference IDs are hard-coded in the specification for each entry. Note that references to deployment objects are based on search paths, not IDs. IDs are installationspecific while search paths are not.

Copy an Entry
When you create a copy of an entry, you create a replica of that entry in another location in the portal. For example, create a copy if you want to use a generic report as the underlying structure for additional reports. The copy of the entry has a new ID. If there is another entry of the same name in the target location, you are prompted to replace the existing entry with the copied entry. If you choose to replace the existing entry, the ID of the existing entry is used. If you copy a folder, references for entries in the folder that reference each other are updated to reference entries in the copied folder.

Administration and Security Guide 251

Chapter 17: IBM Cognos Connection If you want to run an existing agent or report with some minor changes, create an agent view (p. 385) or a report view (p. 354). For example, to change the format, language, or delivery method of a report, create a report view. You can copy multiple entries at the same time to the same location. If you want a report to appear in more than one location, create a shortcut (p. 240). You must have read permissions for an entry you are attempting to copy. You must also have traverse permissions for the current folder, and write and traverse permissions for the target folder (p. 213).

Steps
1. In IBM Cognos Connection, select the check boxes next to the entry or entries you want to copy. 2. Click the copy button on the toolbar. on the

3. Go to the desired location for the new entry or entries and click the paste button toolbar.

4. If an entry name is the same as an entry name in the destination folder, choose whether you want to replace the existing entry with the one that you are copying: To replace the existing entry, click Yes. To cancel the copy, click No.

Move an Entry
When you move an entry, you remove it from the current folder and place it in another folder. You may decide to move an entry if your folder becomes so full that it is difficult to locate particular entries. You can create a series of subfolders and move the entries to support your new folder hierarchy. For example, a folder containing weekly sales reports can be divided into sales reports by month or by author. When you move an entry, the ID stays the same. References to the entry from other entries are not broken. However, shortcuts to the entry no longer work. For example, a report has several report views associated with it. When you move the report to another location in IBM Cognos Connection, the references in the associated report views are not broken. However, shortcuts to the entry no longer work. When you move an entry, if there is another entry of the same name in the target location, you are prompted to replace the existing entry with the moved entry. If you choose to replace the existing entry, the ID of the existing entry is kept. References to the moved entry are broken. Shortcuts to the entry no longer work. If you want to use a generic entry as the underlying structure for additional entries, make a copy of the entry (p. 251). If you want an entry to appear in more than one location, create a shortcut (p. 240). If you want to run an existing agent or report with some minor changes, create an agent view (p. 385) or a report view (p. 354). For example, to change the format, language, or delivery method of a report, create a report view.

252

Chapter 17: IBM Cognos Connection You must have read permissions for the entry you are attempting to move. You must also have write and traverse permissions for the current folder and for the target folder.

Steps
1. In IBM Cognos Connection, select the check boxes next to the entry or entries you want to move. 2. Click the cut button on the toolbar. on the toolbar.

3. Go to the desired location for the entry or entries and click the paste button

4. If an entry name is the same as an entry name in the destination folder, choose whether you want to replace the existing entry with the one that you are copying: To replace the existing entry, click Yes. To cancel the copy, click No.

Rename an Entry
You may decide to rename an entry. Perhaps the current name for an analysis is confusing or the purpose of a report changed. When you rename an entry, the ID stays the same. However, the search path changes. References to the entry from other entries are not broken. Shortcuts to the entry no longer work. For example, a package has reports, agents, and drill-through definitions associated with it. When you rename the package, the references in the associated reports, agents, and drill-through definitions are not broken. You cannot rename an entry to the same name as another entry that already exists in the same location. You must have read permissions for the entry you are attempting to rename. You must also have write and traverse permissions for the current folder and for the target folder.

Steps
1. In IBM Cognos Connection, locate the entry you want to rename, and in the Actions column, click the set properties button 2. Click the Properties tab. 3. In the Name box, type a new name for the entry. 4. Click OK. .

Disable an Entry
You can disable entries to prevent users from accessing them.

Administration and Security Guide 253

Chapter 17: IBM Cognos Connection Disabling entries is useful when you want to perform maintenance operations. For example, you may want to disable a folder while you reorganize its content. When you disable a folder, the folder content is also disabled. If an entry is disabled, the disabled icon appears beside the entry to indicate that it is disabled. ,

If the source entry is disabled, all shortcuts to the entry appear with the source disabled icon indicating that it no longer works.

You must have read and write permissions for an entry (p. 213) to enable or disable it. You must also have traverse permissions on the folder that contains the entry.

Steps
1. In IBM Cognos Connection, locate the entry you want to disable and, in the Actions column, click the set properties button 2. Click the General tab. 3. Select the Disable this entry check box. Tip: To enable a disabled entry, clear the Disable this entry check box. 4. Click OK. If you have only read, execute, or traverse permissions for a disabled entry, you cannot see the entry in the portal. If you have write or set policy permissions for a disabled entry, it appears in the portal with the disabled icon . .

Hide an Entry
You can hide entries in IBM Cognos Connection and IBM Cognos Administration such as reports, packages, pages, folders, jobs, data sources, portlets, and so on, to ensure that the entries are not accessed or run unnecessarily. This specifically applies to drill-through reports that, when they run, could have negative impact on system performance. For example, running drill-through reports that have optional prompts, or no prompts, could result in database queries that use considerable resources. When these reports are hidden in the portal, users cannot run them and the system is not overloaded with unnecessary requests. Hiding an entry does not affect its properties, including security permissions. You can access hidden entries using different methods, such as using a URL. Depending on the user preferences specified in my area , My Preferences, a hidden entry either entirely disappears from the user interface or remains visible, but its icon fades. For more information, see "View a Hidden Entry" (p. 255). You cannot hide users, groups, or roles in external namespaces.

254

Chapter 17: IBM Cognos Connection An administrator controls which users, groups, or roles can hide entries by granting the users access to the Hide Entries capability in IBM Cognos Administration. Only users who have access to this capability can perform the following steps.

Steps
1. In IBM Cognos 8, locate the entry that you want to hide, and click its set properties button . 2. On the General tab, select the Hide this entry check box. 3. Click OK. The entry is now hidden; however, it may still appear in the user interface with a faded icon. To remove the entry from your view, see "Steps to Change the Preference for Viewing Hidden Entries" (p. 256).

View a Hidden Entry

Users can change their preferences to either show or remove hidden entries from the user interface. Icons that represent hidden entries are faded. Depending on the preferences, a hidden entry may or may not appear in search pages, wizards, save as boxes, and so on. For example, when the user interface does not show hidden entries, hidden packages do not appear in the list of available packages when users try to open the applicable studio, and the search results do not include the packages. The following are the rules that apply to viewing hidden entries: A hidden report is accessible as a drill-through target. Drill-through targets include parameter values to avoid resource-intensive query operations. However, the user still requires read and execute permissions to use this target report in a drillthrough activity. A hidden drill-through definition is not displayed in the Go To page if the user interface does not show hidden entries. A visible shortcut can point to a hidden entry. If the shortcut points to a hidden folder, any hidden entries in the folder are not visible. Search pages do not return hidden entries if the user interface does not display the entries.

The following, are examples of situations when hidden entries are always visible, regardless of the user preferences for viewing hidden entries. Hidden entries on the Permissions and Personal tabs The entries icons are faded. Portal tabs associated with hidden pages Portlets in a page Job steps that refer to hidden entries already in a job

Administration and Security Guide 255

Chapter 17: IBM Cognos Connection The entries icons are faded. Agent tasks that refer to hidden entries already in an agent The entries icons are faded. Details in a report run history The icons that represent hidden entries do not change. Setting the default option for viewing hidden entries in IBM Cognos 8 is part of managing user profiles. Only users who have access to the Hide Entries capability in IBM Cognos Administration can perform the following steps.

Steps to Change the Preference for Viewing Hidden Entries

1. Go to my area and click My Preferences.

2. On the General tab, select or clear the Show hidden entries check box. If you select this check box, the hidden entries appear in the user interface with faded icons. If you clear this check box, the hidden entries disappear from the user interface. 3. Click OK.

Select a Link for an Entry

Some entries are linked to other entries when they are created. For example, a report view is linked to a report and a report or agent is linked to a package. Metrics are linked to a metrics package. You can change the link for an entry. For example, if a report is deleted, you may want to link an associated report view to a different report. After you change the link, the report view reflects the content of the new report. Select a link that is appropriate for the entry. For example, the package that a report is linked to must contain a valid model for the report to run correctly. If the link associated with the entry is not available, Unavailable appears. For example, Unavailable appears if the package that a report is linked to is deleted. You must have write permissions for the entry you are attempting to select a link for. You must also have write and traverse permissions for the current folder.

Steps
1. In IBM Cognos Connection, locate the entry you want and click the set properties button 2. Click the General tab and find the current link for the entry. For example, for a report, look in Package. For a report view, look in Source report. 3. Click the link. For example, for a report, click Link to a package. For a report view, click Link to report. .

256

Chapter 17: IBM Cognos Connection 4. Select the new entry that you want to link the entry to and click OK.

Delete an Entry
When you delete an entry, you permanently remove it from the portal and its ID is deleted. You may decide to delete an entry because it is outdated or may no longer satisfy your requirements. Deleting the source entry for a shortcut removes only the source entry. The shortcut entries remain but have an invalid reference icon and are not accessible.

Deleting a shortcut or a report or agent view removes only the selected entry and not the source entry. References from other entries no longer work. You must have write permissions or set policy permissions for the entry you are attempting to delete. You must also have write and traverse permissions for the current folder.

Steps
1. In IBM Cognos Connection, select the check boxes next to the entries you want to delete. 2. Click the delete button on the toolbar.

A confirmation box appears. 3. Click OK.

Specify the Order of Entries

You can specify the order of folders and entries in the portal. You may decide to organize entries by level of usage and place entries that you use daily at the top of the list. By default, existing entries are sorted alphabetically. Entries added after the order is specified are shown at the end of the list. To specify the order of entries, you must have read and write permissions for all entries in the folder and read and traverse permissions for the folder containing the entries.

Steps
1. In IBM Cognos Connection, click the tab you want. 2. Click the order button on the toolbar.

3. Select the entries in the Shown in default order list box and click the right-arrow button to move them to the Shown first list box. Note: You specify the order of folders and entries independently. 4. Click the Up, Down, To top, and To bottom links to move the folders and entries within the list. 5. Click OK.

Administration and Security Guide 257

Chapter 17: IBM Cognos Connection

Create a Folder
You can organize entries into folders. Having folders that are logically labeled and organized helps you easily locate reports. For example, you might want to create folders in My Folders or Public Folders to help you organize your entries. You can create folders in the following locations: Public Folders Entries that are placed in Public Folders are of interest to and can be viewed by many users. When the focus is on the Public Folder tab, the content is grouped by packages or folders. Each package contains a single model and all related entries, such as folders, reports, jobs, report views, agents, metrics, URLs, and shortcuts. My Folders You create personal folders and use them to organize entries according to your preferences. My Folders are accessible by you only when you are logged on. You must have write access to a folder to create entries in it.

Tips
Click More to view a full list of actions that can be performed on an entry. Click Set Properties to change the general properties, defaults, permissions, and job properties for an entry. Not all properties are available for each type of entry.

Steps
1. In IBM Cognos Connection, go to the location for the new folder. 2. Click the new folder button on the portal toolbar.

3. In the Name box, type the name of the new folder. 4. If you want, in the Description and in the Screen tip box, you can type a description of the entry. The description appears in the portal when you set your preferences to use the details view (p. 260). The screen tip, which is limited to 100 characters, appears when you pause your pointer over the icon for the entry in the portal. 5. If you do not want to use the target folder shown under Location, choose another location: Click Select another folder, select the target folder, and click OK. If the folder box is empty, go back one folder level using the path at the top of the dialog box. Click Select My Folders as the location.

6. Click Finish. The new folder has the same permissions as the parent folder. For information about changing access permissions, see "Access Permissions" (p. 213).

258

Chapter 17: IBM Cognos Connection

Specify an Alternative Icon for an Entry

In the portal, the standard icons that appear next to entries help identify the class to which the entry belongs. To better identify an entry among several similar entries, you can replace the standard icon with an alternative icon. When you specify an alternative icon, use a screen resolution of 16 x 16 pixels to ensure that the icon is properly aligned and spaced in the portal. Customizations, such as alternative icons, are not maintained automatically. As a result, alternative icons must be ported manually upon upgrade.

Steps
1. In IBM Cognos Connection, locate the entry you want and click the set properties button. 2. Click the General tab and next to Icon, click Edit. 3. Click Specify an icon, and in the edit box, specify a name for the image, for example, myicon.gif. The image must exist in the folder c8_location/webcontent/ps/portal/images. 4. Click OK. Wherever the entry appears in the portal, the alternative icon appears instead of the standard icon.

Search for an Entry

You can search for entries whose name, description, or both match the string entered in the search criteria. You can find types of entries by leaving the search string empty and selecting a specific entry type in the advanced search criteria. The search ignores capitalization. The following table shows examples of search criteria and results.

Method
Contains the exact string

Search criteria
Report 1

Results
"Report 1", "Report 100", "Copy of Report 1" "report 1", "Report 100" "Report", "report"

Starts with the exact string Matches the exact string

report Report

Entries for which you have access permissions are included in the search results.

Steps
1. Go to the highest level folder you want to include in your search. Tip: You can increase or limit the folders to include in your search by changing the Scope when you enter the search criteria. 2. Click the search button on the toolbar. Administration and Security Guide 259

Chapter 17: IBM Cognos Connection 3. In the search box, type the phrase you want to search for. 4. Click Advanced. 5. Choose the type of match between the search string and the results: To return entries that include the search string somewhere in the name or description, click Contains the exact string. To return entries whose name or description begins with the search string, click Starts with the exact string. To return entries whose name or description matches the search string word for word, click Matches the exact string. 6. In the Type box, click the type of entry to search for. Tip: To search for all shortcuts in the selected location, click Shortcuts. 7. In the Modified box, click the date that the entry was last modified. For example, if you want the search to return entries that were updated in the last week, click In last week. Note: This option is only available in the Cognos namespace. 8. In the Scope box, click the folders you want to include in the search. 9. Click the Search button.

The entries matching the search criteria and for which you have permissions to view appear at the bottom of the screen under Results. Tip: To open an entry, click its link.

Personalize the Portal

You can personalize the way data appears in IBM Cognos Connection by changing your preferences. For example, you can set the product language and the preferred output format of reports. Changes take effect immediately in the current session. The preferences are stored and used for future sessions unless you change them. You can change the following settings:

General
Number of entries in list view

Description
The maximum number of rows that appear in a list before scrollbars are required. This applies to rows where scrolling is allowed.

260

Chapter 17: IBM Cognos Connection

General
Separators in list view

Description
The method of separating entries in lists in Public Folders and My Folders. Choose from no separator, grid lines, or alternating backgrounds. This setting applies to all lists with the exception of the output versions list. This setting is available only if you use Internet Explorer or Firefox.

Style

The uniform look and feel applied to all components of IBM Cognos 8. You can choose from the styles available to you.

Show hidden entries

Use this setting to show or remove hidden entries from your view in IBM Cognos Connection. When you select this check box, the hidden entries remain visible, but their icons are faded. When you clear this check box, the hidden entries disappear from your view. For example, hidden packages are not visible in IBM Cognos Connection and in the associated studios. You must have access to the Hide Entries capability granted by your administrator to see this setting.

Default view

The decision to use list view or details view by default. List view shows the name, modified date, and actions. Details view shows the name, description, modified date, and possible actions. Details view works only in Public Folders and My Folders in IBM Cognos Connection. In other components, list view is used.

Number of columns in details view The maximum number of columns per row for the details view. Report format The preferred format to view the report. Choose between HTML, PDF, Delimited Text (CSV), Excel, and XML.

Show a summary of the run options The option to show a summary of the run options when a report is not run interactively. Show the Welcome page at startup The option to show or hide the Welcome page at the beginning of a session.

Administration and Security Guide 261

Chapter 17: IBM Cognos Connection

General
Product language

Description
The language used by the IBM Cognos 8 user interface. It applies to all IBM Cognos 8 components, such as IBM Cognos Connection, Cognos Viewer, and Report Studio. The language used to view and produce content in IBM Cognos 8, such as names and descriptions of entries, or data in reports. The time zone used. Select the default server time zone set by your administrator. For more information, see the Installation and Configuration Guide. Or you can select another time zone.

Content language

Time zone

Personal settings appear if you have read permissions for your account.

Personal
Primary logon

Description
The namespace and credentials that you used to log on to IBM Cognos 8. Also shows the given name, surname, and email address if they have been defined. A list of secondary logons. The secondary logons exists if you logged on to multiple namespaces.

Secondary logon

Alerts

Use to specify an email address for alerts. When the delivery service processes the alert list, it uses the email address specified in the Email box to send alerts to the user. If there is no email address specified, the email address specified in the Primary logon section is used.

Credentials

Authorization to other users, groups, and roles to run entries using the credentials. Click Renew the credentials after you change your password, or to ensure that all credentials are available if you are logged on to multiple namespaces.

Groups and roles

A list of groups and roles associated both with your primary and secondary logons.

262

Chapter 17: IBM Cognos Connection

Personal
Capabilities

Description
A list of secured functions and features that you can use based on both your primary and secondary logons. To create trusted credentials, see "Trusted Credentials" (p. 218).

Portal tabs settings appear if you have read permissions for your account.

Portal Tabs
List of entries

Description
Represents the tabs, including Public Folders and My Folders, in your IBM Cognos Connection environment. Use to add a tab for a specified page in IBM Cognos Connection. Each tab represents Public Folders, My Folders, or a page.

Add

Remove Modify the sequence

Use to remove a tab from IBM Cognos Connection. Use to change the order of tabs in IBM Cognos Connection.

Steps
1. In IBM Cognos Connection, click My Area, My Preferences, and click the required tab. 2. Choose the appropriate settings. 3. Click OK.

My Watch Items
Use the My Watch Items area of the portal to view (p. 264) and manage watch items from a single location. Watch items include alert lists and watch rules that help you monitor business events that are important to you. The Alerts tab shows the alert lists to which you belong. Use this tab to remove yourself from the alert list for a report or agent. The Rules tab shows the watch rules you created in saved HTML report output. Use this tab to edit a watch rule (p. 264) enable or disable a watch rule. For information, see "Disable an Entry" (p. 253). organize watch rules in folders. For information, see "Create a Folder" (p. 258). delete a watch rule. For information, see "Delete an Entry" (p. 257). edit the My Watch Items page properties. For information, see "Edit a Page" (p. 270).

Administration and Security Guide 263

Chapter 17: IBM Cognos Connection You can also add yourself to the alert list for a report (p. 366), add yourself to the alert list for an agent (p. 386), and create a watch rule for a report (p. 367). The report owner must allow report users to receive alerts and create watch rules for the report.

View Watch Items

To view the alerts lists to which you belong and the watch rules you created, use the My Watch Items area of the portal. You can also remove yourself from an alert list (p. 264), and edit a watch rule (p. 264).

Steps
1. In IBM Cognos Connection, in the upper-right corner, click My Area 2. To view your alerts lists, click Alerts. 3. To view your watch rules, click Rules. , My Watch Items.

Remove Yourself from an Alert List

To remove yourself from an alert list for a report or agent, use the My Watch Items area of the portal. When you are added to an alert list, you receive an email notification when the report, or report associated with the agent task, is saved. After removing yourself from an alert list, you are no longer alerted. Tip: You can also add or remove yourself from an alert list for a report using the Report tab of the Set Properties page (p. 366). For an agent, you can use the Agents tab of the Set Properties page (p. 386).

Steps
1. In IBM Cognos Connection, in the upper-right corner, click My Area , My Watch Items.

2. Click the Alerts tab, and in the Source column, click the alert list to remove. You can select multiple alert lists. 3. Click the remove me from the alert list button. 4. Click the refresh button. Note that the alert list is removed from the Source column.

Edit a Watch Rule

After creating watch rules in saved HTML report output, you can edit them from the My Watch Items area of the portal. For example, you can change the general properties, such as name, language, and description. You can also change the properties, such as rule condition, context, and alert type. For information about creating a watch rule, see "Create a Watch Rule for a Report" (p. 367).

264

Chapter 17: IBM Cognos Connection To edit a watch rule in IBM Cognos Connection, you must have read and write permission to the My Watch Items page.

Steps
1. In IBM Cognos Connection, in the upper-right corner, click the my area button My Watch Items. 2. Click the Rules tab, and in the Actions column, click the set properties button for the watch rule you want to edit. 3. Use the Set properties page, General tab, to change the properties, such as name, language, or description for the watch rule. 4. Use the Set properties page, Rule tab, to change the properties, such as rule, context, and alert type for the watch rule. To change a rule, in the Rule section, click the condition that appears, for example, > (greater than), click a new condition in the list, and specify a value for the condition in the box. To change the context, under For the selected context, select the check box next to the report items you want to include. To edit the alert type, under Alert type, select the alert type, if it is not already selected. Next to the alert type, click Edit the options. , and click

Administration and Security Guide 265

Chapter 17: IBM Cognos Connection

266

Chapter 18: Pages and Dashboards

IBM Cognos Connection pages and dashboards provide quick access to IBM Cognos business intelligence and performance management information, such as reports, metrics, or news items. The information is relevant to specific users or business objectives, and can be monitored at a glance. Dashboards are pages with enhanced functionality. The information is displayed on multiple tabs that are easy to navigate. Each tab can include different segment of information. A dashboard can be accessed as a standalone application through a URL. Users can print selected dashboard pages. The content for pages and dashboards is provided by Cognos portlets, or other supported portlets. Each portlet is an independent application that adds to the page different content and functionality, such as the ability to browse folders and entries, view reports and metrics, and include custom text and images or links to other Web pages. You can add different types of information to your pages and organize them in a way that is meaningful to you. For example, you may want to see specific IBM Cognos reports and metrics, or have links to your favorite Web sites. The following table shows the types of content you can add to an IBM Cognos Connection page, and the portlets that provide this content.

Page Content

Portlet

Portlet Group
Cognos Content

Browse IBM Cognos folders, reports, and other Cognos Navigator entries Search for IBM Cognos reports and other entries Cognos Search View and interact with IBM Cognos reports and Cognos Viewer other entries View and interact with different types of perform- Metric List ance metrics, such as the metrics you want to monitor closely, or the metrics for which you are directly responsible. Add a metric history chart that illustrates the historical performance of the metric Display an impact diagram associated with a metric Display a custom diagram associated with a scorecard. Metric History Chart

Cognos Metrics

Metrics Impact Diagram

Metrics Custom Diagram

Administration and Security Guide 267

Chapter 18: Pages and Dashboards

Page Content

Portlet

Portlet Group
Cognos Extended Applications Portlet

View and interact with custom applications cre- Cognos Extended ated using IBM Cognos 8 Software Development Applications Kit Register and show active links to other Web pages Bookmarks Viewer Add and view custom images, such as logos Insert any other Web page Image Viewer HTML Viewer

Cognos Utility

Add and show the content of a Real Simple Syn- RSS Viewer dication (RSS) news feed specified by a URL address Add and view custom text and images HTML Source Dashboard

Create and view a dashboard with multiple tabs Multi-page Add non-Cognos items to a page

Supported other portlets Content associated with other portlets

Note: The portlets can also be referred to as HTML fragments. The list of pages is cached in an IBM Cognos Connection session. When the state of a page changes during the current session, users who have access to the page are affected. For example, when a page is disabled or deleted, it can no longer be used and its tabs are deleted or not functional. To update the portal with the most current settings, use the IBM Cognos Connection refresh button . When you log on to IBM Cognos Connection for the first time, you access the pages an administrator made available to you. Later, you can create your own pages. You can perform the following page-related tasks in IBM Cognos Connection: create pages (p. 269) and dashboards (p. 275) edit pages (p. 270) share pages with other users (p. 270) modify portlets (p. 271) enable communication between portlets (p. 271) add, remove, or reorder the portal tabs (p. 273) change your home page (p. 275) add interactivity to pages and dashboards (p. 278)

268

Chapter 18: Pages and Dashboards For more information about portlets, see "Deploying Cognos Portlets to Other Portals" (p. 441).

Create a Page
You can create your own pages in IBM Cognos Connection to group different types of information into a single view. The pages are saved in Public Folders or My Folders. If you plan to share a page with other users, save it in Public Folders. After you create the page, you can edit it to modify its contents, layout and style, and to set access permissions (p. 270). You can delete pages in IBM Cognos Connection (p. 257) if you have the required access permissions for the pages. Deleting a page may affect your portal tabs (p. 273).

Steps
1. In IBM Cognos Connection, click the new page button .

2. Specify a name and location for the page, and, if you want, a description and a screen tip. 3. Click Next. The Set columns and layout page appears. 4. Define the layout for your page by setting the number and width of columns. Tip: If you are using multiple columns and one of the columns includes a report that is shown in Cognos Viewer, set the width to at least 50% to minimize scrolling. 5. In the column to which you want to add portlets, click Add. 6. Click the portlet group that contains the portlets you want to add. 7. Select the portlets, and click the add button to move them to the Selected entries box. If

you want to remove a portlet from the Selected entries box, click Remove. Tip: You can preview the content of the portlets by clicking the view this portlet button 8. Click OK. 9. Repeat steps 5 to 8 for each portlet group you want. 10. Click OK, and then click Next. The Set page style page appears. 11. Customize the appearance of your page. If you want, add a title and instructions for the page in the language of the product. For more information, see "Edit a Page" (p. 270). To hide the title or instructions, select the associated check box. .

Administration and Security Guide 269

Chapter 18: Pages and Dashboards Tip: To change the formatting of the text, click Custom. To go back to the default formatting, click Return to default. If you want, hide the portlet borders, title bars, or the edit button in the title bar. This helps to avoid clutter and gives the page a uniform look and feel.

12. Click Next. 13. If you want to add the page to the portal tab bar, select the Add this page to the portal tabs check box. To view the page, select the View the page check box. 14. Click Finish.

Edit a Page
You can change the page content, layout and style, and access permissions. For example, you may want to see a different report, or change the list of users who can access the page.

Page Titles and Instructions

When you create a page, you can specify a title and instructions for the page only in the product language you currently use. For example, if you use the French version of IBM Cognos 8, you can type the title and instructions in French only. After the page is created, you can add the title and instructions for other language versions by editing the page properties on the Page Style tab.

Steps
1. Go to the page you want to edit. 2. Click the edit page button .

Tip: Alternatively, locate the page in IBM Cognos Connection, and click its set properties button. 3. Change the page properties as required. For more information about changing the page content, layout, and style, see "Create a Page" (p. 269). For more information about setting the page access permissions, see "Share a Page" (p. 270).

Share a Page
You can share your page with other users by giving them access permissions for the page. You can set up the permissions so that other users can only view the page or also modify it. To view a page, traverse and execute permissions for the page, and execute permissions for its portlets are required. To modify the page, write permissions are also required.

Steps
1. If you did not create the page in Public Folders, copy it there from your personal folders (p. 251).

270

Chapter 18: Pages and Dashboards 2. Specify which users, groups, or roles can have read, traverse, execute, or write permissions for the page. For more information, see "Access Permissions" (p. 213)

Modify a Portlet
Portlets provide different types of information for pages. You can modify the content of an instance of a portlet in a page if you have the required permissions for the page (p. 270). You will retain the custom settings even if the administrator resets the portlet. Other users who also have access to the page that contains this portlet instance will also see the changes. However, if the administrator locks the portlet, you cannot configure it. The configurable properties for the Cognos portlets vary. For more information, click the help button in the portlet title bar.

Steps
1. Go to the page that contains the portlet. 2. In the portlet title bar, click the edit button 3. Edit the properties as required. Tip: If you want to go back to the default settings, click the reset button. 4. Click OK. .

Enable Communication Between Cognos Portlets

You can enable portlet-to-portlet communication so that the portlets can interact. For example, you can use this functionality when you want to navigate published IBM Cognos reports and view the selected reports on the same page. This functionality applies only to Cognos portlets and works between portlets of different groups. For example, the Metric List portlet can communicate with the Cognos Viewer portlet. One portlet is a target portlet, and the remaining portlets are source portlets. The results of actions in the source portlets are shown in the associated target portlets. Portlets in different pages can communicate between themselves. You can enable portlet-to-portlet communication between the following source and target portlets.

Source portlet
Cognos Navigator Cognos Search Cognos Viewer

Target portlet
Cognos Viewer Cognos Viewer Cognos Viewer

Administration and Security Guide 271

Chapter 18: Pages and Dashboards

Source portlet
Metric List

Target portlet
Cognos Viewer Metric History Chart Metrics Impact Diagram

Metrics Impact Diagram

Cognos Viewer Metric History Chart

Metrics Custom Diagram

Cognos Viewer Metric List Metric History Chart

Bookmarks Viewer Image Viewer RSS Viewer

HTML Viewer HTML Viewer HTML Viewer

To enable this functionality, you specify a channel name in the target portlet and refer to this name in the associated source portlets. For more information about Cognos portlets, see "Deploying Cognos Portlets to Other Portals" (p. 441).

Steps
1. Go to the page or the dashboard that contains the portlets for which you want to enable portletto-portlet communication. 2. Click the edit button in the portlet title bar.

3. For the channel property, type the name you want. The name can contain letters, numbers, and underscore (_) characters, but must not contain any spaces. For example, Cognos, Cognos_Portlets, CognosPortlets are valid names. Note: The boxes where you type the channel name have different labels in different portlets. For example, Channel, Portlets using channel, or In a destination portlet. 4. Click OK. 5. Repeat the steps for each portlet that you want to broadcast on the same channel. Ensure that you type the same channel name.

272

Chapter 18: Pages and Dashboards

Portal Tabs
The tabs in IBM Cognos Connection are used to quickly access the pages that are important to you. The tabs represent: Public Folders My Folders Pages or dashboards

An administrator specifies the default tab setup for users. To personalize IBM Cognos Connection, you can add (p. 273) and remove (p. 274) tabs, or reorder them (p. 275). Other users are not affected by your changes. When you delete a page, the tab associated with this page is automatically removed. Your tabs may also be affected by changes to the associated pages made by other users who have access to the pages. For example, when a page is deleted during the current session, its tab is no longer functional, and an error message may appear when you click the tab. To see the most current tab settings, click the IBM Cognos Connection refresh button .

Note: If many tabs exist, scrolling is added automatically.

Add a Tab
You can add a tab in IBM Cognos Connection for a new page or for an existing page so that you can access the page quickly. If the Public Folders or My Folders tabs are not available in your tab bar, you can add them, too. Only one tab can exist for each folder or page. There are various methods to add a tab. Choose the method that is applicable to your current view.

Steps Using My Preferences

1. Click the may area button , My Preferences, and then click the Portal Tabs tab.

A list of your current tabs appears. 2. Click Add. 3. In the list of available pages, select the page you want. You can select multiple pages. 4. Click the right arrow button 5. Click OK. The tab for the page appears in the portal. to move the page to the Selected entries box.

Administration and Security Guide 273

Chapter 18: Pages and Dashboards 6. Click OK to close My Preferences.

Steps Using the Tab Menu

1. From the tab menu on the left side of the tab bar, click Add tabs.

2. In the list of available pages, select the page you want. You can select multiple pages. 3. Click the right arrow button to move the page to the Selected entries box. 4. Click OK. The tab for the page appears in the portal.

Steps Using the Add Button

1. In the list of available pages, locate the page you want. 2. In the Actions column, click its associated add button The tab appears in the portal. .

Delete a Tab
You can delete a tab when it is not needed. When you delete a page that has a tab, the tab is automatically removed. When you remove a tab for a page, the page is not deleted. You can delete the Public Folders and My Folders tabs, and add them back later, if needed (p. 273). Deleting the tabs does not delete Public Folders and My Folders from Content Manager.

Steps Using My Preferences

1. Click the may area button , My Preferences, and then click the Portal Tabs tab.

A list of your current tabs appears. 2. Select the check box next to the tab you want to remove, and click Remove this tab. You can select multiple tabs. 3. Click OK. The tab is deleted from the tab bar.

Steps Using the Tab Menu

1. On the tab bar, click the tab you want to remove. 2. From the tab menu , on the left side of the tab bar, click Remove this portal tab.

3. In the message box, ensure you are deleting the proper tab, and click OK. The tab is deleted from the tab bar.

274

Chapter 18: Pages and Dashboards

Reorder the Tabs

You can change the order of tabs so that they are organized in a way that is meaningful to you.

Steps Using My Preferences

1. Click the may area button , My Preferences, and then click the Portal Tabs tab.

A list of your current tabs appears. 2. Click Modify the sequence. 3. In the Tabs box, move the tabs up or down as required. 4. Click OK. The tabs appear in the new order. 5. Click OK to close My Preferences.

Steps Using the Tab Menu

1. From the tab menu on the left side of the tab bar, click Modify the sequence of tabs.

A list of your current tabs appears. 2. Move the tabs up or down using the appropriate buttons. 3. Click OK. The tabs appear in the new order.

Change Your Home Page

You can choose any page in IBM Cognos 8 as your home page.

Steps
1. Go to the page you want to set up as your new home page. 2. Next to the home icon , click the arrow, and click Set as Home Page.

Create a Dashboard with Multiple Tabs

A dashboard is a visual display of the most important information that a user needs. The information is consolidated and arranged on a single screen so that it can be monitored at a glance. Different segments of information are displayed on different tabs. To create a dashboard, you assemble the different segments of information into a single view by using the Multi-page portlet (p. 267). This portlet is linked to a source folder that contains entries that appear as tabs in the dashboard. You can make changes to the tabs in the dashboard by adding or deleting the associated entries from the source folder. The following entries can be used as tabs in a dashboard: Administration and Security Guide 275

Chapter 18: Pages and Dashboards folders and shortcuts to folders Use folders to include a second level of tabs. packages and shortcuts to packages Use packages to include a second level of tabs. reports and shortcuts to reports Use to view or run a Report Studio report. report views and shortcuts to report views Use to view or run a Report Studio report. queries and shortcuts to queries Use to view or run a Query Studio report. analysis and shortcuts to analysis Use to view or run an Analysis Studio report. pages and shortcuts to pages Use to add a page or another dashboard URLs and shortcuts to URLs Use to embed a different Web page. PowerPlay reports Use to view or run a PowerPlay report MS Documents Use to include a link to a Microsoft document, such as an Excel, PowerPoint, or Word document. The general dashboard properties are the same as page properties. You can edit the dashboard layout and style (p. 270), modify the properties of the Multi-page portlet (p. 271), set up access permissions for the dashboard (p. 270), and add it to the portal tabs (p. 273).

Setting up the Dashboard Folder Structure

Before you start creating your dashboards, we recommend setting up a folder hierarchy in Public Folders to keep your dashboard resources organized. For example, create a folder for all the dashboards you plan to create. Next, create a subfolder for each dashboard to use as source folder for the entries that you want to include in the dashboard, such as reports, folders, pages, or shortcuts. The folder structure may look like this:

276

Chapter 18: Pages and Dashboards

Root folder Dashboards Sales (1) Marketing (2) Sales Resources Marketing Resources Shortcut (3) Shortcut Page Folder
1. The Sales and Marketing pages are the multi-tabbed dashboards. These are the dashboard master pages that are built using the Multi-page portlet. The Sales Resources folder is the source folder for the Sales dashboard, and the Marketing Resources folder is the source folder for the Marketing dashboard. The source folders can contain entries such as reports, pages, folders, shortcuts, and so on. These entries appear as tabs in the dashboard.

2.

3.

Steps
1. In IBM Cognos Connection, click the new page button 2. Type the name, and select a location for your page. 3. Click Next. 4. In the Set columns and layout page, set the number of columns to 1, and the column width to 100%. 5. Click Add. A list of portlet groups appears. 6. In the Available Entries box, click Dashboard. 7. Select the Multi-page portlet, and click the right arrow button Selected Entries box. 8. Click OK, and then Next. 9. In the Set page style page, specify a meaningful title for the page, select any of the remaining properties, and click Next. 10. In the Select an action page, you can select Add this page to the portal tabs. 11. Click Finish. The page that you created is the dashboard master page. 12. Open the page you created. Administration and Security Guide 277 to move the portlet to the .

Chapter 18: Pages and Dashboards An empty frame of the Multi-page portlet appears. 13. In the portlet toolbar, click the edit button The portlet properties page appears. 14. In the Folder section, click Select an entry. 15. Browse to the folder or package that contains the resources for the dashboard, such as shortcuts, pages, or bookmarks. Select an entry, and click OK. Tip: To add My Folders as a tab in the dashboard, create a shortcut to My Folders. 16. Specify other portlet properties as required. For example, in the Display Style section, specify how to display the dashboard tabs, horizontally at the top of the page, or vertically on the left side of the page. For more information about the portlet properties, see "Multi-page" (p. 738). 17. Click OK. You can now open and view the dashboard page. Tip: Other users can access the dashboard through its URL. To see the URL, go to IBM Cognos Connection, locate the dashboard master page, and open its properties page. On the General tab, click View the search path, ID and URL. .

Adding Interactivity to Pages and Dashboards

Pages and dashboards become much more effective for data reporting and analysis when you add interactivity to them. A single action in one report can cause other reports to refresh simultaneously and show the data associated with the action. You can enhance the page interactivity by defining global filters (p. 278) enabling the sharing of drill-up and drill-down actions (p. 283) enabling the sharing of drill-through actions (p. 283)

Defining Global Filters

Global filters are used to control the display of one or more reports in a single portal page or in a dashboard. For example, a global filter can be on a report that contains only a prompt or prompt controls. This allows for a single selection to drive a number of reports at once. When a prompt answer is changed, all related reports refresh dynamically to show the data that answers the prompt. For example, if you answer a prompt for a country with Brazil, all related reports on the page are filtered to show the data for Brazil. When this is used in a dashboard, the context is passed to all corresponding tabs. Perform the following tasks to set up a page or a dashboard with global filters: Prepare the Reports (p. 279)

278

Chapter 18: Pages and Dashboards Create the Global Filters (p. 279) Assemble the Reports on a Page (p. 280)

Preparing the Reports

Before you start creating a page or a dashboard with global filters, you must know which reports you can use, and have the reports ready. The reports can be authored in Report Studio, Query Studio, or Analysis Studio. If you include reports from only one package, the global filters share parameters using the model item. If you include reports from different packages, the following conditions must be met: All reports must use the same parameter name in their filter statements. An example of a relational filter is Country = ?pCountryPrompt?. An example of an OLAP slicer filter is Great Outdoors Company].[Sales Territory].[SalesTerritory].
[Country]->?pCountryPrompt?.

We do not recommend using the default parameter name, such as Parameter1. The Report Studio reports must follow the naming convention used in one of the other studios. For example, in Query Studio the convention is [attribute name] or [level name], such as Order_Method1. In Analysis Studio the convention is [hierarchy name], such as Order
Method.

Note: If the page contains only Report Studio reports, we recommend using the p[attribute
name]Prompt convention, for example, pCountryPrompt.

Create the Global Filters

A global filter is a value that is shared across different reports. At least one of the reports that you are using for the dashboard needs to contain a prompt or prompt control. The prompted report is embedded into a page or a dashboard using the Cognos Viewer portlet and linked with other reports in the page using the global filter portlet properties. The prompts that are used as global filters control the display of your chosen linked reports. If this functionality is implemented in a single page, the prompts control linked reports in different sections of the page. If the page is a dashboard with multiple tabs, the prompts can control the report filtering across tabs. We recommend creating prompt reports in Report Studio. The rich editing environment of this studio gives the author access to a variety of prompt controls, such as the Next, Reprompt, or Finish buttons. These controls add more interactivity to portal pages. For more information about building prompts and prompt pages, see the Report Studio Professional Authoring User Guide.

Using Metrics as Global Filters

You can use metrics and strategy elements in Cognos Metrics portlets as global filters. In a page, or in a dashboard with multiple tabs, the Metric List, Metrics Impact Diagram, and Metrics Custom Diagram portlets can filter prompted parameters for the Cognos Viewer portlet. You must configure Cognos Viewer to show a report associated with a metric or a strategy element, and set up communication between the portlets using the same channel name (p. 271). Administration and Security Guide 279

Chapter 18: Pages and Dashboards When a user clicks a metric name in Metric List, Metrics Impact Diagram, or Metrics Custom Diagram, Cognos Viewer dynamically updates the report if the report prompt parameters are based on metric values. When a user clicks a strategy element in Metrics Custom Diagram, Cognos Viewer dynamically updates the report if the report prompt parameters are based on strategy element values. For this functionality to work, the following parameters that are broadcast on a channel after a click action in a Cognos Metrics portlet must match the names of the report prompt parameters:
scorecard_extid scorecard_sid strategy_sid metric_sid metric_extid time_period_sid

Steps to Create a Prompted Report

1. In Report Studio, create a prompt on a report page, not on a prompt page, of the report. Set the Auto-Submit property for the prompt to yes. If you want to use cascading prompts, only the last prompt in the sequence needs to be on the report page. For some prompts, such as the value prompts, you may need to add a Finish button to signal that the prompt selection is complete. For cascading prompts, the Reprompt button is also required to restart the prompting sequence. 2. Add other details, such as background images, instructions, or a title. The prompt can now be added to a portal page or a dashboard (p. 280).

Assemble the Reports on a Page

The prompts and the target reports in a page or a dashboard create an interactive and easy way to access IBM Cognos BI environment. Each report is displayed using the Cognos Viewer portlet. The reports communicate with each other using the properties of this portlet. You can use different design strategies to implement global filters in a page. Here is an example of a basic layout:

280

Chapter 18: Pages and Dashboards

Prompt report Target report 1

Target report 2

If your page includes reports from different packages, ensure that the prompt reports use the same parameter names as the target reports. Use the following steps when defining global filters in a single page. If you want to implement this functionality in a dashboard, you must complete additional steps. For more information, see "Create a Dashboard with Multiple Tabs" (p. 275).

Steps
1. In IBM Cognos Connection, click the new page button 2. Type the name, and select a location for your page. 3. Click Next. 4. In the Set columns and layout page, set the number and width of columns. For example, the reports that display the prompts and prompt controls can be placed in one column, and the target reports in a separate column to the right. 5. Click Add at the bottom of the first column. 6. In the Available Entries box, click IBM Cognos Content. 7. Select the Cognos Viewer portlet, click the right arrow button Selected Entries box, and click OK. 8. Repeat steps 5 to 7 for each column. You must add the Cognos Viewer portlet for each report that you want to include in the column. For example, if the column on the left will contain a prompt and prompt controls, add two Cognos Viewer portlets. 9. Click Next. 10. Complete the remaining steps in the wizard, if needed, and click Finish. For more information, see the steps in the section "Create a Page" (p. 269). 11. Go to the folder where you saved the new page, and open it. In the page columns, you can see the empty frames of the Cognos Viewer portlets. to move the portlet to the .

Administration and Security Guide 281

Chapter 18: Pages and Dashboards

12. For any portlet in the page, click the edit button

in the portlet toolbar.

13. In the portlet properties page, click Select an entry to select the report you want to display in the portlet. 14. Click Edit Properties. The Advanced Properties Editor appears. 15. For the Fragment Action property, specify the default portlet action when the portlet is invoked in a page. You can choose to show the run icon, run the report, or view the most recent saved output. Tip: For more information about the portlet properties, click the Help button in the portlet. 16. For the Prompt the user property, specify how to execute the prompts. 17. For the Prompt values property, select the Communicate with other portlets check box. This property enables communication between this portlet and other portlets in the page that have this property set up. When you select Every time, if the report contains optional or required prompts, the user is prompted to enter the prompt values before the report is run. When you select Only when required parameter values are missing, the user is prompted if the report contains required prompts and the values are missing. Otherwise the report runs successfully. When you select Never and show the report only when required values are provided, Cognos Viewer attempts to run the report, but the page remains hidden until the required prompt values are provided. When you select Based on the prompt settings of the report, Cognos Viewer uses the prompts specified in the report.

18. If you want to set up communication between only specific portlets in the page, type the channel name in the box provided. Only the portlets that share the same channel name can interact. By specifying the channel name, you have more control over the page. For example, you can link only the reports that have matching parameters. For more information about this property, click the Help button in the portlet. 19. If you want to see the portlet toolbar in the page, for the Show Toolbar property, select the Normal mode and Maximized mode check boxes. 20. Click OK to close Advanced Properties Editor, and click OK again to close the general properties page. 21. Repeat steps 12 to 20 for each portlet in the page.

282

Chapter 18: Pages and Dashboards

Enable Sharing of Drill-up and Drill-down Actions

In pages, you can enable sharing of drill-up and drill-down actions, between reports that are based on a dimensionally modelled data source. A drill action on an item in one report causes the same action in an associated report if the report is on the same page and contains the same item. For example, when you drill down on the item 2005 in one report, all reports in the page drill down on the same item and the data for the year 2005 appears in all reports. This functionality is enabled using the properties of the Cognos Viewer portlet. By default, drill actions are disabled in a page. This functionality is not supported for dashboards with multiple tabs. However, a single page with drill-up and drill-down actions enabled can be embedded into a dashboard as one of the tabs.

Steps
1. In IBM Cognos Connection, create a page that contains the Cognos Viewer portlet for each report that you want to add to the page. For more detailed information, see the steps in "Create a Page" (p. 269). 2. Configure the Cognos Viewer portlets to display the reports that you want to add to the page. In the portlet properties page, click Select an entry to select the report you want to display in the portlet. 3. In the Advanced Properties Editor of the Cognos Viewer portlets, for the Drill down and drill up property, select the Communicate with other portlets on the page check box. This property enables communication between all portlets in the page using the default channel. For more information, click the Help button in the portlet. 4. If you want to set up communication between only specific portlets in the page, type the channel name in the box provided. Only the portlets that share the same channel name can interact. By specifying the channel name, you have more control over the page.

Enable Sharing of Drill-through Actions

You can enable sharing of drill-through actions in a page. When a user drills from a source report to a target report, the target report appears in the specified area of the page. For this feature to work, a page must have a report that contains an authored drill-through path. The page must also contain a placeholder Cognos Viewer portlet that is set up to receive the drillthrough requests. Report-based drill-through works with both interactive reports and saved report outputs. However, it only works for a single drill-through request. If the drill-through contains multiple targets, it must be invoked from the context menu. This functionality is enabled using the Channel property of the Cognos Viewer portlet. You must specify the same channel name for the portlet that contains the source report and the portlet that receives the target report. By default, drill-through actions are disabled in a page.

Administration and Security Guide 283

Chapter 18: Pages and Dashboards This functionality is not supported for dashboards with multiple tabs. However, a single page with drill-through actions enabled can be embedded into a dashboard as one of the tabs.

Steps
1. In IBM Cognos Connection, create a page that contains the Cognos Viewer portlets for the drill-through source report, and the target report. For more detailed information, see the steps in the section "Create a Page" (p. 269). 2. Configure one of the Cognos Viewer portlets to display the Report Studio source report that contains the drill-through path. In the portlet properties page, click Select an entry to select the report you want to display in the portlet. 3. Configure the other Cognos Viewer portlet to display the drill-through target report. As the target report, we recommend using a report that contains prompts. In the portlet properties page, click Select an entry to select the report you want to display in the portlet. 4. For both portlets configured in step 2 and 3, in the Advanced Properties Editor page, for the Report-based drill-through property, select the Communicate with other portlets on the page check box, and type the channel name in the box provided. The channel name is mandatory. For more information about this property, click the Help button in the portlet.

284

Chapter 19: Activities Management

You can manage IBM Cognos 8 activities from My Activities and Schedules in IBM Cognos Connection. You can view a list of your activities that are current, past, upcoming on a specific day, or scheduled. You can filter the list so that only the entries that you want appear. A bar chart shows you an overview of activities. You can set run priority for entries (p. 293). You can also view the run history for entries (p. 294), specify how long to keep run histories (p. 296), and rerun failed entries (p. 297). As an administrator, you can use IBM Cognos Administration to manage activities for all entries, not just your own. You can see who ran each entry and perform actions on entries as required. For example, you may want to cancel a users large job if it is holding up important entries in the queue. You can also override the priority of an entry instance or you can change it permanently for an entry itself (p. 293). If you switch views, you must refresh to see current data. For example, if you switch from Past Activities to Upcoming Activities, you must refresh to see current data in the panes. You must have the Scheduling capability to access My Activities and Schedules. You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Manage Current Activities

Current activities are entries that are currently being processed in IBM Cognos 8. Each entry is listed by name and shows the request time and the status, and the priority for background activities. The bar chart shows the total number of entries, broken down by the number of pending, executing, waiting, and suspended entries. In IBM Cognos Administration, the user who ran the entry is also listed. You can sort the Request time and Status columns. You can choose to view a list of background activities or interactive activities. You can suspend background entries and release them later when you want them to run. You can permanently cancel runs for entries that have one of the following statuses: pending in the queue executing suspended waiting for a process external to IBM Cognos 8 to complete

Administration and Security Guide 285

Chapter 19: Activities Management You can filter the entries to display only those you want. In My Activities and Schedules, you can choose to display only those entries with a specific status or priority, or entries of a specific type or scope. In IBM Cognos Administration, for interactive current entries, you can filter by status and the dispatcher where the activity is running. For background current entries, you can filter by status, priority, type, scope, user who ran the entry, user who owns the entry, and dispatcher. If you cancel an entry that contains other entries, such as a job or an agent, steps or tasks that have not yet been completed are cancelled. However, steps or tasks that have already completed remain completed. You can change the priority of entries (p. 293) and view the run history (p. 294).

Steps in IBM Cognos Connection

1. Start IBM Cognos Connection. 2. In the upper-right corner, click the my area button Current Activities. 3. In the Filter menu, click the filtering items that you want to use. 4. Click Apply. The list shows the entries that you selected. 5. To perform an action on an individual entry, click the arrow to the right of the entry and select the action. To perform an action on several entries, select the check box for the entries you want and then click one of the following buttons on the toolbar. Tip: To select all entries, click the check box in the upper left-hand corner, next to Name. , and click My Activities and Schedules,

Goal
Show entry details Hide entry details Cancel the run Suspend the run Release suspended entries

Button

286

Chapter 19: Activities Management

Goal
Set entry priority

Button

Steps in IBM Cognos Administration

1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. Click the Status tab, and then click Current Activities. 4. Click Background activities or Interactive activities. 5. From the Filter menu, click the filtering items that you want to use. 6. Click Apply. The list shows the entries that you selected. 7. To perform an action on an individual entry, click the arrow to the right of the entry and select the action. To perform an action on several entries, select the check box for the entries you want and then click one of the following buttons on the toolbar. Tip: To select all entries, click the check box in the upper left-hand corner, next to Name.

Goal
Show entry details Hide entry details Cancel the run Suspend the run Run suspended entries Set entry priority

Button

Manage Past Activities

Past activities are entries that have finished processing in IBM Cognos 8.

Administration and Security Guide 287

Chapter 19: Activities Management Each entry is listed by name and shows the request time and the status. You can sort the Request time and Status columns. The bar chart shows the total number of entries, broken down by status. If an entry has failed, a button appears showing the severity of the error. In IBM Cognos Administration, the user who ran the entry is also listed. You can filter the entries to display only those you want. In My Activities and Schedules, you can choose to view a list of activities that occurred over a specified length of time, such as the last four hours or the last day, or you can specify a date or time range. You can filter by status, type, and scope. In IBM Cognos Administration, you can also filter by the user who ran the entry, the user who owns the entry, and the dispatcher where the activity ran. You can view the run history (p. 294).

Steps in IBM Cognos Connection

1. Start IBM Cognos Connection. 2. In the upper-right corner, click the my area button Past Activities. 3. From the Filter menu, click the filtering items that you want to use. Tips: If you want to use advanced filtering options, click Advanced options. To reset all selections to the default settings, click Reset to default. 4. If an error occurred when the entry ran, pause over the error button next to the status to see the severity of the error. 5. Click Apply. The list shows the entries that you selected. 6. To perform an action on an individual entry, click the arrow to the right of the entry and select the action. To perform an action on several entries, click one of the following buttons on the toolbar. and click, My Activities and Schedules,

Goal
Show entry details Hide entry details

Button

Steps in IBM Cognos Administration

1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. Click the Status tab, and then click Past Activities.

288

Chapter 19: Activities Management 4. From the Filter menu, click the filtering items that you want to use. Tips: If you want to use advanced filtering options, click Advanced options. To reset all selections to the default settings, click Reset to default. 5. Click Apply. The list shows the entries that you selected. 6. If an error occurred when the entry ran, pause over the error button to see the severity of the error. 7. To perform an action on an individual entry, click the arrow to the right of the entry to display the Actions menu and then select the action. To perform an action on several entries, click one of the following buttons on the toolbar.

Goal
Show entry details Hide entry details

Button

Manage Upcoming Activities for a Specific Day

You can choose to view a list of all upcoming activities that are scheduled for a specific day. Each entry is listed by name and shows the request time, the status, and the priority. A bar chart shows an overview of activities broken down by scheduled and canceled items. In IBM Cognos Administration, each entry also indicates the user who scheduled it. You can cancel scheduled runs of entries, reschedule entry runs that have been cancelled, and set priorities. You can filter the entries to display only those you want. You can choose the day for which you want to view upcoming activities. You can filter by status, priority, type, and scope. In IBM Cognos Administration, you can also filter by the user that scheduled the entry and the entry owner. You can also change the priority of an entry in the queue (p. 293).

Steps in IBM Cognos Connection

1. Start IBM Cognos Connection. 2. In the upper-right corner, click the my area button Upcoming Activities. 3. From the Filter menu, click the filtering items that you want to use and click Apply. 4. Click Apply. and click My Activities and Schedules,

Administration and Security Guide 289

Chapter 19: Activities Management The list shows the entries that you selected. 5. To perform an action on an individual entry, click the arrow to the right of the entry and select the action. To perform an action on several entries, select the check box for the entries you want and then click one of the following buttons on the toolbar. Tip: To select all entries, click the check box in the upper left-hand corner, next to Name.

Goal
Show entry details Hide entry details Cancel the run Re-schedule a run that was cancelled Set entry priority

Button

Steps in IBM Cognos Administration

1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. Click the Status tab, and then click Upcoming Activities. 4. From the Filter menu, click the filtering items that you want to use and click Apply. 5. Click Apply. The list shows the entries that you selected. 6. To perform an action on an individual entry, click the arrow to the right of the entry to display the Actions menu and then select the action. To perform an action on several entries, select the check box for the entries you want and then click one of the following buttons on the toolbar. Tip: To select all entries, click the check box in the upper left-hand corner, next to Name.

Goal
Show entry details Hide entry details Cancel the run

Button

290

Chapter 19: Activities Management

Goal
Re-schedule a run that was cancelled Set entry priority

Button

Manage Scheduled Activities

You can choose to view a list of scheduled entries. Each entry is listed by name, status, and priority. A bar chart shows you an overview of activities broken down by enabled and disabled schedules. In IBM Cognos Administration, the date and time the schedule was modified and the user who scheduled it are also listed. You can filter the entries to display only those you want. You can choose to display only those entries with a specific status or priority, or entries of a specific type or scope. In IBM Cognos Administration, you can also filter by the user that scheduled the entry and by the entry owner. You can set properties, run the schedule once, disable and enable scheduled entries, modify the schedule, remove the schedule, set the priority (p. 293), and view the run history (p. 294). Depending on the entry, you may also be able to perform other functions, such as view outputs or event lists. For more information on schedules, see (p. 299).

Steps in IBM Cognos Connection

1. Start IBM Cognos Connection. 2. In the upper-right corner, click the my area button Schedules. 3. From the Filter menu, click the filtering items that you want to use and click Apply. 4. Click Apply. The list shows the entries that you selected. 5. To perform an action on an individual entry, click the arrow to the right of the entry and select the action. To perform an action on several entries, select the check box for the entries you want and then click one of the following buttons on the toolbar. Tip: To select all entries, click the check box in the upper left-hand corner, next to Name. , and click My Activities and Schedules,

Goal
Show entry details

Button

Administration and Security Guide 291

Chapter 19: Activities Management

Goal
Hide entry details Enable the schedule Disable the schedule Set entry priority

Button

Steps in IBM Cognos Administration

1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. Click the Status tab, and then click Schedules. 4. From the Filter menu, click the filtering items that you want to use and click Apply. 5. Click Apply. The list shows the entries that you selected. 6. To perform an action on an individual entry, click the arrow to the right of the entry and select the action. To perform an action on several entries, select the check box for the entries you want and then click one of the following buttons on the toolbar. Tip: To select all entries, click the check box in the upper left-hand corner, next to Name.

Goal
Show entry details Hide entry details Enable the schedule Disable the schedule Set entry priority

Button

292

Chapter 19: Activities Management

Manage Entry Run Priority

Scheduled entries can be assigned a priority from 1 to 5. For example, an entry with priority 1 runs before an entry with priority 5. If there is more than one entry with the same priority, the one that arrived in the queue first runs first. The default priority is 3. Interactive entries always run immediately and priority cannot be changed once they are running. You set the priority for an entry when you schedule it (p. 300). When an entry is in the current, upcoming, or scheduled queue, you can change the priority. You may want to set a low priority for entries that take a long time to run so that other entries in the queue are not delayed. When you schedule a job (p. 301), you set the priority for the whole job, not for individual entries within the job. You may want to set a low priority for a job with many entries so that other entries in the queue are not delayed. You schedule priority for the parent job. When the job runs, all the child entries inherit the priority of the parent. When the job is in the queue and is not yet running, you can update the priority. You cannot do this for the individual entries in the job. Changing the priority of the job changes the priority of all its child entries. You can view the run history of a job (p. 294) while it is executing and see which of its entries have completed, are executing, or are pending. The priority of entries in the queue does not affect an entry that is already running. That entry completes and then the queue priority is checked for the next entry to run. Tip: You can change priority of entries based on filtered options. For example, to change the priority of all entries run by Joan Jackson, select her from Ran by under Filter. Then you can select all of the displayed entries and change the priority for all of them at the same time. You must have the Scheduling capability to access manage entry run priority.

Steps in IBM Cognos Connection

1. Start IBM Cognos Connection. 2. In the upper-right corner, click the my area button , and click My Activities and Schedules

and then click Current Activities, Upcoming Activities, or Schedules. 3. To change the priority for one entry, click the arrow to the right of the entry and select Set Priority. To change the priority of more than one entry, select the check box for the entries you want and then click the set priority button on the toolbar.

Tip: To select all entries, click the check box in the upper left-hand corner, next to Name. 4. From the menu, click the priority that you want, and then click OK. If you selected one entry, the current priority of the entry appears in the Set the priority box. If you selected multiple entries, the Set the priority box contains (Multiple).

Steps in IBM Cognos Administration

1. Start IBM Cognos Connection.

Administration and Security Guide 293

Chapter 19: Activities Management 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. Click the Status tab, and then click Upcoming Activities or Schedules. 4. To change the priority for one entry, click the arrow to the right of the entry and select Set Priority. To change the priority of more than one entry, select the check box for the entries you want and then click the set priority button on the toolbar.

Tip: To select all entries, click the check box in the upper left-hand corner, next to Name. 5. From the menu, click the priority that you want, and then click OK. If you selected one entry, the current priority of the entry appears in the Set the priority box. If you selected multiple entries, the Set the priority box contains (Multiple). The new priority appears in the Priority column next to the entries that you selected.

View the Run History for Entries

Sometimes entries are scheduled to run in the background, without anyone waiting to view them. This includes scheduled entries, entries that are run once and saved, and interactive entries that are saved or mailed. Interactive entries do not have run histories. IBM Cognos 8 keeps history information each time an entry runs in the background. The run history for an entry includes information such as the request time, start time, completion time, and whether the report ran successfully. You can look at a more detailed run history for the entry, which includes general, error, and warning messages related to the entry and any actions you can take. If there is email associated with the entry, the status of the email delivery is included. Some types of entries display additional information in the detailed run history page: For reports, a report output version (p. 364) is kept each time a report is run according to a schedule. You can view the report output version from the detailed run history. For jobs, you can view a list of job steps and see a detailed run history for each one. You can also see the parts of the job that have not yet completed. If the entry is part of a parent entry, you can view the parent entry that initiated the run. For deployment export and import entries, you can view the public folders content. You may see the following message: Only progress information is currently available. The information will be updated following the completion of the parent activity. This means that the deployment has completed but the parent activity is still running. Once the final completion information is obtained from the Content Manager, the message no longer appears. For data movement, you can view nodes that were executed as part of a data movement entry. For more information about nodes, see the Data Manager User Guide.

294

Chapter 19: Activities Management You can rerun failed entries (p. 297) from the detailed run history page. You can view a list of related runs that are part of the rerun series and see a detailed run history for each one. You can specify how many run history occurrences to keep or for how long to keep them (p. 296).

Steps in IBM Cognos Connection

1. Start IBM Cognos Connection. 2. In the upper-right corner, click the my area button 3. Click Schedules or Past Activities. 4. Next to the entry, click the arrow and then click View run history 5. If you want, select the Status of entries that you want to view. A list of selected entries appears. 6. If you want to view the run history details, in the Actions column, click the view run history details button next to the entry you want. Then, if you want, from the Severity list, select the severity of the entries. Under Job Steps, the complete run history details is shown. If the job run history details level was set to Limited, no history details for the jobs steps are recorded. 7. If there is a report output version, in the Actions column, click the view outputs button for the entry you want. Then, from the Versions list, click the version you want. To delete a version, click Manage versions click the check box for the version, and then click Delete. . , and click My Activities and Schedules.

Steps in IBM Cognos Administration

1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. Click the Status tab, and then click Schedules or Past Activities. 4. Next to the entry, click the arrow and then click View run history. 5. If you want, from the Status list, click the status of entries that you want to view. A list of selected entries appears. 6. If you want to view the run history details, in the Actions column, click the view run history details button next to the entry you want. Then, if you want, from the Severity list, select the severity of the entries. Under Job Steps, the complete run history details is shown. If the job run history details level was set to Limited, no history details for the jobs steps are recorded. 7. If there is a report output version, in the Actions column, click the view outputs button next to the entry you want. Then, from the Versions list, click the version you want. To view

Administration and Security Guide 295

Chapter 19: Activities Management the version in Cognos Viewer, click the version you want to view. To delete a version, click Manage versions, click the check box for the version, and then click Delete. 8. If there is a log file associated with the entry and you want to view it, click the view the log file button. 9. If you want to view messages, click an item with a link in the Messages column. Tip: Messages are nested. There may be child messages within child messages. If a message is displayed as a link, you can continue to drill down through the child messages.

Specify How Long to Keep Run Histories

You can keep run histories for a specific number of runs or for a specific number of days or months. For example, you can keep the run histories for the ten latest runs (occurrences) or for the past two days or six months. You can also choose to keep all run histories. You must have read and write permissions for the entry and read or traverse permissions for the folder that contains the entry. Tip: If you are an administrator, you can also set how long to keep run histories for entries in IBM Cognos Administration from Set properties on the Actions menu next to the entry.

Steps in IBM Cognos Connection

1. Click the set properties button next to the entry you want.

2. On the General tab, under Run history, choose the retention method and type the value: To keep run histories for a specific number of occurrences, click Number of occurrences and type the number. To save an unlimited number of run histories, set this value to 0. To keep run histories for a specific length of time, click Duration and click either Days or Months. Type the appropriate value in the box. 3. Click OK.

Steps in IBM Cognos Administration

1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. Click the Status tab, and then click the type of entries you want to view. 4. Next to the entry, click the arrow and then click Set properties. 5. On the General tab, under Run history, choose the retention method and type the value: To keep run histories for a specific number of occurrences, click Number of occurrences and type the number. To save an unlimited number of run histories, set this value to 0. To keep run histories for a specific length of time, click Duration and click either Days or Months. Type the appropriate value in the box. 296

Chapter 19: Activities Management 6. Click OK.

Rerun a Failed Entry Task

When an entry, such as a report, agent task, or job runs according to a schedule or runs in the background and the entry fails, you can resubmit the failed entry with the same options that were specified in the original run. For a job that contains steps that ran successfully and steps that did not run successfully, you are not required to rerun the entire job, but can run the job steps individually. If the job steps are run sequentially, you can rerun the job starting with the failed job step. If you wish, you can select which steps to rerun and skip the failed steps. However, the selected job steps run sequentially and if a step fails, then the steps that occur after the failed step are not run. When you rerun a job step individually, a new run history that includes only the single job step is created for the parent job. For more information about run histories, see "View the Run History for Entries" (p. 294). When rerunning an agent entry, associated tasks, such as an email that sends report output to a list of email recipients, are also rerun if they failed initially. If there are two associated tasks running in parallel and one task fails and one succeeds, rerunning the agent only reruns the failed task. However, if tasks are selected to run on failure, they are run again when the rerun fails. Although the run history shows entries that ran successfully, you cannot rerun an entry that succeeded. The run options are not stored for these entries. A rerun can fail when a task associated with a failed entry is deleted or updated. You must have execute permission to rerun a failed task.

Steps in IBM Cognos Connection

1. Start IBM Cognos Connection. 2. In the upper-right corner, click the my area button Past Activities. 3. Next to the entry, click the arrow and then click View run history details . , and click My Activities and Schedules,

The View run history details page shows run details, such as start time and completion time, run status, and error messages for a failed run. Other information that appears in the page depends on whether the entry is for a single task, a job with multiple steps, or an agent with tasks. For example, if it is a single task, the report options and the report outputs appear. If it is a job with multiple steps, a Job section appears with the run details of the job steps. 4. Under Status, next to Failed, click Rerun. If the rerun task is a single task, you receive a message asking you to confirm the rerun. If the rerun task is a job with multiple job steps or an agent with tasks, the Rerun page appears. Select the check box next to the entries you want to rerun.

Administration and Security Guide 297

Chapter 19: Activities Management Tips: You can also rerun failed entries by clicking Rerun in the Outstanding to complete section. To rerun a single job step, in the Job section, in the Actions column, click the view run history details button for the failed step.

Steps in IBM Cognos Administration

1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. Click the Status tab, and then click Past Activities. 4. Next to the entry, click the arrow to view the Actions menu and then click View run history details .

The View run history details page shows run details, such as start time and completion time, run status, and error messages for a failed run. Other information that appears in the page depends on whether the entry is for a single task, a job with multiple steps, or an agent with tasks. For example, if it is a single task, the report options and the report outputs appear. If it is a job with multiple steps, a Job section appears with the run details of the job steps. 5. Under Status, next to Failed, click Rerun. If the rerun task is a single task, you receive a message asking you to confirm the rerun. If the rerun task is a job with multiple job steps or an agent with tasks, the Rerun page appears. Select the check box next to the entries you want to rerun.

Tips: You can also rerun failed entries by clicking Rerun in the Outstanding to complete section. To rerun a single job step, in the Job section, in the Actions column, click the view run history details button for the failed step.

298

Chapter 20: Schedule Management

You can schedule IBM Cognos 8 entries to run at a time that is convenient for you. For example, you may want to run reports or agents during off hours when demands on the system are low. Or you may want to run them at a regular weekly or monthly interval. If you have administrator privileges, you can also schedule tasks that: maintain your content store import or export entries from a deployment archive run jobs run metrics maintenance

You can schedule entries to run at specified intervals. You can schedule entries individually (p. 300) or use jobs to schedule multiple entries at once (p. 301). Jobs have their own schedules independent from report schedules. You can schedule entries to run on the last day of each month (p. 301). You can also schedule entries to be triggered by occurrences, such as database refreshes or emails (p. 304). Only one schedule can be associated with each entry. If you require multiple schedules for a report or agent entry, you can create report views (p. 354) or agent views (p. 385) and then create a schedule for each view. After you create a schedule, the entry or job runs at the time and date specified. You can then view the scheduled entries and manage them. For more information, see "Activities Management" (p. 285).

Prompts in Scheduled Entries

If an entry that contains prompts is scheduled, you must save the prompt values or specify default values (p. 362) to ensure that values exist when the report runs according to the schedule. In a job, you can specify prompt values for job steps. When an entry runs as part of a job, the prompt values saved in the job definition are used instead of the values saved with the entry. If no values are specified in the job definition, IBM Cognos 8 uses the values saved in the entry.

Priority for Scheduled Entries

When you schedule an entry, you may be able to select a run priority from 1 to 5. For example, an entry with priority 1 runs before an entry with priority 5. If there is more than one entry with a specific priority, the one that arrived in the queue first runs first. The default is 3. If you do not have permissions for entry priorities, the priority appears but you can not change it. When you schedule a job, you can set priority for the whole job only, not for individual entries within a job. However, you can change the priority of individual entries when they are pending in the queue. The priority of entries in the queue does not affect an entry that is already running. The running entry completes and then the queue priority is checked for the next entry to run. Administration and Security Guide 299

Chapter 20: Schedule Management For more information, see "Manage Entry Run Priority" (p. 293).

Run Histories for Scheduled Entries

IBM Cognos 8 keeps history information each time a scheduled entry runs. You can use the run history for an entry to see the times at which it ran and whether the it ran successfully . For more information, see "View the Run History for Entries" (p. 294).

Schedule an Entry
You schedule an entry to run it at a later time or at a recurring date and time. For example, you can schedule a report or an agent. If you no longer need a schedule, you can delete it. You can also disable it without losing any of the scheduling details. You can then enable the schedule at a later time. For more information, see "Activities Management" (p. 285). You can schedule an entry to run on the last day of each month (p. 301) or as part of a job (p. 301). You can schedule reports based on trigger occurrences (p. 304). To schedule an entry, you need the permissions that are required to run the entry. For example, to schedule a report or report view, you must have read, write, execute, and traverse permissions for it. To schedule a child report view, you must have execute permissions on the parent report. You also require the following access permissions for any data sources used by the report: dataSource - Execute and Traverse dataSourceConnection - Execute and Traverse With only Execute access, you are prompted to log on to the database. dataSourceSignon - Execute

To set priority for an entry, you must have the required permissions for the Scheduling priority secured feature. See "Secured Functions and Features" (p. 221).

Steps
1. Click the schedule button for the entry you want to schedule 2. Set the priority for the scheduled entry. Select a lower number for higher priority. The default is 3. 3. Under Frequency, select how often you want the schedule to run. The Frequency section is dynamic and changes with your selection. Wait until the page is updated before selecting the frequency. 4. Under Start, select the date and time when you want the schedule to start. 5. Under End, select when you want the schedule to end. Tip: If you want to create the schedule but not apply it right away, select the Disable the schedule check box. To later enable the schedule, clear the check box. .

300

Chapter 20: Schedule Management 6. If additional options are available on the Schedule page, specify what you want. For example, for reports, you can select formats, languages, delivery method (including how to save report output files), and prompt values. For more information, see "Reports and Cubes" (p. 347). 7. Click OK. A schedule is created and the report runs at the next scheduled time.

Example - Schedule an Entry on the Last Day of the Month

You want to schedule a financial report to run automatically on the last day of each month for the next year.

Steps
1. Click the schedule button for the entry you want to schedule 2. Under Frequency, select By Month, and then select Day. 3. Enter Day 31 of every 1 month(s). Entering 31 as the day ensures that the entry runs on the last day of the month, regardless of how many days are in the month. 4. Under Start, select the last day of the current month as the day you want the monthly schedule to start. 5. Under End, select the last day of the same month next year as the day you want the monthly schedule to end. 6. Click OK. .

Use Jobs to Schedule Multiple Entries

You can set the same schedule for multiple entries by creating a job. A job identifies a collection of reports, report views, and other jobs that are scheduled together and share the same schedule settings. When a scheduled job runs, all the entries in the job run. Tip: If a job item is unavailable, you can select a different link by clicking Link to an entry. Jobs contain steps, which are references to individual reports, jobs, and report views. You can specify whether to run the steps all at once or in sequence. When steps are run all at once, all the steps are submitted at the same time. The job is successful when all the steps run successfully. If a step fails, the other steps in the job are unaffected and still run, but the job has a Failed status. When the steps are run in sequence, you can specify the order in which the steps run. A step is submitted only after the preceding step runs successfully.You can choose to have the job stop or have the other steps continue if a step fails.

Administration and Security Guide 301

Chapter 20: Schedule Management You can schedule a job to run at a specific time, on a recurring basis, or based on a trigger, such as a database refresh or an email (p. 304). The individual reports, jobs, and report views in steps can also have individual schedules. Run options for individual step entries override run options set for the job. You can set run options for the job that serve as the default for step entries that do not have their own run options. You can run reports to produce outputs based on the options that you define, such as format and language. You can also include content store maintenance and deployment imports and exports in a job. For more information, see "Maintain the Content Store" (p. 125) and "Deployment" (p. 307).

Cached Prompt Data

For reports that prompt for values each time that the report is run, you may want to use cached prompt data. Reports run faster because data is retrieved from the cache rather than from the database. The cache is used only when a requested language is the same as one in the cache. For example, the cache contains data for English, English (United States), and German (Germany). When prompted, you request English (United States) for the report. There is an exact match and the cached data is used. The cached data is also used when there is a partial match. If you request English (Canada), the cached data for English is used. If you request German (Austria), there is no match and the cached data is not used. You can use caches for reports or report views. For report views, the report view cache is used first. If no report view cache is found, the cache for the associated report is used. You must use a job to create or refresh a cache. You can refresh the cache automatically by scheduling the job to run periodically. If you want to use live data the next time that you run the report, you can clear the cache.

Permissions
Permissions required to include an entry as part of a job vary depending on the type of entry. The permissions are the same as for scheduling an entry (p. 300).

Steps
1. Click the new job button .

2. Type a name and, if you want, a description and screen tip for the job, select the location in which to save the job, and then click Next. The Select the steps page appears. 3. Click Add. 4. Select the check boxes for the entries you want to add and click the right arrow button the entries you want appear in the Selected entries box, click OK. .When

302

Chapter 20: Schedule Management You can also click Search, and in the Search string box, type the phrase you want to search for. For search options, click Edit. When you find the entry you want, click the right arrow button to list the entry in the Selected entries box and click OK. To remove entries from the Selected entries list, select them and click Remove. To select all entries in a list, click the check box in the upper-left corner of the list. To make the user entries visible, click Show users in the list. 5. If you want to change run options for an individual entry when it runs as part of the job, click the set icon , click Produce report outputs, select the Override the default values box, make

the changes, and click OK. To send the report to mobile recipients, select Send the report to mobile recipients and click Select the recipients. Tip: To return to defaults for individual entries, click the delete button. 6. If you want to refresh the cache for a report when the job runs, click the edit icon next to the report, and then from the Run the report to menu, click Refresh the report cache. Click Override the default values. To accept the displayed language, click OK. To change the language, click Select the languages, select the languages you want, and then click OK. Click OK to accept the displayed languages. Tip: To clear the cache, click the delete button. 7. If you want to create or refresh the cache, click the set icon, click Refresh the report cache, select the Override the default values box, add languages, if you want, and click OK. Tip: To clear the cache, click More next to the report whose cache you want to clear, click Clear the cache, and click OK twice. 8. Under Submission of steps, select whether to submit the steps All at once or In sequence. If you select In sequence, the steps are executed in the order they appear in the Steps list. If you want the job to continue to run even if one of the steps fails, select the Continue on error check box. Tip: To change the order, click Modify the sequence, make the changes, and click OK. 9. If you want to specify default run options at the job level, under Defaults for all steps, click Set. 10. If you want to override defaults, select the category and select the Override the default values check box and select the default options you want for the job and click OK. 11. To save the complete history details for the job steps when the run activity completes successfully, click All from the Run history details level list. Click Limited to save limited run history details for the job. If the job run fails, the complete history details are saved. The default is All. 12. Select the action you want:

Administration and Security Guide 303

Chapter 20: Schedule Management To run now or later, click Run now or at a later time and click Finish. Specify the time and date for the run. Click Find only or Find and fix, then click Run. Review the run time and click OK. To schedule at a recurring time, click Schedule to run at a recurring time and click Finish. Then, select frequency and start and end dates. Click Find only or Find and fix, then click OK. Tip: To temporarily disable the schedule, select the Disable the schedule check box. To view the schedule status, see "Activities Management" (p. 285). To save without scheduling or running, click Save only and click Finish.

A job is created and will run at the next scheduled time.

Trigger-based Entry Scheduling

You can schedule entries based on an occurrence, such as a database refresh or an email. The occurrence acts as a trigger, causing the entry to run. For example, you may want to run a report every time a database is refreshed. Trigger-based scheduling may be used to run entries automatically based on an occurrence. It may also be used to limit when users can run entries. For example, in a warehouse environment where the database is refreshed only once a week, there is no need to run reports more frequently. You can choose to schedule the report based on the database refresh so that the report runs only once a week. Trigger-based scheduling applies only to the entry, not to any entry view associated with it. For example, if trigger-based scheduling applies to a report, it does not apply to report views associated with the report. However, you can schedule a report view using a trigger.

Setting Up Trigger-based Scheduling

To schedule an entry based on an occurrence and confirm trigger-based scheduling, you must have read, write, execute, and traverse permissions. You also require the following access permissions for all data sources used by the entry.

Data source
dataSource dataSourceConnection

Permissions
Execute and Traverse Execute and Traverse With only Execute access, you are prompted to log on to the database.

dataSourceSignon

Execute

Before setting up trigger-based scheduling, ensure that your credentials exist and are up to date.

304

Chapter 20: Schedule Management

Tip: Click the my area button dentials.

, My Preferences, and, on the Personal tab, click Renew the cre-

Follow this process to set up trigger-based scheduling: Schedule an entry based on the occurrence (p. 305). Have your administrator set up the trigger occurrence on a server.

Trigger occurrences can also be set up by an SDK developer using the IBM Cognos 8 Software Development Kit (SDK). For more information, see the SDK Developer Guide. See information about setting up the trigger occurrence on a server (p. 535). You can also disable trigger-based scheduling (p. 535).

Schedule an Entry Based on an Occurrence

As part of setting up trigger-based scheduling, you must schedule an entry based on an occurrence. Trigger-based schedule is activated if the user firing the trigger has: read and traverse permissions for the schedule entry traverse permissions for all ancestors of the schedule entry access to IBM Cognos Administration

Steps
1. Click the schedule button next to the entry you want to schedule.

2. Under Frequency, click the By Trigger tab. 3. In Trigger name, type the name of the trigger occurrence. Note: The trigger name that you enter may be provided to you by your administrator or developer. If not, you must inform your administrator or developer of the trigger name that you use. 4. The default start date is "now", and the default end date is "forever", which means the trigger schedule runs when the trigger is fired (either from trigger.bat or from an SDK application). If you enter a valid start and end date, the trigger schedule can only be fired between those dates. 5. Click OK.

Administration and Security Guide 305

Chapter 20: Schedule Management

306

Chapter 21: Deployment

Deployment involves moving applications from one installation to another. In IBM Cognos 8, you deploy packages, top-level folders, or the entire content store from a source environment to a target environment. Typically, deployment transfers entries, such as packages, folders, reports, and report views, from a development environment to a test environment and then to a production environment. You can also deploy between operating systems. It is important to plan your deployment to ensure that you deploy the correct information and that you do not disturb the target environment. It is also important to consider security in the source and target environments. You can upgrade entries from previous releases, by running the deployment import wizard. For more information, see "Import to a Target Environment" (p. 328). You can use an operating system or scripting mechanism to perform deployment from a command line. You can use the IBM Cognos 8 software development kit (SDK) to automate the deployment process to create, update, and delete a deployment specification load a deployment specification from a deployment archive submit deployment export and import requests access deployment history

For more information, see the IBM Cognos 8 Developer Guide.

Deployment Specifications
A deployment specification is an entry in the content store that defines the entries to be deployed deployment preferences name of the deployment archive

There are two types of deployment specifications. Export specifications are created in the source environment and control the creation of deployment archives. Import specifications are created in the target environment and control the import of entries from the deployment archive. You can view the deployment history for each deployment specification to see the date, time, and details of the import or export.

Administration and Security Guide 307

Chapter 21: Deployment

Deployment Archives
A deployment archive is a compressed file that contains the actual entries that are deployed. A deployment archive is created when you export from the source environment. If you export to an existing deployment archive, the contents of the archive are overwritten. You move the deployment archive from the source environment to the target environment. Then you import from the deployment archive into the target environment. To move a deployment archive, you need access to the installation directories on the computer where IBM Cognos 8 is installed. This location is set in the configuration tool. The default location is c8_location/deployment. For information about changing the location, see the IBM Cognos 8 Installation and Configuration Guide.

Deployment Planning
When you deploy, you must consider how to handle security and which deployment method to select: the entire content store (p. 309) selected packages, folders and directory contents (p. 311)

To avoid breaking references in the target environment, you must deploy all entries that refer to entries in another package or folder. Entries to consider include: jobs, shortcuts, and report views memberships and entry permissions

Security and Deployment

Before you deploy, you must consider access permissions (p. 308), security of deployment archives (p. 309), and references to namespaces other than Cognos(p. 309).

Access Permissions
The entries that you deploy may have security applied to them, such as access permissions (p. 213) that specify which users and groups can access them. If you deploy the entire content store (p. 309), all access permissions are deployed. If you deploy selected packages, public folders and directory content, you can choose whether to deploy access permissions (p. 311). Consider the following: Referenced users and groups If you deploy access permissions to a target environment, the referenced users and groups must exist in the target environment. Access permissions rules For access permissions to work after entries are deployed, the source environment and the target environment must use the same authentication provider with the same configuration. Otherwise, the permissions may not work after deployment.

308

Chapter 21: Deployment Use the Cognos namespace to ensure that the permissions from the source environment work in the target environment. For example, in the source environment, create Cognos groups with the group Everyone as a member, and then set access permissions for the groups. After deployment, in the target environment, map the Cognos groups to the appropriate users and groups from the authentication provider, and then remove Everyone from the groups membership. For information about deploying Cognos groups and roles, see "Including Cognos Groups and Roles" (p. 313).

Securing Deployment Archives

A deployment archive (p. 308) can contain sensitive information, such as signons and confidential account or credit card numbers in report outputs. When you export, you can encrypt the deployment archive by setting a password. Later, when you import, you must type the encryption password. The password must contain eight or more characters. You must encrypt the deployment archive when it contains data source signons (p. 186) or when you deploy the entire content store (p. 309). The encryption settings are configured in the configuration tool. For more information, see the IBM Cognos 8 Installation and Configuration Guide.

Including References to Other Namespaces

Some entries, such as groups, roles, distribution lists, contacts, data source signons, and some report properties, such as email recipients and report contacts, can refer to entities in namespaces other than the Cognos namespace. When you deploy public folders and directory content, you can deploy these entries with or without references to these namespaces. Consider the following: Included references If you include the references to other namespaces, the system verifies that each of the referenced entities exists in the applicable namespaces. Therefore, you must ensure that you are logged on to each namespace, and that you have the necessary permissions to access the required entities in the namespaces. If you cannot access the namespaces, you will encounter errors during the deployment. No included references If you do not include the references to other namespaces, the referenced entities are removed from the membership list of groups, roles, distribution lists, and data source signons and other properties where they may exist. When you deploy the entire content store (p. 309), the references to all namespaces are included.

Deploying the Entire Content Store

Deploying the entire content store ensures that all packages, folders, and directory content are copied to a new location. For example, if you are changing the computer where IBM Cognos 8 is

Administration and Security Guide 309

Chapter 21: Deployment installed, you can move the entire content store from the old environment to the new environment and keep all the reports and other entries created by administrators and users. Other reasons to deploy the entire content store include: moving a whole application into a new, empty environment, such as a new computer, from a development environment refreshing a whole application into an existing environment, such as an existing computer, from a development environment moving an application from an existing environment that uses a different underlying technology, such as a different database type for the content store, or a different operating system upgrading the contents of the content store

When you move a content store from one environment to another, you must use the same namespaces for policies, users, roles, and groups to work correctly. When you deploy the entire content store, if there are no conflicts, the contents of the target content store are removed and replaced by the contents of the source content store, except for configuration data. The imported entries keep the owners from the source content store. For information about conflict resolution, see "Conflict Resolution Rules" (p. 315). After the deployment is complete, some links for packages associated with reports may not work. You may need to relink packages to reports. For information about linking packages to reports, see the documentation for the studios. Tip: Instead of deploying the entire content store, you can deploy only specific public folders and directory content (p. 311).

Content Store
The content store includes all entries in the portal, such as: public folders packages reports data sources distribution lists and contacts printers the Cognos namespace deployment specifications

It does not include the deployment history (p. 311). Configuration objects (p. 311) such as dispatchers, are included in exports by default, but excluded in imports. If you want to deploy users personal folders and personal pages, you must choose to include the user account information when you export and import.

310

Chapter 21: Deployment

Deployment History
When you export an entire content store, the export and import deployment specifications that exist in the source content store are exported. Their deployment histories are not exported. Later, when you import the entire content store, you also import the export and import deployment specifications. You do not see entries in the View the deployment history page for the imported specifications. If any of the imported deployment specifications are used for an encrypted deployment archive, you can delete them. To import an entire content store the first time, you must create a new import deployment specification. By default, the information saved in deployment records includes the progress and summary reports only. If you want to include more detailed information, change the recording level using the advanced setting CM.DEPLOYMENTDETAILENTIRECONTENT. Use the steps in "Set Advanced Content Manager Parameters" (p. 123). More recording levels are available in partial deployment (p. 314).

Configuration Information
When you import an entire content store, configuration data is included in the export, but excluded from the import by default. We recommend that you do not change this setting. However, if you must import configuration settings, you can change the default in the Advanced Settings (p. 331). If you import the configuration data, especially in a distributed environment with multiple content managers, the current information about the content manager status may be overwritten by the imported data. Tip: If you import the configuration, restart the service in the target environment to update status information properly. For information about including configuration data in the import, see "Include Configuration Objects in Import of Entire Content Store " (p. 331). For information about how specific objects in the content store are imported, see "Rules For Deploying the Entire Content Store" (p. 316).

Deploying Selected Public Folders and Directory Content

You can choose to do a partial deployment, deploying only selected public folders and directory content, rather than the entire content store (p. 309). You can deploy any packages and folders in Public Folders. Browse the Public Folders hierarchy and select a package or folder. This will deploy its entire contents. You cannot select specific entries in the packages or folders. During export, the parent packages and folders are not exported and Content Manager does not create placeholder locations for them in the target environment. During both export and import, you can specify a new target location in the Content Manager hierarchy for each deployed package and folder. The directory content that you can deploy includes the Cognos namespace, distribution lists and contacts, and data sources and their connections and signons. For information about how specific objects in the content store are imported, see "Deployment Rules When Importing" (p. 315).

Administration and Security Guide 311

Chapter 21: Deployment After the deployment is complete, some links for packages associated with reports may not work, even if you included packages and their reports in the deployment. You may need to relink packages to reports. For information about linking packages to reports, see the documentation for the studios. Tip: If you want to deploy specific entries, you can create a folder at the root level of Public Folders, copy the specific entries to that folder, and select this folder when you deploy.

Deploying Packages
A package is an entry that contains published reports and metadata. Packages are created in Framework Manager, the modeling tool, and then published to IBM Cognos Connection. Packages are stored in the content store and appear as entries in IBM Cognos Connection. During a partial deployment (p. 311), you can deploy one or more packages at a time. A package can reference objects that are outside the package, such as security objects, data sources, and distribution lists. However, referenced objects are not deployed with the package. While you are importing, you can deselect packages in the deployment archive that you do not want to import.

Renaming Packages and Folders

During a partial deployment (p. 311), you can rename packages and folders so that they have a new name in the target environment. This is useful if you do not want to overwrite a package or folder that has the same name in the target environment. The original package or folder remains intact, and the deployed one is renamed. You might also want to add multilingual names for packages and folders so that users can see names suitable for their locale. A locale specifies linguistic information and cultural conventions for character type, collation, format of date and time, currency unit, and messages. Before you rename packages, you consider the information about renaming entries and what happens to associated references to other entries in "Organizing Entries" (p. 251).

Disabling Packages and Folders

During a partial deployment (p. 311), you can disable the packages and folders in the target environment so that users cannot access them. Disabling packages and folders is useful if you want to test them in the target environment before you make them available to users. You can disable packages and folders at the time of export or import. When you disable a package or folder, the entries it contains are not accessible in the target environment after the import. Users cannot run, view, or edit entries. Only users who have write privileges to the disabled entries can access them. For more information, see "Disable an Entry" (p. 253).

Partial Deployment Options

During a partial deployment (p. 311), when you export and import, you can choose the following options. If you do not select an option when you export, it is not available during import.

Including Report Output Versions

You can choose to include the report output versions (p. 364) in your deployment. If you select this option, you can choose what to do if there is a conflict. You can replace the existing report output 312

Chapter 21: Deployment versions in the target environment with those from the deployment archive or keep target environment versions.

Including Run History

The run history of a report shows statistics about the status and times when the report ran (p. 294) in your deployment. You can choose whether to include the run history of reports. If you select this option, you can choose what to do if there is a conflict. You can replace the existing report run histories in the target environment with those from the deployment archive or keep target environment histories.

Including Schedules
You can choose whether to include schedules (p. 299) in your deployment. If you do not deploy schedules, they are removed from the jobs and reports in the target environment. If you select this option, you can choose what to do if there is a conflict. You can replace the existing schedules in the target environment with those from the deployment archive or keep target environment schedules. When you choose to import schedules in the deployment, you can change the imported schedule credentials to your credentials. The credential of a schedule is the credential used to run the report in the schedule. This credential determines the permissions on the report as well as the capabilities that apply to the report execution. If the report does not have the Run as the owner property set to true, then the credential is also used to access the data source, data connection and signon objects. Changing the credential may affect the operation in the following ways: no impact report produces different data as a result of selecting a different connection or signon in the data source report fails to run because the user does not have the proper capabilities or permissions

To change the imported schedule credentials to the credentials of the person doing the import, do the following: Add the advanced setting CM.DeplomentUpdateScheduleCredential and set the value to True. See procedure, "Set Advanced Content Manager Parameters" (p. 123). When you import to the target environment using the New Import Wizard (p. 328), make sure to click Include schedules and select Replace Existing Entries under Conflict Resolution. Next, under Entry ownership, select The user performing the import.

Including Cognos Groups and Roles

You can choose whether to include Cognos groups and roles (p. 207) in your deployment. When you deploy the Cognos groups and roles, you must deploy them all. However, the following built-in groups are not deployed: Anonymous All Authenticated Users

Administration and Security Guide 313

Chapter 21: Deployment Everyone

When you deploy groups, members of the System Administrators group are merged with the members of this group already in the target environment. This ensures that the target environment is accessible in case the deployed members are not valid. However, you may need to modify the membership list when the deployment is complete. If you select this option, you can choose what to do if there is a conflict.You can replace groups and roles in the target environment with those from the deployment archive or to keep target environment groups and roles.

Including Distribution Lists and Contacts

You can choose whether to include distribution lists and contacts in your deployment. If you choose to deploy distribution lists and contacts, you must deploy them all. If you select this option, you can choose what to do if there is a conflict.You can specify whether to replace the distribution lists and contacts in the target environment with those from the deployment archive or to keep the target distribution lists and contacts.

Including Data Sources

You can choose to include data sources and their associated connections (p. 155) in your deployment. If you choose to deploy data sources, you must deploy them all. You can deploy the data sources with or without their signons. If you do not deploy the signons, you must configure the data sources accordingly in the target environment. If you deploy the signons, you must encrypt the deployment archive. If you select this option, you can choose what to do if there is a conflict.You can specify whether to replace the data sources in the target environment with those from the deployment archive or to keep the target environment data sources. If you replace the target data sources, and the data source connections in the source and target environments do not match, you can lose database connections. In this case, you must manually reconnect to the data sources in the target environment after the import, using the database client software.

Including Access Permissions

You can choose to include access permissions (p. 308) in your deployment. If you select this option, you can choose what to do if there is a conflict. You can specify whether to replace the access permissions in the target environment with those from the deployment archive or to keep the target environment access permissions.

Recording Deployment Details

You can specify what type of information is saved in the deployment records by setting the Recording Level for the deployment. The amount of information kept in the records has an impact on performance. You can set the following recording levels: Basic

314

Chapter 21: Deployment Saves the deployment progress and summary information. This is the default option. Minimal Saves only the deployment summary information. This option requires the least memory. Trace Saves all deployment details. This option requires the most memory. For information about recording deployment details when an entire content store is deployed, see "Deployment History" (p. 311).

Ownership Considerations
You can change the ownership of imported entries to the user performing the import. You can select this option at the time of export or import. If you use the owners from the source, the owners are imported along with the entries. You can apply the ownership options to new entries or to new and existing entries.

Deployment Rules When Importing

This section lists the objects in the content store and the rules that apply when they are imported into a target environment. The rules are different depending on whether you deploy the entire content store or selected public folders and directory content. The method you choose determines which objects are included in the import and how conflicts are resolved when an object already exists in the target environment. Objects in the content store represent entries in the portal and the properties of those entries. For example, the object reportView represents a report view entry in the portal and the object runHistory represents the run history of an entry. For more information about objects, see the IBM Cognos 8 Developer Guide. Objects in Public Folders inherit deployment rules by default, depending on whether you are deploying the entire content store (p. 309), or only selected Public Folders and directory content (p. 311).

Conflict Resolution Rules

A conflict can occur when the entry that you want to import from the deployment archive already exists in the target content store. When this happens, one of the following conflict resolution rules is used:

Rule
Replace

Description
Replaces the entry and its children. The entry and all its children are removed from the source content store. The new entry and all its children are added to the source content store.

Administration and Security Guide 315

Chapter 21: Deployment

Rule
Keep

Description
Keeps the entry. The properties of the entry and all its children are not updated. Existing children of the entry are kept. New children may be added.

Update

Updates the entry. The properties of the entry and its children are updated. Existing children of the entry are kept. New children may be added.

Merge

Merges the properties of the entries with existing entries.

If an entry has no children, replace and update have the same end result.

Rules For Deploying the Entire Content Store

When you deploy the entire content store, different conflict resolution rules apply to the different areas of the content store. The default conflict resolution rule for deploying the entire content store is replace, unless specified differently in the deployment rules for the following areas: configuration capability content deployment directory portal

Configuration
When you import the entire content store, objects in the configuration area of the content store are excluded by default. If you used the advanced settings to include configuration information (p. 331), the configuration is updated rather than replaced. Therefore, existing dispatchers and their configuration in the target environment do not change. However, new dispatchers may be added to the configuration. You may need to unregister dispatchers that are imported if they are not applicable to the target environment (p. 111). The following table lists the objects in the configuration area of the content store, whether they are included during import, and the conflict resolution rule used. The alignment of the object names represents the hierarchy of the objects. When a parent object is included, its children are also included Because the root and parent object is replaced, children from the deployment archive replace the existing set of children in the target environment. Therefore, conflicts are unlikely to occur when the children are imported. If a conflict occurs, the conflict resolution rule is to replace the children. 316

Chapter 21: Deployment The following table lists the objects in the configuration area of the content store, whether they are included in the import, and the conflict resolution rule used. In this table, the parent object is configuration and all objects below it are its children.

Object name
configuration configuration folder dispatcher account pageDefinition

Included
No No No No No

Conflict Resolution Rule

Update* Update Update Replace Replace

*Note: This rule applies only when you manually include the configuration objects using the advanced settings.

Capability
All the objects in the capability area of the content store are included and replaced when you import the entire content store. The following table lists the objects in the capability area of the content store, whether they are included in the import, and the conflict resolution rule used. In this table, the parent object is capability and all objects below it are its children.

Object name
capability securedFunction securedFeature

Included
Yes Yes Yes

Conflict Resolution Rule

Update Update Replace

Content
All the objects in the content area of the content store are included and replaced when you import the entire content store.

Deployment
All the objects in the deployment area of the content store are included and replaced when you import the entire content store except for the importDeployment object, which is handled differently. To import, you use an importDeployment object in the target environment. The importDeployment object and its children are not replaced so that the import can complete and a deployment history record can be created. All the other importDeployment objects are replaced.

Administration and Security Guide 317

Chapter 21: Deployment The following table lists the objects in the deployment area of the content store, whether they are included in the import, and the conflict resolution rule used. In this table, the parent object is adminFolder and all objects below it are its children.

Object name
adminFolder exportDeployment deploymentHistory adminFolder importDeployment deploymentHistory

Included
Yes Yes Yes Yes Yes Yes

Conflict Resolution Rule

Replace Replace Replace Replace Replace Replace

Directory
Before importing a namespace other than the Cognos namespace, IBM Cognos 8 verifies that the namespace exists in the startup configuration of the target environment. If the namespace does not exist, an error occurs and the import moves on the next object. Before importing an account, group, or role, IBM Cognos 8 verifies that the account, group, or role exists in the namespace in the target environment. For more information, see "Including References to Other Namespaces" (p. 309). The members of the System Administrators group are always merged when this group is imported. If you select the option to include user information when you import, the namespace account object and some of its children are included. The following table lists the objects in the directory area, whether they are included in the import, and the conflict resolution rule used. In this table, the parent object is directory and all objects below it are its children.

Object name
directory namespace (except for Cognos) namespaceFolder account credential

Included
Yes Yes Yes Set in options Set in options

Conflict Resolution Rule

Update Update Update Update Replace

318

Chapter 21: Deployment

Object name
session graphic output runTimeState folder namespace (Cognos) namespaceFolder account (anonymous account) credential session graphic output runTimeState folder contact distributionList role group dataSource dataSourceConnection dataSourceNameBinding dataSourceSignon printer

Included
No No No No Set in options Yes Yes No No No No No No No Yes Yes Yes

Conflict Resolution Rule

Not applicable Not applicable Not applicable Not applicable Replace Update Update Not applicable Not applicable Not applicable Not applicable Not applicable Not applicable Not applicable Replace Replace Replace

Yes Yes Yes Yes Yes

Replace Replace Replace Replace Replace

Administration and Security Guide 319

Chapter 21: Deployment

Portal
All objects in the portal area of the content store are updated when you import the entire content store.

Rules For Partial Deployment

When you deploy public folders and directory content rather than the entire content store, you select which of the following objects to include: Option 1: Cognos groups and roles Option 2: distribution lists and contacts Option 3: data sources and connections Option 4: data sources and connections with signons Option 5: report output versions Option 6: run histories Option 7: schedules

The default conflict resolution rule for partial deployment is update, unless specified differently in the deployment rules for the content and directory areas. When you deploy public folders and directory content, you cannot include objects from the configuration, capability, exportDeploymentFolder, and importDeploymentFolder areas of the content store (p. 312). For information, see "Including References to Other Namespaces" (p. 309).

Content
When a parent object is updated, new children from the deployment archive are added and join the existing set of children in the target environment. If a conflict occurs, the conflict resolution rule is to replace the children. Because all job steps are replaced, no conflict is possible when importing jobStepDefinition objects. If you include report output versions and run histories and you keep existing entries, the associated objects from the archive are merged with the objects in the target environment. Even though the objects are merged, the retention rules still apply. A full merge may not occur because some objects may be discarded. The following table lists the objects in the content area, whether they are included in the import, and the conflict resolution rule used. In this table, the parent object is content and all objects below it are its children.

Object name
content

Included
No

Conflict Resolution Rule

Not applicable

320

Chapter 21: Deployment

Object name
package root level folder model modelView folder jobDefinition jobStepDefinition jobHistory

Included
Yes when selected

Conflict Resolution Rule

Update

Yes Yes Yes Yes Yes Yes

Replace Replace Update Update Replace Merge or replace Set in Option 6

schedule

Yes

Keep or replace Set in Option 7

query report reportCache cacheOutput reportView reportVersion

Yes

Update

Not applicable Not applicable Yes Set in Option 5 Update Merge or replace Set in Option 5

output graphic page

Set in Option 5 Set in Option 5 Yes or no Set in Option 5

Replace Replace Replace

SQL runHistory

Set in Option 5 Set in Option 6

Replace Merge or replace Set in Option 6 Administration and Security Guide 321

Chapter 21: Deployment

Object name
schedule

Included
Set in Option 7

Conflict Resolution Rule

Keep or replace Set in Option 7

shortcut URL query agentView reportVersion

Yes Yes Yes

Replace Replace Update

Set in Option 5

Merge or replace Set in Option 5

output runHistory

Set in Option 5 Set in Option 6

Replace Merge or replace Set in Option 6

schedule

Set in Option 7

Keep or replace Set in Option 7

Directory
If you include data sources, connections, and signons, and you keep existing entries, the associated objects from the archive are merged with the objects in the target environment. Even though the objects are merged, the retention rules still apply. A full merge may not occur because some objects may be discarded. Note that when you want to include Cognos groups and roles, and distribution lists and contacts, these items must be stored in a folder within the namespace in order to be deployed. The members of distribution lists, groups, and roles in the archive are not merged with the contents in the target environment. Instead, the set of distribution lists, groups, and roles are merged with the set already existing in the target environment. However, the members of the System Administrators group are always merged when this group is imported. For more information, see "Including Cognos Groups and Roles" (p. 313). The following table lists the objects in the directory area, whether they are included in the import, and the conflict resolution rule used. In this table, the parent object is directory and all objects below it are its children.

Object name
directory

Included
No

Conflict Resolution Rule

Not applicable

322

Chapter 21: Deployment

Object name
namespace (except forCognos) namespaceFolder account credential session graphic output runTimeState folder namespace (IBM Cognos) namespaceFolder

Included
No No No No No No No No No No

Conflict Resolution Rule

Not applicable Not applicable Not applicable Not applicable Not applicable Not applicable Not applicable Not applicable Not applicable Not applicable

Yes if Option 1 or Update Option 2 is true, and they are stored in a folder within the namespace No No No No No No No Set in Option 2 Not applicable Not applicable Not applicable Not applicable Not applicable Not applicable Not applicable Merge or replace Set in Option 2

account (anonymous) credential session graphic output runTimeState folder contact

Administration and Security Guide 323

Chapter 21: Deployment

Object name
distributionList

Included
Set in Option 2

Conflict Resolution Rule

Merge or replace Set in Option 2

role group dataSource

Set in Option 1

Merge or replace Set in Option 1

Set in Option 3

Merge or replace Set in Option 3

dataSourceConnection

Set in Option 3

Keep or replace Set in Option 3

dataSourceNameBinding

Set in Option 3

Keep or replace Set in Option 3

dataSourceSignon

Set in Option 4

Keep or replace Set in Option 4

printer

No

Not applicable

Deploying IBM Cognos 8 Entries

To deploy IBM Cognos 8, you export into a deployment archive in the source environment move the deployment archive to the target environment include configuration objects if you are importing the entire content store import from the deployment archive into the target environment test the deployed entries

In IBM Cognos Connection, you can organize your deployment specification in folders in the same way that you organize all your entries. See "Organizing Entries" (p. 251).

Deployment and Agents

Deployment can be part of an agent. For more information, see "Agents" (p. 383).

Deployment Schedules and Run History

You can schedule deployment to run automatically at a specified time or as part of a job. IBM Cognos 8 saves the run history for each deployment specification. After you export or import, you can view the date and time and the status of the deployment. You can also view any error messages 324

Chapter 21: Deployment created by the deployment and the list of entries that were exported or imported. For more information, see (p. 285).

Permissions
To deploy IBM Cognos 8 entries, you must have execute permissions for the Administration tasks secured feature (p. 693) and traverse permissions for the Administration secured function. We also recommend that you belong to the System Administrators group and have read and write access to the Cognos namespace so that you can deploy the System Administrators group. For more information, see "Set Access Permissions for an Entry" (p. 216). When you do a partial export of public folders and directory content (p. 311) rather than exporting the entire content store (p. 309), you must have read and traverse permissions for the entries that you export. You also need write permissions because you create a deployment specification and deployment history when you export. When you import, you must have write and set policy permissions for the entries that you import.

Prerequisites
IBM Cognos 8 and other products, must be installed and configured in the source and target environments. For more information, see the IBM Cognos 8 Installation and Configuration Guide. We recommend that you stop the Content Manager service before you export and import. This prevents users from receiving unpredictable results if they are performing operations during the deployment. For example, if users view reports in a package while the package is being imported, users may encounter errors when the report outputs are replaced. For more information, see "Stop and Start Dispatchers and Services" (p. 108). Before you start, you must plan the deployment to determine what deployment options to use and what entries to deploy (p. 308). You may want to back up before deployment (p. 197).

Create an Export Deployment Specification

To export the IBM Cognos 8 entries, you create an export deployment specification (p. 307). You can also use a previously saved deployment specification for export or for redeployment of your entries. The entries are exported to an export deployment archive (p. 308) in the source environment. Later, you import the archive entries into the target environment. You can update the entries in the target environment using the entries from the deployment archive. When you export, you select the entries to deploy, and you set the options that are used as defaults when importing.

Steps to Create a New Export Deployment Specification

1. In the source environment, open IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Configuration tab, click Content Administration. 4. On the toolbar, click the new export button . The New Export wizard appears.

Administration and Security Guide 325

Chapter 21: Deployment 5. Type a unique name and an optional description and screen tip for the deployment specification. Select the folder where you want to save it and click Next. 6. Choose whether to export the entire content store or to do a partial export of specific folders and directory content: To export specific folders and directory content, click Select public folders and directory content, and then click Next. Proceed to step 7. To export the entire content store, click Select the entire content store and select whether to include user account information. Click Next and proceed to step 18. 7. In the Select the Public folders content page, click Add. 8. In the Select entries page, in the Available Entries box, select the packages or folders that you want to export. You can browse the Public Folders hierarchy and choose the packages and folders you want. Click the right arrow button click OK. 9. For each package and folder that you export, do one of the following: If you want the package or folder to have a different name in the target environment, or if you want to change the target location or add multilingual names, click the edit icon make your changes, and click OK. If you do not want users to access the package or folder and its entries, select the check box in the Disable after import column. This is useful when you want to test the reports before you make them available in the target environment. 10. Under Options, select whether you want to include the report output versions, run history, and schedules and what to do with entries in case of a conflict. 11. Click Next. 12. In the Select the directory content page, select whether you want to export Cognos groups and roles, distribution lists and contacts, and data sources and connections and what to do with the entries in case of a conflict. 13. Click Next. 14. In the Specify the general options page, select whether to include access permissions and references to namespaces other than IBM Cognos, and who should own the entries after they are imported in the target environment. 15. Specify the Recording Level for the deployment history (p. 314). 16. Click Next. 17. In the Specify a deployment archive page, under Deployment archive, select an existing deployment archive from the list, or type a new name to create one. to move the selected items to the Selected entries box, and

326

Chapter 21: Deployment If you are typing a new name for the deployment archive, we recommend that you do not use spaces in the name. If the name of the new deployment specification matches the name of an existing deployment archive, the characters _# are added to the end of the name, where # is a number such as 1. 18. If you want to secure the archive, under Encryption, click Set the encryption password, type a password, and then click OK. 19. Click Next. The summary information appears. 20. Review the summary information and click Next. Tip: If you want to change information, click Back and follow the instructions. 21. Review the summary information and click Next. 22. Select the action you want: To run now or later, click Save and run once and click Finish. Specify the time and date for the run. Then click Run. Review the run time and click OK. To schedule at a recurring time, click Save and schedule and click Finish. Then, select frequency and start and end dates. Then click OK. Tip: To temporarily disable the schedule, select the Disable the schedule check box. To view the schedule status, see "Manage Scheduled Activities" (p. 291). To save without scheduling or running, click Save only, and then click Finish.

After you run the export, you can move the deployment archive. You can also see the export run history (p. 294).

Steps to Modify an Existing Export Deployment Specification

1. In the target environment, open IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Configuration tab, click Content Administration. 4. In the Actions column, click the properties button want to modify, and then click the Export tab. 5. Modify the deployment options as required. Tip: If you want to change the export target location, click the edit button next to the for the deployment specification you

export name in the Target name column, the Public Folders content section, and choose the package or folder you want. 6. Click OK.

Administration and Security Guide 327

Chapter 21: Deployment This saves the options and you can run the export now or at a later time (p. 328).

Steps to Run an Export

1. In the Actions column, click the run with options button .

2. Click Now to run the export immediately, or click Later, and enter the time, that you want the export to run. You can also schedule a task to run on a recurring basis, and view a list of scheduled tasks using the Schedule Management tool. For more information, see "Schedule Management" (p. 299). Tip: To avoid warning messages when logged into multiple namespaces, before you run the export next time, renew your credentials. In IBM Cognos Connection, in the upper-right corner, click the my area button , and then click My Preferences. On the Personal tab, in the Cre-

dentials section, click Renew the credentials. You can now move the deployment archive.

Move the Deployment Archive

Move the deployment archive that you created in the source environment to the target environment. Later, you use the deployment archive to import in the target environment. If the source and target environments use the same content store, you can import without moving the deployment archive. The location where deployment archives are saved is set in the configuration tool. The default location is c8_location/deployment. If you plan to move the deployment archive to a location on a LAN, ensure that there is enough disk space. If you did not encrypt the deployment archive, we recommend that you copy it to a secure location.

Steps
1. Copy the deployment archive from the source environment to a location on the LAN or to a CD. 2. Copy the deployment archive from the LAN or CD to the target environment in the location set in the configuration tool. You can now include configuration objects if youre importing an entire content store or import to the target environment.

Import to a Target Environment

You import entries from the deployment archive (p. 308) into the target environment. To import the entries, you create an import deployment specification (p. 307).

328

Chapter 21: Deployment You can import using an existing deployment specification if you previously saved it without importing, or if you want to redeploy your IBM Cognos 8 entries. You can update the entries in the target environment with entries from the deployment archive. When you import, you select from entries that were exported. You can either accept the default options set during the export, or change them. You cannot select options that were not included in the deployment archive during the export. For information about how specific objects in the content store are imported, see "Deployment Rules When Importing" (p. 315). You can also use the New Import wizard to upgrade entries from previous releases of the product. You can upgrade report specifications during the import, or choose to upgrade them at a later time using the New Report Upgrade wizard. For more information, see "Upgrade Report Specifications" (p. 332). To use an existing import deployment specification, see "Steps to Modify an Existing Import Deployment Specification" (p. 330)

Partial Deployment
If you do a partial deployment of specific public folders and directory content, the import wizard shows whether packages and folders already exist in the target environment and the date and time they were last modified. You can use this information to help you decide how to resolve conflicts. When you redeploy, the wizard also shows whether the packages and folders were in the original deployment.

Steps to Create a New Import Deployment Specification

1. In the target environment, open IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Configuration tab, click Content Administration. 4. On the toolbar, click the new import button . The New Import wizard appears.

5. In the Deployment archive box, click the deployment archive that you want to import. 6. If the deployment archive is encrypted, type the password, and then click OK. 7. Click Next. 8. Type a unique name and an optional description and screen tip for the deployment specification, select the folder where you want to save it, and then click Next. 9. Select the content that you want to include in the import. Tip: To ensure that the required target package or folder exists in the target content store, click the edit button next to the package, and check the location. If you want, you can change the target location now. 10. Select the options you want, along with your conflict resolution choice for options that you select.

Administration and Security Guide 329

Chapter 21: Deployment 11. In the Specify the general options page, select whether to include access permissions and references to namespaces other than IBM Cognos, and who should own the entries after they are imported in the target environment. 12. Specify the Recording Level for the deployment history (p. 314). 13. Click Next. The summary information appears. 14. Review the summary information and click Next. 15. Select the action you want: To run now or later, click Save and run once and click Finish. Specify the time and date for the run. Then click Run. Review the run time and click OK. To schedule at a recurring time, click Save and schedule and click Finish. Then, select frequency and start and end dates. Then click OK. Tip: To temporarily disable the schedule, select the Disable the schedule check box. To view the schedule status, see "Manage Scheduled Activities" (p. 291). To save without scheduling or running, click Save only then click Finish. When you run the import, you have the option of selecting to upgrade the report specification. If you choose not to upgrade the deployment specification at this time, you can upgrade it later. For more information, see "Upgrade Report Specifications" (p. 332). After you run the import, you can test the deployment. You can also see the import run history (p. 294).

Steps to Modify an Existing Import Deployment Specification

1. In the target environment, open IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Configuration tab, click Content Administration. 4. In the Actions column, click the properties button want to modify, and then click the Import tab. 5. Modify the deployment options as required. Tip: If you want to change the import target location, click the edit button next to the for the deployment specification you

import name in the Target name column, the Public Folders content section, and choose the package or folder you want. 6. Click OK.

330

Chapter 21: Deployment This saves the options and you can run the import now or at a later time (p. 331).

Steps to Run an Import

1. In the Actions column, click the run with options button .

2. Click Now to run the import immediately, or click Later, and enter the time, that you want the import to run. 3. If you want to upgrade the report specifications, click Upgrade all report specifications to the latest version. You can also schedule a task to run on a recurring basis, and view a list of scheduled tasks using the Schedule Management tool. For more information, see "Schedule Management" (p. 299). You can now test the deployment.

Include Configuration Objects in Import of Entire Content Store

You can include configuration objects when importing an entire content store. For example, you may want to import the configuration because you have a series of advanced settings for your services that you want from the source environment. By default, configuration objects are excluded when you import an entire content store, even though they are included in the export. Configuration objects include dispatchers and configuration folders used to group dispatchers. For more information, see "Rules For Deploying the Entire Content Store" (p. 316). We recommend that you do not import configuration objects. Dispatchers should be configured in your target environment before you import data from a source environment. If you must import configuration objects, you should either stop the source dispatcher services before the import, or restart IBM Cognos 8 in the target environment after the import. Otherwise, you may get errors with the status of dispatchers. If you want to import configuration objects, you must be prepared for a brief interruption of services.

Steps
1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Dispatchers and Services. 3. Click the dispatcher you want. 4. Next to ContentManagerService, click the set properties button. 5. Click the Settings tab. 6. In the Value column, click Edit. 7. Select the Override the settings acquired from the parent entry check box. 8. In the Parameter column that appears, type the following in uppercase:

Administration and Security Guide 331

Chapter 21: Deployment CM.DEPLOYMENTINCLUDECONFIGURATION 9. In the Value column, type true 10. Click OK to finish.

Testing Deployed Applications

After you import the packages from the deployment archive, you may want to verify that all the entries were deployed successfully in the target environment. You can test your deployment by reviewing the run history for a deployment ensuring that the correct packages and folders were imported along with their contents ensuring that the data sources, distributions lists and contacts, and Cognos groups and roles were imported verifying the permissions for the imported entries ensuring that the schedules were imported ensuring that any references to renamed packages were updated running imported reports and report views

Upgrade Report Specifications

If you did not upgrade report specifications when you ran the import wizard, you can upgrade them using the New Report Upgrade wizard. Important: Do not upgrade your report specifications if you have SDK applications that create, modify, or save report specifications. You must first update your SDK applications to comply with the IBM Cognos 8 report specifications schema. Otherwise, your SDK applications may not be able to access the upgraded report specifications. For information about upgrading report specifications, see the IBM Cognos 8 Developer Guide.

Steps
1. Log on to IBM Cognos Connection as an administrator with execute permissions for the Content Administration feature (p. 225). 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Configuration tab, click Content Administration. 4. Click the arrow on the new content maintenance button New Report Upgrade 5. Type a name for the upgrade task and, if you want, a description and screen tip. Click Next. 6. Select the packages and locations for the report specification you want to upgrade. Click Next. on the toolbar, and then click

332

Chapter 21: Deployment If you upgrade report specifications by package, all reports in the content store that are based on the model in the package will be upgraded. If you upgrade report specifications by folder, all reports in the folder will be upgraded. 7. Choose one of the following: Save and run once opens the run with options page. Save and schedule opens the scheduling tool. Save only allows you to save the upgrade so that you can run it at a later time.

Administration and Security Guide 333

Chapter 21: Deployment

334

Chapter 22: Administering Packages

Models and packages use corporate business rules to define and group the data to be used for business reporting. A model is a data structure containing imported data from one or more data sources. IBM Cognos 8 users responsible for data modeling use Framework Manager to create models. The data modeler creates a package that defines a subset of data that is relevant to an intended group of users. For example, the data modeler may create a package that marketing managers use for information related to market research. The package can then be distributed to report authors by publishing it to the portal. When you run a report, the result set is defined by the data retrieval information defined in the package. In IBM Cognos Connection, you can manage packages the way you manage other entries. For example, you can organize packages in folders, create shortcuts to packages, and move or copy packages. You can also hide a package to prevent it from unnecessary use (p. 254). For more information about models and packages, see the Framework Manager User Guide.

Data Trees
Data trees may contain many hierarchical levels and items (members). If all levels and members appear, the data trees may be difficult to use. After packages are deployed to IBM Cognos 8 (p. 307), you can specify how data trees appear in the studios. The settings do not affect the model. They affect only the package configuration. The settings for a package are obtained by the studios when a report is opened. The settings are also obtained when a Analysis Studio analysis is opened in Cognos Viewer.

Setting
Default member limit in a data tree level

Purpose
In Analysis Studio, specifies the number of members that appear at a time in one level of the data tree. For example, if this is set to 10, and the maximum member limit is set to 20, Analysis Studio users see only the first ten memebers and must click More to see the next ten. At this point, they see the maximum number and they must then search for a specific member. If your data tree has only 50 members, you may want to set this to 55 so that users do not have to click a link to see all members. Default: 20

Administration and Security Guide 335

Chapter 22: Administering Packages

Setting

Purpose

Maximum member limit in a data tree For all studios, specifies the maximum number of members that appear in one level of the data tree. Thereafter, level users must search for a specific member. If your data tree is large, you may want to set this to a low number because users can find the member they are looking for faster by searching. Default: 50

Configure or Reconfigure a Package

After a new package is deployed, the default settings are used. You can configure a new package to use different settings or you can modify the settings of an existing package configuration at any time. You must have write permission for the package. To modify the package configuration, you must also have write permission for package configuration (p. 336).

Steps
1. In IBM Cognos Connection, locate the package you want. 2. In the Actions column, click More. 3. Click New package configuration or Modify the package configuration. 4. Click Select an analysis. 5. Select the default analysis to be used for this package when new analysis is created. 6. Click OK. 7. Change the package settings as required and click Finish.

Set Permissions for Package Configuration

To modify a package configuration, you must have write permission for package configuration. For more information on permissions, see "Access Permissions" (p. 213).

Steps
1. In IBM Cognos Connection, locate the package you want. 2. In the Actions column, click More. 3. Click Modify the package configuration. 4. Click the Permissions tab. 5. Click OK.

336

Chapter 22: Administering Packages

Remove a Package Configuration

After you configure a new package, you can remove the configuration at any time. You may want to do this to return to the default settings.

Steps
1. In IBM Cognos Connection, locate the package you want. 2. In the Actions column, click More. 3. Click Remove the package configuration. 4. Click OK.

Administration and Security Guide 337

Chapter 22: Administering Packages

338

Chapter 23: Managing User Profiles

User profiles contain portal tab and personal folder content, as well as user preferences such as product language, the preferred output format of reports, and the style used in the user interface. The default user profile applies to all new users. You may want to edit the default user profile for your users (p. 339). You can perform the following tasks on user profiles in IBM Cognos 8: deleting user profiles (p. 340) copying user profiles (p. 340) viewing or changing user profiles (p. 341)

Users can change their own preferences. For more information, see "Personalize the Portal" (p. 260). User entries are created in authentication providers. For more information, see "Users, Groups, and Roles" (p. 207). To copy, edit, or delete user profiles, an administrator must have write permissions for the namespace that contains the applicable users. The IBM Cognos predefined role, Directory Administrators, does not have write permissions for namespaces other than the Cognos namespace. The System Administrators must grant write permissions to Directory Administrators so that they can administer user profiles for the namespace (p. 234).

Edit the Default User Profile

The default user profile contains settings that apply to all new user profiles. You can edit the default user profile for your users to minimize the number of changes you need to make to individual user profiles. You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Security tab, click Users, Groups, and Roles. 4. Click the Cognos namespace. 5. On the toolbar, click the edit default user profile button 6. Set the default user profile and click OK. .

Administration and Security Guide 339

Chapter 23: Managing User Profiles

Delete a User Profile

You can delete user profiles from the content store. This is useful if you are deleting a user in your authentication provider. You may first want to delete the user profile from the content store so that it no longer uses storage space. You should delete the user profile from IBM Cognos 8 before you delete the user in the associated namespace. After you delete the user from the authentication provider, the associated user information no longer appears in IBM Cognos 8 and you cannot manage the user profile by deleting user profiles using IBM Cognos Administration. If the user account was already deleted from the associated namespace, you can use content store maintenance (p. 125) to find, and optionally remove, all associated user account information from IBM Cognos 8. If a user with a deleted user profile logs on, an account is created using defaults. If a user is logged on when you delete the user profile, the users passport expires and the logon page appears. Before you delete a user profile, you may want to view the content (p. 341) to ensure that you are not deleting anything important. You can work only with profiles of users who logged on at least once. When users have logged on, there is a date displayed in the Modified column. You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221). To delete a user profile, you must have write access to the parent object.

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Security tab, click Users, Groups, and Roles. 4. Click the namespace that contains the user. 5. Find the user whose user profile you want to delete. You can use the Search feature to find a user (p. 259). 6. In the Actions column, click More. 7. Click Delete this users profile. 8. Click OK.

Copy a User Profile

You may want to copy a user profile. This is useful in the following situations: A user changes names and you are setting up an account in the new name. A user moves to another namespace or your organization changes namespaces and you must set up new accounts.

340

Chapter 23: Managing User Profiles You are creating many new similar user accounts.

If you plan to delete the source user in your authentication provider, copy the user account information before you delete it. After you delete the user, the user no longer appears in IBM Cognos 8 and you cannot copy the users account information. When you copy a user profile, trusted credentials are not copied. You can only work with profiles of users who have logged in at least once. When users have logged on, there is a date displayed in the Modified column. You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221). To copy user profiles, you must have write access to the namespaces for both the source and target users.

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Security tab, click Users, Groups, and Roles. 4. Click the namespace that contains the source user (the user you want to copy from). 5. Find the source user. You can use the Search feature to find a user (p. 259). 6. Click Select the target user. The Select the user page appears. 7. Click the namespace that contains the target user (the user you want to copy to). Tip: You can select only the namespaces that you have write access to. 8. Select the target user and click OK. 9. Select one or more of the following profile settings that you want to copy: Preferences, Portal tabs, or Personal folders content. 10. If required, select the Delete the source users profile after the copy completes check box. 11. Click Copy.

View or Change a User Profile

You can view or change user preferences. You can also delete specific items in a users My Folder (p. 258) and Portal (p. 267). This may be useful in the following situations: The My Folders or Portal content for a user is taking up so much space that performance is affected. You want to delete some or all of the content. You want to view a user profile before deleting it to ensure that you do not delete any important content.

Administration and Security Guide 341

Chapter 23: Managing User Profiles If a user was deleted in your authentication provider, the user no longer appears in IBM Cognos 8 and you cannot change the user profile. You can only see user profiles of users who have logged in at least once. When users have logged on, there is a date displayed in the Modified column. You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221). To view a user profile, delete content, or change content, you must have traverse permissions for the user account and any other folder that must use Public Folders. You must also have write permissions for the object and the parent of the object that you want to delete.

Steps to View or Change Preferences

1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Security tab, click Users, Groups, and Roles. 4. Click the namespace that contains the user. 5. Find the user whose preferences you want to view or change. You can use the Search feature to find a user (p. 259). 6. In the Actions column, click More. 7. Click Set preferences. 8. Click Cancel to exit without making changes or make changes and click OK.

Steps to Delete Content

1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Security tab, click Users, Groups, and Roles. 4. Select the namespace that contains the user. 5. Find the user. You can use the Search feature to find a user (p. 259). 6. In the Name column, click the user. A list of the users folders appears. 7. Click a folder to see its contents. You cannot delete the folders themselves. 8. Click an item in a folder, then click the delete button on the toolbar.

342

Chapter 24: Administering Microsoft Office Documents

Microsoft Office users can import data from IBM Cognos 8 reports into workbooks, presentations, and documents using IBM Cognos 8 Go! Office and then publish the workbooks, presentations, and documents to the Cognos 8 portal. For more information, see the IBM Cognos 8 Go! Office User Guide and the IBM Cognos 8 BI Analysis for Microsoft Excel User Guide. IBM Cognos Connection users can then download the workbooks, presentations, and documents for viewing or editing in the Microsoft Office application that was used to create it. Note: The only way to publish Microsoft Office workbooks and presentations in IBM Cognos 8 is to use IBM Cognos 8 Go! Office or IBM Cognos 8 BI Analysis. Before users can import IBM Cognos 8 data into Microsoft Office documents or publish those documents in the Cognos 8 portal, you must deploy the IBM Cognos 8 Go! Office and IBM Cognos 8 BI Analysis client to the users workstations.

Deploying IBM Cognos 8 Go! Office Client

IBM Cognos 8 Go! Office is available for installation with IBM Cognos 8 components. After IBM Cognos 8 is installed and configured, you can deploy IBM Cognos 8 Go! Office to client workstations. When you deploy IBM Cognos 8 Go! Office, you install Microsoft .NET Framework and the support files using the provided setup executable and then configure security as required.

Deploying IBM Cognos 8 Go! Office to Client Computers

IBM Cognos 8 Go! Office uses Microsoft .NET Framework to allow users to interact with serverbased components. Microsoft .NET Framework and the required updates are downloaded and installed by the setup file when you install IBM Cognos 8 Go! Office. The setup file must be run on all user computers. For a list of supported versions of Microsoft .NET Framework, see the IBM Cognos Resource Center (http://www.ibm.com/software/data/support/cognos_crc.html). Use the following checklist to guide you through the deployment process: Install .NET Framework and IBM Cognos 8 Go! Office. For more information about installing IBM Cognos 8 Go! Office, see the IBM Cognos 8 Go! Office Installation Guide. Set the macro security level for Microsoft Office XP, if required. Install the CA certificate for secure sockets layer support, if required.

Administration and Security Guide 343

Chapter 24: Administering Microsoft Office Documents

Set Macro Security Level for Microsoft Office XP

For Microsoft Office XP applications to run IBM Cognos 8 Go! Office, you must set your macro security level to an appropriate level. You must set this for Microsoft Office Excel, Microsoft Office Word, and Microsoft Office PowerPoint.

Steps
1. Open your Microsoft Office XP application. 2. From the Tools menu, click Macros, and then click Security. 3. Choose whether to change the security level or the trusted publishers. On the Security Level tab, click Medium or Low, and then click OK On the Trusted Publishers tab, select Trust all installed add-ins or templates, and then click OK.

Install the CA Certificate for the HTTPS Interface to Series 7 PowerPlay

If your environment includes IBM Cognos Series 7 PowerPlay Enterprise Server and you are using the HTTPS (https://) interface to access Series 7 PowerPlay, you must install a certificate issued by a certificate authority (CA). The CA certificate is required for secure sockets layer (SSL) support.

Steps
1. Retrieve the CA certificate from your administrator. The file has a .cer extension. 2. Double-click the .cer file, click Install Certificate, and then click Next. 3. Click Place all certificates in the following store. 4. Click Browse, click Trusted Root Certification Authorities, and then click Next. 5. Click Finish.

Download a Microsoft Office Document

You can download a Microsoft Office document from IBM Cognos Connection if it was published in IBM Cognos 8 using IBM Cognos 8 Go! Office or IBM Cognos BI Analysis for Microsoft Excel . For more information, see the IBM Cognos 8 Go! Office User Guide and the IBM Cognos 8 BI Analysis for Microsoft Excel User Guide. You can download documents created in Microsoft Office Excel, Microsoft Office PowerPoint and Microsoft Office Word. The default action for any Microsoft Office document is to download it. You must have read and traverse permissions to access Microsoft Office documents in IBM Cognos Connection.

344

Chapter 24: Administering Microsoft Office Documents For more information, see "Secured Functions and Features" (p. 221).

Steps
1. In IBM Cognos Connection, locate the document that you want to open. 2. Click more on the actions toolbar to the right of the document that you want to download. The IBM Cognos Connection actions page opens. 3. Download the Microsoft Office document: For a Microsoft Office workbook, click the View most recent document in Excel object . For a Microsoft Office presentation, click the View most recent document in PowerPoint object .

For a Microsoft Office word document, click the View most recent document in Word object .

For a Microsoft Office document of unknown type, click the View most recent document object .

The File Download dialog box appears. 4. Click Open or Save and follow the prompts that appear. When you open the document, it opens in the application that was used to create it. You can now perform the same actions that you would perform for any Microsoft Office document of the selected type.

Administration and Security Guide 345

Chapter 24: Administering Microsoft Office Documents

346

Chapter 25: Reports and Cubes

You can use reports, cubes, and documents to analyze data and help you make informed and timely decisions. In IBM Cognos 8, reports and cubes can be published to the portal to ensure that everyone in your organization has accurate and relevant information when they need it.

Query Studio and Report Studio Reports

Typically, for Query Studio and Report Studio reports, your data modeler creates models (p. 243) from subsets of corporate data. These models are then published as packages in IBM Cognos 8. Query Studio and Report Studio users can create reports based on the packages and publish them in IBM Cognos 8. In IBM Cognos Connection, a Query Studio report is called a query and a Report Studio report is called a report. OLAP sources do not need additional modeling.

Analysis Studio Reports and Cubes

An Analysis Studio administrator can publish Analysis Studio reports and cubes in IBM Cognos 8. Analysis Studio users can create reports and publish them in IBM Cognos 8. In IBM Cognos Connection, an Analysis Studio report is called an analysis.

Working with Reports and Cubes

A report can refer to the specification that defines the information to include in a report, or the results themselves. For Report Studio and Query Studio, report specifications can have saved results or you can run a report to produce new results. For Analysis Studio, reports are always run against the latest data in the cube. After a report is published to the portal, you can view, run, or open it (p. 348) or view report output versions (p. 364). You can also view the report in various formats (p. 357). You can distribute reports by saving them, sending them by email, sending them to your mobile device, printing them, or bursting them (p. 372). You can also set run options for the current run (p. 350), and set advanced run options for the current run (p. 351). You can create an ad hoc report using Query Studio or you can use Report Studio to define layouts, styles, and prompts for your report (p. 353). You can also create Analysis Studio reports (analyses). You can schedule a report to run at a later time or on a recurring basis. You can schedule a report as part of a job or based on a trigger. You can view the run history for a report. For more information, see "View the Run History for Entries" (p. 294). You can also include a report in an agent (p. 383). You can add yourself to the alert list for a report so that you are alerted when new versions of the report are created (p. 366). You can also specify watch rules in saved HTML report output so that you are alerted whenever the events specified by the watch rules are satisfied (p. 366). You can disable selection-based features (p. 371), such as drilling up and down and drill-through.

Administration and Security Guide 347

Chapter 25: Reports and Cubes

Mixed Currencies
Mixed currency values occur when you calculate values with different currencies. When using an OLAP data source, mixed currency values use the asterisk character (*) as the unit of measure.

Accessibility for the Disabled

We are committed to assisting people with disabilities, and promotes initiatives that make workplaces and technologies accessible. IBM Cognos 8 provides an accessible report reading solution. This solution allows disabled users and users of Assistive Technology the ability to access and display reports in Cognos Viewer.

Series 7 Reports and Cubes

For information on working with Series 7 reports and cubes in IBM Cognos 8, see "Series 7 Reports in IBM Cognos Connection" (p. 378).

View, Run, or Open a Report

You can view the most recent run of a report, run a report, or open a report in the authoring tool. The default action is to view the most recent run of a report but you can select the default action that you prefer (p. 348). You must have execute permission to run a report. You must have read and traverse permissions for the folder that contains the report.

Step
In IBM Cognos Connection, click the report that you want. For more information about using PowerPlay Web Explorer, see PowerPlay Web Users Guide. For information about using Analysis Studio, see the Analysis Studio User's Guide.

Set Default Report Options

You can set one of the following actions as the default when a report is run (p. 348): view the most recent report or run if it has not been previously run (default) run the report open the report in the authoring tool that was used to create it (Query Studio, Report Studio, or Analysis Studio)

You can set default report options such as format and language. You can also set the default to prompt for values (p. 362) and run as the owner. For information about properties, see "Entry Properties" (p. 243).

348

Chapter 25: Reports and Cubes You must have execute permissions for the report. You must have read and traverse permissions for the folder that contains the report.

Steps
1. In IBM Cognos Connection, click the set properties button right of the report. on the actions toolbar to the

2. Click the Report tab for a Report Studio report, the Query tab for a Query Studio report, or the Analysis tab for a Analysis Studio report. 3. Under Default action, select the default action for when the report is run. 4. If you want to override report options, under Report options, click the Override the default values check box. You can change some or all of the options, such as format and language. For information about setting advanced PDF options, see "Set Advanced PDF Options for a Report" (p. 358). 5. If you want to prompt for values to filter the data in the report, click select the Prompt for values check box under Prompt Values. Note: You are prompted for values only if the report specification or model includes prompts or if you have access to multiple data source connections or signons. 6. If you want to run the report using the owner credentials, click the check box next to the owner listed under Run as the owner. 7. To set additional report options, click Advanced options. Under Number of rows per Web page in HTML reports, click the number of rows you want to allow. To allow such features as drill up and drill down, drill through, Cognos Search, watch rules, and agent notification when the report is viewed in Cognos Viewer, select Enable selection-based interactivity in HTML reports. If you want to allow the creation of additional output formats so that watch rules can be evaluated and saved output versions can be imported into IBM Cognos 8 Go! Office, select Enable enhanced user features in saved output versions. If you want users to receive alerts when new report output is generated, select Enable alerts about new versions. To create an expiry date for the report cache data, select Day or Month and type a corresponding number under Cache duration. Report cache data is created only if there is no cache data or if the cache data is expired.

8. Click OK.

Administration and Security Guide 349

Chapter 25: Reports and Cubes

Set Report Options for the Current Run

You can set the following options for the current run of a report: report output format (p. 357) language (p. 360) delivery method (p. 372) prompt for values (p. 362)

These options override the defaults for a report for a one-time run. Tip: You can also force database access by clicking More next to the report, and then clicking Clear the cache. You can change default run options for reports (p. 348) If you change the delivery method while a report is running, the run operation is cancelled. The report is run again using the new delivery method that you select. This can be time-consuming for large reports. To save time, specify the delivery method before you run the report. To specify a time for the report to run, to choose additional formats or more than one language, or for additional delivery methods, use advanced run options (p. 351). You must have execute permissions for the report you are attempting to run. You must have read and traverse permissions for the folder that contains the report.

Steps
1. In IBM Cognos Connection, click the run with options button the right of the report you want to run. on the actions toolbar to

2. Under Format, click the format that you want for the report output. 3. Under Language, click the language that you want for the report output. 4. Under Delivery, choose to view the report now, save the report, print the report, or send the report your mobile device. 5. If you choose to print, click Select a printer, click the button next to the printer you want to use, and click OK. If the printer is not listed, you can type the printer information. Tip: If you have administrator privileges and want to set up the printer for future use, click New printer. You must type the network address of the printer by using the format \\server_name\printer_name for a network printer on a Windows installation and printer_name for a UNIX installation or for a local printer. 6. If you want to prompt for values to filter the data in the report, under Prompt Values, click the Prompt for values check box. You are prompted for values only if the report specification or model includes prompts or if you have access to multiple data source connections or signons. 7. Click Run.

350

Chapter 25: Reports and Cubes

Set Advanced Report Options for the Current Run

You can specify the following advanced run options for a report for the current run: time when the report should run multiple report output formats if you choose to run the report later and additional format choices for HTML and PDF (p. 357) one or more languages (p. 360) one or more delivery methods (p. 372) prompt for values (p. 362) burst the report (p. 372)

The report runs in the background if you run the report later, select multiple report formats or languages, select to save, print or email the report, send the report to your mobile device, or burst the report. If you set your preferences to show a summary of the run options (p. 260), the summary appears whenever the report is not run interactively. The report runs in the background. When done, the output versions button appears next to the report on the Actions toolbar. Tip: Click the output versions button to view the selected formats. For more information, see "View Report Output Versions" (p. 364). Default options are set by the report author. You can change default run options for reports "Set Default Report Options" (p. 348). If you choose to save, print, or send the report by email, you can choose multiple formats. If you choose to run the report later, the delivery option is automatically changed to save. For more information on saving report output, see "Save Report Output" (p. 363). You must have execute permissions for the report you are attempting to run. You must have read and traverse permissions for the folder that contains the report. You need the appropriate permissions to set advanced run options.

Steps
1. In IBM Cognos Connection, click the run with options button the right of the report you want to run. 2. Click Advanced options. 3. Under Time and mode, click Run in the background, and then click Now or Later. If you specify Later, set a date and time for the report to run. 4. Under Format, click the formats you want for the report output. The Enable selection-based interactivity check box is selected by default. For information about deselecting this option, see "Disable Selection-based Interactivity" (p. 371). on the actions toolbar to

Administration and Security Guide 351

Chapter 25: Reports and Cubes 5. If you want to select a different or additional languages for the report, under Languages, click Select the languages and use the arrow keys to move the available languages to the Selected languages box and click OK. Tip: To select multiple languages, use the Ctrl key or use the Shift key. 6. Under Delivery, choose the delivery method that you want: If you schedule a report for a future time, select multiple formats or languages, or burst the report. You cannot view the report now. Select one of the other delivery methods. If you choose to print, click Select a printer. Click the button next to the printer you want to use and click OK. Or, if the printer is not listed, you can type the printer information. If you choose to save using report view, you can change the name or destination folder of the report view. Click Edit the save as options, make the changes and click OK. If you choose to email the report, proceed to step 7. Tip: If you have administrator privileges and want to set up the printer for future use, click New printer. You must type the network address of the printer by using the format \\server_name\printer_name for a network printer on a Windows installation and printer_name for a UNIX installation or for a local printer. If you choose to send the report to your mobile device, enter your Mobile device ID.

7. If you select Send the report by email, click Edit the email options and set the following options: To display the blind copy field, click Show Bcc. To choose IBM Cognos 8 recipients, click Select the recipients. Select the check box next to the names you want to include, and click To, Cc (copy), or Bcc (blind copy). The entries that you select are listed under Selected entries. Tip: To select all entries in a list, click the check box in the upper-left corner of the list. To remove names from Selected entries, select the check box next to the name and click Remove. To search, click Search. In the Search string box, type the phrase you want to search for. For advanced search features, click Edit. For more information, see "Search for an Entry" (p. 259). When you are done, click OK. To send the email to other recipients, in the To:, Cc, or Bcc boxes, type the email addresses separated by semicolons (;). Tip: If you logged on, your name automatically appears in the To list box. Under Subject, type the subject of the email. Under Body, type a message to be included in the email. Tip: By default, the body of the email is in HTML format, which provides advanced editing features such as font type and size, text color, text formatting and justification, numbers and bullets, indentation, and tables. To use plain text, click Change to plain text.

352

Chapter 25: Reports and Cubes To include a hyperlink to the report, select the Include a link to the report check box. To include the report as an attachment, select the Attach the report check box. Click OK. You can prevent users from including attachments. For more information, see "Disable Report Attachments in Email Messages" (p. 534). 8. If you want to be prompted for values to filter the data in the report, under Prompt Values, select the Prompt for values check box. If you run the report later, the prompt values you provide are saved and used when the report runs. Note: You are prompted for values only if the report specification or model includes prompts or if you have access to multiple data source connections or signons, even if the Prompt for values check box is selected. 9. Under Bursting, specify whether the report should be bursted. This option is available only if the report author defined burst keys in the report. 10. Click Run.

Create a Report
You can create reports to analyze data and answer specific questions related to your business. Use Query Studio to intuitively explore data by creating ad hoc reports. Report Studio is a comprehensive report authoring environment. Use it to create both highly interactive and sophisticated production reports for mass consumption by specifying queries and layouts for each report. Use Analysis Studio for analyses. Access to the report authoring tools is controlled by the capabilities defined for your logon. If you require access to the report authoring tools but the links are not available on the top navigation bar, contact your system administrator. An existing report may contain most of the information you require, but you may need new prompt values or changes to the layout or style. Instead of creating a new report, you can create a report view to satisfy your requirements (p. 354). For instructions about using the studios, see the following guides: Query Studio User Guide Report Studio Professional Authoring User Guide IBM Cognos Analysis Studio User Guide

Before creating a report, confirm that the package containing the data for your report is available in the portal. If you do not have access to the package, contact your administrator. Tip: A package is identified by the package icon .

Administration and Security Guide 353

Chapter 25: Reports and Cubes You must have write and traverse permissions for the folder in which you want to save the new report.

Steps
1. In IBM Cognos Connection, choose whether you want to create a simple or complex report: To create a simple report, in the upper right corner, click the Query Studio link To create a complex report, in the upper right corner, click the Report Studio link . .

To create an Analysis Studio report, in the upper right corner, click the Analysis Studio link .

2. If the Select Package dialog box appears, do one of the following to select the package containing the data you want to use in your report: In the Recently used packages list, click the package. In the List of all packages list, navigate to the package and click it.

Creating a Query Studio Report Without Using Actual Data

You can create a report without accessing the data that will eventually be used in the report. Query Studios preview mode lets you create or modify reports without retrieving actual data from the database. Instead, simulated data is shown. For more information about preview mode, see the Query Studio User Guide. You can make preview mode the default for Query Studio. For more information, see "Start Query Studio in Preview Mode" (p. 520).

Create a Report View

You can create a report view, which uses the same report specification as the source report, but has different properties such as prompt values (p. 362), schedules, delivery methods, run options, languages (p. 360), and output formats (p. 357). Creating a report view does not change the original report. You can determine the source report for a report view by viewing its properties. The report view properties also provide a link to the properties of the source report. If the source report is moved to another location, the report view link is not broken. If the source report is deleted, the report view icon changes to indicate a broken link link to the source report is removed. , and the properties

If you want to use a generic report as the underlying structure for additional reports, make a copy of the report (p. 251). If you want a report to appear in more than one location, create a shortcut (p. 240).

354

Chapter 25: Reports and Cubes To create a report view, you must have execute or read permissions for the original report.

Steps
1. In IBM Cognos Connection, locate the report you want to use to create the report view. 2. Under Actions, click the report view button 3. In the Name box, type the name of the entry. 4. If you want, in the Description and in the Screen tip box, type a description of the entry. The description appears in the portal when you set your preferences to use the details view (p. 260). The screen tip, which is limited to 100 characters, appears when you pause your pointer over the icon for the entry in the portal. 5. If you do not want to use the target folder shown under Location, click Select another location and select the target folder and click OK. 6. Click Finish. In the portal, report view entries are identified by the report view icon . next to the report.

The report view has the same run options and properties as the original entry. To change the default properties of a report view, see "Set Default Report Options" (p. 348). For information about properties, see "Entry Properties" (p. 243).

View Lineage Information for a Data Item

Lineage information traces the metadata of a data item in an HTML report or a report view back through the package and the data sources used by the package. Lineage also displays any data item filters that were added by the report author, or that were defined in the data model. For example, you can click a cell in a crosstab to see how the cell value was calculated. You can view the data items lineage in the Business View or in the Technical View. The business view shows high-level textual information that describes and explains the data item and the package from which it comes. This information is taken from IBM Cognos Connection and the Framework Manager model. The technical view shows a graphical representation of the lineage of the selected data item. The lineage traces the data item from the package to the data sources used by the package. When you click the item, its properties appear at the bottom of the page. If you click an item in the Package area, you see the items model properties. If you click an item in the Data Sources area, you see the items data source properties. You cannot view lineage information when running a report from a mobile device. IBM Cognos 8 can be configured to use the default lineage solution that comes with the product, or a custom lineage solution. IBM Metadata Workbench is also supported. To access lineage information in a report, an administrator must configure the lineage solution, enable the Lineage capability, and grant read permissions for you on the report.

Administration and Security Guide 355

Chapter 25: Reports and Cubes For more information, see "Configure the Lineage Solution" (p. 151), "Secured Functions and Features" (p. 221), and "Object Capabilities" (p. 229).

Steps
1. Open an HTML report or report view in Cognos Viewer. 2. Right-click the data item you want, and click Lineage. The lineage views appear.

Access the IBM WebSphere Business Glossary

If you already use the IBM WebSphere Business Glossary, you can access the Glossary from Cognos Viewer, and from the metadata tree in Report Studio, Query Studio and Analysis Studio. Before you can access the Glossary, you must have permissions for the Glossary capability, and the Glossary URI must be configured by an administrator. For more information, see "Secured Functions and Features" (p. 221), "Object Capabilities" (p. 229), and "Configure the IBM WebSphere Business Glossary URI" (p. 152).

Steps for Cognos Viewer

1. Open an HTML report or report view in Cognos Viewer. 2. Right-click the data item you want, and click Glossary.

Edit a Report
You can use the IBM Cognos 8 authoring tools to edit an existing report. You may want to change the report layout, style, or font. The report may need to be updated because of changes to the data or to add language support. If the report was created in Report Studio, you can edit the report in Report Studio. If the report was created in Query Studio, you can edit the report in either Query Studio or Report Studio. If you edit a Query Studio report in Report Studio, you cannot go back and edit the report in Query Studio. For more information about modifying reports, see the Report Studio Professional Authoring User Guide, and the Query Studio User Guide. If the report was created in Analysis Studio, you can edit the report in either Analysis Studio or Report Studio. If you edit an Analysis Studio report in Report Studio, you cannot go back and edit the report in Analysis Studio. For more information about modifying Analysis Studio reports, see the Report Studio Professional Authoring User Guide, and the Analysis Studio User Guide. The edit button differs depending on whether the report is a Query Studio report Studio report , or an Analysis Studio report . , a Report

Editing a report modifies the report specification so that everyone who views the report sees the changes you made.

356

Chapter 25: Reports and Cubes Report properties, such as the preferred output format, language, prompt values, or report retention, can be specified by changing the run options in the portal (p. 348). For information about properties, see "Entry Properties" (p. 243). If you want to use a generic report as the underlying structure for additional reports, make a copy of the report (p. 251). If you want a report to appear in more than one location, create a shortcut (p. 240). If you want to keep the underlying report specifications but want the choice of another report format, language, delivery method, or run option, create a report view (p. 354). You must have read and write permissions for the report you are attempting to edit. You must have traverse permissions for the folder containing the report.

Step to Edit a Report in IBM Cognos Connection

In IBM Cognos Connection, click the open button on the Actions menu for the report you want to edit.

The report opens in the authoring tool used to create the report.

Step to Edit a Query Studio Report in Report Studio

Click the More link on the actions toolbar and click Edit with Report Studio

Report Formats
You can choose the output format for a report. You may want to view reports in a browser, or you may want the report in a format that is easily imported into another application. You can choose from the following formats: HTML HTML fragment XHTML XML PDF Excel 2000 Excel 2000 single sheet Excel 2002 Excel 2007 delimited text (CSV) format.

You can specify the default format to be used when a report is run (p. 348). All shortcuts to a report acquire the default format from the source entry. You can specify the report format in the run options page (p. 350), in the report properties (p. 243), or in your preferences (p. 260). When you run a report without specifying run options, the format

Administration and Security Guide 357

Chapter 25: Reports and Cubes specified in the report properties is used. When it is not specified in the report properties, the format specified in your preferences is used. XHTML and some PDF formats are only available when you set advanced run options (p. 351). You can also select multiple formats when you set advanced run options. To specify the report format, you must have read and write permissions for the report and traverse permissions for the folder that contains the report.

HTML Formats
You can select from the following HTML formats: HTML for standard HTML formatting HTML fragment if you must imbed the HTML in an existing Web page XHTML for HTML that is passed through a parser

To select HTML fragment and XMTML or the number of rows per web page, see "Set Advanced Report Options for the Current Run" (p. 351).

XML Format
XML report outputs save the report data in a format that conforms to an internal schema, xmldata.xsd. You can find this schema file in c8_location/bin. This format consists of a dataset element, which contains a metadata element and a data element. The metadata element contains the data item information in item elements. The data element contains all the row and value elements. You can create models from reports and other data that conform to the xmldata.xsd schema. This is useful if you want to use a report as a data source for another report, or if you use a database that cannot be read by Framework Manager. In this case, export the data from the data source to an XML file, in conformance with the xmldata schema, and then open the XML file in Framework Manager. For more information, see the Framework Manager User Guide.

PDF Format
Use the PDF format to view and distribute reports in an online book format. You must have administrator privileges to specify the advanced PDF options. For more information about setting advanced PDF options, see "Set Advanced PDF Options for a Report" (p. 358)

Set Advanced PDF Options for a Report

Using the advanced PDF options, you can control access to the PDF report output and the report contents.

358

Chapter 25: Reports and Cubes You must have administrator privileges to the report to use the advanced options.

Steps
1. In IBM Cognos Connection, click the set properties button on the actions toolbar to the right of the report you want to run. 2. Click the Report tab for a Report Studio report, the Query tab for a Query Studio report, or the Analysis tab for a Analysis Studio report. 3. Click the Override the default values check box. 4. Under PDF options, click Set. 5. In the Set the PDF options page, select the PDF properties you want for the report, and click OK. Here is a list of the properties that are available.

Property
Orientation

Goal
Whether to have portrait or landscape for the report orientation. Set the paper size, such as legal or letter size. Set the password to open the report.

Paper size Requires a password to open the report Requires a password to access options

Set the password to access report options, and then specify the options you want to make available to users, such as whether to allow printing, modifying the report contents, and copying text.

When you run the report, the PDF settings are applied. For example, if you specified a password to open the report, then users must enter the password before viewing the contents of the report.

Excel Formats
The Excel 2000 format can be viewed with versions of Excel 2000 and later. It supports up to 65,536 rows and multiple sheets. The Excel 2000 format is only available in IBM Cognos 8 when IBM Cognos Application Firewall validation is disabled. Excel 2000 single sheet format offers improved security. Excel 2000 may have cookies in the URLs to spreadsheets, which could be used to illegally impersonate a user. Excel 2000 single sheet format does not use outgoing URLs. However, there is a limit of 65,536 rows, and page breaks for multipleauthor pages are ignored. Excel 2002 format and Excel 2000 single sheet format also offer the following benefits: Both work with SSL protocol. Both work with a single signon.

Administration and Security Guide 359

Chapter 25: Reports and Cubes Secure reports can be accessed without subsequent signons because the system automatically identifies users and provides security information. Both work with Netscape 7.01. Spreadsheets are contained in a single file for reliable spreadsheet navigation.

The IBM Cognos 8 full date format does not always appear correctly in Microsoft Excel 2000 if it is on a system with a regional setting other than English. This does not occur with Microsoft Excel 2002 or 2003 versions. To fix this, reapply the proper format in Excel. Excel 2007 format renders report output in native Excel XML format, also known as XLSX, that provides a fast way to deliver native Excel spreadsheets to Microsoft Excel 2002, Microsoft Excel 2003, and Microsoft Excel 2007. Users of Microsoft Excel 2002 and Microsoft Excel 2003 must install the Microsoft Office Compatibility Pack, which provides file open and save capabilities for the new format. The output is similar to other Excel formats, with the following exceptions: Charts are rendered as static images. Row height can change in the rendered report to achieve greater fidelity.

CSV Format
Reports saved in delimited text (CSV) format open in the application associated with the.csv file type, usually Microsoft Excel, Microsoft Windows Wordpad, or Star Office. Reports saved in CSV format are designed to support Unicode data across many client operating systems are UTF-16 Little Endian data-encoded include a BOM (Byte Order Mark) at the beginning of the file are tab-delimited do not enclose strings in quotation marks use a new line character to delimit rows show only the results of a report query. Page layout items, such as titles, images, and paramDisplay values do not appear in the CSV output.

You can modify the CSV output format to suit your environment. For more information about customizing the functionality of IBM Cognos 8, see "Modify Properties for the CSV Output Format" (p. 526).

Report Languages
You can choose the languages for a report. You can specify the report language on the run options page (p. 350), in the report properties (p. 243), or in your preferences (p. 260). When you run a report, the language specified in the report properties is used. When it is not specified in the report properties, the language in your preferences is used.

360

Chapter 25: Reports and Cubes You can run a report using the default language (p. 348), select a different language for a single run of the report (p. 350), or select more than one language for a report (p. 351). You can add multilingual properties for each of the entries in the portal (p. 361). You can specify the default language to be used when a report is run (p. 348). Selecting a language for your report does not change the language used in the portal. You can change the language used in the portal interface by personalizing the portal (p. 260). All shortcuts to a report acquire the default language from the source entry. To specify the report language, you must have read and write permissions for the report and traverse permissions for the folder that contains the report (p. 213). The package used to create the report must contain multilingual data before the report outputs are shown in the selected languages (p. 243).

Report Languages When Using an SAP BW Data Source

When a report runs, the report server connects to the underlying data source to obtain data. When using an SAP BW data source, if the SAP BW server does not support the language associated with your content locale, IBM Cognos 8 checks a locale map for a corresponding locale. If the SAP BW server supports the language for the corresponding locale, this language is used. Otherwise, the report runs using the default language installed on the SAP BW server.

Add Multilingual Properties

You can set multilingual properties for each of the entries in the portal. You can add a name, screen tip, and description for each of the locales defined by your administrator. A locale specifies linguistic information and cultural conventions for character type, collation, format of date and time, currency unit, and messages. If the entry has multilingual properties defined for the selected language, the entry shows the properties. If the entry does not have multilingual properties defined, they are empty. For information about changing the language to be used by the portal, see "Personalize the Portal" (p. 260).

Steps
1. In IBM Cognos Connection, click the set properties button change. 2. Click the General tab. 3. Under Language, select a language from the list. Languages that already have multilingual properties defined appear at the top of the list above a separator line. 4. If you want, type a description in the Name, Description, and Screen tip box. The name appears in the list of portal entries. The description appears when you set your preferences to use the details view (p. 260). The screen tip, which is limited to 100 characters, appears when you pause your pointer over the icon for the entry in the portal. next to the entry you want to

Administration and Security Guide 361

Chapter 25: Reports and Cubes Tip: To remove multilingual properties for a language, select the language in the list and click Remove values for this language. 5. Click OK.

Specify the Default Language for a Report

To specify the default language for a report, change the report properties.

Steps
1. In IBM Cognos Connection, click the set properties button to change. next to the report you want

2. On the Report options tab, under Language, select the default language from the list box and click OK.

Specify the Default Prompt Values for a Report

You can use prompt values to specify the range of data included in a report when it is run. For example, you can specify a date range that is a subset of the dates available in the report. You may be prompted for values if the report author defines prompts in the report or if there is more than one connection or signon. For information about adding prompts to reports, see the Report Studio Professional Authoring User Guide, the Query Studio User Guide, or the Analysis Studio User Guide. If you are the report author, you can create default prompt values for a report. When the report is run, the data is automatically filtered based on the prompt values that you specify. The user does not have to specify prompt values when the report is run. You may find this useful if most users use the same prompt values each time they run a report. If you have write access to a report and change the prompt values, those values are saved for everyone running the report after you. If you consistently use prompt values that differ from the majority of users, create a report view of the report (p. 354) in your personal folders. By default, you are prompted for values each time the report runs. You can change this in the report properties (p. 243) or when you set run options for a report (p. 350). To set default prompt values, you must have read and write permissions for the report and read or traverse permissions for the folder that contains the report.

Steps
1. In IBM Cognos Connection, click the set properties button to change. next to the report you want

2. On the Report tab for Report Studio reports, the Query tab for Query Studio reports, or the Analysis tab for Analysis Studio reports, under Prompt values, click either Set or Edit. If the report does not have saved prompt values, the run options show No values saved and clicking Set results in a message indicating that the report does not contain prompts. 362

Chapter 25: Reports and Cubes 3. Select the default value for the prompts and click OK. 4. If you want to be prompted each time the report is run, select the Prompt for values check box. If the check box is selected, you will be prompted for values if the report contains prompts or if you have access to multiple data source connections or signons. If the check box is not selected and the report is run interactively, you will be prompted only if there are missing values or if you have access to more than one connection or signon. The report will have missing values if saved prompts or default prompts were specified for the report. If the check box is not selected and the report is run in the background, the report fails if prompt values are missing. 5. Click OK.

Save Report Output

All report output is stored automatically in IBM Cognos 8. You may also be able to save copies of reports in other file locations: in IBM Cognos 8 so that it can be used again and for archive purposes outside of IBM Cognos 8 for use in external applications such as web sites and for use by people who dont have access to IBM Cognos 8

You select how to save report copies as a delivery option. You can also choose how to save a report when you schedule it (p. 299). Before you can save report output to file locations, your administrator must set up the locations. For more information about setting up file locations, see "Saved Report Output" (p. 148).

Steps
1. In IBM Cognos Connection, click the run with options button the right of the report you want to run. 2. Click Advanced options. 3. Under Time and mode, click Run in the background, and then click Now or Later. 4. Under Delivery, choose where you want to save your report: To save a copy in IBM Cognos 8, click Save. Then, click Save the report or Save the report as report view. If you choose to save as report view, you can a change the name or destination folder of the report view. Click Edit the options, make the changes and click OK. To save a copy outside IBM Cognos 8, click Save to the file system. To change the report name, click Edit the options. You can also change how file conflict is resolved. Click Keep existing files to not overwrite existing files, Replace existing files to simply overwrite existing files. Click Make the file names unique and append a timestamp or Make the file on the actions toolbar to

Administration and Security Guide 363

Chapter 25: Reports and Cubes names unique and append a sequence number to avoid overwriting existing files by making new files with unique timestamps or sequence numbers and click OK. 5. If more than one file location is defined, select the location where you want to save from the Location list. 6. Click Run.

View Report Output Versions

Reports are run directly against the data source so that they reflect the latest data. However, viewing the most recent data may not always meet your needs. You may want to view older data. For example, you may want to compare monthly sales volume for a product before and after new features are added. The report output is saved when a report runs in the background. A report cannot be viewed at the time it is run when it runs later has multiple formats or languages has a delivery method of save, print, or email is a burst report

Report output versions are listed by report format (p. 357). By default, the list contains report output versions for the language that is defined in your content locale. If no reports versions are found for that language, report formats for all languages are shown. If burst keys are used, they appear next to the report format sorted by burst key and then by language. You can specify how long you want to keep report output (p. 365).

Steps
1. In IBM Cognos Connection, click the view report output versions button that has multiple output versions. 2. Choose the output version that you want to view: To show report formats in a specific language or all languages, click Languages and select from the list. To show a different output version, select the version from the Versions list. To show the current version, click the report format. next to a report

Tip: To delete a version that you have write access to, click Manage versions, select the versions that you want to delete, click Delete and then click the close button to return to the review report output versions page. 3. If you want to download a report output version, click the download icon in the Actions column. 364

Chapter 25: Reports and Cubes You control the report output formats that are available for download. For more information, see "Customize Report Output Formats in IBM Cognos Connection and Cognos Viewer" (p. 517).

Specify How Long to Keep Report Output

You can keep report output for a specific number of runs or for a specific number of days or months. For example, you can keep the report output for the ten latest occurrences or you can keep the report output for the 2 days or 6 months. You can also choose to keep all report output. You must have read and write permissions for the entry and read or traverse permissions for the folder that contains the entry.

Steps
1. Click the set properties button next to the entry you want.

2. On the General tab, under Run history, choose the retention method and type the value: To keep report output for a specific number of occurrences, click Number of occurrences and type the number. To save an unlimited number of report outputs, set this value to 0. To keep report output for a specific length of time, click Duration and click either Days or Months. Type the appropriate value in the box. 3. Click OK.

Enable an Alert List for a Report

Granting permission for an alert list lets the report user decide whether to be alerted when new versions of the report output become available. Whenever the report is run and report output is saved, the report user is alerted by email as a Bcc recipient. The email contains a link to the latest report output. The permission to enable an alert list for a report does not extend to a report view associated with the report. You must grant permission for the report view independently. The alert list is independent of any distribution lists associated with the report (p. 374). To grant permission for an alert list, you must have write permission.

Steps
1. In IBM Cognos Connection, click the set properties button next to the report for which you want to enable an alert list. 2. On the Report tab for Report Studio reports, the Query tab for Query Studio reports, or the Analysis tab for Analysis Studio reports, click Advanced options, and then click the Enable alerts about new versions check box. 3. Click OK. Users can now add their names to the alert list for notifications of the report outputs.

Administration and Security Guide 365

Chapter 25: Reports and Cubes

Add Yourself to or Remove Yourself from the Alert List for a Report
By adding yourself to the alert list for a report, you receive an email notification when new versions of the report output are saved. In this way, you can monitor changes in the output of reports that are of interest to you. In the email, you are included as a Bcc recipient. The email contains a link to the latest report output. Being on the alert list is independent of any distribution lists associated with the report (p. 374). You can view and manage the alert list for a report as a watch item. You can add yourself only once to the alert list for a report. Before you can add yourself to an alert list for a report, the report owner must enable the alert list. To receive alerts, you must have an email address defined in the My Preferences, Personal tab or in your LDAP security profile (used only in special circumstances).

Steps in IBM Cognos Connection

1. In the portal, locate the report. 2. In the Actions column, click More. 3. In the Perform an action page, click Alert me about new versions or Do not alert me about new versions. 4. Click OK. In the My Watch Items area of the portal, note the change in the watch list.

Steps in Cognos Viewer

1. Open the saved report output. 2. On the toolbar, under Watch New Versions, click Alert Me About New Versions or Do Not Alert Me About New Versions.

Steps to Remove Yourself from Multiple Alert Lists

1. In IBM Cognos Connection, click My area, My Watch Items. 2. On the Alerts tab, select the alerts to delete from the list of alerts. 3. Click Remove me from the alert list.

Watch Rules in Saved Reports

Watch rules are defined in Cognos Viewer by report users so that they can monitor events of interest to them in saved reports. Creating watch rules does not require access to Event Studio. Tip: Users can view and edit watch rules in a single location from the My Watch Items area in IBM Cognos Connection.

366

Chapter 25: Reports and Cubes Watch rules are based on event conditions that are evaluated when the report is saved, not when the report runs interactively. When the event condition is satisfied, the report user is alerted by email or news item. The event conditions are created using a numeric measure and can be specified only in saved HTML reports. You can define an unlimited number of conditions for a report. The locale for the conditional report output is the same as the locale for the report that contains the event condition. Before a user can create watch rules and receive alerts, the report owner must enable watch rules for the report (p. 367). To create watch rules, the report user must have read and traverse permissions to the report output.

Enable Watch Rules for a Report

Enabling watch rules lets the report user specify conditions in saved HTML report output and receive alerts based on these conditions. Whenever the report is run and report output is saved and the conditions are satisfied, the report user is alerted by email or news item. For information about creating a watch rule, see "Create a Watch Rule for a Report" (p. 367). To allow watch rules for a report, you must have write permission for the report.

Steps
1. In IBM Cognos Connection, click the set properties button next to the report. 2. On the Report tab for Report Studio reports, the Query tab for Query Studio reports, or the Analysis tab for Analysis Studio reports, under Advanced options, select the Enable selectionbased interactivity in HTML reports and Enable enhanced user features in saved output versions check boxes. Selecting these options specifies that additional context information is saved with the report output. 3. Click OK. After selecting the advanced options, you must run the report and save the report output in HTML format before users can create watch rules.

Create a Watch Rule for a Report

Use watch rules to monitor user-defined events in saved HTML reports. When the report is saved and the watch rule is satisfied, you are alerted by email or news item. You can view or edit the watch rules you create for reports by using the My Watch Items area of the portal. For more information, see "My Watch Items" (p. 263). Watch rules can be created only in saved HTML reports. For example, you cannot create watch rules in PDF report output.

Administration and Security Guide 367

Chapter 25: Reports and Cubes You must have read and traverse permissions to the report output.

Steps
1. In the IBM Cognos Connection portal, go to the saved HTML report and open it in Cognos Viewer. 2. In the report, click a numeric data item, right-click, and then click Alert Using New Watch Rule. 3. In the Specify the rule - Alert Using New Watch Rule page, in the conditional expression that appears, click the down arrow, click the expression you want for the watch rule, for example, >= (greater than or equal), and specify a value in the box. 4. Under For the selected context, click the report items to which the rule applies. 5. Click Next. 6. In the Specify the alert type page, specify how you want to be alerted when the rule is satisfied: To be alerted by email, select the Send the report by email check box. If you want to change the email options, click Edit the options. To be alerted by news item, select the Publish a news item check box. If you want to change the news item options, click Edit the options. 7. Click Next. 8. In the Specify a name and description - Alert Using New Watch Rule page, specify a name, description, and location for the watch rule. You can organize watch rules in folders on the Rules tab of the My Watch Items area of the portal. 9. Click Finish.

Modify or Delete a Watch Rule in Cognos Viewer

Watch rules you create in saved HTML reports can be edited and deleted in Cognos Viewer. For information about creating a watch rule, see "Create a Watch Rule for a Report" (p. 367). You can also delete and edit watch rules from the My Watch Items area of the portal. For more information, see "My Watch Items" (p. 263). To modify or delete a watch rule, you must have write access to the rule.

Steps
1. Open the saved report output in Cognos Viewer. 2. On the toolbar, click Watch New Versions and, while hovering over the watch rule, from the submenu, click Modify to edit the watch rule. The Set properties dialog box appears. Proceed to step 3.

368

Chapter 25: Reports and Cubes click Delete to delete the watch rule.

3. Click the General tab to change properties, such as the language, name, and description of the watch rule. 4. Click the Rules tab to edit the rules properties, such as the conditional expression for the rule, the items to which the rule applies, and the alert type. Note that the changes you make to a watch rule in Cognos Viewer are made also in the My Watch Items area of the portal.

Comments in Saved Reports

Report users can add comments to saved reports using Cognos Viewer. Comments can be added to HTML, PDF and XML reports, but not Excel or CSV reports. Comments are added to a specific version of a report and are deleted with that report version. The comments are not available in other versions of a report, unless they are manually added by a report user. Comments are included when a report is viewed online or when a burst report is distributed via the portal, but they are not included in printed or emailed reports. Before a user can add comments, the report owner must enable comments in saved output versions. To add comments, a report user must have read permission to the report output. These comments are visible to all other users who have read permission to the report output. However, only the comment owner, or an administrator, can modify or delete comments.

Enable Comments in Saved Output Versions

Enabling comments lets a report user add comments to saved HTML, PDF or XML reports. For information about adding comments, see "Add Comments to a Report Version in Cognos Viewer" (p. 370). To enable comments for a report, you must have write permission for the report.

Steps
1. In IBM Cognos Connection, click the set properties button next to the report.

2. On the Report tab for Report Studio reports, the Query tab for Query Studio reports, or the Analysis tab for Analysis Studio reports, under Advanced options, select the Enable comments in saved output versions check box. 3. Click OK. You must now run the report and save the report output in HTML, PDF or XML format before users can add comments to it.

Administration and Security Guide 369

Chapter 25: Reports and Cubes

Add Comments to a Report Version in Cognos Viewer

Use comments to add simple, unformatted text notes to saved reports. You can add multiple comments to a report. Comments can be added to HTML, PDF and XML reports only. You cannot add comments to other report formats. You must have read permission to the report output to add comments to it.

Steps
1. Open the saved report output in Cognos Viewer. 2. On the toolbar, click Add Comments and then click Add a Comment. 3. In the Add a Comment window, type the comment name and description. 4. Repeat steps 2 to 3 to add further comments as required. 5. Click Finish to save the comment. Each comment is added to a drop-down list available from the Add Comments button.

View, Modify or Delete Comments in Cognos Viewer

Comments added by a report user can be viewed by all other users who have read permission to the report output. Only the comment owner, or an administrator, can modify and delete comments. Tip: You can use the Search feature to find specific comments. For more information, see "Search for an Entry" (p. 259). For information about adding comments, see "Add Comments to a Report Version in Cognos Viewer" (p. 370).

Steps to View Comments

1. Open the saved report output in Cognos Viewer. 2. On the toolbar, click Add Comments and then select the required comment from the list of comments available. A summary of the comment appears, which includes the comment name and description, the date it was last modified, and the owner. 3. To view the full details of the selected comment, click View. The View Comment window appears. 4. Click Finish.

Steps to Modify Comments

1. Open the saved report output in Cognos Viewer. 2. On the toolbar, click Add Comments, select the required comment from the list of comments available, and then click Modify to edit the comment.

370

Chapter 25: Reports and Cubes The Modify Comments window appears. 3. Edit the comment name or description. 4. Click Finish.

Steps to Delete Comments

1. Open the saved report output in Cognos Viewer. 2. On the toolbar, click Add Comments, select the required comment from the list of comments available, and then click Delete. 3. Click OK to confirm that you want to delete the comment.

Disable Selection-based Interactivity

You can disable selection-based interactivity for an HTML report that is viewed in Cognos Viewer to shorten the time that it takes the report to run. After you disable this functionality, you cannot: drill up and down in a report drill through to other reports use Cognos Search use conditional report delivery use agent notification

If selection-based interactivity is enabled in IBM Cognos Connection, a user can perform drill up and down and drill-through actions in Report Viewer or Query Studio. If selection-based interactivity is disabled in IBM Cognos Connection, the ability to perform drill up and down and drill-through are disabled regardless of how the drill through definitions and settings are authored in Report Studio and IBM Cognos Connection. Selection-based interactivity is enabled by default. Tip: You can instead enable or disable selection-based interactivity for the current run only. Click Run with options next to the report and then click Advanced options. Click Enable selectionbased interactivity in HTML reports.

Steps
1. In IBM Cognos Connection, click the set properties button right of the report. on the actions toolbar to the

2. Click the Report tab for a Report Studio report, the Query tab for a Query Studio report, or the Analysis tab for an Analysis Studio report. Tip: Disabling selection-based interactivity on an Analysis Studio report has no effect. 3. Click Advanced options.

Administration and Security Guide 371

Chapter 25: Reports and Cubes 4. Clear the Enable selection-based interactivity in HTML reports check box. Note that disabling selection-based interactivity on an Analysis Studio report has not effect.

Exclude Blank Pages in PDF Reports

When you generate a PDF report, all pages, including blank pages are included. You can specify that PDF reports do not include blank pages. This applies to all PDF reports. You must be a server administrator to exclude blank pages.

Steps
1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Dispatchers and Services. 3. Click the dispatcher you want. 4. For the ReportService, in the Actions column, click the set properties button. 5. Click the Settings tab. 6. For the Environment category, next to Advanced settings, click the Edit link. 7. Select the Override the settings acquired from the parent entry check box. 8. In the Parameter column, type rsvp.removeblankpages. 9. In the Value column, type true. 10. Click OK.

Distributing Reports
You can distribute reports to other users to share information with them. In IBM Cognos 8, you can distribute reports by saving them (p. 373) where other IBM Cognos 8 users can access the reports at their convenience sending them to users by email (p. 373) printing them (p. 373) bursting them (p. 374)

You can schedule the distribution of your reports so that recipients receive the reports regularly (p. 299). Recipients must have read permissions for the report and traverse permissions for the folder that contains the report. When you attach a report to an email, the report is no longer secured by the IBM Cognos security system.

372

Chapter 25: Reports and Cubes When sending a report by email, note that if you choose the recipient from a list, such as a group, role, or distribution list, you must have read access to both the list and the recipients email account. Otherwise, the report delivery fails. However, if you type the email address manually, read access is not required. To distribute reports to more than one recipient, you can create distribution lists (p. 374), which contain references to users, groups, and roles. If a recipient is not part of the IBM Cognos security system, you can create a contact (p. 374) for that person and add it to a distribution list.

Saving a Report
You can share a report with others by saving the report in a location that is accessible to other users, such as in the public folders. Public folders typically contain reports that are of interest to many users. You can save a report when you set options for the current run (p. 350) or you can use advanced report options (p. 351) to save a report in Report View (p. 354). To share a report that is currently located in your personal folders, copy the report (p. 251), move the report (p. 252), or create a shortcut to the report (p. 240) and save it in the public folders. For information about saving reports, see Query Studio User Guide, the Report Studio Professional Authoring User Guide, or the Analysis Studio User Guide.

Sending a Report by Email

You can share a report with others by sending the report by email. This is especially useful if you want to share the report with a group of people who do not have access to the portal. To send a report by email, you must have Directory Administrator privileges. You can attach reports to email (p. 351). You can also include a URL to the report in an email. Entries that are sent as attachments to emails are no longer secured by the IBM Cognos security system. You can disable the use of email attachments. For more information, see "Disable Report Attachments in Email Messages" (p. 534). To send a report to others by email, both you and the email recipients must have valid email addresses. Also, if you choose the recipient from a list, such as a group, role, or distribution list, you must have read access to both the list and the recipients email account. Otherwise, the report delivery fails. However, if you type the email address manually, read access is not required.

Sending a Report to your Mobile Device

You can choose to send a report to your mobile device. You must have Cognos 8 Go! Mobile installed.

Printing a Report
It may be convenient for you to have a printed copy of a report. You may need to review a report when your computer is not available, or you may need to take a copy of a report to a meeting. You can use run options to print a report and choose a printer (p. 351).

Administration and Security Guide 373

Chapter 25: Reports and Cubes You can set up printers for users to select from. For more information, see "Set Up Printers" (p. 48).

Distributing a Report by Bursting

Bursting is the process of running a report once and then sending the results to recipients, each of whom sees only a subset of the data. Distribute reports by bursting them when you want users to receive or view reports that contain data applicable only to them. If you distribute burst reports by email, the recipients are specified by the burst options. Note that if you choose the recipient from a list, such as a group, role, or distribution list, you must have read access to both the list and the recipients email account. Otherwise, the report delivery fails. If the burst report contains a drill-through link to another report and the burst report is distributed by email, set the email options to include a link to the report. Otherwise, if you include the report in the email, the drill-through links in the burst report will not work. You can burst reports only if the report author defined burst options for the report. You can use advanced run options (p. 351) to distribute a report by bursting. You must have read and write permissions for the report to enable bursting.

Create Distribution Lists and Contacts

Use distribution lists if you want to send a report to more than one recipient at a time. Distribution lists contain a collection of users, groups, roles, contacts, or other distribution lists. If a recipient is not part of the IBM Cognos security system, you can create a contact for this person. The contacts you create can also be assigned as contacts for reports. Note that if you choose the email recipient from a list, such as a group, role, or distribution list, you must have read access to both the list and the recipients email account. Otherwise, the report delivery fails. To access the directory administration tool, you must have execute permissions for the directory secured feature and traverse permission for the Administration secured function.

Steps for a Distribution List

1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Distribution Lists and Contacts. 3. Click the Cognos namespace. 4. On the toolbar, click the new distribution list button .

Tip: To remove a distribution list, select the entry and click the delete button. 5. Type a name and, if you want, a description and screen tip for the distribution list, and click Next. 6. If you want to add to the distribution list, click Add and choose how to select entries:

374

Chapter 25: Reports and Cubes To choose from listed entries, click the appropriate namespace, and then select the check boxes next to the users, groups, or roles. To search for entries, click Search and in the Search string box, type the phrase you want to search for. For search options, click Edit. Find and click the entry you want. To type the name of entries you want to add, click Type and type the names of groups, roles, or users using the following format, where a semicolon (;) separates each entry: namespace/group_name;namespace/role_name;namespace/user_name; Here is an example: Cognos/Authors;LDAP/scarter; 7. Click the right-arrow button and when the entries you want appear in the Selected entries box, click OK. Tips: To remove entries from the Selected entries list, select them and click Remove. To select all entries in a list, click the check box in the upper-left corner of the list. To make the user entries visible, click Show users in the list. 8. Click Finish. You can now choose this list when you specify recipients for a report.

Steps for a Contact

1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Distribution Lists and Contacts. 3. Click the Cognos namespace. 4. On the toolbar, click the new contact button .

Tip: To remove a contact, select the entry and click the delete button. 5. Type a name and email address for the contact and, if you want, a description and screen tip, and click Finish.

Drilling to View Related Data

Reports that you run in IBM Cognos Connection and view in Cognos Viewer support various drill operations so that you can view different layers of related data. You can perform drill operations in lists, crosstabs, and charts. You can drill up or drill down within the same report drill through to another target drill through to another target passing multiple values

Administration and Security Guide 375

Chapter 25: Reports and Cubes

Drill Up or Drill Down

You can drill up and drill down within a report that is run from IBM Cognos Connection. Reports run from IBM Cognos Connection appear in Cognos Viewer. In lists and crosstabs, hyperlinks identify drillable items. In charts, the pointer changes to a hand when you pause the pointer over a drillable item, and a tooltip indicates what you are drilling on. For example, a column chart shows revenue by product line by year. You can drill on a single axis, such as product line or year. You can also drill on both axes, such as Camping Equipment and 2005. In this case, you are drilling on the intersection of Camping Equipment and 2005. If groups of data items from different queries are linked, when you drill up or drill down in one query, the data item also drills up or drills down in the linked queries. For more information about how to link groups of data items, see the Report Studio Professional Authoring User Guide. After you drill up or drill down, you can save the report as a report view for later viewing. For more information, see "Create a Report View" (p. 354). The drill-up and drill-down functionality is available only when you use dimensionally structured data and view the report in HTML format. You can drill only on members in a level. By default, the drill-up and drill-down functionality is enabled.

Steps
1. Run the report in IBM Cognos Connection and view it in Cognos Viewer. Tip: Alternatively, you can open an Analysis Studio report or Query Studio report in their respective studios. 2. Right-click the report item you want to drill on and click Drill Up or Drill Down .

Drill Through to Another Target

You can navigate from a report to one of the following targets: a Query Studio report a Report Studio report an Analysis Studio analysis a PowerPlay Studio report a package that contains a PowerCube a Microsoft SQL Server Analysis Services (SSAS) action

You can also navigate from a report or analysis authored in one package to more detailed information in a report which was authored in another package. For example, this is useful when you want to drill from a summarized OLAP source, such as your sales information, into the detailed relational or transactional information, such as your inventory volumes. Drilling through from one report to another is a method of passing information from the source (your starting report) to the target (your ending report). For example, you may be evaluating a

376

Chapter 25: Reports and Cubes report and discover something you need to investigate in a certain product line. You can drill through to the detailed target report which provides a focused view of that product line. When drilling through to the target, the product line you selected in the source is passed and the target report is run with that filter, making a more focused report. By default, the ability to drill through from one report to another is enabled. You can disable it by using the Enable selection-based interactivity option. For more information, see "Disable Selectionbased Interactivity" (p. 371). For information about drill-through concepts and setting up drill-through access, see "Drill-through Access" (p. 401). Before you can navigate to another target, a drill-through definition must be created in either the Report Studio source report or in IBM Cognos Connection.

Steps
1. Run the report in IBM Cognos Connection and view it in Cognos Viewer. Tip: Alternatively, you can open an Analysis Studio report or Query Studio report in their respective studios. 2. Right-click the report item from which you want to navigate and click Go To Links. The Go To page appears, showing the available targets. Note: If there is only one possible target for the column, the reports runs and appears in Cognos Viewer. 3. Click the target you want to navigate to. Depending on how the drill-through definition was set up and the report type, the target opens in either Cognos Viewer, Query Studio, PowerPlay Studio, or Analysis Studio. , Related

Drill Through to Another Target Passing Multiple Values

You can have a report that contains a drill-through definition that can be filtered by multiple values in a single query item. For example, while analyzing an OLAP source, you may want to focus on Canada and the United Kingdom. When you drill through, the target report is filtered by both countries. After you run the report in Cognos Viewer, you are prompted to choose values when you navigate from the report to the drill-through target. The values you specify are used to filter the results in the target. For more information about drilling through to a target, see "Drill Through to Another Target" (p. 376). Drilling through using multiple values is available regardless of whether the drill-through definition is authored in the Report Studio source report or in IBM Cognos Connection, Drill-through Definitions. In previous releases, this functionality was available only when the definition was authored in IBM Cognos Connection.

Steps
1. Run the report in IBM Cognos Connection and view it in Cognos Viewer.

Administration and Security Guide 377

Chapter 25: Reports and Cubes Tip: Alternatively, you can open an Analysis Studio, Query Studio, or PowerPlay Studio report in their respective studios. 2. Ctrl+click to select more than one value in a column. If hyperlinks appear in the column in which you are attempting to select cells, click in the empty area around the hyperlinks. If there are no visible hyperlinks but you know that a drill-through target exists, select the cells you want to use as the filter, regardless of whether they are in the same column. Note that when you select multiple values from different columns, the resulting filter in the target report performs an and rather than an or operation with the values passed, for example, Canada and Camping Equipment; United Kingdom and Fax.

3. Right-click in one of the selected cells from which you want to navigate, and from the menu that appears, do one of the following: Under Go To, click the drill-through target name, if one exists. Under Go To, click Related Links. On the Go To page, click the target report you want to run.

The target report runs and if it can be filtered by the selection made in the source report, the target is filtered by those values.

Data Sources With Named Sets May Produce Unpredictable Results

If your dimensional data sources include named sets, which are sets of members or set expressions that are created for reuse, the data results are unpredictable in Query Studio when combined with filtering and level nesting. Additionally, if your data sources include multi-level named sets, the data results are unpredictable in Analysis Studio when aggregated. We therefore recommend that you avoid exposing named sets or multi-level named sets to Query Studio and Analysis Studio users. Working with named sets may also cause unpredictable results in Report Studio. For more information, see the Report Studio Professional Authoring User Guide

Series 7 Reports in IBM Cognos Connection

If your administrator configures IBM Cognos 8 to use the IBM Cognos Series 7 namespace, you can see Series 7 entries in IBM Cognos Connection. When you run a Series 7 report, the report runs in the Series 7 application used to create it. The contents of the Series 7 NewsIndex appears at the bottom of the page in Public Folders. The contents of your Series 7 personal NewsBox appears at the bottom of the page in My Folders.

378

Chapter 25: Reports and Cubes Alternatively, PowerPlay 7.3 can be configured to use IBM Cognos Connection rather than Upfront as a portal. However, if you are accessing content from other IBM Cognos applications or versions previous to PowerPlay 7.3, the administrator may still depend on the Upfront portal. When you access Series 7 entries from IBM Cognos Connection, consider the following things: If the Series 7 namespace and the IBM Cognos 8 namespace are different, you must log on to both. Otherwise, you cannot see content in both areas. If you log off when you are in Upfront, you can no longer access Series 7 entries in IBM Cognos Connection. You should always log off in IBM Cognos Connection. If you belong to several Series 7 user classes, you are unable to select a different user class when you access Upfront through IBM Cognos Connection. If you use an Upfront theme other than standard70, an error message may appear when you click the More link in the Actions column. You cannot access Series 7 entries. If you want to cut, copy, and paste Series 7 entries, use the More link in the Actions column, and then use the Upfront toolbar. If you perform a search in IBM Cognos Connection, the Series 7 entries are not included in the search. You cannot combine IBM Cognos 8 entries and Series 7 entries in a single folder or NewsBox.

For information about working with Series 7 entries in Upfront, see the IBM Cognos Series 7 Web Portal User Guide.

Series 7 PowerPlay Reports and Cubes

After Series 7 PowerPlay reports and cubes are published to the IBM Cognos 8 portal, you can use PowerPlay authoring tools to create and edit Series 7 PowerPlay reports. For more information about PowerPlay authoring tools, see the PowerPlay Web Users Guide. You can change the default run options of Series 7 PowerPlay reports and cubes (p. 381) and select multilingual properties (p. 382). Series 7 PowerPlay reports and cubes function differently from other reports. The following actions do not apply to Series 7 PowerPlay reports and cubes: viewing the run history and report output versions specifying how long to keep report outputs and histories canceling and suspending reports specifying prompt values for report formats other than PDF specifying language for the content of reports running a report as the owner scheduling reports distributing reports

Administration and Security Guide 379

Chapter 25: Reports and Cubes

Single Signon
Single signon ensures that users who are logged on to one IBM Cognos application are not prompted for authentication when they run another IBM Cognos application. You can ensure that your users benefit from single signon by ensuring that both IBM Cognos 8 and PowerPlay use the same Series 7 namespace as their authentication source. Alternatively, you can ensure that the authentication namespaces used for both IBM Cognos 8 and PowerPlay are configured to use an external single signon mechanism for authentication, such as operating system signons for Series 7 PowerPlay or LDAP provider with External Identity Mapping in ReportNet. For instructions about setting up Series 7 single signon, see the Access Manager Administrator Guide. For instructions about setting up single signon for ReportNet, see the Installation and Configuration Guide.

Run or Open a Series 7 PowerPlay Report

You can run Series 7 PowerPlay reports in the following formats (p. 357): If the HTML icon If the PDF icon is visible, the report opens in PowerPlay Web Explorer. is visible, the report runs in the PowerPlay Web Viewer.

PowerPlay administrators can restrict who can open cubes. For information about publishing Series 7 PowerPlay reports and cubes in IBM Cognos 8, see the PowerPlay Enterprise Server Guide. If you use secured Series 7 cubes, the namespace against which the cubes are secured must be configured as an authentication source in IBM Cognos 8. This namespace need not be the only authentication namespace or the primary logon for the user. For more information about configuring authentication namespaces see the Installation and Configuration Guide. Before you can run or open Series 7 PowerPlay reports and cubes directly from IBM Cognos 8, you must have both PowerPlay 7.3 and IBM Cognos 8 installed and configured. You also must have the following permissions: execute and read permissions to run or open a report or cube read and traverse permissions to access the folder that contains the report or cube read and write permissions to set properties for cubes and reports

Step
In IBM Cognos Connection, click the report that you want.

Depending on the default action for the report, the report runs in either PDF format (default) or opens with PowerPlay Web Explorer. If you have the required permissions, you can change the run options for Series 7 PowerPlay reports and cubes (p. 381). For information about using PowerPlay Web Explorer and PowerPlay Web Viewer, see the IBM Cognos PowerPlay Web User's Guide.

380

Chapter 25: Reports and Cubes Tip: To run any Series 7 PowerPlay report in PowerPlay Web Explorer, click the open with PowerPlay Explorer button in the actions toolbar. You can also click More next to the report you want and then open the report in Analysis Studio or Report Studio. The migration tools must already be installed. For information about installing these tools, see the IBM Cognos 8 Migration Tools Installation and Configuration Guide. When you open the report, it is upgraded to the format of the studio that you opened it in. If you save the report, it is saved in the upgraded format. There may be differences between the original PowerPlay report and the IBM Cognos 8 version of the report. If you do not save the report, it remains a Series 7 PowerPlay report. For more information about upgrading Series 7 PowerPlay reports, see the IBM Cognos 8 Migration Tools User Guide.

Change the Defaults for a Series 7 PowerPlay Report

You can change the defaults for Series 7 PowerPlay reports. You can select one of the following default actions when a report is run: run the report in PDF format (default) open the report with PowerPlay Web Explorer

For HTML format reports, you can choose to open the report in design mode (without data). Opening a report in design mode is useful to quickly view the structure of the report. For PDF format reports, you can choose to be prompted for values that filter the range of data included in a report. For example, you can specify a date range that is a subset of the dates available in the report. If the Series 7 PowerPlay report was created with prompt values, you are prompted to enter values when the report runs.

Steps
1. In IBM Cognos Connection, click the set properties button right of the report you want to run. 2. Click the PowerPlay report tab. 3. Under Default action, select the default action for when the report is run. 4. For HTML reports, if you want to open the report without data, design mode, select the Open in design mode check box. Tip: You can also click the open with PowerPlay Web Explorer in design mode button it appears in the actions toolbar. 5. For PDF reports, if you want to be prompted for values, select the Prompt for values check box. Tip: The Prompt for values check box appears only if prompt values are created for the report. You can also click More next to the report you want and then click the run the report in PDF format and prompt for values button . if on the actions toolbar to the

Administration and Security Guide 381

Chapter 25: Reports and Cubes

Open a Series 7 Cube

You can open Series 7 cubes and work with them in PowerPlay Web Explorer. For more information about using PowerPlay Web Explorer, see PowerPlay Web Users Guide.

Step
In IBM Cognos Connection, click the cube that you want.

Multilingual Properties for Series 7 Reports and Cubes

In IBM Cognos Connection, you can select the multilingual properties of a Series 7 report or cube (p. 361). The name, screen tip, and description uses the language that you select. The content, data, category labels, and other labels do not change. The language for these items is set by the PowerPlay administrator who creates the report or cube.

382

Chapter 26: Agents

You can create agents in Event Studio (p. 385) to monitor your organizations data for occurrences of business events, and then perform tasks. For example, tasks can include sending an email, adding information to the portal, and running reports. For more information, see the Event Studio User Guide. After an agent is published to the portal, use IBM Cognos Connection to do the following: run the agent (p. 383) change default properties (p. 384) create an agent view (p. 385) enable an alert list (p. 386) add or remove yourself from an alert list (p. 386) receive news item headlines (p. 387) view a list of the most recent event instances for an agent (p. 387) view the run history (p. 294) rerun a failed agent with the initial parameters (p. 297)

You can schedule agents to run at a specified time or based on a trigger, such as a database refresh or an email. You can also view the run history of scheduled agents. For more information, see "Schedule Management" (p. 299).

Run an Agent
Usually, agents run automatically according to the schedule specified by the agent author. However, you can run the agent manually at any time if you want to check for occurrences of specified events and perform specified tasks if those events occur. For example, an agent is created to send an email to sales staff when they reach 75 percent of their sales quota for the month. The agent prompts for the sales region. A sales manager specifies Spain, and emails are sent only to sales staff in Spain. You must have execute permission to run an agent. You must have traverse permissions for the folder that contains the agent.

Steps
1. In IBM Cognos Connection, click the run with options button to the agent you want to run. on the actions toolbar next

2. Under Time, click Now to run the agent now or click Later to specify a later date and time.

Administration and Security Guide 383

Chapter 26: Agents 3. If you want the agent to prompt for values to filter the results it retrieves, under Prompt Values, select the Prompt for values check box. 4. Click Run. The confirmation page appears. You are prompted for values if the agent specification or model includes prompts or if you have access to multiple data source connections or signons. 5. To view the run history of the agent, select View the details of this agent after closing this dialog. 6. Click OK. The options override the default agent options for the current run only.

Change Default Agent Properties

You can change the defaults that are set for agents in Event Studio, such as whether to use prompt values and run as the owner. If the agent contains one or more tasks with a destination of My Folders, and someone other than the owner runs the agent, the task fails unless run as the owner is selected. You can run an agent (p. 383), create agent views (p. 385), and create and edit agents in Event Studio (p. 385). You must have execute permissions for the agent. You must have traverse permissions for the folder that contains the agent.

Steps
1. In IBM Cognos Connection, click the set properties button the agent you want to run. 2. Click the Agent tab. The tasks in the agent are shown. 3. Under Default action, specify the default action for the agent. 4. If you want the agent to prompt for values to filter the results that it retrieves, under Prompt Values, select the Prompt for values check box. The Prompt for values check box appears only if prompt values are created for the agent in Event Studio. 5. If you want the agent to run using the owner credentials, click the check box next to the owner listed under Run as the owner. 6. To allow users to add themselves to the alert list for the agent, click the Allow users to add themselves to the alert list check box. 7. Click OK. The next time the agent runs, it uses these properties instead of the original defaults. on the actions toolbar next to

384

Chapter 26: Agents

Create an Agent View

Agent views share event definition and tasks with the agent but can have different properties, such as prompt values and run as the owner (p. 249). Creating an agent view does not change the original agent. Except for changes to notification lists, any changes to the original agent are automatically reflected in the agent view. You can determine the source agent for an agent view by viewing its properties. The agent view properties also provide a link to the properties of the source agent. If the source agent is deleted or moved to another location, the agent view icon indicate a broken link, and the properties link to the source agent is removed. changes to

If you want to change the properties of an agent and do not need to retain an agent with the original properties, change the default agent properties (p. 384). If you want to use a generic agent as the basis for a new agent, make a copy of the agent (p. 251). If you want an agent to appear in more than one location, create a shortcut (p. 240). To create an agent view, you must have execute or read permissions for the original agent.

Steps
1. In IBM Cognos Connection, locate the agent you want to use to create the agent view. 2. Under Actions, click the agent view icon 3. In the Name box, type the name of the entry. 4. If you want, in the Description and in the Screen tip box, you can type a description of the entry. The description appears in the portal when you set your preferences to use the details view (p. 260). The screen tip, which is limited to 100 characters, appears when you pause your pointer over the icon for the entry in the portal. 5. If you do not want to use the target folder shown under Location, choose another location, click Select another folder, select the target folder, and click OK. 6. Click Finish. In the portal, agent view entries are identified by the agent view icon . next to the agent.

The agent view has the same run options and properties as the original entry. For information about changing agent properties, see "Entry Properties" (p. 243).

Open or Create an Agent from IBM Cognos Connection

You can open or create agents from IBM Cognos Connection and work with them in Event Studio. To open an existing agent in Event Studio, do the following: In Public Folders or My Folders, click the agent.

To create a new agent in Event Studio, do the following: Administration and Security Guide 385

Chapter 26: Agents In IBM Cognos Connection, in the upper-right corner, click Launch, Event Studio.

For information about using Event Studio, see the Event Studio User Guide.

Enable an Alert List for an Agent

By granting users permission to add an alert list to an agent, users can monitor business events that are important to them. With this permission, users can add themselves to the alert list (p. 386) and be alerted by email as a Bcc recipient when the agent runs and the associated tasks are performed. The permission to add an alert list to an agent does not extend to an agent view associated with the agent. You must grant permission for the agent view independently. To grant permission for an alert list, you must have execute permission for the agent and traverse permission for the folder that contains the agent.

Steps
1. In IBM Cognos Connection, click the set properties button next to the agent for which you want to enable an alert list. 2. Click the Agent tab, and select the Allow users to add themselves to the alert list check box. Emails are sent whenever the agent is run interactively or in the background according to a schedule.

Add Yourself to or Remove Yourself from an Alert List for an Agent

Because an agent monitors important business events, you may want to add yourself to the alert list for the agent. When you subscribe to an alert list, you receive an email notification when the agent is run. You can also view and manage the alert list for the agent as a watch item. Adding yourself to the alert list of an agent does not automatically add you to the alert list for any agent views associated with the agent. If you want to receive alerts for an agent view, you must add yourself to the alert list for the agent view. The agent author must include an email task with the agent and enable an alert list for the agent (p. 386). To add yourself to the alert list of an agent, you must have read and traverse permissions for the agent. You must also have an email address defined in your LDAP security profile or in the My Preferences, Personal tab.

Steps for One Alert List

1. In IBM Cognos Connection, locate the agent. 2. In the Actions column, click More. 3. Click Add me to the alert list 4. Click OK. . or Remove me from the alert list .

386

Chapter 26: Agents Note the change for the alert list in the watch item list. To view your watch items, from the My Area menu, click My Watch Items.

Steps to Remove Yourself from Multiple Alert Lists

1. In IBM Cognos Connection, click the my area icon and then click My Watch Items. 2. On the Alerts tab, select the alerts to delete from the alert list. 3. Click the remove me from the alert list button.

Remove All Users from the Alert List for an Agent

You can remove all users from the alert list for an agent. Any user that is currently on the alert list is removed. For more information about alert lists, see "Add Yourself to or Remove Yourself from an Alert List for an Agent" (p. 386). You must have set policy permission for the agent.

Steps
1. In IBM Cognos Connection, locate the agent. 2. In the Actions column, click More. 3. Click Remove all from the alert list.

Receive News Item Headlines

The author of an agent can specify that news item headlines be published to a folder in IBM Cognos Connection when an event occurs. To be able to read headlines as an RSS-style list, you must set up a page in IBM Cognos Connection that includes a Cognos Navigator portlet that displays the folder where the headlines are published. Edit the properties of the portlet to view the entries as a news list. For instructions, see "Pages and Dashboards" (p. 267). For more information about news items, see the Event Studio User Guide.

View the Most Recent Event List

The most recent event list compares current data with data from the last time the agent ran and groups events by event status. For example, an agent is created to tell you when the quantity sold of any product by any sales person in your database changes. The first time the agent runs, the most recent event list identifies all sales as new events.

Product number
NEW EVENTS

Sales person

Quantity sold

Administration and Security Guide 387

Chapter 26: Agents

Product number
3345 3345 2256

Sales person
Ashley McCormick Bayard Lopes Alessandra Torta

Quantity sold
25 15 100

The second time the agent runs, it finds the following product sales.

Product number
3345 3345 2256 2256

Sales person
Ashley McCormick Bayard Lopes Ashley McCormick Alessandra Torta

Quantity sold
35 15 15 150

If you now view the most recent events list, you see the following list:

Product number
NEW EVENTS 2256 ONGOING (UNCHANGED) 3345 ONGOING (CHANGED) 3345 2256

Sales person

Quantity sold

Ashley McCormick

15

Bayard Lopes

15

Ashley McCormick Alessandra Torta

35 150

Steps
1. In IBM Cognos Connection, locate the agent you want. 2. Under Actions, click the set properties icon. 3. Click the Agent tab. 4. Under Default action, click View most recent event list.

388

Chapter 26: Agents 5. Click OK.

Administration and Security Guide 389

Chapter 26: Agents

390

Chapter 27: Metric Studio Metrics

Users create metrics in Metric Studio, a Web application for managing business metrics by monitoring, analyzing, and reporting them at all levels of the organization. As an administrator, you can configure security, access Metric Studio, create metric packages, run system tasks like scheduling and data loading, and view job history. You do these tasks in IBM Cognos Connection. For information about administering IBM Cognos 8 security, see "Initial Security" (p. 233).

Create a Metric Package

Before users can use Metric Studio, you must create at least one metric package using the New Metric Package wizard. A metric package is an IBM Cognos Connection representation of a Metric Studio application. A metric package contains connection information, reports, and metric management tasks for that application. The metric package content is stored in a metric store. You open the New Metric Package wizard from the toolbar in IBM Cognos Connection. Use the wizard to define the metric package name and the data source connection to the metric store. For a new metric store, you also provide the information necessary to initialize the database, including the start and end dates of the fiscal year. When you create a metric package, it contains several default reports. If Report Studio is installed, you can open these reports in Report Studio. If not, you can open them in Cognos Viewer. For more information about IBM Cognos reports, see "Reports and Cubes" (p. 347). To create metric packages, you must have execute permissions for the Metric Studio Administration secured feature and traverse permission for the Administration secured function.

Steps
1. Start IBM Cognos Connection. 2. Click the New metric package button .

3. Type a name and description for the Metric Studio application to represent this metric package, and click Next. 4. Click New data source. 5. Type a name and description for the data source connection for the metric store that contains the content for this metric package, and click Next. 6. In the Type box, click the database type. 7. Select the isolation level, and click Next. 8. Specify the information required for your database type: For a Microsoft SQL Server database, type the name of the database server and the database. Under Signons, select the Password and Create a signon that the Everyone group can use Administration and Security Guide 391

Chapter 27: Metric Studio Metrics check boxes, and type the user ID and password of the user account with access to the database. For an Oracle database, type the connection string. Select User ID, select the Password and Create a signon that the Everyone group can use check boxes, and type the user ID and password of the user account with access to the database. For a DB2 database, type the name of the database, the connection string, and the collattion sequence. Select User ID, select the Password and Create a signon that the Everyone group can use check boxes, and type the user ID and password of the user account with access to the database. Tip: To test whether the parameters are correct, click Test. 9. Click Next and then click Finish. 10. Click the new data source and click Next. 11. Click Next and follow the prompts to provide the information necessary to initialize the database. When you see the page that summarizes the data source details and the metric store settings, click Initialize. 12. Select Open this package with Metric Studio after closing the wizard and then click Finish. Metric Studio opens, and the new metric package appears in IBM Cognos Connection.

Change the Default Action for Packages

The default action when you click a package name is shown by the icon to the left of the package name in the portal. If the view metric package contents icon If the open with Metric Studio icon is visible default. is visible, the package contents appear. , the package opens in Metric Studio. This is the

To change the default action of the package, do the following: In the Actions column, click the Set properties button for the package and select the default action you want.

Run a Metric Task

To run metric tasks, you must have execute permissions for the Metric Studio Administration secured feature and traverse permission for the Administration secured function. You can run a metric task immediately, or schedule it to run at a later time, or on a recurring basis.

Steps to Run a Task Now

1. In IBM Cognos Connection, in Public folders or My folders, open the Metric Studio package that you want.

392

Chapter 27: Metric Studio Metrics Tip: Unless you changed the default action for the package, clicking the package name will cause the package to open in Metric Studio. 2. Click Metric maintenance, and click the metric task that you want to run.

Steps to Schedule a Task

1. In IBM Cognos Connection, in Public folders or My folders, open the Metric Studio package that you want. 2. Click Metric maintenance, and in the Actions column, click the run with options button 3. Click Later, and enter the time that you want the task to run. You can also schedule a task to run on a recurring basis, and view a list of scheduled tasks using the Schedule Management tool. For more information, see "Schedule Management" (p. 299). .

Delete a Metric Task

You can also modify a metric task. You must have write permissions or set policy permissions for the task you are attempting to delete. You must also have write and traverse permissions for the current package.

Steps
1. In IBM Cognos Connection, in Public folders or My folders, select the check boxes next to the tasks you want to delete. 2. Click the delete button on the toolbar.

A confirmation box appears. 3. Click OK.

Modify a Metric Task

If you want to modify an existing metric task to fit you organizations needs, you can customize the options.

Steps
1. In IBM Cognos Connection, in Public folders or My folders, open the Metric Studio package that you want. 2. Click the set properties button you want to modify. on the actions toolbar to the right of the metric task that

3. Depending on what you want to change, click the Metric maintenance, Metric import, or the Metric export tab. 4. Select or clear the check boxes for the options you want to change.

Administration and Security Guide 393

Chapter 27: Metric Studio Metrics 5. Click OK.

Metric Import Tasks

Metric packages have default import tasks available for importing and transferring data. You can run these tasks as they are (p. 392), modify them to fit your organizations needs (p. 393), or create new import tasks (p. 394). These default tasks are available in your metric package, in the Metric maintenance folder.

Import Data From Files Into the Staging Area

You can use this task to load data from tab-delimited files into the staging tables. This is useful when your data is currently maintained in a spreadsheet or database. This task can be run at anytime without changing what is visible in Metric Studio.

Import and Transfer Data From Files Into the Metric Store
You can use this task to load data from all data sources into the staging tables and then transfer it into the metric store. The data will be appear in Metric Studio but no derived values or calculated metrics will be visible. This task also updates the search index.

Transfer Data From the Staging Area Into the Metric Store
You can use this task to move data from staging tables into the metric store. The data in the staging tables can be from imported tab-delimited files, or from another source such as Metric Designer. You can run this task after importing data from files into the staging tables. This task also updates the search index.

Create New Metric Import Task

Use this wizard to create a new task to import data into Metric Studio.

Steps
1. Click the new data integration task button import from files. 2. Type the name and description to represent this new import task and if necessary, change the location to place the task, and click Next. 3. Click the Transfer data from staging area into metric store to change the pre- and post- import options for the task. Click the options you want to use when the task is run. Click Next. 4. Select the action you want: To run now or later, click Save and run once and click Finish. Specify the time and date for the run. Then click Run. Review the run time and click OK. To schedule at a recurring time, click Save and schedule and click Finish. Then, select frequency and start and end dates. Then click OK. on the toolbar, and then click New metric

394

Chapter 27: Metric Studio Metrics Tip: To temporarily disable the schedule, select the Disable the schedule check box. To view the schedule status, see . To save without scheduling or running, click Save only then click Finish.

Edit Metric Import Task Properties

To edit a metric import task, in the Actions column, click the set properties button import properties appear on the Metric import tab of the Set properties page. . Metric

Property

Description

Import data options: Transfer data from staging Check box to add pre- and post- import data area into metric store options. Pre-import data options Options to clear history and calendar data, and rejected data logs. Options to recalculate derived values, send emails from Metric Studio Watchlist, and maintain the search engine index. Whether to use the owner credentials (p. 218) when the task is run.

Post-import data options

Run as the owner

Metric Maintenance Tasks

Metric packages have default metric maintenance tasks available for importing and transferring data. You can run these tasks as they are (p. 392), modify them to fit your organizations needs (p. 393), or create new import tasks (p. 394). These default tasks are available in your metric package, in the Metric maintenance folder.

Clear Staging Area Rejected Data Logs

Use this metric task to clear the rejects tables. The rejects tables are not cleared automatically after you reload the metadata and data. Each time there are rejects, they are added to the tables. You will need to clear the tables from time to time to prevent them from becoming too large. Do this after you finish troubleshooting and want to begin a new load.

Clear Data Store Metric History and Calendar Data

Use this task to delete actual, target, and user-defined column values. This option also deletes any other calendar-dependent data, such as comments, actions, and mappings from PowerCube cells to metrics. Use this option when you want to change the calendar. You must then re-create the calendar before you can use the metric package again.

Administration and Security Guide 395

Chapter 27: Metric Studio Metrics Warning:Clearing data store metric history and calendar data completely reinitializes the metric package database. All work will be lost.

Clear Data Store Metric History Data Only

Use this task to delete only actual, target, and user-defined column values.

Recalculate Data Store Derived Values

Use this task to recalculate scores and compute derived values and summary data in the data store. You should run this task after you load data into the data store, or after manually adding data. Concurrent recalculate processes are not permitted. This task also updates the search index.

Synchronize Data Store Users With External Namespace

Use this task to copy user information from an external namespace to the metric store.

Update Search Engine Index

Use this task to maintain the index used for searching in Metric Studio. You should run this task after loading or entering new data, to ensure new objects are indexed for searching.

New Metric Maintenance

Use this wizard to create a new task to maintain your metric data.

Steps
1. Click the new data integration task button maintenance. 2. Type the name and description to represent this new maintenance task and if necessary, change the location to place the task, and click Next. 3. Click the options you want to use when the task is run, and click Next. 4. Select the action you want: To run now or later, click Save and run once and click Finish. Specify the time and date for the run. Then click Run. Review the run time and click OK. To schedule at a recurring time, click Save and schedule and click Finish. Then, select frequency and start and end dates. Then click OK. Tip: To temporarily disable the schedule, select the Disable the schedule check box. To view the schedule status, see . To save without scheduling or running, click Save only then click Finish. on the toolbar, and then click New metric

Edit Metric Maintenance Properties

To edit a metric maintenance task, in the Actions column, click the set properties button . Metric maintenance properties appear on the Metric maintenance tab of the Set properties page.

396

Chapter 27: Metric Studio Metrics

Property
Metric data options

Description
Options to move data from the staging area to the metric store and compute derived values and summary data. Options to clear history and calendar data, and rejected data logs. Options to send emails from Metric Studio Watchlist, synchronize user information, and maintain the search engine index. Whether to use the owner credentials (p. 218) when the task is run.

Clear data options

Additional options

Run as the owner

Metric Export Tasks

The following table describes the metric objects that can be exported using the new metric export wizard, and explains the content that is exported for each object.

Metric object
Scorecards

Content exported
Exports all scorecards in the metric store (does not include associated metrics, reports, or diagrams). Exports all metric types and metric type properties including equations. Exports all metrics (does not include metric values, or associated reports, diagrams, or comments). Note that you will need the associated scorecards, metric types, and qualifiers in order to load these metrics into another metric store. Exports the Metric Studio business calendar including calendar levels and periods. Exports all qualifiers. Exports all reports that have been associated with scorecards, metric types, strategies, projects, and metrics. Exports all diagrams that have been associated with scorecards, metric types, strategies, projects, and metrics.

Metric Types

Metrics

Business Calendar

Qualifiers Reports

Diagrams

Administration and Security Guide 397

Chapter 27: Metric Studio Metrics

Metric object
Actions and Projects

Content exported
Export all actions and projects that have been associated with metrics. Exports language tables and group associations for the Strategies feature. Exports all permissions that have been set on Metric Studio objects. Exports flat file and relational import sources that have been defined in Metric Studio. Exports cube import sources that have been defined in Metric Designer along with their associated time levels and time period mappings, currency mappings, and reportlet dimension selections. Exports user defined column definitions. Exports any special units you have defined. Examples of default units are Currency and Percent. Exports all links including metric, scorecard, report, diagram, projects, strategies, and so on. You must export links in order for metrics to appear on scorecards and for reports and diagrams to appear on scorecards or metrics. Exports any special parameters you have staged against Metric Studio objects for use as URL parameters. Exports all watch lists to which you subscribe.

Strategies

Permissions

Import Sources

Metric Designer Import Sources

User Defined Columns Units

Object Links

Custom URL parameters

Watch Lists

Use the new metric export wizard to create a new task to export metric data to files.

Steps
1. Click the new data integration task button export. 2. Type the name and description to represent the new export task and if necessary, change the location to place the task, and click Next. 3. Click to clear the objects you do not want to export, and click Next. 4. Select All data for selected objects, or choose to export data created or changed after a specified date, and click Next. 398 on the toolbar, and then click New metric

Chapter 27: Metric Studio Metrics 5. Under Metrics period, click All Values to export values for the entire time period, or Values for the period to export values created during a specified time period. Under Available value types, select the values you want to export, and click Next. 6. Select the currencies, and click Next. 7. Select the format to use when exporting security references. Note: Using IBM Cognos 8 security references will execute faster. The Metric Studio 2.2 format exports users and groups by name, requiring directory searching. 8. Click Next. 9. Select the languages, and click Next. 10. Select an existing metric data archive to export to, or create a new one. Select the character set encoding and decimal separator value, and click Next. 11. Review your selected options for the export task, and click back if you want to change any options. When you are ready to proceed with the export, click Next. 12. Select the action you want: To run now or later, click Save and run once and click Finish. Specify the time and date for the run. Then click Run. Review the run time and click OK. To schedule at a recurring time, click Save and schedule and click Finish. Then, select frequency and start and end dates. Then click OK. Tip: To temporarily disable the schedule, select the Disable the schedule check box. To view the schedule status, see . To save without scheduling or running, click Save only then click Finish.

Change Metric Export Properties

You can edit the properties of a metric export task. For instance, you may want to add a language for your users.

Steps
1. In the Actions column, click the set properties button to export. 2. Click the Metric export tab. The metric export properties appear. 3. In the Run as the owner box, choose whether to use the owner credentials (p. 218) when the task is run. 4. Click Update the metric export. The Review the summary page appears, showing the current settings for the metric export. for the metric object that you want

Administration and Security Guide 399

Chapter 27: Metric Studio Metrics 5. Press Back as needed to change the settings. 6. Click Save.

400

Chapter 28: Drill-through Access

Drill-through access helps you to build business intelligence applications that are bigger than a single report. Drill-through applications are a network of linked reports that users can navigate, retaining their context and focus, to explore and analyze information. Drill-through access works by passing information from the source to the target object, usually a report. You define what is passed from the source report by having the system match information from the selection context of the source report to the content of the target (dynamic drill through) or by defining parameters in the target (parameterized drill through). You define drill-through access for the source, either at the package level, in IBM Cognos Connection (Launch, Drill-through Definitions) or at the report level (Report Studio Professional authoring mode). Within a package, you control the scope of the data for which drill-through access is available in the drill through definition. Within a report, you define the drill-through access on a report item.

What You Should Know

For a drill through link to work, it is necessary to know: what the source report is or is going to be what the target report is or is going to be whether the users of the drill through link in the source report have the appropriate permissions to view or run the target report how the data in the two reports is related Depending on the underlying data, you may create a drill through definition and have IBM Cognos 8 match the data (dynamic drill through) or map the source metadata to parameters defined in the target report or package (parameterized drill through) whether to run the target report or to open it The target of drill-through access is usually a saved report definition. The report can be created in Report Studio (Professional authoring mode), PowerPlay Studio, Query Studio, or Analysis Studio. The target of drill-through access can also be a package that contains a PowerCube, in which case a default view of the PowerCube is created. if the target is being run, in what format to run it and what filters to run it with If you don't want to run the target report on demand, you may link instead to a bookmark in the saved output.

Sources and Targets

In IBM Cognos 8, there are many different combinations of source and target. For example, you can drill through between reports created in different packages against different data source types (p. 408), such as from an analysis against a cube to a detailed report against a relational data source. Administration and Security Guide 401

Chapter 28: Drill-through Access from one existing report to another report using Report Studio (Professional authoring mode)(p. 422) between Cognos Viewer reports authored in Report Studio, Query Studio, PowerPlay Studio, and Analysis Studio from Series 7 PowerPlay Web cubes to IBM Cognos 8 reports (p. 426) from Metric Studio to other IBM Cognos 8 reports by passing parameters using URLs. For more information, see the Metric Studio User Guide.

Understanding Drill-through Concepts

Before you set up drill-through access, you must understand the key concepts about drilling through. Knowing these concepts will help you to avoid errors so that report consumers drill through as efficiently as possible.

Drill-through Paths
You can create a drill-through path in a source report in Report Studio (Professional authoring mode), or using Drill-through Definitions in IBM Cognos Connection. A drill-through path is the definition of the path that is taken when moving from one report to another, including how the data values are passed between the reports. Using Drill-through Definitions, you can create a drill-through path from any report in the source package to any target report in any other package in IBM Cognos Connection. This type of drillthrough definition is stored in the source package. Users of any report in the package can use the drill-through definition to drill between any combination of Analysis Studio, Query Studio, PowerPlay Studio, or Cognos Viewer reports in any package. For any target report that contains parameters, you should map the target parameters to the correct metadata in the drill-through path. This ensures that the values from the source report are passed to the correct parameter values, and that the target report is filtered correctly. If you do not map parameters, then the users may be prompted for values when the target report is run. A report-based drill-through path refers to a path created and stored in a Report Studio source report (Professional authoring mode). This type of drill-through path is also called "authored drill through". The path is associated with a specific data column, chart, or cross tab in the source report, and is available only when users select that area of the report. If an authored drill-through definition is available, a hyperlink appears in the source report when it is run. Report-based drill-through is limited to Report Studio source reports (Professional authoring mode) and any target reports. Use this type of drill-through access when you want to pass data item values or parameter results from within a source report to the target report, pass the results of a report expression to a target report, or a use URL link as a part of the drill-through definition.

Selection Contexts
The selection context represents the structure of the values selected by the user in the source. In Analysis Studio, this includes the context area. When a package drill-through definition is used,

402

Chapter 28: Drill-through Access the selection context is used to give values for mapped parameters (parameterized drill-through) or also to map the appropriate data items and values. Drill-through links can also be defined to open the target object at a bookmark. The content of this bookmark may also specified by the selection context. Drill-through access is possible between most combinations of the IBM Cognos 8 studios. Each studio has been optimized for the goals and skills of the audience that uses it, and in some cases for the type of data source it is designed for. Therefore, you may need to consider how the various studios manage the selection context when you drill through between objects created in different studios, and how the data sources are conformed. During testing or debugging, you can see how source values are being mapped in different contexts using the drill-through assistant.

Drilling Through to Different Report Formats

The settings in the drill-through definition determine how users see the report results. For example, the users may see the reports in Cognos Viewer as an HTML Web page, or the reports may open in Query Studio, PowerPlay Studio, or Analysis Studio. If your users have PowerPlay Studio, then they may also see the default view of a PowerCube. Reports can be opened as HTML pages, or as PDF, XML, CSV, or Excel formats. When you define a drill-through path, you can choose the output format. This can be useful if the expected use of the target report is something other than online viewing. If the report will be printed, output it as PDF; if it will be exported to Excel for further processing, output it as Excel or CSV, and so on. If you define a drill-through path to a report that is created in Analysis Studio, PowerPlay Studio, or Query Studio, consumers can open the report in its studio instead of in Cognos Viewer. This can be useful if you expect a consumer to use the drill-through target report as the start of an analysis or query session to find more information. For example, if an application contains a dashboard style report of high-level data, you can define a drill-through link to Analysis Studio to investigate items of interest. The Analysis Studio view can then be drilled through to a PDF report for printing. Note: Drilling through to open the target in Report Studio is not supported for the Express Authoring mode. The Report Studio Professional authoring mode does not display data results.

Drilling Through Between Packages

You can set up drill-through access between different packages. The two packages can be based on different types of data source, but there are some limits. The following table shows the data source mappings that support drill-through access.

Source data source

OLAP

Target data source

OLAP Note: OLAP to OLAP drill through is supported only if the data source type is the same, for example, SSAS to SSAS.

Administration and Security Guide 403

Chapter 28: Drill-through Access

Source data source

OLAP OLAP

Target data source

Dimensionally modeled relational Relational data Note: For more information, see "Business Keys" (p. 407).

Dimensionally modeled relational Dimensionally modeled relational Relational

Dimensionally modeled relational Relational Relational

Bookmark References
When you drill through, the values that you pass are usually, but not always, used to filter the report. IBM Cognos 8 Business Intelligence supports bookmarks within saved PDF and HTML reports so that a user can scroll a report to view the relevant part based on a URL parameter. For example, you have a large inventory report scheduled to run daily or weekly during off hours because of resource considerations. Your users may want to view this report as a target because it contains detailed information, but you want them to view the saved output rather than run this large report. Using this Action option and bookmark settings, users can drill through from another source location based on products to open the saved report to the page that shows the product they want to focus on. When a bookmark in the source report is used in a drill-through definition, it provides the value for the URL parameter. When report consumers drill through using this definition, they see the relevant section of the target report. Bookmark references are limited to previously run reports that are output as PDF or HTML and contain bookmark objects.

Members and Values

Dimensionally modeled data, whether stored in cubes or stored as Dimensionally Modeled Relational (DMR) data, organizes data into dimensions. These dimensions contain hierarchies. The hierarchies contain levels. And the levels contain members. An example of a dimension is Locations. A Locations dimension may contain two hierarchies: Locations by Organization Structure and Locations by Geography. Either of these hierarchies may contain levels like Country and City. Members are the instances in a level. For example, New York and London are members in the City level. A member may have multiple properties, such as Population, Latitude, and Longitude. Internally, a member is identified by a Member Unique Name (MUN) (p. 405). The method by which a MUN is derived depends on the cube vendor. Relational data models are made up of data subjects, such as Employees, which are made up of data items, such as Name or Extension. These data items have values, such as Peter Smith.

404

Chapter 28: Drill-through Access In IBM Cognos 8, the methods of drilling through available are Dimensional (member) to Dimensional (member) Dimensional (member) to Relational (data item value) Relational (data item value) to Relational (data item value)

If the target parameter is a member, the source must be a member. The source and target should usually be from a conformed dimension (p. 406). However, if the data will support it, you may also choose to define a mapping using different properties of the source metadata item. If the target parameter is a value, the source can be either a value or a member. If the source is a dimensional member, you must ensure that the level or dimension is mapped to the target data item correctly in the drill-through definition. The business key from which the member is sourced should usually match the relational target value, which is most often the business key (p. 407). However, if the data will support it, you may also choose to define a mapping from the caption of the source metadata item.

Member Unique Names

The member unique name (MUN) is a unique identifier for a member in IBM Cognos reports. It is stored in the report specification when the member is referenced in the report directly. The MUN is used in drill-through between OLAP data sources. The member keys in the MUN for the different OLAP data sources must match. The MUN is used to find the member in the data source, which is similar to how business keys are used to find records in a table. For example, when you create OLAP dimension Products, you use the Product Line database column as s label for the members in your Product Line level. However, you use the Product Line Code business key from the database table to ensure that all the Product lines are unique in that level. The source value that you used to create the members is used in combination with the data source name, hierarchy, and level information in the member unique name. If the MUN changes, members that are directly referenced in expressions, filters, or reports are no longer found. Changes to the MUN may be related to other changes. For example, changes to the hierarchy and level structures may change the level unique name, and changes to the business key values may change the member key path. Other factors that can affect the MUN are application changes during the design stage or over time, IBM Cognos PowerCube category codes that are unpredictably unique, the production environment that has more members than the test environment, or removing the member from the data source. To avoid potential problems, we recommend the following best practices when you build OLAP data sources: Use unique codes and keys within a dimension for the member keys. Define your OLAP and relational packages using unique conformed values for the source values (business keys) within similar dimensions or data values where drill-through between applications may be required.

Administration and Security Guide 405

Chapter 28: Drill-through Access Ensure that the business keys and dimension metadata structure are the same in the production and test environments. Do not change the business keys in Framework Manager in the production environment. Resolve the non-unique keys in a dimension in the data source before you build the cube. Ensure that there are no duplicate source values in all levels of a dimension before you build a PowerCube. We do not recommend using the tilde character (~) in the category codes. For more information, see the section about uniqueness in the IBM Cognos Series 7 Step-byStep Transformer. For information about PowerCubes migrated from IBM Cognos Series 7, see the IBM Cognos 8 BI PowerPlay Migration and Administration Guide.

Conformed Dimensions
If you work with more than one dimensional data source, you may notice that some dimensions are structured the same, and some are not. The reason that dimensions can be structured differently is that the data sources may serve different purposes. For example, a Customer dimension appears in a Revenue data store, but not in an Inventory data store. However, the Products dimension and the Time dimension appear in both data stores. Dimensions that appear in multiple data stores are conformed if their structure is identical for all of the following: hierarchy names level names level order internal keys

Drilling through is possible between different dimensional data stores only if the dimensions are conformed, and if the dimension data store is of the same vendor type, such as IBM Cognos PowerCube as the source and the target. For example, in two data stores for Revenue and Inventory that contain Products and Time dimensions, it is possible to define the Products and Time dimensions differently for each data store. However, for drill-through between the Products and Time dimensions to work, their structures must be identical in each data store. If you are not sure whether your dimensions are conformed, then you should check with the data modeler to ensure that the drilling through will produce meaningful results.

Dimensionally-modeled Relational Data Sources

Ensure that each level contains a business key that has values that match your PowerCube or other DMR models. Also, you must also ensure that the Root Business Key property is set and uses the business key of the first level in the hierarchy. This helps to ensure that you have a conformed member unique name when attempting to drill through using members from this dimension.

406

Chapter 28: Drill-through Access

Business Keys
When drill-through access is defined from a member to a relational value, the business key of the member is passed by default. This means that your relational target parameter must be set up using the data item with a matching value, which is most often the business key data item. You can also choose to pass the caption of the source metadata item. For example, employees are usually uniquely identified by an employee number, not by their name, because their name is not necessarily unique. When you drill through from a dimensional member to a relational data item, the value provided is the business key. Therefore, the parameter in the target report must be defined to accept a business key value. The exact logic used to define the business key value supplied depends on the cube vendor. For IBM Cognos PowerCubes, the business key value is the Source property defined for the level in IBM Cognos Transformer. IBM Cognos Series 7 Transformer PowerCubes pass the source value if the drill-through flag was enabled before the cube was built. Otherwise, the category code is used. In Report Studio (Professional authoring mode), you can determine what the member business key is using an expression such as roleValue('_businessKey',[Camping Equipment]). This expression is case sensitive. SSAS 2005 multi-part business keys are not supported in drill-through operations. Tip: When other users run your drill-through report, you may not want them to be prompted for a business key. In Report Studio, you can build a prompt page with a text that is familiar to the users, but filters on the business key. Your Framework Manager modeler can also set the Display Item Reference option for the Prompt Info property to use the business key when the data item is used in a prompt.

Scope
Scope is specific to drill-through definitions created using Drill-through Definitions in IBM Cognos Connection (package drill-through definitions). The scope you set defines when the target report is shown to the users, based on the items they have in the source report. Usually, you define the scope of a drill-through path to match a parameter that it passes. For example, if a target report contains a list of employees, typically you only want to display the report as an available drill-through choice when a user is viewing employee names in a source report. If employee names are not in the source report and the scope was set on the employee name in the drill-through definition, the employee report does not appear on the list of available drill-through target reports in the Go To page. You can set the scope to a measure or to an item in the report. In report-based drill-through access, where the drill-through path is associated with a specific report column, the column serves as the scope.

Mapped Parameters
Drill-through targets may contain existing parameters, or you may choose to add parameters to the target for greater control over the drill-through link. You usually map all parameters in a drillthrough target to items from the source. When you map source items that are OLAP or DMR members to target parameters, you can select from a set of related member properties to satisfy the requirements of the target parameter. For a Administration and Security Guide 407

Chapter 28: Drill-through Access dimensional target, a dimensional source item uses the member unique name by default. For a relational target, a dimensional source item uses the business key by default. For example, you could change the source member property that is used for a mapping to the member caption instead of the business key to match the parameter in a relational target. For a dimensional target, you could define a parameter that accepts a particular property (such as business key or parent unique name), then pass the appropriate source property to satisfy that target. Note that if you define drill through between non-conformed dimensions, you should test carefully to ensure that the results behave as expected. If you do not specify parameter mappings, then by default, you will be prompted for any parameters required in the target when you use the drill-through link. To customize this behavior, use the display prompt pages setting. When the action is set to "Run using dynamic filtering", then additional filtering is applied if names from the context in the source report match names of items in the target. Use this action as well when there are no parameters defined in the target. If parameters are not mapped correctly, then you may receive an empty report, the wrong results, or an error message. The source and target cannot contain identical parameter names when they are from different packages, even if the data structure is conformed. If the source and target are from the same package, there is no restriction. If you have the necessary permissions, you can use the drill-through assistant to look at what source parameters are passed, and what target parameters are mapped for a given drill-through link.

Drilling Through on Dates Between PowerCubes and Relational Packages

Usually, drilling through from OLAP to relational packages requires that the target report parameter is set using the business key in the relational data. However, this method does not work well for dates. OLAP data sources typically view dates as members, such as Quarter 1 2006, while relational data sources view dates as ranges, such as 1/Jan/2006 to 31/March/2006. A special feature exists for drilling through between PowerCubes and relational packages. Ensure that the target report parameter is set up using in_range. Note that the parameter must be of type date-time, and not integer. An example follows:
[gosales_goretailers].[Orders].[Order date] in_range ?Date?

Also ensure that the drill-through definition maps the parameter at the dimension level and that the PowerCube date level is not set to suppress blank categories. Enabling the option to suppress blank categories in the Transformer model before you build the cube may cause the drill-through on dates to be unsuccessful. This happens because there are missing values in the range.

Set Up Drill-through Access in Packages

A drill-through definition specifies a target for drill-through access, the conditions under which the target is available (such as the scope), and how to run or open, and filter the target. In IBM Cognos 408

Chapter 28: Drill-through Access Connection, a drill-through definition is associated with a source package. The drill-through path defined in the drill-through definition is available to any report based on the source package it is associated with. The target can be based on any target package in IBM Cognos Connection and can be stored anywhere. For example, all reports authored in the GO Data Warehouse (analysis) sample package or in a folder linked to this package can access any drill-through definition created in this package. Note: For reports created in Report Studio (Professional authoring mode), you can define drillthrough access in specific reports by setting up the drill-through definition in the report instead of in the package, or restrict drill-through access by changing report settings so that the report is unavailable as a drill-through target. For more information, see the Report Studio Professional Authoring User Guide. Reports created in Report Studio Express are not supported as drill-through targets. You can define drill-through definitions between reports created in the different IBM Cognos 8 studios, and reports based on different packages and data sources (p. 403). The target report must exist before you start creating the drill-through definition in IBM Cognos Connection. Drill-through targets can be reports, analyses, report views, PowerCube packages and queries. Drill-through definitions support both dimensional and relational packages, and are available to Analysis Studio, Query Studio, PowerPlay Studio, and Cognos Viewer.

Steps to Create a Drill-through Definition

1. Check the drill-through target: Confirm that the drill-through users have access to the target. Hide the target from direct access if you want(p. 254). If necessary, check what parameters exist in the target. When a drill-through definition links objects in different packages, you must consider the data types used in both the source and the target object. Review the structure and values of data that you intend to pass in the drill-through, and ensure that the created parameters are appropriate for your scenario, if you have defined parameters, or that dynamic drill through will work successfully. For more information, see "Conformed Dimensions" (p. 406) and "Business Keys" (p. 407). 2. In IBM Cognos Connection, in the upper-right corner, click Launch, Drill-through Definitions. 3. Navigate to the top level of the package for which you want to create the drill-through definition. 4. Click the new drill-through definition button on the toolbar. Tip: If you do not see the drill-through definition button, then confirm that you are at the top level of the package, and not in a folder in the package. Drill-through definitions must be stored at the package level. 5. Type a name for the drill-through definition. 6. If you want, type a description and screen tip, and then click Next.

Administration and Security Guide 409

Chapter 28: Drill-through Access 7. Follow the instructions on the screen: If you wish, restrict the scope to a query item or a measure in the source. If the target contains parameters, you should set the scope to the parameters that are mapped to the target report. For more information, see "Scope" (p. 407). Select the target from any package available in IBM Cognos Connection. If IBM Cognos 8 BI PowerPlay targets are available, then you must choose whether to set the target as a report or a PowerCube. Click Next.

8. In the Action section, specify how to open the target object when the drill-through link is run and if you chose to run the report, in the Format section, specify the format to run the report in. Users may be able to change the Action settings when they use the drill-through link.If you are using bookmarks in the target, then you must select the action View most recent report. 9. In the Parameter values table, specify how to map the source metadata to any parameters that exist in the target report or object. For example, if you drill through between OLAP data sources, then members are mapped to each other. If you drill through from an OLAP to a relational data source, then the source value (member) is mapped to the query item name (value). Usually, every parameter that exists in the target should be mapped to the source metadata. If not, then the report user may be prompted for any missing values when the drill-through link is used. 10. Click Map to metadata, or click the edit button. In the screen that appears, select the metadata from the source to map to the target parameter. If the source package is dimensional, you can select what property of the source metadata item to use in the mapping. By default, the business key is used for a relational target, and the member unique name is used for a dimensional target. Repeat for each parameter in the list.

11. In the Display prompt pages section, specify when the prompt pages will appear. You can only set this action when there are parameters in the target report and the target report will be run. If you change the action to View most recent report, for example, for bookmark references, the Display prompt pages property is disabled because you will use a previously-run report. If you choose to open the report directly in Analysis Studio, then the the Display prompt pages property is also disabled. You specify prompt settings in IBM Cognos Connection (Report Properties, Prompt for Values). 12. Click Finish.

410

Chapter 28: Drill-through Access 13. Run a report from the source package, and test the drill-through link. Note: The drill-through definition is associated and stored with the source. Errors related to the target are only generated when you run the drill-through links, not when you save the drillthrough definition.

Steps to Edit an Existing Drill-through Definition

1. In IBM Cognos Connection, in the upper-right corner, click Launch, Drill-through Definitions. 2. Click a package name to view its drill-through definitions. 3. Click the set properties button on the actions toolbar to the right of the drill-through definition that you want to modify. Tip: If you do not see the drill-through definitions, check that you are not in a folder in the package. Drill-through definitions are all stored at the root level of the package. If you do not see a specific drill-through definition, confirm that you have the correct permissions. 4. Click the Target tab. 5. Make the necessary modifications, and click OK. 6. Run a report from the source package, and test the drill-through link. Note: The drill-through definition is associated and stored with the source. Errors related to the target are only generated when you run the drill-through links, not when you save the drillthrough definition.

Set Up Parameters for a Drill-Through Report

For greater control over drill-through access, you can define parameters in the target report. For more information about defining parameters, see the Report Studio Professional Authoring User Guide or the Query Studio User Guide.

Steps in Report Studio

1. Open the target report in Report Studio Professional authoring mode. 2. Ensure that the report is available for drill-through access: From the Data menu, select Drill Behavior. In the Basic tab, select Accept dynamic filters when this report is a drill-through target and then click OK.

3. Create a parameter that will serve as the drill-through column, or that will be used to filter the report. (Data menu, Filters). For example, to drill through or filter on Product line, create a parameter that looks like this:
[Product line]=?prodline_p?

Tip: Use the operators in or in_range if you want the target report to accept multiple values, or a range of values.

Administration and Security Guide 411

Chapter 28: Drill-through Access 4. In the Usage box, specify what to do when a value for the target parameter is not passed as part of a drill-through: To specify that users must click a value in the source report, click Required. If a value for the target parameter is not passed, users are prompted to choose a value. To specify that users do not need to click a value in the source report, click Optional. Users are not prompted to choose a value and so the value is unfiltered. To specify not to use the parameter, click Disabled. The parameter is not used in the report, and therefore not available for drill-through definitions. For more information about defining report parameters, see the Report Studio Professional Authoring User Guide. Tip: If the parameter is needed in the report for other reasons, then you can also specify not to use it in the drill-through definition (Parameters table, Method, Do not use parameter). The drill-through definition controls when prompt pages or parameters are displayed.

Steps in Query Studio

1. Open the target report in Query Studio. 2. Confirm that the report is available for drill-through access: From the menu, select Run Report, Advanced Options. Select Enable drill through from a package in the report output and then click OK.

3. Create a filter that will serve as the drill-through parameter, or that will be used to filter the report. Select the column that you want to filter on, and click the filter button. Change the settings as needed, and click OK.

Set Up Parameters for a Drill-through Target in Analysis Studio

You can create a drill-through target analysis and add target parameters in the analysis by setting a dimension as the Go To parameter. When you create a drill-through definition for the analysis, this parameter appears in the target parameter list. To support drilling down within the dimension and then drilling through, map the dimension in the source metadata to the target dimension. The member or members which are currently in your view are passed to the target analysis as filter values. This applies to any query, report, or analysis used in IBM Cognos 8 drill-through actions. To support drilling through directly from a particular level, map that level in the source metadata to the target dimension.

412

Chapter 28: Drill-through Access You can set multiple parameters in an analysis target. However, you cannot pass members within a selection set in Analysis Studio.

Steps
1. In Analysis Studio, create a cross-tab analysis using the package that was set up for drill-through analysis. 2. If you want, add as a row or column the data item that you want to be the prompt. 3. Move or add the dimension or level that you want to be a target parameter to the Context area. Note: You cannot pass members within a selection set in Analysis Studio. 4. View the list for the item in the Context area and click Use as "Go To" Parameter. 5. Save this analysis as your target report in IBM Cognos Connection. You can now create the drill-through definition under a source package. When you create the drill-through definition (p. 408) and use the cross-tab analysis as a target, the Go To parameter item in the analysis appears as a drill-through parameter. You can map to this parameter the same way that you drill through to Report Studio or Query Studio reports.

Example - Drill Through Between OLAP Reports in the Same Package

You want to drill through from an Analysis Studio report that shows revenue breakdown according to order method to a report created in Report Studio, which shows details of planned and actual revenue. Both of these reports exist as samples in the Sales and Marketing (cube) package. The reports are both based on the same package, so the data is conformed (p. 406). You decide to use a parameterized drill-through definition for greater control, because prompt parameters exist in the target already. You also decide to restrict the scope of access to the drill-through target, so it that it is only available to a report in the source package that uses the measure Revenue. This means that any reports created in the package will see this drill-through definition if they contain the measure Revenue. If the source report does not contain order year or order method, then users will be prompted for values for those parameters when the drill-through target is run. You must have the IBM Cognos 8 BI samples from the deployment zip file Cognos_DrillThroughSamples installed to follow this exercise. If you want to check the target report, you must have access to Report Studio, Professional mode.

Administration and Security Guide 413

Chapter 28: Drill-through Access

The target report shows data for the context of the source: the Special order method type, and the year 2005.

Steps to Check the Target and Source Report

1. Open the target report, Actual vs. Planned Revenue, in Report Studio. Go to IBM Cognos Connection. In Public Folders, open the package Sales and Marketing (cube), and then open the folder Report Studio Report Samples. Select the report Actual vs. Planned Revenue, and click the Open with Report Studio icon.

2. In the Actual vs Planned Revenue report in Report Studio, confirm that you have parameters for order method and time. Open the query explorer tab and select Query 1. In the Detail Filters box, confirm that a filter parameter exists for each of Order Method and Year, and note the parameter names. 3. From the Data Items box, note the name of the measure that you plan to use for the scope (Revenue). 4. Close the Actual vs Planned Revenue report. 5. Open the source report, Custom Rank Sample, in Analysis Studio. Go to IBM Cognos Connection. In the Public Folders, open the package Sales and Marketing (cube), and then open the folder Analysis Studio Report Samples. 414 Select the report Custom Rank Sample, and click the Open with Analysis Studio icon.

Chapter 28: Drill-through Access 6. In the Custom Rank Sample report in Analysis Studio, check the name of the measure that you want to use to restrict scope (Revenue). 7. Check the rows and columns in the report and confirm that the data structure will match the parameters in the Actual vs Planned Revenue report. Tip: Pause the mouse over a label in the crosstab to see the path. 8. Leave the Custom Rank Sample report open for testing.

Steps to Create and Test the Drill-through Definition

1. In IBM Cognos Connection, navigate to the Sales and Marketing (cube) package. 2. From the upper right-hand corner of the screen, click Launch, Drill-through Definitions. 3. Click New Drill-through Definition in the upper right hand corner of the screen. Tip: If you dont see the New Drill-through Definition button, check that you are at the root of the folder, and not still in the Analysis Studio Reports folder. 4. In the Drill-through Definition wizard, type the name "Drill Through From Custom Rank to Revenue Details" and a description, and click Next. 5. Click Set the scope, and in the screen that appears, set the scope to the Revenue measure, and then click OK. 6. Click Set the target, and in the screen that appears, set the target report to Actual vs. Planned Revenue, in the Report Studio Report Samples folder of the Sales and Marketing (cube) package. 7. In the Prompt Values table, map the parameters pMethod and pYear in the target to the metadata in the source: confirm that values in the Type column are Connection Use the value "Connection" when you link dimensional data sources. for the pMethod parameter, click the edit button and select [sales_and_marketing].[Order method].[Order method].[Order method type] from the metadata tree. for the pYear parameter, click the edit button and select [sales_and_marketing].[Time]. [Time].[Year] from the metadata tree.

8. Set Display Prompt Pages to Only when required parameter values are missing. 9. Follow the instructions on the screen to save the drill-through definition. 10. Go to the Custom Rank Sample report, right-click outside the report data, and select Go To, Related Links. 11. Go to the Custom Rank Sample report, right-click on a cell in the cross-tab, and select Go To. A list of possible targets for the package and the data that is in scope appears, including the Actual vs. Planned Revenue report. 12. Click the Actual vs. Planned Revenue, and the report runs using the context you selected.

Administration and Security Guide 415

Chapter 28: Drill-through Access The drill-through definition that you have created should be identical to the sample definition MeasureDrill. You can also try the following: In the drill-through definition, change the prompt settings for the target report. In the Sales and Marketing (cube) package, create a report that does not use the Revenue measure, and confirm that the Actual vs Planned Revenue report is no longer available as a drill-through target. A sample drill-through definition also exists for the same target report, Actual vs. Planned Revenue, from the PowerPlay Studio report Revenue by Order Method. If you use PowerPlay Studio, check the source and target reports and try to recreate the drill through definition. If you have permission to debug drill through definitions, then you can view the parameters passed from the source (View passed source values) and available in the target (from the drop down beside the target report name, select View Target Mapping).

Example - Drill Through from an OLAP Report to a DMR Report

You want to drill through from an Analysis Studio report named Top 10 Promotions by Retailers, based on the package Sales and Marketing (cube) to a Report Studio report named Promotion Plan Revenue, based on the package Sales and Marketing (conformed). You set the drill-through definition up in the package, so that the Promotion Plan Revenue report is available to any report based on the source package, and you use dynamic drill through, instead of defining parameters. You must have the IBM Cognos 8 BI samples from the deployment zip file Cognos_DrillThroughSamples installed to follow this exercise. By default, the samples are installed in the Public Folders in IBM Cognos Connection.

416

Chapter 28: Drill-through Access

The target report shows data for the context of the source: Campaign. Other context, such Time, i s not used by the target.

Steps to Check the Target and Source Reports

1. Run the target report: In IBM Cognos Connection, go to the Sales and Marketing (conformed) package, and open the folder Report Studio Report Samples. Run Promotion Plan Revenue in Cognos Viewer.

2. Note what information is available in the target, and how you will filter it. In this example, you filter on the campaign name. 3. Close the target report Promotion Plan Revenue. 4. Open the source report: In IBM Cognos Connection, go to the Sales and Marketing (cube) package and open the Analysis Studio Report Samples folder. Select Top 10 Promotions by Retailer, and open it in Analysis Studio. Note the names of the dimension and level that you want use to drill through. In this example, you will drill through on Campaign.

Administration and Security Guide 417

Chapter 28: Drill-through Access 5. Keep the Top 10 Promotions by Retailer report open for testing.

Steps to Create and Test the Drill-through Definition

1. In IBM Cognos Connection, navigate to the Sales and Marketing (cube) package. 2. From the upper right-hand corner of the screen, click Launch, Drill-through Definitions. 3. Click New Drill-through Definition in the upper right hand corner of the screen. Tip: If you dont see the New Drill-through Definition button, check that you are at the root of the folder, and not still in the Analysis Studio Report Samples folder. 4. In the Drill-through Definition wizard, type the name "Drill Through to Promotion Plan Revenue" and a description if you want, and click Next. Tip: This is the name that users see in the Go To page, for example when they have to select from more than one drill-through target. As with any other object in IBM Cognos Connection, you can create translations of this name. 5. Click Set the scope, and set the scope to Campaign, in the Promotions dimension. This drill-through definition will only be available when Campaign is part of the selection context. 6. Click Select the target, and set the target report to Promotion Plan Revenue, in the Report Studio Report Samples folder of the Sales and Marketing (conformed) package, click OK, and then click Next. Note: If PowerPlay Studio is available in your installation, then you must also specify that the target is a report and not a PowerCube package. 7. Under Action, select Run the report using dynamic filtering. 8. Under Parameter mapping, in the Source metadata item column for the parameter pcampaign, click map to metadata. 9. In the screen that appears, click Promotions and select Campaign. 10. Click Finish to save the drill-through definition. You can edit the properties of the drill-through definition at any time. 11. From IBM Cognos Connection, run the Analysis Studio report Top 10 Promotions by Retailers and test the drill-through definition. The target report appears, filtered by the context you selected. The drill-through definition that you created should be identical to the drill-through definition DrillToDMR. The sample drill-through definition PPStoHidden also goes from an OLAP to a DMR package, from the PowerPlay Studio report Top 20 Product Brands.

418

Chapter 28: Drill-through Access

Debugging a Drill-through Definition

IBM Cognos 8 includes a debugging functionality that you can use to find problems with your drillthrough definitions created in IBM Cognos Connection, and to correct any drill-through errors. It can also help you understand how the drill-through functionality works, especially across different types of data sources. This functionality is also referred to as the drill-through assistant. You can also debug drill-through definitions that were created in a PowerCube and migrated to IBM Cognos 8. If your target report is not receiving any parameters, check the mapping in your drill-through definition, and ensure that your parameters were created against the correct data type for your drillthrough scenario. For example, if you want to create a drill-through definition from an OLAP package to a target report based on a relational package, your target parameters need to be set up to a query item that has the same value as the OLAP business key or the member caption. For more information, see "Members and Values" (p. 404). If your target report is being filtered with the wrong values, check the values that are being mapped from the source to the target. You must have the necessary permissions to use the drill-through assistant. The information that the drill-through assistant provides is available from the Go To page, when you run the drill-through. The drill-through assistant provides the following information.

Passed Source Values

The source values are the values from the selection context that are available for passing to the target report when the user chooses to drill through to the target report or object. For example, if you drill through from a source in Analysis Studio, you see the values at the intersection you selected prior to the drill-through action, and any values in the context area. The values in the debug list are the values in the source report that were transformed by any drillthrough operation. Display Value Shows the value that users see when using this data item or this member. For OLAP members, this is the member caption or label. For example: Telephone is a member from the Order
Method dimension.

Use Value Shows the value that IBM Cognos reports and analyses use when retrieving the data item or the member. For OLAP members, this is the member unique name (MUN). For example:
[great_outdoors_company].[Order Method].[Order Method].[Order Method1]->: [PC].[@MEMBER].[2] is the MUN for the Telephone member in the Order Method dimension.

Target Mapping
If you chose to use parameters in the target, then the target mapping shows the name of each parameter that was mapped in the drill-through definition, and the values that the source is attempting to pass to that parameter. Parameter Name

Administration and Security Guide 419

Chapter 28: Drill-through Access Shows a list of valid target parameters mapped in the drill-through definition to receive information from the query item, level, or hierarchy on which you performed the drill-through action. You can see only parameters for which there is a valid mapping and only the names of the parameters. For example, if the target report contains a parameter for Product Type and the drill-through definition maps that target parameter to the source Product Type level metadata, you see this target parameter only if you attempt to drill through on the Product Type level in the source report. Drilling through on the Product Line level does not display this parameter target. You must ensure that the target parameters in your drill-through definitions are mapped correctly. Incorrectly mapped parameters can receive information from the wrong source metadata, especially where you have data values that are not unique. If you cannot see any target parameters or the parameters you expected to see in the View Target Mapping list, check the parameter mapping in the drill-through definition. Display Value Shows the value that users see when using a data item or member. For OLAP members, this is the member caption or label. For example: Telephone is a member from the Order Method dimension Use Value Shows the transformed value that the drill-through definition uses when passing a data item value or member to the target parameter. OLAP members passed to relational target parameters obtain the business key from the members MUN and pass only the business key. Using the above example of the Telephone member in
Order Methods, the business key is 2. If you are unsure of what the business key is for a

member, you can write a Report Studio expression such as roleValue('_businessKey',

[member]). This value is passed to the target parameter.

OLAP members passed to a target parameter based on another OLAP package of the same OLAP type show a transformed MUN. Using the above Order Methods example, the MUN is now transformed and the drill-through definition uses the value of [great_outdoors_
company].[Order Method].[Order Method].[Order Method1]-> [Order Method1]. [2]:[PC].[@MEMBER].[2]. The middle portion of [Order Method1][2] is where the drill-

through definition finds the correct member in the target when the OLAP data sources are different. To see the MUN for a specific member, you can look at the properties of the member in Report Studio (Professional authoring mode) and look at the Member Unique Name property.

Access the Drill-through Assistant

You can use the drill-through assistant for debugging purposes when you work with drill-through definitions in IBM Cognos Connection.

420

Chapter 28: Drill-through Access To use this functionality, you must have the required permissions for the Drill-Through Assistant secured function in IBM Cognos Administration (p. 221).

Steps
1. Select a link in your source report, right-click the link, and select Go To, or from PowerPlay Studio, click the drill-through button. The Related links page appears, showing the list of available target reports. If your target report is not shown, review the scope settings in your drill-through definition. Tip: If only one target is available, then when you select Related links, the target is opened without showing the Go To page. 2. Click View passed source values to see the values that are available for passing by the source report. 3. Next to the target report, click the down arrow and choose View Target Mapping. A list of the valid mapped data appears, showing the available source values, and the use and display values. 4. For either set of values, click More information to see the XML for the selection context (passed source) or the drill-through specification (target mapping.

Example - Debugging a Drill-through Definition

Your OLAP source has a Products dimension with the levels Line, Type, and Name. You have defined a parameter in your relational target to match each level of that OLAP source dimension. You can have a situation where you see all target parameters from a single dimension displayed in the View Mapped Target list. This is likely because the individual target parameters are mapped to a single dimension in the drill-through definition, in this case the Products dimension. In your OLAP data source, you have a business key value, or the source value used to create the members, that is duplicated in all three levels.

Parameter Name
Prod Line Param Product Type Param Product Name Param

Display Value
Camping Equipment Cooking Gear Trail Chef Water Bag

Use Value
1 1 1

Having all three parameters mapped to the Products dimension is correct if the use values are not duplicated in the dimension. In the above table, you can see that members from all three levels have the same use value. In this case the drill-through operation cannot determine which level is the correct one because the scenario indicates that all levels are valid. In this situation, the first level encountered with a valid business key or use value is fulfilled by the drill-through definition. This can result in unexpected behavior.

Administration and Security Guide 421

Chapter 28: Drill-through Access This example shows why it is important to always ensure that your data warehouses and OLAP sources are designed with unique business keys or source values. To correct this situation, the drillthrough definition should have each individual target parameter mapped to each associated level in the source metadata rather than in the dimension.

Set Up Drill-through Access in a Report

Use Report Studio (Professional authoring mode) to create a source drill-through report to link two reports containing related information. You can then access related or more detailed information in one report by selecting a value or multiple values in the source report. You can also drill through within the same report by creating bookmarks. For more information, see the Report Studio Professional Authoring User Guide. Tip: To use a Report Studio report as a source in a drill-through definition in IBM Cognos Connection, the option Allow package based drill-through must be selected (Data menu,Drill Behavior). This option is selected by default.

Steps to Create a Parameter in the Target

1. In Report Studio (Professional authoring mode), open the target report. 2. Create a parameter that will serve as the drill-through column or that will filter the report. For example, to drill through or filter Product line, create the following parameter: [Product line]=?prodline_p? Tip: Use the operators in or in_range to enable the target report to accept multiple values or a range of values. 3. In the Usage box, specify what to do when a value for the target parameter is not passed as part of a drill through: To specify that users must select a value, click Required. If a value for the target parameter is not passed, users are prompted to choose a value. To specify that users do not need to select a value, click Optional. Users are not prompted to choose a value and so the value is unfiltered. To specify not to use the parameter, click Disabled. The parameter is not used during the drill-through. It will also not be used in the report for any other purposes. Tip: If the parameter is needed in the report for other reasons, then you can also specify not to use it in the drill-through definition (Parameters table, Method, Do not use parameter). The drill-through text appears as a blue hyperlink in text items in the non-chart areas of the report. Report consumers can also start the drill-through action by clicking the Go To button or by rightclicking the item and clicking Go To, Related links. If you have the necessary permissions, you can

422

Chapter 28: Drill-through Access view which parameters were passed from the source and how they are mapped in the target object from the Go To page using the drill-through assistant. For more information, see the IBM Cognos Administration and Security Guide.

Example - Drill Through to a Hidden Report from a Report Studio Report

You want to set up a drill-through link from an employee satisfaction report created in Report Studio to a hidden list report about compensation, also created in Report Studio. The source report (Employee Satisfaction 2006) is based on the package GO Data Warehouse (analysis) which is modeled on a DMR data source. The target report (Compensation (hidden)) is based on the package GO Data Warehouse (query). You set up this drill-through connection from within Report Studio (report-based, or authored drill through) because you do not want to make a report about compensation available for drill through from any source report in the package. The target report is already hidden in the portal, so that it is unlikely to be run by anyone who does not use the drill through link. You must have the IBM Cognos 8 BI samples from the deployment zip file Cognos_DrillThroughSamples installed to follow this exercise, and you must have access to Report Studio, Professional authoring mode. The Compensation report is a hidden report. You may be able to set whether hidden reports are visible (My Preferences, General tab) and whether you can hide reports. This capability is set by your administrator.

Steps to Check the Target Report

1. Open the target report: In IBM Cognos Connection, go to Public Folders, GO Data Warehouse (query), Report Studio Report Samples. Locate the report Compensation (hidden) and open it in Report Studio. Tip: If you dont see the report, go to IBM Cognos Connection and confirm that you can view hidden reports (My Preferences, General tab). 2. In Report Studio, from the Data menu, click Filters and check what filter parameters are available. You want to filter from the source report on department, not time, so you will only use the pPosition parameter in the drill-through definition. 3. In the report body, select the list column body Position-department (level 3) and review the data item properties. Because the drill-through definition goes from DMR to relational, the data item values will need to match.

Administration and Security Guide 423

Chapter 28: Drill-through Access 4. Close the Compensation (hidden) report.

Steps to Create and Test the Drill-Through Definition

1. Open the source report: In IBM Cognos Connection, go to Public Folders, GO Data Warehouse (analysis), Report Studio Report Samples. Locate the Employee Satisfaction 2006 report and open it in Report Studio.

2. Save the Employee Satisfaction 2006 report with a new name, such as Employee Satisfaction 2006 New. This is to keep the original report and drill-through definition intact for comparison. 3. In the table Employee rankings and terminations by department, select the column Positiondepartment (level 3). 4. In the properties pane, review the data item properties, to confirm that the data item names match values in the target report. 5. In the properties pane, under Data, double-click Drill-through definitions. 6. Select the definition DrilltoHiddenRep and delete it. Note: In the following steps, you recreate the drill-through definition. For comparison, use the original sample report. 7. In the Drill-through Definitions box, click the new drill-through definition button. 8. Click the rename button, and type a name for the drill-through definition. Tip: This is the name that consumers see when they select from a list of possible drill-through definitions in the final report. 9. In the Target Report tab, select the target report: Under Report, click the ellipsis button (...). Navigate to GO Data Warehouse (query), Report Studio Report Samples, and select the Compensation (hidden) report. Tip: If you dont see the report, go to IBM Cognos Connection and confirm that you can see hidden reports (My Preferences, General tab). 10. Under Action, select Run the report. 11. Under Parameters, click the edit button. A table of parameters available in the target report appears, showing the parameter pPosition. 12. Map the parameter from the Compensation (Hidden) report to the metadata in the Employee Satisfaction 2006 report: In the Method column, select Pass data item value, because the target report is based on a relational data source.

424

Chapter 28: Drill-through Access In the Value column, select Position-department (level 3). Tip: In this report, you pass values from the column where the drill-through is defined. In other cases, you might pass a related parameter. For example, you could drill through on employee name, but pass the employee number. 13. Save the report. 14. Run the report, and click a department to test the drill-through definition. When you test the drill-through link, the Compensation (hidden) report appears, filtered by the department you selected. The report appears as a drill-through target whether or not it is hidden in IBM Cognos Connection. If your administrator has given you the capability to debug drill through, then you can see additional information you right-click on the link and select Go To see a list of drill-through targets. From the Go To page, you can see what source values are passed, and what target parameters are mapped.

Specify the Drill-through Text

You can specify the drill-through text that appears when users can drill through to more than one target. For example, if users from different regions view the report, you can show text in a different language for each region.

Steps
1. Right-click the drill-through object and click Drill-Through Definitions. 2. If more than one drill-through definition exists for the object, in the Drill-Through Definitions box, click a drill-through definition. 3. Click the Label tab. 4. To link the label to a condition, in the Condition box, do the following: Click Variable and click an existing variable or create a new one. Click Value and click one of the possible values for the variable.

5. In the Source type box, click the source type to use. 6. If the source type is Text, click the ellipsis (...) button beside the Text box and type text. 7. If the source type is Data Item Value or Data Item Label, click Data Item and click a data item. 8. If the source type is Report Expression, click the ellipsis (...) button beside the Report Expression box and define the expression. 9. If the label is linked to a condition, repeat steps 5 to 8 for the remaining possible values. When users run the source report and click a drill-through link, the Go to page appears. The drillthrough text you specified appears for each target. If you did not specify the drill-through text for a target, the drill-through name is used.

Administration and Security Guide 425

Chapter 28: Drill-through Access

Setting Up Drill-through Access from IBM Cognos Visualizer

Setting up drill-through access from IBM Cognos Visualizer to IBM Cognos 8 involves specifying the IBM Cognos 8 target and selecting the filters to add to the target report You must configure drill through to IBM Cognos 8 for individual IBM Cognos Visualizer reports. For more information, see the IBM Cognos Visualizer User Guide. creating and testing the target report (p. 426)

Setting Up Drill-through Access from PowerPlay Web

Setting up drill-through access from PowerPlay Web to IBM Cognos 8 involves for PowerCubes, specifying drill-through targets for IBM Cognos 8 reports in the Transformer model For more information, see the Transformer documentation. for other cubes, specifying drill-through targets for IBM Cognos 8 reports in PowerPlay Connect. For more information, see the PowerPlay OLAP Server Connection Guide. configuring drill-through access in PowerPlay Server Administration In addition to enabling drill-through access to IBM Cognos 8, you must specify the location of the IBM Cognos 8 server and the IBM Cognos 8 folder that contains the target reports. For more information, see the PowerPlay Enterprise Server Guide. selecting the filters to add to the target report In PowerPlay Enterprise Server Administration, enable and use IBM Cognos 8 Assistance to identify the filter expressions required in the target report. For more information, see the PowerPlay Enterprise Server Guide. creating and testing the target report (p. 426)

Create and Test the Target for a Series 7 Report

The target report must be based on a published package that contains the metadata items that you want to filter on, or contains items that are mapped to those metadata items. When you create the target report, ensure that the names of the parameters you add are identical to the parameter names listed in the Drill Through Assistant page in IBM Cognos Series 7. However, the metadata item that you use in the target report for that parameter name does not have to be the identical label. The data values between the target parameter and the source value shown in the drill assistant must match. You may also need to change the type of operator in the target parameter from what is recommended in the Drill Through Assistant. For example, if the assistant recommends

426

Chapter 28: Drill-through Access an = operator but you want to pass a date range, you should change the parameter operator in the target to in_range.

Steps
1. Start Report Studio (Professional authoring mode) and create a new report. 2. Add the data items and other objects you want. 3. From the Data menu, click Filters. 4. In the Detail Filters tab, click the add button. 5. In the Expression Definition box, create the parameterized filter you want by typing the filter expression. 6. Click OK. 7. In the Usage box, click Optional. If you do not make the filter optional, a prompt page appears when you drill through to the report. 8. Repeat steps 4 to 7 for other parameterized filters you want to add. 9. Save the report. The report name must match what you specified as a target in the PowerCube, other cube, or IBM Cognos Visualizer report. 10. Test the drill through in the PowerPlay report or IBM Cognos Visualizer report.

Administration and Security Guide 427

Chapter 28: Drill-through Access

428

Chapter 29: Managing Portlets and Styles

Portal administration in IBM Cognos 8 includes managing portlets (p. 429) and styles (p. 437). Typically, these tasks are performed by portal administrators (p. 234). To access the portal administration area in IBM Cognos Administration, you must have execute permissions for the Styles and portlets secured feature, and traverse permissions for the Administration secured function (p. 221). For information about troubleshooting, see the Troubleshooting section in this guide. For information about configuring portal services, see the Installation and Configuration Guide.

Portlets
A portlet is a mechanism for displaying Web content as part of a portal page. The portlets supported by IBM Cognos Connection include Cognos portlets (p. 429) and other portlets (p. 432). The Cognos portlets are available to users by default. If you want to make other portlets available, you must import them. Managing portlets involves the following tasks: Importing portlets (p. 432) Controlling access to portlets (p. 433) Configuring the portlet cache (p. 434) Modifying portlets (p. 435)

As an additional task, you may want to change the dispatcher settings to allow the HTML code to be executed in RSS Viewer and Cognos Navigator (p. 436). For information about using portlets in IBM Cognos Connection pages, see "Pages and Dashboards" (p. 267).

Cognos Portlets
Portal Services provides portlets that users can add to their personal pages in IBM Cognos Connection (p. 267), or in an existing enterprise portal (p. 441). All Cognos portlets conform to the Web Services for Remote Portlets (WSRP) standard. Users can interact with the portlets without installing IBM Cognos products on their computers. The content that appears in the portlets, such as reports, or metrics, and the ability to perform specific actions on that content depend on the users access permissions. Users must have the required access permissions for the individual entries and for the IBM Cognos 8 secured functions and features. For more information, see "Secured Functions and Features" (p. 221). The following portlets are available.

Administration and Security Guide 429

Chapter 29: Managing Portlets and Styles

Cognos Content Portlets

These portlets provide IBM Cognos content in IBM Cognos Connection or in your existing enterprise portal. By default, these portlets are available in IBM Cognos Administration. They can also be deployed to other portals. The following portlets are available in this group:

Portlet
Cognos Navigator (p. 717)

Description
Shows the IBM Cognos Connection folder hierarchy. Users can browse the hierarchy and open IBM Cognos 8 entries. Provides a search tool to help users find published IBM Cognos reports and other entries, and open them. Opens a default report or lists reports that users can open.

Cognos Search (p. 719)

Cognos Viewer (p. 721)

Cognos Utility Portlets

The Cognos Utility portlets provide additional functionality for pages in IBM Cognos Connection. By default, these portlets are available in IBM Cognos Administration. However, they cannot be deployed to other portals. The following portlets are available in this group.

Portlet
Bookmarks Viewer (p. 732) HTML Viewer (p. 733)

Description
Registers and shows active Web links. Inserts any Web page into an IBM Cognos Connection page. Inserts an image and shows it in a page. Shows the content of a Real Simple Syndication (RSS) 1.0 or 2.0 news feed. RSS is a format for syndicating news and is used by many Web sites. An RSS news feed is specified by a URL address.

Image Viewer (p. 734) RSS Viewer (p. 735)

HTML Source (p. 737)

Use to add custom text and images to a page.

The Cognos Extended Applications Portlet

The Cognos Extended Applications portlet (p. 726) provides access to custom applications created using the Cognos Extended Applications toolkit and the IBM Cognos 8 Software Development Kit. If IBM Cognos 8 Software Development Kit is installed, this portlet is automatically registered and available in IBM Cognos Administration. It can also be deployed to other portals.

430

Chapter 29: Managing Portlets and Styles For information about creating extended applications, see the Developer Guide.

Cognos Metrics
Cognos Metrics provide the capability to view performance metrics in a page. The metrics are created using Metric Studio. If Metric Studio is installed, these portlets are automatically registered and available in IBM Cognos Administration. They can also be deployed to other portals. The following portlets are available in this group:

Portlet
Metric List (p. 726)

Description
Use to add performance metrics to a page. You can configure the portlet to show the following types of metric lists: Watch list Contains the metrics that a user wants to monitor closely. Accountability list Contains the metrics that a user owns. Scorecard metric list Contains metrics associated with a scorecard. Strategy metric list Contains metrics associated with a strategy. To show the metrics grouped by scorecards, select the Apply a scorecard filter check box.

Metric History Chart (p. 728)

Use to add a metric history chart to a page. The history chart is a graphical illustration of the historical performance of a metric. Use to display impact diagrams associated with a metric. Use to display custom diagrams associated with a scorecard.

Metrics Impact Diagram (p. 730) Metrics Custom Diagram (p. 731)

For more information, see the Metric Studio User Guide.

Dashboard Portlets
The dashboard portlets provide the framework and content for the dashboard pages in IBM Cognos Connection.

Administration and Security Guide 431

Chapter 29: Managing Portlets and Styles

Portlet
Multi-page (p. 738)

Description
Use to create a dashboard with multiple pages.

Other Portlets
The other portlets include non-Cognos portlets that conform to the Web Services for Remote Portlets (WSRP) standard, such as Oracle portlets, or Sun portlets. Verification and support for these remote portlets may be incomplete because WSRP is a new standard for remote portlets that is still in the process of implementation by many vendors. The single signon for other portlets may not be available because this functionality is outside the scope of the WSRP standard. Other portlets must be imported into IBM Cognos Connection (p. 432).

Import Portlets
You can import non-Cognos portlets (p. 432) into IBM Cognos Connection if the portlets conform to the WSRP standard. This procedure is not necessary for Cognos portlets because they are automatically registered and available in IBM Cognos Connection if the applicable IBM Cognos component, such as Metric Studio or Software Development Kit, is installed.

Steps
1. In IBM Cognos Connection, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Portlets. 3. Click the import portlets button .

The Specify a producer page appears. 4. Choose the producer Web service. If a Web Services Description Language (WSDL) definition file exists, in the Web Service Description box, type its URL address. Here is an example: http://wsrp.netunitysoftware.com/WSRPTestService/WSRPTestService. asmx?Operation=WSDL If a WSDL definition file does not exist, click Web Services for Remote Portlet (WSRP) interfaces, and type the URL required by the portlet producer. Tip: To import the Cognos portlets, click IBM Cognos producer, and choose the available group. 5. Click Next.

432

Chapter 29: Managing Portlets and Styles 6. If the Specify the registration properties page appears, provide the registration information as required, and click Next again. 7. In the Specify a name and description page appears, do the following: Type a name and, if you want, a description and a screen tip for the portlet group. Choose the portlets to import by selecting or clearing the check boxes next to the portlets. Click Finish.

The portlet group appears on the Portlets tab.

Control Access to Portlets

You can control access to portlets by setting access permissions to specify which portlets are available to which users and what kind of actions the users can perform on a specific portlet. You can set access permissions individually for each portlet, or at the group level. To add a portlet to a page and access its content, end users need read, execute, and traverse permissions for the portlet. You can restrict access to portlets temporarily by disabling (p. 253) them. This may be required when you want to update the portlet producer or modify the portlet settings. When users try to access a disabled portlet from their page, they see a message. You can also lock the portlet if you do not want users to see the edit button in the portlet. As a result, users cannot see the portlet properties and cannot modify them (p. 435).

Steps to Set up Access Permissions

1. In IBM Cognos Connection, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Portlets. 3. Decide whether to set access permissions at the group level, or for each portlet individually. 4. To set permissions for a portlet group, click its properties button in the Actions column and, on the Permissions tab, specify the permissions as required. 5. To set permissions for a specific portlet, click the associated portlet group and, for the portlet you want, click its properties button in the Actions column and specify the permissions as required. For more information, see "Access Permissions" (p. 213) 6. Click OK.

Steps to Lock a Portlet

1. In IBM Cognos Connection, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Portlets. 3. Click the appropriate portlet group.

Administration and Security Guide 433

Chapter 29: Managing Portlets and Styles

4. In the Actions column, click the lock icon

associated with the portlet you want to lock.

Alternatively, click the More link, and then click Lock portlet settings. The icon changes to locked.

Configure the Portlet Cache

Portal Services can cache the portlet markup fragments that are used to quickly regenerate recent views of the portlets in pages. These markup fragments are compressed and stored on the server computer as part of the session object. The basic cache unit represents markup fragments created per page, per one user session. The portlet markup is not always cached. Disabling markup caching saves memory usage, but has a negative impact on performance. Use the following parameters to control the use of the portlet cache at run-time: CPSMaxCacheSizePerPortlet Specifies the number of markup fragments cached for each portlet, per page, per user. For example, a value of 5 with 1000 users, 10 pages, and 4 portlets per page can generate a maximum of 200000 entries in the cache (1000 x 10 x 4 x 5). This parameter can have the following values:

Parameter
-1 (default) 0 1 or an integer greater than 1

Value
Saves unlimited number of portlet markups Disables markup caching Limits the number of markups to a specified number

You must provide run-time values for this parameter for every application server that runs the presentation service. properties.config.cps.cache.timeToIdleSeconds Specifies the length of time, in seconds, to keep the page markup fragments in the cache during a period of inactivity. If the page is not accessed during that time, its cache contents are deleted. The default value is 1800 (30 minutes). properties.config.cps.cache.timeToLiveSeconds Specifies the length of time, in seconds, to keep the page markup fragments in the cache. After this time, the markup is deleted even if the cache is still active. The default value is 86400 (24 hours). properties.config.cps.cache.checkExpiryIntervalSeconds

434

Chapter 29: Managing Portlets and Styles Specifies the length of time, in seconds, that represents the frequency with which the system checks for expired markup fragments in the cache. The default value is 300 (5 minutes). To enable or disable encryption of the portlet markup fragments, use the parameter encryptTemporaryFiles of the Environment category in IBM Cognos Configuration. For more information, see the IBM Cognos Configuration User Guide.

Steps
1. In IBM Cognos Connection, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Dispatchers and Services. 3. Click the dispatcher you want. 4. For PresentationService, click the set properties button. 5. Click the Settings tab. 6. For the Environment category, next to Advanced settings, click the Edit link. 7. If it appears, select the Override the settings acquired from the parent entry check box. Otherwise, proceed to the next step. 8. In the Parameter column, type the required parameter specified in this section. For example, type CPSMaxCacheSizePerPortlet. 9. In the Value column, type the required value for the parameter. 10. Click OK. 11. Click OK again. 12. Click the Configuration link in the path at the top of the page. You return to the list of dispatchers. 13. If you have more than one dispatcher configured, perform steps 3 to 12 for each remaining dispatcher. 14. Restart the IBM Cognos 8 service.

Modify a Portlet
You can define the default content and appearance of portlets. The settings become the default for all users who use the portlet. You can lock the portlet for editing if you want to prevent other users from changing the settings. If the portlet is not locked for editing, users can change their instance of the portlet. They retain their custom settings even if you reset the portlet. Users inherit the settings you configure when they use the portlet instance you configured, or when they reset their portlet instance using the reset button in the portlet edit mode.

Administration and Security Guide 435

Chapter 29: Managing Portlets and Styles Applications that appear in the Cognos Extended Applications portlet may include editable application parameters with default values defined by the developer. To change the parameter values that users see as defaults, you must edit the applications.xml file. For information about modifying application parameters, see the Developer Guide. The configurable properties for the Cognos portlets vary. For more information, see "User Reference Help for Portal Services" (p. 717).

Steps
1. In IBM Cognos Connection, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Portlets. 3. Click the portlet group you want. 4. Next to the portlet you want to modify, click the More link. 5. Click View and customize this portlet. The Cognos portlet appears. 6. In the portlet toolbar, click the edit button . , which

When you modify the Cognos Content portlets, you can use the configure button gives you access to additional functionality. The portlet properties page appears. Tip: To exit the properties page without saving the changes, click the return button title bar or click Cancel. 7. Change the portlet properties as required. Tip: To restore the default settings, click the reset button 8. Click OK. .

in the

Display the HTML Code From the Source RSS Feed in RSS Viewer and Cognos Navigator
Some RSS channels contain HTML code sequences as part of their title and description fields. For security reasons, the HTML code, if present in the source RSS feed, is disabled in the news list view in the portlets RSS Viewer and Cognos Navigator. Instead, a series of HTML control characters is displayed in the title and description fields of both portlets. You can override this setting and allow the HTML code to be executed in RSS Viewer and Cognos Navigator to display the code as intended by the publisher of the RSS feed. To do that, specify the CPSRssAllowUnsafeCharacters run-time parameter with a value of "true" for the dispatcher presentation service. The default value for this parameter is "false".

436

Chapter 29: Managing Portlets and Styles Warning: Allowing execution of the HTML code from external sources represents a security threat.

Steps
1. In IBM Cognos Connection, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Dispatchers and Services. 3. Click the dispatcher you want. 4. For the PresentationService, in the Actions column, click the set properties button. 5. Click the Settings tab. 6. For the Environment category, next to Advanced settings, click the Edit link. 7. If it appears, select the Override the settings acquired from the parent entry check box. 8. In the Parameter column, type the parameter CPSRssAllowUnsafeCharacters 9. In the Value column, as a value for this parameter, type true 10. Click OK. 11. Click OK again. 12. Click the Configuration link in the path at the top of the page. You return to the list of dispatchers. 13. If you have more than one dispatcher configured, perform steps 3 to 12 for each remaining dispatcher.

Styles
A style is a defined set of resources, such as images and cascading style sheets, that controls the appearance of the IBM Cognos 8 Web interface. The branding images and fonts are also part of the style. The resources for the styles are located in the c8_location/webcontent/skins directory. The following predefined styles are available in IBM Cognos 8:

Style
business classic contemporary corporate

Description
Uses soft colors. Creates clean and simple, professional look. Matches the style used by Metric Studio. Uses bolder, more vivid colors. Matches the IBM Cognos corporate branding. This is the default style in IBM Cognos 8.

Administration and Security Guide 437

Chapter 29: Managing Portlets and Styles

Style
modern presentation

Description
Matches the style used by IBM Cognos ReportNet. A variation of the corporate style. Uses larger fonts and increased contrast. Intended for projections.

If the predefined styles do not meet your requirements, you can create your own style and make it available in IBM Cognos 8 (p. 480). At run time, individual users can choose any of the available styles to use in their Web interface (p. 260). Ensure that all users have access to at least one style. The initial style settings for new users are determined by the default user profiles. For information about changing the user profiles, see "Managing User Profiles" (p. 339). Managing styles involves: Adding new styles (p. 438) Controlling access to styles (p. 439) Modifying styles (p. 440)

Add a New Style

You add a new style to create the style object in Content Manager and to associate it with the style resources in the product directory. Use this functionality to add a custom style or to create different styles based on the existing style resources. For example, you can add a new style named blue and associate it with the corporate style resources in the c8_location/webcontent/skins/corporate directory. Before you can add a custom style, the style resources must exist in the c8_location/webcontent/skins directory. For more information about customizing styles, see "Customizing Styles" (p. 479).

Steps
1. In IBM Cognos Connection, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Styles. The new style wizard appears. 3. Click the new style button .

4. Type a name for the style and, if you want, a screen tip and description. The style name can be any word or phrase you want. It does not need to match the name of the product directory where the style resources are located. Tip: You can specify the style name, description, and screen tip only in the product language you currently use. To specify these values for different languages, you can later modify the style (p. 440).

438

Chapter 29: Managing Portlets and Styles 5. Click Next. 6. Specify the location of the style resources: In the Style location name box, type the name of the style directory where the style resources are located. You can specify one of the predefined style directories, such as corporate, classic or modern, or a custom directory, if it exists. In the Preview image URL box, type the URL address where the preview resource for the style is located. An example of a preview resource can be a Web server page, a video, or an image. 7. Click Finish.

Control Access to Styles

Users may need to use different styles in their Web interface depending on the company branding requirements, locale, or product implementation. For example, the styles for Asian users may have specific characteristics that do not apply to users in other geographical locations. Therefore, these styles can be hidden from non-Asian users. You can control access to styles by setting access permissions on them. To make a style available to end users, you grant execute permissions for the required users, groups, or roles. No other permissions are needed. As a result, the style appears in the users preferences in IBM Cognos Connection (p. 260). Users can use the style, but they cannot modify it. Read, write, or set policy permissions can be granted for administrator users. Traverse permissions are irrelevant in relation to styles. For more information about security, see "Access Permissions" (p. 213).

Steps
1. In IBM Cognos Connection, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Styles. 3. Click the properties button for the style you want. 4. Click the Permissions tab. 5. Select the Override the access permissions acquired from the parent entry check box. 6. Grant the required type of access permissions. For end users, grant execute permissions for the users, groups, or roles you want to have access to this style. For administrators, grant read, write, or set policy permissions.

For more information, see "Set Access Permissions for an Entry" (p. 216).

Administration and Security Guide 439

Chapter 29: Managing Portlets and Styles

Modify a Style
You can modify an existing style to change the style name, description, and screen tip You can rename any of the predefined or custom styles to use style names that are more appropriate for your Web interface. add, change, or remove the style name, description, and screen tip for different language versions of the product You may want the style name, description, and screen tip match the users product language. change the style directory You can associate an existing style with a different style directory in c8_location/webcontent/skins. You may need to do this when, for example, the names of the style directories change as a result of the product translation into different languages. For more information about the style general properties, see "Entry Properties" (p. 243)

Steps
1. In IBM Cognos Connection, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Styles. 3. Click the properties button for the style you want. 4. On the General or Styles tab, modify the properties as required. 5. Click OK.

440

Chapter 30: Deploying Cognos Portlets to Other Portals

You can deploy Cognos portlets to your existing enterprise portal so that you can present the Cognos content in your portal instead of IBM Cognos Connection. You can deploy the Cognos portlets to the following portals: IBM WebSphere 5.0, 5.1, 6.0, and 6.1 (p. 441) SAP Enterprise Portal 6.0, 6.4 and 7.0 (p. 445) BEA AquaLogic User Interaction 6.1 and 6.5 (ALUI 6.1 and 6.5) (p. 449) Microsoft SharePoint Portal Server 2003 and 2007 (p. 454)

If you want to use the ReportNet 1.1 portlets in IBM Cognos 8, you may need to upgrade them (p. 464). By default, the root name of file paths in the portlets is Cognos. You can change the root name (p. 464). As an additional security measure, you can disable the mechanism to transfer the IBM Cognos 8 passport ID as a URL parameter between users' browsers and the IBM Cognos 8 gateway (p. 465). After you deploy the portlets, you can enable single signon between the portlets and your portal (p. 467). Notes In SAP Enterprise Portal, portlets are named iViews. This document may refer to iViews as portlets. In Microsoft SharePoint Portal Server, portlets are named Web Parts. This document may refer to Web Parts as portlets.

Deploying Cognos Portlets to WebSphere Portal 5.0, 5.1, 6.0, and 6.1
Before users can add Cognos portlets to their portal pages, you must deploy the portlets to the portal server. You can deploy the following portlets: Cognos Content This group includes Cognos Navigator, Cognos Search, Cognos Viewer. Cognos Extended Applications This group includes the Cognos Extended Applications portlet.

Administration and Security Guide 441

Chapter 30: Deploying Cognos Portlets to Other Portals Cognos Metrics This group includes Metric List, Metric History Chart, Metrics Impact Diagram, and Metrics Custom Diagram. Before you start deploying the portlets, ensure that IBM Cognos 8, including IBM Cognos Connection and Portal Services, is installed and configured. For the Cognos Extended Applications portlet, IBM Cognos 8 Software Development Kit must also be installed. If IBM Cognos 8 Software Development Kit is not installed or not available, the portal administrator should disable the Cognos Extended Applications portlet after the portlet applications file is installed (p. 442). For the Cognos Metrics portlets, Metric Studio must also be installed. If Metric Studio is not installed or not available, the portal administrator should disable the Cognos Metrics portlets after the portlet applications file is installed (p. 442). You must first log on to the portal with administrator privileges. The deployment process consists of the following tasks: Installing the portlet applications file Configuring the portlet applications Configuring the portlet cache Customizing the content of Cognos portlets

After you deploy the portlets, you can configure security for your WebSphere Portal environment (p. 467). For more information, see the Installation and Configuration Guide. Note: The tasks documented in this section may vary slightly for the different versions of WebSphere Portal.

Install the Portlet Applications File

Before Cognos content can appear in any WebSphere page, you must install the portlet applications file CognosBIPortlets.war located in the c8_location\cps\ibm\portlets directory. This file contains the applications for the Cognos portlets, one for Cognos Navigator, Cognos Search, and Cognos Viewer, one for Cognos Extended Applications, and one for Metric List, Metric History Chart, Metrics Impact Diagram, and Metrics Custom Diagram. To install the portlet applications file, you must be logged on to the portal with administrator privileges, and be able to access the CognosBIPortlets.war file from your file system or network file system. If the Portal Services installation is not within your network access, you must manually move the CognosBIPortlets.war file to an accessible location. The portlet applications file can be installed only once. However, it can be updated when required.

Steps
1. At the top of the portal page, click the Administration tab.

442

Chapter 30: Deploying Cognos Portlets to Other Portals 2. From the menu on the left, click Portlet Management, Web Modules, and then click Install. Tip: To update the CognosBIPortlets.war file, click Web Modules, select the file name, and click the update web module button .

3. Click the Browse button, and, in the c8_location\cps\ibm\portlets directory, select the CognosBIPortlets.war file. 4. Click Next. 5. Click Finish. A message confirms that the portlets were successfully installed.

Configure the Portlet Applications

Configure the portlet application to specify the signon mechanism and the address of the server component for Portal Services. This must be done for all sets of Cognos portlets: the Cognos Content portlets, the Cognos Extended Applications portlets, and the Metric Studio portlet.

Steps
1. On the Administration tab, click Portlet Management, Web Modules. 2. Click the CognosBIPortlets.war file. A list of the Cognos portlet applications appears. 3. For the application you want, click the edit portlet application button The edit page appears. 4. For the Active Credential Type property, enter one of the following values to specify the single signon mechanism used in your installation. LtpaToken HttpBasicAuth SiteMinderToken WebSealToken .

For more information about configuring single signon for Portal Services, see "Configuring Security for Portal Services" (p. 467). 5. For the IBM Cognos 8 WSRP WSDL Location property, modify the URL as required to connect to the CPS server. The URL must contain the correct protocol, server name, port number, and server path. By default, the protocol is http. If IBM Cognos 8 is configured to be accessed through Secure Sockets Layer (SSL) connections, change the protocol to https. The server path must point to an IBM Cognos 8 gateway.

Administration and Security Guide 443

Chapter 30: Deploying Cognos Portlets to Other Portals For the Cognos Navigator, Cognos Search, and Cognos Viewer portlets, the path is c8_gateway/wsrp/cps4/portlets/nav?wsdl&b_action=cps.wsdl. For the Cognos Extended Applications portlet, the path is c8_gateway/wsrp/cps4/portlets/ sdk?wsdl&b_action=cps.wsdl. For the Cognos Metrics, the path is c8_gateway/wsrp/cps4/portlets/cmm?wsdl&b_ action=cps.wsdl.

6. Click OK. The Cognos portlets are now available to be added to pages by users. You can configure Cognos portlets so that their default settings are the same for all users. 7. Repeat steps 3 to 6 for the Cognos Extended Applications Portlets and the Cognos Metrics. Note: You can create the Cognos Extended Applications portlets only if IBM Cognos 8 Software Development Kit is installed. For information about creating extended applications for Portal Services, see the Developer Guide.

Configure the Portlet Cache

Portal Services caches HTML markup fragments that are used to quickly regenerate recent views of portlet pages. These markup fragments are compressed and stored in the users session object. You can configure the number of pages stored for each users portlet. The size of the markup fragment for each page depends on the complexity of the portlet, but they are typically about 5KB. By default, the cache stores ten pages for each users portlet.

Steps
1. On the Administration tab, click Portlet Management, Web Modules. 2. Click the portlet applications file CognosBIPortlets.war. 3. In the portlet applications list, click the application you want. 4. For the portlet you want to set the cache size, click the configure portlet button .

5. For the Maximum Cached Pages property, enter the maximum number of pages you want to cache. 6. Click OK. 7. Repeat steps 4 to 6 for each portlet. 8. Restart the IBM Cognos 8 service.

Customize the Content of Cognos Portlets

As an administrator, you can define the default content and appearance of portlets. When you customize a portlet instance using the configure button users who view this instance. , the settings become the default for all

444

Chapter 30: Deploying Cognos Portlets to Other Portals If the portlet is not locked for editing, users can customize the content for their instance of the portlet. Users retain their custom settings even if you reset the portlet. Users inherit the settings you configure only when they view the instance you configured, or when they reset the portlet using the reset button in the edit page of the portlet. Applications that appear in the Cognos Extended Applications portlet may include editable application parameters with default values defined by the developer. To change the parameter values that users see as defaults, you must edit the applications.xml file. For information about modifying application parameters, see the Developer Guide. The configurable properties for the Cognos portlets vary. For more information, see "User Reference Help for Portal Services" (p. 717).

Steps
1. Go to the page where you added the Cognos portlets. 2. Click the configure button 3. Edit the settings as required. These become the default settings for user instances of this portlet. 4. Click OK. for the portlet that you want to configure.

Deploying Cognos Portlets to SAP Enterprise Portal 6.0, 6.4, and 7.0
Before users can add Cognos portlets to their portal pages, you must deploy the portlets to the portal server. You can deploy the following portlets: Cognos Content This group includes Cognos Navigator, Cognos Search, Cognos Viewer Cognos Extended Applications This group includes the Cognos Extended Applications portlet. Cognos Metrics This group includes Metric List, Metric History Chart, Metrics Impact Diagram, and Metrics Custom Diagram. Before you start deploying the Cognos portlets, ensure that IBM Cognos 8, including IBM Cognos Connection and Portal Services, is installed and configured. For the Cognos Extended Applications portlet, IBM Cognos 8 Software Development Kit must also be installed. If IBM Cognos 8 Software Development Kit is not installed or not available, the portal administrator should disable the Cognos Extended Applications portlet after the IBM Cognos business package is installed (p. 446).

Administration and Security Guide 445

Chapter 30: Deploying Cognos Portlets to Other Portals For the Cognos Metrics portlets, Metric Studio must also be installed. If Metric Studio is not installed or not available, the portal administrator should disable the Cognos Metrics portlets after the IBM Cognos business package is installed (p. 446). In SAP Enterprise Portal, portlets are named iViews. Portions of this document refer to iViews as portlets. You must first log on to the portal with administrator privileges. The deployment process consists of the following tasks: Installing the IBM Cognos business package Editing properties for the iViews Setting the default iViews content and appearance

After you deploy the portlets, you must configure security for your SAP Enterprise Portal environment. For more information, see the Proven Practices on the Cognos Software Services Web site.

Notes
Portal Services in IBM Cognos 8 supports SAP portals 6.0, 6.4, and 7.0. This document describes administrative tasks for version 6.0. The tasks may vary slightly for the versions 6.4 and 7.0.

Install the IBM Cognos Business Package

The IBM Cognos business package is an Enterprise Portal Archive (.epa) file named com.cognos. pct.cognos.epa. This package contains the Cognos Navigator, Cognos Search, Cognos Viewer, Cognos Extended Applications, Metric List, Metric History Chart, Metrics Impact Diagram, Metrics Custom Diagram iViews, and the com.cognos.pct.cognos.ivew.par file. You must be logged on to the portal with administrator privileges and be able to access the com. cognos.cognos.epa file from your file system or from the network file system. If the IBM Cognos installation is not within your network access, you must manually move the com.cognos.cognos. epa file to an accessible location.

Steps
1. In the portal, click the System Administration tab. 2. On the Transport tab, click Import. 3. Next to Source for Package Files, click Client. If Client is not functional, click Server. 4. Click Browse to locate the com.cognos.cognos.epa file, and click Open. The com.cognos.cognos.epa file is located in the c8_location\cps\sap\package directory. If you clicked Server in the previous step, browse for the com.cognos.cognos.epa file in the SAP_installation\usr\sap\env\SYS\global\pcd\Import directory, where env represents a directory that is different for different environments. The com.cognos.cognos.epa file must first be copied to this directory. 446

Chapter 30: Deploying Cognos Portlets to Other Portals 5. Click Upload.

Edit Properties for the iViews

The business package includes the Cognos iViews (p. 445). Edit the properties for each iView so that they work with your IBM Cognos 8 installation. The following table shows some of the properties you may want to modify.

Property
CPS: Connection Server

Description
Represents the URL required to connect to the Portal Services server. The URL must contain the correct protocol, server name, port number, and server path. By default, the protocol is http. If IBM Cognos 8 is configured to be accessed through Secure Sockets Layer (SSL) connections, change the protocol to https. The server path must point to an IBM Cognos 8 gateway. For the Cognos Navigator, Cognos Search, and Cognos Viewer iView, the path is c8_gateway/wsrp/ cps4/portlets/nav?wsdl&b_action=cps.wsdl For the Cognos Extended Applications iView, the path is c8_gateway/wsrp/cps4/portlets/sdk?wsdl&b_ action=cps.wsdl For the Cognos Metric List and Metric History Chart iView, the path is c8_gateway/wsrp/cps4/portlets/ cmm?wsdl&b_action=cps.wsd

CPS: Configuration Mode Role

Specifies the SAP role whose members, typically administrators, can modify the default iView properties (p. 448). These users can see the link Edit the properties for all users at the bottom of the iView properties page, and use it to modify the default iView properties. Only one SAP role can be specified to modify the default iView properties. Default: content_admin_role

Steps
1. Log on to the portal with administrator permissions. 2. Click the Content Administration tab. 3. In the window on the left, on the Browse tab, expand the Portal Content folder.

Administration and Security Guide 447

Chapter 30: Deploying Cognos Portlets to Other Portals 4. Continue expanding the folders until you see Cognos iViews. By default, Cognos iViews are imported into the Portal Content, Content Provided by Other Vendors, End User Content, com.cognos.pct.cognos8, iviews folder. 5. Double-click the iView you want to modify. The Property Editor appears in the main window. 6. In the Property Category drop-down list, click Show All. 7. Edit the properties as required. 8. Click Save. 9. Repeat steps 5 to 8 for each Cognos iView. 10. If you want to test the connection between IBM Cognos 8 and Portal Services, click the Preview button.

Set the Default iView Content and Appearance for All Users
An administrator can define the default content and appearance for Cognos iViews. When end users add the iViews to their pages, the default properties are enabled. For example, in the Cognos Navigator iView, the administrator can define the default display folder or package. When users add this iView to their pages, they see the folder or package that was specified by the administrator. End users can change the Cognos iView properties to personalize their pages. Their changes do not affect iViews of other users or other pages. The personalized settings are not affected if the administrator changes the default properties for the iView. Users can click the Reset button to revert to the current administrative defaults. To change the iView properties for all users, you must be a member of the SAP role that has the required access permissions. This role is specified by the CPS: Configuration Mode Role property. For more information, see "Edit Properties for the iViews" (p. 447).

Steps
1. Log on to the portal with administrator permissions. 2. Browse to the page that contains Cognos iViews. 3. For the iView you want to modify, click the option menu button in the upper-right corner of the iView, and select Personalize. The iView properties page appears. 4. At the bottom of the page, click the link Edit the properties for all users. 5. Change the properties as required. These settings become the default settings for user instances of this portlet. 6. Click Save. 7. Repeat steps 3 to 6 for other Cognos iViews.

448

Chapter 30: Deploying Cognos Portlets to Other Portals

Deploying Cognos Portlets to ALUI 6.1 and 6.5 Portal

You can deploy Cognos portlets to the BEA AquaLogic User Interaction 6.1 and 6.5 (ALUI 6.1 and 6.5) portal server so that end users can add the portlets to their pages. You can deploy the following portlets: Cognos Content portlets This group includes Cognos Navigator, Cognos Search, Cognos Viewer Cognos Extended Applications portlets This group includes the Cognos Extended Applications portlet. Metric Studio portlet This group includes the Metric List, Metric History Chart, Metrics Impact Diagram, and Metrics Custom Diagram portlets. Before you start deploying the Cognos portlets, ensure that IBM Cognos 8, including IBM Cognos Connection and Portal Services, is installed and configured. For the Cognos Extended Applications portlet, IBM Cognos 8 Software Development Kit must also be installed. If IBM Cognos 8 Software Development Kit is not installed or not available, the portal administrator should disable the Cognos Extended Applications portlet after the Cognos portlet package file is imported (p. 452). For the Cognos Metrics portlets, Metric Studio must also be installed. If Metric Studio is not installed or not available, the portal administrator should disable the Cognos Metrics portlets after the Cognos portlet package file is imported (p. 452). You must first log on to the portal with administrator privileges. The deployment process consists of the following tasks: starting the remote server importing the portlet package file connecting to the remote server customizing the content of Cognos portlets

After you deploy the portlets, you can configure security for your ALUI 6.1 or 6.5 environment (p. 467). For more information, see the Installation and Configuration Guide.

Start the Remote Server

The remote server is an IBM Cognos Web application that serves as an interface between the core IBM Cognos 8 components and the ALUI 6.1 or 6.5 portal. The remote server application is the cps-alui.war file installed with IBM Cognos 8 in the c8_location\cps\bea_aqualogic\gadgets directory. By default, after IBM Cognos 8 is installed, the remote server is not started. It must be started if you want to use Cognos portlets in an ALUI 6.1 or 6.5 portal.

Administration and Security Guide 449

Chapter 30: Deploying Cognos Portlets to Other Portals You can deploy the remote server to another server. Ensure that the settings are configured properly so that the remote server can access an IBM Cognos 8 gateway. You can start the remote server in its default configuration state. However, the default remote server works only if the following conditions are met: IBM Cognos 8 is configured with a CGI gateway. The remote server runs on the same server as the IBM Cognos 8 gateway, which can be accessed using http://localhost/cognos8.

If these conditions do not apply to your installation, you must change the configuration settings for the remote server before you start it. To start the remote server, you must deploy the remote server into an active webapps folder: For Tomcat, copy the cps-alui.war file from the c8_location\cps\bea_aqualogic\gadgets directory into the c8_location\webapps folder. Tomcat automatically updates all affected directories and starts the remote server. The process may take a few minutes. For other application servers, follow the instructions in their administration guides.

You can now import the Cognos Portlet Package File (p. 452).

Reconfigure the Remote Server

If the default remote server configuration does not apply to your installation, or you want to change the configuration, you can change the configuration settings by modifying the cpsalui.properties file. Then, you must rebuild the remote server (cps-alui.war), and start it by deploying it to an active webapps folder for your Web application server. The following remote server parameters can be changed.

450

Chapter 30: Deploying Cognos Portlets to Other Portals

Parameter
cps_endpoint

Description
Specifies the URL to connect to the IBM Cognos 8 server and extract the WSDL information. The default value of http://localhost/cognos8/cgi-bin/cognos.cgi/ wsrp/cps4/portlets/[package]?wsdl&b_action=xts.run specifies that the IBM Cognos 8 gateway is configured on the same server as the remote server that it is running. In this situation, IBM Cognos 8 can be accessed through a CGI gateway. If not, this parameter must be modified accordingly. Here are a few more examples of values for this parameter: http://myserver/servletgateway/wsrp/cps4/portlets/ [package]?wsdl&b_action=cps.wsdl Specifies an IBM Cognos 8 servlet gateway installation on the server named myserver. http://myserver/ISAPIgateway/wsrp/cps4/portlets/ [package]?wsdl&b_action=cps.wsdl Specifies an IBM Cognos 8 ISAPI gateway installation on the server named myserver.

forward_cookies

Specifies the names of cookies that must be forwarded to the IBM Cognos 8 server for single signon purposes. If the single signon mechanism for the installation depends on a specific active credential cookie, it is necessary to pass this cookie from the ALUI 6.1 or 6.5 server to the IBM Cognos 8 server. Default: null

cps_auth_secret

Specifies the value of the shared secret key. This parameter is optional. Use it only when your environment is configured to use the shared secret single signon mechanism. When this parameter is specified, the user's identity is sent to the IBM Cognos 8 server through an HTTP header variable that is encrypted using the value of the shared secret. The value of this parameter must be identical to the one specified in IBM Cognos Configuration. For more information, see "Configuring Security for Portal Services" (p. 467).

cps_auth_namespace

The namespace ID for the Custom Java Provider.

Steps
1. Stop your application server, such as Tomcat, or stop the remote server application.

Administration and Security Guide 451

Chapter 30: Deploying Cognos Portlets to Other Portals 2. Remove the existing remote server by doing one of the following: For Tomcat, delete the cps-alui folder and the cps-alui.war file from the c8_location\webapps directory. For other application servers, follow the instructions in their administration guides.

3. Open the cpsalui.properties file. The file is located in the c8_location/cps/bea_aqualogic/webapps/gadgets/WEB-INF/classes directory. 4. Change the settings as required and save the file. 5. Rebuild the remote server by running the following batch file: for Windows, c8_location\cps\bea_aqualogic\build.bat for UNIX or Linux, c8_location\cps\bea_aqualogic\build.sh

The configuration settings for the remote server (cps-alui.war) are changed. 6. Start the remote server (p. 449). You can now import the Cognos portlet package file (p. 452).

Import the Cognos Portlet Package File

During the IBM Cognos 8 installation, the Cognos portlet package file CognosBEAAquaLogicPortletPackage.pte is installed as one of the ALUI 6.5 components. This file contains Web services, the remote server, and the definitions of the Cognos portlets (p. 449). Note: For ALUI 6.1, the portlet package file is named CognosBEAAquaLogic61PortletPackage.pte. When you import the Cognos portlet package file, you create one instance of a Cognos portlet server, and one instance of each portlet. The Cognos portlet server acts as a binding layer for the portlets. You can also supply your portal users with default portlets where the users can choose the content and layout. Each portlet appears in a default state. The portlets do not contain any Cognos content, and the default access permissions are read and write for portal administrators, and read-only for portal users.

Steps for ALUI 6.1

1. At the top of your portal page, click Administration. 2. Click Portal Resources. 3. Click Create Object, and click Administrative Folder. 4. Type a name, such as Cognos Portlets, and, if you want, a description for the group of Cognos portlets you want to import. 5. Click OK. 6. Click the folder you created. 452

Chapter 30: Deploying Cognos Portlets to Other Portals 7. Click Select Utility and click Migration - Import. 8. Select Folder Information, click Browse. 9. Select the folder you created to store the new resources, and click OK. 10. Under General Info, click Browse to locate the CognosBEAAquaLogic61PortletPackage.pte. This file is located in the c8_location/cps/bea_aqualogic/gadgets directory. 11. Click Open, and then click Load Package. 12. Click Finish, and click OK. The Cognos portlets appear in the Portal Services folder. You can now connect to the remote server (p. 453).

Steps for ALUI 6.5

1. At the top of your portal page, click Administration. 2. Click Select Utility and click Migration - Import. 3. Select Folder Information, click Browse. 4. Select the folder you created to store the new resources, and click OK. 5. Under General Info, click Browse to locate the CognosBEAAquaLogicPortletPackage.pte. This file is located in the c8_location/cps/bea_aqualogic/gadgets directory. 6. Click Open, and then click Load Package. 7. Click Finish, and click OK. The Cognos portlets appear in the Portal Services folder. You can now connect to the remote server (p. 453).

Connect to the Remote Server

The remote server must be configured and started (p. 449) before you can connect to it.

Steps
1. Click the folder that contains the Cognos portlets. 2. Expand the Remote Server folder, and click IBM Cognos Portal Services. 3. In the Edit Remote Serverpage, in the Remote Server Properties box, change the Base URL from http://localhost:9300/ to the following, where gadget server is the name or IP address of the server that hosts the IBM Cognos 8 remote server, and port is the port number used by the remote server.http://gadget_server:port The default port number is 9300. Here is an example: http://myserver:9300/ 4. Click Finish. Administration and Security Guide 453

Chapter 30: Deploying Cognos Portlets to Other Portals

Customize the Content of Cognos Portlets

You can define the default content and appearance of portlets. When you customize a portlet instance, the settings become the default for all users who view this instance. If the portlet is not locked for editing, users can customize the content for their instance of the portlet. Users retain their custom settings even if you reset the portlet. Users inherit the settings you configure only when they view the instance you configured, or when they reset the portlet using the reset button in the edit page of the portlet. Applications that appear in the Cognos Extended Applications portlet may include editable application parameters with default values defined by the developer. To change the parameter values that users see as defaults, you must edit the applications.xml file. For information about changing application parameters, see the Developer Guide. The configurable properties for the Cognos portlets vary. For more information, see "User Reference Help for Portal Services" (p. 717).

Steps
1. Go to the page where you added the Cognos portlets. 2. Click the configure button for the portlet you want to configure. 3. Edit the settings as required. These become the default settings for user instances of this portlet. 4. Click Done.

Deploying Cognos Portlets to Microsoft SharePoint Portal Server 2003 and 2007
You deploy Cognos portlets to the portal server so that users can add the portlets to their pages. In SharePoint Portal Server, portlets are named Web Parts. Portions of this document refer to Web Parts as portlets. You can deploy the following portlets: Cognos Content This group includes Cognos Navigator, Cognos Search, Cognos Viewer Cognos Extended Applications This group includes the Cognos Extended Applications portlet. To deploy this portlet, IBM Cognos 8 Software Development Kit must also be installed. Cognos Metrics This group includes Metric List, Metric History Chart, Metrics Impact Diagram, and Metrics Custom Diagram. To deploy these portlets, IBM Cognos 8 Metrics Manager Server must also be installed.

454

Chapter 30: Deploying Cognos Portlets to Other Portals Before deploying the Cognos portlets, ensure that IBM Cognos 8, including IBM Cognos Connection and Portal Services, is installed and configured. Also ensure that the following conditions are met: You have administration access to the IIS server computer that hosts SharePoint. You have administration access to the IBM Cognos 8 installation directory c8_location/cps/sharepoint. WSS Language Template Pack required for other supported languages is installed, one for each language.

For information about recommended operating system and SharePoint-related updates, and about the required OS patches, see the conformance information on the IBM Cognos Resource Center Web site (http://www.ibm.com/software/data/support/cognos_crc.html). For SharePoint Portal Server 2007, contact Microsoft for information about required OS patches. To deploy Cognos portlets to a SharePoint Portal Server, perform the following tasks: Set up virtual directories and change the gateway URIs (p. 455) This step applies if Microsoft Internet Information Services (IIS) is your Web server. Copy the Cognos Web Parts resources to the IIS HTTP root directory (p. 456) Set up the IBM Cognos security trust file (p. 457) Modify the .NET Framework web.config file (p. 458) Modify the Cognos Web Parts catalog files (p. 461) Restart IIS (p. 461) Add Cognos Web Parts to a SharePoint page (p. 462) Customize the content of Cognos Web Parts (p. 463)

After you deploy the portlets, you can configure security for your SharePoint Portal Server environment (p. 467). For more information, see the Installation and Configuration Guide.

Set up Virtual Directories and Change the Gateway URIs

If you use Microsoft Internet Information Services (IIS) and plan to enable single signon between the SharePoint portal and IBM Cognos Web Parts, you must create the cps and cps/cgi-bin virtual directories and enable anonymous access for them in Microsoft Internet Information Services (IIS) (p. 455). point the gateway URI to the Cognos Portal Services gateway in IBM Cognos Configuration (p. 456).

For more information, see the Proven Practices on the Cognos Software Services Web site.

Steps to Set up the Virtual Directories

1. In Microsoft Internet Information Services (IIS), create the cps virtual directory and assign the following properties for this directory:

Administration and Security Guide 455

Chapter 30: Deploying Cognos Portlets to Other Portals Specify the path to c8_location/webcontent. Grant read permissions to this directory. Enable anonymous access. Ensure that Integrated Windows authentication is not selected.

2. Under the cps virtual directory, create another directory named cgi-bin, and assign the following properties for this directory: Specify the path to c8_location/cgi-bin. Grant execute permissions to this directory. Enable anonymous access. Ensure that Integrated Windows authentication is not selected.

Steps to Change the Gateway URIs

1. Start IBM Cognos Configuration. 2. For the Environment category, change the Gateway URI to point to the Cognos Portal Services gateway. When properly set up, the Cognos Portal Services gateway URI should look like this: http://webserver/cps/cgi-bin/cognosisapi.dll/wrsp/cps4/portlets/nav?b_action=cps.wsdl&wsdl. 3. Ensure that the remaining Environment properties point to the same URI. 4. Restart the IBM Cognos 8 service.

Copy the Cognos Web Parts Resources to the IIS HTTP Root Directory
IBM Cognos software provides the resources required for the integration of SharePoint Portal Server with IBM Cognos 8. These include the Web Part DLLs for different languages, and catalog files for each Cognos Web Part. You must copy these resources to the IIS HTTP root directory to make them available to SharePoint.

Steps
1. Go to the c8-location/cps/sharepoint directory. 2. Copy all files from this directory to the IIS HTTP root directory, as specified in the following table. An example of the IIS HTTP root directory can be C:/Inetpub/wwwroot for SharePoint Portal Server 2003, and C:/Inetpub/wwwroot/wss/VirtualDirectories/80 for SharePoint Portal Server 2007.

456

Chapter 30: Deploying Cognos Portlets to Other Portals

File

IBM Cognos 8 Dir- IIS HTTP Root Directory ectory

/bin /bin/de /bin/en /bin/fr /bin/ja /wpcatalog /bin /bin/de /bin/en /bin/fr /bin/ja /wpcatalog

Cognos.BI.WebPart.dll Cognos.BI.WebPart.resources.dll Cognos.BI.WebPart.resources.dll Cognos.BI.WebPart.resources.dll Cognos.BI.WebPart.resources.dll CognosNavigator.dwp CognosSearch.dwp CognosViewer.dwp CognosSDK.dwp CognosWatchList.dwp CognosHistoryChart.dwp CognosImpactDiagram.dwp CognosCustomDiagram.dwp dialog_error.gif

/wpresources/Cognos. /wpresources/Cognos.BI. BI.WebPart WebPart

Later you can edit the Cognos*.dwp catalog files (p. 461).

Set Up the IBM Cognos Security Trust File

The Cognos Web Parts use the .NET Web Services Stack and they require a higher security trust level than the default minimum security. A sample of a security trust file named wss_cognostrust. config.sample is provided. This file specifies the required security trust, named WSS_Cognos, for the Cognos Web Parts. Use the wss_cognostrust.config.sample file provided for your version of SharePoint to set up the security trust for the Cognos Web Parts. For a simple SharePoint Portal Server installation the file can be used without any changes. For more complex installations, you may need to edit this file. Note: If you already have a trust file used by other Web Parts in your SharePoint Portal Server, you can add the Cognos-specific information from the sample to the existing file so that it can also be used by the Cognos Web Parts.

Steps
1. Go to the c8_location/cps/sharepoint/config directory.

Administration and Security Guide 457

Chapter 30: Deploying Cognos Portlets to Other Portals 2. Copy the wss_cognostrust.config.sample file: If you use SharePoint Portal Server 2003, copy the wss_cognostrust.config.sample file from the c8_location/cps/sharepoint/config/wss.2003 directory to the C:/Program Files/Common Files/Microsoft Shared/web server extensions/60/CONFIG directory. If you use SharePoint Portal Server 2007, copy the wss_cognostrust.config.sample file from the c8_location/cps/sharepoint/config/wss.2007 directory to the C:/Program Files/Common Files/Microsoft Shared/web server extensions/12/CONFIG directory.

3. Rename the copied file to wss_cognostrust.config.

Modify the .NET Framework web.config File

Microsoft .NET Framework provides a configuration file named web.config. This file, located in the IIS HTTP root directory, is used to configure the SharePoint services at the application level. To configure the Cognos Web Parts, you must add configuration information to this file. IBM Cognos 8 provides a sample configuration file named web.config.sample that shows a typical, fully functional configuration of the Cognos Web Parts with a SharePoint portal. You can use this sample to copy snippets of code and paste them into the web.config file. However, do not copy the entire sample file directly to your IIS environment. To configure the Cognos Web Parts with your SharePoint Portal Server, edit the web.config file by adding the IBM Cognos configuration information (p. 458).

Steps
1. Go to the IIS HTTP root directory, for example, C:/ Inetpub/wwwroot for SharePoint 2003, and C:/Inetpub/wwwroot/wss/VirtualDirectories/80 for SharePoint 2007. 2. Open the web.config file in an XML editor, such as XML Spy. 3. Edit the web.config file as required (p. 458), and save the file.

Changes in the web.config File

The web.config file is the central configuration point for all .NET Framework applications. Add the following information to the configuration element in this file.

Add the IBM Cognos Configuration Section

In the configSections section, add the following sectionGroup element:
<sectionGroup name="Cognos"> <section name="Log" type="System.Configuration.SingleTagSectionHandler, System,Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/> <section name="SoapLog" type="System.Configuration. SingleTagSectionHandler,System, Version=1.0.5000.0, Culffture=neutral, PublicKeyToken=b77a5c561934e089"/> <section name="SSO" type="System.Configuration.SingleTagSectionHandler, System,Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" /> <section name="PortalContext" type="System.Configuration.

458

Chapter 30: Deploying Cognos Portlets to Other Portals

SingleTagSectionHandler, System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" /> <section name="Fault" type="System.Configuration.SingleTagSectionHandler, System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" /> <section name="HttpClient" type="System.Configuration.SingleTagSectionHandler, System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/ > </sectionGroup>

Register the Cognos Web Part Assembly as a Safe Control

In the SharePoint section, add the following SafeControl element to the SafeControls element.
<SafeControl Assembly="Cognos.BI.WebPart, Version=1.0.0.0, Culture=neutral, PublicKeyToken=cb3c72729d0875cd" Namespace="Cognos.Portal. Services" TypeName="*" Safe="True"/>

Register the IBM Cognos Security Trust File

Cognos Web Parts require the security trust named WSS_Cognos that is defined in the wss_ cognostrust.config file (p. 457). In the system.web section, add the following trustLevel element to the securityPolicy element. SharePoint Portal Server 2003
<trustLevel name="WSS_Cognos" policyFile="C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\config\wss_cognostrust.config" />

SharePoint Portal Server 2007

<trustLevel name="WSS_Cognos" policyFile="C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\config\wss_cognostrust.config" />

Change the Trust Level to WSS_Cognos

WSS_Cognos is the security trust required by the Cognos Web Parts (p. 457). In the system.web section, change the trust level from
<trust level="WSS_Minimal" originUrl="" />

to
<trust level="WSS_Cognos" originUrl="" />

Enable the Session Object

In the system.web section, add the following element to the httpModules element if the element does not already exist:
<add name="Session" type="System.Web.SessionState.SessionStateModule"/>

If the element is commented out, remove the comments.

Administration and Security Guide 459

Chapter 30: Deploying Cognos Portlets to Other Portals In the system.web section, add the following pages element.
<pages enableSessionState="true" enableViewState="true" enableViewStateMac="true" validateRequest="false" />

If this element already exists, change the value of its enableSessionState attribute to true. In the system.web section, add the following element to the httpHandlers element:
<add verb="*" path="CognosResources/*.axd"type="Cognos.Portal.Services. HttpResourceHandler, Cognos.BI.WebPart, Version=1.0.0.0, Culture=neutral, PublicKeyToken=cb3c72729d0875cd" validate="false"/>

Register Cognos Portal Services as a SOAP Extension

In the system.web section, add the following webServices element:
<webServices> <soapExtensionTypes> <add type="Cognos.Portal.Services.SoapPatchExtension, Cognos.BI.WebPart, Version=1.0.0.0, Culture=neutral, PublicKeyToken=cb3c72729d0875cd" priority="1" group="0" /> </soapExtensionTypes> </webServices>

The soapExtensionTypes element represents all SOAP extensions that are available to your Web service at run time. If the webServices and soapExtensionTypes elements are already defined, add only the add element.

Specify the IBM Cognos Configuration Parameters

Use the Cognos element to specify the IBM Cognos configuration parameters as defined in IBM Cognos Configuration. Insert the following Cognos element between the closing tags </system.web> and
</configuration>: <Cognos> <SoapLog filename="c:\Cognos.BI.WebPart.Soap.log"/> <Log filename="c:\Cognos.BI.WebPart.log" error="true" warn="false" info="false" debug="false" performance="false" /> <SSO cps_auth_namespace="blank or as defined in IBM Cognos Configuration" cps_auth_secret="blank or as defined in IBM Cognos Configuration" /> <PortalContext gatewayURL="blank or as defined in IBM Cognos Configuration" webContentURL="blank or as defined in IBM Cognos Configuration" /> <Fault stacktrace="false" /> </Cognos>

The elements in the Cognos element represent the different configuration settings. Use the SoapLog element to specify the location for the Web Services log files.

460

Chapter 30: Deploying Cognos Portlets to Other Portals Use the Log element to specify a different location for the log file, and to enable the different logging features by changing the attribute values from false to true. Use the SSO element to specify the IBM Cognos Security Namespace ID of the CPS trusted namespace named cps_auth_namespace, and the shared secret password named
cps_auth_secret.

This parameter is optional. Use the PortalContext element to specify the URL attributes for IBM Cognos gateway and IBM Cognos Web content, as shown in the following example: PortalContext gatewayURL="http://localhost/cps/cgi-bin/cognosisapi.dll" webContentURL="http://c8_host_computer/cps"

This parameter is optional. Use the Fault element to display the call stacks in the error page when a fault is caught by a Web Part.

Edit the Cognos Web Parts Catalog Files

The catalog files contain the definitions of the Cognos Web Parts to use in SharePoint Portal Server. For each Cognos Web Part catalog file, change the WSDL URL to point to your IBM Cognos 8 gateway.

Steps
1. Go to the IIS directory where the catalog files were copied. For example, for SharePoint Portal Server 2003, go to C:/Inetpub/wwwroot, and for SharePoint Portal Server 2007 go to C:/Inetpub/wwwroot/wss/VirtualDirectories/80. 2. In each Cognos Web Part catalog file, Cognos*.dwp, change the URL in the WSDL element to point to your IBM Cognos 8 gateway. Here is an example:
<WSDL xmlns="http://developer.cognos.com/webpart/v1"> http://localhost/cps/cgi-bin/cognosisapi.dll/wsrp/cps4/portlets/nav?b_ action=cps.wsdl&amp;wsdl</WSDL>

Tip: The ampersand characters (&) in the URL must be XML-encoded as &amp; 3. Save the file.

Restart IIS
You must restart Internet Information Services (IIS) for the configuration changes to take effect.

Step
Restart IIS using its management console, or the iisreset.exe command line tool.

Administration and Security Guide 461

Chapter 30: Deploying Cognos Portlets to Other Portals The Cognos Web Parts are now available in SharePoint Portal Server, and can be added to the portal pages (p. 462).

Add Cognos Web Parts to a SharePoint Page

You can use the Cognos Web Parts to add the Cognos content to your pages in SharePoint Portal Server. You can add or remove the Web Parts from the shared view, or from the personal view of the page. Ensure that you are in edit mode before you make changes to the page. The following steps provide only basic instructions for adding the Cognos Web Parts to SharePoint pages. For more information, see the SharePoint Portal Server help.

Steps for SharePoint Portal Server 2003

1. Log on to your SharePoint Portal Server with administrative permissions. 2. Go to the page where you want to add the Cognos Web Parts. 3. From the Actions list on the left side, click Edit Page. 4. In the upper-right corner of the page, click Modify Shared Page, Add Web Parts. 5. Click Browse to add a Web Part from an existing Cognos Web Part library. The page opens in design mode, and the Add Web Parts pane appears on the right side of the page. Tips: You can use the Search option to find the Web Parts in the Web Part library. You can use the Import option if the Web Part you want is not in the library. Type the path or browse to the location of the Cognos*.dwp file that you want to import, and then click Upload. 6. In the Add Web Parts pane, click Virtual Server Gallery. The Cognos Web Parts appear in the Web Part List. 7. Click the Cognos Web Part you want, and then click the Add button at the bottom of the pane. The Web Part appears at the top of the page. Tip:You can also drag the Web Parts to different drop zones in the page. 8. In the Web Part, click the down arrow in the upper-right corner, and click Modify Shared Web Part. 9. In the pane on the right side of the page, specify the URL of the WSDL file under Connection Settings, WSDL. The URL must point to a functional IBM Cognos 8 installation. 10. Click Discover Portlets.

462

Chapter 30: Deploying Cognos Portlets to Other Portals 11. Specify the Portlet handle property. 12. Click Apply to make changes without closing the pane, or click OK when you are done. 13. Repeat steps 4 to 12 for each Cognos Web Part you want to add to the page. You can now customize the content of the Cognos Web Parts (p. 463).

Steps for SharePoint Portal Server 2007

1. Log on to your SharePoint Portal Server with administrative permissions. 2. Go to the page where you want to add the Cognos Web Parts. 3. From the Site Actions menu in the upper-right corner, click Edit Page. 4. In the Web Part zone where you want to add the Cognos Web Part, click Add a Web Part. 5. In the Add Web Parts dialog box, click All Web Parts, Miscellaneous. 6. In the Add Web Parts tool pane on the right side of the page, click Server Gallery. 7. From the list of available Cognos Web Parts, click the Web Part you want. 8. At the bottom of the tool pane, from the Add to menu, select the location on the page where you want the Web Part to appear, and click the Add button. Tip: You can also drag the Web Part to different drop zones in the page. 9. Repeat steps 4 to 8 for each Cognos Web Part you want to add to the page. 10. Click Exit Edit Mode. You can now customize the content of the Cognos Web Parts (p. 463).

Customize the Content of Cognos Web Parts

An administrator can define the default content and appearance for Cognos Web Parts. When users add the Web Part to their pages, the default properties are enabled. For example, in the Cognos Navigator Web Part, the administrator can define the default display folder or package. When users add this Web Part to their pages, they see the folder or package that was specified by the administrator. Users can change the Cognos Web Part properties to personalize their pages. The changes made by each individual user do not affect other users or other pages. The personalized settings are not affected if the administrator changes the default properties for the Web Part. Users can click the Reset button to revert to the current administrative defaults. The configurable properties for each Cognos Web Part are different. For more information, see "User Reference Help for Portal Services" (p. 717).

Steps for SharePoint Portal Server 2003

1. Go to the page in your SharePoint Portal Server that contains the Cognos Web Part you want to edit.

Administration and Security Guide 463

Chapter 30: Deploying Cognos Portlets to Other Portals 2. From the list of Actions on the left side, click Edit Page. 3. In the Web Part, click the down arrow in the upper-right corner, and click Edit Preferences. The Web Part properties page appears. 4. Specify the settings as required. For more information, click the help button in the upper-right corner of the properties page. 5. Click OK.

Steps for SharePoint Portal Server 2007

1. Go to the page in your SharePoint Portal Server that contains the Cognos Web Part you want to edit. 2. From the Site Actions menu in the upper-right corner, click Edit Page. 3. In the Web Part that you want to change, click the edit button. 4. Click Edit preferences. The Web Part properties page appears. 5. Specify the settings as required. For more information, click the help button in the upper-right corner of the properties page. 6. Click OK.

Migrating Cognos Portlets from IBM Cognos ReportNet 1.1 to IBM Cognos 8
When you upgrade ReportNet 1.1 to IBM Cognos 8, you must update the portlets using the latest portlet package file installed with IBM Cognos 8. For a WebSphere portal, use the CognosBIPortlets.war file located in the c8_location\cps\ibm\portlets directory (p. 441). For SAP Enterprise Portal 6.0, use the com.cognos.cognos.epa file located in the c8_location\cps\ sap\package directory (p. 445). Importing the new package into the portal creates a new and distinct set of Cognos portlets and resources. The upgraded portlets are not compatible with ReportNet 1.1, and the personalized settings are lost. You must configure and test the new portlets as required for IBM Cognos 8.

Change the Root Name of File Paths in Cognos Portlets

By default, the root name shown for all file paths in Cognos portlets is Cognos. You can change the root name to another name, such as your company name, by modifying the cpsinavcrnmsgs_ custom.properties file in the c8_location/webapps/p2pd/WEB-INF/classes directory. This changes the root name for the currently used content locale.

464

Chapter 30: Deploying Cognos Portlets to Other Portals If you want to specify root names for different locales, you must create new properties files for the required locales in the c8_location/webapps/p2pd/WEB-INF/classes directory. For example, to specify root names for English, French, German, and Japanese locales, create the following properties files, and provide the root name value in each of them: cpsinavcrnmsgs_custom_en.properties cpsinavcrnmsgs_custom_fr.properties cpsinavcrnmsgs_custom_de.properties cpsinavcrnmsgs_custom_ja.properties

Steps
1. Open the cpsinavcrnmsgs_custom.properties file in a text editor that supports UTF-8 encoding format. The file is located in the c8_location/webapps/p2pd/WEB-INF/classes directory. 2. Change the value 0f the property nav.root.name as follows, where root_name represents the value you change:
nav.root.name=root_name

The default is:

nav.root.name=Cognos

3. Save the cpsinavcrnmsgs_custom.properties file. 4. If you want to specify root names for different locales, create the required properties files now. 5. Restart the IBM Cognos 8 server.

Disable the Transfer of the IBM Cognos 8 Passport ID as a URL Parameter

To ensure a higher degree of security, you can disable the mechanism that transfers the IBM Cognos 8 passport ID as a URL parameter between users' browsers and the IBM Cognos 8 gateway. You can do this only when single signon is implemented between the users' browsers and IBM Cognos 8, and, if applicable, IBM Cognos Series 7, independently of Portal Services. By default, Portal Services re-creates the active credential cookie in the user's browser by passing the passport ID as a URL parameter. If single signon is not implemented, then when portal users interact with Cognos portlets, they are authenticated both in the portal and in IBM Cognos 8. The portal, not the user's browser, maintains the active credential token generated by IBM Cognos 8. In some situations, for example when you want to see a report in a Cognos portlet, a direct connection between the user's browser and the IBM Cognos 8 gateway must be established. This may become a security risk because a valid IBM Cognos 8 passport ID appears in some log files. The

Administration and Security Guide 465

Chapter 30: Deploying Cognos Portlets to Other Portals same applies when IBM Cognos 8 is integrated with IBM Cognos Series 7 and the active credential is passed as a URL parameter.

Steps
1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Dispatchers and Services. 3. Click the dispatcher you want. 4. For the PresentationService, in the Actions column, click the set properties button. 5. Click the Settings tab. 6. For the Environment category, next to Advanced settings, click the Edit link. 7. Select the Override the settings acquired from the parent entry check box. 8. In the Parameter column, type the parameter names: CPSPropagatePassport This parameter controls the transfer of the IBM Cognos 8 passport ID as a URL parameter. When set to 0, it stops the transfer. CPSPropagateTicket Controls the transfer of the IBM Cognos Series 7 ticket ID as a URL parameter. When set to 0, it stops the transfer. The parameters are case sensitive. 9. In the Value column, type 0 for each parameter. 10. Click OK. 11. Click OK again. 12. Click the Configuration link next to the path at the top of the page. You return to the list of dispatchers. 13. If you have more than one dispatcher configured, perform steps 3 to 12 for each remaining dispatcher.

466

Chapter 30: Deploying Cognos Portlets to Other Portals

Set Portal Services Protocol Scheme

For WebSphere portals, if you are using multiple gateways that may not use the same HTTP or HTTPS protocol as specified for the default gateway, you can set the CSPProtocolScheme parameter to override all other protocol settings.

Steps
1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Dispatchers and Services. 3. Click the dispatcher you want. 4. For PresentationService, in the Actions column, click the set properties button. 5. Click the Settings tab. 6. For the Environment category, next to Advanced settings, click the Edit link. 7. If it appears, select the Override the settings acquired from the parent entry check box. Otherwise, proceed to the next step. 8. In the Parameter column, type CPSProtocolScheme. 9. In the Value column, type http or https. 10. Click OK twice. 11. Click the Configuration link in the path at the top of the page. You return to the list of dispatchers. 12. If you have more than one dispatcher configured, perform steps 3 to 11 for each remaining dispatcher.

Configuring Security for Portal Services

When using Portal Services in another portal, you must enable single signon to provide seamless integration between the other portal and IBM Cognos 8 components. Portal Services uses single signon to authenticate users. This means that users do not have to log on to other applications separately through the portal. You must configure a URI into IBM Cognos 8 components for each portlet in Portal Services. To enable security between IBM Cognos 8 components and the other portal, do the following: Disable anonymous access to IBM Cognos 8 components. If your security infrastructure requires you to use another method for single signon, use one of the following methods: Enable single signon for the other portal using shared secret.

Administration and Security Guide 467

Chapter 30: Deploying Cognos Portlets to Other Portals If your security infrastructure requires you to use another method for single signon, use one of the following methods: "Enable Single Signon for WebSphere Portal Using the Application Server" (p. 476) "Enable Single Signon for BEA ALUI Portal Using Basic Authentication" (p. 476) "Enable Single Signon for BEA ALUI Portal Using SiteMinder" (p. 477)

Configure IBM Cognos 8 components for SSL access, if required. For instructions, see the Installation and Configuration Guide.

Disable Anonymous Access to IBM Cognos 8 Components

Portal Services uses single signon for authentication. If anonymous logon is enabled in IBM Cognos 8 components, Portal Services logs all portal users as anonymous. You must ensure that anonymous access is disabled in IBM Cognos 8 components for single signon in Portal Services to be successful. However, you can test the Portal Services connections using anonymous logon to ensure that the portlets are working in the other portal. If Portal Services fails to authenticate a user, the user receives an error message at the other portal.

Steps
1. Start IBM Cognos Configuration. 2. In the Explorer window, under Security, Authentication, click Cognos. 3. In the Properties window, ensure that Allow anonymous access is set to False. 4. From the File menu, click Save. 5. Repeat steps 1 to 4 on all servers where you installed IBM Cognos 8 components.

Enable Single Signon Using Shared Secret

You can use shared secret for single signon between Cognos portlets and IBM Cognos 8 components. The Cognos portlets send a message that contains an encrypted version of the portal user ID. The encryption key is determined by the value of a secret character string shared between the portlets and the custom Java security provider on the IBM Cognos server. You can use shared secret for the other portal only if portal user IDs can be looked up in an NTLM, LDAP, or IBM Cognos Series 7 authentication namespace that is shared by IBM Cognos 8 components. IBM Cognos 8 components must have access to a directory server that contains user IDs for all your portal users. Using IBM Cognos Configuration, you must configure an authentication namespace so that the portal and IBM Cognos 8 components share the same authentication source. You must also create a Custom Java Provider namespace to register the shared secret Java provider that is provided with IBM Cognos 8 components. Within the portlets or iViews, you must link the portlets or iViews to the Custom Java Provider namespace within your respective portal: 468 Cognos iViews (SAP EP)

Chapter 30: Deploying Cognos Portlets to Other Portals Cognos Portlet Application (WebSphere Portal) remote server (BEA ALUI Portal) Cognos WebPart (SharePoint Portal)

You are not required to configure access to the Portal Services Web content. However, if you deploy the portlets to another portal, you can configure access to an alternate URI for Portal Services images and Web content.

Steps to Configure the Required Namespaces

1. In IBM Cognos Configuration, configure a namespace to authenticate portal users. For instructions, see the topic about configuring LDAP, NTLM, or IBM Cognos Series 7 authentication providers in the Installation and Configuration Guide. 2. For an LDAP namespace, configure the following properties: For the Use external identity property, change the setting to True. For the External identity mapping property, set it to (uid=${environment("REMOTE_USER")}) Other properties may be required. For more information, see the topic about configuring IBM Cognos 8 components to use LDAP in the Installation and Configuration Guide. 3. For an IBM Cognos Series 7 namespace, map the portal user IDs to IBM Cognos Series 7 user IDs using OS signons. For more information, see the IBM Cognos Series 7 documentation. 4. In IBM Cognos Configuration, create and configure a Custom Java Provider namespace. For instructions, see the topic about configuring a custom authentication namespace in the Installation and Configuration Guide. For the Namespace ID property, specify any new ID. For example, cpstrusted This new ID must be used in the portlet configuration settings. For the Java class name property, type com.cognos.cps.auth.CPSTrustedSignon Java class names are case-sensitive. 5. In IBM Cognos Configuration, under Environment, Portal Services, configure the following properties: For Trusted Signon Namespace ID, type the namespace ID of the LDAP, NTLM, or IBM Cognos Series 7 namespace that you configured in step 1. Tip: The trusted signon namespace acts as an intermediary and must be attached to a real directory-based namespace of type LDAP, NTLM, or IBM Cognos Series 7.

Administration and Security Guide 469

Chapter 30: Deploying Cognos Portlets to Other Portals For Shared Secret, type the key to be used for single signon. This parameter represents the authorization secret that must be shared between the Cognos portlets and the IBM Cognos server. Consider this as a secret password. You must use the same character string when you configure the portlet application. You must use a single word as the key. For security reasons, we recommend you specify a non-null value. 6. Under Environment, for Gateway Settings, set the Allow Namespace Override property to true. 7. From the File menu, click Save. 8. Restart the IBM Cognos 8 service.

Steps to Configure Access to the Portal Services Web Content

1. On the computer where you installed the Application Tier Components, start IBM Cognos Configuration. 2. In the Explorer window, under Environment, click Portal Services. 3. In the Properties window, click the Value box next to Web Content URI. 4. Specify the host name or IP address of the gateway and a port number using the format host_or_IP_address:port 5. From the File menu, click Save.

Steps to Configure the Cognos iViews for SAP EP

1. Open the iView editor for each Cognos iView. 2. In the Property Category box, select Show All. 3. For the cpsauthsecret: CPS Authorization Secret property, enter the secret character string that you used for the Shared Secret property when you configured the Custom Java Provider namespace. 4. For the cps: authentication namespace ID property, enter the Custom Java Provider namespace ID. 5. For the cpsserver: CPS Connection Server property, enter the URL path to access Portal Services components through the gateway. The format of the URL is as follows: For Cognos content portlets Gateway_URI/wsrp/cps4/portlets/nav?wsdl&b_action=cps.wsdl Example for a CGI gateway: http://myserver/cognos8/cgi-bin/cognos.cgi/wsrp/cps4/portlets/nav?wsdl&b_action=cps. wsdl Example for a servlet gateway: 470

Chapter 30: Deploying Cognos Portlets to Other Portals http://172.0.16.1:9500/wsrp/cps4/portlets/nav?wsdl&b_action=cps.wsdl For Cognos Extended Applications Gateway_URI/wsrp/cps4/portlets/sdk?wsdl&b_action=cps.wsdl Example for a CGI gateway: http://myserver/cognos8/cgi-bin/cognos.cgi/wsrp/cps4/portlets/sdk?wsdl&b_action=cps. wsdl Example for a servlet gateway: http://172.0.16.1:9500/wsrp/cps4/portlets/sdk?wsdl&b_action=cps.wsdl For Metrics Manager Watchlist portlets Gateway_URI/wsrp/cps4/portlets/cmm?wsdl&b_action=cps.wsdl Example for a CGI gateway: http://myserver/cognos8/cgi-bin/cognos.cgi/wsrp/cps4/portlets/cmm?wsdl&b_action=cps. wsdl Example for a servlet gateway: http://172.0.16.1:9500/wsrp/cps4/portlets/cmm?wsdl&b_action=cps.wsdl

Steps to Configure the Cognos Portlets for WebSphere Portal

1. For each Cognos portlet application, click Modify Parameters. 2. For the cps_auth_secret property, enter the secret character string that you used for the Shared Secret property when you configured the Custom Java Provider namespace. 3. For the cps_auth_namespace property, enter the Custom Java Provider namespace ID. 4. For the CPS Endpoint property, enter the URL path to access Portal Services components through the gateway. The format of the URL is as follows: For Cognos content portlets Gateway_URI/wsrp/cps4/portlets/nav?wsdl&b_action=cps.wsdl Example for a CGI gateway: http://myserver/cognos8/cgi-bin/cognos.cgi/wsrp/cps4/portlets/nav?wsdl&b_action=cps. wsdl Example for a servlet gateway: http://172.0.16.1:9500/wsrp/cps4/portlets/nav?wsdl&b_action=cps.wsdl For Cognos Extended Applications Gateway_URI/wsrp/cps4/portlets/sdk?wsdl&b_action=cps.wsdl Example for a CGI gateway:

Administration and Security Guide 471

Chapter 30: Deploying Cognos Portlets to Other Portals http://myserver/cognos8/cgi-bin/cognos.cgi/wsrp/cps4/portlets/sdk?wsdl&b_action=cps. wsdl Example for a servlet gateway: http://172.0.16.1:9500/wsrp/cps4/portlets/sdk?wsdl&b_action=cps.wsdl For Metrics Manager Watchlist portlets Gateway_URI/wsrp/cps4/portlets/cmm?wsdl&b_action=cps.wsdl Example for a CGI gateway: http://myserver/cognos8/cgi-bin/cognos.cgi/wsrp/cps4/portlets/cmm?wsdl&b_action=cps. wsdl Example for a servlet gateway: http://172.0.16.1:9500/wsrp/cps4/portlets/cmm?wsdl&b_action=cps.wsdl

Steps to Configure the Remote Server for BEA Aqualogic User Interaction (BEA ALUI) Portal
1. Using a plain ASCII editor, such as Notepad, edit the cpspt.properties file in the c8_location/ cps/bea_aqualogic/webapps/gadgets/WEB-INF/classes directory. 2. Configure the following settings.

Parameter
cps_endpoint

Value
The URL to connect to the Application Tier Components and extract the WSDL information. Specify the URI to the gateway. For a servlet or ISAPI gateway, replace the localhost/cognos8/ cgi-bin/cognos.cgi portion with the values to target the gateway. For example, http://host_name/cognos8/cgi-bin/cognos.isapi/wsrp/cps4/ portlets/[package]?wsdl&b_action=cps.wsdl For instructions, see the topic about changing the gateway in the Installation and Configuration Guide.

forward_cookies=

The names of the cookie that should be sent to the Application Tier Components for single signon. Leave blank.

472

Chapter 30: Deploying Cognos Portlets to Other Portals

Parameter
cps_auth_secret

Value
The shared secret code IBM Cognos 8 uses to encrypt an HTTP header variable that carries the user identity. This parameter represents the authorization secret that must be shared between the Cognos portlets and the IBM Cognos 8 server. Consider this as a secret password. Use the same value that you used for Shared Secret in IBM Cognos Configuration. For security reasons, we recommend you specify a non-null value.

cps_auth_namespace

The namespace ID for the Custom Java Provider.

3. Go to the c8_location/cps/bea_aqualogic directory and run the following build file: On UNIX or Linux, build.sh On Windows, build.bat

This creates a cps-alui.war file in the c8_location/cps/bea_aqualogic/gadgets directory. 4. If IBM Cognos 8 components are running using Tomcat, Stop IBM Cognos 8. Copy the cps-alui.war file to the c8_location/webapps directory. Tomcat automatically expands the WAR file and starts the remote server. Start IBM Cognos 8.

5. If IBM Cognos 8 components are running under another type of application server, copy the cps-alui.war file to the application server. For instructions, see the administration guide for your application server. Single signon is configured.

Steps to Configure Properties for the Cognos WebPart for SharePoint Portal
1. Using a plain ASCII editor, such as Notepad, edit the web.config file in the drive\Program Files\Common Files\Microsoft Shared\web server extensions\12\CONFIG directory. 2. Find the following string:
<SSO cps_auth_namespace="" cps_auth_secret="" />

3. Set cps_auth_namespace to the namespace ID for the Custom Java Provider namespace. 4. Set cps_auth_secret to the value that you used for Shared Secret in IBM Cognos Configuration.

Administration and Security Guide 473

Chapter 30: Deploying Cognos Portlets to Other Portals

Enable Single Signon for SAP EP with the SAP Logon Ticket
If you enable single signon with the SAP Logon Ticket, you must configure IBM Cognos 8 components with an SAP namespace that links to an SAP BW server. Then you must copy the certificate that was generated during SAP EP installation to the SAP BW personal security environment. Users must have the same user ID in all SAP systems that are accessed through single signon. Before you start, ensure that you have configured IBM Cognos 8 components to use an SAP authentication source For more information, see the Installation and Configuration Guide. enabled single signon between IBM Cognos 8 components and SAP BW For more information, see the Installation and Configuration Guide. installed the latest service packs on the SAP BW server Service packs can be downloaded from SAPNET. installed the latest hot patches for the SAP portal installed the Enterprise Portal plug-in that corresponds to the SAP EP release or SAP BW server For SAP releases earlier than 6.2, on SAPNET, download EP50_PLUG-IN for Basis 620 (SAPKINE32A). Using transaction SAINT, install SAPKINE32A. installed the SAP Security Library on the SAP BW servers From sapservX, under /general/misc/security/SAPSECU/platform, download sapsecin and sepsecu.dll and place both files in the /run directory of the SAP BW server. To enable SSO for SAP EP, complete the procedures for single signon with SAP logon tickets in the SAP Enterprise Portal Security Guide.

Enable Single Signon for SAP EP with User Mapping

If you enable single signon with user mapping, you define an IBM Cognos data source in SAP EP. Individual users or an administrator can enter the user IDs and passwords for IBM Cognos 8 components in the data source. You must map the users logon credentials in the data source to an LDAP or IBM Cognos Series 7 or NTLM namespace. Portal Services iViews transmit the logon credentials to IBM Cognos 8 components using HTTP Basic Authentication.

Steps to Prepare the Environment

1. Configure the gateway URI that will be used by Portal Services to require authentication using HTTP Basic Authentication. For information about configuring a URL to use HTTP Basic Authentication, see the documentation for the gateway or for your Web server. 2. Adjust the iView configuration to access the secure URL. For information, see the documentation for your Web server.

474

Chapter 30: Deploying Cognos Portlets to Other Portals 3. In IBM Cognos Configuration, configure a namespace to authenticate portal users. For instructions, see the topic about configuring LDAP, NTLM, or IBM Cognos Series 7 authentication providers in the Installation and Configuration Guide. 4. If you use an LDAP namespace, configure the following properties: For the Use external identity property, change the setting to True. For the External identity mapping property, set it to (uid=${environment("REMOTE_USER")}) Other properties may be required. For more information, see the topic about configuring IBM Cognos 8 components to use LDAP in the Installation and Configuration Guide.

Steps to Create the Data Source and Map the Users

1. In the SAP portal, ensure that the following properties are configured for the data source in the /PortalContent/other_vendors/every_user/com.cognos.pct.c8/systems/Cognos 8 directory: Logon Method = UIDPW server name = the name of the IBM Cognos server port number = port number of the gateway Protocol of Target system = HTTP User Mapping Type = admin,user system alias (Create a system alias)

For more information, see the SAP Enterprise Portal Administration Guide. 2. For each Cognos iView, enable user mapping for the data source by entering the name of the system alias at the iView level, in an attribute called CPS: User Mapping Datasource. For more information, see the SAP Enterprise Portal Administration Guide. 3. For each Cognos iView, set the CPS: Authentication Namespace ID property to the namespace that you want to use for authentication. 4. Register the IBM Cognos credentials for the portal users. Users can enter their own user IDs and passwords. For more information, see the SAP Enterprise Portal Administration Guide. We recommend that you enable secure communication between SAP EP and IBM Cognos 8.

Enable Secure Communication Between SAP EP and IBM Cognos 8 Components

A secure connection, using SSL, is not required between SAP EP and IBM Cognos 8 components. It is more important if you enabled single signon with user mapping. The SSL security supported by SAP uses encryption above 56 bits. By default, IBM Cognos 8 components use an encryption algorithm up to 56 bits. IBM Cognos provides an enhanced encryption

Administration and Security Guide 475

Chapter 30: Deploying Cognos Portlets to Other Portals module as a complementary product. To enable SSL, you must purchase and install the Enhanced Encryption Module for OpenSSL on top of IBM Cognos 8 components. For more information, see the IBM Cognos Enhanced Encryption Module for OpenSSL Installation and Configuration Guide. To enable SSL between SAP EP and IBM Cognos 8 components, see your SAP EP security documentation. For more information about configuring SSL in IBM Cognos 8 components, see the topic about configuring the SSL protocol in the Installation and Configuration Guide. After SSL is enabled, edit properties for the all iViews so that the cpsserver: CPS Connection Server property uses https instead of http.

Enable Single Signon for WebSphere Portal Using the Application Server
The Portal Services portlets can use the Active Credentials objects provided by WebSphere Portal to connect to IBM Cognos 8 components. Portal Services supports the following Active Credentials objects: HttpBasicAuth, LtpaToken, SiteMinderToken, and WebSealToken. Credentials for the portal user are passed to the gateway using this object. For more information about Active Credential objects, see the documentation for IBM WebSphere Portal. To use application server single signon, see the documentation for IBM WebSphere Application Server. For information about SSL for IBM Cognos 8 components on a WebSphere Application Server, see the topic about enabling SSL in the application server chapter of the Installation and Configuration Guide.

Enable Single Signon for BEA ALUI Portal Using Basic Authentication
You can configure a portlet in BEA ALUI Portal to send the username and password as an HTTP Basic authentication header. The header can be used with an NTLM, LDAP, or IBM Cognos Series 7 authentication namespace to provide single signon.

Steps
1. In IBM Cognos Configuration, configure a namespace to authenticate portal users. For instructions, see the topic about configuring LDAP, NTLM, or IBM Cognos Series 7 authentication providers in the Installation and Configuration Guide. 2. Install an alternate CGI or ISAPI or servlet gateway in IBM Cognos 8. For instructions, see the topic about installing IBM Cognos 8 in the Installation and Configuration Guide. 3. Configure the gateway. For instructions, see the Installation and Configuration Guide. 4. In the administration console of the Web server, configure the virtual directories to access the gateway. For more information, see the documentation for your Web server.

476

Chapter 30: Deploying Cognos Portlets to Other Portals 5. Configure the BEA ALUI remote server to access IBM Cognos 8: Edit the cpspt.properties file in the c8_location/cps/bea_aqualogic/webapps/gadgets/WEBINF/classes directory. Change the cps_endpoint property to indicate the URL of the gateway. For a CGI gateway, you can use the default setting if the gateway and the remote server are on the same computer. Otherwise, replace the localhost portion with host_name:port For a servlet or ISAPI gateway, replace the localhost/cognos8/cgi-bin/cognos.cgi portion with the values to target the gateway. For example, http://host_name:port/cognos8/cgi-bin/cognos.isapi/wsrp/cps4/portlets/[package]?wsdl&b_ action=cps.wsdl Set the cps_auth_namespace property to the namespace that you want to use for authentication.

Enable Single Signon for BEA ALUI Portal Using SiteMinder

If you use eTrust SiteMinder to provide single signon in your security infrastructure, you can also use it for single signon with BEA ALUI Portal. You must configure a SiteMinder authentication namespace in IBM Cognos 8. BEA ALUI Portal sends the SiteMinder active authentication token to the remote server, which sends the token to the IBM Cognos 8 gateway.

Steps
1. In IBM Cognos Configuration, configure a SiteMinder authentication namespace. For instructions, see the topic about configuring SiteMinder authentication namespaces in the Installation and Configuration Guide. 2. Configure the remote server to forward the authentication token: Edit the cpspt.properties file in the c8_location/cps/bea_aqualogic/webapps/gadgets/WEBINF/classes directory. Change the forward_cookies property to include the name of the active authentication token that SiteMinder provides. Change the cps_endpoint property to indicate the URL of the gateway. For a CGI gateway, you can use the default setting if the gateway and the remote server are on the same computer. Otherwise, replace the localhost portion with host_name:port. For a servlet or ISAPI gateway, replace the localhost/cognos8/cgi-bin/cognos.cgi portion with the values to target the gateway. For example, http://host_name:port/cognos8/cgi-bin/cognos.isapi/wsrp/cps4/portlets/[package]?wsdl&b_ action=cps.wsdl Administration and Security Guide 477

Chapter 30: Deploying Cognos Portlets to Other Portals Change the cps_auth_namespace property to the namespace that you want to use for authentication.

478

Chapter 31: Customizing the Appearance of IBM Cognos 8

You can customize the IBM Cognos 8 interface to suit the needs of an international customer or a particular reseller. You can make changes to the colors, fonts, images, and overall appearance of one or more IBM Cognos 8 components, simply by modifying the appropriate cascading style sheets (CSS), HTML content, and graphics. IBM Cognos 8 includes a selection of predefined styles that you can use to globally change the look of the graphical user interface, without affecting product functionality. You can also customize the following IBM Cognos 8 components separately: IBM Cognos Connection (p. 484) Report Studio (p. 486) Query Studio (p. 488) Cognos Viewer (p. 492) prompt pages (p. 494)

For more information about IBM Cognos 8 customizations, see "Customizing the Functionality of IBM Cognos 8" (p. 501).

Making Global Changes to all Components

You can make the following global changes to the appearance of all IBM Cognos 8 components: customize the IBM Cognos 8 styles rebrand the IBM Cognos 8 interface change IBM Cognos 8 fonts change the global IBM Cognos 8 style sheet migrate changes to future releases

Customizing Styles
You can change the appearance of all the product component interfaces by using a different style (p. 437) in the c8_location/webcontent/skins directory. The style can be either a modified version of an existing predefined style (p. 480) or your own custom style (p. 480). The IBM Cognos 8 predefined styles include: business classic

Administration and Security Guide 479

Chapter 31: Customizing the Appearance of IBM Cognos 8 contemporary corporate (product default) modern presentation windows

Note: The windows style is used only with Report Studio. It adopts the display scheme specified by the Windows settings. This style must not be modified and none of the customization techniques described in this document apply to it.

IBM Cognos 8 Components Affected by Styles

Each style has separate directories for the following components: IBM Cognos Connection (job scheduling and query setting defaults) Report Studio (toolbox and preview window) Query Studio (filter dialogs and prompt pages) Cognos Viewer (reports and prompt pages) Analysis Studio Event Studio

Modifying a Style
You can modify an existing style, including the predefined styles, so that it matches your organization Web interface. You can change colors, fonts, images, and some layout properties. Modify the associated style sheets in the c8_location/webcontent/skins/style directory. Rename the styles using IBM Cognos Administration so that the names are more appropriate for your environment (p. 440). Rename the style directories in the c8_location/webcontent/skins directory. Do not rename the corporate directory (p. 481).

Create a Custom Style

You can create a custom style and make it available in IBM Cognos 8.

480

Chapter 31: Customizing the Appearance of IBM Cognos 8 We recommend that you use the existing style resources as a starting point. Change the style sheets, graphics, and fonts as required, but ensure that the structure of the custom style directory matches the structure of the predefined styles directories.

Steps
1. In the c8_location/webcontent/skins directory, make a copy of an existing style directory. 2. Rename the copied directory. 3. In the new directory, modify the style sheets, graphics, or fonts as required. 4. In IBM Cognos Administration, add a new style object (p. 438) and associate it with the style directory created in step 2.

Modifying the Corporate Style for a Customized Environment

Corporate is the default style in IBM Cognos 8. It is used when no other suitable style can be found, for example, at logon time when the user identity is unknown. A reference to the corporate directory is hard-coded in the product and this directory must always exist in the c8_location/webcontent/skins directory. When you customize the styles, do not rename the corporate directory. However, you can modify the style sheets it contains to apply your company look and feel to the style this directory is associated with. You can also rename the corporate style object so that the name corporate does not appear in the user interface (p. 440).

Rebranding the IBM Cognos 8 Interface

You can rebrand the product by globally replacing all instances of the company name and logo with new text and appropriate brand images. Resellers and partners may use a brand-neutral version of the IBM Cognos 8 splash screen image. Graphics for IBM Cognos 8 are created using a Web-safe color palette. They are saved as noninterlaced GIF files. All interface icons are created with a transparent background, shown as the color Magenta.

Changing Brand-related Graphic

The brand-related graphics are grouped together in a directory named c8_location/webcontent/skins/style/branding where style represents each style directory (p. 479). Depending on the style you use, you change the graphics in the associated style directories. You can replace individual IBM Cognos 8 images, which are generally GIF files, with alternatives of a more suitable size or design. However, be careful when replacing similar-looking logos and icons. For example, the nested-square logo used to brand the Web portal (banner_cogsquare.gif) is not the same as the nested-square logo used in the About box (about.gif). To help you locate the correct graphics, note that those used with the product components typically have file names beginning with the prefix tools_. This differentiates them from object or actionrelated graphics, which typically have file names beginning with the prefix icon_.

Administration and Security Guide 481

Chapter 31: Customizing the Appearance of IBM Cognos 8 Tip: To change the text in a graphic, such as the acronym BI, open the relevant file in a graphics editor, replace the text, and resave the graphic in .GIF format.

Changing Component Names and Text Messages

You can change the names of IBM Cognos 8 components and modify the accompanying text messages by opening the relevant message file in a text editor and performing a search-and-replace on the text strings and calls you want to change. The message files are located in the c8_location/msgsdk directory. For changes to take effect, you must restart the IBM Cognos 8 service. For more information about using the message files in the c8_location/msgsdk directory, see the Localization Development Kit Installation and User Guide.

Adding Custom Messages

You can add your own custom messages, such as reseller copyright information, to the existing text in the About box. However, note that you are legally required to maintain the existing IBM Cognos copyright notice.

Checking Global Text Changes

When you are finished making global text changes, we recommend that you check them in all the interfaces exposed to your users. Pay particular attention to browser page captions and generic dialog boxes, which are easy to miss.

Changing IBM Cognos 8 Fonts

IBM Cognos 8 style sheets specify text fonts that are suitable for UTF-8-encoded text. Relative font sizes are specified for interface text elements. Point sizes are specified for report text elements and form controls (input fields). All text strings except the banner, company, and portal strings are language-sensitive. However, no banner string is used in IBM Cognos Connection. You can change the fonts used in IBM Cognos 8 by modifying the font-family list in the file c8_location/webcontent/skins/style/fonts.css where style represents the style directory (p. 479). Modify the fonts.css file associated with the style you want. For example, you can change the default font used on all HTML interfaces, except Report Studio, to one more suited to rendering special Asian characters. Open the file fonts.css in a text editor, comment out the section that shows Tahoma as the first item in the font-family list, and then remove the comment from an entry that better meets your Unicode requirements. Note: Font changes do not apply to Report Studio, which has a separate font-setting style sheet (p. 486).

Changing the Global IBM Cognos 8 Style Sheet

To globally change the default styles used for IBM Cognos 8 reports, you can modify styles in the GlobalReportStyles.css file located in the following directories: c8_location/bin The file in this location is used by Report Server for PDF and Excel outputs.

482

Chapter 31: Customizing the Appearance of IBM Cognos 8 c8_location/webcontent/schemas The file in this location is used by Cognos Viewer for HTML output. c8_location\reportstyles The file in this location is not currently used. c8_location\webcontent\reportstyles The file in this location is used by Report Studio. The files in all directories must be modified to ensure that reports are rendered properly on both the server and the client systems. In a multiple server configuration, the style sheets on all systems must be modified. On the IBM Cognos 8 server system, this is the file in the c8_location/bin directory. On the Web server systems, this is the file in the c8_location/webcontent/schemas directory. For example, if you have 2 IBM Cognos 8 servers and 3 Web servers, you must update 5 copies of the GlobalReportStyles.css file. You can also add styles to this style sheet; however, a simpler alternative is to add a style to a template in Report Studio. Any changes you make to this style sheet are lost if you reinstall or upgrade IBM Cognos 8. If this happens, you must reapply your changes. For more information, see "Migrating Changes to Future Releases" (p. 483) Both Report Studio and Query Studio use the GlobalReportStyles.css file to assign classes to report objects. Query Studio does not expose these classes. However, you can use Report Studio or the SDK to modify the class property of any report object. For example, if you create a default report and then click the title, the class property appears as Report Title Text. You can change this property as required. If you decide to modify the GlobalReportStyles.css file, you must be aware that the class names that appear in Report Studio are multilingual and defined in the Report Studio resource files. Instead of modifying this style sheet, it may be simpler to add a new style into your report. For more information about creating or modifying class styles, see the Report Studio Professional Authoring User Guide. When you work directly with an XML report specification, you can manually set the style of the object. For example, you can edit the report title, which may appear as follows:
<textItem class="reportTitleText"> <text> My report title </text> </textItem>

For more information about modifying styles in a report specification, see the Developer Guide.

Migrating Changes to Future Releases

IBM Cognos 8 does not automatically preserve changes made to style sheets and other customizationrelated files. We recommend that you keep a careful record of your changes. Otherwise, you may inadvertently lose them during migration to a newer version of the product.

Administration and Security Guide 483

Chapter 31: Customizing the Appearance of IBM Cognos 8

Modifying the Appearance of IBM Cognos Connection

The style sheet default.css in the c8_location/webcontent/skins/style/portal directory defines the overall appearance of the IBM Cognos Connection interface for each style (p. 479). Portal-specific graphics, if present, are located in the images subdirectory. You make changes to the appearance of IBM Cognos Connection by modifying the default.css file for the styles you want. Before you begin, we recommend that you back up the original default.css file. Other changes to the appearance of IBM Cognos Connection are made in the c8_location/templates/ ps/portal/system.xml file. Tip: Remember to restart IBM Cognos 8 after completing your modifications, so that the changes take effect. This documentation provides the following examples of customizations in IBM Cognos Connection: Customizing the default Welcome page (p. 484) Changing the background color in the IBM Cognos Connection main header (p. 485) Changing the branding details in the IBM Cognos Connection main header (p. 484) Changing the portal graphics (p. 486) Changing the fonts for page titles and instructions (p. 486)

Example - Customize the Default Welcome Page

You can customize the default Welcome page to apply your organization look and feel to it. You can change the colors, fonts, graphics, and some layout properties. To customize the Welcome page for the style you want, in the c8_location/webcontent/skins/style/portal/default.css file, search for the classes that start with welcome and modify the values as required.

Example - Change the Branding Details in the IBM Cognos Connection Main Header
You can customize the IBM Cognos Connection main header by changing the branding details on the left-hand side. You can change the graphic, the title, and the background color. This change affects also Cognos Viewer and the administration tools. The branding details are defined by the OEM parameter in the portal system.xml file. You must modify this file.

Steps
1. Open the system.xml file in a text or XML editor. This file is located in the c8_location/templates/ps/portal directory. 2. Locate the OEM parameter and add the custom branding details as specified in the following code. 484

Chapter 31: Customizing the Appearance of IBM Cognos 8 The sequence in bold font must be repeated for each style in which you want this change to appear.
<param name="OEM"> <customHeader showContext="true" contextDelimiter="-"> <style styleFolderName="corporate"> <!--Insert well-formedHTMLhere --></style> <style styleFolderName="classic"> </style> ... </customHeader> </param>

Setting the showContext attribute to true adds a report or a page name to the title. The
contextDelimiter attribute, which can be represented by any character or sequence of char-

acters, separates the title from the report or page name. Here is a code example for this change:
<customHeader showContext="true" contextDelimiter=""> <style styleFolderName="corporate"> <table style="background-color:#ffffff"> <tr> <td><img src="../skins/corporate/branding/my_logo.gif"/> </td><tdclass="headerTitle" style="padding-right:2px;white-space: nowrap">Mycompany</td> </tr> </table> </style> <style styleFolderName="classic"> <table style="background-color:#cccccc"> <tr> <td><img src="../skins/corporate/branding/my_logo.gif"/> </td><tdclass="headerTitle" style="padding-right:2px;white-space: nowrap">Mycompany </td> </tr> </table> </style> </customHeader>

Example - Change the Background Color in the IBM Cognos Connection Main Header
Suppose you want to change the background color used in the IBM Cognos Connection header. Open the c8_location/webcontent/skins/style/shared/banner.css file in a text editor and, in the code specified below, change the value shown in bold font as required.
mainHeader1 { border-right: #000000 1px solid; border-left: #000000 1px solid; border-bottom: #000000 1px solid; background-color: #669966; height: 25px; background-image: url(Images/title_bar_grapic.gif); background-repeat: repeat-x; background-position: top; }

Administration and Security Guide 485

Chapter 31: Customizing the Appearance of IBM Cognos 8

Example - Change the Portal Graphics

Suppose you want to remove or replace some of the Web portal graphics for a specific style (p. 479). When replacing the images, we recommend that you retain the same file name. The following table shows the files located in the directory c8_location/webcontent/skins/style/branding that supply the currently used images.

File
branding/portal_splash.gif

Contents
The splash screen image for IBM Cognos Connection The About box graphic The banner image The animated progress image The IBM Cognos image that appears in the lower-right corner of the Welcome page The watermark image that appears in the background of the About box. The IBM Cognos 8 image that appears in the Welcome pages and in the splash screens

branding/about.gif branding/banner_cogsquare.gif branding/progress.gif branding/cognos_sm.gif

branding/logowatermark.gif

branding/cognos_product_label.gif

Example - Change the Default Fonts for Page Titles and Instructions
Suppose you want to change the initial font settings for the page title and instructions. Depending on the product locale or other circumstances, you can specify a different font style and size. In the c8_location/templates/ps/portal/system.xml file, find the section specified below, and change the values shown in bold font as required.
<param name="myPages"> <param name="fontUnit">pt</param> <!-- pt or px or % --> <param name="defaultTitleFontFace">Tahoma</param> <param name="defaultTitleFontSize">12</param> <param name="defaultInstructionsFontFace">Tahoma</param> <param name="defaultInstructionsFontSize">11</param> </param>

Modifying the Report Studio Style Sheets

The two predefined Report Studio styles are CRN (the current default) and windows. The windows folder contains styles that apply uniquely to Report Studio.

486

Chapter 31: Customizing the Appearance of IBM Cognos 8 The customizable Report Studio style sheets are located in the directory c8_location/webcontent/skins/style/pat, or c8_location/webcontent/skins/style/hal, where style represents a specific style directory (p. 479). The style sheets in c8_location/webcontent/skins/windows/pat and c8_location/webcontent/skins/windows/hal must not be changed. Component-specific graphics are located in the images subdirectories of these directories. The following table describes the contents for theReport Studio style sheets.

File
style/pat/skin.css

Contents
Defines the default interface style for Report Studio, including a section that globally sets the font Defines the default interface styles for menus and toolbars Defines a style that applies the users chosen Microsoft Windows display settings to the Report Studio interface

style/hal/hal_style_skin.css windows/pat/skin.css

Example - Change the Fonts Used in Report Studio

Suppose you want to change the default font used in the HTML interface to one that properly renders special Asian characters. Open the style/pat/skin.css file in a text editor and comment out the section that shows Tahoma as the first item in the font-family list. Select or create an entry that better meets your Unicode requirements.
@charset "UTF-8"; DIV.clsToolbar, ... DIV.clsTabPanels { font-family:Tahoma, Arial, 'MS UI Gothic', Gulim, SimSun, PMingLiU, Raghu8, 'Arial Unicode MS', 'Andale WT', sans-serif; font-size: 8pt; }

Example - Change the Colors Used in Report Studio Menus

Suppose you want to change the colors used in the Report Studio menus. Open c8_location/webcontent/skins/style/hal/hal_style.css style sheet in a text editor and change the code shown in bold font to your preferred colors.
DIV.clsMenubar, DIV.clsToolbar { background-color: black; border-top: solid white 1px; border-bottom: solid #999999 1px; color: white; } TD.clsMenubarItem, TD.clsToolbarButton { background-color: white; color: black; }

Administration and Security Guide 487

Chapter 31: Customizing the Appearance of IBM Cognos 8

TD.clsMenubarItem, TD.clsToolbarButton { background-color: white; color: black; }

Example - Change the Report Studio Graphics

Suppose you want to remove or replace some of the graphics used in Report Studio. When replacing images, we recommend that you retain the same directory structure and file name. The following table shows which files supply the currently used images. They are located in the c8_location/webcontent/skins/style/branding directory.

File
branding/rs_splash.gif

Contents
The splash screen image specifically used for Report Studio, which appears in a frame, with a progress bar below it The Welcome page banner image specifically used for Report Studio The About box graphic The banner image The animated progress image

branding/rs_welcome.gif

branding/about.gif branding/banner_cogsquare.gif branding/progress.gif

Modifying the Query Studio Style Sheets

The Query Studio style sheets are located in the directory c8_location/webcontent/skins/style/qs. Graphics specific to a particular component style, such as banner.gif, are located in the images subdirectory. The following table describes the contents for the Query Studio style sheets.

File
QSReport.css

Contents
Defines context menu styles for Query Studio. Uses points to reference font sizes. Defines report styles for Query Studio, such as the appearances of selected columns, columns that are cut, or columns that have the pointer paused over them. Defines styles for the Query Studio and Cognos Viewer interfaces, including the application title area, left pane menu, toolbar, metadata tree, preview pane, and navigation links.

QSSelection.css

QSRVCommonUI.css

488

Chapter 31: Customizing the Appearance of IBM Cognos 8

File
QSRVDialog.css

Contents
Defines styles for the Query Studio and Cognos Viewer dialog boxes. This file is used only to avoid having to include large .css files for every dialog box.

Example - Change the Colors Used in Query Studio Menus

Suppose you want to change the colors used in Query Studio menus. Open the QSRVCommonUI.css style sheet in a text editor and change the code shown in bold font to your preferred colors.
.menuHeader { font-size: 70%; color: #336699; border-collapse: collapse; font-weight: bold; ... } .menuItem, .menuItemSpacer, .menuItemSpacerTop { background-color: #E3E9F3; border: solid #336699; border-width: 0px 1px; border-collapse: collapse; } .menuItem { font-size: 70%; color: 336699; padding: 3px 5px; text-decoration: underline; cursor: pointer; cursor: hand; } .menuItemSelected { color: 336699; border-collapse: collapse; cursor: default; padding: 3px 10px; border: 1px solid #336699; height:20px; font-size: 70%; font-weight: bold; }

Example - Change the Query Studio Graphics

Suppose you want to remove or replace some of the graphics used in Query Studio. The brandingrelated graphics are grouped together in the c8_location/webcontent/skins/style/branding directory. Graphics specific to the Query Studio component, such as banner.gif, are located in the images subdirectory of the directory c8_location/webcontent/skins/style/qs. When replacing images, we recommend that you retain the same directory structure and file names, as shown in the following table.

Administration and Security Guide 489

Chapter 31: Customizing the Appearance of IBM Cognos 8

File
branding/about.gif branding/banner_cogsquare.gif branding/progress.gif

Contents
The About box graphic The banner image The animated progress image

Note: Query Studio has no splash screen or Welcome banner.

Customize the Query Studio Toolbar and Menus

You can customize the Query Studio toolbar and menus by adding or removing buttons, menus, and menu items.

Steps to Add a Toolbar Button

1. Stop the IBM Cognos 8 service. 2. Open the file c8_location/templates/ps/qs/ui.xml in an XML or text editor. 3. Insert the following XML code for the new button:
<button> <name> Name_of_button </name> <link> getConfigFrame().JavascriptFunction() </link> <tooltip> Localized String </tooltip> <icon state="active">Path to icon graphic image </icon> <icon state="inactive"> Path to icon graphic image </icon> </button>

Tip: You can specify separators between toolbar buttons or groups of toolbar buttons by inserting a <separator/> tag between buttons. 4. Save and close the file. 5. Open the file c8_location/webcontent/qs/cmd.js in a text editor, and add a Javascript function that corresponds to the JavascriptFunction for the new button. 6. Save and close the file. 7. Start the IBM Cognos 8 service.

490

Chapter 31: Customizing the Appearance of IBM Cognos 8 Tip: To change the function called by a toolbar button, add a new Javascript function to the cms.js file and change the JavascriptFunction in the toolbar.xml file to call the new function.

Steps to Remove a Toolbar Button

1. Stop the IBM Cognos 8 service. 2. Open the file c8_location/templates/ps/qs/ui.xml in an XML or text editor. 3. Delete the XML code that corresponds to the toolbar button you want to remove, beginning with the <button> tag and ending with the </button> tag. 4. Save and close the file. 5. Start the IBM Cognos 8 service.

Steps to Add a Menu Item

1. Stop the IBM Cognos 8 service. 2. Open the file c8_location/templates/ps/qs/ui.xml in an XML or text editor. 3. Insert the following XML code for the new menu item. If you do not want an icon to represent the menu item, do not include the icon element.
<menuItem> <name> Localized String </name> <tooltip> Localized String </tooltip> <link> getConfigFrame().JavascriptFunction() </link> <icon> Path to icon graphic image </icon> </menuItem>

Tip: You can specify separators between menu items or groups of menu items by inserting a <separator/> tag between menuItems. 4. Save and close the file. 5. Open the file c8_location/webcontent/qs/cmd.js in a text editor, and add a Javascript function that corresponds to the JavascriptFunction for the new menu item. 6. Save and close the file. 7. Start the IBM Cognos 8 service. Tip: To change the function called by a menu item, add a new Javascript function to thecms.js file and change the JavascriptFunction in the menu.xml file to call the new function.

Steps to Remove a Menu Item

1. Stop the IBM Cognos 8 service.

Administration and Security Guide 491

Chapter 31: Customizing the Appearance of IBM Cognos 8 2. Open the file c8_location/templates/ps/qs/ui.xml in an XML or text editor. 3. Delete the XML code that corresponds to the menu item you want to remove, beginning with the <menuItem> tag and ending with the </menuItem> tag. 4. Save and close the file. 5. Start the IBM Cognos 8 service.

Steps to Add a Menu

1. Stop the IBM Cognos 8 service. 2. Open the file c8_location/templates/ps/qs/menu.xml in an XML or text editor. 3. Insert the following XML code for the new menu. The name of the menu is the label shown for the menu in the user interface. The value of the alias attribute, used to identify the menu, must not contain any spaces.
<menu alias="non_localized_string"> <name> Localized String </name> <menuItem> ... </menuItem> <menuItem> ... </menuItem> ... </menu>

Tip: You can specify separators between menu items or groups of menu items by inserting a <separator/> tag between menuItems. 4. Save and close the file 5. Start the IBM Cognos 8 service.

Steps to Remove a Menu

1. Stop the IBM Cognos 8 service. 2. Open the file c8_location/templates/ps/qs/menu.xml in an XML or text editor. 3. Delete the XML code that corresponds to the menu you want to remove, beginning with the <menu> tag and ending with the </menu> tag. 4. Save and close the file. 5. Start the IBM Cognos 8 service.

Modifying the Appearance of Cognos Viewer

You can make the following changes to the appearance of all Cognos Viewer: modify the Cognos Viewer style sheets

492

Chapter 31: Customizing the Appearance of IBM Cognos 8 change the language of the user interface

Modifying the Cognos Viewer Style Sheets

You can modify the Cognos Viewer style sheets at the same time as you customize the Query Studio interface, or as a separate exercise. The relevant style sheets are located in the directory c8_location/webcontent/skins/style/qs. Graphics specific to a particular component style, such as banner.gif, are located in the images subdirectory. The following table describes the Cognos Viewer style sheets.

File
RVReport.css QSRVCommonUI.css

Contents
Defines report styles for Cognos Viewer. Defines styles for the Query Studio and Cognos Viewer interfaces, including the application title area and navigation links.

Example - Change the Language of the Cognos Viewer User Interface

When you view content, such as reports, in Cognos Viewer in a language other than English, French, German, or Japanese, you may want to see the Cognos Viewer user interface in the same language. This requires changing the product language in Cognos Viewer using IBM Cognos Configuration, and later selecting this language in IBM Cognos Connection. Ensure that Cognos Viewer is translated into the language you want to use. Suppose you want to change the Cognos Viewer user interface to Greek for users of reports in Greek. At the same time, you want the user interface of other IBM Cognos components, such as IBM Cognos Connection and the studios, appear in French. To make these changes, perform the following steps.

Steps to Add a New Product Language

1. Start IBM Cognos Configuration. 2. From the Actions menu, click Edit Global Configuration. 3. Click the Product Locales tab. 4. Click the Add button. 5. Type the locale code for Greek, which is el Greek will appear in the list of available product languages in IBM Cognos Connection, in My Preferences. Tip: You can see the locale codes for other languages on the Content Locales tab. 6. Click OK. 7. Save the configuration.

Administration and Security Guide 493

Chapter 31: Customizing the Appearance of IBM Cognos 8 8. Go to IBM Cognos Connection. 9. Click My Area , My Preferences.

10. On the General tab, in the Product Language drop-down list, click Greek. 11. Click OK. The Cognos Viewer user interface appears in Greek. However, other components, such as IBM Cognos Connection and the studios, continue using the default product language, which is English. To specify French as the default product language if Greek is used by the Cognos Viewer user interface, add a new product locale mapping using IBM Cognos Configuration. Note: Only languages for which a full translation of the IBM Cognos 8 user interface exists can be specified as the default product languages.

Steps to Add a New Product Locale Mapping

1. Start IBM Cognos Configuration. 2. From the Actions menu, click Edit Global Configuration. 3. Click the Product Locale Mappings tab. 4. Click the Add button. 5. Map the product languages in the following way: In the Key column, type the code for Greek, which is el-* In the Locale Mapping column, type the code for French, which is fr

6. Click OK. 7. Save the configuration. When a user opens a report in Cognos Viewer in Greek, the Cognos Viewer user interface also appears in Greek. The user interface of other components, such as IBM Cognos Connection and the studios, appears in French.

Modifying the Prompt Page Style Sheets

You can change the style definitions for the prompt pages and related controls used with all IBM Cognos 8 components by modifying the shared promptCommon.css style sheet. This style sheet is located in the directory c8_locationwebcontent/prompting/reportskin/prompting. Prompting graphics specific to a style, if present, are located in the images subdirectory. You can modify this prompt page style sheet in much the same way as you customize any of the component style sheets.

494

Chapter 31: Customizing the Appearance of IBM Cognos 8

Adding Custom Report Templates for Report Studio

Report Studio has predefined report templates that you select from when you create a new report. You can create your own custom report templates and make them available too. To add a custom report template, you must create a report specification for the template (p. 495) add a custom report template to the templates.xml file (p. 497) provide an icon for the template (p. 497) add the custom template information to the Resources.xml file (p. 497)

Note: When you reinstall or upgrade IBM Cognos 8, the changes associated with the custom report templates are not migrated. You may need to redo the above steps (p. 483).

Create a Report Specification for a Custom Report Template

There is no template object in IBM Cognos 8. Instead, you can use any report specification as a report template. You can create the report specification for your custom report template by using Report Studio, an XML editor, or a text editor.

Steps for Report Studio

1. Open Report Studio. 2. Create a new report. For more information, see the Report Studio Professional Authoring User Guide. 3. From the File menu, click Convert to Template. 4. From the Tools menu, click Copy Report to Clipboard to save the report specification XML. 5. Paste the report specification into an XML editor or text editor. 6. Delete the following information, which Report Studio adds to the XML file and which is not necessary for the template: The xmlns attribute of the report element. The template attribute of the report element. The value of the name attribute of the query element. Delete the value, but leave the double quotation marks. The value of the name attribute of the page element. Delete the value, but leave the double quotation marks. The value of the refQuery attribute of the list element.

7. Add a new template element as a parent of the report element. 8. Add a name attribute for the template element.

Administration and Security Guide 495

Chapter 31: Customizing the Appearance of IBM Cognos 8 The name you enter appears as the name of the template in the new report dialog box. 9. Save the report specification. Here is an example of the initial part of a report specification created in Report Studio. The portions to delete appear in bold.
<template name="List - corporate"> ... <report xmlns="http://developer.cognos.com/schemas/report/4.0/" expressionLocale="en" template="true"> <queries> <query name="Query1"> <source> <model/> </source> <selection/> </query> </queries> <layouts> <layout> <reportPages> <page class="pg" name="Page1"> <pageBody class="pb"> <contents> <list class="ls" refQuery="Query1"> <style> <CSS value="border-collapse:collapse"/> </style> </list> ................. </report> </template>

Steps for an XML Editor or Text Editor

1. Open the report specification in an XML editor or text editor. 2. Add the elements you want to appear in your template. For more information, see the Developer Guide. 3. Add a new template element as a parent of the report element. The name you enter appears as the name of the template in the new report dialog box. 4. Add a name attribute to the template element. The name you enter appears as the name of the template in the new report dialog box. 5. Add a <modelPath/> element for the report element. Here is a partial example of the XML for the template created in "Steps for Report Studio" (p. 495).
<xmlFragment> <template name="List - corporate"> <report> <modelPath/> ... </template> </xmlFragment>

6. Save the report specification.

496

Chapter 31: Customizing the Appearance of IBM Cognos 8

Add a Custom Report Template to the templates.xml File

The templates.xml file contains the templates that you select from when you create a new report in Report Studio. You must add your custom report template to this file.

Steps
1. Open the templates.xml file. This file is located in the c8_location/webcontent/pat/res directory. 2. Copy the XML code for the custom report template into the file. The template element must be a child element of the xmlFragment element. 3. Save and close the file.

Provide an Icon for the Custom Report Template

You can create an icon that you want to represent the custom report template. The icons in the new report dialog box are 32 x 32 pixels .gif images. You can use any graphic editor to create the icon.

Steps
1. Create the icon you want. 2. Copy the image file into the c8_location/webcontent/pat/images directory.

Add the Custom Template Information to the Resources.xml File

The Resources.xml file defines the content of the new report dialog box in Report Studio. You must modify this file by adding the information that refers to the custom report template. For the listItems element, you add a new listItem element that represents the new template. The listItem element must have the following attributes.

Attribute
idsLabel

Description
Specifies an ID that refers to a Report Studio string resource file, such as reportstudio_en.xml or reportstudio_fr.xml, located in the c8_location/webcontent/pat/res directory, and a label for the template that appears in the new report dialog box. Use this attribute when you want to translate the label into other languages. If you do not wantto translate the label, use the label attribute instead.

Administration and Security Guide 497

Chapter 31: Customizing the Appearance of IBM Cognos 8

Attribute
label

Description
Specifies a label for the template that appears in the new report dialog box. Use this attribute instead of the idsLabel attribute for the custom template when you do not want to translate the label into other languages, which eliminates the need to use the string resource files, such as reportstudio_en.xml or reportstudio_fr.xml, in the c8_location/webcontent/pat/res directory.

icon

Specifies an image file located in the c8_location/webcontent/pat/images directory that is associated with the template. The image appears as an icon in the new report dialog box. Use a previously created image file for the custom report template.

templateName

Specifies the name of the custom report template.

Steps
1. Open the Resources.xml. This file is located in the c8_location/webcontent/pat/res. 2. Add a new listItem element using one of the following attributes for the custom report template:
label, if you do not want to translate the label into other languages idsLabel, if you want to translate the label into other languages

Ensure that the templateName attribute is the same as specified when creating the report specification for the custom report template. Here is an example of the edited Resources.xml file:
<listView id="New" view="icon" clipLabels="false"> <listItems> <!-- Start custom templates--> <listItem label="List - Corporate" icon="icon_list_corp.gif" templateName=" List - corporate"/> <listItem label="Crosstab - Corporate" icon="icon_crosstab_corp. gif" templateName="Crosstab - Corporate"/> <listItem label="Blank - Corporate" icon="icon_blank_corp.gif" templateName="Blank - Corporate"/> <!-- End custom templates--> <listItem idsLabel="IDS_LBL_NEW_BLANK_REPORT" icon="icon_blank.gif" templateName="Blank"/> <listItem idsLabel="IDS_LBL_NEW_LIST_REPORT" icon="icon_list.gif" templateName="List"/> <listItem idsLabel="IDS_LBL_NEW_CROSSTAB_REPORT" icon="icon_crosstab.gif" templateName="Crosstab"/> <listItem idsLabel="IDS_LBL_NEW_CHART_REPORT" icon="icon_chart.gif" templateName="Chart"/>

498

Chapter 31: Customizing the Appearance of IBM Cognos 8

<listItem idsLabel="IDS_LBL_NEW_MAP_REPORT" icon="icon_map.gif" templateName="Map"/> <listItem idsLabel="IDS_LBL_NEW_FINANCIAL_REPORT" icon="icon_financial. gif" templateName="Financial"/> <listItem idsLabel="IDS_LBL_NEW_REPEATER_REPORT" icon="icon_repeater.gif" templateName="Repeater"/> <listItem idsLabel="IDS_LBL_NEW_TEMPLATE_RT" icon="icon_template_qs.gif" templateName="Template_RT"/> <listItem idsLabel="IDS_LBL_NEW_BROWSE" icon="browse_32x32.gif" idsTooltip="IDS_TOOLTIP_NEWBROWSE" isBrowse="true"/> </listItems> </listView>

3. Save and close the file. You must now restart Report Studio for the custom report template to appear in the new report dialog box.

Administration and Security Guide 499

Chapter 31: Customizing the Appearance of IBM Cognos 8

500

Chapter 32: Customizing the Functionality of IBM Cognos 8

You can customize how IBM Cognos 8 works to suit your particular needs. Presentation services in IBM Cognos 8 maintain XML-based system configuration files named system.xml that are used to customize the product user interface and functionality. Before you start customizing IBM Cognos 8, you may want to migrate the customization changes made in the ReportNet system.xml files (p. 501). You can implement the following customizations: Customize IBM Cognos Connection (p. 502) Start Query Studio in Preview Mode (p. 520) Customize Query Studio Data Formats (p. 520) Change the Default Template for Query Studio (p. 525) Modify Properties for the CSV Output Format (p. 526) Modify Properties for the Batch Report Service and Report Service (p. 529) Customize Error-Handling on the SMTP Mail Server (p. 530) Disable Report Attachments in Email Messages (p. 534) Show attachments in IBM Lotus Notes (p. 534) Disable support for trigger-based scheduling (p. 535) Set up trigger occurrences on a server (p. 535) Hide history summary counts (p. 537) Change the Suppression Functionality in Analysis Studio (p. 538)

For more information about IBM Cognos 8 customizations, see "Customizing the Appearance of IBM Cognos 8" (p. 479).

Upgrade the ReportNet system.xml Files to IBM Cognos 8

The IBM Cognos 8 presentation service supports automatic upgrade of the ReportNet system.xml files. You can use this approach if many customization changes were made in ReportNet and implementing them manually in IBM Cognos 8 would be time-consuming. The system.xml files are upgraded to an IBM Cognos 8 compatible version. All existing ReportNet system.xml parameters can be upgraded to IBM Cognos 8.

Administration and Security Guide 501

Chapter 32: Customizing the Functionality of IBM Cognos 8 If the automatic upgrade is not successful, the system.xml file is not upgraded successfully and a message is generated in the server log. You can perform the upgrade manually using one of the following files in the c8_location/templates/ps directory: for UNIX, system_upgrade.sh for Windows, system_upgrade.bat

For more information, see the system_upgrade.txt file in the same directory. Note: As a general approach, we recommend that you edit the system.xml files manually using a UTF-8-based XML or text editor. Perform the following steps when IBM Cognos 8 and ReportNet are installed in different locations.

Steps
1. Back up the original IBM Cognos 8 versions and the customized ReportNet versions of the system.xml files. 2. Copy the required system.xml file from the ReportNet installation directory to the corresponding directory in the IBM Cognos 8 installation directory. Copy all system.xml files that require upgrade. The process cannot be repeated for each file separately. For example: copy the system.xml file from the crn_location/templates/ps directory to the c8_location/templates/ps directory. 3. Restart the IBM Cognos 8 service.

Customizing IBM Cognos Connection

You can do the following to customize IBM Cognos Connection: Add or hide user interface elements based on groups and roles (p. 503) Hide and disable the new URL button (p. 508) Limit the number of entries that users can cut, copy, and paste (p. 509) Customize object actions (p. 509) Restrict content browsing (p. 513) Implement a custom Welcome page (p. 514) Customize report output formats in IBM Cognos Connection and Cognos Viewer (p. 517) Customize the document lookup table (p. 519)

502

Chapter 32: Customizing the Functionality of IBM Cognos 8

Add or Hide User Interface Elements Based on Groups and Roles

You can customize the IBM Cognos Connection user interface based on the group and role membership. Depending on the group or role to which users belong, certain user interface elements will or will not be available to them. For example, you can hide the preferences and studio links from some users and add links to external applications for other users. To implement this functionality, perform the following tasks: Hide user interface elements (p. 503) Add user interface elements (p. 506) Reference the required groups or roles in the system.xml file (p. 507)

Some user interface elements are shared by IBM Cognos Connection and Cognos Viewer, for example the top header (m1). If you hide these shared interface elements in IBM Cognos Connection, they are also hidden in Cognos Viewer. For a list of elements you can hide and add, see "User Interface Elements Reference List" (p. 707). Note: It is important to note that there is a difference between hiding a UI element and disabling it. Hiding means that the element will no longer be visible, but that the functionality is still available. Disabling a UI element means that the element is not visible and that the underlying functionality is no longer available.

Hide User Interface Elements

You can use URL commands to hide user interface elements for a session, or you can edit the applicable system.xml file to hide user interface elements permanently. When you hide user interface elements in page headers, these elements are not hidden elsewhere in IBM Cognos 8. For example, Report Studio can be run from the Welcome page or from the Launch menu in the h1 header. Hiding the IBM Cognos 8 header using the URL command does not hide the Report Studio link in the Welcome page.

Using URL Commands

Type URL commands in your browser if you want to hide user interface elements for the current IBM Cognos 8 request or session only. You can use URL commands to hide UI elements for both IBM Cognos Connection and Cognos Viewer. IBM Cognos Connection commands can only be appended to IBM Cognos Connection URLs, and Cognos Viewer commands can only be appended to Cognos Viewer URLs. For example, adding &ui=t3m4 at the end of an Cognos Viewer URL does not affect IBM Cognos Connection. Cognos Viewer commands do not affect the IBM Cognos Connection user interface. For example, adding the Cognos Viewer command &tb=0 at the end of an IBM Cognos Connection URL will show no effect. However, IBM Cognos Connection commands may affect Cognos Viewer indirectly. For example, hiding the top header in IBM Cognos Connection will also hide the header in Cognos Viewer. The following example shows the headers in the IBM Cognos Connection main page.

Administration and Security Guide 503

Chapter 32: Customizing the Functionality of IBM Cognos 8

You can use URL commands to hide the following IBM Cognos Connection headers or sections of a header: the IBM Cognos Connection top header (h1) that includes the title (t1), the Launch menu (m1), and all right-hand side header options. the tab bar (h3) that includes tabs such as Public Folders, My Folders, and custom pages (t3). the IBM Cognos Connection header (h4) that includes the navigation path (t4), and the toolbar menu (m4).

Using the System.xml File

To hide all instances of a user interface element in IBM Cognos Connection, you must modify the system.xml file. To hide user interface elements in Public Folders or My Folders, modify the systm.xml file in the c8_location/templates/ps/portal directory. To hide user interface elements in portal pages and dashboards with multiple tabs, modify the systm.xml file in the c8_location/templates/ps directory. Modifying the system.xml file is more flexible than using URL commands for these reasons: You can hide more user interface elements. You can restrict the appearance of user interface elements based on user type or membership in groups and roles.

Steps Using URL Commands in IBM Cognos Connection

1. Start IBM Cognos 8. 2. In IBM Cognos Connection, click in the Web address box and type the following at the end of the URL: &ui=user_interface_elements_to_hide where user_interface_elements_to_hide is one or more of t1, t4, m1, m4, h1, h3, or h4. For example, type: &ui=h1m4 The hidden UI remains hidden for the rest of the user session. 3. To restore the hidden elements, type &ui= at the end of the URL.

Steps Using URL Commands in Cognos Viewer When Viewing Reports

1. Start IBM Cognos 8. 2. In Cognos Viewer, click in the Web address box and type on of the following at the end of the URL:

504

Chapter 32: Customizing the Functionality of IBM Cognos 8 3. To turn off the Cognos Viewer toolbar, type: cv.toolbar=false To turn off the Cognos Viewer header, type: cv.header=false The hidden UI remains hidden for the rest of the user request.

Steps Using the System.xml File

1. Stop the IBM Cognos 8 service. 2. Open the system.xml file in one of the following locations: c8_location/templates/ps/portal Use the system.xml file in this directory to hide user interface elements in Public Folders or My Folders. c8_location/templates/ps Use the system.xml file in this directory to hide user interface elements in pages and dashboards with multiple tabs. 3. Use the following syntax in the <system> element to hide a user interface element:
<param name="ui_hide"> <!--list of user interface elements--> </param>

For example, the following XML code hides the entire IBM Cognos Connection header and the New Job button in the toolbar:
<param name="ui_hide"> <CC_HEADER/> <CC_TOOLBAR_BUTTONS_newjobDefinition/> </param>

For information about all the user interface elements that you can hide, see "Elements You Can Hide" (p. 707). Ensure that you match the case of each user interface element you want to hide. 4. Specify one or more groups or roles you want to view the hidden element by adding their IDs as values of the show attribute. Use the group or role IDs as documented in the topic "Reference the Required Groups or Roles in the system.xml File " (p. 507). Separate IDs using spaces. Here is an example:
<param name="ui_hide"> <CRN_HEADER show="Administrators g1 g2 RSUsers"/> </param>

5. Repeat steps 3 to 4 for each element that you want to hide. 6. Save the file.

Administration and Security Guide 505

Chapter 32: Customizing the Functionality of IBM Cognos 8 7. Start the IBM Cognos 8 service. Tip: There can be only one <param name="ui_hide"> element in system.xml. Therefore, all items you want to hide must be placed inside this element.

Add User Interface Elements

You can add user interface elements to IBM Cognos Connection to connect to external applications or to modify the functionality of IBM Cognos Connection. You can restrict the appearance of these new user interface elements based on different types of users. The xml:lang attribute of the label and tooltip elements corresponds to the product locale in use at the time of the portal page generation. If a new product locale is added to IBM Cognos 8, you must add a translation for the label and tooltip fields. When no label or tooltip is found that matches the product locale, nothing is displayed. The graphic referenced by the icon element must exist in the c8_location/webcontent/ps/portal/ images directory. To add a user interface element in IBM Cognos Connection, you must modify the system.xml file.

Steps
1. Stop the IBM Cognos 8 service. 2. Open the c8_location/templates/ps/portal/system.xml file in an XML or text editor. 3. Use the following syntax in the <system> element to add a user interface element:
<param name="ui_add"> <!--list of user interface elements--> </param>

For example, the following XML code adds an option to start a Google search in a new browser window.
<param name="ui_add"> <CRN_HEADER_OPTIONS> <item> <url>http://www.google.com</url> <target>_blank</target> <label xml:lang="en">Google</label> <tooltip xml:lang="en">Google</tooltip> <label xml:lang="fr">Google</label> <tooltip xml:lang="fr">Google</tooltip> <label xml:lang="de">Google</label> <tooltip xml:lang="de">Google</tooltip> <label xml:lang="ja">Google</label> <tooltip xml:lang="ja">Google</tooltip> <icon>action_search.gif</icon> </item> </CRN_HEADER_OPTIONS> </param>

For information about all the user interface elements that you can add, see "Elements You Can Add" (p. 714). Ensure that you match the case of each user interface element you want to add. 4. Specify one or more groups or roles you want to view the new interface element by adding their IDs as values of the show attribute.

506

Chapter 32: Customizing the Functionality of IBM Cognos 8 Use the IDs as documented in the topic "Reference the Required Groups or Roles in the system.xml File " (p. 507). Separate IDs using spaces. Here is an example:
<param name="ui_add"> <CC_VIEW_TOOLS> <item show="Administrators RSUsers g1 g2"> <url>http://my_server_url/myApplication</url> <target>_blank</target> <label xml:lang="en">My_label in English</label> <label xml:lang="fr">My_label in French</label> <label xml:lang="de">My_label in German</label> <label xml:lang="ja">My_label in Japanese</label> </item> </CC_VIEW_TOOLS> </param>

5. Save the file. 6. Restart the IBM Cognos 8 service. Tip: There can be only one <param name="ui_add"> element in system.xml. Therefore, all items you want to add must be placed inside this element.

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. You can use the predefined groups and roles (p. 233), or your custom groups and roles (p. 208). The predefined groups and roles that can be used include:

User
Anonymous

ID
Anonymous

Description
Users who can access IBM Cognos 8 without being prompted for authentication Users who have the administration capability All authenticated users, which includes Administrators, Query Studio Users, and Report Studio Users

Administrators Consumers

Administrators Consumers

Administration and Security Guide 507

Chapter 32: Customizing the Functionality of IBM Cognos 8

User
Query Studio Users Report Studio Users

ID
QSUsers RSUsers

Description
Users who have the Query Studio capability Users who have the Report Studio capability

Steps
1. Stop the IBM Cognos 8 service. 2. Open the c8_location/templates/ps/portal/system.xml file in an XML or text editor. 3. Add a parameter named ui_groups and then do the following: Add the group element for each group or role you want. Specify a unique id attribute for each group or role. The IDs are case sensitive. 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. For the IBM Cognos 8 predefined groups, use the associated IDs as documented the table above. 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, ID and URL 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>

4. Save the system.xml file. 5. Restart the IBM Cognos 8 service.

Hide and Disable the New URL Button

Hiding UI elements such as toolbar buttons allows you to declutter the UI, but hiding alone will not disable the functionality behind the UI element. For security reasons, if you want to hide the new URL button, it is best to disable it. Doing so hides the button, but more importantly, eliminates the possibility of someone adding an undesirable URL.

Steps
1. Stop the IBM Cognos 8 service. 2. Open the c8_location/templates/ps/portal/system.xml file in an XML or text editor. 508

Chapter 32: Customizing the Functionality of IBM Cognos 8 3. Add the following parameter:
<param name="disableURLObjectCreation">true</param>

4. Save the system.xml file. 5. Restart the IBM Cognos 8 service. The new URL toolbar button is removed, the URL field on the object creation wizard is disabled, and all URL object creation requests on the server handler will be ignored.

Limit the Number of Entries That Users Can Cut, Copy, and Paste
You can limit the number of entries that users can cut, copy, and paste to improve the performance of IBM Cognos 8. This allows you to control the storage space taken up by temporary entries and reduce the time required to execute cut, copy, and paste requests. For example, you can set the limit to 50 entries. If users cut, copy, or paste more than 50 entries, they receive a maximum entries message. For more information about other tasks you can perform to improve the performance of IBM Cognos 8, see "Tune Server Performance" (p. 127). To change the limit, you must have access to the computer where the report server is installed.

Steps
1. On each computer where IBM Cognos 8 is installed, open the c8_location/templates/ps/portal/ system.xml file in an editor. Ensure that your editor supports saving files in UTF-8 format. 2. Find and edit the maxEditEntries parameter as follows:
<param name="maxEditEntries"> 50 </param>

3. Save the system.xml file. 4. Stop and then restart the IBM Cognos 8 service. For more information about stopping IBM Cognos 8, see the Installation and Configuration Guide.

Customizing Object Actions

You can customize the actions available for package, folder, URL, jobDefinition, query, report, reportView in IBM Cognos Connection. For a list of actions that you can customize, you can look at the c8_location/templates/ps/portal/ system.xml file. Search for "base-object-actions".

Administration and Security Guide 509

Chapter 32: Customizing the Functionality of IBM Cognos 8

Remove an Action
To remove an action for a class of objects, such as reports, in the IBM Cognos Connection user interface, you must modify the system.xml file. When you remove an action, users no longer have access to it.

Steps
1. Stop the IBM Cognos 8 service. 2. Open the c8_location/templates/ps/portal/system.xml file in an XML or text editor. 3. Locate the following XML code that describes the actions for the objects in IBM Cognos Connection:
<param name="base-object-actions"> <actions> ... </actions> </param>

4. Remove the action For example, the following XML code describes the actions for reports:
<param name="base-object-actions"> <actions> ... <object class="report"> ... <action name="run_options"/> ... </object> ... </actions> </param>

Remove the following line:

<action name="run_options"/>

The run options action is no longer available in IBM Cognos Connection for reports. 5. Save the file. 6. Start the IBM Cognos 8 service.

Expose a Shortcut Action

A shortcut action gives users the ability to create shortcuts to a class of objects. By default, shortcut actions appear on the IBM Cognos Connection actions page. To add a shortcut action for a class of objects, such as reports, to the IBM Cognos Connection main page, you must modify the system.xml file.

Steps
1. Stop the IBM Cognos 8 service. 2. Open the c8_location/templates/ps/portal/system.xml file in an XML or text editor.

510

Chapter 32: Customizing the Functionality of IBM Cognos 8 3. Locate the following XML code that describes the actions for the objects in IBM Cognos Connection:
<param name="base-object-actions"> <actions> ... </actions> </param>

4. Add the following line of XML code to the actions for the class of objects:
<action name="shortcut" visible="main"/>

For example, the following XML code includes a shortcut action in the actions for folders:
<param name="base-object-actions"> <actions> ... <object class="folder"> <action name="shortcut" visible="main"/> </object> ... </actions> </param>

5. Save the file. 6. Start the IBM Cognos 8 service.

Add a Custom Action

To add a custom action for package, folder, URL, jobDefinition, query, report, or reportView objects in the IBM Cognos Connection user interface, you must modify the system.xml file. Add a custom action when you want to run an SDK application for a particular class of object, such as a report. You can pass the following properties of an object to an application: defaultName defaultOutputFormat searchPath uri permissions usage disabled

In the IBM Cognos Connection main view, custom action icons appear to the left of the More link. In the Perform an action dialog box, custom actions appear under the IBM Cognos-specified actions.

Steps
1. Stop the IBM Cognos 8 service. 2. Open the c8_location/templates/ps/portal/system.xml file in an XML or text editor. 3. Locate the following XML code that describes the actions for the objects in IBM Cognos Connection: Administration and Security Guide 511

Chapter 32: Customizing the Functionality of IBM Cognos 8

<param name="base-object-actions"> <actions> ... </actions> </param>

4. Use the following syntax to add a custom action as a child of the <object> element for the class of object you want to associate the custom action with. The <object> elements are children of the <actions> element. Note that an English tooltip and label are required.
<action name="name" type="custom"> <icon> icon to show for this element </icon> <url> http-encoded URL to execute </url> <label xml:lang="en"> link text </label> <tooltip xml:lang="en"> tooltip text </tooltip> <label xml:lang="language"> link text </label> <tooltip xml:lang="language"> tooltip text </tooltip> <objProperties encode="encoding"> <property> property to be passed to application </property> </objProperties> </action>

For example, the following XML code defines a custom action for a report object that launches an ASP application named myapp. The defaultName and searchPath properties of the report are passed to the application.
<param name="base-object-actions"> <actions> ... <object class="report"> ... <action name="showPath" type="custom"> <icon> action_myaction.gif </icon> <url> /myapp.asp</url> <label xml:lang="en"> View the search path </label> <tooltip xml:lang="en"> View the search path </tooltip> <label xml:lang="fr"> Afficher le chemin d'accs </label> <tooltip xml:lang="fr"> Afficher le chemin d'accs </tooltip> <objProperties encode="shift_jis"> <property>

512

Chapter 32: Customizing the Functionality of IBM Cognos 8

defaultName </property> <property> searchPath </property> </objProperties> </action> </object> ... </actions> </param>

5. Save the file. 6. Start the IBM Cognos 8 service.

Restrict Content Browsing

By default, IBM Cognos Connection users can browse public folders starting at the root content folder (/content). You may want to restrict the folders that users can browse. You can set the root content folder that users can browse to any path for: a given session, using the URL interface all sessions, using a system setting in the system.xml file This setting does not apply to administrators.

Root Content Folder Changes

When you specify a root other than the root content folder, the following changes occur: Content navigation is restricted to the root folder and its subfolders. Search results are limited to objects that are contained in the root folder and its subfolders. The Location property in the Properties dialog box shows the path beginning at the root folder. The choice of destination folders when a consumer creates new content is limited to the root folder and its subfolders.

Considerations
Specifying a root folder other than the root content folder does not restrict administrative functions such as schedule management. Restricting content browsing by specifying a new root folder is not a means of enforcing security. Folder access must be controlled using the IBM Cognos 8 security model.

Steps Using a URL Command

1. Start IBM Cognos 8. 2. Click in the Web address box and delete any path parameters specified by &m_path. If you do not remove these path parameters, they override the root setting. 3. Type the following at the end of the URL:

Administration and Security Guide 513

Chapter 32: Customizing the Functionality of IBM Cognos 8 &m_root=url-encoded search path For example, if you want to restrict browsing to the Go Sales package, while hiding the tab bar, toolbar and standard IBM Cognos 8 header options, type the following: &m_root=%2Fcontent%2Fpackage%5B%40name%3DGO%20Sales%5D&ui=m1h3m4.

Steps Using the System.xml File

1. Stop the IBM Cognos 8 service. 2. Open the c8_location/templates/ps/portal/system.xml file in an XML or text editor. 3. Modify the <param name="consumer-root"> line in the following way:
<param name="consumer-root">search path</param>

For example, typing the following sets the root folder to a folder named Folder1 in the package named Pack1.
<param name="consumer-root"> /content/package[@name='Pack1']/folder[@name='Folder1']</param>

4. Save the file. 5. Start the IBM Cognos 8 service.

Implementing a Custom Welcome Page

You can create a custom Welcome page and configure IBM Cognos Connection to use this page instead of the default page provided by IBM Cognos 8. The custom Welcome page can be any type of a browser page, such as .html, .asp, or .jsp. To provide Welcome pages that are locale- and style-sensitive, you must create a separate page for each language and style (p. 437). When you create a custom Welcome page, you can reuse some elements from the default Welcome page to make your job easier (p. 514). After the page is created, configure your Web server and your application server to expose the new Welcome page (p. 516), and configure IBM Cognos Connection to use it (p. 516).

Reuse Elements From the Default Welcome Page

There are elements in the IBM Cognos 8 Welcome page that may be difficult to implement, especially the logon link and the links to different studios. To make your job easier, you can reuse these elements from the default Welcome page. You can create a page with any content that, through an iFrame, frame, and so on, references the links-only section of the Welcome page. The links-only page will look like this.

514

Chapter 32: Customizing the Functionality of IBM Cognos 8

If you want to change the background color, modify the welcomeToolPanel parameter in the default.css file associated with the style you are using. For more information, see "Example - Customize the Default Welcome Page" (p. 484).

Steps
1. In a text editor, such as Notepad, type the code for the page using the following parameters in the page URL.

Parameter
basewelcome

Values
yes no

Description
This mandatory parameter renders the default Welcome page that only contains the links. This optional parameter specifies where the links appear in the custom Welcome page. Do not include this parameter if you want the links to appear in the same frame.

wtarget

top parent self (default)

The following URL renders the links-only, default Welcome page:

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

For example, if you want to create a custom Welcome page with only one iFrame that uses the links-only page, the source code for the page could be as follows:
<html> <head></head> <body> <iframe width="100%" height="100%" src="http://localhost/cognos8/cgi-bin/cognos.cgi?b_ action=cognosViewer&m=portal/welcome/welcome.xts&basewelcome=yes&wtarget=top"/ > </body> </html>

Administration and Security Guide 515

Chapter 32: Customizing the Functionality of IBM Cognos 8 2. Save the file.

Create the Required Directories

After the custom Welcome page is created, you must save it in a directory that can be accessed by IBM Cognos 8. We recommend that you place your file in a directory that is separate from your IBM Cognos 8 installation. If you create your page as a set of HTML pages, you can set up a virtual directory for your custom Welcome page. For example, you can create the my_welcome virtual directory in c8_location\my_ welcome, where my_welcome is the location of your custom Welcome page, and grant read permissions for the directory. After the virtual directory is set up, you can save the custom Welcome page in it. If you create custom pages for different locales and styles, you must create directories for each locale and style. The directories must be named after the style and locale. For example, if you want to provide a custom Welcome page for the English, French, German, and Japanese locales for all the predefined styles, you must create the following directory structure for each of the en, fr, de, and ja locales, where my_welcome is the virtual directory, and then copy the individual custom Welcome pages into the proper directories. my_welcome/locale/business my_welcome/locale/classic my_welcome/locale/contemporary my_welcome/locale/corporate my_welcome/locale/modern my_welcome/locale/presentation

For more information about setting up virtual directories, see the Installation and Configuration Guide.

Configure IBM Cognos Connection to Use a Custom Welcome Page

You configure IBM Cognos Connection to use a custom Welcome page by adding the welcomeURLOverride parameter to the system.xml file located in the c8_location/templates/ps/ portal directory. The welcomeURLOverride parameter overrides the default Welcome page URL. Depending on the location of the custom Welcome page, the URL can be specified as a relative or absolute path. Note: The path names are case sensitive on UNIX.

Locale and Style Considerations

If you want to implement a custom Welcome page that is style and locale-sensitive, the page URL must use the exposed replacement parameters for the locale and style. The parameters are %LOCALE% and %STYLE%. When the URL is processed, %LOCALE% is replaced by the product locale, and%STYLE% is replaced by the user's currently selected style.

516

Chapter 32: Customizing the Functionality of IBM Cognos 8 For example, if the product language is English and the style is Corporate, the welcomeURLOverride parameter is as follows:
<param name= "welcomeURLOverride">/cognos8/my_welcome/%LOCLAE%/%STYLE%/customwel.htm <param>

When the URL is processed, the %LOCALE% parameter is replaced with en, and the %STYLE% parameter is replaced with Corporate. The URL for this example is as follows:
/cognos8/my_welcome/en/Corporate/customwel.htm

If the product locale were set to French and the style to Classic, the URL would be as follows:
/cognos8/my_welcome/fr/Classic/customwel.htm

Steps
1. From the c8_location/templates/ps/portal directory, open the system.xml file. 2. Add the welcomeURLOverride parameter to the file, where customwel.htm is the custom Welcome page. If you use a relative path, the syntax is:
<param name="welcomeURLOverride">/cognos8/customwel.htm </param>

If you use an absolute path, the syntax is:

<param name="welcomeURLOverride">http://.../customwel.htm </param>

If your Welcome page supports different locales and styles and you use a relative path, the syntax is:
<param name="welcomeURLOverride">/cognos8/my_welcome/%LOCALE%/%STYLE%/ customwel.htm <param>

3. Save and close the system.xml file. 4. Refresh IBM Cognos Connection.

Customize Report Output Formats in IBM Cognos Connection and Cognos Viewer
You can specify which formats are available for users to view their reports. For example, you may want to prevent users from exporting reports in Excel. The report formats available to a user appear in the user preferences (p. 260). The report formats are controlled by the format element of the reportFormats parameter in the system.xml file located in the c8_location/templates/ps directory. The format element has the following attributes:

Attribute
id

Value
Report output formats. For example, HTML or PDF

Description
Specifies the supported report format. This attribute cannot be modified.

Administration and Security Guide 517

Chapter 32: Customizing the Functionality of IBM Cognos 8

Attribute
browserHide

Value
ie safari moz other

Description
Excludes Web browsers in which the report format should be hidden from users. You can modify this attribute.

downloadable

true false

Specifies the download support. You can modify this attribute

appMode

basic - basic run options and preferences

Specifies the IBM Cognos 8 functions where the report format must be supporadv - advanced run options and ted. scheduling You can modify this attribute. rv - report viewing options

extension

Extension value For example, xls

Optional attribute that specifies the file extension of the output format. It is used to control download functionality. Optional attribute that specifies the MIME type. It is used to control download functionality. Specifies the IBM Cognos Application Firewall settings. This attribute cannot be modified.

mime

Mime value. For example, application/vnd. ms-excel

cafaction

true false

Note: Because the format element settings can be used to control access to output formats, this setting can affect how reports that were saved previously are accessed. For example, if a report is saved in PDF format, users cannot view the saved report if the administrator chooses to make the PDF format unavailable. The following example shows how to remove CSV format from the list of available format options, for example, when setting personal preferences or scheduling reports, while still allowing users access to saved CSV output in the portal.
<format id="CSV" browserHide="" downloadable="true" appMode="" extension="csv"/>

The following example shows how to hide the report output completely.
<!--<format id="CSV" browserHide="" downloadable="true" appMode="" extension="csv"/> -->

Steps
1. Open the system.xml file in the c8_location/templates/ps directory. 518

Chapter 32: Customizing the Functionality of IBM Cognos 8 2. In the following code, remove or comment out the format element associated with the report format you want to disable.
<param name="reportFormats"> <!-- Comments --> <format id="HTML" browserHide="" downloadable="false" appMode="basic adv rv"/> <format id="XHTML" browserHide="" downloadable="false" appMode="adv"/> <format id="HTMLFragment" browserHide="" downloadable="false" appMode="adv"/> <format id="PDF" browserHide="" downloadable="true" appMode="basic adv rv" extension="pdf"/> --> <format id="spreadsheetML" browserHide="safari" downloadable="true" appMode="basic adv rv" extension="xlsx"/> <format id="XLWA" browserHide="safari" downloadable="true" appMode="basic adv rv" extension="xls" mime="application/vnd.ms-excel"/> <format id="singleXLS" browserHide="safari" downloadable="true" appMode="basic adv rv" extension="xls"/> <format id="XLS" browserHide="safari moz other" downloadable="false" appMode="basic adv rv" cafaction="true"/> <format id="CSV" browserHide="" downloadable="true" appMode="basic adv rv" extension="csv"/> <format id="XML" browserHide="" downloadable="true" appMode="basic adv rv" extension="xml"/> </param>

The following example shows how to disable the PDF format:

<!-- <format id="PDF" browserHide="" downloadable="true" appMode="basic adv rv"/> -->

The following example shows how to disable support for the CSV format for advanced run options and scheduling by deleting the adv attribute:
<format id="CSV" browserHide="" downloadable="true" appMode="basic rv"/>

3. Save the system.xml file. 4. Restart the IBM Cognos 8 service. Note that the configuration settings you specify in the system.xml file apply only to the presentation services which includes the portal, portal administration, and Cognos Viewer. The settings do not apply to the report server.

Configure the Document Lookup Table

The document format lookup table is used to look up file extensions when downloading document objects. Most browsers require file extensions to determine which program to use to open the file. If the name of the file being downloaded does not end with the expected extension, the portal will append one based on the document lookup table, found in the system.xml file. The following example shows the document format code:
<param name="documentFormats"> <format extension="doc" id="application/vnd.coc-wd"/> <format extension="xls" id="application/vnd.coc-xl"/> <format extension="ppt" id="application/vnd.coc-pp"/> <format extension="xlsx" id="application/vnd.openxmlformats-officedocument. spreadsheet.sheet"/> <format extension="pptx" id="application/vnd.openxmlformats-officedocument. presentationml.presentation"/>

Administration and Security Guide 519

Chapter 32: Customizing the Functionality of IBM Cognos 8

<format extension="docx" id="application/vnd.openxmlformats-officedocument. wordprocessingml.document"/> </param>

Start Query Studio in Preview Mode

You can configure Query Studio to start in preview mode. Users can then create or modify reports without retrieving actual data from the database. Instead, simulated data is shown. If you later upgrade IBM Cognos 8, you must reapply this configuration.

Steps
1. Using IBM Cognos Configuration, stop IBM Cognos 8. 2. Rename the c8_location\templates\ps\async\system.xml.sample file to system.xml. Tip: To restore the regular mode, rename the c8_location\templates\ps\async\system.xml file to system.xml.sample. 3. Using IBM Cognos Configuration, start IBM Cognos 8.

Customizing Data Formats for Query Studio

You can customize the data formats that are available for selection in Query Studio. The data formats listed in the following table are defined in the c8_location/configuration/cogformat.xml file.

Data format
Date

Examples
19/12/03 December 19, 2003

XML code
formatList name = qsdates

Time

11:05 PM 23:05

formatList name = qstimes

Date and time

19/12/03 13:30 Dec 19, 03 1:30 PM

formatList name = qsdatetimes

Time interval

Days Seconds Milliseconds

formatList name = qsintervals

Negative numbers

-29 (29)

formatList name = qsnegatives

520

Chapter 32: Customizing the Functionality of IBM Cognos 8

Data format
Decimal character

Examples
1.23 1,23

XML code
formatList name = rsnumberinput

By modifying the cogformat.xml file, you can change the order in which data formats are presented in Query Studio. You can also change the text string that appears in Query Studio or delete a data format. If the data formats that you prefer are not available in Query Studio, you can add them to the file. Note: If you upgrade to a new version of IBM Cognos 8, your changes to the cogformat.xml file are not reflected in the new version of the file. Make a copy of the file before the upgrade, then replace the new version with your changed version.

Modify the cogformat.xml File

To modify the cogformat.xml file, follow these steps:

Steps
1. Make a backup of the c8_location/configuration/cogformat.xml file. 2. Stop the IBM Cognos 8 service. 3. Open the cogformat.xml file in an XML or text editor. 4. Make your changes as required: "Change the Order of Data Formats" (p. 521) "Change the Text Strings" (p. 522) "Remove Data Formats" (p. 523) "Add a Data Format to a Locale" (p. 524) "Add Data Formats for a New Locale" (p. 525)

5. Save the file. 6. Test the file. 7. Restart the IBM Cognos 8 service. The changes that you made to the cogformat.xml file are implemented.

Change the Order of Data Formats

You can modify the cogformat.xml file to change the order in which data formats are presented in Query Studio. For example, in your locale, the dates might be presented in the following order: 19/12/03 19-Dec-03 Administration and Security Guide 521

Chapter 32: Customizing the Functionality of IBM Cognos 8 December 19, 2003 Friday, December 19, 2003

If your users are most likely to choose the last date format, you might want it to appear first on the list of dates.

Steps
1. In the cogformat.xml file, locate the data format for the locale that you want to modify. For example, the following XML code defines the order of date formats for the en-CA (English Canadian) locale:
... <formatList name="qsdates" xml:lang="en-CA"> <dateFormat dateStyle="short">19/12/03</dateFormat> <dateFormat dateStyle="medium">19-Dec-03</dateFormat> <dateFormat dateStyle="long">December 19, 2003</dateFormat> <dateFormat dateStyle="full">Friday, December 19, 2003</dateFormat> </formatList> ...

2. To change the order in which data formats appear in Query Studio, rearrange the order of the code. For example, to have Friday, December 19, 2003 appear as the first date format, change the XML code as follows:
... <formatList name="qsdates" xml:lang="en-CA"> <dateFormat dateStyle="full">Friday, December 19, 2003</dateFormat> <dateFormat dateStyle="short">19/12/03</dateFormat> <dateFormat dateStyle="medium">19-Dec-03</dateFormat> <dateFormat dateStyle="long">December 19, 2003</dateFormat> </formatList> ...

The dates are now presented in the following order in Query Studio: Friday, December 19, 2003 19/12/03 19-Dec-03 December 19, 2003

Change the Text Strings

You can modify the cogformat.xml file to change the text strings that are presented in Query Studio. For example, in your locale, the dates might be presented as follows: 19/12/03 19-Dec-03 December 19, 2003 Friday, December 19, 2003

522

Chapter 32: Customizing the Functionality of IBM Cognos 8 If your organization uses the standard date format "19/12/03," you can change the text that appears in Query Studio to "Corporate Standard (19/12/03)".

Steps
1. In the cogformat.xml file, locate the date format for the locale you want to modify. For example, the following XML code defines the text strings for date formats for the en-CA (English Canadian) locale:
... <formatList name="qsdates" xml:lang="en-CA"> <dateFormat dateStyle="short">19/12/03</dateFormat> <dateFormat dateStyle="medium">19-Dec-03</dateFormat> <dateFormat dateStyle="long">December 19, 2003</dateFormat> <dateFormat dateStyle="full">Friday, December 19, 2003</dateFormat> </formatList> ...

2. To change the text string for a data format, edit it in the XML code. For example, change the text string for that format as follows:
<dateFormat dateStyle="short">Corporate Standard (19/12/03)</dateFormat>

The dates now appear as follows: Corporate Standard (19/12/03) 19-Dec-03 December 19, 2003 Friday, December 19, 2003

Remove Data Formats

You can modify the cogformat.xml file to remove data formats. For example, you may not want to present users with all the interval formats that are available.

Steps
1. In the cogformat.xml file, locate the data format for the locale that you want to modify. For example, the following XML code defines time interval formats for the en-CA (English Canadian) locale:
... <formatList name="qsintervals" xml:lang="en-ca"> <intervalFormat units="days">2 days</intervalFormat> <intervalFormat>1 day 23 hours 45 minutes 12 seconds 345 milliseconds</ intervalFormat> <intervalFormat units="time" showSeconds="false">1 23:45</intervalFormat> <intervalFormat units="time" showMilliseconds="false">1 23:45:12</ intervalFormat> </formatList> ...

2. To remove an interval format, remove the associated XML code line. For example, to remove milliseconds as an available interval format, remove the following line: Administration and Security Guide 523

Chapter 32: Customizing the Functionality of IBM Cognos 8

<intervalFormat units="time" showMilliseconds="false">1 23:45:12</ intervalFormat>

Note: For information on removing a locale, see the Installation and Configuration Guide.

Add a Data Format to a Locale

You can modify the cogformat.xml file to add data formats. For example, you may want to add a time format that is not included for your locale.

Valid Syntax
You must use valid syntax when adding a data format. You can use Report Studio to show you the XML code that you need for a data format. In Report Studio, create a list report that contains the data that you want. Then, select the column and change the Data Format settings in the Report Studio Properties pane to get the format you want. Its a good idea to run the report to make sure the data format looks the way you want it to. Select View XML and use the same code syntax in the cogformat.xml file. (For an XML file that you can copy and paste from, follow instructions to Open and Save a Report Locally.) For example, if you want to add a data format for date, create a report that contains a date column. Change the format of the date. Use the appropriate XML code syntax in the cogformat.xml file. Your syntax might look similar to the bold code shown below:
<formatList name="qsdates" xml:lang="en-CA"> <dateFormat dateStyle="short" datesSeparator="." </dateFormat> <dateFormat dateStyle="full">Friday, December 19, 2003</dateFormat> <dateFormat dateStyle="short">19/12/03</dateFormat> <dateFormat dateStyle="medium">19-Dec-03</dateFormat> <dateFormat dateStyle="long">December 19, 2003</dateFormat> </formatList>

Steps
1. In the cogformat.xml file, locate the data format for the locale that you want to modify. For example, the following XML code defines time formats for the en-CA (English Canadian) locale:
... <formatList name="qstimes" xml:lang="en-ca"> <timeFormat timeStyle="short">1:30 PM</timeFormat> <timeFormat timeStyle="medium">1:30:55 PM</timeFormat> <timeFormat timeStyle="long">1:30:55 EST PM</timeFormat> <timeFormat timeStyle="full">1:30:55 o&apos;clock PM EST</timeFormat> </formatList>...

2. To add another time format, add another XML code line. For example, to add the time format "1:30 EST PM," add the following line:
<timeFormat timeStyle="long" showSeconds="false">1:30 EST PM</timeFormat>

3. Insert the text that you want to appear in Query Studio into the line you copied and pasted. For example:
<dateFormat dateStyle="short" dateSeparator="." show Years="showCentury">19.12.03</dateFormat>

524

Chapter 32: Customizing the Functionality of IBM Cognos 8

Add Data Formats for a New Locale

The cogformat.xml file contains most locales already. However, if necessary, you can add data formats for a new locale. Add a block of XML code for each of the data formats type.

Steps
1. Copy and paste a similar block of XML code for each data format type. For example, if you want to add a new locale such as en-xx, copy and paste the XML code that defines time formats for the en-CA (English Canadian) locale:
... <formatList name="qstimes" xml:lang="en-ca"> <timeFormat timeStyle="short">1:30 PM</timeFormat> <timeFormat timeStyle="medium">1:30:55 PM</timeFormat> <timeFormat timeStyle="long">1:30:55 EST PM</timeFormat> <timeFormat timeStyle="full">1:30:55 o&apos;clock PM EST</timeFormat> </formatList>...

2. Change the name of the locale. For example, for the new locale en-xx, change the first line of the copied code to:
<formatList name="qstimes" xml:lang="en-xx">

3. Change the data formats as required, following the instructions in one of the following sections: "Change the Order of Data Formats" (p. 521) "Change the Text Strings" (p. 522) "Remove Data Formats" (p. 523) "Add Data Formats for a New Locale" (p. 525)

4. Make similar changes for the other data format types for the new locale.

Change the Default Query Studio Template

All Query Studio reports use a default template. You can create a custom template, for example, to include your company logo in it, and set it up as the default template for Query Studio reports. The templates are created in Report Studio. For more information, see the Report Studio Professional Authoring User Guide.

Steps
1. Go to the c8_location/configuration directory. 2. Locate the file qrsvpproperties.xml.sample, and rename it to qrsvpproperties.xml. 3. Open the qrsvpproperties.xml file, and in the following code:
<structure> <!-- Default template for reports. --> <!--<property>defaultSystemTemplate</property> --> <!--<value>/content/configuration/reportTemplate[@name='QSdefault']

Administration and Security Guide 525

Chapter 32: Customizing the Functionality of IBM Cognos 8

</value> --> </structure>

Un-comment the property and value elements For the value, type the search path of the new template.

Tip: To find the template search path in IBM Cognos Connection, open the template properties page and, on the General tab, click the View the search path, ID and URL link. Following, is an example of the resulting code:
<structure> <!-- Default template for reports. --> <property>defaultSystemTemplate</property> <value>/content/package[@name='GO Sales and Retailers']/folder[@name="Templates "]/reportTemplate[@name='RS template'] </value> </structure>

4. Save the qrsvpproperties.xml file. 5. Restart the IBM Cognos 8 server.

Modify Properties for the CSV Output Format

You can modify properties for the comma separated values (CSV) output format. For example, you can specify encoding and field delimiter characters to suit your environment. The CSV properties are system-wide settings and cannot be specified for specific reports. Note: Always set the CSV output format at the server administration level. Do not override CSV output format settings at lower levels.

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. From the System drop-down menu, click Set properties. 5. Click the Settings tab. 6. Next to Environment, Advanced Settings, click Edit. 7. Enter parameters and values from "CSV Properties and Values" (p. 527), as required. 8. Click OK. After the 30 seconds required for your changes to take effect, your changes are reflected when reports are generated in CSV format.

526

Chapter 32: Customizing the Functionality of IBM Cognos 8

CSV Properties and Values

The following table describes the CSV properties that you can modify. If a property is not specified or its value is empty, the default setting is used.

Parameter
RSVP.CSV.ENCODING

Description
The encoding used for CSV output. Enter a supported encoding value (p. 528). LOCALE Encoding is derived from the content locale. The default value is utf-16le.

RSVP.CSV.DELIMITER

The field delimiter character used for CSV output. Enter one of the following: a single character. If you enter more than one character, only the first character is used. TAB (tab) LOCALE Delimiter is derived from the content locale. This is the default vale.

RSVP.CSV.QUALIFIER

The string qualifier used for CSV output. Enter a single character. If you enter more than one character, only the first character is used. The default value is " (quotation mark). If the qualifier appears as part of your data, it is duplicated. For example, if the qualifier is a quotation mark and your data is ab"cd, the CSV output is "ab""cd".

RSVP.CSV.TERMINATOR The line terminator used for CSV output. Enter one of the following a single characters: CR (carriage return) LF (line feed). This is the default value. CRLF (carriage return/line feed) LFCR (line feed/carriage return)

If you enter more than one character, only the first character is used. RSVP.CSV.MIMETYPE The MIME type attributed to the CSV output. The default value is: application/ vnd.ms-excel/

Administration and Security Guide 527

Chapter 32: Customizing the Functionality of IBM Cognos 8

Supported Encoding Values

The following table shows encoding values that are supported and tested by IBM Cognos.

Character set
UTF-8 Western European (ISO 8859-1) Western European (ISO 8859-15) Western European (Windows-1252) Central and Eastern European(ISO 8859-2) Central and Eastern European (Windows-1250) Cyrillic (ISO 8859-5) Cyrillic (Windows-1251) Turkish (ISO 8859-9) Turkish (Windows-1254) Greek (ISO 8859-7) Greek (Windows-1253) Japanese (EUC-JP) Japanese (ISO-2022-JP) Japanese (Shift-JIS) Traditional Chinese (Big5) Simplified Chinese (GB-2312) Korean (EUC-KR) Korean (ISO 2022-KR) Korean (KSC-5601) Thai (Windows-874)

Supported encoding value

utf-8 iso-8859-1 iso-8859-15 windows-1252 iso-8859-2 windows-1250 iso-8859-5 windows-1251 iso-8859-9 windows-1254 iso-8859-7 windows-1253 euc-jp iso-2202-jp shift_jis big5 gb2312 euc-kr ISO 2022-KR ksc_5601 windows-874

528

Chapter 32: Customizing the Functionality of IBM Cognos 8

Character set
Thai (TIS-620)

Supported encoding value

tis-620

Modify Properties for the Batch Report Service and Report Service
You can modify advanced properties for the Batch Report service and the Report service. For example, you can specify that prompt values entered by a user be saved automatically.

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. From the All Servers drop-down menu, click Services, Batch Report. 5. From the drop-down menu for BatchReportService, click Set properties. 6. Click the Settings tab. 7. For the Environment category, next to Advanced settings, click the Edit link. 8. If it appears, select the Override the settings acquired from the parent entry check box. Otherwise, proceed to the next step. 9. Enter parameters and values from "Batch Report Service and Report Service Properties and Values" (p. 529), as required. 10. Click OK.

Batch Report Service and Report Service Properties and Values

The following table describes the Batch Report service and Report service properties that you can modify. If a property is not specified or its value is empty, the default setting is used.

Parameter
RSVP.PARAMETERS.SAVE

Description
Specifies that report prompt values entered by a user should be saved automatically. Default: false

Administration and Security Guide 529

Chapter 32: Customizing the Functionality of IBM Cognos 8

Parameter
RSVP.CHARTS.ALTERNATECOLOURS

Description
Specifies that each chart instance assigns colors in palette order, and does not attempt to preserve the color of items from one chart instance to another. Default: false

RSVP.FILE.EXTENSION.XLS

Specifies to use XLS as the file extension on XLS output format email attachments instead of HTML. Default: false

Customize Error-Handling on the SMTP Mail Server

The way in which an SMTP mail server handles errors can differ depending on your mail server implementation. For this reason, you can customize the actions that the delivery service should take when it encounters specific errors by setting up SMTP rules in an XML file. A set of default rules for error-handling is stored in a sample file provided with IBM Cognos 8. To customize the rules, you should create a copy of this file and amend it. You then configure the delivery service to use this file.

SMTP Rules
Use the <smtpRule> tag to define an SMTP rule and the <smtpError> tag to define the error code for which you are applying a rule. For example:
<smtpRule> <smtpError> <errorCode>502</errorCode> </smtpError> ... <smtpError> <errorCode>550</errorCode> </smtpError> ... </smtpRule>

Note: The priority of rules is determined by the order in which they appear in the XML file. You can define the following types of SMTP errors: transport errors For example, there is no connection to the mail server, the mail server does not exist or is not configured correctly, or the user has no access to the mail server. Use <transport>true</transport> to include this type of error in your rules. recipient errors

530

Chapter 32: Customizing the Functionality of IBM Cognos 8 For example, there are invalid recipients, too many recipients, or no recipients. Use <invalidRecipients>true</invalidRecipients> to include this type of error in your rules. other specified errors Any standard SMTP error code generated by the mail server. Use <errorCode>nnn</errorCode> to include this type of error in your rules. The following actions can be performed for each error type, and are defined as behaviors in the XML file: resend behavior Specifies how many times to resend an email (n) and the resend interval in seconds (x). Use <resends number="n" delaySeconds="x" /> to apply this behavior. Note: To resend an email indefinitely, use <resends number="-1">. keep mail behavior Specifies whether the delivery service should keep the failed email in a separate queue after it has been resent the required number of times and is unsuccessful. The queue is named SMTPBackupQueue. Note: No further action is performed on emails in the backup queue. To add emails from SMTPBackupQueue to the regular SMTPQueue, you must change the queue name in the database table and restart the server. Use <keepMail>true</keepMail> to apply this behavior. fail mail behavior Allows you to customize the email notification that is sent when an email delivery has failed. Use the <failMail> tag to apply this behavior. There are two further optional attributes you can use to specify the email notification subject (<subject>) and recipient (<recipients>). Tip: If you omit these tags, the email notification is sent by default to original recipients list with the subject "Send failed:". To remove all current recipients, use <recipients sendToCurrentRecipients="false">. To send an email notification to the agent owner, use <owner>true</owner> and, if required, use <recipient address="[email protected]"> to specify an email address. default behavior Defines the action to perform when no matching rule is found. Use the <defaultSmtpBehaviour> tag to apply this behavior.

Administration and Security Guide 531

Chapter 32: Customizing the Functionality of IBM Cognos 8

Examples
The first example shows how to set up a rule for the default behavior. Here, the delivery service attempts to resend the undelivered email three times at hourly intervals. If it is unsuccessful, it sends an email notification using the default fail mail behavior.
<defaultSmtpBehaviour> <smtpBehaviour name="default"> <keepMail>false</keepMail> <resends number="3" delaySeconds="3600" /> <failMail /> </smtpBehaviour> </defaultSmtpBehaviour>

The second example shows how to set up a rule for a transport error. Here, the delivery service resends the email indefinitely, at 30 second intervals, until it is successful.
<smtpRule> <smtpError> <transport>true</transport> </smtpError> <smtpBehaviour name="transport"> <keepMail>false</keepMail> <resends number="-1" delaySeconds="30" /> </smtpBehaviour> </smtpRule>

The third example shows how to set up a rule for a recipient error. Here, the email notification is sent to the agent owner using the email address stored in their user ID. The original email recipients are removed from the recipient list.
<smtpRule> <smtpError> <invalidRecipients>true</invalidRecipients> </smtpError> <smtpBehaviour name="invalidRecips"> <keepMail>false</keepMail> <failMail> <recipients sendToCurrentRecipients="false"> <owner>true</owner> </recipients> </failMail> </smtpBehaviour> </smtpRule>

The fourth example shows how to set up a rule for a specified error code. Here, the undelivered email is sent to the backup queue whenever error 550 occurs. It remains there until you process it manually. A customized email subject is set up for the fail mail notification.
<smtpRule> <smtpError> <errorCode>550</errorCode> </smtpError> <smtpBehaviour name="specialErrorCode-550"> <keepMail>true</keepMail> <failMail> <subject>Error code 550 keep mail</subject> </failMail>

532

Chapter 32: Customizing the Functionality of IBM Cognos 8

</smtpBehaviour> </smtpRule>

Steps
1. Copy the c8_location\configuration\smtpRules-sample.xml file to the c8_location\webapps\ p2pd\WEB-INF\classes folder. Note: To use your own file rather than a copy of the sample file, copy it to the same folder. 2. If you are using the sample file, rename the copied file to smtpRules-custom.xml. 3. Open the required file in an XML or text editor. 4. Amend the file to customize the rules. 5. Start IBM Cognos Connection. 6. In the upper-right corner, click Launch, IBM Cognos Administration. 7. On the Status tab, click System. 8. From the All Servers drop-down menu, click Services, Delivery. 9. From the drop-down menu next to DeliveryService, click Set properties. 10. Click the Settings tab. 11. Next to Environment, click Edit. 12. In the Parameter column, type the parameter name smtp.rules.properties.location. 13. In the Value column, type the name of the customized xml file you are using. 14. In the Parameter column, type the parameter name smtp.rules.properties.reread. Although not mandatory, it is useful to set this parameter for testing purposes so that the SMTP rules are read for every request. 15. In the Value column, type true. 16. Click OK. 17. In the Set properties page, click OK. When you have finished testing the rules, you must reset the smtp.rules.properties.reread parameter. 18. Repeat steps 5 to 11 to access the advanced settings. 19. In the Value column for the smtp.rules.properties.reread parameter, type false. 20. Click OK.

Administration and Security Guide 533

Chapter 32: Customizing the Functionality of IBM Cognos 8

Disable Report Attachments in Email Messages

To prevent users from sending reports as email attachments, modify the system file system.xml. This change hides the Include the report check box under Attachments in the Set the email options dialog box. This restriction applies to all IBM Cognos 8 users.

Steps
1. Stop the IBM Cognos 8 service. 2. Open the c8_location/templates/ps/portal/system.xml file in an XML or text editor. For pages and dashboards, open the c8_location/templates/ps/system.xml file. 3. Add the following XML code to the <system> element:
<param name="ui_hide"> <CC_RUN_OPTIONS_email_attachment/> </param>

If you hide other user interface elements by modifying the system.xml file (p. 505), the <param
name="ui_hide"> element already exists. In this case, add the following to the element: <CC_RUN_OPTIONS_email_attachment/>

4. Save the file. 5. Start the IBM Cognos 8 service.

Show Attachments in IBM Lotus Notes

When chart reports are sent as email attachments, they may not be shown properly in Lotus Notes. You can specify that .png file types be automatically converted to .jpg to avoid this possibility.

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. From the All Servers drop-down menu, click Services, Delivery. 5. For the drop-down menu next to DeliveryService, click Set properties. 6. Click the Settings tab. 7. Next to Environment, click Edit. 8. Select the Override the settings acquired from the parent entry check box. 9. In the Parameter column, type the parameter name lotus.compatibility.mode. 10. In the Value column, type true.

534

Chapter 32: Customizing the Functionality of IBM Cognos 8 11. Click OK. 12. In the Set properties page, click OK. Chart reports are converted to .jpg files and appear properly in Lotus Notes.

Disable Support for Trigger-based Scheduling

By default, trigger-based scheduling (p. 305) is enabled. An occurrence acts as a trigger, causing the report to run. You can disable this feature by modifying the system.xml file.

Steps
1. Stop the IBM Cognos 8 service. 2. Open the c8_location/templates/ps/portal/system.xml file in an XML or text editor. 3. Locate the following XML code in the system element:
<param name="enable-trigger-support"> true </param> <param name="enable-trigger-tab"> true </param>

4. Change the value of both trigger parameters from true to false. The XML code should appear as follows:
<param name="enable-trigger-support"> false </param> <param name="enable-trigger-tab"> false </param>

5. Save the file. 6. Start the IBM Cognos 8 service. The By Trigger tab on the Schedule page no longer appears. Entries that are already scheduled for trigger-based scheduling continue to run, but no further trigger scheduling can occur while support is disabled.

Set Up a Trigger Occurrence on a Server

As part of setting up trigger-based report scheduling (p. 305), you must set up the trigger occurrence on a server. You link the external occurrence, such as a database refresh or an email, with a trigger on the server that causes the entry to run. You must also specify the name of the occurrence. Trigger occurrences can also be set up by an SDK developer using the IBM Cognos 8 software development kit (SDK). For more information, see the The IBM Cognos 8 SDK Developer Guide.

Administration and Security Guide 535

Chapter 32: Customizing the Functionality of IBM Cognos 8

Scripts
Using the Windows script named trigger.bat or the shell script named trigger.sh, you can trigger one or more schedules to run on the server. The script syntax follows where URL is the IBM Cognos 8 server URL, username is a valid username in the specified namespace, password is the password for the username, namespace is the namespace for the username, and triggerlist is a comma separated list of trigger names:
trigger.bat URL [username password namespace] triggerlist

For example, if users want to schedule a report based on a database refresh and want to schedule a second report based on receipt of an email, your custom trigger command line may look similar to this:
trigger.bat http://localhost:9300/p2pd/servlet/dispatch username password namespace databaserefreshtriggername,emailtriggername

Steps
1. If you are setting up a trigger occurrence on a server other than an IBM Cognos 8 server, complete the following tasks: Ensure that the server has a supported version of either a Java Runtime Environment or a Java Development Kit. Copy the following files from c8_location/webapps/p2pd/WEB-INF/lib on an IBM Cognos 8 server to the location on the server where you are setting up the trigger occurrence: activation.jar axis.jar axisCrnpClient.jar commons-discovery.jar commons-logging.jar jaxrpc.jar saaj.jar mail.jar xml-apis.jar xercesImpl.jar Copy the following files from c8_location/webapps/EventTrigger on an IBM Cognos 8 server, to the location on the server where you are setting up the trigger occurrence: trigger.bat trigger.sh trigger.class (a Java utility that can run on any IBM Cognos-supported platform) 2. Ensure that the command line runs when the external occurrence, such as a database refresh or email, occurs.

536

Chapter 32: Customizing the Functionality of IBM Cognos 8 The mechanism that you use to invoke your custom trigger command depends on the application that you are working with, such as a database system or an email application. For information, see the documentation for your application. 3. Inform users that they can now schedule entries based on the trigger occurrence. If a user scheduled an entry based on the occurrence, when the user clicks the schedule button for a report view, occurrence information replaces frequency information on the Schedule page. If a user scheduled an entry based on the occurrence, when the user clicks the schedule button for a report view, occurrence information replaces frequency information on the Schedule page. After the script runs, the trigger method returns an integer value representing the number of schedules that were run. The following integers represent errors: -1 is a usage error, such as invalid parameter or syntax -2 is a communication problem with IBM Cognos 8 server

Hide History Summary Counts

By default, the Schedule Management Activity tab shows the counts of the various run histories for your reports and jobs. Tip: To view history summary counts, in IBM Cognos Connection, click the Schedule Management link. In the Activity tab, summary counts appear at the right. You can disable history summary counts this feature by modifying the system system.xml file.

Steps
1. Stop the IBM Cognos 8 service. 2. Open the system.xml file in a text editor. The file is located in c8_location/templates/ps/portal. 3. Locate the following XML code within the system element:
<param name="enable-history-counts"> true </param>

4. Change the value of the enable-history-counts parameter from true to false. The XML code should appear as follows:
<param name="enable-history-counts"> false </param>

5. Save the file. 6. Start the IBM Cognos 8 service.

Administration and Security Guide 537

Chapter 32: Customizing the Functionality of IBM Cognos 8

Change the Suppression Functionality in Analysis Studio

IBM Cognos 8.0 uses totals-based suppression to remove rows or columns throughout the analysis where the total result is a null or zero value. This approach has several limitations. For more information, see the Analysis Studio User Guide. In IBM Cognos 8.2, the default suppression functionality uses selection-based suppression. You can select a single row or column to remove rows or columns in the opposite axis of the crosstab that contain only empty cells. However, you can change back to the original IBM Cognos 8.0 functionality of totals-based suppression.

Steps
1. Go to the c8_location/configuration directory. 2. Locate the file named ansproperties.xml.sample, and rename it to ansproperties.xml. 3. Open the ansproperties.xml file, and locate the following code:
<structure> <!-- Enabling the 8.0 Zero Suppression feature will provide compatibility for existing 8.0 customers --> <!-- Enabling the 8.0 feature will disable the new capabilities provided in 8.2 and beyond --> <!-- The default is disabled. 0 == disabled (recommended). 1 == enabled. --> <!--<property>Enable8Dot0Suppression</property> <value type="long">0</value>--> </structure>

4. Remove the comment tags (<!--) and (-->) from the Enable8Dot0Suppression property. 5. Change the value from 0 to 1. 6. Save the ansproperties.xml file. 7. Restart the IBM Cognos 8 server.

538

Chapter 33: Troubleshooting Resources

Troubleshooting resources are sources of information that can help you resolve a problem that you are having with a product. Generally, sources of troubleshooting information include logs, debugging modes, documentation, and technical support. In addition to this document, the following troubleshooting resources are available when you work with IBM Cognos 8: error messages log files core dump files metric dump file Windows Event Viewer samples Report Definition in Query Studio IBM Cognos Resource Center IBM Cognos diagnostic tools

By learning what troubleshooting resources are available, you are better able to resolve problems while using IBM Cognos 8.

Error Messages
The first indication of a problem is often an error message. Error messages contain information that can be helpful in determining the cause of a problem. You can click the Details link to see the full error message. The administrator can use this information, as well as other information about what product you are using and what you did before the error message appeared, to resolve an issue. If you click OK in response to the error message, IBM Cognos 8 undoes the last action and returns to the previous state.

Log Files
Log files can help you troubleshoot problems by recording the activities that take place when you work with a product. Operations performed in IBM Cognos 8 are recorded in various log files for tracking purposes. For example, if you experienced problems installing IBM Cognos 8, consult the transfer log file to learn what activities the installation wizard performed while transferring files.

Administration and Security Guide 539

Chapter 33: Troubleshooting Resources Before you begin viewing log files, ensure that they contain the information that you need. The number of log files and the information they contain are set by parameters in IBM Cognos Connection and in IBM Cognos Configuration. Use IBM Cognos Administration to learn about logging categories and how to set the level of detail to log for each category. For more information, see the IBM Cognos 8 Administration and Security Guide. Use IBM Cognos Configuration to specify the size, number, and location of log files, and to configure the properties of the log server. For more information, see the IBM Cognos Configuration User Guide. When troubleshooting, the following files can assist you:

The Transfer Log File

This file records the activities that the installation wizard performed while transferring files. The transfer log file is located in the c8_location\instlog directory. The file name identifies the product name, version, and build number, and includes a time stamp. The following is an example of the file name format: tl-C8BISRVR-8.1-0.0-20080901_1122.txt

The Transfer Summary-Error Log File

This file records the components you installed, disk space information, the selections you made in the transfer dialogs, and any errors the installation wizard encountered while transferring components. The transfer summary-error log file is located in the c8_location/instlog directory. The file name identifies the product name, version, and build number, and includes a time stamp. The following is an example of the file name format: tl-C8BISRVR-8.1-0.0-20080901_1122_summary_error.txt

The Startup Configuration File

This file records your configuration choices each time you save your property settings. The file name is cogstartup.xml. If you are unable to save your configuration, or are having problems you can revert to a previously saved configuration file. The backup configuration files are located in the c8_location/configuration directory. The following is an example of the file name format for backup configuration files: cogstartup_200811231540.xml

The Startup Configuration Lock File

This file is created each time you open IBM Cognos Configuration. It prevents you from opening more than one IBM Cognos Configuration window. If you experience problems opening IBM Cognos Configuration, you can check the c8_location/configuration directory for the cogstartup.lock file. If the file exists and IBM Cognos Configuration is not open, it means that IBM Cognos Configuration did not shut down properly the last time you used it. You can delete the lock file and then open IBM Cognos Configuration.

540

Chapter 33: Troubleshooting Resources

The Locale Configuration File

This file records the configuration choices you make in IBM Cognos Configuration for product and content locales, locale mapping, and currency support. If you experience problems with language support in the user interface or in reports, use these files to track your changes. The backup configuration files are located in the c8_location/configuration directory. The following is an example of the file name format: coglocale_200811231540.xml

The Run-Time Log File

The default IBM Cognos log file named cogserver.log file, or other log files that you configure to receive log messages from the log server, record information after you start the IBM Cognos 8 service. They are located in the c8_location/logs directory. If you configured another destination for log messages, check the appropriate file or database. Some log messages indicate problems. Most messages provide information only, but others can help you to diagnose problems in your run-time environment.

The Gateway Log File

The gateways record errors in the gateway log file, which is located in the c8_location/logs directory. You can use the gateway log file to troubleshoot problems that prevent the gateway from processing requests or from using encryption. Symptoms of these problems are user IDs and passwords do not work, single signon does not work, and the dispatcher is running but users receive the following error message: The IBM Cognos BI server is not available. The gateway log file uses the following naming format, where gateway_interface is cgi, mod (Apache 1.3 module), mod2 (Apache 2.0 module), or isapi. gwgateway_interface.log (for example, gwcgi.log)

The Uninstallation Log File

This file records the activities that the Uninstall wizard performed while uninstalling files. The log file is named cognos_uninst_log.htm and is located in the Temp directory. You can use the log file to troubleshoot problems related to uninstalling IBM Cognos 8 components.

The Silent Mode Log File

This file records the activities that IBM Cognos Configuration performed while running in silent mode. This log file is named cogconfig_response.csv and is located in the c8_location/logs directory.

The ReportNet to IBM Cognos 8 Upgrade File

This file contains a summary of the results of an upgrade from ReportNet to IBM Cognos 8. The log file is named upgradeLog.xml and is located in the c8_location/logs directory. The file is in xml format and references an xslt style sheet. You can double-click the file to have it appear in your browser.

Administration and Security Guide 541

Chapter 33: Troubleshooting Resources

Core Dump Files

If you receive an error message about the report server not responding, IBM Cognos 8 wrote a core dump (.dmp) file to the file system. Core dump files indicate a serious problem with the program, such as an unhandled exception or an IBM Cognos 8 process that terminated abnormally. Core dump files create a complete memory dump of the current state of the program when the problem occurs. The core file usually indicates a bug that requires a software fix. If you see the report server not responding message, immediately check the \bin directory of the IBM Cognos 8 server installation for any core dump files. In Windows, these files are named processID.dmp, such as BIBusTKServerMain_seh_3524_3208.dmp. In UNIX, the files are named core. In Linux, the files are named core.processID.These binary files must be viewed with a debugging program such as dbx, GNU debugger, or the WinDbg debugger for Windows. If your server administrator cannot solve the problem, contact IBM Cognos Resource Center and provide them with a test case, if possible, and the core files. Core files can be 300 MB or more, and a new one of the same size is created each time that the problem occurs. In Windows, the files should be checked and cleaned regularly, during regular server maintenance. In UNIX and Linux, system settings can control how and when the core file is written to the file system when a process abnormally terminates. In Windows, you can use a configuration file to turn off the creation of .dmp files. In a production environment, you can then enable core dumps when you encounter problems. Because not all problems are easy to reproduce, core file creation should be enabled in your testing and development environment so that you can use them. With some IBM Cognos 8 hotsite builds, core dump files are automatically created. The configuration file that controls this setting is different for IBM Cognos 8.1 MR1 (p. 542) and later versions of the product (p. 542). During an upgrade, configuration settings are not overwritten.

Steps to Turn Off Core File Creation for IBM Cognos 8.1 MR1
1. On the server where IBM Cognos 8 is installed, open the rsvpproperties.xml file from the c8_location\configuration directory. 2. Change the Win32StructuredExceptionHandling property to 0 (zero) so that it reads
<property>Win32StructuredExceptionHandling</property> <value type="long">0</value>

3. Save the file.

Steps to Turn Off Core File Creation for IBM Cognos 8.1 MR2 and Later Versions
1. On the server where IBM Cognos 8 is installed, open the cclWin32SEHConfig.xml file from the c8_location\configuration directory. 2. In the configuration element, change the value of the environment variable setting to 0 (zero) so that it reads
<env_var name="CCL_HWE_ABORT" value="0"/>

3. Save the file.

542

Chapter 33: Troubleshooting Resources

Metric Dump File

You may have troubleshooting situations where further detail is required about the state of the system at a particular time. You may also want to track system trends over a given period for historical purposes. The metric dump file records a snapshot of the current system metrics. The file is named metricdump.xml and is located in the c8_location/logs directory. By default, metric dumping is disabled. You can enable the feature by adding an advanced setting in IBM Cognos Administration that specifies the location of the dispatcher. After the feature is enabled, you can keep it inactive by renaming the metric dump configuration file (which would hide the file) and then reactivate metric dumping for a particular event by renaming the configuration file back to the original name. For example, in Event Studio, you can monitor threshold violations and then trigger metric dumping using a simple file name change. You can also edit the configuration file for metric dumping and change settings for resources to be tracked and the size and location of the output.

Steps to Enable Metric Dumping in IBM Cognos Administration

1. Open IBM Cognos Connection by connecting to the IBM Cognos 8 portal and clicking IBM Cognos Content on the Welcome page. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Configuration tab, click Dispatchers and Services. 4. Click the set properties button 5. Click the Settings tab. 6. For the Environment category, in the Name column, next to Advanced settings, in the Value column, click Edit. 7. In the Set advanced settings page, in the Parameter column, type the following advanced setting: DISP.MetricDumpEnabled Note that the setting name is case sensitive. 8. In the Value column, type the URL of the dispatcher, and click OK twice. Tip: You can also delete this setting. To do this, click the check box next to the setting, click Delete, and click OK twice. .

Steps to Change Settings for Metric Dumping

1. Open the file c8_location\configuration\metricdumpconfiguration.xml in an editor. 2. To configure the resources for which metrics are to be logged, specify the resource in the following section:
<mbeans> <mbean>com.cognos:type=Metrics,*</mbean> <mbean>com.cognos:type=MetricHealth,*</mbean>

Administration and Security Guide 543

Chapter 33: Troubleshooting Resources

<mbean>com.cognos:type=ServiceHealth,*</mbean> <mbean>com.cognos:type=ServiceOperationalStatus,*</mbean> </mbeans>

For example, to specify a service

<mbean>com.cognos:type=Metrics,service=contentManagerService</mbean>

3. To change the file name and path, edit the following line:
<filename>../logs/metricdump.xml</filename>

4. To change the time interval for dumping, in milliseconds, edit the following line:
<interval>15000</interval>

5. To change the maximum number of dumps, edit the following line:

<count>-1</count>

where -1 is unlimited 6. To change the maximum file size before rollover, edit the following line:
<filesize>10000000</filesize>

7. To change the number of metric dump files to keep, edit the following line:
<rollover>1</rollover>

8. Save the changes.

Windows Event Viewer

Windows Event Viewer provides information about program, security, and system events. For example, if an IBM Cognos 8 service fails to start, this fact is recorded in the event log. Windows Event Viewer does not record information that is specific to operations or tasks performed in IBM Cognos 8. Consult the IBM Cognos 8 log files for these problems. For information about how to use Windows Event Viewer, see the Windows help.

Samples
IBM Cognos 8 uses samples to highlight product features and to help you learn how to use the product. You can also use samples to troubleshoot problems. You can use the samples that come with IBM Cognos 8 to determine if various components are working together as expected. For example, if you are having a problem running a report, you can try running a sample report to see if problem persists. You may discover that the problem is related to connecting to a database. For information about setting up samples, see the IBM Cognos 8 Administration and Security Guide.

544

Chapter 33: Troubleshooting Resources

Example - Testing Report Studio

You are a database administrator responsible for troubleshooting problems that report authors encounter when designing reports. Report Studio is now installed, and you want to ensure that it is working properly before the author begins using it. To test Report Studio, you open and run one of the reports in the Report Samples folder in Report Studio. If the report opens successfully, it appears in Report Studio, and the GO Sales and Retailers model associated with the report is loaded. When you run the report, Cognos Viewer appears, and the report contains data.

View the Report Definition in Query Studio

You can use the Report Definition command on the Manage File menu or the Query Information command in the Report Definition box to troubleshoot problems with your reports. The Report Definition command shows the expression for each report item. The Query Information command shows the query information for each report item. Note: You cannot change the report properties using these commands.

Steps
1. In Query Studio, open the report that you want. 2. From the Manage File menu, click Report Definition. The Report Properties dialog box appears. It contains a table that lists every filter, report item, and corresponding expression in the report. Tip: Click Query Information to bring up a text box containing information about the query.

Call IBM Cognos Resource Center

If you are unable to resolve a problem using all other troubleshooting resources, call IBM Cognos Resource Center to receive immediate help. For information about locations and programs, see the IBM Cognos Resource Center Web site (http://www.ibm.com/software/data/support/cognos_crc. html). To contact IBM Cognos Resource Center, you must have a current support agreement. Before you call, do the following: Ensure that the problem is related to IBM Cognos software and results in an error message. Attempt to reproduce the problem to ensure that it is not just a simple error. Check obvious things like file locations, directories, paths, and access. Review all relevant documentation, including any release notes or readme files. Check to see if any recent changes in your computing environment may be responsible for the problem.

Administration and Security Guide 545

Chapter 33: Troubleshooting Resources Tip: You can also use the IBM Cognos diagnostic tools.

Steps
1. Have the following information at hand: your customer identification number your service request number, if it is an ongoing service request the phone number where you can be reached the version of the software you use the version of the operating environment you use a description of what you were doing when the problem occurred the exact wording of any error messages that appear any steps you took to attempt to solve the problem

2. Contact the IBM Cognos Resource Center center nearest you. You are asked whether this is a new or ongoing service request. If it is an ongoing service request, provide your service request number or, if appropriate, your customer identification number. If you dont have support on the software about which you are calling, you will be directed to a support renewal representative.

IBM Cognos Diagnostic Tools

IBM Cognos Resource Center provides diagnostic tools to help you: verify your environment identify and troubleshoot issues supply the details and systems information needed to log a case with IBM Cognos Resource Center

The diagnostic tools were developed in Java. Each contains a JAR file, a batch file, and a PDF that explains what the diagnostic tool does and the results you can expect. IBM Cognos diagnostic tools are read-only and do not make changes to your environment or to your IBM Cognos products. New diagnostic tools are continually being developed. To check for the most recent updates, as well as for more information about IBM Cognos diagnostic tools, see the IBM Cognos Resource Center Web site (http://www.ibm.com/software/data/support/cognos_crc.html).

546

Chapter 34: Problems Using Documentation

The topics in this section provide solutions for problems you may encounter when using the IBM Cognos 8 documentation.

Problems When Printing a PDF Manual

You print a document in PDF format, but the print job is incomplete. For example, the job stops printing when it reaches a particular graphic.This is an Adobe Acrobat Reader issue that can occur when printing some PDFs using some versions of Acrobat Reader and some printer models. The same PDF may print correctly under one or both of the following conditions: using a different version of Acrobat Reader using a different printer

If you print from an Acrobat 4.0 or later product, you can try the following solution.

Steps to Force a Page to Print as an Image

1. In Acrobat Reader, from the File menu, click Print. 2. In the Printer section, select the Print as image check box. Because files print more slowly using this option, make sure you specify only the nonprinting page. 3. In the Print Range section, click Pages from and Pages to, type only the page number of the nonprinting page, and then click OK. You can print the rest of the PDF by resending the job starting on the next page. 4. Clear the Print as image check box. 5. In the Print Range section, click Pages from and Pages to, type the page range for the remaining pages, and then click OK. Although you can use the Print as image option to print the file, this setting does not resolve the original printing problem. For more information, see the Adobe Web site.

Unable to Launch a Web Browser When Accessing Help

You are running IBM Cognos Connection on a Linux computer. You click Help and the following message appears: Unable to launch a web browser Attempting to execute netscape-remote openURL Ensure that the web browser is defined in the path

Administration and Security Guide 547

Chapter 34: Problems Using Documentation This error occurs if the Netscape browser is not installed on the computer or the browser path is not set correctly. The solution is to either install Netscape if it is not installed, or add a BrowserPath entry to the file cogconfig.prefs. The entry must specify the full path for the browser.

Text Does Not Appear Properly in Quick Tours

If your computer uses large fonts, you may not see all the text or text may not wrap properly in the IBM Cognos 8 quick tours. To fix this problem, do one of the following: Use small fonts for your computer. Use the smallest font setting in your Web browser.

548

Chapter 35: Installation and Configuration Problems

You may encounter problems during installation and configuration, or when setting up IBM Cognos 8 to run within an application server.

Problems Starting IBM Cognos 8

You may encounter problems when you try to start the IBM Cognos 8 service to open the Welcome page for the IBM Cognos 8 portal for the first time to start an application server, such as WebLogic or WebSphere

Symptoms

Solution

You do not see the splash screen for the IBM Check your Web server configuration. Cognos 8 portal when you start IBM Cognos 8. The service starts but no tables are created in the content store database. The service does not start. Check your content store configuration.

Ensure that you wait a few moments before submitting a request. Check the file permissions and directory names of the application server installation location.

The application server does not start.

Ensure that you use other software that is supported by IBM Cognos components. You can view an up-to-date list of environments, such as operating systems, patches, browsers, Web servers, directory servers, and database servers on the IBM Cognos Resource Center (http://www.ibm.com/ software/data/support/cognos_crc.html).

CFG-ERR-0106 Error When Starting the IBM Cognos 8 Service in IBM Cognos Configuration
When you start the IBM Cognos 8 service, you may receive the following error message: CFG-ERR-0106 Cognos Configuration received no response from the Cognos 8 service in the allotted time. Check that Cognos 8 service is available and properly configured. There are two possible causes for this problem: The IBM Cognos 8 service needs more time to start. Administration and Security Guide 549

Chapter 35: Installation and Configuration Problems A standby Content Manager computer may be configured incorrectly.

The IBM Cognos 8 Service Needs More Time

By default, IBM Cognos Configuration checks the progress of the start request every half second for three minutes. If IBM Cognos Configuration does not receive a response within this time, the error message appears. To avoid this error, you can change the amount of time that IBM Cognos Configuration waits to receive a response from the IBM Cognos 8 service. You do this by configuring the ServiceWaitInterval and ServiceMaxTries properties in the c8_location/configuration/cogconfig.prefs file. The ServiceWaitInterval property represents the time interval, in milliseconds, at which IBM Cognos Configuration checks the progress of the start request. By default, its value is 500, which is equivalent to half a second. The ServiceMaxTries property represents the number of times that IBM Cognos Configuration checks the progress of the start request. By default, its value is 360.

Content Manager Is Configured Incorrectly

If the error message appears on a standby Content Manager computer, the setting for storing the symmetric keys may be incorrect. To avoid this problem, configure the standby Content Manager computer to store the symmetric keys locally.

Steps to Change the Wait Time

1. Using IBM Cognos Configuration, stop the IBM Cognos 8 service. 2. Open the c8_location/configuration/cogconfig.prefs file in an editor. This file is created automatically the first time you open IBM Cognos Configuration. 3. Add the following code to the file: ServiceWaitInterval=number of milliseconds ServiceMaxTries=number of times Tip: Add the numeric values that correspond to your configuration needs. 4. Save the file. 5. Using IBM Cognos Configuration, start the IBM Cognos 8 service.

Steps to Store Symmetric Keys Locally

1. On the standby Content Manager computer, start IBM Cognos Configuration. 2. In the Explorer window, under Security, click Cryptography. 3. In the Properties window, under CSK settings, set Store symmetric key locally to True. 4. From the File menu, click Save. 5. From the Actions menu, click Start. 550

Chapter 35: Installation and Configuration Problems This action starts all installed services that are not running. If you want to start a particular service, select the service node in the Explorer window and then click Start from the Actions menu.

Cryptographic Error When Starting IBM Cognos 8

You received the following error when you tried to start the IBM Cognos 8 service after installing server or client components: [Cryptography] 1. [ ERROR ] java.lang.NoClassDefFoundError: javax/net/ServerSocketFactory: Your Java Runtime Environment (JRE) is missing the encryption and decryption routines that are required by IBM Cognos 8. You must copy the Java Archive (.jar) file that is provided to your JRE directory.

Step
Copy the bcprov-jdknn-nnn.jar file from the c8_location/bin/jre/version/lib/ext directory to the Java_location/jre/lib/ext directory.

Unable to Start the IBM Cognos 8 Service Because the Port is Used by Another Process
You may not be able to start the IBM Cognos 8 service or process if one of the default ports is used by another process. Tip: To view the current network TCP/IP network connections, use the netstat command. Use IBM Cognos Configuration to change the default port that IBM Cognos 8 uses. When you change the port used by the local dispatcher, you must change the value of the Dispatcher URI properties. Because the change affects all the URIs that are based on the local dispatcher, you must change the URIs of all local components. By default, local components contain localhost in the URI. For example, if you install all components on one computer and you want to change the dispatcher port, replace 9300 in all dispatcher and Content Manager URIs with the new port number.

Steps to Change the Default Port

1. Start IBM Cognos Configuration. 2. In the Explorer window, click the appropriate group or component: To access the port number in the dispatcher and Content Manager URIs, click Environment. To access the port number for the local log server, under Environment, click Logging. To access the shutdown port number, under Environment, click IBM Cognos 8 service, IBM Cognos 8.

Administration and Security Guide 551

Chapter 35: Installation and Configuration Problems To access the port number for the location of the applications.xml file used by Portal Services, under Environment, click Portal Services. 3. In the Properties window, click the Value box next to the property that you want to change. 4. Change the value from 9300 to the new value. Ensure that you change the ports in all URIs that contain localhost:9300. 5. From the File menu, click Save. 6. From the Action menu, click Start.

IBM Cognos 8 Service Does Not Start or Fails After Starting

You start the IBM Cognos 8 service but services either do not start correctly or are very slow to start. After services start, the system fails a short time afterwards. While services are starting, Java uses 100 percent of the CPU time. You may also receive multiple occurrences of error messages such as the following: DPR-DPR-1035 Dispatcher detected an error. CAM-CRP-1157 Unable to synchronize the local common symmetric key store with Content Manager.

If you use a DB2 database for the content store, ensure that the database version and Java version are compatible. For DB2 version 8.2, Java 1.5 is not supported. For DB2 version 9, Java 1.5 is supported on all operating systems except HPUX and Solaris. To review an up-to-date list of environments supported by IBM Cognos products, such as operating systems, patches, browsers, Web servers, directory servers, database servers, and application servers, visit the IBM Cognos Resource Center (http://www.ibm.com/software/data/support/cognos_crc. html).

IBM Cognos 8 Server Fails to Start and Gives No Error Message

A IBM Cognos 8 server may fail to start after an upgrade or new installation, but no error message appears. This may occur when a previously running or new IBM Cognos 8 server is configured to use a large amount of memory. If the server on which IBM Cognos 8 is installed contains version 1.0 of Microsoft security update 921883, there may be an issue when a lot of contiguous memory is requested by an application. This is a known issue with version 1.0 of Microsoft security patch 921883. Microsoft distributed a second version of the patch to fix the problem. As a workaround, uninstall the first security patch, or install version 2.0 of the patch. Alternatively, you can configure the IBM Cognos 8 server to use less memory. For more information, see the Microsoft knowledge base article about programs using a lot of contiguous memory failing, at http://support.microsoft.com.

552

Chapter 35: Installation and Configuration Problems

IBM Cognos BI Server Not Available When Starting IBM Cognos 8

After you configure IBM Cognos components and start the IBM Cognos 8 services, when you connect to the IBM Cognos 8 portal, the following error message may appear: The Cognos Gateway is unable to connect to the Cognos BI server. The server may be unavailable, or the gateway may not be correctly configured. Check the IBM Cognos server log file for more information. By default, the cogserver.log file is located in the c8_location/logs directory. If you configured another destination for log messages, check the appropriate file or database. Content Manager may not be able to connect to the content store if the content store is not configured properly. This may occur if the content store uses an unsupported character encoding the content store uses a database collation sequence that is case sensitive the configuration settings you specified in IBM Cognos Configuration are not valid

Unsupported Character Encoding

If the following messages appear in the log file, the database you created for the content store does not use a supported character encoding: For Oracle: CM-CFG-5063 A Content Manager configuration error was detected while connecting to the content store. CM-SYS-5121 Content Manager cannot start because the database character set for the content store is not supported. CM-SYS-5126 The content store database server uses the character set US7ASCII. CM-SYS-5125 The content store database client uses the character set US7ASCII. For DB2 UDB: CM-CFG-5063 A Content Manager configuration error was detected while connecting to the content store. CM-SYS-5121 Content Manager cannot start because the database character set for the content store is not supported. CM-SYS-5124 The content store database server uses the code page 1252. For Sybase: CM-CFG-5063 A Content Manager configuration error was detected while connecting to the content store. CM-SYS-5121 Content Manager cannot start because the database character set for the content store is not supported. For Content Manager to connect to the content store, the content store must use the appropriate character encoding.

Administration and Security Guide 553

Chapter 35: Installation and Configuration Problems

Database
Oracle 9i

Character encoding
AL32UTF8 AL32UTF16

DB2 UDB Sybase ASE Microsoft SQL Server

Codeset UTF-8 UTF-8 UTF8 UTF16

To resolve this problem, you must recreate the content store database using the correct character encoding, or convert the character encoding. For more information, see the database documentation.

Case Sensitive Collation Sequence

If the following messages appear in the log file, the database you created for the content store uses a database collation sequence that is case sensitive: CM-CFG-5063 A Content Manager configuration error was detected while connecting to the content store. CM-SYS-5122 The content store database has a default collation that is case-sensitive. Content Manager requires a content store that has a case-insensitive collation. CM-SYS-5123 The content store database server uses the collation <parameter>. CM-SYS-5007 Content Manager build @cm_build_version@ failed to start! Review the Content Manager log files and then contact your system administrator or customer support. To resolve this problem, you must recreate the content store database using a database collation sequence that is not case sensitive. For more information, see the database documentation.

Invalid Configuration Settings

If the following or similar messages appear in the log file, you did not configure the content store correctly in IBM Cognos Configuration. For Microsoft SQL Server: CM-CFG-5063 A Content Manager configuration error was detected while connecting to the content store. CM-CFG-5036 Content Manager failed to connect to the content store. The connection string is "jdbc:JSQLConnect://localhost:1433/cm". Failed Logon:com.jnetdirect.jsql.x: Cannot open database requested in login 'cm'. Login fails. url:jdbc:JSQLConnect://localhost:1433/cm. For DB2: CM-CFG-5063 A Content Manager configuration error was detected while connecting to the content store. 554

Chapter 35: Installation and Configuration Problems CM-SYS-5003 Content Manager is unable to access the content store. Verify your database connection parameters and then contact your database administrator. [IBM][CLI Driver] SQL1013N The database alias name or database name "CM123" could not be found. For Oracle: CM-CFG-5063 A Content Manager configuration error was detected while connecting to the content store. CM-CFG-5036 Content Manager failed to connect to the content store. The connection string is "jdbc:oracle:thin:@localhost:1521:pb1". ORA-01017: invalid username/password; logon denied. For Sybase: CM-CFG-5063 A Content Manager configuration error was detected while connecting to the content store. CM-CFG-5036 Content Manager failed to connect to the content store. The connection string is "jdbc:sybase:Tds:localhost:5000/cm". JZ006: Caught IOException: java.net.ConnectException: Connection refused: connect. If you are using an Oracle database, do not use illegal characters such as an underscore in IBM Cognos Configuration for the Service Name property. If the Service Name includes illegal characters, tables are not created in the content store database when the IBM Cognos 8 service is started.

Steps for Microsoft SQL Server, Oracle, DB2, and Sybase

1. On the computer where you installed Content Manager, start IBM Cognos Configuration. 2. In the Explorer window, under Data Access, Content Manager, right-click Content Store and click Delete. This deletes the default resource. Content Manager must be configured to access only one content store. 3. Right-click Content Manager, and then click New resource, Database. 4. In the Name box, type a name for the resource. 5. In the Type box, select the type of database and click OK. If you are upgrading and want to use an existing content store, ensure that you select the type of database you use for the older version of ReportNet or IBM Cognos 8. If you installed more than one version of IBM Cognos 8, you must use a different content store for each version. When a content store is used by a new version of IBM Cognos 8, it cannot be used by an older version of ReportNet or IBM Cognos 8. Tip: If you want to use Oracle Net8 keyword-value pair to manage the database connection, select Oracle database (Advanced). 6. In the Properties window, provide values depending on your database type:

Administration and Security Guide 555

Chapter 35: Installation and Configuration Problems If you use a Microsoft SQL Server database, type the appropriate values for the Database server with port number or instance name and Database name properties. For a Microsoft SQL Server database, you can choose to use a port number, such as 1433, or a named instance as the value for the Database server with port number or instance name property. To connect to a named instance, you must specify the instance name as a JDBC URL property or a data source property. For example, you can type localhost\instance1. If no instance name property is specified, a connection to the default instance is created. Note that the properties specified for the named instance, along with the user ID and password, and database name, are used to create a JDBC URL. Here is an example: jdbc:JSQLConnect://localhost\\instance1/user=sa/more properties as required If you use a DB2 database, for the Database name property, type the database alias. If you use an Oracle database, type the appropriate values for the Database server and port number and Service name properties. If you use an advanced Oracle database, for the Database specifier property, type the Oracle Net8 keyword-value pair for the connection. Here is an example: (description=(address=(host=myhost)(protocol=tcp)(port=1521)(connect_data=(sid=(orcl))))) If you use a Sybase database, type the appropriate values for the Database server and port number and Database name properties. 7. If you want to change the logon credentials, specify a user ID and password: Click the Value box next to the User ID and password property and then click the edit button when it appears. Type the appropriate values and click OK.

8. From the File menu, click Save. The logon credentials are immediately encrypted. 9. Test the connection between Content Manager and the content store. Tip: In the Explorer window, right-click the new database and click Test. Content Manager connects to the database, checks the database permissions, and creates and populates a table. The table is not deleted and is used each time that the test is repeated.

Cannot Log On to a Namespace When Using IBM Cognos Connection

You open IBM Cognos 8 through IBM Cognos Connection. However, when you attempt to create a data source and log on to a namespace, the following error messages appear: PRS-CSE-1255 Exception error encountered in data decryption.

556

Chapter 35: Installation and Configuration Problems CAM-CRP-1064 Unable to process the PKCS #7 data because of an internal error. Reason: java.lang.IndexOutOfBoundsException.

This issue may occur if you do not have the necessary permissions for the following directories: c8\configuration c8\configuration\csk c8\configuration\encryptkeypair c8\configuration\signkeypair

The solution is to enable the read and execute permissions on the directories listed above for anyone who must start the IBM Cognos 8 service.

IBM Cognos 8 Services Fail to Restart After a Network Outage

The IBM Cognos Bootstrap Service restarts IBM Cognos 8 services after a network outage for Tomcat installations where a network IP address is specified in the internal dispatcher URI. During the restart, the IBM Cognos 8 services may not initialize successfully, requiring a manual restart after the network is restored. To resolve the problem, configure the Internal dispatcher URI property in IBM Cognos Configuration to use localhost or the network host name.

No Warning That Installing a Later Version of IBM Cognos 8 Will Automatically Update the Earlier Version of the Content Store
You have a version of ReportNet or IBM Cognos 8 installed on your computer. You install a later version into a new location. You use the same database for the content store for both versions. After you configure the later version and start the IBM Cognos 8 service, the earlier version of ReportNet or IBM Cognos 8 no longer works because all content is automatically upgraded. If you want to use different versions of ReportNet and IBM Cognos 8 after you upgrade, ensure that before you install the later version, you back up the database you use for the content store restore the backup to a new location

Alternatively, you can choose to use the deployment tool to import the entire content store from an earlier version to the later version. All existing content in the content store database is replaced by the imported content. You receive a warning message about this.

Download of Resource Fails

You start Report Studio in Internet Explorer and the following error message appears: The download of the specified resource has failed. This problem may be caused by recent Microsoft XMLHTTP upgrades if you do not have a language preference set in Internet Explorer. To resolve the problem, specify a language preference in Internet Explorer. Administration and Security Guide 557

Chapter 35: Installation and Configuration Problems

DB2 Returns SQL1224N Error When Connecting from AIX

If your content store is a DB2 database and you receive an SQL1224N error on AIX, check the db2diag.log file for additional information about the error. If the error includes reason code 18, you may need to change the DB2 configuration to accept more connections. For more information, see the IBM DB2 support pages for the error SQL1224N.

Content Manager Error When Starting IBM Cognos 8

After starting IBM Cognos 8, no BIBUSTKSERVMA process is started. There are errors listed in the pogo******.log and cogserver.log files. Users receive errors in the browser when connecting to the IBM Cognos 8 portal. In the pogo******.log file, an error related to Content Manager appears. In the cogserver.log file, the following error appears: An attempt to register the dispatcher in Content Manager was unsuccessful. Will retry periodically. When connecting to http://computer name/cognos8, the following error messages appear in the browser: DPR-ERR-2058 The dispatcher cannot service the request at this time. The dispatcher is still initializing SoapSocketException: Connection Refused

IBM Cognos Configuration uses a user ID to bind to the LDAP database. If this user ID is moved to another group, IBM Cognos Configuration can no longer locate it. To correct the problem, move the user ID back to the original group.

DPR-ERR-2014 Error Appears in Log File on Content Manager Computer

If Content Manager is installed on a separate computer and the event management service on the Content Manager computer is disabled, the following error message may appear in the cogserver.log file:
DPR-ERR-2014 Unable to load balance the request because no nodes in the cluster are available, or no nodes are configured for the service: eventManagementService

To correct the problem, do the following: Start IBM Cognos Configuration on the Content Manager computer. In the Explorer pane, go to Environment, IBM Cognos 8 service. Set the Event management service enabled? property to False.

Non-ASCII Characters in Installation Directory Cause Run-time Errors

On all operating systems, if you use non-ASCII characters in the installation directory for IBM Cognos 8, it causes run-time errors. It also causes some product functions, such as report execution, to fail.

558

Chapter 35: Installation and Configuration Problems To resolve this issue, install IBM Cognos 8 in the default directory or use a directory name that contains only ASCII Latin-1 characters.

Cannot Open an MS Cube or PowerCube

You are unable to open an MS Cube or PowerCube, or you can open an MS Cube but only metadata is shown. For an MS Cube, you may receive the following error message: MO-ERR-0030 "Cannot connect to the datasource. Please set the service to run as a domain user with the correct privileges." To solve this problem, ensure that the user running the IBM Cognos 8 service has access rights to the cube. PowerCubes are accessed through mapped drives or UNC path names.

Steps for MS Cubes

1. Add the domain user account that starts the IBM Cognos 8 service to the Act as part of the operating system privilege: Under Administrative Tools, select Local Security Policy. Expand Security Settings, Local Policies and click User Rights Assignment. Right-click the Act as part of the operating system policy and select Properties. Click Add User or Group and add the user account that starts the IBM Cognos 8 service.

2. If you use the domain userID and password method of authentication, add the user account that starts the IBM Cognos 8 service to the domain that includes Content Manager, the Application Tier Components, IIS Web server, and the data source server (Microsoft SQL Server or Microsoft Analysis Server). 3. If you use an external namespace, such as Active Directory Server, for authentication, add the user account that starts the IBM Cognos 8 service to the domain that includes the authentication provider. This domain must also include Content Manager, the Application Tier Components, IIS Web server, and the data source server (Microsoft SQL Server or Microsoft Analysis Server). For more information about configuring external namespaces for authentication, see the topics about authentication providers in the Installation and Configuration Guide.

Step for PowerCubes

Ensure that the IBM Cognos user profile has sufficient operating system or domain access rights to open the PowerCube file. For information, see the Administration and Security Guide.

Administration and Security Guide 559

Chapter 35: Installation and Configuration Problems

Cannot Open an OLAP Data Source

You cannot open one of the following data sources: MSAS Essbase DB2

You can try opening the same cube with Excel. This will tell you whether the OLAP server is configured and running, and whether the appropriate client software is installed.

The Page Cannot Be Found When Starting IBM Cognos 8 in Windows 2003
After installing IBM Cognos 8 on Windows 2003, the following message may appear when you try to start IBM Cognos 8: The page cannot be found. The page you are looking for might have been removed, had its name changed, or is temporarily unavailable. HTTP Error 404 - File or Directory not found. This error is caused by a security feature in Windows 2003 Internet Information Services (IIS). This security feature does not allow unknown cgi file extensions. To resolve this problem, add a new file extension in IIS for the cognos.cgi file. For more information, see the IIS documentation.

The Page Is Not Shown When Opening a Portal After Installing IBM Cognos 8
After you install and configure IBM Cognos 8, you are unable to connect to the Cognos 8 portal. This may be because the Web server is not properly configured. For example, the virtual directories required for IBM Cognos 8 may not exist or they may point to the wrong physical folders. For information about configuring the Web server, see the Installation and Configuration Guide.

DPR-ERR-2058 Error Appears in Web Browser When Starting IBM Cognos 8

After you start the services in IBM Cognos Configuration and then try to open the portal, a message similar to one of the following may appear: DPR-ERR-2058 The dispatcher encountered an error while servicing a request. XTS handler must be initialized before being invoked. DPR-ERR-2058 The dispatcher cannot service the request at this time. The dispatcher is still initializing. Please try again or contact your administrator. These error messages usually occur when the dispatcher cannot communicate with Content Manager. To help you determine the specific cause, look in the cogserver.log file in the c8_location/logs directory. The most common causes are listed below, with solutions.

IBM Cognos Services are Not Done Initializing

After you start the services in IBM Cognos Configuration and the configuration tool shows that the services are running, wait a few minutes for all services to start before you open the portal.

560

Chapter 35: Installation and Configuration Problems

Content Manager is Not Available

In a distributed installation, ensure that Content Manager is installed, configured, and running. Ensure also that the other IBM Cognos computers are configured with the correct Content Manager URI.

The Content Store is Not Available or is Not Configured Properly

Ensure that the content store database was created and that you configured it correctly in IBM Cognos Configuration.

Tables are Not Created in the Content Store

Ensure that you are using a version of DB2, Microsoft SQL Server, Oracle, or Sybase that is supported by IBM Cognos components.

The Logon Credentials for the Content Store Are Incorrect

Check whether the information changed. For example, DB2 reads information from the NT user management. If the password for the NT account changed, you must also change the logon credentials for the content store in IBM Cognos Configuration. Check for special characters in the logon password. Occasionally, the JDBC driver does not accept characters that are reserved for xml, such as %, !, <, and >.

The User Does not Have Appropriate Permissions

Ensure that the user has the appropriate permissions.

Out of Memory on HP-UX

If you are using Tomcat, you can determine the issue is related to HP-UX server configuration. You may be exceeding the expected maximum number of simultaneously active threads per process. Steps to Check for an HP-UX Configuration Problem 1. In the /bin/startup.sh file, find ../tomcat4.1.27/bin/catalina.sh start "$@" 2. Change it to the following: ../tomcat4.1.27/bin/catalina.sh run "$@" The run command causes the Tomcat output to appear in the console window for IBM Cognos 8. 3. Stop and restart IBM Cognos 8 using the ./shutdown.sh and ./startup.sh commands. If the following error message appears in the console window for any of the application servers, the issue is an HP-UX configuration problem: OutofMemoryException error: Unable to create new native thread on HP-UX. The problem is that the default values for HP-UX 11.0 and 11i are set too low for most Java applications. Tip: You can check the number of threads in your process by using the -eprof option available in JDK 1.1.8 and by analyzing the Java.eprof file using HPjmeter by selecting the threads metric.

Administration and Security Guide 561

Chapter 35: Installation and Configuration Problems

Steps to Increase the maximum Number of Threads Per Process

1. Have your system administrator change the Kernel parameter as follows: max_thread_proc = 512 nkthread = 1024

2. Ensure that the ulimit settings are unlimited.

Content Manager Cannot Connect to the Content Store on Oracle

If you are using an Oracle database as a content store, the DPR-ERR-2058 error may be generated when logging onto the portal http://host_name/cognos8. All tables are created on the database. You may also receive the following error messages: CM-CFG-5036 Content Manager failed to connect to the content store. ORA-01017: invalid username/password; logon denied

Steps to Set the Oracle Database Server Name

1. In the Explorer window, click Data Access, Content Manager, Content Store. 2. Change the Oracle database server name to a fully qualified name such as host_name.companyname:1534 to match the name in the tnsnames.ora file.

EBA-090034 Error When Starting WebLogic 8

After configuring WebLogic 8 to use SSL, you used the command startManagedWebLogic.cmd to start the application server. The application server did not start and you received the following error message: EBA-0990034 Not listening for SSL The problem occurred because WebLogic 8 has a feature that is incompatible with the IBM Cognos 8 bcprov-jdk14.134.jar file. To resolve the problem, you must add a new version of the BouncyCastle bcprov .jar file to the WebLogic Java extension directory.

Steps
1. From the BouncyCastle Web site, http://www.bouncycastle.org/download/, download a compatible BouncyCastle bcprov .jar file, such as bcprov-jdk14-137.jar. 2. Copy the downloaded .jar file to the WebLogic Java extension directory, WebLogic_location\jdk142_nn\jre\lib\ext. 3. In the WebLogic_location\jdk142_nn\jre\lib\security directory, edit the java.security file and add the following line to the provider list:
security.provider.6=org.bouncycastle.jce.provider.BouncyCastleProvider

562

Chapter 35: Installation and Configuration Problems

Report Studio Does Not Start

You may not be able to start Report Studio if you are using pop-up blocking software on your computer. When you start Report Studio, it opens in a new browser window. In addition, a new browser window opens when you run a report and when an error is detected. To correct the problem, disable any pop-up blocking software when working in Report Studio.

DPR-ERR-2022 Error Appears in Web Browser When Starting IBM Cognos 8

After you start the services in IBM Cognos Configuration and then try to open the portal, a message similar to the following may appear: DPR-ERR-2022 No response generated. This may be due to an incorrect configuration, a damaged installation, or the dispatcher not having finished initializing.

Opening the Portal Too Soon

This problem can occur if you try to open the portal before IBM Cognos services are initialized. To avoid this problem, after you start the services in IBM Cognos Configuration and the configuration tool shows that the services are running, wait a few minutes for all services to start before you open the portal.

The system.xml File Contains Errors

The system.xml file may have been edited. Replace the system.xml file in the c8_location\templates\ps\portal directory with a copy from backup or use an XML editor to edit it.

Unable to Download the cognos.xts File

After installing IBM Cognos 8, you are prompted to download the cognos.xts file when connecting to the IBM Cognos 8 portal. The following error message may appear: You have chosen to download a file from this location. cognos.xts from servername This problem occurs when the permissions on the virtual directories are not set properly. You must provide the cgi-bin virtual directory in the Microsoft Internet Information Service (IIS) with execute permissions. To resolve this problem, recreate the virtual directories in IIS with the following permissions.

Alias
cognos8

Path
c8_location\Program Files\ Cognos\c8\webcontent c8_location\Program Files\ Cognos\c8\cgi-bin

Permissions
Read

cognos8\ cgi-bin

Read Execute

Administration and Security Guide 563

Chapter 35: Installation and Configuration Problems

Alias
cognos8\help

Path
c8_location\Program Files\ Cognos\c8\webcontent\ documentation

Permissions
Read

Application Server Startup Script Fails

You may have problems running the startup scripts for an application server to deploy the IBM Cognos application if IBM Cognos 8 components are installed in a directory with a name that includes spaces. To resolve this problem, rename the directory and do not include spaces in the new name. If this solution is not easily handled by the startup scripts, try adding quotation marks around the directory name that includes spaces or use the 8.3 DOS naming convention.

Issues with IBM WebSphere 6.0 on AIX 5.3

Testing has found difficulties with IBM WebSphere 6.0 on AIX 5.3. Upgrading to AIX 5.3 Technology Level 4, Service Pack 2 is recommended.

IBM Cognos 8 Running under WebLogic Application Server on AIX Fails

The IBM Cognos 8 server instance may go into a FAILED_NOT_RESTARTABLE state in the WebLogic Administration Console. Numerous core files and Java core files are written to the IBM Cognos 8 domain directory. IBM Cognos 8 terminates and is not accessible via the portal. This behavior occurs only when the IBM Cognos 8 Managed Node is started with the WebLogic Administration Console. Start the IBM Cognos 8 Managed Node using the WebLogic startup scripts instead.

Deploying IBM Cognos 8 to an Oracle Application Server or IBM WebSphere Application Server Fails
Deploying IBM Cognos 8 to an Oracle application server or an IBM WebSphere application server may fail with any of the following errors: Browser timeout in administration console Error Message: HTTP 500 Internal Error Error Message: Deployment failed: Base Exception: java.rmi.RemoteException (Oracle) Return to application file selection page (IBM WebSphere)

These errors can occur because the application file that you are trying to deploy is too large. To solve this problem, do the following: If you are using the Build Application Wizard, clear the Include static files from the Webcontent folder check box when you select the application to build.

564

Chapter 35: Installation and Configuration Problems This will reduce the size of the application file. If static content is required, you can manually copy it to the deployed application location after you have successfully deployed IBM Cognos 8 into the application server. If you are deploying the application file manually for an Oracle application server, type the following command: dcmctl deployapplication -f path_and_name_of_ear_file -a application_name -co OC4J_instance_name This command is not supported for Oracle Release 3. For more information about deploying IBM Cognos 8 to an application server, see the Installation and Configuration Guide.

Microsoft Excel 2000 Multipage Report Type Does Not Work

To ensure that report URLs cannot be changed when passed from a client browser to the Application Tier Components, IBM Cognos 8 applies signatures to the URLs it generates. However, Excel 2000 multipage (XLS) does not support signed URLs. To use the Excel 2000 multipage report type, you must disable digital signing of the URLs by doing the following:

Steps to Disable Signed URLs

1. Stop the dispatcher. 2. In the c8_location/configuration directory, rename the cafconfig.xml.sample file to cafconfig.xml. 3. Open the cafconfig.xml and find the following section:
<!--Should we reject unsigned requests for /gd/ urls. (e.g. multipage excel reports) Default: true--> <crn:parameter name="caf_signedReportUrls"> <crn:value xsi:type="xsd:boolean">true</crn:value> </crn:parameter>

4. Change ="xsd:boolean">true</crn:value> to ="xsd:boolean">false</crn:value>. 5. Restart your dispatcher. 6. Repeat the above steps for every dispatcher in your environment, or copy the cafconfig.xml to each c8_location/configuration directory and restart the dispatchers.

Unable to Deserialize Context Attribute Error When Deploying the p2pd.war File to WebLogic
When you deploy the p2pd.war file to WebLogic, you may see the following error: Error [context]Could not deserialize context attribute java.io.NotSerializableException: com.cognos.logserver.LogService This error does not affect the deployment of the p2pd.war file.

Administration and Security Guide 565

Chapter 35: Installation and Configuration Problems To avoid this problem, add at least one language preference in Internet Explorer.

Error Appears After Upgrading IBM Cognos 8 on a WebLogic Application Server

You are using WebLogic and upgrade IBM Cognos 8 from an earlier release. After you deploy the p2pd.war file for the new installation, a message similar to the following may appear: <BEA-101215> <Malformed Request "null". Request parsing failed, Code: -10> This can occur if you undeploy IBM Cognos 8 from WebLogic and some files from the earlier version are not removed from the system. To solve this problem, use the administrative tools for your application server to ensure that IBM Cognos 8 has been undeployed. For information about undeploying applications, see your application server documentation. If the directory to which IBM Cognos 8 was originally deployed is not removed during the undeploy process, delete the directory. Also, remove any IBM Cognos 8 .jar files that are cached in your application server environment. For example, in WebLogic 7.0, .jar files are sometimes left in %WL_ HOME%\user_projects\<domain-name>\<managed-server-name>\.wlnotdelete\c8_p2pd_p2pd\ jarfiles You can remove them by deleting the WEB-INF directory. In WebLogic 8.1.2, the cache location is %WL_HOME%\user_projects\domains\<domainname>\<managed-server-name>\.wlnotdelete\extract\c8_p2pd_p2pd\jarfiles After you remove all files from the previous installation, you can redeploy IBM Cognos 8.

Chinese, Japanese, or Korean Characters Are Different After Upgrade

If you use Chinese, Japanese, or Korean characters, you may notice differences in some characters after upgrading from ReportNet to IBM Cognos 8. Examples You run an existing report. When you compare the output to the same report in ReportNet, you see that some of the characters are different. You do a search that you did in ReportNet and get different results.

The differences occurred because the conversion tables that are used for Chinese, Japanese, and Korean were modified to meet global standards. If your report specifications or search filters contain expressions that use constant values, the results may be affected. If you want to use the same conversion table that you used in ReportNet, run the following script in the c8_location/bin directory: On UNIX, type conv_compat.sh On Linux, type conv_compat.sh On Windows, type

566

Chapter 35: Installation and Configuration Problems conv_compat.cdm

Accented or Double-Byte Characters May Not Display Correctly When Installing IBM Cognos 8 on Linux
If you are using issetup under a UTF-8 locale, accented or double-byte characters may not display correctly. To resolve this problem when installing in German or French, use a non-UTF-8 locale and then launch issetup to install IBM Cognos 8. To resolve this problem when installing in Japanese, change the encoding setting of X Terminal to Shift-JIS, and then install IBM Cognos 8 using an unattended installation. For more information, see the Installation and Configuration Guide.

RSV-SRV-0066 A soap fault has been returned or RQP-DEF-0114 The user cancelled the request Errors Appear in High User Load Environments
These errors may appear in the C8 cogserver.log if you have a high user load (over 165 users) and interactive reports are running continuously in a distributed installation. To resolve this problem, increasing the async_wait_timeout_ms parameter parameter in webapps/ p2pd/WEB-INF/services/reportservice.xml file. For more information, see the Cognos 8 Installation and Configuration Guide. Also, increase the Queue Time Limit setting to 360. For information, see the IBM Cognos 8 Administration and Security Guide.

Problems Configuring IBM Cognos 8

After you install IBM Cognos 8 components, you may encounter problems when you save changes in IBM Cognos Configuration. Ensure that you configure and start the services on the computer where Content Manager is located before you configure other components restart the IBM Cognos 8 service after you make any configuration changes

Configuration Tool cogconfig.sh Return Values Are Not Compliant with Conventional UNIX Return Values
On UNIX platforms, the configuration tool command cogconfig.sh returns 0 for an unsuccessful execution and 1 for a successful execution. These return values are not compliant with the conventional UNIX return results, where a return value of 0 indicates a successful execution and a nonzero return value indicates an error. The non-compliant behavior will be corrected in a future release. You may be required to make changes to your customer applications and scripts before making use of the new behavior.

Administration and Security Guide 567

Chapter 35: Installation and Configuration Problems

Run Database Cleanup Scripts

In some troubleshooting situations, you may be advised to start with new configuration data. You can run an SQL script to delete all the tables in any of the following databases that IBM Cognos 8 components use: content store for data that IBM Cognos 8 needs to operate delivery database for report notifications log database for log messages metric store for metric package content and Metric Studio user preferences

When you delete a table, its structural definition and data are deleted permanently from the database. For the metric store, database objects may also be deleted. When you restart the IBM Cognos 8 service, a new set of required database tables are created automatically in the location specified by your configuration settings.

Steps
1. On each computer where Content Manager is located, stop the IBM Cognos 8 service. 2. Go to the appropriate directory: To delete tables from the log database, go to c8_location\configuration\schemas\logging. To delete tables from the content store, go to c8_location\configuration\schemas\content. To delete tables from the notification database, go to c8_location\configuration\schemas\ delivery. To delete tables from the metric store, go to c8_location\configuration\schemas\cmm.

3. Go to the appropriate database directory. 4. Depending on the database and database type, run one of the following scripts in the appropriate database tool to delete the tables.

Database
Content store

Database Type
DB2 Derby Microsoft SQL Server Oracle Sybase

Script Name
dbClean_db2.sql dbClean_derby.sql dbClean_mssqlserver.sql dbClean_oracle.sql dbClean_sybase.sql NC_DROP_DB2.sql

Notification

DB2

568

Chapter 35: Installation and Configuration Problems

Database

Database Type
Derby Microsoft SQL Server Oracle Sybase

Script Name
NC_DROP_Derby.sql NC_DROP_MS.sql NC_DROP_ORA.sql NC_DROP_SYBASE.sql LS_dbClean_db2.sql LS_dbClean_derby.sql LS_dbClean_mssql.sql LS_dbClean_oracle.sql LS_dbClean_sybase.sql cmm_uninstall dbalias username password Specify the dbalias only if a database with the same name is already cataloged.

Log

DB2 Derby Microsoft SQL Server Oracle Sybase

Metric store

DB2

Microsoft SQL

cmm_uninstall metric_store_name database_name Admin_user_name password cmm_uninstalldatabase_name database_user_name password Replace database_name with the name in the tnsnames.ora file that refers to the database SID for Metric Studio

Oracle

5. Start the IBM Cognos 8 service.

Administration and Security Guide 569

Chapter 35: Installation and Configuration Problems

Error Trying to Encrypt Information When Saving Your Configuration

When you save your configuration using the configuration tool, you may see an error message that the cryptographic information cannot be encrypted. An error occurred when requesting a certificate from the Certificate Authority. The cryptographic information cannot be encrypted. Do you want to save the configuration in plain text? Before you can encrypt your configuration settings, the computer where Content Manager is installed must be configured and running. On UNIX, ensure that you copied the appropriate .jar files to the installation location of your Java Runtime Environment. In addition, ensure that your Java environment is configured correctly, the URIs are correct, and the same certificate authority password is configured for all Content Manager computers. On Linux, ensure that you copied the appropriate .jar files to the installation location of your Java Runtime Environment. Also, an error message similar to the following may appear: java.lang.NoClassDefFoundError: javax/net/ServerSocketFactory. The cryptographic error usually means the Java environment is not configured correctly. Ensure that the JAVA_HOME environment variable is set correctly and the appropriate security providers are installed, such as JSSE for JRE 1.31.

Steps to Check the Configuration

1. On the Content Manager computer, start IBM Cognos Configuration. 2. In the Explorer window, click Environment. 3. In the Properties window, verify these properties: Under Gateway Settings, Gateway URI Under Dispatcher Settings, External dispatcher URI and Internal dispatcher URI Under Other URI Settings, Dispatcher URI for external applications and Content Manager URIs 4. In the Explorer window, click Security, Cryptography, Cognos. 5. In the Properties window, under Certificate Authority settings, click the value for Password. Ensure that the same password is used on all Content Manager computers. 6. Save the configuration and restart IBM Cognos 8.

Problems Generating Cryptographic Keys in IBM Cognos Configuration

When you uninstall IBM Cognos 8, some temporary folders are left behind. Reinstalling the product to the same location without first removing the temporary folders may cause problems while attempting to generate the cryptographic keys in IBM Cognos Configuration.

570

Chapter 35: Installation and Configuration Problems To resolve this problem, uninstall IBM Cognos 8, remove the c8_location/temp/cam folder, and install IBM Cognos 8 again.

CAM-CRP-1315 Error When Saving Configuration

When you save your configuration, you may receive the following error message: CAM-CRP-1315 Current configuration points to a different Trust Domain than originally configured. This error occurs when there has been a change to your environments trust domain. The trust domain is managed by the Certificate Authority associated with the content store. This error can occur if the content store you originally used has been removed or if you modified your configuration to use a Content Manager associated with a different content store after you have saved your original configuration. To resolve the problem, change your configuration to use the original content store or regenerate the cryptographic keys.

Steps to Regenerate Cryptographic Keys

1. On the Content Manager computer, back up the existing cryptographic keys by saving the following directories to an alternate location that is secure: c8_location/configuration/csk c8_location/configuration/encryptkeypair c8_location/configuration/signkeypair

2. Delete the csk, encryptkeypair, and signkeypair directories. 3. In IBM Cognos Configuration, save the configuration and restart the services. 4. Repeat steps 1 to 3 on all computers that have IBM Cognos 8 components installed.

Manually Changing the Installation Directory Name Affects Installations Running Under an Application Server
You installed IBM Cognos 8 using the installation wizard and later renamed the installation directory or manually copied the contents to another directory. When you attempt to run IBM Cognos 8 within an application server, you may have one of the following problems: IBM Cognos 8 does not start. Log directories are empty. Logs contain a linkage error or unsatisfied link error.

When you manually change the installation directory, the information in the IBM Cognos 8 root directory becomes invalid. To resolve the problem, you must either update the IBM Cognos 8 root directory before you create the IBM Cognos 8 application file to deploy to the application server

Administration and Security Guide 571

Chapter 35: Installation and Configuration Problems or you must reinstall IBM Cognos 8 in the original location. If you reinstall IBM Cognos 8, follow the process for upgrading.

Steps
1. In the new or renamed installation directory, open c8_location/webapps/p2pd/WEB-INF/classes/ cogroot.link in a text editor. 2. Replace the path with the new location of the installation directory and save the file. 3. To build the application file to be deployed to the application server, in IBM Cognos Configuration, from the Actions menu, select Build Application Files. 4. If you built and deployed an application file to the application server before updating the cogroot.link file, undo the deployment. 5. Deploy the new application file to the application server. For more information about configuring IBM Cognos 8 for another application server, see the Installation and Configuration Guide.

Configuration Data is Locked by Another Instance of IBM Cognos Configuration

You may get an error message that the configuration data is locked by another instance of IBM Cognos Configuration. When you start IBM Cognos Configuration, it checks to see if the cogstartup.lock file exists in c8_location/configuration. The file may exist if a previous instance did not shut down properly or if another instance of IBM Cognos Configuration is running. If another instance of IBM Cognos Configuration is running, you should exit that instance. Otherwise, any changes you make to the local configuration may result in errors. If no other instance of IBM Cognos Configuration is running, delete the cogstartup.lock file in c8_location/configuration. If the IBM Cognos 8 service is stopped, click Start.

Unable to Exit a Tab Sequence When Using Keyboard-only Navigation in IBM Cognos Configuration
If you use the Tab key to navigate in IBM Cognos Configuration, you may experience problems exiting a tab sequence. For example, in the Properties window, you can press the Tab key to move from one property to another. However, because IBM Cognos Configuration is a Java application, when you want to close the Properties window, you must press Ctrl+Tab.

Unable to Save Your Configuration

You may be unable to save your configuration because you are missing a resource. For example, you delete a resource such as the Cognos namespace, a cryptographic provider, or the content store. You can replace the default database type for the content store with Oracle, DB2, or Sybase. You

572

Chapter 35: Installation and Configuration Problems cannot replace the Cognos namespace. You can recreate it, but you must then recreate your Cognos groups and roles. For more information about creating groups and roles in IBM Cognos Connection, see the Administration and Security Guide.

Steps to Recreate the Cognos Namespace

1. Start IBM Cognos Configuration. 2. In the Explorer window, under Security, right-click Authentication and then click New resource, Namespace. 3. In the Name box, type a name for the resource. 4. In the Type box, click Cognos, and then click OK. The Cognos namespace appears in the Explorer window. 5. From the File menu, click Save.

Java Error When Starting IBM Cognos Configuration

When you start IBM Cognos Configuration, you may receive an error message that the Java Runtime Environment (JRE) has changed and that the current cryptographic information is not compatible with the new JRE. You may then be prompted to regenerate the cryptographic information for the new JRE or exit to switch back to the previous JRE. This error may occur for one of these reasons: Your configuration data was encrypted using a different JRE than the one IBM Cognos 8 components are currently using. The cryptographic information may have been corrupted.

If you click Regenerate in the error dialog, the IBM Cognos 8 service is stopped and the cryptographic information is regenerated. If you click Exit in the error dialog, you must set the JAVA_HOME environment variable to point to the JRE that you used to save your configuration. On Windows, if you want IBM Cognos 8 components to use the JRE that is installed by default, unset JAVA_HOME or set JAVA_HOME to c8_location/bin/jre. Note: If you want to change from one JRE to another, see the topic on changing the version of JVM that IBM Cognos 8 components use. For more information, see the Installation and Configuration Guide.

Cryptographic Error When Starting IBM Cognos Configuration

When you start IBM Cognos Configuration, the following error message may appear: The cryptographic information may have been corrupted or the cogstartup.xml file is invalid. You may have to fix this file or remove it from disk. For more information, see the Installation and Configuration Guide.

Administration and Security Guide 573

Chapter 35: Installation and Configuration Problems This error occurs when IBM Cognos 8 components detect an error in the cogstartup.xml file. This can occur when the cogstartup.xml file is manually edited and there is an error in the changed text. To resolve the problem, replace the cogstartup.xml file with a copy from your backup location.

Current Configuration Settings Are Not Applied to Your Computer

You change default property values or add a resource to your installation in IBM Cognos Configuration. After saving the current configuration, you may not see the changes or be able to use the resource in the run-time environment. To apply the new settings to your computer, you must restart the IBM Cognos 8 service.

Steps to Restart the IBM Cognos 8 Service

1. Start IBM Cognos Configuration. 2. From the Actions menu, click the appropriate command: If the IBM Cognos 8 service is currently running, click Restart. This action starts all installed services that are not running and restarts services that are running. If you want to restart a particular service, select the service node in the Explorer window and then click Restart from the Actions menu. If the IBM Cognos 8 service is stopped, click Start. This action starts all installed services that are not running. If you want to start a particular service, select the service node in the Explorer window and then click Start from the Actions menu.

CM-CFG-029 Error When Trying to Save a Configuration That Specifies a SQL Server Content Store
In IBM Cognos Configuration, you try to save a configuration and the following error message appears in the cogserver.log file: CM-CFG-029 Content Manager is unable to determine whether the content store is initialized. EXECUTE permission is denied on object "sp_tables", database "master", owner "dbo'. This indicates that you do not have the correct permissions to initialize a content store or create a table in the database. The solution is to ensure that the content store user has permissions to use the sp_tables stored procedure in the master database.

DPR-ERR-2079 When Content Manager Configured For Failover

You configured multiple computers as standby computers to ensure failover for Content Manager. However, the following error message appears to the user: DPR-ERR-2079 Firewall Security Rejection. Your request was rejected by the security firewall This error message can occur if you have not configured all the standby computers as valid hosts for the IBM Cognos Application Firewall. 574

Chapter 35: Installation and Configuration Problems To solve this problem, on each distributed computer, start IBM Cognos Configuration and do the following: 1. In the Explorer pane, click Security, IBM Cognos Application Firewall. 2. In the right pane, click in the Value column next to Valid domains or hosts. 3. Click the edit button. 4. Enter the names of all the computers that you are configuring for failover. 5. Save and start the configuration.

Importing a Large Content Store in Solaris using JRE 1.5 Fails

If you export a content store that is greater than 2 GB when exported, and then attempt to import it in Solaris using JRE 1.5, the import fails with the error message "CM-SYS-5001 A Content Manager internal error occurred." This is due to a bug in JRE 1.5 on Solaris. Use JRE 1.4.2 instead.

Users are Prompted for Active Directory Credentials

The single signon mechanism does not work when IBM Cognos 8 is configured as follows: Microsoft Internet Explorer runs on a Windows NT computer. The authentication namespace is configured with the Active Directory provider. Microsoft Internet Explorer on a Windows 2000 or Windows 2003 server is configured for Integrated Windows Authentication.

As a result, users are prompted for their Active Directory credentials. This problem occurs because the IBM Cognos 8 Active Directory provider uses ADSI protocol and Kerberos delegation for authentication in a single signon environment. When Microsoft Internet Explorer runs on Windows NT, it cannot authenticate to the IIS server using Kerberos delegation. When your system is configured for Windows Integrated Authentication, for the single signon to work with IIS, you must configure IBM Cognos 8 to communicate with the Active Directory server using the LDAP provider. configure the external identity mapping property to read the REMOTE_USER environment variable.

Font on UNIX Not Found When Starting IBM Cognos Configuration

When you start IBM Cognos Configuration, the following error message may appear: Font specified in font.properties not found... This is a common problem on UNIX. It means that the Java Virtual Machine (JVM) is trying to use one or more fonts that are not installed on your computer. However, the JVM should use the system default, and IBM Cognos Configuration should start and run normally. Administration and Security Guide 575

Chapter 35: Installation and Configuration Problems To avoid these errors, add the missing fonts to your Java Runtime Environment by editing the font.properties files. Several font.properties files, which contain standard font environment information, are installed with your Java SDK. You can find these files in the JRE_location/lib directory. For more information, see the Java documentation.

Unable to Load Essbase/DB2 OLAP Library in Framework Manager

If you install an earlier Essbase/DB2 OLAP client version than what is configured for IBM Cognos 8, you may receive this error: DB2-ERR-0028 Unable to load the following DB2 OLAP library: "C:\ibm\db2olap\bin\essapin.dll" For example, you installed DB2 OLAP 8.1 client and the qfs_config.xml file in IBM Cognos 8 is configured to use the DB2 OLAP library for Version 8.2. To resolve this problem, you must edit the qfs_config.xml file and change the library name for the appropriate client version you are installing.

Steps
1. In the c8_location\configuration directory, edit the qfs_config.xml file. 2. Find the following code:
<provider name="DB2OlapODP" libraryName="doodp82" connectionCode="DO"/>

3. Change the library name from doodp82 or doodp81 and save the changes. Hyperion Essbase version 9.3.1 is the default client configuration. If you are installing DB2 OLAP client for either Version 8.1 or 8.2, you must edit the qfs_config.xml file and change the library name for the appropriate client version you are installing.

Steps
1. In the c8_location\configuration directory, edit the qfs_config.xml file. 2. Find the following code:
<provider name="DB2OlapODP" libraryName="essodp93" connectionCode="DO"/>

3. Change the library name from essodp93 to doodp81 or doodp82 and save the changes.

Group Membership is Missing From Active Directory Namespace

If an Active Directory namespace is configured for the same forest and a user is authenticated using a credential, the group membership will be missing. The process identity of IBM Cognos 8, when running as a local system account or a domain user, must have one of these privileges: impersonate a client after authentication act as part of the operating system

If the privilege is missing, there is no group membership for the authenticated user.

576

Chapter 35: Installation and Configuration Problems To solve this problem, perform the following steps.

Steps
1. From the Start menu, click Settings, Control Panel. 2. Click Administrative Tools, and then double-click Local Security Policy. 3. In the console tree, click Security Settings, Local Policies. 4. Click User Rights Assignment. 5. Add the process identity of IBM Cognos 8 to one of the following policies: Impersonate a client after authentication The default is Administrators, Service. For more information, see http://technet2.microsoft.com/WindowsServer/en/Library/ fe1fb475-4bc8-484b-9828-a096262b54ca1033.mspx Act as part of the operating system The default is Local system. For more information, see http://technet2.microsoft.com/WindowsServer/en/Library/ ec4fd2bf-8f91-4122-8968-2213f96a95dc1033.mspx Both of these privileges give an account the ability to act as another user. The privilege Impersonate a client after authentication is similar to the Act as part of the operating system privilege except that it will only allow a process to impersonate after authentication, whereas the privilege Act as part of the operating system allows a process to impersonate before authentication. For more information, see http://www.microsoft.com/technet/prodtechnol/windowsserver2003/ technologies/security/tkerbdel.mspx

Deploying IBM Cognos 8 to an Oracle Application Server or IBM WebSphere Application Server
You are deploying IBM Cognos 8 to an Oracle application server or an IBM WebSphere application server and you receive the following errors: Browser timeout in administration console Error Message: HTTP 500 Internal Error Error Message: Deployment failed: Base Exception: java.rmi.RemoteException (Oracle) Return to application file selection page (IBM WebSphere)

This error can occur because the application file that you are trying to deploy is too large. To solve this problem, on an Oracle application server, you can deploy the application file manually using the following command:

Administration and Security Guide 577

Chapter 35: Installation and Configuration Problems dcmctl deployapplication -f <path and name of ear file> -a <application name> -co <OC4J instance name> For either IBM WebSphere or Oracle application servers, clear the Include static files from the Webcontent folder option when you use the Build Application Wizard. Not including the static content will reduce the size of the application file. If static content is required, you can manually copy it to the deployed application location after you have successfully deployed IBM Cognos 8 into the application server. For more information about deploying IBM Cognos 8 to an application server, see the Installation and Configuration Guide.

Errors Displayed Deploying to Oracle 10G Application Server

You are deploying IBM Cognos 8 to an Oracle 10G Application Server, and get the following error messages: CMM-APP-3254 The initialization of the metrics store failed. DIS-ERR-3115 Task execution failed. MDS-RUN-3213 Unable to locate database bulk load utility. Please install the appropriate database tool for this platform ('bcp' for SQL Server, 'sqlldr' for Oracle) This occurs because the bulk loading utilities (SQL Loader on Oracle) are not included in the deployment file created by IBM Cognos Configuration. To resolve this error, you must use the Oracle client software on the computer where you installed the Oracle 10G Application Server to install the missing components. Ensure that you install SQL Loader.

Page Cannot be Found Error Running Reports using IBM Cognos 8 Go! Office
In a Microsoft Office document configured for IBM Cognos 8 Go! Office, you use Run Report but receive a "The page cannot be found" error message. This can occur if the IBM Cognos 8 gateway and dispatcher use "localhost" as the server name values on the IBM Cognos 8 server. To correct this, use the computer name for the gateway and dispatcher host values instead of "localhost".

Error Initializing Oracle Content Store After Upgrade from ReportNet

You are creating a content store in Oracle or upgrading a ReportNet content store in Oracle to IBM Cognos 8, and you receive the following error message: Content Manager can not initialise the content store with the assistance of the initialisation file: dbupgrade2_0021-to-2_0022_oracle.sql ORA-22858 invalid alteration of datatype This error occurs if the Oracle database compatibility level is set lower than 9.0.1. You can correct this by changing the compatibility level to 9.0.1 or higher and restarting the Oracle instance.

578

Chapter 35: Installation and Configuration Problems

CGI Timeout Error While Connected to IBM Cognos 8 Components Through a Web Browser
When performing operations through your Web browser, you receive the following error message: CGI Timeout, process will be deleted from server. The error occurs when you use Windows Internet Information Services (IIS) as your Web server and the gateway is configured to use CGI. IIS has a default timeout for CGI applications. To resolve this problem, you can configure the gateway to use ISAPI. IIS does not have a default timeout for ISAPI applications. Or, if you want to keep using a CGI gateway, you can increase the CGI timeout in IIS.

Steps to Change the Gateway to ISAPI

1. On the gateway computer, start IBM Cognos Configuration. 2. Under Environment, for the Gateway URI property, change the cognos.cgi portion of the URI to cognosisapi.dll 3. In your Web browser, specify the ISAPI URI: http://computer_name/cognos8/isapi

Steps to Increase the CGI Timeout

1. In the Windows administrative tools, open Internet Information Services. 2. Under the local computer node, right-click Websites and select Properties. 3. In the Home Directory tab, click Configuration. 4. In the Process Options tab, increase the CGI script timeout.

Servlet Class Fails to Load in WebLogic

You may have problems when configuring a distributed server installation and using WebLogic as the application server for IBM Cognos 8. When deploying the p2pd.war for the Application Tier Components computer, you may receive servlet exceptions and the dispatcher does not start. The cogserver.log is also not created. The following error messages appear in the WebLogic Server console: <Jul 9, 2004 3:47:37 PM EDT> <Error> <HTTP><BEA-101249> <[ServletContext (id=19023494,name=p2pd,context-path=/p2pd)]:Servlet class com.cognos.pogo.isolation.ServletWrapper for servletcfgss could not be loaded because the requested class was not found in the classpath /host2/bea812/user_projects/domains/c8/applications/p2pd/WEB-INF/classes. java.lang.ClassNotFoundException: com.cognos.pogo.isolation.ServletWrapper.> <Jul 9, 2004 3:47:37 PM EDT> <Error> <HTTP> <BEA-101216> <Servlet: "cfgss" failed to preload on startup in Web application: "p2pd".

Administration and Security Guide 579

Chapter 35: Installation and Configuration Problems javax.servlet.ServletException: [HTTP:101249][ServletContext(id=19023494,name=p2pd,contextpath=/p2pd)]: Servlet class com.cognos.pogo.isolation.ServletWrapperfor servlet cfgss could not be loaded because the requested class was not found in the classpath /host2/bea812/user_projects/ domains/c8/applications/p2pd/WEB-INF/classes.java.lang.ClassNotFoundException: com.cognos.pogo.isolation.ServletWrapper. at weblogic.servlet.internal.ServletStubImpl.prepareServlet (ServletStubImpl.java:799) at weblogic.servlet.internal.WebAppServletContext.preload Servlet(WebAppServletContext.java:3252) To avoid this problem, do not deploy the p2pd application from the WebLogic applications directory. Create the p2pd directory in another location and deploy p2pd from there.

Steps
1. Open IBM Cognos Configuration and configure the Application Tier Components computer. 2. Restart the Content Manager computer. 3. Create a p2pd directory in a location that is accessible by the WebLogic server but is not in the WebLogic applications directory. For example, create a directory named p2pd in the following location: WebLogic_location/user_projects/domain_name 4. Create the p2pd.war file. 5. In the p2pd directory, extract the p2pd.war file to the WebLogic installation using the following command: %JAVA_HOME%/bin/jar xvfm "c8_location/p2pd.war" . 6. Start WebLogic. 7. In the WebLogic Server Console, deploy the p2pd application.

Desktop Icons or IBM Cognos Configuration Window Flicker on Windows

When you run IBM Cognos Configuration on Windows, you may notice that the desktop icons or the IBM Cognos Configuration window flickers. To resolve this issue, start IBM Cognos Configuration using the -noddraw command line option.

580

Chapter 36: Security Problems

You may encounter problems when using IBM Cognos Connection to administer security in IBM Cognos 8. For information about using IBM Cognos Connection, see the IBM Cognos Connection User Guide. For information about security administration, see the Administration and Security Guide.

Problems Setting Up Security

The topics in this section document problems you may encounter when setting up security.

Access to Entries is Denied During Deployment

If you deploy data using the Reports Administrator role, access to security entries may be denied. By default, the Reports Administrator role does not have write access to the Cognos namespace. Before you deploy, modify the permissions of this role to ensure that it has read and write permissions to the Cognos namespace.

Prompt to Change Passwords When Logging On to an Active Directory Security Source

When logging on to IBM Cognos 8 using a Microsoft Active Directory security source, the submitted password is recognized as expired and you are prompted to change it. This occurs even if the password should still be valid. If the password is successfully changed, the behavior still occurs. The following error message appears: Your password has expired. Please change it. Please type your credentials for authentication. The solution is to set up the authority for delegated administration for IBM Cognos 8. Ensure that the server name or named account for starting the IBM Cognos 8 service is set up in the Active Directory properties as an authority for delegated administration. Without these permissions, IBM Cognos 8 is unable to read all user properties from the Active Directory server. For more information, see the Active Directory documentation.

Unable to Log On
If IBM Cognos 8 uses an Active Directory Server as the security provider, you may not be able to log on using only your user ID. One of the following errors may appear: Your password has expired. Please change it. The provided credentials are invalid. This problem occurs when the Content Manager service runs under the local system account and runs on a computer that is not part of the Active Directory Server domain.

Administration and Security Guide 581

Chapter 36: Security Problems To log on, you must qualify your user ID using the domain name. For example, when you log on, type domain\user ID If you still cannot log on, contact your IBM Cognos 8 security administrator.

Certificate Authority Error When Logging On to IBM Cognos Connection

You attempt to log on, entering a valid user ID and Password, to IBM Cognos Connection in an environment that uses the default IBM Cognos Cryptographic Provider settings. However, the following error message appears: CAM-CRP-1071 Unable to process a remote request for the common symmetric key. The certificate with the DN C=CA,O=Cognos,CN=CAMUSER issued by the Certificate Authority with the DN C=CA,O=Cognos,CN=CA is not trusted. Reason: Exception thrown while doing CertPath validation Cause:certificate expired on yyymmddhhmmGMT+00:00 This problem occurs when the certificate issued by the Certificate Authority (CA) has expired. You can renew the certificate by saving the configuration in IBM Cognos Configuration on the computer where Content Manager is installed and then restarting the IBM Cognos 8 service.

HTTPS DRP-ERR-2068 Error In Log File When No Error is Reported During a Switch to HTTPS
You stopped the services on all computers in a distributed installation and configured the computers to use SSL (HTTPS). You started the services successfully, with no reported errors. However, when you checked the log file, you found an error similar to the following: HTTPS DPR-ERR-2068 The administration request failed. Cannot connect to dispatcher. The error occurred because when you restarted the services, the dispatchers were initializing and could not communicate with each other. During the initialization, a normal administration request could not be processed and a fault was generated. The fault was recognized as an initialization fault and so no error was shown during the startup. However, IBM Cognos Application Firewall does not distinguish between a regular fault and an initialization fault. As a security best practice, all messages are sent to the log file. You can ignore the message in the log file.

Entries Do Not Appear in IBM Cognos Connection for a Member of a Newly Created Group
A user who is a member of a newly created group, which is itself a member of the Query Users group, logs on to IBM Cognos Connection. The user sees that some entries, such as My Folders, are missing. The user name may also be missing from the upper-left corner of the page.

582

Chapter 36: Security Problems The namespace that the user belongs to must have traverse rights to the Query Users group.

Steps to Add Traverse Permission

1. Log on to IBM Cognos Connection as a system administrator. 2. Click Directory. 3. Click Set Properties next to the namespace. 4. Click the Permissions tab. 5. If it is not already there, add the Query Users group to the namespace. 6. Click the check box for Query Users and ensure that Traverse permission is granted. 7. Click Apply, and click OK. 8. Test with a user.

Problems Logging On to Cognos Portlets

There are several reasons why users with valid portal user IDs and passwords may not be able to log on to Cognos Portlets. For information about configuring single signon between IBM Cognos 8, Portal Services, and your portal, see the IBM Cognos 8 Installation and Configuration Guide.

Anonymous Access
If IBM Cognos 8 is configured to allow anonymous access, all portlet users are logged on as anonymous.

Multiple Namespaces
If IBM Cognos 8 is configured to use more than one authentication namespace, you must install a separate IBM Cognos 8 gateway and configure it to use the namespace for portal users. You must also change the CPS connection point in the Cognos portlets: For IBM Websphere, change the CPS Endpoint parameter in the portlet application. For SAP EP, change the _cpsserver: CPS Connection Server field in each iView.

SAP Enterprise Portal Using the SAP Logon Ticket Method

If you use the SAP Enterprise Portal and the SAP logon ticket method to enable single signon, ensure that the following is true: IBM Cognos 8 is configured to use an SAP BW authentication namespace. A proper trust relationship is established between the SAP portal and the SAP BW back end.

SAP Enterprise Portal Using the User Mapping Method

If you use the SAP Enterprise Portal and use the user mapping method to enable single signon, ensure that the following is true: Administration and Security Guide 583

Chapter 36: Security Problems A data source was created in the SAP Enterprise Portal, and it refers to the same IBM Cognos 8 URL as in the iViews. The iView generating the error is associated with the IBM Cognos 8 data source in the portal. The user entered valid IBM Cognos 8 credentials in the portal.

These settings are located under user mappings in the personalize portal settings. The user name and password are registered in the namespace used by IBM Cognos 8. The IBM Cognos 8 URL entry point is secured in IBM Cognos 8.

Create a secure URL to access the dispatcher servlet or servlet gateway.

IBM WebSphere Portal

If you use the IBM Websphere portal, ensure that the following is true. The credentials for the portal user are available in the IBM Cognos 8 authentication namespace. The server running the portal and the server running IBM Cognos 8 are both configured to use the IBM WebSphere Application server. Both application servers are configured for single signon using one of the supported Active Credentials objects: HttpBasicAuth, LtpaToken, SiteMinderToken, or WebSealToken. The selected Active Credentials method is indicated in the parameters for the Cognos portlet application. If using Ltpa token as an Active Credentials object, the IBM Cognos 8 URL entry point is secured in IBM Cognos 8.

Create a secure URL to access the dispatcher servlet or servlet gateway.

Existing Passwords May not Work in an SAP Namespace

When you log on to IBM Cognos Connection using an SAP namespace, some previously functional passwords may no longer work. The following error message may appear: "Unable to authenticate a user. Please contact your security administrator. Please type your credentials for authentication". This is because of a policy change in SAP software. In previous versions of SAP software, passwords were not case sensitive. All password characters were automatically converted to uppercase. In SAP RFC 6.40, password characters are not automatically converted to uppercase and so passwords are case sensitive. To address the password policy change, the SAP BAPI interface introduced a new configuration parameter named bapiPasswordConv. Using this parameter, you can enable or disable the functionality that automatically converts all password characters to uppercase. To ensure that all previously created passwords can still provide successful logon to IBM Cognos Connection, set the value of the bapiPasswordConv parameter to true.

Steps to Change the Setting of the bapiPasswordConv Parameter

1. Open the file bapiint_config.xml.

584

Chapter 36: Security Problems This file is located in the c8_location\bin directory. 2. Change the value of the bapiPasswordConv parameter to true, as shown in the following fragment of code:
<bapiAbapDebug value="false"/> <bapiTransCall value="false"/> <bapiCharConv value="true"/> <bapiCmdRecording value="false"/> <bapiCacheReset value="false"/> <bapiCallLocks value="false"/> <bapiSupportCancel value="true"/> <bapiMaxSuspendTime value="200"/> <bapiPasswordConv value="true"/>

3. Save the file. 4. Restart the IBM Cognos 8 service. For more information, see the following SAP Notes: 792850 - Preparing ABAP systems to deal with incompatible passwords 862989 - New password rules as of Web AS ABAP 7.0/NetWeaver 2004

Users Are Repeatedly Prompted for Credentials When Trying to Log On to an SAP Namespace
When users whose user IDs or passwords contain special characters try to log on to an SAP namespace, they are repeatedly prompted for credentials and may not be granted access. This is because SAP BW systems, version 3.5 and older, by default use a non-Unicode code page. Newer SAP systems use a Unicode code page. As a result, the default SAP server code page was modified for the SAP authentication provider to use a Unicode code page, which is SAP CP 4110. To avoid this issue, in IBM Cognos Configuration, modify the default SAP BW Server Code Page parameter for the SAP authentication provider to use a non-Unicode code page, such as SAP CP 1100.

Problems Using Authentication Providers

The topics in this section document problems you may encounter when using an authentication provider.

CAM-AAA-0096 Unable to Authenticate User When Using an IBM Cognos Series 7 Namespace
When you try to log on in IBM Cognos 8 using a user account that is deleted from all user classes in Access Manager, you receive the following error message: CAM-AAA-0096 Unable to authenticate because the account can not be accessed. The scenario is as follows: You create a new user in IBM Cognos Series 7 Access Manager and assign them to a user class.

Administration and Security Guide 585

Chapter 36: Security Problems You log on to IBM Cognos 8 as Administrator and assign the same Series7 user to an IBM Cognos 8 role, such as authors. You log off IBM Cognos 8 and log on again as the new Series7 user. In Access Manager, you remove that user from the user class so that the user is not in any user classes. In IBM Cognos 8, when you try to log on as the user, you get the error message.

If you configured an IBM Cognos Series 7 namespace for use with IBM Cognos 8, but a user in that namespace is not a member of at least one Access Manager user class, you cannot log on as that user in IBM Cognos 8. To correct the problem, add the user to at least one user class in Access Manager.

Expired Password Error Appears When Using Active Directory Server

You use Active Directory Server as an authentication provider. When you log on to IBM Cognos 8, you see the following error message: Your password has expired. Please change it. Please type your credentials for authentication. Ensure that you set up the authority for delegated administration for IBM Cognos 8. The server name or named account for starting the IBM Cognos 8 service must be set up in the Active Directory Server as an authority for delegated administration. IBM Cognos 8 can then read all user properties from the Active Directory server. For more information, see the Active Directory Server documentation.

Single Signon Is Not Working When Using Active Directory Server

You use Active Directory Server as an authentication provider and single signon is not working. To ensure that users are not prompted to log on to IBM Cognos 8, the following must be true: Active Directory is running in native mode. The user does not have the Account is sensitive and cannot be delegated attribute selected. For each IIS Web server This computer is part of the Active Directory domain. If the process is running as a Local System Account, the Trust computer for delegation attribute is selected. If the process is running as a Domain User Account, the Account is trusted for delegation attribute is selected.

For each ReportNet Content Manager server This computer is part of the Active Directory domain If the process is running as a Local System Account, the Trust computer for delegation attribute is selected

586

Chapter 36: Security Problems If the process is running as a domain User Account, the Account is trusted for delegation attribute is selected.

Kerberos authentication must be the active WWW-authentication header.

Note: Kerberos will not work in an Internet zone.

Unable to Authenticate User for Cognos Portlets

When you attempt to access Cognos portlets through your portal, you may see the following error message: Failed to process the request. CPS-CCM-1200 The WSRP operation "getMarkup" failed. CPS-WSF-2000 Authentication failed. CAM-AAA-0055 User input is required. CAM-AAA-0036 Unable to authenticate because the credentials are invalid. A more detailed description of the error that occurred can be found in the log. This message indicates that Portal Services is unable to authenticate the current portal user with IBM Cognos 8. For information about how to configure single signon between IBM Cognos 8, Portal Services, and your portal, see the IBM Cognos 8 Installation and Configuration Guide.

Unable to Identify SAP Permissions Required

You may encounter errors using SAP BW because your SAP user signon does not have sufficient permissions. To identify the permissions needed, use the ST01 transaction.

Steps
1. In SAP R/3, type /ST01 in the command window. 2. Under Trace components, select Authorization check. 3. Select Change trace. 4. In the Options for Trace Analysis Field, under General Restrictions, enter the user name of the IBM Cognos account you are tracing.

Unable to Access IBM Cognos Administration When an NTLM Namespace Is Used and Single Signon Is Enabled
When you are logged into IBM Cognos 8 using an NTLM namespace and single signon is enabled for your system, an IBM Cognos Application Firewall (CAF) error may occur when you try to access IBM Cognos Administration.

Administration and Security Guide 587

Chapter 36: Security Problems To avoid this problem, resolve any possible issues related to the gateway host name. You can either ensure that the gateway host name matches the gateway host or you can add the name of the gateway server to the list of valid domains and hosts.

Steps to Match the Gateway Host Name

1. Open IBM Cognos Configuration. 2. In the Explorer window, click Environment. 3. In the Properties window, under Gateway Settings, ensure that Gateway URI specifies the correct server name or IP address and not localhost. Tip: We recommend that all URI properties specify a server name or IP address and not localhost. 4. Save the configuration.

Steps to Add the Gateway Server as a Valid Host

1. Open IBM Cognos Configuration. 2. In the Explorer window, under Security, click IBM Cognos Application Firewall. 3. In the Properties window, click the Value column for Valid domains or hosts and then click the edit button. 4. Click Add. 5. Type the name of the gateway server in the blank row and then click OK. For more information about valid domains, see the Installation and Configuration Guide. 6. Save the configuration. 7. Restart the IBM Cognos 8 service.

588

Chapter 37: Report and Server Administration Problems

You may encounter problems when using IBM Cognos Connection to administer IBM Cognos 8. For information about using IBM Cognos Connection, see the IBM Cognos Connection User Guide. For information about administration, including setting up sample report projects and models, see the IBM Cognos 8 Administration and Security Guide.

Database Connection Problems

Each data source can contain one or more physical connections to databases. The topics in this section document problems you may encounter when setting up a database connection.

Unable to Select ODBC as the Type of Data Source Connection

Because IBM Cognos 8 on UNIX does not support all ODBC drivers, when you create data source connections to IBM Red Brick, Microsoft SQL Server, or NCR Teradata databases, you cannot select ODBC as the type of data source connection. To create an ODBC connection to these database vendors, select Other Type instead. For the following database vendors, add the associated database codes when you type the connection string.

Database vendor
IBM Red Brick Microsoft SQL Server NCR Teradata Type the data source connection, as follows:

Database code
RB SS TD

[^UserID:[^?Password:]];LOCAL;{RBSSTD};DSN=Data_Source[; UID=%s[;PWD=%s]][@ASYNC= {01}][@Connection_Timeout/Reply_Timeout][@COLSEQ=[Collation_Sequence]] The following are examples of connection strings: ^UserID:^?Password:;LOCAL;RB;DSN=DB62SALES;UID=%s;PWD=%s@ASYNC=0 ;LOCAL;SS;DSN=TESTSERVER

To create data source connections to Microsoft SQL Server from UNIX, you must use the DataDirect ODBC driver for SQL Server. For more information, see the Administration and Security Guide.

Administration and Security Guide 589

Chapter 37: Report and Server Administration Problems

Cannot Connect to an SQL Server Database Using an OLE DB Connection

You cannot create a native connection to a Microsoft SQL Server using OLE DB in IBM Cognos Connection. The following error messages appear: QE-DEF-0285 Logon failure QE-DEF-0325 The cause of the logon failure is: QE-DEF-0068 Unable to connect to at least one database during a multi-database attach to 1 database(s) in: testDataSourceConnection UDA-SQL-0031 Unable to access the "testDataSourceConnection" database UDA-SQL-0107 A general exception has occurred during the operation "{0}" UDA-SQL-0208 There was an error initializing "MSDA" for OLEDB The solution is to ensure that MDAC version 2.71 or higher is installed. The registry of the local system should hold the MDAC version information.

Intermittent Problems Connecting to a SQL Server Database

You use SQL Server database as a reporting data source. You test the same database connection several times in IBM Cognos Connection. Sometimes the test succeeds, but other times you see one of the following or a similar error message: SQL Server cannot be found. Access denied. In addition, when you run reports, sometimes they run but other times you see the following or a similar error message: Connection not found - Check DNS entry or select different connection. You may also have problems creating the database that is used for the content store. These errors can occur if you configure named pipes instead of TCP/IP protocol as the default network library in the SQL Server Client Network Utility for a SQL Server reporting or content store database.

Cannot Access IBM Cognos Series 7 Reports from IBM Cognos Connection
After modifying IBM Cognos 8 to use an IBM Cognos Series 7 namespace and modifying the system.xml file, the Upfront content is not available in the Public Folder area and the personal content is not available in the My Folder area. The solution is to ensure that the value for the <!-- character encoding used by series7 --> entry uses the series7_character_encoding value. This value can be obtained from the IBM Cognos Series 7 IBM Cognos Configuration Manager. The value can be shown in the Explorer pane by clicking Locale under IBM Cognos Shared.

Steps to Modify the Character Encoding Used by IBM Cognos Series 7

1. Open the system.xml file located in the <installation drive>:\Program Files\cognos\c8\templates\ ps directory.

590

Chapter 37: Report and Server Administration Problems 2. Modify the <!-- Series 7 Integration parameters --> <param name="series7"> <enabled>true</enabled> <!-- character encoding used by series7 --> <encoding>windows-1252</encoding> <!-- host and port to connect to Upfront server --> <host>wottcumarasr2k1</host> <port>8030</port> <!-- Upfront gateway location --> <gateway>/cognos/cgi-bin/upfcgi.exe</gateway> <!-- prefix for IBM Cognos 8 back URLs when linking to series 7 content. (e.g., http://Cognos 8 computer) --> <back-prefix>http://wottcumarasr2k1</back-prefix> </param>

Series 7 Namespaces Do Not Initialize When Services are Started

To address an issue related to Series 7 namespaces, a new setting called Series7NamespacesAreUnicode has been added to IBM Cognos Configuration. This setting instructs the IBM Cognos 8 Series 7 provider to enable UTF-8 processing on the namespace data. UTF-8 processing is only available with Series 7 namespaces of version 16.0 and above. For other versions, the behavior and actions are as follows: In a multi-code page environment, do not disable the setting or the server may fail. If the system finds a Series 7 version 15.2 namespace and the Series7NamespacesAreUnicode setting is enabled, IBM Cognos 8 reverts to disabled behavior. If you have a mixed namespace environment, that is, a directory server with both version 15.2 and version 16.0 namespaces, the version 15.2 namespace may not initialize. In this case, you must disable the Series7NamespacesAreUnicode setting.

Content Manager Connection Problem in Oracle (Error CM-CFG-5036)

Starting the IBM Cognos 8 Service does not create the tables in an Oracle Content Manager. One of the following error messages is generated: CM-CFG-5063 A Content Manager configuration error was detected while connecting to the content store. CM-CFG-5036 Content Manager failed to connect to the content store. CM-SYS-5007 Content Manager failed to start. Review the Content Manager log files and then contact your system administrator or customer support.

Administration and Security Guide 591

Chapter 37: Report and Server Administration Problems When you create a new database in Oracle, the SID name that is created has no underscore in it. You must use this SID with no underscore as the Service Name in IBM Cognos Configuration.

Steps to Configure the Oracle Content Manager

1. Ensure that you can contact the Oracle instance through "tnsping <SID>" where the <SID> does not contain an underscore. 2. Configure the Oracle Content Manager connection in IBM Cognos Configuration so that the Service Name is the same as the <SID> in step 1.

Cannot Connect to an OLAP Data Source

You cannot connect to an OLAP source (such as SAP BW, Essbase, or DB2 OLAP) Confirm the following: You can open the OLAP server from Microsoft Excel. Most OLAP vendors have a plug-in which allows connectivity through Excel. You have the correct client software installed on the relevant IBM Cognos 8 servers. Any IBM Cognos 8 computer which retrieves data from the OLAP source must have the appropriate client software. For MSAS, check that Pivot Table service is installed and the correct service pack is applied. You can open the OLAP source through IBM Cognos Series 7. You can open either the OLAP vendor samples or the IBM Cognos samples. The problem may be specific to one model, outline, or cube. The user making the request from IBM Cognos 8 is a Domain user with the appropriate access rights.

Error When Creating a Data Source Connection to a PowerCube

When you create a data source connection to a PowerCube where both the PowerCube and all report servers are on UNIX or Linux computers, the following error may appear: "The field "Windows location:" is mandatory" To solve the problem, type any characters in the Windows location field. The UNIX or Linux location must be correct.
592187

Not Yet Optimized IBM Cognos PowerCubes May Open Slowly in IBM Cognos 8
If PowerCubes created with previous versions of Transformer take too long to open in the IBM Cognos 8 Web studios, we recommend that you run a command line utility named pcoptimizer, supplied with IBM Cognos 8, to improve run-time performance. This optimization utility is suitable for older PowerCubes when the model no longer exists or the data used to build the PowerCube is

592

Chapter 37: Report and Server Administration Problems no longer available. It is not necessary to run this command line utility for cubes created in Transformer version 8.x.

Steps
1. Back up your target PowerCube, then navigate to the Cognos_8_installation_location/bin directory. 2. On Windows, open a command line window and run PCOptimizer.exe. 3. On UNIX/Linux, enter the following line to run the optimization command line utility:
pcoptimizer [-t] [-v] [-h]cubename

where cubename is the fully qualified PowerCube or time-based partitioned control cube name with the .mdc extension, if the PowerCube resides in the same location as pcoptimizer. Otherwise, cubename is the full path with the .mdc extension. Note: This method only supports metadata extraction. To set up user-configurable drill-through, you must use Transformer. Wildcard character support is not currently available. You must therefore invoke the utility once per PowerCube. If cubename is not provided, the program enters an interactive mode, prompting you for a PowerCube name and accepting keyboard input. The optional parameters are as follows:
-t or test mode; it tests whether the metadata was extracted and loaded into the PowerCube.

The return code indicates the status. 0 if the metadata was extracted and loaded 10 if the metadata was not loaded 20 if an error occurred while accessing the PowerCube

-v or verbose mode; text is output to standard output (stdout), indicating what was done,

including any error messages. If running in interactive mode, -v is assumed. All text is output in English only.
-h for command-line help; if cubename is not provided, it prints the usage and options to

the screen.

Other Administration Problems

The topics in this section document problems you may encounter when administering IBM Cognos 8.

Restarting Servers After Solving Content Store Problems

If the content store becomes unavailable, after resolving the problem, you must stop and restart IBM Cognos 8 services to resume processing. For information about stopping and starting IBM Cognos 8 services, see the IBM Cognos Configuration User Guide.

Administration and Security Guide 593

Chapter 37: Report and Server Administration Problems

An Update or Delete Request Fails

When any property of an object changes, the version property associated with the object changes. If you try to update or delete an object, the request fails if the value of the version property changed after you retrieved the object from the data store. For example, if two administrators read the properties of the same object at the same time, they both have the same version of the object. If they both try to update, the first update request succeeds. However, the second update request fails because the version of the object no longer matches the version retrieved from the data store. If this happens when you submit an update request, you must read the data again to get the current version of the object and then resubmit your update request.

BI Bus Server Processes Remain in Memory After a Shutdown

On rare occasions, the processes for the BI Bus server, BIBusTKServerMain, may stay in memory after you perform a normal shutdown. If this occurs, terminate the processes manually.

Steps to Terminate Processes in Windows

1. In the Windows Task Manager dialog box, click the Processes tab. 2. Click the BIBusTKServerMain processes. 3. Click End Process.

Steps to Terminate Processes in UNIX

1. Use the ps command to find the orphan processes. For example, type ps -ef grep | BIBus 2. Use the kill -9 command to terminate the processes. For example, type kill -9 [BIBus process-id]

Higher Logging Levels Negatively Affect Performance

All the IBM Cognos 8 services send events to the log server, which directs messages to a log file. After an error or problem occurs, you can review the log messages to obtain clues as to what happened. Log messages also provide the status of components and a high-level view of important events, such as successful completions and fatal errors. In the server administration tool, five levels of logging are available. They range from minimal, which logs the least amount of detail and is intended for less frequent events, to full, which logs more detail and is intended for more frequent events and detailed troubleshooting purposes. Increasing the logging level may negatively affect the performance of IBM Cognos 8. The higher the level of detail logged, the more resources that are used. If performance is slow, you can try lowering the logging levels.

594

Chapter 37: Report and Server Administration Problems To access the server administration tool, you must have execute permissions for the Administration secured function.

Steps to Change Logging Levels

1. In IBM Cognos Connection, click Launch, IBM Cognos Administration. 2. On the Configuration tab, click Dispatchers and Services. 3. In the Actions column, click the set properties button for the dispatcher or configuration folder you want. 4. Click the Settings tab to view all the configuration settings. 5. In the Value column, click a new value for the following settings, each of which represents a logging category: Audit logging level Audit run-time usage logging level Audit administration logging level Audit other logging level

Tip: If you want to reset a configuration setting to its default value, select its check box and click Reset to parent value. 6. Click OK.

Problems Accessing Cognos Portlets

When you attempt to access Cognos portlets through your portal, you may see an error message similar to one of the following: Failed to process the request. CPS-WSR-1042 Failed to send the request to target "http://MyServer:9300/p2pd/servlet/dispatch/ cps2/nav". Connection refused: connect A more detailed description of the error that occurred can be found in the log. Failed to process the request CPS-CCM-1200 The WSRP operation "getMarkup" failed CPS-WSF-2008 Normal execution of the operation failed PRS-TPR-0352 Failed to open template file "/cps2/portlets/nav2/navigator/getMarkup.xts" A more detailed description of the error that occurred can be found in the log Failed to process the request CPS-WSR-1049 The request failed the server returned the HTTP error code "404" for the target "http://wottbouillom-2k:9300/p2pd/servlet/gateway/cps2/nav" A more detailed description of the error that occurred can be found in the log Administration and Security Guide 595

Chapter 37: Report and Server Administration Problems Failed to process the request CPS-WSR-1043 Failed to read the response from target "http://sottcps3:9300/p2pd/servlet/dispatch/ cps2/nav" Stream closed A more detailed description of the error that occurred can be found in the log These messages indicate that there is a problem connecting to the IBM Cognos 8 Server. This problem can be caused by one of the following: The IBM Cognos 8 server is not running or is still initializing. Ensure that the IBM Cognos 8 Server is started properly, and test it by accessing IBM Cognos Connection through a Web browser. The portal server does not have network access to IBM Cognos 8 server. To test connectivity to the IBM Cognos 8 server, use the portal server computer to ping the IBM Cognos 8 server. Use the server name and address that appear in the error message. If the ping is successful, ensure that there is no firewall blocking the port used by Portal Services, which is 9300 by default. The URL for connecting to IBM Cognos 8 is incorrect. For IBM Websphere, locate and modify the CPS Endpoint parameter in each portlet application as required. For SAP EP, locate and modify the _cpsserver: CPS Connection Server field in each iView as required. Java Virtual Machine conflicts exist on the IBM Cognos 8 server. IBM Cognos 8 includes a version of Java Runtime Environment (JRE). Ensure that no other version of the Java Virtual Machine or Java SDK are installed. For information about configuring IBM Cognos 8 to work with Portal Services, see the IBM Cognos 8 Installation and Configuration Guide.

Unable to Edit Object Properties in ALUI 6.1 and 6.5 Portal

When you import the Portal Services package into a BEA Aqualogic 6.1 and 6.5 (ALUI 6.1 and 6.5) portal and try to edit the properties of IBM Cognos objects, such as the remote server, or the portlets, an error may occur that indicates that certain property values are missing. As a result, you cannot apply your property changes. The missing values refer to global ALUI properties, such as URL, and can be used in searches for objects or documents. Because the global properties are not used by Portal Services, the portlet package file CognosBEAAquaLogicPortletPackage.pte for version 6.5 and CognosBEAAquaLogic61PortletPackage.pte for version 6.1 do not include default values for them. If the Global Object Properties Map in the ALUI portal has a property assigned to a certain type of object, such as the remote server type, when you try to edit this type of IBM Cognos object, you are prompted to specify a value for this property. To solve this problem, you can perform one of the following tasks: 596

Chapter 37: Report and Server Administration Problems Remove the problematic property from the ALUI 6.1 or 6.5 Global Object Properties Map. Please note that changing the global property settings for one object may affect other objects. Specify any value, for example a space, for the problematic property. The property is not used by Cognos portlets so the value is irrelevant.

Steps to Edit the Global Object Properties Map

1. In an ALUI portal, click Administration. 2. In the Select Utility drop-down list, click Global Object Property Map. 3. For the object you want to edit, click the edit icon. 4. Clear the check box next to the property you want to remove. 5. Click OK.

Steps to Specify a Value for a Global Property

1. In an ALUI portal, click Administration. 2. Locate the IBM Cognos object whose properties you want to edit. 3. Click the object. 4. Under Edit Standard Settings, click Properties and Names. 5. Type any value for the property. 6. Click Finish.
477906

Only the Administrator Can See Cognos Portlets

When using Portal Services with a WebSphere portal, you may find that only the administrator can see the Cognos portlets. This problem can be caused by portlet access rights that are improperly set. To fix this problem, log on to the portal as an administrator and grant your users Edit or View rights for each portlet as required.

Locale Mismatch in Cognos Navigator Portlet

If you use the Cognos Navigator portlet to view a report, the language used in the report may not match the language used in the browser. This problem can occur if the locale selected for the portal is different than the default locale of the browser. To fix this problem, set the locale selection for the portal to nothing selected. If no locale is selected, the portal uses the default locale for the browser.

Administration and Security Guide 597

Chapter 37: Report and Server Administration Problems

Properties Pages in Cognos Portlets Are not Displayed Properly

In portals other than Cognos Connection, the properties pages in Cognos portlets may not be displayed properly. The properties are pushed to the left side and there is no indentation. To avoid this problem, add the IBM Cognos 8 server domain and the portal domain to the list of trusted sites in the browser.

Steps for Internet Explorer

1. From the Tools menu, click Internet Options. 2. On the Security tab, add the domain name to the Trusted sites Web content zone.
592142, 592142

Problems Displaying HTML Reports in a Multi-tab Dashboard

If your reports contain HTML items with unsupported Java Script, the reports may not be displayed in a multi-tab dashboard. Instead, the following error may appear: "The report cannot be displayed because it contains unsupported javascript code. Please use the Safe Mode Viewer portlet or contact your system administrator." To avoid this problem, use the Safe Mode Viewer portlet to display the reports that you want to add to the dashboard. The Safe Mode Viewer portlet is the version of the Cognos Viewer portlet shipped with IBM Cognos 8.3. Note: The Safe Mode Viewer portlet has some limitations. For example, it is slower and does not support all communication options available in the IBM Cognos 8.4 portlets.

Steps to Import Safe Mode Viewer

1. In IBM Cognos Administration, on the Configuration tab, click Portlets. 2. Click the import portlets button .

The Specify a producer page appears. 3. Click the Web Services for Remote Portlets (WSRP) interfaces option. 4. In the Markup, Service description, Registration, and Portlet Management boxes, type interface://wsrp/cps4/portlets/nav 5. Click Next. 6. In the import portlets wizard, type a name for the portlet group that will contain Safe Mode Viewer. 7. Make sure Cognos Viewer is selected. If you want, you can also select Cognos Navigator and Cognos Search. 8. Click Finish.
603172

598

Chapter 37: Report and Server Administration Problems

Unable to Identify SAP BW Version and Corrections

You must use supported versions and patch levels of SAP BW, so you must be able to see a list of patches (correction notes) that have been applied. For more information about supported versions, see the IBM Cognos Resource Center Web site (http://www.ibm.com/software/data/support/cognos_ crc.html). To see a list of correction notes that have been applied, you can run one of two transactions in R/3: SE95, or SNOTE. In all cases, you must be authorized to run these transactions. In some cases, you may need to run the transactions using the same account that was used to apply the correction notes.

Steps
1. In SAP R/3, type /SE95 in the command window. 2. Enter an asterisk (*) in the Last Changed By field, to view all notes. 3. Select the type of modification in the Modifications tab.

SBW-ERR-0020 Error When Running Reports Based on SAP BW Data Sources

Occasionally, when you run reports based on an SAP BWdata source, the following error message may appear: "Querying the SAP BW cube's failed. SAP error code: BAP-ERR-0002 A BAPI error has occurred in the function module BAPI_MDDATASET_GET_AXIS_DATA. &INCLUDE INCL_INSTALLATION_ERROR" This message means that SAP BWhas run out of resources. In this situation, we recommend contacting your system administrator.
561043

Links to Referenced Content Objects are Broken Following Deployment

After you import a deployment archive to a new location, some links for objects associated with reports do not work. When you import content objects which contain references to other objects that are not in the target environment, these references are removed. For example, if you deploy an archive containing reports based on a metadata package that is not in the deployment archive or the target environment, then the links will remain broken even if the referenced object is subsequently created. To solve this problem, do one of the following: Reimport your deployment package after the target objects have been created. The objects will be automatically linked Manually reconnect the links to an object. For more information about manually resetting links, see the topic about selecting links for entry in the Administration and Security Guide.

Administration and Security Guide 599

Chapter 37: Report and Server Administration Problems

Table or View Does not Exist for Sample Database

The schema property in each of the Framework Manager models is synchronized to run against the schemas defined in the sample databases. If you change any of the database schemas, you receive an error connected to the Framework Manager model that says the table or view does not exist. To solve the problem, open the model in Framework Manager and update the schema name and then re-publish all packages.
589069

600

Chapter 38: Problems When Using Framework Manager

You may encounter problems when working in Framework Manager.

Measures Not Added After Initial Import in an Upgraded Model

After upgrading an IBM Cognos ReportNet 1.x model to IBM Cognos 8, measures that were added to the key figures folder for the underlying SAP BW object after the initial import will not be added when a synchronization is performed. The solution is to re-import the object. Note: This issue does not affect new models created in IBM Cognos 8.

Unable to View the Result Set of a Stored Procedure

If the result set of a stored procedure contains a CLOB (character large object) or BLOB (binary large object), you must modify the stored procedure before running it.

Steps to Use CLOBS

1. Create a model query subject that references the stored procedure. 2. Insert a Cast or Substring function to calculate a string based on the CLOB.

Steps to Use BLOBS

1. Create a model query subject that references the stored procedure. 2. Remove the BLOB from the Select statement of the query subject. 3. Add query items to the Select statement that perform a lookup on the table that contains the BLOB data.

Unable to Compare Two CLOBs in Oracle

If you are using Oracle and ask IBM Cognos 8 to compare two CLOBs, such as where C2 = C3, you will see an Oracle runtime error. To avoid this problem, use the DBMS_LOB.compare method:
where 0 = dmbs_lob.compare (c1, c2)

Administration and Security Guide 601

Chapter 38: Problems When Using Framework Manager

An Out of Memory Error with ERWin Imported Metadata

When you test query subjects based on a View table, an Out of Memory error may occur while performing the sqlPrepareWithOptions operation. The solution is to create a data source query subject using the same Content Manager connection as the ERWin model.

Calculation Fails Testing

You import a user-defined function, such as CHAR, that uses the same name as a vendor-specific function, such as char in Microsoft SQL Server. You insert the user-defined function in a calculation and test it in the Calculation Definition dialog box. The test fails. The solution is not to use the same name as a vendor-specific function when creating a user-defined function. For information about function names used in your database, see the database product documentation.

Framework Manager Cannot Access the Gateway URI

You create a new project in Framework Manager and the following message appears: Unable to access service at URL: http://hostname:80/cognos8/cgi-bin/cognos.cgi/ b_acton=xts.run&m=portal/close.xts Please check that your gateway URI information is configured correctly and that the service is available. For further information please contact your service administrator. This message appears if the gateway is not properly configured. The gateway URI must be set to the computer name where IBM Cognos 8 is installed and reflect the type of gateway you are using. You must log on as an administrator to configure the gateway URI.

Steps to Configure the Gateway URI

1. Close Framework Manager. 2. In IBM Cognos Configuration, in the Explorer window, click Environment. 3. In the Properties window, in the Gateway URI box, type the appropriate value: To use ISAPI, replace cognos.cgi with cognosisapi.dll. To use apache_mod, replace cognos.cgi with mod_cognos.dll. To use a servlet gateway, type the following: http[s]://host:port/context_name/servlet/Gateway Note:context_name is the name you assigned to the ServletGateway Web application when you deployed the ServletGateway WAR file.

602

Chapter 38: Problems When Using Framework Manager If you are not using a Web server, to use the dispatcher as the gateway, type the following: http[s]://host:port/p2pd/servlet/dispatch 4. If required, change the host name portion of the Gateway URI from localhost to either the IP address of the computer or the computer name. 5. From the File menu, click Save. 6. From the Actions menu, click Restart.

Object Names Appear in the Wrong Language

When you import multiple languages from an SAP BW Query to a Framework Manager model, not all the object names retrieved from SAP BW appear in the correct language. To avoid this problem, save the SAP BW Query again in each of the logon languages in Business Explorer Query Designer. The correct language texts will then show correctly in Framework Manager.

Full Outer Joins in Oracle Return Incorrect Results

When using an Oracle data source prior to version 10.2, full outer joins return incorrect data results. To avoid this problem, IBM Cognos 8 processes these as local operations. As a result of this processing, you must set the query processing to limitedLocal for any projects that expect explicit or implicit outer joins.

Error When Testing Query Subjects in a Model Imported from Teradata

You are using a model imported from Teradata. When you test some query subjects that contain graphic items, you see this error: QE-DEF-0177 An error occurred while performing operation 'sqlOpenResult' status='-28'. UDA-SQL-0114 The cursor supplied to the operation "sqlOpenResult" is inactive. UDA-SQL-0107 A general exception has occurred during the operation "SgiCursor::doOpenResult ()". [NCR][ODBC Teradata Driver][Teradata RDBMS] An unknown character string translation was requested. The reason is that the GRAPHIC and VARGRAPHIC data types are not supported.

Error for Type-In SQL Query Subject

You define the following in DB2:
create type address as ( number character (6),

Administration and Security Guide 603

Chapter 38: Problems When Using Framework Manager

street varchar(35), city varchar(35) ) MODE DB2SQL; create table emp ( emp_no int, emp_address address); Select e.emp_no, e.emp_address..street from emp e SQL0206N "aBmtQuerySubject.2

When you define a type-in SQL query subject, an error appears because of the name assigned for the attribute reference in the structured type. To resolve this problem, you have two options: assign a simple correlation name to the column in the original query subject, such as Select
e.emp_no, e.emp_address..street as "ABC" from emp e

use pass-through notation for the query subject by surrounding the column with double curly brackets ({{ }})

Function Name Not Recognized

IBM Cognos 8 does not validate the syntax you enter in expressions. The expression parser does not check the number or types of arguments for any function you use. This is because the database may accept different syntax or may have a function with the same name as IBM Cognos 8 but a different signature. If an expression will not run, review the Tips box in the expression editor for more information about the specific function you are using. The Tips box gives detailed information about each function.

QE-DEF-0259 Error
This error occurs if you use braces { } in the wrong position in an expression. IBM Cognos 8 expects anything between the braces { } to be at the same level as a function. If you have used braces elsewhere in an expression, you will see the following error message: QE-DEF-0259 There was a parsing error You can also use braces to send unique syntax to the data source. For example, your database uses a keyword for a function but this keyword is not used in IBM Cognos 8. IBM Cognos 8 does not validate the syntax you enter between braces. The syntax is simply sent to the data source. The solution is to make sure that braces are not used in the wrong positions. For example, you type the following in an expression:
[ss_ole_both].[authors_lith].[au_id] = [ss_ole_both].[authors_latin].[au_id] { collate Lithuanian_CI_AI}

You see the following error message: QE-DEF-0259 There was a parsing error before or near position: 75, text starting at position: 5 "le_both].[authors_lith].[au_id]=[ss_ole_both].[authors_latin].[au_id]{" Meanwhile the following expression is valid: 604

Chapter 38: Problems When Using Framework Manager

{ Q3.au_id } } = { Q4.au_id collate lithuanian_CI_AI

QE-DEF-0260 Parsing Error

This error occurs if you pick a list of Query Studio filters that is too large or when the size of the string values for the keys is large. One solution is to use predefined filters from Framework Manager instead of using the Query Studio interface. Also, we recommend that you pick columns and filter where the distinct list of values is relatively small.

Externalized Key Figures Dimension Retains Old Prompt Value

You have a key figures dimension (SAP BW) that contains an optional prompt. If you externalize this dimension as a csv or tab file, the externalized file does not contain all the rows of data. This is because the prompt value is retained. For example, you set the prompt value for the dimension when testing the dimension in Framework Manager. The prompt value is kept in the cache. Even if you clear the value of the prompt in the Prompt dialog box, externalizing the key figures dimension results in a file containing data that is filtered by the most recently used prompt. To avoid this problem, do one of the following: Do not test the key figures dimension before you externalize it. Close the model, open it again, and externalize the key figures dimension.

Older IBM Cognos 8 Models Display Level Object Security

If you are using a previously-created IBM Cognos 8 model, object security on a level may have been defined. Object security on a level is not supported. The solution is to verify and repair the older model before publishing it.

Steps
1. From the Project menu, click Verify Model. 2. Select the security view that references a level and click Repair.

Exporting a Framework Manager Model to a CWM File Fails With Error MILOG.TXT was not found
Exporting a Framework model to a CWM file fails with error MILOG.TXT was not found when the path contains Japanese characters. Do one of the following to solve this problem: Specify an export path that does not use Japanese characters.

Administration and Security Guide 605

Chapter 38: Problems When Using Framework Manager Change the system default language on your computer to Japanese. You can set the system default language in the Control Panel, under Regional and Language Options -> Advanced. For more information on how to do this, refer to the Windows operating system help.

Difference in SQL for Inner Joins After Upgrading to IBM Cognos 8.3
If you migrated from IBM Cognos 8.1 to IBM Cognos 8.2 or 8.3, there can be differences in the generation of SQL used for the INNER JOIN syntax. You can control the SQL syntax used for inner joins by selecting the Server determined setting for the SQL Join Syntax governor. The SQL generated in IBM Cognos 8.1, IBM Cognos 8.2, and IBM Cognos 8.3 produces the same results. If you are using RDBMS materialization technology which can be implemented using either implicit or explicit syntax, you must ensure that you select the same syntax setting for the SQL Join Syntax governor in your model.

Publishing a Large Package Results in a CCLOutOfMemory Error

When you try to publish a large package, you see this error message: CCLOutOfMemory To resolve this problem, reduce the size of your package by removing namespaces. You could also create a series of smaller packages that each target specific business goals. Note: Publishing very large packages may negatively affect the future performance and maintainability of your models.

Full Outer Joins Not Sent to Oracle 9i and 10GR1

By default, IBM Cognos 8 will not send full outer joins to ORACLE 9i and 10GR1 due to Oracle bug #2874433. This requires using limited local processing in IBM Cognos 8. To enable full outer joins with Oracle, you must ensure that you have the required patch sets, which include the fix for Bug#2874433 modify the cogdmor.ini file to turn on full outer joins (Full_outer_join=T)

Because any manual edits to the ini settings are overwritten by the next installation, you must manually replicate them on all machines where you installed Cognos 8 or Framework Manager.
nbna

Review Governors When Upgrading Models

If you have a segmented or linked model that was created with a previous version of Framework Manager, you must review the governor settings for each child and parent model before and after

606

Chapter 38: Problems When Using Framework Manager upgrade. The governor settings for the top-level parent model are the settings that are applied when publishing. If you run a script that was created in a previous version of Framework Manager, the script bypasses the upgrade process. Review the governor settings before and after running the script to ensure that the settings are what you want.
579031, 580784

File Creation from Framework Manager fails with Error QEDEF-0178

File creation from Framework Manager may fail if a file name or path name contains GB18030 characters. For example, this may occur when externalizing query subjects as Framework Manager uses the name of the query subject as the file name. It may also occur when exporting a translation file. We recommend that you do not use multibyte characters, such as those seen in GB18030, in file or path names. 599875

Administration and Security Guide 607

Chapter 38: Problems When Using Framework Manager

608

Chapter 39: Problems When Using Transformer

This document describes issues and limitations that may be encountered by IBM Cognos Transformer users, with suggested workarounds. The information is organized into the following sections: "Known Issues When Modeling in IBM Cognos Transformer" (p. 609) "Known Issues Using Cubes in the IBM Cognos 8 Studios" (p. 613)

Known Issues When Modeling in IBM Cognos Transformer

Documented in this section are known issues and limitations when modeling in IBM Cognos Transformer.

BAPI Error Occurs After the Prompt Specification File Edited Manually
In Transformer, you create a prompt specification for a SAP-based package. You edit the prompt specification file, prompt.xml, manually and save your changes. After editing the file, you attempt to generate a PowerCube using the command line options, for example,
cogtr -fpromptspecfilename -n cubename.mdl

but the PowerCube is not generated and you receive a BAPI error. The error is caused by an invalid member unique name (MUN). Because editing the prompt.xml file manually is error prone, we recommend that you do not edit the prompt.xml file manually but create an alternate prompt specification instead.
582131

Unable to Access an IQD Data Source using a Sybase Database Connection

In Framework Manager, you use an IQD file to externalize a model using a Sybase database connection. When you attempt to import the data source file into Transformer, you receive the following error message: [TR1907] Transformer cannot gain access to database database_name with signon information <user ID, password>. The database connection fails because quotes are added to the SQL query when the data source is created in Framework Manager. To successfully connect to the IQD data source and import the model, you must first edit certain configuration files in the CS7Gateways\bin directory.

Steps
1. Open the cs7g.ini file and ensure the database type in the connection string is CT, not CT15. Cs7g.ini is located in the <installation_location>\cognos\c8\CS7Gateways\bin directory.

Administration and Security Guide 609

Chapter 39: Problems When Using Transformer 2. In the [Services] section, include the following:
CTDBA=ctdba, ctdba15

3. Save your changes. 4. Open the cogdmct.ini file and in the [UDA USER OPTIONS] section, specify the following:
Attach=SET QUOTED_IDENTIFIER ON

Cogdmct.ini is located in the <installation_location>\cognos\c8\CS7Gateways\bin directory. 5. Save your changes. 6. Open Transformer and import the data source.
588853

Importing Time Dimensions from IBM Cognos 8 Packages Not Supported

When you create a query in Transformer based on a Framework Manager package that contains hierarchical time-related categories, Transformer interprets the time-related categories as a regular dimension and not as a time dimension. As a result, the time dimension in your PowerCube will not contain any relative time categories. Ensure that you import all of the data needed to define your time dimension, and use Transformer to create the date levels and categories.

Data in Multiple Languages Does Not Display Properly

When you create a data source using an IBM Cognos 8 report, and the report includes data in multiple languages, some of the language characters do not display properly in the Transformer Data Source Viewer. These characters are displayed as -- . Transformer does not support reports with multilingual data as a data source. When the operating system locale is properly set, Transformer displays the characters for that locale. There is no workaround for this problem.

Unable to Use an IQD Created in Framework Manager That Contains an Oracle Stored Procedure
In Transformer, when trying to open an IQD created in Framework Manager that contains an Oracle stored procedure, you may receive a message similar to the following: (TR0118) Transformer can't read the database [datasource] defined in <Lan location>\ <datasource><iqd_name>.iqd. DMS-E_General A general exception has occurred during operation 'execute' The native SQL generated in an IQD created in Framework Manager is wrong. The IQD cannot be used in Transformer. To resolve this problem, execute the stored procedure in Framework Manager and set the Externalize Method to IQD. Create a model query subject from the executed stored procedure, then publish the package and open it in Transformer.

610

Chapter 39: Problems When Using Transformer

Preventing Errors When Model Calculations Use Double Quotation Marks

If you try to open an .mdl-format model containing calculations that include double quotation marks, as might be used to create concatenated categories, you may get an error, even if you followed the recommended practice of wrapping these calculations in single quotation marks. This is because .mdl-format models do not support the use of single and double quotation marks together, if the ObjectIDOutput flag is set to True, which is the default model creation setting. To avoid this problem, you have two choices: You can open the cogtr.xml.sample file in a text editor, search for the string ObjectIDOutput, and change the setting to 0. Save the cogtr.xml.sample file as cogtr.xml. Restart Transformer, and resave the model. You can use your RDBMS or a tool such as Framework Manager to perform the required calculations, and then import the data into your model.

Whichever strategy you choose, you can then open the .mdl or py?-format model without error.
537305

Framework Manager and Transformer may Display Different Locale Session Parameters for Some Languages
Transformer version 8.x may not return data in the expected locale during test or cube build when the following conditions are encountered: The locale shown in the File/Session information in Transformer is not included in the Framework Manager parameter map for session parameters. The modeler attempts to create a data source in Transformer using a query subject from the package where the locale does not exist.

When this is encountered, the locale of the modelers session parameter does not exist in the Framework Manager parameter map. As a result, the data returned will not be the locale of the Session information shown in Transformer. To avoid this problem, add the locale string that is displayed in the Transformer File/Session information to the Framework Manager parameter list so that Transformer can retrieve the expected data when accessing the data source. However, the model metadata will still be shown in English, or in the Framework Manager design language.

Regular Columns cannot be Converted to Calculated Columns and Vice Versa

When you attempt to convert a regular column to a calculated column by opening the Column property sheet, the Calculated button is unavailable. In Transformer version 8.x, you can no longer convert an existing regular column to a calculated column by changing the column properties. Similarly, existing calculated columns cannot be converted into regular columns by changing the column properties. In Transformer version 8.x, you can only create calculated columns using the Insert Column feature. For more information, see "Define a Calculated Column" in the Transformer User Guide.

Administration and Security Guide 611

Chapter 39: Problems When Using Transformer This change in functionality does not affect how calculated columns are imported from an IBM Cognos Series 7 model into Transformer version 8.x. Existing calculated columns originally created in IBM Cognos Series 7 will be imported correctly.

Transformer Takes a Long Time to Retrieve Data from an SAP-based Data Source
You are attempting to retrieve data from an SAP-based data source in Transformer with null suppression turned off. The retrieval takes a long time to complete. Ensure that the machine where Transformer is installed has sufficient memory to perform the import. If physical memory is limited, Transformer may perform the operation very slowly. In this situation, you can end the task using Task Manager.
589874

Categories Missing When Creating a Transformer Model Based on an SAP Query Containing a Manually Created SAP Structure
The stream extract interface that reads the fact data doesn't handle certain features of the SAP queries. A manually created structure in the query will look like a dimension when Transformer completes the import from the Framework Manager package, but incomplete data is returned. A dimension added to the SAP query as a characteristic will look like a dimension but no data is returned. If you must use a BEx query with these limitations, consider turning off the stream extract and rely on an MDX query. Note that if the MDX query is large, it may fail.
591834

Error Occurs When Creating a PowerCube Containing an SAP Unbalanced Hierarchy

You import an SAP package into Transformer that contains an unbalanced, ragged hierarchy and you receive a TR2317 error when you create a PowerCube. To avoid this error, before generating categories for the dimension, do the following steps.

Steps
1. In the Dimension Map, right-click the lowest level in the ragged unbalanced hierarchy that is marked unique. 2. Click Properties and on the Source tab, click Move. 3. From the Run menu, click Generate Categories. 4. From the Run menu, click Create PowerCubes.
589899

Rebuilding a PowerCube Soon After Publishing Produces a TR0787 Error

After publishing a PowerCube using the Publish wizard in Transformer, the PowerCube file is locked for a few minutes by the IBM Cognos 8 server. If you attempt to rebuild the cube during 612

Chapter 39: Problems When Using Transformer this time, the cube build may fail, with Transformer error TR0787 indicating that the cube is being used by another application. To avoid this situation, do one of the following: Do not use the Publish wizard to publish the cube. Wait for the file lock to be released, and then rebuild the cube. Build the cube in a location that is different from the location where the cube is published.

596414

Known Issues Using Cubes in the IBM Cognos 8 Studios

Transformer version 8.x enables PowerCubes and their data sources to be published directly into the IBM Cognos 8 environment, without requiring Framework Manager as an intermediary. Documented in this section are known issues and limitations when viewing PowerCubes created for the IBM Cognos 8 Web Studios, such as Analysis Studio and Report Studio.

Not Yet Optimized IBM Cognos PowerCubes May Open Slowly in IBM Cognos 8
If PowerCubes created with previous versions of Transformer take too long to open in the IBM Cognos 8 Web studios, we recommend that you run a command line utility named pcoptimizer, supplied with IBM Cognos 8, to improve run-time performance. This optimization utility is suitable for older PowerCubes when the model no longer exists or the data used to build the PowerCube is no longer available. It is not necessary to run this command line utility for cubes created in Transformer version 8.x.

Steps
1. Back up your target PowerCube, then navigate to the Cognos_8_installation_location/bin directory. 2. On Windows, open a command line window and run PCOptimizer.exe. 3. On UNIX/Linux, enter the following line to run the optimization command line utility:
pcoptimizer [-t] [-v] [-h]cubename

where cubename is the fully qualified PowerCube or time-based partitioned control cube name with the .mdc extension, if the PowerCube resides in the same location as pcoptimizer. Otherwise, cubename is the full path with the .mdc extension. Note: This method only supports metadata extraction. To set up user-configurable drill-through, you must use Transformer. Wildcard character support is not currently available. You must therefore invoke the utility once per PowerCube. If cubename is not provided, the program enters an interactive mode, prompting you for a PowerCube name and accepting keyboard input. The optional parameters are as follows:
-t or test mode; it tests whether the metadata was extracted and loaded into the PowerCube.

The return code indicates the status. 0 if the metadata was extracted and loaded Administration and Security Guide 613

Chapter 39: Problems When Using Transformer 10 if the metadata was not loaded 20 if an error occurred while accessing the PowerCube

-v or verbose mode; text is output to standard output (stdout), indicating what was done,

including any error messages. If running in interactive mode, -v is assumed. All text is output in English only.
-h for command-line help; if cubename is not provided, it prints the usage and options to

the screen.

Analysis Studio Shows the Wrong Currency Symbol

When published to IBM Cognos 8 Analysis Studio, PowerCubes show a default currency rather than the currency associated with the locale of your servers and PCs. For example, GBP () is shown as $. To resolve this problem, you can do one of the following: Create a currency table when you prepare your model in Transformer and embed a default currency symbol into the resulting PowerCubes, based on the system locale used by your Transformer computer. For PowerCubes that do not contain an embedded currency table, set the fallbackCurrency parameter as the default currency.

Steps to Create a Currency Table in Transformer

1. In Transformer, from the File menu, click Currency Table and click OK. 2. Right-click each currency measure and click Allow currency conversion. This default currency table does not include currency information for any locales other than your running locale. Also, you cannot convert to a different currency while working in Analysis Studio.

Step to Set fallbackCurrency as the Default Currency

Define a default currency by setting the fallbackCurrency parameter in the installation_location\configuration\qfs_config.xml file to GBP (Great Britain Pounds) or to an alternative currency code as listed in the installation_location\bin\ccli18nrescr_xx.xml file. Here is an example.
<!-- execution layer providers--> <provider name="PowerCubeODP" libraryName="pcodp" connectionCode="PC"> ... <providerDetails> <parameters> <!-- Max depth of nested calculated members within a query. -->

614

Chapter 39: Problems When Using Transformer

<parameter name="maxCalculatedMemberNestingDepth" value="30"/> <!-- Normalize yen/won currency symbols - set to "false" to disable --> <parameter name="normalizeYenWon" value="true"/> <!-- Fallback currency for cubes with no default currency specified - set to USD, EUR etc. --> <parameter name="fallbackCurrency" value="USD"/> </parameters> </providerDetails> </provider>

Changes to Decimals in Currency Formats

When you open a PowerCube in an IBM Cognos 8 Web studio or in IBM Cognos 8 Business Intelligence Mobile Analysis version 8.3, you may notice changes in the number of default decimal places shown in currency formats. This behavior is due to the following changes: The default decimal formatting in currency formats is now determined by the measure format selected in the cube, instead of from the data source currency table definition. For example, if the Actual Revenue measure format specifies two decimal places and the USD currency in the currency table specifies no decimal places, two decimal places will appear in the USD currency value. Calculations that include a division operator and at least one currency operand will now show a resulting value with three decimal places only when neither of the currency values includes decimals two currency operands have different numbers of decimal places

In all other calculations of this type, the number of decimals in the resulting value is determined by the number of decimals in the currency value. The following examples illustrate this new behavior: $4.00 / $2.00 = $2.00 $4 / $3.0000 = $1.3333 $4 / $3 = $1.333 $4.0 / $3.00 = $1.333

Ragged or Unbalanced Hierarchies Result in Unexpected Behavior

In ragged or unbalanced hierarchies, some members that are not at the lowest level of the hierarchy may have no descendants at one or more lower levels. Support for these hierarchy gaps in relational sources is limited. For OLAP sources, more complete support is provided, but some reports may result in unexpected behavior:

Administration and Security Guide 615

Chapter 39: Problems When Using Transformer Groups corresponding to missing members may appear or disappear when grouped list reports are pivoted to a crosstab. This happens with set expressions using the filter function, and detail filters on members. Ragged and unbalanced sections of the hierarchy are suppressed when set expressions in that hierarchy are used on an edge. When a crosstab is sectioned or is split into a master-detail report, sections corresponding to missing members become empty.

Some of these behaviors may be corrected in a future release, while others may be codified as supported behavior. To prevent these behaviors, avoid the scenarios above. The following scenarios are believed to be safe: one or more nested level references on an edge, with no modifying expression. a hierarchy reference on only one level of one edge. one or more explicit members or sets of explicit members as siblings on only one level of one edge. summaries of the previous three scenarios.

In all cases, reports based on ragged and unbalanced hierarchies should be tested to confirm that hierarchy gaps are handled correctly.

Error Opening Saved Reports After PowerCube Refresh

After a PowerCube is refreshed, when you open reports that include drill down on directly referenced special time categories, you may receive the following error: OP-ERR-0025 The following OLAPPlanner internal error occurred: internal error When drill down is not used, you will not receive the error; however, the data shown may not be correct. There is no workaround for this problem.

Unable to Open Sample Model, Great Outdoors Sales.mdl, and Generate Cubes
If your setup information for the Great Outdoors Sales.mdl is incorrect, you will be unable to open the sample model for Transformer, Great Outdoors Sales.mdl, or generate cubes. To avoid this problem set up the Great Outdoors Sales.mdl as follows: 1. Modify the Cs7g.ini to contain [Databases] connections. The Cs7g.ini file is located in the installation_location/c8/cs7Gateways/bin directory. 2. Open ODBC Data Source Administrator and create a new ODBC data source named great_ outdoors_warehouse to connect to the SQL server database, GOSALESDW, which is provided with the sample installation. 3. Connect using a valid User Id and password for SQL Server authentication. 4. Open the model. 616

Chapter 39: Problems When Using Transformer

Data Records that Support External Rollup Measure Data are Not Always Created
When PowerCubes are built, data records that support External Rollup Measure data are not created in certain circumstances. To receive a software update, access the IBM Cognos Resource Center (http://www.ibm.com/ software/data/support/cognos_crc.html). After you apply the update, you can rebuild the PowerCube with the expected results.
579654

Administration and Security Guide 617

Chapter 39: Problems When Using Transformer

618

Chapter 40: Problems Authoring Reports

Report Studio can be used to create different types of reports, including lists, crosstab reports, charts, and user-designed reports. You may encounter problems when authoring reports in Report Studio or Query Studio. For information about using Report Studio, see the Report Studio Professional Authoring User Guide. For information about using Query Studio, see the Query Studio User Guide.

Problems Creating Reports

Planned, professional reports are created in Report Studio, and ad hoc reports are created in Query Studio. The topics in this section document problems you may encounter when creating reports.

Chart Labels Overwrite One Another

In Report Studio and Query Studio, if you define a chart and render it in HTML or PDF format using the default sizes, the axis labels of the chart may overwrite each other. To avoid this problem, make the chart wider or taller by modifying the height and width properties of the chart or enable the Allow Skip property.

Chart Shows Only Every Second Label

You create a report that includes a chart. The Allow Skip option is set to false, but when you run the report, labels are skipped. This can occur if there is not enough room for all labels and the options Allow 45 Degree Rotation, Allow 90 Degree Rotation, and Allow Stagger are also set to false. IBM Cognos 8 has no options for making the labels fit, so it skips every second label. The solution is to select either Allow 45 Degree Rotation, Allow 90 Degree Rotation, or Allow Stagger.
444936

Chart Gradient Backgrounds Appear Gray

In Report Studio, you can define a custom palette for a chart that includes a gradient. When the chart is rendered in HTML format, the chart background appears gray. This is a Microsoft Web browser issue. To avoid this problem, select the chart and define the color white as the chart background. For more information, see the Microsoft Knowledge Base article at http://support.microsoft.com/ kb/294714.

Administration and Security Guide 619

Chapter 40: Problems Authoring Reports

Division by Zero Operation Appears Differently in Lists and Crosstabs

If you have a list that accesses a relational data source, a calculation containing a division by zero operation appears as a null value, such as an empty cell. In a crosstab, the division by zero operation appears as /0. This happens when the Avoid Division by Zero property is set to Yes, which is the default. To have a consistent display of null values in lists and crosstabs, define an if-then-else statement in the expression in the crosstab cell that changes the value /0 to the value null.

Application Error Appears When Upgrading a Report

When upgrading a report, the following error appears if the report contains data items in the page layout that are not in a data container: RSV-SRV-0040 An application error has occurred. Please contact your Administrator. This error occurs when IBM Cognos 8 cannot determine the query reference for a data item. Such data items are identified by a small red circle with a white x icon that appears in the lower left corner. To correct the error, drag the data items into a container. If the container is a list, we recommend that you drag the data items into the list page header or footer, or the overall header or footer. If you want to see the first row of the item on each page or in the overall report, drag the item to the list page header or overall header. If you want to see the items last row on each page or in the overall report, drag the item to the list page footer or overall footer. Tip: If a header or footer does not exist, create it.

Nested List Report Containing a Data Item That is Grouped More Than Once Does Not Run After Upgrade
When you upgrade a nested list report that contains a data item that is grouped in both lists, the report does not run and an error such as the following appears: OP-ERR-0199: The query is not supported. The dimensions on the edge are inconsistent. The dataItems from dimension="[Product line]" must be adjacent. This error occurs when the report is run against a dimensional data source and both lists are using the same query. This error does not occur if the report is run against a relational data source. For example, you have a list that contains the grouped items Product line and Product type and a nested list that contains the data items Year, Quarter, and Unit sale price. Year, Quarter, and Product line are grouped items in the nested list. To resolve the issue, delete the data item that is grouped in both lists from the inner list.

Steps to Delete a Grouped Data Item From an Inner List

1. Click anywhere in the report. 2. In the Properties pane, click the select ancestor button and click the List link that represents the inner list. 3. Double-click the Grouping & Sorting property.

620

Chapter 40: Problems Authoring Reports 4. In the Groups pane, select the data item that you want and click the delete button.

Background Color in Template Does not Appear

When creating a Query Studio template in Report Studio, if you add a list object and change its background color, the color change does not appear when you apply the template to a Query Studio report. To work around this issue, do one of the following: Edit the style sheet (CSS) classes for lists in Report Studio. Do not add any objects to the page body when you are creating a Query Studio template. Leave the page body blank.

Subtotals in Grouped Lists

When using a PowerCube that contains a ragged hierarchy, if you group on the first level in the hierarchy, subtotals may appear in the wrong place or show wrong values. To resolve the issue, group on the second level.

Metadata Change in Essbase Not Reflected in Reports and in the Studios

When there is a metadata change on the Essbase server, the change is not immediately reflected in the metadata tree in the studios. In addition, when a report is run, the report does not pick up the republished changes. To view the new structure, you must restart the Content Manager server.
545114

Relationships Not Maintained in a Report With Overlapping Set Levels

In a report, the relationship between nested or parallel sets at overlapping levels in the same dimension may not always be maintained. For example, a named set in the data source that contains members from both a Year and Month member is nested under Year, but is not properly grouped by year. In another example, an error message such as this appears: "OP-ERR-0201 Values cannot be computed correctly in the presence of multiple hierarchies ([Product].[B1], [Product].[Product]) that each have a level based on the same attribute (Product)." This problem occurs in the following scenarios involving non-measure data items X and Y, that overlap in the same dimension: X and Y together as ungrouped report details Y nested under X Y appended as an attribute of a group based on X

Administration and Security Guide 621

Chapter 40: Problems Authoring Reports When using named sets, or sets that cover more than one level of a hierarchy, do not use sets from the same dimension in more than one place in the same report. They should appear on only one level of one edge.
567492

Creating Sections on Reports That Access SAP BW Data Sources

SAP BW data sources may have problems with sections in reports under different circumstances: If a section in a report uses the lowest-level query item in a ragged hierarchy, such as the children of the "not assigned" node, the following BAPI error may appear: BAPI error occurred in function module BAPI_MDDATASET_SELECT_DATA. Value <valueName> for characteristic <cubeName> unknown For more information about working with ragged or unbalanced hierarchies, see the Report Studio Professional Authoring User Guide. If you create a section in a report using conformed multicubes with SAP variables, an SAP error message may appear.

Lowest-level Query Item in a Ragged Hierarchy

The solution is to remove the section from the lowest-level query item.
443696

Several Multicubes with SAP Variables

The solution is to use one multicube when creating sections in reports.
437613

Error Characters (--) Appear in Reports

When you run a report, you see two dash (--) characters in your report instead of values. These characters may appear if you use an OLAP data sources other than PowerCube and Microsoft SQL Server 2005 Analysis Services (SSAS), and you apply aggregation to calculations and measures that use rollups other than Sum (Total), Maximum, Minimum, First, Last, and Count. All other types of rollup either fail or return error cells, which typically display as two dash characters (--). This problem occurs in, but is not limited to, the following: footers aggregate function summary filters and detail filters that use a summary detail, summary, and context filters that select more than one member of a hierarchy that is used elsewhere on the report

622

Chapter 40: Problems Authoring Reports If you are working with a SSAS 2005 data source, these characters may also appear in summary cells if you use an OR filter in the summary. To avoid this problem, do not use OR filters in summaries.
595858

Descendants Function Unreliable with Sets

If you create an expression that uses the descendants function with sets, you may encounter unpredictable results. Some expected members may be missing or may have blank captions or labels. This problem occurs if the descendants function uses a set as its first parameter instead of a single member and if the descendants function is nested under another data item from the same hierarchy. To avoid this problem, replace the first parameter in the descendants function with the function
currentmember(H), where H is the hierarchy of the desired set and under which the expression is

nested. For example, use descendants(currentmember(H).

564561

Columns, Rows, or Data Disappear With SSAS 2005 Cubes

Microsoft SQL Server 2005 Analysis Services (SSAS) has a feature called AutoExists that removes tuples that have no facts at the intersection of two hierarchies of the same dimension. Columns, rows, or data can disappear if you set the default member of a hierarchy to a member that does not exist with every other member in the dimension. To avoid this problem, change the default member that caused the disappearance to a member that exists with all other members in the dimension. Columns, rows, or data can also disappear if members are specified that result in one or more nonexistent tuples. There is currently no workaround for this scenario. For more information, see the Microsoft Knowledge Base article at http://support.microsoft.com/kb/944527.
567839, 569506

You may also encounter unexpected results if the default member of a hierarchy is a member that doesn't also exist in all other hierarchies in the dimension, and if you query members from different hierarchies in the same dimension. For example a Report Studio crosstab includes the following (using the Adventure Works cube): Rows: Generate([Adventure_Works].[Account].[Accounts],set([Balance Sheet],[Units])) nested with children([Adventure_Works].[Department].[Departments]->:[YK].[[Department]].[Departments]]. &[1]]]) Column: [Adventure_Works].[Account].[Account Number].[Account Number] Measure: [Adventure_Works].[Measures].[Amount]

You run the report and notice that the query renders with some blanks cells. You then apply the simple detail filter [Amount]>1 and run the report. Only row labels are displayed and all data and columns are missing.

Administration and Security Guide 623

Chapter 40: Problems Authoring Reports In the Adventure Works cube, the [Account].[Accounts] attribute has a default member set to [Net Income]. When evaluating the GENERATE set expression, SSAS looks in the entire cube space and looks at all coordinates for the [Account] dimension. These coordinates include both [Account][Account Type].&[] and [Account].[Accounts].[Net Income]. Because these two coordinates don't exist within the same hierarchy, SSAS returns an empty set. To avoid this problem the SSAS administrator must set the default member in the cube to a member that exists in all other hierarchies.
567839, 569506 565153

Unexpected Cell Formatting in Reports

When using data sources other than OLAP and you run a report, cell formatting may not appear as expected. For example, some cells may appear very small. This could be caused by null values returned from the query. To specify what appears for a data container when there are null values in a query, refer to the Report Studio Professional Authoring User Guide. You may also see an "Invalid Dates" message in some cells. This issue is specific to Transformer and occurs when cubes are constructed with unknown date values. For more information, see the Transformer User Guide.
494181

Report Differences Between TM1 Executive Viewer and IBM Cognos 8 with TM1 Data Sources
When using a TM1 data source, comparable reports created in an IBM Cognos 8 studio and in TM1 Executive Viewer may contain different cell values. This occurs because the TM1 Executive Viewer product uses an algorithm for selecting default members for non-projected dimensions that differs slightly from traditional OLAP clients. To avoid this problem, when filtering your reports in the IBM Cognos studios, use context filters that match the default selections shown in the Executive Viewer user interface. This ensures that the cell values in IBM Cognos 8 match the values in Executive Viewer.
592662

Order of Metadata Tree Differs for TM1 Data Sources

When using a TM1 data source, the order of members in the metadata tree of the Insertable Objects pane of an IBM Cognos 8 studio may differ from the order shown in TM1 Architect. By default, TM1 Architect renders members of hierarchies using a slightly different algorithm than does IBM Cognos 8. IBM Cognos 8 automatically renders member metadata from TM1 data sources in hierarchical order. From within TM1 Architect, if you want to see how an IBM Cognos 8 studio will render a hierarchy, click the Hierarchy Sort button.
606541, 605615

624

Chapter 40: Problems Authoring Reports

Problems Calculating Data

The topics in this section document problems you may encounter when using expressions to calculate data or when aggregating data in your reports.

Count Summaries in Query Calculations Include Nulls with SAP BW Data Sources
When using an SAP BW data source in Report Studio, null values in the database are returned in the result set and the Count summary function includes the empty cells in the following scenarios: A query calculation includes an arithmetic calculation where one or more NULL operands and an aggregation is performed on the calculation. The result of a query calculation is a constant, such as current_time() and current_date().

The Count summary function should normally exclude NULL values. To avoid this problem, for the first scenario, ensure that both operands do not return null values. For example, the original expression is [num1]+[num2]. Instead, use the following expression: if([num1] is null) then ( 0 ) else ([num1]) if([num2] is null) then ( 0 ) else ([num2]) There is no workaround for the second scenario.
564890, 570900, 568001

Unexpected Summary Values in Nested Sets

If a report contains nested sets, summaries other than the inner set summaries may contain unexpected values. For example, you insert a summary in a crosstab that contains a set with years in the rows.

You then nest a product line set within years.

Notice that the summary value does not change to represent the total of the new values. This occurs because the within set aggregation that Report Studio uses with dimensional packages does not take into account sets that are nested below the set that is summarized.

Administration and Security Guide 625

Chapter 40: Problems Authoring Reports To show the correct summary values, if the inner and outer sets do not belong to the same dimension, you can nest a copy of the inner summary item under the outer summary item, as follows.

576832

Incorrect Results with IBM Cognos PowerCubes and Time Measures

If a report uses an IBM Cognos PowerCube data source and the following combination of data items, you will encounter incorrect results: a measure with a Time State Rollup set to Average or Weighted Average an aggregate( members from time dimension ) expression an intersection with a member in a relative time hierarchy

To avoid incorrect results, do not use this combination in your reports.

592225

Problems Filtering Data

You can use filters to specify the subset of records that the report retrieves. Any data that does not meet the filter criteria is eliminated from the report. The topics in this section document problems you may encounter when using filters in reports. In general, when creating filters, select functions that are available from the Vendor Specific list. You must use Tabular SQL for other functions. Tip: If combining internal functions and vendor functions, set processing to Limited Local.

HRESULT= DB_E_CANTCONVERTVALUE Error When Filtering on a _make_timestamp Column

You cannot filter on a _make_timestamp column, and the following error messages appear: UDA-SQL-0114 The cursor supplied to the operation "sqlOpenResult" is inactive UDA-SQL-0206 The OLEDB driver returned the following value: HRESULT= DB_E_CANTCONVERTVALUE " RSV-SRV-0025 Unable to execute this request The solution is to apply the filter after aggregation and not before.

626

Chapter 40: Problems Authoring Reports

Problems Distributing Reports

The topics in this section document problems you may encounter when distributing reports.

A Report Link in an Email Notification Does Not Work

If a report link in an email notification does not work, the Gateway URI may not be configured correctly. You must change the host name portion of the Gateway URI from localhost to either the IP address of the computer or the computer name. If the URL in the email contains localhost, remote users cannot open the report.

Report Contains No Data

In Event Studio, if an agent running against a dimensionally-modeled data source passes values to a report based upon a relational source, the report may contain no data. When the source is dimensional, the agent passes member unique names (MUNs) to the target report. If the target report is based upon the same dimensional source, the report runs correctly. However, if the report is based upon a relational source, the agent must pass values (not MUNs) for the report to run correctly.

Steps to Convert the MUN to a Value

1. Drag the data item from the Insertable Objects tree to the Value field in the report task page. 2. Click in the field. 3. From the Insert menu, click Caption.

Hyperlinks in Email Messages Are Stripped Out When the Agent is Saved
In Event Studio, hyperlinks are stripped out when the agent is saved. The administrator must allow email links to ensure that the links remain in emails created by agents.

Steps to Allow Links in Email

1. Add the following line to templates/ps/portal/system.xml: <param name="allow-email-links">true</param> 2. Restart the server. Note: Adding this setting does not fix existing agents.

Steps to Insert a Link in an Email

1. Highlight some text in the email. 2. Press Ctrl-K. 3. Enter a URL into the box that appears.
560626

Administration and Security Guide 627

Chapter 40: Problems Authoring Reports

CNC-ASV-0001 The Following Agent Service General Error Occurred: java.lang. StackOverflowError
When running a web service task, you may encounter errors when the WSDL that describes the Web service is very large.

Step to Modify the Bootstrap_win32.xml File

To prevent this error, modify the file bootstrap_win32.xml in the bin folder to add the ThreadStackSize parameter: <process name="catalina"> ...<param condName="${java_vendor}" condValue="Sun">-XX: MaxPermSize=128m</param><param condName="${java_vendor}" condValue="Sun">-XX: ThreadStackSize=512</param>

Cannot Call the SDK from Event Studio

Even though Event Studio has a feature to insert a web service as a task, it is not possible to call the IBM Cognos SDK web service. Due to the complexity of the SDK and complex data types and options, the web service feature in Event Studio does not handle the IBM Cognos SDK. The exception to this rule is the trigger command that can be called from Event Studio.

Saving a Report Takes a Long Time

When you save a report, the Save As dialog box appears with a Loading message. The report will not be saved until it has finished loading, and this can take a long time. This issue will be resolved in the next version of IBM Cognos 8.
593393

628

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses

You may encounter problems when running, viewing, or printing reports. For information about reports, see the IBM Cognos Connection User Guide.

Problems Running Reports and Analyses

The topics in this section document problems you may encounter when running reports.

Summaries in Report Do not Correspond to the Visible Members

If a crosstab or chart created in Report Studio using a dimensional data source has a contextdependent set function such as filter or topCount on an edge, summaries do not correspond to the visible members. This occurs when the summaries use the within set aggregation mode. This problem occurs because a summary that uses the within set aggregation mode uses a set that is dependent on the members that it intersects with on the opposite edge. For example, the following crosstab has as columns the top three products returned. The expression used to generate the columns is
topCount([Product],3,[Return quantity])

where [Product] is the level.

The summary values for Total(ReturnedProducts) and Minimum(ReturnedProducts) for all rows except Central Europe do not correspond to the member values in the crosstab. This means that the top three products returned in all regions except for Central Europe are not Bug Shield Lotion 89110, Bug Shield Extreme 90110, and Sun Shelter 30 94110. Note that the summary values for Total(Region) and Minimum(Region) do correspond to the visible member values. That is because those summary values represent the total and minimum quantities returned for those three products in each region. You can see what the top three products returned in each region are by dragging the columns to the right of the rows, creating the following single-edge crosstab.

Administration and Security Guide 629

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses

To obtain summary values that reflect the visible members, modify the expression of the data item containing the context-dependent set function so that it includes a tuple that is locked to the default member of every hierarchy that appears on the opposite edge. For this example, modify the expression to the following:
topCount([Product],3,tuple([Return quantity], defaultMember([Retailer site])))

where [Product] is the level and [Retailer site] is the hierarchy. When you run the report, all summary values reflect the visible members in the crosstab.

Unexpected Results for Analysis Studio Reports Using Suppression and Nested Rows
In Cognos Viewer, you run an Analysis Studio report for which page breaks have been set. Detail items appear only on the page that contains the item for which suppression is applied, and only summary items appear on all other pages. This may occur because of the following combined conditions: The report contains nested levels. Suppression is applied to an item nested inside the outermost group.

630

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses In the report options, the page breaks setting is applied to the outermost groups on rows.

To avoid this result, in Analysis Studio you can do one of the following: In the report options, clear the page breaks setting. Move the outermost group to the context filter area before applying suppression. Remove all suppression. You can also run the report as is. To prevent this message from appearing, from the Run menu, click Report Options. On the Display tab, clear the checkbox under Warning page. If you do not have access to Analysis Studio, contact your administrator.

Unexpected Results May Occur When Using Items from the Same Hierarchy on Multiple Crosstab Edges
A crosstab that contains items from the same hierarchy on more than one edge may have unpredictable results, and may change from release to release. For example, in an analysis that uses items from Years on rows and Quarters on columns, unexplainable More values and Totals, and unexpected blank cells may appear. Also, expected results may be difficult to read because the useful numbers are distributed over a large area of mostly blank cells. For best results, ensure that items from the same hierarchy are on the same crosstab edge before saving.

Defining Languages for OLAP Data Sources

The first time you publish a cube definition to IBM Cognos Connection, you must identify all the languages that represent the data contained in the cube. If you add a language to the model after the cube is published, users with locales that match the added language locale may find that Analysis Studio does not recognize references to the member unique names. There is no impact on users whose locale matches the original language list.

Crosstab Shows Percentage But Chart Shows Values

When the crosstab calculates the percentage of the total for an item, the chart does not show the values as a percentage.

Cube Refresh in Data Analysis Studio Uses UTC/GMT Time

There is a difference between Report Studio and Analysis Studio when displaying the cube refresh timestamp. In Analysis Studio, the cube refresh timestamp is based on the UTC/GMT format, so there may be several hours of difference between the timestamp and the actual time that the cube was updated. In Report Studio, you use report expressions to reference the cube refresh data. Users who access the report output from Report Studio in Cognos Viewer are presented with the timestamp in local time and based on user preferences.

Administration and Security Guide 631

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses You can view the timestamp in local time and based on user preferences by opening the analysis in Report Studio and adding a layout calculation with the following expressions CubeDataUpdatedOn (dimension) or CubeSchemaUpdatedOn(dimension) using any cube dimension for either expression.

Cannot Drill when Caption Represents a Blank or a Zero-length String

A dimensional model over relational data may return a zero length '' or blank ' ' caption in the row or column in Analysis Studio. When it does, you cannot drill up or down from the set because no link appears. If this occurs, you can right-click the caption and select Drill Up or Drill Down in the shortcut menu.

DPR-ERR-2082 The Complete Error Has Been Logged by CAF With SecureErrorID
You cannot run a report in IBM Cognos Connection, and the following error messages appear: DPR-ERR-2082 An error has occurred. Please contact your administrator. The complete error has been logged by CAF with SecureErrorID: timestamp-#number. RSV-DR-0002 Unable to execute this request. These error messages do not indicate an IBM Cognos Application Firewall problem. You can view a more detailed error message, in the c8server.log file that resides in the logs directory on the IBM Cognos 8 server.

Steps to View a Detailed Error Message

1. Open the cogserver.log file, which is in the c8_location\logs directory on the IBM Cognos 8 server. 2. Search for SecureError or the timestamp-error number combination shown in the error message, such as 2004-06-29-15:15:03.796-#8. 3. The error message is under the SecureErrorID heading.

Query Studio Does Not Generate a SELECT DISTINCT statement if a Column is Aliased Without Using the Actual Column Name
When filtering on a column name, the query does not generate a SELECT DISTINCT statement if the referenced column is aliased by manually typing the alias in the SQL of the query subject. To avoid this situation, do not manually type the alias. Instead, in Framework Manager, rename the column by right-clicking on it and selecting the Rename option.
493536

Cannot Find the Database in the Content Store (Error QE-DEF-0288)

You cannot retrieve data from the selected database when running a report from Query Studio, IBM Cognos Connection, or Report Studio. The following error message appears:

632

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses QE-DEF-0288 Unable to find the database... If this error does not occur when you are logged on as an administrator, then to solve the problem, ensure that the user has permissions to the signon embedded. If this error always occurs, the data source has not been created. Create the data source with the name mentioned in the error message.

Parse Errors When Opening or Running an Upgraded Report

Earlier versions of ReportNet and IBM Cognos 8 included the cast_Date function for reports that run on an Oracle database. This function does not exist for Oracle in IBM Cognos 8.1.2 MR1 and later versions. If a report that uses an Oracle database includes the cast_Date function, parse errors will be received when you try to open or run the report.

Overflow Error Occurs When a Value in a Crosstab Is More Than 19 Characters

In a crosstab report, values support a maximum of 19 characters, including the decimal point. If a value exceeds 19 digits, an overflow error occurs. By default, the decimal precision is set to 7 digits, which restricts the number of integers to 11 digits. To use more than 11 integers, you must edit a configuration file to reduce the decimal precision. For more information, see the IBM Cognos 8 Administration and Security Guide.

IBM Cognos 8 Runs Out of TEMP Space

By default, IBM Cognos 8 stores temporary files in the c8_location/temp directory. The amount of space required by the temporary files directory depends upon several factors, including the number and type of reports created. The following error message indicates that the temporary files directory ran out of space: QE-DEF-0177 An error occurred while performing operation 'sqlOpenResult'. UDA-SQL-0114 The cursor supplied to the operation "sqlOpenResult" is inactive. UDA-TBL-0004 There was a Write error while processing a temporary file. If this error occurs, ensure that the disk on which the temporary files directory is located has adequate space. You should also periodically delete unwanted files from this directory.

A Report Does Not Run as Expected

A report may not run as expected if the model contains errors or the wrong governor settings.

Steps to Check the Model

1. Open the model in Framework Manager. 2. Ensure governors are set to disallow. 3. In the diagram view, ensure that there are no cross-join errors or ambiguous joins. 4. Check the package for a missing query subject. 5. Run the Verify Model function, and correct any errors detected.

Administration and Security Guide 633

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses

Performance Issues when Showing Multiple Attributes Using Dimensionally Modeled Relational Data Sources
If you display multiple attributes for the items in a set on the crosstab, you can only select one attribute at a time, so Analysis Studio executes a query for each attribute selection. The performance of this approach is an expensive one to execute against a relational data source because of the query necessary to retrieve the attribute and its value. You can select multiple attributes for a selected crosstab set in Analysis Studio by using the Properties pane . By selecting multiple attributes before clicking OK or Apply in the dialog box, only a single query for all selected attributes is executed, instead of one per attribute. Multiple selection in the UI is the preferred approach for enabling the display of more than one attribute for dimensionally modeled relational data source packages, because of the reduced performance impact on the relational data source.

Analysis Studio Shows the Wrong Currency Symbol

When published to IBM Cognos 8 Analysis Studio, PowerCubes show a default currency rather than the currency associated with the locale of your servers and PCs. For example, GBP () is shown as $. To resolve this problem, you can do one of the following: Create a currency table when you prepare your model in Transformer and embed a default currency symbol into the resulting PowerCubes, based on the system locale used by your Transformer computer. For PowerCubes that do not contain an embedded currency table, set the fallbackCurrency parameter as the default currency.

Steps to Create a Currency Table in Transformer

1. In Transformer, from the File menu, click Currency Table, and click OK. 2. Right-click each currency measure, and click Allow currency conversion. This default currency table does not include currency information for any locales other than your running locale. Also, you cannot convert to a different currency while working in Analysis Studio.

Step to Set fallbackCurrency as the Default Currency

Define a default currency by setting the fallbackCurrency parameter in the configuration/ qfs_config.xm file to GBP (Great Britain Pounds) or to an alternative currency code as listed in the /ccli18nrescr_xx.xml file. Here is an example.
<!-- execution layer providers--> <provider name="PowerCubeODP" libraryName="pcodp" connectionCode="PC"> ... <providerDetails>

634

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses

<parameters> <!-- Max depth of nested calculated members within a query. --> <parameter name="maxCalculatedMemberNestingDepth" value="30"/> <!-- Normalize yen/won currency symbols - set to "false" to disable --> <parameter name="normalizeYenWon" value="true"/> <!-- Fallback currency for cubes with no default currency specified - set to USD, EUR etc. --> <parameter name="fallbackCurrency" value="USD"/> </parameters> </providerDetails> </provider>
516574

Error Occurs in Japanese Internet Explorer 7 When Running an Excel Report in Analysis Studio
An error may occur when you close Japanese Internet Explorer 7 installed on Windows XP SP2 while it is running an Analysis Studio report in Excel format. To solve this problem, Microsoft recommends that you unregister the msctf.dll file using the following command:
Regsvr32/U Msctf.dll

This .dll file is part of the ctfmon.exe speech recognition application. You may turn off any speech recognition application installed on your computer before unregistering the .dll file. For more information about turning off speech recognition, see http://support.microsoft.com/kb/313176/EN-US/
540718

The ORA-00907 Error Appears When Running a Report

When using an Oracle 9.2 data source, under certain circumstances, multiple or nested join operations may fail and produce the following error: ORA-00907: missing right parenthesis A query that uses both a left outer join and an ON clause condition returns zero values instead of null values.

Drilling Through to IBM Cognos 8 from an IBM Cognos Series 7 Product Results in Firewall Error
You use an IBM Cognos Series 7 product that is configured to use a proxy server. When you drill through to IBM Cognos 8, the following error message appears: DPR-ERR-2079 Firewall Security Rejection. Your request was rejected by the security firewall. Please try again or contact your administrator. Administration and Security Guide 635

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses This is because the IBM Cognos 8 Web server does not recognize the proxy server name and rejects the entry. To correct this problem, add the proxy server name in IBM Cognos Configuration.

Steps to Add a Proxy Server Name

1. Start IBM Cognos Configuration. 2. In the Explorer window, click Security, and then click IBM Cognos Application Firewall. 3. In the Valid domains or hosts box, add the proxy server name. 4. From the File menu, click Save. 5. From the Action menu, click Start.
433666

Scheduled Reports Fail

You schedule reports that previously ran successfully, but now fail. The following error message appears: CAM.AAA Error authenticating user This may happen because a user changed a password. IBM Cognos 8 uses a copy of the user ID and password to run the scheduled report. The solution is for the user to renew their credentials.

Steps to Renew Credentials

1. Ask the user who scheduled the report to log on to IBM Cognos Connection. 2. In IBM Cognos Connection, click the my area button and click My Preferences. 3. On the Personal tab, scroll to the Credentials section. 4. Click Renew the credentials. Note that this does not apply to users from an IBM Cognos Series 7 namespace.

The Table or View Was Not Found in the Dictionary

When you run a report, the following error message appears: The table or view "xxx" was not found in the dictionary. This may occur if permissions were not properly set. Ensure that the user defined in the data source has SELECT privileges for the affected table.

Mixed Languages Are Displayed in IBM Cognos Connection When Using Samples
When you restore the Cognos_samples.zip file in the webcontent/samples/content folder it contains multilingual content. When you change the locale setting on your computer, reports appear in the language specified for your computer. This is not true for sample IBM Cognos PowerCubes. When 636

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses you restore Cognos_powercube.zip or Cognos_powercube_financial.zip, a different folder is set up for each language. If you select a PowerCube from a language folder that is different than the language specified by the locale setting on your computer, a mixture of languages is displayed in IBM Cognos Connection. There are two options for solving this problem: Re-install Cognos_powercube.zip or Cognos_powercube_financial.zip. First ensure that your computer is set to the locale that is consistent with the language of the PowerCube package you are installing. Then, install only the package from the language folder that matches the locale setting. Or, in IBM Cognos Connection, open each PowerCube package, click the Set Properties button, and in the Language box, select the language of the IBM Cognos PowerCube.

Unable to Select Multiple Report Formats When Running a Report

When running a report with options, you cannot select multiple formats when the delivery option is to view the report. Before selecting multiple formats on the Run with advanced options page, you must first change the Delivery option to Save the report, print it, or send an email.

A Report Does Not Run as Scheduled

A scheduled report may fail, or an administrator may cancel it. To view the run history and status of a report you scheduled and to view detailed information about why a scheduled report failed, do the following:

Steps
1. In IBM Cognos Connection, click the my area button, and click My Activities and Schedules, Schedules. 2. Click the arrow next to the item to view the Actions menu, and then click View run history. The View run history page appears. 3. To view the run history details, in the Actions column, click the view run history details button.

A Report or Analysis Does Not Run Because of Missing Items

You attempt to run a report or analysis and a message indicates that one or more items are missing or changed. Each missing item is listed by its MUN (member unique name). The MUN includes the complete path within the hierarchy for the item. When you place your cursor on an item in the Insertable Objects pane, the MUN for that item is displayed in a tooltip. This situation may occur if members have been removed from or changed in the data source. It may also occur when you attempt to run a report that uses items to which you do not have access. For example, an administrator may create an analysis that includes items that you don't have the correct permission to access.

Administration and Security Guide 637

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses The solution is to find a suitable replacement in the Insertable Objects pane, and drag it to the New Item column. The report or analysis will then run.

Cannot View Burst Report

When you burst a report, each burst output is sent to the associated list of recipients. If a list of recipients contains invalid entries, the following occurs: The burst output is not saved to Content Manager. Consequently, you cannot view the burst output in IBM Cognos Connection. If you choose to send the output by email, only valid recipients will receive an email. Although the output is sent as an attachment if you select the Attach the report check box, no link is generated if you select the Include a link to the report check box. The following error message appears in the run history for the report, where parameter 1 is the burst key, parameter 2 is the list of recipients, and parameter 3 contains the error messages returned by Content Manager: An error occurred while saving the output for the burst instance <param type="string" index="1"/> with the recipients (<param type="string" index="2"/>). Here are the details: <param type="string" index="3"/> Note: The list of recipients includes both the valid and invalid recipients. For example, a report is set up to burst on Country, and the recipients are managers. Running the report produces the following countries and recipients: Canada: John, Mary US: Peter, Frank France: Danielle, Maryse

Frank is an invalid recipient. The burst outputs for Canada and France are saved to Content Manager, but not the U.S. output. If you choose to send an email to each recipient and you selected the Include a link to the report check box, the email to Peter will not contain a link to the output for US. The error message that is generated will contain Peter and Frank as values for parameter 2 with no indication as to which is invalid.

Steps to Correct or Remove Burst Recipients

1. View the error message in the run history for the report. 2. From the list of recipients, determine which recipients are invalid. You may need to consult with your administrator to find out which recipients are invalid. 3. Correct or remove the invalid recipients. Correcting or removing invalid recipients will depend on how the list of recipients was defined, such as through a calculated field or a burst table. 4. Run the report again.

638

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses

PCA-ERR-0057 Recursive Evaluation Error

You run a report and encounter the following error: PCA-ERR-0057 Recursive evaluation has exceeded limit. Calculated member trace: COG_OQP_ USR_Aggregate(Retailer Type): COG_OQP_INT_m2: COG_OQP_INT_m1: COG_OQP_USR_ Aggregate(Retailer Type): COG_OQP_INT_m2: COG_OQP_INT_m1: COG_OQP_USR_Aggregate (Retailer Type): COG_OQP_INT_m2: COG_OQP_INT_m1: COG_OQP_USR_Aggregate(Retailer Type): COG_OQP_INT_m2: COG_OQP_INT_m1 You may encounter this error when two or more data items form a recursive evaluation. For example, in the above error, the calculation of Aggregate(Retailer Type) is dependent on a column expression while at the same time the column expression is dependent on Aggregate(Retailer Type). Therefore, the cyclic relationship cannot be resolved. To avoid this problem, ensure that calculations do not have cyclic relationships.
585236

Arithmetic Overflow Error When Running a Report in PDF Format

If you use a Microsoft SQLServer 2005 data source and your report includes aggregations, you may encounter the following error when you run your report in PDF format: RQP-DEF-0177 An error occurred while performing operation 'sqlOpenResult' status='-28'. UDASQL-0114 The cursor supplied to the operation "sqlOpenResult" is inactive. UDA-SQL-0564 [Microsoft OLE DB Provider for SQL Server] Arithmetic overflow error converting expression to data type int. (SQLSTATE=22003, SQLERRORCODE=8115) This error occurs because the action is performed in the database, and the database data type is too small. This error did not occur in IBM Cognos 8 version 8.3 or earlier because aggregation was processed locally, by the BI server. In version 8.4 or later, aggregation is processed at the database level. To avoid this problem, increase the size of the the database data type.
587166

Performance Problems When Running Reports

The topics in this section document performance problems you may encounter when running reports in IBM Cognos Connection.

CGI Timeout Error While Transferring Data to IBM Cognos 8 Components

When performing operations through your Web browser, you receive the following error message: CGI Timeout, process will be deleted from server. The error occurs when you use Windows Internet Information Services (IIS) as your Web server and the gateway is configured to use CGI. IIS has a default timeout for CGI applications.

Administration and Security Guide 639

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses To resolve this problem, you can configure the gateway to use ISAPI. IIS does not have a default timeout for ISAPI applications. Or, if you want to keep using a CGI gateway, you can increase the CGI timeout in IIS.

Steps to Change the Gateway to ISAPI

1. On the gateway computer, start IBM Cognos Configuration. 2. Under Environment, for the Gateway URI property, change the cognos.cgi portion of the URI to cognosisapi.dll. 3. In your Web browser, specify the ISAPI URI: http://computer_name/cognos8/isapi

Steps to Increase the CGI Timeout

1. In the Windows administrative tools, open Internet Information Services. 2. Under the local computer node, right-click Websites and select Properties. 3. In the Home Directory tab, click Configuration. 4. In the Process Options tab, increase the CGI script timeout.

Slow Server Performance

If your content store has many users and policies, clients reading schedule information for many users can slow down server performance for all users. To correct this problem, administrators can remove the Entries I Own, Public Folders, and Any options from the Scope list on the Schedule Management page. You can use a URL or edit the system.xml file to remove user interface elements for most users while showing the user interface elements to other users, such as the administrator. The following table describes these user interface elements.

User interface element

SMT_SCOPE_any

Description
Any value from the Scope list in the Schedule Management tool. Entries I Own value from the Scope list in the Schedule Management tool. Public Folders value from the Scope list in the Schedule Management tool.

SMT_SCOPE_entries_i_own

SMT_SCOPE_public_folders

For information about hiding user interface elements, see the IBM Cognos 8 Administration and Security Guide.

640

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses

The BAP-ERR-0002 BAPI Error

When using IBM Cognos 8 with an SAP BW data source, the following error message may appear: BAP-ERR-0002 BAPI error occurred in function module BAPI_MDDATASET_CHECK_SYNTAX. Error occurred when starting the parser. This error usually occurs because the SAP BW server is overloaded. To resolve this problem, restart the IBM Cognos 8 server or close all open connections from the SAP BW Administrator Workbench.

The Out of Memory Error Appears in HP-UX

In HP-UX, the default setting for the threads per process is too low for most Java applications. To avoid out of memory errors, increase the value for the following kernel parameters:
max_thread_proc nkthread.

Note: The nkthread parameter should be double the value of the max_thread_proc parameter. For more information, see the HP Web site.

A Query Is Slow When Filtering Non-ASCII Text

When using an SAP BW data source, and range filters are defined on non-ASCII text values, such as city names that contain accented characters, the query may take longer to run. This occurs because the filter must be performed on the application server and not on the SAP BW server because SAP BW 3.0B supports queries only if they use ASCII values. To avoid this problem, do not filter non-ASCII values.

Query Studio Output Takes a Long Time to Run

In IBM Cognos Connection, you click Run with Options and select the Save the report delivery option. This action returns all data, renders the report, and stores it in the content store, which can take a long time. It is quicker to run the report manually, using the Run command, which generates the report a page at a time.

Problems Viewing Reports

The topics in this section document problems you may encounter when viewing reports.

A Report Upgraded from ReportNet Does Not Retain its Original Look
When you upgrade a report to IBM Cognos 8, a new style sheet is applied that changes the look of the report.

Administration and Security Guide 641

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses To preserve the formatting that was used in the original report, you can select a different style sheet. This retains the original look of the report and specifies that any new items added to the report, such as list columns or crosstab levels, have the original formatting applied to them.

Steps
1. In Report Studio, from the File menu, click Report Properties. 2. Click Report styles and select 1.x styles.

Drill-through Links Not Active in the Safari Browser

When viewing a PDF report in the Macintosh Safari browser, you cannot open hyperlinks. This is because the Macintosh Safari browser does not have the necessary Adobe Acrobat plug-in. To avoid this problem, use the HTML format when creating drill-through reports that may be viewed in Safari.

A Running Total in Grouped Reports Gives Unexpected Results

You have a running total calculation in a grouped report that returns unexpected values. Because tabulation of the running total calculation depends on the order in which the grouping is executed, you must ensure that the grouped totals are tabulated before applying the running total. To ensure that the grouping is executed in correct order, define a running total calculation as a freestanding calculation outside the query subject in Framework Manager, and ensure that the Regular Aggregate property is set to Automatic. This may also be an issue with other running, moving, and ranking aggregations.

The Page Cannot Be Found Error Appears When Viewing Report Outputs from Email Links
When a report is distributed by email, no error message appears if the report output from the email link is not available. This can occur when the output is deleted or when the user does not have permissions to the report. Instead, the error "The Page Cannot Be Found" appears. You are unable to view the report output from the email link when Allow Anonymous Access is set to true and when the Anonymous user does not have access to the report output. When you run a secured report from an email link and when Allow Anonymous Access is set to True, a passport is automatically issued to the Anonymous user. The Anonymous user is not prompted to log on and is unable to view the report output.

Non-English Characters Appear as Placeholders

IBM Cognos 8 and Framework Manager are Unicode applications. A Unicode application permits handling of content in any language, or any combination of languages. However, if your database contains non-English characters, and if the database client is not configured to receive these characters, some characters may appear as placeholder characters, such as boxes or inverted question marks.

642

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses To avoid this problem, ensure that your database clients are properly configured. For more information, see your database vendor documentation. For Oracle 9, you can force the use of Unicode on the client by ensuring that the system environment variable NLS_LANG is set to "xxx.UTF8", where xxx is whatever is needed for other applications on that computer. If there are none, the value can be simply .UTF8. For information about configuring your database for multilingual reporting, see the IBM Cognos 8 Administration and Security Guide. While enforcing the use of Unicode on the database client guarantees that it can handle multilingual data, some characters in some character sets may still appear incorrectly, such as Japanese ShiftJIS. For information about configuring Shift-JIS characters, see the IBM Cognos 8 Administration and Security Guide.

Cannot Drill Between PowerCubes Because MUNs Do Not Match

An IBM Cognos PowerCube has category codes and source values that are different. Its source values are conformed with another PowerCube however the category codes in both PowerCubes are different. You cannot drill between shared dimensions in these PowerCubes because their Member Unique Names (MUN) do not match. The source value for a PowerCube member is used as the member business key in IBM Cognos 8. If the source value business key is conformed between PowerCubes, you can pass the business key in a calculation to drill through between two cubes where the MUN does not match. This technique works only if the business keys are unique. If the business keys are not unique, then the result may be unexpected. For example, drilling through from London, England in the source may produce a drill-through report that contains both London, England and London, Ontario. If drilling through was not enabled at build time, the source cube will pass the category code instead of the source value. To pass the business key to the target, do the following: Create the target report parameter by typing: roleValue('_businessKey',[member])=?prompt? When you drill through, the business key is passed. For more information about drill-through access, see the IBM Cognos 8 Administration and Security Guide.

Unexpected or Empty Results When Drilling Through

When you drill from a source report to a drill-through target, sometimes no value is found. If there is no data that corresponds to the drill-through selections, or if you do not have permission to view the data, this may be the correct result. In other cases, or if the wrong data item appears, it may be that the source item is not correctly mapped to the target. If you have the necessary permissions, you can debug drill-through definitions by using the drillthrough assistant from the Goto page. (Right-click the selection in the source report, and select Go To.) You can view the passed source information, and the mapping to the target report or object. You use this tool for both authored and package drill-through definitions. Administration and Security Guide 643

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses You may be able to correct the problem by modifying the parameter mapping in the drill-through definition. For example, when you drill from a cube to a relational data source, sometimes no value is found, or the wrong data item appears, because the business key values in the two data sources do not match. You can change the drill-through definition to pass the caption of the PowerCube member instead of the business key.

Step to Pass the Caption from a PowerCube to a Relational Source

Edit the drill-through definition as follows: If the drill-through definition was created in Report Studio (Professional authoring mode), open the report, and go to the drill-through definition associated with the drill-through source object. On the parameter mapping page, select Member Caption in the Property to pass column. If the drill-through definition was created in the source package, go to IBM Cognos Connection, Drill-Through Definitions, and open the package drill-through definition. On the Target tab of the drill-through definition, select Member Caption in the Property to pass column for the appropriate parameter. When you drill through, instead of the business key, the caption is passed to the target. For more information about drill-through access, see the IBM Cognos 8 Administration and Security Guide.

Cannot Drill From a Relational Source to a Cube

You cannot drill through from a relational data source to a cube. This is because a cube expects a Member Unique Name (MUN) as a parameter value and relational sources do not use MUNs. Members have several properties such as a business key and a caption. If either of these match data items within the relational source, drilling through can be performed as long as the cube target report is authored in Report Studio. If the source data source has a query item, for example display name, that corresponds to a member property in the target cube, for example caption, you must create the parameter on the caption in the target report. To pass the data item to the cube target, do the following: In the cube target report, create a parameter that accepts the caption of the member. Type the following caption([member])=?prompt? When you drill through, the selected value is passed to the target. For more information about drill-through access, see the IBM Cognos 8 Administration and Security Guide.

Charts Do Not Appear in HTML reports

In IBM Cognos 8, HTML output reports are displayed in Microsoft Internet Explorer 6.x with 24bit transparency to ensure that the appropriate color depth is displayed, typically for charts.

644

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses If you operate in an environment that requires the Internet Explorer 6.x security level to be set to high, charts may not appear. If you cannot lower the security setting for security reasons, you may want to disable chart transparency. Charts are displayed in Internet Explorer with transparencies displayed in white. You must have the required permissions to access IBM Cognos Administration functionality. See "Secured Functions and Features" (p. 221).

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click Services, Report Data 5. Click the arrow next to the service to display the Actions menu, and then click Set Properties. 6. Click the Settings tab. 7. For the Environment category, next to Advanced settings, click the Edit link. 8. If it appears, select the Override the settings acquired from the parent entry check box. Otherwise, proceed to the next step. 9. In the Parameter column, type EnableChartTransparencyIE. 10. In the Value column, type False to disable chart transparency in Internet Explorer. 11. Click OK. 12. Click OK again.

Portal Problems
The topics in this section document problems you may encounter with a portal when viewing reports.

Cannot Connect to a SQL Server Database Using an ODBC Driver

The connection works in Framework Manager, and metadata can be imported. When testing the database connection in the IBM Cognos Connection portal, the following error messages appear: QE-DEF-0285 Logon failure QE-DEF-0325 The cause of the logon failure is: QE-DEF-0068 Unable to connect to at least one database during a multi-database attach to 1 database(s) in: testDataSourceConnection UDA-SQL-0031 Unable to access the "testDataSourceConnection" database. UDA-SQL-0129 Invalid login information was detected by the underlying database. Administration and Security Guide 645

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses [Microsoft][ODBC SQL Server Driver] [SQL Server] Login failed for user '(null)'. Reason Not associated with a trusted SQL The solution is to change the Network Library Configuration for SQL Server to use TCP/IP instead of Named Pipes.

Steps to Set TCP/IP as the Network Library Configuration

1. Open ODBC Data Source Administrator. Tip: In Windows 2000 you can do this by clicking Start, Settings, Control Panel, Administrative Tools, Data Sources (ODBC). 2. Select the data source name defined for SQL Server on the System or User DSN tab. 3. Click Configure. 4. On the Microsoft SQL Server DSN Configuration page, click Next. 5. Click Client Configuration. 6. Ensure that TCP/IP is selected for the Network library entry.

The My Folders Tab Does Not Appear After Logging On to IBM Cognos Connection
A user is a member of a new group, and this group is a member of the Query Users group. When this user logs on, the My Folders and the personalized pages tabs do not appear in IBM Cognos Connection. Also, the user name does not appear in the upper-left corner of IBM Cognos Connection. To avoid these problems, the namespace to which the user belongs must have traverse permission to the Query Users group.

Steps to Specify Traverse Permission

1. Log on to IBM Cognos Connection as an administrator. 2. From the Launch menu, click IBM Cognos Administration. 3. On the Security tab, click Users, Groups, and Roles. 4. Click the set properties button next to the namespace. 5. Click the Permissions tab. 6. Ensure that the Query Users group appears in the namespace. 7. Select the Query User Traverse check box. 8. Click Apply and then click OK. 9. Test with a user.

Icon Graphics Are Not Working in Portlets

When you access IBM Cognos portlets in SAP EP or WebSphere, icons and pagination graphics may appear as empty rectangles. 646

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses This problem can be caused by improper settings in IBM Cognos Configuration.

Steps to Change Settings

1. Start IBM Cognos Configuration. 2. In the Explorer window, under Environment, click Portal Services. 3. Ensure that all URIs use absolute server names instead of localhost.

Styles Used in the Previous Installation Still Appear

You can customize the styles (previously called skins) used by IBM Cognos 8. The styles are applied when users access IBM Cognos Connection. If you reinstall IBM Cognos 8, styles from the previous installation may still appear when users access IBM Cognos Connection. The styles are cached by the browser. If you do not want to apply customized styles, ensure that users delete the temporary files from the browser cache.

Unable to Click Links

Links in IBM Cognos Connection will not work if your browser is not properly configured. Consequently, you cannot perform operations such as running a report or starting Report Studio. For all Web browsers, cookies and JavaScript must be enabled. For more information, see your browser help. For Internet Explorer only, the following must be enabled: Run ActiveX controls and plug-ins Script ActiveX controls marked safe for scripting Active scripting

IBM Cognos does not provide or download ActiveX controls as part of IBM Cognos 8. Report Studio uses the native Internet Explorer XML support, which is an integral component of the browser. Because Microsoft implements XML using ActiveX, you must enable ActiveX support for Report Studio.

Steps to Enable Internet Explorer Options

1. In Internet Explorer, from the Tools menu, click Internet Options. 2. On the Security tab, click Custom Level. 3. In the Security Settings dialog box, scroll to the Activex controls and plug-ins settings and enable Run Activex controls and plug-ins and Script Activex controls marked safe for scripting. 4. Scroll to the Scripting settings and enable Active scripting. 5. Click OK.

Administration and Security Guide 647

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses

Missing Images in a PDF Report

Images that appear in reports rendered as HTML are missing in reports rendered as PDF. The embedded GIF, JPG, and BMP images do not appear. Only the borders of the missing images appear. If you use Microsoft Internet Information Services (IIS), go to the properties sheet of the Web site and ensure that the Enable the HTTP Keep Alives option is selected. Ensure that the virtual directory where the images are stored has anonymous access enabled. Open IIS and open the properties sheet for the virtual directory for your images. Select the Anonymous Access check box.

Charts in PDF Output Show Unexpected Results

Charts, when viewed in PDF output, have different levels of interaction support, depending on the version of Adobe Acrobat Reader and the style of chart element. Adobe Reader version 5 does not support tooltips. Drill up and down and Go to links have limited support, due to technical limitations. Only rectangular areas in charts, such as bars, columns, horizontal labels on the axis, or legend labels can be enabled for drill or Go to interaction. Nonrectangular areas, such as pie slices in pie charts, cannot be enabled for drill or Go to interactions. Adobe Reader version 6 and 7 supports tooltips, drill up and down, and Go to links for all chart types. When chart elements overlap or are separated by only a few pixels, the interactive region may be smaller than the area shown.

Problems Printing Reports

The topics in this section document problems you may encounter when printing reports.

Unable to Print PDF Reports

When you try to print a PDF report from IBM Cognos Connection and Report Studio, you may be unable to print or an error message such as the following may appear: CNC-GEN-2107: An unexpected error has occurred. There may be no error messages and the status of the print job is Succeeded. To correct the problem, try the following: Ensure that Adobe Reader version 5.0.5 or later is installed on each computer where IBM Cognos 8 servers are installed. Ensure that the IBM Cognos 8 server is started using an account that has access to the network printer. Sometimes, system accounts may not have access to network printers. If IBM Cognos 8 is installed on UNIX, ensure that Adobe Reader is installed in the path of the user that starts IBM Cognos 8. If IBM Cognos 8 is installed on UNIX, ensure that the lpstat -v command returns a configured printer and that a printer variable is defined.

648

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses When you define the network address for the printer in IBM Cognos Connection, use the following syntax: For Windows: \\server_name\printer_name For UNIX: printer_name

When you define the network address for the printer, try using the IP address of the printer instead of the computer name. Ensure that IBM Cognos 8 users have the correct access permissions for the printer.

Tip: In IBM Cognos Connection, from the Launch menu, click IBM Cognos Administration. On the Configuration tab, click Printers. Click the arrow next to the printer to view the Actions menu, and then click Set properties. Click the Permissions tab. Ensure that the Directory Administrators group has all the access permissions granted and that the group Everyone has Read, Execute, and Traverse access permissions granted. Ensure that you can print a test page on the printer. If Tomcat is used as an application server, the crn_ROOT environment variable must not be defined. Ensure that users have read, execute, and traverse permissions for the printer object in IBM Cognos Connection. The printer name consists of only the first 127 ASCII characters.

A Printed HTML Report is Unsatisfactory

Printing HTML may produce unsatisfactory results. For best results, use the View in PDF Format command, and then print the PDF. This alternative gives you more control over such things as pagination than the browser does.

Administration and Security Guide 649

Chapter 41: Problems Running, Viewing, or Printing Reports and Analyses

650

Chapter 42: Problems When Using Map Manager

This section provides solutions for problems you may encounter when using Map Manager. For information about Map Manager, see the Map Manager Installation and User Guide.

Problems Importing Files

You may encounter problems when you try to import a map file or text file.

Error Importing Translated Text File

When you import a TXT or CSV file that has been translated, you receive an error message similar to the following: Unable to save the file. An error occurred while importing the map file. Unable to import. The translation file contains no useful content. The problem may be caused by one of the following: The map file that is open is not the map from which you created the export translation file. Features were added or deleted in the file. Columns (extra tabs or commas) were added to the file. The data was sorted and is now in a different sequence than when it was first exported.

To resolve the problem, first ensure that the correct map file is open. If it is, then resend the original exported file for translation and specify that the contents must not be sorted, deleted, added to, or modified except to add translated features. If required, export the translation features and languages again.

Administration and Security Guide 651

Chapter 42: Problems When Using Map Manager

652

Chapter 43: Problems With Metrics

This section provides solutions for problems you may encounter when using Metric Studio or Metric Designer. The information is organized into the following sections: "Known Issues When Using Metric Studio" (p. 654) "Known Issues When Using Metric Designer" (p. 658)

Also, log files (p. 653) can help you troubleshoot problems by recording the activities that take place when you work with Metric Studio. If you must contact customer support for assistance with a Metric Studio issue, attaching the support bundle (p. 654) will help expedite your case.

Metric Studio Log Files

Operations performed in Metric Studio are recorded in various log files for tracking purposes. For example, if you experienced problems loading data into Metric Studio, consult the debug_info.log file to learn what activities were performed during the load. You can find the log files at the following locations: installation_location/logs/MetricMaintenance/databasename-timestamp/Metaloader The metaloader log file contains information about when the load started how many and what types of objects were loaded the amount of time taken to apply the business rules steps in the loading process how long the load took to run

The load_summary.log file contains the number of loading errors and the associated error codes. The sql_history.log file is useful when tuning performance. It is a tab-delimited file that you can open using Excel. It contains SQL commands, the rows affected, and the time elapsed for each SQL statement. The debug_info.log file is a tab-delimited file and contains debugging information. The amount of information in this file depends on the level of logging detail selected. For information about setting the level of logging, see "Logging Settings" in the Metric Studio User Guide. installation_location/logs/MetricStoreInstall/databasename-timestamp installation_location/logs/MetricStoreUpgrade/databasename-timestamp Administration and Security Guide 653

Chapter 43: Problems With Metrics installation_location/logs/MetricNewPackage installation_location/logs/MetricUpgradePackage

Metric Studio Support Bundle

If you must contact customer support for assistance with a Metric Studio issue, attaching the support bundle will help expedite your case. This support bundle is a zip file generated by a tool called cmm_support_bundle. The command is located in installation_location/bin and is invoked as follows: cmm_support_bundle databaseServer databaseName databaseUser databasePassword databaseType output_filename where databaseServer is the hostname of the database server (default: localhost) For Oracle, you can add an optional port by appending ':port' to the hostname (default: 1521). For example, localhost:1234. The databaseServer parameter is ignored for database type 'db2'. databaseName is the name of the database (default: cmm) This is the 'database file' entry for database type 'db2'. databaseUser is the database user name (default: sa) databasePassword is the database password (default: cmm) databaseType is the database type (default: sqlserver; values can include sqlserver, oracle, db2) output_filename is the fully qualified name of the zip file to create (defaults to the _SUPPORT_FILES directory)

For example, if a SQL Server database contains your metric store, issue a command such as cmm_support_bundle dbserver1 prod_db sa topsecret sqlserver or on UNIX sh cmm_support_bundle.sh dbserver1 prod_db sa topsecret sqlserver By default, this will create output in the installation location/_SUPPORT_FILES directory.

Known Issues When Using Metric Studio

The information in this section will help you resolve issues encountered when working with Metric Studio.

Metric Studio Reports Fail Because of an Oracle Internal Error

Some reports that are included with Metric Studio fail to run because of an Oracle internal error. This occurs when you are using 10.2.0.x releases of Oracle. 654

Chapter 43: Problems With Metrics The reference bug for Oracle is 5864217. If you encounter this error, you can resolve it by installing Oracle 10.2.0.3, Patch 5, which is officially named 5946186. You can obtain this patch from the Oracle Support's Metalink site which is available through your existing support agreement. Apply the patch as directed by the instructions included with the download from Oracle Support.
567585

Metric Studio Errors Occur When Loading Data into an Oracle Database
The application is disconnected from Oracle with ORA-07445 and ORA-3113 errors. You can see these errors in the database alert log. The database errors then cause errors in Metric Studio. This is a known issue with Oracle (Bug 5026836 - Ora-7445 [Kxccres()+3052] Updating View With Instead Of Trigger). The workaround is for the database administrator to run the following command while logged in as SYS: If an SPFILE is in use, ALTER SYSTEM SET optimizer_features_enable='10.1.0' SCOPE=BOTH. If an SPFILE is not in use, ALTER SYSTEM SET optimizer_features_enable='10.1.0'. If an SPFILE is not in use, the database administrator should also add this setting to the init.ora file for the database instance.
530992 510492

Oracle Errors Occur When Using the cmm_uninstall Script

Oracle internal errors occur when clearing an Oracle schema using the cmm_uninstall script. The errors occur if using the undocumented FORCE option. The errors are caused by an existing Oracle bug that is scheduled to be fixed in version 11. Details can be found in Oracle Note 338953.1. The errors can be avoided by disabling the recycle bin using one of the following methods: In the init.ora file, add the line _recyclebin = false and restart the database. Run the command SQL> alter system set "_recyclebin" = false scope=spfile; and restart the database.

531440

Error When Attempting to Run Metric Studio on SQL Server 2005

When clicking a scorecard, a SQL Server error appears: Msg 169, Level 15, State 1, Line 3 - A column has been specified more than once in the order by list. Columns in the order by list must be unique. This has been identified by Microsoft as bug #484681 and occurs in Microsoft SQL Server 2005 RTM (Build 9.00.1399). The problem was resolved by Microsoft in Microsoft SQL Server SP1.

Administration and Security Guide 655

Chapter 43: Problems With Metrics If you encounter this error, you can resolve it by installing Service Pack 1 for SQL Server 2005 (or later).
577840

Data from a Relational Database Source or a Flat File Data Source Does Not Appear
You use IBM Cognos Connection to load data into the metric store. If IBM Cognos Connection encounters a problem while loading data from a relational database source or a flat file import source, the data will not appear. Typical problems include text fields that are too long required fields are missing duplicate rows references to non-existent objects

To find the error, run the batch file or shell script from the command line and check the status of each step. Alternatively, you can repeat the loading process in two stages through the user interface and check the success of each stage.

Steps to Separate the Loading Process into Stages

1. In IBM Cognos Connection, under the Metric Maintenance folder for your package, click Import data from files into staging area. 2. Use an SQL query tool to check whether the data was loaded. If not, ensure that you have defined the data source correctly and that the files are in the correct location formatted the flat file with tab-delimited columns included the correct number of columns used the correct data formats, such as yyyy-mm-dd for dates and a period for the decimal separator

The logs from the attempt to load each tab-delimited file can be found at installation_location/logs/Metric Maintenance/databasename-timestamp/BulkLoad, and may contain more descriptive error messages than are available from the user interface. 3. If you find errors, correct them and repeat steps 1 and 2. 4. After the data appears in the staging tables, in IBM Cognos Connection, under the Metric Maintenance folder for your package, click Transfer data from staging area into metric store. 5. Check whether the data appears in Metric Studio. If it does not, check the last three columns of the kpi_value_stage_rejects table for error information.

656

Chapter 43: Problems With Metrics

A Metric Maintenance Task Fails to Run

If you manually run a metric maintenance task and it fails, Metric Studio displays an error message. If you run a scheduled metric maintenance task, you should check the run history to verify if the task was successful or not. For more information, see the Administration and Security Guide. To determine the cause of a failed task, check the logs located in installation_location/logs/DIS/package_date_time. The logs for each metric maintenance task are kept in a folder named with the task's package name, date, and time.

You Do Not Have Permission to Access This Metric Package. Contact Your System Administrator.
You must have Read, Execute, and Traverse permissions to open Metric Studio using the link on the Welcome page or in IBM Cognos Connection. Ask your system administrator to check your access permissions. For more information, see the Administration and Security Guide.

Failed to Check the Metrics Store Install Status Error When Using DB2 8.2.3
When you try to create a metric package using DB2 8.2.3 as the data source, you may receive the following error message: Failed to check the metrics store install status. If the version of the DB2 client on the Metric Studio computer is not the same version as the DB2 server, or you upgraded your DB2 instance, you must run commands to bind the DB2 client to the database. Run the commands on the Metric Studio computer. On Windows, run the commands in a db2cmd window from DB2InstallDir\sqllib\bnd. On UNIX, run the commands from DB2InstanceDir/sqllib/bnd. Type the following commands: db2 connect to database user userName db2 bind @db2ubind.lst blocking all grant public db2 bind @db2cli.lst blocking all grant public db2 bind db2schema.bnd blocking all grant public sqlerror continue db2 terminate

Errors Occur When Importing Tab-delimited Files into a DB2 Metric Store
When Metric Studio is installed on Windows and the DB2 metric store is installed on UNIX, errors occur when you run metric maintenance tasks to import tab-delimited files into the staging tables or into the metric store. The run history indicates that there were problems loading some of the tab-delimited files. The individual log files for the tab-delimited files indicate that the last column of the tab-delimited file data was truncated because it exceeded the target column width.

Administration and Security Guide 657

Chapter 43: Problems With Metrics Ensure that the tab-delimited files use end-of-line characters that are suitable for UNIX, such as a linefeed character and not the carriage return and linefeed character combination that is typically used by Windows.

Required User Permissions for the Metric Store Database (MS SQL Server)
The user account for the metric store database must be the database owner. You must use the owner user-account to log on to the IBM Cognos 8 data source used in the Metric Package. For information about setting user permissions, see the MS SQL Server documentation for the sp_changedbowner utility.

Error When Viewing a History Chart or Diagram on a DB2 Server with the 8.2 JDBC Driver
When the user tries to view a history chart or diagram, they see the following error: The IBM Cognos Gateway is unable to connect to the IBM Cognos BI server. The server may be unavailable, or the gateway may not be correctly configured. Please try again or contact your administrator. This problem is known to occur only when Metric Studio is installed on an HP/UX Itanium server. This problem is caused by a bug in the DB2 8.2 JDBC driver (APAR IY92903). IBM plans to fix this problem in FixPak 15. The only workaround for this problem is to use DB2 9.1.

Oracle 9.2 Package Initialization Error if NLS_LANG Environment Variable is Not Set Appropriately Before Starting Up IBM Cognos 8 Tomcat Server
You will encounter an exception error when trying to initialize a CMM package if the Oracle specific environment variable NLS_LANG is not set correctly. Workaround: IBM Cognos 8 requires that the Oracle specific environment variable NLS_LANG be set appropriately before starting up IBM Cognos 8 Tomcat server. Please ensure that the character set portion of this variable is set to UTF8. For example, in the United States, this may be something like AMERICAN_AMERICA.UTF8.

Known Issues When Using Metric Designer

The information in this section will help you resolve issues encountered when working with Metric Designer.

Adding Multiple IQD Files to an Import Source

When you add multiple IQD files to an import source, Metric Designer creates an outer join between the first pair of non-numeric, non-date columns with matching names. The join approach is designed to work with a single fact IQD file and with multiple dimension IQD files.

658

Chapter 43: Problems With Metrics Metric Designer does not recognize joins where more than one column is required for a join condition. In this case, enter the IQD files into Metric Designer as separate import sources or combine them into a single IQD using Impromptu.
440049

Previewed Scorecard Hierarchy Shows Blanks

If you use if () then () else () statements in an expression for level attributes, you will see blank entries when you preview the scorecard hierarchy. The workaround is to change the expression to cast the query item to VARCHAR. For example: if (cast([great_outdoors].[Locations].[Locations].[Country].[PPDS_CODE],VARCHAR(1000)) = 'Canada') then ('Craig') else ('George') if ( cast([great_outdoors].[Locations].[Locations].[Country].[Country] ,VARCHAR(1000)) = 'Canada') then ('Craig') else ('George') To eliminate duplicates for items other than 'Canada', you can add a level filter expression. For example: [great_outdoors].[Locations].[Locations].[Country].[Country] = 'Canada' or [great_outdoors]. [Locations].[Locations].[Country].[Country] = 'China'
508879

Administration and Security Guide 659

Chapter 43: Problems With Metrics

660

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service
Use this troubleshooting information to help solve problems you may encounter during or after the installation of IBM Cognos 8 for Microsoft Office, IBM Cognos 8 Go! Office, IBM Cognos 8 BI Analysis for Microsoft Excel, and Report Data Service (RDS) components. For more troubleshooting information search the Knowledge Base of the IBM Cognos Resource Center Web site (http://support.cognos.com/kb-app/knowledgebase).

Configuration Issues
The following issues are related to configuration and setup.

The IBM Cognos 8 for Microsoft Office Interface Fails to Initialize in Microsoft Office
IBM Cognos 8 for Microsoft Office may not initialize when the Microsoft .NET Framework is not installed or the version is not correct. The required Microsoft .NET Framework version is 2.0. Another possible reason for this condition is that the IBM Cognos 8 for Microsoft Office COM add-in is either not installed or not registered. If you are running the wrong version of Microsoft .NET Framework, uninstall it and then reinstall Microsoft .NET Framework version 2.0. To install the IBM Cognos 8 for Microsoft Office COM add-in, run the .msi program that is found on the installation disk. For more information, see the installation guide. Before you attempt to install Microsoft .NET Programmability Support, you must have installed Microsoft .NET Framework version 2.0.

IBM Cognos 8 Go! Office Does Not Start in Microsoft Word

You open an IBM Cognos 8 Go! Office session in Microsoft Word, but nothing appears to happen. This can occur if Microsoft Outlook has opened a session of Microsoft Word to edit email messages. To check whether you are using Word to edit email messages, in Microsoft Outlook, click Tools, Options, Mail Format. In the Message format section of the dialog box, verify the options for editing your email messages. To resolve this problem, close Microsoft Outlook before opening the Microsoft Word document configured for IBM Cognos 8 Go! Office.

Administration and Security Guide 661

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service

IBM Cognos 8 for Microsoft Office Fails to Initialize in Microsoft Internet Explorer
If you use Internet Explorer to browse IBM Cognos 8 and open a workbook, document, or presentation published by IBM Cognos 8 for Microsoft Office, the document launches in Microsoft Office, but without full functionality. To configure Internet Explorer to open Microsoft Office files in Microsoft Office instead of in Internet Explorer, you must use the Folder Options tool to update browse options. It is also possible to do this in Windows Registry.

Steps to Configure Internet Explorer to Open Microsoft Office Documents in Microsoft Office Applications
1. Open My Computer. 2. From the Tools menu, click Folder Options. 3. On the File Types tab, under Registered file types, click Microsoft Excel Worksheet, and then click Advanced. The Edit File Type dialog box appears. 4. Clear the Browse in same window check box and click OK. 5. Complete the same steps for Microsoft Office PowerPoint presentations and Microsoft Office Word documents.

bo:heap Buffer Overflow Error

After long sessions, Microsoft Office may stop responding by generating a bo:heap Buffer Overflow error. This error may be falsely identified as a potential virus by some virus-monitoring programs.

Microsoft Office Does Not Open a Microsoft Office Document Published from IBM Cognos 8 for Microsoft Office
If you observe Microsoft Office trying to open a published document twice when you double-click the workbook, document, or presentation from Windows Explorer, the file association is either corrupted or not installed properly. There are two options to resolve this issue. You can start the Microsoft Office application first, and then open the document using the Open command from the File menu, or you can reregister the file type.

Steps to Reregister Workbook File Types for Microsoft Office Excel

1. From the Start menu, click Run. 2. Type the following command and click OK. "C:\Program Files\Microsoft Office\Office\Excel.Exe" /regserver

662

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service You can adapt this command to your environment by providing the proper local drive and location.

Steps to Reregister Presentation File Types for Microsoft Office PowerPoint

1. From the Start menu, click Run. 2. Type the following command and click OK. "C:\Program Files\Microsoft Office\Office\Powerpnt.Exe" /regserver You can adapt this command to your environment by providing the proper local drive and location.

Steps to Reregister Document File Types for Microsoft Office Word

1. From the Start menu, click Run. 2. Type the following command and click OK. "C:\Program Files\Microsoft Office\Office\winword.exe" /regserver You can adapt this command to your environment by providing the proper local drive and location.

Unable to Open Published Microsoft Office Documents from IBM Cognos Connection
If the browser does not prompt you to open or save the workbook, document, or presentation, it may mean that the option to prompt before opening was cleared. Reset this option. You must enable the File Download and Automatic prompting for file downloads in Internet Explorer.

Steps to Confirm Opening of Documents

1. Start the Windows Control Panel. 2. Double-click Folder Options. 3. From the Folder Types tab, in the Registered file types list, click Microsoft Excel Worksheet, and then click Advanced. 4. Ensure that the Confirm open after download check box is selected and click OK. 5. Repeat steps 3 and 4 for other Microsoft Office documents that are supported in IBM Cognos 8 for Microsoft Office, such as Microsoft Office Excel Template, Microsoft PowerPoint Presentation, Microsoft Office PowerPoint Template, Microsoft Word Document, and Microsoft Office Word Template. 6. Click Close.

Steps to Reset Internet Security Options

1. Start Internet Explorer.

Administration and Security Guide 663

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service 2. From the Tools menu, click Internet Options. 3. From the Security tab, click the Web content zone for which you are updating these options, and then click Custom Level. 4. Scroll down to the Downloads section and click Enable for the File download and Automatic prompting for file downloads options. 5. Click OK twice.

Error Messages, the .NET shortcut, or the .NET Console Are Not in the Language of the .NET Framework 2.0 That Was Installed
When you install a non-English version of .NET Framework in a non-English operating system, you will notice that the error messages, .NET shortcut and .NET Console are in English. To solve this issue, you must apply the .NET Framework Language Pack for your language. The subkey numbers relate to the language as follows: 1033=en-en, 1036=fr-fr, 1031=de-de, and 1041=ja. If you are missing the language pack subkeys, you must install the .NET language pack, which is available from the Microsoft support Web site.

Workbook Closes Unexpectedly if the Name Contains a Square Bracket

If you install the COM add-in and your Microsoft Excel workbook name contains a square bracket, Excel stops responding or closes unexpectedly after opening. To resolve this problem, rename the workbook so that it does not contain square brackets.

The server committed a protocol violation. Section=ResponseHeader Detail=CR must be followed by LF

The EXCEL.EXE.config file is required and is missing. You must create the EXCEL.EXE.config file, copy it to the same location as IBM Cognos 8 BI Analysis for Excel and add the following lines: <?xml version="1.0" encoding="utf-8" ?> <configuration> <system.net> <settings> <httpWebRequest useUnsafeHeaderParsing="true" /> </settings> </system.net> </configuration>

664

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service

Reports Unavailable in IBM Cognos Connection Jobs after Using Save As Command in Report Studio
After opening a report in Report Studio and saving a copy using the Save As command, you may find that if the report is included in a job, it is not available in the IBM Cognos Connection portal. Do not use the Save As command in Report Studio to save changes when a report is included in a job. Instead, make a copy of the report, make changes to the copy, and then copy the updated report to the IBM Cognos Connection portal. Use this method to overwrite the report in the job without breaking the report links.

Unable to Correctly Display East Asian Characters

Your locale is set to one of the East Asian languages and odd characters or question marks appear in the user interface, dialog boxes, and menus. IBM Cognos 8 for Microsoft Office products support GB18030, which is a Chinese National Standard for encoding characters. To display Simplified Chinese characters properly on Windows XP or earlier, you must add GB18030 support for Windows core fonts and then enable font linking. To resolve this issue, after installing the language support for Simplified Chinese, ensure that you have linked the SimSun18030.ttc font collection to the following core fonts: Tahoma Arial Microsoft Sans Serif SimSun

For more information, see the installation guide for the specific product.

The Content of the Cell-based Report Shows #NAME?

When building a cell-based report in IBM Cognos 8 BI Analysis for Excel, the content of the cells shows #NAME? When you drag items from the source tree directly to the cells of a worksheet, you are creating a COGNAME or COGVAL formula that references the item in the database. This functionality is available only when the CognosOfficeUDF.Connect automation add-in is loaded. If #NAME? appears in the contents of the cell, it means that the add-in was not loaded and the CognosOfficeUDF.Connect check box in the Add-in dialog box (Tools, Add-Ins) is not selected. To resolve this issue and ensure that the add-in is always properly loaded, you must verify that the value of the OPEN registry key is set to /A "CognosOfficeUDF.Connect".

Steps
1. From the Windows Start menu, click Run. 2. In the Open box, type Regedit, and then click OK. 3. In the Registry Editor, go to the Registry branch:

Administration and Security Guide 665

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\version\Excel\Options 4. In the right pane, under Name, right-click OPEN, and then click Modify. 5. In the Value Data box, type /A "CognosOfficeUDF.Connect" 6. Click OK, and then close the Registry Editor.

Processing Issues
The following issues are related to processing and rendering reports.

Cannot Render this Report

The Report Data Service (RDS) cannot bring report elements into a Microsoft Office document. Some combinations of text and images are beyond the scope of the target application. To resolve this problem, evaluate the report and attempt to simplify the content requirements so that IBM Cognos 8 Go! Office can render the report.

RDS Data Limit Exceeded When Importing from Large Report Outputs
While attempting to import all or part of a large report, the application attempts to open the entire report. A provisional governor limit restricts the size of report output allowed and might result in an error (even if you are trying to import only part of a report). To resolve this problem, you can adjust the size limit for report data by changing the Governor limit setting.

Steps
1. Start IBM Cognos Connection. 2. In the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click Services, and then click Report Data. 5. Click the arrow next to ReportDataService to view the Action menu, and then click Set Properties. 6. Click the Settings tab. 7. In the Value column, change the number for Governor limit (MB), and then click OK.

RDS Server Unavailable

The IBM Cognos Report Data Service (RDS) manages the transfer of report data between IBM Cognos 8 and applications that consume the data, such as IBM Cognos 8 Go! Office.

666

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service To resolve this problem, restart RDS. RDS restarts when the IBM Cognos 8 service is restarted.

Steps to Restart the RDS Server

1. In a browser, connect to IBM Cognos 8 as an administrator. 2. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 3. On the Status tab, click System. 4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change View menu. Click Services, and then Report Data. 5. With the Report Data service displayed, click the arrow to view the Actions menu next to the service, and then click Start. 6. If RDS fails to start, or if IBM Cognos 8 is not responding, start IBM Cognos Configuration. 7. Choose whether to start or restart IBM Cognos 8. If IBM Cognos 8 is not running, click Start. If IBM Cognos 8 is running, click Restart.

Imported Reports Are Missing Charts or Images

IBM Cognos 8 Go! Office is functioning normally, but charts and images are missing. The client machine, which is running IBM Cognos 8 Go! Office, cannot connect to the gateway URL as configured in IBM Cognos 8. This may be because it is behind a firewall, the hostname/DNS is not known to this client machine, or the client machine has proxy issues. To resolve the connectivity issues, work with your system administrator.

#ERROR Appears in Cells with Multiple Images in a Cell (Excel Only)

Multiple images in a cell cannot be rendered. The solution is to reauthor the report to move each image to its own cell, then reimport the report.

The Dispatcher Is Unable to Process the Request. The Request Is Directed to an Unknown Service Name: Content
The IBM Cognos Report Data Service (RDS) cannot bring report elements into a Microsoft Office document. Some combinations of text and images are beyond the scope of the target application. To resolve this problem, evaluate the report and attempt to simplify the content requirements so that IBM Cognos 8 Go! Office can render the report.

Report Content is Not Imported

If the report name has a single quotation mark and the Create new worksheets for report pages option is selected, the report content is not imported.

Administration and Security Guide 667

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service To resolve this problem, you must rename the report without the single quotation mark.

Incorrect Format for the Prompt Value in Prompted Reports

When you refresh a prompted report using the Specified Value type, the prompt value does not display properly in the UseValue field. Not all prompt values are affected. Some of the prompt properties appear as expected while others may look like this:
[great_outdoors_company].[Products].[Products].[Product line]->:[PC].[@MEMBER]. [5~236]

In this example, the selected prompt value is "Golf Equipment" which is displayed properly in the Display Value prompt property. In cases where this occurs, you must know that the equivalent format in the Specified Value is the value with which you want to refresh the report. In the example, [great_outdoors_company]. [Products].[Products].[Product line]->:[PC].[@MEMBER].[5~236] is equivalent to Golf Equipment. To refresh the report, we recommend that you use the Always Prompt option. That way, users can select the value from the reports own prompt dialog box.

Steps to Select the Always Prompt Option

1. To view the report properties, from the Manage Data tab, click the report. 2. Expand the prompt properties. 3. In the Type box, click Always Prompt. 4. Refresh the report. The report refreshes with the requested parameters. Note: This does not affect the import of prompted reports.

DPR-ERR-2079 Firewall Security Rejection

If you run a report after your session has expired and then try to navigate away from the first page of the report, you encounter the following error message: DPR-ERR-2079 Firewall Security Rejection. Your request was rejected by the security firewall. CAF rejection details are available in the log. Please contact your administrator. To resolve this problem, after an expired session, you must log on again.

Steps to Log On
1. In the report list, right-click the top node item. 2. Click Log On. 3. Provide your authentication credentials as prompted and click OK.

668

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service

This item cannot be expanded. Microsoft Excel has reached the maximum number of rows or columns for this worksheet
The number of rows and columns is limited in Microsoft Excel. Expanding the current item is not possible because it would shift rows or columns beyond this worksheet limit. Microsoft Office Excel cannot shift nonblank cells off the worksheet. Manually move items so that the row or column item can expand without reaching the limit, or move your exploration or analysis to another worksheet. Or, you can move the data to a new location and try again.

Prompted to Log on for Each Imported Report

When refreshing all data in a document before logging on to the required servers, you are automatically prompted to log on for each report in the document even if the reports originate from the same server. To log on only once to each server, use the Log On toolbar button to log on to the required servers before refreshing report data.

Object reference not set to an instance of an object

An internal processing error occurred. Initialization of a critical process failed. Contact IBM Cognos Resource Center. Be ready to supply all relevant logs and details related to this error.

Error 0:RSV-BBP-0027 The Secondary Request Failed

When you create a list report and you use the More or All option to view members, you get the following error: Error 0: RSV-BBP-0027 The secondary request failed. The requested session does not exist and failover has been disabled. Contact your Administrator. To resolve this issue, increase the number of rows that you can display on the worksheet.

Steps
1. On the IBM Cognos 8 for Microsoft Office toolbar, click the Options button 2. In the left navigation pane, IBM Cognos 8 BI Analysis. 3. Under Exploration Settings, in the Data Display Row Limit box, increase the number of rows so that you can display more or all of the remaining members in the list, and then click OK. .

Security Issues
The following issues are related to security setup.

Administration and Security Guide 669

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service

IBM Cognos 8 for Microsoft Office Unable to Create Trust Relationship

If you are using HTTPS to RDS and you receive an error in IBM Cognos 8 for Microsoft Office about being unable to trust the relationship, the Certificate Authority (CA) certificate that was issued by the Web server is not trusted on the client workstation. To resolve this problem, you must ensure that the Certificate Authority (CA) that issued the Web server certificate is also trusted on the client workstation. If the certificate is not from an authority that is already trusted on the client, such as Verisign, you must install the CA certificate in the trust store on the client.

Steps to Ensure that the CA Certificate is Trusted on the Client Workstation

1. Retrieve the CA certificate from the issuing authority. The file has a .cer extension. This is not the same certificate as the one used by the Web server. It is the certificate for the issuing authority itself. 2. Double-click the .cer file, click Install Certificate, and then click Next. 3. Click Place all certificates in the following store. 4. Click Browse, click Trusted Root Certification Authorities, and then click Next. 5. Click Finish.

Unable to View Reports After Clicking View Report

IBM Cognos 8 Go! Office is functioning normally, but you cannot use the View Report option to view reports. The client machine, running IBM Cognos 8 Go! Office, cannot connect to the gateway URL as configured in IBM Cognos 8. It is behind a firewall, the hostname/DNS is not known to this client machine, or the client machine has proxy issues. To resolve the connectivity issues, work with your system administrator.

Report Data Service (RDS) Numbered Error Messages

The following error messages may appear in a dialog box and are recorded in the server log, which is located at <IBM Cognos 8 installation location>/logs/cogserver.log.

RDS-ERR-1000 Report Data Service Could Not Process the Response from the Content Provider
The cause for this error varies based on the application server. In WebSphere, this error occurs if another XML parser, such as Xalan is colliding with the one RDS uses. In BEA WebLogic, this error occurs if the JAVA_OPTIONS variable has not been set with the correct parser information. This error can also occur if a package from a previous version of IBM Cognos 8 (or ReportNet) was deployed to IBM Cognos 8 without the report specifications being upgraded. 670

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service Another possible reason for this error message is that RDS cannot handle the report. For example, this error occurs if a Report Studio report contains a block with either of the following: a repeater or repeater table inside a block or a table a layout object, such as a list, crosstab, chart, or text object in a conditional block inside another block or a table

Set the Class Loader Policy in WebSphere

For WebSphere, the best solution is to set the Class loader policy to PARENT_LAST. The WebSphere documentation tells the administrator how to do this.

Set the JAVA_OPTIONS Variable in WebLogic

If you are accessing IBM Cognos 8 Go! Office through IBM Cognos 8 on a BEA WebLogic Application Server add the following to the JAVA_OPTIONS variable of the startManagedWebLogic. cmd (Windows) or startManagedWebLogic.sh (UNIX) script file: -Dorg.xml.sax.driver=org.apache.xerces.parsers.SAXParser

Upgrade Report Specifications

Follow the steps for "Upgrading Report Specifications" in the IBM Cognos 8 Administration and Security Guide.

Edit the Report

To avoid problems with report layout, you must modify the report by performing one of the following: Take the repeater or repeater table out of the block or table. Cut the layout object from the conditional block into a new conditional block, block, or table.

RDS-ERR-1001 The PowerPlay Report Name Could Not Be Run. The Expected Response Was Not Returned by PowerPlay
PowerPlay failed while running the report or RDS cannot understand the output. To resolve this problem, ensure that PowerPlay is functioning properly. The user should check to see that the PowerPlay server is running, or check the PowerPlay logs for errors. If IIS is being used for the Web server, ensure that Anonymous Access is enabled. For more information, see the IBM Cognos 8 Installation and Configuration Guide.

RDS-ERR-1004 A Connection Could Not Be Established with IBM Cognos 8

IBM Cognos 8 is not responding. Check the IBM Cognos 8 logs. Ensure that IBM Cognos 8 is functioning properly.

Administration and Security Guide 671

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service

RDS-ERR-1005 The Logon Requirements for IBM Cognos 8 Could Not Be Obtained. You May Already Be Logged into this Namespace, or the Target Namespace Does Not Exist
Generally, this error occurs when trying to log on to the same namespace twice. In some cases, it may indicate a problem with a security setup such as SiteMinder. Ensure that you are not already logged in.

RDS-ERR-1012 IBM Cognos Content Service was Unable to Discover the Content Providers
This error usually appears in conjunction with RDS-ERR-1028 and means that RDS could not communicate with any PowerPlay providers. (RDS-ERR-1028 can occur separately if there is more than one PowerPlay server, and only one has failed). Check that all instances of PowerPlay Enterprise Server are running properly.

RDS-ERR-1013 Report Data Service Was Unable to Query Content Manager

Content Manager is not responding. Ensure that Content Manager is running. Check the server log for error messages related to Content Manager.

RDS-ERR-1014 Report Data Service Was Unable to Create the Document Object Object Name
Content Manager is not responding. Ensure that Content Manager is running. Check the server log for error messages related to Content Manager.

RDS-ERR-1015 Report Data Service Was Unable to Create a New Document Version
Content Manager is not responding. Ensure that Content Manager is running. Check the server log for error messages related to Content Manager.

RDS-ERR-1016 Report Data Service Was Unable to Create a New Document Content Object
Content Manager is not responding. Ensure that Content Manager is running. Check the server log for error messages related to Content Manager.

672

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service

RDS-ERR-1018 The IBM Cognos 8 Report Name Could Not Be Run. The Expected Response Was Not Returned by IBM Cognos 8
An error was returned by IBM Cognos 8 when the report was run or refreshed. One of the following may be the cause: PowerPoint does not contain the necessary facilities to recreate the rich formatting and layout of this report. Check the IBM Cognos 8 error log for troubleshooting information. If the report in question was not able to be rendered, adjust the report to remove the formatting and layout to expose the data in PowerPoint, where you can modify formatting and layout. You tried to refresh a Series 7 PowerPoint report that was migrated to IBM Cognos 8. Series 7 content is no longer accessed from the Series 7 PowerPlay Enterprise Server, and the IBM Cognos 8 Report Data Service (RDS) is attempting to resolve the path of the PowerCube datasource. In IBM Cognos 8 Go! Office, ensure that the value of the Search Path property of the report matches the search path of the same report that was migrated to IBM Cognos 8 and published to IBM Cognos Connection. For more information, see the IBM Cognos 8 Go! Office User Guide. For prompted reports in IBM Cognos 8 Go! Office using Microsoft Excel, if you have set, in the Properties pane, prompt values to be retrieved from a cell reference and the value in the cell reference is invalid for the prompt, you receive this error message. We recommend that you select Always Prompt as this is the best practice for prompted reports. For more information, and to determine if this is the exact cause for this error message, see the IBM Cognos 8 server log file. Search for this error message, RDS-ERR-1018 and then look for error messages similar to the following: "Failure QFS-ERR-0139 The request has multiple errors. RQP-DEF-0354 The query contains one or more unresolved prompts. QE-DEF-0385 Invalid format for prompt 'Parameter1'. Expected format is unknown."

RDS-ERR-1019 IBM Cognos Content Service Was Unable to Retrieve the Portal Information from IBM Cognos Connection
IBM Cognos 8 may have stopped processing. Ensure that IBM Cognos 8 is started.

RDS-ERR-1020 The Currently Provided Credentials are Invalid. Please Provide the Logon Credentials
Your user name and password are not correct. Ensure that you typed a valid user name and password.

Administration and Security Guide 673

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service

RDS-ERR-1021 The IBM Cognos 8 Report Name Could Not be Run Because it Contains Unanswered Prompts. Please Provide the Prompt Answers, and Run the Report Again
The report has prompts that have not been set. You must open the report and then save a version of the report with the desired prompt answers before importing the content into IBM Cognos 8 Go! Office.

RDS-ERR-1022 The Request Received by Report Data Service Is Not Valid

This error message could indicate that someone is trying to externally access RDS. Stop and restart RDS.

RDS-ERR-1023 The Report Name Could Not Be Run Because It Exceeds the Report Data Service Data Size Limit Set by the Administrator
A report fails because it exceeds the data size limit set by the administrator. The default limit for IBM Cognos 8 Go! Office is 10 MB. Increase the size limit for report data by changing the Governor limit setting. For more information, see the IBM Cognos 8 Administration and Security Guide.

RDS-ERR-1027 The Encoding for the PowerPlay Server Name Could Not Be Determined. ISO-8859-1 Will Be Used as the Encoding
This condition can be caused if PowerPlay is not responding. Ensure that PowerPlay is started and functioning properly.

RDS-ERR-1030 A Security Error Occurred While Trying to Establish a Connection with Name
The CA certificate was not installed into RDS. Install the CA certificate.

RDS-ERR-1031 Report Data Service was unable to retrieve the metadata for Name
The provider, such as IBM Cognos 8 or PowerPlay is not responding. Ensure that IBM Cognos 8 or PowerPlay is running. Check the server log for error messages related to these providers.

RDS-ERR-1033 Report Data Service Was Unable to Create the Report View Name
Content Manager is not responding. Ensure that Content Manager is running. Check the server log for error messages related to Content Manager.

674

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service

RDS-ERR-1034 The Report Specification for Name Could Not Be Retrieved From IBM Cognos 8
This message occurs if the metadata could not be retrieved from IBM Cognos 8. Ensure that IBM Cognos 8 is running. Check the server log for error messages related to IBM Cognos 8.

RDS-ERR-1039 The Request Could Not Be Cancelled. The Request is No Longer Running
This error occurs if a user (or administrator) tries to cancel an RDS request, but the request no longer exists. This can happen if the user clicks Cancel after the administrator has already restarted RDS. Wait for RDS to restart.

RDS-ERR-1040 The Conversation With Conversation ID Has Been Cancelled

This message appears in the audit log if a request is cancelled by either the user or by the administrator. Users can cancel their own requests. Administrators cannot cancel specific requests, but can cancel all requests by stopping and restarting the service. Stop the service and abandon all running requests.

Steps
1. In IBM Cognos Connection, in the upper-right corner, click Launch, IBM Cognos Administration. 2. On the Status tab, click System. 3. In the upper-left corner of the Scorecard pane, click the arrow to view the Change View menu. Click Services, and then Report Data. 4. With the Report data service displayed, click the arrow to view the Actions menu next to the service, and then click Stop immediately. By using this method, RDS supports canceling long running requests, such as running a report.

RDS-ERR-1044 The Output for the Requested Version for Object NameCould Not be Retrieved
The report output version that you want to run cannot be retrieved from the content store. This problem can be caused by one or more of the following: the requested report version name, specified burst key, or burst ID, does not exist the requested version does not have any outputs that meet any of the accepted formats, such as XML, PDF, or HTML The report author did not specify a default format to be used when the report is run. you do not have sufficient access permissions to retrieve this output Administration and Security Guide 675

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service To run the report, you must have execute permission for the report and traverse permissions for the folder that contains the report.

RDS-ERR-1045 LayoutDataXML Output Was Not Generated for the Requested Version for Object [Name]
The report version you want to run exists in the content store, but was not saved with the LayoutDataXML output. When the report output version was saved, the report author must have selected the Enable enhanced user features in saved output version check box in IBM Cognos Connection. For more information, see the IBM Cognos Connection User Guide.

IBM Cognos 8 Go! Office Numbered Error Messages

The following error messages may appear in a dialog box and are recorded in the IBM Cognos 8 Go! Office log.

COC-ERR-1003 Failed to Create Slide

You cannot add a new slide in the wizard. Microsoft Office PowerPoint is in a state that it cannot add a slide. Exit the wizard and attempt to create a slide manually in Microsoft Office PowerPoint.

COC-ERR-1302 There Is No Data Source Available

IBM Cognos 8 Go! Office cannot connect to the Report Data Service (RDS). Check for connectivity issues.

COC-ERR-2005 The Import Failed

An unknown issue caused the import of report content to fail. Other possibilities may include the logon requirements for IBM Cognos 8 are not available. You may already be logged onto this namespace, or the target namespace does not exist. protection for the Excel workbook structure exists The protection prevents users from adding or deleting worksheets or from displaying hidden worksheets. Check that your report uses standard practices. Revise and resave the report, ensuring that text and images are not located in the same cell. If the workbook structure is protected, ensure that the Structure check box in the Protect Workbook dialog box is cleared. In Excel, from the Tools menu, click Protection, and then click Protect Workbook. In the Protect Workbook dialog box, clear the Structure check box, and then click OK.

676

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service

COC-ERR-2006 Failed to Load the Portal Tree: Name

This error occurs while attempting to log onto the IBM Cognos 8 Server from an IBM Cognos 8 Go! Office session. You must install .NET Framework v2.0. This can be a connectivity issue. It may also mean that the IBM Cognos 8 service has stopped. As documented in the IBM Cognos 8 Installation and Configuration Guide, to deploy IBM Cognos 8 Go! Office, you must first install Microsoft .NET Framework version 2.0 on the client workstation. If you have already installed the required Microsoft .NET framework, check for LAN connectivity issues. Restart the IBM Cognos 8 service.

COC-ERR-2012 Failed to Render the List

A cell style or cell format in the Microsoft Office Excel workbook is not compatible with the data that you are attempting to import, or you are attempting to import content to a locked range. Ensure that the range is valid and not locked, and that the style of the cell in the Microsoft Office Excel workbook is compatible with the style in IBM Cognos 8.

COC-ERR-2013 This Is an Unsupported Office Application

IBM Cognos 8 Go! Office supports the following Microsoft Office applications: Microsoft Office Excel Microsoft Office Word Microsoft Office PowerPoint

You cannot load IBM Cognos 8 Go! Office content to another Microsoft Office application, such as Microsoft Access, even when there is an add-in that enables these applications to interoperate. Load the report content into one of the supported applications and environments. For a complete listing of supported Excel, Word, and PowerPoint versions, see the IBM Cognos Resource Center Web site.

COC-ERR-2014 Refresh Failed

IBM Cognos 8 Go! Office cannot refresh report content. Another error message should indicate why. If there is no other error message, the problem is outside IBM Cognos 8 Go! Office. This may indicate a system problem, a server malfunction, or no LAN connectivity. Attempt to refresh the content again. Check system and server functions.

COC-ERR-2015 Failed to Open the Import Wizard Dialog

When the IBM Cognos 8 Go! Office Import Content wizard loads, it pages through the report and populates the tree and creates a page for each report element. If an unexpected error occurs in the report, this error is logged. Try importing the report again. If it fails, open the report in the studio in which is was created and save the report. Check the log file for more detailed information. Administration and Security Guide 677

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service

COC-ERR-2019 Failed to Refresh an Image

The image could not be rendered because the Microsoft Windows Clipboard is locked. Wait until the clipboard operation finishes. You may need to finish clipboard activity in another application before trying to refresh the content.

COC-ERR-2301 Logon Failed

Your user name and password are not correct. Ensure that you entered a valid user name and password.

COC-ERR-2303 This Report Is Not Valid for Rendering

IBM Cognos 8 Go! Office cannot render a top report, where a report is nested within another report. Take the report out of its nested report and resubmit the request.

Steps
1. Redesign the report. 2. Resave the report. 3. Import the resaved report into IBM Cognos 8 Go! Office.

COC-ERR-2304 This Is a Prompted Report. It Is Not Currently Supported

Depending on the version of IBM Cognos 8 Go! Office and the type of report, some prompting may not be supported. Modify the report so that prompting can take place at the same time using a prompt sheet, or try to establish defaults for the prompts based on user privileges. You can also save the report with prompt values.

Steps to Save the Report with Prompt Values

1. Using IBM Cognos 8 or PowerPlay Web, run the report. 2. Save the report view. 3. In IBM Cognos Connection, click Properties for the report view that you saved. 4. Click the Run Options tab. 5. Under Prompt Values, click Set the prompt values. 6. Provide the prompt answers. 7. Click OK.

678

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service

COC-ERR-2305 Microsoft Excel Returned an Error. Ensure That Microsoft Excel is Not in Edit Mode, Then Try Again
Report content cannot be refreshed while one of the cells of the workbook is being edited. Click outside the active cell to return it to a non-edit mode and try again.

COC-ERR-2308 Report Specification is Empty

The report you attempted to import into IBM Cognos 8 Go! Office has no content. To import a report, it must have content. Choose another report to import, or finish authoring the report before attempting to import it.

COC-ERR-2603 You Must Add a Slide to the Presentation Before Importing Any Content
The presentation has no slides. IBM Cognos 8 Go! Office requires at least one slide in the presentation for the Import Content wizard to start. Add a slide to the presentation and then try to import report content again.

COC-ERR-2604 Cannot Render Empty List Object

The list object you selected for import was empty. IBM Cognos 8 Go! Office cannot import an empty list object. Open the report and populate the list object with data before attempting to import the content into IBM Cognos 8 Go! Office.

COC-ERR-2607 Microsoft Office Message

During initialization, you receive an error, COC-ERR-2607, and, in some instances, a Microsoft Office message, such as: File or assembly name Microsoft.Office.Interop.ApplicationName, or one of its dependencies, was not found. This error indicates that a required application or the .NET support for one of the required Microsoft Office applications is not installed. Microsoft Office Excel, PowerPoint, and Word, and Microsoft .NET Programmability support for all three of these applications is required for IBM Cognos 8 Go! Office to work properly. Ensure that you have installed all three Microsoft Office applications and that the Microsoft .NET support is enabled. For more information, see the IBM Cognos 8 Installation and Configuration Guide.

COC-ERR-2609 The Custom property "Property_Name" does not exist

You have imported a prompted report and have specified a name for Custom Property in the Properties pane that does not match the custom document property name in the Microsoft Office Properties dialog box.

Administration and Security Guide 679

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service In IBM Cognos 8 Go! Office, in the Properties pane, for each prompt, ensure that the value specified in the Custom Property box, matches the value specified in the custom document property in the Microsoft Office Properties dialog box (File, Properties, Custom tab). Ensure that there are no leading and trailing character spaces in the name of the custom document property. For more information, see the IBM Cognos 8 Go! Office User Guide.

IBM Cognos 8 for Microsoft Office Numbered Error Messages

The following error messages may appear in a dialog box and are recorded in the IBM Cognos 8 for Microsoft Office log.

COI-ERR-2002 Block type is not valid

An internal processing error occurred. The block object was not able to be processed. Contact IBM Cognos Resource Center. Be ready to supply all relevant logs and details related to this error.

COI-ERR-2005 This Version of Microsoft Office Is Not Supported

IBM Cognos 8 for Microsoft Office supports the following Microsoft Office applications: Microsoft Office Excel 2003 or 2007 (Professional or Standard), Microsoft Office Excel XP, Microsoft Office Word 2003 or 2007 (Professional or Standard), Microsoft Office Word XP, Microsoft Office PowerPoint 2003 to 2007, and Microsoft Office PowerPoint XP. You cannot load IBM Cognos Office content to another Microsoft Office application, such as Microsoft Access even when there is an add-in that enables these applications to interoperate. Load the report content into one of the supported applications and environments.

COI-ERR-2006 This Microsoft Office Product Is Not Supported

IBM Cognos 8 for Microsoft Office supports the following Microsoft Office applications: Microsoft Office Excel 2003 or 2007 (Professional or Standard), Microsoft Office Excel XP, Microsoft Office Word 2003 or 2007 (Professional or Standard), Microsoft Office Word XP, Microsoft Office PowerPoint 2003 to 2007, and Microsoft Office PowerPoint XP. You cannot load IBM Cognos Office content to another Microsoft Office application, such as Microsoft Access even when there is an add-in that enables these applications to interoperate. Load the report content into one of the supported applications and environments.

COI-ERR-2008 Unable to Retrieve from Resources. Tried '{0}'

An internal processing error occurred. Contact IBM Cognos Resource Center. Be ready to supply all relevant logs and details related to this error.

680

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service

COI-ERR-2009 Unable to Perform This Operation Because Microsoft Excel is in Edit Mode
Report content cannot be refreshed while one of the cells of the workbook is being edited. Click outside the active cell to return it to a non-edit mode and try again.

COI-ERR-2010 The Name {0} is Not Valid. A Name Must Not Contain Both a Quote (") Character and an Apostrophe (') Character
When you create a folder, rename a folder, or publish a document, the name can contain an apostrophe or a quote, but not both. To resolve this problem, rename the folder or document. Exclude the apostrophe or quote character from the name.

COI-ERR-2011 The server did not return the expected response. Check that the gateway is valid.
This error message is displayed if the value entered in the System Gateway URI box of the Options dialog box is not a valid IBM Cognos 8 server. To resolve this problem, reenter the System Gateway URI with the gateway address for a valid IBM Cognos 8 server.

IBM Cognos 8 BI Analysis for Microsoft Excel Numbered Error Messages

The following error messages may appear in a dialog box and are recorded in the IBM Cognos 8 for Microsoft Office log.

COR-ERR-2002 Block Type is Not Valid

An internal processing error occurred. An exploration may have experienced an anomaly. Reset the exploration and try to reconstruct your analysis. If the problem continues, contact IBM Cognos Resource Center.

COR-ERR-2005 Block Specification is Not Valid or Missing "{0}"

An internal processing error occurred. An exploration may have experienced an anomaly. Reset the exploration and try to reconstruct your analysis. If the problem continues, contact IBM Cognos Resource Center.

COR-ERR-2006 Unexpected Type: [Stacked Block]

IBM Cognos 8 BI Analysis for Microsoft Excel was not able to render the data block in the rows and columns of the worksheet. An internal processing error occurred. Contact IBM Cognos Resource Center.

Administration and Security Guide 681

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service

COR-ERR-2007 Error Retrieving from Resources. Tried '{0}'

The exploration experienced a bad state. Contact IBM Cognos Resource Center.

COR-ERR-2009 Name Formula is Not Valid

The COGNAME formula did not parse correctly. It may have been altered manually and may have a missing argument. Check the COGNAME formula in the active cell and ensure that it is in the right format, or optionally, redrag the member from the source tree.

COR-ERR-2010 Formula is Not Valid

If an argument to a COGNAME or COGVAL formula references a cell and that cell does not contain the expected string formula you receive this error. Check the cell and its dependents. Look for #REF or #VALUE in the cell. The contents of the cell may have accidentally been deleted.

COR-ERR-2011 Prompted Metadata Is Not Supported

IBM Cognos 8 BI Analysis for Microsoft Excel does not support prompts. You receive this error message when a package that contains prompts loads or when selecting or expanding members in the source tree of a package with prompts. You must choose a package that does not have prompts.

COR-ERR-2012 Unable to Load Metadata

A request was made to the IBM Cognos 8 BI Server for metadata but it was unable to supply the requested items. Attempt the same request in Analysis Studio or Report Studio to see if you get the same result, then contact Cognos Software Services.

COR-ERR-2013 Exploration Cannot Be Converted to Formula Based Because at Least One Context Item Contains a Selection
With more than one item in the Context drop zone there is no way for the multiple items to be rendered into the cells of the worksheet. Remove one dimension from the Context drop zone. You must have one item per dimension to convert to a formula-based analysis.

COR-ERR-2014 Due to Excel worksheet limitations the results may be truncated

If the data that you receive back has more than 250 columns or more that 65,500 rows and you are not using Microsoft Excel 2007, the result is truncated. You receive this message to make you aware of the truncation. To avoid this limitation, limit your data selections. 682

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service

COR-ERR-2015 Exploration Cannot Be Converted to Formula Based Because There is a Default Measure and a Measure on Either Rows or Columns
IBM Cognos 8 BI Analysis for Microsoft Excel does not support the mixed case of measures. Remove the default measure or the measure on either rows or columns.

Step
To remove measures from an exploration, on the Exploration bar, Ctrl+click the Reset to blank exploration button.

COR-ERR-2016 Unable to Retrieve Package Name

After you selected a package using the Open Package dialog box, an error occurred when trying to download the package from the server. This is an internal error. You must contact Cognos Software Services.

COR-ERR-2017 The Current Selection Did Not Return Any Data

Your selections in the source tree did not result in any data. The exploration is cleared or returned to the previous state. To display items in the worksheet, you must select objects from the source tree that intersect on data points.

Administration and Security Guide 683

Chapter 44: Troubleshooting IBM Cognos 8 for Microsoft Office and the Report Data Service

684

Appendix A: Round Trip Safety Configuration of Shift-JIS Characters

Shift-JIS is a character encoding system for Japanese characters. It is equivalent to ASCII, a character encoding system for English characters.

Native Encoding and Unicode

Because Shift-JIS and ASCII both define characters for one language, they are native encoding systems. Unicode is a character encoding system that defines characters for all languages. Because software is used in a global, multilingual environment, characters for processing by computers must often be converted between native encoding systems and Unicode.

Round Trip Safety

Issues associated with conversions between native encoding systems and Unicode are referred to as round trip safety issues. Using Unicode, applications are developed that can handle input from different languages at the same time. Input data, which is entered by users or retrieved from databases, may contain characters encoded in a native encoding system. For example, in Windows, English characters input by a user are encoded using Windows-1252. When an application receives characters in a native encoding system, it converts the characters into Unicode for processing. After the processing is finished, the characters may be converted back into the native encoding system. In most cases, the characters are converted without ambiguity because each native character is mapped to a single Unicode character. If the conversion of a native language character to and from Unicode results in the original character, the character is considered round trip safe. For example, the character "A" is round trip safe in Windows-1252, as follows: The Windows-1252 character for "A" is 0x41. It converts to Unicode U+0041. No other Windows-1252 character converts to the same Unicode character, so it always converts back to 0x41.

Issues Specific to Shift-JIS

Although the characters from most native character encoding systems are round trip safe, the ShiftJIS encoding system is an exception. Approximately 400 characters in Shift-JIS are not round trip safe because multiple characters in this group can be mapped to the same Unicode character. For example, the Shift-JIS characters 0x8790 and 0x81e0 both convert to the Unicode character U+2252.

Administration and Security Guide 685

Appendix A: Round Trip Safety Configuration of Shift-JIS Characters

IBM Cognos 8 and Shift-JIS

IBM Cognos 8 uses Unicode. The round trip safety of characters is essential to ensure the accuracy of data in generated reports. The Round Trip Safety Configuration utility (p. 686) ensures the round trip safety of Shift-JIS characters only when it is used both to convert characters: from Shift-JIS to Unicode from Unicode to Shift-JIS

If data is requested from a database that has its own automatic mechanism for Shift-JIS to Unicode conversion, IBM Cognos 8 does not call the Round Trip Safety Configuration utility to convert the characters from Unicode to Shift-JIS. The round trip safety of characters in the data cannot be ensured.

Example: Safe Conversion of Shift-JIS

The following example illustrates the problem with Shift-JIS conversion to Unicode: A database contains characters encoded in Shift-JIS. A record in the database contains the Shift-JIS character 0x8790. A user enters the Shift-JIS character 0x8790 into a data entry form in a browser. The application receives the input form and converts the Shift-JIS character 0x8790 to the Unicode character U+2252. Because the database contains Shift-JIS encoded characters, the Unicode character U+2252 cannot be specified as part of the query. The application must convert U+2252 back to a Shift-JIS character. Both 0x8790 and 0x81e0 convert to U+2252. If the conversion process selects 0x81e0, the query returns no records.

To resolve this problem, you can use the Round Trip Safety Configuration utility to ensure that conversion is to 0x8790 and the record is found.

The Round Trip Safety Configuration Utility

You can use the Round Trip Safety Configuration utility to configure the conversion process of Shift-JIS characters so that IBM Cognos 8 always returns the right records. This utility gives you control over the following two situations: More than one Shift-JIS character converts to the same Unicode character. If your data contains such Shift-JIS characters, you can use the utility to specify that the Unicode character always converts to the required Shift-JIS character (p. 687). More than one Unicode character represents the same or similar character after conversion.

686

Appendix A: Round Trip Safety Configuration of Shift-JIS Characters Such Unicode characters can be considered identical when processed by computers and can be substituted for one another. You can use the utility to ensure that the correct substitution is made (p. 688).

Specify Conversions
If your data contains more than one Shift-JIS character that converts the same Unicode character, use the Round Trip Safety Configuration utility to specify that the Unicode character always converts to the required Shift-JIS character.

Conversion Tab
On this tab, native encoding characters appears in the form 0xYYYY, and Unicode characters appear in the form U+YYYY, where YYYY represents the hexadecimal value of the Unicode character. For example, the character "A" appears as follows: for native encoding, 0x41 for Unicode, U+0041

Each row represents a mapping rule that associates two or three Shift-JIS characters with the Unicode character in the first column. By default, all Shift-JIS characters in a row are converted to the associated Unicode character. For example, the Shift-JIS characters 0x8782 and 0xFA59 both convert to the Unicode character U+2116. You can configure more than one character at a time.

Prerequisite
Before you choose the Shift-JIS character to use in a conversion, determine which Shift-JIS character is currently used in the environment. Only one of the possible Shift-JIS equivalents of a Unicode character can be used in a specific environment.

Steps
1. Start the Round Trip Safety Configuration utility in the c8_location/ bin: for Windows, rtsconfig.exe for UNIX, rtsconfig

2. Click the Conversion tab. Tip: To see the glyph next to the Unicode character, from the View menu, click Glyphs. Depending on the type and size of fonts you use, some glyphs may not be visible. 3. From the Edit menu, click Find a character, and then enter the hexadecimal value of the ShiftJIS character. 4. Click OK. 5. In the First Shift-JIS Character, Second Shift-JIS Character, or Third Shift-JIS Character column, select the Shift-JIS character that you want the Unicode character to convert to. Administration and Security Guide 687

Appendix A: Round Trip Safety Configuration of Shift-JIS Characters 6. Repeat steps 3 to 5 for each Shift-JIS character that you want to configure. 7. Save your specifications using one of the following methods: To only save your specifications, from the File menu, click Save. To save and apply your specifications, from the Tools menu, click Configure.

If you save only, you can apply your specification later (p. 689). You can also restore default settings (p. 689). The specifications are saved in the file shift-jis.xml in the c8_location/bin directory.

Specify Substitutions
After the conversion, the Unicode data may contain characters that are identical in meaning, but different in appearance. For example, a full-width tilde (~) and a half-width tilde have different values in Unicode, but can be considered identical during processing. You can use the Round Trip Safety Configuration utility to specify that specific pairs of similar characters be substituted by a single character. For example, you can specify that both widths of tilde are substituted by a full-width tilde.

Substitution Tab
On this tab, the first column contains pairs of characters that generally mean the same thing, but are represented by different values in Unicode. Each row represents a substitution rule. The first column lists the data before conversion. The second column lists the possible replacement characters.

Steps
1. Start the Round Trip Safety Configuration utility in the c8_location/ bin: for Windows, rtsconfig.exe for UNIX, rtsconfig

2. Click the Substitution tab. Tip: To see the glyph next to the Unicode character, from the View menu, click Glyphs. Depending on the type and size of fonts you use, some glyphs may not be visible. 3. In the Original Code column, click the character that you want to substitute. 4. In the Substitute Code column, click the equivalent character. A list of possible substitution options appears. 5. In the list, click the Unicode character that you want to use, or click Do not substitute. 6. Repeat steps 3 to 5 for each Unicode character that you want to substitute. 7. Save your specifications using one of the following methods: To only save your specifications, from the File menu, click Save. To save and apply your specifications, from the Tools menu, click Configure.

688

Appendix A: Round Trip Safety Configuration of Shift-JIS Characters If you only save, you can apply your specification later (p. 687). You can also restore default settings (p. 689). The specifications are saved in the file shift-jis.xml in the c8_location/bin directory.

Apply the Conversions and Substitutions

If you do not apply changes when you save, you can apply the data later. Based on information saved in the file c8_location/bin/shift-jis.xml, two files are generated: for substitution data, i18n_res.xml for conversion data, ibm-943_P14A-2000.cnv

When you apply the data, by default, characters are not checked for round trip safety. When you set the configuration mode, you may choose to check for round trip safety by selecting the option that returns a conversion error at run time for characters that are not round trip safe. This can be useful to initially detect which Shift-JIS characters must be configured.

Steps
1. Stop IBM Cognos 8. 2. In the Round Trip Safety Configuration utility, from the Tools menu, click Set the configuration mode. 3. Specify whether you want characters checked for round trip safety. 4. From the Tools menu, click Configure. 5. Start IBM Cognos 8.

Restore the Default Conversion Settings

At any time, you can quickly restore the default settings in your configuration and substitution data. For example, you may want to restore the configuration in the following situations: after your application is set to use a different data source that requires a different configuration after prototyping

Steps
1. Stop IBM Cognos 8. 2. In the Round Trip Safety Configuration utility, from the Tools menu, click Restore defaults. The conversion process is set to use the default values. 3. Start IBM Cognos 8.

Administration and Security Guide 689

Appendix A: Round Trip Safety Configuration of Shift-JIS Characters

Specify Conversions for Series 7 PowerPlay Web Reports

IBM Cognos Series 7 supplies a limited solution for the Japanese Vendor Defined Characters (VDC) in Shift-JIS encoding. To ensure data integrity and consistency when using PowerPlay Web reports with IBM Cognos 8, you must set the character mapping to default values.

Steps
1. Stop IBM Cognos 8. 2. Start the Round Trip Safety Configuration utility (p. 686). 3. From the Tools menu, click Restore defaults. 4. From the Tools menu, click Configure. The conversion tables are set to use the default values in the background. 5. Close the Round Trip Safety Configuration utility. 6. Start IBM Cognos 8.

690

Appendix B: Initial Access Permissions

When Content Manager initializes a content store, it creates basic structures and security information. We recommend that you modify these initial settings to secure IBM Cognos 8 (p. 233). The following icons are used to indicate the access permissions. For more information, see "Access Permissions" (p. 213).

Icon

Permissions
Read Write Execute Set policy Traverse

Content Manager Hierarchy of Objects

The following table shows the Content Manager hierarchy of objects and their contents.

Folder
/Root /Root/Directory

Contents
All folders below /Root in the hierarchy. Information about authentication providers and other information typically found in a directory service. The Cognos directory namespace containing Cognos groups, data sources, distribution lists, and contacts. Other security namespaces, such as NTLM, LDAP, and Active Directory. All application data in Content Manager.

/Root/Directory/Cognos

/Root/Directory/other providers

/Root/Public Folders

Administration and Security Guide 691

Appendix B: Initial Access Permissions

Folder
/Root/Directory/application packages

Contents
A separate folder for each application containing information about the application. Configuration data for all IBM Cognos 8 components and templates. Objects that can be secured through policies that restrict access to functionality, such as Administration, Report Studio, and Query Studio; and to features, such as user defined SQL, and bursting. Deployment information for each archive imported into Content Manager. Deployment information for each archive exported from Content Manager.

/Root/Configuration

/Root/Capabilities

/Root/Import

/Root/Export

The Root Object Object

Root

Group, role, or account

Everyone

Top-level Content Manager Objects Object

Capabilities

Group, role, or account

Directory Administrators Everyone

Configuration

Server Administrators Everyone

Public Folders

Report Administrators Authors Query Users Consumers

692

Appendix B: Initial Access Permissions

Object

Group, role, or account

Express Authors Readers

Export Import Directory

Report Administrators Report Administrators Everyone

Capabilities Object
Adaptive Analytics

Group, role, or account

Adaptive Analytics Administrators Adaptive Analytics Users Directory Administrators

Administration

Directory Administrators Portal Administrators Report Administrators Server Administrators Metrics Administrators Planning Rights Administrators Controller Administrators

Administration/Adaptive Adaptive Analytics AdminisAnalytics Administration trators Directory Administrators Administration/Run activities and schedules Report Administrators

Administration and Security Guide 693

Appendix B: Initial Access Permissions

Object

Group, role, or account

Metrics Administrators Controller Administrators Directory Administrators

Administration/Configure Server Administrators and manage the system Directory Administrators Administration/Users, Groups, and Roles Directory Administrators

Administration/Set Directory Administrators capabilities and manage UI profiles Administration/Data Sources Connections Administration/ Administration tasks Directory Administrators

Server Administrators

Report Administrators Metrics Administrators Controller Administrators Directory Administrators Administration/ Distribution Lists and Contacts Administration/Printers Administration/Metric Studio Administration Directory Administrators

Directory Administrators Metrics Administrators

Directory Administrators

694

Appendix B: Initial Access Permissions

Object
Administration/Planning Administration

Group, role, or account

Planning Rights Administrators Directory Administrators

Administration/Styles and Portal Administrators portlets Directory Administrators Administration/Controller Controller Administrators Administration Directory Administrators Analysis Studio Report Administrators Authors Analysis Users Directory Administrators Cognos Viewer Context Menu Selection Toolbar Authors Consumers Query Users Analysis Users Readers Express Authors Directory Administrators Report Administrators

Administration and Security Guide 695

Appendix B: Initial Access Permissions

Object

Group, role, or account

Cognos Viewer/Run With Report Administrators Options Authors Consumers Query Users Analysis Users Express Authors Directory Administrators Controller Studio Controller Users Controller Administrators Directory Administrators Data Manager Data Manager Authors Directory Administrators Detailed Errors Drill Through Assistant Event Studio Directory Administrators Directory Administrators Report Administrators Authors Metrics Administrators Metrics Authors Directory Administrators Glossary Everyone Directory Administrators Hide Entries Everyone

696

Appendix B: Initial Access Permissions

Object

Group, role, or account

Directory Administrators

Lineage

Everyone Directory Administrators

Metric Studio

Metrics Administrators Metrics Users Metrics Authors Directory Administrators

Metric Studio/Edit View

Metrics Administrators Metrics Authors Directory Administrators

Planning Contributor

Planning Contributor Users Planning Rights Administrators Directory Administrators

Query Studio Create Advanced

Authors

Query Users Report Administrators Directory Administrators Report Studio Authors Report Administrators Directory Administrators Express Authors Administration and Security Guide 697

Appendix B: Initial Access Permissions

Object
Report Studio Bursting HTML items in report User Defined SQL

Group, role, or account

Authors

Report Administrators Directory Administrators Report Studio Create/Delete Report Administrators Directory Administrators Express Authors Scheduling Report Administrators Authors Consumers Query Users Metrics Administrators Metrics Authors Controller Administrators Controller Users Analysis Users Directory Administrators Express Authors Scheduling/Scheduling Priority Report Administrators Authors

698

Appendix B: Initial Access Permissions

Object

Group, role, or account

Metrics Administrators Controller Administrators Directory Administrators

Set Entry-Specific Capabil- Directory Administrators ities Specification Execution Data Manager Authors Directory Administrators Watch Rules Report Administrators Authors Query Users Consumers Metrics Administrators Metrics Authors Controller Administrators Controller Users Analysis Users Express Authors Directory Administrators

The Cognos Namespace Object

Cognos

Group, role, or account

Everyone Directory Administrators

Administration and Security Guide 699

Appendix B: Initial Access Permissions

Built-in and Predefined Objects in the Cognos Namespace Object

Adaptive Analytics Administrators

Group, role, or account

Adaptive Analytics Administrators Directory Administrators

Adaptive Analytics Users Directory Administrators Adaptive Analytics Users All Authenticated Users All Authenticated Users Analysis Users All Authenticated Users All Authenticated Users Analysis Users Directory Administrators Anonymous Anonymous Everyone Directory Administrators Authors All Authenticated Users Authors Directory Administrators Consumers All Authenticated Users Consumers Directory Administrators Controller Administrators Controller Administrators Directory Administrators Controller Users All Authenticated Users

700

Appendix B: Initial Access Permissions

Object

Group, role, or account

Controller Users Directory Administrators

Data Manager Authors

All Authenticated Users Data Manager Authors Directory Administrators

Directory Administrators Directory Administrators Express Authors Directory Administrators Express Authors All Authenticated Users Everyone All Authenticated Users Anonymous Metrics Administrators Metrics Administrators Directory Administrators Metrics Authors Metrics Authors All Authenticated Users Directory Administrators Metrics Users Metrics Users All Authenticated Users Directory Administrators Planning Contributor Users All Authenticated Users

Planning Contributor Users Directory Administrators

Administration and Security Guide 701

Appendix B: Initial Access Permissions

Object

Group, role, or account

Planning Rights Adminis- Planning Rights Administrattrators ors Directory Administrators Portal Administrators Portal Administrators Directory Administrators Query Users All Authenticated Users Directory Administrators Query Users Readers Directory Administrators Readers All Authenticated Users Report Administrators Directory Administrators Report Administrators Server Administrators Directory Administrators Server Administrators System Administrators System Administrators

702

Appendix C: Localization of Samples Databases

The samples databases provided with IBM Cognos 8 store a selection of text fields, such as names and descriptions, in 23 languages to demonstrate a multilingual reporting environment. This appendix provides information about how data is stored in the samples databases and how the samples databases are set up to use multilingual data, including: one column per language (p. 703) one row per language (p. 704) transliterations and multiscript extensions for Asian languages (p. 705)

For more information on the samples, see "Setting Up the Samples" (p. 63).

One Column Per Language

In this structure, tables contain sets of 23 columns, one for each language. A logical naming convention is used to indicate which language a column contains. The name of each column ends with a language code suffix, such as _EN for English and _FR for French. For example, the column that contains information about countries is named COUNTRY_FR for French data and COUNTRY_DE for German data. All tables use this structure except for PRODUCT_LOOKUP

Determining the Language (Columns) in the Model

In Framework Manager, you can insert a macro in the SQL of the data source query subject to return a specific column of data. The query subject uses the macro to apply the locale setting and to return a language code. The locale specifies linguistic information and cultural conventions for character type, collation, format of date and time, currency unit, and messages. The macro, runLocale, uses a parameter map to convert the users desired content language into a complete or partial column name. This column name is then substituted in the SQL before the query runs. Because the samples databases use a language code as the suffix for the column name, the macro uses a parameter map to convert valid run locales into a language code and then concatenates the language code to the base column name.

Sample Query
The macro in the following sample query uses the runLocale session variable as the Language_lookup parameter map key. It returns the language code to be used as the suffix of the column name. In the following Select statement, where French is the language, the macro generates the column name COUNTRY_FR.
Select COUNTRY.COUNTRY_CODE, #'COUNTRY.COUNTRY_' + $Language_lookup{$runLocale}# as Product_Line

Administration and Security Guide 703

Appendix C: Localization of Samples Databases

from [great_outdoors].COUNTRY

Because Framework Manager is flexible, your multilingual columns do not have to use the naming system used in the samples. In fact, your multilingual columns can use any naming system. You can encode your naming scheme into the parameter map, as required. You can use any session variable as the parameter map key and return any SQL syntax that you require to substitute at runtime. For more information, see the Framework Manager User Guide.

One Row Per Language

In this structure, each string value has a separate row with a code column that identifies the language. Data is filtered to return only the row that contains the required language data. Normally, multilingual data is stored in a separate table to avoid duplicating non-descriptive or monolingual data. In the samples databases, the data table contains the primary key and monolingual data, such as date information. The multilingual table contains data and a compound key composed of the foreign key and language code. For example, the PRODUCT_NAME_LOOKUP table contains the PRODUCT_NUMBER, PRODUCT_LANGUAGE, and PRODUCT_NAME columns, where PRODUCT_NUMBER and PRODUCT LANGUAGE form the primary key. Each of the localized items is expressed in 23 rows, one for each language. The following foreign key table contains one or more localized items.

Primary key table

PRODUCT SLS PRODUCT DIM

Foreign key table

PRODUCT_NAME_LOOKUP SLS_PRODUCT_LOOKUP

Database
GOSALES GOSALESDW

The samples databases use ISO language codes to identify each row of data.

Determining the Language (Rows) in the Model

In Framework Manager, you can insert a macro in the SQL of the data source query subject to return a specific row of data. The query subject uses the macro to apply the locale setting and to return a language code.

Sample Query
The macro in the sample query below uses the runLocale session variable as the Language_lookup parameter map key and returns the corresponding language code. The sq() function specifies that the return value of the macro be enclosed in single quotation marks to produce a valid SQL filter predicate. In the following Select statement, where German is the language, the macro identifies the language as DE (German), and product the filter (PRODUCT_MULTILINGUAL."LANGUAGE" = 'DE').
Select P.INTRODUCTION_DATE, P.PRODUCT_TYPE_CODE,

704

Appendix C: Localization of Samples Databases

P.PRODUCTION_COST, P.MARGIN, PRODUCT_LOOKUP.PRODUCT_NUMBER as PRODUCT_NUMBER1, PRODUCT_LOOKUP."PRODUCT_LANGUAGE", PRODUCT_LOOKUP.PRODUCT_NAME, PRODUCT_LOOKUP.PRODUCT_DESCRIPTION From gosales].PRODUCT as P, [gosales].PRODUCT_LOOKUP Where P.PRODUCT_NUMBER = PRODUCT_LOOKUP.PRODUCT_NUMBER and (PRODUCT_LOOKUP."PRODUCT_LANGUAGE" = #sq($Language_lookup{$runLocale})#)

Transliterations and Multiscript Extensions

For transliteration of Asian languages, a table contains two columns with equivalent information. One column shows string values using only Latin characters. The other column shows string values using both Asian and Latin characters. The naming convention is to add the suffix _MB. In the Latin-only columns, transliteration defines the phonetic equivalent of the value defined in the _MB column. The following tables include columns that contain transliterated values.

Table
ORDER_HEADER RETAILER RETAILER_SITE _MB BRANCH EMPLOYEE

Database
GOSALES GOSALESs GOSALES GOSALES GOSALES

Transliterations in the Model

The following example creates a single data source, based on a query subject of two tables. The tables are identical except for the use of Asian characters in one table. Column with names that end with the suffix _MB store Asian-related data using Asian characters, such as Chinese ideograms. This removes some duplication and makes it easier to define relationships to other query subjects in the model.
Select RS.RTL_RETAILER_SITE_CODE, RS.RTL_RETAILER_CODE, RS.RTL_ADDRESS1, RS.RTL_ADDRESS2, RS.RTL_CITY, RS.RTL_REGION, RS.RTL_POSTAL_ZONE, RS.RTL_COUNTRY_CODE,

Administration and Security Guide 705

Appendix C: Localization of Samples Databases

RS.RTL_ACTIVITY_STATUS_CODE, RS_MB.RTL_ADDRESS1 as Address1_MB, RS_MB.RTL_ADDRESS2 as Address2_MB, RS_MB.RTL_CITY as City_MB, RS_MB.RTL_REGION as Region_MB from [goretailers].RETAILER_SITE as RS, [goretailers].RETAILER_SITE_MB as RS_MB where RETAILER_SITE.RETAILER_SITE_CODE = RETAILER_SITE_MB.RETAILER_SITE_CODE

Multiscript Extensions
After defining the query subjects in the model, items with the _MB extension are renamed with a multiscript extension, such as Address 1 (multiscript) to ease use and readability.

Using Multiscript Extensions for Conditional Formatting

An example of multiscript usage is a mailing address in which the multiscript values ensure that mailing labels are formatted for local handling and delivery. To add more value to mailing labels, the GO Sales and Retailers model applies conditional formatting to generate international address formats. In the following example, Address line 3 is the name of a user-defined calculation that is used to generate line three of a mailing label. The expression uses a Country code value to specify how to format the line.
if ([Retailers].[Retailer site].[Country code] = 6) then (' ' + [Retailers].[Retailer site].[Address 1 (multiscript)]) else if ([Retailers].[Retailer site].[Country code] = 8) then ([Retailers].[Retailer site].[Address 2 (multiscript)]) else if ([Retailers].[Retailer site].[Country code] = 13) then ([Retailers].[Retailer site].[Region (multiscript)] + ' ' + [Retailers].[Retailer site].[City (multiscript)] + ' ' + [Retailers].[Retailer site].[Address 1 (multiscript)] + ' ' + [Retailers].[Retailer site].[Address 2 (multiscript)]) else if ([Retailers].[Retailer site].[Country code] = 14) then ([Retailers].[Retailer site].[Address 2 (multiscript)]) else ([Retailers].[Retailer site].[Address 1 (multiscript)])

Multiscript extensions allow a user in any language to use the same model columns to create an address block and see the address properly formatted for each delivery location. For more information, see the Mailing address data source query subjects in the gosales_goretailers sample model.

706

Appendix D: User Interface Elements Reference List

This appendix shows the IBM Cognos Connection user interface elements that you can hide and add.

Elements You Can Hide

The following table describes the user interface elements that you can hide in IBM Cognos Connection. Items starting with CRN and CC indicate IBM Cognos Connection interface elements. Items starting with RV indicate Cognos Viewer elements. Items starting with SMT indicate Schedule Management Tool elements. For information about hiding elements, see "Hide User Interface Elements" (p. 503).

User Interface Element

<CRN_HEADER/>

Description
The IBM Cognos Connection top header (h1) Left-hand side of the IBM Cognos Connection top header (h1) Right-hand side of the IBM Cognos Connection top header (h1) The Launch menu in the upper-right corner of Cognos Connection Not supported Authentication options Refresh button Search options My Area options My Watch Items option in My Area My Preferences option in My Area

<CRN_HEADER_TITLE/>

<CRN_HEADER_OPTIONS/>

<CRN_HEADER_LAUNCH/>

<CRN_HEADER_USERNAME/> <CRN_HEADER_AUTHENTICATION/> <CRN_HEADER_REFRESH/> <CRN_HEADER_SEARCH/> <CRN_HEADER_PERSONAL/> <CRN_HEADER_PERSONAL_subscriptions/> <CRN_HEADER_PERSONAL_preferences/>

Administration and Security Guide 707

Appendix D: User Interface Elements Reference List

User Interface Element

<CRN_HEADER_PERSONAL_activities/>

Description
My Activities and Schedules option in My Area Help menu Quick Tour link Getting Started link More Documentation link IBM Cognos on the Web link Go to the Welcome Page link About IBM Cognos Connection link Home option Set View as Home option Deprecated Report Studio link Query Studio link Metric Studio link Event Studio link. Used to be <CRN_ HEADER_OPTIONS_ags> Analysis Studio link. Used to be <CRN_ HEADER_OPTIONS_ps> IBM Cognos Connection link (Cognos Viewer only). Deprecated. Contributor link Controller Studio link Drill-through Definitions link

<CRN_HEADER_HELP/> <CRN_HEADER_HELP_quickTour/> <CRN_HEADER_HELP_getStarted/> <CRN_HEADER_HELP_moreDocs/> <CRN_HEADER_HELP_companyWebsite/> <CRN_HEADER_HELP_welcome/> <CRN_HEADER_HELP_about/> <CRN_HEADER_HOME/> <CRN_HEADER_HOME_setHome/> <CRN_HEADER_OPTIONS_mypages/> <CRN_HEADER_OPTIONS_rs/> <CRN_HEADER_OPTIONS_qs/> <CRN_HEADER_OPTIONS_mm/> <CRN_HEADER_OPTIONS_es/>

<CRN_HEADER_OPTIONS_as/>

<CRN_HEADER_OPTIONS_cc/>

<CRN_HEADER_OPTIONS_pc/> <CRN_HEADER_OPTIONS_cs/> <CRN_HEADER_OPTIONS_dt/>

708

Appendix D: User Interface Elements Reference List

User Interface Element

<CRN_HEADER_OPTIONS_aa/> <CC_HEADER/>

Description
Adaptive Analytics link IBM Cognos Connection header (h2). Deprecated Left-hand side of the IBM Cognos Connection header (h2). Deprecated Right-hand side of the IBM Cognos Connection header (h2). Deprecated "home" link. Replaced by <CRN_HEADER_HOME/> "return" link (Cognos Viewer only) "search" link "logon" link "logoff" link "about" link ( Cognos Viewer only). Replaced by <CRN_HEADER_HELP_ about/> "help" link "preferences" link "tools" link. Deprecated "directory" link. Deprecated "capabilities" link. Deprecated "schedule" link. Deprecated "server administration" link. Deprecated Deprecated "content administration" link. Deprecated

<CC_HEADER_TITLE/>

<CC_HEADER_MENU/>

<CC_HEADER_MENU_home/>

<CC_HEADER_MENU_return/> <CC_HEADER_MENU_search/> <CC_HEADER_MENU_logon/> <CC_HEADER_MENU_logoff/> <CC_HEADER_MENU_about/>

<CC_HEADER_MENU_help/> <CC_HEADER_MENU_preferences/> <CC_VIEW_TOOLS/> <CC_VIEW_TOOLS_directory/> <CC_VIEW_TOOLS_capabilities/> <CC_VIEW_TOOLS_schedule/> <CC_VIEW_TOOLS_administration/> <CC_VIEW_TOOLS_deployment/> <CC_VIEW_TOOLS_csadministration/>

Administration and Security Guide 709

Appendix D: User Interface Elements Reference List

User Interface Element

<CC_VIEW_TOOLS_portal/> <CC_VIEW_TOOLS_drillthru/> <CC_VIEW_TOOLS_preferences/> <CC_VIEW/> <CC_VIEW_TABS/>

Description
"portal administration" link. Deprecated "drill-through definition" link "my preferences" link IBM Cognos Connection header (h3) Left-hand side of the IBM Cognos Connection header (h3) that includes the tabs The page menu button on left-hand side of the portal tabs IBM Cognos Connection header (h4) that includes the path navigation and toolbar Path navigation Toolbar buttons Refresh New Job New Folder New URL

<CC_VIEW_TABS_OPTIONS/>

<CC_TOOLBAR/>

<CC_TOOLBAR_PATH/> <CC_TOOLBAR_BUTTONS/> <CC_TOOLBAR_BUTTONS_refreshUsingGet/> <CC_TOOLBAR_BUTTONS_newjobDefinition/> <CC_TOOLBAR_BUTTONS_newfolder/> <CC_TOOLBAR_BUTTONS_newURL/>

CC_TOOLBAR_BUTTONS_newconfigurationFolder/ New Configuration Folder > <CC_TOOLBAR_BUTTONS_newrole/> <CC_TOOLBAR_BUTTONS_newgroup/> <CC_TOOLBAR_BUTTONS_newnamespaceFolder/> <CC_TOOLBAR_BUTTONS_newdataSource/> <CC_TOOLBAR_BUTTONS_ newdataSourceConnection/>

New Role New Group New Namespace Folder New Data Source New Connection

<CC_TOOLBAR_BUTTONS_newdataSourceSignon/> New Data Source Signon

710

Appendix D: User Interface Elements Reference List

User Interface Element

<CC_TOOLBAR_BUTTONS_newcontact/>

Description
New Contact

<CC_TOOLBAR_BUTTONS_newdistributionList/> New Distribution List <CC_TOOLBAR_BUTTONS_newprinter/> <CC_TOOLBAR_BUTTONS_newadminFolder/> <CC_TOOLBAR_BUTTONS_newportletFolder/> <CC_TOOLBAR_BUTTONS_newcontentTask/> <CC_TOOLBAR_BUTONS_newcmmSystemTask/> <CC_TOOLBAR_BUTTONS_ newimportDeploymentFolder/> <CC_TOOLBAR_BUTTONS_ newexportDeploymentFolder/> <CC_TOOLBAR_BUTTONS_import/> <CC_TOOLBAR_BUTTONS_export/> <CC_TOOLBAR_BUTTONS_cut/> <CC_TOOLBAR_BUTTONS_copy/> <CC_TOOLBAR_BUTTONS_paste/> <CC_TOOLBAR_BUTTONS_delete/> <CC_TOOLBAR_BUTTONS_refresh/> <CC_TOOLBAR_BUTTONS_selectall/> <CC_TOOLBAR_BUTTONS_deselectall/> <CC_TOOLBAR_BUTTONS_list/> <CC_TOOLBAR_BUTTONS_detail/> <CC_TOOLBAR_BUTTONS_properties/> <CC_TOOLBAR_BUTTONS_configuration_ properties/>

New Printer New Admin Folder New Portlet Folder New Content Task New IBM Cognos Metrics Manager task New import deployment folder

New export deployment folder

New import specification New export Specification Cut Copy Paste Delete Refresh Select all Deselect All List view mode Detailed view mode Current folder properties Configuration folder properties

Administration and Security Guide 711

Appendix D: User Interface Elements Reference List

User Interface Element

<CC_TOOLBAR_BUTTONS_order/>

Description
Order

<CC_TOOLBAR_BUTTONS_deployment_properties/ Deployment Properties > <CC_TOOLBAR_BUTTONS_enable_sched/> <CC_TOOLBAR_BUTTONS_disable_sched/> <CC_TOOLBAR_BUTTONS_view_events/> <CC_TOOLBAR_BUTTONS_page_sizes/> <CC_TOOLBAR_BUTTONS_search/> <CC_TOOLBAR_BUTTONS_add_portet/> <CC_TOOLBAR_BUTTONS_edit_layout/> <CC_TOOLBAR_BUTTONS_new_page/> <CC_TOOLBAR_BUTTONS_delete_page/> <CC_TOOLBAR_BUTTONS_ newmetricsIntegrationTaskGroup/> <CC_TOOLBAR_BUTTONS_newmetricsPackage/> <CC_DIALOG_HEADER/> <CC_DIALOG_HEADER_help/> <CC_RUN_OPTIONS_email_attachment/> <RV_HEADER/> <RV_HEADER_TITLE/> <RV_HEADER_MENU/>

Enable Schedule Disable Schedule View Events Page sizes option in configuration tool Search Add a portlet to custom portal pages Edit the layout of a custom portal page Add a custom portal page Delete a custom portal page New data integration task

New metrics package Not supported "Help" link on dialog screens "Include the report" check box Cognos Viewer header Left hand side of the Cognos Viewer header Right hand side of the Cognos Viewer header "log off" link "logon" link

<RV_HEADER_MENU_LOGOFF/> <RV_HEADER_MENU_LOGON/>

712

Appendix D: User Interface Elements Reference List

User Interface Element

<RV_HEADER_MENU_RETURN/> <RV_HEADER_MENU_ABOUT/> <RV_HEADER_MENU_HOME/> <RV_TOOLBAR/> <RV_TOOLBAR_BUTTONS/> <RV_TOOLBAR_BUTTONS_DOWNLOAD/>

Description
"return" link "about" link "home link Not applicable Toolbar options in Cognos Viewer Download toolbar button. This applies when download is enabled. Save toolbar button Save As toolbar button Email toolbar button History toolbar option Run toolbar button HTML format view button PDF format view button XLS format view button CSV format view button XML format view button Excel 2007 format view Excel 2002 format view Excel 2000 format view Excel 2000 single sheet format view Hides the drill down button Hides the drill up button

<RV_TOOLBAR_BUTTONS_SAVE/> <RV_TOOLBAR_BUTTONS_SAVEAS/> <RV_TOOLBAR_BUTTONS_SEND/> <RV_TOOLBAR_BUTTONS_HISTORY/> <RV_TOOLBAR_BUTTONS_RUN/> <RV_TOOLBAR_BUTTONS_HTML/> <RV_TOOLBAR_BUTTONS_PDF/> RV_TOOLBAR_BUTTONS_XLS/> <RV_TOOLBAR_BUTTONS_XLS_CSV/> <RV_TOOLBAR_BUTTONS_XML/> <RV_TOOLBAR_BUTTONS_XLS_SPREADSHEETML/> <RV_TOOLBAR_BUTTONS_XLS_XLWA/> <RV_TOOLBAR_BUTTONS_XLS_XLS/> <RV_TOOLBAR_BUTTONS_XLS_SINGLEXLS/> <RV_TOOLBAR_BUTTONS_DRILLDOWN/> <RV_TOOLBAR_BUTTONS_DRILLUP/>

Administration and Security Guide 713

Appendix D: User Interface Elements Reference List

User Interface Element

<RV_TOOLBAR_BUTTONS_GOTO/> RV_TOOLBAR_BUTTONS_ADD_THIS_REPORT RV_TOOLBAR_BUTTONS_ADD_TO_MY_BOOKMARKS RV_TOOLBAR_BUTTONS_ADD_TO_MY_FOLDERS RV_TOOLBAR_BUTTONS_KEEP_THIS_VERSION <SMT_SCOPE_any/>

Description
Hides the go to button Hides the Add this report button Hides the Add to My Bookmarks button Hides the Add to My Folders button Hides the Keep this version button Any choice from the Scope selection in the Schedule Management tool. Entries I Own choice from the Scope selection in the Schedule Management tool. Public Folders choice from the Scope selection in the Schedule Management tool.

<SMT_SCOPE_entries_i_own/>

<SMT_SCOPE_public_folders/>

Elements You Can Add

The following table describes the user interface elements that can be added to IBM Cognos Connection. For information about hiding these elements, see "Hide User Interface Elements" (p. 503).

714

Appendix D: User Interface Elements Reference List

User Interface Element

<CRN_HEADER_OPTIONS> <item show="user_type"> <url> http-encoded URL to execute </url> <onclick>other action to take when link is clicked </onclick> <target>browser window to target </target> <label xml:lang="en">link text </label> <tooltip xml:lang="en">tooltip text </tooltip> <label xml:lang="language">link text </label> <tooltip xml:lang="language"> tooltip text </tooltip> <icon>icon to show for this element </icon> </item> </CRN_HEADER_OPTIONS> <CC_HEADER_MENU> <item show="user_type"> <url>http-encoded URL to execute </url> <onclick>other action to take when link is clicked </onclick> <target>browser window to target </target> <label xml:lang="en">link text </label> </item> </CC_HEADER_MENU> <CC_DIALOG_HEADER> <item show="user_type"> <url>http-encoded URL to execute </url> <onclick>other action to take when link is clicked </onclick> <target>browser window to target </target> <label xml:lang="en">link text </label> </item> </CC_DIALOG_HEADER>

Description
Renders additional options to the right hand side of the IBM Cognos 8 header to the right of the Report Studio link. Only a url, an icon, and a tooltip and label in English are required. Target can be one of _blank, _self, _parent, or _top.

Renders additional options on the right hand side of the IBM Cognos Connection header to the right of the Help link. Only a url and a label in English are required. Target can be one of _blank, _self, _parent, or _top.

Renders additional options to the right of the Help link in dialog boxes.

Administration and Security Guide 715

Appendix D: User Interface Elements Reference List

716

Appendix E: User Reference Help for Portal Services

Administrators typically configure default settings for each instance of a portlet before making it available to users. When you access the Cognos portlets through your portal, you can change some settings to customize instances of each Cognos portlet. You can then save your settings for subsequent sessions. You can change the content and layout of a portlet using the edit button on the title bar. If the page or portlet is read-only or locked by an administrator, the edit button is disabled or does not appear on the portlet title bar.

Cognos Navigator
Use this portlet to browse a list of links that open published IBM Cognos reports and other entries. To modify the properties for this portlet, click the edit button to open the properties page. If the edit button is disabled or not visible, the administrator did not make these settings available to you. In the portlet properties page, to reset the default portlet settings, or to return to the settings specified by your administrator, click the reset button in the portlet title bar. To exit the properties page or click Cancel.

without saving the changes, click the return button

Notes:
In SAP Enterprise Portal, portlets are named iViews. This document may refer to iViews as portlets. In Microsoft SharePoint Portal Server, portlets are named Web Parts. This document may refer to Web Parts as portlets.

The following table shows the properties that you can change.

Property
Title

Description
Specifies the title of the portlet. If no title is specified, the folder name is used by default. You can specify a title for each supported language version of the product. Note: The title does not appear in WebSphere, ALUI, and SAP portals.

Language

Specifies the product language version in which the title appears. You can assign the same title for multiple language versions.

Administration and Security Guide 717

Appendix E: User Reference Help for Portal Services

Property
Folder View

Description
Specifies the location where the portlet navigation begins. Specifies how entries are shown: To show a list of entry names, use the Navigator list view. This is the default view. To show entry names and detailed information, such as the last modification date, use the Navigator details view. Links open more detailed information about the entry. To show URLs and shortcuts in an RSS-type format, use the News list view. RSS is a way of showing URLs in a Web page as short summaries that contain links to the associated pages.

Open links

Specifies how the links in this portlet are opened. You can open and navigate the linked entries in a new browser window. This is the default option. open and navigate the linked entries in the currently opened browser window. open and navigate the linked entries in a specified HTML frame. Type the name of the window or frame in the provided text box. open and navigate the linked entries in the Cognos Viewer portlet. Type the channel name as specified in Cognos Viewer.

Open navigation links Specifies whether to maximize the portlet view when navigating the folder inside this portlet hierarchy.

718

Appendix E: User Reference Help for Portal Services

Property
Features to expose in the Navigator views

Description
Specifies how the IBM Cognos 8 entries are shown in this portlet: To show or hide the parent entry of the starting folder in the IBM Cognos 8 folder hierarchy, use the Parent in path check box. To show or hide the Actions column for the entries, and view the content of container entries in source applications, use the Actions check box. To show or hide the modification date and description of entries in applicable views, use the Additional information check box. To specify in how many columns you want the entries to appear in the details view, use the Number of columns in a details view check box. The default is 2 for the normal portlet view, and 4 for the maximized portlet view. You can specify a different view for normal and maximized windows. Note: The maximized view is not available in SharePoint Portal Server.

Number of entries

Specifies the maximum number of entries to show per page. The menu bar in the portlet shows how many entries are available for a folder.

Separators

Specifies whether separators are used in a list view. To make long lists of entries easier to read, use alternating background colors to separate the entries in the list.

Cognos Search
Use this portlet to find published IBM Cognos reports and other entries. Searches are performed against various types of IBM Cognos entries and folders. Use the advanced search options to perform more complex searches. By default, the search results are shown as links that open entries in a new browser window. You can save your search settings for future use. To modify the properties for this portlet, click the edit button to open the properties page. If the edit button is disabled or not visible, the administrator did not make these settings available to you.

Administration and Security Guide 719

Appendix E: User Reference Help for Portal Services In the portlet properties page, to reset the default portlet settings, or to return to the settings specified by your administrator, click the reset button in the portlet title bar. To exit the properties page or click Cancel.

without saving the changes, click the return button

Notes:
In SAP Enterprise Portal, portlets are named iViews. This document may refer to iViews as portlets. In Microsoft SharePoint Portal Server, portlets are named Web Parts. This document may refer to Web Parts as portlets.

The following table shows the properties that you can change.

Property
Title

Description
Specifies the title of the portlet. If no title is specified, the portlet name is used by default. You can specify a title for each supported language version of the product. Note: The title does not appear in WebSphere, ALUI, and SAP portals.

Language

Specifies the product language version in which the title appears. You can assign the same title for multiple language versions. Specifies the saved results of previous searches. To save your most recent search results, type a name in the Last search box and then click Save. To rename a search, type the new name in the appropriate Saved searches text box. To delete a search, click Delete next to the appropriate Saved searches text box.

Saved searches

Open links

Specifies how the links are opened. You can open and navigate the linked entries in a new browser window. This is the default option open and navigate the linked entries in the currently opened browser window. open the linked entries in a target browser window or frame. Type the name of the window or frame in the provided text box. open and navigate the linked entries in the Cognos Viewer portlet. Type the channel name as specified in Cognos Viewer.

720

Appendix E: User Reference Help for Portal Services

Property
Number of results to show per page

Description
Specifies the maximum number of entries to list per page.

Content of entry view Specifies whether to show additional details for the entries in the search results. Use the Show details check box to show the entry modification date. Use the Show actions check box to show the entry actions. For example, you can use this option to view report outputs, run reports with options, open reports for editing, set properties, or set a schedule to run reports directly from the search results view. Search results Specifies how to show the search results. Select the Maximize the view when displaying search results check box when you want to show the results in a maximized view. This is useful when the results list is long.

Cognos Viewer (IBM Cognos Connection)

Use this portlet to view and interact with published IBM Cognos reports and other entries, and to enable interactivity between other Cognos Viewer portlets in the same page. To modify the properties for this portlet, click the edit button to open the properties page. If the edit button is disabled or not visible, the administrator did not make these settings available to you. In the portlet properties page, to reset the default portlet settings, or to return to the settings specified by your administrator, click the reset button in the portlet title bar. To exit the properties page or click Cancel.

without saving the changes, click the return button

Notes:
In SAP Enterprise Portal, portlets are named iViews. This document may refer to iViews as portlets. In Microsoft SharePoint Portal Server, portlets are named Web Parts. This document may refer to Web Parts as portlets.

The following table shows the properties that you can change.

Administration and Security Guide 721

Appendix E: User Reference Help for Portal Services

Property
Title

Description
Specifies the title of the portlet. If no title is specified, the entry name is used by default. You can specify a title for each supported language version of the product. Note: The title does not appear in WebSphere, ALUI, and SAP portals.

Language

Specifies the product language version in which the title appears. You can assign the same title for multiple language versions. Specifies the location of the entry, such as a report, to display in this portlet. You can search the folders to locate the entry. After you select the entry, the Report Properties link appears. Use this link to access the advanced portlet properties.

Entry

Channel

Enables communication between this portlet and other Cognos portlets. To set up communication between specific portlets, type the same channel name for the portlets that you want to interact. The channel name can contain only letters, numbers, and underscore (_) characters, and must not contain any spaces. For example, Cognos, Cognos_Portlets, or CognosPortlets.

Height (pixels)

Specifies the portlet height in pixels. If the report image is larger than this setting, scroll bars appear when you view the report.

Advanced Properties
Use these properties to override the default Cognos Viewer properties, customize the portlet user interface, and enable interactivity between other portlets in the same page.

Property
Fragment action

Description
Defines the default action when the portlet is invoked in a page. When you select Show a run action, the run button appears in the portlet. When the button is clicked, the report runs. This feature helps to avoid running multiple reports a the same time. When Show most recent saved output is selected and there is no saved report output when the portlet is invoked, you can choose to run the report, or show the run button.

722

Appendix E: User Reference Help for Portal Services

Property
Prompt the user

Description
Controls prompted reports in a page or a dashboard. When you select Only when required parameter values are missing, the user is prompted if the report contains required prompts and the values are missing. Otherwise the report runs successfully. When you select Every time, if the report contains optional or required prompts, the user is prompted to enter the prompt values before the report is run. When you select Based on the prompt settings of the report, Cognos Viewer uses the prompts specified in the report. When you select Never and show the report only when required values are provided, Cognos Viewer attempts to run the report, but the page remains hidden until the required prompt values are provided.

Portlet communica- Enables communication between the Cognos Viewer portlets in the same tion options (Prompt page when using prompted reports. values) When you select the Communicate with other portlets check box, communication between this portlet and other portlets that also have this check box selected is enabled. To set up communication between specific portlets, click Portlets using channel and type the channel name. Only the portlets that share the same channel name can interact. By specifying the channel name, you have more control over the page. For example, you can link only reports that have matching parameters. The channel name can contain only letters, numbers, and underscore (_) characters, and must not contain any spaces. For example, sales_reports or AbC are valid channel names.

Administration and Security Guide 723

Appendix E: User Reference Help for Portal Services

Property
Drill down and drill up

Description
Enables sharing of drill-down and drill-up actions when a page contains reports based on dimensionally modeled data sources. The item on which the drill action is based must be present in all linked reports in the page. In some cases, the sharing of drill events is not recommended. For example, simultaneous drill requests may have a negative impact on performance. When you select the Communicate with other portlets check box, communication between the portlet and other portlets that also have this check box selected is enabled. To set up communication between specific portlets, click Portlets using channel and type the channel name. Only the portlets that share the channel name can interact. By specifying the channel name, you have more control over the page. For example, you can link only the reports that have matching parameters. The channel name can contain only letters, numbers, and underscore (_) characters, and must not contain any spaces. For example, sales_reports or AbC.

Report-based drill through

Enables sharing of drill-through actions when a page contains a report with an authored drill-through path. You must select the Communicate with other portlets on the page check box, and type the channel name in the box provided. Only the portlets that share the channel name can interact. The channel name can contain only letters, numbers, and underscore (_) characters, and must not contain any spaces. For example, sales_reports or AbC are valid channel names.

View Options (Show Specify whether the portlet toolbar should appear in the normal or Toolbar) maximized view. The toolbar contains the edit button, help button, and refresh button.

Cognos Viewer
Use this portlet to view and interact with published IBM Cognos reports and other entries in your portal. To modify the properties for this portlet, click the edit button to open the properties page. If the edit button is disabled or not visible, the administrator did not make these settings available to you.

724

Appendix E: User Reference Help for Portal Services In the portlet properties page, to reset the default portlet settings, or to return to the settings specified by your administrator, click the reset button in the portlet title bar. To exit the properties page or click Cancel.

without saving the changes, click the return button

Notes:
In SAP Enterprise Portal, portlets are named iViews. This document may refer to iViews as portlets. In Microsoft SharePoint Portal Server, portlets are named Web Parts. This document may refer to Web Parts as portlets.

The following table shows the properties that you can change.

Property
Title

Description
Specifies the title of the portlet. If no title is specified, the entry name is used by default. You can specify a title for each supported language version of the product. Note: The title does not appear in WebSphere, ALUI, and SAP portals.

Language

Specifies the product language version in which the title appears. You can assign the same title for multiple language versions. Specifies the location of the entry, such as a report, to display in this portlet. You can search the folders to locate the entry.

Entry

Channel

Enables communication between this portlet and other Cognos portlets. To set up communication between specific portlets, type the same channel name for the portlets that you want to interact. The channel name can contain only letters, numbers, and underscore (_) characters, and must not contain any spaces. For example, Cognos, Cognos_Portlets, or CognosPortlets.

Portlet action

Specifies the report run options. You can choose to show the most recent saved report output, show a run option button that a user can activate, or run the report. Specifies whether to show the portlet toolbar in the normal or maximized view. This applies to reports only. Note: The maximized view is not available in SharePoint Portal Server.

Show toolbar

Administration and Security Guide 725

Appendix E: User Reference Help for Portal Services

Property

Description

Portlet width in pixels Specifies the portlet width in pixels. If the report image is larger than this setting, scroll bars appear when you view the report. Portlet height in pixels Specifies the portlet height in pixels. If the report is larger than this setting, scroll bars appear when you view the report.

Cognos Extended Applications

Use this portlet to view and interact with custom applications created using the IBM Cognos 8 Software Development Kit. To modify the properties for this portlet, click the edit button to open the properties page. If the edit button is disabled or not visible, the administrator did not make these settings available to you. In the portlet properties page, to reset the default portlet settings, or to return to the settings specified by your administrator, click the reset button in the portlet title bar. To exit the properties page or click Cancel.

without saving the changes, click the return button

Notes:
In SAP Enterprise Portal, portlets are named iViews. This document may refer to iViews as portlets. In Microsoft SharePoint Portal Server, portlets are named Web Parts. This document may refer to Web Parts as portlets.

The following table shows the properties that you can change.

Property
Application Options

Description
Specifies an application to show in the portlet. Some extended applications include application parameters that you can configure. These parameters affect how the application operates.

Metric List
Use this portlet to add performance metrics to a page. The metrics are created in Metric Studio. You can configure the portlet to show different types of metric lists, such as a watch list, an accountability list, a scorecard, or a strategy list. However, if the Metrics Custom Diagram portlet

726

Appendix E: User Reference Help for Portal Services in a page uses the same channel, the configured metric list may not appear. Instead, a strategy metric list of the Metrics Custom Diagram portlet appears. To see the configured metric list, click Back to default entry. This portlet is interactive. When you click a metric name, the content of the Metric History Chart and Cognos Viewer portlets using the same channel is automatically updated. When you position a pointer over a metric icon, a tooltip appears that shows the history chart associated with the metric. When you click the arrow button , the metric opens in Metric Studio. When you position a pointer over the comment icon for a metric or a strategy, the tooltip shows the latest comment. To modify the properties for this portlet, click the edit button to open the properties page. If the edit button is disabled or not visible, the administrator did not make these settings available to you. In the portlet properties page, to reset the default portlet settings, or to return to the settings specified by your administrator, click the reset button in the portlet title bar. To exit the properties page or click Cancel.

without saving the changes, click the return button

Notes:
In SAP Enterprise Portal, portlets are named iViews. This document may refer to iViews as portlets. In Microsoft SharePoint Portal Server, portlets are named Web Parts. This document may refer to Web Parts as portlets.

The following table shows the properties that you can change.

Property
Title

Description
Specifies the title of the portlet. You can use the default metric list name, or type a new name. If no title is specified, the portlet name is used. You can specify a title for each supported language version of the product. Note: The title does not appear in WebSphere, ALUI, and SAP portals.

Language

Specifies the product language version in which the title appears. You can assign the same title for multiple language versions.

Show title in content area Shows the title in content area of the portlet. This option is useful when the portal does not show the title bar. Metric package Specifies a metric package that contains the metrics.

Administration and Security Guide 727

Appendix E: User Reference Help for Portal Services

Property
List type

Description
Use to add performance metrics to a page. You can configure the portlet to show the following types of metric lists: Watch List Contains the metrics that a user wants to monitor closely. Accountability List Contains the metrics that a user owns. Scorecard metric list Contains the metrics included in a scorecard. Strategy metric list Contains metrics associated to a strategy. The metrics can befiltered by a specified scorecard. To select a scorecard, use the Apply a scorecard filter check box. If no scorecard is selected, all metrics in the strategy are shown.

Portlet communication options

Enables communication between this portlet, the Cognos Viewer portlet, and other Cognos Metrics portlets. When you select the Communicate with other portlets check box, communication between this portlet and other portlets that also have this check box selected is enabled. To set up communication between specific portlets, click Portlets using channel and type the channel name. Only the portlets that share the same channel name can interact. The channel name can contain only letters, numbers, and underscore (_) characters, and must not contain any spaces. For example, sales_reports or AbC are valid channel names.

Number of entries

Specify the maximum number of metrics displayed in the list. For a strategy metric list, and lists viewed with grouping enabled, this value is ignored. Valid range is 1 to 1000.

Metric History Chart

Use this portlet to add a metric history chart to a page. The history chart is a graphical illustration of the historical performance of a metric. When you click a metric name in other Cognos Metrics portlets, the metric history chart in this portlet is automatically updated if the portlets are using the same channel.

728

Appendix E: User Reference Help for Portal Services

To modify the properties for this portlet, click the edit button to open the properties page. If the edit button is disabled or not visible, the administrator did not make these settings available to you. In the portlet properties page, to reset the default portlet settings, or to return to the settings specified by your administrator, click the reset button in the portlet title bar. To exit the properties page or click Cancel.

without saving the changes, click the return button

Notes:
In SAP Enterprise Portal, portlets are named iViews. This document may refer to iViews as portlets. In Microsoft SharePoint Portal Server, portlets are named Web Parts. This document may refer to Web Parts as portlets.

The following table shows the properties that you can change.

Property
Title

Description
Specifies the title of the portlet. Select the Use the entry name check box if you want to use the name of a metric associated with the history chart as a title. If no title is specified, the portlet name is used by default. You can specify a title for each supported language version of the product. Note: The title does not appear in WebSphere, ALUI, and SAP portals.

Language

Specifies the product language version in which the title appears. You can assign the same title for multiple language versions. Shows the title in content area of the portlet. This option is useful when the portal does not show the title bar.

Show title in content area

Portlet communication Enables communication between this portlet, the Cognos Viewer portlet, options and other Cognos Metrics portlets. When you select the Communicate with other portlets check box, communication between this portlet and other portlets that also have this check box selected is enabled. To set up communication between specific portlets, click Portlets using channel and type the channel name. Only the portlets that share the same channel name can interact. The channel name can contain only letters, numbers, and underscore (_) characters, and must not contain any spaces. For example, sales_reports or AbC are valid channel names. Image Width Specifies the image width in pixels. The range is 350 to 1000 pixels.

Administration and Security Guide 729

Appendix E: User Reference Help for Portal Services

Property
Image Height

Description
Specifies the image height in pixels. The range is 100 to 1000 pixels.

Metrics Impact Diagram

Use this portlet to display impact diagrams associated with a metric. When you click a metric in the Metrics Custom Diagram or Metric List portlet, the impact diagram associated with the metric appears in this portlet. You can select other diagrams from the dropdown menu in the top, left corner of the portlet. The diagrams in this portlet are interactive. When you click a metric name, the content of the Metric History Chart and Cognos Viewer portlets using the same channel is automatically updated. When you position a pointer over a metric icon, a tooltip appears that shows the history chart and the most recent data values associated with the metric. To modify the properties for this portlet, click the edit button to open the properties page. If the edit button is disabled or not visible, the administrator did not make these settings available to you. In the portlet properties page, to reset the default portlet settings, or to return to the settings specified by your administrator, click the reset button in the portlet title bar. To exit the properties page or click Cancel.

without saving the changes, click the return button

Notes:
In SAP Enterprise Portal, portlets are named iViews. This document may refer to iViews as portlets. In Microsoft SharePoint Portal Server, portlets are named Web Parts. This document may refer to Web Parts as portlets.

The following table shows the properties that you can change.

Property
Title

Description
Specifies the title of the portlet. Select the Use the entry name check box if you want to use the name of a metric associated with the impact diagram as a title. If no title is specified, the portlet name is used by default. You can specify a title for each supported language version of the product. Note: The title does not appear in WebSphere, ALUI, and SAP portals.

Language

Specifies the product language version in which the title appears. You can assign the same title for multiple language versions.

730

Appendix E: User Reference Help for Portal Services

Property
Show title in content area

Description
Shows the title in content area of the portlet. This option is useful when the portal does not show the title bar.

Portlet communication Enables communication between this portlet, the Cognos Viewer portlet, options and other Cognos Metrics portlets. When you select the Communicate with other portlets check box, communication between this portlet and other portlets that also have this check box selected is enabled. To set up communication between specific portlets, click Portlets using channel and type the channel name. Only the portlets that share the same channel name can interact. The channel name can contain only letters, numbers, and underscore (_) characters, and must not contain any spaces. For example, sales_reports or AbC are valid channel names. Image Width Image Height Specifies the image width in pixels. The range is 100 to 2000 pixels. Specifies the image height in pixels. The range is 100 to 2000 pixels.

Metrics Custom Diagram

Use this portlet to display custom diagrams associated with a scorecard. You can configure the portlet to show the default diagram associated with the scorecard. You can select other diagrams from the drop-down menu in the top, left corner of the portlet. The diagrams in this portlet are interactive. When you click a metric name, the content of the Metric History Chart, Metrics Impact Diagram, and Cognos Viewer portlets is updated. When you position a pointer over a metric icon, the tooltip appears that shows the history chart and the most recent data values associated with the metric. When you click a strategy element, the content of the Metric List portlet is updated. When you position a pointer over a strategy element, a tooltip appears that shows the metrics summary count. To modify the properties for this portlet, click the edit button to open the properties page. If the edit button is disabled or not visible, the administrator did not make these settings available to you. In the portlet properties page, to reset the default portlet settings, or to return to the settings specified by your administrator, click the reset button in the portlet title bar. To exit the properties page or click Cancel.

without saving the changes, click the return button

Notes:
In SAP Enterprise Portal, portlets are named iViews. This document may refer to iViews as portlets.

Administration and Security Guide 731

Appendix E: User Reference Help for Portal Services In Microsoft SharePoint Portal Server, portlets are named Web Parts. This document may refer to Web Parts as portlets.

The following table shows the properties that you can change.

Property
Title

Description
Specifies the title of the portlet. Select the Use the entry name check box if you want to use the scorecard name as a title. If no title is specified, the portlet name is used by default. You can specify a title for each supported language version of the product. Note: The title does not appear in WebSphere, ALUI, and SAP portals.

Language

Specifies the product language version in which the title appears. You can assign the same title for multiple language versions. Shows the title in content area of the portlet. This option is useful when the portal does not show the title bar. Specifies a metric package that contains the scorecard. Specifies the scorecard associated with the configured metric package.

Show title in content area Metric package Scorecard

Portlet communication Enables communication between this portlet, the Cognos Viewer portlet, options and other Cognos Metrics portlets. When you select the Communicate with other portlets check box, communication between this portlet and other portlets that also have this check box selected is enabled. To set up communication between specific portlets, click Portlets using channel and type the channel name. Only the portlets that share the same channel name can interact. The channel name can contain only letters, numbers, and underscore (_) characters, and must not contain any spaces. For example, sales_reports or AbC are valid channel names. Image Width Image Height Specifies the image width in pixels. The range is 100 to 2000 pixels. Specifies the image height in pixels. The range is 100 to 2000 pixels.

Bookmarks Viewer
Use this portlet to register and show active Web links in a page.

732

Appendix E: User Reference Help for Portal Services

To modify the properties for this portlet, click the edit button to open the properties page. If the edit button is disabled or not visible, the administrator did not make these settings available to you. In the portlet properties page, to reset the default portlet settings, or to return to the settings specified by your administrator, click the reset button in the portlet title bar. To exit the properties page or click Cancel.

without saving the changes, click the return button

The following table shows the properties that you can change.

Property
Title

Description
Specifies the title of the portlet. If no title is specified, the name Bookmarks Viewer is used by default. You can specify a title for each supported language version of the product.

Language

Specifies the product language version in which the title appears. You can assign the same title for multiple language versions. Specifies the URL address of the Web page you want to register. You can type an alias next to the URL. The alias will be shown in the portlet instead of the URL. To add boxes for new URLs, click Add a bookmark line. To delete URLs, select the associated check box and click Delete.

Bookmarks

Open links

Specifies how the links in this portlet are opened. You can open and navigate the linked entries in a new browser window. This is the default option open and navigate the linked entries in the currently opened browser window. open the linked entries in a target browser window or frame. Type the name of the window or frame in the provided text box. open and navigate the linked entries in the HTML Viewer portlet. Type the channel name as specified in HTML Viewer.

HTML Viewer
Use this portlet to insert any Web page into a page. The Web page is specified by a URL address.

Administration and Security Guide 733

Appendix E: User Reference Help for Portal Services

To modify the properties for this portlet, click the edit button to open the properties page. If the edit button is disabled or not visible, the administrator did not make these settings available to you. In the portlet properties page, to reset the default portlet settings, or to return to the settings specified by your administrator, click the reset button in the portlet title bar. To exit the properties page or click Cancel.

without saving the changes, click the return button

The following table shows the properties that you can change.

Property
Title

Description
Specifies the title of the portlet. If no title is specified, the Web page URL address is used by default. You can specify a title for each supported language version of the product.

Language

Specifies the product language version in which the title appears. You can assign the same title for multiple language versions. Specifies the URL address of the Web page you want to insert in the portlet. Enables communication between this portlet and other Cognos Utility portlets in a page. The portlets can communicate using the default, empty channel. To set up communication between specific portlets, type the same channel name for the portlets that you want to interact. The channel name can contain only letters, numbers, and underscore (_) characters, and must not contain any spaces. For example, Cognos, Cognos_Portlets, or CognosPortlets.

HTML content

Channel name

Portlet height in pixels Specifies the portlet height in pixels. If the report image is larger than this setting, scroll bars appear when you view the report.

Image Viewer
Use this portlet to insert an image into a page. The image must be a single file that is accessible by a URL address. The image can also be used as a link. To modify the properties for this portlet, click the edit button to open the properties page. If the edit button is disabled or not visible, the administrator did not make these settings available to you.

734

Appendix E: User Reference Help for Portal Services In the portlet properties page, to reset the default portlet settings, or to return to the settings specified by your administrator, click the reset button in the portlet title bar. To exit the properties page or click Cancel.

without saving the changes, click the return button

The following table shows the properties that you can change.

Property
Title

Description
Specifies the title of the portlet. If no title is specified, the image URL address is used by default. You can specify a title for each supported language version of the product.

Language

Specifies the product language version in which the title appears. You can assign the same title for multiple language versions. Specifies the location of the image. Type the associated URL address.

Image

Target URL

Specifies the Web page where a link to the image or the image appears. Type the appropriate URL address.

Open links

Specifies how the links in this portlet are opened. You can open and navigate the linked entries in a new browser window. This is the default option open and navigate the linked entries in the currently opened browser window. open the linked entries in a target browser window or frame. Type the name of the window or frame in the provided text box open and navigate the linked entries in the HTML Viewer portlet. Type the channel name as specified in HTML Viewer.

Image size

Specifies the size of the image. You can leave the original size of the image, or customize the image by changing its height and width. You can also tile the image.

RSS Viewer
Use this portlet to show the content of a Real Simple Syndication (RSS) 1.0 or 2.0 news feed specified by a URL address. RSS is a format for syndicating news and is used by many Web sites to publish frequently updated content. Administration and Security Guide 735

Appendix E: User Reference Help for Portal Services

To modify the properties for this portlet, click the edit button to open the properties page. If the edit button is disabled or not visible, the administrator did not make these settings available to you. In the portlet properties page, to reset the default portlet settings, or to return to the settings specified by your administrator, click the reset button in the portlet title bar. To exit the properties page or click Cancel.

without saving the changes, click the return button

The following table shows the properties that you can change.

Property
Title

Description
Specifies the title of the portlet. If no title is specified, the Web page URL address is used by default. You can specify a title for each supported language version of the product.

Language

Specifies the product language version in which the title appears. You can assign the same title for multiple language versions. Specifies the URL address that identifies the RSS channel feed. The RSS channel includes a list of links to specific Web pages. The links may include a title and a short description of the linked story.

URL

Features to expose

Specifies how the entries in this portlet are shown. Use the Show details option to include a description of an entry. Use the Show the RSS channel signature option to include an image, such as a logo, associated with the entry. Use the Alternating backgrounds option to separate entries in long lists with different background colors to make the entries easier to read.

Open links

Specifies how the links in RSS Viewer are opened. You can open and navigate the linked entries in a new browser window. This is the default option. open and navigate the linked entries in the currently opened browser window. open the linked entries in a target browser window or frame. Type the name of the window or frame in the provided text box. open and navigate the linked entries in the HTML Viewer portlet. Type the channel name as specified in HTML Viewer.

736

Appendix E: User Reference Help for Portal Services

Property
Maximum displayed entries

Description
Specifies the maximum number of URLs to display in the portlet.

HTML Source
Use this portlet to insert custom text and images into a page. This portlet adds a Freeform HTML code to the page, as typed by the user. For security reasons, the HTML tags that could pose a cross-site scripting threat, or break the integrity of the page, are not supported. If invalid HTML code is added, the portlet may not render it successfully. In this situation, you may need to delete the portlet from the page and start again. For more information about supported tags, see the table in this section. To modify the properties for this portlet, click the edit button to open the properties page. If the edit button is disabled or not visible, the administrator did not make these settings available to you. In the portlet properties page, to reset the default portlet settings, or to return to the settings specified by your administrator, click the reset button in the portlet title bar. To exit the properties page or click Cancel.

without saving the changes, click the return button

The following table shows the properties used to configure this portlet.

Property
Title

Description
Specifies the title of the portlet. If no title is specified, the Web page URL address is used by default. You can specify a title for each supported language version of the product.

Language

Specifies the product language version in which the title appears. You can assign the same title for multiple language versions.

Administration and Security Guide 737

Appendix E: User Reference Help for Portal Services

Property
HTML Code

Description
Specifies the HTML code to render in the view mode of the portlet. The code can be in any supported language. Type valid HTML code that contains: supported HTML tags The following tags are not supported: <BODY>, </BODY>, <FORM>, </FORM>, <HTML>, </HTML> These tags are filtered and removed from the code. <HEAD>, </HEAD>, <FRAMESET>, </FRAMESET>, <FRAME></FRAME> These tags are filtered and removed from the code including the content between the start and end tags. <script> JavaScript is not supported. supported attributes for the tags matching start and end tags Ensure that all start tags have matching end tags. When the start and end tags are not matched, the missing tag is removed, but the content remains. absolute URLs in references to images and external resources, such as CSS files The URLs must include server names. Relative URLs are not supported. Note: You must have the required permissions for the Styles and portlets secured feature in IBM Cognos 8 to access this property

Multi-page
Use this portlet to create a dashboard with multiple tabs. To modify the properties for this portlet, click the edit button to open the properties page. If the edit button is disabled or not visible, the administrator did not make these settings available to you. In the portlet properties page, to reset the default portlet settings, or to return to the settings specified by your administrator, click the reset button in the portlet title bar. To exit the properties page or click Cancel.

without saving the changes, click the return button

738

Appendix E: User Reference Help for Portal Services The following table shows the properties that you can change.

Property
Title

Description
Specifies the title of the portlet. If no title is specified, the Web page URL address is used by default. You can specify a title for each supported language version of the product.

Language

Specifies the product language version in which the title appears. You can assign the same title for multiple language versions. Specifies a folder or package in Public Folders where the entries for the portlet tabs reside. The entries can be pages, reports, shortcuts, folders, and so on. Specifies how the tabs appear in the dashboard: horizontally at the top of the page, or vertically on the left side of the page. Shows the icons that represent the type of entry in each tab. For example, if the entry is a shortcut, the shortcut icon will be included in the tab. Specifies the default width in pixels for vertical tabs. Specifies whether to show the tab menu button in the top, left side of the page. The tab menu is used to add, delete, and reorder the page tabs, and to edit the page.

Source folder for pages

Display Style

Show icons in tabs

Vertical tabs width Show page menu

Administration and Security Guide 739

Appendix E: User Reference Help for Portal Services

740

Appendix F: Schema for Data Source Commands

When you work with data source connections, you can also add or edit data source commands. Data source commands are run when the query engine performs specific actions on a database, such as opening a connection or closing a user session. For example, you can use data source commands to set up an Oracle proxy connection or virtual private database. For more information, see "Using Database Commands for Oracle, DB2, and Microsoft SQL Server" (p. 190). A data source command block is an XML document that is used to specify the commands that the database should run. This document contains reference material about each element in the XML schema that defines the command blocks. After the description of each element, separate sections describe the child elements that the element can or must have the parent elements that can contain the element

There are also code samples that show how you can use elements in a command block.

Element Model Group

The list of children for each element is presented as a DTD model group, and elements are listed in the order that they must occur. The following standard notation is used.

Symbol
Plus sign (+)

Meaning
The preceding element may be repeated more than once but must occur at least once. The preceding element is optional. It may be absent or it may occur exactly once. An asterisk (*) after an element specifies that the element is optional. It may occur zero or more times. If an element has no plus sign (+), question mark (?), or asterisk (*) following it, the element must occur only once. Parentheses group elements. Element groups are controlled using the same symbols as elements. A bar (|) between elements specifies that one of the listed elements must be present.

Question mark (?)

Asterisk (*)

None

Parentheses

Bar (|)

Administration and Security Guide 741

Appendix F: Schema for Data Source Commands

Symbol
Comma (,)

Meaning
The elements that it separates must be present in the specified order.

commandBlock
Defines a group of commands that the database runs when specific events occur. This is the root element of the schema.

Child Elements of commandBlock Element

(commands)+

Parent Elements of commandBlock Element

The commandBlock element has no parent elements.

commands
Specifies the set of commands that the database runs. The commands run in the order that they appear within the commandBlock.

commands Sample Code

Here is an example of how you can use this element in a commandBlock.
<commandBlock> <commands> <sessionStartCommand> <arguments> <argument> <name>OCI_ATTR_USERNAME</name> <value>PROXY_USER1</value> </argument> </arguments> </sessionStartCommand> </commands> </commandBlock>

Child Elements of commands Element

(sessionStartCommand|sessionEndCommand|setCommand|sqlCommand)*

Parent Elements of commands Element

commandBlock

sessionStartCommand
Defines a command used to begin a proxy session in the database.

742

Appendix F: Schema for Data Source Commands There should be only one sessionStartCommand per commandBlock. If the commandBlock contains more than one sessionStartCommand, only the last one will be used to create a proxy session.

sessionStartCommand Sample Code

Here is an example of how you can use this element in a commandBlock.
<commandBlock> <commands> <sessionStartCommand> <arguments> <argument> <name>OCI_ATTR_USERNAME</name> <value>PROXY_USER1</value> </argument> <argument> <name>OCI_ATTR_PASSWORD</name> <value>password1</value> </argument> </arguments> </sessionStartCommand> </commands>

Child Elements of sessionStartCommand Element

(arguments)?

Parent Elements of sessionStartCommand Element

commands

sessionEndCommand
Defines a command used to terminate a proxy session in the database. If no sessionEndCommand is supplied, the proxy session will be terminated upon disconnecting from the database.

sessionEndCommand Sample Code

Here is an example of how you can use this element in a commandBlock.
<commandBlock> <commands> <sessionEndCommand> <arguments/> </sessionEndCommand> </commands> </commandBlock>

Child Elements of sessionEndCommand Element

(arguments)?

Parent Elements of sessionEndCommand Element

commands

Administration and Security Guide 743

Appendix F: Schema for Data Source Commands

arguments
Specifies the argument values to be used with the command.

arguments Sample Code

Here is an example of how you can use this element in a commandBlock.
<commandBlock> <commands> <sessionEndCommand> <arguments/> </sessionEndCommand> </commands> </commandBlock>

Child Elements of arguments Element

(argument)*

Parent Elements of arguments Element

sessionStart sessionEnd

argument
Defines an argument value for a call to a database API.

argument Sample Code

Here is an example of how you can use this element in a commandBlock.
<commandBlock> <commands> <sessionStartCommand> <arguments> <argument> <name>OCI_ATTR_USERNAME</name> <value>PROXY_USER1</value> </argument> <argument> <name>OCI_ATTR_PASSWORD</name> <value>password1</value> </argument> </arguments> </sessionStartCommand> </commands> </commandBlock>

Child Elements of argument Element

(name, value)

Parent Elements of argument Element

744 arguments

Appendix F: Schema for Data Source Commands

setCommand
This element is reserved for future use.

sqlCommand
Defines a command that represents a native SQL statement to be run by the database.

sqlCommand Sample Code

Here is an example of how you can use this element in a commandBlock.
<commandBlock> <commands> <sqlCommand> <sql> BEGIN PKG1.STORED_PROC1; END; </sql> </sqlCommand> </commands> </commandBlock>

Child Elements of sqlCommand Element

(sql)

Parent Elements of sqlCommand Element

commands

sql
Specifies the SQL statement for the database to run. The SQL statement must be in native SQL.

sql Sample Code

Here is an example of how you can use this element in a commandBlock.
<commandBlock> <commands> <sqlCommand> <sql> BEGIN PKG1.STORED_PROC1; END; </sql> </sqlCommand> </commands> </commandBlock>

Child Elements of sql Element

The sql element has no child elements.

Parent Elements of sql Element

sqlCommand

name
Identifies the argument to be set. Administration and Security Guide 745

Appendix F: Schema for Data Source Commands The value of the name element must be one of: OCI_ATTR_USERNAME OCI_ATTR_PASSWORD

name Sample Code

Here is an example of how you can use this element in a commandBlock.
<commandBlock> <commands> <sessionStartCommand> <arguments> <argument> <name>OCI_ATTR_USERNAME</name> <value>PROXY_USER1</value> </argument> </arguments> </sessionStartCommand> </commands> </commandBlock>

Child Elements of name Element

The name element has no child elements.

Parent Elements of name Element

argument setCommand

value
Specifies the value to be used for the argument.

value Sample Code

Here is an example of how you can use this element in a commandBlock.
<commandBlock> <commands> <sessionStartCommand> <arguments> <argument> <name>OCI_ATTR_USERNAME</name> <value>PROXY_USER1</value> </argument> </arguments/> </sessionStartCommand> </commands> </commandBlock>

Child Elements of value Element

The value element has no child elements.

746

Appendix F: Schema for Data Source Commands

Parent Elements of value Element

argument setCommand

Administration and Security Guide 747

Appendix F: Schema for Data Source Commands

748

Appendix G: Data Schema for Log Messages

If you configure IBM Cognos 8 to send log messages to a database (p. 79), the tables and the columns in each table are automatically created when you start the IBM Cognos 8 services. To avoid name conflicts with database keywords, all column names in the log database have the prefix "COGIPF". If you are upgrading from ReportNet 1.1 MR1 or MR2 to IBM Cognos Series 8, the prefixes exist in the log database already and you do not need to make any changes. However, if you are upgrading from a release before ReportNet 1.1 MR1, to continue using reports that are based on the sample model from the previous release, you must update your audit metadata package to reflect the new column names. You can either: reimport the Sample Deployment Archive republish the package using the sample model

If you have created your own log database model, you must add the prefix "COGIPF" to the column names of the logging database tables in the model.

Table Definitions
Log messages are recorded in a table in the logging database under certain conditions. These conditions depend on the logging level that you configure in the Web portal. For information about logging levels, see "Log Messages" (p. 80). When a user logs on to IBM Cognos 8, a session ID is assigned and recorded in all log messages. You can use the session ID to identify all actions performed by a user. The database table definitions that are created in the logging database are described in the following table, with a cross-reference to associated column definitions.

Table Name
COGIPF_ACTION (p. 752)

Description
Stores information about operations performed on objects Stores user logon and logoff information Stores information about queries that IBM Cognos 8 makes to other components Stores parameter information logged by a component Stores information about job runs Stores information about job step runs

COGIPF_USERLOGON (p. 753) COGIPF_NATIVEQUERY (p. 754)

COGIPF_PARAMETER (p. 755) COGIPF_RUNJOB (p. 756) COGIPF_RUNJOBSTEP (p. 757)

Administration and Security Guide 749

Appendix G: Data Schema for Log Messages

Table Name
COGIPF_RUNREPORT (p. 759) COGIPF_VIEWREPORT (p. 763) COGIPF_EDITQUERY (p. 761) COGIPF_AGENTBUILD (p. 764) COGIPF_AGENTRUN (p. 766)

Description
Stores information about report runs Stores information about report view requests Stores information about query runs Stores information about agent mail delivery Stores information about agent activity including tasks and delivery

COGIPF_THRESHOLD _VIOLATIONS Stores information about threshold violations for system (p. 766) metrics

Table Interactions
An example of table interactions is shown in the following diagram. Your audit sample may be different depnding on your needs.

750

Appendix G: Data Schema for Log Messages

(1)

COGIPF_ACTION

COGIPF_NATIVEQUERY

COGIPF_VIEWREPORT

COGIPF_AGENTBUILD

COGIPF_AGENTRUN

COGIPF_PARAMETER

COGIPF_RUNREPORT

COGIPF_USERLOGON

COGIPF_RUNJOB

(2)

COGIPF_RUNJOBSTEP

COGIPF_EDITQUERY

1.

Interactions with COGIPF_PARAMETER are COGIPF_REQUESTID= COGIPF_REQUESTID Interactions with COGIPF_USERLOGON are COGIPF_SESSIONID= COGIPF_SESSIONID

2.

COGIPF_REQUESTID= COGIPF_REQUESTID

Administration and Security Guide 751

Appendix G: Data Schema for Log Messages

COGIPF_ACTION Table
The COGIPF_ACTION table contains the following columns.

Column name
COGIPF_HOST_ IPADDR

Description

Data type

The host IP address where the log message VARCHAR2 (15) is generated The host port number NUMBER

COGIPF_HOST_ PORT COGIPF_PROC_ID

The process ID assigned by the operating NUMBER system The local date and time when the log mes- DATE sage was generated NUMBER

COGIPF_LOCAL TIMESTAMP

COGIPF_TIMEZONE_ OFF- The time zone, offset from GMT SET COGIPF_SESSIONID COGIPF_ REQUESTID The identification number of the session The identification number of the request

VARCHAR2 (255) VARCHAR2 (255) UNIQUE NOT NULL VARCHAR2 (255)

COGIPF_STEPID

The identification number for the step within a job run (empty if there is none)

COGIPF_ SUBREQUESTID

The identification number of the compon- VARCHAR2 (255) ent subrequest The identification number of the thread where the request is run VARCHAR2 (255)

COGIPF_THREADID

COGIPF_ COMPONENTID The name of the component that generates VARCHAR2 (4) the indication COGIPF_ BUILDNUMBER The major build number for the component NUMBER that generates the indication The level of the indication The action performed on the object The object on which the operation is run NUMBER VARCHAR2 (255) VARCHAR2 (255)

COGIPF_ LOG_LEVEL COGIPF_ OPERATION COGIPF_ TARGET_TYPE

752

Appendix G: Data Schema for Log Messages

Column name
COGIPF_ TARGET_PATH COGIPF_STATUS

Description
The target object path

Data type
VARCHAR2 (512)

The status of the operation: blank if execu- VARCHAR2 (255) tion has not completed, success, warning, or failure VARCHAR2 (2000)

COGIPF_ ERRORDETAILS Error details

COGIPF_USERLOGON Table
The COGIPF_USERLOGON table contains the following columns.

Column name
COGIPF_ HOST_IPADDR

Description

Data type

The host IP address where the log message VARCHAR2 (15) is generated The host port number NUMBER

COGIPF_ HOST_PORT COGIPF_PROC_ID

The process ID assigned by the operating NUMBER system The local date and time when the log mes- DATE sage was generated NUMBER

COGIPF_ LOCALTIMESTAMP

COGIPF_TIMEZONE_ OFF- The time zone, offset from GMT SET COGIPF_SESSIONID COGIPF_REQUESTID The identification number of the session The identification number of the request

VARCHAR2 (255) VARCHAR2 (255) UNIQUE NOT NULL VARCHAR2 (255)

COGIPF_STEPID

The identification number for the step within a job run (empty if there is none)

COGIPF_ SUBREQUESTID

The identification number of the compon- VARCHAR2 (255) ent subrequest The identification number of the thread where the request is run VARCHAR2 (255)

COGIPF_THREADID

Administration and Security Guide 753

Appendix G: Data Schema for Log Messages

Column name

Description

Data type

COGIPF_ COMPONENTID The name of the component that generates VARCHAR2 (4) the indication COGIPF_ BUILDNUMBER The major build number for the component NUMBER that generates the indication The level of the indication NUMBER

COGIPF_LOG_LEVEL COGIPF_STATUS

The status of the operation: blank, success, VARCHAR2 (255) warning, or failure VARCHAR2 (2000) VARCHAR2 (255)

COGIPF_ ERRORDETAILS Error details

COGIPF_ LOGON_OPERA- Logon, logoff, or logon expired TION COGIPF_USERNAME COGIPF_USERID COGIPF_ NAMESPACE The display name of the user The username of the user The namespace display name

VARCHAR2 (255) VARCHAR2 (255) VARCHAR2 (255)

COGIPF_NATIVEQUERY Table
The COGIPF_NATIVEQUERY table contains the following columns.

Column name
COGIPF_HOST_ IPADDR

Description

Data type

The host IP address where the log message VARCHAR2 (15) is generated The host port number NUMBER

COGIPF_HOST_ PORT COGIPF_PROC_ID

The process ID assigned by the operating NUMBER system The local date and time when the log mes- DATE sage was generated NUMBER

COGIPF_ LOCALTIMESTAMP

COGIPF_TIMEZONE_ OFF- The time zone, offset from GMT SET COGIPF_SESSIONID The identification number of the session

VARCHAR2 (255)

754

Appendix G: Data Schema for Log Messages

Column name
COGIPF_REQUESTID

Description
The identification number of the request

Data type
VARCHAR2 (255) NOT NULL VARCHAR2 (255)

COGIPF_STEPID

The identification number for the step within a job run (empty if there is none)

COGIPF_ SUBREQUESTID

The identification number of the compon- VARCHAR2 (255) ent subrequest The identification number of the thread where the request is run VARCHAR2 (255)

COGIPF_THREADID

COGIPF_ COMPONENTID The name of the component that generates VARCHAR2 (4) the indication COGIPF_ BUILDNUMBER The major build number for the component NUMBER that generates the indication The level of the indication NUMBER NTEXT

COGIPF_LOG_LEVEL

COGIPF_ REQUESTSTRING The query request string made to other components

COGIPF_PARAMETER Table
The COGIPF_PARAMETER table contains the following columns.

Column name
COGIPF_REQUESTID

Description
The identification number of the request

Data type
VARCHAR2 (255) UNIQUE NOT NULL VARCHAR2 (255)

COGIPF_STEPID

The identification number for the step within a job run (empty if there is none) The action performed on the object The object on which the operation is run The name of the parameter logged by a component

COGIPF_OPERATION COGIPF_TARGET_ TYPE COGIPF_ PARAMETER_NAME

VARCHAR2 (255) VARCHAR2 (255) VARCHAR2 (255)

Administration and Security Guide 755

Appendix G: Data Schema for Log Messages

Column name
COGIPF_ PARAMETER_VALUE

Description
The value of the parameter logged by a component

Data type
VARCHAR2 (512)

COGIPF_RUNJOB Table
The COGIPF_RUNJOB table contains the following columns.

Column name
COGIPF_HOST_ IPADDR

Description

Data type

The host IP address where the log message VARCHAR2 (15) is generated The host port number NUMBER

COGIPF_HOST_PORT COGIPF_PROC_ID

The process ID assigned by the operating NUMBER system The local date and time when the log mes- DATE sage was generated While the report is executing, this is the time that the report execution started. After the report execution is complete, this is the end time of report execution. To check if execution is complete, see COGIPF_STATUS. A blank entry means an incomplete execution. A filled entry means execution completed. To calculate the execution start time for a report that has already completed execution, subtract COGIPF_RUNTIME from COGIPF_LOCALTIMESTAMP.

COGIPF_ LOCALTIMESTAMP

COGIPF_TIMEZONE_ OFF- The time zone, offset from GMT SET COGIPF_SESSIONID COGIPF_REQUESTID The identification number of the session The identification number of the request

NUMBER

VARCHAR2 (255) VARCHAR2 (255) UNIQUE NOT NULL VARCHAR2 (255)

COGIPF_STEPID

The identification number for the step within a job run (empty if there is none)

756

Appendix G: Data Schema for Log Messages

Column name
COGIPF_ SUBREQUESTID

Description

Data type

The identification number of the compon- VARCHAR2 (255) ent subrequest The identification number of the thread where the request is run VARCHAR2 (255)

COGIPF_THREADID

COGIPF_ COMPONENTID The name of the component that generates VARCHAR2 (4) the indication COGIPF_ BUILDNUMBER The major build number for the component NUMBER that generates the indication The level of the indication The object on which the operation is run The job path NUMBER VARCHAR2 (255) VARCHAR2 (512)

COGIPF_LOG_LEVEL COGIPF_ TARGET_TYPE COGIPF_JOBPATH COGIPF_STATUS

The status of the operation: blank, success, VARCHAR2 (255) warning, or failure VARCHAR2 (2000)

COGIPF_ ERRORDETAILS Error details

COGIPF_RUNTIME

The number of milliseconds it took the job NUMBER to run

COGIPF_RUNJOBSTEP Table
The COGIPF_RUNJOBSTEP table contains the following columns.

Column name
COGIPF_HOST_ IPADDR

Description

Data type

The host IP address where the log message VARCHAR2 (15) is generated The host port number NUMBER

COGIPF_HOST_PORT COGIPF_PROC_ID

The process ID assigned by the operating NUMBER system

Administration and Security Guide 757

Appendix G: Data Schema for Log Messages

Column name
COGIPF_ LOCALTIMESTAMP

Description

Data type

The local date and time when the log mes- DATE sage was generated While the report is executing, this is the time that the report execution started. After the report execution is complete, this is the end time of report execution. To check if execution is complete, see COGIPF_STATUS. A blank entry means an incomplete execution. A filled entry means execution completed. To calculate the execution start time for a report that has already completed execution, subtract COGIPF_RUNTIME from COGIPF_LOCALTIMESTAMP.

COGIPF_ TIMEZONE_OFF- The time zone, offset from GMT SET COGIPF_SESSIONID COGIPF_REQUESTID The identification number of the session The identification number of the request

NUMBER

VARCHAR2 (255) VARCHAR2 (255) UNIQUE NOT NULL VARCHAR2 (255)

COGIPF_STEPID

The identification number for the step within a job run (empty if there is none)

COGIPF_ SUBREQUESTID

The identification number of the compon- VARCHAR2 (255) ent subrequest The identification number of the thread where the request is run VARCHAR2 (255)

COGIPF_THREADID

COGIPF_ COMPONENTID The name of the component that generates VARCHAR2 (4) the indication COGIPF_ BUILDNUMBER The major build number for the component NUMBER that generates the indication The level of the indication The object on which the operation is run NUMBER VARCHAR2 (255)

COGIPF_LOG_LEVEL COGIPF_ TARGET_TYPE

758

Appendix G: Data Schema for Log Messages

Column name
COGIPF_ JOBSTEPPATH COGIPF_STATUS

Description
The job step path

Data type
VARCHAR2 (512)

The status of the operation: blank, success, VARCHAR2 (255) warning, or failure VARCHAR2 (2000) NUMBER

COGIPF_ ERRORDETAILS Error details

COGIPF_RUNTIME

The number of milliseconds it took the jobstep run

COGIPF_RUNREPORT Table
The COGIPF_RUNREPORT table contains the following columns.

Column name
COGIPF_ HOST_IPADDR

Description

Data type

The host IP address where the log message VARCHAR2 (15) is generated The host port number NUMBER

COGIPF_HOST_PORT COGIPF_PROC_ID

The process ID assigned by the operating NUMBER system The local date and time when the log mes- DATE sage was generated While the report is executing, this is the time that the report execution started. After the report execution is complete, this is the end time of report execution. To check if execution is complete, see COGIPF_STATUS. A blank entry means an incomplete execution. A filled entry means execution completed. To calculate the execution start time for a report that has already completed execution, subtract COGIPF_RUNTIME from COGIPF_LOCALTIMESTAMP.

COGIPF_ LOCALTIMESTAMP

COGIPF_TIMEZONE_ OFF- The time zone, offset from GMT SET

NUMBER

Administration and Security Guide 759

Appendix G: Data Schema for Log Messages

Column name
COGIPF_SESSIONID COGIPF_REQUESTID

Description
The identification number of the session The identification number of the request

Data type
VARCHAR2 (255) VARCHAR2 (255) UNIQUE NOT NULL VARCHAR2 (255)

COGIPF_STEPID

The identification number for the step within a job run (empty if there is none)

COGIPF_ SUBREQUESTID

The identification number of the compon- VARCHAR2 (255) ent subrequest The identification number of the thread where the request is run VARCHAR2 (255)

COGIPF_THREADID

COGIPF_ COMPONENTID The name of the component that generates VARCHAR2 (4) the indication COGIPF_ BUILDNUMBER The major build number for the component NUMBER that generates the indication The level of the indication NUMBER

COGIPF_LOG_LEVEL COGIPF_ TARGET_TYPE

The object on which the operation is run. VARCHAR2 (255) The values include: ReportService is an interactive report PromptForward ReportService is a report generated after a prompt PromptBackward ReportService is a report generated after the user moved to the previous prompt page BatchReportService is a batch or scheduled run report VARCHAR2 (1024)

COGIPF_ REPORTPATH

The report path

COGIPF_STATUS

The status of the operation: blank, success, VARCHAR2 (255) warning, or failure

760

Appendix G: Data Schema for Log Messages

Column name

Description

Data type
VARCHAR2 (2000) NUMBER

COGIPF_ ERRORDETAILS Error details

COGIPF_RUNTIME

The number of milliseconds it took the report to run The name of the report that was run The package that the report is associated with

COGIPF_ REPORTNAME COGIPF_PACKAGE

VARCHAR2 (512) VARCHAR2 (1024)

COGIPF_MODEL

The model that the report is associated with VARCHAR2 (512)

COGIPF_EDITQUERY Table
The COGIPF_EDITQUERY table contains the following columns.

Column name
COGIPF_ HOST_IPADDR

Description

Data type

The host IP address where the log message VARCHAR2 (15) is generated The host port number NUMBER

COGIPF_HOST_PORT COGIPF_PROC_ID

The process ID assigned by the operating NUMBER system The local date and time when the log mes- DATE sage was generated While the report is executing, this is the time that the report execution started. After the report execution is complete, this is the end time of report execution. To check if execution is complete, see COGIPF_STATUS. A blank entry means an incomplete execution. A filled entry means execution completed. To calculate the execution start time for a report that has already completed execution, subtract COGIPF_RUNTIME from COGIPF_LOCALTIMESTAMP.

COGIPF_ LOCALTIMESTAMP

Administration and Security Guide 761

Appendix G: Data Schema for Log Messages

Column name

Description

Data type
NUMBER

COGIPF_TIMEZONE_ OFF- The time zone, offset from GMT SET COGIPF_SESSIONID COGIPF_REQUESTID The identification number of the session The identification number of the request

VARCHAR2 (255) VARCHAR2 (255) UNIQUE NOT NULL VARCHAR2 (255)

COGIPF_STEPID

The identification number for the step within a job run (empty if there is none)

COGIPF_ SUBREQUESTID

The identification number of the compon- VARCHAR2 (255) ent subrequest The identification number of the thread where the request is run VARCHAR2 (255)

COGIPF_THREADID

COGIPF_ COMPONENTID The name of the component that generates VARCHAR2 (4) the indication COGIPF_ BUILDNUMBER The major build number for the component NUMBER that generates the indication The level of the indication The object on which the operation is run The report path NUMBER VARCHAR2 (255) VARCHAR2 (1024)

COGIPF_LOG_LEVEL COGIPF_ TARGET_TYPE COGIPF_ QUERYPATH

COGIPF_STATUS

The status of the operation: blank, success, VARCHAR2 (255) warning, or failure VARCHAR2 (2000) NUMBER

COGIPF_ ERRORDETAILS Error details

COGIPF_RUNTIME

The number of milliseconds it took the query to run The name of the report that was queried The package that the report is associated with

COGIPF_ QUERYNAME COGIPF_PACKAGE

VARCHAR2 (512) VARCHAR2 (1024)

762

Appendix G: Data Schema for Log Messages

Column name
COGIPF_MODEL

Description

Data type

The model that the report is associated with VARCHAR2 (512)

COGIPF_VIEWREPORT Table
The COGIPF_VIEWREPORT table contains the following columns.

Column name
COGIPF_ HOST_IPADDR

Description

Data type

The host IP address where the log message VARCHAR2 (15) is generated The host port number NUMBER

COGIPF_HOST_PORT COGIPF_PROC_ID

The process ID assigned by the operating NUMBER system The local date and time when the log mes- DATE sage was generated While the report is executing, this is the time that the report execution started. After the report execution is complete, this is the end time of report execution. To check if execution is complete, see COGIPF_STATUS. A blank entry means an incomplete execution. A filled entry means execution completed. To calculate the execution start time for a report that has already completed execution, subtract COGIPF_RUNTIME from COGIPF_LOCALTIMESTAMP.

COGIPF_ LOCALTIMESTAMP

COGIPF_TIMEZONE_ OFF- The time zone, offset from GMT SET COGIPF_SESSIONID COGIPF_REQUESTID The identification number of the session The identification number of the request

NUMBER

VARCHAR2 (255) VARCHAR2 (255) UNIQUE NOT NULL VARCHAR2 (255)

COGIPF_STEPID

The identification number for the step within a job run (empty if there is none)

Administration and Security Guide 763

Appendix G: Data Schema for Log Messages

Column name
COGIPF_ SUBREQUESTID

Description

Data type

The identification number of the compon- VARCHAR2 (255) ent subrequest The identification number of the thread where the request is run VARCHAR2 (255)

COGIPF_THREADID

COGIPF_ COMPONENTID The name of the component that generates VARCHAR2 (4) the indication COGIPF_BUILDNUMBER The major build number for the component NUMBER that generates the indication The level of the indication The object on which the operation is run The report path NUMBER VARCHAR2 (255) VARCHAR2 (1024)

COGIPF_LOG_LEVEL COGIPF_ TARGET_TYPE COGIPF_ REPORTPATH

COGIPF_STATUS

The status of the operation: blank, success, VARCHAR2 (255) warning, or failure VARCHAR2 (2000) NUMBER

COGIPF_ ERRORDETAILS Error details

COGIPF_RUNTIME

The number of milliseconds it took the query to run The name of the report that was viewed The package with which the report is associated

COGIPF_ REPORTNAME COGIPF_PACKAGE

VARCHAR2 (512) VARCHAR2 (1024) VARCHAR2 (255)

COGIPF_ REPORTFORMAT The format of the report (p. 357) COGIPF_MODEL

The model that the report is associated with VARCHAR2 (512)

COGIPF_AGENTBUILD Table
The COGIPF_AGENTBUILD table contains the following columns.

764

Appendix G: Data Schema for Log Messages

Column name
COGIPF_ HOST_IPADDR

Description

Data type

The host IP address where the log message VARCHAR2 (15) is generated The host port number NUMBER

COGIPF_HOST_PORT COGIPF_PROC_ID

The process ID assigned by the operating NUMBER system The local date and time when the log mes- DATE sage was generated NUMBER

COGIPF_ LOCALTIMESTAMP

COGIPF_TIMEZONE_OFF- The time zone, offset from GMT SET COGIPF_SESSIONID COGIPF_REQUESTID The identification number of the session The identification number of the request

VARCHAR2 (255) VARCHAR2 (255) UNIQUE NOT NULL VARCHAR2 (255)

COGIPF_STEPID

The identification number for the step within a job run (empty if there is none)

COGIPF_ SUBREQUESTID

The identification number of the compon- VARCHAR2 (255) ent subrequest The identification number of the thread where the request is run VARCHAR2 (255)

COGIPF_THREADID

COGIPF_ COMPONENTID The name of the component that generates VARCHAR2 (4) the indication COGIPF_BUILD NUMBER The major build number for the component NUMBER that generates the indication The level of the indication The operation The object on which the operation is run NUMBER VARCHAR2 (128) VARCHAR2 (255) VARCHAR2 (512)

COGIPF_LOG_LEVEL COGIPF_OPERATION COGIPF_ TARGET_TYPE

COGIPF_TARGET_ NAME The target name

Administration and Security Guide 765

Appendix G: Data Schema for Log Messages

Column name
COGIPF_ TARGET_PATH

Description
The target path

Data type
VARCHAR2 (1024)

COGIPF_STATUS

The status of the operation: blank, success, VARCHAR2 (255) warning, or failure VARCHAR2 (2000) VARCHAR2 (1024) INTEGER VARCHAR2 (512) VARCHAR2 (512)

COGIPF_ ERRORDETAILS Error details

COGIPF_AGENT_ PATH

The agent name

COGIPF_ SCHEDULETIME The target schedule time COGIPF_USER COGIPF_EMAIL The user who created the agent The email address

COGIPF_AGENTRUN Table
The COGIPF_AGENTRUN table contains the following columns.

Column name
COGIPF_ HOST_IPADDR

Description

Data type

The host IP address where the log message VARCHAR2 (15) is generated The host port number NUMBER

COGIPF_HOST_PORT COGIPF_PROC_ID

The process ID assigned by the operating NUMBER system The local date and time when the log mes- DATE sage was generated NUMBER

COGIPF_ LOCALTIMESTAMP

COGIPF_TIMEZONE_OFF- The time zone, offset from GMT SET COGIPF_SESSIONID COGIPF_REQUESTID The identification number of the session The identification number of the request

VARCHAR2 (255) VARCHAR2 (255) UNIQUE NOT NULL

766

Appendix G: Data Schema for Log Messages

Column name
COGIPF_STEPID

Description
The identification number for the step within a job run (empty if there is none)

Data type
VARCHAR2 (255)

COGIPF_ SUBREQUESTID

The identification number of the compon- VARCHAR2 (255) ent subrequest The identification number of the thread where the request is run VARCHAR2 (255)

COGIPF_THREADID

COGIPF_ COMPONENTID The name of the component that generates VARCHAR2 (4) the indication COGIPF_BUILD NUMBER The major build number for the component NUMBER that generates the indication The level of the indication The operation The object on which the operation is run The target path NUMBER VARCHAR2 (128) VARCHAR2 (255) VARCHAR2 (1024)

COGIPF_LOG_LEVEL COGIPF_OPERATION COGIPF_ TARGET_TYPE COGIPF_ TARGET_PATH

COGIPF_STATUS

The status of the operation: blank, success, VARCHAR2 (255) warning, or failure VARCHAR2 (2000) VARCHAR2 (1024) INTEGER VARCHAR2 (512) VARCHAR2 (512) VARCHAR2 (512)

COGIPF_ ERROR_DETAILS Error details

COGIPF_AGENTPATH

The agent name

COGIPF_ SCHEDULETIME The target schedule time COGIPF_TARGET_ NAME The target name COGIPF_USER COGIPF_EMAIL The user who created the agent The email address

Administration and Security Guide 767

Appendix G: Data Schema for Log Messages

COGIPF_THRESHOLD_VIOLATIONS Table
The COGIPF_THRESHOLD_VIOLATIONS table contains the following columns. For more information, see "System Performance Metrics" (p. 91).

Column name
COGIPF_ HOST_IPADDR

Description

Data type

The host IP address where the log message VARCHAR2 (15) is generated The host port number NUMBER

COGIPF_HOST_PORT COGIPF_PROC_ID

The process ID assigned by the operating NUMBER system The local date and time when the log mes- DATE sage was generated NUMBER

COGIPF_ LOCALTIMESTAMP

COGIPF_TIMEZONE_OFF- The time zone, offset from GMT SET COGIPF_COMPONENTID

The identification number of the compon- VARCHAR2 (255) ent The identification number of the build NUMBER

COGIPF_BUILDNUMBER COGIPF_LOG_LEVEL

The logging level. Should always be 1 to NUMBER ensure that threshold violation information is available. A threshold for the metric has been crossed VARCHAR2 (255) The target type The target name The target path of the dispatcher that conatins the threshold manager VARCHAR2 (255) VARCHAR2 (4) VARCHAR2 (1024) VARCHAR2 (255)

COGIPF_ OPERATION COGIPF_TARGET_TYPE COGIPF_ TARGETNAME COGIPF_ TARGET_PATH

COGIPF_RESOURCE_TYPE The resource type that exceeds the threshold

COGIPF_ RESOURCE_PATH The path of the resource that exceeded the VARCHAR2 threshold value (2000) COGIPF_METRIC_NAME The name of the metric VARCHAR2 (1024)

768

Appendix G: Data Schema for Log Messages

Column name

Description

Data type
VARCHAR2 (1024)

COGIPF_ METRIC_VALUE The value of the metric

COGIPF_METRIC_ HEALTH COGIPF_LOWER_AVG_ THRSHLD

The status of the metric: good, average, or VARCHAR2 (512) poor The lower average threshold setting. If COGIPF_LOWER_AVG_THRSHLD_ XCL is 1, the metric score is average when the metric is less than this threshold setting. The metric score is good when the metric is greater than or equal than this value. If COGIPF_LOWER_AVG_THRSHLD_ XCL is 0 (zero), the metric score is average when the metric is less than or equal to this value. The metric score is good when the metric is greater than this value. VARCHAR2 (512)

COGIPF_LOWER_AVG_ THRSHLD_XCL

The flag that indicates if the threshold set- BOOLEAN ting in COGIPF_LOWER_AVG_THRSHLD is included when determining the metric score. If it is 0, the threshold setting is included when the metric score is determined. If it is 1, the threshold setting is not included when the metric score is determined.

COGIPF_LOWER_POOR_ THRSHLD

The lower poor threshold setting. If COGIPF_LOWER_POOR_THRSHLD_ XCL is 1, the metric score is poor when the metric is less than this threshold setting. If COGIPF_LOWER_POOR_THRSHLD_ XCL is 0 (zero), the metric score is poor when the metric is less than or equal to this value.

VARCHAR2 (512)

Administration and Security Guide 769

Appendix G: Data Schema for Log Messages

Column name
COGIPF_LOWER_POOR_ THRSHLD_EXCL

Description

Data type

The flag that indicates if the threshold set- BOOLEAN ting in COGIPF_LOWER_POOR_THRSHLD is included when determining the metric score. If it is 0, the threshold setting is included when the metric score is determined. If it is 1, the threshold setting is not included when the metric score is determined.

COGIPF_UPPER_AVG_ THRSHLD

The upper average threshold setting If COGIPF_UPPER_AVG_THRSHLD_ XCL is 1, the metric score is poor when the metric is less than this threshold setting. If COGIPF_UPPER_AVG_THRSHLD_ XCL is 0 (zero), the metric score is average when the metric is greater than or equal to this value. The metric score is good when the metric is less than or equal to this value.

VARCHAR2 (512)

COGIPF_UPPER_AVG_ THRSHLD_EXCL

The flag that indicates if the threshold set- BOOLEAN ting in COGIPF_UPPER_AVG_THRSHLD is included when determining the metric score. If it is 0, the threshold setting is included when the metric score is determined. If it is 1, the threshold setting is not included when the metric score is determined.

COGIPF_UPPER_POOR_ THRSHLD

The upper poor threshold setting. If COGIPF_UPPER_POOR_THRSHLD_ XCL is 1, the metric score is poor when the metric is less than this threshold setting. If COGIPF_UPPER_POOR_THRSHLD_ XCL is 0 (zero), the metric score is poor when the metric is greater than or equal to this value.

VARCHAR2 (512)

770

Appendix G: Data Schema for Log Messages

Column name
COGIPF_UPPER_POOR_ THRSHLD_EXCL

Description

Data type

The flag that indicates if the threshold set- BOOLEAN ting in COGIPF_UPPER_POOR_THRSHLD is included when determining the metric score. If it is 0, the threshold setting is included when the metric score is determined. If it is 1, the threshold setting is not included when the metric score is determined.

Administration and Security Guide 771

Appendix G: Data Schema for Log Messages

772

Appendix H: Performing Tasks in IBM Cognos 8 Using URLs

The URLs provide a quick and efficient way to start IBM Cognos 8 components and open specified content, such as reports, metrics, folders, or pages. You can use the URLs to start IBM Cognos 8 components access an IBM Cognos Connection page

You can use the URL Report sample program included with the IBM Cognos 8 Software Development Kit (SDK) to perform basic tasks by clicking embedded links on an active server page. For information about the samples installed with the SDK, see the Developer Guide. However, for complex tasks, such as scheduling, we recommend that you use the SDK to create a custom application. You can use various declarations to identify the requested action, depending on the IBM Cognos 8 component. Note: These declarations are not the same as the SDK methods exposed by the BI Bus API.

CGI Program and Alternative Gateways

All URL commands begin with a declaration of the end point for the request: either cognos.cgi or an alternative gateway. For IBM Cognos 8, the complete syntax is:
http://webservername:portnumber/cognos8/cgi-bin/cognos.cgi

If you configured IBM Cognos 8 to use a gateway other than the default CGI program, type the URL that corresponds to your gateway. For information about configuring gateways, see the Installation and Configuration Guide. The supported gateways are listed in the following table:

Gateway
ISAPI Apache Connector (Windows)

URL
http://webservername/cognos8/isapi http://webservername/cognos8/cgi-bin/mod_cognos.dll

Apache Connector (Solaris and AIX) http://webservername/cognos8/cgi-bin/mod_cognos.so Apache Connector (HPUX) Gateway Servlet http://webservername/cognos8/cgi-bin/mod_cognos.sl http://webservername:9300/ServletGateway/servlet/Gateway

Administration and Security Guide 773

Appendix H: Performing Tasks in IBM Cognos 8 Using URLs

Gateway
CGI

URL
http://webservername/cognos8

URL Methods
There are two methods to start IBM Cognos components: parameterized URL and cognosLaunch. Both methods perform the same function and use the same parameters. You can use either method to perform any UI task.

Parameterized URL Method

The parameterized URL method performs tasks or starts specific components using parameters typed in the Web browser address bar. Using both get and post methods, the launch.xts or cc.xts parameter starts the specified IBM Cognos 8 component. This method requires that the parameters use the following format:
&ArgumentName=ArgumentValue

The ArgumentName parameter specifies the type, and the ArgumentValue parameter specifies the value of the called arguments. All names and values must be character strings. This method is easier to begin using than the cognosLaunch method because it does not require advance preparation. However, the longer URL-encoded entries are restrained by browser character limits. You can use these commands to browse content in IBM Cognos Connection or view pages in Cognos Viewer.

Mandatory Parameterized URL Parameters

If you are using the parameterized URL method to start any component, you must use the following parameters with this syntax:
http://localhost/cgi-bin/cognos.cgi?b_action=xts.run&m=portal/launch.xts

followed by the specific component parameters you want to use. If you want to start Cognos Viewer using the parameterized URL method, use the following parameters with this syntax:
http://localhost/cgi-bin/cognos.cgi?b_action=cognosViewer

If you want to start IBM Cognos Connection using the parameterized URL method, use the following URL:
http://localhost/cgi-bin/cognos.cgi?b_action=xts.run&m=portal/cc.xts

The mandatory building blocks for parameterized URL commands are as follows:
gateway

This is the mandatory argument value that specifies the IBM Cognos 8 gateway. The gateway name in this example is http://server/cognos8/cgi-bin/cognos.cgi?

774

Appendix H: Performing Tasks in IBM Cognos 8 Using URLs IBM Cognos Application Firewall validation is enforced on URLs that contain this parameter. For more information see, "URL Validation" (p. 776)
b_action=xts.run

Identifies the action. To specify Cognos Viewer, use b_action=cognosViewer. For more information see, "Starting Cognos Viewer" (p. 783).
m=portal/launch.xts&ui.tool=tool_name

Identifies the IBM Cognos 8 component interface that displays the result. To start IBM Cognos Connection, use m=portal/cc.xts

cognosLaunch Method
The cognosLaunch method uses a JavaScript function to perform tasks and start components. To use the launch utility in a Web page, you must first include the following statement in the HTML file from which you start the specific component:
<script language="JavaScript" src="Cognos8Gateway/cognoslaunch.js"> </script> Cognos8Gateway is the main IBM Cognos 8 gateway defined in IBM Cognos Configuration.

This statement enables the page to open a specified report in the chosen IBM Cognos component using the cognosLaunch JavaScript parameters. This method requires that the parameters use the following format:
"Argument Name","Argument Value"

The Argument Name parameter specifies the type, and the Argument Value parameter specifies the value of the called arguments. All names and values must be character strings. The cognosLaunch method uses a simpler construction than the parameterized URL method, but requires an enabled starting page.

Mandatory cognosLaunch Parameters

If you are using the cognosLaunch method to start any component, use the following parameters with this syntax:
cognosLaunch("ui.gateway"," gateway ","ui.tool"," component")

"ui.gateway"

This is the mandatory argument value that specifies the IBM Cognos 8 gateway. IBM Cognos Application Firewall validation is enforced on URLs that contain this parameter. For more information see, "URL Validation" (p. 776)
"ui.tool"

This is the mandatory argument value that specifies the IBM Cognos 8 component.

Administration and Security Guide 775

Appendix H: Performing Tasks in IBM Cognos 8 Using URLs

Common Optional Parameters

In addition to the mandatory parameters required by each IBM Cognos 8 component, you can use the following optional parameters, unless otherwise specified:
ui.object

Specifies the path of the target object. Acceptable values are the Content Manager search path or store ID. For more information, see "Using Search Paths and Page IDs" (p. 788). This parameter is mandatory for Event Studio, Analysis Studio, and Metric Studio.
ui.action

Specifies the action to take. Acceptable values for the Studio components are new and edit. The default is new. Acceptable values for Cognos Viewer are run and view. The default is view. This parameter is mandatory for Event Studio and Query Studio. You cannot use this parameter with Metric Studio.
ui.folder

Specifies the target folder. Acceptable values are the Content Manager search path or store ID. For more information, see "Using Search Paths and Page IDs" (p. 788). You cannot use this parameter with Analysis Studio.
ui.backURL

Specifies the URI to open after you close the selected component. IBM Cognos Application Firewall validation is enforced on URLs that contain this parameter. For more information see, "URL Validation" (p. 776)
ui.drillThroughTargetParameterValues

Use this parameter when the report that you want to drill through contains a prompt. This parameter specifies the values that fulfill that prompt, and display the requested data. The acceptable value is a Web64-encoded XML string. This string must include the name of the prompt parameter you want to fulfill, and its values. Using the example in "Start Parameters" (p. 778), if you wanted to start Cognos Viewer to run the Target report and get information specific to Italy, you would append the URL with the ui.
drillThroughTargetParameterValues argument name, followed by this argument value: <parameterValues SOAP-ENC:arrayType=\"bus:parameterValue[]\" xsi:type=\"SOAP-ENC:Array\"><item xsi:type=\"bus:parameterValue\"><name xsi:type=\"xs:string\">Country</ name><value SOAP-ENC:arrayType=\"bus:parmValueItem[]\" xsi:type=\"SOAP-ENC: Array\"><item xsi:type=\"bus:simpleParmValueItem\"><use xsi:type=\"xs:string\ ">Italy</use></item></value></item></parameterValues>

You cannot use this parameter with Event Studio or Metric Studio.

URL Validation
IBM Cognos Application Firewall validation is enforced on URLs using the following rules. Fully qualified, or absolute URLs:

776

Appendix H: Performing Tasks in IBM Cognos 8 Using URLs

protocol://host[:port]/path[?query]

Where protocol is either http or https and the host is validated against the valid domain list, which is specified by the Administrator in IBM Cognos Configuration. For more information, see the Installation and Configuration Guide. URLs relative to the C8 installation web root:
/<install root>/.*

Where <install root> is the gateway file path, taken from the Gateway URI from Cognos Configuration Tool. For example, /cognos8/ps/portal/images/. One of the following specifically allowed URLs:
about:blank (case insensitive) JavaScript:window.close() (case insensitive, with or without trailing semi-colon) JavaScript:parent.close() (case insensitive, with or without trailing semi-colon) JavaScript:history.back() (case insensitive, with or without trailing semi-colon) parent.cancelErrorPage() (case insensitive, with or without trailing semi-colon) doCancel() (case insensitive, with or without trailing semi-colon)

In addition, an advanced configuration setting, RSVP.RENDER.VALIDATEURL, can be used to specify whether these rules are applied to values specified by any URL values contained within a report specification. CAF must be enabled for the RSVP.RENDER.VALIDATEURL setting to take effect.

Starting IBM Cognos 8 Components

Use a URL to start IBM Cognos 8 components and open specified content. For example, you can quickly open a report in Query Studio, or a metric in Metric Studio without using IBM Cognos Connection. The components can be started from any enabled Web page. You can use a URL to start the following IBM Cognos 8 components: Report Studio (p. 778) Query Studio (p. 779) Analysis Studio (p. 781) Metric Studio (p. 782) Event Studio (p. 782) Cognos Viewer (p. 783)

Administration and Security Guide 777

Appendix H: Performing Tasks in IBM Cognos 8 Using URLs

Start Parameters
Before using either the parameterized URL or cognosLaunch method you must first locate the object you want to access. The easiest way to identify the location of an object, such as a saved report, is to start IBM Cognos Connection and copy the object search path "Using a Page ID Instead of the Object Search Path" (p. 789) into the required URL command. The full path must be copied, as listed in the report properties, including the relevant package name and report names. For example, using the following parameterized URL starts Cognos Viewer and runs the report named 2005 Sales Summary:
http://localhost/cgi-bin/cognos.cgi?b_action=cognosViewer&ui.action=run&ui. object=/content/package[@name='GO Sales (analysis)']/folder[@name='Report Studio Report Samples']/report[@name='2005 Sales Summary']

The following script performs the same function using the cognosLaunch method in an enabled Web page:
cognosLaunch('ui.gateway','http://localhost /cgi-bin/cognos.cgi','ui.tool','CognosViewer','ui.action','run','ui.object','/ content/package[@name=\'GO Sales (analysis)\']/folder[@name=\'Report Studio Report Samples\']/report[@name=\'2005 Sales Summary\']')

The following topics describe each of the parameters used in this example, and examples of some other commonly used parameters.

Starting Report Studio

You can use a URL to open and run a specific report in Report Studio. Use the following parameters to start Report Studio with the parameterized URL method:
http://localhost/cognos8/cgi-bin/cognos.cgi?b_action=xts.run&m=portal/launch. xts&ui.tool=ReportStuio&ui.gateway=http://localhost/cognos8/cgi-bin/cognos. cgi?&ui.option=/content

When starting Report Studio with the parameterized URL method, specify both the gateway (http:
//localhost/cognos8/cgi-bin/cognos.cgi?) and the ui.gateway parameter.

Use the following parameters to start Report Studio with the cognosLaunch method:
cognosLaunch("ui.gateway","http://localhost/cognos8/cgi-bin/cognos.cgi?","ui. tool","ReportStudio","ui.option","/content")

Parameterized URL Examples

This section provides examples for performing specific functions when starting Report Studio using the parameterized URL method. Starting Report Studio
http://localhost/cgi-bin/cognos.cgi?b_action=xts.run&m=portal/launch.xts&ui. gateway=http://localhost /cgi-bin/cognos.cgi&ui.tool=ReportStudio&ui.object=/content&ui.action=new

Starting Report Studio to a specific package

http://localhost/cgi-bin/cognos.cgi?b_action=xts.run&m=portal/launch.xts&ui. gateway=http://localhost /cgi-bin/cognos.cgi&ui.tool=ReportStudio&ui.object=/content/package[@name='GO Sales (analysis)']&ui.action=new

778

Appendix H: Performing Tasks in IBM Cognos 8 Using URLs Editing a report in Report Studio
http://localhost/cgi-bin/cognos.cgi?b_action=xts.run&m=portal/launch.xts&ui. gateway=http://localhost /cgi-bin/cognos.cgi&ui.tool=ReportStudio&ui.object=/content/package[@name='GO Sales (analysis)']/folder[@name='Report Studio Report Samples']/report [@name='2005 Quarterly Sales Forecast']&ui.action=edit

cognosLaunch Examples
This section provides examples for performing specific functions when starting Report Studio using the CognosLaunch method. Starting Report Studio
cognosLaunch('ui.gateway','http://localhost /cgi-bin/cognos.cgi','ui.tool','ReportStudio')

Starting Report Studio to a specific package

cognosLaunch('ui.gateway','http://localhost /cgi-bin/cognos.cgi','ui.tool','ReportStudio','ui.action','new','ui.object','/ content/package[@name=\'GO Sales (analysis)\']')

Editing a report in Report Studio

cognosLaunch('ui.gateway','http://localhost /cgi-bin/cognos.cgi','ui.tool','ReportStudio','ui.action','edit','ui. object','/content/package[@name=\'GO Sales (analysis)\']/folder[@name=\'Report Studio Report Samples\']/report[@name=\'2005 Quarterly Sales Forecast\']')

Starting Query Studio

You can use a URL to quickly open a specific report in Query Studio. Use the following mandatory parameters to start Query Studio with the parameterized URL method:
http://localhost/cgi-bin/cognos.cgi?b_action=xts.run&m=portal/launch.xts&ui. tool=QueryStudio&ui.object=/content&ui.action=new

Use the following mandatory parameters to start Query Studio with the cognosLaunch method:
cognosLaunch('ui.gateway','http://localhost /cgi-bin/cognos.cgi','ui.tool','QueryStudio','ui.action','new')

The ui.action parameter is a mandatory for both methods. The following parameters are optional for Query Studio:
cv.header

Specifies whether to display the header. Acceptable values are true and false.
ui.spec

Specifies an XML document that contains an IBM Cognos 8 report specification. For information about IBM Cognos 8 report specifications, see the report specification topics in the IBM Cognos 8 SDK Developer Guide.
run.outputLocale

Specifies the output language. Acceptable values are expressed as a hyphenated language-region pair, in accordance with the RFC3066 standard. The default value is en-us.

Administration and Security Guide 779

Appendix H: Performing Tasks in IBM Cognos 8 Using URLs

run.prompt

Specifies whether the report service issues prompts, so you can enter report option values. Acceptable values are true and false. The default value is true. Use the following parameters for debugging purposes only:
run.outputFormat

Specifies the output format. Acceptable values are CSV, HTML, PDF, singleXLS, XHTML, XLWA, and XML.
asynch.primaryWaitThreshold

Specifies the maximum amount of time, in seconds, that the server can use to process the request before sending a response to the client. Acceptable values are any integer. Use a value of 0 to make the client wait indefinitely. The default value is 7.
asynch.secondaryWaitThreshold

Specifies the maximum amount of time, in seconds, that the server can use to process the request before sending a response to the client. Acceptable values are any integer. Use a value of 0 to make the client wait indefinitely. The default value is 30.

Parameterized URL Examples

This section provides examples for performing specific functions when starting Query Studio using the parameterized URL method. Starting Query Studio to a specific package
http://localhost/cgi-bin/cognos.cgi?b_action=xts.run&m=portal/launch.xts&ui. tool=QueryStudio&ui.object=/content/package[@name='GO Sales (query)']&ui. action=new

Starting Query Studio to a specific report

http://localhost/cgi-bin/cognos.cgi?b_action=xts.run&m=portal/launch.xts&ui. tool=QueryStudio&ui.object=/content/package[@name='GO Data Warehouse (analysis)']/folder[@name='Query Studio Report Samples']/query[@name='Returns by Product Type']&ui.action=edit

cognosLaunch Examples
This section provides examples for performing specific functions when starting Query Studio using the CognosLaunch method. Starting Query Studio to a specific package
cognosLaunch('ui.gateway','http://localhost /cgi-bin/cognos.cgi','ui.tool','QueryStudio','ui.action','new','ui.object','/ content/package[@name=\'GO Data Warehouse (analysis)\']')

Starting Query Studio to a specific report

cognosLaunch('ui.gateway','http://localhost /cgi-bin/cognos.cgi','ui.tool','QueryStudio','ui.action','edit','ui.object','/ content/package[@name=\'GO Data Warehouse (analysis)\']/folder[@name=\'Query Studio Report Samples\']/query[@name=\'Return Quantity by Product Line\']')

780

Appendix H: Performing Tasks in IBM Cognos 8 Using URLs

Starting Analysis Studio

You can use a URL to quickly open and run a specific report in Analysis Studio. Use the following parameters to start Analysis Studio with the parameterized URL method:
http://localhost/cgi-bin/cognos.cgi?b_action=xts.run&m=portal/launch.xts&ui. gateway=http://localhost /cgi-bin/cognos.cgi&ui.tool=AnalysisStudio&ui.action=new

When starting Analysis Studio with the parameterized URL method, specify both the gateway (http://localhost/cognos8/cgi-bin/cognos.cgi?) and the ui.gateway parameter. Use the following parameters to start Analysis Studio with the cognosLaunch method:
cognosLaunch('ui.gateway','http://localhost /cgi-bin/cognos.cgi','ui.tool','AnalysisStudio','ui.action','new')

The ui.object parameter is mandatory for both methods. However, if it is missing, you are prompted to select a package.

Parameterized URL Examples

This section provides examples for performing specific functions when starting Analysis Studio using the parameterized URL method. Starting Analysis Studio to a specific package
http://localhost/cgi-bin/cognos.cgi?b_action=xts.run&m=portal/launch.xts&ui. gateway=http://localhost /cgi-bin/cognos.cgi&ui.tool=AnalysisStudio&ui.object=/content/package [@name='Go Data Warehouse (analysis)']&ui.action=new

Viewing an analysis report in Analysis Studio

http://localhost/cgi-bin/cognos.cgi?b_action=xts.run&m=portal/launch.xts&ui. gateway=http://localhost /cgi-bin/cognos.cgi&ui.tool=AnalysisStudio&ui.tool=AnalysisStudio&ui.object=/ content/package[@name='Sales and Marketing (cube)']/folder[@name='Analysis Studio Report Samples']/analysis[@name='Combine Filters Sample']&ui. action=edit

cognosLaunch Examples
This section provides examples for performing specific functions when starting Analysis Studio using the CognosLauch method. Starting Analysis Studio to a specific package
cognosLaunch('ui.gateway','http://localhost /cgi-bin/cognos.cgi','ui.tool','AnalysisStudio','ui.action','new','ui. object','/content/package[@name=\'Sales and Marketing (cube)\']')

Viewing an analysis report in Analysis Studio

cognosLaunch('ui.gateway','http://localhost /cgi-bin/cognos.cgi','ui.tool','AnalysisStudio','ui.action','edit','ui. object','/content/package[@name=\'Sales and Marketing (cube)\']/folder[@name=\ 'Analysis Studio Report Samples\']/analysis[@name=\'Combine Filters Sample\']')

Administration and Security Guide 781

Appendix H: Performing Tasks in IBM Cognos 8 Using URLs

Starting Metric Studio

You can use a URL to quickly open a metric in Metric Studio. Use the following parameters to start Metric Studio with the parameterized URL method:
http://localhost/cgi-bin/cognos.cgi?b_action=xts.run&m=portal/launch.xts&ui. tool=MetricStudio&ui.action=new

Use the following parameters to start Metric Studio with the cognosLaunch method:
cognosLaunch('ui.gateway','http://localhost /cgi-bin/cognos.cgi','ui.tool','MetricStudio','ui.object','/content')

The ui.object parameter is mandatory for both methods. However, if it is missing, you are prompted to select a package.

Parameterized URL Examples

This section provides an example when starting Metric Studio using the parameterized URL method. Starting Metric Studio to a specific package
http://localhost/cgi-bin/cognos.cgi?b_action=xts.run&m=portal/launch.xts&ui. tool=MetricStudio&ui.object=/content/package[@name='GO Metrics']&ui.action=new

cognosLaunch Examples
This section provides an example when starting Metric Studio using the CognosLaunch method. Starting Metric Studio to a specific package
cognosLaunch('ui.gateway','http://localhost /cgi-bin/cognos.cgi','ui.tool','MetricStudio','ui.object','/content/package [@name=\'GO Metrics\']')

Starting Event Studio

You can use a URL to quickly access and edit an agent in Event Studio. Use the following parameters to start Event Studio with the parameterized URL method:
http://localhost/cgi-bin/cognos.cgi?b_action=xts.run&m=portal/launch.xts&ui. tool=EventStudio&ui.object=/content/package[@name='GO Sales (analysis)']&ui. action=new

Use the following parameters to start Event Studio with the cognosLaunch method:
cognosLaunch('ui.gateway','http://localhost /cgi-bin/cognos.cgi','ui.tool','EventStudio')

The ui.action and ui.object parameters are mandatory. If ui.object is missing, you are prompted to select a package.

Parameterized URL Examples

This section provides an example when starting Event Studio using the parameterized URL method. Opening an agent in Event Studio
http://localhost/cgi-bin/cognos.cgi?b_action=xts.run&m=portal/launch.xts&ui. tool=EventStudio&ui.object=/content/package[@name='GO Events']/agentDefinition [@name='GO Event']&ui.action=run

782

Appendix H: Performing Tasks in IBM Cognos 8 Using URLs

cognosLaunch Examples
This section provides examples for performing specific functions when starting Event Studio using the CognosLaunch method. Starting Event Studio
cognosLaunch('ui.gateway','http://localhost /cgi-bin/cognos.cgi','ui.tool','EventStudio','ui.action','new','ui.object','/ content/package[@name=\'GO Sales and Retailers\']')

Opening an agent in Event Studio

cognosLaunch('ui.gateway','http://localhost /cgi-bin/cognos.cgi','ui.tool','EventStudio','ui.action','edit','ui.object','/ content/package[@name=\'GO Events\']/agentDefinition[@name=\'GO Event\']')

Starting Cognos Viewer

You can use a URL to quickly open a specified report in Cognos Viewer. Use the following parameters to start Cognos Viewer with the parameterized URL method:
http://localhost/cgi-bin/cognos.cgi?b_action=cognosViewer&ui.object=/content/ package[@name='Sales and Marketing (cube)']/folder[@name='Report Studio Report Samples']/report[@name='Revenue by Product Brand (2005)']&ui.action=run

Use the following parameters to start Cognos Viewer with the cognosLaunch method:
cognosLaunch('ui.gateway','http://localhost /cgi-bin/cognos.cgi','ui.tool','CognosViewer')

For a complete list of the Cognos Viewer parameters, see the "URL API Reference" Appendix in the SDK Developer Guide. The following parameters are optional for Cognos Viewer:
run.outputFormat

Specifies the output format. Acceptable values are CSV, HTML, PDF, singleXLS, XHTML, XLWA, and XML. The default value is HTML. Note: To protect IBM Cognos 8 and your servers, the IBM Cognos Application Firewall (CAF) rejects URL-based requests for output in XLS format.
run.outputLocale

Specifies the output language. Acceptable values are expressed as a hyphenated language-region pair, in accordance with the RFC3066 standard. The default value is en-us.
run.prompt

Specifies whether the report service issues prompts, so you can enter report option values. Acceptable values are true and false. The default value is true.
run.xslURL

Specifies the location of an XSL stylesheet that can be applied to the report, thereby rendering it in the requested format. An acceptable value is a URI.

Administration and Security Guide 783

Appendix H: Performing Tasks in IBM Cognos 8 Using URLs When referencing the XSL file, ensure that the specified file is valid, and exists on the application server in the templates/rsvp/xsl directory. Referencing an invalid stylesheet terminates the process.
run.outputEncapsulation

Specifies how output documents in the response are encapsulated. Acceptable values are HTML,
URL, URLQueryString, none.

asynch.attachmentEncoding

Specifies how attachments to the response are encoded. Acceptable values are base64, MIME,
MIMECompressed. The default value is base64.

asynch.primaryWaitThreshold

Specifies the maximum amount of time, in seconds, that the server can use to process the request before sending a response to the client. Acceptable values are any integer. Use a value of 0 to make the client wait indefinitely. The default value is 7.
asynch.secondaryWaitThreshold

Specifies the maximum amount of time, in seconds, that the server can use to process the request before sending a response to the client. Acceptable values are any integer. Use a value of 0 to make the client wait indefinitely. The default value is 30.

Parameterized URL Examples

This section provides examples for performing specific functions when viewing reports using the parameterized URL method. Viewing saved reports
http://localhost/cgi-bin/cognos.cgi?b_action=cognosViewer&ui.object=/content/ package[@name='GO Sales (analysis)']/folder[@name='Report Studio Report Samples']/report[@name='2005 Sales Summary']&ui.action=run

Running live reports

http://localhost/cgi-bin/cognos.cgi?b_action=cognosViewer&ui.object=/content/ package[@name='GO Sales (analysis)']/folder[@name='Report Studio Report Samples']/report[@name='2005 Sales Summary']&ui.action=run

Viewing reports in different output modes

http://localhost/cgi-bin/cognos.cgi?b_action=cognosViewer&ui.object=/content/ package[@name='GO Sales (analysis)']/folder[@name='Report Studio Report Samples']/report[@name='2005 Sales Summary']&ui.action=run&run. outputFormat=PDF

cognosLaunch Examples
This section provides examples for performing specific functions when viewing reports using the CognosLaunch method. Viewing saved reports
cognosLaunch('ui.gateway','http://localhost /cgi-bin/cognos.cgi','ui.tool','CognosViewer','ui.action','view','ui.

784

Appendix H: Performing Tasks in IBM Cognos 8 Using URLs

object','defaultOutput(/content/package[@name='GO Sales (analysis)']/folder [@name='Report Studio Report Samples']/report[@name='2005 Sales Summary'])')

Running live reports

cognosLaunch('ui.gateway','http://localhost /cgi-bin/cognos.cgi','ui.tool','CognosViewer','ui.action','run','ui.object','/ content/package[@name=\'GO Sales (analysis)\']/folder[@name=\'Report Studio Report Samples\']/report[@name=\'2005 Sales Summary\']')

Viewing reports in different output modes

cognosLaunch('ui.gateway','http://localhost /cgi-bin/cognos.cgi','ui.tool','CognosViewer','ui.action','run','ui.object','/ content/package[@name='GO Sales and Retailers']/folder[@name= 'Report Studio Report Samples']/report[@name='2005 Sales Summary']','run.outputFormat', 'PDF')

Starting IBM Cognos 8 Components in a Specified Browser Window

This feature allows you to start an IBM Cognos 8 component in a named browser window. To do this, you must use the following parameters with this syntax:
cognosLaunchInWindow(windowName, windowProperties, "ui.gateway"," gateway","ui.tool","component")

The windowName and windowProperties parameters represent the values specific to starting an IBM Cognos 8 component in a named browser window. The windowName string is the name of the browser window, frame, or iframe in which to start the specified component. If the specified name does not exist, a newly created pop-up browser window appears with the name. To create a new pop-up window, use "_blank" as the value. The windowProperties string defines the properties applied to the new pop-up window. This only applies to newly created windows. The available values depend on the type of the Web browser you are using, and correspond to the values supported by the JavaScript window.open() function. Some options may not work in all browsers. The windowProperties parameter consists of a comma-separated list. Each item consists of an option and a value, separated by the equals sign (=). For example, "fullscreen=yes ,
toolbar=yes". Some common examples include:

channelmode

Specifies whether to display the window in theater mode, and show the channel band. The default is no. Acceptable values are yes and no.
directories

Specifies whether to add directory buttons. The default is yes. Acceptable values are yes and
no.

fullscreen

Specifies whether to display the browser in full-screen mode. This mode hides the browser's title bar and menus. A window in full-screen mode must also be in channelmode. The default is no. Acceptable values are yes and no.
height

Administration and Security Guide 785

Appendix H: Performing Tasks in IBM Cognos 8 Using URLs This integer specifies the height of the window, in pixels. The minimum value is 100.
left

This integer specifies the left position, in pixels, relative to the upper-left corner of the screen.
location

Specifies whether to display the input field for entering URLs directly into the browser. The default is yes. Acceptable values are yes and no.
menubar

Specifies whether to display the menu bar. The default is yes. Acceptable values are yes and
no.

resizable

Specifies whether to display resize handles at the corners of the window. The default is yes. Acceptable values are yes and no.
scrollbars

Specifies whether to display horizontal and vertical scroll bars. The default is yes. Acceptable values are yes and no.
status

Specifies whether to display a status bar at the bottom of the window. The default is yes. Acceptable values are yes and no.
titlebar

Specifies whether to display a title bar for the window. This parameter is only valid if the calling application is an HTML Application, or a trusted dialog box. The default is yes. Acceptable values are yes and no.
toolbar

Specifies whether to display the browser toolbar. The default is yes. Acceptable values are yes and no.
top

This integer specifies the top position, in pixels. This value is relative to the upper-left corner of the screen.
width

This sets the width of the window, in pixels. The minimum value is 100. The ui.gateway, ui.tool, along with some additional parameter values are described in "Start Parameters" (p. 778).

786

Appendix H: Performing Tasks in IBM Cognos 8 Using URLs

Access an IBM Cognos Connection Page

Using a URL, you can quickly access any IBM Cognos Connection page. For example, if you use a corporate portal not supported by Portal Services, and use IBM Cognos portlets to populate frames in that portal, you can embed any IBM Cognos Connection page using the page URL. This page appears in a targeted frame, using your corporate look and feel. Before you can access an IBM Cognos Connection page using URLs, you must prepare the page for standalone access (p. 788).

Step
In a browser, type a URL using the following parameters:
http://[gateway]?b_action=xts.run&m=portal/cc.xts&m_page=path:[search path]&style=[stylesheet]&ui=h1&m_pagemode=view]

The parameters for starting a page are as follows:

gateway

Full prefix that identifies the IBM Cognos 8 gateway. For example, localhost/cognos8/
cgi-bin/cognos.cgi.

m=portal/cc.xts

Identifies the component interface.

m_page=path:[search path]

Identifies an IBM Cognos Connection page. For more information, see "Using Search Paths and Page IDs" (p. 788).
style=[stylesheet]

Identifies the .css file that overrides the default IBM Cognos 8 style. The IBM Cognos Connection pages use the IBM Cognos 8 stylesheet by default. You can use your own corporate style to maintain a consistent look and feel of your page. To do so, edit the URL to set the style=[stylesheet] parameter to the location of the required .css file. For example, style=http://myserver/mystyles.css.
ui=h1

Hides some of the IBM Cognos 8 user interface elements. When an IBM Cognos Connection page appears as a portion of another Web page, some of its user interface elements, such as top headers, links, and toolbars, may became redundant. You can hide these elements and leave only the required content of the page. In this example, h1 hides the main IBM Cognos Connection header. For more information about hiding user interface elements, see the customization chapters in the Administration and Security Guide.
m_pagemode=view

Hides some of the portlet user interface elements, and makes the page read-only.

Administration and Security Guide 787

Appendix H: Performing Tasks in IBM Cognos 8 Using URLs Some of the portlet user interface elements, such as frames around the portlets and title bars, may become redundant when the portlet appears within another page. You can hide these elements.

Preparing a Page for Standalone Access

You must prepare each page in IBM Cognos Connection so that the page can be accessed by using a URL. You must do this even if you intend to use only one portlet in the page. Ensure that the following conditions are met: The page is saved in a public folder in IBM Cognos Connection. The objects in Public Folders can be accessed by all users. An individual users can access a standalone page from his own My Folders directory, but that page is only accessible to that user. The IBM Cognos 8 logon mechanism is implemented by your application. Your application is responsible for authenticating users. This is not required if the host application and IBM Cognos 8 have already established single signon. For more information about setting single signon, see the Installation and Configuration Guide. The required access permissions are set for the page. Read permissions are granted to all users of a portal page or application that embeds the IBM Cognos Connection page. Write permissions are granted to the portal administrator and the page owner. This makes the page read-only, preventing other users from editing the portlet settings inside the page. For more information about setting access permissions, see the Administration and Security Guide. The page is now ready for standalone access (p. 787).

Using Search Paths and Page IDs

When building URLs, you need to know the search paths of the objects you want to access using the URLs. If you want to access an IBM Cognos Connection page, you can use its search paths or its ID. Search paths define the fully qualified location of the entry in the content store and are not installationspecific. IDs are installation-specific. For ease of use, we recommend that you access the page using search paths (p. 789). When using the cognosLaunch method, you specify the object's search path after the "ui.object" parameter. If you are using the parameterized URL method, specify the object's search path using the following m_page parameter format, where search path is the search path of the page object:
&m_page=path:[[search path]]

788

Appendix H: Performing Tasks in IBM Cognos 8 Using URLs For example,

m_page=path:/content/folder[@name='Public Pages']/pagelet[@name='EP portlet Demo'

Tip: To find the page search path and ID in IBM Cognos Connection, navigate to the folder that contains the page and click the page properties button. On the General tab, click View the search path, ID and URL.

Using a Page ID Instead of the Object Search Path

Instead of the search path, you can also specify the object's page ID using the following cognosLaunch parameters:
"ui.object","storeID('storeID')

If you are using the parameterized URL method (p. 774), you can specify the object's page ID using the following m_page parameter format, where page ID is the object's page ID:
m_page=[page ID]

The ID appears as an unseparated series of characters. For example,

i80E9B692820A4F91B8655D4E84F292AF

To find the IDs, follow the instructions in "Using Search Paths and Page IDs" (p. 788).

Deployment Considerations
References to deployment objects are based on search paths, not IDs. For a specific IBM Cognos Connection page, the object's page ID remains valid until the application's deployment mechanism transfers the original object to another IBM Cognos 8 server. In the destination environment, all IDs are different. In such an event, you must map all ID references to the new IDs on the system.

Administration and Security Guide 789

Appendix H: Performing Tasks in IBM Cognos 8 Using URLs

790

Glossary
access permissions
Rules defining the access rights to resources. Access permissions can be granted to any combination of namespaces, groups, or users. Examples of resources are reports and folders.

agent
The object type created and edited by Event Studio. An agent contains the event condition and the associated tasks to perform. Once defined, an agent can be scheduled to check for instances of the event.

analysis
A process where a user interacts with data to gain insight and understanding. In IBM Cognos 8, Analysis Studio is designed to facilitate analysis.

anonymous access
A method of accessing resources in which users are not authenticated, and all users gain the same access permissions.

authentication
The process of verifying the identity of users when they log on. Users must be authenticated before they can be authorized to use any secured resources.

authentication provider
The communication mechanism to an external authentication source. Functionality such as user authentication, group membership, and namespace searches are made available through authentication providers.

burst
To create many report results by running a single report once. For example, you can create a report that shows sales for each employee, and run it once, sending different results to regional managers by bursting on region. You set up bursting in Report Studio and enable it in the portal.

burst key
The dimension or level of a query in the report specification that is used to create, or burst, a set of report results. For example, you can create a report that shows sales for each employee, and send different results to regional managers by bursting on region.

capabilities
Capabilities refer to the ability to use certain functions and features within IBM Cognos 8. The Capabilities tool controls access to secured functions such as Administration and the IBM Cognos Query Studio, and secured features, such as User Defined SQL and Bursting. The permissions define

Administration and Security Guide 791

Glossary which of the predefined and built-in Cognos groups and roles have access to which secured functions and features, and the type of access. Access to these capabilities is set by the security administrator. Users can see their access permissions in the Personal area of their Preferences, under Capabilities.

connection
The named information that defines the type of the data source, its physical location, and any signon requirements. A data source can have more than one connection.

contact
A named email address to which reports and agent emails can be sent. Contacts are never authenticated.

content locale
A code that is used to set the language or dialect used for browsers, report text, and so on; and the regional preferences, such as formats for time, date, money, money expressions, and time of day. For IBM Cognos products, you can specify a locale for the product interface (product locale) and for the data in the report (content locale).

Content Manager
The IBM Cognos 8 service that manages the storage of customer applications, including applicationspecific security, configuration data, models, metrics, reports, and report output. Content Manager is needed to publish models, retrieve or store report specifications, manage scheduling information, and manage the Cognos namespace.

content store
The database that contains data that IBM Cognos 8 needs to operate, such as report specifications, published models, and the packages that contain them; connection information for data sources; information about the external namespace, and the Cognos namespace itself; and information about scheduling and bursting reports. Design models and log files are not stored in the content store. The IBM Cognos 8 service that uses the content store is named Content Manager.

credentials
Information stored about the identity of an IBM Cognos user, usually a user name and password. You can assign your credentials to someone else so that they can use resources that you are authorized to use. Credentials are created for IBM Cognos components. If a user schedules or programs an action, credentials must be stored in the content store.

data source
A relational database, dimensional cube, file, or other physical data store that can be accessed through IBM Cognos 8.

792

Glossary

deployment
The process of moving an IBM Cognos 8 application (reports, models, and so on) to a different instance of IBM Cognos 8. For example, you often create reports in a test environment and then deploy them to production. When you deploy an application, you export, transfer, and import it.

deployment archive
A file used for deployment. A deployment archive contains the data from the content store that is being moved.

deployment specification
A definition of what packages to move (deploy) between source and target environments, the deployment preferences, and the archive name. You use deployment specifications for import and for export.

drill down
In IBM Cognos Planning, drill down is a technique used to analyze D-Cube data that was imported by a D-Link. You can drill down on any single cell in a D-Cube. If the cell contains data transferred by a D-Link, drill down opens a view of the source data. If the data was imported from another DCube, drill down opens the appropriate selection from the source D-Cube. If the data was imported from an external source (a mapped ASCII file or an ODBC database), drill down extracts the relevant data from the source file and displays it in a special drill-down results dialog box. In IBM Cognos 8 BI, drill down refers to the act of navigating from one level of data to a more detailed level. The levels are set by the structure of the data. See also drill up.

drill up
The act of navigating from one level of data to a less detailed level. The levels are set by the structure of the data. See also drill down.

event
An exceptional item of data, defined by specifying a query expression against items in a package. When data is detected matching the event condition, it causes an agent to perform tasks.

gateway
An extension of a Web server program that transfers information from the Web server to another server. Gateways are often CGI programs, but may follow other standards such as ISAPI and Apache Modules.

glyph
An image of a character in a font. Letters are glyphs, but in most cases, the term is used in discussions of non-alphabetic writing systems.

Administration and Security Guide 793

Glossary

group
In security, a list of users or other groups that can be used to assign access permissions and capabilities. Groups can be referenced from other authentication sources or can be local to IBM Cognos 8. Local groups are managed from the administration portal. The list of groups that an authentication user is a member of is part of the user's passport for an IBM Cognos 8 session. In reporting, grouping is the action of organizing common values of query item together and only displaying the value once. Headers and footers often appear after each instance of a common value in a grouped column

job
A group of runnable objects, such as reports, agents, and other jobs that you run and schedule as a batch.

job step
The smallest part of a job that can be run separately. Usually, a job step is a report. A job step can also be another job.

locale
A code that is used to set the language or dialect used for browsers, report text, and so on; and the regional preferences, such as formats for time, date, money, and money expressions. For IBM Cognos products, you can specify a locale for the product interface (product locale) and for the data in the report (content locale).

metric
A measure to assess performance in a key area of a business.

metric package
an IBM Cognos Connection representation of a Metric Studio application. A metric package contains connection information, reports, and metric management tasks for that application.

model
A physical or business representation of the structure of the data from one or more data sources. A model describes data objects, structure, and grouping, as well as relationships and security. In IBM Cognos 8 BI, a design model is created and maintained in Framework Manager. The design model or a subset of the design model must be published to the IBM Cognos 8 server as a package for users to create and run reports. In IBM Cognos Planning, a model is a group of D-Cubes, D-Lists, D-Links, and other objects stored in a library. A model may reside in one or more libraries, with a maximum of two for Contributor.

namespace
For authentication and access control, a configured instance of an authentication provider. Allows access to user and group information.

794

Glossary In XML, a collection of names, identified by a URI reference, which are used in XML documents as element types and attribute names. In Framework Manager, namespaces uniquely identify query items, query subjects, and so on. You import different databases into separate namespaces to avoid duplicate names.

news item
A single entry in a rich site summary (RSS) compatible format. It can include a headline, text, and a link to more information. A news item task in an agent can be used to create news items for display in an IBM Cognos Connection portlet.

package
A subset of a model, which can be the whole model, to be made available to the IBM Cognos 8 server. For Metric Studio users, see metric package.

passport
Session-based information regarding authenticated users. A passport is created the first time a user accesses IBM Cognos 8. It is retained until a session ends, either when the user logs off, or after a specified period of inactivity. Passport information is stored in Content Manager memory. Credentials are stored encrypted. A passport is stored in a memory-only browser cookie for the duration of the session.

portlet
A mechanism for displaying Web content as part of a portal page.

product locale
The code or setting that specifies what language, regional settings, or both to use for parts of the product interface, such as menu commands.

project
In Framework Manager, a set of models, packages, and related information for administration, and for sharing model information. In Metric Studio, a project is a task or set of tasks undertaken by a team and monitored on a scorecard. A project tracks the dates, resources and status of the project. In Metric Designer, a project is a group of extracts. Each extract contains the metadata that is used to populate the Metric Studio data store or to create applications.

prompt
A report element that asks for parameter values before the report is run.

Administration and Security Guide 795

Glossary

publish
In IBM Cognos 8 BI, refers to exposing all or part of a Framework Manager model or Transformer PowerCube, via a package, to the IBM Cognos 8 server, so that it can be used to create reports and other content. In IBM Cognos Planning, refers to a function that is used to copy the data from Contributor or Analyst to a datastore, typically so it can be used for reporting purposes.

query
A specification for a set of data retrieved from a data source. A report specification can contain one or more queries. In Query Studio, the type of object created and edited. A query is a subtype of report. In Transformer, models can contain multiple queries as data sources. A query or data source appears as a cylinder icon in the Data Sources list.

really simple syndication

(RSS) See rich site summary.

report
A set of data deliberately laid out to communicate business information. Depending on the context, "report" may refer to report specification or report output. Report (more precisely, report specification) is the generic term for the objects created or edited by Query Studio, Report Studio, and Analysis Studio.

report output
Report output combines data at the point in time when the report was run with a report specification. It is a document that can be displayed, printed, or emailed. IBM Cognos 8 can produce report outputs in HTML, PDF, Excel, or CSV formats.

report specification
The definition of queries, prompts, layouts, and styles that make up a report. A report specification is combined with data by a run operation to create report outputs. You create report specifications by using Report Studio, Query Studio, Analysis Studio, or through the Software Development Kit.

report view
A reference to another report that has its own properties, such as prompt values, schedules, and results. You use report views to share a report specification instead of making copies of it.

rich site summary

(RSS) An industry standard format for displaying transient data, such as breaking news, in a web page or standalone viewer. IBM Cognos Connection includes a portlet type for displaying RSS format data. This can be used to display data from a public RSS service or to display news items generated by agents detecting events. A synonym for Really Simple Syndication.

796

Glossary

session
The time during which an authenticated user is logged on to IBM Cognos 8.

task
An action performed by an agent if the event status meets the task execution rules. For example, an agent can send an email, publish a news item, or run a report.

template
A reusable report layout or style that can be used to set the presentation of a query or report.

user
A person accessing an IBM Cognos 8 application. User information, such as the location of personal folders or preferred formats for viewing reports, is stored in IBM Cognos 8. Authenticated user definitions and information, such as passwords and IDs, are maintained in other authentication sources.

watch list
A list of metrics that each user has chosen to monitor closely. If notification is enabled in Metric Studio, the user will receive email notification of changes to these metrics. Users can also choose to display their watch list as a portlet within IBM Cognos Connection.

watch rule
A user-defined condition that determines whether a report is delivered to the user. When the rule is run, the output is evaluated and, if it satisfies the condition or rule, the report is delivered by email or news item. Watch rules limit report delivery to those reports containing data of significance to the user.

Web Services for Remote Portlets

(WSRP) A standard for creating presentation-oriented Web services so that they can be easily integrated within other applications, such as Web portals.

Administration and Security Guide 797

Glossary

798

Index
Symbols
.cnv applying substitutions, 689 .css changing IBM Cognos 8 fonts, 482 global changes to appearance, 482 .csv formatting output, 526 properties, 527 .dmp, See core dump files .dwp deploying Cognos portlets to SharePoint Portal Server, 456 .epa deploying Cognos portlets to SAP Enterprise Portal 6.0, 446 .mdl errors calculations with double quotation marks, 611 .NET Framework troubleshooting, 664 version, 661 .NET programmability support, 661 .otl files, 69 .pte deploying Cognos portlets to ALUI 6.1, 452 .xml adding custom report templates, 497 applying conversions, 689 specifying conversions, 687 $nopage>audit logs, See Also troubleshooting #ERROR troubleshooting in Microsoft Excel, 667 #NAME? errors, 665 -- characters, 622 access denied error, 590 access permissions, 225 anonymous, 233 built-in entries, 699, 700 credentials, 218 definition, 791 granting or denying, 215 initial, 691 metric packages, 657 ownership of entries, 215 pages, 270 portlets, 433 predefined entries, 700 secured functions and features, 225, 693 Series 7 reports from IBM Cognos Connection, 52 setting, 216 styles, 439 to entries denied, 581 users, 214 See Also permissions access rights, See access permissions actions adding shortcuts, 510 credentials, 218 customizing in IBM Cognos Connection, 509 permissions, 215 removing, 510 activating services, 110 Active Directory distribution lists as members of groups and roles, 209 Active Directory Server missing group membership, 576 single signon not working, 586 activities managing, 285 adding comments, 370 administration IBM Cognos 8, 43

A
accented characters not displayed properly, 567 access more documentation, 35

Administration and Security Guide 799

Index metrics for Metric Studio, 391 server, 37 Administration secured functions and features, 221 administrators improved user interface, 35 advanced configuration settings RSVP.RENDER.VALIDATEURL, 776 advanced properties report service, 529 affinity settings, 131 agents, 383 adding yourself to alert list, 386 allowing alert list, 386 creating from IBM Cognos Connection, 385 default actions, 40 definition, 791 deleting alert list, 387 most recent event list, 387 news item headlines, 387 opening from IBM Cognos Connection, 385 properties, 249, 384 removing yourself from alert list, 386 rerunning failed, 297 running, 383 viewing, 385 agent service, 105, 106 agent tasks resubmitting on fail, 40 aggregating samples and time dimensions, 60 troubleshooting running totals, 642 AIX error connecting to DB2 database, 558 version, IBM WebSphere, 564 alert lists allowing for agents, 386 allowing for reports, 365 deleting for agent, 387 for agents, 386 for reports, 366 removing for agents, 386 removing from watch items, 264 viewing in IBM Cognos Connection, 264 alerts report, 38 800 All option Error 0\:RSV-BBP-0027 error, 669 ALUI 6.1 customizing Cognos portlets, 454 deploying Cognos portlets, 449 remote servers, 449, 450, 453 unable to edit object properties, 596 Always Prompt (property value), 668 analyses definition, 791 analysis studio limiting hot spots, 139 Analysis Studio changing suppression default, 538 cubes, 347 customizing styles, 480 data tree display settings, 335 Excel reports, 635 Japanese Internet Explorer, 635 report properties, 247 reports, 347 secured functions and features, 221 setting up drill-through targets, 412 troubleshooting, 630, 631, 632 wrong currency symbol, 614, 634 anonymous access definition, 791 APIs, 44 appearance Cognos Viewer, 492 fonts, 482 global changes, 479 migrating changes to future releases, 483 rebranding, 481 style sheets, 482 application errors upgrading a report, 620 application servers problems running IBM Cognos 8, 571 servlet class fails to load in WebLogic, 579 startup script fails, 564 Application Tier Components log server, 79 archives deployment, 308 arithmetic overflow errors, 639

Index ASCII requirements for installation directory, 558 as percentage values, 631 attachments IBM Lotus Notes, 534 attributes metric score, 101 audit logs, 79 audit logs log destinations, 79 See Also log messages audit reports new samples, 36 audits reports, 82 authentication, 201 CAM-AAA-0096 error, 585 definition, 791 expired password, 586 single-signon not working when using Active Directory, 586 unable to authenticate user, 585 unable to authenticate user for Cognos portlets, 587 users, 239 authentication prompts, 216 authentication providers, 201 definition, 791 problems, 585 authoring enabling Report Studio modes, 37 authoring modes Report Studio, 37 authoring profiles express, 227 professional, 227 authorization, 203 automating tasks, 44 restoring files, 197 balanced hierarchies DB2 OLAP, 165 BAP-ERR-0002 errors, 641 BAPI error editing prompt specification file, 609 batch reports, 105 report services, 105 batch report service, 106 BEA AquaLogic User Interaction 6.1, See ALUI 6.1 BEA WebLogic parser collision with Report Data Service, 670 blank pages excluding in PDF reports, 372 BLOB in stored procedures, 601 bo\:heap Buffer Overflow troubleshooting, 662 bookmarks creating for drill-through access, 404 creating for IBM Cognos 8 entries, 242 Bookmarks Viewer, 732 braces in expressions, 604 browser settings, 647 browsing content, 513 controlling external namespaces, 123 built-in entries initial access permissions, 699, 700 bursting deploying results, 308 reports, 374 burst keys definition, 791 burst reports troubleshooting, 638 bursts definition, 791 business keys using for drill-through, 407

B
background colors not appearing in templates, 621 troubleshooting in charts, 619 backing up data, 197

Administration and Security Guide 801

Index

C
caches configuring Cognos portlets in WebSphere Portal, 444 caching disabling for a session, 145 CAF, 776 calculated column converting to regular column, 611 calculations with double quotation marks model errors, 611 CAM.AAA errors, 636 CAM-CRP-1071, 582 CAM-CRP-1157 error, 552 cancel entry run, 285 cannot call the SDK from Event Studio, 628 capabilities administrative, 35 changed, 42 definition, 791 Capabilities secured functions, 221 capacity dispatchers, 129 cast_Date functions troubleshooting, 633 categories missing in Transformer model, 612 CCLOutofMemory Error, 606 cell-based reports #NAME? errors, 665 Certificate Authority (CA) security errors, 674 unable to create trust relationship, 670 CGI timeout error, 579, 639, 640 changed features version 8.3, 41 version 8.4, 34 changes to decimal formats, 615 changing suppression default Analysis Studio, 538 character encoding in PDF files, 134 characters encoding not supported, 553 characters improperly displayed, 567

charts display every second label, 619 gradient backgrounds appear gray, 619 labels overwrite one another, 619 limitations, 648 missing in imported reports, 667 not appearing, 644 transparency, 644 Chinese characters display incorrectly after upgrade, 566 characters in file names, 607 clearing metric history and calendar data for Metric Studio, 395 metric rejects tables for Metric Studio, 395 CLOB in stored procedures, 601 Oracle, 601 cluster compatible mode, 129 cmm_support_bundle, 654 CM-SYS-5001 A Content Manager internal error occurred, 575 CNC-ASV-0001 error, 628 CNC-GEN-2107 errors, 648 COC-ERR-2609, 679 cogconfig.sh return codes not UNIX compliant, 567 cogformat.xml file adding data formats for a locale, 524 modifying, 521 removing data formats for locales, 523 Cognos portlets, 464 portlets, deploying iViews to SAP Enterprise Portal 6.0, 445 Cognos 8, See IBM Cognos 8 Cognos Extended Applications, 726 Cognos namespace recreating, 572 Cognos Navigator, 717 Cognos portlets cannot log on, 583 properties pages not displayed properly, 598 Cognos portlets, See portlets Cognos Search, 719 Cognos Software Services, 539, 545

802

Index Cognos SQL adding comments to SQL statements, 147 Cognos Viewer, 721, 724 changing the product language, 493 customizing, 492 customizing report output formats, 517 customizing styles, 480 disabling session caching, 145 modifying style sheets, 493 secured functions and features, 221 Cognos Viewer portlet drill-down actions, 283 drill-through actions, 283 drill-up actions, 283 global filters, 280 cogroot.link file, 571 cogstartup.lock file, 540 cogstartup.xml file invalid file, 573 collation sequences case-sensitive, 553 colors not appearing in templates, 621 Query Studio menus, 489 Report Studio menus, 487 columns disappearing, 623 Com Add-in Excel workbook closes unexpectedly, 664 commands database, 742 native SQL, 745 starting proxy sessions, 742 stopping proxy sessions, 743 comments, 369 adding in Cognos Viewer, 370 adding to saved reports, 32 Cognos SQL, 147 deleting in Cognos Viewer, 370 enabling, 369 managing in Cognos Viewer, 32 modifying in Cognos Viewer, 370 native SQL, 147 viewing in Cognos Viewer, 370 common symmetric key error in processing a request, 582 Common Warehouse Metamodel exporting to, 605 components global changes to appearance, 479 Report Studio style sheets, 486 Composite Information Server changes in 8.4, 34 composite software, See Also IBM Cognos Virtual View Manager compression algorithm level in PDF files, 134 concurrent query execution, 141 configuration cache size for Cognos portlets in WebSphere Portal, 444 Cognos portlets in a WebSphere Portal, 444 cryptographic information cannot be encrypted, 570 data locked, 572 dispatchers and services, 127 error when encrypting information, 570 folders, 112 iViews, 447 Japanese character encoding, 685 lock file, 540 portlet cache in IBM Cognos Connection, 434 QE-DEF-0177 errors, 633 settings not applied, 574 Shift-JIS characters, 685 unable to open IBM Cognos Configuration, 540 unable to save, 572 Web browsers, 50 configuration issues, 567, 661 connection pool settings Content Manager database, 121 connections data source, 155 data source connections, 67 definition, 792 dispatchers, 131 managing, 121 OLAP data sources, 70 remote servers, 453 setting number, 131 contacting Cognos Software Services, 539, 545 contacts creating, 374 definition, 792 Administration and Security Guide 803

Index content browsing using a URL command, 513 browsing using the system.xml file, 513 setting languages, 260 content compression type in PDF files, 134 content locale definition, 792 Content Manager advanced settings, 121 an attempt to register the dispatcher, 558 control browsing of external namespaces, 123 database connection pool settings, 121 definition, 792 initial access permissions, 691 maximum number of connections, 121 objects, 691 resolving unresponsiveness, 672 service, 105 synchronizing standby, 123 Content Manager error messages, 574 Content Manager service, 106 content store backing up, 197 compatible versions of DB2 and Java, 552 definition, 792 deleting tables from the database, 568 error initializing in Oracle, 578 invalid settings, 553 securing, 237 upgrading, 557 content stores deploying, 309 maintaining, 125 context attribute cannot be deserialized, 565 context error, 565 copying entries, 251 copyright material printing, 29 core dump files, 89, 542 corporate style, 481 creating calculated columns in Transformer, 611 configuration folders, 112 packages, 162 watch rules, 367 804 creating files in Framework Manager, 607 using GB18030 characters, 607 credentials, 239 definition, 792 trusted, 218 credentials invalid, 581 crosstabs overflow errors, 633 troubleshooting, 631 cryptographic error, 573 cogstartup.xml file invalid, 573 JRE error, 573 problems after upgrading, 570 cryptographic information cannot be encrypted, 570 cryptographic keys regenerating, 571 CSV formatting reports, 360 cubes, 347 Analysis Studio, 347 cannot open, 559 data sources, 157 drilling through to relational data gives unexpected results, 643 IBM Cognos Series 7, 379 IBM Cognos Series 7 multilingual properties, 382 opening IBM Cognos Series 7, 382 PowerCubes open slowly, 592, 613 cube update data, 631 currencies displaying mixed, 347 current activities, 285 entries, 285 current run advanced options, 351 report options, 350 customer support contacting Cognos Software Services, 539, 545 customizing Cognos Viewer, 492 custom report template icons, 497 fonts in pages, 486 header background color in IBM Cognos Connection, 485

Index header branding in IBM Cognos Connection, 484 IBM Cognos 8 appearance, 479 IBM Cognos 8 functionality, 501 IBM Cognos Connection, 484, 502, 503 object actions in IBM Cognos Connection, 509 portal graphics, 486 portals, 260 prompt page formats, 494 Query Studio graphics, 489 Query Studio menu colors, 489 Query Studio toolbar buttons, 490 report output formats, 517 Report Studio fonts, 487 Report Studio graphics, 488 Report Studio interfaces, 487 Report Studio menu colors, 487 Report Studio style sheets, 486 report templates, 495 styles, 480 Welcome pages, 484, 514 customizing Cognos portlets for WebSphere Portal, 444 customizing user interface adding elements, 714 hiding elements, 707 Custom Property troubleshooting, 679 locked by IBM Cognos Configuration, 572 multilingual samples, 703 PowerCube not displayed, 656 relational data not displayed in Metric Studio, 656 specifying data sources, 155 viewing lineage, 355 database connection cannot select ODBC as type, 589 connecting to SQL Server, 590 creating, 589 databases bulk load utility missing, 578 command block examples, 192 command blocks, 191 commands, 190, 742 configuring for multilingual, 47 deleting tables, 568 IBM Cognos samples, 63 native SQL commands, 745 returning to original state in Event Studio, 78 sorting of entries for non-English locales, 122 starting proxy sessions, 742 stopping proxy sessions, 743 tables for log messages, 749 data formats adding for a locale, 524 changing the order, 521 customizing for Query Studio, 520 removing for a locale, 523 data integration service, 106 data modeling, 243 data movement, 199 properties, 200 running, 199 data retrieval troubleshooting an SAP-based data source, 612 data schema for log messages, 749 data size limits, 674 data source connections changing, 183 data sources, 155 adding connections, 183 command block examples, 192 command blocks, 191 commands, 741 connection commands, 742 Administration and Security Guide 805

D
dashboards, 40 adding interactivity, 278 creating, 275 drill-through actions, 283 drill-up and drill-down actions, 283 global filters, 278 hiding user interface elements, 504 Multi-page portlet, 275 problems displaying reports, 598 See Also pages data backing up, 197 deploying, 324 exporting, 325 flat file data not displayed in Metric Studio, 656 IBM Cognos samples, 63 importing, 328 in multiple languages, 610

Index connection timeouts, 184 creating, 180 creating signons, 186 cubes, 157 database commands, 190 DB2, 156 DB2 OLAP, 164, 165 definition, 792 deploying, 314 Hyperion Essbase, 164 IBM Cognos Finance, 157 IBM Cognos Now! Cube, 157 IBM Cognos Planning -Contributor, 157 IBM Cognos Planning - Series 7, 157 IBM Cognos Virtual View Manager, 174 IBM Infosphere Warehouse Cubing Services, 168 Informix, 169 isolation levels, 188 Microsoft Analysis Server, 169 Microsoft SQL Server, 171 modifying connections, 183 modifying sources, 186 ODBC, 173 Oracle, 176 paths to file-based data source connections, 181 PowerCubes, 157 samples connections, 67 SAP Business Information Warehouse (SAP BW), 176 securing against multiple namespaces, 216 security, 195 TM1, 178 XML files, 179 data source signons changing, 186 creating, 186 data stores conformed dimensions, 406 data tree display settings, 335 datatypes graphic, 603 dates using for drill-through access, 408 DB2, 560, 603 creating a metric package, 657 Metric Studio, 658 806 supported Java versions, 552 DB2 data source, 156 DB2-ERR-0028, 576 DB2 OLAP data sources, 164, 165 unable to load library, 576 decimal formats changes, 615 default actions for agents, 40 defaults agent properties, 384 data movement properties, 200 iViews content and appearance, 448 PowerPlay reports, 381 report languages, 362 report prompt values, 362 report run options, 348 service, 110 styles, 481 user profiles, 339 users, groups, and roles, 233 delete request fails, 593, 594 deleting dispatchers, 111 entries, 257 IBM Cognos samples, 78 metric tasks for Metric Studio, 393 namespaces, 202 pages, 269 tabs, 274 user profiles, 340 delivery service, 105 delivery service, 106 customizing SMTP error-handling, 530 setting compression for attachments, 140 denying access, 215 deploying archives, 308 Cognos iViews to SAP Enterprise Portal 6.0, 445 Cognos Portlets to ALUI 6.1, 449 Cognos portlets to SharePoint Portal Server, 454 Cognos portlets to WebSphere Portal, 441 command lines, 307 configuration objects, 331

Index data, 324 data sources, 314 directory content, 311 entire content store, 309 exporting, 325 external namespace references, 308, 309 failure on Oracle or WebSphere Application Server, 564 groups, 313 IBM Cognos 8, 577 importing, 328 moving archives, 328 packages, 311 partial deployment, 311 permissions, 324 planning, 308 portlets to other portals, 441 prerequisites, 324 public folders, 311 reports, 307 roles, 313 SAP Enterprise Portal 6.0, 445 security, 216, 308 specifications, 307 testing, 332 updated PowerCubes, 163 deploying System Administrators, 313 deployment, 307 broken links, 599 creating an export specification, 325 definition, 792 reducing details, 36 rules, 315 See Also deploying deployment archives definition, 793 deployment options partial, 312 deployment specifications definition, 793 Detailed Errors secured functions and features, 221 details reducing deployment, 36 diagnostics, See troubleshooting diagnostic tools, 546 diagram error, 658 different values TM1 data sources, 624 dimensions conformed for drill-through access, 406 overlapping named set levels, 621 directories deploying content, 311 directories, See folders directory not found error, 560 disabled access to reports, 347 disabling chart transparency, 644 content maintenance job, 75, 126 creation core dump files, 89 entries, 253 folders when deploying, 312 packages when deploying, 312 portlets, 433 report attachments in emails, 534 secure error messages, 88 selection-based interactivity, 371 session caching, 145 transfer of IBM Cognos 8 passport ID, 465 trigger-based scheduling, 535 disappearing columns, 623 dispatcher does not start on Application Tier Components computer, 579 dispatchers, 105 cluster compatible mode, 129 deleting, 111 failover for multiple, 118 grouping, 112 importing, 331 load balancing, 129 load-balancing, 129 move, 112 renaming, 116 securing, 120 setting scans for servlet gateways, 119 setting status scans, 118 stopping and starting, 108, 110 testing, 117 Administration and Security Guide 807

Index displaying mixed currencies, 347 distributing burst reports, 374 reports, 372, 374 reports by email, 373 distribution lists creating, 374 groups and roles membership, 209 dividing by zero appearing different in lists and crosstabs, 620 documentation access to more, 35 double-byte characters improperly displayed, 567 downloading, 344 downloading IBM Cognos 8 Go! Office documents in IBM Cognos Connection, 344 download of resource fails, 557 DPR-DPR-1035 error, 552 DPR-ERR-2079 errors, 635 DPR-ERR-2079 Firewall Security Rejection, 668 DPR-ERR-2082 error, 632 drill down definition, 793 drill-down actions Cognos Viewer portlet, 283 pages and dashboards, 283 drilling down, 376 drilling through from cubes to relational data, 643 from relational data to cubes, 644 links not active in Safari Web browsers, 642 multiple values, 38, 422 selection contexts, 402 setting up target parameters, 411 troubleshooting PowerCubes, 643 drilling up, 376 drill-through multiple values, 38 one target report, 39 passing multiple values, 377 to target report, 376 drill through, See drill-through access drill-through access, 401 between packages, 403 808 between PowerCubes and packages, 408 business keys, 407 concepts, 402 conformed dimensions, 406 creating reports, 422 debugging, 419 defining access in packages, 408 Drill-through Assistant, 419 formats, 403 members, 404 model-based access, 402 new features in version 8.4, 33 report-based access, 402 setting up for IBM Cognos Visualizer reports, 426 setting up for PowerPlay reports, 426 setting up in packages, 408 setting up targets in Analysis Studio, 412 using bookmarks, 404 using dates, 408 using scope in model-based, 407 using URLs, 404 values, 404 drill-through actions Cognos Viewer portlet, 283 pages and dashboards, 283 drill-through definition, 402 debugging, 419 Drill-through Assistant, 419 drill-through reports hiding, 32 specifying text, 425 drill up definition, 793 drill-up actions Cognos Viewer portlet, 283 pages and dashboards, 283 DSServlet running, 87 dump files, 542 dynamic SQL adding application context, 32

E
East Asian characters, 665 EBA-090034 Error on WebLogic 8, 562

Index editing iViews, 447 pages, 270 reports, 356 emailing reports, 373 emailing reports disabling, 534 emails setting compression for attachments, 140 enabling comments, 369 communication between portlets, 271 entries, 243, 253 queue metrics, 153 encoding values, 528 encryption configuration errors, 570 entries agents, 383 cancel run, 285 copying, 251, 509 creating bookmarks, 242 current, 285 cutting, 509 deleting, 257 disabling, 253 enabling, 243, 253 hiding, 32, 254 managing, 285 moving, 252 ordering, 257 organizing, 251 past, 287 pasting, 509 properties, 243 renaming, 251, 253 rerunning failed, 297 run history, 294 run priority, 293 scheduled, 291 scheduling, 300 scheduling based on occurrences, 305 scheduling last day of month, 301 searching, 259 selecting links, 256 specifying alternative icon, 259 suspend run, 285 upcoming, 289 viewing hidden entries, 255 entries do not appear, 582 environments setting up multilingual, 46 error certificate expired, 582 creating Framework Manager files, 607 Error 0\:RSV-BBP-0027, 669 error messages #ERROR appears in cells with multiple images in a cell, 667 access denied, 590 BAP-ERR-0002, 641 BAPI-MDDATASET_CHECK_SYNTAX, 641 bo\:heap Buffer Overflow, 662 CAM.AAA, 636 CAM-AAA-0096, 585 CAM-CRP-1064, 556 CAM-CRP-1315 Current configuration points to a different trust domain, 571 cannot render this report, 666 CCS-ERR-1005 login requirements for IBM Cognos 8 could not be obtained, 672 CFG-ERR-0106 Cognos Configuration received no response, 549 CGI timeout, 579, 639, 640 CM-CFG-029 Content Manager is unable to determine, 574 CM-CFG-5036, 591 CMM-APP-3254 The initialization of the metrics store failed, 578 CM-SYS-5007, 591 CM-SYS-5063, 591 CNC-ASV-0001, 628 CNC-GEN-2107, 648 COC-ERR-1003 failed to create slide, 676 COC-ERR-1302 no data source available, 676 COC-ERR-2005 import failed, 676 COC-ERR-2006 failed to load the portal tree, 677 COC-ERR-2012 failed to render the list, 677 COC-ERR-2013 unsupported Office application, 677 COC-ERR-2014 refresh failed, 677 Administration and Security Guide 809

Index COC-ERR-2015 failed to open the import wizard dialog, 677 COC-ERR-2019 failed to refresh an image, 678 COC-ERR-2301 logon failed, 678 COC-ERR-2303 report is not valid for rendering, 678 COC-ERR-2304 this is a prompted report, 678 COC-ERR-2305 Microsoft Excel returned an error, 679 COC-ERR-2308 report specification is empty, 679 COC-ERR-2603 you must add a slide to the presentation before importing any content, 679 COC-ERR-2604 cannot render empty list object, 679 COC-ERR-2607, 679 COC-ERR-2609, 679 COI-ERR-2002 Block type is not valid, 680 COI-ERR-2005 this version of Microsoft Office is not supported, 680 COI-ERR-2006 this Microsoft Office product is not supported, 680 COI-ERR-2008 Unable to retrieve from resources, 680 COI-ERR-2009 Unable to perform this operation because Microsoft Excel is in Edit mode, 681 COI-ERR-2010 The name {0} is not valid, 681 COI-ERR-2011 The server did not return the expected response, 681 COR-ERR-2002 Block type is not valid, 681 COR-ERR-2005 Block specification is not valid or missing, 681 COR-ERR-2006 unexpected type, 681 COR-ERR-2007 error retrieving from resources, 682 COR-ERR-2009 Name formula is not valid, 682 COR-ERR-2010 Formula is not valid, 682 COR-ERR-2011 prompted metadata is not supported, 682 COR-ERR-2012 unable to load metadata, 682 COR-ERR-2013 exploration cannot be converted to formula based, 682 COR-ERR-2014 Due to Excel Worksheet Limitations the Results May Be Truncated, 682 COR-ERR-2015 Exploration cannot be converted to formula based, 683 COR-ERR-2016 Unable to retrieve package, 683 COR-ERR-2017 The current selection did not return any data, 683 corrupt cryptographic information, 573 could not deserialize context attribute, 565 credentials invalid, 581 cryptographic information cannot be encrypted, 570 DIS-ERR-3115 Task execution failed, 578 dispatcher is unable to process the request, 667 download of specified resource fails, 557 DPR-ERR-2014, 558 DPR-ERR-2022 No response generated, 563 DPR-ERR-2056 report server not responding, 542 DPR-ERR-2058, 558, 560 DPR-ERR-2079, 574, 635 DPR-ERR-2082, 632 Excel workbook closes unexpectedly, 664 HRESULT, 626 HTTP Error 404, 560 IBM Cognos 8 for Microsoft Office fails to initialize in Microsoft Internet Explorer, 662 IBM Cognos 8 for Microsoft Office Fails to Initialize in Microsoft Office, 661 IBM Cognos 8 for Microsoft Office unable to create trust relationship, 670 imported reports are missing charts or images, 667 java.lang.StackOverflowError, 628 Java Runtime Environment, 573 malformed request, 566 MDS-RUN-3213 Unable to locate database bulk load utility, 578 Microsoft Office Excel does not open a workbook published from IBM Cognos 8 for Microsoft Office, 662 Object reference not set to an instance of an object, 669 OP-ERR-0199, 620 OP-ERR-0201, 621 ORA-00907, 635 out of memory, 641 overflow errors, 633 page not found, 560 password expired, 581, 586 PCA-ERR-0057, 639 prompted reports, 674, 678 PRS-CSE-1255, 556 QE-DEF-0068, 590, 645

810

Index QE-DEF-0177, 603, 633 QE-DEF-0259, 604 QE-DEF-0260 parsing error, 605 QE-DEF-0285, 590, 645 QE-DEF-0288, 632 QE-DEF-0325, 590, 645 RDS Data Limit Exceeded, 666 RDS-ERR-1000 Report Data Service could not process the response from the content provider, 670 RDS-ERR-1001 PowerPlay report could not be run, 671 RDS-ERR-1004 connection could not be established with IBM Cognos 8, 671 RDS-ERR-1012 IBM Cognos Content Service unable to discover the content providers, 672 RDS-ERR-1013 Report Data Service unable to query Content Manager, 672 RDS-ERR-1014 Report Data Service unable to create the document object, 672 RDS-ERR-1015 Report Data Service unable to create a new document version, 672 RDS-ERR-1016 Report Data Service unable to create a new document content object, 672 RDS-ERR-1018 IBM Cognos 8 report could not be run, 673 RDS-ERR-1019 IBM Cognos Content Service unable to retrieve portal information from IBM Cognos Connection, 673 RDS-ERR-1020 currently provided credentials are invalid, 673 RDS-ERR-1021 IBM Cognos 8 report could not be run because it contains unanswered prompts, 674 RDS-ERR-1022 request received by Report Data Service is not valid, 674 RDS-ERR-1023 report could not be run because it exceeds the Report Data Service data size limit set by the administrator, 674 RDS-ERR-1027 encoding for the PowerPlay server could not be determined, 674 RDS-ERR-1028, 672 RDS-ERR-1030 security error occured while trying to establish a connection, 674 RDS-ERR-1031 Report Data Service was unable to retrieve the metadata for report, 674 RDS-ERR-1033 Report Data Service unable to create the report view, 674 RDS-ERR-1034 report specification for report could not be retrieved from IBM Cognos 8, 675 RDS-ERR-1039 request could not be cancelled. request is no longer running, 675 RDS-ERR-1040 conversation with conversation ID has been cancelled, 675 RDS-ERR-1044 The output for the requested version could not be retrieved, 675 RDS-ERR-1045 LayoutDataXML Output was not generated, 676 RDS Server unavailable, 666 Report Data Service (RDS) numbered error messages, 670 reports unavailable in IBM Cognos Connection jobs after using Save As command in Report Studio, 665 RQP-DEF-0114, 567 RSV-DR-0002, 632 RSV-SRV-0025, 626 RSV-SRV-0040, 620 RSV-SRV-0066, 567 SBW-ERR-0020, 599 secure, 88 servlet class fails to load on WebLogic, 579 SoapSocketException, 558 SQL1224N, 558 SQL Server cannot be found, 590 table or view not found in dictionary, 636 This item cannot be expanded, 669 UDA-SQL-0031, 590, 645 UDA-SQL-0107, 590, 603 UDA-SQL-0114, 603, 626, 633 UDA-SQL-0206, 626 UDA-SQL-0208, 590 UDA-TBL-0004, 633 Unable to load balance the request, 558 unable to open published Microsoft Office documents from IBM Cognos 8, 663 unable to view reports after clicking view report, 670 using, 539 you have chosen to download a file, 563 errors calculations with double quotation marks, 611 DB2-ERR-0028, 576 Administration and Security Guide 811

Index importing tab-delimited files, 657 importing translation files to Map Manager, 651 ERWin metadata out of memory error, 602 Essbase, 560 cube sample, 69 See Hyperion Essbase Essbase changes, 621 eTrust SiteMinder namespace, 201 event management service, 106 event management services, 105 events definition, 793 logging, 80 records, 80 viewing most recent, 387 viewing program, security, and systems, 544 Event Studio agents, 383 cannot call the SDK from Event Studio, 628 CNC-ASV-0001 java.lang.StackOverflowError, 628 customizing styles, 480 hyperlinks in email messages are stripped out when the agent is saved, 627 report contains no data, 627 returning databases to original state, 78 samples, 76 secured functions and features, 221 examples Shift-JIS encoding, 686 testing the installation, 545 Excel multipage report type does not work, 565 Excel, See Microsoft Excel Excel formatting reports, 359 Excel reports Analysis Studio, 635 exceptions unhandled, 542 execute permissions, 213 secured functions and features, 225 execution time, maximum, 137 expired password, 586 expired sessions, 668 exporting, 325 creating a specification, 325 data, 325 Exporting to a CWM file, 605 expressions braces, 604 errors, 604 externalized dimensions prompts, 605 external namespaces control browsing, 123 deploying references, 308, 309 eTrust SiteMinder, 201 IBM Cognos Series 7, 201 LDAP, 201 Microsoft Active Directory, 201 NTLM, 201 SAP, 201

F
failed entries rerunning, 297 failovers multiple dispatchers, 118 fails metric maintenance task, 657 features, See secured features file-based data sources paths, 181 files importing map files, 651 not found, 560 file types registering, 662 filter expressions creating for drilling through from IBM Cognos Series 7 to IBM Cognos 8, 426 filtering troubleshooting, 626 filters global, 40 make_timestamp columns, 626 Query Studio, 632 finding information, 29

812

Index firewall errors, 635 firewalls IBM Cognos Application Firewall, 204 firewall security rejection, 668 flicker, 580 folders configuration, 112 creating, 258 deploying public, 311 disabling when deploying, 312 My Folders, 258 ordering, 257 personal, 258 public, 258 font embedding in PDF files, 134 fonts changing, 482 changing defaults, 482 changing Report Studio interface, 487 in PDF files, 134 installing, 47 linking to core fonts, 665 not found when starting IBM Cognos Configuration on UNIX, 575 formats changes to decimals, 615 drill-through access, 403 format strings, 166 formatting .csv outputs, 526 colors, 482 data formats for Query Studio, 520 reports, 357 reports in CSV format, 360 reports in Excel format, 359 reports in HTML, 358 reports in XML, 358 reports show unexpected results, 624 style sheets, 482 text, 482 Framework Manager backing up, 197 cryptographic error, 551 sample models, 76 unable to load DB2 OLAP library, 576 full outer joins, 603 Oracle, 606 functions errors, 604 functions, See secured functions

G
gateway cannot access URI, 602 log file, 541 recommended settings for Microsoft IIS, 579 when to use ISAPI, 579 gateways definition, 793 specifying mappings for report data service, 116 GB18030 characters in names, 607 GB18030 support, 665 global changes fonts, 482 migrating changes to future releases, 483 rebranding, 481 style sheets, 482 global filters Cognos Viewer portlet, 280 drill-through reports, 40 drill-up and drill-down actions, 40 pages and dashboards, 278 prompts, 40 using metrics, 279 GlobalReportStyles.css file, 482 Glossary object capabilities, 229 secured functions and features, 221 See Also IBM WebSphere Business Glossary glyphs definition, 793 Go To page more information, 41 govenor limit, 141 Governor limit (IBM Cognos Connection setting), 674 Governor limits report sizes for report data service, 141 granting access, 215 graphic datatype, 603

Administration and Security Guide 813

Index graphics customizing portal interfaces, 486 interface images, 479 Query Studio, 489 Report Studio, 488 Great Outdoors, See IBM Cognos samples Great Outdoors samples, 57 grouped data items troubleshooting, 620 grouped lists subtotals, 621 grouped reports troubleshooting incorrect running totals, 642 grouping dispatchers, 112 groups, 208 adding and removing members, 211 adding distribution lists, 209 built-in, 233 creating, 210 customizing user interfaces in IBM Cognos Connection, 503 definition, 793 deploying, 313 IBM Cognos Controller, 210 missing membership in Active Directory Server, 576 modifying settings after installation, 236 security, 207 histories deployment, 332 history chart error, 658 history summary counts hiding, 537 home pages setting, 275 hotspots, limiting, 139 HRESULT errors, 626 HTML printed report unsatisfactory, 649 HTML formatting reports, 358 HTML Source, 737 HTML Viewer, 733 HTTP Error 404, 560 Hyperion Essbase data sources, 164 hyperlinks in email messages are stripped out when the agent is saved, 627

I
IBM Cognos business packages in SAP Enterprise Portal 6.0, 446 namespace, 203 samples, 63 Series 7, adding content to the portal, 52 Series 7, using namespace, 52 IBM Cognos 8 accessing IBM Cognos Connection using URLs, 787 dispatchers, 108 does not start on an application server, 571 performing tasks using URLs, 773 service does not start, 552 services, 108 starting components using URLs, 777 using report data in Microsoft Office, 343 IBM Cognos 8 administration, 43 IBM Cognos 8 and PowerPlay single signon, 380 IBM Cognos 8 BI Analysis for Excel cell-based report errors, 665 numbered error messages, 681 IBM Cognos 8 for Microsoft Office configuration and setup issues, 661

H
Han characters troubleshooting, 665 help getting, 29 unable to launch, 547 hidden entries, 254 viewing, 255 hiding drill-through reports, 32 entries, 32, 254 history summary counts, 537 user interface elements, 503, 504, 707 user interface elements in pages and dashboards, 504 hierarchies DB2 OLAP, 165

814

Index failure to initialize in Microsoft Office, 661 numbered error messages, 680 opening published documents, troubleshooting, 662 processing issues, 666 security issues, 669 supported Microsoft Office applications, 680 IBM Cognos 8 gateway addresses, 681 IBM Cognos 8 Go! Office data size limits, 674 deploying the client components, 343 downloading documents in IBM Cognos Connection, 344 error using Run Reports, 578 firewall security rejection, 668 macro seciurity level for Microsoft Office XP, 344 numbered error messages, 676 opening in Microsoft Word, 661 rendering reports, troubleshooting, 666 SSL, 344 unable to view reports, 670 using IBM Cognos report data in Microsoft Office, 343 IBM Cognos 8 samples, 544 IBM Cognos 8 server fails to start, 552 IBM Cognos 8 service server not available, 553 starting, 574 IBM Cognos Administration access denied, 587 Status page, 99 IBM Cognos Application Firewall, 204, 776 IBM Cognos Configuration changing the sort buffer size, 633 font not found error on UNIX, 575 invalid settings, 553 problems opening, 540 problems saving a configuration, 567 problems with keyboard navigation, 572 trouble generating cryptographic keys after install, 570 unable to start, 572 IBM Cognos Connection, 239 accessing using URLs, 787 adding user interface elements, 506 agents, 385 background color in header, 485 customizing, 502 customizing appearance, 484 customizing report output formats, 517 customizing user interface elements, 503 downloading IBM Cognos 8 Go! Office documents, 344 downloading Microsoft Office documents, 344 entries do not appear, 582 header background color, 485 hiding user interface elements, 503 main header branding, 484 Series 7 reports, 52 troubleshooting unavailable reports, 665 unable to open, 560 unable to open published Microsoft Office documents, 663 unable to retrieve portal information, 673 updated look for 8.3, 41 IBM Cognos Connection styles, 260 IBM Cognos Controller security, 210 IBM Cognos Finance data sources, 157 IBM Cognos groups creating, 210 updating, 211 IBM Cognos Now! Cube data sources, 157 IBM Cognos Office Connection, See IBM Cognos 8 Go! Office IBM Cognos Planning - Contributor data sources, 157 IBM Cognos Planning - Series 7 data sources, 157 IBM Cognos PowerCubes open slowly, 592, 613 IBM Cognos Resource Center, 29 IBM Cognos roles creating, 210 updating, 211 IBM Cognos samples, 63 IBM Cognos Series 7 cubes, 157 migrating reports to IBM Cognos 8, 127 opening cubes, 382 opening PowerPlay reports, 380 PowerPlay reports and cubes, 379 reports in IBM Cognos Connection, 378 running PowerPlay reports, 380 Administration and Security Guide 815

Index users, 207 IBM Cognos Series 7 namespace, 201 IBM Cognos Series 7 namespaces single signon, 380 IBM Cognos Series 7 reports cannot access, 590 IBM Cognos Transformer known issues, 609 IBM Cognos Virtual View Manager, See Also composite software IBM Cognos Visualizer reports setting up drill-through access to IBM Cognos 8, 426 IBM Cognos Watchlist, See Metric List IBM DB2, See DB2 IBM Infosphere Warehouse Cubing Services, 168 IBM Lotus Notes attachments, 534 IBM Metadata Workbench, 32 lineage solution, 151, 355 IBM WebSphere AIX version, 564 IBM WebSphere Business Glossary accessing in Cognos Viewer, 356 configuring URI, 152 icon graphics not working in Portal Services, 646 icons custom report templates, 497 specifying alternative for entry, 259 images missing in imported reports, 667 missing in PDF report, 648 multiple images in Microsoft Excel, 667 refreshing, 678 Image Viewer, 734 Import Content wizard failure to open, 677 slides, troubleshooting, 676 importing configurations, 331 data into IBM Cognos 8, 328 metric data for Metric Studio, 394 portlets in IBM Cognos Connection, 432 samples, 74 importing data rules, 315 improving performance, 127 information finding, 29 Informix data sources, 169 initial security settings, 233 inner joins, 606 installation problems, 549 requirements for directory name, 558 testing, 545 installation and configuration issues cannot load DB2 OLAP library, 576 installation directory problems after renaming or moving, 571 installations COM add-in, 661 installing fonts, 47 IBM Cognos 8 on Linux, 567 IBM Cognos business packages in SAP Enterprise Portal 6.0, 446 portlet applications file for WebSphere Portal, 442 Integrated Windows Authentication issues, 575 interactive features controls in reports, 36 interactivity in pages and dashboards, 278 interfaces changing appearance of components, 479 Internet Explorer, See Microsoft Internet Explorer invalid cogstartup.xml file, 573 invalid settings content store, 553 IBM Cognos Configuration, 553 iqd data source troubleshooting Sybase connection error, 609 IQD files unable to use, 610 ISAPI when to use for a gateway, 579 isolation levels data sources, 188 iViews configuring, 447 default content and appearance, 448

816

Index editing, 447 personalizing, 448 See Also portlets

K
keyboard navigation problems, 572 key figures not added after importing, 601 prompts, 605 Knowledge Base, 539 known issues IBM Cognos Transformer, 609 Metric Studio, 654, 658 Korean characters display incorrectly after upgrade, 566 Korean characters troubleshooting, 665

J
Japanese characters display incorrectly after upgrade, 566 characters in export path, 605 Japanese characters round trip safety, 686 troubleshooting, 665 Japanese Internet Explorer Analysis Studio, 635 jar file error when starting configuration, 573 Java supported versions for DB2 content store, 552 uses all of CPU, 552 JAVA_HOME setting, 573 java.lang.NoClassDefFoundError, 551 Java error when starting configuration, 573 job queue metrics, enabling, 153 jobs, 40 definition, 794 delivery options, 248 properties, 248 rerunning failed, 297 scheduling, 301 services, 105 steps, 301 submission of steps, 248 job service, 106 job steps definition, 794 joins full outer, 603 inner, 606 Oracle, 606 JRE conflicts when using portal services, 595 JVM conflicts when using portal services, 595

L
language conversion tables, 566 does not match, 597 incompatibility after upgrade, 566 language packs troubleshooting subkeys, 664 languages choosing for reports, 360 data does not display properly, 610 defaults for reports, 362 incorrect in SAP BW query, 603 mixed when using samples, 636 new support in version 8.4, 31 OLAP data sources, 631 SAP BW data sources, 361 LDAP namespace, 201 levels member unique names, 405 security, 605 limiting content browsing, 513 lineage configuring, 151 IBM Metadata Workbench, 151, 355 viewing, 33, 355 Lineage object capabilities, 229 secured functions and features, 221 linked fonts, 665 linked models upgrading, 606 Administration and Security Guide 817

Index links broken following deployment, 599 entries, 256 unable to click, 647 Linux characters not displayed properly, 567 list objects rendering empty lists, 679 list reports More or All errors, 669 lists subtotals in grouped lists, 621 load-balancing setting, 129 load balancing dispatchers, 129 loading message saving a report takes a long time, 628 locale mismatch, 597 locales definition, 794 Microsoft Analysis Server, 169 overriding in the prompt cache, 124 sorting of entries, 122 users, 208 locking portlets, 433 log database deleting tables, 568 log destinations types of, 79 log files, 539 for gateway errors, 541 locale configuration, 541 Metric Studio, 653 run-time, 541 silent mode, 541 startup configuration, 540 transfer, 540 transfer summary, 540 uninstallation, 541 logging audit reports, 82 data schema for messages, 749 messages, 80 native queries, 81 report validation levels, 81 818 setting up, 80 logging levels setting, 82 logging levels affect performance, 594 logging off, 239 logging on, 239 multiple namespaces, 216 log messages remote log server, 79 See Also troubleshooting logon problems SAP namespace, 584, 585 logs database tables for messages, 749 message processing, 79 metric maintenance tasks, 657 service, 107 services, 105 Lotus Notes attachments, 534

M
managing packages in non-root folders, 36 Map Manager configuring for multilingual, 46 importing files, 651 importing translated text files, 651 measures format strings, 166 not added after importing, 601 members drill-through access, 404 IBM Cognos groups and roles, 211 member unique names relational metadata, 405 troubleshooting, 637 messages logging, 80 metadata, 243 Metric Designer adding IQD files to an import source, 658 blanks in scorecard hierarchy preview, 659 troubleshooting, 653 Metric History Chart, 41, 728 Metric List, 41, 726

Index metric maintenance task fails, 657 metric package DB2, 657 metric packages access permissions, 657 definition, 794 metric packages for Metric Studio changing default action, 392 metrics definition, 794 resetting, 103 resetting for the system, 103 metric scores attributes, viewing, 101 metric scores in Scorecard pane, 99 Metrics Custom Diagram, 731 metrics for Metric Studio, 391 changing export properties, 399 changing import tasks, 395 clearing metric history and calendar data, 395 clearing metric history data, 396 clearing rejected data logs, 395 clearing rejects tables, 395 creating export tasks, 397 creating import tasks, 394 creating maintenance tasks, 396 creating packages, 391 deleting tasks, 393 importing data into metric store, 394 importing data into staging tables, 394 importing data tasks, 394 maintenance tasks, 395 modifying import tasks, 395 modifying tasks, 393 recalculating derived values, 396 running tasks, 392 scheduling tasks, 392 synchronizing users with namespaces, 396 transferring data to metric store, 394 updating search engine indexes, 396 metrics for system performance, 91 data gathering, 91 jvm, 94 list of metrics, 92 process, 98 queue, 93 request, 95 session, 92 Metrics Impact Diagram, 730 Metrics Manager service, 107 Metrics pane in IBM Cognos Administration, 100 metric store failure, 578 permissions, 658 Metric Studio cmm_uninstall script, 655 creating metrics, 391 data source not displayed, 656 DB2, 658 errors when importing, 657 known issues, 654, 658 metrics, 391 metric store check fails, 657 permission denied, 657 portlets, 34, 41 secured functions and features, 221 SQL Server 2005 error, 655 support bundle, 654 task fails, 657 troubleshooting, 653 user permissions for metric store, 658 metric threshold setting, 101 Microsoft security update affects memory, 552 SharePoint Portal Server, 454 Microsoft .NET Framework, 343 Microsoft .NET support for Microsoft applications is not installed, 679 Microsoft Active Directory, 201 Microsoft Analysis Server data sources, 169 single signon, 169 Microsoft Analysis Services setting up MSAS cube samples, 68 Microsoft Excel #ERROR, 667 #NAME? errors, 665 COC-ERR-2305, 679 COC-ERR-2607, 679 failure to render lists, 677 Administration and Security Guide 819

Index More or All errors, 669 no report content is imported, 667 refreshing content, troubleshooting, 681 row and column restrictions, resolving, 669 supported versions, 677 using IBM Cognos report data in workbooks, 343 workbook closes unexpectedly, 664 Microsoft Excel 2007 support, 39 Microsoft IIS Web servers recommended gateway settings, 579 Microsoft Internet Explorer cannot initialize IBM Cognos 8 for Microsoft Office, 662 IBM Cognos 8 for Microsoft Office, setting options, 676 setting security options, 663 Microsoft Office report data service, 108 supported applications are not installed, 679 using IBM Cognos report data in workbooks and presentations, 343 Microsoft Office documents downloading from IBM Cognos 8, 344 renaming folders or documents, 681 Microsoft Office Excel multipage report type does not work, 565 Microsoft Outlook resolving IBM Cognos 8 Go! Office issues, 661 Microsoft PowerPoint importing slides, troubleshooting, 679 report format and layout, troubleshooting, 673 supported versions, 677 troubleshooting Import Content wizard, 676 using IBM Cognos report data in presentations, 343 Microsoft SharePoint support for Portal 2003, 41 Microsoft SQL Server creating data source connections, 589 data sources, 171 single signon, 171 Microsoft SQL Server 2008, 171 Microsoft Word IBM Cognos 8 Go! Office does not start, 661 supported versions, 677 migrating interface customization to later versions, 483 portlets, 464 ReportNet system.xml files, 501 Migration service, 107 missing items in a report or analysis, 637 missing values dividing by zero, 620 model troubleshooting import error, 609 model-based drill-through access using scope, 407 model errors calculations with double quotation marks, 611 modeling sample models and packages, 61 models, 243 backing up, 197 database samples, 76 definition, 794 modifying for samples, 74 optimizing, 128 monitoring events, 80 services, 105 monitor service, 107 More option Error 0\:RSV-BBP-0027 error, 669 move dispatchers, 112 movement data, 199 moving deployment archives, 328 entries, 252 MSAS, 560 MS Cube, 559 Multi-page, 738 Multi-page portlet, 40 creating dashboards, 275 multiple formats unable to select, 637 multiple languages data does not display properly, 610 multiple values drill-through, 38

820

Index multiscript extensions, 703 My Folders, See folders My Folders tab missing, 646 My Pages adding IBM Cognos Series 7 content, 52 news item headlines receiving, 387 news items definition, 795 non-english characters appear as placeholders, 642 non-English operating system troubleshooting .NET Framework, 664 no response generated, 563 notification database deleting tables, 568 NTLM namespace, 201 access to IBM Cognos Administration denied, 587 null values included in count summaries, 625 null-value suppression, 162 numeric formats, 166

N
named sets limitations, 378 nested or parallel sets overlapping, 621 namespace Active Directory Server missing group membership, 576 cannot log on, 556 recreating, 572 namespaces, 201 browsing external, 123 definition, 794 deleting, 202 deploying external references, 308, 309 IBM Cognos, 203 logging on, troubleshooting, 672 multiple, 201 multiple namespaces, 216 restoring, 202 using from IBM Cognos Series 7, 52 See Also authentication providers See Also external namespaces native language support, 665 native query logging, 81 native SQL adding comments to SQL statements, 147 native SQL commands, 745 nested list reports not running after upgrading, 620 nested reports troubleshooting, 678 nested sets unexpected summary values, 625 network outage services fail to start, 557 new features IBM WebSphere Business Glossary, 32 version 8.3, 35 version 8.4, 31

O
object capabilities, 33, 229 Glossary, 229 Lineage, 229 setting up, 231 See Also secured functions objects customizing actions in IBM Cognos Connection, 509 removing actions, 510 ODBC data source connections, 589 data sources, 173 OLAP data sources, 559, 560 connections, 70 languages, 631 members missing or inaccessible, 576 OLAP source cannot connect, 592 opening agents from IBM Cognos Connection, 385 PowerPlay reports, 380 reports, 348 OP-ERR-0199 errors, 620 OP-ERR-0201 errors, 621 optimizing models, 128 performance, 127 options advanced current run, 351 Administration and Security Guide 821

Index current report run, 350 report run defaults, 348 setting advanced for PDF format, 358 ORA-00907 errors, 635 Oracle CM-CFG-5063, 591 CM-SYS-5007, 591 CM-SYS-5036, 591 content manager connection, 591 deployment errors, 578 failed Metric Studio reports, 654 full outer joins, 606 Metric Studio disconnected from database, 655 NLS_LANG environment variable, setting, 658 unable to use IQD file, 610 Oracle Application Server deploying IBM Cognos 8, 577 IBM Cognos 8 deployment failure, 564 Oracle content store compatibility levels, 578 error initializing, 578 Oracle databases proxy connections, 190, 193 virtual private databases, 190, 194 Oracle data sources, 176 troubleshooting, 635 Oracle full outer joins, 603 ordering entries, 257 folders, 257 organizing entries, 251 outer joins full, 603 Oracle, 606 out of memory error, 602 out of memory errors in HP-UX, 641 output files system metrics, 543 overflow errors in crosstab report, 633 packages, 243, 601 administering, 335 definition, 795 deploying, 312 disabling when deploying, 312 drilling-through, 403 large, 606 managing, 36 publishing, 36 setting up drill-through access, 408 page breaks unexpected results, 630 page not found error starting IBM Cognos 8 in Windows 2003, 560 pages access permissions, 270 adding interactivity, 278 content, 267 creating, 269 creating tabs, 273 customizing fonts, 486 custom Welcome page, 514 deleting, 269 deleting tabs, 274 drill-through actions, 283 drill-up and drill-down actions, 283 editing, 270 global filters, 278 hiding user interface elements, 504 home, 275 managing in IBM Cognos Connection, 267 multiple tabs, 40 properties, 249 sharing, 270 See Also dashboards paper sizes defining, 247 parse errors opening or running upgraded reports, 633 passports definition, 795 password expired, 581 passwords SAP namespace, 584 past entries, 287

P
p2pd.war file for WebLogic, 565 package creating, 162 822

Index past activities, 287 pcactivate deploying updated PowerCubes, 163 PCA-ERR-0057 errors, 639 PDF format character encoding settings, 134 compression algorithm level settings, 134 content compression type settings, 134 excluding blank pages in reports, 372 file settings, 134 font embedding settings, 134 reports, 358 setting advanced options, 358 PDF manual printing, 547 PDF problems charts, 648 missing images in report, 648 printing reports, 648 PDF security setting in reports, 358 performance BAPI errors, 641 logging level, 594 peak times, 130 Query Studio is slow, 641 query takes too long to filter non-ASCII text, 641 running reports, 639 system, 91 tuning, 127 Performance assessement of system, 100 periodical document settings, 138 permissions actions, 215 deleting groups and roles, 216 deploying, 324 deployment, 216 execute, 213 granting or denying, 215 metric store, 658 parent/child, 216 properties, 246 read, 213 secured functions and features, 221, 225 set policy, 213 traverse, 213 write, 213 See Also access permissions personal folders, See folders personalizing portals SAP BW iViews, 448 PIA (Primary Interop Assemblies) installing subkeys, 661 planning deployment, 308 planning data service, 107 planning job service, 107 planning Web service, 107 plannning administration console service, 107 Plumtree portal, See ALUI 6.1 pop-up blocking, 563 portal, 260 errors in starting, 560, 563 portal problems, 645 icon graphics not working, 646 My Folders tab does not appear, 646 styles used in previous version still applied, 647 unable to click links, 647 unable to open, 560 portals, 239 customizing object actions, 509 personalizing IBM Cognos Connection, 260 supported in IBM Cognos 8, 441 portal services conflicts with JREs, 595 only administrator can see portlets using IBM Websphere portal, 597 unable to access portlets, 595 Portal Services, 717 icon graphics not working, 646 protocol schemes, 467 run-time parameters, 434, 465 unable to authenticate user, 587 unable to log on, 587 portlet applications file installing in WebSphere Portal, 442 portlets, 429, 717 access permissions, 433 Bookmarks Viewer, 732 cannot access, 595 Cognos Extended Applications, 726 Cognos Navigator, 717 Administration and Security Guide 823

Index Cognos portlets, 429 Cognos Search, 719 Cognos Viewer, 721, 724 configuring cache in IBM Cognos Connection, 434 definition, 795 disabling, 433 enabling communications, 271 HTML Source, 737 HTML Viewer, 733 Image Viewer, 734 importing into IBM Cognos Connection, 432 locking, 433 Metric History Chart, 41, 728 Metric List, 41, 726 Metrics Custom Diagram, 731 Metrics Impact Diagram, 730 migrating, 464 modifying, 271, 435, 444, 454 Multi-page, 40, 738 new in IBM Cognos Connection, 34, 41 RSS Viewer, 735 Safe Mode Viewer, 598 single signon, 432 WSRP standard, 432 ports already in use, 551 PowerCubes cannot open, 559 creating packages, 162 data sources, 157 error when creating data source connections, 592 incorrect results, 626 location paths, 157 open slowly, 592, 613 optimizing, 157 paths to cube files, 181 pcactivate, 163 troubleshooting drilling through, 643 updating, 33, 163 PowerPlay changing report defaults, 381 connection problems, 672 failure to retrieve metadata from, 674 font conversions Series 7 Web reports, 690 report properties, 247 running reports, troubleshooting, 671 specifying server location for IBM Cognos Connection, 116 unresponsiveness, troubleshooting, 674 using PowerPlay report authoring tools, 379 PowerPlay reports setting up drill-through access to IBM Cognos 8, 426 PowerPlay Web Explorer working with cubes, 382 predefined entries, 234 initial access permissions, 700 preferences viewing hidden entries, 255 preferences, See IBM Cognos Connection styles prerequisites deploying, 324 presentation service, 108 presentation services, 105 preview modes Query Studio, 520 Primary Interop Assemblies (PIA), 661 printers setting up, 48 printing after restarting dispatcher, 658 reports, 373 setting up printers, 48 printing copyright material, 29 printing PDF manuals, 547 printing reports, 648 missing images in PDF, 648 PDF reports, 648 problems, 629 unsatisfactory results when printing HTML reports, 649 prioritizing queries, 143 problems SAP namespace, 585 problems opening IBM Cognos Configuration, 540 processes BI Bus server remains in memory after shutdown, 594 dispatcher capacity, 129 setting number, 131 processing capacity, 129 processing issues, 666

824

Index product languages adding to Cognos Viewer, 493 setting, 260 product locale definition, 795 profiles styles, 437 user, 339 projects backing up, 197 definition, 795 prompt cache overriding locales, 124 prompted reports error messages, 674, 678 incorrect format for the Prompt value, 668 prompts cache data, 301 definition, 795 key figures, 605 page formats, 494 scheduled entries, 299 specifying default report values, 362 properties .csv outputs, 526 agents, 249, 384 changing metric export properties for Metric Studio, 399 changing metric import tasksfor Metric Studio, 395 contacts, 243 data movement, 200 disabling entries, 243 entries, 243 formats, 247 jobs, 248 languages, 243, 247 modifying metric import tasks for Metric Studio, 395 multilingual, 361 multilingual IBM Cognos Series 7 reports and cubes, 382 owners, 243 pages, 249 permissions, 246 prompt values, 247 report output versions, 243 rules, 250 run histories, 243 running as the owner, 247 screen tips, 243 shortcuts, 243 source reports, 243 protocol schemes Portal Services, 467 providers security, 201 proxy connections Oracle databases, 190, 193 proxy sessions starting in databases, 742 stopping in databases, 743 public folders, 258 deploying, 311 published documents opening in Microsoft Office, 662 unable to open from IBM Cognos Connection, 663 publishing definition, 795 packages in non-root folders, 36

Q
QE-DEF-0068 errors, 645 QE-DEF-0177, 603 QE-DEF-0177 errors, 633 QE-DEF-0259, 604 QE-DEF-0260 parsing error, 605 QE-DEF-0285 errors, 645 QE-DEF-0288 errors, 632 QE-DEF-0325 errors, 645 qrsvpproperties.xml.sample file, 525 queries definition, 796 prioritizing, 143 query calculations null values included in count summaries, 625 query execution, concurrent, 141 Query Studio changing the default template, 525 creating reports without data, 354 customizing data formats, 520 customizing graphics, 489 customizing menu colors, 489 customizing styles, 480 Administration and Security Guide 825

Index customizing toolbars and menus, 490 disabling session caching, 145 filters, 632 modifying style sheets, 488 QE-DEF-0260 parsing error, 605 report definition, 545 report properties, 247 reports, 347 secured functions and features, 221 starting in preview mode, 520 query subjects DB2, 603 queue limits setting, 133 queue metrics, enabling, 153 queues managing, 36 quick tours using, 29 removing actions, 510 data formats for a locale, 523 renaming dispatchers, 116 entries, 251, 253 styles, 480 reordering tabs, 275 report contains no data, 627 report data service, 105, 108 specifying gateway mappings, 116 Report data service report size limit, 141 Report Data Service (RDS) cancelling requests, 675 Data Limit Exceeded errors, 666 failure to connect to PowerPlay Enterprise Server, 672 numbered error messages, 670 processing requests, troubleshooting, 667 unavailable server, troubleshooting, 666 report definition in Query Studio, 545 report distribution problems, 627 report link in email notification does not work, 627 ReportNet to IBM Cognos 8 upgrade file, 541 ReportNet reports upgraded reports look different, 641 report output how long to keep, 365 viewing, 364 report output files saving, 148, 363 saving in IBM Cognos 8, 149 saving outside IBM Cognos 8, 149 report outputs definition, 796 saving to a file, 39 reports, 240, 347 accessibility for the disabled, 347 adding custom templates, 495 adding multilingual properties, 361 adding to alert list, 366 advanced current run options, 351

R
ragged hierarchies Report Studio, 615 read permissions, 213 rebranding, 481 recalculating derived metric values for Metric Studio, 396 recreating the Cognos namespace, 572 recursive evaluation errors, 639 refresh caches, 301 Refresh all data (command) troubleshooting, 677 refresh cache data, 301 regular column converting to calculated column, 611 related documentation, 27 relational data drilling through to cubes, 644 relational data sources members missing or inaccessible, 576 remote servers connecting, 453 reconfiguring in ALUI 6.1, 450 starting in ALUI 6.1, 449

826

Index allowing alert lists, 365 Analysis Studio, 347 bursting, 374 cannot access Series 7 reports, 590 cell-based with #NAME? errors, 665 changing PowerPlay defaults, 381 choosing languages, 360 comments, 369 comments in saved reports, 32 configuring for multilingual, 47 contains no data, 627 controlling interactive features, 36 creating, 353 creating distribution lists, 374 creating drill-through access, 422 creating in Query Studio without data, 354 creating views, 354 CSV formats, 360 current run options, 350 customizing output formats in IBM Cognos Connection and Cognos Viewer, 517 customizing reports using styles, 482 default languages, 362 default options, 348 definition, 796 deploying, 307 disabling as email attachments, 534 display problems in dashboards, 598 distributing, 372 drilling down, 376 drilling through, 401 drilling through passing multiple values, 377 drilling through to target report, 376 drilling up, 376 drill-through text, 425 editing, 356 emailing, 373 enabling comments, 369 enabling watch rules, 367 exceeding RDS data limits, 666 Excel formats, 359 excluding blank pages in PDF, 372 format of prompted reports, 668 formats, 357 formatting changes when upgrading, 641 HTML formats, 358 IBM Cognos Series 7, 379 IBM Cognos Series 7 in IBM Cognos Connection, 378 IBM Cognos Series 7 multilingual properties, 382 migrating IBM Cognos Series 7 to IBM Cognos 8, 127 missing charts or images, troubleshooting, 667 nested reports, troubleshooting, 678 no report content is imported in IBM Cognos 8 Go! Office, 667 opening, 348 PDF format, 358 printing, 373 prompted reports in IBM Cognos 8 Go! Office, 668 Query Studio, 347 removing from alert list, 366 report names with quotation marks, 667 Report Studio, 347 rerunning failed, 297 resubmitting failed, 40 running, 240, 348 running IBM Cognos 8 Go! Office reports after expired session, 668 saving, 373 saving report outputs to a file, 39 scheduling, 299 scheduling last day of month, 301 scheduling views, 299 setting queue limits, 133 specifying default prompt values, 362 targeting, 39 troubleshooting, 630 troubleshooting report rendering problems, 666 unable to view reports in IBM Cognos 8 Go! Office, 670 usage audit, 87 user access to Series 7 from IBM Cognos Connection, 52 using alerts, 38 viewing, 348 viewing older versions, 364 watch rules, 366 XML formats, 358 report server managing data source connection timeouts, 184 report server settings, 143 Administration and Security Guide 827

Index report service, 105 advanced properties, 529 advanced settings, 644 report services, 108 report specifications custom template, 495 definition, 796 missing content, 679 upgrading, 332 Report Studio authoring modes, 37 authoring profiles, 227 creating drill-through reports, 422 customizing graphics, 488 customizing styles, 480 custom report templates, 495 disabling session caching, 145 does not start, 563 interface fonts, 487 Map Manager, 46 menu colors, 487 modifying style sheets, 486 nulls included in count summaries, 625 ragged hierarchies, 615 report properties, 247 reports, 347 saving changes in a job, 665 secured functions and features, 221 testing, 545 unbalanced hierarchies, 615 unexpected summary values when using nested sets, 625 Report Studio authoring modes enabling, 37 report subscriptions, 38 report templates custom icons, 497 report validation levels, 81 report views definition, 796 requests load-balancing, 129 processing, 131 requirements installation directory, 558 resetting metrics, 103 system metrics, 103 resources, 539 troubleshooting, 539 Resources.xml file, 497 restoring data, 197 namespaces, 202 samples databases, 64 restricting access to IBM Cognos 8, 53 restricting content browsing, 513 using a URL command, 513 using the system.xml file, 513 resubmitting failed, 40 result set of stored procedure, 601 return values cogconfig.sh not UNIX compliant, 567 rights, See access permissions roles, 208 adding and removing members, 211 adding distribution lists, 209 built-in, 233 creating, 210 customizing user interfaces in IBM Cognos Connection, 503 deploying, 313 IBM Cognos Controller, 210 IBM Cognos Series 7, 209 modifying settings after installation, 236 predefined, 234 running reports, 209 security, 207 root name for Cognos portlets changing, 464 round trip safety applying conversions and substitutions, 689 configuration utility, 686 Japanese characters, 686 restoring default conversion settings, 689 Series 7 PowerPlay Web reports, 690 specifying conversions, 687 routing reports setting server group names, 128 RQP-DEF-0177 errors, 639

828

Index RSS definition, 796 RSS channels displaying the HTML code, 436 RSS Viewer, 735 RSV-DR-0002 error, 632 RSVP.PROMPT.RECONCILIATION settings, 143 RSVP.RENDER.VALIDATEURL, 776 RSV-SRV-0025 errors, 626 RSV-SRV-0040 errors, 620 rules deployment, 315 properties, 250 run history how long to keep, 296 scheduled entries, 300 viewing, 294 running agents, 383 data movement, 199 entry history, 294 metric tasks for Metric Studio, 392 PowerPlay reports, 380 reports, 240, 348 scripts, 606 running reports cannot find database, 632 DPR-ERR-2082, 632 not running as expected, 633 not running as scheduled, 637 ORA-00907 error, 635 performance problems, 639 problems, 629 Query Studio is slow, 641 query takes long time to filter non-ASCII text, 641 roles, 209 scheduled reports fail, 636 table or view not found in dictionary, 636 unable to select multiple formats, 637 running totals troubleshooting, 642 run priority, 293 run-time parameters Portal Services, 465

S
Safari Web browsers drill-through links not active, 642 Safe Mode Viewer, 598 samples, 539 data source connections, 67 deleting, 78 Essbase cubes, 69 Event Studio, 76 general employee information, 60 general financial information, 58 general sales and marketing information, 60 GO data warehouse, 61 GO Sales transactional database, 62 Great Outdoors, 57 Great Outdoors company structure, 58 importing, 74 Metric Designer, 63 Metric Studio, 73 mixed languages, 636 model design, 61 models, 76 MSAS cube, 68 new audit reports, 36 OLAP data sources, 70 restoring samples databases, 64 setting up, 63 using, 544 samples (IBM Cognos) using multilingual data, 703 SAP password policy, 584 SAP Business Information Warehouse (SAP BW) data sources, 176 SAP BW errors running reports, 599 unable to identify SAP permissions, 587 unable to identify version, 599 using non-ASCII text values, 641 wrong language in query, 603 SAP BW data sources languages, 361 query calculations, 625 sectioning reports, 622 SAP data source troubleshooting data retrieval, 612 Administration and Security Guide 829

Index SAP EP customizing Cognos portlets, 447 deploying Cognos portlets, 445 SAP namespace, 201 logon problems, 584, 585 repeated prompts for authentication, 585 SAP package BAPI error when generating PowerCube, 609 SAP portal supported versions, 446 SAP query missing categories in Transformer model, 612 SAP unbalanced hierarchy troubleshooting in Transformer, 612 saving report output files, 148, 363 report output files in IBM Cognos 8, 149 report output outside IBM Cognos 8, 149 reports, 373 taking a long time, 628 schedules creating for last day of month, 301 credentials, 218 entries, 300 entries based on occurrences, 305 jobs, 301 last day of month, 301 manage, 291 manage upcoming activities, 289 managing, 294, 299 metric tasks for Metric Studio, 392 multiple entries, 301 prompts, 299 reports and report views, 299 run history, 300 seting up trigger occurrences on server, 535 setting priority, 36 trigger-based, 304 Scheduling secured functions and features, 221 schema data source commands, 741 scope using in drill-through access, 407 Scorecard pane in IBM Cognos Administration, 99 screen flicker, 580 830 scripts to delete tables from databases, 568 SDK cannot call the SDK from Event Studio, 628 searching entries, 259 sectioning reports SAP BW data sources, 622 secured features access permissions, 225 initial access permissions, 693 See Also secured functions secured functions access permissions, 225 Administration, 221 Analysis Studio, 221 Cognos Viewer, 221 Detailed Errors, 221 Event Studio, 221 Glossary, 221 initial access permissions, 693 Lineage, 221 Metric Studio, 221 Query Studio, 221 Report Studio, 221 Scheduling, 221 secure error messages, view details, 88 securing content store, 237 dispatchers, 120 security access permissions, 213 access to entries denied, 581 access to IBM Cognos Administration denied, 587 application levels, 204 authentication, 201 built-in entries, 233 cannot log on to portlets, 583 change passwords, 581 credentials invalid, 581 data sources, 195 default users, 233 deployment, 216, 308 entries do not appear, 582 events, 544 Everyone group, 53

Index functions and features, 221 IBM Cognos Application Firewall, 204 initial policies, 233 initial settings, 233 issues with Integrated Windows Authentication, 575 levels, 605 metric packages, 657 models, 201 modifying settings after installation, 236 password expired, 581 Portal Services, 465 predefined entries, 234 problems, 581 problems logging on to an SAP namespace, 584 providers, 201 restricting access to IBM Cognos 8, 53 setting for PDF output, 358 setting up, 233, 236, 581 System Administrators role, 234 unable to log on, 581 users, groups, and roles, 207 security issues, 669 segmented models upgrading, 606 selection-based interactivity, 371 Series 7, See IBM Cognos Series 7 Series 7 namespaces do not initialize when services are started, 591 Series 7 PowerPlay Web reports round trip safety, 690 servers administration, 105 concurrent query execution, 141 group names, 128 remote, reconfiguring in ALUI 6.1, 450 starting remote server in ALUI 6.1, 449 services, 105 activating, 110 agent, 106 agent services, 105 batch report, 106 Content Manager, 106, 121 data integration, 106 delivery, 106 delivery services, 105 event management, 106 event management services, 105 fail to start after network outage, 557 IBM Cognos 8, 108 job, 106 job services, 105 log, 107 logs, 105 Metrics Manager, 107 Migration, 107 monitor, 107 monitoring services, 105 planning data, 107 presentation, 105, 108 report, 108 report data, 108 reports, 105 stopping and starting, 108 system, 108 unable to start, 551 session caching disabling, 145 sessions definition, 796 starting proxy, 742 stopping proxy, 743 set policy permissions, 213 sets nested or parallel sets overlapping, 621 setting access permissions, 216 access to secured functions and features, 225 advanced current run options, 351 current run report options, 350 data tree displays, 335 default report options, 348 dispatcher scans for servlet gateways, 119 frequency of dispatcher status scans, 118 home pages, 275 logging levels, 82 maximum execution time, 137 periodical document retention, 138 watch list output retention, 138 Settings pane in IBM Cognos Administration, 100 setting up drill-through access in packages, 408 drill-through targets in Analysis Studio, 412 Administration and Security Guide 831

Index logging, 80 printers, 48 samples, 63 setup issues, 661 SharePoint Portal Server deploying Cognos portlets, 454 sharing pages, 270 Shift-JIS encoding example, 686 shortcuts adding actions, 510 creating, 240 source reports, 240 showing user interface elements, 506 shutdown processes remain in memory, 594 signons data sources, 186 Simplified Chinese troubleshooting, 665 single signon access to IBM Cognos Administration denied, 587 IBM Cognos 8 and PowerPlay, 380 issues with Integrated Windows Authentication, 575 Microsoft Analysis Server, 169 Microsoft SQL Server, 171 non-Cognos portlets, 432 problems with Portal Services, 583 SiteMinder logging on to a namespace, 672 skins, See styles SMTP error-handling delivery service, 530 SMTP queue metrics, enabling, 153 SOAP response error when viewing report outputs from email link, 642 Solaris JRE 1.5, 575 sorting non-English locales, 122 source reports shortcuts, 240 sources deployment environments, 307 832 specifications deployment, 307 SQL adding application context to dynamic SQL, 32 SQL See Cognos SQL See native SQL SQL for inner joins, 606 SQL Server cannot be found, 590 cannot connect using OLE DB connection, 590 creating data source connections, 589 SQL Server 2005 error Metric Studio, 655 SSL additional steps to configure on WebLogic 8, 562 configuring for IBM Cognos 8 Go! Office, 344 starting IBM Cognos 8 components using URLs, 777 services, 108, 110 startup configuration lock file, 540 DB2 returns SQL1224N error when connecting from AIX, 558 download of resource fails, 557 IBM Cognos 8 service, 574 page not found, 560 problems, 549 Report Studio does not start, 563 script fails, 564 unable to download cognos.xts, 563 unable to open IBM Cognos Connection, 560 unable to start service, 551 Startup failure without error, 552 statistics access to system, 35 status snapshot of system, 35 status in Scorecard pane, 99 Status page in IBM Cognos Administration, 99 stopping services, 108 stored procedures unable to use IQD file, 610 unable to view, 601

Index streamlined deployment and administration enabling Report Studio authoring modes, 37 strings changing, 522 studios Essbase changes, 621 styles, 429, 437, 479 access permissions, 439 choosing in IBM Cognos Connection, 260 corporate, 481 creating, 438 customizing, 480 modifying, 440, 480 pages, 269 product default, 481 renaming, 480 user profiles, 437 windows, 479 wrong styles applied, 647 style sheets formatting, 482 modifying Cognos Viewer, 493 modifying prompt pages, 494 modifying Query Studio, 488 subtotals grouped lists, 621 summaries troubleshooting, 629 summary values unexpected when using nested sets, 625 support bundle Metric Studio, 654 suppressing null values, 162 suspend entries, 285 suspend entry run, 285 Sybase data source connection troubleshooting, 609 synchronizing metric users for Metric Studio, 396 standby Content Manager, 123 syntax errors, 604 system access to statistics, 35 performance, 91 snaphot of health, 35 system.xml files disabling reports as email attachments, 534 hiding user interface elements, 504 migrating from ReportNet, 501 setting up triggers for scheduling, 535 using to add custom actions, 511 using to add shortcut actions, 510 using to add user interface elements, 506 using to hide user interface elements, 503 using to remove actions, 510 System Administrators deploying, 313 system events, 544 system metrics output file, 543 resetting, 103 system perfomance assessment, 100 system service, 108

T
tab-delimited files errors, 657 Tab key problems in IBM Cognos Configuration, 572 table or view not found in dictionary, 636 tables database for log messages, 749 deleting from a database, 568 tabs adding, 273 deleting, 274 managing, 273 reordering, 275 target environments deployment, 307 target reports creating for drilling through from IBM Cognos Series 7, 426 task queue metrics, enabling, 153 tasks automating, 44 definition, 797 Metric Studio metrics, 391 performing in IBM Cognos 8 using URLs, 773 Administration and Security Guide 833

Index templates background colors not appearing, 621 changing the default for Query Studio, 525 custom report specifications, 495 definition, 797 Report Studio, 495 templates.xml file, 497 temporary directories deleting before reinstall, 570 testing calculations, 602 components, 544 deployment, 332 dispatchers, 117 installation examples, 545 query subjects, 603 text adding, 479 changing strings, 522 translating, 479 threshold setting, metric, 101 time dimensions creating in Transformer rather than Framework Manager, 610 timeouts, 133 data source connections, 184 specifying for Content Manager database connections, 121 times setting peak, 130 time zones setting, 260 TM1 data sources, 178 TM1 data sources differences, 624 differences in data tree, 624 TM1 Executive Viewer, 624 toolbars Query Studio button functionality, 490 tools diagnostic, 546 totals troubleshooting running totals, 642 TR0787 error Transformer, 612 transfering the passport ID as a URL parameter, 465 Transformer creating calculated columns, 611 rebuilding a PowerCube produces TR0787 error, 612 unable to open IQD file, 610 translation files problems importing into Map Manager, 651 transliterations of multilingual data, 703 traverse permissions, 213 trigger-based scheduling, 304 disabling, 535 trigger occurrences setting up triggers for scheduling, 535 troubleshooting Analysis Studio, 630, 631, 632 data retrieval from an SAP-based data source, 612 distributing reports, 627 logging, 79 logging messages, 80 Metric Designer, 653 Metric Studio, 653 Metric Studio log files, 653 missing categories in Transformer model, 612 report authoring, 619 resources, 539 SAP unbalanced hierarchy in Transformer, 612 summaries in reports, 629 troubleshooting data retrieval SAP data source in Transformer, 612 troubleshooting IBM Cognos 8 BI Analysis for Excel, 661 troubleshooting IBM Cognos 8 for Microsoft Office, 661 troubleshooting IBM Cognos 8 Go! Office, 661 troubleshooting Report Data Service, 661 trust domain error when saving the configuration, 571 trusted credentials, 218 creating, 218 scheduling, 218 tuning server performance, 127 type-in SQL, 603

834

Index

U
UDA-SQL-0031 errors, 645 UDA-SQL-0107, 603 UDA-SQL-0114, 603 UDA-SQL-0114 errors, 626, 633, 639 UDA-SQL-0129 errors, 645 UDA-SQL-0206 errors, 626 UDA-SQL-0564 errors, 639 UDA-TBL-0004 errors, 633 unable to access service at URL, 602 unable to open IBM Cognos Configuration, 540 unbalanced hierarchies DB2 OLAP, 165 Report Studio, 615 unexpected results crosstabs, 631 page breaks, 630 unhandled exceptions diagnosing, 542 unicode, 642 UNIX creating data source connections, 589 font not found error, 575 unregistering dispatchers, 111 namespaces, 202, 203 unsupported characters, 553 upcoming activities, 289 update request fails, 593, 594 updating groups and roles, 211 Upfront NewsBoxes adding to portals, 52 upgrading affect on Chinese, Japanese, or Korean characters, 566 content store, 557 models, 606 problems with cryptographic keys, 570 report specifications, 332 segmented models, 606 upgrading models key figures, 601 upgrading reports applications errors, 620 formatting not retained, 641 URI

report will not open, 633 unable to access service, 602 URLs accessing IBM Cognos Connection, 787 creating, 241 hiding user interface commands, 503 starting IBM Cognos 8 components, 777 using to hide user interface elements, 503 URLS accessing services using, 773 performing tasks in IBM Cognos 8, 773 url_xml, 773 URL validaton, 776 user credentials RDS-ERR-1020, 673 user interface improved for administrators, 35 user interface elements, 707 user interfaces adding elements, 714 customizing elements, 503 hiding elements, 707 hiding elements using the system.xml file, 504 hiding elements using URL commands, 503 showing elements, 506 user profiles default, 339 styles, 437 users, 207 anonymous, 233 anonymous logon, 239 authenticated, 233 built-in, 233 changing profiles, 341 classes and permissions, 214 definition, 797 deleting and recreating, 207 deleting profiles, 340 IBM Cognos Series 7, 207 locales, 208 profiles, 339 security, 207 System Administrators, 234 utilities round trip safety configuration, 686 Administration and Security Guide 835

Index

V
validation URL, 776 values as percentage, 631 vargraphic datatype, 603 versions deploying report output, 312 viewing older reports, 364 viewing reports, 348 viewing events, 544 viewing reports problems, 629, 641 SOAP response error when viewing from email link, 642 virtual private databases Oracle databases, 190, 194

W
watch items, 38 removing alert lists, 264 rule properties, 250 viewing in IBM Cognos Connection, 264 watch list output retention, 138 watch lists definition, 797 watch rule definition, 797 watch rules, 38, 366 creating, 367 deleting in Cognos Viewer, 368 enabling, 367 modifying in Cognos Viewer, 368 viewing in IBM Cognos Connection, 264 Web configuring browsers, 50 web.config file configuring Cognos Web parts, 458 web.config.sample, 458 Web browsers errors in starting the Web portal, 563 errors when starting the web portal, 560 unable to access help, 547

WebLogic could not deserialize context attribute, 565 deploying p2pd.war file, 566 servlet class fails to load, 579 startup script fails, 564 WebLogic 8 problem configuring SSL, 562 WebLogic Application Server IBM Cognos 8 fails, 564 Web parts IBM Cognos, 454 See Also portlets Web services description language importing portlets into IBM Cognos Connection, 432 Web Services for Remote Portlets importing portlets into IBM Cognos Connection, 432 Web Services for Remote Portlets, See WSRP WebSphere parser collisions with Report Data Service, 670 WebSphere Application Server deploying IBM Cognos 8, 577 IBM Cognos 8 deployment failure, 564 startup script fails, 564 WebSphere Portal customizing Cognos portlets, 444 deploying Cognos portlets, 441 installing portlet applications file, 442 Welcome page customizing, 484, 514 Windows Event Viewer, 539, 544 Windows IIS recommended gateway settings, 579 windows style, 479 write permissions, 213 WSRP definition, 797 WSRP standard portlets, 432

X
XML data sources, 179 XML formatting reports, 358

836