User Guide - Cognos Transformer
User Guide - Cognos Transformer
User Guide - Cognos Transformer
Note Before using this information and the product it supports, read the information in Notices on page 139.
Product Information
This document applies to IBM Cognos Business Intelligence Version 10.2.1 and may also apply to subsequent releases. Licensed Materials - Property of IBM Copyright IBM Corporation 2005, 2013. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii Chapter 1. What's New? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Deprecated Features in Version 10.2.0 . . . . . . . . . . . . . . . . . . . The Migration Assistant command line tools. . . . . . . . . . . . . . . . Open with Report Studio and Open with Analysis Studio actions. . . . . . . . . New Features in Version 10.1.1 . . . . . . . . . . . . . . . . . . . . . Export to Microsoft Excel 2007 Open XML Format . . . . . . . . . . . . . . Support for Migration from IBM Cognos Series 7 version 5 to IBM Cognos 10.1.1 . . . Changed Features in Version 10.1.1 . . . . . . . . . . . . . . . . . . . . Improved zero suppression migration to Report Studio . . . . . . . . . . . . New Features in Version 10.1.0 . . . . . . . . . . . . . . . . . . . . . IBM Cognos Business Insight . . . . . . . . . . . . . . . . . . . . . Support for Migration from IBM Cognos Series 7 Version 4 MR4 to IBM Cognos Business New Migration Options . . . . . . . . . . . . . . . . . . . . . . Support for Migrating Content from Multiple IBM Cognos Series 7 Servers . . . . . Perform Tasks in IBM Cognos PowerPlay Using URLs . . . . . . . . . . . . Change Settings for Content in My Folders for a Specific User. . . . . . . . . . Changed Features in Version 10.1.0 . . . . . . . . . . . . . . . . . . . . Support for Additional Types of Packages . . . . . . . . . . . . . . . . Increased Performance When Migrating Content . . . . . . . . . . . . . . More Detailed Migration Summary Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Intelligence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.1.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1 1 1 1 2 2 2 2 2 2 2 3 3 3 3 3 4 4
Chapter 2. What is IBM Cognos PowerPlay? . . . . . . . . . . . . . . . . . . . . 5 Chapter 3. What is Different in IBM Cognos PowerPlay? . . . . . . . . . . . . . . . 7
Architecture . . . . . . . . . . . . . . . . . . . Web Portals. . . . . . . . . . . . . . . . . . . . Data Sources . . . . . . . . . . . . . . . . . . . Security . . . . . . . . . . . . . . . . . . . . Request Flow . . . . . . . . . . . . . . . . . . . The Migration Service . . . . . . . . . . . . . . . . PowerPlay Studio . . . . . . . . . . . . . . . . . PowerPlay Client . . . . . . . . . . . . . . . . . Installation and Configuration . . . . . . . . . . . . . PowerPlay Administration . . . . . . . . . . . . . . Server Properties . . . . . . . . . . . . . . . . Folder Properties . . . . . . . . . . . . . . . . Cube and Report Properties . . . . . . . . . . . . . Drill-Through Access . . . . . . . . . . . . . . . . Understanding Drill-through Access in IBM Cognos BI . . . . Example - Drill Through Between OLAP and Relational Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 . 9 . 10 . 10 . 11 . 11 . 12 . 14 . 16 . 17 . 18 . 20 . 21 . 22 . 22 . 24
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
29 29 29 30 30 32 33 34 35 36
iii
Customize the Toolbar. Cube Settings. . . . Report Settings . . . Customize the Appearance
. . . of
. . . . . . . . . . . . IBM Cognos
. . . . . . BI .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
39 40 46 49
Chapter 5. Migrating from IBM Cognos Series 7 PowerPlay to IBM Cognos PowerPlay
Why Migrate IBM Cognos Series 7 PowerPlay Content to IBM Cognos PowerPlay? . . . Using PowerPlay Assets in IBM Cognos BI . . . . . . . . . . . . . . . . Migration Approach . . . . . . . . . . . . . . . . . . . . . . . Moving to IBM Cognos PowerPlay . . . . . . . . . . . . . . . . . . . What Gets Migrated and to Where Does it Migrate? . . . . . . . . . . . . . . Before You Migrate . . . . . . . . . . . . . . . . . . . . . . . . . Define Aliases for Your IBM Cognos Series 7 Servers . . . . . . . . . . . . Migrate Content to IBM Cognos PowerPlay . . . . . . . . . . . . . . . . Create a Migration Task . . . . . . . . . . . . . . . . . . . . . . Specify the Migration Source . . . . . . . . . . . . . . . . . . . . Select the Migration Options. . . . . . . . . . . . . . . . . . . . . Select the Content to Migrate . . . . . . . . . . . . . . . . . . . . Start the Migration . . . . . . . . . . . . . . . . . . . . . . . . Recommendation - Keep Cubes and Reports in Your Source Environment Until Migration Migrating Local Reports to IBM Cognos BI . . . . . . . . . . . . . . . . . Convert PPR Files to PPX Files for Migration . . . . . . . . . . . . . . . Migrate Local Reports to IBM Cognos BI . . . . . . . . . . . . . . . . Using the Bookmark Conversion Utility in IBM Cognos PowerPlay. . . . . . . . . Run the Bookmark Conversion Utility as an Application . . . . . . . . . . . Run the Bookmark Conversion Utility as a Server . . . . . . . . . . . . . Manually Create a Conversion Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . Is . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Complete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
51
51 52 52 53 54 58 60 61 62 63 63 65 66 67 67 67 68 69 69 71 73
iv
Migration Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Content That Cannot be Migrated . . . . . . . . . . . . . . . . . . . . . . . . . Cube Mapping Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Name of Folder Created for Migrated Content Is not in the Correct Language . . . . . . . . . . . Unable to Migrate Content Because Locale not Configured or Mapped in IBM Cognos Configuration . . . IBM Cognos Series 7 Migration Service Memory Allocation . . . . . . . . . . . . . . . . . Drill Through Properties May Need to Be Altered After Migration. . . . . . . . . . . . . . . Error When Migrating from Upfront. . . . . . . . . . . . . . . . . . . . . . . . . Cannot Migrate Upfront Content if PowerPlay Enterprise Server Is not Secured . . . . . . . . . . Cannot Connect to Upfront Server During Migration if Upfront is Secured for Single Signon or OS Signon . Personal NewsBoxes Don't Appear in the Tree View of Upfront in the IBM Cognos Migration Assistant . . Problems Migrating Reports with Internal Path Names Exceeding 255 Characters . . . . . . . . . History Details Do Not Appear for Migration Job . . . . . . . . . . . . . . . . . . . . Upfront Contact Information not Migrated . . . . . . . . . . . . . . . . . . . . . . Apostrophe in Folder Name not Migrated . . . . . . . . . . . . . . . . . . . . . . . Empty Folder Named "cubes" Created After Migrating from IBM Cognos Connection . . . . . . . . Starting the Series 7 Migration Service Returns an Error . . . . . . . . . . . . . . . . . . Custom View Migrated a Second Time Appears as a Broken Link . . . . . . . . . . . . . . . Error Message not Clear when Migrating Upfront Content from a Series 7 Distributed Installation Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unable to Migrate Reports on UNIX when Path Names Contain Certain European Characters . . . . . Ranking Applied to an Axis having a Custom Subset and One or More Categories not Migrated to Analysis Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Migrating a Report with a Single Measure on X or Y Axis Does not Run in Report Studio . . . . . . . Folders in Upfront Personal NewsBox not Migrated . . . . . . . . . . . . . . . . . . . Bookmark Migration Produces URLs That Are Not Valid . . . . . . . . . . . . . . . . . . PDF Output of Migrated Report Does Not Display Correctly . . . . . . . . . . . . . . . . Inherited Lightweight PDF Generation Setting not Migrated . . . . . . . . . . . . . . . . . Problems Working in IBM Cognos PowerPlay Administration . . . . . . . . . . . . . . . . . PowerPlay Requests Do Not Appear in System Status or Activities Lists. . . . . . . . . . . . . Some PowerPlay Activity Is Not Logged . . . . . . . . . . . . . . . . . . . . . . . Connection Error When PowerCube File Name Includes Simplified Chinese Characters . . . . . . . Problems Working in IBM Cognos PowerPlay Studio . . . . . . . . . . . . . . . . . . . . Error After Inserting a Calculation in PowerPlay Studio . . . . . . . . . . . . . . . . . . Error When Opening the Link in the Email for a Scheduled Report . . . . . . . . . . . . . . Page Error When Editing a Chart Title in Japanese . . . . . . . . . . . . . . . . . . . . Long Strings Are Truncated . . . . . . . . . . . . . . . . . . . . . . . . . . . Hebrew Text Displayed in Charts. . . . . . . . . . . . . . . . . . . . . . . . . . After Exporting to PDF the Label for the OTHER Category in a Pie Chart Changes to Actual Category Name Unreadable or Inaccessible Display . . . . . . . . . . . . . . . . . . . . . . . . . Delimiter Used for Export to CSV Different from IBM Cognos Series 7 . . . . . . . . . . . . . Cognos Application Firewall Error When Saving a PowerPlay Studio Report . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
107 108 109 109 110 111 111 112 112 112 112 113 114 114 114 114 114 115
. 115 . 115 . . . . . . . . . . . . . . . . 116 116 117 117 117 118 119 119 119 119 120 120 120 120 120 120 120 . 120 . 121 . 121
Characters not Migrated Correctly when Using a Different Migration Source . . . . . . . Problems Migrating Cubes with non-ASCII Characters on UNIX . . . . . . . . . . . Unable to Migrate Because Content Manager Reports Object with Same Name Already Exists .
. . .
. . .
. . .
. . .
vi
Introduction
This document is intended for use with IBM Cognos PowerPlay.
Audience
To use this document effectively, you should be familiar with IBM Cognos Series 7 PowerPlay administration, your information technology and security infrastructure, and database and reporting concepts.
Finding information
To find IBM Cognos product documentation on the web, including all translated documentation, access one of the IBM Cognos Information Centers (http://pic.dhe.ibm.com/infocenter/cogic/v1r0m0/index.jsp). Release Notes are published directly to Information Centers, and include links to the latest technotes and APARs. You can also read PDF versions of the product release notes and installation guides directly from IBM Cognos product disks.
Accessibility features
This product does not currently support accessibility features that help users with a physical disability, such as restricted mobility or limited vision, to use this product.
Forward-looking statements
This documentation describes the current functionality of the product. References to items that are not currently available may be included. No implication of any future availability should be inferred. Any such references are not a commitment, promise, or legal obligation to deliver any material, code, or functionality. The development, release, and timing of features or functionality remain at the sole discretion of IBM.
Samples disclaimer
The Sample Outdoors Company, Great Outdoors Company, GO Sales, any variation of the Sample Outdoors or Great Outdoors names, and Planning Sample depict fictitious business operations with sample data used to develop sample
Copyright IBM Corp. 2005, 2013
vii
applications for IBM and IBM customers. These fictitious records include sample data for sales transactions, product distribution, finance, and human resources. Any resemblance to actual names, addresses, contact numbers, or transaction values is coincidental. Other sample files may contain fictional data manually or machine generated, factual data compiled from academic or public sources, or data used with permission of the copyright holder, for use as sample data to develop sample applications. Product names referenced may be the trademarks of their respective owners. Unauthorized duplication is prohibited.
viii
Open with Report Studio and Open with Analysis Studio actions
The options to open a PowerPlay report in IBM Cognos Report Studio or IBM Cognos Analysis Studio are not available in the IBM Cognos Business Intelligence 10.2.0 release.
Higher as a target format. Selecting this option will result in Open XML (.xlsx) files being created which are native to Microsoft Excel 2007.
Support for Migration from IBM Cognos Series 7 version 5 to IBM Cognos 10.1.1
This version of the IBM Cognos Migration Assistant supports migration from IBM Cognos Series 7 version 5 to IBM Cognos Business Intelligence 10.1.1.
Support for Migration from IBM Cognos Series 7 Version 4 MR4 to IBM Cognos Business Intelligence 10.1.0
This version of the IBM Cognos Migration Assistant supports migration from IBM Cognos Series 7 version 4 MR4 to IBM Cognos Business Intelligence 10.1.0.
Related tasks: Migrate Content to IBM Cognos PowerPlay on page 61 Using the IBM Cognos Migration Assistant, you can migrate IBM Cognos Series 7 PowerPlay content that has been published to IBM Cognos Connection or IBM Cognos Series 7 Upfront, or content from IBM Cognos Series 7 PowerPlay Enterprise Server.
Support for Migrating Content from Multiple IBM Cognos Series 7 Servers
You can now migrate content from multiple IBM Cognos Series 7 servers. For best results, define server aliases to avoid name collisions when migrating content that has the same name or folder structure. Related tasks: Define Aliases for Your IBM Cognos Series 7 Servers on page 60 Define aliases for your IBM Cognos Series 7 servers to more easily identify the sources from which you are migrating. By defining aliases, you can avoid name collisions when you migrate content from multiple Series 7 servers that has the same name or folder structure in a single migration.
Architecture
IBM Cognos Business Intelligence has a multitiered architecture. For description purposes, it can be separated into three tiers: web server, applications, and data. The tiers are based on business function, and are typically separated by network firewalls. IBM Cognos BI user interfaces, such as PowerPlay Studio, sit above the tiers.
For more information about the architecture, see the IBM Cognos BI Architecture and Deployment Guide.
Content Store
Content Manager stores information in a content store database, which is typically located in the data tier of the IBM Cognos BI architecture. The content store is a relational database where IBM Cognos BI content, connection information for data sources including IBM Cognos PowerCubes, and user capabilities are maintained.
Web Portals
The IBM Cognos Business Intelligence web portal is IBM Cognos Connection. IBM Cognos Connection replaces Upfront and the PowerPlay Web Table of Contents as the portal for accessing PowerPlay reports.
In addition to being the portal for published reports, IBM Cognos Connection provides access to packages used to build new reports, other IBM Cognos BI studios, and IBM Cognos Administration, which allows administrators to set configuration options for your IBM Cognos BI servers and set cube and report properties for your PowerPlay content. IBM Cognos Administration also allows you to run the IBM Cognos Migration Assistant to move your IBM Cognos Series 7 PowerPlay content to IBM Cognos PowerPlay.
Data Sources
In IBM Cognos Business Intelligence, PowerCubes are the supported data source for IBM Cognos PowerPlay Studio and PowerPlay Client. Like other IBM Cognos BI studios, PowerPlay Studio accesses a data source through a package. PowerPlay Client can open local PowerCubes directly, or access remote PowerCubes by connecting to a package. Administrators create and manage data source entries by defining connections to specific data sources, using IBM Cognos Administration. When an administrator creates a data source entry using a connection to a PowerCube they have the option to create a package at the same time. Optionally, a modeler can use the IBM Cognos BI metadata modeling tool, Framework Manager, build a model and then create a package. A modeler can combine different data sources in a package. PowerPlay Studio and PowerPlay Client support packages based on one PowerCube data source, or mixed data source packages that are based on one PowerCube data source and other types of data sources such as a relational data source. IBM Cognos PowerPlay Studio and IBM Cognos PowerPlay Client do not support packages built from only relational data sources or OLAP data sources other than PowerCubes. Typically, a data source entry uses only one data source connection. An administrator can define a data source entry that includes more than one data source connection. For example, the administrator creates a new data source entry called GO Sales. The administrator adds two data source connections to GO Sales, one to GO_Sales_East. mdc and one to GO_Sales_West.mdc and creates a package from GO Sales. When a PowerPlay Studio user or PowerPlay Client user opens the GO Sales package, they are prompted to select either GO_Sales_West or GO_Sales_East. You can use PowerCubes created in either IBM Cognos Series 7 or IBM Cognos BI Transformer. Some IBM Cognos Series 7 PowerCube features are not supported in IBM Cognos BI PowerPlay. For example, compressed PowerCubes are not a supported data source in IBM Cognos BI.
Security
In IBM Cognos Series 7, administrators assign a user to user classes from a namespace as part of the security infrastructure. The user class determines the user's view of the cube data. IBM Cognos Business Intelligence security is different than IBM Cognos Series 7. IBM Cognos BI administrators assign capabilities to users, groups, and roles to allow them to perform actions, such as read or write, on content store objects, such as folders and reports. The user information, such as user names and passwords, is maintained using your authentication provider, and IBM Cognos BI administrators
10
assign the users and groups in your namespace to roles in the IBM Cognos BI namespace. For more information about security, see the IBM Cognos BI Administration and Security Guide. IBM Cognos BI security also allows you to use more than one namespace for your security. When users log in, they are prompted to choose a namespace. A users capabilities may be different for each namespace. IBM Cognos BI can use your existing IBM Cognos Series 7 namespace, however, you will need to continue using IBM Cognos Series 7 Access Manager to administer the namespace. Security information in your PowerPlay content will be maintained when you migrate to IBM Cognos BI. Only users and user classes referenced in NewsBoxes and NewsItems being migrated are migrated. Password protected cubes will remain password protected. If you use user class security in your cubes, the security is maintained and you must continue to use your IBM Cognos Series 7 namespace in your IBM Cognos BI environment. Note that migrating security information is optional when you migrate to IBM Cognos BI. In IBM Cognos PowerPlay, you cannot access a cube password that is stored in IBM Cognos Series 7 Access Manager. An administrator must add the cube password to the data source signon when they create the data source connection in IBM Cognos Administration. Also, you cannot open local cubes that are secured against a namespace using IBM Cognos PowerPlay Client. As an alternative, you can use password protected local cubes.
Request Flow
In IBM Cognos Series 7, incoming requests are sent from the gateway to the PowerPlay server and from the PowerPlay server to a query processor. In the default configuration, the query processor sends the response directly to the gateway, bypassing the PowerPlay server. To do this, the gateway listens for connections on a server socket and the query processor opens a socket connection back to the gateway. This requires open outbound ports in firewalls between the web tier and the Application Tier Components. In IBM Cognos Business Intelligence, responses always travel back through the same socket connections that the request arrived on. This is the same as enabling the restrict outgoing port configuration option in IBM Cognos Series 7.
11
migrate your content from IBM Cognos Series 7 PowerPlay Enterprise Server. The IBM Cognos Series 7 service is not required if you are migrating PowerPlay reports published to IBM Cognos Connection to Report Studio or Analysis Studio. The IBM Cognos Series 7 Migration service is started from the Microsoft Windows Services manager or on UNIX operating system using the command ./configure.sh --start. The IBM Cognos BI migration service is run by the IBM Cognos BI dispatcher and is automatically started when you start the IBM Cognos BI service.
PowerPlay Studio
IBM Cognos PowerPlay Studio lets you view, explore, and distribute PowerPlay reports using your web browser, just as you did with IBM Cognos Series 7 PowerPlay Web. You access PowerPlay Studio from IBM Cognos Connection, the IBM Cognos Business Intelligence portal. When you open PowerPlay Studio it replaces IBM Cognos Connection in your web browser. This behavior is similar to opening a PowerPlay report from Upfront in IBM Cognos Series 7. You can not configure PowerPlay Studio to open in a new window. While the user experience should be very familiar to PowerPlay Web users, there are some differences in PowerPlay Studio.
12
Event Studio integration for PowerPlay reports does not support reports created using packages that use more than one PowerCube data source connection, or reports created using a password-protected PowerCube data source. For PowerPlay reports that use a secured package, you must log on with the appropriate credentials before starting Event Studio or running Event Studio agents.
Drill Through
IBM Cognos BI includes a drill-through service that is used by all IBM Cognos BI studios. When you click the drill-through button in PowerPlay Studio v if only one drill-through target is available, the target report or package opens v if more than one drill-through target available, you are presented with a list of drill-through targets to choose from. In both IBM Cognos Series 7 and IBM Cognos BI, a modeler can define drill through in a cube using Transformer, with any additional settings configured in the administration tool. Also, if you migrate your IBM Cognos Series 7 content to IBM Cognos BI, any drill through settings you have defined in PowerPlay Enterprise Server for the cubes or reports will be migrated to IBM Cognos BI. In IBM Cognos BI you can create package-based drill through definitions from the Launch menu in IBM Cognos Connection. Using this type of drill through, you do not have to rebuild the cube to add or change drill through targets.
Error Handling
When errors occur in IBM Cognos BI, a dialog box appears which includes a Details button and a detailed trace. Detail information and tracing is available for IBM Cognos PowerPlay errors.
13
PowerPlay Client
IBM Cognos PowerPlay lets you view, explore, format, and distribute PowerPlay reports, just as you did with IBM Cognos Series 7 PowerPlay. The following information describes the differences in PowerPlay between IBM Cognos Business Intelligence and IBM Cognos Series 7.
14
15
IBM Cognos PowerPlay does not support the .wmf graphic type. If you use .wmf graphics in IBM Cognos Series 7, convert them to a supported format for use in IBM Cognos BI: .bmp, .gif, .jpg, or .png.
Multilingual Installation
In IBM Cognos BI, the server components are multilingual and the installed product is provided in all supported languages. This allows users to change the language in the IBM Cognos BI portal. IBM Cognos PowerPlay Client installs only one language, and users are prompted to select a language when they install.
16
CGI Configurations
In IBM Cognos Series 7 version 4, administrators can change settings for the temporary file access method using the following property in the IBM Cognos Series 7 Configuration Manager: PowerPlay Enterprise Server.Gateway.General.Temporary File Access The property can be set to one of three modes, Shared, CGI, and Fetch/Dispatcher. IBM Cognos BI does not include the an equivalent configuration option for PowerPlay. The behavior in IBM Cognos BI is comparable to Fetch/Dispatcher mode, which is more secure than the Shared mode.
PowerPlay Administration
In IBM Cognos Series 7, administrators use PowerPlay Enterprise Server Administration to specify runtime settings. In IBM Cognos Business Intelligence, administrators manage runtime settings, including PowerPlay settings, in IBM Cognos Administration. IBM Cognos Administration provides administrators with convenient access to all runtime settings from the same location. Many IBM Cognos BI settings for PowerPlay will be familiar to administrators of IBM Cognos Series 7 PowerPlay. For example, the generic and enhanced interface options are available. Also, you can also choose the toolbar buttons that are visible to users and the IBM Cognos Series 7 drill through targets that are available.
Load Balancing
In IBM Cognos Series 7 PowerPlay Enterprise Server, you can add mirror references to distribute the processing load. In IBM Cognos BI, you can specify routing rules to direct requests to dispatchers in identified server groups. Routing rules can be defined by package, user group, or user role. In IBM Cognos BI if your installation includes more than one dispatcher, you can specify the proportion of requests that each dispatcher handles by changing its processing capacity. You can also configure the number of client connections to balance your server load.
17
Organizing Content
In PowerPlay Enterprise Server, you organize and administer groups of cubes and reports by using folders and collections. Folders and collections allow you to change the settings of all the descendant objects from a single dialog box. IBM Cognos BI uses folders and packages in the Public Folders, My Folders, or in My Pages to organize content. You can override the settings inherited from a parent object. IBM Cognos BI does not use Collections.
Print Settings
In IBM Cognos Series 7, users can print PowerPlay Web Explorer reports by exporting the report to a PDF and then printing the PDF. The settings for the exported PDF are determined by the settings applied to the Print Settings report at the root of the Table of Contents hierarchy in PowerPlay Enterprise - Server Administration. For example, if you set the page orientation of the Print Settings report to landscape, each report that is exported to PDF will use a landscape orientation. In IBM Cognos Power Play, you configure print settings from the PowerPlay tab in IBM Cognos Administration.
Server Properties
The following information describes server properties from IBM Cognos Series 7 PowerPlay Enterprise Server Administration that either do not have an equivalent setting or are managed differently in IBM Cognos Business Intelligence. The following server properties from the Options group on the Settings tab do not have an equivalent setting in IBM Cognos BI. v Resource (/ppwb) location v Imported reports folder v Security dialog box v v Administrator email address Selection of preferences
18
v v v
The following server properties from the Options group on the Settings tab are managed differently in IBM Cognos BI.
Table 1. Server properties: Options group PowerPlay Enterprise Server Administration Temporary files location IBM Cognos BI Configured in IBM Cognos Configuration in the Environment group of properties. Logging levels are configured in IBM Cognos Administration, but PowerPlay auditing can also be used. You configures the number of high and low affinity connections for the PowerPlay service with an advanced setting for the PowerPlay service. You configures the queue time limit of the PowerPlay service with an advanced setting for the PowerPlay service. IBM Cognos BI groups and roles are used for authentication and authorization. IBM Cognos BI groups and roles are used for authentication and authorization. Advanced setting for the PowerPlay service.
Auditing level
The Location for audit files server property from the Audit Log Generator group on the Settings tab does not have an equivalent setting in IBM Cognos BI. IBM Cognos BI uses a combination of IBM Cognos BI and IBM Cognos Series 7 PowerPlay logging. The following server properties from the Audit Log Generator and PowerPlay Web Viewer groups on the Settings tab are managed differently in IBM Cognos BI.
Table 2. Server properties: Audit Log Generator and PowerPlay Web Viewer groups PowerPlay Enterprise Server Administration Maximum size of each file in kiloBytes (kB) Temporary file deletion interval (days) IBM Cognos BI Advanced setting for the PowerPlay service. Advanced setting for the PowerPlay service.
The following server properties from the Publishing group on the Settings tab are managed differently in IBM Cognos BI.
Chapter 3. What is Different in IBM Cognos PowerPlay?
19
Table 3. Server properties: Publishing group PowerPlay Enterprise Server Administration Default portal IBM Cognos ReportNet/IBM Cognos 8 Gateway URI IBM Cognos ReportNet/IBM Cognos 8 Dispatcher URI IBM Cognos BI IBM Cognos Connection is the IBM Cognos BI portal. Configured in IBM Cognos Configuration under the Environment group of properties. Configured in IBM Cognos Configuration under the Environment group of properties.
Related concepts: Chapter 7, Setting Up Logging, on page 81 IBM Cognos Business Intelligence log messages provide information about the status of components, including PowerPlay activity, and a high-level view of important events. Related tasks: Configure Advanced Settings on page 32 You configure advanced settings for the IBM Cognos PowerPlay service in IBM Cognos Administration.
Folder Properties
Folders in IBM Cognos Series 7 and IBM Cognos Business Intelligence are used to organize and administer related objects in a hierarchy. The following information describes Folder Properties from IBM Cognos Series 7 PowerPlay Enterprise Server Administration that either do not have an equivalent setting or are managed differently in IBM Cognos BI. The Mount at and Parent properties on the General tab do not have an equivalent setting in IBM Cognos BI. All IBM Cognos BI application data is stored in the content store and managed by the Content Manager service. The following properties on the General tab are managed differently in IBM Cognos BI.
Table 4. Folder properties: General tab PowerPlay Enterprise Server Administration Name and Description IBM Cognos BI Appear in the properties of the IBM Cognos BI package or the report in IBM Cognos Connection Stored in the content store. IBM Cognos BI uses routing rules, processing capacity for dispatchers, and affinity connection settings for load balancing. For more information, see the Administration and Security Guide.
The following properties on the Settings tab do not have an equivalent setting in IBM Cognos BI. v Sharing v Upfront Server Group
20
v v v
Upfront Publish Template Upfront NewsBox for Cubes Upfront NewsBox for Reports
The following properties on the Settings tab are managed differently in IBM Cognos BI. v v Cognos ReportNet/Cognos BI folder for cubes Cognos ReportNet/Cognos BI folder for reports
When you create a package from a PowerCube data source and then publish the package or when you publish a report to IBM Cognos Connection you specify the folder where the package or report is published.
Description
Mirror references
The following properties on the Settings tab of Report Properties do not have an equivalent setting in IBM Cognos BI.
Table 6. Report properties: Settings tab PowerPlay Enterprise Server Administration Sharing Page by page report serving Explore in Windows format IBM Cognos BI Reports are stored in the content store. IBM Cognos BI always uses byte-serving. IBM Cognos PowerPlay Client users can open remote reports.
Chapter 3. What is Different in IBM Cognos PowerPlay?
21
The Publishing properties on the Settings tab do not have equivalent settings in IBM Cognos BI.
Drill-Through Access
Drill-through access in IBM Cognos Business Intelligence is different from IBM Cognos Series 7. Related tasks: Enable Drill Through on page 36 You can control the drill through options to both IBM Cognos Business Intelligence and IBM Cognos Series 7 content.
22
v between reports created in different packages against different data source types, such as from an analysis against a cube to a detailed report against a relational data source v from one existing report to another report using Report Studio v between Cognos Viewer reports authored in Report Studio, Query Studio, PowerPlay Studio, and Analysis Studio v from IBM Cognos PowerPlay Web cubes to IBM Cognos BI reports v from Metric Studio to other IBM Cognos BI reports by passing parameters using URLs. For more information, see the Metric Studio User Guide.
23
In IBM Cognos Series 7, the drill-through icon is disabled if no drill-through definitions are available. In IBM Cognos BI, the drill-through icon is enabled, unless drill-through access has been disabled by the administrator or owner of the target object. v debugging drill-through access In IBM Cognos Series 7, the drill-through assistant helped administrators and drill-through authors create valid targets from PowerPlay to IBM Cognos ReportNet or IBM Cognos BI reports. In IBM Cognos BI, a drill-through assistant is not needed to define the target report. However, you can use a debugging feature to obtain information about values being passed and about information mapped between source and target. The IBM Cognos BI administrator can set permissions for this feature.
Drill-through Definitions
Drill-through definitions may exist in a source package, in the source Report Studio report, or in a PowerCube that was migrated from IBM Cognos Series 7. You should consider using IBM Cognos BI for any new drill-through applications, to be able to use parameterized drill-through access for more control, create drill-through definitions that do not require building PowerCubes, and so on. Drill-through definitions in the PowerCube are managed in the PowerPlay tab in IBM Cognos Administration. For more information, see the IBM Cognos PowerPlay Migration and Administration Guide and the IBM Cognos Transformer User Guide. If the drill-through link was defined in IBM Cognos BI, a drill-through definition must be associated with the source report or package, and may have parameters mapped from source to target (parameterized drill-through). A Report Studio author can create a drill-through definition in a report. An IBM Cognos BI user can create a drill-through definition in a package in IBM Cognos Connection (Launch, Drill-through Definitions), that will be available to any reports in the package. You define parameters in the target report when you want to control how the target item is filtered. When a parameter mapping exists in the drill-through definition, then the data item value is not used for mapping. For example, if a value exists in both Product Line and Product Line Type, then you might map the metadata Product Line in the source to a parameter that you create in the target. Also, the scope can be set so that the target reports only appear at predefined points. For more information, see the Report Studio User Guide or the IBM Cognos BI Administration and Security Guide.
24
dynamic drill through. This means that when the drill-through link is made, IBM Cognos Business Intelligence matches names of items in the context of the source to available items in the target. For more information and examples, see the IBM Cognos Business Intelligence Administration and Security Guide. You must have the IBM Cognos BI samples from the deployment zip file IBM_Cognos_DrillThroughSamples installed to follow this exercise. To check the target report, you should have access to Report Studio. Note: You can set up drill-through definitions without checking the target reports. However, if you set up drill-through access between packages or between objects created in different authoring tools, you should be aware of how the metadata will be matched. The following figure shows the target report with data for the context of the source, which is the Promotion Plan Revenues for various promotions.
25
Procedure
1. Open the target report, Total Revenue by Country or Region: v Go to IBM Cognos Connection. v From Public Folders, navigate to the package GO Data Warehouse (query), and then open the folder Report Studio Report Samples. v Select the report Total Revenue by Country or Region, and open it in Report Studio. 2. Confirm the names of the data items that will be used for filtering context from the source: v In the Page Explorer, select the report item. v In the Properties pane, check the Data Item property Name.
26
3. 4.
5. 6.
v Note the items named Region, Retailer country or region, and Product line. Close the target report. Open the source report, Profit Margin and Revenue by Country or Region: v Go to IBM Cognos Connection. v From Public Folders, open the package Sales and Marketing (cube), and then open the folder PowerPlay Studio Report Samples. v Select the Profit Margin and Revenue by Country or Region report, and open it in PowerPlay Studio. Review the data in the report. (For example, right-click a retailer name and select Explain to look at the structure of the data.) Keep the Profit Margin and Revenue by Country or Region report open for testing.
7. In IBM Cognos Connection, navigate to the Sales and Marketing (cube) package. 8. Click Launch, Drill-through Definitions. 9. Click New Drill-through Definition. Tip: If you do not see the New Drill-through Definition button, check that you are at the root of the folder, and not still in the PowerPlay Studio Report Samples folder. 10. In the Drill-through Definition wizard, type a name, such as Drill Through to Total Revenue by Country or Region, and a description, 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. 11. Click Set the target, Select a report... and in the screen that appears, set the target report to Total Revenue by Country or Region, in the Report Studio Report Samples folder of the GO Data Warehouse (query) package, and then click OK. 12. Click Set the scope, and in the screen that appears, set the scope to [sales_and_marketing].[Retailers].[Retailers].[Retailer country or region], and then click OK. 13. Click Next. In the Action field, select Run with dynamic filter. 14. Leave all other settings at the default values and click Finish. 15. Go to the Profit Margin and Revenue by Country or Region report, and click the drill-through icon. v If the drill-through definition you created is the only drill-through target available, the target reports runs. v If more than one drill-through target is available, a list of possible targets for the package and the data that is in scope appears. Click the drill-through definition that you created, and the target runs using the context you selected.
Results
Report users in PowerPlay Studio can drill through from the Profit Margin and Revenue by Country or Region report to the target report that you have defined (Total Revenue by Country or Region for Product Line). Also, the target report is
27
available as a drill-through target for any existing or new report based on the Sales and Marketing (cube) package, whenever Retailer Country or Region is part of the scope. The drill-through definition that you create should be identical to the sample drill-through definition Dynamicdrill in the Sales and Marketing (cube) package.
28
Procedure
1. Connect to the IBM Cognos BI portal. 2. Start IBM Cognos Administration: v In the Welcome page, click Administer IBM Cognos Content. v In IBM Cognos Connection, from the toolbar, click Launch, IBM Cognos Administration. 3. Click the PowerPlay tab.
29
These users or groups must have Execute and Traverse permissions on the following capabilities: v Users, Groups, and Roles v Data Source Connections v Administration Tasks
Procedure
1. 2. 3. 4. In IBM Cognos Administration, on the Security tab, click Capabilities. Click Administration. Click the arrow next to Users, Groups, and Roles, and click Set Properties. In the Set Properties dialog box, click the Permissions tab.
The users or groups with assigned capabilities are shown. Users must have Execute and Traverse permissions to be able to migrate content. 5. Click Add, to add users or groups. You may have to select Override the access permissions acquired from the parent entry to allow you to add new users and change permissions. For more information, click Help or see the Administration and Security Guide. 6. For each user or group you want to add, select Execute and Traverse permissions, and then click Apply. 7. Click OK to return to the list of capabilities. 8. Click the arrow next to Data Source Connections, click Set Properties, and repeat steps 5 - 7 above. 9. Click the arrow next to Administration Tasks, click Set Properties, and repeat steps 5 - 7 above. Related tasks: Migrate Content to IBM Cognos PowerPlay on page 61 Using the IBM Cognos Migration Assistant, you can migrate IBM Cognos Series 7 PowerPlay content that has been published to IBM Cognos Connection or IBM Cognos Series 7 Upfront, or content from IBM Cognos Series 7 PowerPlay Enterprise Server.
Recommendation - Create Groups or Roles to Assign Capabilities Rather Than Using Individual Users
If you need to enable several users to be able to run migration tasks, you can create a group in the IBM Cognos namespace and assign the appropriate capabilities to that group. For example, create a group called Migration Operators and then add individual users from your corporate namespace to the group. For more information about adding groups to the IBM Cognos namespace, see the Security Administration section of the Administration and Security Guide.
30
Table 7. Advanced settings for the PowerPlay service IBM Cognos Series 7 feature Maximum Restrict Client Connections Specifies the maximum number of connections available for remote clients. Restrict Connection Idle Timeout (min) Sets the number of minutes before an idle remote connection is ended. PowerPlay Web Viewer - Temporary File deletion interval (days) IBM Cognos BI advanced setting (parameter and value) SRV.Options. MaxRestrictClientConnections An example value is IN,50
SRV.PWR.TempFileDeletionTime An example value is IN,30 SRV.PWQ.TempFileDeletionTime An example value is IN,900 SRV.Options. UseCompiledStylesheets
The options are IN,1 for enabled, or IN,2 for Specifies whether to pre-compile the style sheets. To improve performance, you should disabled always enable this setting. The setting should be disabled only if you are experimenting with style sheets. PowerPlay PDF Accessibility PowerPlayServer_Accessible_PDF The options are IN,1 for enabled, or IN,2 for disabled Auditing Level SRV.Options.AuditLevel
Specifies the level of detail for audit logging. In IBM Cognos BI, the settings are as The options are None, Summary, and Detail. follows. IN,0 sets audit logging to None. IN,1 sets it to Summary. IN,2 sets it to Detail. Maximum size of each audit log file in KB SRV.Audit.MaxFileSize An example value is IN,256 PowerPlay Server - PPSDSRemote Port In IBM Cognos Series 7, the PPDSRemote Port setting is in the cern.ini file. SRV.PPDSRM.ServerPort An example value is IN,8020 Use this parameter to restrict the port used for communication between PowerPlay Client and the PowerPlay server, such as when the environment includes a firewall.
31
Table 7. Advanced settings for the PowerPlay service (continued) IBM Cognos Series 7 feature Delimiter used for export to CSV In IBM Cognos Series 7, CSV files are created in the native encoding of the PowerPlay Enterprise Server computer. The delimiter for CSV files was dependent on the list separator for the current locale, most commonly a comma). IBM Cognos BI advanced setting (parameter and value) SRV.Options.CSVDelimeter By default, IBM Cognos PowerPlay uses tab delimited output for export to CSV file. To change the delimeter to a comma (,) use SRV.Options.CSVDelimeter TX,, To change the delimeter to a semi-colon (;) use SRV.Options.CSVDelimeter TX,;
Related concepts: Chapter 7, Setting Up Logging, on page 81 IBM Cognos Business Intelligence log messages provide information about the status of components, including PowerPlay activity, and a high-level view of important events. Delimiter Used for Export to CSV Different from IBM Cognos Series 7 on page 121 By default, IBM Cognos PowerPlay uses a tab delimiter for export to CSV file. This behavior is consistent with other IBM Cognos studios.
Procedure
1. In IBM Cognos Administration, on the Status tab, click System. 2. Click the arrow beside All Servers, click Services, and then click PowerPlay.
32
3. 4. 5. 6. 7.
Click the arrow beside PowerPlay Service, and click Set properties. Click the Settings tab. In the Value column, click Edit for Advanced Settings. Select Override the settings acquired from the parent entry. In the Parameter column, enter the parameter name, and in the Value column, enter the value for the setting. For numeric values, the format for the Value column is "IN,#" where # is the number associated with the setting you want. For example, to set the maximum size of audit log files in IBM Cognos BI to 256 kilobytes, you must enter the Parameter as SRV.Audit.MaxFileSize and the Value as IN,256. For text values, such as the delimiter to use for export to CSV file, the format for the Value column is "TX,#" , where # is the text symbol. Related tasks: Enable Auditing for Cubes and Reports on page 92 When you enable auditing, activity information is continuously recorded in the ppes_audit.log file.
Procedure
1. In PowerPlay administration, select an item in the Configurable Objects list.
Chapter 4. Administering IBM Cognos PowerPlay
33
2. Modify a property and then use one of the following actions to change cube or report settings. v To apply the changes only to the entry you selected in the Configurable Objects list, click Save. v To apply the changes to the descendants of the entry you selected in the Configurable Objects list, click Reset Descendants and then click Save. v To restore the default settings for an entry, select an individual property and click Reset, or click Reset All to restore the default settings for all properties. You can use the Reset Descendants option to apply the same change to descendants. To apply the changes, click Save.
Results
The changes are applied to the selected folder, cube, or report.
Procedure
1. Obtain the search path for the user that owns the My Folders location you want to customize.
34
The search path is available in the user's properties in the Security tab of IBM Cognos Administration. The following is an example of a search path for a user: CAMID("series7:u:authid=3212592089") For more information, see the IBM Cognos BI Administration and Security Guide. 2. In PowerPlay administration, enter the search path into the search box and then click Search. The user's name and My Folders content appears on the Search Results tab. 3. Select an item in the Configurable Objects list. 4. Modify a property and then use one of the following actions to change cube or report settings. v To apply the changes only to the entry you selected in the Configurable Objects list, click Save. v To apply the changes to the descendants of the entry you selected in the Configurable Objects list, click Reset Descendants and then click Save. v To restore the default settings for an entry, select an individual property and click Reset, or click Reset All to restore the default settings for all properties. You can use the Reset Descendants option to apply the same change to descendants. To apply the changes, click Save.
Results
The changes are applied to the selected folder, cube, or report in the My Folders location. Related concepts: Cube Settings on page 40 You can use the cube settings to customize your IBM Cognos PowerPlay application. Report Settings on page 46 You can use the report settings to customize your IBM Cognos PowerPlay application.
35
Procedure
1. In IBM Cognos Administration, click the PowerPlay tab. 2. Click a folder or package in the Configurable Objects list. If you select the root folder, the property is inherited by all the descendants, but can also be overridden by properties for a descendant. 3. On the Cube Settings tab, under the Display (Web) group, next to the Type property, click the arrow and select an interface option. 4. Click Save.
Results
When users open a report or package in PowerPlay Studio, the selected interface is used.
Procedure
1. In IBM Cognos Administration, click the PowerPlay tab. 2. In the Configurable Objects list, select a folder or package. 3. Click the Cube Settings tab, enable the drill through options, and specify connection information. 4. Click the Report Settings tab and enable the drill through options you want. The following table describes the drill through settings. Some settings, such as connection information, apply to only the Cube Settings tab. Requirement: Gateway settings used to support drill through, such as PowerPlay Web Target, must match the gateway URL settings in IBM Cognos Series 7 Configuration Manager.
Table 8. Drill through settings Drill Through setting PowerPlay cubes Description Allows users to drill through to details in another cube. Use it to enable or disable drill-through access in the client application. Both PowerCubes created with PowerPlay Transformer and other OLAP sources modified with PowerPlay Connect can allow drill through.
36
Table 8. Drill through settings (continued) Drill Through setting PowerPlay Web target Description Specifies the URL to the PowerPlay Web gateway program, such as http://host_name/ibmcognos/cgi-bin/ ppdscgi.exe Depending on how your network is configured, you may also need to include the domain name, for example, http://host_name.yourorg.com/ibmcognos/cgi-bin/ ppdscgi.exe To specify a port number other than the default web server port 80, append the number to the server name, for example, http://host_name:port_number/ibmcognos/ cgi-bin/ppdscgi.exe If your Web server is using Secure Sockets Layer (SSL), specify the HTTPS protocol with the server name, for example, https://host_name/ibmcognos/cgi-bin/ ppdscgi.exe PowerPlay Web Drill Through Newsbox Specifies that users can drill through from PowerPlay to targets that are not in the root server folder. Cube definitions can reference drill-through targets contained in an Upfront NewsBox hierarchy. This is the same value as your Upfront Server Group, as specified in IBM Cognos Series 7 Configuration Manager. Specifies the folder where your drill-through targets are in IBM Cognos ReportNet or IBM Cognos BI. Allows users to drill through to details in IBM Cognos Query. Use to enable or disable drill-through access in the client application. Specifies the URL to the IBM Cognos Query gateway program, such as http://host_name/ibmcognos/cgi-bin/ cqcgi.exe Depending on how your network is configured, you may also need to include the domain name, for example, http://host_name.yourorg.com/ibmcognos/cgi-bin/ cqcgi.exe To specify a port number other than the default port 80, append the number to the server name, for example, http://host_name:port_number/ibmcognos/cgi-bin/ cqcgi.exe If your web server is using Secure Sockets Layer (SSL), specify the HTTPS protocol with the server name, for example, https://host_name/ibmcognos/cgi-bin/cqcgi.exe Impromptu Web Reports Allows users to drill through to details in an Impromptu report. Use this setting to enable or disable drill-through access in the client application.
PowerPlay Web Drill Through Server Group PowerPlay Web Drill Through CRN Folder IBM Cognos Query
37
Table 8. Drill through settings (continued) Drill Through setting Impromptu Web Reports Drill Through NewsBox Description Specifies the Upfront Newsbox of the published report set that contains the target drill-through report. For example, if the drill-through report go.imr is located in the Great Outdoors folder, type Great Outdoors in this box. The imr file name must also be written in the cube if it was built using the cube/measure drill-through properties in Transformer and was therefore included at build time. Specifies the URL to the Impromptu Web Reports gateway program on Microsoft Windows operating system and UNIX operating system, such as http://host_name/ibmcognos/cgi-bin/imrap.cgi Depending on how your network is configured, you may also need to include the domain name, for example, http://host_name.yourorg.com/ibmcognos/cgi-bin/ imrap.cgi To specify a port number other than the default port 80, append the number to the server name, for example, http://host_name:port_number/ibmcognos/cgi-bin/ imrap.cgi If your web server is using Secure Sockets Layer (SSL), specify the HTTPS protocol with the server name, for example, https://host_name/ibmcognos/cgi-bin/ imrap.cgi IBM Cognos ReportNet/IBM Cognos Connection Allows users to drill through to details in IBM Cognos ReportNet or IBM Cognos BI. Use this setting to enable or disable drill-through access in the client application. Specifies the URL to the IBM Cognos ReportNet or IBM Cognos BI gateway program on Windows and UNIX, such as http://host_name/ibmcognos/cgi-bin/cognos.cgi Depending on how your network is configured, you may also need to include the domain name, such as http://host_name.yourorg.com/ibmcognos/cgi-bin/ cognos.cgi To specify a port number other than the default port 80, append the number to the server name, such as http://host_name:port_number/ibmcognos/cgi-bin/ cognos.cgi If your web server is using Secure Sockets Layer (SSL), specify the HTTPS protocol with the server name., such as https://host_name/ibmcognos/cgi-bin/cognos.cgi IBM Cognos ReportNet/IBM Cognos Connection Folder Specifies the IBM Cognos ReportNet or IBM Cognos BI folder that contains the target drill-through report.
38
Table 8. Drill through settings (continued) Drill Through setting IBM Cognos ReportNet/IBM Cognos Assistance Description Specifies that when users click Drill Through on a cube, the Assist Drill Through page opens. Use this page to identify the parameters that are defined for the drill-through report. Allows users to drill through to details in another PowerCube or IBM Cognos PowerPlay report. Specifies the IBM Cognos BI folder that contains the drill-through PowerCubes or IBM Cognos PowerPlay reports. Allows users to select from a list of existing IBM Cognos BI drill through definitions or create a new definition.
5. Do one of the following v To apply the changes to the selected configurable object and it's descendants, click Reset Descendants and then click Save. v To apply the change to only the selected configurable object, click Save. Related concepts: Drill-Through Access on page 22 Drill-through access in IBM Cognos Business Intelligence is different from IBM Cognos Series 7.
Procedure
1. Select a folder or package in the Configurable Objects list. 2. In the Cube Settings, modify the toolbar settings.
Table 9. Toolbar settings Toolbar property Image Description Enables or disables the image specified in the Background image file setting
39
Table 9. Toolbar settings (continued) Toolbar property Background Image File Description Specifies the file name of .gif or .jpg image to be used as the background of the toolbar area. You must copy images to the c10_location\webcontent\ ppwb\images folder. Do not include the path when you specify the file name. You must enable the transparency property to use a background image. Background Color Transparency Predefined buttons Custom buttons Specifies the background color of the toolbar area. Specifies whether the background color is transparent or not. Lists the available toolbar buttons. Allows you to enable the custom toolbar functions that you added to the ppwbcustom.js file
Procedure
1. From the installation_location\webcontent\ppwb folder, open the ppwbcustom.js file in a text editor. 2. In one of the custom functions, create a JavaScript for the custom command and then save the ppwbcustom.js file. 3. In the Configurable Objects list in PowerPlay administration, select a folder or package. 4. In the Cube Settings, Toolbar group, enable the appropriate custom entry for the function you modified in the ppwbcustom.js file., and then click Save. 5. Choose whether you want to apply the change to all descendants and then click Save.
Cube Settings
You can use the cube settings to customize your IBM Cognos PowerPlay application. The information in the following table describes the Options properties.
Table 10. Cube settings: Options properties Options property Title Description Specifies a title. You can also add variables to the title.
40
Table 10. Cube settings: Options properties (continued) Options property HTML Encode User Specified Title Description If enabled, only a limited set of HTML tags that are allowed in the titles of reports that may be published to the web. If disabled, any HTML tag is allowed in the title. Specifies that PowerPlay Client users can save the cube as a subcube. If this option is enabled, users can connect to the remote cube and save portions of it as a subcube, that is, a local PowerCube (.mdc file) on their local drives. This allows users to disconnect from the server and access the subcube on their computer. Later, they can re-synchronize to the remote server cube. Only PowerCubes created with PowerPlay Transformer can be saved as subcubes. Get Data Allows users to explore a report without showing data in a crosstab display. When this is enabled, the user will be able to select Get Data Later from the Options menu and Get Data from within the display. Specifies the level of auditing for the cube. If you enable auditing, information is recorded that may help you analyze and troubleshoot problems. The following auditing options are available. None records no information. Summary records requests made to cubes. Detail records statistics on the measures, dimensions, and levels of a cube that are accessed by PowerPlay Studio. This allows you to determine which areas of a cube are used more or less frequently, and may help you to develop a strategy for creating more efficient cubes. Queued Request Timeout(s) Sets the length of time, in seconds, that cube or report requests will remain queued. If these requests are not processed within the set time, users will receive a message asking them to try again. Specifies whether the dimension line information is included when a user exports a Comma Separated Value file (.csv) from PowerPlay Studio. Specifies how PDFs are rendered. Automatic is based on the authoring tool. Web Layout uses the PowerPlay Studio style PDF. Client Layout uses the PowerPlay Client style PDF.
Chapter 4. Administering IBM Cognos PowerPlay
Save as PowerCube
Auditing Level
41
Table 10. Cube settings: Options properties (continued) Options property PDF Rendering Viewer Description Specifies PDF options for the report viewer. IBM Cognos Viewer uses the IBM Cognos Business Intelligence style viewer. PowerPlay Studio Report Viewer uses the IBM Cognos Series 7 style viewer.
The information in the following table describes the Process Control properties.
Table 11. Cube settings: Process Control properties Process Control property Connection Timeout (min) Description Sets the number of minutes a user's connection to cubes remains active for PowerPlay Studio users. When the connection times out, the user may be prompted for the cube password again, but not the authentication information. Connection timeout does not apply to connections to the server from PowerPlay Client. Minimum Processes Maximum Processes Sets the minimum number of processes that remain running once they are executed. Sets the maximum number of processes that can be executed at the same time. Sets the maximum length of time in seconds that the server spends processing requests. If the requests are not processed within the set time, users receive a message asking them to try again. Sets the number of minutes a process remains active between requests. When a process times out, the memory it used becomes available to the server. The number of processes specified in Minimum Processes remain active even if requests are not being processed. Recycle Time (min) Specifies the maximum amount of time in minutes a process is allowed to run before being retired. You can reduce the default value if these processes consume too many resources. The default value is 1440 minutes (24 hours). To disable the recycle time setting, set the value to 0 (zero).
The information in the following tables describes the Display (Web) properties.
42
Table 12. Cube settings: Display (Web) properties Display (Web) property Screen Resolution Description Optimizes the appearance of buttons and displays. Use to select the most common resolution for user workstations. If the resolution does not match the web browser, the buttons and displays appear at a different scale from the text. If you aren't sure which resolution to use, 800 x 600 is recommended. Type Specifies one of the available user interfaces. Generic restricts the generation of HTML pages to code supported by older web browsers. If you enable this setting, users do not get DHTML rendering regardless of the browser used. If you have large cubes, DHTML can reduce performance of the server. If you enable Generic, you can improve performance. The Enhanced - IBM Cognos PowerPlay Studio interface uses the look and feel of other IBM Cognos studios. The Enhanced - Series 7 interface uses the look and feel of IBM Cognos Series 7.
The information in the following table describes the Page Size properties.
Table 13. Cube settings: Page Size properties Page Size property Row Limit Column Limit Description Limits the number of rows and columns that appear on a page. Use to improve the performance and readability of large reports. Report pages include navigation buttons that allow users to move forward and backward. For example, after opening a report, users can page forward to the next 20 columns or 50 rows. Buttons are also available for going directly to the first or last page of columns or rows. The page limits that you set are defaults only. Users can redefine the limits after they open paginated reports.
The information in the following table describes the Menu Size properties.
43
Table 14. Cube settings: Menu Size properties Menu Size property Character Limit Description Limits the number of characters shown for category names in drop down menus in the generic interface and dimension viewer and flyouts in the enhanced interface. The box width is determined by the longest category name, up to the maximum set. Any category longer than the maximum limit is truncated. You may need to increase this limit if more characters are necessary to distinguish categories. You can also decrease the limit if categories are easily distinguishable with fewer characters. Item Limit Limits the number of categories shown per level. Use to prevent web browser problems associated with displaying a large number of list items in drop down menus in the generic interface and dimension viewer and flyouts in the enhanced interface. If you can't redesign cubes so that dimensions contain fewer categories, you can limit the number of categories included in each level. For example, you limit dimension box categories to 50. Any level that exceeds 50 categories is truncated to show only the first 50 categories. An option is shown at the end of the list so users can view the next categories. The option name depends on the version of the user's web browser.
The information in the following table describes the Dimension Area properties.
Table 15. Cube settings: Dimension Area properties Dimension Area property Report Banner Description Shows the PowerPlay Studio banner containing the name of the currently connected cube. Enables or disables the image specified in the Background Image File setting. Specifies the file name of .gif or .jpg image to be used as the background of the area where the dimension lists appear. You must copy images to the c10_location\webcontent\ ppwb\images folder. Do not include the path when you specify the file name. You must enable the transparency property to use a background image. Background Color Specifies the background color of the area where the dimension lists appear.
Image
44
Table 15. Cube settings: Dimension Area properties (continued) Dimension Area property Transparency Description Specifies whether the background color is transparent or not.
The information in the following table describes the Crosstab Frame properties.
Table 16. Cube settings: Crosstab Frame properties Crosstab Frame property Link Color Text Color Description Specifies the color of hyperlinked text such as category labels. Specifies the color of non-hyperlinked text such as data values. Enables or disables the image specified in the Background Image File setting. Specifies the file name of .gif or .jpg image to be used as the background of the crosstab frame. You must copy images to the installation_location\ webcontent\ppwb\images folder. Do not include the path when you specify the file name. You must enable the transparency property to use a background image. Background Color Specifies the background color of the area where the dimension lists appear. Specifies whether the background color is transparent or not.
Image
Transparency
45
Table 17. Cube settings: Crosstab properties (continued) Crosstab property Background Color Description Specifies the background color of the area where the dimension lists appear. Specifies whether the background color is transparent or not.
Transparency
The information in the following table describes the Chart Frame properties.
Table 18. Cube settings: Chart Frame properties Chart Frame property Link Color Text Color Description Specifies the color of hyperlinked text such as category labels. Specifies the color of non-hyperlinked text such as data values. Enables or disables the image specified in the Background Image File setting. Specifies the file name of .gif or .jpg image to be used as the background for chart displays. You must copy images to the installation_location\ webcontent\ppwb\images folder. Do not include the path when you specify the file name. You must enable the transparency property to use a background image. Background Color Specifies the background color of the area where the dimension lists appear. Specifies whether the background color is transparent or not.
Image
Transparency
Report Settings
You can use the report settings to customize your IBM Cognos PowerPlay application. The information in the following table describes the Options properties.
Table 19. Report settings: Options properties Options property Explore in Interactive HTML Format Description Specifies whether users can explore PDF reports in interactive HTML format. This option also affects whether users can open reports in interactive HTML if the report is published to the portal.
46
Table 19. Report settings: Options properties (continued) Options property Auditing Level Description Specifies the level of auditing for the report. If you enable auditing, information is recorded that may help you analyze and troubleshoot problems. The following auditing options are available. None records no information. Summary records requests made to reports. Detail records statistics on the measures, dimensions, and levels of a cube that are accessed by PowerPlay Studio. This allows you to determine which areas of a cube are used more or less frequently, and may help you to develop a strategy for creating more efficient cubes. Queued Request Timeout Sets the length of time, in seconds, that cube or report requests will remain queued. If these requests are not processed within the set time, users will receive a message asking them to try again. Specifies the page size for printing PDF reports. Specifies the default orientation for printing PDF reports. Specifies whether the Display Frame Borders check box is available, allowing users to add a border to their reports. Specifies whether reports displayed in PDF contain Explain drill links on the row or column labels. Specifies whether the status line is shown. Specifies that PDF labels can be wrapped. If enabled, PDFs will be layered similar to how they are in PowerPlay Client. Specifies how PDFs are rendered. Automatic is based on the authoring tool. Client Layout uses the PowerPlay Client style PDF. Web Layout uses the PowerPlay Studio style PDF. PDF Rendering Viewer Specifies PDF options for the report viewer. Cognos Viewer uses the IBM Cognos Business Intelligence style viewer. PowerPlay Studio Report Viewer uses the IBM Cognos Series 7 style viewer.
Chapter 4. Administering IBM Cognos PowerPlay
47
Table 19. Report settings: Options properties (continued) Options property Pagination Description Allows you to define options for how PDFs are paginated.
The information in the following table describes the Process Control properties.
Table 20. Report settings: Process Control properties Process Control property Connection Timeout (min) Description Sets the number of minutes a user's connection to reports remains active for PowerPlay Studio users. When the connection times out, the user may be prompted for the cube password again, but not the authentication information. Connection timeout does not apply to connections to the server from PowerPlay Client. Minimum Processes Maximum Processes Sets the minimum number of processes that remain running once they open. Sets the maximum number of processes that can be open at the same time. Sets the number of minutes a process remains active between requests. When a process times out, the memory it used becomes available to the server. The number of processes specified in Minimum Processes remain active even if requests are not being processed. Recycle Time (min) Specifies the maximum amount of time a process is allowed to run before being retired. You can reduce the default value if these processes consume too many resources. The default value is 1440 minutes (24 hours). To disable the recycle time setting, set the value to 0 (zero).
48
Table 21. Report settings: Display properties Display property Screen resolution Description Optimizes the appearance of buttons and displays. Use to select the most common resolution for user workstations. If the resolution does not match the web browser, the buttons and displays appear at a different scale from the text. If you aren't sure which resolution to use, the default, 800 x 600 is recommended.
Related concepts: PDF Output of Migrated Report Does Not Display Correctly on page 117 When you run a migrated report in PDF, the PDF does not display correctly. The text appears as a series of dots, and you receive an error message saying that AndaleWT font is not available.
49
To create a custom style for IBM Cognos PowerPlay you work with two folder locations. You must ensure that both folders have the files required to support the custom style. To create a custom style for IBM Cognos PowerPlay, use the following steps instead of the Create a Custom Style procedure in IBM Cognos BI Administration and Security Guide.
Procedure
1. In the installation_location/webcontent/skins directory, make a copy of an existing style directory. 2. Rename the copied directory. 3. In the installation_location/ppserver/skins directory, make a copy of the directory that has the same name as the directory you copied in step 1. 4. Rename the copied directory using the same name as in step 2. 5. In the new installation_location/webcontent/skins directory, modify the style sheets, graphics, or fonts as required. 6. In IBM Cognos Administration, add a new style object and associate it with the style directory created in step 2.
50
Chapter 5. Migrating from IBM Cognos Series 7 PowerPlay to IBM Cognos PowerPlay
Before you move your IBM Cognos Series 7 PowerPlay applications to IBM Cognos PowerPlay, you should consider your options to determine the best strategy for your content. You can migrate all of your applications at the same time, or you can migrate them one at a time. You can also build new applications in IBM Cognos Business Intelligence, and continue to use IBM Cognos Series 7 PowerPlay for some applications. When migrating existing applications and moving users to IBM Cognos BI, you have options as to how you can proceed. v You do not have to migrate all or any of your PowerPlay applications. v You can build new PowerPlay applications in IBM Cognos BI. v You can migrate some of your content to compare the results with your existing reports. v You can migrate all of your existing PowerPlay content to IBM Cognos PowerPlay immediately and take advantage of the PowerPlay services and the IBM Cognos BI architecture. You use the IBM Cognos Migration Assistant to migrate your PowerPlay content from IBM Cognos Series 7 Upfront or IBM Cognos PowerPlay Enterprise Server, or IBM Cognos Series 7 content previously published to IBM Cognos Connection. Once in IBM Cognos PowerPlay, the user experience is the same when you move from IBM Cognos PowerPlay Web to IBM Cognos PowerPlay Studio, or from the IBM Cognos Series 7 to IBM Cognos BI versions of IBM Cognos PowerPlay Client. Local client reports are not migrated by the IBM Cognos Migration Assistant. IBM Cognos PowerPlay Client users will be prompted for an IBM Cognos BI package when they open their IBM Cognos Series 7 reports that use a remote cube as a data source.
Why Migrate IBM Cognos Series 7 PowerPlay Content to IBM Cognos PowerPlay?
IBM Cognos Business Intelligence is built on the proven and scalable Web services architecture introduced with IBM Cognos ReportNet. Compared with IBM Cognos Series 7, business users work differently with IBM Cognos BI: v A single product provides all business intelligence capabilities: reporting, analysis, scorecards, workspaces, business event management, and data integration. Users choose the capabilities they need. v Because metadata is defined once, users have a complete and consistent view of corporate data. Users do not have to go to different products or locations to see different data. v Individual users can choose the tools and information they need. They do not have to learn generic tools designed for highly technical users. This flexible business intelligence meets the needs of a greater variety of roles in the organization.
51
Moving from IBM Cognos Series 7 PowerPlay to IBM Cognos PowerPlay provides a lower risk and lower cost of migration. Minimal retraining is required to assist end users moving from IBM Cognos Upfront or the IBM Cognos PowerPlay Web Table of Contents to IBM Cognos Connection. Many PowerPlay application properties from IBM Cognos PowerPlay Enterprise Server are the same in IBM Cognos PowerPlay. Server management, load-balancing, failover, performance tuning, and monitoring are now administered remotely using IBM Cognos Administration and your reports are stored in a central database, the IBM Cognos BI content store. Also, there are a number of improvements to drill through in IBM Cognos BI, including dynamic filtering of target reports and removing the need for administrators to add drill-through targets using IBM Cognos Transformer.
PowerCubes
In IBM Cognos BI, all data sources are accessed through packages. The package contains connection information that identifies the data source, such as a PowerCube. The cube connection information includes the cube location on your file system. When you migrate to IBM Cognos BI, your PowerCubes are mapped to packages. Packages contain connection information for your PowerCubes. Users can then create new reports using the packages. Users with access to other IBM Cognos BI studios can also use these packages to create new reports from your original IBM Cognos Series 7 PowerCubes as data sources. This allows you to extend the use of your existing cubes. By default, the name of the data source, such as the cube name, is used to create the package in IBM Cognos BI. During the migration, you can accept the default or change the cube mapping to an existing package. The cube files (.mdc) are not migrated or moved during the migration. Their location will not change. Their connection information, however, will be migrated to your IBM Cognos BI environment. To ensure that your applications will work in the IBM Cognos BI environment, the cubes must be in a location that is accessible by your IBM Cognos BI servers. Credentials are not required to create a data source connection or package in IBM Cognos BI, but they may be required to access the package.
Migration Approach
The recommended migration approach involves: v Creating new applications in IBM Cognos Business Intelligence The best way to learn and understand a new product is by gaining practical experience. This step involves freezing application development in IBM Cognos Series 7 products and creating new applications in IBM Cognos BI. Creating new
52
applications in IBM Cognos BI allows you to learn about the features and benefits of IBM Cognos BI and to determine which migration approach to use for your existing applications. v Migrate PowerPlay users and applications to IBM Cognos PowerPlay Migrating PowerPlay users and applications to IBM Cognos PowerPlay provides the benefits of the IBM Cognos BI architecture and performance while preserving the PowerPlay user experience. Once you have migrated to IBM Cognos PowerPlay, you can take advantage of many other aspects of IBM Cognos BI.
53
PowerPlay Web users will be very familiar with the functionality and exploration capabilities of PowerPlay Studio. Similarly, PowerPlay Client users will have the same experience when moving from IBM Cognos Series 7 to IBM Cognos BI. v Administering your content in IBM Cognos PowerPlay In IBM Cognos Series 7 PowerPlay, you administered your content using the PowerPlay Enterprise Server administration tool. The tool allowed you to set properties for cubes and reports as well as set properties for how your PowerPlay servers functioned. In IBM Cognos PowerPlay, most administration is done in IBM Cognos Administration. While the settings for cubes and reports have been maintained, the behavior of your PowerPlay servers now utilizes the IBM Cognos BI infrastructure. Related concepts: Chapter 3, What is Different in IBM Cognos PowerPlay?, on page 7 IBM Cognos PowerPlay brings the proven exploration and analysis capabilities of IBM Cognos Series 7 PowerPlay into the IBM Cognos Business Intelligence environment. Migrating Local Reports to IBM Cognos BI on page 67 Two macros are provided to migrate local PowerPlay reports to IBM Cognos PowerPlay. One macro will convert reports in ppr format to ppx format, which is required by IBM Cognos PowerPlay. The other will change the remote cube references in your ppx reports to package references for your IBM Cognos PowerPlay environment. Using PowerPlay Assets in IBM Cognos BI on page 52 Migrating IBM Cognos Series 7 PowerPlay users and applications to IBM Cognos PowerPlay allows you to preserve the PowerPlay user experience but also take advantage of many other aspects of IBM Cognos Business Intelligence.
54
Only cubes that are used by the reports selected for migration in the IBM Cognos Migration Assistant will be migrated. Cubes that have been published to IBM Cognos BI but are not used by any reports are not migrated. Cubes are migrated to packages. You do not have to create data source connections to the cubes or publish packages. The IBM Cognos Migration Assistant creates the data source connections and packages. v Folders The Migration Assistant recreates the source folder structure in the target location. v My Folders Each user's IBM Cognos Series 7 PowerPlay content in their My Folders location will be migrated to a Migrated Content folder in their My Folders location. v Report settings All of the report properties and all properties for the folders in which the report is contained up to, but not including, the root folder are applied to the report. Properties set on the root folder are applied to the Migrated Content folder, the default folder where your content is migrated. Note: The migration process does not migrate inherited properties when the migration source is IBM Cognos Connection.
Chapter 5. Migrating from IBM Cognos Series 7 PowerPlay to IBM Cognos PowerPlay
55
Personal NewsBox content is migrated to IBM Cognos BI as My Folders content for each user. Each user in IBM Cognos BI will have their own My Folders location which other users cannot access. Tip: You can also choose to migrate Personal NewsBox content to the Public Folder or to not migrate the content. The migration task creates an account in IBM Cognos BI for users that have already logged on. For more information about users and accounts in IBM Cognos BI, see the IBM Cognos Administration and Security Guide. v Shortcuts Shortcuts are migrated only if you migrate the target reports that the shortcuts point to in the same migration task. v Security Security is migrated if you are using the IBM Cognos Series 7 namespace as an authentication source in your IBM Cognos BI environment. Only users and user classes referenced in NewsBoxes and NewsItems being migrated are migrated. Access permissions that you have set on your content in Upfront are migrated to IBM Cognos BI, as shown in the following table:
Table 23. Mapping of access permissions Upfront Read Write Execute Owner IBM Cognos BI Traverse, Read Traverse, Read, Write Traverse, Read, Execute Traverse, Read, Write, Execute, Set Policy
For more information about IBM Cognos BI access permissions, see the IBM Cognos Administration and Security Guide. Tip: You can choose what Upfront security information to migrate. v Cube views Cube views are migrated to URLs that launch PowerPlay Studio with the appropriate package. v Custom views Custom views become report views during the migration, and must be migrated in the same migration task as the target report. v Report settings All of the report properties and all properties for the folders in which the report is contained up to, but not including, the root folder are applied to the report. The properties are taken from the properties set on the report indicated under Source report name in the Advanced Properties page of the Upfront report. Properties set on the root folder are applied to the Migrated Content folder, the default folder where your content is migrated. Report properties of reports published to Upfront as report links are not migrated.
56
Chapter 5. Migrating from IBM Cognos Series 7 PowerPlay to IBM Cognos PowerPlay
57
Related concepts: Inherited Lightweight PDF Generation Setting not Migrated on page 118 The Lightweight PDF Generation setting for a report is not migrated when it is inherited from the parent folder instead of being explicitly set. Content That Cannot be Migrated on page 108 You are migrating content and receive error messages that an object will not be migrated. Related tasks: Convert PPR Files to PPX Files for Migration on page 67 IBM Cognos PowerPlay does not open reports in ppr format. To be able to open ppr reports, you must first convert them to ppx format.
58
__ v For IBM Cognos BI on the UNIX operating system, ensure that all parts of the locale (language, country or region code, and character set) in IBM Cognos BI are identical to your IBM Cognos Series 7 environment. Tip: You might need to install additional language fonts to support the character set used in IBM Cognos Series 7. For more information, see the IBM Cognos BI Installation and Configuration Guide. The locale set in IBM Cognos Series 7 Configuration Manager must match the product locale, content locale, and server locale in IBM Cognos BI. In addition, you must create a language properties file in IBM Cognos BI for the locale to which the Series 7 environment is set. Otherwise, the name of the folder containing the migrated content may not be in the expected language. __ v If you are migrating reports that use the Shift-JIS encoding system for Japanese characters, you might need to map certain Shift-JIS characters to Unicode, the encoding system that IBM Cognos BI uses. The following tasks ensure that migration components are installed, configured, and enabled on the proper computers. __ v Install the migration components on all computers where IBM Cognos Series 7 or IBM Cognos BI server components are installed. The migration components include an IBM Cognos Series 7 component and an IBM Cognos BI component, which must be installed on the appropriate server. For more information, see the IBM Cognos PowerPlay Installation and Configuration Guide. Migration from Upfront depends on an IBM Cognos Series 7 component named Deployment Manager being available. Deployment Manager is installed by default with IBM Cognos Series 7 administration tools. The IBM Cognos Series 7 server you are migrating content from must have IBM Cognos Series 7 administration tools installed to ensure that Deployment Manager is available. __ v If you are migrating from multiple IBM Cognos Series 7 servers in a single migration task, define server aliases to more easily identify the sources from which you are migrating and to avoid name collisions. The following tasks ensure that you have the proper login information to run a migration task. __ v Provide an IBM Cognos Series 7 or IBM Cognos Connection user name and password during the migration. The user name that you choose must be a member of the root user class or an administrator to migrate content from Upfront or PowerPlay Enterprise Server. __ v Log onto IBM Cognos BI as an authenticated user. You must log on as an authenticated user to migrate personal information such as IBM Cognos Upfront Personal Newsboxes and report contact information. The following tasks help to maximize performance when running a migration task. __ v Set the logging level for the migration service to Minimum. This logging level monitors system and service startup and shutdown, run-time errors, user account management and run-time usage of IBM Cognos BI, and use requests. If you must troubleshoot the migration service, you can select a detailed logging level for just that service, keeping log messages to a minimum. For
Chapter 5. Migrating from IBM Cognos Series 7 PowerPlay to IBM Cognos PowerPlay
59
information about setting logging levels, see the IBM Cognos Administration and Security Guide. The migration service messages use the name 'mis' in the log files. __ v For best results, set the IBM Cognos BI service configuration type to Medium configuration. The configuration type that you use will depend on the hardware that you are using and the content you want to migrate. If you experience out of memory errors when running a migration task, you may need to change the IBM Cognos BI service configuration. For information about how to set the configuration type, see the IBM Cognos PowerPlay Installation and Configuration Guide. __ v For IBM Cognos BI on the UNIX operating system, set all resources available to the current shell and all processes started by it to unlimited. You can confirm these settings by running the following command from the command prompt: ulimit -Ha Related concepts: Appendix C, Japanese Shift-JIS Character Mapping, on page 129 When migrating reports or cubes whose names contain Japanese characters, issues may occur because there is no industry standard for mapping byte sequences from Shift-JIS characters to and from Unicode. Related tasks: Personal NewsBoxes Don't Appear in the Tree View of Upfront in the IBM Cognos Migration Assistant on page 112 When you create a migration task with Upfront as a source, Personal NewsBoxes do not appear in the tree view of NewsBoxes. Problems Migrating Cubes with non-ASCII Characters on UNIX on page 135 If the IBM Cognos Series 7 PowerPlay Enterprise Server service is using a non-ASCII path name to access a PowerCube and the IBM Cognos Business Intelligence server is running in a locale that uses a different character set, then the IBM Cognos BI server is unable to locate the referenced PowerCube on disk. Name of Folder Created for Migrated Content Is not in the Correct Language on page 109 When the IBM Cognos Series 7 or IBM Cognos Business Intelligence environment is in a locale other than English, the folder created in IBM Connection for the migrated content is named Migrated Content.
60
The same naming convention is used for packages created for migrated cubes and for the data source connections to the cubes. You can define a server alias to replace the concatenated name in all of these cases. Server aliases cannot contain the following special characters: {}:;/\<>".|*?
Procedure
1. Open the s7_location/migs7/migs7service_configuration.xml file. 2. Locate and uncomment the <server-aliases> section. Tip: For more information about defining aliases, read the comments for the section. For example, the comments explain what will happen if you define the same alias for two different Series 7 servers. 3. For each server alias that you want to define, specify the following information: v Series 7 server name v server port number v Series 7 rendition name v server alias If you do not specify a value for the alias, an alias will be generated. The alias will be the concatenation of the server name, server port number, and Series 7 rendition name. Leading or trailing spaces will be removed. For example, if you specify <alias> PPES1 </alias>as the alias, the actual alias will be <alias>PPES1</alias>. 4. Save the file. You must save the file in UTF-8. If you want to save the file in the encoding used by your locale, such as Shift-JIS, you must change the encoding specified in the first line of the file. <?xml version="1.0" encoding="UTF-8"?>
61
performs are recorded in the cogserver.log file or logging database that you have set up in your IBM Cognos BI environment. For best results, regularly monitor the log files and maintain the folders in which they are created. For example, if you are migrating many reports, the size of the log files may grow quickly. v Run histories IBM Cognos BI keeps a run history for tasks, such as migrations. The run history includes information such as the request time, start time, completion time, and whether the migration ran successfully. You can look at the run history for a task to view any errors or warning messages that are related to the task. To migrate content from IBM Cognos Connection, ensure that the migration components are installed on the same IBM Cognos BI instance from which you want to migrate. You cannot migrate content from another IBM Cognos BI instance. You must also ensure that all users who will run a migration have the required capabilities. For best results, do not remove cubes and reports from your IBM Cognos Series 7 environment until you have completed your migration. Note: If you run a migration task and then run another migration task using the same target location, any content that has already been migrated will be overwritten. The objects that will be overwritten include reports, cubes, server settings, data sources, and folders. If you have changed settings in IBM Cognos BI after you have migrated the content, the migration task will overwrite the settings with the original settings. For example, you migrate content from a folder in PowerPlay Enterprise Server. After you migrate, you use IBM Cognos Administration to modify some cube, report, or folder settings for the migrated content. If you migrate the content from that folder in PowerPlay Enterprise Server again, the original settings will overwrite any settings that you have changed in IBM Cognos BI for the contents of that folder. Report and cube settings will only be overwritten if the same report or cube is migrated again. Folder settings are overwritten if any content is migrated to the folder in IBM Cognos BI. Related concepts: Migration Logging on page 107 Events encountered when migrating IBM Cognos Series 7 PowerPlay to IBM Cognos PowerPlay are logged in two files, c10_location\logs\cogserver.log and s7_location/migs7/log.txt. Related tasks: Enable Users to Run a Migration Task on page 29 Users or groups of users you want to be able to run migration tasks must be granted the appropriate capabilities.
Procedure
1. In IBM Cognos Administration, on the Configuration tab, click Content Administration. . 2. On the toolbar, click the New Migration icon 3. In the Name box, type a unique name for the migration task.
62
Optionally, you can enter a Description and Screen Tip. If you do not want to use the target folder shown under Location to save the migration task, click Select another location, and click New folder to create a new location.
Results
After you created a migration task, you must specify the migration source.
Procedure
1. In the Specify a Series 7 migration server page, type the name of the IBM Cognos Series 7 server where the IBM Cognos Series 7 migration components are installed, and the port number that the IBM Cognos Series 7 migration service uses. The default is 21567. The IBM Cognos Series 7 server name that you specify does not need to match the server names specified in IBM Cognos Series 7 Configuration Manager. The names must only resolve down to the same IP address, to be considered as the same computer. Tip: The entry in the migs7service_configuration.xml file located in the s7_location\migs7 folder determines the port that the migration service uses. 2. On the Select a migration source page, choose the source in the Migrate PowerPlay content from drop down list. v Select IBM Cognos Connection to migrate IBM Cognos Series 7 PowerPlay content that was published to IBM Cognos Connection. v Select Upfront to migrate content from Upfront, including Upfront content and content published from PowerPlay. v Select PowerPlay Enterprise Server to migrate content from PowerPlay Enterprise Server. For the user name and the password, enter valid credentials for the source server. To migrate content from Upfront or PowerPlay Enterprise Server, the user name that you choose must be a member of the root user class.
Results
After you specified the migration source, you select the migration options.
Procedure
1. Under IBM Cognos Series 7 PowerPlay report PDF fonts, choose how you want to migrate Series 7 PowerPlay report PDF fonts. This option controls how the Lightweight PDF Generation option is migrated. v If the migration source is PowerPlay Enterprise Server and you want to migrate Series 7 PowerPlay PDF report settings to IBM Cognos PowerPlay as is, click Retain the Series 7 PDF font settings.
Chapter 5. Migrating from IBM Cognos Series 7 PowerPlay to IBM Cognos PowerPlay
63
Note: If the source report has the Lightweight PDF Generation option enabled and the PDF Layout setting is Client Layout, the report might not render correctly in IBM Cognos BI. The AndaleWT font used in PowerPlay reports is not a standard Microsoft Windows operating system font. To avoid this problem, include fonts in migrated reports. If the migration source is IBM Cognos Connection, the Lightweight PDF Generation option is not migrated when it is inherited rather than explicitly set. v To disable the Lightweight PDF Generation option in IBM Cognos PowerPlay, click Include fonts. Fonts are embedded in reports and they will render correctly in PDF. Note that including fonts will increase the size of the report. v To enable the Lightweight PDF Generation option in IBM Cognos PowerPlay, click Exclude fonts. Fonts are not embedded in the PDF output of reports. The PDF output may not display correctly if the computer that is used to view the PDF does not have the required fonts installed. 2. In the Security settings section, choose how you want to migrate security information. Some options are available only when the IBM Cognos Series 7 namespace is defined in IBM Cognos BI. Note: If you are migrating to the 64-bit version of IBM Cognos BI, you cannot migrate security information because IBM Cognos Series 7 namespaces are not supported in 64-bit IBM Cognos BI. v Under IBM Cognos Series 7 namespace secured PowerPlay cubes, choose how you want to migrate secured cubes. To migrate secured cubes only if the cube namespace for each cube is defined in IBM Cognos BI, click Migrate to data source and restrict authentication method to source namespace. For each migrated cube, the data source connection for the package is created with the signon option set to restrict PowerCube authentication to the namespace. To migrate all secured cubes, click Migrate to data source and set authentication method to All Applicable Namespaces. For each migrated cube, the data source connection for the package is created with the signon option set to authenticate with all applicable namespaces. After migration, you might need to set up security information in IBM Cognos BI to make the packages usable. v Under Upfront Personal NewsBoxes, choose where you want to migrate personal NewsBoxes when migrating Upfront content. To migrate Personal NewsBox content to each user's My Folders folder, click Migrate to IBM Cognos My Folders. To migrate Personal NewsBox content to the Public Folder, click Migrate to IBM Cognos Public Folder. The content will inherit the IBM Cognos BI permission settings of the parent folder. If you do not want to migrate Personal NewsBox content, click Do not migrate. Personal NewsBoxes will not be visible when you select the content that you want to migrate. v Under Upfront security access privileges, choose whether you want to migrate user classes and Upfront Access Control List (ACL) information.
64
To migrate user classes and Upfront ACL information, click Migrate to IBM Cognos permissions. Only users with enough privileges can access migrated objects in IBM Cognos Connection when IBM Cognos BI is secured. If you do not want to migrate user classes and Upfront ACL information, click Do not migrate. Migrated objects in IBM Cognos Connection will inherit the IBM Cognos BI permission settings of the parent folder for each object. v Under Upfront report contact info, choose whether you want to migrate user class contact information. To migrate contact information, click Migrate to IBM Cognos contact info. Contact information is migrated to the contact information of the migrated object in IBM Cognos Connection. If you do not want to migrate contact information, click Do not migrate. The contact information for each migrated object will be set to None. Note that if you migrate the same Upfront content again with the option to migrate contact information, contact information will not be migrated.
Results
After you specified the migration options, you select the content to migrate. Related concepts: Inherited Lightweight PDF Generation Setting not Migrated on page 118 The Lightweight PDF Generation setting for a report is not migrated when it is inherited from the parent folder instead of being explicitly set. Upfront Contact Information not Migrated on page 114 You migrate IBM Cognos Series 7 Upfront content and you select the option to not migrate user class contact information. You migrate the same Upfront content a second time with the option to migrate user class contact information, but the information is not migrated.
Procedure
1. On the Select the content page, select the folders or NewsBoxes to migrate. The content that you see in the source tree depends on the security options you selected in the previous step. You cannot select individual cubes or reports within a folder. However, you can migrate cubes that have no reports created from them. If you select an empty folder or NewsBox, it will not be migrated and it will not appear in the log as a failure to migrate. If you do not want to use the target folder that appears under Location to migrate your public content to, click Select another location to choose another location or create a new location for your migrated public content. Private content is migrated to each user's My folders location in IBM Cognos BI. You cannot select another location to migrate private content. Note: Entries that are placed in Public Folders are of interest to and can be viewed by many users. If you do not want the migrated content to be available to other users, choose or create a target location with more restricted permissions. 2. In the Specify cube mappings page, do one of the following:
Chapter 5. Migrating from IBM Cognos Series 7 PowerPlay to IBM Cognos PowerPlay
65
v To accept the default cube mapping, click Next. The source path and name of each PowerCube are used to create the default target package name. v To select another package, click Select a package in the Actions column. The package must already exist. You can change the location by clicking a link in the navigation path and locating the package that you want to use for the mapping. Tip: You can reset your selection to the default cube mapping by clicking Reset.
Results
After you select the content to migrate, you can start the migration. Related concepts: Using PowerPlay Assets in IBM Cognos BI on page 52 Migrating IBM Cognos Series 7 PowerPlay users and applications to IBM Cognos PowerPlay allows you to preserve the PowerPlay user experience but also take advantage of many other aspects of IBM Cognos Business Intelligence.
Procedure
1. In the Review the summary page, do one of the following: v If you are satisfied with your selections, click Next. v To make corrections to your selections, click Back. Tip: The Reports and other PowerPlay related objects counter includes reports, shortcuts, URLs, cube views, and custom views. 2. In the Select an action page, select how you want to complete the migration, and click Finish. v To save the migration task and migrate the content immediately or at a later time, click Save and run once. v To save the migration task and migrate content on a specific schedule, click Save and schedule. v To save the migration task without running it, click Save only. The migration might take a long time depending on the number of objects that you are migrating.
Results
When the migration task has completed, a Migrated Content folder is created in the location that you specified, and contains the same directory structure as the view that you migrated. A deployment archive containing the migrated content is also created. The name of the archive is the migration task name appended with the timestamp of when the archive was created. If the migration is not successful, you can view the run history of the migration task, or go to the c10_location\logs folder and check the cogserver.log file.
66
If you run the migration task again at a later time, a new deployment archive is created.
Recommendation - Keep Cubes and Reports in Your Source Environment Until Migration Is Complete
To ensure a successful migration, you must have valid content in your IBM Cognos Series 7 environment. For best results, do not remove any of your valid content, either cubes or reports, from your IBM Cognos Series 7 environment until you have completed your migration.
Procedure
1. Go to the c10_location\PPClient\Macros directory on the computer where you installed IBM Cognos PowerPlay. 2. Open the ppr2ppx.mac file in IBM Cognos Series 7 CognosScript Editor. Instructions for using the macro on the command line are provided in the macro. For more information about macros, see the PowerPlay Macro Reference Guide. Tip: You can use other supported tools such as Microsoft Visual Basic to run macros. 3. Find the line that reads
Chapter 5. Migrating from IBM Cognos Series 7 PowerPlay to IBM Cognos PowerPlay
67
strSourceDir = ""
and enter a source directory where your ppr files are located. For example, change the line to
strSourceDir = "c:\myreports"
and enter the directory to where you want the converted reports copied. For example, change the line to strOutputDir = "c:\mymigratedreports" 5. If you have security applied to your PowerCubes, find the line that reads
objPPlayApp.SetMDCAccessInfo
and uncomment the line by removing the ' from the beginning of the line, and enter the required PowerCube security information. For more information about macro elements, see the PowerPlay Macro Reference Guide. 6. If you do not want to be prompted for missing security information, find the line that reads
objPPlayApp.LogonPrompt = False
and uncomment the line by removing the ' from the beginning of the line. This will allow the macro to run unattended. Any reports accessing secured cubes without the appropriate credentials will not be converted, but they will be logged. 7. Save and run the macro. Your converted ppx files are created in the output directory you indicated, and any log messages are added to the ppr2ppx.log file in the output directory.
Procedure
1. Go to the c10_location\PPClient\Macros directory on the computer where you installed IBM Cognos PowerPlay. 2. Open the ppx_upgrade.mac file in IBM Cognos Series 7 CognosScript Editor. Instructions for using the macro on the command line are provided in the macro. For more information about macros, see the PowerPlay Macro Reference Guide. Tip: You can use other supported tools such as Microsoft Visual Basic to run macros. 3. Find the line that reads
strSourceDir = ""
and enter a source directory where your ppx files are located. For example, change the line to strSourceDir = "c:\myreports" 4. Find the line that reads
strOutputDir = ""
68
and enter the directory to where you want the migrated reports copied. For example, change the line to strOutputDir = "c:\mymigratedreports" 5. Find the line that reads
strMigrationFile = ""
and enter the path and name of the conversion configuration file that is created when you run a migration task. The file is named PPS7TOC8CFG.xml and is created in your c10_location\configuration directory. For example, change the line to strMigrationFile = "c:\Program Files\ibm\cognos\c10\configuration\ PPS7TOC8CFG.xml" 6. Save and run the macro. Your upgraded ppx files are created in the output directory you indicated, and any log messages are added to the ppx_upgrade.log file in the output directory. Related tasks: Using the Bookmark Conversion Utility in IBM Cognos PowerPlay You use the bookmark conversion utility to convert PowerPlay Enterprise Server bookmarks into a format that can be read by IBM Cognos PowerPlay Studio.
69
You must specify the conversion configuration file, the input text file, and an output text file that will be created automatically when you run the utility. Because Linux operating system is not a supported platform for IBM Cognos Series 7 PowerPlay, the bookmark conversion utility is not supported on Linux.
Procedure
1. Create a file in a text editor. 2. Enter the URL of each bookmark on a new line in the file:
http://series7server1/cognos/cgi-bin/ppdscgi.exe?bookmark1_id http://series7server1/cognos/cgi-bin/ppdscgi.exe?bookmark2_id http://series7server1/cognos/cgi-bin/ppdscgi.exe?bookmark3_id http://series7server1/cognos/cgi-bin/ppdscgi.exe?bookmarkn_id
3. Save the file. This file will be used as the input_file.txt in the following steps. 4. Go to the c10_location\bin directory. 5. Run the bookmark conversion utility by entering the following at the command prompt: pp7bkmmigtool.exe APP path\PPS7TOC8CFG.xml path\input_file.txt path\output_file.txt If you migrated content in a language other than English, you must include a language parameter in the command to correctly process the bookmark conversion configuration file. For example, if you migrated French content, enter the command as pp7bkmmigtool.exe APP path\PPS7TOC8CFG.xml path\input_file.txt path\output_file.txt fr The language option uses a two letter language code. For example, fr for French, de for German, es for Spanish, ja for Japanese. When you specify a language parameter, log messages will also be in that language. Errors are logged to the PP7BkmTool.log file in the c10_location\bin directory.
Results
The output file is generated, containing the converted IBM Cognos Business Intelligence bookmarks.
70
Related tasks: Manually Create a Conversion Configuration File on page 73 A bookmark conversion configuration file is automatically generated when you run a migration task. However, if you do not run a migration task, this file will not be generated. Bookmark Migration Produces URLs That Are Not Valid on page 117 After running the bookmark migration utility, the URL of each migrated bookmark is not valid. Specifically, the gateway in each URL does not match the actual IBM Cognos Business Intelligence gateway. The gateway used is the default gateway, which is usually http://localhost:80/ibmcognos/cgi-bin/cognos.cgi.
71
localhost for the server name, port number 7777, bookmarkcgi.log for the log file, and English for the language used to log messages.
Procedure
1. In the s7_location\cgi-bin directory, create a text file named bookmarkcgi.conf and add the following lines:
PPBOOKMARKTOOL_SERVER=<server_name> PPBOOKMARKTOOL_PORT=<port_number> CGI_LOGFILE=<logfile_name> CGI_LOCALE=<language>
The language option uses a two letter language code. For example, FR for French, DE for German, ES for Spanish, JA for Japanese. Each entry must be on its own line. 2. In the c10_location\bin directory, start the bookmark conversion utility at the command prompt:
pp7bkmmigtool.exe SERVER path\PPS7TOC8CFG.xml port_number
where PPS7TOC8CFG.xml is the configuration file generated by the migration, or the one that you manually created if you did not run a migration task. The bookmark conversion utility is started and must remain running to convert bookmarks as users access them. Errors are logged to the pp7bkmtool.log file.
Results
You can now allow users to change bookmarks to IBM Cognos Business Intelligence or automatically redirect bookmarks to IBM Cognos BI.
Procedure
1. Open the PowerPlay Enterprise Server administration tool. 2. View the server properties, click Cube Settings, and expand the Toolbars folder. 3. For the Custom 1 property, change the setting to Enabled. in the toolbar that appears when you are This creates a custom button viewing a cube. 4. In the s7_location\webcontent\ppwb directory, open the ppwbcustom.js file in an editor. 5. Locate the following lines:
function custom1() { alert(Custom action 1); // please replace // parent.location.href=http://www.cognos.com/ // example url }
72
} var bkmURL = tparent.location.href; var bkmCGIURL = <bookmarkcgi URL>; if (bkmURL.indexOf(?) != -1) bkmCGIURL += bkmURL.substr(bkmURL.indexOf(?)); tparent.location.href = bkmCGIURL; }
where <bookmarkcgi URL> is the URL to the bookmarkcgi.exe file in the c10_location\cgi-bin directory. For example, if you access IBM Cognos BI from http://server_name/ ibmcognos/cgi-bin/cognos.cgi, the bookmark cgi is accessed at http://server_name/ibmcognos/cgi-bin/bookmarkcgi.exe. Note: The quotes in the lines are required. The angle brackets, < and >, indicate a value you must change.
Results
After opening any IBM Cognos Series 7 bookmark, you can convert it and redirect it to an IBM Cognos BI equivalent bookmark by using the new custom button.
Procedure
1. In the c10_location\cgi-bin directory, make a copy of the bookmarkcgi.exe file and rename it ppdsweb.cgi. 2. Copy ppdsweb.cgi to each of the s7_location\cgi-bin directories on each of your IBM Cognos Series 7 server computers. 3. To display any messages in the appropriate language, copy all of the dll files, or cat files on UNIX operating system, that begin with PPWebCGIMsg from your c10_location\cgi-bin directory to your s7_location\cgi-bin directories.
Results
All bookmarks in IBM Cognos Series 7 are now automatically converted and redirected to IBM Cognos BI when they are opened. Note: This will only apply for bookmarks that were created against the CGI gateway. Bookmarks created against an ISAPI or NSAPI gateway will not be converted. You can convert those bookmarks by changing the URI to http://server_name/ibmcognos/cgi-bin/bookmarkcgi.exe in the old bookmarks. Do not modify the BZ parameter.
Procedure
1. Using an XML editor, create a conversion configuration file, as shown below.
Chapter 5. Migrating from IBM Cognos Series 7 PowerPlay to IBM Cognos PowerPlay
73
<?xml version="1.0" encoding="UTF-8"?> <bkmk_mig_tool> <c8gateway>http://servername:port_number/ibmcognos/cgi-bin/cognos.cgi</c8gateway> <section> <s7encoding value="windows-1252"/> <s7gateways> <gateway>http://servername/cognos/cgi-bin/ppdscgi.exe</gateway> <gateway>http://series7alt1/cognos/cgi-bin/ppdscgi.exe</gateway> </s7gateways> <datasources> <datasource s7path="/cube1name" c8SearchPath="/content/folder[@name= foldername] /package[@name=cube1name]" c8StoreId="iGHSJKDNGJSAMDHSJRGANDJDFGJAS"/> <datasource s7path="/cube2name" c8SearchPath="/content/folder[@name= foldername] /package[@name=cube2name]" c8StoreId="iGAUIHMTJUTOSLATMSDJFIGGHYUIR"/> </datasources> </section> </bkmk_mig_tool>
where: v the c8gateway element is the URL of the IBM Cognos Business Intelligence gateway computer. All converted bookmarks are executed using this gateway. Only one gateway can be specified. v the s7encoding element is the native encoding of the IBM Cognos Series 7 environments included in the file. The bookmark conversion utility will convert the bookmark from the native encoding to UTF-8 encoding, which is required in IBM Cognos BI. Tip: You can check the encoding used in your IBM Cognos Series 7 environment. In Configuration Manager, under Cognos Shared, click Locale. v the s7gateways element is the gateway for your IBM Cognos Series 7 environment. If you use alternate gateways, add a gateway element for series7alt1. For example, add a line like the following to the s7gateways element: <gateway>http://otherservername/cognos/cgi-bin/ppdscgi.exe</gateway> The conversion utility uses this list to determine the IBM Cognos Series 7 environment to which the bookmark belonged, and which mapping list to use. v the datasources element shows the cubes in your IBM Cognos Series 7 environment that were migrated. The datasource element contains the information for a cube. s7path contains the fully qualified file name from the Cube Properties window in the IBM Cognos Series 7 PowerPlay Enterprise Server administration tool. For example, if the Great Outdoors cube exists inside a folder named Cubes, the path would be /Cubes/Great Outdoors. c8SearchPath contains the path of the matching package in IBM Cognos BI. next In the IBM Cognos BI portal, you can click the Set properties icon to any package to show the Set Properties dialog box, and click View the search path, ID and URL to see the Search Path value. c8StoreId contains the ID value from the View the search path, ID and URL dialog box. This value is unique for each object in the IBM Cognos content store. 2. Save the file, naming it PPS7TOC8CFG.xml.
74
3. Convert your bookmarks by running the bookmark conversion utility as either an application or as a server. Related concepts: Run the Bookmark Conversion Utility as a Server on page 71 When you run the bookmark conversion utility as a server, you can use it in two ways. Related tasks: Run the Bookmark Conversion Utility as an Application on page 69 When you run the bookmark conversion utility as an application, it converts all of the IBM Cognos Series 7 bookmarks contained in the input text file at the same time.
Chapter 5. Migrating from IBM Cognos Series 7 PowerPlay to IBM Cognos PowerPlay
75
76
Procedure
1. Connect to the IBM Cognos BI portal. 2. Start IBM Cognos Administration: v In the Welcome page, click Administer IBM Cognos Content. v In IBM Cognos Connection, from the toolbar, click Launch, IBM Cognos Administration. 3. In IBM Cognos Administration, click the Configuration tab. . 4. Click the New Data Source button 5. In the Name box, type great_outdoors_sales_en and then click Next. The name must be all lowercase and include the underscore characters. 6. In the Type box, select IBM Cognos PowerCube and then click Next. 7. In the location box, type the path and file name for the great_outdoors_sales_en.mdc PowerCube. For example, if you are creating a connection to samples installed to the default installation location on the local computer, type C:\Program Files\ibm\cognos\c10\webcontent\samples\datasources\cubes\ PowerCubes\EN\great_outdoors_sales_en.mdc 8. To confirm that you entered all parameters correctly, click Test the Connection. After you test the connection, click Close on both the View the Results and Test the Connection pages to return to the connection string page. 9. Click Finish. 10. On the Finish page click OK. Do not select Create a Package.
Results
The great_outdoors_sales_en entry appears on the Data Source Connections list. Related tasks: Import the Sample Reports You can make the sample reports available for use in Cognos Viewer or IBM Cognos PowerPlay Studio by importing them using a deployment archive.
77
The sample PowerPlay data is packaged in a deployment archive for PowerPlay and migration and a deployment archive for drill-through examples. You import the deployment archives in IBM Cognos Administration before users can access the reports. Another method to make reports available in Cognos Viewer or PowerPlay Studio is to publish them using PowerPlay Client.
Procedure
1. On the computer where the samples are installed, go to the c10_location\webcontent\samples\content directory. For example, if the samples were installed to the default installation location, the path is C:\Program Files\ibm\cognos\c10\webcontent\samples\content 2. Copy IBM_Cognos_PowerPlay.zip to the c10_location\deployment directory on the computer where the Content Manager component is installed. 3. Connect to the IBM Cognos BI portal. 4. Start IBM Cognos Administration: v In the Welcome page, click Administer IBM Cognos Content. v In IBM Cognos Connection, from the toolbar, click Launch, IBM Cognos Administration. 5. Click the Configuration tab. 6. Click Content Administration. 7. 8. 9. 10. 11. 12. 13. 14. . Click the New Import button Select IBM_Cognos_PowerPlay and click Next. Keep the default name and location and then click Next. Select the Samples folders and click Next. Keep the default options and click Next. Review the summary and click Next. Select Save and run once and click Finish. Select Now and click Run.
Results
IBM_Cognos_PowerPlay appears in Administration and a Samples folder appears in Public Folders in IBM Cognos Connection.
78
Procedure
1. On the computer where the samples are installed, go to the c10_location\webcontent\samples\content directory. For example, if the samples were installed to the default installation location, the path is C:\Program Files\ibm\cognos\c10\webcontent\samples\content 2. Copy IBM_Cognos_DrillThroughSamples.zip to the c10_location\deployment directory on the computer where the Content Manager component is installed. 3. Connect to the IBM Cognos BI portal. 4. Start IBM Cognos Administration: v In the Welcome page, click Administer IBM Cognos Content. v In IBM Cognos Connection, from the toolbar, click Launch, IBM Cognos Administration. 5. Click Configuration. 6. Click Content Administration. . 7. Click the new import button 8. Select IBM_Cognos_DrillThroughSamples and click Next. 9. 10. 11. 12. 13. Keep the default name and location and then click Next. Select the Samples folder and click Next. Keep the default options and click Next. Review the summary and click Next. Select Save and run once and click Finish.
Procedure
1. To a. b. c. test a report in Cognos Viewer, do the following: Connect to the IBM Cognos BI portal and start IBM Cognos Connection. In the Welcome page, click IBM Cognos content. In the Public Folders list, open Samples, PowerPlay.
d. Click great_outdoors_sales_en. e. Click any report in the list.The report opens in IBM Cognos Viewer. 2. To a. b. c. test a report in PowerPlay Studio, do the following: Connect to the IBM Cognos BI portal and start IBM Cognos Connection. In the Welcome page, click IBM Cognos content. In IBM Cognos Administration, from the toolbar, click Launch, IBM Cognos Connection. d. Go to Public Folders, Samples, PowerPlay. e. Click More for the great_outdoors_sales_en entry.
Chapter 6. Setting Up the IBM Cognos PowerPlay Samples
79
f. Click View package contents. g. Click the Open with PowerPlay Studio button for any report in the list. The report opens in PowerPlay Studio.
Procedure
1. From the computer where the IBM Cognos BI Samples are installed, copy the following content to the IBM Cognos Series 7 computer. v all reports from the c10_location\webcontent\samples\powerplay_reports\ powerplay_7\reports_for_remote_cubes\language v great_outdoors_7.mdc from the c10_location\webcontent\samples\ datasources\cubes\PowerCubes\language directory 2. In IBM Cognos Series 7 PowerPlay Administration, add the cube and reports to PowerPlay Enterprise Server. 3. To update the cube mapping, in IBM Cognos Series 7 PowerPlay Client, open each report using a remote connection to great_outdoors_7.mdc, and then save the report.
Results
The cube and reports are now ready for use in IBM Cognos Series 7.
80
81
Table 24. Information recorded for each logging level Details System and service startup and shutdown, runtime errors User account management and runtime usage of IBM Cognos Business Intelligence Use requests Service requests and responses All requests to all components with their parameter values other queries to IBM Cognos BI components (native query) Minimal X Basic X Request X Trace X Full X
X X
X X
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 BI. The default logging level is Minimal. If the default setting does not provide the information you require, gradually increase the logging level. For example, moving to the request logging level will provide information about dimension, level, and measure activity. Use Full logging level only for detailed troubleshooting purposes because it may significantly degrade server performance.
Procedure
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, select Services and then click PowerPlay. 5. Click the arrow next to PowerPlay Service to view the Actions menu, and then click Set properties. 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.
82
Unless you are troubleshooting problems, Request is an appropriate logging level for most installations. 9. Click OK. Related concepts: Some PowerPlay Activity Is Not Logged on page 119 If you view the log file or log database and information about IBM Cognos PowerPlay activity you want to track does not appear you can increase the logging level to record more information.
Procedure
1. In IBM Cognos Administration, click the PowerPlay tab. 2. In the Configurable Objects list, select a folder or package. The settings will be applied to all objects contained in the selected folder or package. You can change the auditing level for individual items later to be different from the parent. 3. Click the Cube Settings or Report Settings tab. 4. For Auditing Level, select Summary or Detail. 5. Click OK.
83
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 the IBM Cognos Business Intelligence Administration and Security Guide. When a user logs on to IBM Cognos BI, 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 IBM Cognos BI logging database for PowerPlay are described in the following table, with a cross-reference to associated column definitions.
Table 26. Table definitions for the logging database Table name COGIPF_POWERPLAY Description Stores information about PowerPlay package, report and report view requests Stores information about dimensions used in PowerPlay package, report and report view requests Stores information about levels used in PowerPlay package, report and report view requests Stores information about PowerPlay measures used in PowerPlay package, report and report view requests Stores information about migration service operations
COGIPF_POWERPLAY_DIM_USAGE
COGIPGF_POWERPLAY_LEVEL_USAGE
COGIPF_POWERPLAY_MEASURE_USAGE
COGIPF_MIGRATION
Table Interactions
The following information describes columns for each IBM Cognos PowerPlay table in the logging database.
84
85
Table 27. Columns in the COGIPF_POWERPLAY table (continued) Column name COGIPF_THREADID Description and data type The identification number of the thread where the request is run VARCHAR2 (255) COGIPF_ COMPONENTID The name of the component that generates the indication VARCHAR2 (4) COGIPF_ BUILDNUMBER The major build number for the component that generates the indication NUMBER COGIPF_ LOG_LEVEL The level of the indication NUMBER COGIPF_ TARGET_TYPE The object on which the operation is run VARCHAR2 (255) COGIPF_ REPORTPATH The report path VARCHAR2 (512) COGIPF_STATUS The status of the operation: blank if execution has not completed, success, warning, or failure VARCHAR2 (255) COGIPF_ RUNTIME The number of milliseconds required to execute the report NUMBER COGIPF_REPORTNAME The name of the report VARCHAR2 (255) COGIPF_PACKAGE The package that the report is associated with VARCHAR2 (512) COGIPF_DATASOURCE The data source that the report is associated with VARCHAR2 (512)
86
Table 27. Columns in the COGIPF_POWERPLAY table (continued) Column name COGIPF_DATASOURCE_CONNECTION Description and data type The data source connection that the report is associated with VARCHAR2 (512) COGIPF_CUBEPATH The path to the local PowerCube that the report is associated with VARCHAR2 (512) COGIPF_OPERATION The action performed on the object VARCHAR2 (128) COGIPF_MESSAGE Error details VARCHAR2 (2000) COGIPF_REQUEST_TYPE COGIPF_SUB_COMPONENTID NUMBER VARCHAR2 (64)
87
88
Table 30. Columns in the COGIPF_POWERPLAY_MEASURE_USAGE table (continued) Column name COGIPF_MEASURE_NAME Description and data type The measure name associated with the request VARCHAR2 (256) COGIPF_MEASURE_COUNT The measure count associated with the request NUMBER
89
Table 31. Columns in the COGIPF_MIGRATION table (continued) Column name COGIPF_ SUBREQUESTID Description and data type The identification number of the component subrequest VARCHAR(255) COGIPF_THREADID The identification number of the thread where the request is run VARCHAR(255) COGIPF_ COMPONENTID The name of the component that generates the indication VARCHAR(64) COGIPF_ BUILDNUMBER The major build number for the component that generates the indication INT(4) COGIPF_ LOG_LEVEL The level of the indication INT(4) COGIPF_OPERATION The action performed on the object VARCHAR(64) COGIPF_TARGET_TYPE The type of object that is migrated VARCHAR(64) COGIPF_TARGET_PATH The path of the migrated object in IBM Cognos Business Intelligence nVARCHAR(1024) COGIPF_TARGET_NAME The name of the migrated object in IBM Cognos BI nVARCHAR(255) COGIPF_STATUS The status of the operation VARCHAR(64) COGIPF_DETAILS Detailed information about the operation nVARCHAR(2000) COGIPF_PACKAGE The package that was created as part of the migration task nVARCHAR(512)
90
Table 31. Columns in the COGIPF_MIGRATION table (continued) Column name COGIPF_MIGRATION_TASK Description and data type The name of the migration task nVARCHAR(1024) COGIPF_MSGNUM The message number INT(4) COGIPF_SOURCE_TYPE The migration source type (IBM Cognos Connection, Upfront, or PowerPlay Enterprise Server) VARCHAR(64) COGIPF_SOURCE_PATH The path of the object in IBM Cognos Series 7 nVARCHAR(1024) COGIPF_SOURCE_NAME The name of the object in IBM Cognos Series 7 nVARCHAR(255)
91
v Run the PPESAuditFileProcessor command line utility to transfer audit data from text files to an audit database. v Create reports to assess cube, report, and system activity.
Procedure
1. In IBM Cognos Administration, on the Status tab, click System. 2. Click the arrow beside All Servers, click Services, and then click PowerPlay.
3. Click the arrow beside PowerPlayService, and click Set properties. 4. Click the Settings tab. 5. In the Value column, click Edit for Advanced Settings. 6. Select Override the settings acquired from the parent entry. 7. In the Parameter column, enter SRV.Options.AuditLevel. In the Value column, enter one of the following: v IN,0 to set audit logging to None v IN,1 to set it to Summary v IN,2 to set it to Detail
92
By default, log files are created in the c10_location\logs\powerplay directory. A new log file is opened each time the server is started or when the size of the log file exceeds the maximum file size setting.
Procedure
1. In IBM Cognos Administration, click the PowerPlay tab. 2. In the Configurable Objects list, select a folder or package. The settings will be applied to all objects contained in the selected folder or package. 3. Click the Cube Settings or Report Settings tab. 4. For Auditing Level, select Summary or Detail. 5. Optionally, change the default values for the maximum size of each audit file and Location for audit files settings. 6. Click OK. Related tasks: Configure Advanced Settings on page 32 You configure advanced settings for the IBM Cognos PowerPlay service in IBM Cognos Administration.
Procedure
1. In IBM Cognos Administration, click the Configuration tab. . 2. Click the new data source button 3. In the Name box, type a name for the database, and then click Next. 4. In the Type box, select the type of database you are using for your audit database, and then click Next. 5. Type the database connection information and any signon information required for the audit database. For more information about database connection information, see the IBM Cognos Business Intelligence Administration and Security Guide. 6. Click Test the connection. The database connection string appears under Connection string. Record or copy the connection string. This is the value you will require when you use the PPESAuditFileProcessor utility. Click Close in the View the results dialog box will display the connection string page again.
Chapter 7. Setting Up Logging
93
7. Click Test to verify that the connection string is valid. You do not need to complete the steps in the wizard once you have obtained the database connection string. The string is used when you run the PPESAuditFileProcessor utility from the command line.
Procedure
1. Change to the c10_location\bin directory. 2. Enter the command to run the utility and include the command line options. For example, PPESAuditFileProcessor -dbname OracleDataSource -dbconnect "^UserID:^ ?Password:;LOCAL;OR;ORACLE@%s@cyborg/%s" -dbuser Admin -dbpass AdminPW -auditlocation C:\cognos\c10\logs\powerplay\ppesaudit
Table 32. Command line options for the PPESAuditFileProcessor utility Command line options -dbname -dbconnect Description The database name. The database connection string that contains the database type and connection information. A database user name with read and write access to the database. The password for the database user name. The location of the generated audit log files. The files are located in c10_location\logs\ powerplay. The name of the log file. The number or rows processed for each transaction. Stop processing when an error occurs.
-dbuser
-dbpass -auditlocation
-errorlog -nbrows
-exitonerror
Dispatcher Table
The dispatcher table, named PPES_DISPATCHER, captures the following pieces of information from the audit log files.
94
Table 33. Columns in the PPES_DISPATCHER table Column name MACHINE_NAME Description VARCHAR(100). Specifies the dispatcher that created the log. INTEGER. Specifies the port that the dispatcher was listening on. DATETIME. Specifies the date and time that the server started. VARCHAR(100). Specifies the time zone used for all entries in the log. VARCHAR(20). Specifies the version of PPES. INTEGER. Specifies the log file version. INTEGER. Specifies the generated log file number.
MACHINE_PORT
SERVER_START_DATE_TIME
TIME_ZONE
PPES_VERSION
LOGFILE_VERSION LOGFILE_GENERATION
Session Table
The session table, named PPES_SESSION, captures the following pieces of information from the audit log files.
Table 34. Columns in the PPES_SESSION table Column name SESSION_ID USER_NAME Description VARCHAR(100). Specifies the session ID. VARCHAR(100). Specifies the user name for the request. User names are written for web requests and remote requests.
Request Table
The request table, named PPES_REQUEST, captures the following pieces of information from the audit log files.
Table 35. Columns in the PPES_REQUEST table Column name PPES_SESSION.SESSION_ID REQUEST_ID START_DATE_TIME Description VARCHAR(100). Specifies the session ID. VARCHAR(100). Specifies the request ID. DATETIME. Specifies the request start date and time.
95
Table 35. Columns in the PPES_REQUEST table (continued) Column name END_DATE_TIME Description DATETIME. Specifies the request end date and time. INTEGER. Specifies the request status. failed = 0; succeeded = 1 VARCHAR(100). Specifies the user class. INTEGER. Specifies whether the initial QP handled the request (1 or 0). INTEGER. Specifies the type of request. web = 0; remote =1; admin = 2 VARCHAR(20).. Specifies the type of action: GET, SET, or Publish. VARCHAR(500). Specifies one or more mirrors available. VARCHAR(500). Specifies message details provided in the log VARCHAR(100). Specifies the name of the server. INTEGER. Specifies the port of the server. DATETIME. Specifies the start date and time of the server.
REQUEST_STATUS
USER_CLASS REDISPATCH
REQUEST_TYPE
ACTION
MIRRORS
MESSAGE
MACHINE_NAME
MACHINE_PORT SERVER_START_DATE_TIME
REQUEST_ID
SOURCE_NAME SOURCE_TYPE
96
SOURCE_NAME SOURCE_TYPE
SOURCE_FILENAME
REQUEST_ID
DIM_CODE
DIM_COUNT DIM_NAME
97
Table 39. Columns in the PPES_LEVEL_USAGE table (continued) Column name REQUEST_ID Description VARCHAR(100). Specifies the request ID of the request. VARCHAR(256). Specifies the dimension code. VARCHAR(256). Specifies the level code. VARCHAR(256). Specifies the level name. INTEGER. Specifies the level count.
DIM_CODE
REQUEST_ID
MEASURE_CODE MEASURE_NAME
MEASURE_COUNT
98
99
QUIT REMOVE type [PATH] name RENAME source destination RESET name property RESET BELOW name property SET name property=value SHOW name EXIT
filename
Specifies the fully qualified path of the mdc file, including the file extension.
folder
Specifies an object name of type FOLDER, which represents the folder path within the portal hierarchy.
name
Specifies the name of an object (cube, report, or folder). When the object is a folder, it can be used to form a folder hierarchy. A server is also considered the root folder.
namespace
Specifies the namespace ID that contains the user you are using to log in.
objectname
Specifies the logical name of the cube package, report, or folder as defined in the portal.
option
Specifies a command option, as described in the Options.
password
Specifies either a simple server password or the password for the specified Access Manager user name. Do not include the password command if the username does not require a password.
path
Specifies a physical path to the data source file. Uses the format of your operating system (UNIX or Windows).
100
property
Specifies an object property in (.) object hierarchy format. For a list of properties, use the SHOW command.
server
Specifies the name or IP address of a PowerPlay server.
type
Specifies the type of object. The type can be PACKAGE, REPORT, or FOLDER.
username
Specifies a user name to log on as.
value
Specifies the value for a property.
Conventions
When entering file paths or the variable name (when the object is a folder), a dot (.) represents the current folder, two dots (..) represent the parent folder, and a slash (/) represents the root folder, which is the server. For example, the following script disables all objects on server hp_srv.
ppadmtool > connect hp_srv > disable ./ > exit
When entering file names or paths containing spaces, enclose the entire file name or path in quotation marks ("). For example
SHOW great outdoors COPY ../gnt /CF systems/great outdoors
You can also redirect input from a file and output to a file.
ppadmtool < ../adm/daily_update.txt > check.log
Commands
With the batch administration utility, you can execute administration commands for IBM Cognos PowerPlay from the Microsoft Windows operating system command prompt or UNIX operating system command shell instead of using IBM Cognos Administration in a browser session.
ADD
Adds a new object to the connected server. PATH indicates a data source. The following example adds the cube "Great Outdoors" to the connected server. The command creates a data source and package in IBM Cognos Business Intelligence:
ADD CUBE "Great Outdoors" PATH "F:/cubes/great outdoors.mdc"
101
CONNECT
Connects to a IBM Cognos PowerPlay server. The following example connects to the server c10_server_name as the user name JuliaX from the Default namespace using the password neptune:
CONNECT http://C10_server_name:9300/p2pd/servlet/dispatch USER JuliaX PASSWORD neptune NAMESPACE Default
You can also use -i -j and -k in place of USER, PASSWORD, and NAMESPACE. The example would then become:
CONNECT http://C10_server_name:9300/p2pd/servlet/dispatch -i JuliaX -j neptune -k Default
CD
Changes the current folder. The command-line prompt indicates the current folder and the path from the root folder. The following example changes the current folder from /global networking/finances to /global networking/hub product/marketing. For clarity, the prompt is included in the example: global networking /finances> CD ../hub products/marketing global networking/hub products/marketing>
COPY
Creates a copy of an object and its associated overridden properties in a new object. The following example copies the report gnt from the parent folder to the folder /CF systems and names the new object great outdoors:
COPY ../gnt /CF systems/great outdoors
DISABLE
Disable selects the disable check box within the package properties page. This property is accessible from the portal. When an object is disabled, users who 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 users have write access to it, the disabled icon appears next to the entry. The following example makes the object "Finance" unavailable:
DISABLE Finance
ENABLE
Enable clears the disable check box on the package properties page:
ENABLE "Sales 2009"
EXIT
Closes the ppadmtool utility.
HELP
Shows a list of the ppadmtool commands.
102
LIST
Lists all the objects in the specified folder. The following example lists all objects in the folder "/docs/recent reports":
LIST "/docs/recent reports"
If no folder is specified, all the objects in the current folder are listed.
MOVE
Moves an object and its associated overridden properties to a new object. You must specify both a target location as well as a name for the moved object. If the target location does not exist, it will be created for you. The following example creates a new object "bls"in the "/new/" folder:
MOVE gnt "/new/bls"
REMOVE
Removes an object or the reference to its data source file without deleting the actual file. If the operation removes all references, the object is removed in its entirety. The following example removes the cube "new_sales" from the connected server.
REMOVE CUBE new_sales
The following example removes the reference to the data source file for the object "general networks".
REMOVE PATH "general networks"
If the object is a folder, all child objects are also removed. If a type is not specified, the object is assumed to be a cube.
RESET
Resets the selected properties on an object to the properties inherited from higher level folders. If there are no higher level folders, the properties are set to the default properties for that object. The following example resets the value "LA" on the object "Great Outdoors" to the default value for the folder, or, if there is no default folder, the default value for the object type:
RESET "Great Outdoors" LA
RESET BELOW
Resets the properties on the contents of a folder and its subfolders, but not the properties of the folder itself. The following example resets the value "Published" on the contents of the root folder to the default value specified for the folder, or, if there is no folder default, the default for the object type:
RESET BELOW / Published
SET
Assigns property values to an object. Properties are case sensitive. You must enter the property name exactly as it is used. To display the properties for an object, use the SHOW option. v The following example sets the maximum number of processes for the Great Outdoors cube to 5:
SET "Great Outdoors" .PWQ.Control.MaxProcess=5
v To set a property for all of the objects on the server insert a forward slash (/) instead of an object name. The following example sets the property "PWQ.Control.MaxProcess" to "5" on the root folder (or server):
Chapter 8. PowerPlay Batch Administration
103
SET / .PWQ.Control.MaxProcess=5
v To set a property for content in My Folders for a specific user, use the search path from the users properties to specify the location. The following example sets the property
SET CAMID(... some cam id )/folder[@name=My Folders] <some property>=<some value>
SHOW
Displays all the properties for the specified object. The following example displays all properties for the "Sales 2009" object:
SHOW "Sales 2009"
The following example displays .FLD.Control.MinProcess property for the testfolder2 object:
SHOW /testfolder2 .FLD.Control.MinProcess
Deprecated Commands
The following commands have been deprecated and are not available in the IBM Cognos PowerPlay version of the ppadmtool. ADD DS type name DS mirror CRN REPLACE GATEWAY KILL name NOTIFY {(CUBE_OBJECT objectname | CUBE_FILEfilename)} EVENT = UPDATE [ON_ERROR IGNORE | FAIL] PUBLISH name PUBLISHLINK name REMOVEDS name DS mirror REMOVELINK name
Changed Commands
The following changes have been made in the IBM Cognos PowerPlay version of the ppadmtool. v The IBM Cognos Business Intelligence dispatcher URI is now used for the server name. You can obtain the dispatcher information from Cognos Configuration. v If your connection to the server requires authentication, you must provide a user name, password, and namespace ID to connect. You will not be prompted if this information is not provided. No authentication is required if you are connecting using anonymous access. v If the user name that you are using to connect has no password, then do not add the PASSWORD parameter as part of the connect command. In the IBM Cognos Series 7 ppadmtool, no password was specified using quotes with no text with the PASSWORD parameter. v You can no longer issue additional commands as arguments when initially calling the program. For example, the following command is invalid.
104
D:\ppadmtool>ppadmtool connect "http://wottppeslab3:9300/p2pd/servlet/ dispatch" user dan password dan namespace s7 add cube cubename path d:\cubes\ppweb.mdc You must first connect to the server and then issue commands. v CRN REPLACE CUBENAME does not replace all matching cube names on the server. When the command is executed from a folder named XY, only objects in XY are changed. v Add will create a data source and a package in Cognos Connection if the object you are adding is an IBM Cognos PowerCube.
Configuration Requirements to Use SSL for the PowerPlay Server Batch Administration Utility
If IBM Cognos Business Intelligence is configured to use the Secure Sockets Layer (SSL) protocol for communication between IBM Cognos BI components, you must complete the following configuration before you can use the PowerPlay Server Batch Administration utility. This configuration is not required if SSL is enabled only on the web server. Configuration involves three steps. v Extract an SSL certificate. v Create a key store for the certificate. v Modify the parameters in the ppadmintool.bat file.
Procedure
1. Go to the installation_location\bin directory. 2. Type the following command: ThirdPartyCertificateTool.bat -java:local -E -T -r cacert.cer -k ..\configuration\signkeypair\jCAKeystore -p password
Results
The CA certificate, cacert.cer, is exported to the installation_location\bin directory. You can now create a keystore for the certificate.
Procedure
1. Go to the installation_location\bin\jre\version\bindirectory. 2. Type the following command: keytool.exe -import -file installation_location\bin\cacert.cer -keystore installation_location\webapps\utilities\ppadmtool\MyKeyStore -storepass password -alias ibmcognos_alias
105
Results
The key store file, MyKeyStore, is created in the installation_location\webapps\ utilities\ppadmtool directory. You can now modify the parameters for the batch administration utility.
Procedure
1. From the installation_location\webapps\utilities\ppadmtool directory, open ppadmtool.bat in a text editor. 2. Locate the following line: %_RUNJAVA% -cp %CP%%J_OPTS% com/spotonsystems/cubeadmin/cli/ PpAdmin%* 3. Edit the line to identify the keystore and password: %_RUNJAVA% -cp %CP% %J_OPTS% -Djavax.net.ssl.trustStore=MyKeystore Djavax.net.ssl.trustStorePassword=password com/spotonsystems/cubeadmin/ cli/PpAdmin %*
Results
When the IBM Cognos BI installation is configured to use the SSL protocol, use the following format for the CONNECT command in the ppadmtool utility: CONNECT https://server_name:port/p2pd/servlet/dispatch
106
Appendix A. Troubleshooting
Use this troubleshooting reference information and solutions as a resource to help you solve specific problems you may encounter when using IBM Cognos PowerPlay. Problems that you may encounter are organized in the following areas. Log files may also contain information to help you solve problems.
Problems when Migrating from IBM Cognos Series 7 PowerPlay to IBM Cognos PowerPlay
This section describes problems you may encounter when migrating content from IBM Cognos Series 7 PowerPlay to IBM Cognos PowerPlay.
Migration Logging
Events encountered when migrating IBM Cognos Series 7 PowerPlay to IBM Cognos PowerPlay are logged in two files, c10_location\logs\cogserver.log and s7_location/migs7/log.txt. After you migrate from IBM Cognos Series 7 PowerPlay to IBM Cognos PowerPlay, review messages in the log files to ensure that all reports are migrated successfully. To learn more about the details of migration events, follow these best practices: v v v v Set the appropriate logging level before migrating. Enable debug logging. Migrate from IBM Cognos Series 7 PowerPlay to IBM Cognos PowerPlay. Review the migration log messages and take appropriate action.
107
You must have the required permissions to access the IBM Cognos Administration functionality and set logging levels.
Procedure
In IBM Cognos Administration, on the Status tab, click System. Click the arrow beside System, and click Set properties. Click the Settings tab. Find Audit logging level for migration service in the list, and, from the Value menu, select Basic for the logging level. If you are having problems with the migration, select Full before you migrate to ensure that all migration events are logged. 5. Click OK. 1. 2. 3. 4.
Procedure
1. Open the s7_location/migs7/migs7service_configuration.xml file in a text editor. 2. Set the enable-migs7service-debug-logging element to yes. 3. Save the file. You must save the migs7service_configuration.xml file in UTF-8. If you want to save the file in the encoding used by your locale, such as Shift-JIS, you must change the encoding specified in the first line of the file. <?xml version="1.0" encoding="UTF-8"?>
Procedure
1. Open the c10_location\logs\cogserver.log file in a text editor. 2. Review the messages for migration events (MIS) with a Failure status. Most messages provide direction to solve the problem. 3. Correct the problem, and run your migration again.
108
This will occur if your IBM Cognos Series 7 reports are invalid or if the cubes on which the reports are based are not found or are invalid. If reports or cubes are invalid or are not found, the reports cannot be migrated. The reports and cubes that are not migrated are recorded in a file named cogserver.log that is located in your IBM Cognos Business Intelligence c10_location/logs directory or the logging database you have set up in your IBM Cognos BI environment. To resolve this problem, either correct the report so that it is valid or remove the report if it is no longer needed, then retry your migration. Non-PowerPlay content will not be migrated and this content will be recorded in the log file. Related concepts: What Gets Migrated and to Where Does it Migrate? on page 54 Depending on the source you select to migrate your content in the IBM Cognos Migration Assistant, different objects will be migrated.
v empty NewsBoxes To resolve this problem, in your IBM Cognos Series 7 environment, make the necessary changes to the content that you want to migrate.
Name of Folder Created for Migrated Content Is not in the Correct Language
When the IBM Cognos Series 7 or IBM Cognos Business Intelligence environment is in a locale other than English, the folder created in IBM Connection for the migrated content is named Migrated Content. Ensure that the locale set in IBM Cognos Series 7 Configuration Manager is the same as the product locale, content locale, and server locale in IBM Cognos BI. The product and content locales are user preference settings in IBM Cognos Connection. The server locale is a global configuration setting that you access from the Actions menu in IBM Cognos Configuration. In addition, create a language properties file in IBM Cognos BI for the locale to which the Series 7 environment is set.
Appendix A. Troubleshooting
109
Locale values in IBM Cognos Series 7 are in the format language-country or region code, such as en-us. In IBM Cognos BI, the product locale is language only. Content and server locales can be language-country or region code or language only. If the Series 7 and IBM Cognos BI locales have the same language value but a different country or region code value, you must also create a language properties file in IBM Cognos BI for the different country or region code value. The following table lists the language properties files that are required in various scenarios.
Table 41. Required language properties files IBM Cognos BI IBM Cognos server BI product IBM Cognos BI locale locale content locale de-de German
de-de
de-at
German
de-at
de-de
German
de-at
de-at
German
German (Austria)
migrationMsg_deat.properties
Procedure
1. Create a copy of the c10_location/webapps/p2pd/WEB-INF/classes/ migrationMsg_<lang>.properties files in another directory. 2. Rename the copy as migrationMsg_<lang>-<country or region code>.properties where <lang>-<country or region code> is the Series 7 locale. 3. Move the copy to the directory specified in step 1. 4. If the IBM Cognos BI server or content locale <country or region code> value is different than the Series 7 locale <country or region code>, repeat steps 1-2. 5. Rerun the migration.
Unable to Migrate Content Because Locale not Configured or Mapped in IBM Cognos Configuration
If the locale used in the content that you are migrating is not configured or mapped in IBM Cognos Configuration, the migration process stops and the following error messages appear.
CM-REQ-4342 An error occurred with the client. CM-REQ-4193 The deployment option import is incorrect.
110
CM-REQ-4179 The locale locale is not one of the configured content locales.
To work around the problem, add or map the locale used by the source content in IBM Cognos Configuration. For example, if the source content locale is en-us, in IBM Cognos Configuration, add en-us or map en-us to en. If the source content locale is not configured in IBM Cognos Configuration but is mapped, the migration process replaces the source content locale in the deployment archive with the mapped locale. For example, en-us is replaced with en. This change occurs only in the archive options and folder hierarchy properties. The locale in report specifications is not changed. A warning message is added to the migration log file to indicate the change.
v restart the service if its memory footprint becomes excessive On the Windows operating system, change to the s7_location/migs7 directory, and use the following command:
configure.exe --stop
on the UNIX operating system, change to the s7_location/migs7 directory, and use the following command:
./configure --stop
111
For settings for drill through to IBM Cognos Series 7 application servers, changes are only necessary if you use server group names to refer to your servers. If so, then you should change these server group names to gateway URLs. For drill through to an IBM Cognos Business Intelligence package, two new properties were introduced. These properties, PowerPlay Studio Package and PowerPlay Studio Package Folder, must be set after migration in order to enable this functionality. For drill through to an Upfront NewsBox, one new property was introduced. This property, PowerPlay Web Drill Through Server Group, must be set after migration in order to enable this functionality.
Cannot Connect to Upfront Server During Migration if Upfront is Secured for Single Signon or OS Signon
The IBM Cognos Migration Assistant currently requires that you provide a Basic signon user name and password for an IBM Cognos Series 7 namespace when migrating IBM Cognos Series 7 Upfront or PowerPlay Enterprise Server content. If the IBM Cognos Series 7 namespace is configured for OS signons only, your authentication will fail and you cannot migrate your content. To resolve this problem, configure the IBM Cognos Series 7 namespace for Basic signon or both Basic and OS signons, and ensure that you have a Basic signon configured for the user name you will use to authenticate to Upfront or the PowerPlay Enterprise Server.
Personal NewsBoxes Don't Appear in the Tree View of Upfront in the IBM Cognos Migration Assistant
When you create a migration task with Upfront as a source, Personal NewsBoxes do not appear in the tree view of NewsBoxes. By default, Personal NewsBoxes are hidden. Hidden objects do not appear in the IBM Cognos Migration Assistant.
112
The Personal NewsBoxes and content will be migrated even though they are not visible in the IBM Cognos Migration Assistant. In environments with large amounts of content, this limits the ability to break a migration into manageable pieces. To resolve this problem, you must change the settings for personal NewsBoxes.
Procedure
1. Log in to Upfront as the user who will be using the IBM Cognos Migration Assistant. 2. Click Personalize. 3. On the General tab, select Show all entries in the tree, Show entry details, and Show hidden entries, and then click OK. 4. Under NewsIndex, click Personal NewsBoxes, and then click NewsBox Properties. 5. Clear the Hide this entry box.
Problems Migrating Reports with Internal Path Names Exceeding 255 Characters
When migrating IBM Cognos Series 7 Upfront content, if the number of characters used for the folder name and report name exceeds 255 characters, the migration fails. The following error appears: S7S-err-0813 Exception encountered parsing IBM Cognos Deployment Manager errors and warning from file: UNEXPECTED INTERNAL ERROR: CDM dump is missing the "PPES.packletLocation" property. IBM Cognos Series 7 PowerPlay Enterprise Server may also generate a core file in the S7_install/bin/ directory. When path names exceed 255 bytes in length, the PowerPlay Enterprise Server process may overflow a buffer. In particular, you may want to check the length of your paths in the PPSRoot directory. For example, S7_install/ppserver/PPSRoot/... You are most likely to encounter this problem v on the UNIX operating system UNIX usually permits path names of 1023 or more bytes. Windows limits path names to 260 bytes when using the APIs that PPES uses. v when using a multi-byte language such as Japanese A single character can occupy two or more bytes. Consequently, path names can reach the 255 byte limit with fewer characters. To work around the problem, contact the IBM Cognos Customer Center (www.ibm.com/software/data/cognos/customercenter/) for a software update to address the issue. Alternatively, you can avoid the problem by selecting to migrate only NewsBoxes containing reports with path names that are less than 255 characters in length. Or rename the report and NewsBox names so that they use less than 255 bytes.
Appendix A. Troubleshooting
113
Empty Folder Named "cubes" Created After Migrating from IBM Cognos Connection
After performing a migration with IBM Cognos Connection as the migration source, an empty folder named "cubes" is created in the migrated content location. Objects are migrated successfully and the package related to cube references was migrated to the PowerPlay folder. You can safely remove the empty folder.
114
Failed to load csx file. This problem may occur if the cer5.csx file is missing from the S7_install/bin directory. To resolve the problem, create the cer5.csx file by reapplying the configuration setting.
Procedure
1. 2. 3. 4. In Configuration Manager, open the current configuration. In the Components tab, select the root node. From the Actions menu, click Apply Selection. If the cer5.csx file is not created in the bin directory, reinstall PowerPlay Enterprise Server. 5. Start the Series 7 migration service.
Error Message not Clear when Migrating Upfront Content from a Series 7 Distributed Installation Environment
When migrating IBM Cognos Series 7 Upfront content from an IBM Cognos Series 7 environment where PowerPlay Enterprise Server services and Upfront services are on two different computers, the migration fails if the PowerPlay Enterprise Server services are stopped. The following error message appears: MGD-msg-0440 A communication error has occurred with <host name> on port <port number>. Verify that the Series 7 migration server name and port number are correct. The error message does not clearly indicate that the PowerPlay Enterprise Server could not be contacted.
Unable to Migrate Reports on UNIX when Path Names Contain Certain European Characters
An error occurs when migrating reports with path names that contain certain European characters on the UNIX operating system. The error occurs when the migration source is IBM Cognos Connection, and the reports were published to IBM Cognos Business Intelligence in the following way: 1. The source PPX reports are created under the Windows-1252 encoding. 2. The reports are transferred, using FTP, to UNIX running in the French locale fr_FR.8859-15 or the German locale de_DE.8859.15. 3. In one of the locales in the previous step, the PowerPlay Enterprise Server service is started.
Appendix A. Troubleshooting
115
4. The reports are inserted in PowerPlay Enterprise Server and then published to IBM Cognos BI. 5. The locale is changed in IBM Cognos Series 7 Configuration Manager after the reports are published in the previous step and before the migration task is run. The migration error occurs if the path name contains one of the following characters: v 0xA4 (euro symbol) v 0xA6 (S caron) v 0xA8 (s caron) v 0xB4 (Z caron) v 0xB8 (z caron) v 0xBC (OE) v 0xBD (oe) v 0xBE (Y umlaut) An error message appears in the run history details or the migration log:
S7S-err-0646 Exception caught: ...... 93 (__privateGetProperty) ppes_bridge.py: 72(__privateEncode) /dap ..../lib/python2.5/encodings/iso8859_15.py: 12 (encode)
To work around the problem, change the locale in Configuration Manager to the previous locale, run a migration of the affected content, and then change the locale in Configuration Manager back to the new locale.
Ranking Applied to an Axis having a Custom Subset and One or More Categories not Migrated to Analysis Studio
Ranking applied to an axis having a custom subset and one or more categories, even if the categories are from the same dimension, is not migrated to IBM Cognos Analysis Studio. After migration, the rank cells are empty for the subset. To work around the problem, do one of the following: v Migrate the report to IBM Cognos Report Studio instead. v In the original report, leave only the custom subset on the axis and remove the other categories.
Migrating a Report with a Single Measure on X or Y Axis Does not Run in Report Studio
When migrating an IBM Cognos PowerPlay Web or PowerPlay Studio report that has a single measure on the x or y axis to IBM Cognos Report Studio, the report is not valid and does not run. The following error appears: RSV-V AL-0003 Unable to find the item <measure name>_Summary in the query <query name>. In Report Studio, a new node <measure name>_Summary is created in the crosstab. A red x appears on the node indicating a problem. To resolve the problem, delete the new node from the report.
116
Procedure
1. To correct the gateway value in the PPS7TOC8CFG.xml file, do the following: v Open the PPS7TOC8CFG.xml file in a text editor. v Locate the <c8gateway> section and update the gateway to the correct value. v Rerun the bookmark migration utility. 2. To correct the gateway value in the bookmark migration output file, do the following: v Open the output file generated by the bookmark migration utility. v For each bookmark in the output file, update the gateway to the correct value.
Appendix A. Troubleshooting
117
Related concepts: Report Settings on page 46 You can use the report settings to customize your IBM Cognos PowerPlay application.
v In PowerPlay Enterprise Server (PPES), the Lightweight PDF Generation setting is enabled for the root folder and disabled for the folder. The source report inherits the setting from the folder.
118
v In IBM Cognos Connection, the Lightweight PDF Generation setting is disabled for Public Folders. The published folder inherits the setting from Public Folders and the published report inherits the setting from the folder. v For the Migrated Content folder, the Lightweight PDF Generation setting is enabled, as it is taken from the PPES root folder. The IBM Cognos Connection folder inherits the setting from the Migrated Content folder. The migrated folder inherits the setting from the IBM Cognos Connection folder, and the migrated report inherits the setting from the migrated folder. To resolve the problem, explicitly set the Lightweight PDF Generation setting that you want in the source report, the migrated report, or one of the migrated reports. Alternatively, set the option to include or exclude fonts in the migration task.
Connection Error When PowerCube File Name Includes Simplified Chinese Characters
When IBM Cognos PowerPlay is installed on an IBM AIX computer, you may encounter the following error when connecting to a PowerCube that has Simplified Chinese characters in the file name. The error can occur when testing the data source connection or when opening a package based on the PowerCube.
The cube was not opened successfully. PDS-PPE-0084 No error message is available. {0}ppdsweb/source/CExecCrosstab.cpp(1313): CPPWebException: CCL_THROW: CExecCrosstab::Execute
To prevent this error, rename the cube to use English characters, and remove native characters from the cube name. Another option is to use UTF-8 characters for Simplified Chinese (GB2312) code points when you create the data source
Appendix A. Troubleshooting
119
connection. These characters will appear incorrectly in Cognos Connection, however, the connection will work correctly.
Error When Opening the Link in the Email for a Scheduled Report
When a user schedules a report to run and requests the delivery option to be email, only the most recently sent email will contain a valid link. Any previous email will contain a link to a report that no longer exists and result in either a blank page or a page not found error.
After Exporting to PDF the Label for the OTHER Category in a Pie Chart Changes to Actual Category Name
When creating a pie chart in IBM Cognos PowerPlay Studio, the OTHER category is generated and is visible in the legend. After exporting to PDF, the correct category name replaces OTHER in the legend. This is the expected behavior.
120
Delimiter Used for Export to CSV Different from IBM Cognos Series 7
By default, IBM Cognos PowerPlay uses a tab delimiter for export to CSV file. This behavior is consistent with other IBM Cognos studios. To change the delimiter format, modify the advanced settings for the PowerPlay service. Related concepts: Configuring Advanced Settings for the PowerPlay Service on page 30 You can use advanced settings to customize your IBM Cognos PowerPlay environment.
To prevent this error use a different supported database for the IBM Cognos BI content store.
Appendix A. Troubleshooting
121
122
123
For IBM Cognos Business Intelligence, the complete syntax is http:// webservername:portnumber/ibmcognos/cgi-bin/cognos.cgi. If you configured IBM Cognos BI 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 IBM Cognos Business Intelligence Installation and Configuration Guide. The supported gateways are listed in the following table:
Table 43. Supported gateways Gateway ISAPI Apache Connector (Microsoft Windows operating system) Apache Connector (Solaris and AIX) URL http://webservername/ibmcognos/isapi http://webservername/ibmcognos/cgi-bin/ mod_cognos.dll http://webservername/ibmcognos/cgi-bin/ mod_cognos.so http://webservername/ibmcognos/cgi-bin/ mod_cognos.sl http://webservername:9300/ServletGateway/ servlet/Gateway http://webservername/ibmcognos
Gateway Servlet
CGI
URL Methods
There are two methods to start most 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 many UI tasks.
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.
124
You can use these commands to browse content in IBM Cognos Connection or view pages in IBM Cognos Viewer.
followed by the specific component parameters you want to use. If you want to start IBM 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: v gateway This is the mandatory argument value that specifies the IBM Cognos BI gateway. The gateway name in this example is http://server/ibmcognos/cgibin/cognos.cgi?. IBM Cognos Application Firewall validation is enforced on URLs that contain this parameter. For more information see, URL Validation. v b_action=xts.run Identifies the action. To specify IBM Cognos Viewer, use b_action=cognosViewer. v m=portal/launch.xts&ui.tool=tool_name Identifies the IBM Cognos BI component interface that displays the result. To start IBM Cognos Connection, use m=portal/cc.xts. v ui.action Specifies the action to take. Acceptable values for the Studio components are new and edit. The default is new. Acceptable values for IBM Cognos Viewer are run and view. The default is view.
URL Validation
IBM Cognos Application Firewall validation is enforced on URLs using the following rules. v Fully qualified, or absolute 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 IBM Cognos Business Intelligence Installation and Configuration Guide. v URLs relative to the IBM Cognos BI installation web root: /<install root>/.* Where <install root> is the gateway file path, taken from the Gateway URI from Cognos Configuration Tool. For example, /ibmcognos/ps/portal/images/. v One of the following specifically allowed URLs:
Appendix B. Performing tasks in IBM Cognos BI using URLs
125
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.
The b.action, TARGET, and ui.action parameters are mandatory. v The b_action parameter directs the incoming requests to the appropriate service. v The TARGET parameter identifies the name and location of the report object. The TARGET parameter is usually the search path of the report object being used. v The ui.action parameter specifies the action to take. The acceptable values are run and edit. The FORMAT, FILTER, and PROMPT parameters are optional. v The FORMAT parameter specifies the output format. Acceptable values are PDF and HTML. v The FILTER parameter specifies the context of the package or report. The parameter requires a URL-encoded value of Dimension Code1<tab>PPDSID Code<tab>Dimension Code2<tab>PPDSID Code. You can only use one PPDSID Code per Dimension Code. You cannot pass multiple values to the same dimension.
126
v The PROMPT parameter specifies whether the client report with dimension line filtering displays the dimension line filtering page. This setting only applies to published reports in PDF format with dimension line filtering enabled.
127
128
129
v the IBM Cognos BI server The IBM Cognos BI server relies on the JVM used to run IBM Cognos BI to perform character mappings. Even if you are using the same JVM vendor for IBM Cognos BI and ppsrvadm, the two servers may map some Shift-JIS characters to different Unicode codepoints. If any of the encoding points do not employ the same characters mappings, you must either change cube and report names to remove the problem characters or reconfigure characters to make them use the same mapping.
0x2141
0x8160
U+301C U+FF5E
0x2142
0x8161
U+2016 U+2225
0x215D
0x817C
U+2212 U+FF0D
0x216F
0x818F
U+00A5* U+FFE5
130
Table 44. Shift-JIS characters that can cause problems in migration (continued) JIS bytes 0x2171 Shift-JIS bytes 0x8191 Unicode codepoints U+00A2 U+FFE0 0x2172 0x8192 U+00A3 U+FFE1 Description Cent sign Fullwidth cent sign Pound sign Full width pound sign Not sign Full width not sign
0x224C
0x81CA
U+00AC U+FFE2
Related tasks: Reconfigure the Shift-JIS Characters to Unicode Mapping You can fine tune the mapping from Shift-JIS to Unicode and back that the IBM Cognos Series 7 migration service uses by placing a configuration file named shift-jis.xml in your s7_location\migs7 directory.
Procedure
1. Start the Round Trip Safety Configuration utility: v On the Microsoft Windows operating system, double-click c10_location\bin\rtsconfig.bat. v on the UNIX operating system, run the command c10_location/bin/rtsconfig. 2. In the Conversion tab, specify how to render the listed Unicode characters to Shift-JIS. 3. In the Substitution tab, specify how certain Shift-JIS characters are rendered into Unicode. 4. Save your changes.
Appendix C. Japanese Shift-JIS Character Mapping
131
The file c10_location\bin\shift-jis.xml is updated. 5. Copy the shift-jis.xml file to the s7_location\migs7 location. 6. If you need to manually edit the file, open the file in the s7_location\migs7 location using an XML or text editor and make the changes that you want. 7. Create an environment variable named PYCODECS_MAP_DIR and point it to the s7_location\migs7 folder. For example, C:\Program Files\Cognos\cer5\migs7. Note: In Windows, you must make this a system environment variable and not a user variable so that it is accessible to the IBM Cognos Series 7 migration service. 8. Stop and restart the IBM Cognos Series 7 migration service: v On Windows, change to the s7_location/migs7 directory, and use the following command: configure.exe --stop To restart the service, use the following command: configure.exe --start v on the UNIX operating system, change to the s7_location/migs7 directory, and use the following command: ./configure --stop To restart the service, use the following command: ./configure --start
Results
Note: If you leave a copy of your shift-jis.xml file in the c10_location\bin directory, it will affect IBM Cognos BI's run-time behavior when interacting with end users and with databases that do not provide their own conversion mechanisms. If you do not want to change this behavior, restore the shift-jis.xml file located in the c10_location\bin\folder to the backup version. Related concepts: Appendix C, Japanese Shift-JIS Character Mapping, on page 129 When migrating reports or cubes whose names contain Japanese characters, issues may occur because there is no industry standard for mapping byte sequences from Shift-JIS characters to and from Unicode. The shift-jis.xml File Does not Appear to Affect the Mappings Used on page 133 After making changes to the shift-jis.xml file, the mappings used are not affected.
132
Before you edit the shift-jis.xml file, you must become familiar with the file format. The following example specifies that when the Unicode character U+2116 is encountered, it is converted to Shift-JIS 0x8782.
<conversion> <entry id="1"> <unicode>U+2116</unicode> <native selected="true">0x8782</native> <native>0xFA59</native> <references> <reference>9333</reference> <reference>9334</reference> </references> </entry>
The following example specifies that when a Shift-JIS sequence can map to either U+00A2 or U+FFE0, it is mapped to U+FFE0.
<substitution> <entry id="1"> <codepoint value="U+00A2" replaceWith="U+FFE0"/> <codepoint value="U+FFE0" replaceWith="U+FFE0"/> </entry>
The shift-jis.xml File Does not Appear to Affect the Mappings Used
After making changes to the shift-jis.xml file, the mappings used are not affected. To resolve the problem, try one of the following: v Verify that the files s7_location\migs7\rtssubstitution.dat and s7_location\migs7\rtsconversion.dat were created and are newer than the s7_location\migs7\shift-jis.xml file. If this is not the case, stop and restart the IBM Cognos Series 7 migration service. v Verify that the .dat files are readable by the userid under which the IBM Cognos Series 7 migration service is running. For example, on Windows, the Local System account may not have read access to the files. v Turn on debug logging by setting the system environment variable PYCODECS_MAP_DEBUG to 1 and then restarting the IBM Cognos Series 7 migration service. This generates the text file %PYCODECS_MAP_DIR%\ PyCodec.txt that may help diagnose the problem.
133
Related concepts: Multibyte Error Message Appears During a Migration When performing a migration, the following error message appears: Related tasks: Reconfigure the Shift-JIS Characters to Unicode Mapping on page 131 You can fine tune the mapping from Shift-JIS to Unicode and back that the IBM Cognos Series 7 migration service uses by placing a configuration file named shift-jis.xml in your s7_location\migs7 directory.
To resolve the problem, try one of the following: v If you created a shift-jis.xml file, check for the presence of the byte sequence in the file. Verify that both a forward (substitution) and reverse (conversion) mapping were defined. For example, if you defined the substitution U+2015 -> U+2014, you should also define the conversion U+2014 -> 0x815C. v Verify that your mappings are loading as expected by enabling PYCODECS_MAP_DEBUG. Related concepts: The shift-jis.xml File Does not Appear to Affect the Mappings Used on page 133 After making changes to the shift-jis.xml file, the mappings used are not affected.
The IBM Cognos Series 7 Migration Service Cannot Open a PowerPlay File Containing Problematic Characters
When performing a migration, the migration service reports that it cannot open a .ppx file containing problematic characters. To resolve the problem, try one of the following: v Verify that the IBM Cognos PowerPlay report exists in the correct location and that it can be opened by the userid under which the migration service is running. v If your file system is storing file names in Unicode, you may need to define a shift-jis.xml file that explicitly maps the problematic characters in the same way that the file system does. For example, for the NTFS file system on Windows, you likely need the following mappings.
Table 45. Mapping SHIFT-JIS characters to Unicode characters Shift-JIS 0x815C 0x8160 0x8161 0x817C 0x818F Unicode U+2015 U+FF5E U+2225 U+FF0D U+FFE5
134
Table 45. Mapping SHIFT-JIS characters to Unicode characters (continued) Shift-JIS 0x8191 0x8192 0x81CA Unicode U+FFE0 U+FFE1 U+FFE2
135
For example, the PPES service is using a Japanese name encoded in Shift-JIS using the Solaris operating system locale ja_JP.PCK and the IBM Cognos BI server is running in the locale ja_JP.UTF-8. As a result, the migration of reports that depend on the PowerCube fails with error messages like the following: MGD-msg-0424 Unable to create the following data source in IBM Cognos BI: cubes/Japanese/<Japanese characters> MGD-msg-0422 MigDeploy Exception: MGD-msg-0432 Invalid data source parameters. The path to the physical cube is not specified. The procedure to work around the problem depends on whether you want to use the same or different locale setting in IBM Cognos BI as in IBM Cognos Series 7. If you want to use the same locale setting in IBM Cognos BI as in Series 7, set language environment variables to match those used when starting Series 7 PPES. If you want to use a different locale setting in IBM Cognos BI, make a copy of the PowerCube under the locale's encoding. Note that you will probably need to use a custom shell or other file-copy utility because entering file names using two separate encodings at a shell command prompt may not work.
Procedure
1. To set language variables to match those used when starting Series 7 PPES, do the following: v Set the LANG, LC_ALL, and if applicable, LC_CTYPE environment variables to match those that were used when starting IBM Cognos Series 7 PPES. For example, LANG= ja_JP.UTF-8. v Launch c10_install/bin/cogconfig.sh. v Restart the IBM Cognos service. v Redo the migration. 2. To make a copy of the PowerCube under the locale's encoding, do the following: v Copy the PowerCube .mdc file on disk from its name under the old locale's encoding to its new name under the new locale's encoding. For example, to move the file "cubes/Japanese/Japanese characters.mdc" from ja_JP.PCK to ja_JP.UTF-8, copy the file named ".../cubes/Japanese/\x93\xfa\x96{\x8c\xea\x82\xcc\x83L\x83\x85\ x83u.mdc" to the new filename ".../cubes/Japanese/\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e\xe3\x81\ xae\xe3\x82\xad\xe3\x83\xa5\xe3\x83\x96.mdc" v Redo the migration.
Unable to Migrate Because Content Manager Reports Object with Same Name Already Exists
When running a migration task, the Content Manager reports an error in the run history details that an object with the same name already exists, and the migration is unable to continue. If you then query the Content Manager database, you cannot find the object.
136
This problem occurs only when the Content Manager is a Microsoft SQL Server database, and is caused by the existence of an object in the Content Manager database that contains a variant of one of the characters in the object name. For example, the object you are migrating contains the Unicode character U+00A2 (cent sign), and an object with the Unicode character U+FFE0 (full-width cent sign) exists in the database. To resolve the problem, do one of the following before migrating: v In the Content Manager database, delete the object that is stopping the migration. v Recreate the Content Manager database using the collation sequence Latin1_General_CI_AS_KS_WS instead of Latin1_General_CI_AS. By creating the Content Manager database using a collation sequence that includes width-sensitive characters (_WS), you will avoid conflicts with objects that contain both half-width and full-width variants of the same character in their names.
137
138
Notices
This information was developed for products and services offered worldwide. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. This document may describe products, services, or features that are not included in the Program or license entitlement that you have purchased. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: Intellectual Property Licensing Legal and Intellectual Property Law IBM Japan Ltd. 19-21, Nihonbashi-Hakozakicho, Chuo-ku Tokyo 103-8510, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
Copyright IBM Corp. 2005, 2013
139
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Software Group Attention: Licensing 3755 Riverside Dr Ottawa, ON K1V 1B7 Canada Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. If you are viewing this information softcopy, the photographs and color illustrations may not appear.
140
Trademarks
IBM, the IBM logo and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at Copyright and trademark information at www.ibm.com/legal/copytrade.shtml. The following terms are trademarks or registered trademarks of other companies: v Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. v Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both. v UNIX is a registered trademark of The Open Group in the United States and other countries. v Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.
Notices
141
142
A
administration 29 advanced configuration settings RSVP.RENDER.VALIDATEURL 125 advanced settings PowerPlay 30, 32 aliases Series 7 server name 61 applications migrating 51 auditing database 81 connection string 93 creating the database 93 running the PPESAuditFileProcessor utility
E
error message RSV-VAL-0003 116 export formats Microsoft Excel 2007 2
F
failed to load csx file troubleshooting 115
94
G
graphic types supported 15
B
bookmarks incorrect URL in migrated bookmarks migrating 69 117
I
IBM Cognos performing tasks using URLs 123 starting components using URLs 126 IBM Cognos Administration 29 IBM Cognos Application Firewall 125 IBM Cognos Business Insight 2 IBM Cognos Connection empty folder named cubes created after migration migrating content from 54 IBM Cognos Migration Assistant 62 Personal NewsBoxes are hidden in tree view 113 IBM Cognos Series 7 migration service potential memory leaks 111 Internet Explorer error in PowerPlay Studio calculation 120 introduction vii
C
CAF 125 checklist for migration 58 connection string for audit database 93 content what gets migrated 54 Content Manager database unable to migrate because of name conflict 137 csv delimiter 121 cube mapping errors 109 cubes settings 33 cubes, See PowerCubes custom views appear as broken links when migrated a second time
114
115
J
Japanese characters 129 mapping to Unicode 131
D
data sources supported 14 databases tables for log messages 84 distributed installations administration considerations drill through advanced settings 30 Copyright IBM Corp. 2005, 2013
L
29 launch IBM Cognos PowerPlay using a URL lightweight PDF generation not migrated 118 setting 117 local reports migrating 67 126
143
locales troubleshooting problems when migrating logging audit database 81 logging levels setting 81, 107 logs database tables for messages 84 migration 107
110
O
offline data access 15
P
packages 52 PowerCubes migrating 52 setting up the sample for PowerPlay 77 PowerPlay advanced settings 30, 32 PowerPlay audit database 81 PowerPlay Client opening remote reports 14 PowerPlay Connect 15 PowerPlay Enterprise Server migrating content from 57 security requirements when migrating Upfront content 112 PowerPlay reports unsupported objects 57 PPESAuditFileProcessor utility 94
M
mapping Shift-JIS to Unicode 129 memory allocation leaks in IBM Cognos Series 7 migration service 111 Microsoft Excel 2007 export format 2 migrating 51 bookmarks 69 checklist 58 content 54 cubes 54 local reports 67 PowerCubes 52 reports 54 using the IBM Cognos Migration Assistant 62 migration apostrophe in folder name not migrated 114 cannot connect to Upfront server during migration 112 custom views migrated a second time appear as broken links 115 drill through properties may need altering after migration 112 empty folder named cubes created 114 error when migrating Upfront content from a Series 7 distributed environment 115 folder name not in correct language 110 folders in Upfront personal NewsBox not migrated 117 log files 107 migrating cubes with non-ASCII characters on AIX 136 problems migrating reports with long names 113 ranks not migrated to Analysis Studio when applied to axis with custom subset and one or more categories 116 S7S error when migrating a NewsBox 112 unable to migrate reports on UNIX when path names contain certain European characters 115 unable to run report with a single measure in Report Studio 116 Upfront contact information not migrated 114 migration approach 52 migration task cube mapping errors 109 enabling users 30 modifying delimiter for csv files 121 Mozilla Firefox error in PowerPlay Studio calculation 120
R
ranking not migrated to Analysis Studio when applied to axis with custom subset and one or more categories 116 remote reports opening in PowerPlay Client 14 report format .ppr files 14 reports drilling through 22 settings 33 RSVP.RENDER.VALIDATEURL 125
S
sample PowerCube setting up 77 sample reports Profit Margin and Revenue by Country or Region 26 Total Revenue by Country or Region 26 security requirements for migrating Upfront content 112 Series 7 distributed environment migration error when PPES services are stopped 115 Series 7 migration service error when starting 115 Series 7 server names defining aliases 61 server groups 29 setting logging levels 81 settings cube 33 drill through 33 report 33 shift-JIS characters troubleshooting 133 Shift-JIS characters 129 mapping to Unicode 131 single signon requirements when migrating from Upfront 112
N
NewsBoxes hidden in tree view of IBM Cognos Migration Assistant 113 S7S error when migrating 112
144
126
U
Unicode mapping to Shift-JIS 131 Upfront cannot connect to server during migration 112 cannot migrate content if PowerPlay Enterprise Server is not secured 112 contact information not migrated 114 folders in personal NewsBox not migrated 117 migrating content from 55 S7S error when migrating a NewsBox 112 URL validaton 125 URLs recommended practices 123 starting IBM Cognos components 126 starting IBM Cognos PowerPlay 126 URLS accessing services using 123 performing tasks in IBM Cognos 123 url_xml 123 users enabling to run a migration task 30
T
tables database for log messages 84 tasks performing in IBM Cognos using URLs 123 troubleshooting apostrophe in folder name not migrated 114 cube mapping errors 109 custom views migrated a second time appear as broken links 115 empty folder named cubes created after migration 114 error when migrating Upfront content from a Series 7 distributed environment 115 error when starting Series 7 migration service 115 incorrect URL in migrated bookmarks 117 Japanese characters 129 lightweight PDF generation setting not migrated 118 migrating cubes with non-ASCIII characters on AIX 136 migrating reports with long names 113 migration folder name not in correct language 110 PDF output of migrated report does not display correctly 117 problems when migrating Shift-JIS characters 133 unable to migrate because CM reports object with same name exists 137 unable to migrate because locale not configured or mapped in IBM Cognos Configuration 110 unable to migrate reports on UNIX when path names contain certain European characters 115 Upfront contact information not migrated 114
V
validation URL 125
W
working offline 15
Index
145