ug_mig

Cognos(R) 8 Business Intelligence Migration
Tools Readme
Cognos 8 Migration Tools User Guide
USER GUIDE
Cognos (R) 8 Business Intelligence
MIGRATION TOOLS
USER GUIDE

Product Information
This document applies to Cognos (R) 8 Migration Tools Version 8.2 and may also apply to subsequent releases. To check for newer versions of
this document, visit the Cognos Global Customer Services Web site (http://support.cognos.com).
Copyright
Copyright (C) 2007 Cognos Incorporated.
Portions of Cognos(R) software products are protected by one or more of the following U.S. Patents: 6,609,123 B1; 6,611,838 B1; 6,662,188
B1; 6,728,697 B2; 6,741,982 B2; 6,763,520 B1; 6,768,995 B2; 6,782,378 B2; 6,847,973 B2; 6,907,428 B2; 6,853,375 B2; 6,986,135 B2;
6,995,768 B2; 7,062,479 B2; 7,072,822 B2.
Cognos and the Cognos logo are trademarks of Cognos Incorporated in the United States and/or other countries. All other names are
trademarks or registered trademarks of their respective companies.
While every attempt has been made to ensure that the information in this document is accurate and complete, some typographical errors or
technical inaccuracies may exist. Cognos does not accept responsibility for any kind of loss resulting from the use of information contained in
this document.
This document shows the publication date. The information contained in this document is subject to change without notice. Any
improvements or changes to either the product or the document will be documented in subsequent editions.
U.S. Government Restricted Rights. The software and accompanying materials are provided with Restricted Rights. Use, duplication, or
disclosure by the Government is subject to the restrictions in subparagraph (C)(1)(ii) of the Rights in Technical Data and Computer Software
clause at DFARS 252.227-7013, or subparagraphs (C) (1) and (2) of the Commercial Computer Software - Restricted Rights at
48CFR52.227-19, as applicable. The Contractor is Cognos Corporation, 15 Wayside Road, Burlington, MA 01803.
This software/documentation contains proprietary information of Cognos Incorporated. All rights are reserved. Reverse engineering of this
software is prohibited. No part of this software/documentation may be copied, photocopied, reproduced, stored in a retrieval system,
transmitted in any form or by any means, or translated into another language without the prior written consent of Cognos Incorporated.

Table of Contents
Introduction 9
New Features 11
PART 1: Migration Planning 13
Chapter 1: Where Do I Start? 15
What to Expect When You Move Content from Cognos Series 7 to Cognos 8 17
Cognos Series 7 Products and Components Migrated With Tools 17
Cognos Series 7 Products and Components Not Migrated With Tools 19
Chapter 2: The Migration Process 21
PART 2: Migrating Cognos Series 7 Content to Cognos 8 25
Chapter 3: Migrating Metadata 27
Common Pre-migration Tasks 28
Export Architect Models 29
Architect Model Migration Tool 30
Export Impromptu Catalogs 32
impcat2xml 33
Create Data Source Connections in Cognos 8 35
Import Metadata into Framework Manager 35
Common Post-migration Tasks 35
Testing the Imported Metadata 36
Publishing a Framework Manager Package 37
Synchronize a Framework Manager Project with Updated Cognos Series 7 Metadata 37
Chapter 4: Migrating Applications 39
Preparing the Application for Migration 41
Preparing the Migration Source 41
Create the Migration Source Using a Deployment Manager Package 41
Create the Migration Source Using a Directory Structure 42
Create a Migration Package 42
migratetoc8 43
Migration Package 46
Move the Migration Package to Cognos 8 46
Check Package Mapping 47
Deploy the Migration Package 48
Choosing the Target Studio for Migrated Reports 48
deploytoc8 49
Migration Deployment Archive 51
Import a Deployment Archive 51
Review the Migration Log File 51
Test the Migration 51
Provide Users With Access to the Migrated Application 52
Chapter 5: Migrating PowerPlay Reports Published to Cognos 8 53
Configure Cognos 8 to Support PowerPlay Report Migration 53
Migrate a Published PowerPlay Report to Analysis Studio or Report Studio 54
Published PowerPlay Reports Migrated to Cognos 8 Log Files 54
User Guide 3

PART 3: Mapping Cognos Series 7 Objects to Cognos 8 Objects 55
Chapter 6: Impromptu Catalog Mapping 57
Mapping Objects in the Physical View 57
The Catalog 58
Tables and Table Aliases 58
Table Columns 59
Joins 59
Mapping Objects in the Business View 59
Folders 60
Folder Columns 60
Calculations 60
Conditions 61
Prompts 61
Migrating Expressions 62
User Defined Functions 62
Objects Not Migrated 62
Chapter 7: Impromptu Reports Mapping 65
Report Functionality Mapping 65
Impromptu Report Formatting Mappings 67
Chapter 8: PowerPlay Mapping 71
Report Structure Mappings 71
Layers 72
Report Functionality Mappings 73
Custom Exception Definitions and Formatting 75
Zero Suppression 75
Advanced Subsets 78
Find Subsets 78
Prompts 78
Report Formatting Mappings 79
Graphical Display Mappings 81
Mappings of Other PowerPlay Objects 85
Differences Between PowerPlay and Analysis Studio 85
Chapter 9: Upfront Mapping 91
Content Mapping 91
NewsBox Mapping 91
NewsBox Shortcut Mapping 92
NewsItem Mapping 92
NewsItem Shortcut Mapping 93
Mappings of Other Upfront Objects 93
Security 93
Chapter 10: Impromptu Web Reports Mapping 95
Report Set Mappings 95
Report Mappings 95
Schedule Mappings 96
Event Mappings 97
Mappings of Other Impromptu Web Reports Objects 97
Chapter 11: Architect Mapping 99
Architect Model Security 99
Security by Value 100
Migrating Expressions 100
Mapping Architect Business Layer Metadata 101
Entities Folders 101
Entities 102
Attributes 103
4 Migration Tools

Attribute Proxies 103
Filters Folders 104
Filters 105
Relationships 106
Subtype Relationships 106
Prompts 107
Mapping Architect Data Access Layer Metadata 108
Database Folders 108
Databases 109
Catalogs 110
Schemas 110
Tables 111
Views 112
SynonymViews 113
Synonyms 114
Columns 115
Keys 116
SQL Query Folders 117
SQL Queries 117
Stored Procedures 118
Stored Procedure Parameters 119
Stored Procedure Return Parameters 119
Indexes 120
Physical Joins 121
Mapping Architect Package Layer Metadata 122
Package Folders 122
Packages 123
Subject Folders 124
Subject Filters 124
Subject Prompts 125
Subject Entities 125
Subject Attributes 126
Chapter 12: Impromptu Functions Mapping 127
PART 4: Appendices 131
Appendix A: Troubleshooting 133
Log Files 133
Problems with the Command Line Tools 134
Command Fails to Run with Special Character in File Path 134
Problems Migrating Metadata 134
Metadata Objects Are Missing After Migration 134
Exception Raised 135
Prompted to Log On During Metadata Export 135
Failed to Open Model, Terminating XML Generation 135
Logon Prompts While Migrating Catalogs 135
Problems Migrating a Non-English Impromptu Catalog 135
Unable to Start the Impromptu Automation Server 135
Unable to Open an Impromptu Catalog 136
You Cannot Open Catalog as Creator When Running User Version of Impromptu 136
Problems Importing Metadata into Framework Manager 136
XML Validation Error Occurs When Importing XML Files into Framework
Manager 136
Query Items in an Impromptu Subfolder Are Represented by Calculation Icons in
Framework Manager 136
Unexpected Results with Filters After Migrating Architect Models 137
Incorrect Decimal Separators After Importing Architect Model Metadata 137
User Guide 5

6 Migration Tools
Problems Migrating Applications 137
Unable to Open the Catalog for the Following Impromptu Report 137
Errors Migrating Large Applications 137
Same Problems Occur When Migrating Reports 137
Unable to Find the Source Folder Containing the Images to be Migrated 137
An Impromptu Report Cannot Be Accessed 138
Packlets Cannot Be Found 138
Categories Missing from a Migrated PowerPlay Report that Includes Child Categories
That Do Not Roll Up 138
Suppressed Categories Replaced by Children Categories in Migrated PowerPlay Explorer
Reports 138
Problems Deploying Migrated Applications 139
Login to Cognos 8 Failed. Please Verify Credential Information 139
CM-REQ-4024 Name Conflict 139
JRE Not Found. Cannot Run the Migration Tool 139
None of the Packages Listed in the nameMap.xml file Were Found in the Content
Store 139
Problems Running Migrated Reports 140
Migrated Impromptu Report Fails to Run or Runs with Errors 140
Automatic Summary for the Entire Impromptu Report Does not Appear in Migrated
Report 140
Report Was Not Migrated 140
Missing Images in Migrated Reports 141
Using Generic Mapping for Function Error for Migrated Impromptu Report 141
The Following Function Is not Supported Error for Migrated Impromptu Report 141
The Following Function is Mapped as an Expression Using the Cast Operation Error for
Migrated Impromptu Report 141
The Following Function is Mapped as a No-Operation Error for Migrated Impromptu
Report 142
The Following Function is Mapped as a No-Operation on the First Argument Error for
Migrated Impromptu Report 142
The Following Function is Mapped as a Constant Value of Zero Error for Migrated
Impromptu Report 142
The Following Function is Mapped as a Constant Number Error for Migrated
Impromptu Report 142
Unable to Open the Catalog Error for Migrated Impromptu Report 142
Report Objects Not Found When Running Reports 142
Parsing Error Message When Migrated Impromptu Report Fails to Run 143
Incorrect Results from Date/Time Functions for Migrated Impromptu Report 143
Report Fails to Run with Function Expression Errors for Migrated Impromptu
Report 143
Missing Information in Cognos 8 Error Messages 143
The Following Package Was Not Found in the Content Store 144
Referenced Data Item is Not Found in the Query 144
Run-time Error in Conditional Formatting Expression for Migrated Impromptu
Report 144
An Unhandled Application Error Has Occurred 144
The Report Server is Not Responding 145
Unexpected Sorting of Grouped Items for Migrated Impromptu Report 145
Unable to Run a Report Against a Migrated Architect Model 145
QFS-ERR-0140 Referenced data item 'Not Found' Error for Migrated Impromptu
Report 145
Migrated Impromptu Report Takes Longer Than Expected 145
Data in Migrated Impromptu Report Containing a Master/Detail Query and Filter Is not
Filtered 145
Invalid Operands in Calculation for Migrated PowerPlay Report 146
Report Cells Contain -- or #!Error for Migrated PowerPlay Report 146

Migrated PowerPlay Report Has Extra or Missing Rows and Columns 146
PowerPlay Reports that Reference Missing Categories Migrate Improperly or Will Not
Run 146
Rank Values Are Different in Migrated Report 146
Additional Summary Rows Appear in Migrated PowerPlay Web Reports 147
Using Generic Mapping for Variable Error for Migrated PowerPlay Report 147
The Following Variable Is not Supported Error for Migrated PowerPlay Report 147
Problems with Report Formatting 147
A Report Looks Different in Cognos 8 Than in Impromptu 147
Missing Headers or Footers 147
Charts or Images Do Not Appear Correctly 147
Incorrect Page Breaks or Blank Pages for Migrated Impromptu Report 148
Pie Chart Does Not Show Any Segments in Migrated PowerPlay Report 148
Duplicate Categories in Migrated PowerPlay Reports That Contained Custom
Subsets 148
Row of Data Missing in Analysis Studio for Migrated PowerPlay Report 148
Charts Do Not Display Correctly 148
An Extra Column Appears in the Migrated PowerPlay Report 149
Shared Custom Exception Definition Is not Applied in Migrated PowerPlay Report 149
Problems with Security 149
Access Control List is Not Migrated as Expected 149
Appendix B: Samples 151
Cognos Series 7 Content 151
Transformer Model Samples 151
PowerCube Samples 151
PowerPlay Report Samples 152
Impromptu Catalog Sample 152
Impromptu Web Reports Report Samples 152
Migrated Content 152
PowerPlay Report Samples 152
Impromptu Web Reports Report Samples 157
PART 5: Worksheets 159
Migration Worksheet 161
Index 163
User Guide 7

8 Migration Tools

Introduction
This document is intended for use with the migration tools, which convert metadata, Impromptu
catalogs and reports, PowerPlay reports, and Upfront content to Cognos 8.
For information about upgrading Cognos ReportNet 1.1, Cognos Metrics Manager, or Cognos
DecisionStream to Cognos 8, see the Cognos 8 Installation and Configuration Guide.
This document provides background information and step-by-step procedures to help you move
metadata and applications from Cognos Series 7 to Cognos 8.
Audience
To use this guide, you should have background knowledge in report authoring, metadata
modeling, and security and server administration. You should also know how to use the Cognos
Series 7 product you are migrating from, and the Cognos 8 product you are migrating to. We
recommend that you learn how to use Cognos 8 before starting migration. You should not use
migration as a way to learn Cognos 8.
Related Documentation
Our documentation includes user guides, getting started guides, new features guides, readmes, and
other materials to meet the needs of our varied audience. The following documents contain related
information and may be referred to in this document.
Note: If an error message appears when you click a document name, search the Documentation
library of the Cognos Global Customer Services Web site (http://support.cognos.com). If you
require logon credentials, consult your administrator or send an email to
support.america@cognos.com.
Document
Planning a Migration from Series 7 to
Cognos 8 BI
Migration Tools Installation and
Configuration Guide
Cognos Series 7 Deployment Manager User
Guide
Cognos 8 Installation and Configuration
Guide
Cognos 8 Administration and Security
Guide
Cognos Connection User Guide
Report Studio User Guide
Analysis Studio User Guide
Description
Planning a migration from Series 7 to Cognos 8 BI
and understanding the migration options
Planning and preparing for a migration, installing
and configuring the Cognos 8 migration tools
Packaging Cognos Series 7 business intelligence
data
Installing, upgrading, configuring, and testing
Cognos 8, changing application servers, and
setting up samples
Managing servers, security, reports, and Portal
Services; setting up Cognos samples; and
customizing Cognos 8
Using Cognos Connection to publish, find,
manage, organize, and view Cognos content, such
as scorecards, reports, analyses, and agents
Authoring reports that analyze corporate data
according to specific needs
Exploring, analyzing, and comparing dimensional
data
User Guide 9

Introduction
Document
Framework Manager User Guide
Framework Manager Guidelines for
Modeling Metadata
Cognos 8 Troubleshooting Guide
Cognos 8 Software Development Kit
Developer Guide
Description
Creating and publishing models using Framework
Manager
Recommendations for modeling metadata to use
in business reporting and analysis
Helping administrators to quickly identify and
solve problems
Managing Cognos 8 processes and implementing
custom reporting solutions by using a collection
of cross-platform Web services, libraries, and
programming interfaces provided with the
Cognos 8 SDK
Finding Information
To find the most current product documentation, including all localized documentation, access the
Cognos Global Customer Services Web site (http://support.cognos.com). Click the Documentation
link to access documentation guides. Click the Knowledge Base link to access all documentation,
technical papers, and multimedia materials.
Product documentation is available in online help from the Help menu or button in Cognos
products. You can also download documentation in PDF format from the Cognos Global
Customer Services Web site, or click the following link to open a printable version of this
document (PDF).
To find the most current Cognos documentation, including all localized documentation, access the
Cognos Global Customer Services Web site (http://support.cognos.com). Click the Documentation
link to access product documentation. Click the Knowledge Base link to access all documentation,
technical papers, and multimedia materials.
PDF versions of the documentation are also available on the Cognos documentation CD.
You can also read PDF versions of the product readme files and installation guides directly from
Cognos product CDs.
Getting Help
For more information about using this product or for technical assistance, visit the Cognos Global
Customer Services Web site (http://support.cognos.com). This site provides product information,
services, user forums, and a knowledge base of documentation and multimedia materials. To
create a case, contact a support person, or provide feedback, click the Contact Us link. For
information about education and training, click the Training link.
Printing Copyright Material
You can print selected pages, a section, or the whole book. Cognos grants you a non-exclusive,
non-transferable license to use, copy, and reproduce the copyright materials, in printed or
electronic format, solely for the purpose of operating, maintaining, and providing internal training
on Cognos software.
10 Migration Tools

New Features
The following new features are introduced in this version of the migration tools.
• support for Cognos Series 7 version 7.4 only
To migrate Architect 7.4 models, you must use the arch2xml74 command. If you want to
migrate earlier Architect versions of models, such as 7.3, you must use the arch2xml
command. However, Cognos no longer supports the arch2xml command.
For more information, see "Export Architect Models" (p. 29).
• improved support for PowerPlay layers (p. 72) in migrated reports
Each layer is now migrated to a separate page in a Report Studio report.
• improved support for PowerPlay prompts in migrated reports
The content of the report now reacts to the prompt value selected by users in a manner that is
similar to PowerPlay.
• improved support for PowerPlay charts (p. 81) in migrated reports
• improved log messages that are easier to use and understand, as well as summary information
• sample model, cubes, and reports
User Guide 11

New Features
12 Migration Tools

PART 1: Migration Planning
User Guide 13

14 Migration Tools

Chapter 1: Where Do I Start?
You made the decision to adopt Cognos 8 after working with your Cognos representative to
understand the benefits of Cognos 8 and where it fits in your long-term business intelligence
plans. Even after adopting Cognos 8, you do not have to migrate existing applications. Cognos
will continue to support Cognos Series 7 for several years and flexible licensing options provide
time for you to determine when and how migration is beneficial for you. For some customers, the
best option is to not migrate their existing applications. These customers can continue to maintain
the existing Cognos Series 7 applications and use Cognos 8 for new applications.
If you decide to migrate your existing applications, a migration project requires a significant
commitment of time and resources. A small migration project will take several weeks. For a large
Cognos Series 7 deployment, a migration project can last several months. Thorough planning,
including identifying specific goals for the migration project, ensures that the migration meets
expectations and adds value to your business intelligence environment.
A migration project may be part of your initial Cognos 8 deployment plans, or you may start
migration planning after deploying Cognos 8. We recommend that you take the time necessary to
learn about Cognos 8 and to evaluate your current Cognos Series 7 applications before you start
to plan a migration. For more information, see Planning a Migration from Series 7 to Cognos 8
BI.
Cognos Global Professional Services can help you assess and understand the best way to proceed
with your migration to Cognos 8, with tools
• to assess your needs
• to assess your existing Cognos Series 7 environment
• to design the Cognos 8 environment that best meets your future needs
Understand How Cognos 8 is Different From Cognos Series 7
We recommend that you become familiar with Cognos 8 before you develop a migration plan.
Cognos 8 is different from Cognos Series 7. You should not use migration as a tool to educate you
on Cognos 8. If you do, your migration may simply re-create the same application in Cognos 8,
without taking advantage of new features and functionality.
Cognos 8 is built on the proven and scalable Web services architecture introduced with Cognos
ReportNet. This architecture supports a truly unified product suite, and it is the basis for future
development efforts at Cognos. Compared with Cognos Series 7, business users work differently
with Cognos 8:
• A single product provides all business intelligence capabilities: reporting, analysis, scorecards,
dashboards, business event management, and data integration. Users chose the capabilities
they need.
• 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.
• 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.
In addition to understanding the high-level concepts and benefits of Cognos 8, you should
understand the differences in features between Cognos Series 7 and Cognos 8. A direct mapping
for some features does not exist between Cognos Series 7 and Cognos 8. For example, in
PowerPlay, you can apply 80/20 suppression to data. Analysis Studio does not include this option.
However, the top and bottom filtering options in Analysis Studio provide greater control for
suppressing data and allow you to achieve similar results to 80/20 suppression in PowerPlay.
User Guide 15

Chapter 1: Where Do I Start?
Assess the Size and Complexity of Your Cognos Series 7 Application
We recommend that you complete a detailed assessment of your Cognos Series 7 applications
before starting a migration. The size and complexity of your Cognos Series 7 applications are
important factors to consider when planning the migration. The total size of the applications has a
significant impact on the time required to complete the migration. You must understand the
complexity of your applications to set appropriate and accurate expectations for the migration. A
detailed assessment can take several weeks to complete for large applications.
You likely will not want to migrate Cognos Series 7 content that is rarely or never used. You can
use the auditing tools included with Cognos Series 7 to identify how often content is used. The
audits provide an objective view of the applications. Assessing and reducing the size of the
applications is a useful exercise even if you decide to not migrate. Do not rely only on user
feedback to determine which content is used.
The complexity of your applications determines how much work is required to refine the content
in Cognos 8. What proportion of the reports are basic list or crosstab reports? What proportion of
the reports use advanced features, such as drill-through to other applications, or complex
formatting? For some types of reports, a relatively minor amount of work is required to refine the
reports after migration. For more complex reports, you may want to recreate the content from
scratch, or make significant changes to migrated content, to take advantage of new features and
functionality in Cognos 8. Your experience with Cognos 8 will help you to understand
functionality mapping between Cognos Series 7 and Cognos 8 and to decide if Cognos 8 offers a
better alternative for achieving the same results.
Identify How Cognos 8 Adds Value to Your Cognos Series 7 Application
We recommend that you work with your users to identify essential Cognos 8 functionality that
was not available in Cognos Series 7.
After you learn about Cognos 8 and assess your Cognos Series 7 applications, you will realize that
you do not want to use migration to simply replicate your Cognos Series 7 applications in Cognos
8. You want to take advantage of the benefits of Cognos 8 while leveraging the investment you
have in Cognos Series 7 applications.
• List the critical features in Cognos Series 7 applications. Are these features available in
Cognos 8? Do the migration tools map the feature to Cognos 8, or do you have to re-create
the feature after migration? If direct mapping in Cognos 8 does not exist, can you achieve
similar results in a different way in Cognos 8?
• List the essential Cognos 8 features that were unavailable in Cognos Series 7. Can you add
these features as enhancements to a migrated report? Should you create new reports that use
the features?
By comparing and listing important features with your users, you can start to identify which
Cognos Series 7 content is a good candidate for migration. You should migrate content if most
features map from Cognos Series 7 to Cognos 8, if the migration tools preserve all or most of the
features, and if you find it easier to enhance the migrated report with Cognos 8 features than to
re-create the report.
Decide How to Approach Migration
There are two different approaches that you can take to migration:
• Lift and shift
This approach completely replicates an existing application in the new environment. This is
what often happens when you move between different versions of a product, such as from
PowerPlay 7.0 to 7.1.
• Compress and optimize
Rather than duplicating the existing application with the new software, you step back and do
a full assessment of the business requirements and how they can best be fulfilled with the new
software before you migrate. This can mean performing tasks like consolidating Impromptu
catalogs into a smaller number of Framework Manager models or combining many reports
into one report by using prompts, security, and so on.
16 Migration Tools

Chapter 1: Where Do I Start?
Regardless of which approach you decide to take, the migration costs are usually about the same.
If you use the lift and shift approach, more of the cost and time go into doing the migration and
testing the migrated reports. If you use the compress and optimize approach, there is more cost
and time spent up front in the interview and design phases. The compress and optimize approach
usually results in applications that are better designed for the Cognos 8 architecture, require less
maintenance, and better fulfill your requirements.
The migration tools provide a lift and shift solution. They replicate what you have in Cognos
Series 7 in a Cognos 8 environment. This solution may be the right one for you. But you can also
use the migration tools to give you a head start in a compress and optimize solution. For example,
you can use the migration tools to migrate the basic metadata or queries to Cognos 8, and then
rework your reports so that they are better optimized in Cognos 8.
The size of your applications is also a factor in deciding which approach you should take. If you
have large or many applications, the compress and optimize approach may seem difficult or overly
expensive. In this case, we recommend that you do not migrate all of your applications right away.
You can build new applications in Cognos 8 and keep existing applications going in Cognos
Series 7. Over time, migrate your applications as business drivers present themselves using the
compress and optimize approach.
What to Expect When You Move Content from Cognos Series
7 to Cognos 8
Because of differences in product architecture and functionality, it is not possible to simply reuse
Cognos Series 7 metadata or applications in Cognos 8. Cognos provides migration tools to help
you take advantage of investments you have made in Cognos Series 7. However, to successfully
move to Cognos 8, in addition to using the migration tools, there is additional work required to
prepare for the migration, and to test and refine the migrated content in Cognos 8. For more
information, see "The Migration Process" (p. 21).
As part of the migration planning process, we recommend that you move a subset of your
Cognos Series 7 content and then assess the results and the amount of work required to refine the
content in Cognos 8. Sometimes only minor updates, such as formatting changes, are required in
Cognos 8. In other cases you may find that a Cognos Series 7 feature that is important to you is
not available in Cognos 8.
After testing the migration process with a subset of your Cognos Series 7 content, you can decide
if reusing the content saves time when developing a Cognos 8 application or if it is more efficient
to re-create the application in Cognos 8.
There are some differences between Cognos Series 7 and Cognos 8 that can affect how
Cognos Series 7 content appears after migration to Cognos 8. Examples of these differences
include default settings, report formatting, and language support. General considerations for
various migration scenarios are described in the following sections.
Cognos Series 7 Products and Components Migrated With
Tools
You can migrate the following products and components to Cognos 8 using the migration tools.
Impromptu
You can migrate Impromptu catalogs and reports to Cognos 8. You use migrated catalogs as a
metadata source for Framework Manager. After completing the catalog migration process, you
can migrate and deploy Impromptu reports.
PowerPlay
You can migrate PowerPlay Windows reports, PowerPlay Web Explorer reports, PowerPlay for
Excel reports, or PowerPlay for Windows reports published to PowerPlay Web to Cognos 8 using
the migration tools.
User Guide 17

Chapter 1: Where Do I Start?
You can only migrate PowerPlay reports saved in PowerPlay Portable Report (.ppx) format. If you
want to migrate PowerPlay reports saved in PowerPlay report (.ppr) format, you must open these
reports and save them in .ppx format. If you have many .ppr reports that you want to migrate,
you can create a macro using OLE automation to quickly convert them.
Cognos 8 supports the use of cubes as a data source. You do not have to migrate cubes used in
Cognos Series 7. However, before deploying migrated PowerPlay reports in Cognos 8, you must
do the following:
• Create data source connections for the cubes associated with the reports.
• Use the cube data sources in a Framework Manager model.
• Publish a separate Framework Manager package for each cube.
Use the cube name as the package name. For example, if the reports use a cube named Great
Outdoors, name the package Great Outdoors. By using the cube name for the package name,
you do not have to edit the nameMap.xml to ensure correct package mapping.
• Check package mapping.
Database signons are not migrated. If required, you must add the database signons in Cognos 8.
You can continue to use Cognos Series 7 Transformer, including the version delivered as a Cognos
8.2 component, to build and maintain .mdc-format PowerCubes for use in Cognos 8. You can
build PowerCubes that are unsecured or secured using your Cognos Series 7 namespace.
For more information about using cubes in Cognos 8, see the Cognos 8 Administration and
Security Guide.
There are two methods for migrating PowerPlay reports:
• You can use the migration tools to migrate a set of PowerPlay reports from the Cognos Series
7 environment to the Cognos 8 environment.
• If you already published PowerPlay reports from Cognos Series 7 to Cognos 8
(interoperability between Cognos Series 7 and Cognos 8 BI), and the Cognos 8 migration
tools are installed, you can migrate individual reports from Cognos 8 Cognos Connection. To
use this option, in Cognos Connection, select either Open with Analysis Studio or Open with
Report Studio from the available actions. The report is migrated to the studio you used to
open the report, and you can choose whether or not to save the migrated report. The original
PowerPlay report is still available in Cognos Connection whether or not you save the
migrated report. You must enable PowerPlay report migration capability in Cognos
Connection before you can use this option.
The migration tools preserve as much of the report structure, functionality, and formatting as
possible from the original report. However, there may be differences between the original and
migrated versions of reports.
The target Cognos 8 applications for PowerPlay reports are Analysis Studio and Report Studio. By
default, reports are migrated to Report Studio. Because equivalent report features may be
available in only one of the target studios, the deploytoc8 command includes options for mapping
reports to the most appropriate studio.
If after you migrate reports to Analysis Studio you find that functionality is missing in some
reports, run the migration tools again to migrate the reports to Report Studio. If Analysis Studio
was not the appropriate target studio, opening the report in Report Studio does not restore lost
functionality. You must repeat the migration process and specify Report Studio as the target
studio.
Upfront
You can migrate Upfront content to Cognos 8. The migration process maps the Upfront content
structure to a Cognos Connection folder structure. By preserving the existing Upfront
organization, it is easier to complete administrative tasks, such as applying security to the
migrated content.
18 Migration Tools

Chapter 1: Where Do I Start?
Impromptu Web Reports
You can migrate Impromptu Web Reports to Cognos 8. You migrate Impromptu Web Reports
using a Cognos Series 7 Deployment Manager package as the migration source. Before you
migrate Impromptu Web Reports you must migrate the Impromptu catalog metadata used by the
reports.
Note: PowerPrompts are not migrated, but you can implement similar functionality using the
Cognos 8 Software Development Kit.
Architect
You can migrate Architect models for use as a metadata source for Framework Manager.
Security
You can include Cognos Series 7 security information when you migrate Cognos Web-based
content in Upfront. The Cognos Series 7 migration tool has options for including access control
list (ACL) information from Upfront in the migration package.
By default, the migratetoc8 process generates an ACL report that shows the security settings by
user class for all Upfront objects. This report can help you replicate the Cognos Series 7 security in
Cognos 8. If Cognos 8 is configured to use the same namespace as Cognos Series 7, another
option is to migrate ACL definitions. When you migrate ACL definitions, the migrated content
maintains the original security settings in Cognos 8.
The migration process supports Access Manager namespace schema version 15.2 or later.
If you configure Cognos 8 to use the same namespace as Cognos Series 7, you maintain other
security settings:
• Impromptu catalog security such as table filters and access permissions, including when these
security settings are inherited in an Impromptu report. The user classes in the catalog must
exist in the Cognos Series 7 namespace.
• Architect model security
Migration does not include database signons.
If you decide to change authentication sources, we recommend that you use the Cognos 8
namespace groups and roles when applying application-level security. You then manage the
membership of these Cognos namespace groups and roles using the users, groups, and roles from
your authentication source.
This method ensures that you must redefine the memberships for the Cognos namespace groups
and roles only if the authentication source changes.
For more information, see the Cognos 8 Administration and Security Guide.
Cognos Series 7 Products and Components Not Migrated
With Tools
The following Cognos Series 7 products and components are not migrated by the migration tools.
However, you can duplicate most content or functionality in Cognos 8.
Cognos Query
The migration tools do not move Cognos Query objects, such as saved queries, to Cognos 8. The
migration log file identifies Cognos Query objects found in the migration source.
You can duplicate most Cognos Query functionality in Cognos 8. Foundation queries are
available in Cognos 8 when you migrate an Architect model. Also, you can manually replicate
saved queries using SQL components in Report Studio.
Cognos Visualizer
The migration tools do not move Cognos Visualizer objects to Cognos 8. You can duplicate most
Cognos Visualizer functionality using the charting, layout, and formatting options in Analysis
Studio or Report Studio.
User Guide 19

Chapter 1: Where Do I Start?
Cognos NoticeCast
The migration tools do not move Cognos NoticeCast objects to Cognos 8. You can duplicate most
alert and notification functionality using Event Studio.
Cognos Web Services
The migration tools do not move Cognos Web Services objects to Cognos 8. You can duplicate
most Cognos Web Services functionality using the Cognos 8 Software Development Kit.
CognosScript
The migration tools do not move CognosScript objects to Cognos 8. You can duplicate
automation functionality using the Cognos 8 Software Development Kit.
Cognos Portal Services
The migration tools do not move Cognos Portal Services objects to Cognos 8. You can duplicate
most Cognos Portal Services functionality using Cognos Connection.
20 Migration Tools

Chapter 2: The Migration Process
To ensure that you achieve the expected results when you move metadata and applications from
Cognos Series 7 to Cognos 8, complete a thorough initial research and planning before you use
the migration tools. After you use the tools to move the Cognos Series 7 content to the Cognos 8
environment, you need to test and refine the applications.
You can move content only from Cognos Series 7 version 4 (7.4) to Cognos 8 8.2. If you are using
an earlier version of Cognos Series 7, you must migrate the software and data to Cognos Series 7
version 4 (7.4) before the migration to Cognos 8.
Note: The report specification has changed between Cognos ReportNet 1.1 and Cognos 8. You
must use the Cognos ReportNet 1.1 version of the migration tools to move Cognos Series 7
content to Cognos ReportNet 1.1. You cannot use the migration tools described in this document
to migrate Architect models, Impromptu catalogs, or Impromptu reports to Cognos ReportNet
1.1. You cannot migrate Cognos Series 7 Web-based content (PowerPlay, Impromptu Web
Reports, Upfront) to Cognos ReportNet 1.1. For information about obtaining the migration tools,
see the Migration Tools Installation and Configuration Guide.
The following table describes what tool you need to migrate different applications to Cognos
ReportNet.
Migration source
Architect models
Impromptu catalogs
and reports
PowerPlay
Impromptu Web
Reports
Upfront
Migration tool
Cognos ReportNet 1.1 Architect
Metadata Migration Tool
(arch2xml)
Cognos ReportNet 1.1
Impromptu Migration Tools
(impcat2xml, migratetocrn,
deploytocrn)
Not supported. Cognos does not
provide migration tools to move
PowerPlay content to Cognos
ReportNet.
Not supported. Cognos does not
provide migration tools to move
Impromptu Web Reports content
to Cognos ReportNet.
Not supported. Cognos does not
provide migration tools to move
Upfront content to Cognos
ReportNet.
The following table describes what tool you need to migrate different applications to Cognos 8
Business Intelligence.
Migration source
Architect models
Migration tool
Cognos 8 Architect Metadata
Migration Tool (arch2xml74)
User Guide 21

Chapter 2: The Migration Process
Migration source
Impromptu catalogs and
reports
PowerPlay
Impromptu Web Reports
Upfront
Migration tool
Cognos 8 Migration Tools
(impcat2xml, migratetoc8,
deploytoc8)
Cognos 8 Migration Tools
(migratetoc8, deploytoc8)
Cognos 8 Migration Tools
(migratetoc8, deploytoc8)
Cognos 8 Migration Tools
(migratetoc8, deploytoc8)
You can migrate the following types of content to all supported Cognos 8 platforms except Linux
or Hewlett-Packard Itanium:
• Cognos Series 7 Web-based content, such as PowerPlay, PowerPlay Web Explorer, and
Impromptu Web Reports reports, from Windows and UNIX
• Impromptu reports and catalogs from Windows
• Architect models from Windows
Cognos Services offer a variety of support options for migration, including both planning and
implementation services. For more information about migration services, visit the Cognos Global
Customer Services Web site (http://support.cognos.com).
The migration process consists of the following steps:
❑ Familiarize yourself with the overall migration process and considerations.
Some steps in the migration process are different from other tasks that you perform in a
Cognos environment. However, you will be familiar with many of the tasks you perform
before and after you use the migration tools.
Some Cognos Series 7 content is not migrated to Cognos 8 by the tools. Review the migration
considerations (p. 17) to understand which products, components, and functionality are
covered by migration.
❑ Recruit people with the appropriate knowledge to assist with the migration process.
In addition to product knowledge of both Cognos Series 7 and Cognos 8, you need
knowledge about other details of the Cognos environment such as data sources and security.
Cognos Consulting Services can help with your migration. For more information, contact
your local services manager, visit http://support.cognos.com/consulting, or send an email to
gcs@cognos.com.
❑ Set expectations about the migration process (p. 17).
The migration tools help you take advantage of investments in Cognos Series 7 applications.
However, the use of these tools is only one part of the migration process. For all migrations,
there is additional work to prepare for the migration. Also, you must test and refine the
migrated content in Cognos 8 before you make the content available to users.
❑
Review the Cognos Series 7 applications and identify the parts to migrate.
Work with data modelers, report authors, and report consumers to identify the content for
migration to Cognos 8. If auditing is enabled for Cognos Series 7 products, you can use the
audit information to determine content use patterns. Do not migrate content unless you
identified a need for the content to be available in Cognos 8. Do not migrate content that will
be a duplicate of content already available in the Cognos 8 environment. In some cases you
can reduce the number of reports by using Cognos 8 functionality such as bursting, prompts,
and support for multiple languages.
Note: The migration tools do not fix errors in the Cognos Series 7 content. Ensure that
metadata and reports do not include errors before migration to Cognos 8. For example,
22 Migration Tools

Chapter 2: The Migration Process
❑
❑
❑
❑
• run the Cognos Series 7 user cleanup tool from Cognos Series 7 Upfront Server
Administration to identify and delete invalid resources from the Upfront content store.
This tool will delete Personal NewsBoxes and content related to users that were deleted
from Access Manager.
For more information, see the Upfront Server Administrator Guide.
• run the Cognos Series 7 PowerPlay administration tool ppserver -ppx to identify unused
or corrupt PowerPlay .ppx files. You can use errors in the command output to identify
content that cannot be found or read by the migration tools. If you don’t delete this
invalid content, there will be errors when you create a Deployment Manager package.
For more information, see the Cognos Series 7 Solution Installation Guide.
• ensure that the Cognos Series 7 Deployment Manager package is free from errors before
using the package as a migration source. Deployment Manager errors will identify
problems such as NewsItems with invalid gateway URL references, or content providers
that were not available. These errors can cause problems if not corrected before
migration.
For more information, see the Deployment Manager User Guide.
Using the appropriate migration tools, move a representative subset of your metadata and
applications to a Cognos 8 test environment.
Test the migration process to understand how the content will appear in Cognos 8 and the
amount of work required to refine the content. Migrate and test reports in both Analysis
Studio and Report Studio to determine which studio is the most appropriate target for your
application. Feedback from this testing stage provides the best time and resource requirements
for the migration process and will help you develop your project plan.
Another option for testing the migration process is to use the samples installed with Cognos
Series 7. By default, the Cognos Series 7 samples are installed in C:\Program
Files\Cognos\cer5\samples.
Develop a plan for completing the migration.
Based on the review of the Cognos Series 7 applications and the results of the testing, develop
a detailed plan for moving metadata and applications to Cognos 8. One option is to move
subsets of the Cognos Series 7 content based on specific business requirements.
Migrate metadata and applications to the Cognos 8 production environment.
Test and refine the content.
Work with data modelers, report authors, and report consumers to test and refine the
migrated content.
Instead of attempting to maintain the same metadata and applications in both Cognos Series 7
and Cognos 8 environments, consider the move to Cognos 8 as a one-time process. After you
move the Cognos Series 7 metadata and applications to Cognos 8, encourage modelers and users
to adopt Cognos 8. Otherwise, to synchronize Cognos 8 with changes in Cognos Series 7, you
must repeat the migration process, including the work required to refine the Cognos Series 7
content in Cognos 8.
User Guide 23

Chapter 2: The Migration Process
24 Migration Tools

PART 2: Migrating Cognos Series 7 Content to
Cognos 8
User Guide 25

26 Migration Tools

Chapter 3: Migrating Metadata
This chapter discusses migrating metadata from Architect and Impromptu. You can skip this
chapter if are only migrating PowerPlay.
You can migrate Architect models and Impromptu catalogs for use as metadata sources in
Framework Manager. The metadata migration tools export the Cognos Series 7 metadata to an
XML format file. In Cognos 8, you can use the XML file as a metadata source in a Framework
Manager model.
For information about working with metadata in Cognos 8, see the Framework Manager
Guidelines for Modeling Metadata.
Cognos 8 supports the use of cubes as a data source. Unlike Architect models or Impromptu
catalogs, you do not have to export PowerCubes to an XML format file to use the metadata in
Cognos 8. After you create a data source connection to the PowerCube in Cognos Connection or
Framework Manager, you can use the PowerCube as a metadata source for new or existing
Framework Manager projects. For more information about using cubes in Cognos 8, see the
Cognos 8 Administration and Security Guide.
If Cognos 8 is configured to use the same namespace as Cognos Series 7, and you select the
Cognos Series 7 namespace when you import the migrated metadata into Framework Manager,
security settings remain the same. Otherwise, you can still migrate and import the metadata.
However, the metadata does not include security which must be applied after importing the
migrated metadata into Cognos 8.
To migrate metadata from Cognos Series 7 to Cognos 8, complete the following steps:
❑ Ensure that supported versions of Cognos products are installed and working correctly on the
source and target computers.
For more information, see "The Migration Process" (p. 21).
❑ Test the Cognos Series 7 metadata to ensure that the Architect models and Impromptu
catalogs do not contain errors that may cause problems after migration to Cognos 8.
The migration tools do not correct errors in the Cognos Series 7 metadata. Exporting models
or catalogs that contain errors or functionality not supported in Cognos 8 can cause
unexpected results when you use the metadata in Framework Manager. Examples of tests that
you can use before migrating metadata include verifying the Architect models and generating
content overview reports for Impromptu catalogs.
❑ Ensure that Framework Manager and Architect use the same locale settings. Otherwise, locale
specific data formats, such as list and decimal separators, may be invalid.
To determine the locale settings for the Architect model, use Cognos Series 7 Access Manager
Administration to view the regional settings of the default namespace. The Architect model
uses the same settings. For more information, see the Access Manager Administrator Guide. If
the Framework Manager and Architect locale settings are different, you must temporarily
change the settings on the Architect computer to run the Architect model migration tool
(p. 29).
For more information about configuring the design language in Framework Manager and
troubleshooting expression syntax errors, see the Framework Manager User Guide.
❑ Install the required migration tools on the source computers.
For more information see the Migration Tools Installation and Configuration Guide.
❑ Export the Cognos Series 7 metadata to XML format.
Use the appropriate migration tool to export Architect models (p. 29) and Impromptu
catalogs (p. 32) to XML format files.
❑ Import the metadata into Framework Manager (p. 35).
❑ Create data source connections in Cognos 8 (p. 35).
User Guide 27

Chapter 3: Migrating Metadata
❑ Test the imported metadata (p. 36).
For more information, see the Framework Manager User Guide. If you are not familiar with
working with metadata in Cognos 8, see the Framework Manager Guidelines for Modeling
Metadata.
The following diagram shows the workflow for migrating Cognos Series 7 metadata to Cognos 8.
Common Pre-migration Tasks
To provide the most effective mapping to Cognos 8 functionality, and to reduce the amount of
work required to refine the Cognos Series 7 data after migration to Cognos 8, review the
following tasks and complete the tasks that apply to you.
Test the Cognos Series 7 Metadata
If you are not familiar with the Architect models and Impromptu catalogs, test the metadata and
correct errors before running the migration tools. The migration tools do not correct errors in the
Cognos Series 7 metadata.
Ensure That Impromptu Catalog Includes Appropriate Key Settings
If the Impromptu catalog does not include appropriate key settings, when you import the
metadata into Framework Manager, all numeric items without a key map to facts. This can cause
unexpected results such as summarizing instead of grouping a column in a report.
Before exporting the catalog, review tables to ensure that the appropriate keys are set.
28 Migration Tools

Chapter 3: Migrating Metadata
For more information, see "Unexpected Sorting of Grouped Items for Migrated Impromptu
Report" (p. 145).
Temporarily Change the Locale Settings on the Architect Computer
If the Framework Manager design language is different from the locale settings on the Architect
computer, locale specific data formats, such as list and decimal separators, may be invalid after
you import the migrated metadata into Framework Manager. To prevent this problem, you must
temporarily change the locale settings on the Architect computer to use the same settings as the
Framework Manager computer before you run the arch2xml74 command.
Steps
1. On the Architect computer, open Configuration Manager and go to Architect.General
Properties.Locale Mode
2. The temporary configuration change depends on the Locale Mode setting:
• If the Standalone option is used, close Configuration Manager, and then change the locale
in the Windows Regional Settings.
• If the Suite option is used, change the setting to Standalone, apply the change, and then
change the locale in the Windows Regional Settings.
3. Run the arch2xml74 command to export the Architect models.
4. Reverse the temporary locale configuration changes on the Architect computer.
Export Architect Models
You can export Architect models for use as a metadata source in Framework Manager.
To export a single Architect model, run the arch2xml74 command specifying appropriate
parameters. You can export multiple models at the same time using a batch file. The output is an
XML format file that you can use as a metadata source in Framework Manager. We recommend
that you work from a backup copy of the model. If you use the original model, ensure that all
objects are checked in and that the model is not open.
If you want to migrate earlier versions of Architect models, such as 7.3, you must run the
arch2xml command. The arch2xml command uses the same parameters as the arch2xml74
command. Note that Cognos no longer supports this version of the Architect model migration
tool.
To export models, a supported version of Cognos Series 7 Architect including ObjectStore, and
the Architect model migration tool must be installed on the same computer. To migrate 7.1 or 7.3
models, you need version 7.1 or 7.3 of Architect and ObjectStore respectively and you must use
the arch2xml command. To migrate 7.4 models, you need version 7.4 of Architect and
ObjectStore and you must use the arch2xml74 command. For information about installing the
Architect model migration tool, see the Migration Tools Installation and Configuration Guide.
For more information about using the Architect model migration tool and for command line
examples, see "Architect Model Migration Tool" (p. 30).
Before you use the Architect model migration tool, print a copy of the migration worksheet
(p. 161) and record the information you need to complete the migration process, such as the
values you use on the command line.
Steps for One Model
1. Open a command prompt window and go to the bin directory of the Cognos Series 7
installation. For example, C:\Program Files\Cognos\cer5\bin.
2. Run the arch2xml74 command with the appropriate parameters (p. 30).
Ensure that the command line includes the appropriate parameters including authentication
information.
3. When the export process is complete, confirm that the XML file is in the target location.
Steps for Multiple Models
1. Create a batch file that includes a command line for each model that you want to export.
User Guide 29

Chapter 3: Migrating Metadata
Ensure that each command line includes the appropriate parameters including authentication
information.
2. Save the batch file to the bin location where you installed the Architect model migration tool.
For example, C:\Program Files\Cognos\cer5\bin.
To run the batch file from a different location each command line must include the full path
for the Architect model migration tool.
3. Run the batch file.
4. When the export process is complete, confirm that the XML files are in the target location.
The export of the Architect models is complete. Transfer the XML files to a Cognos 8 Framework
Manager computer for use as a metadata source. After you create the required data source
connections (p. 35), import the XML files into Framework Manager (p. 35).
For information about correcting common errors, see "Troubleshooting" (p. 133).
Architect Model Migration Tool
The Architect model migration tool converts an Architect model to an XML format file that you
can use as a metadata source in Framework Manager. The migration tool does not change the
.cem file.
You can run the Architect model migration tool directly from a command prompt window to
export a single model (p. 29) or you can run the tool using a batch file to export multiple models
(p. 29).
Syntax
The syntax to run the Architect model migration tool is:
arch2xml74 -options source_location target_location
All parameters are case sensitive.
Parameter
Description
-h Shows a description of the parameters. To use this option, do
not specify source or target.
source_location
target_location
Specifies the directory that contains the model to migrate.
You can specify a file path on the local file system or a UNC
file path to a directory or file on another server. You can use
slash (/) or backslash (\) as delimiters of path segments. Enclose
any path in double quotation marks (" ") if any file or
directory names in the path contain spaces.
Specifies the output location and file name for the exported
XML file.
The target directory must be a directory path on the local file
system, or a UNC file path to a directory on another server.
The directory must already exist and you must have write
permissions to the directory.
Do not use the same directory for both source and target.
You can use slash (/) or backslash (\) as delimiters of path
segments in the command line. Enclose the path in double
quotation marks (" ") if any directory names contain spaces.
If an XML file that uses the same file name already exists in
the target location, the migration process replaces the existing
file.
30 Migration Tools

Chapter 3: Migrating Metadata
Parameter
Description
-U user ID Specifies the Access Manager user who has access rights to the
model.
If you do not specify a user for a secured model, the migration
process will prompt you for a user ID and password.
If you are migrating several models, you can omit the
authentication information from the command line by logging
on to Architect before running the arch2xml74 command.
-P password Specifies the password for the Access Manager user who has
access to the model.
-q Optional
Suppresses the display of progress messages during the export
process.
Example: Display the arch2xml74 Command Help
Use the following command to display information about the arch2xml74 command syntax and
options:
arch2xml74 -h
Example: Export an Unsecured Model
The following command example exports an unsecured model:
arch2xml74 C:\models\gomodel.cem C:\exported_models\gomodel.xml
Example: Export a Secured Model
The following command example exports a secured model:
arch2xml74 -U admin -P password C:\models\gomodel.cem
C:\exported_models\gomodel.xml
Example: Export Multiple Models
The following command example uses a batch file saved to the same location as the Architect
model migration tool to export multiple models. The batch file includes a command line for each
model you want to export.
arch2xml74 -U admin -P password C:\models\gosalesregion1.cem
C:\exported_models\gosalesregion1.xml
arch2xml74 -U admin -P password C:\models\gosalesregion2.cem
C:\exported_models\gosalesregion2.xml
arch2xml74 -U admin -P password C:\models\gosalesregion3.cem
C:\exported_models\gosalesregion3.xml
Example: Export Multiple Secured Models
The following command example exports multiple models using a batch file saved to a location
different from the Architect model migration tool. The batch file includes a command line for each
model you want to export.
C:\Program Files\Cognos\cer5\bin\arch2xml74
-U admin -P
password C:\models\gosalesregion1.cem C:\exported_models\gosalesregion1.xml
C:\Program Files\Cognos\cer5\bin\arch2xml74
-U admin -P
password C:\models\gogosalesregion2.cem C:\exported_models\gosalesregion2.xml
C:\Program Files\Cognos\cer5\bin\arch2xml74
-U admin -P
password C:\models\gosalesregion3.cem C:\exported_models\gosalesregion3.xml
User Guide 31

Chapter 3: Migrating Metadata
Export Impromptu Catalogs
You can export Impromptu catalogs for use as a metadata source in Framework Manager.
If you are migrating Impromptu reports, you must migrate catalogs to support the report
migration. You can use a single tool to migrate both the Impromptu catalog and the reports. You
do not have to first run the impcat2xml tool to migrate the catalog. For more information, see
"Migrating Applications" (p. 39).
To export a single Impromptu catalog, you run the impcat2xml command specifying appropriate
parameters. You can export multiple catalogs at the same time using a batch file. The output is an
XML format file that you can use as a metadata source in Framework Manager. We recommend
that you work from a backup copy of the catalog. If you use the original catalog, ensure that the
catalog is not open.
Review the Impromptu catalog mapping information (p. 57) to understand what to expect when
you export a catalog for use as metadata in Framework Manager. Also, identify the name and
location of the catalogs you want to migrate.
To export an Impromptu catalog:
• Cognos Series 7 version 4 (7.4) Impromptu Administrator or later and the Cognos Series 7
migration tool must be installed on the same computer. For information about installing the
Cognos Series 7 migration tool, see the Migration Tools Installation and Configuration
Guide.
• Access Manager Runtime must be configured
For more information about using the impcat2xml tool, and command line examples, see
"impcat2xml" (p. 33).
Before you use the impcat2xml tool, print a copy of the migration worksheet (p. 161) and record
the information you need to complete the migration process, such as the values you will use on the
command line.
Steps for One Catalog
1. Open a command prompt window and go to the migs7 directory of the migration tool
installation. For example, if you installed the migration tool to the default Cognos Series 7
location, go to C:\Program Files\Cognos\cer5\migs7.
2. Run the impcat2xml command with the appropriate parameters (p. 33).
If the catalog is secured and you do not provide a user ID and password in the command, the
migration process prompts you for authentication information.
3. When the export process is complete, confirm that the XML file is in the target location and
review the log file for warnings and errors.
Steps for Multiple Catalogs
1. Create a batch file that includes a command line for each catalog that you want to export.
Ensure that each command line includes the appropriate parameters including authentication
information.
2. Save the batch file to the migs7 directory where you installed the impcat2xml migration tool.
For example, if you installed the migration tool to the default Cognos Series 7 location, save
the batch file in C:\Program Files\Cognos\cer5\migs7.
To run the batch file from a different location each command line must include the full path
for the impcat2xml migration tool.
3. Run the batch file.
4. When the export process is complete, confirm that the XML files are in the target location
and review the log file for warnings and errors.
The export of the Impromptu catalogs is complete. Transfer the XML files to a Framework
Manager computer for use as a metadata source. After you create the required data source
connections (p. 35), import the XML file into Framework Manager (p. 35).
For information about correcting common errors, see "Troubleshooting" (p. 133).
32 Migration Tools

Chapter 3: Migrating Metadata
impcat2xml
The impcat2xml migration tool converts an Impromptu catalog to an XML format file that you
can use as a metadata source in Framework Manager. The migration tool does not change the .cat
file.
Syntax
The syntax to run the impcat2xml migration tool is:
impcat2xml -options catalog_location output_location
All parameters are case sensitive.
Parameter
Description
-h Shows a description of the parameters. To use this option, do
not specify source or target.
catalog_location
output_location
Specifies the directory that contains the catalog to migrate.
You can specify a file path on the local file system or a UNC
file path to a directory or file on another server. You can use
slash (/) or backslash (\) as delimiters of path segments. Enclose
any path in double quotation marks (" ") if any file or
directory names in the path contain spaces.
Specifies the output location and file name for the exported
XML file.
The target directory must be a directory path on the local file
system, or a UNC file path to a directory on another server.
The directory must already exist and you must have write
permissions to the directory.
Do not use the same directory for both source and target.
You can use slash (/) or backslash (\) as delimiters of path
segments in the command line. Enclose the path in double
quotation marks (" ") if any directory names contain spaces.
If an XML file that uses the same file name already exists in
the target location, the migration process replaces the existing
file.
-n user_class Specifies the user class to use to log on to the catalog. If this
parameter is not specified, the Creator name is assumed. If you
use a localized version of Impromptu, ensure that you specify
the localized Creator name. For example, use Ersteller for
German and Auteur for French.
Specify either a Creator name and password, or an Access
Manager user and password. You do not have to specify both.
-p password Specifies the password for the Impromptu catalog user profile.
The default is no password. Errors occur if you do not provide
the password for a password-protected user profile.
-U user ID Specifies the Access Manager user name for the default
namespace. Specify either a Creator name and password, or an
Access Manager user name and password. You do not have to
specify both.
-P password Specifies the Access Manager user password for the default
namespace.
User Guide 33

Chapter 3: Migrating Metadata
Parameter
Description
-i Optional
Specifies which Impromptu Automation server to use when
there is more than one version on the computer.
-L location\file name Optional
Writes progress messages to the specified file.
-q Optional
Suppresses the display of progress messages during the export
process. Errors and warnings still appear in the log file.
-e Optional
Specifies the character set encoding to use when writing the
exported XML file.
Example: Display the impcat2xml Command Help
Use the following command to display information about the impcat2xml command syntax and
options:
impcat2xml -h
Example: Export an Unsecured Catalog
The following command example exports an unsecured catalog:
impcat2xml C:\catalogs\gosales.cat
C:\exported_catalogs\gosales.xml
Example: Export a Secured Catalog
The following command example exports a catalog that is secured using Access Manager:
impcat2xml -U admin -P password C:\catalogs\gosales.cat
C:\exported_catalogs\gosales.xml
Example: Export a Secured Catalog from a Network Location
The following command example exports a secured catalog from a local location to a shared
network location:
impcat2xml -U admin -P password C:\catalogs\gosales.cat
\\computer_name\exported_catalogs\gosales.xml
Example: Export a Secured Catalog with User Profile Logon Information
The following command example exports a secured catalog using the authentication information
required for the Systems user profile:
impcat2xml -n Systems -p password C:\catalogs\gosales.cat
C:\exported_catalogs\gosales.xml
Example: Export a Catalog from a German Version of Impromptu
The following command example exports a catalog from a German version of Impromptu using
the authentication information required for the Ersteller user class (Creator user class):
impcat2xml -n Ersteller -p"" C:\catalogs\gosales.cat
C:\exported_catalogs\gosales.xml
Example: Export Multiple Catalogs Using a Batch File
The following command example exports multiple catalogs using a batch file saved to the same
location as the impcat2xml migration tool. The batch file includes a command line for each
catalog you want to export.
impcat2xml -U admin -P password C:\catalogs\gosalesregion1.cat
C:\exported_catalogs\gosalesregion1.xml
34 Migration Tools

Chapter 3: Migrating Metadata
impcat2xml -U admin -P password C:\catalogs\gogosalesregion2.cat
C:\exported_catalogs\gosalesregion2.xml
impcat2xml -U admin -P password C:\catalogs\gosalesregion3.cat
C:\exported_catalogs\gosalesregion3.xml
Example: Export Multiple Secured Catalogs Using a Batch File
The following command example exports multiple catalogs using a batch file saved to a location
different from the impcat2xml migration tool. The batch file includes a command line, with the
path to the impcat2xml migration tool, for each catalog you want to export.
C:\Program Files\Cognos\cer5\bin\impcat2xml
-U admin
-P password C:\catalogs\gosalesregion1.cat C:\catalogs\gosalesregion1.xml
C:\Program Files\Cognos\cer5\bin\impcat2xml
-U admin
-P password C:\catalogs\gogosalesregion2.cat C:\catalogs\gosalesregion2.xml
C:\Program Files\Cognos\cer5\bin\impcat2xml
-U admin
-P password C:\catalogs\gosalesregion3.cat C:\catalogs\gosalesregion3.xml
Create Data Source Connections in Cognos 8
You must create data source connections in Cognos 8 for exported Architect models and
Impromptu catalogs.
You can create new data source connections in either Framework Manager or Cognos Connection
for the database. The data source connections must match the Cognos Series 7 connections. One
source for the Cognos Series 7 data source information is the cognos.ini file. By default, the
cognos.ini is created in the Cognos folder of the Cognos Series 7 installation location.
For instructions about creating data source connections in Cognos 8, see the Framework Manager
User Guide or the Cognos 8 Administration and Security Guide.
Import Metadata into Framework Manager
You can import Cognos Series 7 metadata into a new project, or an existing project. You can
import more than one Architect or Impromptu metadata source into the same project.
To import an exported Architect model or Impromptu catalog into Framework Manager, the
XML format files you created with the arch2xml74 and impcat2xml tools must be in a location
accessible to the Framework Manager computer.
If Cognos 8 is configured to use the same namespace as Cognos Series 7 and you want to maintain
security settings from Cognos Series 7, ensure that you select the Cognos Series 7 namespace when
importing the metadata.
For instructions about importing metadata, see the Framework Manager User Guide. If you are
not familiar with working with metadata in Cognos 8, see the Framework Manager Guidelines
for Modeling Metadata.
Common Post-migration Tasks
After importing the Cognos Series 7 metadata into Framework Manager you may have to
complete one or more tasks to prevent errors or unexpected results caused by differences in
functionality between Cognos Series 7 and Cognos 8.
Evaluate Filters in Imported Architect Metadata
You may have to update filter properties to achieve the expected results. For example, you want
the filter to be optional. Because Architect does not support optional filters, you must change the
filter properties in Framework Manager.
User Guide 35

Chapter 3: Migrating Metadata
Review Cardinality in the Framework Manager Model
Examine and, if necessary, refine cardinality to ensure that the relationships correctly reflect your
users' reporting requirements. Cardinality in Framework Manager is inferred based on Cognos
Series 7 metadata relationships. You may be able to improve query processing time and
performance with further tuning.
You must recreate some relationships after you import the Cognos Series 7 metadata. We
recommend that you verify relationships when importing any type of metadata in Framework
Manager.
Performance improvements may result from refining cardinalities related to databases that contain
the most frequently used tables and greatest row volumes.
Support Reports Created Before Impromptu 6.0
Any report created with a version of Impromptu earlier than Impromptu 6.0, even if the report is
migrated to later versions of Impromptu, contains direct references to the database table columns
rather than the catalog folder item that the report author selected in the query dialog. This
behavior is different from the version of Impromptu supported for migration, Impromptu 7.4.
Opening the report in a later version of Impromptu does not change this behavior in the report.
In the Framework Manager model created from the migrated catalog, the database table columns
are under the [Tables] namespace, and the catalog folder items are under the [Folders] namespace.
By default, the [Tables] namespace is hidden from report authors when the package is published.
This means that any direct references to the database table columns in the report created with a
version of Impromptu earlier than 6.0 do not resolve in package metadata. These references
display an error, for example "[Not Found: [db].[cat].[sch].[tbl].[col]]" in the migrated report.
The error is different depending upon the database architecture. To resolve this problem, unhide
the [Tables] namespace in package properties before publishing the package and deploying the
migrated reports. For more information, see "Parsing Error Message When Migrated Impromptu
Report Fails to Run" (p. 143).
Testing the Imported Metadata
After you import the metadata into Framework Manager, you must ensure that the metadata
migrated successfully.
The organization of the information in Framework Manager is similar to how it is organized in
the Architect model or Impromptu catalog. You can find most of the migrated information in the
Tables and Folders namespaces. Because some model and catalog features do not have equivalent
functionality in Framework Manager, you may see differences in the metadata.
For information about how Cognos Series 7 metadata objects are mapped to Framework
Manager, see "Architect Mapping" (p. 99) and "Impromptu Catalog Mapping" (p. 57).
For information about how to perform the following tests, see the Framework Manager User
Guide.
❑ Test the data source connections.
❑ Verify the model to ensure that there are no invalid objects that can break queries in the
published package.
In Framework Manager, icons of broken objects indicate that an object has problems. If you
do not resolve these problems before report authors use the objects to create reports, they may
get unexpected results.
Reevaluation warning messages are produced for all migrated data source query subjects. You
must repair the query subjects before you publish the model to Cognos 8. The repair function
refreshes the data source query subjects with information coming from the underlying
database, such as size and precision, and ensures that queries based on the migrated model
will run correctly.
For more information about problems you may encounter with importing metadata into
Framework Manager, see "Problems Importing Metadata into Framework
Manager" (p. 136).
Continue to develop the project and then publish a Framework Manager package.
36 Migration Tools

Chapter 3: Migrating Metadata
Publishing a Framework Manager Package
To make the migrated metadata available to report authors, and to support the migration of
Impromptu reports, you must publish a Framework Manager package to Cognos Connection.
To reduce the number of steps required to deploy migrated Impromptu reports, use the catalog file
name for the package you publish. For example, if the original Impromptu catalog is gosales.cat,
name the package gosales.cat.
For more information about publishing a package to Cognos 8, see the Framework Manager User
Guide.
Test the published package by creating reports in the Cognos 8 studios.
After you complete the metadata migration and test the published package, you can migrate
Cognos Series 7 applications (p. 39).
Synchronize a Framework Manager Project with Updated
Cognos Series 7 Metadata
We recommend that you consider migration to Cognos 8 as a one-time process. After you migrate
Cognos Series 7 metadata to Cognos 8 you should only make changes to the metadata in Cognos
8 and freeze the Cognos Series 7 source. However, if you want to maintain the metadata in
Cognos Series 7 as well as Cognos 8, you can synchronize changes made in the original Architect
models and Impromptu catalogs with projects created from the migrated metadata. To do this you
must repeat the export process for the model or catalog and then synchronize the Framework
Manager project.
For information about copying projects, see the Framework Manager User Guide.
Before you synchronize, ensure that you create a backup of the Framework Manager project and
the original exported XML file from your Architect model or Impromptu catalog.
Steps
1. Export the Architect model or Impromptu catalog using the same target XML file name that
you used for the original export.
2. Copy the XML file to the location used for the Framework Manager project, replacing the
original XML file.
3. In Framework Manager, synchronize the project.
For instructions, see the Framework Manager User Guide.
4. Ensure that the updates are reflected in your Framework Manager project.
Complete the same tests and updates you used when you originally imported the Cognos
Series 7 metadata.
The Framework Manager project includes the updates to the Cognos Series 7 metadata. Republish
the project to make the updates available to report authors.
User Guide 37

Chapter 3: Migrating Metadata
38 Migration Tools

Chapter 4: Migrating Applications
You can migrate some components of a Cognos Series 7 application to Cognos 8. For more
information about what is included when you migrate a Cognos Series 7 application, see "The
Migration Process" (p. 21).
To migrate applications from Cognos Series 7 to Cognos 8, complete the following steps:
❑ Ensure that supported versions of Cognos products are installed and working correctly on the
source and target computers (p. 21).
❑ Test the Cognos Series 7 applications to ensure that the applications do not contain errors.
The migration tools do not correct existing errors in the Cognos Series 7 application.
Exporting applications that contain errors can cause unexpected results.
❑ Install the required migration tools on Cognos Series 7 and Cognos 8 computers.
For information about installing the migration tools, see the Migration Tools Installation and
Configuration Guide.
❑ Prepare the migration source files (p. 41).
❑ Export the Cognos Series 7 applications to a migration package using the migratetoc8 tool
(p. 42).
❑ Move the migration package to Cognos 8 (p. 46).
❑ Ensure that the metadata required by Cognos Series 7 reports is available in Cognos 8.
Each migrated report must map to an existing published Framework Manager package
created from Cognos Series 7 metadata (Impromptu catalog or cube).
To support Impromptu report migration, you must first complete metadata migration (p. 27).
Do not use a package created from a migrated Architect model as the metadata source for
migrated Impromptu reports.
To support PowerPlay report migration, you must create a data source connection in Cognos
8 to the related cubes and use the data source to create and publish a package from
Framework Manager.
❑ Deploy the applications in Cognos 8 (p. 48).
You can deploy the content automatically when you run the Cognos 8 migration tool, or
import the content later from a deployment archive (p. 51).
❑ Complete the migration by testing the migrated application, applying security if required, and
enabling access to report authors.
For information about working with the deployed content and deployment archives, see the
Cognos 8 Administration and Security Guide.
The following diagram shows the workflow for migrating Cognos Series 7 applications to
Cognos 8.
User Guide 39

Chapter 4: Migrating Applications
40 Migration Tools

Chapter 4: Migrating Applications
Preparing the Application for Migration
To provide the most effective mapping to Cognos 8 functionality, and to reduce the amount of
work required to refine the Cognos Series 7 data after migration to Cognos 8, review the
following tasks and complete the tasks that apply to your application.
Set Schedules for Impromptu Web Reports
The save the result option is not available in Cognos 8 if the original Impromptu Web Reports
NewsItem did not have schedule settings.
To ensure that the save the result option is available in Cognos 8, set a schedule for Impromptu
Web Reports before migration.
Migrating Applications from UNIX
To migrate Cognos Series 7 applications on UNIX, you must transfer the content to a Windows
computer using a binary file transfer method.
Preparing the Migration Source
You can use one or more directories as the migration source. The content of the migration source
depends on the Cognos components you want to migrate.
• To migrate Web-based content from Upfront, PowerPlay Enterprise Server, and Impromptu
Web Reports, the migration source is one or more Deployment Manager packages.
You can use a directory as an alternative source for migrating PowerPlay reports.
• To migrate Impromptu or PowerPlay for Windows reports, the migration source is a directory
that contains the reports and associated files, such as catalogs and linked graphics. To support
the migration processing, the catalogs used by the Impromptu reports must be in the same
directory as the reports.
How the migratetoc8 tool processes the source files depends on the contents of the source location
and the parameters you use with the migratetoc8 command. For example, the source location can
contain a combination of Deployment Manager package files (.dmp) and reports. When exporting
the content, you can process a single package, all packages, or only the reports.
Create the Migration Source Using a Deployment Manager Package
To migrate Cognos Series 7 Web-based content, you use a Cognos Series 7 Deployment Manager
package as the migration source. You use Deployment Manager to create the package, which
defines the components and objects that you want to migrate. To create the package, select the
providers and NewsBoxes that you want to migrate.
We recommend that you create the Deployment Manager package on the same computer where
you installed the Cognos Series 7 migration tools. For instructions about creating a Deployment
Manager package, see the Deployment Manager User Guide.
After you create the Deployment Manager package, you run the migratetoc8 command against
the .dmp file.
The package and packlet files must be located on the computer where you are running the
migratetoc8 command. If you created a Deployment Manager package for a distributed Cognos
Series 7 environment, the package and packlet files may be on more than one computer. In this
case you must complete the following additional steps using the package file (.dmp) to prepare the
migration source before running the migratetoc8 command. The .dmp file is an XML format file
that you can open and edit in a text or XML editor.
Steps
1. Open the .dmp file in a text or XML editor and search for class="packlet" to identify the
location of all packlets.
The following is an example of an Impromptu Web Reports (IWR) packet location in a .dmp
file.
User Guide 41

Chapter 4: Migrating Applications
mappingID="IWR.Map.L.AdminMarketing" class="packlet"
propertyID="IWR.Prop.L.AdminMarketing">\\computername\ReportS
toreLocation\Marketing\AdminMarketing
Other packlet types used in migration are PowerPlay Enterprise Server (PPES), Upfront, and
Access Manager (ACCMAN).
2. Copy the packlets, preserving the folder structure, to the computer where you are running the
migratetoc8 command.
3. In the .dmp file, modify the for the location of the packlets to show the
correct location on the local computer.
4. Save the .dmp file.
Create the Migration Source Using a Directory Structure
To migrate Impromptu reports, you use a directory structure as the migration source. You can also
use a directory structure instead of the Deployment Manager package for migrating PowerPlay
reports. You can use a single directory as the migration source. However, you may want to create
a directory structure to provide an initial organization when you deploy the content to Cognos 8.
For some applications, you must duplicate the original working directory structure to support the
migration of features such as linked graphics.
The migration source should contain the following files:
• .ppx format files for the PowerPlay reports
• .imr and .cat files for the Impromptu reports
• associated images such as .bmp and .jpeg files
Steps
1. Create the directory structure.
When you deploy the migrated content to Cognos 8, the folder names from the migration
source are used in Cognos Connection. Do not use _SUPPORT or _LOG for folder names.
The migratetoc8 process creates directories with these names in the target location. Errors
occur if the name already exists in the source or target location.
2. Copy reports and other required files to the directories.
You can use the working directories as the migration source. However, the migration tool
processes all content in the directories. You cannot migrate a subset of the reports.
You can now run the migratetoc8 tool against the migration source.
Create a Migration Package
You use the migratetoc8 tool to create a migration package that is compatible with Cognos 8. This
tool processes the Cognos Series 7 migration source (p. 41) and creates two versions of the
migration package: a set of directories and files, and a .zip format version of all the directories and
files. The .zip format version makes it easier to transfer the migration package if Cognos 8 is
installed on a different computer than Cognos Series 7.
Review the information about the migratetoc8 tool (p. 43) and identify the command line
parameters required to process the migration source. For example, to migrate secured content you
must know the required Access Manager logon information.
Before you run the migratetoc8 command, print a copy of the migration worksheet (p. 161) and
record the information you need to complete the migration process, such as the values you use on
the command line.
Steps
1. Create the source (p. 41) and target locations.
Tip: To make it easier to type the required command, do not use complex paths or folder
names.
42 Migration Tools

Chapter 4: Migrating Applications
migratetoc8
2. Open a command prompt window and go to the migs7 directory of the migration tool
installation. For example, if you installed the migration tool with Cognos Series 7, the default
location is C:\Program Files\Cognos\cer5\migs7.
3. Run the migratetoc8 migration tool with the appropriate parameters (p. 43).
You can use Ctrl+c to stop the migratetoc8 process.
If errors occur, view the migration log file for more information about warnings and errors.
The migration log file, viewMigrationLog.html, is located in the _LOG folder in the target
location.
4. Check that the migration package contains the expected directories and files (p. 46).
The export is complete. You must run the deploytoc8 tool to complete the processing of the
migration package before using the content in Cognos 8 (p. 48). You cannot import contents of
the migration package directly into Cognos 8.
If Cognos 8 is installed on a different computer, the next step is to transfer the migration package
to the Cognos 8 computer for deployment (p. 46). If Cognos Series 7 and Cognos 8 are installed
on the same computer, you do not need to transfer files and you can continue by verifying the
package mapping (p. 47).
For information about correcting common errors, see "Troubleshooting" (p. 133).
The migratetoc8 tool does the following to create a migration package:
• sets up the migration environment
• creates a hierarchy of directories and files that contain information about the migration
source, including an XML file for each report and catalog
• creates a directory that contains images used in the reports
• creates log files in the target location
• creates a zip file of all of the content in the target location
For more information about installing the tool, see the Migration Tools Installation and
Configuration Guide.
You can install and run the migratetoc8 tool only on Windows.
Syntax
The syntax used to run the migratetoc8 migration tool is
migratetoc8 [options] ...
All parameters are case sensitive.
You can specify more than one source directory. The source and target keywords are optional. If
you do not include these keywords, the last directory is the target and all other directories are
source locations.
While it is possible to specify more than one source location, we recommend that you export one
source location at a time to make it easier to troubleshoot errors.
Parameter
Description
-h Shows a description of the parameters. To use this option, do
not specify the source or target.
User Guide 43

Chapter 4: Migrating Applications
Parameter
Description
Specifies the directory that contains reports to be migrated, or
a Cognos Series 7 Deployment Manager package that
describes content that was published to Upfront. You can
specify more than one source location. Each source location
must be a file path on the local file system or a UNC file path
to a directory or file on another server. You can use slash (/)
or backslash (\) as delimiters of path segments. Enclose any
path in double quotation marks if any file or directory names
in the path contain spaces.
Specifies the parent folder for the migration package created
by the migratetoc8 process. The migratetoc8 process creates a
new folder in the target location with the following name
format:
timestamp.computer_name.migratetoc8
Existing content in the target location is not deleted or
changed.
The target directory must be a directory path on the local file
system, or a UNC file path to a directory on another server.
You must have write permissions to an existing target
directory, or you must have permissions to create a new
directory if the specified target does not exist.
Do not use the same directory for both source and target. Do
not use _SUPPORT as the name of the target location. The
migratetoc8 tool creates a directory named _SUPPORT in the
target location. Errors occur if the name already exists.
You can use slash (/) or backslash (\) as delimiters of path
segments in the command line. Enclose the path in double
quotation marks if any directory names contain spaces.
-u Specifies the user class to use to log on to the catalog. If this
parameter is not specified, the Creator name is assumed. If
you use a localized version of Impromptu, ensure that you
specify the localized Creator name. For example, use Ersteller
for German and Auteur for French. If you specify a user class
other than Creator, some report objects may not be available
as expected in the migrated reports.
Specify either a user class and password, or an Access
Manager user and password. You do not have to specify
both.
-p Specifies the password for the Impromptu catalog user
profile. The default is no password. Errors occur if you do
not provide the password for a password-protected user
profile.
-U user_ID Specifies a user name from the Cognos Series 7 namespace. If
you do not provide logon information on the command line
for secured content, you may be prompted for the
information during the migratetoc8 process.
For Impromptu catalogs, specify either a Creator name and
password, or an Access Manager user and password. You do
not have to specify both.
-P user_password Specifies the user password.
44 Migration Tools

Chapter 4: Migrating Applications
Parameter
Description
-d Specifies that Deployment Manager packages in the source
directories are not included in migratetoc8 processing.
-e encoding Specifies the character set encoding to use when writing the
exported XML file.
-i server_name Specifies which Impromptu Automation server to use when
there is more than one version installed on the computer.
-r rendition Specifies the Cognos rendition name to use when there is
more than one version of Impromptu installed on the
computer.
--acl strategy
Specifies that access control list (ACL) information for
Upfront content is included in the migratetoc8 processing.
You can specify one of the following strategies:
• 0 = Do not generate ACL report or migrate ACL
definitions.
• 1 (default) = Generate ACL report but do not migrate
ACL definitions.
• 2 = Generate ACL report and migrate ACL definitions.
To use this option, you must configure Cognos 8 to use
the same namespace as Cognos Series 7 and you must
provide the namespace ID on the command line.
For more information about the options for migrating ACL
information, see "Security" (p. 93).
-N namespace_ID Specifies the Cognos 8 namespace to use as the source of
contact user ID and security. You can obtain the namespace
ID from namespace properties in Cognos Configuration.
--scv
Migrates only Impromptu Web Reports and PowerPlay
shortcuts and custom views.
You can migrate shortcuts and custom views only after all
packages are migrated. After you migrate the packages, verify
that all of the report folders work. Then create a package in
Deployment Manager (p. 41) that includes the shortcuts and
custom views that you want to migrate and all referenced
source NewsItems. Run the migratetoc8 command again with
this option to migrate shortcuts and custom views only.
-q Optional
Suppresses the display of progress messages during the export
process. Errors and warnings still appear in the log file.
Example: Export a Deployment Manager Package
The following command exports a specific Deployment Manager package. The migration tool
does not process other content in the same location.
migratetoc8 -U admin -P password
C:\Cognos\cer5\packages\migration\series7_package.dmp
C:\Migration\output
Example: Export One or Multiple Deployment Manager Packages
If you do not specify a package definition, the migration tool processes all package definitions in
the source directory. The migration tool does not export reports in the same directory.
User Guide 45

Chapter 4: Migrating Applications
Migration Package
migratetoc8 -U admin -P password C:\Cognos\cer5\packages\migration
C:\Migration\output
Example: Export the Contents of a Directory
Use the -d parameter to exclude Deployment Manager packages from the migratetoc8 processing.
The migration tool exports only reports.
migratetoc8 -d C:\Cognos\reports C:\Migration\output
Example: Export the Contents of Multiple Directories
Use the -d parameter to exclude Deployment Manager packages from the migratetoc8 processing.
migratetoc8 -d --source C:\Cognos\regionA_reports
C:\Cognos\regionB_reports C:\Cognos\regionC_reports
--target C:\Migration\output
Example: Export Using a Specific Rendition When More Than One Version of Cognos
Series 7 is Installed
Use the -r parameter to specify the version of Cognos Series 7 to use for the export process.
migratetoc8 -r cer3 --source C:\Cognos\regionA_reports
--target C:\Migration\output
Example: Export Using a Specific Encoding
Use the -e parameter to specify an encoding when the source content encoding is different from
the local computer.
migratetoc8 -e utf-8 C:\migration\DeployPkg.dmp
C:\Temp\migs7
After you run the migratetoc8 command, the target location contains several directories and files.
You may need to work with the following content:
• target\deploytoc8.zip
The deploytoc8.zip file is a compressed format version of the entire migration package. The
.zip format makes it easier to transfer the migration package (p. 46) if Cognos 8 is installed on
a different computer than Cognos Series 7.
• target\_LOG\migratetoc8.xml
The migratetoc8.xml log file contains information about the migratetoc8 process. After you
run the deploytoc8 command, the deploytoc8 log file also includes the migratetoc8 log file
information.
• target\target_name.dmp\ACL_Report\default.html
If you created an ACL report when you ran the migratetoc8 command, open default.html in a
Web browser to view the report.
• target\_SUPPORT\maps\nameMap.xml
The nameMap.xml file includes default names for Framework Manager packages based on
Impromptu catalogs. Before you deploy the migration package, check package mapping
(p. 47) to ensure that the deploytoc8 process is successful.
Do not change or delete any of the directories or files from the migration package.
Move the Migration Package to Cognos 8
If Cognos Series 7 and Cognos 8 are installed on different computers, move the migration package
to the Cognos 8 computer to create the source directory for the deploytoc8 migration tool. If
Cognos Series 7 and Cognos 8 are installed on the same computer, you do not have to complete
this task.
46 Migration Tools

Chapter 4: Migrating Applications
Steps for a Windows Computer
1. Copy the deploytoc8.zip file from the Cognos Series 7 migratetoc8 target location to the
Cognos 8 computer.
2. Extract the contents of the deploytoc8.zip file to a new directory.
Tip: To make it easier to type the required command, do not use complex paths or folder
names.
Steps for a UNIX Computer
1. Transfer the compressed deploytoc8 file from the target location to the Cognos 8 UNIX
computer using a binary file transfer method.
2. Extract the contents of the compressed file to a new directory on the Cognos 8 computer.
Tip: To make it easier to type the required command, do not use complex paths or folder
names.
3. If the encoding used on the UNIX computer does not support any of the non-ASCII characters
used in directory or file names, you must edit the names to use supported characters. Replace
non-ASCII characters in directory and files names with the equivalent character in the
encoding used on the UNIX computer.
Continue with the migration by checking package mapping.
Check Package Mapping
Each report that you want to migrate must map to a published package in Cognos Connection.
• To support Impromptu report migration, migrate catalogs, import the migrated metadata into
a Framework Manager project, and then publish a package to Cognos Connection.
For more information, see "Migrating Metadata" (p. 27).
• To support PowerPlay report migration, create data source connections to the required cubes
using either Framework Manager or Cognos Connection. In Framework Manager, use the
cube data source in a Framework Manager project, and then publish a package to Cognos
Connection using the cube name for the package name. For example, if reports use a cube
named Great_Outdoors, create and publish a package named Great_Outdoors.
If the report set uses more than one cube, you must create a separate package for each cube.
For more information, see the Cognos 8 Administration and Security Guide, and the
Framework Manager User Guide.
The migration process assumes the package name for the required metadata is the same as the file
name of the Series 7 metadata. For example, for Impromptu reports based on a catalog named
gosales.cat, the migration process assumes that a package named gosales.cat is available in
Cognos Connection. If you changed the name of the migrated metadata, you must edit the
nameMap.xml file or the migration process will not be able to map the migrated report to the
appropriate metadata.
Before deploying a migration package, check package mapping by comparing the default package
name in the nameMap.xml file to the name of the published package. If the names do not match,
you must change one of the names.
Steps
1. Open the nameMap.xml file in a text or XML editor.
The nameMap.xml file is in the _SUPPORT\maps directory in the target location you
specified when you ran the migratetoc8 command.
2. Check whether the names in default_name elements match
the name of a published package that represent the Cognos Series 7 metadata required by the
migrated reports.
3. If a name does not match, edit the nameMap.xml file to make the name the same as the
published package.
Do not edit any other parts of the nameMap.xml file.
4. Save and close the nameMap.xml file.
User Guide 47

Chapter 4: Migrating Applications
You can now deploy the migration package in Cognos 8 (p. 48).
Deploy the Migration Package
To make the migrated application available in Cognos 8, run the deploytoc8 command against the
Cognos 8 migration package. The deploytoc8 process creates a deployment archive. You can use a
deploytoc8 command line option to automatically import the content to Cognos 8, or you can
import the content from the deployment archive as a separate step at a later time.
Review the information about the deploytoc8 tool (p. 49) and identify the command line
parameters required to process the migration package. For example, namespace information is
required if Cognos 8 is configured to use the same namespace as Cognos Series 7. Also, signon
information must be provided to access the packages referenced in the nameMap.xml file.
To test the migration process, deploy a set of reports to both Analysis Studio and Report Studio
and then compare the results to determine which studio is the most appropriate target. Use the -y
option when you run the deploytoc8 command to specify which studio is used for the target
(p. 49). After you complete the testing, ensure that you delete duplicate content before providing
access to users.
If you redeploy a migration package, the original reports are not overwritten. You must delete the
reports before you redeploy the package.
Before you run the deploytoc8 command, ensure that the required Framework Manager packages
that represent the Cognos Series 7 metadata and cubes are published (p. 37), and check package
mapping (p. 47).
Before you run the deploytoc8 command, print a copy of the migration worksheet (p. 161) and
record the information you need to complete the migration process, such as the values you will use
on the command line.
Steps
1. Open a command prompt window and go to the c8\migdeploy directory.
For example, if you used the default location for Cognos 8, go to C:\Program
Files\Cognos\c8\migdeploy.
2. Run the deploytoc8 command with the appropriate parameters (p. 49).
You can use Ctrl+c to stop the deploytoc8 process.
If errors occur, view the migration log file for more information about errors and warnings.
The migration log file is in the _LOG folder in the target location.
3. Check that the expected directories and files appear in the target location (p. 51).
If you used the -a option to automatically import the content to Cognos 8, see "Migration
Deployment Archive" (p. 51) for more information about the directories and files added to
Cognos 8.
Choosing the Target Studio for Migrated Reports
You can migrate reports to Report Studio or to Analysis Studio. The following information can
help you decide which studio to choose as the target.
• If a report is run and viewed on a regular basis with little or no requirement to explore or
analyze the data in the report, Report Studio is the most appropriate target.
• If a report has characteristics such as complex formatting, Report Studio is the most
appropriate target.
• If a report consumer needs to explore or analyze the information in a report to understand a
problem or gain insight into the business by looking at different perspectives of the data,
Analysis Studio is the most appropriate target. Examples of exploring and analyzing
information include drill down, swapping rows and columns, applying zero suppression or
80/20 suppression, and exception highlighting.
48 Migration Tools

Chapter 4: Migrating Applications
deploytoc8
The deploytoc8 tool completes the following tasks to complete the migration to Cognos 8:
• maps reports to the package that represents the required metadata or cube. If metadata
mapping fails, the process writes the text [not found] to the report and continues based on the
default package name.
• saves the images used in the migrated reports to the images directory at the target location
• creates links in each of the XML reports to required images and drill picklist references
• transforms the XML reports generated by the migratetoc8 tool to Cognos 8 report
specifications
• encodes the report specifications into the string format required by Cognos 8 import
deployment
• creates the deployment archive and copies it to the deployment directory
• creates a log file in the _LOG directory at the target location. The log file contains details
about what happens during the deployment and links to troubleshooting topics in the
documentation to help you solve any problems.
• if you use the optional -a parameter, deploytoc8 imports the reports to Cognos 8. For Cognos
Series 7 Web-based content, the Upfront NewsIndex structure is preserved in Cognos
Connection.
For information about installing the tool, see the Migration Tools Installation and Configuration
Guide.
Syntax
The syntax to run the deploytoc8 migration tool is
deploytoc8 -options --source location --target location
All parameters are case sensitive.
The source and target keywords are optional. If you do not include the keywords, the first
directory is the source and the second directory is the target.
Parameter
Description
-h Shows a description of the parameters. To use this option, do
not specify source or target.
--source location
--target location
Specifies the location of the migration deployment package.
The location of the package created by the migratetoc8
command has the following name format:
timestamp.computer_name.migratetoc8
Specifies the parent folder for the deployment package
created by the deploytoc8 process. To make it easier to
manually import the migrated content into Cognos 8, use the
deployment files location as specified in Cognos
Configuration as the target. The deploytoc8 process creates a
new folder in the target location with the following name
format:
timestamp.computer_name.deploytoc8
Existing content in the target location is not deleted or
changed.
-a Optional
Automatically deploy the reports to Cognos 8. If you do not
use this option, you must manually import from the
deployment archive later.
User Guide 49

Chapter 4: Migrating Applications
Parameter
Description
--user user_ID Specifies the user name to sign on to Cognos 8.
If anonymous access is disabled in Cognos 8, you must
provide user and namespace information with the deploytoc8
command.
--password user_password Specifies the user password to sign on to Cognos 8.
If a password is not required for the user, do not add
--password to the command. For example, in the following
command, administrator does not require a password:
deploytoc8 C:\exported_reports C:\c8_reports
--user administrator --namespace "Series 7"
--namespace namespace_ID
Specifies the namespace that contains the user information.
You can obtain the namespace ID from Cognos
Configuration.
-y strategy Specifies the target studio for migrated PowerPlay reports.
For more information about how PowerPlay report features
map to Cognos 8 studios, see "PowerPlay Mapping" (p. 71).
This parameter has the following options:
• analysis - migrate all reports to Analysis Studio
• report - migrate all reports to Report Studio. This is the
default action if you do not use the y parameter.
-t time Optional
Specifies the number of seconds allowed by Cognos 8 for the
SDK calls used by the deploytoc8 process.
By default, the time-out limit is 60 seconds. Use this optional
parameter to specify a greater amount of time if the
deploytoc8 log file includes read timed-out exception errors.
These errors typically occur when migrating reports
associated with Framework Manager packages created from
large migrated Impromptu catalogs.
-q Optional
Suppresses the display of progress messages during the export
process. Errors and warnings still appear in the log file.
Example: Deploy a Migration Package to a Deployment Archive
The following command converts the migration package to a Cognos 8 deployment archive:
deploytoc8 C:\exported_reports C:\c8_reports --user administrator
--password admin1234 --namespace "Series 7"
Example: Automatically Deploy the Migrated Content
The following command converts the migration package to a Cognos 8 deployment archive and
automatically imports the migrated content to Cognos Connection:
deploytoc8 -a C:\exported_reports C:\c8_reports --user
administrator --password admin1234 --namespace "Series 7"
Example: Specify Report Studio as the Target for PowerPlay Reports
The following command converts PowerPlay reports for use in Report Studio:
deploytoc8 C:\exported_reports C:\c8_reports --user administrator
--password admin1234 --namespace "Series 7" -y report
50 Migration Tools

Migration Deployment Archive
Chapter 4: Migrating Applications
After you run the deploytoc8 command, the target directory contains several directories and files.
You may need to work with the following content:
• target\_LOG\viewMigrationLog.html
You can open viewMigrationLog.html in a Web browser. This log file contains information
about both the migratetoc8 and deploytoc8 processes.
• target\deployment\_DEPLOYMENT\
This directory contains the compressed deployment archive files (.zip) that you can import
into Cognos 8. For more information about importing deployment archives, see the Cognos 8
Administration and Security Guide.
Do not change or delete any of the directories or files from the migration deployment archive.
Import a Deployment Archive
If you do not use the option to automatically import content to Cognos 8 when you run the
deploytoc8 command, you must import the deployment archive in Cognos Connection to make
the content available to users.
If the deployment archive is not available in the New Import wizard, copy the .zip file from
target\_SUPPORT\deployment\_DEPLOYMENT to the Deployment files location specified in the
Environment section in Cognos Configuration. An example of the deployment archive name
format is 20060207T143105.zip. You can copy the file to a different location on the same
computer or to a different Windows or UNIX computer. If you are transferring the file from a
Windows computer to a UNIX computer, use a binary file transfer method.
For instructions about importing a deployment archive, see the Cognos 8 Administration and
Security Guide.
Review the Migration Log File
You should review the migration log file to see details and results about the migration processes.
The log file, named viewMigrationLog.html, is located in the _LOG folder in the target location
used for the deploytoc8 process. The log file contains information about both the migratetoc8
process and the deploytoc8 process.
The information in the log file helps you assess the results of the migration and determine the
amount of work required to refine the content in Cognos 8. Sometimes only minor updates are
required in Cognos 8 to correct errors and warnings in the log file. In other cases, you may find
that it is more efficient to continue to use the content in Cognos Series 7 and develop new
applications in Cognos 8.
For more information about correcting errors and warnings in the log file, see
"Troubleshooting" (p. 133).
Test the Migration
After the packages from the deployment archive are imported, check whether all the entries were
deployed successfully in the target environment by doing the following:
Steps
1. Review the run history for a deployment in Cognos Connection.
For information about run histories, see the Cognos 8 Administration and Security Guide.
2. Ensure that the import process created the correct packages, folders, and folder contents.
3. Check the permissions for the imported entries.
4. Run imported reports to ensure that the reports work as expected.
User Guide 51

Chapter 4: Migrating Applications
You may see differences in functionality and appearance. Not all features in Cognos Series 7
have a direct or equivalent functionality in Cognos 8 (p. 17). For example, you must
reconfigure some drill-though options. For more information, see Part 3: Mapping Cognos
Series 7 Objects to Cognos 8 Objects.
If some migrated reports do not run, see "Troubleshooting" (p. 133).
When all your reports are able to run, provide users with access. You can also delete the source
and target directories specified in the deploytoc8 command.
Tip: We recommend that you first back up the log files in the target directory so you have a record
of the migration.
Provide Users With Access to the Migrated Application
You must enable the package so that users can access it.
By default, the package is disabled and none of the entries it contains are accessible in the target
environment after deployment. The package is disabled so that you can test it in the target
environment before you make it available to users.
You must have read and write permissions to enable a package.
For instructions about enabling entries in Cognos Connection, see the Cognos 8 Administration
and Security Guide.
52 Migration Tools

Chapter 5: Migrating PowerPlay Reports
Published to Cognos 8
Starting with Cognos Series 7 version 3 (7.3), you can publish PowerPlay reports and cubes to
Cognos ReportNet. This publishing option is supported by subsequent releases of Cognos
ReportNet and Cognos 8 BI.
If you have PowerPlay reports published to Cognos Connection, you can migrate those reports to
Analysis Studio or Report Studio directly from Cognos Connection. You can migrate only one
report at a time.
For information about other options for migrating PowerPlay reports, see "Migrating
Applications" (p. 39).
To migrate PowerPlay reports published to Cognos 8:
❑ Install the Cognos 8 migration tool on the Cognos 8 computer.
You do not have to install the Cognos Series 7 migration tools.
For more information, see the Migration Tools Installation and Configuration Guide.
❑ Configure Cognos 8 to enable PowerPlay report migration (p. 53).
❑ Ensure that the reports can map to a package.
To support PowerPlay report migration, create data source connections to the required cubes
using either Framework Manager or Cognos Connection. In Framework Manager, use the
cube data source in a Framework Manager project, and then publish a package to Cognos
Connection using the cube name for the package name. For example, if reports use a cube
named Great_Outdoors, create and publish a package named Great_Outdoors. You must
create a separate package for each cube.
For more information, see the Cognos 8 Administration and Security Guide, and the
Framework Manager User Guide.
❑ Open a PowerPlay report in either Analysis Studio or Report Studio (p. 54).
After you open the PowerPlay report in either Analysis Studio or Report Studio, the migration is
complete. You can then choose whether or not to save the migrated report, as saving is not part of
the migration process. To prevent duplicate reports, you may want to delete the original
PowerPlay report from Cognos Connection. If you make changes to the PowerPlay report, you
must repeat the migration process to apply the changes to the version of the report in Analysis
Studio or Report Studio.
Configure Cognos 8 to Support PowerPlay Report Migration
After you install the Cognos 8 migration tool, you must enable PowerPlay report migration using
the Server Administration.
Steps
1. In Cognos Connection, click Tools, Server Administration.
2. In Server Administration, click the Configure tab.
3. Click the set properties button.
4. Click the Settings tab and then click Edit for environment advanced settings.
5. Type the following parameter and value to add a new parameter to the advanced
configuration settings.
Parameter = MIGR.EnablePPUpgrade
User Guide 53

Chapter 5: Migrating PowerPlay Reports Published to Cognos 8
Value = true
6. Click OK to save the configuration change.
7. Click OK to return to Server Configuration.
PowerPlay report migration from Cognos Connection is now enabled.
Migrate a Published PowerPlay Report to Analysis Studio or
Report Studio
To migrate a PowerPlay report published to Cognos Connection, you open the report in either
Analysis Studio or Report Studio. You can then choose whether to save the migrated report.
Migration of published PowerPlay reports directly from Cognos Connection is supported,
beginning with Cognos 8 MR1, under the following conditions:
• You have PowerPlay reports published from Cognos Series 7 version 4 (7.4) to Cognos 8
MR1.
• You published PowerPlay reports from a version of Cognos Series 7 version 3 earlier than
MR3 to either Cognos ReportNet or the initial release of Cognos 8, and you subsequently
migrated to Cognos 8 MR1 using content store migration.
If you published PowerPlay reports from a version of Cognos Series 7 version 3 earlier than MR3
directly to Cognos 8 MR1, you cannot migrate those reports directly in Cognos Connection. You
must use the migration tools to migrate your PowerPlay reports. If you use a version of Cognos
Series 7 version 3 earlier than MR3, and you want to migrate PowerPlay reports in Cognos
Connection, migrate to Cognos Series 7 (7.4) before publishing the reports.
You must enable PowerPlay report migration (p. 53) before completing the following steps.
Steps
1. In Cognos Connection, click the More option for a PowerPlay report.
2. Choose the target studio to use for the migration:
• To migrate the report to Analysis Studio, click Open with Analysis Studio.
• To migrate the report to Report Studio, click Open with Report Studio.
The report opens in the studio you selected.
3. You can now save the report.
The PowerPlay report is migrated to the studio you selected. You may want to delete the original
PowerPlay report from Cognos Connection and use only the migrated version of the report. If you
make changes to the PowerPlay report, you must complete the migration steps again to see the
changes in the version of the report in Analysis Studio or Report Studio.
Published PowerPlay Reports Migrated to Cognos 8 Log Files
Any errors encountered when migrating PowerPlay reports published to Cognos 8 Cognos
Connection are logged in Cognos 8 installation_location\temp\migrsvp.
Consult these files to troubleshoot any problems encountered when you migrate a report. In
addition, we recommend that you periodically clean out the \temp directory.
54 Migration Tools

PART 3: Mapping Cognos Series 7 Objects to
Cognos 8 Objects
User Guide 55

56 Migration Tools

Chapter 6: Impromptu Catalog Mapping
The information in this section will help you understand the mapping of objects when migrating
Impromptu metadata models (catalogs) from Cognos Series 7 to Cognos 8.
For information about Impromptu functions migration, see "Impromptu Functions
Mapping" (p. 127).
Security
You apply user class filters at run time to give user classes access to specific data.
You can create filter expressions using security metadata such as user classes, user roles, and user
names.
Migration replaces the references in expressions to user-name with references to the session
parameter #sq($account.personalInfo.userName)#. Also, migration replaces the references in
expressions to user-classes with #CSVIdentityName(%ImportedUserClasses)#, where
ImportedUserClasses is a hard-coded parameter map. During the import, the expression is loaded
with the currently available roles, both as map keys and as map values.
You can secure an Impromptu catalog using Access Manager, or define the security in the catalog
itself. If you secure the catalog using Access Manager, the user-name and user-class tokens are
exposed. If you secure the catalog using its internal security, the catalog-user-profile() tokens are
mapped to #CSVIdentityName(%ImportedUserClasses)#.
You must replicate security information stored directly in an Impromptu catalog in the namespace
that contains the security information used by Cognos 8.
The following are examples of the migration mapping for Impromptu filter expressions that use
internal catalog security.
Impromptu filter expression
user-name='Bob'
'Sales' in catalog-user-profile()
Framework Manager expression
#sq($account.personalInfo.userName)#='Bob'
'Sales' in #CSVIdentityName(%ImportedUserClasses)#
In addition to these expressions, the migration process creates an empty parameter map named
ImportedUserClasses that the Cognos 8 modeler can modify.
Mapping Objects in the Physical View
Each object in the physical view of Impromptu catalogs is mapped to Framework Manager as a
model object in the Tables namespace. Entries of the Tables namespace are namespaces that have
the same name as the logical database that the catalog is based on.
When you expand the Tables namespace, you see query subjects and query items in a structure
that is similar to tables and columns in the physical view of catalogs. Each of these objects has its
own set of properties that you can view in the properties pane.
To preserve a user experience close to that in Cognos Series 7, the objects created from the
physical layer of the catalog are normally hidden from report authors in the Cognos 8 authoring
tools that use the Framework Manager model.
User Guide 57

Chapter 6: Impromptu Catalog Mapping
The Impromptu catalog physical view objects are mapped to Framework Manager model objects
as follows.
Impromptu object
Catalog
Table and Table Alias
Table column
Join
Framework Manager object
Model
Query subject
Note: Security filters for table aliases are not
migrated.
Query item
Relationship between database query subjects
The Catalog
The properties of an Impromptu catalog are migrated to properties of a Framework Manager
namespace. Migration creates a single default object-based package for every user profile and user
class in this namespace.
Impromptu catalog property
Name
Description
Access Manager namespace
Is distributed
Path to the catalog
Unique ID
Framework Manager model property
Name
Description
Access Manager namespace
Is distributed
Catalog path
Unique ID
Note: Access Manager namespace, Is distributed, Path to the catalog, and Unique ID are custom
properties.
Tables and Table Aliases
The properties of Impromptu catalog tables and table aliases are migrated to properties of
Framework Manager query subjects in the following way.
Impromptu table property
Name
Qualification level
Weight
Master table reference (for table aliases)
Framework Manager query subject property
Name
Not supported in Cognos 8, so not migrated
Not supported in Cognos 8, so not migrated
Not mapped
58 Migration Tools

Table Columns
Chapter 6: Impromptu Catalog Mapping
The properties of Impromptu catalog table columns are migrated to properties of Framework
Manager query items in the following way.
Impromptu column property
Name
Data type
IsKey
Framework Manager query item property
Name
Datatype
Impromptu table columns with the IsKey attribute
set to true become query items with the Usage
attribute set to Identifier. In the model, the
determinant is created with query items created
from Impromptu table columns with IsKey set to
true. These query items become determinant keys.
Joins
Migration migrates Impromptu joins to the Framework Manager model as relationships between
query subjects. The name of the relationship is as follows:
[LeftTableName] [RightTableName]
Migration creates left and right cardinality based on the following rules:
• Left minimum cardinality is equal to 1 if the join type is either inner or right outer.
• Left minimum cardinality is equal to 0 if the join type is either full outer or left outer.
• Left maximum cardinality is always equal to 1.
• Right minimum cardinality is equal to 1 if the join type is either inner or left outer.
• Right minimum cardinality is equal to 0 if the join type is either full outer or right outer.
• Right maximum cardinality is always equal to 1.
Impromptu join property
Left table reference
Right table reference
Expression
Join type
Framework Manager relationship property
left refobject
right refobject
Expression
For more information, see "Migrating
Expressions" (p. 62).
Not mapped
Mapping Objects in the Business View
Migration maps objects in the business view of Impromptu catalogs to Framework Manager as
model objects in the Folders namespace.
User Guide 59

Chapter 6: Impromptu Catalog Mapping
When you expand the Tables namespace, you see query subjects and query items in a structure
that is similar to tables and columns in the business view of catalogs. Each of these objects has its
own set of properties that you can view in the properties pane.
Impromptu business view object
property
Folder
Folder column
Calculation
Condition
Prompt
Framework Manager model property
Namespace or model query subject
Simple reference to a query item, calculation, or
filter
Embedded calculation or stand-alone calculation
Filter
Model prompt
Folders
Folder Columns
Calculations
Migration maps Impromptu catalog folders to a Framework Manager model as namespaces or
model query subjects.
If all the children of the folder are folder columns or calculations, the folder is migrated as a model
query subject. Otherwise, the folder is migrated to a Framework Manager model namespace.
Empty folders and empty folder structures are not migrated.
The Impromptu catalog folder name is mapped to the Framework Manager namespace or model
query subject name.
Duplicate Folder Names
Framework Manager does not allow duplicate object names in any namespace. When you migrate
a catalog that has folders with duplicate names, the migration process modifies duplicate names to
ensure each migrated object has a unique name. For example, if Country was used as a folder
name more than once in the catalog business view, the migration process adds a unique postfix to
the name: Country~1, Country~2, and so on. The modified names do not affect the functionality
of migrated Impromptu reports.
You can change object names in Framework Manager after migrating a catalog. However, you
should make the changes before you publish the metadata package to the Cognos 8 content store
and before you use the deploytoc8 tool to migrate reports that use the catalog. If you change
names after you migrate Impromptu reports, you must repeat the deploytoc8 part of the report
migration process.
Migration maps Impromptu catalog folder names to Framework Manager as either model query
items or model calculations.
If the parent folder is migrated as a namespace, the folder columns are migrated to model
calculations containing a simple reference to a query item. Otherwise, the folder columns are
migrated to model query items.
Impromptu catalog folder column names are mapped to Framework Manager query item names
or model calculation names.
Migration maps Impromptu calculations to Framework Manager as either embedded calculations
or model calculations.
60 Migration Tools

Chapter 6: Impromptu Catalog Mapping
If the parent folder maps to Framework Manager as a namespace, the calculation maps to a model
calculation. Otherwise, the calculation maps to an embedded calculation.
Impromptu calculation property
Name
Expression
Framework Manager calculation property
Name
Expression
For more information, see "Migrating
Expressions" (p. 62).
Conditions
Migration maps Impromptu conditions to Framework Manager as model filters.
Impromptu condition property
Name
Expression
Framework Manager model filter property
Name
Expression
For more information, see "Migrating
Expressions" (p. 62).
Prompts
Migration maps Impromptu prompts stored in the catalog to Framework Manager as model
prompts (model calculations) with the following syntax:
#prompt(promptName,datatype)#
An example is #prompt(’Country’,’string’)#.
The model prompts are placed in the namespace created from the folder that contains these
prompt definitions in the Impromptu catalog. The Impromptu prompt definition string, as
returned by the Impromptu Catalog Automation Interface, is placed in the model as the Prompt
Definition property in the Impromptu Properties property set of the model prompt.
The following types of prompts are migrated:
• type-in prompts
The data type in the prompt value determines the mapping for type-in prompts. Possible
Cognos 8 mappings are text box prompt, date prompt, time prompt, date and time prompt,
or interval prompt.
• catalog picklist prompts are migrated to value prompts
• report picklist prompts are migrated to value prompts
File picklist prompts are not migrated.
A list of migrated prompts appears in the folder namespace.
Impromptu prompt properties that do not have a corresponding property in Framework Manager
become custom properties. In the Framework Manager expression, a reference to the model
prompt replaces the prompt reference in the Impromptu expression.
User Guide 61

Chapter 6: Impromptu Catalog Mapping
Migrating Expressions
Migration migrates Impromptu expressions to Framework Manager expressions. The following
table describes how components in expressions are migrated.
Impromptu catalog expression
Folder item references
Stored procedure references
Prompt references
Security by value tokens
References to external User Defined
Functions (UDFs)
Calls to database built-in functions
Database UDFs
Framework Manager expression
Reference to query item reference
Model function references
Model calculation references representing prompts
Equivalent Framework Manager tokens
Replicated literally in the Framework Manager
expressions. Expressions containing this type of
reference may require editing after the migration is
complete.
Calls to Cognos 8 database functions or constructs
using these functions. For more information, see
"Impromptu Functions Mapping" (p. 127).
References to model function
After you migrate, verify the functions and expressions in Framework Manager before publishing
the package from the model. If an expression is not valid in Framework Manager, check whether
the expression is valid in the original Impromptu catalog.
Calculations in Impromptu catalogs may contain constructs that are not supported in Cognos 8.
In such cases, you may need to manually edit the expressions using the Framework Manager
Expression Editor to achieve the expected results.
You can also test the expressions in Framework Manager. For more information, see the
Framework Manager User Guide.
User Defined Functions
Objects Not Migrated
The migration process does not migrate external user defined functions (UDFs). If an Impromptu
expression references an external UDF, the Framework Manager expression includes a literal copy
of the Impromptu reference syntax.
Database UDFs are migrated to Framework Manager as model functions in the Folders
namespace. As long as the function still exists in the database schema, the expressions referencing
the database UDF are valid.
For more information about expressions, see the Framework Manager User Guide.
Migration does not process the following Impromptu catalog objects:
• external user-defined functions (UDFs)
• governors
There is no equivalent for Impromptu governors in Framework Manager. Framework
Manager governors are set at the project level and apply to all report consumers using a
published package.
• HotFiles and snapshots
• table weighting
• client-server settings
62 Migration Tools

Chapter 6: Impromptu Catalog Mapping
Client-server settings are not required. The settings are for Impromptu client and are not
applicable to a Web environment.
User Guide 63

Chapter 6: Impromptu Catalog Mapping
64 Migration Tools

Chapter 7: Impromptu Reports Mapping
The information in this section will help you understand the mapping of objects when migrating
Impromptu reports from Cognos Series 7 to Cognos 8.
For information about Impromptu functions migration, see "Impromptu Functions
Mapping" (p. 127).
Report Functionality Mapping
Impromptu report functionality is preserved when equivalent or similar functionality is available
in Cognos 8. The following table includes information about how report functionality is mapped
to Cognos 8. If report functionality does not map to Cognos 8, the specific functionality is
dropped from the migrated report. Depending on the structure of the report, dropping a feature
can have a significant impact on how the report appears in Report Studio. You may be able to
recreate the same or similar functionality in Cognos 8. The migration log file will include
information about changes or errors in report functionality.
Report functionality
Calculated columns in a
crosstab
Catalog and report paths
Charts
Client-server balancing options
Mapping
Not migrated
Instead of a path to the catalog, Cognos 8 uses a model path.
The ModelPath() function returns the search path to the
model. The ReportPath() function returns the search path
to a report.
A search path uses expressions to specify a path through the
content store hierarchy to find objects. The search path is
similar to a path in an operating system such as DOS or
UNIX in that the search path is constructed through
parent-child relationships from the root object.
Charts are migrated except for the following types:
• Gantt
• log line
• stock
• spider
Note: Legends do not appear in Impromptu reports migrated
to Cognos 8 unless the chart associated with the legend is a
bar chart.
Limited local and database-only processing options are
supported in Cognos 8.
The flexible processing option is not. Use the limited local
processing option instead.
User Guide 65

Chapter 7: Impromptu Reports Mapping
Report functionality
Drill-through access
Formats
Governors
Impromptu macros
Impromptu query definition
(.iqd) files
Overall headers and footers for
crosstab reports
Page count
Placeholders
Prompts
Mapping
Drill-through settings between Impromptu reports are
migrated to Cognos 8 if you migrate all related reports at the
same time.
Migration does not include drill-through settings from
Cognos Series 7 to Cognos 8. However, you can set up
drill-through access in Cognos Connection after you deploy
the migrated reports.
For more information, see the Cognos Connection User
Guide.
Formats are migrated except for the following types:
• string formatting
For example, if a report uses the format Aa* for a string,
the string appears as unformatted in Cognos 8.
• mixed-type formatting
For example, if a number is formatted as a date in an
Impromptu report, the number appears as unformatted
in Cognos 8.
Governors are migrated except for the following settings:
• sorting on non-indexed columns
• direct entry SQL
• warning when an execution query exceeds a specified
number of database tables used
• warning when an execution query exceeds a specified
number of rows of data retrieved
• warning when an executing query exceeds a specified
number of minutes
Migration does not process Impromptu macros. Similar
functionality can be implemented in Cognos 8 using the
Software Development Kit.
Not migrated
Not migrated
Total page count in HTML report output is replaced with a
question mark (?). However, page count is provided in PDF
report output.
Not migrated
The following types of prompts are migrated:
• type-in prompts
The data type in the prompt value determines the
mapping for type-in prompts. Possible Cognos 8
mappings are text box prompt, date prompt, time
prompt, date and time prompt, or interval prompt.
• catalog picklist prompts are migrated to value prompts
• report picklist prompts are migrated to value prompts
File picklist prompts are not migrated.
66 Migration Tools

Chapter 7: Impromptu Reports Mapping
Report functionality
Report objects
Report templates
Save as HTML options
Snapshots
Summary filters in crosstab
reports
Suppression of zero values
Table of contents for HTML
reports
Mapping
Report objects are migrated except for the following:
• OLE objects
• rectangles
• column spacers
• running page totals
• catalog file name
• database name
• database user ID
• snapshot timestamp
• filter text (detail, summary, and drill-through)
• catalog user profile
• user classes
• user name
Not migrated
Not migrated
Similar functionality is available in Cognos 8 studios.
Not migrated
Not migrated
Not migrated
You can use filters in Report Studio to achieve similar results.
Not migrated
Impromptu Report Formatting Mappings
When you view your reports in Cognos 8, you will see differences in the appearance of reports.
The way that reports are formatted for presentation differs between Impromptu, a
Windows-based product, and Cognos 8, a Web-based product. For example, layout elements such
as the lines used in headers and footers, may appear differently in Cognos 8.
If a report uses Impromptu default data formatting, the report may appear different because
Impromptu and Cognos 8 formatting defaults are different. For example, the default format for
numeric values in a report column in Cognos 8 includes a comma and the default format in
Impromptu does not.
You can use Report Studio to change the appearance of a migrated report. For more information,
see the Report Studio User Guide.
Default Formatting
In Impromptu, you can use default formatting in a report, such as the default format for column
titles and the list grid shown in the following example.
User Guide 67

Chapter 7: Impromptu Reports Mapping
In Cognos 8, the report uses the Cognos 8 default formatting as shown in the following example.
If an Impromptu report contains formatting that overrides the default formatting, the formatting
is migrated if it is supported in Cognos 8. But default formats in Impromptu are mapped to
default formats in Cognos 8, even if they are different.
Number Formatting
In Impromptu, if you set the formatting for a numeric column to 0, the values appear as numbers
without a separator, such as 40102.
In Cognos 8, the values appear with a separator, such as 40,102.
Crosstab Headers
In Impromptu, a crosstab report can include a column header or report header.
In Cognos 8, the headers do not appear.
To update the migrated report to match the original format, open the report in Report Studio and
add the headers by inserting a text item.
68 Migration Tools

Chapter 7: Impromptu Reports Mapping
Borders
In Impromptu, you can specify a border for a text frame, such as a column header.
In Cognos 8, the default formatting may not provide enough space for the borders. This means
that the borders do not appear.
To make the borders appear, open Report Studio and change the height and width of the items in
the text item.
Justification of Text Frames
In Impromptu, when you specify justification for a text item, the text aligns with the text frame as
defined.
In Cognos 8, a text item that is not wide enough to show all text expands to show all text. As a
result, the text may have a different horizontal and vertical position on the page.
To make the text appear in a similar location on the page as it does in Impromptu, open Report
Studio and change the properties of the text item or the block item that contains the text item.
Page Width
In Impromptu, when you insert a text frame without specifying word wrap, the text appears as in
the first text frame in the following example.
In Cognos 8, the text causes the report to widen to show all of the text on one line.
To adjust the report width, change the size and overflow settings for the block that contains the
text item. For instructions, see the Report Studio User Guide.
User Guide 69

Chapter 7: Impromptu Reports Mapping
70 Migration Tools

Chapter 8: PowerPlay Mapping
The information in this section will help you understand the mapping of objects when migrating
PowerPlay reports to Analysis Studio or Report Studio. If a feature or functionality is not
mentioned, an equivalent is available in Cognos 8.
PowerPlay Windows reports are migrated using the following rules:
• Reporter reports are migrated according to PowerPlay Windows behavior.
• Explorer reports are migrated according to PowerPlay Web behavior.
Analysis Studio and Report Studio are different from PowerPlay. To ensure a successful migration,
take the time necessary to learn Analysis Studio and Report Studio before migrating PowerPlay
reports.
Report Structure Mappings
Most report structure features are preserved or mapped to an equivalent element.
The following table includes information about report structures that are and are not migrated.
Some migrated report structures may cause unexpected results. The migration log file includes
information about any changes or errors in the report structure.
Report structure Report Studio Analysis Studio
Indented layout for
crosstab displays
Not migrated
Migrated reports that used
indented layout display as a
standard crosstab. You can
reproduce the indented layout in
Report Studio.
Not migrated
Migrated reports that used
indented layout display as a
standard crosstab.
Layers Partially migrated Not migrated including related
settings such as Show Value As
% of Layer Total
Nested charts Migrated Not migrated
Alternate hierarchies of
the same dimension on
different axes
Not migrated
Migrated reports use the primary
hierarchy.
Categories from alternate
hierarchies of the same dimension
that are nested under categories
from a different hierarchy of the
same dimension are not migrated.
Such categories are dropped in the
migrated report.
Not migrated
Migrated reports use the
primary hierarchy.
Categories from alternate
hierarchies of the same
dimension that are nested
under categories from a
different hierarchy of the same
dimension are not migrated.
Such categories are dropped in
the migrated report.
User Guide 71

Chapter 8: PowerPlay Mapping
Layers
Layers in PowerPlay Windows reports are migrated to Report Studio with some restrictions. Each
layer is migrated to a page group within a page set that has a defined master-detail link. If layers
are built by members from nested levels, multiple page groups are created within the page set. For
example, the layer "Canada.Toronto" is migrated to two page groups, one for Countries and the
other for Cities.
If layers are built using multiple hierarchies and dimensions, multiple page sets are created. Each
page set contains a copy of the report page and its own page groups.
When you run the migrated report, clicking Page Up and Page Down corresponds to viewing the
different layers.
Layers in charts are also migrated. If a chart has layers as well as different displays, the displays
appear in each layer in the migrated report. For example, if a chart has three layers and 24
displays, the migrated report contains three pages and each page contains 24 displays. For more
information about chart displays, see "Graphical Display Mappings" (p. 81).
The following restrictions exist when migrating layers:
• For layers built using members that are from the same dimension but from different
hierarchies, and have the same caption in the cube, migration only processes members that are
in the primary hierarchy.
• Calculation layers are dropped during migration, because Report Studio page sets do not
support a grouping on a calculation.
• Layers built using multi-level subsets are not migrated, because Cognos 8 does not currently
support them.
Only subsets created with a single level and with layers that are later applied to different
members of the subset are migrated.
• The order of layers is not always maintained in the migrated report.
It is sometimes necessary to reorganize layers in order to improve performance in the migrated
report. This usually applies to Reporter mode reports when there are categories from the same
hierarchy. In general, the categories are adjacent to each other.
• Layers built using measures are dropped after migration, because Cognos 8 does not support
page groups built using measures.
• The current layer is automatically reset to the first layer when you drill up or drill down. To
return to the page that you were on, click Page Up or Page Down.
• Summary layers are dropped if multiple page groups are created.
• If layers and a filter share the same dimension, only layers from the same dimension are
migrated. The filter is not migrated.
• Colors used for different layers in charts are not migrated.
The information about colors is stored as default values. PowerPlay default values are not
migrated. For more information, see "Report Formatting Mappings" (p. 79).
Tip: You can choose the color of each layer in the migrated report by specifying a conditional
palette for the chart.
72 Migration Tools

Chapter 8: PowerPlay Mapping
Report Functionality Mappings
PowerPlay report functionality is preserved when equivalent or similar functionality is available in
Cognos 8. The following table includes information about how report functionality is mapped to
Cognos 8. If report functionality does not map to Cognos 8, the specific functionality is dropped
from the migrated report. Depending on the structure of the report, dropping a feature can have a
significant impact on how the report appears in Report Studio or Analysis Studio. You may be
able to recreate the same or similar functionality in Cognos 8. The migration log file will include
information about changes or errors in report functionality.
Report functionality Report Studio Analysis Studio
80/20 suppression Not migrated Not migrated
Open the migrated report in
Analysis Studio and use top or
bottom filtering to achieve
similar results.
Bookmarks
Automatic exception
highlighting
Custom exception
definitions and formatting
Not migrated
Bookmarks are encoded URLs,
and the migration tools migrate
only saved reports. To migrate
bookmarked content, open the
bookmark, save the target as a
PowerPlay Web report, and then
migrate the .ppx file.
Not migrated
Migrated
Not migrated
Bookmarks are encoded
URLs, and the migration tools
migrate only saved reports. To
migrate the bookmarked
content, open the bookmark,
save the target as a PowerPlay
Web report, and then migrate
the .ppx file.
Not migrated
Not migrated
Zero suppression Migrated Migrated
Advanced subsets Migrated Migrated
Custom subsets
(PowerPlay Web reports
only)
Parentage subsets
Migrated
Migrated
The migration process creates
one or two data items for each
parentage subset, depending on
the option clicked in the
Qualifier box in the Parentage
Subset dialog box.
Note: In multi-level parentage
subsets, if all members of a
lower level are hidden, the
parent is hidden.
Migrated
Migrated
The migration process creates
one or two items for each
parentage subset, depending
on the option clicked in the
Qualifier box in the Parentage
Subset dialog box.
Note: In multi-level parentage
subsets, if all members of a
lower level are hidden, the
parent remains. For more
information, see "Hidden
Children Levels" (p. 88).
Find subsets Partially migrated Partially migrated
Forecast calculation Not migrated Not migrated
User Guide 73

Chapter 8: PowerPlay Mapping
Report functionality Report Studio Analysis Studio
Cumulative percent of base
calculation
Not migrated
Not migrated
Percent of base calculation Not migrated Not migrated
Accumulate calculation Not migrated Not migrated
Calculations across
dimensions or hierarchies
In PowerPlay, you can
create a calculation based
on categories from
different dimensions, or
from different hierarchies
of the same dimension.
Ranking across dimensions
or hierarchies
Rank calculations
Calculations based on
hidden categories
In PowerPlay, a report can
show the results of a
calculation based on
categories that are hidden.
Calculations in lower
levels of single dimension
nesting
In PowerPlay, you can
create a calculation using
nested levels in the same
dimension. The calculation
will appear in the same
dimension.
Calculation override
precedence
Not migrated
You cannot create calculations
between hierarchies or
dimensions in Report Studio.
You may be able to achieve the
desired results using an alternate
hierarchy.
Not migrated
For more information about
ranking, see "Rank Values Are
Different in Migrated
Report" (p. 146).
Migrated
If a rank calculation does not
appear in the report layout, it is
not migrated. In addition, all
other calculations that refer to
the rank calculation are not
migrated.
Migrated
Migrated
The calculation will appear
nested at the same level in all
dimensions.
Not migrated
To specify calculation override
precedence in a migrated report,
set the Solve Order property.
Not migrated
You cannot create calculations
between hierarchies or
dimensions in Analysis Studio.
You may be able to achieve
the desired results using an
alternate hierarchy.
Not migrated
For more information about
ranking, see "Rank Values Are
Different in Migrated
Report" (p. 146).
Migrated
If a rank calculation does not
appear in the report layout, it
is not migrated. In addition,
all other calculations that refer
to the rank calculation are not
migrated.
Migrated
For more information about
exceptions, see "Position of
Calculated
Categories" (p. 85).
Not migrated
Not migrated
74 Migration Tools

Chapter 8: PowerPlay Mapping
Report functionality Report Studio Analysis Studio
Show Value As % settings
Migrated except for the
following:
• Show Value as % of Layer
Total
• Save Value as % setting
applied to measures used in
row or column axis
Migrated except for the
following:
• Show Value as % of Layer
Total
• Save Value as % setting
applied to measures used
in row or column axis
Prompts Partially migrated Not migrated
Prompting for alternate
drill paths
Intersect categories
Not migrated
Migrated
The migration process creates
data items that use the tuple
function.
Not migrated
Not migrated
Custom Exception Definitions and Formatting
Zero Suppression
A single report variable is created that contains all of the information regarding where to apply
the exceptions and formatting, the style to be used for each one of them, and the conditions that
trigger a certain style. If an exception and formatting are applied to the same row or column, the
exception takes precedence.
The migration process does not mix formats. Formatting is applied in the migrated report in the
order that it was applied in the original report. As a result, when a style, whether it's a custom
exception or formatting, is applied, it overrides the style that was previously applied. For example,
a background pattern is applied to the row in a crosstab, and then a foreground color is applied to
a column. The intersection cell of the row and column loses the background pattern, and only the
foreground color is applied.
Notes
• Calculations and ranking also have precedence over formatting. The rules of precedence are
custom exceptions, calculations and ranking, and then formatting.
• Only solid background patterns are migrated. For more information, see "Background
Patterns" (p. 80).
• If a custom exception definition and formatting are applied to a measure in either axis of a
crosstab, the formatting is dropped in the migrated report.
• Shared custom exception definitions are not migrated. For more information, see "Shared
Custom Exception Definition Is not Applied in Migrated PowerPlay Report" (p. 149).
Zero suppression in PowerPlay, with the exception of PowerPlay Windows Reporter reports, is
migrated in both Report Studio and Analysis Studio. Zero suppression in Reporter reports is not
migrated because zero suppression is migrated based on summaries, and Reporter reports do not
have summaries.
PowerPlay, Report Studio, and Analysis Studio implement zero suppression differently. As a
result, different categories may be suppressed in migrated reports.
User Guide 75

Chapter 8: PowerPlay Mapping
PowerPlay
In PowerPlay, all values in a row or column must be zero or null for zero suppression to be
applied. For example, if zero suppression is applied to the rows and columns in the following
crosstab, there is no change.
Camping Equipment Outdoor Protection Products
2004 10000 -10000 0
2005 -10000 32000 12000
Years 0 12000 12000
In addition, PowerPlay applies zero suppression to summaries as well as to calculated columns
and rows.
In PowerPlay Windows, user preferences determine the types of values to which zero suppression
is applied, such as division by zero values and missing values. User preferences are not migrated.
Report Studio
Report Studio does not automatically suppress zeros. You use expressions to filter data, and you
can create expressions to filter zero or null values. When migrating a PowerPlay report to Report
Studio, the migration process creates expressions that replicate the way that Analysis Studio
applies zero or null suppression using the totals-based suppression method. In addition, reports
migrated to Report Studio will have zero suppression applied to calculated columns and rows, but
not to summary rows and columns nor nested rows and columns.
For each data item that can have zero suppression applied in the migrated report, three
expressions are created. For example, the following is the first expression created for the data item
Quarter, which is a row item in a crosstab.
Tip: To access this expression, double-click Quarter.
zero-suppressed on row indicates that zero suppression is on for a row item, and when you
run the report, it calls an expression with a unique name such as
Quarter_N10127(zero-suppressed on row). Alternatively, zero suppression for a column item is
indicated by zero-suppressed on col. If you want to turn off zero suppression, change the
clause to non zero-suppressed on row. When you run the report, an expression with a unique
name such as Quarter_N10127(non zero-suppression on row) is called. Do not modify these two
expressions.
After you migrate a PowerPlay report to Report Studio, verify that the data is filtered as expected.
If necessary, modify the expressions to achieve the required results. Note that you can turn zero
suppression off or on in Report Studio only if zero suppression was turned on in the PowerPlay
report before it was migrated. Otherwise, zero suppression filters are not added during the report
migration.
Zero suppression cannot be applied in a crosstab if either of the following is true:
• The default measure is non-aggregating.
A message in the migration log file explains why zero suppression was not applied.
76 Migration Tools

Chapter 8: PowerPlay Mapping
• There is a measure on the opposite axis.
For example, a PowerPlay report has zero suppression on both the rows and columns of a
crosstab, and the rows contain a measure. When the report is migrated to Report Studio, row
suppression is applied because the columns do not contain a measure. However, column
suppression cannot be applied because the rows contain a measure. A message in the
migration log file explains why zero suppression was not applied to the columns.
Tip: If you want to turn off zero suppression in a large report or for many columns, use the Copy
To Clipboard command to copy the report specification to the clipboard, and then paste it in a
text or XML editor. You can then do a search and replace to quickly turn off zero suppression for
the columns you want. When you are finished, copy the modified report specification to the
clipboard, open it in Report Studio with the Open Report From Clipboard command, and save it.
For more information, see the Report Studio User Guide.
Analysis Studio
Analysis Studio can apply zero suppression using selection-based suppression or totals-based
suppression. A configuration setting in Cognos Connection specifies which method is used. If you
do not like the results that you are seeing, ask your administrator to change the setting. For more
information about the configuration setting, see the Documentation Updates section for the
Cognos 8 Administration and Security Guide in the Cognos 8 readme.
By default, Analysis Studio uses selection-based suppression. This means that you can select a
single row or column to remove rows or columns in the opposite axis of a crosstab that contains
only empty cells. For example, if you select the column 2005 in the following crosstab and click
Suppress, all of the rows where the revenue for 2005 is zero are suppressed.
2004 2005 Years
Humphrey Willoughby 888,168.32 564,777.42 1,452,945.74
James Ross-Hythe 1,171,047.72 1,575,106.32 2,746,154.04
Walter Taylor 0 0 0
Polly Linton 0 0 0
Maria Iacobucci 0 0 0
Josef Lopez 271,034.02 198,267.78 469,301.80
By Staff name 2,330,250.06 2,338,151.52 4,668,401.58
With totals-based suppression, Analysis Studio applies zero or null suppression based on summary
values. For example, if zero suppression is applied to the rows in the following crosstab, the 2004
row will be suppressed. If zero suppression is applied to the columns, the Camping Equipment
column will be suppressed.
Camping Equipment Outdoor Protection Products
2004 10000 -10000 0
2005 -10000 32000 12000
Years 0 12000 12000
In addition, reports migrated to Analysis Studio will not have zero suppression applied to
summary rows and columns, calculated rows and columns, and nested rows and columns.
User Guide 77

Chapter 8: PowerPlay Mapping
Advanced Subsets
Find Subsets
If you migrate a PowerPlay report to Analysis Studio, ensure that the zero and null suppression
meets expectations. If necessary, use the zero and null value suppression options in Analysis Studio
to achieve the required results. Note that in Analysis Studio, you can turn zero suppression on or
off regardless of whether zero suppression was on or off in the original PowerPlay report.
Zero suppression cannot be applied in a crosstab if either of the following is true:
• The default measure is non-aggregating.
• There is a measure on the opposite axis.
For more information about zero suppression methods, see the Documentation Updates section
for the Analysis Studio User Guide in the Cognos 8 readme.
Advanced subsets in PowerPlay Windows reports are migrated with some restrictions. Data items
are created for each advanced subset that is migrated. The number of data items that is created
depends on the number of levels in the advanced subset. The following advanced subset features
are not migrated:
• Find a name using a wildcard pattern or short name for advanced subset definitions with
restriction by name or description.
• Advanced subset as a layer.
• Calculations that reference items that are not in the report.
The calculations are dropped if the report is migrated to Analysis Studio.
• Find a name across more than one hierarchy.
Such subsets are removed during migration.
However, custom exceptions applied to an advanced subset that is not migrated may still appear
in the migrated report. For information about how custom exceptions are migrated, see "Custom
Exception Definitions and Formatting" (p. 75).
Find subsets in PowerPlay Windows reports are partially migrated. A data item is created for each
find subset that is migrated. The following find subset features are not migrated.
• Find a string from all dimensions and from a report.
Such find subsets are removed during migration.
• Find a string from all measures or one measure.
Such find subsets are removed during migration.
• Find a string using a wildcard pattern.
The long name of the category is searched instead.
• Find string from the short name.
The long name of the category is searched instead.
• Calculations that have find subsets may be dropped.
Prompts
Prompts are partially migrated to Report Studio. The prompt options zero suppression, swap
rows and columns, long/short category names, and currency are not supported.
Dimension prompts, with the exception of the Measures dimension, are supported. They are
migrated to tree prompts in Report Studio. Because Cognos 8 does not support prompts on
measures, when the report is run, data is returned for the default measure specified in the
PowerPlay report. The following limitations exist with tree prompts.
• You can browse only one hierarchy.
• There is no default selection for an unfiltered dimension. Consequently, users will often have
to select one or more prompt values when they run the report.
78 Migration Tools

Chapter 8: PowerPlay Mapping
• In Cognos 8, prompt values may not affect the report edges in the same manner as in
PowerPlay. The extent of the effect depends on the content of the report and the prompt
values selected.
Report Formatting Mappings
Report formatting is not available in Analysis Studio. To preserve report formatting, specify
Report Studio as the target application. Report Studio supports many of the report formats used
in PowerPlay reports, as well as providing many more formatting options. The migration log file
includes information about any changes or errors in report formatting.
PowerPlay default values are not migrated to Cognos 8. Instead, PowerPlay default values are
substituted with Cognos 8 default values in migrated reports. If you want to migrate a PowerPlay
default value, apply the default value to the object that you want in the report before migrating.
For example, if you migrate a report that contains currency values, the default currency format is
not migrated. If you want the values in the migrated report to have the default currency format,
apply the currency format to the values in the PowerPlay report.
Tip: You can also set default values in Cognos 8. Consequently, you can specify the same default
values in Cognos 8 that exist in PowerPlay.
Fonts and Colors
Font and color information are not migrated to Analysis Studio.
Long and Short Names
Only long names are migrated to Report Studio and Analysis Studio.
Titles, Headers, and Footers
Report Studio supports most title, header, and footer formats, including font, alignment, and
color options. If Analysis Studio is the target application, titles appear in plain text and other
formatting is dropped.
When possible, migration processing maps a variable to an equivalent Report Studio report
expression.
PowerPlay variable
report file name
report file date
report file time
MDC file name
MDC file date
MDC file time
MDC description
current default measure
current default period
current default row
current default column
current default layer
Report Studio report expression
ReportName()
ReportSaveDate()
AsOfTime()
ModelPath()
no equivalent report expression
no equivalent report expression
ReportDescription()
no equivalent report expression
no equivalent report expression
RowNumber()
no equivalent report expression
no equivalent report expression
User Guide 79

Chapter 8: PowerPlay Mapping
PowerPlay variable
user name
company name
current date
current time
page number
layer display reference
report layer reference
dimension line
individual dimensions
Report Studio report expression
migrated as text
migrated as text
Today()
Now()
PageNumber()
no equivalent report expression
no equivalent report expression
no equivalent report expression
no equivalent report expression
If a variable is not migrated, when you open the report, the report may include text that indicates
a title, header, or footer object was not migrated. For example, the following report originally
used the MDC file date variable.
Pictures (Linked or Embedded)
Because of differences between source and target applications, pictures are not migrated.
Report Studio supports the use of pictures in reports. You can add pictures to the migrated report
in Report Studio.
Analysis Studio does not support the use of pictures in reports.
Background Patterns
Analysis Studio does not support background patterns. Report Studio supports only solid
background patterns. All patterns are migrated to solid background colors. If both a background
and foreground pattern are specified, the background pattern is migrated as the background color.
If only a background or foreground pattern is specified, the pattern is migrated as the background
color.
Row and Column Sizes
Because of differences between the source and target applications, specific row and column sizes
are not migrated. If necessary, you can adjust row and column sizes in the target applications after
the migration.
PowerPlay for Windows Display Options
The display options available from the Format, Display Options, and General tabs in PowerPlay
for Windows are not migrated. This includes settings for summary options, gridline options, and
word wrap.
80 Migration Tools

Chapter 8: PowerPlay Mapping
Graphical Display Mappings
If customized graphical displays are an important component of your PowerPlay report set, we
recommend that you migrate the reports to Report Studio. Report Studio is designed to help you
create standard and complex reports and includes more report formatting options compared to
Analysis Studio. Analysis Studio is designed to help you explore and analyze data. You will not be
able to replicate many graphical display formatting options if you migrate the reports to Analysis
Studio.
All types of PowerPlay graphical displays map to Cognos 8 charts. Because Cognos 8 supports a
larger variety of chart types, there are some differences in terminology for the same chart between
Cognos Series 7 and Cognos 8. For example, a Cognos Series 7 bar chart maps to a Cognos 8
column chart. Both charts use vertical data markers. In Cognos 8, a bar chart refers to a chart
with horizontal data markers.
After you migrate reports that include charts, you may have to adjust some objects in the report.
Common adjustments include chart size and font size for labels. For more information, see
"Differences Between PowerPlay and Analysis Studio" (p. 85).
Like layers (p. 72), graphical displays are migrated to page groups and page sets. When you run
the migrated report, click the Page Up and Page Down links to view the different displays. For
example, if a chart has 24 displays, you must click Page Down 24 times to view all displays.
However, if both layers and graphical displays exist in a chart report, the layers are migrated to
page groups and page sets, and the displays are migrated to each layer. For example, if a chart has
three layers and 24 displays, the migrated report contains three pages and each page contains 24
displays.
The following limitations exist when migrating graphical displays:
• You cannot migrate displays to Analysis Studio.
• Displays built using measures, calculations, or subsets are not migrated.
• For displays built using alternative hierarchies of members, migration only processes displays
in the primary hierarchy.
Graphical Display Options
The following table describes how graphical display options map from PowerPlay to Report
Studio or Analysis Studio. If a graphical display option does not map to Cognos 8, the option is
dropped from the migrated report.
PowerPlay
display type Report Studio Analysis Studio
Pie
3D bar
Migrated
All display options except the following
are migrated:
• tilt angle
• rotation direction and angle
Migrated
All display options except the following
are migrated:
• 3D View Tool settings
• there may be slight differences in the
primary axis if the axis scale is set to
From the lowest value
• picture background style and related
settings
• Autofit labels settings for axis titles
Migrated
Display options are not migrated.
Migrated
Display options are not migrated.
User Guide 81

Chapter 8: PowerPlay Mapping
PowerPlay
display type Report Studio Analysis Studio
Simple bar
Clustered bar
Migrated
Migrated
All display options except the following The Horizontal orientation
are migrated:
setting, Depth setting, and the
• Autofit labels setting for axis titles Show setting for Values on bars
are migrated. Other display
• Autofit labels setting for values on
options are not migrated.
bars
• font settings for values on bars
• Bar spacing setting
• picture background style and related
settings
• Show ties setting. You cannot hide
ties in Report Studio.
• there may be slight differences in the
primary axis if the axis scale is set to
From the lowest value
• Word wrap setting for column labels
• all scrolling options
• standard deviation, logarithmic
regression, and linear regression
statistical lines
Migrated
Migrated
All display options except the following The Depth setting and the Show
are migrated:
setting for Values on bars are
• Word wrap setting for column labels migrated. Other display options
are not migrated.
• Autofit labels settings for axis titles
• font settings for values on bars
• picture background style and related
settings
• there may be slight differences in the
primary axis if the axis scale is set to
From the lowest value
• spacing setting for bars and clusters
• all scrolling options
• Show ties setting. You cannot hide
ties in Report Studio.
• standard deviation, logarithmic
regression, and linear regression
statistical lines
82 Migration Tools

Chapter 8: PowerPlay Mapping
PowerPlay
display type Report Studio Analysis Studio
Stacked bar
Migrated
All display options except the following
are migrated:
Migrated
The Depth setting is migrated.
Other display options are not
• Show ties setting. You cannot hide
ties in Report Studio.
migrated.
• all scrolling options
• there may be slight differences in the
primary axis if the axis scale is set to
From the lowest value
• Word wrap setting for column labels
• picture background style and related
settings
• Autofit labels settings for axis titles
Single line
Migrated
All display options except the following
are migrated:
• Show ties setting. You cannot hide
ties in Report Studio.
• picture background style and related
settings
• font settings for values above
markers
• there may be slight differences in the
primary axis if the axis scale is set to
From the lowest value
• Autofit labels settings for axis titles
• font settings for values above
markers
• Word wrap setting for column labels
• all scrolling options
• standard deviation, logarithmic
regression, and linear regression
statistical lines
Migrated
Display options are not migrated.
User Guide 83

Chapter 8: PowerPlay Mapping
PowerPlay
display type Report Studio Analysis Studio
Multiline
Scatter
Correlation
Migrated
All display options except the following
are migrated:
• Show ties setting. You cannot hide
ties in Report Studio.
• Autofit labels settings for axis titles
• picture background style and related
settings
• font settings for labels
• there may be slight differences in the
primary axis if the axis scale is set to
From the lowest value
• Word wrap setting for column labels
• all scrolling options
• standard deviation, logarithmic
regression, and linear regression
statistical lines
Migrated
All display options except the following
are migrated:
• there may be slight differences in the
primary axis if the axis scale is set to
From the lowest value
• Autofit labels settings
• font settings for labels
• picture background style and related
settings
• standard deviation and logarithmic
regression statistical lines
Migrated
All display options except the following
are migrated:
• there may be slight differences in the
primary axis if the axis scale is set to
From the lowest value
• Show ties setting. You cannot hide
ties in Report Studio.
• Bar spacing setting
• picture background style and related
settings
• Word wrap setting for column labels
• all scrolling options
• Autofit labels settings for axis titles
• Autofit labels settings for values on
bars
• font settings for values on bar
• standard deviation, logarithmic
regression, and linear regression
statistical lines
Migrated
Display options are not migrated.
Migrated to single line chart
Display options are not migrated.
Migrated to single line chart
Display options are not migrated.
84 Migration Tools

Chapter 8: PowerPlay Mapping
Mappings of Other PowerPlay Objects
In addition to cubes and reports, a PowerPlay application includes related objects and
information, such as style sheets and configuration information.
The following objects are not migrated to Cognos 8 by the migration tools:
• cascading style sheets used by PowerPlay Enterprise Server
Cognos 8 includes customization options that you can use to achieve similar results.
• PowerPlay for Windows styles
• performance settings related to PowerPlay Enterprise Server, such as mirroring, failover, and
load balancing
You can replicate most of these settings in Cognos 8 administration.
• drill-through settings in PowerPlay Enterprise Server
Drill-through options must be reconfigured in Cognos 8 after the migration. For more
information, see the Administration and Security Guide.
• page size and page orientation settings for reports
• namespace information for cubes
Differences Between PowerPlay and Analysis Studio
Position of Calculated Categories
If a report contains calculated categories, the relative position of the rows or columns that show
the calculated categories may be different between PowerPlay and Analysis Studio. This
formatting difference does not affect the data.
The following examples show the difference in the position of a calculated column, 2004 + 2005.
The first image shows the original PowerPlay report. The second image shows the same report
after migration to Analysis Studio.
Charting of Summary Data
Analysis Studio does not show summary values in charts. If the original PowerPlay report
included charts that showed summary values, this level of detail will not appear in the charts in
Analysis Studio.
User Guide 85

Chapter 8: PowerPlay Mapping
Default Display Format for Bar Charts
In PowerPlay, a simple bar chart can combine the components of a summary in one bar. Analysis
Studio always shows a bar for each component of the summary.
The following examples show the differences in the display of bar charts. The first image shows
the original PowerPlay report. The second image shows the same report after migration to
Analysis Studio.
Default Display Format for Pie Charts
In PowerPlay, a pie chart can combine the components of a summary in one chart. Analysis Studio
always shows a separate chart for each component of the summary. If there is no data for a
component of the summary, an empty pie chart is included for that component.
The following examples show the differences in the display of pie charts. The first image shows
the original PowerPlay report. The second image shows the same report after migration to
Analysis Studio.
86 Migration Tools

Chapter 8: PowerPlay Mapping
Reports with Calculated Columns
In PowerPlay, a report can show only calculated columns. In Analysis Studio, a report must show
at least one measure. If the original PowerPlay report shows only calculated columns, an
additional column containing a measure will appear in the Analysis Studio report.
In the following Analysis Studio report, which was migrated from PowerPlay, the revenue column
did not appear in the original report.
User Guide 87

Chapter 8: PowerPlay Mapping
You may notice other differences between PowerPlay and Analysis Studio related to calculated
columns. For example, if the PowerPlay report includes a calculated column in a nested category,
the column will not appear in Analysis Studio. Analysis Studio does not support calculated
columns in a nested level.
Default View in Analysis Studio
You can change the default view for an analysis by changing the package configuration properties.
This allows you to create a default view similar to PowerPlay, where the order of dimensions and
measures determines the default rows, columns, and measure when you open the cube.
For more information about administering packages, see the Cognos 8 Administration and
Security Guide.
Hidden Children Levels
In PowerPlay reports, when all children levels of a parent level are hidden, the parent level is also
hidden. The parent level appears in reports migrated to Analysis Studio. For example, a
PowerPlay report contains the levels Products and Outdoor Protection. Products is the parent of
Outdoor Protection. If you hide Outdoor Protection and all of its children levels, no data appears
for Products or Outdoor Protection. If you migrate this report to Analysis Studio, Products
appears.
Hidden Measures
In PowerPlay reports, you can hide measures. Analysis Studio does not support hiding measures.
Measures and Dimensions Nested Along the Same Axis
In PowerPlay reports, you can nest measures and dimensions on one axis. Analysis Studio does
not support nesting items under a measure. When migrated to Analysis Studio, the following
occurs:
• If there are multiple measures on the same axis, the outermost measures are dropped.
• If the axis still contains nested items and the remaining measure is not the lowest or,
innermost, level, it is moved to the lowest level.
The following examples show what happens when a PowerPlay report with nested measures is
migrated to Analysis Studio. The first image shows the original PowerPlay report. The second
image shows the same report after migration to Analysis Studio.
88 Migration Tools

Chapter 8: PowerPlay Mapping
Drilling Down on Calculations
In PowerPlay, you can drill down on a category that is a calculation until it is the only object
showing. Analysis Studio does not support this type of structure for calculations. When migrated
to Analysis Studio, the next level appears, as if you had drilled up once.
The following example shows a multiline chart in PowerPlay where the category about, a
calculation, is drilled down until it is the only object showing.
When this report is migrated to Analysis Studio, the chart shows lines for 1995 and 1996, as if
you had drilled up once on about.
Tip: If you want to avoid this problem, migrate the report to Report Studio instead of Analysis
Studio.
User Guide 89

Chapter 8: PowerPlay Mapping
Calculations in Parentage Subsets
In PowerPlay, you can define calculations in the lower level of a two-level parentage subset.
Analysis Studio does not support calculations in the lower level. For example, if you define a
parentage subset as the next two levels of Years/2006, you get the first level Quarters and the
second level Months beneath it. If you define a calculation that adds two of the months together,
this calculation is not migrated.
90 Migration Tools

Chapter 9: Upfront Mapping
The information in this section will help you understand the mapping of objects when migrating
Upfront content from Cognos Series 7 to Cognos 8.
Content Mapping
The Upfront portal can contain a variety of content, including both content created by Cognos
products such as Impromptu Web Reports, and non-Cognos content. Only some Upfront content
is included in a migration.
You can migrate Upfront content created by PowerPlay, Impromptu, and Impromptu Web
Reports. Migration also includes URL NewsItems. For more information, see Part 3: Mapping
Cognos Series 7 Objects to Cognos 8 Objects.
The following types of Upfront content are not included in migration:
• Cognos Query
• Cognos Visualizer
• Cognos NoticeCast
• Cognos 8 Planning
• Cognos Finance
• Cognos Metrics Manager
• non-Cognos content
For more information, see "Cognos Series 7 Products and Components Not Migrated With
Tools" (p. 19).
NewsBox Mapping
Migration maps NewsBoxes to Cognos Connection folders. Migration includes both public and
personal NewsBoxes.
In Upfront, personal NewsBoxes are subfolders that give users access so that they can get to their
own NewsBox. Each user's personal NewsBox has an access control list that prevents anyone
other than a NewsIndex administrator and the user to whom the NewsBox belongs from
accessing it. After migration, a folder is created in Public Folders that contains all personal
NewsBoxes. After verifying the content of the migrated personal NewsBoxes, you can move this
content to the appropriate folders, such as to each user's My Folders.
The following table shows the mapping for NewsBox properties.
NewsBox property
Name
Description
Hide this entry
Mapping
Folder name
Folder description
Disable entry
When disable this entry is selected, only users with write
access see the object.
For more information about disabling entries, see the Cognos
8 Administration and Security Guide.
User Guide 91

Chapter 9: Upfront Mapping
Migration does not include the following NewsBox properties:
• duplicate NewsBox names at the same level
To prevent unexpected migration results, ensure that NewsBoxes at the same level use unique
names.
• creation date
NewsBox Shortcut Mapping
A NewsBox shortcut is mapped to a Cognos Connection folder shortcut. The following table
shows the NewsBox shortcut properties that are mapped.
NewsBox shortcut property
Name
Description
Source NewsBox ID
Mapping
Folder shortcut name
Folder shortcut description
Source folder search path
NewsItem Mapping
A NewsItem is mapped to a Cognos Connection entry. The following table shows the NewsItem
properties that are mapped.
NewsItem property
Name
Description
Hide this entry
Default run action and default
show action settings (not
applicable to all types of
NewsItems)
Contact information
Mapping
Entry name
Entry description
Disable entry
When disable this entry is selected, only users with write
access see the object.
For more information about disabling entries, see the Cognos
8 Administration and Security Guide.
See "Impromptu Web Reports Mapping" (p. 95) for details
about default run action mapping.
If you configure Cognos 8 to use the same namespace as
Cognos Series 7, and you use the acl option with the
migratetoc8 command to migrate access control list (ACL)
definitions, the user profile is the source of contact
information. If the user does not exist in the namespace, the
email address from the NewsItem is the contact in Cognos 8.
The following NewsItem properties are not migrated:
• duplicate NewsItem names
duplicate entry names at the same level are not supported in Cognos 8. To prevent unexpected
migration results, ensure that NewsItems at the same level use unique names.
• security settings
92 Migration Tools

Chapter 9: Upfront Mapping
The migratetoc8 tool includes options for taking advantage of existing security information
(p. 93).
• create and update dates
NewsItem Shortcut Mapping
Migration maps NewsItem shortcuts to Cognos Connection entry shortcuts. The following table
shows the mapping for NewsItem shortcut properties.
NewsItem shortcut property
Name
Description
Source NewsItem ID
Mapping
Entry shortcut name
Entry shortcut description
Source entry search path
Mappings of Other Upfront Objects
Migration does not include the following objects:
• user settings, such as Personalize settings
• themes
Standard and custom themes are not migrated. Cognos 8 includes customization options that
you can use to achieve similar results.
Security
In Upfront, the access control list (ACL) contains information about which users or user classes
can read or write to a particular object, such as a report or a URL. To help you implement security
when you migrate Cognos Series 7 Web-based content to Cognos 8, the migratetoc8 command
(p. 43) includes three processing options for ACL information when you create a migration
deployment package.
Generate ACL Report
By default, the migratetoc8 process generates an ACL report that shows the security settings by
user class for all Upfront objects. This report can help you replicate the Cognos Series 7 security in
Cognos 8.
Generate ACL Report and Migrate ACL Definitions
If Cognos 8 is configured to use the same namespace as Cognos Series 7, you can migrate ACL
definitions to maintain the Cognos Series 7 security settings in Cognos 8. You must include the
namespace ID as recorded in Cognos Configuration in the migratetoc8 command.
Changes to security settings in Upfront after migration are not applied to the migrated Upfront
objects in Cognos 8. You must manage Upfront and Cognos 8 security settings separately.
Exclude ACL Information
If you plan to apply security settings manually in Cognos 8, or you don’t want to use the Series 7
namespace in Cognos 8, you can choose to not generate an ACL report or migrate ACL
definitions.
User Guide 93

Chapter 9: Upfront Mapping
94 Migration Tools

Chapter 10: Impromptu Web Reports Mapping
The information in this section will help you understand the mapping of objects when migrating
Impromptu Web Reports applications from Cognos Series 7 to Cognos 8.
The source for an Impromptu Web Reports migration is a Deployment Manager package.
You must migrate Impromptu catalogs before migrating Impromptu Web Reports (p. 27).
For related information, see "Impromptu Reports Mapping" (p. 65).
Report Set Mappings
There is no equivalent concept in Cognos 8 for creating and managing a report set. However, the
migration tools preserve the report set concept by grouping reports in a Cognos Connection folder
that uses the original report set name in the Impromptu Web Reports package.
Many report set properties in Impromptu Web Reports are mapped to equivalent Cognos 8
properties.
Report set property
Report set name
Description
Contact email address
Report list
Mapping
Name of the Cognos Connection folder that contains the
reports from the report set
Folder description
Folder email contact
Determines the reports that appear in the Cognos Connection
folder that represents the report set
Report Mappings
Migration does not include report set security settings. For more information, see
"Security" (p. 93).
The following table shows report properties in Impromptu Web Reports that are mapped to
equivalent or similar features in Cognos 8.
Report property
NewsItem name
NewsItem description
Contact information
Mapping
Entry name in Cognos Connection
Entry description
If you configure Cognos 8 to use the same namespace as
Cognos Series 7, and you specify the namespace using the -N
parameter with the migratetoc8 command, contact
information from the user profile migrates if the user exists in
the namespace. Otherwise, the email address from the
NewsItem migrates as the contact email address.
User Guide 95

Chapter 10: Impromptu Web Reports Mapping
Report property
Prompt settings
Report format settings
Number of versions setting
Default show action setting
Default run action setting
Custom view
Mapping
Saved prompt values
Report output formats
Number of report output versions to be maintained in
Content Manager
Default report output format settings
Saved prompt value settings
Report view
Migration does not include the following report features in Impromptu Web Reports:
• report versions
Cognos 8 includes similar functionality called report output versions.
• burst settings
You can implement similar functionality using Cognos 8 bursting options. For more
information, see the Report Studio User Guide.
• report dependency settings
• governor settings
• priority setting
• security settings
For more information about the options for migration security settings, see "Security" (p. 93).
Schedule Mappings
Cognos 8 includes schedule features similar to report and event schedules. Most schedule settings
are fully supported. The following table shows schedule properties in Impromptu Web Reports
that are mapped to Cognos 8.
Schedule property
Schedule type
End date
Mapping
Compared to Impromptu Web Reports, the daily schedule
type in Cognos 8 includes more options, including the ability
to specify frequency by hours. Therefore, mapping hourly
schedules to daily schedules provides equivalent functionality.
The last day of the month schedule type is not supported in
Cognos 8.
In Impromptu Web Reports, an end date setting includes year,
month, and day. In Cognos 8, an end date setting also
includes hours and minutes. When mapping end dates, hours
and minutes are set to the time used in the start date.
If the Impromptu Web Reports environment and the Cognos 8 environment use different date and
time settings, you must update schedules after migration to use the Cognos 8 settings.
Migration does not include cleanup and audit data collection schedules.
96 Migration Tools

Chapter 10: Impromptu Web Reports Mapping
Event Mappings
Events map to equivalent functionality in Cognos 8. The migration tool creates a Cognos
Connection folder named Events to contain the migrated events. Many event properties are
mapped to equivalent Cognos 8 properties.
Event property
Event
Event name
Schedule
Dependant reports
Event list
Mapping
Job
Job name
Job schedule
jobStepDefinition
Determines the contents of the Events folder in Cognos
Connection
Mappings of Other Impromptu Web Reports Objects
Impromptu Web Reports applications include related objects and information.
Migration does not include the following objects:
• PowerPrompts
You can implement similar functionality using the Cognos 8 Software Development Kit.
• Impromptu Web Reports data store
Cognos 8 uses a single content store. A separate data store is not required for migrated
Impromptu Web Reports objects.
• configuration information, such as server performance settings
Similar functionality is available in Cognos Connection.
• HotFiles
User Guide 97

Chapter 10: Impromptu Web Reports Mapping
98 Migration Tools

Chapter 11: Architect Mapping
The information in this section will help you understand the mapping of objects when migrating
Architect models from Cognos Series 7 to Cognos 8. If a feature or functionality is not mentioned,
an equivalent is available in Cognos 8.
Architect Model Security
To migrate secured models and retain the access controls applied in Architect, you must configure
Cognos 8 to use the Cognos Series 7 namespace. If Cognos 8 is not configured to use the Cognos
Series 7 namespace, the model or catalog migrates but does not include security.
For information about configuring an authentication source in Cognos 8, see the Cognos 8
Administration and Security Guide.
Database Access
In an Architect model, you can specify the databases and database components that your users can
access. This information is included in the Architect metadata file (.xml) you import into the
Framework Manager project. After migration, the Framework Manager project contains a
package for each user class that has model security applied to it.
Tip: To view the specific objects in a user class package, double-click the package you want. The
unselected objects should match the components that the user class did not have access to in the
Architect model.
Access to Entities
In an Architect model, you can specify which entities user classes can access. This information is
included in the Architect metadata file you import into the Framework Manager project. After
migration, the Framework Manager project contains a package for each user class that has model
security applied to it.
Tip: To view the specific objects in a user class package, double-click the package you want. The
unselected objects should match the components that the user class did not have access to in the
Architect model.
User Class Filters
You apply user class filters at run time to give user classes access to specific data. These security
filters are included in the Architect metadata file you import into the Framework Manager project
and can be found in the corresponding query subject.
Package Access
In an Architect model, you can specify which packages and package components user classes have
access to. The migration process creates a package for each package object in the Package Layer
namespace and one role-based security package for each user class. The security package reflects
the exclusion list of the user class access in Architect. After migration, Architect packages appear
in the Framework Manager project in the Package Layer namespace and the Packages folder.
You use a package in Framework Manager to publish a subset of the metadata in a project to
report authors.
Tip: To view the specific objects in a package, double-click the package you want. The unselected
objects should match the components that the user class did not have access to in the Architect
model.
User Guide 99

Chapter 11: Architect Mapping
Security by Value
You can create filter expressions using security metadata such as user classes, user roles, and user
names.
The references in expressions to user-name() map to references to the session parameter
#$account.defaultName#.
The references in expressions to user-classes() map to
#CSVIdentityName(%ImportedUserClasses)#, where ImportedUserClasses is a hard-coded
parameter map. During the import, the parameter map loads with the currently available roles,
both as map keys and as map values.
Here are examples of filter expressions using Cognos Series 7 security tokens and their mappings
into Framework Manager.
Architect filter expression
user_name()='Bob'
’Sales’ in user_classes()
Framework Manager expression
#$account.defaultName#='Bob'
’Sales’ in #CSVIdentityName(%ImportedUserClasses)#
In addition to these expressions, the migration process creates a parameter map named
ImportedUserClasses. It contains the user classes and user names from the current namespace in
Cognos Series 7 Access Manager.
Migrating Expressions
Migration includes expressions in Architect, which use Cognos SQL syntax.
The expressions are reproduced in Framework Manager with the following mappings.
Architect
Column and attribute references
Stored procedure references
Prompt references
Filter references
Security by value tokens
References to external user defined
functions (UDF)
Calls to database built-in functions
Framework Manager
Query item references
Model function references
Model calculation references representing prompts
Migrated expressions
Equivalent Framework Manager tokens
Replicated literally in the Framework Manager
expressions. Expressions containing this type of
reference may require editing after the migration is
complete.
Calls to Cognos 8 database functions or constructs
using these functions. For more information, see
"Impromptu Functions Mapping" (p. 127).
After you migrate, check the functions and expressions in Framework Manager before publishing
the model.
100 Migration Tools

Chapter 11: Architect Mapping
Expressions in Architect Models Spanning Multiple Database Types
The migration process does not convert Architect expressions that connect to multiple database
types. This type of expression appears in Framework Manager in the original format. This
mapping only applies to built-in or vendor specific function calls. Expressions that already exist in
Framework Manager and do not require conversion will continue to work in Cognos 8.
User Defined Functions
Migration does not include external UDFs. References to external UDFs are replicated literally in
migrated expressions in Framework Manager.
Database UDFs are mapped to model functions in the Folders namespace of the Framework
Manager project. As long as the function still exists in the database schema, the expressions
referencing the database UDF are valid.
For more information about expressions, see the Framework Manager User Guide.
Mapping Architect Business Layer Metadata
Entities Folders
After you import an Architect XML file to Framework Manager, the following namespaces that
correspond to layers in an Architect model appear in the Project Viewer:
• Data Access Layer (p. 108)
• Business Layer
• Package Layer (p. 122)
These namespaces contain the migrated metadata from each of the corresponding layers in
Architect. The namespaces are organized hierarchically in the Project Viewer. For information
about namespaces, see the Framework Manager User Guide.
Migration includes object properties that are set in Architect unless the properties do not apply to
Framework Manager objects. Some objects, such as steward and lineage, are migrated for
informational purposes.
Objects created in Framework Manager do not contain these properties.
For information about object properties, see the Framework Manager User Guide.
Migration maps an Architect Entities folder to Framework Manager as an Entities namespace.
The parent of an Architect Entities folder is the Business Layer folder or another Entity folder. The
children of the Architect Entities folder are other Entity folders or entity objects. The entities are
mapped to Framework Manager as model query subjects (p. 102).
For information about model query subjects, see the Framework Manager User Guide.
To view the Entities namespace properties, in the Project Viewer, expand the Business Layer
namespace, and click the Entities namespace. A list of the properties appears in the Properties
pane.
Architect property
Entities folder name
Entities folder description text
Entities folder imported description text
Entities folder import source
Entities folder external ID
Entities folder lineage
Framework Manager property
Name
Description
Imported description text
No longer required
No longer required
Lineage
User Guide 101

Chapter 11: Architect Mapping
Architect property
Entities folder imported lineage
Entities folder import exclusion list
Entities folder help text
Entities folder imported help text
Entities folder steward
Framework Manager property
Imported lineage
No longer required
Help text
No longer required
Steward
Entities
Migration maps Architect entities to Framework Manager as model query subjects.
The parent of an Architect entity is an Entity folder. An Entity folder is migrated to Framework
Manager as an Entities namespace (p. 101).
The children of an Architect entity are attributes, keys, or proxies of attributes or keys. Both
attributes (p. 103) and attribute proxies (p. 103) map to Framework Manager as query items.
Migration does not include keys and key proxies. For information about relationships, see the
Framework Manager User Guide.
To view the properties for a specific entity, in the Project Viewer, expand the Business Layer
namespace, expand Entities, and click the entity you want. A list of the properties appears in the
Properties pane.
Architect property
Entity name
Entity description text
Entity imported description text
Entity import source
Entity external ID
Entity lineage
Entity imported lineage
Entity import exclusion list
Entity help text
Entity imported help text
Entity steward
Entity merge duplicates
Entity supertype
Entity filter
Framework Manager property
Name
Description
Imported description text
No longer required
No longer required
Lineage
Imported lineage
No longer required
Help text
No longer required
Steward
Not applicable
Not applicable
Embedded filter
For more information, see the Framework
Manager User Guide.
102 Migration Tools

Chapter 11: Architect Mapping
Attributes
An Architect attribute is migrated to Framework Manager as a query item. Attribute usage is
mapped to a property of the query item.
The parent of an attribute is an entity. Entities are migrated to Framework Manager as model
query subjects (p. 102).
To view the properties for a specific attribute, in the Project Viewer, expand the Business Layer
namespace, expand Entities, expand a specific entity, and click the attribute you want. A list of the
properties appears in the Properties pane.
Architect property
Attribute name
Attribute description text
Attribute imported description text
Attribute import source
Attribute external ID
Attribute lineage
Attribute imported lineage
Attribute import exclusion list
Attribute help text
Attribute imported help text
Attribute steward
Attribute data type
Attribute expression
Attribute default style
Attribute list of model prompts
Attribute enumeration values
Attribute usage
Framework Manager property
Name
Description
Imported description text
No longer required
No longer required
Lineage
Imported lineage
No longer required
Help text
No longer required
Steward
Datatype
Query item or a calculated attribute
For more information, see "Migrating
Expressions" (p. 100).
No longer required
For information about formatting columns, see the
Report Studio User Guide.
No longer required
No longer required because enumeration values are
not migrated for use with Cognos 8
Usage
Attribute Proxies
Migration maps Architect attribute proxies to Framework Manager as query items.
The parent of an attribute proxy is an entity. During migration, entities are mapped to Framework
Manager as model query subjects (p. 102).
The properties of the proxy are derived from the attribute it references.
User Guide 103

Chapter 11: Architect Mapping
To view the attribute proxy properties, in the Project Viewer, expand the Business Layer
namespace, and click an attribute you want. A list of the properties appears in the Properties pane.
Architect property
Attribute proxy name
Attribute proxy description text
Attribute proxy imported description text
Attribute proxy import source
Attribute proxy external ID
Attribute proxy lineage
Attribute proxy imported lineage
Attribute proxy import exclusion list
Attribute proxy help text
Attribute proxy imported help text
Attribute proxy steward
Attribute proxy data type
Attribute proxy expression
Attribute proxy default style
Attribute proxy list of model prompts
Attribute proxy enumeration values
Attribute proxy usage
Framework Manager property
Name
Description
Imported description text
No longer required
No longer required
Lineage
Imported lineage
No longer required
Help text
No longer required
Steward
Datatype
Expression
For more information, see "Migrating
Expressions" (p. 100).
Not applicable
For information about formatting columns, see the
Report Studio User Guide.
No longer required
No longer required because enumeration values are
not migrated for use with Cognos 8.
Usage
Filters Folders
Migration maps an Architect Filters folder to a Filters namespace in Framework Manager.
The parent of an Architect Filters folder is the Business Layer folder or another Filter folder. The
children of the Architect Filters folder are other Filter folders or filter objects.
To view the Filters namespace properties, in the Project Viewer, expand the Business Layer
namespace, and click the Filters namespace. A list of the properties appears in the Properties pane.
Architect property
Filters folder name
Filters folder description text
Filters folder imported description text
Framework Manager property
Name
Description
Imported description text
104 Migration Tools

Chapter 11: Architect Mapping
Architect property
Filters folder import source
Filters folder external ID
Filters folder lineage
Filters folder imported lineage
Filters folder import exclusion list
Filters folder help text
Filters folder imported help text
Filters folder steward
Framework Manager property
No longer required
No longer required
Lineage
Imported lineage
No longer required
Help text
No longer required
Steward
Filters
Migration maps an Architect filter to Framework Manager as a Framework Manager filter.
The parent of an Architect filter is a Filter folder. Filter folders map to Framework Manager as a
Filters namespace (p. 104).
To view the properties for a specific filter, in the Project Viewer, expand the Business Layer
namespace, expand Filters, and click the filter you want. A list of the properties appears in the
Properties pane.
Architect property
Filter name
Filter description text
Filter imported description text
Filter import source
Filter external ID
Filter lineage
Filter imported lineage
Filter import exclusion list
Filter help text
Filter imported help text
Filter steward
Filter expression
Filter expression list of references
Framework Manager property
Name
Description
Imported description text
No longer required
No longer required
Lineage
Imported lineage
No longer required
Help text
No longer required
Steward
Expression
For more information, see "Migrating
Expressions" (p. 100).
No longer required
User Guide 105

Chapter 11: Architect Mapping
Relationships
Migration maps Architect relationships to Framework Manager as relationships between model
query subjects.
The parent of an Architect relationship is the model root.
Architect property
Relationship name
Relationship description text
Relationship imported description text
Relationship import source
Relationship external ID
Relationship lineage
Relationship imported lineage
Relationship import exclusion list
Relationship help text
Relationship imported help text
Relationship steward
Relationship reference to left entity
Relationship reference to right entity
Relationship left cardinality
Relationship right cardinality
Relationship left type
Relationship right type
Relationship left role
Relationship right role
Relationship expression
Framework Manager property
Name
Description
Imported description text
No longer required
No longer required
Lineage
Imported lineage
No longer required
Help text
No longer required
Steward
Left refobject
Right refobject
Left mincard, maxcard
Right mincard, maxcard
No longer required
No longer required
Left description property
Right description property
Expression
For more information, see "Migrating
Expressions" (p. 100).
Subtype Relationships
Migration maps a subtype relationship to Framework Manager as a model query with a
generateSQL property set to asView.
Architect entities can have subtypes with or without their own attributes. You can migrate both
types.
106 Migration Tools

Chapter 11: Architect Mapping
Subtypes Without Attributes
When you migrate an Architect entity with a subtype that has no attributes of its own, the
migrated entity appears in Framework Manager, as well as a shortcut to the entity. This shortcut
to the entity represents the subtype.
Migration includes existing relationships between the entity and other entities. For each of these
relationships, a new relationship is created between the shortcut representing the subtype and one
of the other entities.
Subtypes Attributes
When you migrate an Architect entity with a subtype that has attributes of its own, the migrated
entity appears in Framework Manager as a query item that represents the mapping of the attribute
that the proxy points to. A new model query subject representing the subtype also appears in
Framework Manager.
Migration includes any existing relationships between the entity and other entities. For each of
these relationships, a new relationship is created between the new model query subject
representing the subtype and one of the other entities.
Joins Between Supertypes and Other Entities
Joins between an Architect supertype and any other entity maps to Framework Manager as a
relationship between the model query representing the subtype and the model query representing
the other entity.
A filter applied to a supertype is not inherited by its subtypes.
Architect property
Subtype relationship name
Subtype relationship description text
Subtype relationship imported description
text
Subtype relationship import source
Subtype relationship external ID
Subtype relationship lineage
Subtype relationship imported lineage
Subtype relationship import exclusion list
Subtype relationship help text
Subtype relationship imported help text
Subtype relationship steward
Subtype relationship mapping
Framework Manager property
Name
Description
Imported description text
No longer required
No longer required
Lineage
Imported lineage
No longer required
Help text
No longer required
Steward
No longer required
Prompts
Migration maps Architect prompts from the Business Layer in Architect to stand-alone
calculations in Framework Manager.
File prompts and all of their properties are migrated. However, the list of values specified for a file
prompt in Architect is ignored.
User Guide 107

Chapter 11: Architect Mapping
To view the properties for a specific prompt, in the Project Viewer, expand the Business Layer
namespace, expand Architect Prompts, and click the prompt you want. A list of the properties
appears in the Properties pane.
Architect prompts map to a stand-alone calculation with the same name as the Architect prompt
object. The descriptive information is available and the expression becomes a macro prompt with
the following syntax, where ModelReference is set to Nil:
#prompt(’promptName’[,’datatype’[,’defaultValue’ [,’Text’
[,’ModelReference’] ] ] ] )#,
All the non-mappable properties migrate to custom properties. Migration converts prompt
references in the Architect expression to a reference to the stand-alone calculation in the
Framework Manager expression.
Mapping Architect Data Access Layer Metadata
Database Folders
After you import an Architect XML file to Framework Manager, the following namespaces that
correspond to layers in an Architect model appear in the Project Viewer:
• Data Access Layer
• Business Layer (p. 101)
• Package Layer (p. 122)
These namespaces contain the migrated metadata from each of the corresponding layers in
Architect. The namespaces are organized hierarchically in the Project Viewer. For information
about namespaces, see the Framework Manager User Guide.
Migration maps Architect object properties to Framework Manager, unless they do not apply to
Framework Manager objects. Some objects, such as steward and lineage, migrate for
informational purposes.
For information about object properties, see the Framework Manager User Guide.
Migration maps Architect database folders to Framework Manager as Databases namespaces.
The parent of an Architect database folder is the Data Access Layer folder. The children of an
Architect database folder map to Framework Manager as database objects.
To view the Database namespace properties, in the Project Viewer, expand the Data Access Layer
namespace, and click the Databases namespace. A list of the properties appears in the Properties
pane.
Architect property
Databases folder name
Databases folder description text
Databases folder imported description
text
Databases folder import source
Databases folder external ID
Databases folder lineage
Databases folder imported lineage
Framework Manager property
Name
Description
Imported description text
This is a custom property.
No longer required
No longer required
Lineage
This is a custom property.
Imported lineage
This is a custom property.
108 Migration Tools

Chapter 11: Architect Mapping
Architect property
Databases folder import exclusion list
Databases folder help text
Databases imported help text
Databases folder steward
Framework Manager property
No longer required
Help text
This is a custom property.
No longer required
Steward
This is a custom property.
Databases
Migration maps Architect databases to Framework Manager as Framework Manager databases.
When you expand the Databases namespace, in the Data Access Layer namespace, a list of the
migrated databases appears.
The parent of an Architect database is the Databases folder. During migration, the Databases
folder maps to Framework Manager as a Databases namespace (p. 108).
The children of an Architect database are catalog objects. During migration, the catalogs map to
Framework Manager as catalog namespaces (p. 110).
To view the properties for a specific database, in the Project Viewer, expand the Data Access
Layer namespace, expand Databases, and click the database you want. A list of the properties
appears in the Properties pane.
Architect property
Database name
Database description text
Database imported description text
Database import source
Database external ID
Database lineage
Database imported lineage
Database import exclusion list
Database help text
Database imported help text
Database steward
Framework Manager property
Name
Description
Imported description text
This is a custom property.
No longer required
No longer required
Lineage
This is a custom property.
Imported lineage
This is a custom property.
No longer required
Help text
This is a custom property.
No longer required
Steward
This is a custom property.
User Guide 109

Chapter 11: Architect Mapping
Catalogs
Migration maps Architect catalogs to Framework Manager as catalog namespaces.
If a catalog is defined in the database, a corresponding namespace for that catalog in the specific
database namespace appears. For example, if you expand the gosales_oracle namespace, the
catalog appears. The catalog has its own set of properties that you can view in the Properties
pane.
If the catalog name was added in Architect, the namespace has the same name. Otherwise, it
appears as _Default Catalog.
The parent of an Architect catalog is a database. The database maps to Framework Manager as a
namespace (p. 109).
The children of an Architect catalog are schemas. A schema maps to Framework Manager as a
schema namespace (p. 110).
To view the Catalog properties, in the Project Viewer, expand the Data Access Layer namespace,
expand Databases, expand the specific database namespace you want, and click the catalog
namespace. A list of the properties appears in the Properties pane.
Architect property
Catalog name
Catalog description text
Catalog imported description text
Catalog import source
Catalog external ID
Catalog lineage
Catalog imported lineage
Catalog import exclusion list
Catalog help text
Catalog imported help text
Catalog steward
Framework Manager property
Name
Description
Imported description text
This is a custom property.
No longer required
No longer required
Lineage
This is a custom property.
Imported lineage
This is a custom property.
No longer required
Help text
This is a custom property.
No longer required
Steward
This is a custom property.
Schemas
Migration maps Architect schemas to Framework Manager as schema namespaces.
If a schema is defined in the database, a corresponding namespace for that schema in the specific
database namespace appears. For example, if you expand the Catalog namespace in the
gosales_oracle namespace, the schema appears. The schema has its own set of properties that you
can view in the Properties pane.
If you added the schema name in Architect, the Framework Manager schema namespace has the
same name. Otherwise, it appears as _Default Schema.
110 Migration Tools

Chapter 11: Architect Mapping
The parent of an Architect schema is a catalog. The catalog maps to Framework Manager as a
namespace (p. 110).
The children of an Architect schema are tables, views, stored procedures, or synonym objects. A
table maps to a database query (p. 111), a view maps to a database query (p. 112), a stored
procedure maps to a model function (p. 118), and a synonym object maps to a shortcut (p. 113).
To view the schema properties, in the Project Viewer, expand the Data Access Layer namespace,
expand Databases, expand the specific database namespace you want, expand Catalog, and click
the Schema namespace. A list of the properties appears in the Properties pane.
To view the data source properties, in the Project Viewer, expand the Data Sources folder, and
click the data source you want. A list of the data source properties appears in the Properties pane.
Architect property
Schema name
Schema description text
Schema imported description text
Schema import source
Schema external ID
Schema lineage
Schema imported lineage
Schema import exclusion list
Schema help text
Schema imported help text
Schema steward
Framework Manager property
Name
Description
Imported description text
This is a custom property.
No longer required
No longer required
Lineage
This is a custom property.
Imported lineage
This is a custom property.
No longer required
Help text
This is a custom property.
No longer required
Steward
This is a custom property.
Tables
Migration maps Architect tables to Framework Manager as database query subjects.
The parent of an Architect table is a schema object. The mapping of an Architect schema (p. 110)
into Framework Manager is a schema namespace.
The children of an Architect table are column, index, or key objects. A column maps to a query
item (p. 115), an index maps to a Framework Manager index (p. 120), and a key maps to a
Framework Manager key (p. 116).
For information about query subjects, see the Framework Manager User Guide.
User Guide 111

Chapter 11: Architect Mapping
To view the query subject properties, in the Project Viewer, in the Data Access Layer namespace,
click the query subject you want. A list of the query subject properties appears in the Properties
pane.
Architect property
Table name
Table description text
Table imported description text
Table import source
Table external ID
Table lineage
Table imported lineage
Table import exclusion list
Table help text
Table imported help text
Table steward
Table estimated record count
Table last update date time
Table weight (Impromptu)
Framework Manager property
Name
Description
Imported description text
This is a custom property.
No longer required
No longer required
Lineage
This is a custom property.
Imported lineage
This is a custom property.
No longer required
Help text
This is a custom property.
No longer required
Steward
This is a custom property.
No longer required
No longer required
No longer required
Views
Migration maps Architect views to Framework Manager as database query subjects.
The parent of an Architect view is a schema object. An Architect schema (p. 110) maps to
Framework Manager as a schema namespace.
The children of an Architect view are column, index, or key objects. A column maps to a query
item (p. 115), an index maps to a Framework Manager index (p. 120), and a key maps to a
Framework Manager key (p. 116).
For information about query subjects, see the Framework Manager User Guide.
To view the query subject properties, in the Project Viewer, in the Data Access Layer namespace,
click the query subject you want. A list of the query subject properties appears in the Properties
pane.
Architect property
View name
Framework Manager property
Name
112 Migration Tools

Chapter 11: Architect Mapping
Architect property
View description Text
View imported description Text
View import source
View external ID
View lineage
View imported lineage
View import exclusion List
View help text
View imported help text
View steward
View estimated record count
View last update date time
View weight (Impromptu)
Framework Manager property
Description
Imported description text
This is a custom property.
No longer required
No longer required
Lineage
This is a custom property.
Imported lineage
This is a custom property.
No longer required
Help text
This is a custom property.
No longer required
Steward
This is a custom property.
No longer required
No longer required
No longer required
SynonymViews
Migration maps Architect SynonymViews to Framework Manager as database query subject
shortcuts.
The parent of an Architect SynonymView is a schema object. An Architect schema (p. 110) maps
to Framework Manager as a schema namespace.
For information about query subjects and shortcuts, see the Framework Manager User Guide.
To view the query subject properties, in the Project Viewer, in the Data Access Layer namespace,
click the query subject you want. A list of the query subject properties appears in the Properties
pane.
Architect property
SynonymView name
SynonymView description text
SynonymView imported description text
SynonymView import source
SynonymView external ID
Framework Manager property
Name
Description
Imported description text
This is a custom property.
No longer required
No longer required
User Guide 113

Chapter 11: Architect Mapping
Architect property
SynonymView lineage
SynonymView imported lineage
SynonymView import exclusion list
SynonymView help text
SynonymView imported help text
SynonymView steward
SynonymView estimated record count
SynonymView last update date time
SynonymView weight (Impromptu)
Framework Manager property
Lineage
This is a custom property.
Imported lineage
This is a custom property.
No longer required
Help text
This is a custom property.
No longer required
Steward
This is a custom property.
No longer required
No longer required
No longer required
Synonyms
Migration maps Architect SynonymTables to Framework Manager as database query subject
shortcuts.
The parent of an ArchitecttTable is a schema object. An Architect schema (p. 110) maps to
Framework Manager as a schema namespace.
For information about query subjects and shortcuts, see the Framework Manager User Guide.
To view the query subject properties, in the Project Viewer, in the Data Access Layer namespace,
click the query subject you want. A list of the query subject properties appears in the Properties
pane.
Architect property
SynonymTable name
SynonymTable description text
SynonymTable imported description text
SynonymTable import source
SynonymTable external ID
SynonymTable lineage
SynonymTable imported lineage
SynonymTable import exclusion list
SynonymTable help text
Framework Manager property
Name
Description
Imported description text
This is a custom property.
No longer required
No longer required
Lineage
This is a custom property.
Imported lineage
This is a custom property.
No longer required
Help text
114 Migration Tools

Chapter 11: Architect Mapping
Architect property
SynonymTable imported help text
SynonymTable steward
SynonymTable estimated record count
SynonymTable last update date time
SynonymTable weight (Impromptu)
Framework Manager property
No longer required
Steward
This is a custom property.
No longer required
No longer required
No longer required
Columns
Migration maps Architect columns to Framework Manager as query items.
The parent of an Architect column is a table, view, SQL query, or an Impromptu HotFile. Tables
(p. 111), views (p. 112), and SQL queries (p. 110) map to Framework Manager as database query
subjects. Migration does not include Impromptu HotFiles.
To view the query subject properties, in the Project Viewer, in the Data Access Layer namespace,
click the query subject you want. A list of the query subject properties appears in the Properties
pane.
Architect property
Column name
Column description text
Column imported description text
Column import source
Column external ID
Column lineage
Column imported lineage
Column help text
Column imported help text
Column steward
Column null allowed
Column data type
Column size
Column scale
Framework Manager property
Name
Description
Imported description text
This is a custom property.
No longer required
No longer required
Lineage
This is a custom property.
Imported lineage
This is a custom property.
Help text
This is a custom property.
No longer required
Steward
This is a custom property.
Nullable
Datatype
Size
Scale
User Guide 115

Chapter 11: Architect Mapping
Architect property
Column leading precision
Column trailing precision
Column MIME type
Column language
Column character set
Column collating sequence
Column expression editor tip
Framework Manager property
No longer required
No longer required
MIMEType
No longer required
Original encoding name
Original collation sequence name
Screen tip
Keys
Migration maps Architect keys to Framework Manager as determinant keys.
The parent of an Architect determinant key is a table. A table maps to a database query subject
(p. 111).
Architect determinants are used to infer usage and create relationships, and their properties are
visible in Framework Manager from the Determinants tab.
Information on the determinant keys that are used to create joins can be found by editing the
definition of the query subject and viewing Determinants tab.
For information about relationships, see the Framework Manager User Guide.
Architect property
Key name
Key description
Key imported description text
Key import source
Key external ID
Key lineage
Key imported lineage
Key import exclusion list
Key help text
Key imported help text
Key steward
Framework Manager property
Determinant key name
Text description
Imported description text
This is a custom property.
No longer required
No longer required
Lineage
This is a custom property.
Imported lineage
This is a custom property.
No longer required
Help text
This is a custom property.
No longer required
Steward
This is a custom property.
116 Migration Tools

SQL Query Folders
Chapter 11: Architect Mapping
Migration maps SQL query folders to Framework Manager as SQL queries namespaces.
The parent of an Architect SQL query folder is the Data Access Layer folder. The children of an
Architect SQL Query folder map to Framework Manager as database query subjects.
For information about database query subjects, see the Framework Manager User Guide.
To view the SQL queries namespace properties, in the Project Viewer, expand the Data Access
Layer namespace and click the SQL Queries namespace. A list of the properties appears in the
Properties pane.
Architect property
SQL query folder name
SQL query folder description text
SQL query folder imported description
text
SQL query folder import source
SQL query folder external ID
SQL query folder lineage
SQL query folder imported lineage
SQL query folder import exclusion list
SQL query folder help text
SQL query folder imported help text
SQL query folder steward
Framework Manager property
Name
Description
Imported description text
This is a custom property.
No longer required
No longer required
Lineage
This is a custom property.
Imported lineage
This is a custom property.
No longer required
Help text
This is a custom property.
No longer required
Steward
This is a custom property.
SQL Queries
Migration maps SQL queries to Framework Manager as database query subjects.
The parent of an Architect SQL query is the SQL query folder. The SQL query folder (p. 117)
maps to Framework Manager as an SQL query namespace.
The child of an SQL query is a column. A column maps to Framework Manager as a query item
(p. 115).
For information about database query subjects, see the Framework Manager User Guide.
Architect property
SQL query name
SQL query description text
Framework Manager property
Name
Description
User Guide 117

Chapter 11: Architect Mapping
Architect property
SQL query imported description text
SQL query import source
SQL query external ID
SQL query lineage
SQL query imported lineage
SQL query import exclusion list
SQL query help text
SQL query imported help text
SQL query steward
SQL
SQL query estimated record count
Framework Manager property
Imported description text
This is a custom property.
No longer required
No longer required
Lineage
This is a custom property.
Imported lineage
This is a custom property.
No longer required
Help text
This is a custom property.
No longer required
Steward
Query subject SQL property
Not applicable
Stored Procedures
Migration maps Architect stored procedures to Framework Manager as model functions. Stored
procedures are visible only in the Object Explorer view in Framework Manager.
The parent of an Architect stored procedure is a schema object. An Architect schema (p. 110)
maps to Framework Manager as a schema namespace.
For information about stored procedure query subjects, see the Framework Manager User Guide.
To view the stored procedure properties, in the Object Explorer View, under the database schema
folder in the Data Access namespace, click the stored procedure. A list of the stored procedure
properties appears in the Properties pane.
Architect property
Stored procedure name
Stored procedure description text
Stored procedure imported description
text
Stored procedure import source
Stored procedure external ID
Stored procedure lineage
Stored procedure imported lineage
Framework Manager property
Name
Description
Imported description text
This is a custom property.
No longer required
No longer required
Lineage
This is a custom property.
Imported lineage
This is a custom property.
118 Migration Tools

Chapter 11: Architect Mapping
Architect property
Stored procedure import exclusion list
Stored procedure help text
Stored procedure imported help text
Stored procedure steward
Stored procedure SQL label
Stored procedure expression editor tip
Stored procedure parameters tab
Stored procedure results tab
Framework Manager property
No longer required
Help text
This is a custom property.
No longer required
Steward
This is a custom property.
canonicalName
syntaxTip
+ procParameters
+ result
Stored Procedure Parameters
Migration maps Architect stored procedure parameters to Framework Manager as stored
procedure parameters. Stored procedure parameters are visible only in the Object Explorer view in
Framework Manager.
For information about stored procedure query subjects, see the Framework Manager User Guide.
To view the stored procedure parameter properties, in the Object Explorer View, click the stored
procedure. Expand the +procParameters tab in the Properties pane to view the parameters.
Architect property
Stored procedure parameter name
Stored procedure parameter description
text
Stored procedure parameter data type
Stored procedure parameter size
Stored procedure parameter null allowed
Framework Manager property
Name
Description
Datatype
Size
Nullable
Stored Procedure Return Parameters
Migration maps Architect stored procedure return parameters to Framework Manager as model
function results. Stored procedures are visible only in the Object Explorer view in Framework
Manager.
For information about stored procedure query subjects, see the Framework Manager User Guide.
To view the stored procedure parameter properties, in the Object Explorer View, click the stored
procedure. Expand the +result tab in the Properties pane to view the properties.
Architect property
Stored procedure return parameter name
Framework Manager property
Name
User Guide 119

Chapter 11: Architect Mapping
Architect property
Stored procedure return parameter
description text
Stored procedure return parameter
imported description text
Stored procedure return parameter import
source
Stored procedure return parameter
external ID
Stored procedure return parameter
lineage
Stored procedure return parameter
imported lineage
Stored procedure return parameter import
exclusion list
Stored procedure return parameter help
text
Stored procedure return parameter
imported help text
Stored procedure return parameter
steward
Stored procedure return parameter data
type
Stored procedure return parameter size
Stored procedure return parameter scale
Stored procedure return parameter null
allowed
Stored procedure return parameter
leading precision
Stored procedure return parameter
trailing precision
Stored procedure return parameter
language
Stored procedure return parameter
character set
Framework Manager property
Description
Imported description text
This is a custom property.
No longer required
No longer required
Lineage
This is a custom property.
Imported lineage
This is a custom property.
No longer required
Help text
This is a custom property.
No longer required
Steward
This is a custom property.
DataType
Size
Scale
Nullable
No longer required
No longer required
No longer required
No longer required
Indexes
The migration process uses Architect indexes to infer usage and create relationships.
120 Migration Tools

Chapter 11: Architect Mapping
The parent of an Architect index is a table. Tables map to Framework Manager as a database
query subject (p. 111).
Architect property
Index name
Index description text
Index imported description text
Index import source
Index external ID
Index lineage
Index imported lineage
Index import exclusion list
Index help text
Index imported help text
Index steward
Index null allowed
Index type
Framework Manager property
Name
Description
Imported description text
This is a custom property.
No longer required
No longer required
Lineage
This is a custom property.
Imported lineage
This is a custom property.
No longer required
Help text
No longer required
Steward
This is a custom property.
No longer required
Unique
Physical Joins
Migration maps Architect physical joins to Framework Manager as relationships between
database query subjects.
The parent of an Architect physical join is the model root.
Architect property
Physical join name
Physical join description text
Physical join imported description text
Physical join import source
Physical join external ID
Physical join lineage
Framework Manager property
Name
Description
Imported description text
This is a custom property.
No longer required
No longer required
Lineage
This is a custom property.
User Guide 121

Chapter 11: Architect Mapping
Architect property
Physical join imported lineage
Physical join import exclusion list
Physical join help text
Physical join imported help text
Physical join steward
Physical join reference to left table
Physical join reference to right table
Physical join left cardinality
Physical join right cardinality
Physical join left role
Physical join right role
Physical join expression
Framework Manager property
Imported lineage
This is a custom property.
No longer required
Help text
This is a custom property.
No longer required
Steward
This is a custom property.
Left refobject
Right refobject
Left mincard, maxcard
Right mincard, maxcard
Left description property
Right description property
Expression
Mapping Architect Package Layer Metadata
Package Folders
After you import an Architect XML file to Framework Manager, the following namespaces that
correspond to layers in an Architect model appear in the Project Viewer:
• Data Access Layer (p. 108)
• Business Layer (p. 101)
• Package Layer
These namespaces contain the migrated metadata from each of the corresponding layers in
Architect. The namespaces are organized hierarchically in the Project Viewer. For information
about namespaces, see the Framework Manager User Guide.
Migration maps Architect packages to the Packages Layer namespace and the Packages folder in
Framework Manager. The packages in the Package Layer namespace are shortcuts to the objects
in the Business Layer namespace. If you delete the Package Layer namespace, you invalidate the
packages in the Packages folder.
We recommend that you create a new package using the objects from the Business Layer or Data
Access Layer namespaces. For information about packages, see the Framework Manager User
Guide.
Migration maps object properties that are set in Architect, unless the properties do not apply to
Framework Manager objects. The migration process uses some objects, such as steward and
lineage, for informational purposes.
For information about object properties, see the Framework Manager User Guide.
Migration maps a user-defined Architect package folder to Framework Manager as a Package
Layer namespace.
122 Migration Tools

Chapter 11: Architect Mapping
The parent of an Architect package folder is the root package folder. The root package folder is
not migrated to Framework Manager. Children of a user defined Architect package folder are
other package folders or packages. Architect packages map to Framework Manager as two
objects, a package namespace and a package (p. 123).
To view the Package Layer namespace properties, in the Project Viewer, click the Package Layer
namespace. A list of the properties appears in the Properties pane.
Architect property
Package folder name
Package folder description text
Package folder imported description text
Package folder import source
Package folder external ID
Package folder lineage
Package folder imported lineage
Package folder import exclusion list
Package folder help text
Package folder imported help text
Package folder steward
Framework Manager property
Name
Description
Imported description text
No longer required
No longer required
Lineage
Imported lineage
No longer required
Help text
No longer required
Steward
Packages
Migration maps Architect packages to Framework Manager as two objects, a package namespace
and a package object.
A package is also created for each Architect user class. For more information, see "Architect
Model Security" (p. 99).
The parent of an Architect package is the package folder. The package folder maps to Framework
Manager as a Package Layer namespace (p. 122).
The children of an Architect package are subject folders, subject entities, subject attributes, subject
filters, or subject prompts.
Architect property
Subject folder
Framework Manager property
Namespace
Subject entity Shortcut or model query subject (p. 125)
Subject attribute Query item (p. 126)
Subject filter Embedded filter or filter shortcut (p. 126)
Subject prompt Query item or a shortcut to a calculation (p. 125)
When you expand the Package Layer namespace, a list of the migrated packages appears. Each
package has its own set of properties that can be viewed in the Properties pane.
User Guide 123

Chapter 11: Architect Mapping
To view the properties for a specific package, in the Project Viewer, expand the Package Layer
namespace, and click the package you want. A list of the properties appears in the Properties
pane.
Architect property
Package name
Package description text
Package imported description text
Package import source
Package external ID
Package lineage
Package imported lineage
Package import exclusion list
Package help text
Package imported help text
Package steward
Package target application
Package Cognos Query limits
Framework Manager property
Name
Description
Imported description text
No longer required
No longer required
Lineage
Imported lineage
No longer required
Help text
No longer required
Steward
Target applications
This is a custom property.
No longer required
Subject Folders
Subject Filters
Migration maps Architect subject folders to Framework Manager as model query subjects or
namespaces.
If the children of the Architect subject folder are all subject attributes, subject filters, or subject
prompts, the subject folder maps to Framework Manager as a model query subject. Otherwise,
the subject folder maps to Framework Manager as a namespace.
If the Architect subject folder maps to Framework Manager as a namespace, the following
mappings occur:
• all children subject attributes map as embedded calculations
• all children subject filters map as filter shortcuts pointing to corresponding model filters in the
Business Layer namespace
• all subject prompts map as model calculation shortcuts
Migration maps Architect subject filters to Framework Manager as embedded filters or filter
shortcuts.
If the parent of the subject filter maps to Framework Manager as a query subject, the subject filter
maps as an embedded filter that references the corresponding model filter in the Business Layer
namespace.
If the parent of the subject filter maps to Framework Manager as a namespace, the subject filter
maps as a filter shortcut that points to the corresponding model filter in the Business Layer
namespace.
124 Migration Tools

Subject Prompts
Subject Entities
Chapter 11: Architect Mapping
Migration maps Architect subject prompts to Framework Manager as query items or shortcuts to
model calculations.
If the parent of the subject prompt maps to Framework Manager as a query subject, the subject
prompt maps as a query item referencing the corresponding model calculation in the Business
Layer namespace.
If the parent of the subject prompt maps to Framework Manager as a namespace, the subject
prompt maps as a model calculation pointing to the corresponding model calculation in the
Business Layer namespace.
Migration maps Architect subject entities to Framework Manager as a shortcut or model query
subject. The subject entity is a copy of an entity in the Business Layer.
The subject entity maps as a query subject shortcut if all children of the subject entity reference the
attributes of the entity specified in the Based On property. Otherwise, the subject entity maps as a
model query subject.
The parent of a subject entity is a package folder, package, or subject folder. A package folder
maps as a Package Layer namespace (p. 122). A package maps as both a Framework Manager
namespace and a Framework Manager package (p. 123). A subject folder maps as either a model
query subject or a namespace (p. 124).
The children of an Architect subject entity are subject attributes, subject filters, or subject
prompts.
Architect property
Subject attribute
Framework Manager property
Query item (p. 126) or model calculation,
depending on its parent
Subject filter Embedded filter or filter shortcut (p. 124)
Subject prompt Query item or a shortcut to a calculation (p. 125)
To view the properties for a specific subject, in the Project Viewer, expand the Package Layer
namespace, expand a package, and click the subject you want. A list of the properties appears in
the Properties pane.
The following are the mapped properties if the subject entity maps to Framework Manager as a
model query subject. Otherwise, the subject entity has the properties of a shortcut.
Architect property
Subject entity name
Subject entity description text
Subject entity imported description text
Subject entity import source
Subject entity external ID
Subject entity lineage
Subject entity imported lineage
Subject entity import exclusion list
Framework Manager property
Name
Description
Imported description text
No longer required
No longer required
Lineage
Imported lineage
No longer required
User Guide 125

Chapter 11: Architect Mapping
Architect property
Subject entity help text
Subject entity imported help text
Subject entity steward
Subject entity list of references
Framework Manager property
Help text
No longer required
Steward
No longer required
Subject Attributes
Migration maps Architect subject attributes to Framework Manager as query items or model
calculations.
The parent of a subject attribute is a package folder, subject folder, package, or a subject entity.
Architect property
Framework Manager property
Package folder Package namespace (p. 122)
Subject folder Model query subjects or namespaces (p. 124)
Package Package namespace and a package object (p. 123)
Subject entity Shortcut or a model query subject (p. 125)
To ensure that migration was successful, in Framework Manager, in the Package Layer
namespace, right-click a subject name, and click Go To Target. The equivalent Business Layer
object appears in the Object Explorer view.
Architect property
Subject attribute name
Subject attribute description text
Subject attribute imported description
text
Subject attribute import source
Subject attribute external ID
Subject attribute lineage
Subject attribute imported lineage
Subject attribute import exclusion list
Subject attribute help text
Subject attribute imported help text
Subject attribute steward
Subject attribute list of references
Framework Manager property
Name
Description
Imported description text
No longer required
No longer required
Lineage
Imported lineage
No longer required
Help text
No longer required
Steward
No longer required
126 Migration Tools

Chapter 12: Impromptu Functions Mapping
Functions are predefined calculations you use to define an expression to do one of the following:
• Create a calculation.
• Create a condition to filter report data or conditionally format a report.
• Create a condition or calculation to store in the catalog.
The migratetoc8 process maps Cognos Series 7 functions to a syntax supported by Framework
Manager. If errors occur for functions mapping, view the log file to see details about the error and
identify changes required to correct the error. For more information about the log file, see
"Troubleshooting" (p. 133).
Function mapping for migration is controlled by the impimr2xml-translate-functions-map.xml
file. If you receive errors about functions, the information in this file may help you to troubleshoot
the function mapping for your environment.
The impimr2xml-translate-functions-map.xml file is in the migs7 directory where you installed the
Cognos Series 7 migration tools. For example, if you installed the migration tools to the default
Cognos Series 7 installation location, the file is in C:\Program Files\cognos\cer5\migs7.
The following table describes how some Impromptu functions are processed.
Function
_age(date_exp)
first-of-month(date_expdatetime_exp)
moving-average(numeric_exp, integer_exp)
Mapping
Cognos 8 does not process this
function the same way as Impromptu.
We recommend that you open the
report in Report Studio and replace
instances of this function with the
expression: current_date -
(date_exp), and then format the
result as interval to show the value in
days.
This function does not exist in Cognos
8.
For this function, Impromptu returns
zero if the user specifies more
preceding rows than available.
Cognos 8 returns the average of the
preceding rows that exist.
User Guide 127

Chapter 12: Impromptu Functions Mapping
Function
round-down(numeric_exp,integer_exp)
spread(string_exp)
substitute (string_exp1, string_exp2)
_ymdint_between()
Mapping
Because this function is usually
mapped to _round ( numeric_exp,
integer_exp ) in Cognos 8, values
calculated using the round-down
function in Impromptu may be
different in reports migrated to
Cognos 8. For example, the expression
round-down ( 157.25, 1 ) returns
157.2 , while the expression _round
( 157.25, 1 ) returns 157.3.
Also, for the Impromptu function, if
the value of the integer_exp
parameter is negative, the function
rounds the digits to the left of the
decimal point. Because a negative
integer is not a valid value for the
integer_exp parameter of the
Cognos 8 function, an error message
appears when the report runs in
Cognos 8.
This function does not exist in Cognos
8. The value of the parameter
string_exp replaces the call to the
function.
This function does not exist in Cognos
8. The value of the parameter
string_exp1 replaces the call to the
function.
Cognos 8 does not process this
function the same way as Impromptu.
We recommend that you open the
report in Report Studio and replace
instances of this function with the
expression: datetime_exp1 -
(datetime_exp2), and then format
the result as interval to show the value
in days.
The following functions are not supported in Cognos 8:
• arctan2()
• cosh()
• ctoi4()
• database()
• day_of_ymd_interval()
• daysint_to_ymdint()
• decrypt()
• encrypt()
• number_to_character()
• pack()
• month_of_ymd_interval()
• partition()
• pi()
128 Migration Tools

Chapter 12: Impromptu Functions Mapping
• reverse()
• user()
• year_of_ymd_interval()
• ymdint_to_daysinst()
User Guide 129

Chapter 12: Impromptu Functions Mapping
130 Migration Tools

PART 4: Appendices
User Guide 131

132 Migration Tools

Appendix A: Troubleshooting
Log Files
Use this troubleshooting reference information and solutions as a resource to help you solve
specific problems you may encounter when using the migration tools.
Problems are characterized by their symptoms. Each symptom can be traced to one or more causes
by using specific troubleshooting tools and techniques. After being identified, each problem can be
fixed by implementing a series of actions.
When you are troubleshooting, log files can help you. Another valuable troubleshooting tool is the
Knowledge Base, which is available on the Cognos Global Customer Services Web site
(http://support.cognos.com). The Knowledge Base is a database of problems and solutions for all
Cognos products.
When you cannot resolve a problem, the final resource is your Cognos technical support
representative. To analyze a problem, your technical support representative requires information
about the situation and the symptoms that you are experiencing. To help isolate the problem,
collect the necessary data before you contact your representative.
Problems that you may encounter are organized in the following areas. Log files may also contain
information to help you solve problems.
• "Problems Migrating Metadata" (p. 134)
• "Problems Importing Metadata into Framework Manager" (p. 136)
• "Problems Migrating Applications" (p. 137)
• "Problems Deploying Migrated Applications" (p. 139)
• "Problems Running Migrated Reports" (p. 140)
• "Problems with Report Formatting" (p. 147)
• "Problems with Security" (p. 149)
Where appropriate, the error message is used as the title of the troubleshooting topic.
Log files can help you troubleshoot problems by recording the activities that take place when you
work with a product. Operations performed by the migration tools are recorded in various log
files for tracking purposes. For example, if you experienced problems installing the tools, consult
the transfer log file to learn what activities the installation wizard performed while transferring
files.
Note: We recommend that you 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 folders may grow
quickly.
Installation Log Files
The installation wizard creates two log files in the installation_location\instlog directory. The log
file names include the product name, version, build number, and time stamp.
The transfer log file records the activities that the installation wizard performed while transferring
files. The transfer log file is in the installation_location\instlog directory. The file name identifies
the product name, version, and build number, and includes a time stamp. The following is an
example of the file name format:
tl-MIGRATION-8.2.209.345-20061018_1426.txt
User Guide 133

Appendix A: Troubleshooting
The transfer summary-error log file records the components you installed, disk space information,
the selections you made in the transfer dialogs, and any errors the installation wizard encountered
while transferring components. The transfer summary-error log file is in the
installation_location/instlog directory. The file name identifies the product name, version, and
build number, and includes a time stamp. The following is an example of the file name format:
tl-MIGRATION-8.2.209.345-20061018_1426_summary-error.txt
The uninstallation log file records the activities that the Uninstall wizard performed while
uninstalling files. The log file is named cognos_uninst_log.htm and is located in the Temp
directory. You can use the log file to troubleshoot problems related to uninstalling the migration
tools.
Cognos Series 7 Migration Log File
The migratetoc8 process creates a log file named migratetoc8.xml in target\_LOG.
Cognos 8 Migration Log File
The deploytoc8 process creates a log file named viewMigrationLog.html in target\_LOG. This log
file includes information about the deploytoc8 process and the content from the migratetoc8 log
file.
Published PowerPlay Reports Migrated to Cognos 8 Log Files
Any errors encountered when migrating PowerPlay reports published to Cognos 8 Cognos
Connection are logged in Cognos 8 installation_location\temp\migrsvp.
Problems with the Command Line Tools
Command Fails to Run with Special Character in File Path
If the source or target file path includes the special characters ampersand (&), pipe (|), or
parentheses ( ), the migration command will fail to run.
To use these special characters in a file path, the special characters must be XML encoded. For
example, the following commands will run properly:
migratetoc8 "e:\IS&T\reports" "e:\IS&T\migrate"
migratetoc8 e:\IS^&T e:\IS^&T\migrate
Problems Migrating Metadata
Metadata Objects Are Missing After Migration
Objects may not appear as expected or may be missing after you migrate an Architect model or
Impromptu catalog to Framework Manager. You can probably determine why by answering the
following questions in the given order:
• Does the object exist in the Architect model or Impromptu catalog that you migrated?
• Do you have access to the object that did not migrate?
You must have appropriate privileges to access the metadata to perform the migration. For
example, you must have Creator access to export a catalog using the impcat2xml tool.
• Does the object exist in the Framework Manager project?
If you cannot find the object, check the migration log file for information about how the
migration process handled the object.
Some objects may be hidden by default in Framework Manager. For example, check the
package definition to determine if an object is selected or not.
134 Migration Tools

Appendix A: Troubleshooting
Exception Raised
If the Framework Manager import did not include the object, you can achieve similar
functionality using Framework Manager. For more information, see the Framework Manager
User Guide.
This error occurs if the command line syntax is incorrect.
Ensure that you specified the appropriate parameters on the command line. If you still encounter
the error, test the parameters individually. For example, enter only mandatory parameters and see
if the problem still occurs. If the migration is successful, gradually add the optional parameters
back.
Prompted to Log On During Metadata Export
If an Architect model or Impromptu catalog is secured and you do not provide namespace
authentication information in the command line, the migration process prompts you for the user
ID and password. You can still export the model if you log on interactively.
If you want to do a silent or batch export, ensure that you include the user ID and password on
the command line.
Failed to Open Model, Terminating XML Generation
This error can occur if the Architect model is open or if the ObjectStore services are not running
when you run the arch2xml74 command.
Ensure that the model is not currently open in Architect, and that the ObjectStore services are
running.
If you still encounter the migration error, open the model in Architect and ensure that the model
does not include errors.
Logon Prompts While Migrating Catalogs
The migration process prompts you to log on when you attempt to export an Impromptu catalog.
This can occur if you changed the password for the Creator user name and you did not enter the
new password properly. The default authentication credentials are a user name of Creator, and no
password.
Problems Migrating a Non-English Impromptu Catalog
If you export catalogs using a non-English version of Impromptu, you must specify the Creator
name for the language of Impromptu that you use. If you do not specify the localized Creator
name, the tool defaults to the English name Creator.
For example, if you use the German version of Impromptu, type the following:
impcat2xml -n Ersteller c:\testcatalogs\gosales.cat c:\xmlcats\gosales.xml
If you use the French version of Impromptu, type the following:
impcat2xml -n Auteur c:\testcatalogs\gosales.cat c:\xmlcats\gosales.xml
Unable to Start the Impromptu Automation Server
You attempt to migrate a catalog, and the Impromptu automation server does not start.
This error can occur if the impadmin server is not registered, possibly because Impromptu was
installed without applying the configuration using Configuration Manager. This error can also
occur when you uninstall a previous version of Impromptu after installing a more recent version.
User Guide 135

Appendix A: Troubleshooting
To correct this error you need to reapply the configuration settings for Impromptu Administrator.
In Cognos Series 7 Configuration Manager, select Cognos Impromptu.Impromptu Administrator,
and then from the Actions menu, click Apply Selection. Close Configuration Manager and then
run the impcat2xml command.
Unable to Open an Impromptu Catalog
When you run the impcat2xml command, you get an error message indicating that the migration
process was unable to find a catalog.
To fix this problem, ensure that the following statements are true:
• The catalog path is correct.
• You can open the catalog interactively using the version of Impromptu Administrator that the
commands use during migration.
Tip: If Impromptu is open, and a dialog box is waiting for input, the impcat2xml command
may not run successfully.
• You have sufficient security credentials to open the catalog.
If all the statements are true, open the Cognos Series 7 Configuration Manager, reapply the
settings for Impromptu Administrator, and run the command again.
This error can also occur when you use the migratetoc8 tool for Impromptu report migration. For
more information, see "Unable to Open the Catalog for the Following Impromptu
Report" (p. 137).
You Cannot Open Catalog as Creator When Running User Version of
Impromptu
If you have both Impromptu User and Impromptu Administrator installed on the computer where
you run the impcat2xml command, you may receive an error stating that you cannot open a
catalog as Creator when running Impromptu User.
To correct this error you need to reapply the configuration settings for Impromptu Administrator.
In Cognos Series 7 Configuration Manager, select Cognos Impromptu.Impromptu Administrator,
and then from the Actions menu, click Apply Selection. Close Configuration Manager and then
run the impcat2xml command.
Problems Importing Metadata into Framework Manager
XML Validation Error Occurs When Importing XML Files into Framework
Manager
In Framework Manager, if you import an XML file that is not of the metadata type that you
selected, the XML validation error message appears. For example, you try to import the XML file
for an exported Architect model using the Cognos Impromptu XML option.
Try the import again, specifying the correct metadata type.
This error can also occur if the XML file was modified after export. If this is the case, delete the
file and run the appropriate migration tool again to create a new XML file.
Query Items in an Impromptu Subfolder Are Represented by Calculation Icons
in Framework Manager
You migrate an Impromptu folder that has a subfolder and subfolder items. The subfolder items
appear as calculations in Framework Manager. This does not affect the functionality of the object.
136 Migration Tools

Unexpected Results with Filters After Migrating Architect Models
Appendix A: Troubleshooting
Because Architect and Framework Manager support different filter types, you may have to update
filter properties to achieve the expected results.
For example, you want to use an optional filter. Because Architect does not support optional
filters, you must change the filter properties in Framework Manager. For more information about
working with filters, see the Framework Manager User Guide.
Incorrect Decimal Separators After Importing Architect Model Metadata
After importing Architect model metadata into Framework Manager, the decimal separators do
not match the format in the original Architect model. This can be caused by differences between
regional settings on the Cognos Series 7 computer and the Framework Manger design language.
To correct the problem, change the regional settings on the Architect computer to use the same
decimal separator as the Framework Manager design language and then repeat the export process
using the Architect model migration tool. When you import the metadata, the correct decimal
separator should appear. After exporting the model, change the regional settings back to the
original format. For more information, see "Temporarily Change the Locale Settings on the
Architect Computer" (p. 29).
Problems Migrating Applications
Unable to Open the Catalog for the Following Impromptu Report
A message appears during export indicating that the migration process was unable to find a
catalog.
Because each report is opened in the background during migratetoc8 processing, the catalog must
be accessible, either by preserving the report and catalog folder structure from the original
working location, or by placing a copy of the catalog in the migration source folder with the
reports.
Try the following to correct the error:
• Check the command line syntax for errors.
• Open a report from the migration source location to ensure that the catalog is available.
• Move the catalog to the same location as the reports and repeat the export.
Errors Migrating Large Applications
It can be difficult to troubleshoot errors when migrating large applications.
If possible, migrate the application in parts. Export, deploy, and test each part before completing
the migration process for the remainder of the application.
Same Problems Occur When Migrating Reports
When you migrate many or all of your reports, you see the same problems occur. This can happen
when many reports in an application are set up as clones or copies of a few original reports, so
they are very similar in structure. If you encounter a problem or defect, the same problem can
affect many or all of your reports.
Try migrating reports from a different application.
Unable to Find the Source Folder Containing the Images to be Migrated
If you know that the reports do not use any images, you can ignore this message. Otherwise, see
"Missing Images in Migrated Reports" (p. 141) for information about resolving this problem.
User Guide 137

Appendix A: Troubleshooting
An Impromptu Report Cannot Be Accessed
Migration fails because the migratetoc8 process cannot access a report.
This can occur if the Impromptu report generates errors or interactive messages, other than
prompts, when run in Impromptu.
Check whether you can open the Impromptu report without any errors or interactive messages. If
there are errors, fix them and run the migratetoc8 command again.
Packlets Cannot Be Found
If you use a Deployment Manager package created in a distributed Cognos Series 7 environment,
the package and packlet files you want to use as the migration source may be on different
computers. For example, the Deployment Manager package file (.dmp) can be on a Windows
computer and the packlets can be on one or more UNIX computers. If the package and packlet
files are not on the same computer, you get an error when you run the migratetoc8 command
indicating the migration process cannot find a packlet.
Before running the migratetoc8 command, the package and packlet files must be located on the
computer where you will run the migratetoc8 command. Also, you must modify the .dmp file to
show the correct location of the packlet files.
For more information, see "Create the Migration Source Using a Deployment Manager
Package" (p. 41).
Categories Missing from a Migrated PowerPlay Report that Includes Child
Categories That Do Not Roll Up
In PowerPlay, a report can refer to a category that has children that do not roll up. If you migrate
a report that uses a category whose children do not roll up on rows or columns, those categories
are missing from the report after migration.
For example, in the following structure, Current Month does not roll up to Relative Time.
In this example, if you migrate a PowerPlay report that uses any of the child categories of Relative
Time as rows or columns, those categories are missing from the report after migration.
The migration log file will include a message for this report indicating that a category is missing
from the package.
There is no workaround for this problem.
Suppressed Categories Replaced by Children Categories in Migrated PowerPlay
Explorer Reports
If a category is suppressed in Cognos 8, the category is replaced by its children in migrated
reports. A suppressed category is present in the cube but has been implicitly suppressed, and
therefore cannot be referenced by the Cognos 8 model. An example of a category that would be
suppressed in Cognos 8 is Relative Time.
The migration log file will include a message for this report indicating that a category is
suppressed from the package.
138 Migration Tools

Appendix A: Troubleshooting
Problems Deploying Migrated Applications
Login to Cognos 8 Failed. Please Verify Credential Information
If anonymous access is disabled in Cognos 8 and you do not provide the correct user and
namespace information with the deploytoc8 command, the deploytoc8 process fails. The
migration log file includes the following error:
Login to Cognos 8 failed. Please verify credential information.
To correct the error, run the deploytoc8 command again providing the correct user and namespace
information.
CM-REQ-4024 Name Conflict
You attempt to deploy a migrated report set, but Cognos 8 returns an error message similar to the
following:
The name [time_date_stamp] conflicts with the names of existing object(s)
/[Import/time_date_stamp]. Your application may not display all objects that exist at this location.
This occurs when you attempt to deploy a migrated report set that was previously deployed.
The specification that was created by the original migration was named according to the time and
date stamp of the migratetoc8 command. If you run the deploytoc8 command on the same
migrated report set, Cognos 8 attempts to create a new import specification using the same time
stamp. You will get an error message indicating a name conflict. You cannot deploy a migrated
report set twice.
To update a report set that was already deployed, do one of the following:
• Run the migratetoc8 command on the report set again, and run the deploytoc8 command on
the newly migrated report set.
• In Cognos Connection, from the Tools menu, click Deployment. Click the Import tab, find the
import specification, and click Update Import.
• In Cognos Connection, from the Tools menu, click Deployment. Click the Import tab, delete
the old import specification, and run the deploytoc8 command.
JRE Not Found. Cannot Run the Migration Tool
When you run the deploytoc8 command, you receive a JRE error. This can happen if you have
installed the Cognos 8 migration tool in a different location than where Cognos 8 is installed.
The Cognos 8 migration tool must be installed in the installation_location\Cognos\c8 directory.
For more information, see the Migration Tools Installation and Configuration Guide.
None of the Packages Listed in the nameMap.xml file Were Found in the
Content Store
When you run the deploytoc8 command, you receive an error indicating the deploy process did
not find a required package in the Cognos 8 content store. Review the following possible causes
for this error to identify a solution that applies to your situation.
Package Name in Namemap.xml File Does Not Match Name of Published Package
The migratetoc8 process creates a nameMap.xml file that contains a default package name for
each package expected in Cognos 8. The nameMap.xml file is located in _SUPPORT\maps in the
migratetoc8 target location.
Open the nameMap.xml file in an XML or text editor and verify that the name in each
element matches a published package in Cognos 8. If the package names do not
match, edit the nameMap.xml to make the package name the same as the name of the published
package and then run the deploytoc8 command again.
User Guide 139

Appendix A: Troubleshooting
For more information, see "Check Package Mapping" (p. 47).
Package Does Not Exist in Cognos Connection
Verify that the required metadata is available. Each migrated report must map to an existing
package in Cognos 8. For Impromptu reports you must create and publish a package using a
migrated catalog (p. 37). For PowerPlay reports you must create a data source connection in
Cognos 8 to required cubes and then create and publish a package. For more information about
using cubes in Cognos 8, see the Cognos 8 Administration and Security Guide.
If the package was not available when you ran the deploytoc8 tool, you must create and publish a
package from Framework Manager to Cognos Connection and then run the deploytoc8 command
again.
Wrong Namespace ID Specified in the Deploytoc8 Command
Verify that you specified the correct namespace ID, and that there wasn’t a typing error in the
namespace ID, in the deploytoc8 command.
If there was a problem with the namespace ID, run the deploytoc8 command again specifying the
correct namespace ID.
Problems Running Migrated Reports
Migrated Impromptu Report Fails to Run or Runs with Errors
When you attempt to run a migrated report, the report fails to run or runs with errors. These
errors may be caused by problems that existed before migration. For example, the following error
is related to a problem that existed in the original report and is not caused by an error in the
migration process or an incompatibility between Cognos Series 7 and Cognos 8.
Error: UDA-SQL-0196 The table or view "identifier" was not found in the dictionary.
The first step in troubleshooting errors in migrated reports is to ensure that the original report
works correctly in Impromptu. Open the original report in Cognos Series 7 Impromptu. If there
are errors, complete the changes necessary to make the report run successfully and then repeat the
migration process.
Automatic Summary for the Entire Impromptu Report Does not Appear in
Migrated Report
In Impromptu, when you use the total function in an expression and you select Automatic in the
Association box, the calculated total for the entire report appears, such as Total Sales for 2004: $1
057 202.88.
In Cognos 8, the total is not calculated for the entire report because automatic association is not
supported.
To make the total appear for the entire report, open Report Studio and change the expression so
that it uses the report component as follows:
total (Sales04) for report
Report Was Not Migrated
When you try to open a migrated report in Report Studio, an error message appears stating that
the report was not migrated.
This can occur if your reports use encoding rules that are different than those of the operating
system. The migration tool uses the operating system settings to determine which encoding rules
to use. If you need different settings, use -e encoding_name as an optional parameter with the
migratetoc8 command to specify the correct encoding name.
140 Migration Tools

Appendix A: Troubleshooting
For example, to set the encoding value to UTF-8, use the following optional parameter in your
migratetoc8 command:
migratetoc8 -e utf_8 source_location target_location
Missing Images in Migrated Reports
Images are not rendered after you migrate and deploy a report to Cognos 8.
This can occur for the following reasons:
• The image files are in a different location than the report files.
When you run the migratetoc8 command, all graphic files used by reports must be present in
the source directory or subdirectory. Otherwise, the images are not included in the
deployment package. For images to be properly referenced in migrated reports, you must
migrate the images with their respective reports. You cannot migrate the images using a
different migratetoc8 command.
• In the Impromptu report, the image loads using the file name in column, and the value of the
associated data item has trailing spaces.
Switch the data item's datatype to varchar, and update the values so that there are no trailing
spaces.
• In the Impromptu report, the column references image files that are stored in the database
with the .jpg extension.
The migration process adds the .jpg extension to the data item's report expression. Delete the
.jpg extension from the report expression and the images will appear when you run the report.
• You deploy reports to UNIX, and there are type case differences between the database image
reference and the actual file name.
Ensure that the database image reference and the file name are exactly the same, including
type case.
Using Generic Mapping for Function Error for Migrated Impromptu Report
This message indicates that a function in a migrated report may not retain its original meaning
because of generic mapping. Consequently, the results may not be correct. This can occur if the
Impromptu function cannot map directly to a Cognos 8 function.
To ensure that the function provides correct results, use Report Studio to review the function in
the Cognos 8 report specification, and make changes if appropriate.
The Following Function Is not Supported Error for Migrated Impromptu
Report
This message indicates that a function in a migrated report may not retain its original meaning
because it is not supported. Consequently, the results may not be correct. This can occur if the
Impromptu function cannot map directly to a Cognos 8 function.
To ensure that the function provides correct results, use Report Studio to review the function in
the Cognos 8 report specification, and make changes if appropriate.
The Following Function is Mapped as an Expression Using the Cast Operation
Error for Migrated Impromptu Report
This message indicates that a function in a migrated report may not conserve its original objective
because it maps to Cognos 8 as a cast operation. As a result, the results may not be correct. This
can happen if the Impromptu function cannot map directly to a Cognos 8 function.
To ensure that the function provides correct results, use Report Studio to review the function in
the Cognos 8 report specification, and make changes if appropriate.
User Guide 141

Appendix A: Troubleshooting
The Following Function is Mapped as a No-Operation Error for Migrated
Impromptu Report
This message indicates that a function in a migrated report may not conserve its original objective
because it maps to Cognos 8 as a no-operation. As a result, the results may not be correct. This
can happen if the Impromptu function cannot map directly to a Cognos 8 function.
To ensure that the function provides correct results, use Report Studio to review the function in
the Cognos 8 report specification, and make changes if appropriate.
The Following Function is Mapped as a No-Operation on the First Argument
Error for Migrated Impromptu Report
This message indicates that a function in a migrated report may not conserve its original objective
because it maps to Cognos 8 as a no-operation on the first argument. As a result, the results may
not be correct. This can happen if the Impromptu function cannot map directly to a Cognos 8
function.
To ensure that the function provides correct results, use Report Studio to review the function in
the Cognos 8 report specification, and make changes if appropriate.
The Following Function is Mapped as a Constant Value of Zero Error for
Migrated Impromptu Report
This message indicates that a function in a migrated report may not conserve its original objective
because it maps to Cognos 8 as a constant value of zero. As a result, the results may not be
correct. This can happen if the Impromptu function cannot map directly to a Cognos 8 function.
To ensure that the function provides correct results, use Report Studio to review the function in
the Cognos 8 report specification, and make changes if appropriate.
The Following Function is Mapped as a Constant Number Error for Migrated
Impromptu Report
This message indicates that a function in a migrated report may not conserve its original objective
because it maps to Cognos 8 as a constant number. As a result, the results may not be correct. This
can happen if the Impromptu function cannot map directly to a Cognos 8 function.
To ensure that the function provides correct results, use Report Studio to review the function in
the Cognos 8 report specification, and make changes if appropriate.
Unable to Open the Catalog Error for Migrated Impromptu Report
For more information about resolving this problem, see "Unable to Open the Catalog for the
Following Impromptu Report" (p. 137).
Report Objects Not Found When Running Reports
When you try to run a report, an error message indicates that report objects were not found.
This situation can occur for the following reasons:
• The package name does not match the catalog name.
Change the package name so that it is exactly the same as the catalog name, including the
extension. For example, if the catalog name is catalog_name.cat, then ensure that the package
name is also catalog_name.cat.
• You ran the deploytoc8 command before you published a package.
Ensure that the package is published before you run the deploytoc8 command.
142 Migration Tools

Appendix A: Troubleshooting
Parsing Error Message When Migrated Impromptu Report Fails to Run
After you import a report into Cognos 8, it fails to run, and you receive a parsing error.
This situation can happen for the following reasons:
• You used the same location as a source and target directory when you ran the deploytoc8
command. Use a different source and target directory (p. 49).
• You did not use the correct -target parameter syntax (p. 49).
• You are using reports initially created in a pre-6.0 version of Impromptu.
If the report was migrated from a version of Impromptu earlier than 6.0, you must unhide the
tables in the Framework Manager package that supports the migrated reports. Also, use the
Verify Selected Object tool to ensure that there are no invalid objects that can break queries in
the published package. If necessary, correct errors, republish the package, and run the report
again.
For more information, see "Support Reports Created Before Impromptu 6.0" (p. 36).
Steps to Unhide Tables
1. In Framework Manager, right-click the package, and then click Edit Definition.
2. If the hide icon appears beside any component, click the menu for the model, and then click
Select Component and Children.
3. If any components were hidden, republish the package and run the report again.
Incorrect Results from Date/Time Functions for Migrated Impromptu Report
After you migrate and deploy a report to Cognos 8, date/time functions return incorrect results.
For example, the _age function returns 40,214 when it should return 4 years, 02 months, 14 days.
This is an example of a function that does not migrate properly to Cognos 8. For more
information, see "Impromptu Functions Mapping" (p. 127).
To fix this problem, open Report Studio and modify the function directly in the report
specification.
Report Fails to Run with Function Expression Errors for Migrated Impromptu
Report
If a report fails to run because of function expression errors, it is possible that the migration
process did not correctly identify the expression. Open the report in Report Studio, correct the
expression syntax or create an equivalent expression, and run the report again.
Missing Information in Cognos 8 Error Messages
Cognos 8 fails when you try to run migrated reports, but the error message does not contain any
details.
This happens if Cognos Application Firewall (CAF) in Cognos 8 is enabled, which is the default
setting. In this case, you can obtain error message details by accessing crnserver.log, the Cognos 8
server log file. For more information about the Cognos 8 server log file, see the Cognos
Configuration User Guide.
If you are in a test environment, and you need to view error details without going to the log file,
you must disable CAF validation in Cognos 8.
The Cognos Application Firewall is an essential component of Cognos 8 security helping to
provide protection against penetration vulnerabilities. Disabling the Cognos Application Firewall
removes this protection.
For information about changing the Cognos 8 CAF setting, see the Cognos 8 Installation and
Configuration Guide.
User Guide 143

Appendix A: Troubleshooting
The Following Package Was Not Found in the Content Store
For information about resolving this problem, see "Report Objects Not Found When Running
Reports" (p. 142).
Referenced Data Item is Not Found in the Query
When you try to run a migrated report, the following run-time error appears:
Referenced data item is not found in the query Master_Section_Query_5
Steps to manually edit the report specification
1. Open the report specification in Report Studio.
2. Copy the missing data items from the detail query (Query5) to the master query
(Master_Section_Query5).
3. Validate the report.
4. If additional errors appear, continue to modify the queries until the report validates without
errors.
For information about correcting the problems with page layout, see "Incorrect Page Breaks or
Blank Pages for Migrated Impromptu Report" (p. 148).
Run-time Error in Conditional Formatting Expression for Migrated Impromptu
Report
When you try to run a migrated report, the following run-time error appears:
An error on or around the position . The variable named is invalid.
Steps to manually edit the report specification
1. Open the report specification in Report Studio.
2. Create a new query.
3. Associate the new query with the layout element that contains the invalid expression.
The layout element is usually Page Body.
4. Add the query items reported in the run-time error message to the new query.
5. Validate the report.
6. If additional errors appear, continue to modify the queries until the report validates without
errors.
An Unhandled Application Error Has Occurred
When you try to run a migrated report, the following run-time error appears if a query item is
missing or invalid:
An unhandled application error has occurred. Please contact your Administrator.
CCLAssertError:0:Fatal: CCL_ASSERT(pRDINode);
Steps to manually edit the report specification
1. Open the report specification in Report Studio.
2. Copy the missing data items from the detail query (Query5) to the master query
(Master_Section_Query5).
3. If the data items do not appear in the layout, add them to the Properties property of the list.
4. Validate the report.
5. If additional errors appear, continue to modify the queries until the report validates without
errors.
For information about correcting the problems with page layout, see "Incorrect Page Breaks or
Blank Pages for Migrated Impromptu Report" (p. 148).
144 Migration Tools

The Report Server is Not Responding
Appendix A: Troubleshooting
After attempting to run a report, you receive an error message that states the report server is not
responding.
To correct the problem, validate the report and correct errors. For example, you may have to
update unresolved query references. If necessary, verify the model in Framework Manager and
correct errors in the model and package used by the report.
For more information, see the Cognos 8 Troubleshooting Guide.
Unexpected Sorting of Grouped Items for Migrated Impromptu Report
There are differences in the default sorting methods between Cognos Series 7 and Cognos 8. After
migration, a grouped item that was not sorted in Cognos Series 7 may be sorted in Cognos 8. The
sorting differences are most common in summary level reports.
For more information about how sorting is controlled and how to change the sorting in Cognos 8,
see the Framework Manager User Guide and the Report Studio User Guide.
Unable to Run a Report Against a Migrated Architect Model
You cannot run migrated reports against a package that was created in Framework Manager from
a migrated Architect model. This is because you cannot author Impromptu reports directly against
an Architect model.
To author Impromptu reports against an Architect model, you must first export the Architect
model to an Impromptu catalog. This catalog must then be migrated using the Impromptu catalog
migration tool. For more information, see "Migrating Metadata" (p. 27).
QFS-ERR-0140 Referenced data item 'Not Found' Error for Migrated
Impromptu Report
If you migrate an Impromptu report that uses a catalog prompt, you may get an error when you
attempt to run the migrated report in Cognos 8. Catalog prompts cannot be migrated using the
migration tools.
Before migrating Impromptu reports, review catalog prompts from the reports and create report
prompts to duplicate the same functionality.
Migrated Impromptu Report Takes Longer Than Expected
When you attempt to run a migrated report, the report takes significantly longer to run than the
original Impromptu report, or the report does not return any results and there is no error to
indicate the report failed to run.
Changing the Auto Group & Summarize property to no for the Query5 object may reduce the
amount of time it takes to run the report.
Data in Migrated Impromptu Report Containing a Master/Detail Query and
Filter Is not Filtered
If you migrate an Impromptu report to Report Studio that contains a master/detail query with a
filter in the detail query, the data is not filtered when you run the report.
In the migrated report, copy the same filter in the master query.
Steps to copy a filter from the detail query to the master query
1. Open the report in Report Studio.
2. Pause the pointer over the query explorer button and click the detail query.
3. Click the filter that you want to copy and then click the copy button in the toolbar.
4. Pause the pointer over the query explorer button and click the master query.
User Guide 145

Appendix A: Troubleshooting
5. In the toolbar, click the paste button.
Invalid Operands in Calculation for Migrated PowerPlay Report
The following log message can indicate that an operand for a calculation was not found in the
package.
The category with the code was not found in the package named .
The calculation is still migrated. However, you have to modify or recreate the calculation in
Report Studio or Analysis Studio to achieve the same results as the original report.
Report Cells Contain -- or #!Error for Migrated PowerPlay Report
If a PowerPlay report uses an alternate hierarchy on both axes, and the Show Value As % of
Grand Total setting is applied to the data, the correct data may not appear in the cells after you
migrate the report.
• -- may appear in the cells if you migrated the reports to Report Studio
• #!Error may appear in the cells if you migrated the report to Analysis Studio
Migrated PowerPlay Report Has Extra or Missing Rows and Columns
If you migrate a PowerPlay report that has zero suppression turned on, you may see extra rows
and columns or, conversely, some rows and columns in the PowerPlay report do not appear in the
migrated report.
Zero suppression is implemented differently in PowerPlay and in Cognos 8. For more
information, see "Zero Suppression" (p. 75).
PowerPlay Reports that Reference Missing Categories Migrate Improperly or
Will Not Run
The problem occurs when you migrate a PowerPlay report which references categories that do not
exist in the cube. This can happen when a report was created with a version of the cube that is
different from the cube used in Cognos 8. For example, a category with a code of Toasters existed
in the cube when the report was authored. In the cube used for the migration to Cognos 8, the
category Toasters was removed and replaced with a new category, Super Toasters. This means that
when Cognos 8 queries the cube for Toasters, it is unable to find a category matching that code.
Reports which exhibit this problem often continue to work in Cognos Series 7 because PowerPlay
can resolve changes to categories in some cases. When PowerPlay is notified that Toasters does not
exist, it will examine the usage of this category in the report. It could discover that the category is
a member of the second level of the Products dimension. PowerPlay then asks the cube to provide
the root category of the second level of the Products dimension, which, in this case, would be
Super Toasters. After it identifies this new category, it substitutes the old category at runtime and
the report, if the new category is semantically equivalent, renders correctly.
The migration tools do not have the context available to PowerPlay to resolve missing categories.
Therefore, Toasters comes back as missing. The migration tools write a message to the log stating
that: "The category with code 'Toasters' was not found in the package named 'My Package'."
To correct the problem, open and save the report in PowerPlay against the same cube used in
Cognos 8. This updates the report and removes any categories that no longer exist in the cube. In
some cases you must manually update the report to ensure it contains the correct categories. After
updating the report in PowerPlay repeat the migration to Cognos 8 process and then test the
migrated report to verify the report opens and runs correctly.
Rank Values Are Different in Migrated Report
When you migrate a PowerPlay Windows report that contains ranking, the rank values may be
different in Cognos 8.
146 Migration Tools

Appendix A: Troubleshooting
The migration tools migrate ranking using the PowerPlay Web method to rank data. If you create
the same report in PowerPlay Web, rank values in PowerPlay Web and Cognos 8 match.
Additional Summary Rows Appear in Migrated PowerPlay Web Reports
When migrating PowerPlay Web reports that contain nested rows under a summary row, a nested
row appears for each summary row in the migrated report. For example, a PowerPlay Web report
has Years and Locations as rows, with Locations nested, and a summary row for Years. In the
migrated report, nested rows appear under the summary rows for Years. Although this behavior is
different than PowerPlay Web, it is consistent with PowerPlay Windows.
There is no workaround.
Using Generic Mapping for Variable Error for Migrated PowerPlay Report
This message indicates that a variable in a title, header, or footer in a migrated report may not
retain its original meaning because of generic mapping. Consequently, the results may not be
correct. This can occur if the PowerPlay variable cannot map directly to a Cognos 8 function. For
more information, see "Titles, Headers, and Footers" (p. 79).
To ensure that the function provides correct results, use Report Studio to review the function in
the Cognos 8 report specification, and make changes if appropriate.
The Following Variable Is not Supported Error for Migrated PowerPlay Report
This message indicates that a variable in a title, header, or footer in a migrated report may not
retain its original meaning because it is not supported. Consequently, the results may not be
correct. This can occur if the PowerPlay variable cannot map directly to a Cognos 8 function. For
more information, see "Titles, Headers, and Footers" (p. 79).
To ensure that the function provides correct results, use Report Studio to review the function in
the Cognos 8 report specification, and make changes if appropriate.
Problems with Report Formatting
A Report Looks Different in Cognos 8 Than in Impromptu
After you open a migrated report in Cognos 8, some style elements may be different from what
they were in Impromptu. This is because Cognos Series 7 and Cognos 8 have different default
style settings. For example, the list grid that was visible in Impromptu is not visible in Cognos 8.
For information about format differences between Impromptu and Cognos 8, see "Impromptu
Report Formatting Mappings" (p. 67) and "Impromptu Reports Mapping" (p. 65).
To set the styles to match default settings that existed in Impromptu, modify the report
specification in Report Studio. For more information, see the Report Studio User Guide.
Missing Headers or Footers
After you migrate and deploy a list report to Cognos 8, headers or footers that contain no text
seem to be missing. The header or footer object is still present in the report specification, but the
height is set to zero.
To make the header or footer visible in the report output, add a text value to the object in Report
Studio. For more information, see the Report Studio User Guide.
Charts or Images Do Not Appear Correctly
After you migrate a report that contains charts or images, the charts or images do not display
correctly. For example, a chart in a table cell may not appear or may be difficult to read. This
display problem may be related to incompatible sizing settings for the chart or image.
User Guide 147

Appendix A: Troubleshooting
To correct the display, in Report Studio, check the Size and Overflow property for the chart or
image object and, if necessary, delete or change the migrated settings.
Incorrect Page Breaks or Blank Pages for Migrated Impromptu Report
An Impromptu report may include filters to limit the data that is displayed on the report. The
same report may also include scope settings to break pages at a specific control break. For this
type of report, the migration tool must create two queries: a master query that manages the page
control breaks, and a detail query that renders the results as with the original Impromptu query.
When you run the report after migration, some of the pages are blank or incomplete.
The problem is incorrect filter settings in the master and detail queries. In the original Impromptu
report, there is usually a filter on the control break item. In the migrated report, the detail query
has this filter, but the master does not. Therefore, the master query returns results for control
break values that are filtered out by the detail query. For example, the master query would return
a row for Product X, the detail query would return no rows for Product X because it is filtered
out, resulting in a rendered page that is mostly blank.
To correct the problem, copy the portion of the detail query filter that affects the control break
item into the master query filter. This change means both queries are filtered the same way with
respect to the control break item.
Pie Chart Does Not Show Any Segments in Migrated PowerPlay Report
Because of differences in the way Cognos Series 7 and Cognos 8 handle summaries when creating
pie charts, a pie chart in a migrated report may appear empty in Cognos 8.
To correct the display in Cognos 8, unhide the details rows or use a different chart type.
Duplicate Categories in Migrated PowerPlay Reports That Contained Custom
Subsets
A PowerPlay custom subset can include both a search condition and a picklist. When you migrate
a report that includes this type of custom subset to Analysis Studio, the migrated report may
contain duplicate categories. For example, if your custom subset includes a search condition that
adds children of years beginning with 2, and you explicitly include the year 2005, the migrated
report will contain two instances of 2005.
This problem does not occur if you migrate the report from PowerPlay to Report Studio.
To correct the duplication in Analysis Studio, delete the duplicate category.
Row of Data Missing in Analysis Studio for Migrated PowerPlay Report
In PowerPlay, a report may use an unbalanced hierarchy. An unbalanced hierarchy is a
subdimension that provides different levels of detail for specific categories. For example, some
branch offices may report product sales down to the item level, whereas others may report only to
the product level. You can create a subdimension for those branches that report to the item level.
When you migrate a report that uses an unbalanced hierarchy to Analysis Studio, one or more of
the original rows may not appear in the migrated report.
Charts Do Not Display Correctly
After you migrate a report that contains a chart, some objects may not display correctly. For
example, the chart may be larger than expected, or labels may overlap.
To correct the display, manually adjust the size of the chart or related objects, such as the font size
used in labels.
148 Migration Tools

An Extra Column Appears in the Migrated PowerPlay Report
Appendix A: Troubleshooting
Because of differences between PowerPlay for Windows and PowerPlay Web, there can be
differences in the display of the same report. For example, a ranking column that appears in
PowerPlay for Windows does not appear when you open the report in PowerPlay Web.
Depending on where the report was originally authored, a migrated report may show features that
appeared only in PowerPlay for Windows. For example, the ranking category that did not appear
in PowerPlay Web does appear in the report after migration.
Shared Custom Exception Definition Is not Applied in Migrated PowerPlay
Report
In PowerPlay, shared custom exception definitions are applied at runtime. Because the migration
process only migrates saved report specifications, shared custom exception definitions are not
migrated.
To apply shared custom definitions in a migrated report, save the report. The shared custom
definitions are saved in the ppx file, and as a result they will be migrated when you migrate the
report.
Problems with Security
Access Control List is Not Migrated as Expected
After deploying Cognos Series 7 Web-based content from Upfront to Cognos 8, security settings
are not as expected.
Confirm that you completed the following tasks:
• Cognos 8 is configured to use the same namespace as Cognos Series 7.
• The migratetoc8 command included the --acl 2 parameter.
• The deploytoc8 command included the correct namespace ID.
This must be the namespace ID for the Series 7 namespace as it appears in Cognos
Configuration.
If you did not complete all of the tasks correctly, you must repeat the migration process, or
manually apply the required security in Cognos 8. For more information about configuring
security in Cognos 8, see the Cognos 8 Administration and Security Guide.
User Guide 149

Appendix A: Troubleshooting
150 Migration Tools

Appendix B: Samples
The samples provided demonstrate how Cognos Series 7 content is migrated to Cognos 8 using
the migration tools. In addition, the migrated reports were modified after migration to highlight
features that are available only in Cognos 8 or features that are improvements over Cognos
Series 7. Consequently, there are two sets of samples provided, migrated samples and modified
samples.
The samples included with the migration tools are in English only. Migration samples in other
languages are available from the Cognos Global Customer Services Web site
(http://support.cognos.com).
For information about how to set up the samples, see the Migration Tools Installation and
Configuration Guide.
Cognos Series 7 Content
In addition to the migrated content, the source Cognos Series 7 content is provided so that you
can compare source applications with migrated applications. The Cognos Series 7 content
includes Transformer models, PowerCubes, PowerPlay reports, an Impromptu catalog, and
Impromptu Web Report reports.
Transformer Model Samples
PowerCube Samples
The Transformer model sample Great Outdoors (Modified).mdl is used to create the PowerCube
for the modified PowerPlay reports. To enable queries against multiple hierarchies in the same
PowerCube, the model was modified by adding
• a special category named Relative Time that includes all Relative Time categories
• a special category named Current Month that is separate from the Relative Time category
These modifications were made because Cognos 8 interprets any grouping of categories from the
same dimension that disregards the primary hierarchical organization, such as relative time
categories, special categories, or categories from an alternate drill path, as a distinct new hierarchy
in that dimension.
The model is located in the c8_location/webcontent/samples/trnmdl/en directory.
The following PowerCube samples are used as the data sources for the migrated PowerPlay
reports. The PowerCubes are located in two folders in the
c8_location/webcontent/samples/models/PowerCubes_Migrated/en directory.
• Sample Cube (Migrated).mdc
This PowerCube is used for the reports that are migrated without any modifications.
• Sample Cube (Modified).mdc
This PowerCube, based on the Great Outdoors (Modified).mdl model, is used for the reports
that are modified after migration.
User Guide 151

Appendix B: Samples
PowerPlay Report Samples
Two sets of PowerPlay report samples are provided. One set of reports uses the Sample Cube
(Migrated) PowerCube and the other set uses the Sample Cube (Modified) PowerCube. The
PowerPlay report samples are located in two folders in the
c8_location/webcontent/samples/reports/PowerPlay/EN directory.
If you open a PowerPlay report sample, ensure that you choose the correct PowerCube for the
report. The PowerCube that you must choose is located in the same folder as the report.
Impromptu Catalog Sample
The Impromptu catalog sample gosales.cat is used as the data source for the migrated Impromptu
Web Reports reports. The catalog is located in the c8_location/webcontent/samples/reports/IWR
directory.
Impromptu Web Reports Report Samples
The Impromptu Web Reports report samples that are provided use the gosales.cat catalog sample.
The reports are located in the c8_location/webcontent/samples/reports/iwr/EN/IWR_Reports
(Migrated) directory.
Migrated Content
The migrated content is organized in Cognos Connection in several packages. The Sample Cube
(Migrated) package contains PowerPlay reports that were migrated to both Analysis Studio and
Report Studio. The Sample Cube (Modified) package contains PowerPlay reports that were
modified in Analysis Studio and Report Studio after migration. The gosales.cat package contains
the Impromptu Web Reports reports that were migrated to Report Studio. No modifications were
made to these reports.
PowerPlay Report Samples
Charting Options Sample
The following sections describe the source PowerPlay report samples and the modifications made
to each one after migration.
Clustered bar chart with layers. The following formatting changes were made to the report after
migration to improve its appearance. Because of differences between Report Studio and Analysis
Studio, some formatting changes were applied to only one of the target reports.
• Changed the Maximum Value, Minimum Value, and Scale Interval properties of the chart's
y-axis.
• Changed the Size & Overflow, Palette, and Value Location properties of the chart.
• Changed the Fill Effects property for the chart body.
Currency (Reporter) Sample
Report showing the Convert Currency option in reporter mode. The following formatting changes
were made to the report after migration to improve its appearance. Because of differences between
Report Studio and Analysis Studio, some formatting changes were applied to only one of the
target reports.
• Renamed the first column to Revenue.
• Changed the font for all columns and rows.
• Changed the color of the first column.
• Set the currency format for all data items to GBP.
152 Migration Tools

Appendix B: Samples
Parentage Subset Sample
Report containing a parentage subset definition using the qualifier Next level children for the
Years dimension. The following formatting changes were made to the report after migration to
improve its appearance. Because of differences between Report Studio and Analysis Studio, some
formatting changes were applied to only one of the target reports.
• Changed the font of the report title and the Revenue column.
• Renamed the row data item.
• Changed the font and alignment of the column headers.
• Changed the font and color of the row headers.
• Changed the font of all data cells.
• Added a report footer containing the page number.
Nested Crosstab 1 Sample
Reporter mode report with indented levels. The following formatting changes were made to the
report after migration to improve its appearance:
• Set the font for the crosstab corner item, row headers, column headers, and data cells.
• Changed the background color for the row headers and data cells.
• Added a header.
Forecasting Sample
Report showing a forecasting calculation in a crosstab with indented levels. The following
modifications and enhancements were made to the report after migration. The modifications
simulate forecasting in PowerPlay.
• Added two calculations, named Target and Tolerance, to simulate forecasting calculations
which are not supported in Cognos 8.
• Added filters for prompting and drill-through.
• Added zero suppression.
• Added a pareto stacked column with a 3-D visual effect chart.
The following is the source PowerPlay report.
User Guide 153

Appendix B: Samples
The following is the report migrated and modified in Report Studio.
Nested Crosstab 4 Sample
Report showing the children of the Locations dimension as nested categories in all of the rows.
The following modifications and enhancements were made to the report after migration. The
modifications replicate formatting in PowerPlay.
• Added Revenue as the default measure.
• Added filters for prompting and drill-through.
• Added zero suppression.
• Added a report title and another text item for the crosstab.
The following is the source PowerPlay report.
154 Migration Tools

Appendix B: Samples
The following is the report migrated and modified in Report Studio.
External Rollup Sample
Report showing the External Rollup Customer Count calculation. The External Rollup function
summarizes measure values in the PowerCube. The following modifications and enhancements
were made to the report to replicate the calculations using the Relative Time hierarchy and
formatting in PowerPlay. The formatting changes were applied only to the target Report Studio
report.
• Added Revenue as the default measure.
• Added Prior YTD and QTD Growth as rows and formatted them.
The following is the source PowerPlay report.
The following is the report migrated in Analysis Studio.
User Guide 155

Appendix B: Samples
The following is the report migrated and modified in Analysis Studio.
Ranking 3 Sample
Report showing rank options. The following formatting changes and modifications were made to
the report. Because of differences between Report Studio and Analysis Studio, some formatting
changes were applied to only one of the target reports.
• Changed the alignment, font, and background color for the column and row headers.
• Changed the font and alignment for all data cells.
• Added Revenue as the default measure.
The following is the source PowerPlay report.
156 Migration Tools

Appendix B: Samples
The following is the report migrated and modified in Report Studio.
Note: Ranking differences exist between Analysis Studio and Report Studio. As a result, the report
migrated to Analysis Studio is different than the report migrated to Report Studio.
Impromptu Web Reports Report Samples
The following sections describe the source Impromptu Web Reports report samples. No
modifications were made to these reports after migration.
Customer Satisfaction Sample
Report demonstrating conditional formats.
User Guide 157

Appendix B: Samples
Income from Customers Sample
Products Sample
Sales Staff Report Sample
Report showing a list of retailers ranked by income.
Report showing all products.
Report demonstrating grouped lists. Members of the sales staff are grouped by position and sorted
by last name.
Simple Crosstab Report Sample
Report showing annual revenue totals for each product line.
158 Migration Tools

PART 5: Worksheets
User Guide 159

160 Migration Tools

Migration Worksheet
Before you use the migration tools, record the information you need for the command lines and
for other tasks such as checking package mapping. You may need to contact your administrator
for some of the information.
Information for the arch2xml74 Command
• Source location and name of the Architect models
_______________________________________________________
_______________________________________________________
_______________________________________________________
_______________________________________________________
_______________________________________________________
• Target location for the XML output. Create the target location before you run the
arch2xml74 command.
_______________________________________________________
• Access Manager user ID
_______________________________________________________
• User password
_______________________________________________________
• Name of the published Framework Manager package
_______________________________________________________
Information for the impcat2xml Command
• Source location and name of the Impromptu catalogs
_______________________________________________________
_______________________________________________________
_______________________________________________________
_______________________________________________________
_______________________________________________________
• Target location for the XML output. Create the target location before you run the
impcat2xml command.
_______________________________________________________
• User class ID
_______________________________________________________
• User password
_______________________________________________________
• Access Manager user ID
_______________________________________________________
• User password
_______________________________________________________
• Name of the published Framework Manager package. Use the catalog name for the package
name.
_______________________________________________________
User Guide 161

Migration Worksheet
Information for the migratetoc8 Command
• Source location of the reports
_______________________________________________________
_______________________________________________________
_______________________________________________________
_______________________________________________________
_______________________________________________________
• Source location and name of the Deployment Manager package files (.dmp)
_______________________________________________________
_______________________________________________________
_______________________________________________________
_______________________________________________________
_______________________________________________________
• Source location of the Deployment Manager packlets folders
_______________________________________________________
_______________________________________________________
_______________________________________________________
_______________________________________________________
_______________________________________________________
• Target location for the migration package output. Create the target location before you run
the migratetoc8 command.
_______________________________________________________
• User class ID for catalogs
_______________________________________________________
• User password
_______________________________________________________
• Access Manager user ID
_______________________________________________________
• User password
_______________________________________________________
• Name of the published Framework Manager package
_______________________________________________________
Information for the deploytoc8 Command
• Source location of the migration package
_______________________________________________________
• Target location for the deployment package
_______________________________________________________
• User ID for the Cognos 8 namespace
_______________________________________________________
• User password
_______________________________________________________
• Namespace ID
_______________________________________________________
• Data source connections
_______________________________________________________
_______________________________________________________
_______________________________________________________
162 Migration Tools

Index
Symbols
.ppx files
migrating, 18
Numerics
80/20 suppression
mapping for PowerPlay reports, 73
A
access control list
migrating, 19
migrating from Upfront, 93
migration options, 93
troubleshooting migration problems, 149
Access Manager
namespace schema versions, 19
ACL report
location, 46
Analysis Studio
selecting for PowerPlay report migration, 18
applications
migrating, 39
migrating from UNIX, 41
migration process diagram, 39
arch2xml command, 11, 29
arch2xml74 command
description, 30
examples, 31
migrating Architect models, 29
syntax, 30
Architect
arch2xml74 command, 30
migrating a single model, 29
migrating models, 29
migrating multiple models, 29
migration overview, 19
objects missing after migration, 134
Architect catalogs
migration mapping, 110
Architect metadata
package layer, 122
Architect models
attribute proxies, 103
attributes, 103
columns, 115
command line examples, 31
data access layer, 108
database folders, 108
databases, 109
decimal separators, 137
entities, 102
Architect models (cont'd)
entities folders, 101
expressions, 100
filters, 105
filters folders, 104
indexes, 120
keys, 116
multiple database expressions, 101
multiple database functions, 101
package folders, 122
packages, 123
physical joins, 121
problems with filters after importing metadata, 137
prompts, 107
publish Framework Manager package, 37
relationships, 106
schemas, 110
security by value, 100
security mapping, 99
SQL queries, 117
SQL query folders, 117
stored procedure parameters, 119
stored procedure return parameters, 119
stored procedures, 118
subject attributes, 126
subject entities, 125
subject filters, 124
subject folders, 124
subject prompts, 125
subtype relationships, 106
synonym tables, 114
SynonymViews, 113
tables, 111
unable to run report, 145
user classes, 100
views, 112
Architect security
database access, 99
entity access, 99
migration mapping, 99
package access, 99
user class filters, 99
attribute proxies
mapping for Architect models, 103
attributes
mapping for Architect models, 103
B
blank pages
troubleshooting errors, 148
borders
mapping for Impromptu reports, 69
User Guide 163

Index
business view
mapping for Impromptu catalogs, 59
C
CAF
configuration settings in Cognos 8, 143
calculated columns
mapping for Impromptu crosstab reports, 65
calculations
invalid operands, 146
mapping for Impromptu catalogs, 60
cardinality
testing for migrated metadata, 36
cast operation
function mapping, 141
catalog export
logon prompt, 135
problems with non-English Impromptu catalog, 135
unable to open catalog error, 136
catalog prompts, 66
catalogs
unable to find, 137
unable to open, 142
categories
missing from migrated PowerPlay reports that includes
child categories that do not roll up, 138
suppressed from migrated PowerPlay reports, 138
characters
unsupported, 140
charts
mapping for Impromptu reports, 65
mapping for legends in Impromptu reports, 65
mapping for PowerPlay reports, 81
problems with display, 148
troubleshooting display errors, 147
choosing
target studio, 48
client-server balancing
configuration options for Impromptu, 65
Cognos 8
Cognos Application Firewall setting, 143
deploying migration package, 48
enabling packages, 52
importing deployment archive, 51
missing information in error messages, 143
security, 143
testing migration, 51
upgrading from Cognos ReportNet 1.1, 9
using cubes as a data source, 27
using PowerCubes as a data source, 27
Cognos Application Firewall
configuration settings in Cognos 8, 143
Cognos NoticeCast
migration overview, 20
Cognos Portal Services
migration overview, 20
Cognos Query
migration overview, 19
Cognos ReportNet 1.1
upgrading to Cognos 8, 9
Cognos Series 7
Deployment Manager, 41
migrating applications on UNIX, 41
preparing source files, 41
what is migrated, 17
Cognos Services, 22
Cognos SQL
expressions in Impromptu catalogs, 62
Cognos Visualizer
migration overview, 19
Cognos Web Services
migration overview, 20
CognosScript
migration overview, 20
columns
extra columns appear in a report, 149
mapping for Architect models, 115
commands
arch2xml74, 30
arch2xml74 examples, 31
deploying to Cognos 8, 48
deploytoc8, 49
deploytoc8 examples, 50
impcat2xml, 33
impcat2xml examples, 34
migratetoc8, 43, 45
migrating applications, 42
migrating Architect models, 30
migrating Impromptu catalogs, 33
migrating reports, 42
using special characters, 134
conditional formatting
run-time errors, 144
conditions
mapping for Impromptu catalogs, 61
configuring
location of deployment archives, 51
constant number
function mapping, 142
constant value of zero
function mapping, 142
contact email address
mapping for Impromptu Web Reports, 95
contact information
mapping for Impromptu Web Reports, 95
mapping for Upfront, 92
copyright, 2
creating
migration package, 42
crosstab headers
mapping for Impromptu reports, 68
cubes
using in Cognos 8, 27
custom exception definitions, 75
shared custom exception definitions not applied to report,
149
custom subsets
correcting duplicate categories after migration, 148
164 Migration Tools

Index
D
data
does not appear in report cells, 146
data access layer
mapping for Architect models, 108
data items
troubleshooting errors, 144
data source connections
creating for metadata, 35
requirements for Cognos Series 7 metadata, 35
data sources
cubes, 27
PowerCubes, 27
database folders
mapping for Architect models, 108
database query subjects
mapping for Impromptu catalog table aliases, 58
mapping for Impromptu catalog tables, 58
databases
mapping for Architect models, 109
date and time functions
incorrect results, 143
deploying
migration package, 48
deployment archive
importing, 51
location, 51
Deployment Manager
preparing source files, 41
deploytoc8
log file, 51
deploytoc8 command
deploying migration package, 48
description, 49
examples, 50
package not found error, 139
parameters, 49
report not migrated error message, 140
syntax, 49
diagrams
metadata migration workflow, 28
migrating applications, 39
differences between PowerPlay and Analysis Studio
drilling down on calculations, 89
lower level calculations in parentage subsets, 90
displays
mapping for PowerPlay, 81
drilling down on calculations
differences between PowerPlay and Analysis Studio, 89
drill-through settings
mapping for Impromptu reports, 66
E
enabling
packages, 52
encoding
troubleshooting errors, 140
entities
mapping for Architect models, 102
entities folders
mapping for Architect models, 101
error messages
cannot open catalog as creator, 136
CM-REQ-4024 name conflict, 139
exception raised, 135
failed to open model, 135
importing metadata into Framework Manager, 136
incomplete, 143
JRE not found, 139
login failed, 139
name conflict, 139
objects not found, 142
package not found, 139
parsing error, 143
QRS-ERR-0140 referenced data item not found, 145
report cannot be accessed, 138
report not migrated, 140
running Architect migration tool, 135
unable to find catalog, 137
unable to find packlets, 138
unable to open catalog, 136, 142
unable to start Impromptu automation server, 135
utility fails to run, 134
errors
log file, 51
events
mapping for Impromptu Web Reports, 97
examples
deploytoc8 command, 50
migratetoc8 command, 45
migrating Architect models, 31
migrating Impromptu catalogs, 34
expressions
mapping for Architect models, 100
mapping for Impromptu catalogs, 62
F
files
preparing migration source, 41
filter expressions
mapping for Impromptu catalogs, 57
filters
does not work in detail query, 145
mapping for Architect models, 105
mapping for summary filters in Impromptu reports, 67
updating in Framework Manager, 137
filters folders
mapping for Architect models, 104
folder columns
mapping for Impromptu catalogs, 60
folders
duplicate names in Impromptu catalogs, 60
mapping for Impromptu catalogs, 60
footers
mapping for Impromtu reports, 66
missing after migration, 147
formatting, 75
mapping for Impromptu reports, 67
Framework Manager
calculations in Impromptu catalogs, 60
conditions in Impromptu catalogs, 61
duplicate folder names in Impromptu catalogs, 60
User Guide 165

Index
Framework Manager (cont'd)
errors importing metadata, 136
errors with Impromptu subfolder query items, 136
expressions in Impromptu catalogs, 62
folder columns in Impromptu catalogs, 60
folders in Impromptu catalogs, 60
importing Cognos Series 7 metadata, 35
Impromptu catalog business view, 59
incorrect decimal separators in Architect metadata, 137
mapping joins to cardinality, 36
modifying projects, 101
package names, 47
problems running reports against Architect model, 145
prompts in Impromptu catalogs, 61
publish package, 37
testing Cognos Series 7 metadata, 36
user defined functions in Impromptu catalogs, 62
using Cognos Series 7 metadata, 27
Framework Manager namespace
mapping for Impromptu catalogs, 58
function not supported, 141
functions
cast operation, 141
constant number, 142
constant value of zero, 142
date and time errors, 143
expression errors, 143
mapping, 141, 147
migration mapping, 127
no-operation, 142
no-operation on first argument, 142
not supported, 141
troubleshooting errors, 141, 147
G
generic mapping for function, 141, 147
governors
mapping for Impromptu reports, 66
graphics
not displaying in reports, 141
graphs
mapping for PowerPlay reports, 81
H
headers
mapping for crosstabs in Impromptu reports, 68
mapping for Impromptu reports, 66
missing after migration, 147
HotFiles
mapping for Impromptu Web Reports, 97
HTML reports
mapping for page count in Impromptu reports, 66
I
images
mapping for PowerPlay reports, 80
missing in migrated reports, 141
unable to find source folder error, 137
impcat2xml command
description, 33
impcat2xml command (cont'd)
examples, 34
syntax, 33
impcat2xml tool
migrating Impromptu catalogs, 32
impimr2xml-translate-functions-map.xml, 127
importing
Architect xml file into Framework Manager, 136
Cognos Series 7 metadata in Framework Manager, 35
deployment archive, 51
Impromptu xml file into Framework Manager, 136
Impromptu
client-server balancing options, 65
errors migrating reports, 138
impcat2xml command, 33
mapping for prompts, 66
migrating a single catalog, 32
migrating catalogs, 32
migrating multiple catalogs, 32
migration overview, 17
unable to start automation server error, 135
Impromptu catalog
sample, 152
Impromptu catalogs, 57
business view, 59
calculations, 60
command line examples, 34
conditions, 61
expressions, 62
filter expressions, 57
folder columns, 60
folders, 60
joins, 59
mapping to Framework Manager namespace, 58
physical view, 57
prompts, 61
publish Framework Manager package, 37
security, 57
table aliases, 58
table columns, 59
tables, 58
user defined functions, 62
Impromptu reports
borders, 69
calulated columns, 65
catalog and report paths, 65
catalog prompts, 66
chart formats, 65
chart legends, 65
crosstab headers, 68
differences in formatting in Cognos 8, 147
drill-through settings, 66
footers, 66
governors, 66
headers, 66
migration mapping details, 65
number formatting, 68
page count, 66
page width, 69
placeholders, 66
report formatting, 67
save as HTML options, 67
166 Migration Tools

Index
Impromptu reports (cont'd)
snapshots, 67
string formats, 66
summary filters in crosstabs, 67
summary values, 140
table of contents for HTML reports, 67
templates, 66, 67
text frames, 69
unsupported report objects, 67
zero suppression, 67
Impromptu Web Reports
data store, 97
events, 97
features not supported in Cognos 8, 96
HotFiles, 97
mapping for contact email address, 95
mapping for contact information, 95
mapping for prompt settings, 96
mapping for report list, 95
mapping for report set name, 95
migration mapping, 95
migration overview, 19
ObjectStore, 97
PowerPrompts, 19, 97
report properties, 95
report sets, 95
schedules, 41, 96
indexes
mapping for Architect models, 120
J
joins
mapping for Impromptu catalogs, 59
mapping to cardinality in Framework Manager, 36
JRE
errors when running migration tool, 139
K
keys
mapping for Architect models, 116
L
layers, 72
log file
fixing errors and warnings, 51
migration, 51
log files
deploytoc8 log, 51
descripton, 133
installation log file, 133
migratetoc8 log, 46
migration deployment log file, 134
migration export log file, 134
published PowerPlay reports migrated to Cognos 8 log
files, 54, 134
login failed
error messages, 139
M
macros
migrating, 66
map files
impimr2xml-translate-functions-map.xml, 127
mapping
functions, 141, 147
functions as a constant number, 142
functions as a constant value of zero, 142
functions as no-operation on first argument, 142
functions using cast operation, 141
functions using no-operation, 142
metadata from Impromptu catalogs to Framework
Manager, 57
master/detail queries
filter in detail query does not work, 145
metadata
creating data source connections, 35
data access layer mapping for Architect models, 108
importing in Framework Manager, 35
migration overview, 27
migration workflow diagram, 28
synchronizing, 37
testing before migration, 28
testing in Framework Manager, 36
metadata mapping
Impromptu catalogs to Framework Manager, 57
migratetoc8
log file, 51
migratetoc8 command
creating migration package, 42
description, 43
examples, 45
parameters, 43
syntax, 43
migrating
access control list, 19
applications, 39
Architect models, 29
Impromptu catalogs, 32
Impromptu macros, 66
metadata, 27
multiple Architect models, 29
multiple Impromptu catalogs, 32
non-english data, 27
single Architect models, 29
single Impromptu catalog, 32
supporting other languages, 27
migrating reports
choosing the target studio, 48
same problems occur, 137
migration
testing, 51
understanding the process, 21
migration deployment archive
description, 51
migration package
creating, 42
deploying, 48
description, 46
moving to Cognos 8, 46
User Guide 167

Index
missing categories
errors in PowerPlay reports, 146
modifying
Framework Manager projects, 101
multiple database expressions
mapping for Architect models, 101
multiple database functions
mapping for Architect models, 101
N
nameMap.xml file
package names, 47
names
mapping for PowerPlay reports, 79
namespace schema
supported versions, 19
new features, 11
NewsBox shortcuts
mapping for Upfront, 92
NewsBoxes
mapping for Upfront, 91
NewsItem shortcuts
mapping for Upfront, 93
NewsItems
mapping for Upfront, 92
non-english data
migrating, 27
no-operation
function mapping, 142
no-operation on first argument
function mapping, 142
NoticeCast
migration overview, 20
number formatting
mapping for Impromptu reports, 68
O
ObjectStore
Impromptu Web Reports, 97
opening
models, 135
overview
migrating applications, 39
P
package folders
mapping for Architect models, 122
package layer metadata
mapping for Architect models, 122
package names
check mapping, 47
nameMap.xml file, 47
packages
enabling, 52
error when running deploytoc8, 139
mapping for Architect models, 123
troubleshooting errors, 144
packlets
not found, 138
page breaks
troubleshooting errors, 148
page count
mapping for Impromptu reports, 66
page width
mapping for Impromptu reports, 69
parameters
arch2xml74 command, 30
deploytoc8 command, 49
impcat2xml command, 33
migratetoc8 command, 43
parentage subsets
lower level calculations not migrated to Analysis Studio,
90
parsing
troubleshooting errors, 143
paths
mapping for Impromptu catalogs and reports, 65
PDF reports
mapping for page count in Impromptu reports, 66
physical joins
mapping for Architect models, 121
physical view
mapping for Impromptu catalogs, 57
picklist prompts, 66
pictures
mapping for PowerPlay reports, 80
pie charts
correcting display differences, 148
placeholders
mapping for Impromptu reports, 66
planning
understanding the migration process, 21
PowerCubes
samples, 151
using in Cognos 8, 17, 27
PowerPlay
migration mapping, 71
migration overview, 17
unbalanced hierarchy, 148
using cubes in Cognos 8, 17
PowerPlay report
categories missing after migration that include child
categories that do not roll up, 138
PowerPlay reports
.ppx files, 18
categories suppressed after migration, 138
fail to open or run, 146
mapping for charts, 81
mapping for graphical displays, 81
mapping for images, 80
mapping for long and short names, 79
mapping for pictures, 80
mapping for report formatting, 79
mapping for report functionality, 73
mapping for report structure, 71
mapping for titles, headers, and footers, 79
migration options, 18
selecting Cognos 8 studio for migration, 18
unsupported objects, 85
PowerPrompts
mapping for Impromptu Web Reports, 97
168 Migration Tools

Index
process
migration planning, 21
prompt settings
mapping for Impromptu Web Reports, 96
prompts
catalog, 66
mapping for Architect models, 107
mapping for Impromptu catalogs, 61
mapping for Impromptu prompts, 66
picklist, 66
PowerPlay reports, 78
type-in, 66
publish
Framework Manager package, 37
Q
queries
referenced data item not found error, 144
query items
mapping for Impromptu catalogs, 59
R
ranking
different in migrated report, 146
relationships
mapping for Architect models, 106
mapping for Impromptu catalogs, 59
report formatting
troubleshooting, 147
report list
mapping for Impromptu Web Reports, 95
report properties
mapping for Impromptu Web Reports, 95
report server
troubleshooting errors, 145
report set name
mapping for Impromptu Web Reports, 95
report sets
mapping for Impromptu Web Reports, 95
Report Studio
selecting for PowerPlay report migration, 18
reports
choosing the target studio, 48
correct data does not appear in cells, 146
extra columns appear, 149
troubleshooting extra rows or columns, 146
troubleshooting missing rows or columns, 146
running reports
problems, 140
takes longer than expected, 145
S
samples
Impromptu catalog, 152
PowerCubes, 151
source Impromptu Web Reports reports, 152
source PowerPlay reports, 152
Transformer model, 151
save as HTML
mapping for Impromptu report options, 67
saved prompt values
mapping for Impromptu Web Reports, 96
schedules
Impromptu Web Reports, 41
mapping for Impromptu Web Reports, 96
schemas
mapping for Architect models, 110
security
access control list, 19, 93
Cognos 8, 143
database access for Architect models, 99
enabling packages, 52
entity access for Architect models, 99
mapping for Architect models, 99
mapping for Impromptu catalogs, 57
mapping for Upfront, 93
migration overview, 19
package access in Architect models, 99
security by value settings in Architect models, 100
user class filters in Architect models, 99
snapshots
mapping for Impromptu reports, 67
sorting
troubleshooting sorting methods, 145
source files
creating with Deployment Manager, 41
preparing, 41
preparing source directory, 42
source Impromptu Web Reports reports
samples, 152
source PowerPlay reports
samples, 152
special characters
using in file path, 134
SQL queries
mapping for Architect models, 117
SQL query folders
mapping for Architect models, 117
stored procedure parameters
mapping for Architect models, 119
stored procedure return parameters
mapping for Architect models, 119
stored procedures
mapping for Architect models, 118
string formats
mapping for Impromptu reports, 66
subject attributes
mapping for Architect models, 126
subject entities
mapping for Architect models, 125
subject filters
mapping for Architect models, 124
subject folders
mapping for Architect models, 124
subject prompts
mapping for Architect models, 125
subtype relationships
mapping for Architect models, 106
summary filters
mapping for Impromptu crosstab reports, 67
summary values
mapping for Impromptu reports, 140
User Guide 169

Index
synchronizing
metadata, 37
synonym tables
mapping for Architect models, 114
SynonymView properties
Architect models, 113
syntax
arch2xml74 command, 30
deploytoc8 command, 49
impcat2xml command, 33
migratetoc8 command, 43
T
table aliases
mapping for Impromptu catalogs, 58
mapping in Framework Manager, 57
table columns
mapping for Impromptu catalogs, 59
table of contents
mapping for Impromptu HTML reports, 67
tables
mapping for Architect models, 111
mapping for Impromptu catalogs, 58
templates
mapping for Impromptu reports, 67
mapping for placeholders in Impromptu reports, 66
testing
Cognos Series 7 metadata, 28
metadata in Framework Manager, 36
migration, 51
text frames
mapping for Impromptu reports, 69
themes
mapping for Upfront, 93
Transformer model
sample, 151
troubleshooting
access control list migration, 149
Architect objects missing after migration, 134
blank pages in migrated reports, 148
borders in Impromptu reports, 69
cannot open catalog as creator error, 136
chart display errors, 147
charts not displaying correctly, 148
CM-REQ-4024 name conflict error, 139
crosstab headers in Impromptu reports, 68
data in report containing master/detail query is not
filtered, 145
date and time function errors, 143
decimal separators in Architect models, 137
default formatting in Impromptu reports, 67
differences in report appearance between Impromptu and
Cognos 8, 147
display differences in pie charts, 148
duplicate categories, 148
encoding problems, 140
errors for functions, 127
exception raised error message, 135
extra columns appear in a report, 149
extra rows or columns appear in report, 146
failed to open model error, 135
troubleshooting (cont'd)
filters in Architect models, 137
functions, 141, 147
headers and footers, 147
imported metadata into Framework Manager, 136
incorrect page breaks, 148
invalid operands in calculations, 146
JRE not found error, 139
log files, 133
log on prompt during metadata export, 135
logon prompt on catalog migration, 135
migrating non-English catalog, 135
missing images, 141
missing rows, 148
missing rows or columns appear in report, 146
number formatting in Impromptu reports, 68
objects not found error, 142
page width in Impromptu reports, 69
parsing errors, 143
problems deploying migrated applications, 139
problems importing metadata into Framework Manager,
136
problems migrating applications, 137
problems migration metadata, 134
problems running migrated reports, 140
problems with report cells, 146
problems with report formatting, 147
problems with security, 149
QRS-ERR-0140 error, 145
rank values different in migrated report, 146
report cannot be accessed error, 138
report fails to run or runs with errors, 140
report server not responding error, 145
report takes longer than expected to run, 145
run-time errors in conditonal formatting expressions, 144
same problems occur when migrating reports, 137
shared custom exception definitions, 149
sorting of grouped items, 145
subfolder query items in Framework Manager, 136
summary values in Impromptu reports, 140
text frames in Impromptu reports, 69
unable to find catalog error, 137
unable to find images error, 137
unable to find package error, 144
unable to find packlets error, 138
unable to find referenced data item error, 144
unable to open catalog error, 136
unable to run report against Architect model, 145
unable to start Impromptu automation server error, 135
unhandled application errors, 144
unsupported characters, 140
variables, 147
type-in prompts, 66
U
UDFs, See user defined functions
unbalanced hierarchy
Analysis Studio, 148
PowerPlay, 148
unhandled application errors, 144
170 Migration Tools

Index
UNIX
migrating applications, 41
unsupported features
mapping for Impromptu Web Reports, 96
Upfront
mapping for contact information, 92
migration mapping, 91
migration overview, 18
NewsBox shortcuts, 92
NewsBoxes, 91
NewsItem shortcuts, 93
NewsItems, 92
security, 93
supported content for migration, 91
themes, 93
unsupported content for migration, 91
user settings, 93
upgrading
Cognos ReportNet 1.1 to Cognos 8, 9
user classes
Architect models, 100
user defined functions
mapping for Impromptu catalogs, 62
user settings
mapping for Upfront, 93
V
variable not supported, 147
variables
not supported, 147
troubleshooting errors, 147
version of document, 2
views
mapping for Architect models, 112
W
warnings
log file, 51
workflow
migrating metadata, 28
Z
zero suppression
mapping for Impromptu reports, 67
mapping for PowerPlay reports, 75
User Guide 171

Index
172 Migration Tools